@konvert7/klint 0.7.1 → 0.9.0

package/README.md

@@ -1,188 +1,298 @@
 # klint
 
-The bridge between vibe coding and agentic engineering.
+Architecture and type-aware linting for TypeScript projects.
 
-## Why
+Biome and oxlint are excellent at syntax, style, and fast local correctness. klint handles the rules that need project context: layer boundaries, singleton ownership, forbidden patterns, custom repository policies, and type-aware checks that should block an AI agent or CI run before code lands.
 
-Biome and oxlint enforce syntax-level style. klint enforces architecture-level rules — the kind that require TypeScript's type graph, span multiple files, or encode constraints that an AI agent must not bypass. If a rule needs to know that `fetchUser()` returns `Promise<User>`, or that sync filesystem calls are banned inside async hooks, that's a klint rule.
+Use klint when "please follow AGENTS.md" is not strong enough. Put the rule in `klint.yaml`, run `klint`, and make the constraint executable.
 
-Rules give your agent freedom. Without constraints, every decision is a risk. With klint, your agent knows exactly where it can move fast — and where it can't.
+## Install
 
-## Architecture as Code
-
-klint's YAML config supports an `arch:` section that lets you define architectural rules declaratively — no code required.
-
-> **AGENTS.md tells the model what to do. Klint ensures it actually did.**
->
-> Instructions in a prompt are a contract with no enforcement. A model that's drifting, context-starved, or just wrong will violate AGENTS.md silently and ship anyway. Klint makes the violation structurally impossible to land — the gate blocks it regardless of what the model thought it understood.
-
-### Layers
+klint currently runs on Bun.
 
-Define named file groups once, reference them everywhere:
-
-```yaml
-arch:
-  layers:
-    core:   ["src/hooks/lib/**", "src/tools/**"]
-    skills: ["assets/skills/**"]
+```sh
+bun add -d @konvert7/klint
 ```
 
-### Import boundaries
+Add a script:
 
-```yaml
-arch:
-  imports:
-    # deny: block imports from one layer into another
-    - from: skills
-      deny: core
-      message: "Skills must be self-contained and portable"
-      severity: warn          # optional, default: error
-
-    # allow: whitelist mode — anything not listed is denied (npm/node: builtins always pass)
-    - from: ["src/dao/**"]
-      allow: ["src/dao/**", "src/prisma/**", "src/types/**"]
-      message: "DAO may only import from dao, prisma, or types"
-
-    # type-only: allow — import type {} is permitted even when value imports are denied
-    - from: core
-      deny: ["src/targets/**"]
-      type-only: allow
-      message: "Core must not depend on agent-specific code"
+```json
+{
+  "scripts": {
+    "klint": "klint"
+  }
+}
 ```
 
-### Forbidden patterns
+Then create `klint.yaml` in your project root.
 
-Block literal string patterns inside a scoped layer:
+## Quickstart
 
 ```yaml
-arch:
-  forbidden:
-    - pattern: "console.log("
-      in: core
-      message: "Leaks into the agent event stream — use the hook output API instead"
+# klint.yaml
+include: ["src", "!**/node_modules/**"]
 
-    - pattern: "process.exit("
-      in: ["src/hooks/lib/**"]
-      message: "Library functions should return or throw, not terminate the process"
-```
-
-### Singleton locations
-
-Enforce that a pattern appears only in one designated file:
+rules:
+  no-floating-promise: error
+  no-unguarded-json-parse: error
+  no-sync-in-async:
+    severity: error
+    include: ["src/hooks/**"]
 
-```yaml
 arch:
-  singleton:
-    - pattern: "process.env.PAL_HOME"
-      only: "src/hooks/lib/paths.ts"
-      in: ["src/**"]                  # optional: limit scan scope
-      message: "Use the paths module"
+  layers:
+    app: ["src/app/**"]
+    data: ["src/data/**"]
+    ui: ["src/components/**"]
 
-    - pattern: "process.env.API_KEY"
-      only: "src/lib/auth.ts"
-      message: "Use the auth module"
+  imports:
+    - from: ui
+      deny: data
+      message: "UI components must go through app services, not data modules"
 ```
 
-### Agent integration
+Run it:
 
