@konvert7/klint 0.24.0 → 0.25.0

package/core/arch.ts

@@ -264,9 +264,33 @@ export function runArchRules(
     }
   }
 
+  for (const rule of arch.maxLines ?? []) {
+    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 === undefined) continue;
+      if (countLines(content) > rule.limit) {
+        violations.push({
+          file: relativeSlashPath(root, file),
+          line: rule.limit + 1,
+          message: rule.message ?? `File exceeds the maximum of ${rule.limit} lines`,
+          rule: "arch/max-lines",
+          severity,
+        });
+      }
+    }
+  }
+
   return violations;
 }
 
+/** Counts physical lines the same way Rust's `str::lines()` does — a trailing newline does not add a line. */
+function countLines(content: string): number {
+  if (content.length === 0) return 0;
+  return content.split("\n").length - (content.endsWith("\n") ? 1 : 0);
+}
+
 function toArray<T>(v: T | T[]): T[] {
   return Array.isArray(v) ? v : [v];
 }
@@ -303,6 +327,24 @@ function scanJsxElements(
   }
 }
 
+const REGEX_PREFIX = "re:";
+
+function buildLineMatcher(pattern: string): (line: string) => boolean {
+  if (!pattern.startsWith(REGEX_PREFIX)) {
+    return (line) => line.includes(pattern);
+  }
+  const source = pattern.slice(REGEX_PREFIX.length);
+  let regex: RegExp;
+  try {
+    regex = new RegExp(source);
+  } catch (cause) {
+    throw new Error(
+      `klint: invalid regex in arch pattern "${pattern}": ${(cause as Error).message}`
+    );
+  }
+  return (line) => regex.test(line);
+}
+
 function scanLinesForPattern(
   files: string[],
   pattern: string,
@@ -313,12 +355,13 @@ function scanLinesForPattern(
   severity: Severity,
   violations: Violation[]
 ): void {
+  const matchesLine = buildLineMatcher(pattern);
   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)) {
+      if (matchesLine(lines[i])) {
         violations.push({
           file: relativeSlashPath(root, file),
           line: i + 1,

package/core/config.schema.ts

@@ -115,7 +115,7 @@ const ArchForbiddenPatternRuleSchema = z
     pattern: z
       .string()
       .describe(
-        "Literal substring to search for in source. No regex — exact substring match (for example, a console logging call)."
+        "Pattern to search for, scanned per line. A literal substring by default (e.g. a console logging call). Prefix with `re:` to match a regular expression instead (e.g. `re:\\bp-\\[\\d+px\\]`). Regexes must use the common JS/RE2 subset — no lookaround or backreferences — so the TS and Rust engines agree. Note: a literal pattern that itself begins with `re:` cannot be expressed; such a value is always read as a regex."
       ),
     in: StringOrStringArray.describe(
       "Layer name(s) or glob(s) the pattern is forbidden in. Files outside the scope are not checked."
@@ -163,7 +163,7 @@ const ArchSingletonPatternRuleSchema = z
     pattern: z
       .string()
       .describe(
-        "Literal substring whose appearance is allowed only at one location. Exact substring match (e.g. `process.env.API_KEY`)."
+        "Pattern whose appearance is allowed only at one location, scanned per line. A literal substring by default (e.g. `process.env.API_KEY`). Prefix with `re:` to match a regular expression instead. Regexes must use the common JS/RE2 subset — no lookaround or backreferences — so the TS and Rust engines agree. Note: a literal pattern that itself begins with `re:` cannot be expressed; such a value is always read as a regex."
       ),
     only: z
       .string()
@@ -206,6 +206,37 @@ const ArchSingletonRuleSchema = z
     ],
   });
 
+const ArchMaxLinesRuleSchema = z
+  .object({
+    limit: z
+      .number()
+      .int()
+      .positive()
+      .describe(
+        "Maximum number of physical lines a file may contain. Counts every line including blanks and comments. A file with more lines than this is a violation."
+      ),
+    in: StringOrStringArray.describe(
+      "Layer name(s) or glob(s) the limit applies to. Files outside the scope are not checked."
+    ),
+    message: z
+      .string()
+      .optional()
+      .describe(
+        "Optional error message. Defaults to a message naming the limit (e.g. 'File exceeds the maximum of 300 lines')."
+      ),
+    severity: ArchSeveritySchema.optional(),
+  })
+  .strict()
+  .describe(
+    "A per-file line-count limit. Caps how long any file in scope may grow — the honest way to keep modules small without a formatter dependency."
+  )
+  .meta({
+    examples: [
+      'arch:\n  maxLines:\n    - limit: 300\n      in: src/**\n      message: "Split this module"',
+      "arch:\n  maxLines:\n    - limit: 300\n      in: src/**\n    - limit: 600\n      in: tests/**",
+    ],
+  });
+
 const ArchSchema = z
   .object({
     layers: ArchLayersSchema.optional(),
@@ -225,6 +256,12 @@ const ArchSchema = z
       .describe(
         "Singleton-location rules. Pin a pattern to one file; every other touch is a violation."
       ),
+    maxLines: z
+      .array(ArchMaxLinesRuleSchema)
+      .optional()
+      .describe(
+        "Per-file line-count limits. Cap how long files in a layer may grow, with different ceilings per scope."
+      ),
   })
   .strict()
   .describe(

package/core/native-binary.ts

@@ -100,7 +100,11 @@ function nativePackageVersionMatches(
 }
 
 function readJsonFile(path: string): { version?: string } {
-  return JSON.parse(readFileSync(path, "utf-8")) as { version?: string };
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as { version?: string };
+  } catch {
+    return {};
+  }
 }
 
 function resolveOptionalPackageJson(

package/core/types.ts

@@ -97,11 +97,19 @@ interface ArchSingletonJsxRule extends ArchSingletonRuleBase {
 
 type ArchSingletonRule = ArchSingletonPatternRule | ArchSingletonJsxRule;
 
+interface ArchMaxLinesRule {
+  limit: number;
+  in: string | string[];
+  message?: string;
+  severity?: Exclude<Severity, "off">;
+}
+
 export interface ArchConfig {
   layers?: Record<string, string[]>;
   imports?: ArchImportRule[];
   forbidden?: ArchForbiddenRule[];
   singleton?: ArchSingletonRule[];
+  maxLines?: ArchMaxLinesRule[];
 }
 
 export interface KlintConfig {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konvert7/klint",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Architecture-as-Code linter for TypeScript. Enforce layer boundaries, import rules, and singleton patterns in YAML.",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "cli.ts",
+    "cli",
     "core",
     "rules",
     "plugins",
@@ -64,10 +65,10 @@
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "@konvert7/klint-darwin-arm64": "0.24.0",
-    "@konvert7/klint-darwin-x64": "0.24.0",
-    "@konvert7/klint-linux-x64": "0.24.0",
-    "@konvert7/klint-win32-x64": "0.24.0"
+    "@konvert7/klint-darwin-arm64": "0.25.0",
+    "@konvert7/klint-darwin-x64": "0.25.0",
+    "@konvert7/klint-linux-x64": "0.25.0",
+    "@konvert7/klint-win32-x64": "0.25.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.7",

package/skill/klint-rules/SKILL.md

@@ -4,6 +4,19 @@ description: Add, modify, or explain klint architecture rules for this repo. Use
 argument-hint: <constraint to enforce>
 ---
 
+## Schema
+
+The full, authoritative config schema lives in the repo and is the source of truth for every field below:
+
+- YAML: <https://github.com/konvert7/klint/blob/main/klint.schema.yaml>
+- JSON: <https://github.com/konvert7/klint/blob/main/klint.schema.json>
+
+Wire it into `klint.yaml` for editor autocomplete and validation:
+
+```yaml
+# yaml-language-server: $schema=./klint.schema.yaml
+```
+
 ## Workflow
 
 1. **Understand the constraint** — if scope is ambiguous, ask: which files/layers are involved? should it block or warn? are there legitimate exceptions?
@@ -19,8 +32,12 @@ argument-hint: <constraint to enforce>
    |---|---|
    | Layer X must not import from layer Y | `arch.imports` + `deny` |
    | Layer X may only import from Y and Z | `arch.imports` + `allow` |
-   | Pattern P must only appear in one designated file | `arch.singleton` |
-   | Pattern P must never appear inside a scoped layer | `arch.forbidden` |
+   | Pattern P must only appear in one designated file | `arch.singleton` + `pattern` |
+   | Pattern P must never appear inside a scoped layer | `arch.forbidden` + `pattern` |
+   | Raw HTML/JSX element must never appear in a scoped layer | `arch.forbidden` + `jsx-element` |
+   | Raw HTML/JSX element may only appear in one primitive file | `arch.singleton` + `jsx-element` |
+   | A value-shaped pattern (regex) must never appear in a scoped layer | `arch.forbidden` + `pattern: "re:…"` |
+   | No file in a layer may exceed N lines | `arch.maxLines` + `limit` |
 
 4. **Read `klint.yaml`** — check existing `arch.layers` and rules before adding anything. Add a new named layer to `arch.layers` if the file group doesn't exist yet.
 
@@ -69,29 +86,80 @@ arch:
 ```
 
 ### Singleton — one designated location
+
+Pin a `pattern` (literal string) **or** a `jsx-element` (AST-matched tag) to exactly one file. Every other in-scope occurrence is a violation.
+
 ```yaml
 arch:
   singleton:
+    # pattern: literal string match — fires if it appears anywhere except `only`
     - pattern: "process.env.API_KEY"
       only: "src/lib/auth.ts"
-      in: ["src/**"]           # optional: limit scan scope (default: all files)
+      in: ["src/**"]           # optional: limit scan scope (default: all files). string OR array
       message: "Use the auth module instead of reading API_KEY directly"
+      severity: error          # optional — default error; use warn to record without blocking
+
+    # jsx-element: pin a raw element to its design-system primitive
+    - jsx-element: "button"     # one tag, or a list: ["button", "input"]
+      only: "src/components/ui/button.tsx"
+      in: ["src/**/*.tsx"]
+      message: "Raw <button> belongs only to the Button primitive"
 ```
 
-`pattern` is a **literal string match**. It fires if the pattern appears in any in-scope file except the `only` file.
+Required: `only` + `message`, plus one of `pattern` / `jsx-element` (not both in the same stanza).
 
 ### Forbidden — banned pattern in scope
+
+Block a `pattern` (literal string) **or** a `jsx-element` (AST-matched tag) inside a scoped layer.
+
 ```yaml
 arch:
   forbidden:
+    # pattern: literal substring by default; prefix with `re:` for a regex
     - pattern: "console.log("
-      in: ["src/lib/**"]
+      in: ["src/lib/**"]       # string OR array; supports ! negation
       message: "Use the logger — console.log leaks into the agent event stream"
+      severity: error          # optional — default error; use warn to record without blocking
+
+    # re: prefix — match a regular expression (common JS/RE2 subset; no lookaround/backrefs)
+    - pattern: 're:\b(?:p|gap)-\['
+      in: ["src/**/*.tsx"]
+      message: "Use the spacing scale, not arbitrary bracket values like p-[18px]"
+
+    # jsx-element: forbid raw HTML elements outside the design system
+    - jsx-element: ["button", "input", "label"]
+      in: ["src/app/**/*.tsx", "src/components/**/*.tsx", "!src/components/ui/**"]
+      message: "Use the design-system primitives in @/components/ui/* instead of raw HTML elements"
 ```
 
+Required: `in` + `message`, plus one of `pattern` / `jsx-element` (not both in the same stanza). A `pattern` may be a literal substring or, with the `re:` prefix, a regex; `singleton` patterns accept `re:` too.
+
+`jsx-element` matches intrinsic element names on the AST (opening and self-closing tags), so it is robust to whitespace, attributes, and naming collisions like `<buttonGroup>` — unlike a literal `pattern: "<button"` scan. It works on `.tsx`/`.jsx` files in both the TS and Rust engines.
+
+### Max lines — cap file length
+
+Limit how many physical lines a file in scope may have. Use a separate stanza per scope to give different ceilings to source and tests.
+
+```yaml
+arch:
+  maxLines:
+    - limit: 300               # positive integer; required
+      in: ["src/**"]           # string OR array; supports ! negation
+      message: "Split this module"   # optional — defaults to "File exceeds the maximum of N lines"
+      severity: error          # optional — default error; use warn to record without blocking
+
+    - limit: 600               # tests may run longer
+      in: ["tests/**"]
+```
+
+Required: `limit` + `in`. The count is **total physical lines** — blanks and comments included, not code lines — and a file over the limit is flagged at line `limit + 1`. Enforced identically in the TS and Rust engines, across every language klint scans.
+
 ## Pitfalls
 
-- `pattern` in `singleton` and `forbidden` is a **literal string** — will not catch `process.env["KEY"]` (bracket notation). Grep for both forms if both are possible.
+- `pattern` in `singleton` and `forbidden` is a **literal substring** by default — it will not catch `process.env["KEY"]` (bracket notation). Either grep for both forms, or use a `re:` regex prefix to match them in one rule. Caveat: a literal pattern that itself begins with `re:` cannot be expressed (it is always read as a regex), and regexes must stay in the common JS/RE2 subset (no lookaround or backreferences) so both engines agree.
+- `maxLines.limit` counts **total physical lines** (blanks and comments included), not code lines; a trailing newline does not add a line, and both engines count identically.
+- `jsx-element` matches **intrinsic** (lowercase HTML) tags only — `button`, `input`, `label`. It does not match custom React components like `<Button>`; to restrict those, use `arch.imports` against the component's module instead.
+- A `forbidden`/`singleton` stanza takes either `pattern` or `jsx-element`, never both — split into two stanzas if you need both.
 - `only` in `singleton` is relative to the project root — use forward slashes on all platforms.
 - `severity: warn` records the violation but does not block the session. Use `error` (the default) to block.
 - Path aliases (`@/*`) resolve via `tsconfig.json` `compilerOptions.paths`, including `extends` chains.

package/tools/generate-homebrew-formula.ts

@@ -19,16 +19,12 @@ class Klint < Formula
   version "${version}"
   license "MIT"
 
-  on_macos do
-    on_arm do
-      url "https://github.com/konvert7/klint/releases/download/native-v${version}/klint-${version}-darwin-arm64.tar.gz"
-      sha256 "${options.darwinArm64Sha}"
-    end
-
-    on_intel do
-      url "https://github.com/konvert7/klint/releases/download/native-v${version}/klint-${version}-darwin-x64.tar.gz"
-      sha256 "${options.darwinX64Sha}"
-    end
+  if Hardware::CPU.arm?
+    url "https://github.com/konvert7/klint/releases/download/native-v${version}/klint-${version}-darwin-arm64.tar.gz"
+    sha256 "${options.darwinArm64Sha}"
+  else
+    url "https://github.com/konvert7/klint/releases/download/native-v${version}/klint-${version}-darwin-x64.tar.gz"
+    sha256 "${options.darwinX64Sha}"
   end
 
   def install