diff --git a/eslint.config.js b/eslint.config.js index 5d3e6b503..9a9e2816f 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -1,13 +1,14 @@ import eslintConfigESLint from "eslint-config-eslint"; -import { defineConfig, includeIgnoreFile } from "@eslint/config-helpers"; +import globals from "globals"; +import { + defineConfig, + globalIgnores, + includeIgnoreFile, +} from "@eslint/config-helpers"; import tseslint from "typescript-eslint"; import { fileURLToPath } from "node:url"; import path from "node:path"; -const eslintPluginJSDoc = eslintConfigESLint.find( - config => config.plugins?.jsdoc, -).plugins.jsdoc; - const filename = fileURLToPath(import.meta.url); const dirname = path.dirname(filename); @@ -15,29 +16,25 @@ export default defineConfig([ includeIgnoreFile(path.join(dirname, ".gitignore"), { gitignoreResolution: true, }), - - { - ignores: ["**/tests/fixtures/"], - }, - + globalIgnores(["**/tests/fixtures/"], "rewrite/global-ignores"), { + name: "rewrite/js", + files: ["**/*.js"], extends: [eslintConfigESLint], + settings: { + jsdoc: { + preferredTypes: { + object: "object", + }, + }, + }, 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", - ]), - ), }, }, - - // Tools and CLI { + name: "rewrite/tools", files: [ "scripts/**", "tools/**", @@ -48,30 +45,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 e50c73493..985157085 100644 --- a/package.json +++ b/package.json @@ -46,6 +46,7 @@ "c8": "^11.0.0", "eslint": "^10.0.3", "eslint-config-eslint": "^14.0.0", + "globals": "^17.7.0", "knip": "^6.0.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..15013c57a 100644 --- a/packages/compat/src/fixup-rules.js +++ b/packages/compat/src/fixup-rules.js @@ -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/src/ignore-file.js b/packages/compat/src/ignore-file.js index d8af09112..82ce0a64b 100644 --- a/packages/compat/src/ignore-file.js +++ b/packages/compat/src/ignore-file.js @@ -24,7 +24,6 @@ import path from "node:path"; * Converts an ESLint ignore pattern to a minimatch pattern. * @param {string} pattern The .eslintignore or .gitignore pattern to convert. * @returns {string} The converted pattern. - * * @deprecated Use the `convertIgnorePatternToMinimatch()` function exported by * `@eslint/config-helpers` instead. */ @@ -75,7 +74,6 @@ export function convertIgnorePatternToMinimatch(pattern) { * @param {string} [name] The name of the ignore file config. * @returns {FlatConfig} An object with an `ignores` property that is an array of ignore patterns. * @throws {Error} If the ignore file path is not an absolute path. - * * @deprecated Use the `includeIgnoreFile()` function exported by * `@eslint/config-helpers` instead (also available at `eslint/config`). */ diff --git a/packages/compat/tests/fixup-rules.test.js b/packages/compat/tests/fixup-rules.test.js index 23260cd7d..29246e8f8 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", () => { + /** + * Legacy function-style rule fixture without metadata. + * @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", () => { + /** + * Legacy function-style rule fixture with a top-level schema. + * @type {LegacyRuleDefinition} + */ function rule(context) { return { Identifier(node) { diff --git a/packages/config-array/fix-std__path-imports.js b/packages/config-array/fix-std__path-imports.js index 9966e0b93..f16a6b301 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 matches 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 match. + * @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 1ce15682d..e00415a04 100644 --- a/packages/config-array/src/config-array.js +++ b/packages/config-array/src/config-array.js @@ -154,6 +154,7 @@ function getConfigName(config) { * @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) { @@ -270,7 +271,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 ( @@ -367,6 +367,12 @@ async function normalize( const allowFunctions = extraConfigTypes.includes("function"); const allowArrays = extraConfigTypes.includes("array"); + /** + * Recursively flattens items and resolves config functions into config objects. + * @param {Array} array The array to traverse. + * @returns {AsyncGenerator} Async generator yielding config objects. + * @throws {TypeError} If functions or arrays are not allowed, or if a config function returns another function. + */ async function* flatTraverse(array) { for (let item of array) { if (typeof item === "function") { @@ -431,6 +437,12 @@ function normalizeSync( const allowFunctions = extraConfigTypes.includes("function"); const allowArrays = extraConfigTypes.includes("array"); + /** + * Recursively flattens items and resolves config functions into config objects. + * @param {Array} array The array to traverse. + * @returns {Generator} Generator yielding config objects. + * @throws {TypeError} If functions or arrays are not allowed, if a config function returns another function, or if it returns a promise. + */ function* flatTraverse(array) { for (let item of array) { if (typeof item === "function") { @@ -569,6 +581,12 @@ function shouldIgnorePath( */ function pathMatches(filePath, relativeFilePath, config) { // match both strings and functions + /** + * Matches a file matcher against the provided file path. + * @param {FileMatcher} pattern The matcher pattern or function. + * @returns {boolean} True if the string pattern matches `relativeFilePath` or the matcher function returns true for `filePath`, false otherwise. + * @throws {TypeError} If the matcher is not a string or function. + */ function match(pattern) { if (isString(pattern)) { return doMatch(relativeFilePath, pattern); @@ -731,7 +749,6 @@ export class ConfigArray extends Array { /** * Tracks if the array has been normalized. - * @property isNormalized * @type {boolean} * @private */ @@ -739,7 +756,6 @@ export class ConfigArray extends Array { /** * The schema used for validating and merging configs. - * @property schema * @type {ObjectSchemaInstance} * @private */ @@ -754,7 +770,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; @@ -770,7 +785,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..c4889c31a 100644 --- a/packages/config-array/src/files-and-ignores-schema.js +++ b/packages/config-array/src/files-and-ignores-schema.js @@ -9,6 +9,7 @@ /** @typedef {import("@eslint/object-schema").PropertyDefinition} PropertyDefinition */ /** @typedef {import("@eslint/object-schema").ObjectDefinition} ObjectDefinition */ +/** @typedef {import("./types.ts").FileMatcher} FileMatcher */ //------------------------------------------------------------------------------ // Helpers @@ -16,8 +17,8 @@ /** * Asserts that a given value is an array. - * @param {*} value The value to check. - * @returns {void} + * @param {unknown} value The value to check. + * @returns {asserts value is unknown[]} Asserts that the value is an array. * @throws {TypeError} When the value is not an array. */ function assertIsArray(value) { @@ -28,8 +29,8 @@ function assertIsArray(value) { /** * Asserts that a given value is an array containing only strings and functions. - * @param {*} value The value to check. - * @returns {void} + * @param {unknown} value The value to check. + * @returns {asserts value is FileMatcher[]} Asserts that the value is an array of file matchers. * @throws {TypeError} When the value is not an array of strings and functions. */ function assertIsArrayOfStringsAndFunctions(value) { @@ -48,8 +49,8 @@ function assertIsArrayOfStringsAndFunctions(value) { /** * Asserts that a given value is a non-empty array. - * @param {*} value The value to check. - * @returns {void} + * @param {unknown} value The value to check. + * @returns {asserts value is unknown[]} Asserts that the value is a non-empty array. * @throws {TypeError} When the value is not an array or an empty array. */ function assertIsNonEmptyArray(value) { diff --git a/packages/config-array/tests/config-array.test.js b/packages/config-array/tests/config-array.test.js index ac2bc10e7..6f9762618 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 to merge with the default `ConfigArray` constructor options. + * @returns {ConfigArray} The created instance. + */ function createConfigArray(options) { return new ConfigArray( [ @@ -298,6 +303,15 @@ describe("ConfigArray", () => { }); describe("Validation", () => { + /** + * Defines tests that assert validation errors in both async and sync normalize flows. + * @param {Object} options Test options. + * @param {boolean} [options.only=false] If true, run these tests exclusively. + * @param {string} options.title Test title prefix. + * @param {Iterable|Function|Object} options.configs Configs to pass to the `ConfigArray` constructor. + * @param {assert.AssertPredicate} options.expectedError Expected error matcher for `assert.rejects()` and `assert.throws()`. + * @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 40a3546ea..124d50f74 100644 --- a/packages/config-helpers/src/define-config.js +++ b/packages/config-helpers/src/define-config.js @@ -41,7 +41,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) { @@ -55,7 +55,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") { @@ -72,7 +72,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. @@ -92,7 +92,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)); @@ -139,7 +139,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; @@ -209,7 +209,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( @@ -244,7 +244,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) { @@ -297,7 +297,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++) { @@ -317,7 +317,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) { @@ -366,7 +366,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 }; @@ -397,7 +397,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) { @@ -493,7 +493,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/config-helpers/src/ignore-file.js b/packages/config-helpers/src/ignore-file.js index 2e1674e3d..dbc4ca3ac 100644 --- a/packages/config-helpers/src/ignore-file.js +++ b/packages/config-helpers/src/ignore-file.js @@ -20,7 +20,7 @@ import path from "node:path"; /** @typedef {import("@eslint/core").ConfigObject} Config */ /** - * @typedef {object} IncludeIgnoreFileOptionsObject + * @typedef {Object} IncludeIgnoreFileOptionsObject * @property {boolean} [gitignoreResolution] Whether to interpret the contents of an ignore file relative to the config file or the ignore file. * - gitignoreResolution: false (default): Interprets ignore patterns relative to the config file * - gitignoreResolution: true: Interprets the ignore patterns in a file relative to the ignore file @@ -85,8 +85,9 @@ export function convertIgnorePatternToMinimatch(pattern) { } /** - * @param {string} ignoreFilePath - * @returns {string[]} + * Reads an ignore file and converts its entries to minimatch patterns. + * @param {string} ignoreFilePath The absolute path to the ignore file. + * @returns {string[]} The minimatch patterns from the ignore file. */ function ignoreFilePathToPatterns(ignoreFilePath) { const ignoreFile = fs.readFileSync(ignoreFilePath, "utf8"); @@ -100,9 +101,9 @@ function ignoreFilePathToPatterns(ignoreFilePath) { /** * Helper to parse and validate the options to `includeIgnoreFile()` - * - * @param {string | { gitignoreResolution?: unknown, name?: unknown } | undefined} options - * @returns {{ gitignoreResolution: boolean, name: string }} + * @param {string | { gitignoreResolution?: unknown, name?: unknown } | undefined} options The options to parse. + * @returns {{ gitignoreResolution: boolean, name: string }} The normalized options. + * @throws {TypeError} If options is not an object or string, or if an option has an invalid type. */ function parseOptions(options) { // legacy compatibility with @eslint/compat's `includeIgnoreFile` @@ -136,9 +137,6 @@ function parseOptions(options) { /** * @overload - * - * Reads ignore files and returns objects with the ignore patterns. - * * @param {string[]} ignoreFilePathArg The paths of ignore files to include. * @param {IncludeIgnoreFileOptions} [options] * @returns {Config[]} @@ -146,9 +144,6 @@ function parseOptions(options) { /** * @overload - * - * Reads an ignore file and returns an object with the ignore patterns. - * * @param {string} ignoreFilePathArg The path of the ignore file to include. * @param {IncludeIgnoreFileOptions} [options] * @returns {Config} @@ -156,9 +151,6 @@ function parseOptions(options) { /** * @overload - * - * Reads an ignore file(s) and returns an object(s) with the ignore patterns. - * * @param {string[] | string} ignoreFilePathArg The path(s) of the ignore file(s) to include. * @param {IncludeIgnoreFileOptions} [options] * @returns {Config[] | Config} @@ -166,10 +158,11 @@ function parseOptions(options) { /** * Reads an ignore file(s) and returns an object(s) with the ignore patterns. - * * @param {string[] | string} ignoreFilePathArg The path(s) of the ignore file(s) to include. - * @param {IncludeIgnoreFileOptions} [options] - * @returns {Config[] | Config} + * @param {IncludeIgnoreFileOptions} [options] The options for including the ignore file(s). + * @returns {Config[] | Config} The config object(s) with the ignore patterns. + * @throws {TypeError} If the ignore file path argument contains a non-string value or if options are invalid. + * @throws {Error} If an ignore file path is not absolute. */ export function includeIgnoreFile(ignoreFilePathArg, options) { const returnSingleObject = !Array.isArray(ignoreFilePathArg); diff --git a/packages/mcp/tests/mcp-cli.test.js b/packages/mcp/tests/mcp-cli.test.js index 90573da87..40aeacb77 100644 --- a/packages/mcp/tests/mcp-cli.test.js +++ b/packages/mcp/tests/mcp-cli.test.js @@ -19,8 +19,9 @@ const forkedProcesses = new Set(); const EXECUTABLE_PATH = path.resolve("./src/mcp-cli.js"); /** - * Forks the process to run an instance of ESLint. - * @returns {childProcess.ChildProcess} The resulting child process + * Forks the process to run an instance of the MCP server. + * @param {childProcess.ForkOptions} [options] Options to merge with the defaults passed to `childProcess.fork()`. + * @returns {childProcess.ChildProcess} The resulting child process. */ function runServer(options) { const newProcess = childProcess.fork( diff --git a/packages/migrate-config/src/migrate-config.js b/packages/migrate-config/src/migrate-config.js index 0a6b633ca..8fd82c677 100644 --- a/packages/migrate-config/src/migrate-config.js +++ b/packages/migrate-config/src/migrate-config.js @@ -87,7 +87,6 @@ class Migration { /** * Creates a migration object. - * * @param {TargetVersion} targetVersion The target version for the migration. */ constructor(targetVersion) { @@ -411,7 +410,7 @@ function convertGlobPattern(pattern) { function createGitignoreEntry(migration) { migration.inits.push(getGitignoreInit()); - /** @type string */ + /** @type {string} */ let code; if (migration.targetVersion === "9") { @@ -642,6 +641,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 `files` is neither an array expression nor a string literal. */ function createFilesArrayFromNode(files) { if (files.type === "ArrayExpression") { @@ -1132,6 +1132,10 @@ function convertLegacyConfigExpression(config, migration) { /** @type {ObjectExpression} */ let globals; + /** + * Adds the languageOptions property to the output config object if it hasn't been created yet. + * @returns {void} + */ function createLanguageOptionsNode() { if (languageOptionsProperties.length === 0) { newProperties.push( @@ -1144,6 +1148,10 @@ function convertLegacyConfigExpression(config, migration) { } } + /** + * Adds the globals property to the languageOptions object when globals are available. + * @returns {void} + */ function createGlobalsNode() { if (globals) { languageOptionsProperties.push( @@ -1582,6 +1590,7 @@ export function migrateConfig( * @param {TargetVersion} options.targetVersion The target version of ESLint for the migration. * @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 a supported object expression. */ export function migrateJSConfig( code, diff --git a/packages/plugin-kit/src/source-code.js b/packages/plugin-kit/src/source-code.js index 3f661b465..ad9dd3586 100644 --- a/packages/plugin-kit/src/source-code.js +++ b/packages/plugin-kit/src/source-code.js @@ -634,6 +634,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..8c988f2cb 100644 --- a/packages/plugin-kit/tests/source-code.test.js +++ b/packages/plugin-kit/tests/source-code.test.js @@ -1938,6 +1938,10 @@ describe("source-code", () => { [node1, undefined], ]); + /** + * Test helper subclass that overrides getParent() to exercise + * getAncestors() with a parent map. + */ 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 7f4ae65e5..9dfd1ac10 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( @@ -146,8 +146,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(", ")}`, @@ -187,7 +187,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..15060820e 100644 --- a/scripts/shared.js +++ b/scripts/shared.js @@ -79,6 +79,14 @@ export function createBuildOrder(dependencies) { const buildOrder = []; const seen = new Set(); + /** + * Recursively visits a package's monorepo dependencies before adding the + * package to the build order. + * External dependencies are ignored because only packages in this monorepo + * need to be built. + * @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 = [];