feat: create linter system (#191)

* feat: linter

Signed-off-by: flakey5 <[email protected]>

* feat: wip

* fix: optional location

* fix: create hasError getter

* fix: optional location

* test: update expected metadata

* refactor: some changes

* fix: missing reporter option

* fix: reporter node position

* refactor: some improvements

* refactor: better docs

* refactor: remove useless directive

* refactor: remove semver regex

* refactor: add yaml_position description

* test: create rules tests

* test: create reporters tests

* fix: missing change version issue location

* feat: add disable rule cli option

* test: create engine test

* feat: create cli option

* test: oops

* chore: add FORCE_COLOR env

---------

Signed-off-by: flakey5 <[email protected]>
Co-authored-by: flakey5 <[email protected]>

Author: araujogui

.github/workflows/pr.yml

@@ -9,6 +9,9 @@ on:
 permissions:
   contents: read
 
+env:
+  FORCE_COLOR: 1
+
 jobs:
   build:
     runs-on: ubuntu-latest

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,9 @@ 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';
+import rules from '../src/linter/rules/index.mjs';
 
 const availableGenerators = Object.keys(generators);
 
@@ -50,6 +53,19 @@ program
       'Set the processing target modes'
     ).choices(availableGenerators)
   )
+  .addOption(
+    new Option('--disable-rule [rule...]', 'Disable a specific linter rule')
+      .choices(Object.keys(rules))
+      .default([])
+  )
+  .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 +76,27 @@ 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 {string[]} disableRule Specifies the linter rules to disable.
+ * @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,
+  disableRule,
+  lintDryRun,
+  reporter,
+} = program.opts();
+
+const linter = createLinter(lintDryRun, disableRule);
 
 const { loadFiles } = createMarkdownLoader();
 const { parseApiDocs } = createMarkdownParser();
@@ -80,6 +110,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 +124,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-lock.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",

package.json

@@ -420,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/constants.mjs

@@ -0,0 +1,51 @@
+'use strict';
+
+/**
+ * Creates a linter engine instance to validate ApiDocMetadataEntry entries
+ *
+ * @param {import('./types').LintRule} rules Lint rules to validate the entries against
+ */
+const createLinterEngine = rules => {
+  /**
+   * Validates a ApiDocMetadataEntry entry against all defined rules
+   *
+   * @param {ApiDocMetadataEntry} entry
+   * @returns {import('./types').LintIssue[]}
+   */
+  const lint = entry => {
+    const issues = [];
+
+    for (const rule of rules) {
+      const ruleIssues = rule(entry);
+
+      if (ruleIssues.length > 0) {
+        issues.push(...ruleIssues);
+      }
+    }
+
+    return issues;
+  };
+
+  /**
+   * Validates an array of ApiDocMetadataEntry entries against all defined rules
+   *
+   * @param {ApiDocMetadataEntry[]} entries
+   * @returns {import('./types').LintIssue[]}
+   */
+  const lintAll = entries => {
+    const issues = [];
+
+    for (const entry of entries) {
+      issues.push(...lint(entry));
+    }
+
+    return issues;
+  };
+
+  return {
+    lint,
+    lintAll,
+  };
+};
+
+export default createLinterEngine;

src/linter/engine.mjs

@@ -0,0 +1,77 @@
+'use strict';
+
+import createLinterEngine from './engine.mjs';
+import reporters from './reporters/index.mjs';
+import rules from './rules/index.mjs';
+
+/**
+ * Creates a linter instance to validate ApiDocMetadataEntry entries
+ *
+ * @param {boolean} dryRun Whether to run the engine in dry-run mode
+ * @param {string[]} disabledRules List of disabled rules names
+ */
+const createLinter = (dryRun, disabledRules) => {
+  const engine = createLinterEngine(getEnabledRules(disabledRules));
+
+  /**
+   * Lint issues found during validations
+   *
+   * @type {Array<import('./types').LintIssue>}
+   */
+  const issues = [];
+
+  /**
+   * Lints all entries using the linter engine
+   *
+   * @param entries
+   */
+  const lintAll = entries => {
+    issues.push(...engine.lintAll(entries));
+  };
+
+  /**
+   * 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');
+  };
+
+  /**
+   * Retrieves all enabled rules
+   *
+   * @returns {import('./types').LintRule[]}
+   */
+  const getEnabledRules = () => {
+    return Object.entries(rules)
+      .filter(([ruleName]) => !disabledRules.includes(ruleName))
+      .map(([, rule]) => rule);
+  };
+
+  return {
+    lintAll,
+    report,
+    hasError,
+  };
+};
+
+export default createLinter;

src/linter/index.mjs

@@ -0,0 +1,30 @@
+'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})`
+    : '';
+
+  process.stdout.write(
+    styleText(
+      levelToColorMap[issue.level],
+      `${issue.message} at ${issue.location.path}${position}`
+    ) + '\n'
+  );
+};