@konvert7/klint 0.28.0 → 0.30.0

package/README.md

@@ -209,6 +209,23 @@ arch:
 
 `klint.config.json` is still supported for backwards compatibility.
 
+### Pinning the schema version
+
+The `# yaml-language-server:` comment above points your editor at the schema shipped
+inside the package, which always matches the installed klint. To pin a specific
+published schema instead, set `$schema` to a version-tagged URL:
+
+```yaml
+$schema: https://raw.githubusercontent.com/konvert7/klint/refs/tags/v0.29.0/klint.schema.json
+```
+
+When the tagged version differs from the installed klint, the run reports a
+`klint/schema-version` warning naming both versions and the URL to move to. It is a
+warning, not an error — the exit code is unaffected. Local paths such as
+`./klint.schema.json` carry no version and are never checked.
+
+`klint --version` prints the installed version.
+
 ## Architecture as Code
 
 The `arch:` section turns project boundaries into executable policy.
@@ -415,6 +432,18 @@ arch:
 
 Set `countDocComments: true` on either rule to count doc-comments toward the limit as well. Both rules run in the TS and Rust engines; Python (`#`) and Swift (`//`, `/* */`) files are enforced by the Rust engine.
 
+Some comments are machinery rather than prose — markers a build or codegen step reads, region pragmas — and counting them makes both limits measure the wrong thing. `ignore` exempts them, on either rule:
+
+```yaml
+arch:
+  maxCommentDensity:
+    - limit: 5
+      in: ["src/**"]
+      ignore: ["@codegen:"]     # literal substring, or "re:" for a regex
+```
+
+An ignored line still counts in the density denominator — it is a physical line like code — and still holds a comment block together, so a marker cannot be sprinkled between comment lines to split an over-tall block. Matching tests the physical source line and therefore only ever applies to lines already lexed as comments.
+
 ### Language Support
 
 klint scans TypeScript/JavaScript, Python, Swift, and Rust. Every architecture rule is enforced from the same `klint.yaml`, but what a rule can *see* depends on what the language actually has.

package/cli/output.ts

@@ -85,6 +85,25 @@ export function mergeJsonOutputs(...outputs: JsonPayload[]): JsonPayload {
   };
 }
 
