@konvert7/klint 0.3.0 → 0.5.0

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/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.3.0",
+  "version": "0.5.0",
   "description": "Architecture-as-Code linter for TypeScript. Enforce layer boundaries, import rules, and singleton patterns in YAML.",
   "type": "module",
   "bin": {
@@ -39,6 +39,7 @@
     "check-write": "biome check --write",
     "knip": "knip-bun",
     "klint": "bun cli.ts",
+    "schema": "bun tools/generate-schema.ts",
     "lint-staged": "lint-staged",
     "prepare": "bun .husky/install.mjs"
   },

package/rules/no-async-predicate.ts

@@ -7,6 +7,11 @@ import { defineRule } from "../core/types";
 const PREDICATE_METHODS = new Set(["filter", "some", "every", "find", "findIndex"]);
 
 export const noAsyncPredicate = defineRule({
+  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"],
+  },
   check({ files, root }, violations) {
     const program = createProgram(files, root);
     const checker = program.getTypeChecker();

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

@@ -5,6 +5,11 @@ import type { RawViolation } from "../core/types";
 import { defineRule } from "../core/types";
 
 export const noDateEquality = defineRule({
+  meta: {
+    description:
+      "Flags `Date` comparisons with `==`/`===`/`!=`/`!==` — these compare object identity, not the time value. Use `.getTime()` instead.",
+    examples: ["no-date-equality: error"],
+  },
   check({ files, root }, violations) {
     const program = createProgram(files, root);
     const checker = program.getTypeChecker();

package/rules/no-floating-promise.ts

@@ -5,6 +5,11 @@ import type { RawViolation } from "../core/types";
 import { defineRule } from "../core/types";
 
 export const noFloatingPromise = defineRule({
+  meta: {
+    description:
+      "Flags Promise-returning expressions that aren't awaited or `.catch()`-handled — silent failures and unpredictable execution order.",
+    examples: ["no-floating-promise: error"],
+  },
   check({ files, root }, violations) {
     const program = createProgram(files, root);
     const checker = program.getTypeChecker();

package/rules/no-misused-promises.ts

@@ -5,6 +5,11 @@ import type { RawViolation } from "../core/types";
 import { defineRule } from "../core/types";
 
 export const noMisusedPromises = defineRule({
+  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"],
+  },
   check({ files, root }, violations) {
     const program = createProgram(files, root);
     const checker = program.getTypeChecker();

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

@@ -22,6 +22,11 @@ const SAFE_SYMBOL_NAMES = new Set([
 ]);
 
 export const noObjectInTemplate = defineRule({
+  meta: {
+    description:
+      "Flags non-primitive objects interpolated into template literals — produces `[object Object]` unless `toString()` is overridden.",
+    examples: ["no-object-in-template: error"],
+  },
   check({ files, root }, violations) {
     const program = createProgram(files, root);
     const checker = program.getTypeChecker();

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

@@ -5,6 +5,11 @@ import type { RawViolation } from "../core/types";
 import { defineRule } from "../core/types";
 
 export const noOptionalChainOnNonNullable = defineRule({
+  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"],
+  },
   check({ files, root }, violations) {
     const program = createProgram(files, root);
     const checker = program.getTypeChecker();

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

@@ -63,6 +63,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) ?? "";

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

@@ -4,6 +4,11 @@ import { walkAst } from "../core/ast";
 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) ?? "";

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

@@ -4,6 +4,11 @@ import { walkAst } from "../core/ast";
 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) ?? "";

package/rules/prefer-string-replaceall.ts

@@ -4,6 +4,11 @@ import { walkAst } from "../core/ast";
 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) ?? "";

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 = {
@@ -32,10 +15,10 @@ const schema = {
   ...raw,
 };
 
-const jsonOutPath = resolve(import.meta.dir, "../../klint.schema.json");
+const jsonOutPath = resolve(import.meta.dir, "../klint.schema.json");
 writeFileSync(jsonOutPath, `${JSON.stringify(schema, null, 2)}\n`);
 process.stdout.write(`Generated ${jsonOutPath}\n`);
 
-const yamlOutPath = resolve(import.meta.dir, "../../klint.schema.yaml");
+const yamlOutPath = resolve(import.meta.dir, "../klint.schema.yaml");
 writeFileSync(yamlOutPath, toYaml(schema, { lineWidth: 120 }));
 process.stdout.write(`Generated ${yamlOutPath}\n`);