feat: introduce raw ast linter

Author: araujogui

bin/commands/generate.mjs

@@ -1,6 +1,5 @@
 import { cpus } from 'node:os';
 import { resolve } from 'node:path';
-import process from 'node:process';
 
 import { coerce } from 'semver';
 
@@ -12,7 +11,8 @@ import createGenerator from '../../src/generators.mjs';
 import { publicGenerators } from '../../src/generators/index.mjs';
 import createNodeReleases from '../../src/releases.mjs';
 import { loadAndParse } from '../utils.mjs';
-import { runLint } from './lint.mjs';
+import createLinter from '../../src/linter/index.mjs';
+import { getEnabledRules } from '../../src/linter/utils/rules.mjs';
 
 const availableGenerators = Object.keys(publicGenerators);
 
@@ -123,12 +123,12 @@ export default {
    * @returns {Promise<void>}
    */
   async action(opts) {
-    const docs = await loadAndParse(opts.input, opts.ignore);
+    const linter = opts.skipLint
+      ? undefined
+      : createLinter(getEnabledRules(opts.disableRule));
+    const docs = await loadAndParse(opts.input, opts.ignore, linter);
 
-    if (!opts.skipLint && !runLint(docs)) {
-      console.error('Lint failed; aborting generation.');
-      process.exit(1);
-    }
+    linter.report();
 
     const { runGenerators } = createGenerator(docs);
     const { getAllMajors } = createNodeReleases(opts.changelog);

bin/commands/lint.mjs

@@ -4,6 +4,7 @@ import createLinter from '../../src/linter/index.mjs';
 import reporters from '../../src/linter/reporters/index.mjs';
 import rules from '../../src/linter/rules/index.mjs';
 import { loadAndParse } from '../utils.mjs';
+import { getEnabledRules } from '../../src/linter/utils/rules.mjs';
 
 const availableRules = Object.keys(rules);
 const availableReporters = Object.keys(reporters);
@@ -17,22 +18,6 @@ const availableReporters = Object.keys(reporters);
  * @property {keyof reporters} reporter - Reporter for linter output.
  */
 
-/**
- * Run the linter on parsed documentation.
- * @param {ApiDocMetadataEntry[]} docs - Parsed documentation objects.
- * @param {LinterOptions} options - Linter configuration options.
- * @returns {boolean} - True if no errors, false otherwise.
- */
-export function runLint(
-  docs,
-  { disableRule = [], dryRun = false, reporter = 'console' } = {}
-) {
-  const linter = createLinter(dryRun, disableRule);
-  linter.lintAll(docs);
-  linter.report(reporter);
-  return !linter.hasError();
-}
-
 /**
  * @type {import('../utils.mjs').Command}
  */
@@ -95,9 +80,14 @@ export default {
    */
   async action(opts) {
     try {
-      const docs = await loadAndParse(opts.input, opts.ignore);
-      const success = runLint(docs, opts);
-      process.exitCode = success ? 0 : 1;
+      const rules = getEnabledRules(opts.disableRule);
+      const linter = createLinter(rules, opts.dryRun);
+
+      await loadAndParse(opts.input, opts.ignore, linter);
+
+      linter.report();
+
+      process.exitCode = linter.hasError() ? 1 : 0;
     } catch (error) {
       console.error('Error running the linter:', error);
       process.exitCode = 1;

bin/utils.mjs

@@ -9,7 +9,7 @@ import createMarkdownParser from '../src/parsers/markdown.mjs';
  */
 export const lazy = factory => {
   let instance;
-  return () => (instance ??= factory());
+  return args => (instance ??= factory(args));
 };
 
 // Instantiate loader and parser once to reuse,
@@ -23,11 +23,12 @@ const parser = lazy(createMarkdownParser);
  * Load and parse markdown API docs.
  * @param {string[]} input - Glob patterns for input files.
  * @param {string[]} [ignore] - Glob patterns to ignore.
+ * @param {import('../src/linter/types').Linter} [linter] - Linter instance
  * @returns {Promise<ApiDocMetadataEntry[]>} - Parsed documentation objects.
  */
-export async function loadAndParse(input, ignore) {
+export async function loadAndParse(input, ignore, linter) {
   const files = await loader().loadFiles(input, ignore);
-  return parser().parseApiDocs(files);
+  return parser(linter).parseApiDocs(files);
 }
 
 /**

package-lock.json

@@ -56,7 +56,9 @@
     "shiki": "^3.2.1",
     "unified": "^11.0.5",
     "unist-builder": "^4.0.0",
+    "unist-util-find": "^3.0.0",
     "unist-util-find-after": "^5.0.0",
+    "unist-util-find-before": "^4.0.1",
     "unist-util-position": "^5.0.0",
     "unist-util-remove": "^4.0.0",
     "unist-util-select": "^5.1.0",

package.json

@@ -0,0 +1,59 @@
+'use strict';
+
+/**
+ * Creates a linting context for a given file and AST tree.
+ *
+ * @param {import('vfile').VFile} file
+ * @param {import('mdast').Root} tree
+ * @returns {import('./types').LintContext}
+ */
+const createContext = (file, tree) => {
+  /**
+   * Lint issues reported during validation.
+   *
+   * @type {import('./types').LintIssue[]}
+   */
+  const issues = [];
+
+  /**
+   * Reports a lint issue.
+   *
+   * @param {import('./types').ReportIssueProps} issue
+   * @returns {void}
+   */
+  const report = ({ level, message, position }) => {
+    /**
+     * @type {import('./types').LintIssueLocation}
+     */
+    const location = {
+      path: file.path,
+    };
+
+    if (position) {
+      location.position = position;
+    }
+
+    issues.push({
+      level,
+      message,
+      location,
+    });
+  };
+
+  /**
+   * Gets all reported issues.
+   *
+   * @returns {import('./types').LintIssue[]}
+   */
+  const getIssues = () => {
+    return issues;
+  };
+
+  return {
+    tree,
+    report,
+    getIssues,
+  };
+};
+
+export default createContext;

src/linter/context.mjs

@@ -1,52 +1,48 @@
 'use strict';
 
-import createLinterEngine from './engine.mjs';
+import createContext from './context.mjs';
 import reporters from './reporters/index.mjs';
-import rules from './rules/index.mjs';
 
 /**
- * Creates a linter instance to validate ApiDocMetadataEntry entries
+ * Creates a linter instance to validate API documentation ASTs against a
+ * defined set of rules.
  *
- * @param {boolean} dryRun Whether to run the engine in dry-run mode
- * @param {string[]} disabledRules List of disabled rules names
+ * @param {import('./types').LintRule[]} rules - Lint rules to apply
+ * @param {boolean} [dryRun] - If true, the linter runs without reporting
+ * @returns {import('./types').Linter}
  */
-const createLinter = (dryRun, disabledRules) => {
+const createLinter = (rules, dryRun = false) => {
   /**
-   * Retrieves all enabled rules
-   *
-   * @returns {import('./types').LintRule[]}
-   */
-  const getEnabledRules = () => {
-    return Object.entries(rules)
-      .filter(([ruleName]) => !disabledRules.includes(ruleName))
-      .map(([, rule]) => rule);
-  };
-
-  const engine = createLinterEngine(getEnabledRules(disabledRules));
-
-  /**
-   * Lint issues found during validations
+   * Lint issues collected during validations.
    *
    * @type {Array<import('./types').LintIssue>}
    */
   const issues = [];
 
   /**
-   * Lints all entries using the linter engine
+   * Lints a API doc and collects issues.
    *
-   * @param entries
+   * @param {import('vfile').VFile} file
+   * @param {import('mdast').Root} tree
+   * @returns {void}
    */
-  const lintAll = entries => {
-    issues.push(...engine.lintAll(entries));
+  const lint = (file, tree) => {
+    const context = createContext(file, tree);
+
+    for (const rule of rules) {
+      rule(context);
+    }
+
+    issues.push(...context.getIssues());
   };
 
   /**
-   * Reports found issues using the specified reporter
+   * Reports collected issues using the specified reporter.
    *
-   * @param {keyof typeof reporters} reporterName Reporter name
+   * @param {keyof typeof reporters} [reporterName] Reporter name
    * @returns {void}
    */
-  const report = reporterName => {
+  const report = (reporterName = 'console') => {
     if (dryRun) {
       return;
     }
@@ -59,7 +55,7 @@ const createLinter = (dryRun, disabledRules) => {
   };
 
   /**
-   * Checks if any error-level issues were found during linting
+   * Checks if any error-level issues were collected.
    *
    * @returns {boolean}
    */
@@ -68,7 +64,8 @@ const createLinter = (dryRun, disabledRules) => {
   };
 
   return {
-    lintAll,
+    issues,
+    lint,
     report,
     hasError,
   };

src/linter/engine.mjs

@@ -1,6 +1,6 @@
 'use strict';
 
-import { duplicateStabilityNodes } from './duplicate-stability-nodes.mjs';
+// import { duplicateStabilityNodes } from './duplicate-stability-nodes.mjs';
 import { invalidChangeVersion } from './invalid-change-version.mjs';
 import { missingIntroducedIn } from './missing-introduced-in.mjs';
 import { missingLlmDescription } from './missing-llm-description.mjs';
@@ -9,7 +9,7 @@ import { missingLlmDescription } from './missing-llm-description.mjs';
  * @type {Record<string, import('../types').LintRule>}
  */
 export default {
-  'duplicate-stability-nodes': duplicateStabilityNodes,
+  // 'duplicate-stability-nodes': duplicateStabilityNodes,
   'invalid-change-version': invalidChangeVersion,
   'missing-introduced-in': missingIntroducedIn,
   'missing-llm-description': missingLlmDescription,