lint @inheritDoc tags for correct canonical references

Author: phryneas

config/apiExtractor.ts

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
-import { join } from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
+import { format, join, parse } from "node:path";
 import { parseArgs } from "node:util";
 import * as path from "path";
 
@@ -84,10 +85,36 @@ try {
       })
     );
 
-    await buildReport("@apollo/client", entryPointFile, "docModel");
+    const result = await buildReport(
+      "@apollo/client",
+      entryPointFile,
+      "docModel"
+    );
     if (process.exitCode === 50) {
       process.exitCode = 0; // if there were only warnings, we still want to exit with 0
     }
+
+    console.log("Creating file with all possible canonical references...");
+    const canonicalReferences = new Set<string>();
+    const file = await readFile(result.extractorConfig.apiJsonFilePath, "utf8");
+    JSON.parse(file, (key, value) => {
+      if (
+        key === "canonicalReference" &&
+        typeof value === "string" &&
+        value.startsWith("@apollo/client")
+      ) {
+        canonicalReferences.add(value);
+      }
+      return undefined;
+    });
+    await writeFile(
+      format({
+        ...parse(result.extractorConfig.apiJsonFilePath),
+        base: "canonical-references.json",
+      }),
+      JSON.stringify([...canonicalReferences.values()], null, 2),
+      "utf8"
+    );
   }
 
   if (parsed.values.generate?.includes("apiReport")) {
@@ -185,4 +212,5 @@ async function buildReport(
       );
     }
   }
+  return extractorResult;
 }

eslint-local-rules/canonical-references.ts

@@ -0,0 +1,84 @@
+import type { TSESTree as AST } from "@typescript-eslint/types";
+import { ESLintUtils } from "@typescript-eslint/utils";
+import type { SourceCode } from "@typescript-eslint/utils/ts-eslint";
+
+import references from "../docs/public/canonical-references.json" with { type: "json" };
+
+const referenceSet = new Set(references);
+
+export const validInheritDoc = ESLintUtils.RuleCreator.withoutDocs({
+  create(context) {
+    const source = context.sourceCode;
+    let handled = new Set();
+    return {
+      "*"(node) {
+        for (const comment of source.getCommentsBefore(node)) {
+          if (handled.has(comment)) {
+            continue;
+          }
+          handled.add(comment);
+          if (comment.type === "Block") {
+            const text = source.getText(comment);
+            let match: RegExpMatchArray | null;
+            if ((match = text.match(/@inheritDoc\s+([^\s}]+)/d))) {
+              const canonicalReference = match[1];
+              if (!referenceSet.has(canonicalReference)) {
+                context.report({
+                  node: comment,
+                  loc: locForMatch(source, comment, match, 1),
+                  messageId: "invalidCanonicalReference",
+                });
+              }
+            }
+            if (
+              (match = text.match(/@inheritdoc/di)) &&
+              match[0] !== "@inheritDoc"
+            ) {
+              const loc = locForMatch(source, comment, match, 0);
+              context.report({
+                node: comment,
+                loc,
+                messageId: "invalidSpelling",
+                fix(fixer) {
+                  return fixer.replaceTextRange(
+                    [
+                      source.getIndexFromLoc(loc.start),
+                      source.getIndexFromLoc(loc.end),
+                    ],
+                    "@inheritDoc"
+                  );
+                },
+              });
+            }
+          }
+        }
+      },
+    };
+  },
+  meta: {
+    messages: {
+      invalidCanonicalReference: "Unknown canonical reference.",
+      invalidSpelling: "Invalid spelling of @inheritDoc.",
+    },
+    type: "problem",
+    schema: [],
+    fixable: "code",
+  },
+  defaultOptions: [],
+});
+
+function locForMatch(
+  source: SourceCode,
+  node: AST.NodeOrTokenData,
+  match: RegExpMatchArray,
+  index: number
+) {
+  return {
+    start: source.getLocFromIndex(
+      source.getIndexFromLoc(node.loc.start) + match.indices[index][0]
+    ),
+    end: source.getLocFromIndex(
+      source.getIndexFromLoc(node.loc.start) + match.indices[index][1]
+    ),
+  };
+}

eslint-local-rules/index.mjs

@@ -1,3 +1,4 @@
+import { validInheritDoc } from "./canonical-references.ts";
 import { rule as forbidActInDisabledActEnvironment } from "./forbid-act-in-disabled-act-environment.ts";
 import {
   importFromExport,
@@ -18,4 +19,5 @@ export default {
   "no-internal-import-official-export": noInternalImportOfficialExport,
   "no-duplicate-exports": noDuplicateExports,
   "no-relative-imports": noRelativeImports,
+  "valid-inherit-doc": validInheritDoc,
 };

eslint-local-rules/tsconfig.json

@@ -6,7 +6,10 @@
     "noEmit": true,
     "allowImportingTsExtensions": true,
     "rewriteRelativeImportExtensions": true,
-    "verbatimModuleSyntax": true
+    "verbatimModuleSyntax": true,
+    "resolveJsonModule": true,
   },
-  "include": ["**/*.ts"]
+  "include": [
+    "**/*.ts"
+  ]
 }

eslint.config.mjs

@@ -194,6 +194,7 @@ export default [
       "import/consistent-type-specifier-style": ["error", "prefer-top-level"],
 
       "local-rules/require-using-disposable": "error",
+      "local-rules/valid-inherit-doc": "error",
     },
   },
   ...compat.extends("plugin:testing-library/react").map((config) => ({