-Wire `--json` into your Stop hook so violations are machine-readable:
+```sh
+bun run klint
+```
 
-```typescript
-// .agents/hooks/klint.ts
-import { runHook } from "./run-hook";
-const exitCode = runHook(["bun", "klint/cli.ts", "--json"]);
-process.exit(exitCode);
+For machines and hooks:
+
+```sh
+bun run klint -- --json
 ```
 
-On errors the hook exits 2 (blocking) and emits:
+`--json` emits structured violations and exits `2` when errors are present.
 
 ```json
 {
   "violations": [
     {
       "rule": "arch/imports",
-      "file": "assets/skills/telos/tools/update-telos.ts",
-      "line": 23,
-      "severity": "warn",
-      "message": "Skills must be self-contained and portable",
+      "file": "src/components/Profile.tsx",
+      "line": 3,
+      "severity": "error",
+      "message": "UI components must go through app services, not data modules",
       "fix": null
     }
   ],
-  "summary": { "errors": 0, "warnings": 1 }
+  "summary": { "errors": 1, "warnings": 0 }
 }
 ```
 
-The agent reads the structured violations and fixes them before the session can close.
+## What Klint Catches
+
+klint is for rules that are too project-specific or context-heavy for a formatter.
+
+| Problem | Example |
+|---------|---------|
+| Layer boundaries | `src/components/**` must not import from `src/data/**` |
+| Singleton ownership | `process.env.API_KEY` may only appear in `src/lib/auth.ts` |
+| Forbidden patterns | `console.log(` is blocked inside hook libraries |
+| Type-aware mistakes | Promise-returning calls cannot be silently discarded |
+| Repository policy | Custom `klint.rules.ts` rules run with the same severity/config system |
 
----
+Rules give agents room to move quickly because the unsafe moves are blocked structurally.
 
-## Usage
+## CLI
 
 ```sh
-bun klint/cli.ts [--config <dir>] [--rules <file>] [--fix] [--json]
+klint [--config <dir>] [--rules <file>] [--fix] [--json]
+klint install-skill [--agents <list>] [--symlink | --copy]
 ```
 
 | Flag | Description |
 |------|-------------|
 | `--config <dir>` | Directory containing `klint.yaml` or `klint.config.json` (default: cwd) |
-| `--rules <file>` | Path to custom rules file (default: auto-discovered — see below) |
+| `--rules <file>` | Path to custom rules file (default: `<configDir>/klint.rules.ts` when present) |
 | `--fix` | Apply auto-fixes for fixable violations in-place |
-| `--json` | Emit structured JSON to stdout (for agent/CI consumption) |
+| `--json` | Emit structured JSON to stdout for agents and CI |
 
-If `--rules` is omitted, klint looks for `klint.rules.ts` next to the config file. If it exists it is loaded automatically; if it doesn't, no custom rules are used.
+`klint install-skill` installs the bundled rule-authoring skill for agent environments:
+
+```sh
+klint install-skill --agents claude,opencode,cursor,codex --copy
+```
 
 ## Configuration
 
-**`klint.yaml`** — lives at your project root alongside `biome.json` and `knip.json`:
+`klint.yaml` lives at your project root alongside tools like `biome.json`, `tsconfig.json`, and `knip.json`.
 
 ```yaml
 # yaml-language-server: $schema=./klint.schema.yaml
 
-include: ["src", "klint", "!**/node_modules/**"]
+include: ["src", "!**/node_modules/**"]
 plugins: [sonar]
+
 rules:
   no-unguarded-json-parse: error
-  no-sync-in-async:
-    severity: error
-    include: ["src/hooks/**"]
   no-floating-promise: error
-  my-custom-rule: warn
+  no-misused-promises: error
+  sonar/prefer-string-replaceall: warn
+  my-custom-rule:
+    severity: error
+    include: ["src/server/**"]
 
 arch:
   layers:
-    core: ["src/hooks/lib/**", "src/tools/**"]
+    server: ["src/server/**"]
+    client: ["src/client/**"]
+
   imports:
-    - from: ["assets/skills/**"]
-      deny: ["src/**"]
-      message: "Skills must be self-contained"
-      severity: warn
+    - from: client
+      deny: server
+      message: "Client code must not import server-only modules"
 ```
 
-`include` — glob patterns selecting which `.ts` files to lint.  
-`plugins` — named rule bundles (`"sonar"`) that apply a default set of rules.  
-`rules` — map of rule name → `"error" | "warn" | "off"` or an options object with `severity` and/or `include`.  
-`arch` — declarative architecture constraints (see Architecture as Code above).
+`include` selects `.ts` files to lint. Patterns support `**` globs and `!` negation.
 
-A `klint.config.json` fallback is supported for backwards compatibility.
+`plugins` enables bundled rule groups. Today, `sonar` provides focused code-quality rules.
+
+`rules` maps rule names to `"error"`, `"warn"`, `"off"`, or an options object with `severity` and/or `include`.
+
+`arch` declares architecture constraints without writing a custom rule.
+
+`klint.config.json` is still supported for backwards compatibility.
+
+## Architecture as Code
+
+The `arch:` section turns project boundaries into executable policy.
+
+### Layers
+
+Define named file groups once, then reference them from import rules:
+
+```yaml
+arch:
+  layers:
+    core: ["src/core/**", "src/lib/**"]
+    features: ["src/features/**"]
+    adapters: ["src/adapters/**"]
+```
+
+### Import Boundaries
+
+Use `deny` to block one layer from importing another:
+
+```yaml
+arch:
+  imports:
+    - from: features
+      deny: adapters
+      message: "Features must use core ports, not adapter implementations"
+      severity: error
+```
+
+Use `allow` for whitelist mode. Anything not listed is denied:
+
+```yaml
+arch:
+  imports:
+    - from: ["src/data/**"]
+      allow: ["src/data/**", "src/db/**", "src/types/**"]
+      message: "Data modules may only depend on data, db, and types"
+```
+
+Allow type-only imports when runtime imports are forbidden:
+
+```yaml
+arch:
+  imports:
+    - from: core
+      deny: adapters
+      type-only: allow
+      message: "Core may reference adapter types, but not adapter values"
+```
+
+### Forbidden Patterns
+
+Block literal string patterns inside a scoped layer:
+
+```yaml
+arch:
+  forbidden:
+    - pattern: "console.log("
+      in: ["src/hooks/**"]
+      message: "Hook output must go through the structured output API"
+
+    - pattern: "process.exit("
+      in: ["src/lib/**"]
+      message: "Libraries should return or throw, not terminate the process"
+```
+
+### Singleton Locations
+
+Enforce that a pattern appears only in one designated file:
+
+```yaml
+arch:
+  singleton:
+    - pattern: "process.env.API_KEY"
+      only: "src/lib/auth.ts"
+      in: ["src/**"]
+      message: "Use the auth module"
+```
 
 ## Built-in Rules
 
 | Rule | Type-aware | Description |
-|------|-----------|-------------|
+|------|------------|-------------|
 | `no-unguarded-json-parse` | No | `JSON.parse()` called outside a try/catch |
-| `no-sync-in-async` | No | Sync filesystem calls (`readFileSync` etc.) inside async functions |
-| `no-floating-promise` | **Yes** | Promise-returning call whose result is discarded |
-| `no-misused-promises` | **Yes** | Async function passed where a sync callback is expected |
+| `no-sync-in-async` | No | Sync filesystem calls inside async functions |
+| `no-floating-promise` | Yes | Promise-returning call whose result is discarded |
+| `no-misused-promises` | Yes | Async function passed where a sync callback is expected |
+| `no-async-predicate` | No | Async predicate passed to array filtering/search methods |
+| `no-date-equality` | No | Date values compared by object identity |
+| `no-optional-chain-on-non-nullable` | Yes | Optional chaining on values TypeScript knows are non-nullable |
+| `no-object-in-template` | Yes | Object values interpolated into template strings |
+| `no-nested-template-literals` | No | Template literals nested inside template literals |
+| `no-consecutive-array-push` | No | Multiple consecutive `push()` calls that should be grouped |
+| `no-string-match` | No | `String#match()` usage better expressed with clearer APIs |
+
+## Plugins
+
+Enable plugin rules with `plugins: [sonar]`, then override individual severities in `rules` when needed.
+
+| Rule | Description |
+|------|-------------|
+| `sonar/prefer-string-replaceall` | Prefer `replaceAll()` when replacing every string occurrence |
+| `sonar/prefer-string-raw-regexp` | Prefer `String.raw` for regex strings where escaping is easy to misread |
+| `sonar/prefer-string-raw` | Prefer `String.raw` for escape-heavy strings |
+| `sonar/prefer-nullish-coalescing-assign` | Prefer `??=` for nullish assignment patterns |
+| `sonar/no-single-char-class` | Avoid regex character classes with a single character |
+| `sonar/prefer-at` | Prefer `.at()` for relative index access |
+
+## Agent and CI Integration
+
+Agent hooks should run klint with `--json` so violations are machine-readable.
+
+```ts
+// .agents/hooks/klint.ts
+import { runHook } from "./run-hook";
+
+const exitCode = runHook(["bun", "run", "klint", "--", "--json"]);
+process.exit(exitCode);
+```
+
+In CI, run the same command you use locally:
+
+```sh
+bun install
+bun run klint
+```
+
+The important contract is simple: klint exits `0` when the project is clean, `2` when blocking errors exist, and can emit JSON for agents that need structured feedback.
 
 ## Custom Rules
 
-Create `klint.rules.ts` at your project root and export a `Record<string, KlintRule>` as default. Each key is the rule name:
+Create `klint.rules.ts` next to `klint.yaml` and export a `Record<string, KlintRule>` as default. Each key is the rule name.
 
 ```ts
 import { relative } from "node:path";
-import type { KlintRule } from "./klint/core/types";
+import type { KlintRule } from "@konvert7/klint/core/types";
 
-const myCustomRule: KlintRule = {
+const noForbiddenPattern: KlintRule = {
   check({ files, root, fileContents }, violations) {
     for (const file of files) {
       const lines = (fileContents.get(file) ?? "").split("\n");
@@ -191,7 +301,7 @@ const myCustomRule: KlintRule = {
           violations.push({
             file: relative(root, file),
             line: i + 1,
-            message: "Explain what's wrong and how to fix it.",
+            message: "Explain what is wrong and how to fix it.",
           });
         }
       }
@@ -200,25 +310,24 @@ const myCustomRule: KlintRule = {
 };
 
 export default {
-  "my-custom-rule": myCustomRule,
+  "no-forbidden-pattern": noForbiddenPattern,
 };
 ```
 
-All exported rules run at `"error"` severity by default. Override severity or scope them via `rules` in `klint.yaml` — the same mechanism as built-in rules:
+All exported custom rules run at `"error"` severity by default. Override severity or scope through `rules`:
 
 ```yaml
 rules:
-  my-custom-rule: warn
-  my-scoped-rule:
-    severity: error
-    include: ["src/hooks/**"]
+  no-forbidden-pattern:
+    severity: warn
+    include: ["src/server/**"]
 ```
 
-No separate registration step — everything exported from `klint.rules.ts` is picked up automatically.
+No separate registration step is required.
 
-### Auto-fix support
+### Auto-fix Support
 
-Add a `fix` field to a violation to make it auto-fixable with `--fix`. The fix replaces a line range with new text:
+Add a `fix` field to a violation to make it auto-fixable with `--fix`. Fixes replace a line range with new text:
 
 ```ts
 violations.push({
@@ -233,21 +342,22 @@ violations.push({
 });
 ```
 
-### Type-aware rules
+### Type-aware Rules
 
-For rules that need TypeScript's type checker, use `walkAst` from `klint/core/ast`:
+For rules that need the TypeScript AST, use `walkAst`:
 
 ```ts
 import ts from "typescript";
-import { walkAst } from "./klint/core/ast";
+import { walkAst } from "@konvert7/klint/core/ast";
+import type { KlintRule } from "@konvert7/klint/core/types";
 
-const myTypeAwareRule: KlintRule = {
-  check({ files, root, fileContents }, violations) {
+const noSpecificCall: KlintRule = {
+  check({ files, fileContents }, violations) {
     for (const file of files) {
       const content = fileContents.get(file) ?? "";
-      walkAst(file, content, (node, src) => {
+      walkAst(file, content, (node) => {
         if (ts.isCallExpression(node)) {
-          // inspect node using the TypeScript AST
+          // Inspect node with the TypeScript AST.
         }
       });
     }
@@ -255,32 +365,13 @@ const myTypeAwareRule: KlintRule = {
 };
 ```
 
-## Scoped includes
-
-Any rule can be restricted to a file subset via the `include` option. Patterns support `**` globs and negation with `!`:
-
-```yaml
-no-sync-in-async:
-  severity: error
-  include: ["src/hooks/**", "!src/hooks/scripts/**"]
-```
+## How It Fits
 
-## Architecture
+klint is not a replacement for Biome, oxlint, ESLint, knip, or TypeScript itself.
 
-```
-klint/
-  cli.ts          — CLI entry point; discovers config + rules, reports violations
-  core/
-    types.ts      — KlintRule, KlintConfig, ArchConfig, Violation, RuleEntry
-    runner.ts     — runKlint(); resolves files, dispatches rules, calls arch engine
-    arch.ts       — runArchRules(); AST import scanner, layers/imports/forbidden/singleton
-    ast.ts        — walkAst(), createProgram(), nearestFunctionIsAsync(), isInsideTry()
-    fixer.ts      — applyFixes(); bottom-up line-range patch with overlap detection
-  rules/
-    index.ts      — BUILT_IN_RULES registry
-    ...
-  tests/
-    ...
-```
+- Use TypeScript for type correctness.
+- Use Biome or oxlint for fast syntax and style checks.
+- Use knip for unused files and exports.
+- Use klint for architecture, agent constraints, project policy, and custom type-aware checks.
 
-The `klint/` directory is intentionally decoupled from the rest of the codebase — no imports cross the boundary in either direction. When it has enough rules, it ships as a standalone package.
+The goal is a small, sharp gate: the rules your project cannot afford to leave as prose.

package/cli.ts

@@ -283,7 +283,7 @@ function printHelp(): void {
       "klint — agent harness for TypeScript architecture rules",
       "",
       "Usage: klint [--config <dir>] [--rules <file>] [--fix] [--json]",
-      "       klint install-skill [--out <path>]",
+      "       klint install-skill [--agents <list>] [--symlink | --copy]",
       "",
       "  --config <dir>   directory containing klint.yaml or klint.config.json (default: cwd)",
       "  --rules  <file>  custom rules file (default: <configDir>/klint.rules.ts if present)",

package/core/arch.ts

@@ -78,7 +78,9 @@ function resolveLayerPrefixes(
   layers: Record<string, string[]> | undefined,
   root: string
 ): string[] {
-  return resolveGlobs(ref, layers).map((g) => globToPrefix(g, root));
+  return resolveGlobs(ref, layers)
+    .filter((g) => !g.startsWith("!"))
+    .map((g) => globToPrefix(g, root));
 }
 
 function resolveLayerFiles(
@@ -87,8 +89,18 @@ function resolveLayerFiles(
   root: string,
   allFiles: string[]
 ): string[] {
-  const prefixes = resolveLayerPrefixes(ref, layers, root);
-  return allFiles.filter((f) => prefixes.some((p) => f === p || f.startsWith(`${p}/`)));
+  const globs = resolveGlobs(ref, layers);
+  const includePrefixes = globs
+    .filter((g) => !g.startsWith("!"))
+    .map((g) => globToPrefix(g, root));
+  const excludePrefixes = globs
+    .filter((g) => g.startsWith("!"))
+    .map((g) => globToPrefix(g.slice(1), root));
+  return allFiles.filter(
+    (f) =>
+      includePrefixes.some((p) => f === p || f.startsWith(`${p}/`)) &&
+      !excludePrefixes.some((p) => f === p || f.startsWith(`${p}/`))
+  );
 }
 
 function inPrefixes(absPath: string, prefixes: string[]): boolean {
@@ -196,16 +208,29 @@ export function runArchRules(
   for (const rule of arch.forbidden ?? []) {
     const severity: Severity = rule.severity ?? "error";
     const inFiles = resolveLayerFiles(rule.in, layers, root, allFiles);
-    scanLinesForPattern(
-      inFiles,
-      rule.pattern,
-      fileContents,
-      root,
-      "arch/forbidden",
-      rule.message,
-      severity,
-      violations
-    );
+    if ("jsx-element" in rule) {
+      scanJsxElements(
+        inFiles,
+        toArray(rule["jsx-element"]),
+        fileContents,
+        root,
+        "arch/forbidden",
+        rule.message,
+        severity,
+        violations
+      );
+    } else {
+      scanLinesForPattern(
+        inFiles,
+        rule.pattern,
+        fileContents,
+        root,
+        "arch/forbidden",
+        rule.message,
+        severity,
+        violations
+      );
+    }
   }
 
   for (const rule of arch.singleton ?? []) {
@@ -215,21 +240,70 @@ 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
-    );
+    if ("jsx-element" in rule) {
+      scanJsxElements(
+        scope,
+        toArray(rule["jsx-element"]),
+        fileContents,
+        root,
+        "arch/singleton",
+        rule.message,
+        severity,
+        violations
+      );
+    } else {
+      scanLinesForPattern(
+        scope,
+        rule.pattern,
+        fileContents,
+        root,
+        "arch/singleton",
+        rule.message,
+        severity,
+        violations
+      );
+    }
   }
 
   return violations;
 }
 
+function toArray<T>(v: T | T[]): T[] {
+  return Array.isArray(v) ? v : [v];
+}
+
+function scanJsxElements(
+  files: string[],
+  tagNames: string[],
+  fileContents: Map<string, string>,
+  root: string,
+  ruleName: string,
+  message: string,
+  severity: Severity,
+  violations: Violation[]
+): void {
+  const targets = new Set(tagNames);
+  for (const file of files) {
+    if (!/\.(tsx|jsx)$/.test(file)) continue;
+    const content = fileContents.get(file);
+    if (!content) continue;
+    walkAst(file, content, (node, src) => {
+      if (!ts.isJsxOpeningElement(node) && !ts.isJsxSelfClosingElement(node)) return;
+      const tagName = node.tagName;
+      if (!ts.isIdentifier(tagName)) return;
+      if (!targets.has(tagName.text)) return;
+      const { line } = src.getLineAndCharacterOfPosition(tagName.getStart());
+      violations.push({
+        file: relative(root, file).replaceAll("\\", "/"),
+        line: line + 1,
+        message,
+        rule: ruleName,
+        severity,
+      });
+    });
+  }
+}
+
 function scanLinesForPattern(
   files: string[],
   pattern: string,

package/core/config.schema.ts

@@ -110,7 +110,7 @@ const ArchImportRuleSchema = z
     ],
   });
 
-const ArchForbiddenRuleSchema = z
+const ArchForbiddenPatternRuleSchema = z
   .object({
     pattern: z
       .string()
@@ -127,17 +127,38 @@ const ArchForbiddenRuleSchema = z
       ),
     severity: ArchSeveritySchema.optional(),
   })
-  .strict()
+  .strict();
+
+const ArchForbiddenJsxRuleSchema = z
+  .object({
+    "jsx-element": StringOrStringArray.describe(
+      "JSX intrinsic element name(s) to forbid (e.g. `button`, `input`, `label`). AST-matched on opening and self-closing tag names — robust to whitespace, attributes, and naming collisions like `<buttonGroup>`."
+    ),
+    in: StringOrStringArray.describe(
+      "Layer name(s) or glob(s) the element is forbidden in. Files outside the scope are not checked."
+    ),
+    message: z
+      .string()
+      .describe(
+        "Required error message explaining why the raw element is forbidden. Typically points at the design-system replacement (e.g. `Use <Button /> from @/components/ui/button`)."
+      ),
+    severity: ArchSeveritySchema.optional(),
+  })
+  .strict();
+
+const ArchForbiddenRuleSchema = z
+  .union([ArchForbiddenPatternRuleSchema, ArchForbiddenJsxRuleSchema])
   .describe(
-    "A forbidden-pattern rule. Blocks literal substrings (console.log, process.exit, raw SDK fetches, etc.) inside specific layers."
+    "A forbidden-pattern rule. Blocks either a literal substring (`pattern:`) or a JSX element (`jsx-element:`) inside specific layers."
   )
   .meta({
     examples: [
       'arch:\n  forbidden:\n    - pattern: "console.log("\n      in: core\n      message: "Leaks into the agent event stream"',
+      'arch:\n  forbidden:\n    - jsx-element: ["button", "input", "label"]\n      in: ["src/app/**/*.tsx", "src/components/**/*.tsx", "!src/components/ui/**"]\n      message: "Use the design-system primitives in @/components/ui/* instead of raw HTML elements."',
     ],
   });
 
-const ArchSingletonRuleSchema = z
+const ArchSingletonPatternRuleSchema = z
   .object({
     pattern: z
       .string()
@@ -152,20 +173,36 @@ const ArchSingletonRuleSchema = z
     in: StringOrStringArray.optional().describe(
       "Optional scope. Limit the scan to these layers/globs; defaults to all files in `include`."
     ),
-    message: z
+    message: z.string(),
+    severity: ArchSeveritySchema.optional(),
+  })
+  .strict();
+
+const ArchSingletonJsxRuleSchema = z
+  .object({
+    "jsx-element": StringOrStringArray.describe(
+      "JSX intrinsic element name(s) allowed only inside the `only` file. AST-matched on tag names."
+    ),
+    only: z
       .string()
       .describe(
-        "Required error message explaining why the pattern must stay singleton (security boundary, module-of-record, etc.)."
+        "The single file path where the element is allowed (typically the design-system primitive that wraps it)."
       ),
+    in: StringOrStringArray.optional(),
+    message: z.string(),
     severity: ArchSeveritySchema.optional(),
   })
-  .strict()
+  .strict();
+
+const ArchSingletonRuleSchema = z
+  .union([ArchSingletonPatternRuleSchema, ArchSingletonJsxRuleSchema])
   .describe(
-    "A singleton-location rule. Pins a pattern to exactly one file — the only honest way to enforce a module of record."
+    "A singleton-location rule. Pins a pattern or JSX element to exactly one file — the only honest way to enforce a module of record or a design-system primitive."
   )
   .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."',
+      'arch:\n  singleton:\n    - jsx-element: "button"\n      only: "src/components/ui/button.tsx"\n      in: ["src/**/*.tsx"]\n      message: "Raw <button> belongs only to the Button primitive."',
     ],
   });
 

