From 477193606fa6736b4fe0058398b2c46928298c97 Mon Sep 17 00:00:00 2001 From: Pixel998 Date: Tue, 11 Nov 2025 03:29:23 +0300 Subject: [PATCH 1/2] chore: restore eslint-plugin-jsdoc rules --- eslint.config.js | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/eslint.config.js b/eslint.config.js index 57eaab003..628dadd0d 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -2,28 +2,17 @@ import eslintConfigESLint from "eslint-config-eslint"; import { defineConfig } from "@eslint/config-helpers"; import tseslint from "typescript-eslint"; -const eslintPluginJSDoc = eslintConfigESLint.find( - config => config.plugins?.jsdoc, -).plugins.jsdoc; - export default defineConfig([ { ignores: ["**/tests/fixtures/", "**/dist/", "**/coverage/"], }, { + files: ["**/*.js"], extends: [eslintConfigESLint], rules: { // disable rules we don't want to use from eslint-config-eslint "no-undefined": "off", - - // TODO: re-enable eslint-plugin-jsdoc rules - ...Object.fromEntries( - Object.keys(eslintPluginJSDoc.rules).map(name => [ - `jsdoc/${name}`, - "off", - ]), - ), }, }, From aee33e9c1f621758b6d32f2f0f5bd8356cbf2d0b Mon Sep 17 00:00:00 2001 From: Pixel998 Date: Sun, 30 Nov 2025 19:15:52 +0300 Subject: [PATCH 2/2] chore: restore eslint-plugin-jsdoc rules --- eslint.config.js | 35 +++++++---------- package.json | 1 + packages/compat/src/fixup-rules.js | 15 +++++--- packages/compat/tests/fixup-rules.test.js | 14 +++++++ packages/compat/tests/ignore-file.test.js | 2 +- .../config-array/fix-std__path-imports.js | 7 ++++ packages/config-array/src/config-array.js | 38 +++++++++++++------ .../src/files-and-ignores-schema.js | 6 +-- .../config-array/tests/config-array.test.js | 14 +++++++ packages/config-helpers/src/define-config.js | 24 ++++++------ packages/mcp/tests/mcp-cli.test.js | 1 + packages/migrate-config/src/migrate-config.js | 10 +++++ packages/object-schema/src/merge-strategy.js | 18 ++++----- .../object-schema/src/validation-strategy.js | 14 +++---- packages/plugin-kit/src/source-code.js | 13 ++++--- packages/plugin-kit/tests/source-code.test.js | 3 ++ scripts/publish.js | 14 +++---- scripts/shared.js | 7 ++++ tools/new-pkg.js | 2 +- 19 files changed, 154 insertions(+), 84 deletions(-) diff --git a/eslint.config.js b/eslint.config.js index 628dadd0d..fbb4625dd 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -1,13 +1,15 @@ import eslintConfigESLint from "eslint-config-eslint"; -import { defineConfig } from "@eslint/config-helpers"; +import globals from "globals"; +import { defineConfig, globalIgnores } from "@eslint/config-helpers"; import tseslint from "typescript-eslint"; export default defineConfig([ + globalIgnores( + ["**/tests/fixtures/", "**/dist/", "**/coverage/"], + "rewrite/global-ignores", + ), { - ignores: ["**/tests/fixtures/", "**/dist/", "**/coverage/"], - }, - - { + name: "rewrite/js", files: ["**/*.js"], extends: [eslintConfigESLint], rules: { @@ -15,9 +17,8 @@ export default defineConfig([ "no-undefined": "off", }, }, - - // Tools and CLI { + name: "rewrite/tools", files: [ "scripts/**", "tools/**", @@ -28,30 +29,22 @@ export default defineConfig([ "n/no-process-exit": "off", }, }, - { + name: "rewrite/tests", files: ["**/tests/**"], languageOptions: { globals: { - describe: "readonly", - xdescribe: "readonly", - it: "readonly", - xit: "readonly", - beforeEach: "readonly", - afterEach: "readonly", - before: "readonly", - after: "readonly", + ...globals.mocha, }, }, }, - - // TypeScript - ...tseslint.config({ + { + name: "rewrite/ts", files: ["**/*.ts"], ignores: ["**/tests/**/*.ts"], - extends: [...tseslint.configs.strict, ...tseslint.configs.stylistic], + extends: [tseslint.configs.strict, tseslint.configs.stylistic], rules: { "no-use-before-define": "off", }, - }), + }, ]); diff --git a/package.json b/package.json index 7870ba402..90636d454 100644 --- a/package.json +++ b/package.json @@ -39,6 +39,7 @@ "c8": "^10.1.3", "eslint": "^9.35.0", "eslint-config-eslint": "^13.0.0", + "globals": "^16.5.0", "knip": "^5.62.0", "lint-staged": "^16.0.0", "mocha": "^11.5.0", diff --git a/packages/compat/src/fixup-rules.js b/packages/compat/src/fixup-rules.js index e893f52e7..57c91b1a9 100644 --- a/packages/compat/src/fixup-rules.js +++ b/packages/compat/src/fixup-rules.js @@ -76,8 +76,8 @@ const fixedUpPlugins = new WeakSet(); /** * Determines if two nodes or tokens overlap. - * @param {object} first The first node or token to check. - * @param {object} second The second node or token to check. + * @param {Object} first The first node or token to check. + * @param {Object} second The second node or token to check. * @returns {boolean} True if the two nodes or tokens overlap. */ function nodesOrTokensOverlap(first, second) { @@ -90,7 +90,7 @@ function nodesOrTokensOverlap(first, second) { /** * Checks whether a node is an export declaration. - * @param {object} node An AST node. + * @param {Object} node An AST node. * @returns {boolean} True if the node is an export declaration. */ function looksLikeExport(node) { @@ -102,8 +102,8 @@ function looksLikeExport(node) { /** * Checks for the presence of a JSDoc comment for the given node and returns it. - * @param {object} node The AST node to get the comment for. - * @param {object} sourceCode A SourceCode instance to get comments. + * @param {Object} node The AST node to get the comment for. + * @param {Object} sourceCode A SourceCode instance to get comments. * @returns {object|null} The Block comment token containing the JSDoc comment * for the given node or null if not found. */ @@ -151,6 +151,11 @@ export function fixupRule(ruleDefinition) { ? ruleDefinition : ruleDefinition.create.bind(ruleDefinition); + /** + * Compatibility rule creator that adds missing methods to context and sourceCode objects. + * @param {Object} context The rule context. + * @returns {Object} The rule visitor. + */ function ruleCreate(context) { const sourceCode = context.sourceCode; diff --git a/packages/compat/tests/fixup-rules.test.js b/packages/compat/tests/fixup-rules.test.js index 23260cd7d..7ac2b2725 100644 --- a/packages/compat/tests/fixup-rules.test.js +++ b/packages/compat/tests/fixup-rules.test.js @@ -14,6 +14,12 @@ import { } from "../src/fixup-rules.js"; import { Linter } from "eslint"; +//----------------------------------------------------------------------------- +// Types +//----------------------------------------------------------------------------- + +/** @typedef {import("@eslint/core").RuleDefinition["create"]} LegacyRuleDefinition */ + //----------------------------------------------------------------------------- // Data //----------------------------------------------------------------------------- @@ -170,6 +176,10 @@ describe("@eslint/compat", () => { }); it("should return a rule object when a function-style rule is passed to fixupRule", () => { + /** + * Test fixture simulating a legacy function-style rule. + * @type {LegacyRuleDefinition} + */ function rule(context) { return { Identifier(node) { @@ -208,6 +218,10 @@ describe("@eslint/compat", () => { }); it("should return a rule object with `meta.schema` when a function-style rule with schema is passed to fixupRule", () => { + /** + * Test fixture simulating a legacy function-style rule. + * @type {LegacyRuleDefinition} + */ function rule(context) { return { Identifier(node) { diff --git a/packages/compat/tests/ignore-file.test.js b/packages/compat/tests/ignore-file.test.js index 60a48a8a6..a09292307 100644 --- a/packages/compat/tests/ignore-file.test.js +++ b/packages/compat/tests/ignore-file.test.js @@ -1,5 +1,5 @@ /** - * @filedescription Fixup tests + * @fileoverview Fixup tests */ //----------------------------------------------------------------------------- diff --git a/packages/config-array/fix-std__path-imports.js b/packages/config-array/fix-std__path-imports.js index 9966e0b93..e64ccc966 100644 --- a/packages/config-array/fix-std__path-imports.js +++ b/packages/config-array/fix-std__path-imports.js @@ -12,6 +12,13 @@ import { readFile, writeFile } from "node:fs/promises"; +/** + * Replaces all occurrences of a pattern in a file with a replacement string. + * @param {string} file The file path to modify. + * @param {RegExp} search The regular expression to search for. + * @param {string} replacement The replacement string. + * @returns {Promise} Resolves when the file has been written. + */ async function replaceInFile(file, search, replacement) { let text = await readFile(file, "utf-8"); text = text.replace(search, replacement); diff --git a/packages/config-array/src/config-array.js b/packages/config-array/src/config-array.js index 6163ee976..b08ea7bc6 100644 --- a/packages/config-array/src/config-array.js +++ b/packages/config-array/src/config-array.js @@ -147,9 +147,10 @@ function getConfigName(config) { /** * Rethrows a config error with additional information about the config object. - * @param {object} config The config object to get the name of. + * @param {ConfigObject} config The config object to get the name of. * @param {number} index The index of the config object in the array. * @param {Error} error The error to rethrow. + * @returns {void} * @throws {ConfigError} When the error is rethrown for a config. */ function rethrowConfigError(config, index, error) { @@ -160,7 +161,7 @@ function rethrowConfigError(config, index, error) { /** * Shorthand for checking if a value is a string. * @param {any} value The value to check. - * @returns {boolean} True if a string, false if not. + * @returns {value is string} True if a string, false if not. */ function isString(value) { return typeof value === "string"; @@ -220,8 +221,8 @@ function assertValidBaseConfig(config, index) { * faster matching speed over multiple file path evaluations. * @param {string} filepath The file path to match. * @param {string} pattern The glob pattern to match against. - * @param {object} options The minimatch options to use. - * @returns + * @param {MinimatchOptions} options The minimatch options to use. + * @returns {boolean} True if the filepath matches the pattern. */ function doMatch(filepath, pattern, options = {}) { let cache = minimatchCache; @@ -266,7 +267,6 @@ function normalizePattern(pattern) { * Checks if a given pattern requires normalization. * @param {any} pattern The pattern to check. * @returns {boolean} True if the pattern needs normalization, false otherwise. - * */ function needsPatternNormalization(pattern) { return ( @@ -363,6 +363,12 @@ async function normalize( const allowFunctions = extraConfigTypes.includes("function"); const allowArrays = extraConfigTypes.includes("array"); + /** + * Recursively flattens and resolves items in the array into config objects. + * @param {Array} array The array to traverse. + * @returns {AsyncGenerator} Async generator yielding config objects. + * @throws {TypeError} If an unexpected function or array is encountered. + */ async function* flatTraverse(array) { for (let item of array) { if (typeof item === "function") { @@ -395,7 +401,7 @@ async function normalize( * Async iterables cannot be used with the spread operator, so we need to manually * create the array to return. */ - const asyncIterable = await flatTraverse(items); + const asyncIterable = flatTraverse(items); const configs = []; for await (const config of asyncIterable) { @@ -427,6 +433,12 @@ function normalizeSync( const allowFunctions = extraConfigTypes.includes("function"); const allowArrays = extraConfigTypes.includes("array"); + /** + * Recursively flattens and resolves items in the array into config objects. + * @param {Array} array The array to traverse. + * @returns {Generator} Generator yielding config objects. + * @throws {TypeError} If an unexpected function, array, or async function is encountered. + */ function* flatTraverse(array) { for (let item of array) { if (typeof item === "function") { @@ -484,13 +496,13 @@ function toRelativePath(fileOrDirPath, namespacedBasePath, path) { /** * Determines if a given file path should be ignored based on the given * matcher. - * @param {Array<{ basePath?: string, ignores: Array boolean)>}>} configs Configuration objects containing `ignores`. + * @param {Array<{ basePath?: string, ignores: Array boolean)>}>} configs Configuration objects containing `ignores`. * @param {string} filePath The unprocessed file path to check. * @param {string} relativeFilePath The path of the file to check relative to the base path, * using forward slash (`"/"`) as a separator. * @param {Object} [basePathData] Additional data needed to recalculate paths for configuration objects * that have `basePath` property. - * @param {string} [basePathData.basePath] Namespaced path to witch `relativeFilePath` is relative. + * @param {string} [basePathData.basePath] Namespaced path to which `relativeFilePath` is relative. * @param {PathImpl} [basePathData.path] Path-handling implementation. * @returns {boolean} True if the path should be ignored and false if not. */ @@ -565,6 +577,12 @@ function shouldIgnorePath( */ function pathMatches(filePath, relativeFilePath, config) { // match both strings and functions + /** + * Matches a pattern against the provided file path. + * @param {string|((filePath: string) => boolean)} pattern The matcher pattern or function. + * @returns {boolean} True if the pattern matches, false otherwise. + * @throws {TypeError} When the matcher type is unexpected. + */ function match(pattern) { if (isString(pattern)) { return doMatch(relativeFilePath, pattern); @@ -725,7 +743,6 @@ export class ConfigArray extends Array { /** * Tracks if the array has been normalized. - * @property isNormalized * @type {boolean} * @private */ @@ -733,7 +750,6 @@ export class ConfigArray extends Array { /** * The schema used for validating and merging configs. - * @property schema * @type {ObjectSchemaInstance} * @private */ @@ -748,7 +764,6 @@ export class ConfigArray extends Array { /** * The path of the config file that this array was loaded from. * This is used to calculate filename matches. - * @property basePath * @type {string} */ this.basePath = basePath; @@ -764,7 +779,6 @@ export class ConfigArray extends Array { /** * A cache to store calculated configs for faster repeat lookup. - * @property configCache * @type {Map} * @private */ diff --git a/packages/config-array/src/files-and-ignores-schema.js b/packages/config-array/src/files-and-ignores-schema.js index 3c3adb462..9fce65efc 100644 --- a/packages/config-array/src/files-and-ignores-schema.js +++ b/packages/config-array/src/files-and-ignores-schema.js @@ -16,7 +16,7 @@ /** * Asserts that a given value is an array. - * @param {*} value The value to check. + * @param {any} value The value to check. * @returns {void} * @throws {TypeError} When the value is not an array. */ @@ -28,7 +28,7 @@ function assertIsArray(value) { /** * Asserts that a given value is an array containing only strings and functions. - * @param {*} value The value to check. + * @param {any} value The value to check. * @returns {void} * @throws {TypeError} When the value is not an array of strings and functions. */ @@ -48,7 +48,7 @@ function assertIsArrayOfStringsAndFunctions(value) { /** * Asserts that a given value is a non-empty array. - * @param {*} value The value to check. + * @param {any} value The value to check. * @returns {void} * @throws {TypeError} When the value is not an array or an empty array. */ diff --git a/packages/config-array/tests/config-array.test.js b/packages/config-array/tests/config-array.test.js index 707dc8e13..ebb7a35e1 100644 --- a/packages/config-array/tests/config-array.test.js +++ b/packages/config-array/tests/config-array.test.js @@ -60,6 +60,11 @@ const CSSLanguage = class {}; const MarkdownLanguage = class {}; const JSONLanguage = class {}; +/** + * Creates a `ConfigArray` pre-populated with test fixtures. + * @param {Object} [options] Options passed to the `ConfigArray` constructor. + * @returns {ConfigArray} The created instance. + */ function createConfigArray(options) { return new ConfigArray( [ @@ -298,6 +303,15 @@ describe("ConfigArray", () => { }); describe("Validation", () => { + /** + * Helper to assert validation errors in both async and sync normalize flows. + * @param {Object} options Test options. + * @param {boolean} [options.only=false] If true, run this test exclusively. + * @param {string} options.title Test title prefix. + * @param {Iterable|Function|Object} options.configs Configs to test with. + * @param {assert.AssertPredicate} options.expectedError Expected error matcher. + * @returns {void} + */ function testValidationError({ only = false, title, diff --git a/packages/config-helpers/src/define-config.js b/packages/config-helpers/src/define-config.js index b2fb096fd..c930fbafd 100644 --- a/packages/config-helpers/src/define-config.js +++ b/packages/config-helpers/src/define-config.js @@ -40,7 +40,7 @@ const allowedGlobalIgnoreKeys = new Set(["basePath", "ignores", "name"]); * Gets the name of a config object. * @param {Config} config The config object. * @param {string} indexPath The index path of the config object. - * @return {string} The name of the config object. + * @returns {string} The name of the config object. */ function getConfigName(config, indexPath) { if (config.name) { @@ -54,7 +54,7 @@ function getConfigName(config, indexPath) { * Gets the name of an extension. * @param {SimpleExtendsElement} extension The extension. * @param {string} indexPath The index of the extension. - * @return {string} The name of the extension. + * @returns {string} The name of the extension. */ function getExtensionName(extension, indexPath) { if (typeof extension === "string") { @@ -71,7 +71,7 @@ function getExtensionName(extension, indexPath) { /** * Determines if a config object is a legacy config. * @param {Config|LegacyConfig} config The config object to check. - * @return {config is LegacyConfig} `true` if the config object is a legacy config. + * @returns {config is LegacyConfig} `true` if the config object is a legacy config. */ function isLegacyConfig(config) { // eslintrc's plugins must be an array; while flat config's must be an object. @@ -91,7 +91,7 @@ function isLegacyConfig(config) { /** * Determines if a config object is a global ignores config. * @param {Config} config The config object to check. - * @return {boolean} `true` if the config object is a global ignores config. + * @returns {boolean} `true` if the config object is a global ignores config. */ function isGlobalIgnores(config) { return Object.keys(config).every(key => allowedGlobalIgnoreKeys.has(key)); @@ -138,7 +138,7 @@ function getPluginMember(id) { * @param {string} userNamespace The namespace of the plugin. * @param {Plugin} plugin The plugin config object. * @param {Config} config The config object to normalize. - * @return {Config} The normalized config object. + * @returns {Config} The normalized config object. */ function normalizePluginConfig(userNamespace, plugin, config) { const pluginNamespace = plugin.meta?.namespace; @@ -208,7 +208,7 @@ function normalizePluginConfig(userNamespace, plugin, config) { * @param {Plugin} plugin The plugin object. * @param {Config|LegacyConfig|(Config|LegacyConfig)[]} pluginConfig The plugin config to normalize. * @param {string} pluginConfigName The name of the plugin config. - * @return {InfiniteConfigArray} The normalized plugin config. + * @returns {InfiniteConfigArray} The normalized plugin config. * @throws {TypeError} If the plugin config is a legacy config. */ function deepNormalizePluginConfig( @@ -243,7 +243,7 @@ function deepNormalizePluginConfig( * Finds a plugin config by name in the given config. * @param {Config} config The config object. * @param {string} pluginConfigName The name of the plugin config. - * @return {InfiniteConfigArray} The plugin config. + * @returns {InfiniteConfigArray} The plugin config. * @throws {TypeError} If the plugin config is not found or is a legacy config. */ function findPluginConfig(config, pluginConfigName) { @@ -296,7 +296,7 @@ function findPluginConfig(config, pluginConfigName) { * Flattens an array while keeping track of the index path. * @param {any[]} configList The array to traverse. * @param {string} indexPath The index path of the value in a multidimensional array. - * @return {IterableIterator<{indexPath:string, value:any}>} The flattened list of values. + * @returns {IterableIterator<{indexPath:string, value:any}>} The flattened list of values. */ function* flatTraverse(configList, indexPath = "") { for (let i = 0; i < configList.length; i++) { @@ -316,7 +316,7 @@ function* flatTraverse(configList, indexPath = "") { * Extends a list of config files by creating every combination of base and extension files. * @param {(string|string[])[]} [baseFiles] The base files. * @param {(string|string[])[]} [extensionFiles] The extension files. - * @return {(string|string[])[]} The extended files. + * @returns {(string|string[])[]} The extended files. */ function extendConfigFiles(baseFiles = [], extensionFiles = []) { if (!extensionFiles.length) { @@ -365,7 +365,7 @@ function extendConfigFiles(baseFiles = [], extensionFiles = []) { * @param {string} baseConfigName The name of the base config object. * @param {Config} extension The extension config object. * @param {string} extensionName The index of the extension config object. - * @return {Config} The extended config object. + * @returns {Config} The extended config object. */ function extendConfig(baseConfig, baseConfigName, extension, extensionName) { const result = { ...extension }; @@ -398,7 +398,7 @@ function extendConfig(baseConfig, baseConfigName, extension, extensionName) { * Processes a list of extends elements. * @param {ConfigWithExtends} config The config object. * @param {WeakMap} configNames The map of config objects to their names. - * @return {Config[]} The flattened list of config objects. + * @returns {Config[]} The flattened list of config objects. * @throws {TypeError} If the `extends` property is not an array or if nested `extends` is found. */ function processExtends(config, configNames) { @@ -494,7 +494,7 @@ function processExtends(config, configNames) { * Processes a list of config objects and arrays. * @param {ConfigWithExtends[]} configList The list of config objects and arrays. * @param {WeakMap} configNames The map of config objects to their names. - * @return {Config[]} The flattened list of config objects. + * @returns {Config[]} The flattened list of config objects. */ function processConfigList(configList, configNames) { return configList.flatMap(config => processExtends(config, configNames)); diff --git a/packages/mcp/tests/mcp-cli.test.js b/packages/mcp/tests/mcp-cli.test.js index 90573da87..5da1e8036 100644 --- a/packages/mcp/tests/mcp-cli.test.js +++ b/packages/mcp/tests/mcp-cli.test.js @@ -20,6 +20,7 @@ const EXECUTABLE_PATH = path.resolve("./src/mcp-cli.js"); /** * Forks the process to run an instance of ESLint. + * @param {childProcess.ForkOptions} [options] Options passed to childProcess.fork * @returns {childProcess.ChildProcess} The resulting child process */ function runServer(options) { diff --git a/packages/migrate-config/src/migrate-config.js b/packages/migrate-config/src/migrate-config.js index b1c33fd7b..db173df16 100644 --- a/packages/migrate-config/src/migrate-config.js +++ b/packages/migrate-config/src/migrate-config.js @@ -609,6 +609,7 @@ function createFilesArray(patterns) { * Creates an array expression from a node representing files. * @param {ArrayExpression|Literal} files The node to convert. * @returns {ArrayExpression} The AST for the array expression. + * @throws {TypeError} If the provided node is not an ArrayExpression or string Literal. */ function createFilesArrayFromNode(files) { if (files.type === "ArrayExpression") { @@ -1099,6 +1100,10 @@ function convertLegacyConfigExpression(config, migration) { /** @type {ObjectExpression} */ let globals; + /** + * Adds the languageOptions property to the config object if it hasn't been created yet. + * @returns {void} + */ function createLanguageOptionsNode() { if (languageOptionsProperties.length === 0) { newProperties.push( @@ -1111,6 +1116,10 @@ function convertLegacyConfigExpression(config, migration) { } } + /** + * Adds the globals property to the languageOptions object if globals are present. + * @returns {void} + */ function createGlobalsNode() { if (globals) { languageOptionsProperties.push( @@ -1547,6 +1556,7 @@ export function migrateConfig( * @param {boolean} [options.gitignore] `true` to include contents of a .gitignore file. * @returns {{code:string,messages:Array,imports:Map}} The migrated config and * any messages to display to the user. + * @throws {TypeError} If the config file does not export an object expression. */ export function migrateJSConfig( code, diff --git a/packages/object-schema/src/merge-strategy.js b/packages/object-schema/src/merge-strategy.js index 2358209fd..3a1e786fa 100644 --- a/packages/object-schema/src/merge-strategy.js +++ b/packages/object-schema/src/merge-strategy.js @@ -12,9 +12,9 @@ export class MergeStrategy { /** * Merges two keys by overwriting the first with the second. - * @param {*} value1 The value from the first object key. - * @param {*} value2 The value from the second object key. - * @returns {*} The second value. + * @param {any} value1 The value from the first object key. + * @param {any} value2 The value from the second object key. + * @returns {any} The second value. */ static overwrite(value1, value2) { return value2; @@ -23,9 +23,9 @@ export class MergeStrategy { /** * Merges two keys by replacing the first with the second only if the * second is defined. - * @param {*} value1 The value from the first object key. - * @param {*} value2 The value from the second object key. - * @returns {*} The second value if it is defined. + * @param {any} value1 The value from the first object key. + * @param {any} value2 The value from the second object key. + * @returns {any} The second value if it is defined. */ static replace(value1, value2) { if (typeof value2 !== "undefined") { @@ -37,9 +37,9 @@ export class MergeStrategy { /** * Merges two properties by assigning properties from the second to the first. - * @param {*} value1 The value from the first object key. - * @param {*} value2 The value from the second object key. - * @returns {*} A new object containing properties from both value1 and + * @param {any} value1 The value from the first object key. + * @param {any} value2 The value from the second object key. + * @returns {any} A new object containing properties from both value1 and * value2. */ static assign(value1, value2) { diff --git a/packages/object-schema/src/validation-strategy.js b/packages/object-schema/src/validation-strategy.js index c3123e79e..d4ac2f2de 100644 --- a/packages/object-schema/src/validation-strategy.js +++ b/packages/object-schema/src/validation-strategy.js @@ -12,7 +12,7 @@ export class ValidationStrategy { /** * Validates that a value is an array. - * @param {*} value The value to validate. + * @param {any} value The value to validate. * @returns {void} * @throws {TypeError} If the value is invalid. */ @@ -24,7 +24,7 @@ export class ValidationStrategy { /** * Validates that a value is a boolean. - * @param {*} value The value to validate. + * @param {any} value The value to validate. * @returns {void} * @throws {TypeError} If the value is invalid. */ @@ -36,7 +36,7 @@ export class ValidationStrategy { /** * Validates that a value is a number. - * @param {*} value The value to validate. + * @param {any} value The value to validate. * @returns {void} * @throws {TypeError} If the value is invalid. */ @@ -48,7 +48,7 @@ export class ValidationStrategy { /** * Validates that a value is a object. - * @param {*} value The value to validate. + * @param {any} value The value to validate. * @returns {void} * @throws {TypeError} If the value is invalid. */ @@ -60,7 +60,7 @@ export class ValidationStrategy { /** * Validates that a value is a object or null. - * @param {*} value The value to validate. + * @param {any} value The value to validate. * @returns {void} * @throws {TypeError} If the value is invalid. */ @@ -72,7 +72,7 @@ export class ValidationStrategy { /** * Validates that a value is a string. - * @param {*} value The value to validate. + * @param {any} value The value to validate. * @returns {void} * @throws {TypeError} If the value is invalid. */ @@ -84,7 +84,7 @@ export class ValidationStrategy { /** * Validates that a value is a non-empty string. - * @param {*} value The value to validate. + * @param {any} value The value to validate. * @returns {void} * @throws {TypeError} If the value is invalid. */ diff --git a/packages/plugin-kit/src/source-code.js b/packages/plugin-kit/src/source-code.js index c02da02f3..8900f2d2e 100644 --- a/packages/plugin-kit/src/source-code.js +++ b/packages/plugin-kit/src/source-code.js @@ -29,7 +29,7 @@ /** * Determines if a node has ESTree-style loc information. - * @param {object} node The node to check. + * @param {Object} node The node to check. * @returns {node is {loc:SourceLocation}} `true` if the node has ESTree-style loc information, `false` if not. */ function hasESTreeStyleLoc(node) { @@ -38,7 +38,7 @@ function hasESTreeStyleLoc(node) { /** * Determines if a node has position-style loc information. - * @param {object} node The node to check. + * @param {Object} node The node to check. * @returns {node is {position:SourceLocation}} `true` if the node has position-style range information, `false` if not. */ function hasPosStyleLoc(node) { @@ -47,7 +47,7 @@ function hasPosStyleLoc(node) { /** * Determines if a node has ESTree-style range information. - * @param {object} node The node to check. + * @param {Object} node The node to check. * @returns {node is {range:SourceRange}} `true` if the node has ESTree-style range information, `false` if not. */ function hasESTreeStyleRange(node) { @@ -56,7 +56,7 @@ function hasESTreeStyleRange(node) { /** * Determines if a node has position-style range information. - * @param {object} node The node to check. + * @param {Object} node The node to check. * @returns {node is {position:SourceLocationWithOffset}} `true` if the node has position-style range information, `false` if not. */ function hasPosStyleRange(node) { @@ -115,7 +115,7 @@ export class VisitNodeStep { /** * The target of the step. - * @type {object} + * @type {Object} */ target; @@ -134,7 +134,7 @@ export class VisitNodeStep { /** * Creates a new instance. * @param {Object} options The options for the step. - * @param {object} options.target The target of the step. + * @param {Object} options.target The target of the step. * @param {1|2} options.phase The phase of the step. * @param {Array} options.args The arguments of the step. */ @@ -623,6 +623,7 @@ export class TextSourceCodeBase { /** * Traverse the source code and return the steps that were taken. + * @abstract * @returns {Iterable} The steps that were taken while traversing the source code. */ traverse() { diff --git a/packages/plugin-kit/tests/source-code.test.js b/packages/plugin-kit/tests/source-code.test.js index cdd3f5ebd..3a8d5fda6 100644 --- a/packages/plugin-kit/tests/source-code.test.js +++ b/packages/plugin-kit/tests/source-code.test.js @@ -1938,6 +1938,9 @@ describe("source-code", () => { [node1, undefined], ]); + /** + * Test helper subclass that implements getParent() to exercise getAncestors(). + */ class TextSourceCode extends TextSourceCodeBase { // eslint-disable-next-line class-methods-use-this -- Testing purposes getParent(node) { diff --git a/scripts/publish.js b/scripts/publish.js index bdf816c92..3bafb71ef 100644 --- a/scripts/publish.js +++ b/scripts/publish.js @@ -50,7 +50,7 @@ const releaseOutputs = JSON.parse(process.env.STEPS_RELEASE_OUTPUTS); * Gets the output of a GitHub Actions step from the environment variables. * @param {string} packageDir The directory of the package. * @param {string} name The name of the output. - * @return {string} The output value. + * @returns {string} The output value. */ function getReleaseOutput(packageDir, name) { return releaseOutputs[`${packageDir}--${name}`]; @@ -59,7 +59,7 @@ function getReleaseOutput(packageDir, name) { /** * Gets the list of packages to publish. * @param {Array} packageDirs The list of package directories. - * @return {Array} The list of packages to publish. + * @returns {Array} The list of packages to publish. */ function getPackagesToPublish(packageDirs) { return packageDirs.filter( @@ -72,7 +72,7 @@ function getPackagesToPublish(packageDirs) { * Maps the dependencies into a structure where they keys are package * paths and the values are an array of package paths. * @param {Map }>} dependencies The dependencies to map. - * @return {Map>} The mapped dependencies. + * @returns {Map>} The mapped dependencies. */ function mapDependenciesToPaths(dependencies) { const mappedDependencies = new Map(); @@ -92,7 +92,7 @@ function mapDependenciesToPaths(dependencies) { * will still be published. * @param {Array} packageDirs The list of package directories. * @param {Map>} dependencies The dependencies between packages. - * @return {Map} A map of package directory to whether it was published successfully. + * @returns {Map} A map of package directory to whether it was published successfully. */ function publishPackagesToNpm(packageDirs, dependencies) { console.log( @@ -140,8 +140,8 @@ function publishPackagesToNpm(packageDirs, dependencies) { * Publishes the packages to JSR. If one package fails to publish, the rest * will still be published. * @param {Array} packageDirs The list of package directories. - * @return {Map} A map of package directory to whether it was published successfully. - **/ + * @returns {Map} A map of package directory to whether it was published successfully. + */ function publishPackagesToJsr(packageDirs) { console.log( `Publishing packages to JSR in this order: ${packageDirs.join(", ")}`, @@ -181,7 +181,7 @@ function publishPackagesToJsr(packageDirs) { /** * Posts the results to social media. * @param {Map} npmPublishResults The results of the npm publish. - * @return {void} + * @returns {void} */ function postResultToSocialMedia(npmPublishResults) { const messages = []; diff --git a/scripts/shared.js b/scripts/shared.js index 9de24264e..54466924b 100644 --- a/scripts/shared.js +++ b/scripts/shared.js @@ -79,6 +79,13 @@ export function createBuildOrder(dependencies) { const buildOrder = []; const seen = new Set(); + /** + * Recursively visits a package and its dependencies to determine build order. + * Visits all dependencies first (depth-first) before adding the current package + * to ensure dependencies are built before their dependents. + * @param {string} name The package name to visit. + * @returns {void} + */ function visit(name) { if (!seen.has(name)) { seen.add(name); diff --git a/tools/new-pkg.js b/tools/new-pkg.js index ada28ff20..44a482808 100644 --- a/tools/new-pkg.js +++ b/tools/new-pkg.js @@ -20,7 +20,7 @@ import { parseArgs } from "node:util"; /** * Recursively gets all files in a directory. * @param {string} dir The directory to search. - * @param {string[]} fileList The list of files found so far. + * @returns {string[]} The list of files found so far. */ function getAllFiles(dir) { const fileList = [];