feat: create linter system

bin/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { resolve } from 'node:path';
-import { argv } from 'node:process';
+import { argv, exit } from 'node:process';
 
 import { Command, Option } from 'commander';
 
@@ -12,6 +12,8 @@ import generators from '../src/generators/index.mjs';
 import createMarkdownLoader from '../src/loaders/markdown.mjs';
 import createMarkdownParser from '../src/parsers/markdown.mjs';
 import createNodeReleases from '../src/releases.mjs';
+import createLinter from '../src/linter/index.mjs';
+import reporters from '../src/linter/reporters/index.mjs';
 
 const availableGenerators = Object.keys(generators);
 
@@ -50,6 +52,14 @@ program
       'Set the processing target modes'
     ).choices(availableGenerators)
   )
+  .addOption(
+    new Option('--lint-dry-run', 'Run linter in dry-run mode').default(false)
+  )
+  .addOption(
+    new Option('-r, --reporter [reporter]', 'Specify the linter reporter')
+      .choices(Object.keys(reporters))
+      .default('console')
+  )
   .parse(argv);
 
 /**
@@ -60,13 +70,25 @@ program
  * @property {string} output Specifies the directory where output files will be saved.
  * @property {Target[]} target Specifies the generator target mode.
  * @property {string} version Specifies the target Node.js version.
- * @property {string} changelog Specifies the path to the Node.js CHANGELOG.md file
+ * @property {string} changelog Specifies the path to the Node.js CHANGELOG.md file.
+ * @property {boolean} lintDryRun Specifies whether the linter should run in dry-run mode.
+ * @property {keyof reporters} reporter Specifies the linter reporter.
  *
  * @name ProgramOptions
  * @type {Options}
  * @description The return type for values sent to the program from the CLI.
  */
-const { input, output, target = [], version, changelog } = program.opts();
+const {
+  input,
+  output,
+  target = [],
+  version,
+  changelog,
+  lintDryRun,
+  reporter,
+} = program.opts();
+
+const linter = createLinter(lintDryRun);
 
 const { loadFiles } = createMarkdownLoader();
 const { parseApiDocs } = createMarkdownParser();
@@ -80,6 +102,8 @@ const { runGenerators } = createGenerator(parsedApiDocs);
 // Retrieves Node.js release metadata from a given Node.js version and CHANGELOG.md file
 const { getAllMajors } = createNodeReleases(changelog);
 