package/core/runner.ts

@@ -17,7 +17,8 @@ function walk(dir: string): string[] {
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     const full = join(dir, entry.name);
     if (entry.isDirectory()) out.push(...walk(full));
-    else if (entry.name.endsWith(".ts")) out.push(full.replaceAll("\\", "/"));
+    else if (/\.(tsx?|jsx?|mts|cts)$/.test(entry.name))
+      out.push(full.replaceAll("\\", "/"));
   }
   return out;
 }

package/core/types.ts

@@ -63,15 +63,23 @@ interface ArchImportRule {
   severity?: Exclude<Severity, "off">;
 }
 
-interface ArchForbiddenRule {
-  pattern: string;
+interface ArchForbiddenRuleBase {
   in: string | string[];
   message: string;
   severity?: Exclude<Severity, "off">;
 }
 
-interface ArchSingletonRule {
+interface ArchForbiddenPatternRule extends ArchForbiddenRuleBase {
   pattern: string;
+}
+
+interface ArchForbiddenJsxRule extends ArchForbiddenRuleBase {
+  "jsx-element": string | string[];
+}
+
+type ArchForbiddenRule = ArchForbiddenPatternRule | ArchForbiddenJsxRule;
+
+interface ArchSingletonRuleBase {
   only: string;
   message: string;
   /** Limit scan to these files/layers. Defaults to all files. */
@@ -79,6 +87,16 @@ interface ArchSingletonRule {
   severity?: Exclude<Severity, "off">;
 }
 
+interface ArchSingletonPatternRule extends ArchSingletonRuleBase {
+  pattern: string;
+}
+
+interface ArchSingletonJsxRule extends ArchSingletonRuleBase {
+  "jsx-element": string | string[];
+}
+
+type ArchSingletonRule = ArchSingletonPatternRule | ArchSingletonJsxRule;
+
 export interface ArchConfig {
   layers?: Record<string, string[]>;
   imports?: ArchImportRule[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konvert7/klint",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Architecture-as-Code linter for TypeScript. Enforce layer boundaries, import rules, and singleton patterns in YAML.",
   "type": "module",
   "bin": {