Validate rules referenced by a library's rulesets at build time

.chronus/changes/library-linter-validate-rulesets-2026-8-4-22-15-0.md

@@ -0,0 +1,22 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/library-linter"
+---
+
+Validate that rules and rulesets referenced by the rulesets a library defines actually exist. Previously a dangling reference was only reported when a consumer happened to extend the offending ruleset.
+
+```ts
+export const $linter = defineLinter({
+  rules: [casingRule],
+  ruleSets: {
+    recommended: {
+      // warning: Rule 'removed-rule' referenced by ruleset '@typespec/best-practices/recommended'
+      // is not defined in library '@typespec/best-practices'.
+      enable: { "@typespec/best-practices/removed-rule": true },
+    },
+  },
+});
+```
+
+References to a library that is not part of the compilation are skipped, and only the rulesets of the library being compiled are validated.

packages/library-linter/README.md

@@ -25,6 +25,13 @@ tsp compile . --import @typespec/library-linter
 | `missing-signature`        | Validate that every exported JS decorator function has a matching `extern dec` declaration.                                       |
 | `missing-documentation`    | Validate that every public declaration and member (properties, enum members, parameters, template parameters) has documentation.  |
 | `extraneous-documentation` | Validate that doc comments do not document things that do not exist, such as an unknown `@param` name or an unrecognized doc tag. |
+| `unknown-rule`             | Validate that every rule referenced by a ruleset the library defines actually exists.                                             |
+| `unknown-rule-set`         | Validate that every ruleset referenced by a ruleset the library defines actually exists.                                          |
+| `invalid-rule-reference`   | Validate that references in a ruleset use the `<library-name>/<name>` format.                                                     |
 
 Declarations in a namespace named `Private` and declarations marked `internal` are not part of the
 public surface of a library and are excluded from the documentation rules.
+
+Rulesets are only validated for the library being compiled, not for its dependencies. A reference to
+a library that is not loaded in the compilation is skipped, since there is nothing to resolve it
+against.

packages/library-linter/src/lib.ts

@@ -22,6 +22,24 @@ export const libDef = {
         member: paramMessage`Missing documentation for ${"kind"} '${"name"}' of '${"container"}'. Add a doc comment describing it.`,
       },
     },
