@konvert7/klint 0.4.0 → 0.6.0

package/core/arch.ts

@@ -196,23 +196,16 @@ export function runArchRules(
   for (const rule of arch.forbidden ?? []) {
     const severity: Severity = rule.severity ?? "error";
     const inFiles = resolveLayerFiles(rule.in, layers, root, allFiles);
-
-    for (const file of inFiles) {
-      const content = fileContents.get(file);
-      if (!content) continue;
-      const lines = content.split("\n");
-      for (let i = 0; i < lines.length; i++) {
-        if (lines[i].includes(rule.pattern)) {
-          violations.push({
-            file: relative(root, file).replaceAll("\\", "/"),
-            line: i + 1,
-            message: rule.message,
-            rule: "arch/forbidden",
-            severity,
-          });
-        }
-      }
-    }
+    scanLinesForPattern(
+      inFiles,
+      rule.pattern,
+      fileContents,
+      root,
+      "arch/forbidden",
+      rule.message,
+      severity,
+      violations
+    );
   }
 
   for (const rule of arch.singleton ?? []) {
@@ -222,24 +215,45 @@ export function runArchRules(
       ? resolveLayerFiles(rule.in, layers, root, allFiles)
       : allFiles;
     const scope = inFiles.filter((f) => f !== onlyFile);
+    scanLinesForPattern(
+      scope,
+      rule.pattern,
+      fileContents,
+      root,
+      "arch/singleton",
+      rule.message,
+      severity,
+      violations
+    );
+  }
 
-    for (const file of scope) {
-      const content = fileContents.get(file);
-      if (!content) continue;
-      const lines = content.split("\n");
-      for (let i = 0; i < lines.length; i++) {
-        if (lines[i].includes(rule.pattern)) {
-          violations.push({
-            file: relative(root, file).replaceAll("\\", "/"),
-            line: i + 1,
-            message: rule.message,
-            rule: "arch/singleton",
-            severity,
-          });
-        }
+  return violations;
+}
+
+function scanLinesForPattern(
+  files: string[],
+  pattern: string,
+  fileContents: Map<string, string>,
+  root: string,
+  ruleName: string,
+  message: string,
+  severity: Severity,
+  violations: Violation[]
+): void {
+  for (const file of files) {
+    const content = fileContents.get(file);
+    if (!content) continue;
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].includes(pattern)) {
+        violations.push({
+          file: relative(root, file).replaceAll("\\", "/"),
+          line: i + 1,
+          message,
+          rule: ruleName,
+          severity,
+        });
       }
     }
   }
-
-  return violations;
 }

package/core/config.schema.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { BUILT_IN_PLUGINS } from "../plugins/index";
 import { BUILT_IN_RULES } from "../rules/index";
+import type { KlintRule, RuleMeta } from "./types";
 
 const builtInRuleNames = Object.keys(BUILT_IN_RULES) as [string, ...string[]];
 const builtInPluginNames = Object.keys(BUILT_IN_PLUGINS) as [string, ...string[]];
@@ -12,18 +13,25 @@ const allKnownRuleNames = [...new Set([...builtInRuleNames, ...pluginRuleNames])
   ...string[],
 ];
 
+/** Look up a rule's implementation across BUILT_IN_RULES and plugin implementations. */
+function findRule(name: string): KlintRule | undefined {
+  if (BUILT_IN_RULES[name]) return BUILT_IN_RULES[name];
+  for (const plugin of Object.values(BUILT_IN_PLUGINS)) {
+    if (plugin.implementations[name]) return plugin.implementations[name];
+  }
+  return undefined;
+}
+
+function metaFor(name: string): RuleMeta | undefined {
+  return findRule(name)?.meta;
+}
+
 const SeveritySchema = z
   .enum(["error", "warn", "off"])
   .describe(
     'Rule severity. "error" exits with code 2; "warn" reports but exits 0; "off" silences.'
   );
 
