@konvert7/klint 0.26.0 → 0.27.0

package/README.md

@@ -148,7 +148,7 @@ klint --engine compare --json  # parity check; rejects unsupported rules
 
 Rust currently supports:
 
-- `arch` rules: imports, forbidden patterns (literal + `re:` regex), singleton locations, `maxLines` file limits
+- `arch` rules: imports, forbidden patterns (literal + `re:` regex), singleton locations, `maxLines` file limits, comment budgets (`maxCommentDensity`, `maxCommentBlock`)
 - `no-unguarded-json-parse`
 - `no-sync-in-async`
 - `no-nested-template-literals`
@@ -342,6 +342,31 @@ arch:
 
 `maxLines` is enforced in both the TS and Rust engines and applies to every language klint scans, with no formatter dependency.
 
+### Comment Budgets
+
+Push intent into names and code rather than prose — and keep token cost down — by capping how much of a file may be comments. Two independent limits, both counting only ordinary `//`, `/* */`, and `#` comments; doc-comments (`/** */` JSDoc and Python docstrings) are exempt by default so documentation stays free.
+
+`maxCommentDensity` caps the share of a file's physical lines that are comment lines. The denominator is total physical lines (the same count `maxLines` uses), so blank lines dilute the ratio:
+
+```yaml
+arch:
+  maxCommentDensity:
+    - limit: 5                # percent — no more than 5% of the file may be comments
+      in: ["src/**"]
+      message: "Encode intent in names, not comments"   # optional
+```
+
+`maxCommentBlock` caps how many consecutive comment lines may stack into one block, flagged at the first line past the limit. A tall explanation should become a well-named function instead:
+
+```yaml
+arch:
+  maxCommentBlock:
+    - limit: 2                # at most 2 comment lines in a row
+      in: ["src/**"]
+```
+
+Set `countDocComments: true` on either rule to count doc-comments toward the limit as well. Both rules run in the TS and Rust engines; Python files (`#` comments) are enforced by the Rust engine.
+
 ### Python Architecture Checks
 
 The Rust engine can apply architecture rules to Python projects:

package/core/arch-comments.ts

@@ -0,0 +1,93 @@
+import ts from "typescript";
+
+interface CommentSpan {
+  startLine: number;
+  endLine: number;
+  isDoc: boolean;
+}
+
+/** JS-like sources are lexed for comments; Python/Swift comment rules run in the native engine. */
+function collectComments(file: string, content: string): CommentSpan[] {
+  if (!/\.(tsx?|jsx?|mts|cts)$/.test(file)) return [];
+  const variant = /\.(tsx|jsx)$/.test(file)
+    ? ts.LanguageVariant.JSX
+    : ts.LanguageVariant.Standard;
+  const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, variant, content);
+  const starts = lineStarts(content);
+  const spans: CommentSpan[] = [];
+  let token = scanner.scan();
+  while (token !== ts.SyntaxKind.EndOfFileToken) {
+    if (
+      token === ts.SyntaxKind.SingleLineCommentTrivia ||
+      token === ts.SyntaxKind.MultiLineCommentTrivia
+    ) {
+      const start = scanner.getTokenStart();
+      const end = scanner.getTokenEnd();
+      spans.push({
+        startLine: lineAt(starts, start),
+        endLine: lineAt(starts, Math.max(start, end - 1)),
+        isDoc: isDocComment(content.slice(start, end)),
+      });
+    }
+    token = scanner.scan();
+  }
+  return spans;
+}
+
+/** A `/** *​/` JSDoc block, but not the empty `/**​/` comment. Mirrors the Rust engine. */
+function isDocComment(text: string): boolean {
+  return text.startsWith("/**") && text !== "/**/";
+}
+
+export function commentLineSet(
+  file: string,
+  content: string,
+  countDocComments: boolean
+): Set<number> {
+  const set = new Set<number>();
+  for (const span of collectComments(file, content)) {
+    if (!countDocComments && span.isDoc) continue;
+    for (let line = span.startLine; line <= span.endLine; line++) set.add(line);
+  }
+  return set;
+}
+
+/** Returns the first line at which a run of consecutive comment lines exceeds `limit`. */
+export function firstCommentBlockOverrun(
+  sortedLines: number[],
+  limit: number
+): number | undefined {
+  let runStart = sortedLines[0];
+  let prev = sortedLines[0];
+  for (let i = 1; i <= sortedLines.length; i++) {
+    const line = sortedLines[i];
+    if (line === prev + 1) {
+      prev = line;
+      continue;
+    }
+    if (prev - runStart + 1 > limit) return runStart + limit;
+    runStart = line;
+    prev = line;
+  }
+  return undefined;
+}
+
+function lineStarts(content: string): number[] {
+  const starts = [0];
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === "\n") starts.push(i + 1);
+  }
+  return starts;
+}
+
+/** 1-based line for a character offset, via binary search over line starts. */
+function lineAt(starts: number[], offset: number): number {
+  let lo = 0;
+  let hi = starts.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (starts[mid] <= offset) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo + 1;
+}

