@konvert7/klint 0.24.1 → 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.1",
+  "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.1",
-    "@konvert7/klint-darwin-x64": "0.24.1",
-    "@konvert7/klint-linux-x64": "0.24.1",
-    "@konvert7/klint-win32-x64": "0.24.1"
+    "@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

@@ -36,6 +36,8 @@ Wire it into `klint.yaml` for editor autocomplete and validation:
    | 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.
 
@@ -113,25 +115,49 @@ Block a `pattern` (literal string) **or** a `jsx-element` (AST-matched tag) insi
 ```yaml
 arch:
   forbidden:
-    # pattern: literal substring — no regex
+    # pattern: literal substring by default; prefix with `re:` for a regex
     - pattern: "console.log("
       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).
+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.