-const RuleNameSchema = z
-  .union([z.enum(allKnownRuleNames), z.string()])
-  .describe(
-    "Built-in or plugin rule name (with autocomplete) or a custom rule name defined in klint.rules.ts."
-  );
-
 const RuleOptionsSchema = z
   .object({
     severity: SeveritySchema.optional(),
@@ -39,6 +47,165 @@ const RuleOptionsSchema = z
     'Rule options object. Omit severity to default to "error". Add include to scope the rule to specific files.'
   );
 
+const RuleValueSchema = z.union([SeveritySchema, RuleOptionsSchema]);
+
+// ─── arch ─────────────────────────────────────────────────────────────
+
+const ArchSeveritySchema = z
+  .enum(["error", "warn"])
+  .describe(
+    'Severity for the arch rule. "error" exits with code 2; "warn" reports but exits 0. (arch rules cannot be "off" — remove the entry instead.)'
+  );
+
+const StringOrStringArray = z
+  .union([z.string(), z.array(z.string())])
+  .describe(
+    "Either a single layer name / glob pattern or an array of them. Layer names defined in `arch.layers` are resolved to their glob lists."
+  );
+
+const ArchLayersSchema = z
+  .record(z.string(), z.array(z.string()))
+  .describe(
+    "Named architectural zones. Keys are arbitrary layer names; values are glob patterns matching the files in that layer. Other arch rules reference these names instead of repeating globs."
+  )
+  .meta({
+    examples: [
+      'layers:\n  core:   ["src/hooks/lib/**", "src/tools/**"]\n  skills: ["assets/skills/**"]\n  dao:    ["src/dao/**"]',
+    ],
+  });
+
+const ArchImportRuleSchema = z
+  .object({
+    from: StringOrStringArray.describe(
+      "Source — a layer name or glob(s) for the files this rule applies to. Imports originating in `from` are checked against `deny`/`allow`."
+    ),
+    deny: StringOrStringArray.optional().describe(
+      "Layer name(s) or glob(s) the source is not allowed to import from. Mutually exclusive in spirit with `allow` (use one or the other)."
+    ),
+    allow: StringOrStringArray.optional().describe(
+      "Allowlist of layer name(s) / glob(s) the source may import from. Anything not matching `allow` is denied."
+    ),
+    "type-only": z
+      .literal("allow")
+      .optional()
+      .describe(
+        'When set to "allow", `import type` statements that would otherwise be denied are permitted. Useful for type-only references across layers.'
+      ),
+    message: z
+      .string()
+      .optional()
+      .describe(
+        "Custom error message reported when the rule is violated. Shown in the agent's event stream alongside file:line."
+      ),
+    severity: ArchSeveritySchema.optional(),
+  })
+  .strict()
+  .describe(
+    "An import-boundary rule. Restricts which layers a source can or cannot import from."
+  )
+  .meta({
+    examples: [
+      'arch:\n  imports:\n    - from: skills\n      deny: core\n      message: "Skills must be self-contained and portable"\n      severity: warn',
+      'arch:\n  imports:\n    - from: ["src/dao/**"]\n      allow: ["src/dao/**", "src/prisma/**", "src/types/**"]',
+    ],
+  });
+
+const ArchForbiddenRuleSchema = z
+  .object({
+    pattern: z
+      .string()
+      .describe(
+        "Literal substring to search for in source. No regex — exact substring match (e.g. `console.log(`)."
+      ),
+    in: StringOrStringArray.describe(
+      "Layer name(s) or glob(s) the pattern is forbidden in. Files outside the scope are not checked."
+    ),
+    message: z
+      .string()
+      .describe(
+        "Required error message explaining why the pattern is forbidden. Shown to the agent so it can fix the call site."
+      ),
+    severity: ArchSeveritySchema.optional(),
+  })
+  .strict()
+  .describe(
+    "A forbidden-pattern rule. Blocks literal substrings (console.log, process.exit, raw SDK fetches, etc.) inside specific layers."
+  )
+  .meta({
+    examples: [
+      'arch:\n  forbidden:\n    - pattern: "console.log("\n      in: core\n      message: "Leaks into the agent event stream"',
+    ],
+  });
+
+const ArchSingletonRuleSchema = z
+  .object({
+    pattern: z
+      .string()
+      .describe(
+        "Literal substring whose appearance is allowed only at one location. Exact substring match (e.g. `process.env.API_KEY`)."
+      ),
+    only: z
+      .string()
+      .describe(
+        "The single file path where this pattern is allowed. Every other occurrence becomes a violation."
+      ),
+    in: StringOrStringArray.optional().describe(
+      "Optional scope. Limit the scan to these layers/globs; defaults to all files in `include`."
+    ),
+    message: z
+      .string()
+      .describe(
+        "Required error message explaining why the pattern must stay singleton (security boundary, module-of-record, etc.)."
+      ),
+    severity: ArchSeveritySchema.optional(),
+  })
+  .strict()
+  .describe(
+    "A singleton-location rule. Pins a pattern to exactly one file — the only honest way to enforce a module of record."
+  )
+  .meta({
+    examples: [
+      'arch:\n  singleton:\n    - pattern: "process.env.API_KEY"\n      only: "src/lib/auth.ts"\n      message: "API key access must funnel through the auth module."',
+    ],
+  });
+
+const ArchSchema = z
+  .object({
+    layers: ArchLayersSchema.optional(),
+    imports: z
+      .array(ArchImportRuleSchema)
+      .optional()
+      .describe(
+        "Import-boundary rules. The dependency graph your README claims you have."
+      ),
+    forbidden: z
+      .array(ArchForbiddenRuleSchema)
+      .optional()
+      .describe("Forbidden-pattern rules. Block literal strings scoped to a layer."),
+    singleton: z
+      .array(ArchSingletonRuleSchema)
+      .optional()
+      .describe(
+        "Singleton-location rules. Pin a pattern to one file; every other touch is a violation."
+      ),
+  })
+  .strict()
+  .describe(
+    "Architecture-as-Code constraints — layers, import boundaries, forbidden patterns, singleton locations. Enforced by the arch engine alongside the rule set."
+  );
+
+function buildRulesSchema() {
+  const shape: Record<string, z.ZodType> = {};
+  for (const name of allKnownRuleNames) {
+    const meta = metaFor(name);
+    let entry: z.ZodType = RuleValueSchema.optional();
+    if (meta?.description) entry = entry.describe(meta.description);
+    if (meta?.examples?.length) entry = entry.meta({ examples: meta.examples });
+    shape[name] = entry;
+  }
+  return z.object(shape).catchall(RuleValueSchema);
+}
+
 export const KlintConfigSchema = z
   .object({
     $schema: z
@@ -65,18 +232,12 @@ export const KlintConfigSchema = z
       .describe(
         'Named rule bundles to enable. Each plugin applies a default set of rules at "error" severity. Individual rules from the bundle can be overridden or silenced via the rules map. Available: "sonar".'
       ),
-    rules: z
-      .record(RuleNameSchema, z.union([SeveritySchema, RuleOptionsSchema]))
-      .optional()
-      .describe(
-        'Map of rule name → severity or options. Example: { "no-floating-promise": "error", "no-sync-in-async": { "severity": "warn", "include": ["src/hooks/**"] } }. Run `klint --help` for the full rule list.'
-      ),
-    arch: z
-      .unknown()
+    rules: buildRulesSchema()
       .optional()
       .describe(
-        "Architecture as Code constraints — layers, import boundaries, forbidden patterns, singleton locations. Parsed by the arch engine (Phase 2)."
+        'Map of rule name → severity or options. Example: { "no-floating-promise": "error", "no-sync-in-async": { "severity": "warn", "include": ["src/hooks/**"] } }.'
       ),
+    arch: ArchSchema.optional(),
   })
   .strict()
   .describe(

package/core/rule-helpers.ts

@@ -0,0 +1,76 @@
+import { relative } from "node:path";
+import ts from "typescript";
+import { createProgram } from "./ast";
+import type { KlintRule, RawViolation, RuleMeta } from "./types";
+import { defineRule } from "./types";
+
+export interface AstRuleContext {
+  sourceFile: ts.SourceFile;
+  checker: ts.TypeChecker;
+  root: string;
+  report(node: ts.Node, message: string): void;
+}
+
+export function defineAstRule(opts: {
+  meta: RuleMeta;
+  shouldRun?: (program: ts.Program) => boolean;
+  visit: (node: ts.Node, ctx: AstRuleContext) => void;
+}): KlintRule {
+  return defineRule({
+    meta: opts.meta,
+    check({ files, root }, violations) {
+      const program = createProgram(files, root);
+      if (opts.shouldRun && !opts.shouldRun(program)) return;
+      const checker = program.getTypeChecker();
+      const fileSet = new Set(files);
+
+      for (const sourceFile of program.getSourceFiles()) {
+        if (!fileSet.has(sourceFile.fileName) || sourceFile.isDeclarationFile) continue;
+
+        const ctx: AstRuleContext = {
+          sourceFile,
+          checker,
+          root,
+          report(node, message) {
+            const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+            violations.push({
+              file: relative(root, sourceFile.fileName),
+              line: line + 1,
+              message,
+            });
+          },
+        };
+
+        const walk = (node: ts.Node): void => {
+          opts.visit(node, ctx);
+          ts.forEachChild(node, walk);
+        };
+        walk(sourceFile);
+      }
+    },
+  });
+}
+
+/** Builds a single-node replacement fix preserving surrounding line text. */
+export function buildNodeReplacementFix(
+  src: ts.SourceFile,
+  node: ts.Node,
+  replacement: string
+): NonNullable<RawViolation["fix"]> {
+  const { line: startLine } = src.getLineAndCharacterOfPosition(node.getStart());
+  const { line: endLine } = src.getLineAndCharacterOfPosition(node.getEnd());
+  const lineStarts = src.getLineStarts();
+  const lineStart = lineStarts[startLine];
+  const lineEnd =
+    endLine + 1 < lineStarts.length ? lineStarts[endLine + 1] - 1 : src.text.length;
+  const linesText = src.text.slice(lineStart, lineEnd);
+  const nodeOffset = node.getStart() - lineStart;
+  const nodeEndOffset = node.getEnd() - lineStart;
+  const fixedLines =
+    linesText.slice(0, nodeOffset) + replacement + linesText.slice(nodeEndOffset);
+  return {
+    startLine: startLine + 1,
+    endLine: endLine + 1,
+    replacement: fixedLines,
+  };
+}

package/core/types.ts

@@ -33,8 +33,16 @@ export interface RuleContext {
 /** Violation as emitted by a rule — rule name and severity are stamped by the runner. */
 export type RawViolation = Omit<Violation, "rule" | "severity">;
 
+export interface RuleMeta {
+  /** One- or two-line description of what the rule catches. */
+  description: string;
+  /** Concrete YAML config snippets showing usage. Rendered as code blocks in docs. */
+  examples?: string[];
+}
+
 export interface KlintRule {
   check: (ctx: RuleContext, violations: RawViolation[]) => void;
+  meta?: RuleMeta;
 }
 
 /** A named bundle of rules with their default severities and implementations. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konvert7/klint",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Architecture-as-Code linter for TypeScript. Enforce layer boundaries, import rules, and singleton patterns in YAML.",
   "type": "module",
   "bin": {
@@ -39,6 +39,8 @@
     "check-write": "biome check --write",
     "knip": "knip-bun",
     "klint": "bun cli.ts",
+    "jscpd": "jscpd --noTips --silent",
+    "jscpd:report": "jscpd --noTips",
     "schema": "bun tools/generate-schema.ts",
     "lint-staged": "lint-staged",
     "prepare": "bun .husky/install.mjs"
@@ -64,6 +66,7 @@
     "@types/bun": "latest",
     "@types/node": "latest",
     "husky": "^9.1.7",
+    "jscpd": "4.2.3",
     "knip": "^6.9.0",
     "lint-staged": "^15.5.2",
     "semantic-release": "^25.0.3"

package/rules/no-async-predicate.ts

@@ -1,57 +1,36 @@
-import { relative } from "node:path";
 import ts from "typescript";
-import { createProgram } from "../core/ast";
-import type { RawViolation } from "../core/types";
-import { defineRule } from "../core/types";
+import { defineAstRule } from "../core/rule-helpers";
 
 const PREDICATE_METHODS = new Set(["filter", "some", "every", "find", "findIndex"]);
 
-export const noAsyncPredicate = defineRule({
-  check({ files, root }, violations) {
-    const program = createProgram(files, root);
-    const checker = program.getTypeChecker();
-    const fileSet = new Set(files);
+export const noAsyncPredicate = defineAstRule({
+  meta: {
+    description:
+      "Flags `async` functions passed to `.filter`/`.some`/`.every`/`.find`/`.findIndex`. Array methods coerce the returned promise to truthy, so every element appears to match.",
+    examples: ["no-async-predicate: error"],
+  },
+  visit(node, ctx) {
+    if (
+      !ts.isCallExpression(node) ||
+      !ts.isPropertyAccessExpression(node.expression) ||
+      !PREDICATE_METHODS.has(node.expression.name.text) ||
+      node.arguments.length === 0
+    )
+      return;
 
-    for (const sourceFile of program.getSourceFiles()) {
-      if (!fileSet.has(sourceFile.fileName) || sourceFile.isDeclarationFile) continue;
-      visitFile(sourceFile, checker, root, violations);
+    const receiverType = ctx.checker.getTypeAtLocation(node.expression.expression);
+    if (isArrayLike(receiverType) && isAsyncFunction(node.arguments[0])) {
+      const method = node.expression.name.text;
+      ctx.report(
+        node.arguments[0],
+        `Async callback passed to .${method}() — the returned Promise is always truthy, so the predicate never filters correctly. The array method cannot await it.`
+      );
     }
   },
 });
 
-function visitFile(
-  sourceFile: ts.SourceFile,
-  checker: ts.TypeChecker,
-  root: string,
-  violations: RawViolation[]
-): void {
-  function visit(node: ts.Node): void {
-    if (
-      ts.isCallExpression(node) &&
-      ts.isPropertyAccessExpression(node.expression) &&
-      PREDICATE_METHODS.has(node.expression.name.text) &&
-      node.arguments.length > 0
-    ) {
-      const receiverType = checker.getTypeAtLocation(node.expression.expression);
-      if (isArrayLike(receiverType, checker) && isAsyncFunction(node.arguments[0])) {
-        const method = node.expression.name.text;
-        const { line } = sourceFile.getLineAndCharacterOfPosition(
-          node.arguments[0].getStart()
-        );
-        violations.push({
-          file: relative(root, sourceFile.fileName),
-          line: line + 1,
-          message: `Async callback passed to .${method}() — the returned Promise is always truthy, so the predicate never filters correctly. The array method cannot await it.`,
-        });
-      }
-    }
-    ts.forEachChild(node, visit);
-  }
-  visit(sourceFile);
-}
-
-function isArrayLike(type: ts.Type, checker: ts.TypeChecker): boolean {
-  if (type.isUnion()) return type.types.some((t) => isArrayLike(t, checker));
+function isArrayLike(type: ts.Type): boolean {
+  if (type.isUnion()) return type.types.some((t) => isArrayLike(t));
   const sym = type.getSymbol();
   if (sym?.name === "Array" || sym?.name === "ReadonlyArray") return true;
   const ref = type as ts.TypeReference;

package/rules/no-consecutive-array-push.ts

@@ -4,6 +4,11 @@ import { walkAst } from "../core/ast";
 import type { KlintRule } from "../core/types";
 
 export const noConsecutiveArrayPush: KlintRule = {
+  meta: {
+    description:
+      "Flags consecutive `arr.push(x); arr.push(y);` calls — combine into `arr.push(x, y)` or `arr.push(...items)`.",
+    examples: ["no-consecutive-array-push: warn"],
+  },
   check({ files, root, fileContents }, violations) {
     for (const file of files) {
       const content = fileContents.get(file) ?? "";

package/rules/no-date-equality.ts

@@ -1,53 +1,33 @@
-import { relative } from "node:path";
 import ts from "typescript";
-import { createProgram } from "../core/ast";
-import type { RawViolation } from "../core/types";
-import { defineRule } from "../core/types";
+import { defineAstRule } from "../core/rule-helpers";
 
-export const noDateEquality = defineRule({
-  check({ files, root }, violations) {
-    const program = createProgram(files, root);
-    const checker = program.getTypeChecker();
-    const fileSet = new Set(files);
+export const noDateEquality = defineAstRule({
+  meta: {
+    description:
+      "Flags `Date` comparisons with `==`/`===`/`!=`/`!==` — these compare object identity, not the time value. Use `.getTime()` instead.",
+    examples: ["no-date-equality: error"],
+  },
+  visit(node, ctx) {
+    if (!ts.isBinaryExpression(node)) return;
+    const { kind } = node.operatorToken;
+    if (
+      kind !== ts.SyntaxKind.EqualsEqualsEqualsToken &&
+      kind !== ts.SyntaxKind.ExclamationEqualsEqualsToken
+    )
+      return;
 
-    for (const sourceFile of program.getSourceFiles()) {
-      if (!fileSet.has(sourceFile.fileName) || sourceFile.isDeclarationFile) continue;
-      visitFile(sourceFile, checker, root, violations);
+    const leftType = ctx.checker.getTypeAtLocation(node.left);
+    const rightType = ctx.checker.getTypeAtLocation(node.right);
+    if (isDateType(leftType) && isDateType(rightType)) {
+      const op = node.operatorToken.getText(ctx.sourceFile);
+      ctx.report(
+        node,
+        `Date values compared with ${op} — this compares object references, not time values. Use .getTime() or .valueOf() instead.`
+      );
     }
   },
 });
 
-function visitFile(
-  sourceFile: ts.SourceFile,
-  checker: ts.TypeChecker,
-  root: string,
-  violations: RawViolation[]
-): void {
-  function visit(node: ts.Node): void {
-    if (ts.isBinaryExpression(node)) {
-      const { kind } = node.operatorToken;
-      if (
-        kind === ts.SyntaxKind.EqualsEqualsEqualsToken ||
-        kind === ts.SyntaxKind.ExclamationEqualsEqualsToken
-      ) {
-        const leftType = checker.getTypeAtLocation(node.left);
-        const rightType = checker.getTypeAtLocation(node.right);
-        if (isDateType(leftType) && isDateType(rightType)) {
-          const op = node.operatorToken.getText(sourceFile);
-          const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
-          violations.push({
-            file: relative(root, sourceFile.fileName),
-            line: line + 1,
-            message: `Date values compared with ${op} — this compares object references, not time values. Use .getTime() or .valueOf() instead.`,
-          });
-        }
-      }
-    }
-    ts.forEachChild(node, visit);
-  }
-  visit(sourceFile);
-}
-
 function isDateType(type: ts.Type): boolean {
   if (type.getSymbol()?.name === "Date") return true;
   if (type.isUnion()) return type.types.some(isDateType);

package/rules/no-floating-promise.ts

@@ -1,49 +1,28 @@
-import { relative } from "node:path";
 import ts from "typescript";
-import { createProgram } from "../core/ast";
-import type { RawViolation } from "../core/types";
-import { defineRule } from "../core/types";
+import { defineAstRule } from "../core/rule-helpers";
 
-export const noFloatingPromise = defineRule({
-  check({ files, root }, violations) {
-    const program = createProgram(files, root);
-    const checker = program.getTypeChecker();
-    const fileSet = new Set(files);
-
-    for (const sourceFile of program.getSourceFiles()) {
-      if (!fileSet.has(sourceFile.fileName) || sourceFile.isDeclarationFile) continue;
-      visitFile(sourceFile, checker, root, violations);
-    }
+export const noFloatingPromise = defineAstRule({
+  meta: {
+    description:
+      "Flags Promise-returning expressions that aren't awaited or `.catch()`-handled — silent failures and unpredictable execution order.",
+    examples: ["no-floating-promise: error"],
   },
-});
-
-function visitFile(
-  sourceFile: ts.SourceFile,
-  checker: ts.TypeChecker,
-  root: string,
-  violations: RawViolation[]
-): void {
-  function visit(node: ts.Node): void {
+  visit(node, ctx) {
     if (
       ts.isExpressionStatement(node) &&
       ts.isCallExpression(node.expression) &&
       !isHandled(node.expression)
     ) {
-      const type = checker.getTypeAtLocation(node.expression);
+      const type = ctx.checker.getTypeAtLocation(node.expression);
       if (isPromiseLike(type)) {
-        const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
-        violations.push({
-          file: relative(root, sourceFile.fileName),
-          line: line + 1,
-          message:
-            "Promise-returning call is not awaited — errors will be silently discarded and execution order is unpredictable. Use await, void, or .catch().",
-        });
+        ctx.report(
+          node,
+          "Promise-returning call is not awaited — errors will be silently discarded and execution order is unpredictable. Use await, void, or .catch()."
+        );
       }
     }
-    ts.forEachChild(node, visit);
-  }
-  visit(sourceFile);
-}
+  },
+});
 
 function isHandled(node: ts.CallExpression): boolean {
   if (!ts.isPropertyAccessExpression(node.expression)) return false;

package/rules/no-misused-promises.ts

@@ -1,57 +1,34 @@
-import { relative } from "node:path";
 import ts from "typescript";
-import { createProgram } from "../core/ast";
-import type { RawViolation } from "../core/types";
-import { defineRule } from "../core/types";
+import { defineAstRule } from "../core/rule-helpers";
 
-export const noMisusedPromises = defineRule({
-  check({ files, root }, violations) {
-    const program = createProgram(files, root);
-    const checker = program.getTypeChecker();
-    const fileSet = new Set(files);
-
-    for (const sourceFile of program.getSourceFiles()) {
-      if (!fileSet.has(sourceFile.fileName) || sourceFile.isDeclarationFile) continue;
-      visitFile(sourceFile, checker, root, violations);
-    }
+export const noMisusedPromises = defineAstRule({
+  meta: {
+    description:
+      "Flags Promises passed where the type expects a non-thenable (e.g. an `if` condition, a `void` callback). The Promise's truthiness — not its resolved value — drives the branch.",
+    examples: ["no-misused-promises: error"],
   },
-});
-
-function visitFile(
-  sourceFile: ts.SourceFile,
-  checker: ts.TypeChecker,
-  root: string,
-  violations: RawViolation[]
-): void {
-  function visit(node: ts.Node): void {
-    if (ts.isCallExpression(node)) {
-      const sig = checker.getResolvedSignature(node);
-      if (sig) {
-        const params = sig.getParameters();
-        for (let i = 0; i < node.arguments.length; i++) {
-          const arg = node.arguments[i];
-          if (!isAsyncFunction(arg)) continue;
-
-          const param = params[Math.min(i, params.length - 1)];
-          if (!param) continue;
-
-          const paramType = checker.getTypeOfSymbolAtLocation(param, node);
-          if (expectsSyncCallback(paramType, checker)) {
-            const { line } = sourceFile.getLineAndCharacterOfPosition(arg.getStart());
-            violations.push({
-              file: relative(root, sourceFile.fileName),
-              line: line + 1,
-              message:
-                "Async function passed where a sync callback is expected — the caller cannot await it and errors will be silently lost.",
-            });
-          }
-        }
+  visit(node, ctx) {
+    if (!ts.isCallExpression(node)) return;
+    const sig = ctx.checker.getResolvedSignature(node);
+    if (!sig) return;
+    const params = sig.getParameters();
+    for (let i = 0; i < node.arguments.length; i++) {
+      const arg = node.arguments[i];
+      if (!isAsyncFunction(arg)) continue;
+
+      const param = params[Math.min(i, params.length - 1)];
+      if (!param) continue;
+
+      const paramType = ctx.checker.getTypeOfSymbolAtLocation(param, node);
+      if (expectsSyncCallback(paramType, ctx.checker)) {
+        ctx.report(
+          arg,
+          "Async function passed where a sync callback is expected — the caller cannot await it and errors will be silently lost."
+        );
       }
     }
-    ts.forEachChild(node, visit);
-  }
-  visit(sourceFile);
-}
+  },
+});
 
 function isAsyncFunction(
   node: ts.Node

package/rules/no-nested-template-literals.ts

@@ -4,6 +4,11 @@ import { walkAst } from "../core/ast";
 import type { KlintRule } from "../core/types";
 
 export const noNestedTemplateLiterals: KlintRule = {
+  meta: {
+    description:
+      "Flags template literals nested inside template literals — almost always unreadable; extract to a variable.",
+    examples: ["no-nested-template-literals: warn"],
+  },
   check({ files, root, fileContents }, violations) {
     for (const file of files) {
       const content = fileContents.get(file) ?? "";

package/rules/no-object-in-template.ts

@@ -1,8 +1,5 @@
-import { relative } from "node:path";
 import ts from "typescript";
-import { createProgram } from "../core/ast";
-import type { RawViolation } from "../core/types";
-import { defineRule } from "../core/types";
+import { defineAstRule } from "../core/rule-helpers";
 
 // Builtins with a meaningful toString() that isn't [object Object]
 const SAFE_SYMBOL_NAMES = new Set([
@@ -21,46 +18,25 @@ const SAFE_SYMBOL_NAMES = new Set([
   "Symbol",
 ]);
 
-export const noObjectInTemplate = defineRule({
-  check({ files, root }, violations) {
-    const program = createProgram(files, root);
-    const checker = program.getTypeChecker();
-    const fileSet = new Set(files);
-
-    for (const sourceFile of program.getSourceFiles()) {
-      if (!fileSet.has(sourceFile.fileName) || sourceFile.isDeclarationFile) continue;
-      visitFile(sourceFile, checker, root, violations);
-    }
+export const noObjectInTemplate = defineAstRule({
+  meta: {
+    description:
+      "Flags non-primitive objects interpolated into template literals — produces `[object Object]` unless `toString()` is overridden.",
+    examples: ["no-object-in-template: error"],
   },
-});
-
-function visitFile(
-  sourceFile: ts.SourceFile,
-  checker: ts.TypeChecker,
-  root: string,
-  violations: RawViolation[]
-): void {
-  function visit(node: ts.Node): void {
-    if (ts.isTemplateExpression(node)) {
-      for (const span of node.templateSpans) {
-        const type = checker.getTypeAtLocation(span.expression);
-        if (wouldRenderAsObjectObject(type, checker)) {
-          const { line } = sourceFile.getLineAndCharacterOfPosition(
-            span.expression.getStart()
-          );
-          violations.push({
-            file: relative(root, sourceFile.fileName),
-            line: line + 1,
-            message:
-              "Object interpolated in template literal has no custom toString() — it will render as [object Object]. Access a specific property or implement toString().",
-          });
-        }
+  visit(node, ctx) {
+    if (!ts.isTemplateExpression(node)) return;
+    for (const span of node.templateSpans) {
+      const type = ctx.checker.getTypeAtLocation(span.expression);
+      if (wouldRenderAsObjectObject(type, ctx.checker)) {
+        ctx.report(
+          span.expression,
+          "Object interpolated in template literal has no custom toString() — it will render as [object Object]. Access a specific property or implement toString()."
+        );
       }
     }
-    ts.forEachChild(node, visit);
-  }
-  visit(sourceFile);
-}
+  },
+});
 
 function wouldRenderAsObjectObject(type: ts.Type, checker: ts.TypeChecker): boolean {
   const primitiveFlags =

package/rules/no-optional-chain-on-non-nullable.ts

@@ -1,48 +1,27 @@
-import { relative } from "node:path";
 import ts from "typescript";
-import { createProgram } from "../core/ast";
-import type { RawViolation } from "../core/types";
-import { defineRule } from "../core/types";
+import { defineAstRule } from "../core/rule-helpers";
 
-export const noOptionalChainOnNonNullable = defineRule({
-  check({ files, root }, violations) {
-    const program = createProgram(files, root);
-    const checker = program.getTypeChecker();
-
-    if (!program.getCompilerOptions().strictNullChecks) return;
-
-    const fileSet = new Set(files);
-    for (const sourceFile of program.getSourceFiles()) {
-      if (!fileSet.has(sourceFile.fileName) || sourceFile.isDeclarationFile) continue;
-      visitFile(sourceFile, checker, root, violations);
-    }
+export const noOptionalChainOnNonNullable = defineAstRule({
+  meta: {
+    description:
+      "Flags `?.` on receivers whose static type cannot be `null` or `undefined`. The optional chain is dead code and obscures the real shape.",
+    examples: ["no-optional-chain-on-non-nullable: warn"],
   },
-});
-
-function visitFile(
-  sourceFile: ts.SourceFile,
-  checker: ts.TypeChecker,
-  root: string,
-  violations: RawViolation[]
-): void {
-  function visit(node: ts.Node): void {
+  shouldRun(program) {
+    return program.getCompilerOptions().strictNullChecks === true;
+  },
+  visit(node, ctx) {
     const receiver = getOptionalChainReceiver(node);
-    if (receiver) {
-      const type = checker.getTypeAtLocation(receiver);
-      if (!isNullable(type)) {
-        const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
-        violations.push({
-          file: relative(root, sourceFile.fileName),
-          line: line + 1,
-          message:
-            "Optional chain (?.) on a non-nullable type — the receiver can never be null or undefined here. Use . to remove misleading dead code.",
-        });
-      }
+    if (!receiver) return;
+    const type = ctx.checker.getTypeAtLocation(receiver);
+    if (!isNullable(type)) {
+      ctx.report(
+        node,
+        "Optional chain (?.) on a non-nullable type — the receiver can never be null or undefined here. Use . to remove misleading dead code."
+      );
     }
-    ts.forEachChild(node, visit);
-  }
-  visit(sourceFile);
-}
+  },
+});
 
 function getOptionalChainReceiver(node: ts.Node): ts.Expression | undefined {
   if (

package/rules/no-single-char-class.ts

@@ -1,6 +1,7 @@
 import { relative } from "node:path";
 import ts from "typescript";
 import { walkAst } from "../core/ast";
+import { buildNodeReplacementFix } from "../core/rule-helpers";
 import type { KlintRule } from "../core/types";
 
 // Unescaped metacharacters that lose their special meaning inside a character class,
@@ -63,6 +64,11 @@ function parseCharClasses(pattern: string): CharClass[] {
 }
 
 export const noSingleCharClass: KlintRule = {
+  meta: {
+    description:
+      "Flags single-character character classes in regex (e.g. `/[a]/`) — drop the brackets; the regex matches the same.",
+    examples: ["sonar/no-single-char-class: warn"],
+  },
   check({ files, root, fileContents }, violations) {
     for (const file of files) {
       const content = fileContents.get(file) ?? "";
@@ -90,27 +96,13 @@ export const noSingleCharClass: KlintRule = {
         fixedPattern += pattern.slice(prev);
 
         const fixedRegex = `/${fixedPattern}/${flags}`;
-        const { line } = src.getLineAndCharacterOfPosition(node.getStart());
-        const { line: endLine } = src.getLineAndCharacterOfPosition(node.getEnd());
-        const lineStarts = src.getLineStarts();
-        const lineStart = lineStarts[line];
-        const lineEnd =
-          endLine + 1 < lineStarts.length ? lineStarts[endLine + 1] - 1 : src.text.length;
-        const linesText = src.text.slice(lineStart, lineEnd);
-        const nodeOffset = node.getStart() - lineStart;
-        const nodeEndOffset = node.getEnd() - lineStart;
-        const fixedLines =
-          linesText.slice(0, nodeOffset) + fixedRegex + linesText.slice(nodeEndOffset);
+        const fix = buildNodeReplacementFix(src, node, fixedRegex);
 
         violations.push({
           file: relative(root, file),
-          line: line + 1,
+          line: fix.startLine,
           message: `Character class [${toFix[0].inner}] contains a single element — remove the brackets.`,
-          fix: {
-            startLine: line + 1,
-            endLine: endLine + 1,
-            replacement: fixedLines,
-          },
+          fix,
         });
       });
     }

package/rules/no-string-match.ts

@@ -4,6 +4,11 @@ import { walkAst } from "../core/ast";
 import type { KlintRule } from "../core/types";
 
 export const noStringMatch: KlintRule = {
+  meta: {
+    description:
+      "Flags `String#match` — prefer `.matchAll()` for iteration or `.test()` for boolean checks. `.match()` returns different shapes depending on the `/g` flag.",
+    examples: ["no-string-match: error"],
+  },
   check({ files, root, fileContents }, violations) {
     for (const file of files) {
       const content = fileContents.get(file) ?? "";

package/rules/no-sync-in-async.ts

@@ -4,6 +4,14 @@ import { nearestFunctionIsAsync, walkAst } from "../core/ast";
 import type { KlintRule } from "../core/types";
 
 export const noSyncInAsync: KlintRule = {
+  meta: {
+    description:
+      "Flags synchronous I/O (`readFileSync`, `execSync`, etc.) inside async functions — blocks the event loop when an async equivalent is available.",
+    examples: [
+      "no-sync-in-async: error",
+      'no-sync-in-async:\n  severity: warn\n  include: ["src/server/**"]',
+    ],
+  },
   check({ files, root, fileContents }, violations) {
     for (const file of files) {
       const content = fileContents.get(file) ?? "";

package/rules/no-unguarded-json-parse.ts

@@ -4,6 +4,11 @@ import { isInsideTry, walkAst } from "../core/ast";
 import type { KlintRule } from "../core/types";
 
 export const noUnguardedJsonParse: KlintRule = {
+  meta: {
+    description:
+      "Flags `JSON.parse()` calls that aren't wrapped in try/catch — malformed input crashes the process.",
+    examples: ["no-unguarded-json-parse: error"],
+  },
   check({ files, root, fileContents }, violations) {
     for (const file of files) {
       const content = fileContents.get(file) ?? "";

package/rules/prefer-at.ts

@@ -1,9 +1,15 @@
 import { relative } from "node:path";
 import ts from "typescript";
 import { walkAst } from "../core/ast";
+import { buildNodeReplacementFix } from "../core/rule-helpers";
 import type { KlintRule } from "../core/types";
 
 export const preferAt: KlintRule = {
+  meta: {
+    description:
+      "Flags negative-index access via `arr[arr.length - 1]` — `.at(-1)` reads cleaner for last-element access.",
+    examples: ["sonar/prefer-at: warn"],
+  },
   check({ files, root, fileContents }, violations) {
     for (const file of files) {
       const content = fileContents.get(file) ?? "";
@@ -26,27 +32,13 @@ export const preferAt: KlintRule = {
         if (baseText !== arg.left.expression.getText(src)) return;
 
         const fixedCall = `${baseText}.at(-${n})`;
-        const { line } = src.getLineAndCharacterOfPosition(node.getStart());
-        const { line: endLine } = src.getLineAndCharacterOfPosition(node.getEnd());
-        const lineStarts = src.getLineStarts();
-        const lineStart = lineStarts[line];
-        const lineEnd =
-          endLine + 1 < lineStarts.length ? lineStarts[endLine + 1] - 1 : src.text.length;
-        const linesText = src.text.slice(lineStart, lineEnd);
-        const nodeOffset = node.getStart() - lineStart;
-        const nodeEndOffset = node.getEnd() - lineStart;
-        const fixedLines =
-          linesText.slice(0, nodeOffset) + fixedCall + linesText.slice(nodeEndOffset);
+        const fix = buildNodeReplacementFix(src, node, fixedCall);
 
         violations.push({
           file: relative(root, file),
-          line: line + 1,
+          line: fix.startLine,
           message: `Prefer ${baseText}.at(-${n}) over ${baseText}[${baseText}.length - ${n}] for cleaner negative indexing.`,
-          fix: {
-            startLine: line + 1,
-            endLine: endLine + 1,
-            replacement: fixedLines,
-          },
+          fix,
         });
       });
     }

package/rules/prefer-nullish-coalescing-assign.ts

@@ -4,6 +4,11 @@ import { walkAst } from "../core/ast";
 import type { KlintRule } from "../core/types";
 
 export const preferNullishCoalescingAssign: KlintRule = {
+  meta: {
+    description:
+      "Flags `x = x ?? y` patterns — `x ??= y` is the dedicated nullish assignment operator.",
+    examples: ["sonar/prefer-nullish-coalescing-assign: warn"],
+  },
   check({ files, root, fileContents }, violations) {
     for (const file of files) {
       const content = fileContents.get(file) ?? "";

package/rules/prefer-string-raw-regexp.ts

@@ -4,6 +4,11 @@ import { walkAst } from "../core/ast";
 import type { KlintRule } from "../core/types";
 
 export const preferStringRawRegexp: KlintRule = {
+  meta: {
+    description:
+      "Flags regex literals built from escape-heavy string concatenation — `String.raw` drops the double backslashes.",
+    examples: ["sonar/prefer-string-raw-regexp: warn"],
+  },
   check({ files, root, fileContents }, violations) {
     for (const file of files) {
       const content = fileContents.get(file) ?? "";

package/rules/prefer-string-raw.ts

@@ -1,9 +1,15 @@
 import { relative } from "node:path";
 import ts from "typescript";
 import { walkAst } from "../core/ast";
+import { buildNodeReplacementFix } from "../core/rule-helpers";
 import type { KlintRule } from "../core/types";
 
 export const preferStringRaw: KlintRule = {
+  meta: {
+    description:
+      "Flags string literals with multiple backslash escapes — `String.raw` is more readable (Windows paths, regex source, etc.).",
+    examples: ["sonar/prefer-string-raw: warn"],
+  },
   check({ files, root, fileContents }, violations) {
     for (const file of files) {
       const content = fileContents.get(file) ?? "";
@@ -17,29 +23,15 @@ export const preferStringRaw: KlintRule = {
         // Can't embed backtick, ${ (would start interpolation), or trailing \ (would escape closing backtick)
         if (value.includes("`") || value.includes("${") || value.endsWith("\\")) return;
 
-        const { line } = src.getLineAndCharacterOfPosition(node.getStart());
-        const { line: endLine } = src.getLineAndCharacterOfPosition(node.getEnd());
-        const lineStarts = src.getLineStarts();
-        const lineStart = lineStarts[line];
-        const lineEnd =
-          endLine + 1 < lineStarts.length ? lineStarts[endLine + 1] - 1 : src.text.length;
-        const linesText = src.text.slice(lineStart, lineEnd);
-        const nodeOffset = node.getStart() - lineStart;
-        const nodeEndOffset = node.getEnd() - lineStart;
         const fixedNode = `String.raw\`${value}\``;
-        const fixedLines =
-          linesText.slice(0, nodeOffset) + fixedNode + linesText.slice(nodeEndOffset);
+        const fix = buildNodeReplacementFix(src, node, fixedNode);
 
         violations.push({
           file: relative(root, file),
-          line: line + 1,
+          line: fix.startLine,
           message:
             "String literal with escaped backslashes — use String.raw`...` for clarity (Sonar S6535).",
-          fix: {
-            startLine: line + 1,
-            endLine: endLine + 1,
-            replacement: fixedLines,
-          },
+          fix,
         });
       });
     }

package/rules/prefer-string-replaceall.ts

@@ -1,9 +1,15 @@
 import { relative } from "node:path";
 import ts from "typescript";
 import { walkAst } from "../core/ast";
+import { buildNodeReplacementFix } from "../core/rule-helpers";
 import type { KlintRule } from "../core/types";
 
 export const preferStringReplaceall: KlintRule = {
+  meta: {
+    description:
+      "Flags `.replace(/x/g, y)` on strings — `.replaceAll('x', y)` is clearer and faster for all-occurrence replacements.",
+    examples: ["sonar/prefer-string-replaceall: error"],
+  },
   check({ files, root, fileContents }, violations) {
     for (const file of files) {
       const content = fileContents.get(file) ?? "";
@@ -32,28 +38,13 @@ export const preferStringReplaceall: KlintRule = {
           ? `'${pattern.replaceAll("'", "\\'")}'`
           : `"${pattern}"`;
         const fixedCall = `${strText}.replaceAll(${patternLit}, ${replacementText})`;
-
-        const { line: s } = src.getLineAndCharacterOfPosition(node.getStart());
-        const { line: e } = src.getLineAndCharacterOfPosition(node.getEnd());
-        const lineStarts = src.getLineStarts();
-        const lineStart = lineStarts[s];
-        const lineEnd =
-          e + 1 < lineStarts.length ? lineStarts[e + 1] - 1 : src.text.length;
-        const linesText = src.text.slice(lineStart, lineEnd);
-        const nodeOffset = node.getStart() - lineStart;
-        const nodeEndOffset = node.getEnd() - lineStart;
-        const fixedLines =
-          linesText.slice(0, nodeOffset) + fixedCall + linesText.slice(nodeEndOffset);
+        const fix = buildNodeReplacementFix(src, node, fixedCall);
 
         violations.push({
           file: relative(root, file),
-          line: s + 1,
+          line: fix.startLine,
           message: `Prefer \`${strText}.replaceAll(${patternLit}, ...)\` over \`.replace(/${pattern}/g, ...)\` — replaceAll() with a string is clearer and avoids regex escaping pitfalls.`,
-          fix: {
-            startLine: s + 1,
-            endLine: e + 1,
-            replacement: fixedLines,
-          },
+          fix,
         });
       });
     }

package/tools/generate-schema.ts

@@ -3,27 +3,10 @@ import { writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { stringify as toYaml } from "yaml";
 import { KlintConfigSchema } from "../core/config.schema";
-import { BUILT_IN_PLUGINS } from "../plugins/index";
-import { BUILT_IN_RULES } from "../rules/index";
-
-const allKnownRuleNames = [
-  ...Object.keys(BUILT_IN_RULES),
-  ...Object.values(BUILT_IN_PLUGINS).flatMap((p) => Object.keys(p.rules)),
-];
 
 const raw = KlintConfigSchema.toJSONSchema() as Record<string, unknown>;
 
-// VS Code reads `properties` for key autocomplete, not `propertyNames`.
-// Expand known rule names into explicit property entries so editors suggest them.
-// `additionalProperties` stays to allow custom rule names without validation errors.
-const rulesSchema = (raw.properties as Record<string, Record<string, unknown>>).rules;
-const valueSchema = rulesSchema.additionalProperties;
-rulesSchema.properties = Object.fromEntries(
-  allKnownRuleNames.map((name) => [name, valueSchema])
-);
-delete rulesSchema.propertyNames;
-
-// Remove the 2020-12 $schema key; set Draft-07 for broad editor compatibility
+// Set Draft-07 (broad editor compatibility) instead of 2020-12.
 delete raw.$schema;
 
 const schema = {