+    "unknown-rule": {
+      severity: "warning",
+      messages: {
+        default: paramMessage`Rule '${"name"}' referenced by ruleset '${"ruleSetName"}' is not defined in library '${"libraryName"}'.`,
+      },
+    },
+    "unknown-rule-set": {
+      severity: "warning",
+      messages: {
+        default: paramMessage`Ruleset '${"name"}' referenced by ruleset '${"ruleSetName"}' is not defined in library '${"libraryName"}'.`,
+      },
+    },
+    "invalid-rule-reference": {
+      severity: "warning",
+      messages: {
+        default: paramMessage`Reference '${"ref"}' in ruleset '${"ruleSetName"}' is invalid. It must be in the format "<library-name>/<name>".`,
+      },
+    },
     "extraneous-documentation": {
       severity: "warning",
       messages: {

packages/library-linter/src/linter.ts

@@ -2,13 +2,15 @@ import type { Namespace, Program, Type } from "@typespec/compiler";
 import { SyntaxKind } from "@typespec/compiler/ast";
 import { reportDiagnostic } from "./lib.js";
 import { validateDocumentation } from "./validate-docs.js";
+import { validateRuleSets } from "./validate-rulesets.js";
 
 export function $onValidate(program: Program) {
   const root = program.getGlobalNamespaceType();
 
   validateNoExportAtRoot(program, root);
   validateDecoratorSignature(program);
   validateDocumentation(program);
+  validateRuleSets(program);
 }
 
 function validateNoExportAtRoot(program: Program, root: Namespace) {

packages/library-linter/src/validate-rulesets.ts

@@ -0,0 +1,144 @@
+import {
+  resolveLinterDefinition,
+  type LinterResolvedDefinition,
+  type LinterRuleSet,
+  type Program,
+} from "@typespec/compiler";
+import type { JsSourceFileNode } from "@typespec/compiler/ast";
+import { reportDiagnostic } from "./lib.js";
+
+interface LoadedLinter {
+  readonly libName: string;
+  readonly linter: LinterResolvedDefinition;
+  /** JS file declaring the linter. Used as the diagnostic target so reports have a location. */
+  readonly node: JsSourceFileNode;
+  /** Whether this linter belongs to the library being compiled as opposed to one of its dependencies. */
+  readonly isProject: boolean;
+}
+
+/**
+ * Validate that every rule and ruleset referenced by the rulesets of the library being compiled
+ * actually exists. Without this a dangling reference is only reported when a consumer happens to
+ * extend the offending ruleset.
+ */
+export function validateRuleSets(program: Program) {
+  const { linters, knownLibraries } = collectLibraries(program);
+  const knownRules = new Set<string>();
+  const knownRuleSets = new Set<string>();
+  for (const { libName, linter } of linters) {
+    for (const rule of linter.rules) {
+      knownRules.add(rule.id);
+    }
+    for (const name of Object.keys(linter.ruleSets)) {
+      knownRuleSets.add(`${libName}/${name}`);
+    }
+  }
+
+  for (const { libName, linter, node, isProject } of linters) {
+    if (!isProject) continue;
+    for (const [name, ruleSet] of Object.entries(linter.ruleSets)) {
+      validateRuleSet(program, `${libName}/${name}`, ruleSet, node, {
+        knownLibraries,
+        knownRules,
+        knownRuleSets,
+      });
+    }
+  }
+}
+
+interface KnownReferences {
+  readonly knownLibraries: ReadonlySet<string>;
+  readonly knownRules: ReadonlySet<string>;
+  readonly knownRuleSets: ReadonlySet<string>;
+}
+
+function validateRuleSet(
+  program: Program,
+  ruleSetName: string,
+  ruleSet: LinterRuleSet,
+  target: JsSourceFileNode,
+  known: KnownReferences,
+) {
+  for (const ref of ruleSet.extends ?? []) {
+    validateReference(program, ruleSetName, ref, "ruleset", target, known);
+  }
+  for (const ref of Object.keys(ruleSet.enable ?? {})) {
+    validateReference(program, ruleSetName, ref, "rule", target, known);
+  }
+  for (const ref of Object.keys(ruleSet.disable ?? {})) {
+    validateReference(program, ruleSetName, ref, "rule", target, known);
+  }
+}
+
+function validateReference(
+  program: Program,
+  ruleSetName: string,
+  ref: string,
+  kind: "rule" | "ruleset",
+  target: JsSourceFileNode,
+  known: KnownReferences,
+) {
+  const parsed = parseReference(ref);
+  if (parsed === undefined) {
+    reportDiagnostic(program, {
+      code: "invalid-rule-reference",
+      format: { ref, ruleSetName },
+      target,
+    });
+    return;
+  }
+
+  // The referenced library is not part of this compilation, so there is nothing to check against.
+  // This happens when a ruleset references a library that the current library does not import.
+  if (!known.knownLibraries.has(parsed.libraryName)) {
+    return;
+  }
+
+  const exists = kind === "rule" ? known.knownRules.has(ref) : known.knownRuleSets.has(ref);
+  if (!exists) {
+    reportDiagnostic(program, {
+      code: kind === "rule" ? "unknown-rule" : "unknown-rule-set",
+      format: { name: parsed.name, libraryName: parsed.libraryName, ruleSetName },
+      target,
+    });
+  }
+}
+
+function parseReference(ref: string): { libraryName: string; name: string } | undefined {
+  const segments = ref.split("/");
+  const name = segments.pop();
+  const libraryName = segments.join("/");
+  if (!libraryName || !name) {
+    return undefined;
+  }
+  return { libraryName, name };
+}
+
+function collectLibraries(program: Program): {
+  linters: LoadedLinter[];
+  knownLibraries: Set<string>;
+} {
+  const linters: LoadedLinter[] = [];
+  // Every library loaded in this compilation, including those defining no linter: a reference into
+  // such a library is known to be broken, unlike one pointing at a library that was never loaded.
+  const knownLibraries = new Set<string>();
+  for (const jsFile of program.jsSourceFiles.values()) {
+    const lib = jsFile.esmExports.$lib;
+    if (typeof lib?.name !== "string") {
+      continue;
+    }
+    knownLibraries.add(lib.name);
+
+    const linter = jsFile.esmExports.$linter;
+    if (linter === undefined) {
+      continue;
+    }
+    linters.push({
+      libName: lib.name,
+      linter: resolveLinterDefinition(lib.name, linter),
+      node: jsFile,
+      isProject: program.getSourceFileLocationContext(jsFile.file).type === "project",
+    });
+  }
+  return { linters, knownLibraries };
+}

packages/library-linter/test/validate-rulesets.test.ts

@@ -0,0 +1,151 @@
+import { expectDiagnosticEmpty, expectDiagnostics, mockFile } from "@typespec/compiler/testing";
+import { describe, it } from "vitest";
+import { Tester } from "./test-host.js";
+
+function libFile(name: string, linter?: unknown) {
+  return mockFile.js({
+    $lib: { name },
+    ...(linter === undefined ? {} : { $linter: linter }),
+  });
+}
+
+const casingRule = {
+  name: "casing",
+  severity: "warning",
+  description: "casing",
+  messages: { default: "casing" },
+  create: () => ({}),
+};
+
+async function diagnoseLib(linter: unknown, extraFiles: Record<string, any> = {}) {
+  const imports = ["./mylib.js", ...Object.keys(extraFiles)]
+    .map((x) => `import "${x}";`)
+    .join("\n");
+  return Tester.files({
+    "./mylib.js": libFile("@test/mylib", linter),
+    ...extraFiles,
+  }).diagnose(imports);
+}
+
+describe("validate rulesets", () => {
+  it("emits no diagnostic when a ruleset references a rule of its own library", async () => {
+    const diagnostics = await diagnoseLib({
+      rules: [casingRule],
+      ruleSets: { recommended: { enable: { "@test/mylib/casing": true } } },
+    });
+    expectDiagnosticEmpty(diagnostics);
+  });
+
+  it("emits a diagnostic when a ruleset enables a rule that does not exist", async () => {
+    const diagnostics = await diagnoseLib({
+      rules: [casingRule],
+      ruleSets: { recommended: { enable: { "@test/mylib/removed": true } } },
+    });
+    expectDiagnostics(diagnostics, {
+      code: "@typespec/library-linter/unknown-rule",
+      severity: "warning",
+      message:
+        "Rule 'removed' referenced by ruleset '@test/mylib/recommended' is not defined in library '@test/mylib'.",
+    });
+  });
+
+  it("emits a diagnostic when a ruleset disables a rule that does not exist", async () => {
+    const diagnostics = await diagnoseLib({
+      rules: [casingRule],
+      ruleSets: { recommended: { disable: { "@test/mylib/removed": "gone" } } },
+    });
+    expectDiagnostics(diagnostics, {
+      code: "@typespec/library-linter/unknown-rule",
+      message:
+        "Rule 'removed' referenced by ruleset '@test/mylib/recommended' is not defined in library '@test/mylib'.",
+    });
+  });
+
+  it("emits a diagnostic when a ruleset extends a ruleset that does not exist", async () => {
+    const diagnostics = await diagnoseLib({
+      rules: [casingRule],
+      ruleSets: { recommended: { extends: ["@test/mylib/missing"] } },
+    });
+    expectDiagnostics(diagnostics, {
+      code: "@typespec/library-linter/unknown-rule-set",
+      message:
+        "Ruleset 'missing' referenced by ruleset '@test/mylib/recommended' is not defined in library '@test/mylib'.",
+    });
+  });
+
+  it("emits a diagnostic when a reference is not in the '<library-name>/<name>' format", async () => {
+    const diagnostics = await diagnoseLib({
+      rules: [casingRule],
+      ruleSets: { recommended: { enable: { removed: true } } },
+    });
+    expectDiagnostics(diagnostics, {
+      code: "@typespec/library-linter/invalid-rule-reference",
+      message: `Reference 'removed' in ruleset '@test/mylib/recommended' is invalid. It must be in the format "<library-name>/<name>".`,
+    });
+  });
+
+  it("resolves references to the auto generated `all` ruleset", async () => {
+    const diagnostics = await diagnoseLib({
+      rules: [casingRule],
+      ruleSets: { recommended: { extends: ["@test/mylib/all"] } },
+    });
+    expectDiagnosticEmpty(diagnostics);
+  });
+
+  it("resolves references to rules of another library in the compilation", async () => {
+    const diagnostics = await diagnoseLib(
+      { rules: [], ruleSets: { recommended: { enable: { "@test/other/casing": true } } } },
+      { "./other.js": libFile("@test/other", { rules: [casingRule] }) },
+    );
+    expectDiagnosticEmpty(diagnostics);
+  });
+
+  it("emits a diagnostic for a missing rule of another library in the compilation", async () => {
+    const diagnostics = await diagnoseLib(
+      { rules: [], ruleSets: { recommended: { enable: { "@test/other/removed": true } } } },
+      { "./other.js": libFile("@test/other", { rules: [casingRule] }) },
+    );
+    expectDiagnostics(diagnostics, {
+      code: "@typespec/library-linter/unknown-rule",
+      message:
+        "Rule 'removed' referenced by ruleset '@test/mylib/recommended' is not defined in library '@test/other'.",
+    });
+  });
+
+  it("emits a diagnostic for a rule of a library in the compilation that defines no linter", async () => {
+    const diagnostics = await diagnoseLib(
+      { rules: [], ruleSets: { recommended: { enable: { "@test/other/casing": true } } } },
+      { "./other.js": libFile("@test/other") },
+    );
+    expectDiagnostics(diagnostics, {
+      code: "@typespec/library-linter/unknown-rule",
+      message:
+        "Rule 'casing' referenced by ruleset '@test/mylib/recommended' is not defined in library '@test/other'.",
+    });
+  });
+
+  it("validates every ruleset defined in the project being compiled", async () => {
+    const diagnostics = await diagnoseLib(
+      { rules: [casingRule] },
+      {
+        "./other.js": libFile("@test/other", {
+          rules: [],
+          ruleSets: { recommended: { enable: { "@test/other/removed": true } } },
+        }),
+      },
+    );
+    expectDiagnostics(diagnostics, {
+      code: "@typespec/library-linter/unknown-rule",
+      message:
+        "Rule 'removed' referenced by ruleset '@test/other/recommended' is not defined in library '@test/other'.",
+    });
+  });
+
+  it("ignores references to a library that is not part of the compilation", async () => {
+    const diagnostics = await diagnoseLib({
+      rules: [casingRule],
+      ruleSets: { recommended: { enable: { "@test/not-installed/some-rule": true } } },
+    });
+    expectDiagnosticEmpty(diagnostics);
+  });
+});