package/core/arch.ts

@@ -1,5 +1,6 @@
 import { dirname, isAbsolute, resolve } from "node:path";
 import ts from "typescript";
+import { commentLineSet, firstCommentBlockOverrun } from "./arch-comments";
 import { walkAst } from "./ast";
 import { relativeSlashPath, toSlashPath } from "./paths";
 import type { ArchConfig, Severity, Violation } from "./types";
@@ -282,6 +283,54 @@ export function runArchRules(
     }
   }
 
+  for (const rule of arch.maxCommentDensity ?? []) {
+    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;
+      const total = countLines(content);
+      if (total === 0) continue;
+      const commentLines = commentLineSet(file, content, rule.countDocComments ?? false);
+      const density = (commentLines.size / total) * 100;
+      if (density > rule.limit) {
+        violations.push({
+          file: relativeSlashPath(root, file),
+          line: 1,
+          message:
+            rule.message ??
+            `Comment density ${density.toFixed(1)}% exceeds the maximum of ${rule.limit}%`,
+          rule: "arch/max-comment-density",
+          severity,
+        });
+      }
+    }
+  }
+
+  for (const rule of arch.maxCommentBlock ?? []) {
+    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;
+      const commentLines = [
+        ...commentLineSet(file, content, rule.countDocComments ?? false),
+      ].sort((a, b) => a - b);
+      const overrun = firstCommentBlockOverrun(commentLines, rule.limit);
+      if (overrun !== undefined) {
+        violations.push({
+          file: relativeSlashPath(root, file),
+          line: overrun,
+          message:
+            rule.message ??
+            `Comment block exceeds the maximum of ${rule.limit} consecutive lines`,
+          rule: "arch/max-comment-block",
+          severity,
+        });
+      }
+    }
+  }
+
   return violations;
 }
 

package/core/config.schema.ts

@@ -237,6 +237,76 @@ const ArchMaxLinesRuleSchema = z
     ],
   });
 
