feat: linter

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

Author: flakey5

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 { Linter } from '../src/linter/index.mjs';
+import reporters from '../src/linter/reporters/index.mjs';
 
 const availableGenerators = Object.keys(generators);
 
@@ -50,6 +52,12 @@ program
       'Set the processing target modes'
     ).choices(availableGenerators)
   )
+  .addOption(new Option('--skip-validation', 'TODO').default(false))
+  .addOption(
+    new Option('--reporter', 'TODO')
+      .choices(Object.keys(reporters))
+      .default('console')
+  )
   .parse(argv);
 
 /**
@@ -66,7 +74,17 @@ program
  * @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,
+  skipValidation,
+  reporter,
+} = program.opts();
+
+const linter = skipValidation ? undefined : new Linter();
 
 const { loadFiles } = createMarkdownLoader();
 const { parseApiDocs } = createMarkdownParser();
@@ -91,4 +109,13 @@ await runGenerators({
   version: coerce(version),
   // A list of all Node.js major versions with LTS status
   releases: await getAllMajors(),
+  linter,
 });
+
+if (linter) {
+  linter.report(reporter);
+
+  if (linter.hasError) {
+    exit(1);
+  }
+}

src/generators/types.d.ts

@@ -1,6 +1,7 @@
 import type { SemVer } from 'semver';
 import type availableGenerators from './index.mjs';
 import type { ApiDocReleaseEntry } from '../types';
+import type { Linter } from '../linter/index.mjs';
 
 declare global {
   // All available generators as an inferable type, to allow Generator interfaces
@@ -30,6 +31,8 @@ declare global {
 
     // A list of all Node.js major versions and their respective release information
     releases: Array<ApiDocReleaseEntry>;
+
+    linter: Linter | undefined;
   }
 
   export interface GeneratorMetadata<I extends any, O extends any> {

src/linter/index.mjs

@@ -0,0 +1,81 @@
+// @ts-check
+'use strict';
+
+import reporters from './reporters/index.mjs';
+
+/**
+ *
+ */
+export class Linter {
+  #_hasError = false;
+
+  /**
+   * @type {Array<import('./types.d.ts').LintMessage>}
+   */
+  #messages = [];
+
+  /**
+   *
+   */
+  get hasError() {
+    return this.#_hasError;
+  }
+
+  /**
+   * @param {import('./types.d.ts').LintMessage} msg
+   */
+  log(msg) {
+    if (msg.level === 'error') {
+      this.#_hasError = true;
+    }
+
+    this.#messages.push(msg);
+  }
+
+  /**
+   * @param {keyof reporters} reporterName
+   */
+  report(reporterName) {
+    const reporter = reporters[reporterName];
+
+    for (const message of this.#messages) {
+      reporter(message);
+    }
+  }
+
+  /**
+   * @param {string} msg
+   * @param {import('./types.d.ts').LintMessageLocation | undefined} location
+   */
+  info(msg, location) {
+    this.log({
+      level: 'info',
+      msg,
+      location,
+    });
+  }
+
+  /**
+   * @param {string} msg
+   * @param {import('./types.d.ts').LintMessageLocation | undefined} location
+   */
+  warn(msg, location) {
+    this.log({
+      level: 'warn',
+      msg,
+      location,
+    });
+  }
+
+  /**
+   * @param {string} msg
+   * @param {import('./types.d.ts').LintMessageLocation | undefined} location
+   */
+  error(msg, location) {
+    this.log({
+      level: 'error',
+      msg,
+      location,
+    });
+  }
+}

src/linter/reporters/console.mjs

@@ -0,0 +1,22 @@
+// @ts-check
+
+'use strict';
+
+import { styleText } from 'node:util';
+
+/**
+ * TODO is there a way to grab the parameter type for styleText since the types aren't exported
+ * @type {Record<import('../types.d.ts').LintLevel, string>}
+ */
+const levelToColorMap = {
+  info: 'gray',
+  warn: 'yellow',
+  error: 'red',
+};
+
+/**
+ * @type {import('../types.d.ts').Reporter}
+ */
+export default msg => {
+  console.log(styleText(levelToColorMap[msg.level], msg.msg));
+};

src/linter/reporters/github.mjs

@@ -0,0 +1,13 @@
+// @ts-check
+
+'use strict';
+
+/**
+ * GitHub action reporter for
+ *
+ * @type {import('../types.d.ts').Reporter}
+ */
+export default msg => {
+  // TODO
+  console.log(msg);
+};

src/linter/reporters/index.mjs

@@ -0,0 +1,9 @@
+'use strict';
+
+import console from './console.mjs';
+import github from './github.mjs';
+
+export default /** @type {const} */ ({
+  console,
+  github,
+});

src/linter/types.d.ts

@@ -0,0 +1,16 @@
+export type LintLevel = 'info' | 'warn' | 'error';
+
+export interface LintMessageLocation {
+  // The absolute path to the file
+  path: string;
+  line: number;
+  column: number;
+}
+
+export interface LintMessage {
+  level: LintLevel;
+  msg: string;
+  location?: LintMessageLocation;
+}
+
+export type Reporter = (msg: LintMessage) => void;

src/parsers/markdown.mjs

@@ -14,12 +14,14 @@ import { createNodeSlugger } from '../utils/slugger.mjs';
 
 /**
  * Creates an API doc parser for a given Markdown API doc file
+ *
+ * @param {import('./linter/index.mjs').Linter | undefined} linter
  */
-const createParser = () => {
+const createParser = linter => {
   // Creates an instance of the Remark processor with GFM support
   // which is used for stringifying the AST tree back to Markdown
   const remarkProcessor = getRemark();
-
+  linter?.info('asd123');
   const {
     setHeadingMetadata,
     addYAMLMetadata,