+linter.lintAll(parsedApiDocs);
+
 await runGenerators({
   // A list of target modes for the API docs parser
   generators: target,
@@ -92,3 +116,7 @@ await runGenerators({
   // A list of all Node.js major versions with LTS status
   releases: await getAllMajors(),
 });
+
+linter.report(reporter);
+
+exit(Number(linter.hasError()));

package.json

@@ -30,6 +30,7 @@
   },
   "dependencies": {
     "acorn": "^8.14.0",
+    "@actions/core": "^1.11.1",
     "commander": "^13.1.0",
     "estree-util-visit": "^2.0.0",
     "dedent": "^1.5.3",

src/constants.mjs

@@ -125,17 +125,45 @@ export const DOC_SLUG_ENVIRONMENT = 'environment-variables-1';
 // JavaScript globals types within the MDN JavaScript docs
 // @see DOC_MDN_BASE_URL_JS_GLOBALS
 export const DOC_TYPES_MAPPING_GLOBALS = {
-  ...Object.fromEntries([
-    'AggregateError', 'Array', 'ArrayBuffer', 'DataView', 'Date', 'Error',
-    'EvalError', 'Function', 'Map', 'NaN', 'Object', 'Promise', 'Proxy', 'RangeError',
-    'ReferenceError', 'RegExp', 'Set', 'SharedArrayBuffer', 'SyntaxError', 'Symbol',
-    'TypeError', 'URIError', 'WeakMap', 'WeakSet',
-
-    'TypedArray',
-    'Float32Array', 'Float64Array',
-    'Int8Array', 'Int16Array', 'Int32Array',
-    'Uint8Array', 'Uint8ClampedArray', 'Uint16Array', 'Uint32Array',
-  ].map(e => [e, e])),
+  ...Object.fromEntries(
+    [
+      'AggregateError',
+      'Array',
+      'ArrayBuffer',
+      'DataView',
+      'Date',
+      'Error',
+      'EvalError',
+      'Function',
+      'Map',
+      'NaN',
+      'Object',
+      'Promise',
+      'Proxy',
+      'RangeError',
+      'ReferenceError',
+      'RegExp',
+      'Set',
+      'SharedArrayBuffer',
+      'SyntaxError',
+      'Symbol',
+      'TypeError',
+      'URIError',
+      'WeakMap',
+      'WeakSet',
+
+      'TypedArray',
+      'Float32Array',
+      'Float64Array',
+      'Int8Array',
+      'Int16Array',
+      'Int32Array',
+      'Uint8Array',
+      'Uint8ClampedArray',
+      'Uint16Array',
+      'Uint32Array',
+    ].map(e => [e, e])
+  ),
   bigint: 'BigInt',
   'WebAssembly.Instance': 'WebAssembly/Instance',
 };
@@ -392,3 +420,9 @@ export const DOC_TYPES_MAPPING_OTHER = {
   Response: `${DOC_MDN_BASE_URL}/API/Response`,
   Request: `${DOC_MDN_BASE_URL}/API/Request`,
 };
+
+export const LINT_MESSAGES = {
+  missingIntroducedIn: "Missing 'introduced_in' field in the API doc entry",
+  missingChangeVersion: 'Missing version field in the API doc entry',
+  invalidChangeVersion: 'Invalid version number: {{version}}',
+};

src/linter/index.mjs

@@ -0,0 +1,94 @@
+'use strict';
+
+import reporters from './reporters/index.mjs';
+import { invalidChangeVersion } from './rules/invalid-change-version.mjs';
+import { missingChangeVersion } from './rules/missing-change-version.mjs';
+import { missingIntroducedIn } from './rules/missing-introduced-in.mjs';
+
+/**
+ * Creates a linter instance to validate ApiDocMetadataEntry entries
+ *
+ * @param {boolean} dryRun Whether to run the linter in dry-run mode
+ */
+const createLinter = dryRun => {
+  /**
+   * Lint issues found during validations
+   *
+   * @type {Array<import('./types.d.ts').LintIssue>}
+   */
+  const issues = [];
+
+  /**
+   * Lint rules to validate the entries against
+   *
+   * @type {Array<import('./types.d.ts').LintRule>}
+   */
+  const rules = [
+    missingIntroducedIn,
+    missingChangeVersion,
+    invalidChangeVersion,
+  ];
+
+  /**
+   * Validates a ApiDocMetadataEntry entry against all defined rules
+   *
+   * @param {ApiDocMetadataEntry} entry
+   * @returns {void}
+   */
+  const lint = entry => {
+    for (const rule of rules) {
+      const ruleIssues = rule(entry);
+
+      if (ruleIssues.length > 0) {
+        issues.push(...ruleIssues);
+      }
+    }
+  };
+
+  /**
+   * Validates an array of ApiDocMetadataEntry entries against all defined rules
+   *
+   * @param {ApiDocMetadataEntry[]} entries
+   * @returns {void}
+   */
+  const lintAll = entries => {
+    for (const entry of entries) {
+      lint(entry);
+    }
+  };
+
+  /**
+   * Reports found issues using the specified reporter
+   *
+   * @param {keyof typeof reporters} reporterName Reporter name
+   * @returns {void}
+   */
+  const report = reporterName => {
+    if (dryRun) {
+      return;
+    }
+
+    const reporter = reporters[reporterName];
+
+    for (const issue of issues) {
+      reporter(issue);
+    }
+  };
+
+  /**
+   * Checks if any error-level issues were found during linting
+   *
+   * @returns {boolean}
+   */
+  const hasError = () => {
+    return issues.some(issue => issue.level === 'error');
+  };
+
+  return {
+    lintAll,
+    report,
+    hasError,
+  };
+};
+
+export default createLinter;

src/linter/reporters/console.mjs

@@ -0,0 +1,31 @@
+'use strict';
+
+import { styleText } from 'node:util';
+
+/**
+ * @type {Record<import('../types.d.ts').IssueLevel, string>}
+ */
+const levelToColorMap = {
+  info: 'gray',
+  warn: 'yellow',
+  error: 'red',
+};
+
+/**
+ * Console reporter
+ *
+ * @type {import('../types.d.ts').Reporter}
+ */
+export default issue => {
+  const position = issue.location.position
+    ? ` (${issue.location.position.start.line}:${issue.location.position.end.line})`
+    : '';
+
+  console.log(
+    styleText(
+      // @ts-expect-error ForegroundColors is not exported
+      levelToColorMap[issue.level],
+      `${issue.message} at ${issue.location.path}${position}`
+    )
+  );
+};