+const CountDocCommentsSchema = z
+  .boolean()
+  .optional()
+  .describe(
+    "Count doc-comments toward the limit. Doc-comments are `/** … */` JSDoc blocks (TS/JS) and docstrings (Python); ordinary `//`, `/* */`, and `#` comments are always counted. Defaults to false, so documentation is exempt and only explanatory/inline comments are capped."
+  );
+
+const ArchMaxCommentDensityRuleSchema = z
+  .object({
+    limit: z
+      .number()
+      .positive()
+      .max(100)
+      .describe(
+        "Maximum percentage of a file's physical lines that may be comment lines. Denominator is total physical lines (code + comments + blanks), the same count `maxLines` uses. A file above this ratio is a violation."
+      ),
+    countDocComments: CountDocCommentsSchema,
+    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 measured density and the limit."
+      ),
+    severity: ArchSeveritySchema.optional(),
+  })
+  .strict()
+  .describe(
+    "A per-file comment-density ceiling. Caps how much of a file may be explanatory comments — the honest way to push intent into code and names rather than prose (and to keep token cost down), while leaving doc-comments free by default."
+  )
+  .meta({
+    examples: [
+      'arch:\n  maxCommentDensity:\n    - limit: 5\n      in: src/**\n      message: "Encode intent in names, not comments"',
+      "arch:\n  maxCommentDensity:\n    - limit: 10\n      countDocComments: true\n      in: src/**",
+    ],
+  });
+
+const ArchMaxCommentBlockRuleSchema = z
+  .object({
+    limit: z
+      .number()
+      .int()
+      .positive()
+      .describe(
+        "Maximum number of consecutive comment lines allowed in a single block. A run of more comment lines than this — e.g. a tall comment stacked above a statement — is a violation, reported at the first offending line."
+      ),
+    countDocComments: CountDocCommentsSchema,
+    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 consecutive-line limit."
+      ),
+    severity: ArchSeveritySchema.optional(),
+  })
+  .strict()
+  .describe(
+    "A per-block comment-height cap. Limits how many comment lines may stack together, so comments stay terse and a long explanation becomes a well-named function instead. Doc-comments are exempt by default."
+  )
+  .meta({
+    examples: [
+      'arch:\n  maxCommentBlock:\n    - limit: 2\n      in: src/**\n      message: "Extract a named function instead of a comment block"',
+    ],
+  });
+
 const ArchSchema = z
   .object({
     layers: ArchLayersSchema.optional(),
@@ -262,10 +332,22 @@ const ArchSchema = z
       .describe(
         "Per-file line-count limits. Cap how long files in a layer may grow, with different ceilings per scope."
       ),
+    maxCommentDensity: z
+      .array(ArchMaxCommentDensityRuleSchema)
+      .optional()
+      .describe(
+        "Per-file comment-density ceilings. Cap the share of a file that may be explanatory comments; doc-comments are exempt by default."
+      ),
+    maxCommentBlock: z
+      .array(ArchMaxCommentBlockRuleSchema)
+      .optional()
+      .describe(
+        "Per-block comment-height caps. Limit how many comment lines may stack together; doc-comments are exempt by default."
+      ),
   })
   .strict()
   .describe(
-    "Architecture-as-Code constraints — layers, import boundaries, forbidden patterns, singleton locations. Enforced by the arch engine alongside the rule set."
+    "Architecture-as-Code constraints — layers, import boundaries, forbidden patterns, singleton locations, comment budgets. Enforced by the arch engine alongside the rule set."
   );
 
 function buildRulesSchema() {

package/core/fixer.ts

@@ -20,12 +20,7 @@ export function applyFixes(violations: Violation[], root: string): number {
   let applied = 0;
   for (const [absPath, fileViolations] of byFile) {
     const lines = readFileSync(absPath, "utf-8").split("\n");
-    // Sort by endLine descending so the largest-range fix at any position wins.
-    // This handles bottom-to-top ordering (higher lines first) AND ensures outer
-    // fixes beat inner/overlapping fixes when chained calls share a start position.
-    const sorted = [...fileViolations].sort(
-      (a, b) => (b.fix?.endLine ?? 0) - (a.fix?.endLine ?? 0)
-    );
+    const sorted = [...fileViolations].sort(byLargestFixRangeFirst);
 
     const used: Array<{ start: number; end: number }> = [];
     for (const v of sorted) {
@@ -42,3 +37,11 @@ export function applyFixes(violations: Violation[], root: string): number {
 
   return applied;
 }
+
+/**
+ * Largest-range fix wins: sorting by `endLine` descending applies fixes bottom-to-top
+ * and lets an outer or overlapping fix beat inner ones that share a start position.
+ */
+function byLargestFixRangeFirst(a: Violation, b: Violation): number {
+  return (b.fix?.endLine ?? 0) - (a.fix?.endLine ?? 0);
+}

package/core/runner.ts

@@ -64,7 +64,14 @@ function resolveFiles(
       // directory doesn't exist — skip
     }
   }
-  return [...files];
+  return [...files].sort(byLexicographicOrder);
+}
+
+// Not localeCompare — must match the Rust engine's locale-independent Vec<PathBuf>::sort().
+function byLexicographicOrder(a: string, b: string): number {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
 }
 
 function matchPattern(relPath: string, pattern: string): boolean {

package/core/types.ts

@@ -104,12 +104,29 @@ interface ArchMaxLinesRule {
   severity?: Exclude<Severity, "off">;
 }
 
+interface ArchCommentRuleBase {
+  limit: number;
+  in: string | string[];
+  /** Count doc-comments (`/** *​/` JSDoc, Python docstrings) toward the limit. Defaults to false. */
+  countDocComments?: boolean;
+  message?: string;
+  severity?: Exclude<Severity, "off">;
+}
+
+/** Caps the share of a file's physical lines that are non-doc comments. */
+interface ArchMaxCommentDensityRule extends ArchCommentRuleBase {}
+
+/** Caps how many consecutive comment lines may stack into a single block. */
+interface ArchMaxCommentBlockRule extends ArchCommentRuleBase {}
+
 export interface ArchConfig {
   layers?: Record<string, string[]>;
   imports?: ArchImportRule[];
   forbidden?: ArchForbiddenRule[];
   singleton?: ArchSingletonRule[];
   maxLines?: ArchMaxLinesRule[];
+  maxCommentDensity?: ArchMaxCommentDensityRule[];
+  maxCommentBlock?: ArchMaxCommentBlockRule[];
 }
 
 export interface KlintConfig {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konvert7/klint",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Architecture-as-Code linter for TypeScript. Enforce layer boundaries, import rules, and singleton patterns in YAML.",
   "type": "module",
   "bin": {
@@ -65,10 +65,10 @@
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "@konvert7/klint-darwin-arm64": "0.26.0",
-    "@konvert7/klint-darwin-x64": "0.26.0",
-    "@konvert7/klint-linux-x64": "0.26.0",
-    "@konvert7/klint-win32-x64": "0.26.0"
+    "@konvert7/klint-darwin-arm64": "0.27.0",
+    "@konvert7/klint-darwin-x64": "0.27.0",
+    "@konvert7/klint-linux-x64": "0.27.0",
+    "@konvert7/klint-win32-x64": "0.27.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.7",

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

@@ -4,14 +4,16 @@ import { relativeSlashPath } from "../core/paths";
 import { buildNodeReplacementFix } from "../core/rule-helpers";
 import type { KlintRule } from "../core/types";
 
-// Unescaped metacharacters that lose their special meaning inside a character class,
-// making [.] a valid shorthand for a literal dot without needing \.
+/**
+ * Metacharacters that lose their special meaning inside a character class, so `[.]`
+ * is a valid shorthand for a literal dot and must not be unwrapped to a bare `.`.
+ */
 const METACHAR_EXCEPTIONS = new Set([".", "*", "+", "?", "{", "}", "(", ")", "|", "$"]);
 
 interface CharClass {
-  start: number; // index of '[' in pattern
-  end: number; // index of ']' in pattern
-  inner: string; // the single token inside
+  bracketStart: number;
+  bracketEnd: number;
+  innerToken: string;
 }
 
 function parseCharClasses(pattern: string): CharClass[] {
@@ -58,7 +60,9 @@ function parseCharClasses(pattern: string): CharClass[] {
     }
     if (i >= pattern.length) break;
     const end = i++;
-    if (tokens.length === 1) results.push({ start, end, inner: tokens[0] });
+    if (tokens.length === 1) {
+      results.push({ bracketStart: start, bracketEnd: end, innerToken: tokens[0] });
+    }
   }
   return results;
 }
@@ -81,17 +85,16 @@ export const noSingleCharClass: KlintRule = {
         const flags = regexSrc.slice(lastSlash + 1);
 
         const allClasses = parseCharClasses(pattern);
-        const toFix = allClasses.filter((c) => !METACHAR_EXCEPTIONS.has(c.inner));
+        const toFix = allClasses.filter((c) => !METACHAR_EXCEPTIONS.has(c.innerToken));
         if (toFix.length === 0) return;
 
-        // Build fixed pattern: replace [token] with token for non-exceptions
         let fixedPattern = "";
         let prev = 0;
         for (const cls of allClasses) {
-          if (METACHAR_EXCEPTIONS.has(cls.inner)) continue;
-          fixedPattern += pattern.slice(prev, cls.start);
-          fixedPattern += cls.inner;
-          prev = cls.end + 1;
+          if (METACHAR_EXCEPTIONS.has(cls.innerToken)) continue;
+          fixedPattern += pattern.slice(prev, cls.bracketStart);
+          fixedPattern += cls.innerToken;
+          prev = cls.bracketEnd + 1;
         }
         fixedPattern += pattern.slice(prev);
 
@@ -101,7 +104,7 @@ export const noSingleCharClass: KlintRule = {
         violations.push({
           file: relativeSlashPath(root, file),
           line: fix.startLine,
-          message: `Character class [${toFix[0].inner}] contains a single element — remove the brackets.`,
+          message: `Character class [${toFix[0].innerToken}] contains a single element — remove the brackets.`,
           fix,
         });
       });