feat: enforce JSDoc and add central type definitions

- Upgrade JSDoc rules from warn to error for strict enforcement
- Add types.js with central TypeDefs (ModuleData, ConfigData, etc.)
- Enable better IDE autocomplete and type safety
- All existing code already has good JSDoc coverage

Author: KristjanESPERANTO

eslint.config.mjs

@@ -37,6 +37,21 @@ export default defineConfig([
       "@stylistic/padded-blocks": "off",
       "@stylistic/quote-props": ["error", "consistent"],
       "capitalized-comments": "off",
+      "jsdoc/require-jsdoc": [
+        "error", {
+          "require": {
+            "FunctionDeclaration": true,
+            "MethodDefinition": true,
+            "ClassDeclaration": true,
+            "ArrowFunctionExpression": false,
+            "FunctionExpression": false
+          }
+        }
+      ],
+      "jsdoc/require-param": "error",
+      "jsdoc/require-param-type": "error",
+      "jsdoc/require-returns": "error",
+      "jsdoc/require-returns-type": "error",
       "max-lines-per-function": ["warn", 250],
       "max-statements": ["warn", 60],
       "no-inline-comments": "off",

node_helper.js

@@ -1,5 +1,18 @@
 /* global Module */
 
+/**
+ * @file MagicMirror² Remote Control Module - Node Helper
+ * @module node_helper
+ */
+
+/**
+ * @typedef {import('./types').ModuleData} ModuleData
+ * @typedef {import('./types').ConfigData} ConfigData
+ * @typedef {import('./types').ModuleConfig} ModuleConfig
+ * @typedef {import('./types').BackupInfo} BackupInfo
+ * @typedef {import('./types').ApiResponse} ApiResponse
+ */
+
 /*
  * MagicMirror²
  * Module: Remote Control
@@ -97,6 +110,10 @@ module.exports = NodeHelper.create({
     this.loadTimers();
   },
 
+  /**
+   * Set up periodic timers for module list updates
+   * @returns {void}
+   */
   loadTimers () {
     const delay = 24 * 3600;
 
@@ -107,6 +124,11 @@ module.exports = NodeHelper.create({
     }, delay * 1000);
   },
 
+  /**
+   * Combine default config with user config from config.js
+   * Sets this.configOnHd and this.thisConfig
+   * @returns {void}
+   */
   combineConfig () {
     // function copied from MagicMirrorOrg (MIT)
     const defaults = require(`${__dirname}/../../js/defaults.js`);
@@ -140,6 +162,10 @@ module.exports = NodeHelper.create({
     this.loadTranslation(this.configOnHd.language);
   },
 
+  /**
+   * Get the MagicMirror config file path
+   * @returns {string} Absolute path to config.js
+   */
   getConfigPath () {
     let configPath = path.resolve(`${__dirname}/../../config/config.js`);
     if (globalThis.configuration_file !== undefined) {
@@ -194,6 +220,11 @@ module.exports = NodeHelper.create({
 
   formatName (string) { return formatName(string); },
 
+  /**
+   * Update the list of available modules from 3rd-party repository
+   * @param {boolean} force - Force re-download even if cache exists
+   * @returns {void}
+   */
   updateModuleList (force) {
     const downloadModules = require("./scripts/download_modules");
     downloadModules({
@@ -205,6 +236,11 @@ module.exports = NodeHelper.create({
     });
   },
 
+  /**
+   * Read and parse modules.json file
+   * Populates this.modulesAvailable with ModuleData[]
+   * @returns {void}
+   */
   readModuleData () {
     fs.readFile(path.resolve(`${__dirname}/modules.json`), (error, data) => {
       this.modulesAvailable = JSON.parse(data.toString());
@@ -242,6 +278,10 @@ module.exports = NodeHelper.create({
     });
   },
 
+  /**
+   * Get the modules directory path from config or use default
+   * @returns {string} Modules directory path (relative or absolute)
+   */
   getModuleDir () {
     return this.configOnHd.foreignModulesDir || (this.configOnHd.paths
       ? this.configOnHd.paths.modules
@@ -531,17 +571,36 @@ module.exports = NodeHelper.create({
     }
   },
 
+  /**
+   * Handle POST API requests
+   * @param {object} query - Query parameters
+   * @param {object} request - Express request object
+   * @param {object} res - Express response object
+   * @returns {void}
+   */
   answerPost (query, request, res) {
     if (query.data === "config") {
       this.saveConfigWithBackup(request.body, res, query);
     }
   },
 
+  /**
+   * Handle request for list of available modules
+   * @param {object} query - Query parameters
+   * @param {object} res - Express response object
+   * @returns {void}
+   */
   handleGetModuleAvailable (query, res) {
     this.modulesAvailable.sort((a, b) => a.name.localeCompare(b.name));
     this.sendResponse(res, undefined, {query, data: this.modulesAvailable});
   },
 
+  /**
+   * Handle request for list of installed modules
+   * @param {object} query - Query parameters
+   * @param {object} res - Express response object
+   * @returns {void}
+   */
   handleGetModuleInstalled (query, res) {
 
     // Wait for pending update checks to complete before sending response
@@ -653,6 +712,13 @@ module.exports = NodeHelper.create({
     };
   },
 
+  /**
+   * Handle GET API requests
+   * @param {object} query - Query parameters
+   * @param {string} query.data - Data type requested
+   * @param {object} res - Express response object
+   * @returns {void}
+   */
   answerGet (query, res) {
     const handlers = this.getDataHandlers();
     const handler = handlers[query.data];
@@ -1100,6 +1166,13 @@ module.exports = NodeHelper.create({
     return false;
   },
 
+  /**
+   * Install a module from a git repository
+   * @param {string} url - Git repository URL
+   * @param {object} res - Express response object
+   * @param {object} data - Additional installation data
+   * @returns {void}
+   */
   installModule (url, res, data) {
 
     simpleGit(path.resolve(`${__dirname}/..`)).clone(url, path.basename(url), (error) => {
@@ -1330,6 +1403,12 @@ module.exports = NodeHelper.create({
     return addresses;
   },
 
+  /**
+   * Handle socket notifications from the frontend module
+   * @param {string} notification - Notification type
+   * @param {object | ConfigData} payload - Notification payload (varies by type)
+   * @returns {void}
+   */
   socketNotificationReceived (notification, payload) {
 
     if (notification === "CURRENT_STATUS") {

types.js

@@ -0,0 +1,98 @@
+/**
+ * @file Central type definitions for MMM-Remote-Control
+ * @module types
+ * @description
+ * This file contains JSDoc type definitions used throughout the codebase.
+ * Import these types in your files with:
+ * @example
+ * // @typedef {import('./types').ModuleData} ModuleData
+ */
+
+/**
+ * Module metadata from 3rd-party-modules repository
+ * @typedef {object} ModuleData
+ * @property {string} name - Module display name
+ * @property {string} id - GitHub repository identifier (e.g., "author/repo")
+ * @property {string} url - GitHub repository URL
+ * @property {string} maintainer - Module maintainer/author
+ * @property {string} [description] - Module description
+ * @property {string} [category] - Module category (e.g., "Weather", "Calendar")
+ * @property {string[]} [keywords] - Search keywords
+ * @property {number} [stars] - GitHub stars count
+ * @property {string} [image] - Preview image URL
+ * @property {string} [lastCommit] - Last commit date (ISO 8601)
+ * @property {string} [license] - License type (e.g., "MIT", "GPL-3.0")
+ * @property {boolean} [installed] - Whether module is installed locally
+ * @property {boolean} [isDefaultModule] - Whether module is a MagicMirror default
+ * @property {boolean} [hasChangelog] - Whether module has a changelog
+ * @property {object} [defaultConfig] - Default configuration object
+ */
+
+/**
+ * MagicMirror configuration data
+ * @typedef {object} ConfigData
+ * @property {string} [address] - Server address
+ * @property {number} [port] - Server port
+ * @property {string} [language] - Display language
+ * @property {string} [timeFormat] - Time format (12/24)
+ * @property {string} [units] - Unit system (metric/imperial)
+ * @property {ModuleConfig[]} modules - Module configurations
+ * @property {object} [electronOptions] - Electron-specific options
+ * @property {string[]} [ipWhitelist] - IP whitelist for access control
+ */
+
+/**
+ * Module configuration entry
+ * @typedef {object} ModuleConfig
+ * @property {string} module - Module name
+ * @property {string} [position] - Display position
+ * @property {string} [header] - Module header text
+ * @property {object} [config] - Module-specific configuration
+ * @property {string[]} [classes] - CSS classes
+ * @property {boolean} [disabled] - Whether module is disabled
+ */
+
+/**
+ * Backup metadata
+ * @typedef {object} BackupInfo
+ * @property {string} timestamp - ISO 8601 timestamp
+ * @property {string} filename - Backup filename
+ * @property {number} size - File size in bytes
+ * @property {string} [description] - Optional backup description
+ */
+
+/**
+ * API response structure
+ * @typedef {object} ApiResponse
+ * @property {boolean} success - Whether the operation succeeded
+ * @property {object | Array | string | number | boolean} [data] - Response data (type varies by endpoint)
+ * @property {string} [message] - Error or info message
+ * @property {object} [query] - Original query parameters
+ */
+
+/**
+ * Socket notification payload
+ * @typedef {object} NotificationPayload
+ * @property {string} notification - Notification type
+ * @property {object | Array | string | number | boolean | null} [payload] - Notification data
+ */
+
+/**
+ * Git operation result
+ * @typedef {object} GitResult
+ * @property {boolean} success - Whether git operation succeeded
+ * @property {string} [stdout] - Command stdout
+ * @property {string} [stderr] - Command stderr
+ * @property {number} [code] - Exit code
+ * @property {string} [error] - Error message
+ */
+
+/**
+ * Module installation options
+ * @typedef {object} InstallOptions
+ * @property {string} url - Git repository URL
+ * @property {number} [index] - Installation index in modules array
+ * @property {boolean} [skipNpmInstall] - Skip npm install after clone
+ */
+
+module.exports = {};