+export function withAdvisories(
+  stdout: string,
+  advisories: Array<Omit<Violation, "fix">>
+): string {
+  if (advisories.length === 0) return stdout;
+  const payload = parseJsonPayload(stdout);
+  if (!isJsonPayload(payload)) return stdout;
+
+  const violations = [
+    ...payload.violations,
+    ...advisories.map((advisory) => ({ ...advisory, fix: null })),
+  ];
+  const errors = violations.filter((v) => v.severity === "error").length;
+  return JSON.stringify({
+    violations,
+    summary: { errors, warnings: violations.length - errors },
+  });
+}
+
 export function isJsonPayload(value: unknown): value is JsonPayload {
   if (!value || typeof value !== "object") return false;
   const candidate = value as Partial<JsonPayload>;

package/cli/rust-engine.ts

@@ -3,7 +3,7 @@ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { runKlint } from "../core/runner";
-import type { KlintRule, RuleConfigValue } from "../core/types";
+import type { KlintRule, RuleConfigValue, Violation } from "../core/types";
 import {
   emptyJsonPayload,
   isJsonPayload,
@@ -13,6 +13,7 @@ import {
   parseJsonPayload,
   toJsonCliResult,
   toJsonPayload,
+  withAdvisories,
   writeTextOutput,
 } from "./output";
 import { PACKAGE_ROOT } from "./paths";
@@ -25,6 +26,7 @@ import {
 } from "./rust-config";
 
 export function runRustEngine({
+  advisories,
   fix,
   json,
   raw,
@@ -32,6 +34,7 @@ export function runRustEngine({
   rulesFile,
   startedAt,
 }: {
+  advisories: Array<Omit<Violation, "fix">>;
   fix: boolean;
   json: boolean;
   raw: {
@@ -73,7 +76,7 @@ export function runRustEngine({
 
   if (result.stderr) process.stderr.write(result.stderr);
   if (json) {
-    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stdout) process.stdout.write(withAdvisories(result.stdout, advisories));
     process.exit(result.status ?? 1);
   }
 
@@ -82,10 +85,11 @@ export function runRustEngine({
     process.stderr.write("klint: --engine rust failed to parse Rust JSON output\n");
     process.exit(1);
   }
-  writeTextOutput(payload.violations, startedAt);
+  writeTextOutput([...payload.violations, ...advisories], startedAt);
 }
 
 export function runCompareEngine({
+  advisories,
   fix,
   json,
   raw,
@@ -93,6 +97,7 @@ export function runCompareEngine({
   rulesFile,
   tsViolations,
 }: {
+  advisories: Array<Omit<Violation, "fix">>;
   fix: boolean;
   json: boolean;
   raw: {
@@ -154,7 +159,7 @@ export function runCompareEngine({
     process.exit(1);
   }
 
-  process.stdout.write(tsResult.stdout);
+  process.stdout.write(withAdvisories(tsResult.stdout, advisories));
   process.exit(tsResult.status);
 }
 
@@ -188,6 +193,7 @@ function writeRustEngineConfig({
 }
 
 export function runAutoEngine({
+  advisories,
   fix,
   json,
   raw,
@@ -197,6 +203,7 @@ export function runAutoEngine({
   customRules,
   customRulesMap,
 }: {
+  advisories: Array<Omit<Violation, "fix">>;
   fix: boolean;
   json: boolean;
   raw: {
@@ -241,10 +248,10 @@ export function runAutoEngine({
   const tsOutput = toJsonPayload(tsViolations);
   const merged = mergeJsonOutputs(rustOutput, tsOutput);
   if (json) {
-    process.stdout.write(JSON.stringify(merged));
+    process.stdout.write(withAdvisories(JSON.stringify(merged), advisories));
     process.exit(merged.summary.errors > 0 ? 2 : 0);
   }
-  writeTextOutput(merged.violations, startedAt);
+  writeTextOutput([...merged.violations, ...advisories], startedAt);
 }
 
 function runAutoRustSubset({

package/cli.ts

@@ -8,14 +8,26 @@ import { installSkill } from "./cli/install-skill";
 import {
   formatDuration,
   toJsonCliResult,
+  withAdvisories,
   writeDebugEvent,
   writeTextOutput,
 } from "./cli/output";
+import { PACKAGE_ROOT } from "./cli/paths";
 import { runAutoEngine, runCompareEngine, runRustEngine } from "./cli/rust-engine";
 import { applyFixes } from "./core/fixer";
 import { runKlint } from "./core/runner";
+import { schemaVersionAdvisory } from "./core/schema-version";
 import type { ArchConfig, KlintConfig, KlintRule, RuleConfigValue } from "./core/types";
 
+async function installedVersion(): Promise<string> {
+  const manifest = await readFile(resolve(PACKAGE_ROOT, "package.json"), "utf-8");
+  try {
+    return (JSON.parse(manifest) as { version?: string }).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
 interface CliOptions {
   configDir?: string;
   rulesFile?: string;
@@ -52,6 +64,9 @@ export async function main(opts: CliOptions = {}): Promise<void> {
     else if (args[i] === "--help" || args[i] === "-h") {
       printHelp();
       process.exit(0);
+    } else if (args[i] === "--version" || args[i] === "-V") {
+      process.stdout.write(`klint ${await installedVersion()}\n`);
+      process.exit(0);
     }
   }
 
@@ -70,6 +85,7 @@ export async function main(opts: CliOptions = {}): Promise<void> {
   }
 
   interface RawConfig {
+    $schema?: string;
     root?: string;
     include?: string[];
     plugins?: string[];
@@ -77,17 +93,25 @@ export async function main(opts: CliOptions = {}): Promise<void> {
     arch?: unknown;
   }
   let raw: RawConfig;
+  let configText = "";
   try {
-    const text = await readFile(configPath, "utf-8");
-    raw = (usingYaml ? parseYaml(text) : JSON.parse(text)) as RawConfig;
+    configText = await readFile(configPath, "utf-8");
+    raw = (usingYaml ? parseYaml(configText) : JSON.parse(configText)) as RawConfig;
   } catch {
     process.stderr.write(`klint: failed to parse ${configPath}\n`);
     process.exit(1);
   }
   const root = resolve(configDir, raw.root ?? ".");
 
+  const advisories = schemaVersionAdvisory({
+    schema: raw.$schema,
+    installed: await installedVersion(),
+    configFile: usingYaml ? "klint.yaml" : "klint.config.json",
+    configText,
+  });
+
   if (engine === "rust") {
-    runRustEngine({ fix, json, raw, root, rulesFile, startedAt });
+    runRustEngine({ advisories, fix, json, raw, root, rulesFile, startedAt });
     return;
   }
   if (
@@ -119,6 +143,7 @@ export async function main(opts: CliOptions = {}): Promise<void> {
 
   if (engine === "auto") {
     runAutoEngine({
+      advisories,
       fix,
       json,
       raw,
@@ -145,6 +170,7 @@ export async function main(opts: CliOptions = {}): Promise<void> {
 
   if (engine === "compare") {
     runCompareEngine({
+      advisories,
       fix,
       json,
       raw,
@@ -157,7 +183,7 @@ export async function main(opts: CliOptions = {}): Promise<void> {
 
   if (json) {
     const tsResult = toJsonCliResult(violations);
-    process.stdout.write(tsResult.stdout);
+    process.stdout.write(withAdvisories(tsResult.stdout, advisories));
     process.exit(tsResult.status);
   }
 
@@ -189,7 +215,7 @@ export async function main(opts: CliOptions = {}): Promise<void> {
     process.stdout.write(`${msg} Finished in ${formatDuration(startedAt)}.\n`);
     process.exit(0);
   }
-  writeTextOutput(violations, startedAt);
+  writeTextOutput([...violations, ...advisories], startedAt);
 }
 
 if (import.meta.main) await main();

package/core/arch-comments.ts

@@ -52,22 +52,40 @@ export function commentLineSet(
   return set;
 }
 
-/** Returns the first line at which a run of consecutive comment lines exceeds `limit`. */
+/**
+ * Comment lines whose source text matches an `ignore` pattern. They stay in the
+ * density denominator and keep a comment run contiguous, but count toward neither.
+ */
+export function ignoredCommentLines(
+  content: string,
+  commentLines: Iterable<number>,
+  matchesIgnore: (text: string) => boolean
+): Set<number> {
+  const sourceLines = content.split("\n");
+  const ignored = new Set<number>();
+  for (const line of commentLines) {
+    if (matchesIgnore(sourceLines[line - 1] ?? "")) ignored.add(line);
+  }
+  return ignored;
+}
+
+/**
+ * Returns the first line at which a run of consecutive comment lines exceeds
+ * `limit`. An ignored line neither counts toward the height nor breaks the run.
+ */
 export function firstCommentBlockOverrun(
   sortedLines: number[],
-  limit: number
+  limit: number,
+  ignored?: ReadonlySet<number>
 ): number | undefined {
-  let runStart = sortedLines[0];
-  let prev = sortedLines[0];
-  for (let i = 1; i <= sortedLines.length; i++) {
-    const line = sortedLines[i];
-    if (line === prev + 1) {
-      prev = line;
-      continue;
-    }
-    if (prev - runStart + 1 > limit) return runStart + limit;
-    runStart = line;
+  let counted = 0;
+  let prev: number | undefined;
+  for (const line of sortedLines) {
+    if (prev !== undefined && line !== prev + 1) counted = 0;
     prev = line;
+    if (ignored?.has(line)) continue;
+    counted += 1;
+    if (counted > limit) return line;
   }
   return undefined;
 }

package/core/arch.ts

@@ -1,6 +1,10 @@
 import { dirname, isAbsolute, resolve } from "node:path";
 import ts from "typescript";
-import { commentLineSet, firstCommentBlockOverrun } from "./arch-comments";
+import {
+  commentLineSet,
+  firstCommentBlockOverrun,
+  ignoredCommentLines,
+} from "./arch-comments";
 import { walkAst } from "./ast";
 import { relativeSlashPath, toSlashPath } from "./paths";
 import type { ArchConfig, Severity, Violation } from "./types";
@@ -309,6 +313,7 @@ export function runArchRules(
 
   for (const rule of arch.maxCommentDensity ?? []) {
     const severity: Severity = rule.severity ?? "error";
+    const ignoreMatcher = buildIgnoreMatcher(rule.ignore);
     const inFiles = resolveLayerFiles(rule.in, layers, root, allFiles);
     for (const file of inFiles) {
       const content = fileContents.get(file);
@@ -316,7 +321,11 @@ export function runArchRules(
       const total = countLines(content);
       if (total === 0) continue;
       const commentLines = commentLineSet(file, content, rule.countDocComments ?? false);
-      const density = (commentLines.size / total) * 100;
+      const ignored = ignoreMatcher
+        ? ignoredCommentLines(content, commentLines, ignoreMatcher)
+        : undefined;
+      const counted = commentLines.size - (ignored?.size ?? 0);
+      const density = (counted / total) * 100;
       if (density > rule.limit) {
         violations.push({
           file: relativeSlashPath(root, file),
@@ -333,6 +342,7 @@ export function runArchRules(
 
   for (const rule of arch.maxCommentBlock ?? []) {
     const severity: Severity = rule.severity ?? "error";
+    const ignoreMatcher = buildIgnoreMatcher(rule.ignore);
     const inFiles = resolveLayerFiles(rule.in, layers, root, allFiles);
     for (const file of inFiles) {
       const content = fileContents.get(file);
@@ -340,7 +350,10 @@ export function runArchRules(
       const commentLines = [
         ...commentLineSet(file, content, rule.countDocComments ?? false),
       ].sort((a, b) => a - b);
-      const overrun = firstCommentBlockOverrun(commentLines, rule.limit);
+      const ignored = ignoreMatcher
+        ? ignoredCommentLines(content, commentLines, ignoreMatcher)
+        : undefined;
+      const overrun = firstCommentBlockOverrun(commentLines, rule.limit, ignored);
       if (overrun !== undefined) {
         violations.push({
           file: relativeSlashPath(root, file),
@@ -402,6 +415,15 @@ function scanJsxElements(
 
 const REGEX_PREFIX = "re:";
 
+function buildIgnoreMatcher(
+  ignore: string | string[] | undefined
+): ((line: string) => boolean) | undefined {
+  const patterns = toArray(ignore ?? []);
+  if (patterns.length === 0) return undefined;
+  const matchers = patterns.map(buildLineMatcher);
+  return (line) => matchers.some((matches) => matches(line));
+}
+
 function buildLineMatcher(pattern: string): (line: string) => boolean {
   if (!pattern.startsWith(REGEX_PREFIX)) {
     return (line) => line.includes(pattern);

package/core/config.schema.ts

@@ -244,9 +244,13 @@ const CountDocCommentsSchema = z
   .boolean()
   .optional()
   .describe(
-    "Count doc-comments toward the limit. Doc-comments are `/** … */` JSDoc blocks (TS/JS) and docstrings (Python); ordinary `//`, `/* */`, and `#` comments are always counted. Defaults to false, so documentation is exempt and only explanatory/inline comments are capped."
+    "Count doc-comments toward the limit. Doc-comments are `/** … */` JSDoc blocks (TS/JS), `///` (Swift), and `///` or `//!` (Rust); ordinary `//`, `/* */`, and `#` comments are always counted. Defaults to false, so documentation is exempt and only explanatory/inline comments are capped. Has no effect on Python: docstrings are string expressions rather than comments, so they never count toward either limit."
   );
 
+const CommentIgnoreSchema = StringOrStringArray.optional().describe(
+  "Comment lines matching these patterns are structural, not prose — marker comments a build or codegen step reads, for example — and count toward neither limit. A literal substring by default; prefix with `re:` for a regex. Ignored lines still count in the density denominator (they are physical lines) and still hold a comment block together, so a marker cannot be used to split an over-tall block."
+);
+
 const ArchMaxCommentDensityRuleSchema = z
   .object({
     limit: z
@@ -257,6 +261,7 @@ const ArchMaxCommentDensityRuleSchema = z
         "Maximum percentage of a file's physical lines that may be comment lines. Denominator is total physical lines (code + comments + blanks), the same count `maxLines` uses. A file above this ratio is a violation."
       ),
     countDocComments: CountDocCommentsSchema,
+    ignore: CommentIgnoreSchema,
     in: StringOrStringArray.describe(
       "Layer name(s) or glob(s) the limit applies to. Files outside the scope are not checked."
     ),
@@ -289,6 +294,7 @@ const ArchMaxCommentBlockRuleSchema = z
         "Maximum number of consecutive comment lines allowed in a single block. A run of more comment lines than this — e.g. a tall comment stacked above a statement — is a violation, reported at the first offending line."
       ),
     countDocComments: CountDocCommentsSchema,
+    ignore: CommentIgnoreSchema,
     in: StringOrStringArray.describe(
       "Layer name(s) or glob(s) the limit applies to. Files outside the scope are not checked."
     ),
@@ -371,7 +377,7 @@ export const KlintConfigSchema = z
       .string()
       .optional()
       .describe(
-        "JSON Schema reference. Use ./klint.schema.json for local validation or https://klint.dev/schema.json for the published schema."
+        "JSON Schema reference. Use ./klint.schema.json for local validation, or a version-tagged URL such as https://raw.githubusercontent.com/konvert7/klint/refs/tags/v0.29.0/klint.schema.json to pin the schema. A tagged URL naming a version other than the installed one raises a klint/schema-version warning."
       ),
     root: z
       .string()

package/core/schema-version.ts

@@ -0,0 +1,46 @@
+import type { Violation } from "./types";
+
+const SCHEMA_VERSION_RULE = "klint/schema-version";
+
+const TAGGED_SCHEMA_URL = /\/refs\/tags\/v(\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?)\//;
+const UNRELEASED = "0.0.0";
+
+export function schemaUrlForVersion(version: string): string {
+  return `https://raw.githubusercontent.com/konvert7/klint/refs/tags/v${version}/klint.schema.json`;
+}
+
+export function declaredSchemaVersion(schema: string | undefined): string | undefined {
+  return schema?.match(TAGGED_SCHEMA_URL)?.[1];
+}
+
+export function schemaVersionAdvisory({
+  schema,
+  installed,
+  configFile,
+  configText,
+}: {
+  schema: string | undefined;
+  installed: string;
+  configFile: string;
+  configText: string;
+}): Array<Omit<Violation, "fix">> {
+  const declared = declaredSchemaVersion(schema);
+  if (declared === undefined || declared === installed || installed === UNRELEASED) {
+    return [];
+  }
+
+  return [
+    {
+      file: configFile,
+      line: schemaDeclarationLine(configText),
+      rule: SCHEMA_VERSION_RULE,
+      severity: "warn",
+      message: `config declares schema v${declared} but klint ${installed} is installed — update $schema to ${schemaUrlForVersion(installed)}`,
+    },
+  ];
+}
+
+function schemaDeclarationLine(configText: string): number {
+  const index = configText.split("\n").findIndex((line) => line.includes("$schema"));
+  return index === -1 ? 1 : index + 1;
+}

package/core/types.ts

@@ -108,8 +108,10 @@ interface ArchMaxLinesRule {
 interface ArchCommentRuleBase {
   limit: number;
   in: string | string[];
-  /** Count doc-comments (`/** *​/` JSDoc, Python docstrings) toward the limit. Defaults to false. */
+  /** Count doc-comments (`/** *​/` JSDoc, Swift `///`, Rust `///` and `//!`) toward the limit. Defaults to false. No effect on Python, whose docstrings are never counted. */
   countDocComments?: boolean;
+  /** Comment lines matching these patterns count toward neither limit. Literal substring, or `re:` for a regex. */
+  ignore?: string | string[];
   message?: string;
   severity?: Exclude<Severity, "off">;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konvert7/klint",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Architecture-as-Code linter for TypeScript. Enforce layer boundaries, import rules, and singleton patterns in YAML.",
   "type": "module",
   "bin": {
@@ -65,10 +65,10 @@
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "@konvert7/klint-darwin-arm64": "0.28.0",
-    "@konvert7/klint-darwin-x64": "0.28.0",
-    "@konvert7/klint-linux-x64": "0.28.0",
-    "@konvert7/klint-win32-x64": "0.28.0"
+    "@konvert7/klint-darwin-arm64": "0.30.0",
+    "@konvert7/klint-darwin-x64": "0.30.0",
+    "@konvert7/klint-linux-x64": "0.30.0",
+    "@konvert7/klint-win32-x64": "0.30.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.7",

package/skill/klint-rules/SKILL.md

@@ -39,6 +39,8 @@ Wire it into `klint.yaml` for editor autocomplete and validation:
    | Raw HTML/JSX element may only appear in one primitive file | `arch.singleton` + `jsx-element` |
    | A value-shaped pattern (regex) must never appear in a scoped layer | `arch.forbidden` + `pattern: "re:…"` |
    | No file in a layer may exceed N lines | `arch.maxLines` + `limit` |
+   | No file may be more than N% comments | `arch.maxCommentDensity` + `limit` |
+   | No comment block may stack more than N lines | `arch.maxCommentBlock` + `limit` |
 
 4. **Read `klint.yaml`** — check existing `arch.layers` and rules before adding anything. Add a new named layer to `arch.layers` if the file group doesn't exist yet.
 
@@ -169,10 +171,65 @@ arch:
 
 Required: `limit` + `in`. The count is **total physical lines** — blanks and comments included, not code lines — and a file over the limit is flagged at line `limit + 1`. Enforced identically in the TS and Rust engines, across every language klint scans.
 
+### Comment budget — cap explanatory prose
+
+Two ceilings on how much of a file may be comments. Use them to push intent into names and small
+functions rather than paragraphs that drift from the code they describe.
+
+```yaml
+arch:
+  # maxCommentDensity: what share of a file may be comment lines
+  maxCommentDensity:
+    - limit: 5                 # percent; required
+      in: ["src/**"]           # string OR array; supports ! negation
+      countDocComments: false  # optional — default false, so JSDoc/docstrings are exempt
+      message: "Encode intent in names and small functions, not prose"
+      severity: error          # optional — default error; use warn to record without blocking
+
+  # maxCommentBlock: how tall a single stack of comment lines may get
+  maxCommentBlock:
+    - limit: 2                 # consecutive comment lines; required
+      in: ["src/**"]
+      ignore: ["@codegen:"]    # optional — structural markers, not prose
+      message: "Extract a well-named function instead of stacking comment lines"
+```
+
+Required: `limit` + `in`. Density is a **percentage of total physical lines** (code + comments +
+blanks — the same denominator `maxLines` uses). Block height counts **consecutive** comment lines and
+is reported at the first offending line. Both exempt doc-comments by default — `/** … */` JSDoc and
+Python docstrings — so documentation is not penalised; ordinary `//`, `/* */`, and `#` comments always
+count. Set `countDocComments: true` to include them.
+
+The two are complementary: density catches a file that is 30% commented in scattered one-liners,
+block catches a ten-line essay above one function in an otherwise sparse file. Neither alone catches both.
+
+**`ignore` — comments that are machinery, not prose.** Some comments are load-bearing input to a
+build or codegen step (`// @codegen:region-start`, feature-strip markers, pragmas). They are comments to the
+lexer but structure to the project, and counting them makes both limits measure the wrong thing:
+
+```yaml
+arch:
+  maxCommentDensity:
+    - limit: 5
+      in: ["src/**"]
+      ignore: ["@codegen:"]         # literal substring, or "re:" for a regex
+```
+
+Two rules govern how an ignored line behaves, and both matter:
+
+- **It stays in the density denominator.** A marker is a physical line like code, so a 20-line file
+  with 4 markers and 1 real comment measures 1/20, not 1/16.
+- **It does not break a comment block.** `// a` / `// @marker` / `// b` / `// c` is a run of three
+  counted lines, not two runs. Otherwise sprinkling a marker every other line would defeat the cap.
+
+`ignore` tests the **physical source line**, so it only ever applies to lines already identified as
+comments — code containing the same text is untouched. Enforced identically in both engines.
+
 ## Pitfalls
 
 - `pattern` in `singleton` and `forbidden` is a **literal substring** by default — it will not catch `process.env["KEY"]` (bracket notation). Either grep for both forms, or use a `re:` regex prefix to match them in one rule. Caveat: a literal pattern that itself begins with `re:` cannot be expressed (it is always read as a regex), and regexes must stay in the common JS/RE2 subset (no lookaround or backreferences) so both engines agree.
 - `maxLines.limit` counts **total physical lines** (blanks and comments included), not code lines; a trailing newline does not add a line, and both engines count identically.
+- `maxCommentDensity.limit` is a **percentage, not a line count** — `limit: 5` means 5% of the file, so a 40-line file is over budget at its third comment line. Measure before picking a number: land it as `severity: warn` first, read the reported densities, then tighten to `error`.
 - `jsx-element` matches **intrinsic** (lowercase HTML) tags only — `button`, `input`, `label`. It does not match custom React components like `<Button>`; to restrict those, use `arch.imports` against the component's module instead.
 - A `forbidden`/`singleton` stanza takes either `pattern` or `jsx-element`, never both — split into two stanzas if you need both.
 - `only` in `singleton` is relative to the project root — use forward slashes on all platforms.

package/tools/generate-schema.ts

@@ -1,17 +1,27 @@
 #!/usr/bin/env bun
-import { writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { stringify as toYaml } from "yaml";
 import { KlintConfigSchema } from "../core/config.schema";
+import { schemaUrlForVersion } from "../core/schema-version";
 
 const raw = KlintConfigSchema.toJSONSchema() as Record<string, unknown>;
 
 // Set Draft-07 (broad editor compatibility) instead of 2020-12.
 delete raw.$schema;
 
+function packageVersion(): string {
+  const manifest = readFileSync(resolve(import.meta.dir, "../package.json"), "utf-8");
+  try {
+    return (JSON.parse(manifest) as { version?: string }).version ?? "0.0.0";
+  } catch {
+    throw new Error("package.json is not valid JSON — cannot stamp the schema version");
+  }
+}
+
 const schema = {
   $schema: "http://json-schema.org/draft-07/schema#",
-  $id: "https://klint.dev/schema.json",
+  $id: schemaUrlForVersion(packageVersion()),
   ...raw,
 };
 

package/tools/semantic-release-native-npm.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { spawnSync } from "node:child_process";
 
 const NATIVE_PACKAGES = [
@@ -57,6 +57,8 @@ export async function prepare(_, context) {
     if (!existsSync(binary)) {
       throw new Error(`Missing native binary for ${nativePackage.name}: ${binary}`);
     }
+
+    writeFileSync(join(dirname(binary), "VERSION"), `${version}\n`);
   }
 }
 

package/tools/semantic-release-root-npm.js

@@ -18,7 +18,7 @@ export async function verifyConditions(_, context) {
   }
 }
 
-export async function prepare(_, context) {
+export async function prepare(pluginConfig = {}, context) {
   const cwd = context.cwd ?? process.cwd();
   const version = context.nextRelease?.version;
 
@@ -29,6 +29,20 @@ export async function prepare(_, context) {
   const packageJson = readPackageJson(cwd);
   packageJson.version = version;
   writePackageJson(cwd, packageJson);
+
+  regenerateSchema(cwd, pluginConfig.spawnSync ?? spawnSync);
+}
+
+function regenerateSchema(cwd, spawn) {
+  const result = spawn("bun", ["tools/generate-schema.ts"], {
+    cwd,
+    encoding: "utf-8",
+    stdio: "inherit",
+  });
+
+  if ((result.status ?? -1) !== 0) {
+    throw new Error(`Schema generation failed with exit code ${result.status ?? -1}`);
+  }
 }
 
 export async function publish(pluginConfig = {}, context) {