@konvert7/klint 0.27.0 → 0.29.0

package/README.md

@@ -248,6 +248,10 @@ arch:
       message: "Data modules may only depend on data, db, and types"
 ```
 
+Every rule reads the module specifier off the AST, so `import`, dynamic
+`import()`, and re-exports all count as dependencies — `export { x } from "…"`
+and `export * from "…"` cross a boundary exactly like an import does.
+
 Allow type-only imports when runtime imports are forbidden:
 
 ```yaml
@@ -259,6 +263,50 @@ arch:
       message: "Core may reference adapter types, but not adapter values"
 ```
 
+This covers `import type`, `export type … from`, and — in Python — every import
+inside an `if TYPE_CHECKING:` block. The `else` and `elif` branches of such a
+guard stay runtime imports and are still reported.
+
+Block npm packages and `node:` builtins with `deny-packages`. `deny` and `allow` work on layers of
+project files, so they can never reach a specifier that doesn't resolve to one — that is what
+`deny-packages` is for:
+
+```yaml
+arch:
+  imports:
+    - from: ["src/dao/**"]
+      deny-packages: ["next/headers", "node:fs"]
+      message: "Data access must not read request state or touch the filesystem"
+```
+
+Matching is per segment, so `next` also covers `next/headers` while leaving `nextra` alone,
+and `next/headers` does not match `next/navigation`. Python splits on dots instead, so the same
+rule blocks pip packages and stdlib modules — `os` covers `os.path` and leaves `oscrypto` alone:
+
+```yaml
+arch:
+  imports:
+    - from: ["src/app/jobs/**"]
+      deny-packages: ["requests", "os"]
+      message: "Jobs must go through the http client and config"
+```
+
+Swift splits on dots as well and matches at module granularity, which makes system frameworks —
+exactly the imports that never resolve to a project file — the natural target:
+
+```yaml
+arch:
+  imports:
+    - from: ["Sources/App/Core/**"]
+      deny-packages: ["UIKit", "Foundation"]
+      message: "Core must stay free of UI and platform frameworks"
+```
+
+The specifier comes off the AST rather than a
+text scan, so static imports and dynamic `import()` are both caught while a mention inside a comment
+or string is not. `type-only: allow` exempts `import type` here too. `deny-packages` composes with
+`deny` in the same rule — one covers packages, the other project paths.
+
 ### Forbidden Patterns
 
 Block literal string patterns inside a scoped layer:
@@ -365,7 +413,49 @@ arch:
       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.
+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 (`#`) and Swift (`//`, `/* */`) files are enforced by the Rust engine.
+
+Some comments are machinery rather than prose — markers a build or codegen step reads, region pragmas — and counting them makes both limits measure the wrong thing. `ignore` exempts them, on either rule:
+
+```yaml
+arch:
+  maxCommentDensity:
+    - limit: 5
+      in: ["src/**"]
+      ignore: ["@codegen:"]     # literal substring, or "re:" for a regex
+```
+
+An ignored line still counts in the density denominator — it is a physical line like code — and still holds a comment block together, so a marker cannot be sprinkled between comment lines to split an over-tall block. Matching tests the physical source line and therefore only ever applies to lines already lexed as comments.
+
+### Language Support
+
+klint scans TypeScript/JavaScript, Python, Swift, and Rust. Every architecture rule is enforced from the same `klint.yaml`, but what a rule can *see* depends on what the language actually has.
+
+| | TypeScript / JavaScript | Python | Swift | Rust |
+|---|---|---|---|---|
+| **Engines** | `ts`, `rust` | `rust` | `rust` | `rust` |
+| **Parser** | TypeScript compiler API (TS engine), tree-sitter (Rust engine) | tree-sitter | tree-sitter | tree-sitter |
+| `arch.imports` — static | ✅ | ✅ | ✅ | ✅ `use` |
+| `arch.imports` — dynamic | ✅ `import()` | ✅ `importlib.import_module`, `__import__` | — | — |
+| `arch.imports` — re-exports | ✅ `export … from` | — | ✅ `@_exported import` | ✅ `pub use` |
+| `arch.imports` — multi-target | — | ✅ `import a, b` | — | ✅ `use a::{b, c}` |
+| `type-only: allow` | ✅ `import type` | ✅ `if TYPE_CHECKING:` | — | — |
+| Path aliases | ✅ `tsconfig.json` `paths` | — | — | — |
+| Module resolution | relative paths + alias chains | relative, absolute, and PEP 420 namespace packages | module name against project dirs and file stems | `crate::`/`self::`/`super::` against the directory tree |
+| `deny-packages` | ✅ `/` segments | ✅ `.` segments | ✅ `.` segments, module granularity | ✅ `::` segments |
+| `arch.forbidden` / `singleton` — `pattern` | ✅ | ✅ | ✅ | ✅ |
+| `arch.forbidden` / `singleton` — `jsx-element` | ✅ | — | — | — |
+| `arch.maxLines` | ✅ | ✅ | ✅ | ✅ |
+| `arch.maxCommentDensity` / `maxCommentBlock` | ✅ `//`, `/* */`, `/** */` docs | ✅ `#` | ✅ `//`, `/* */`, `///` and `/** */` docs | ✅ `//`, `/* */`, `///` and `//!` docs |
+| Built-in rules and plugins | ✅ | ✗ | ✗ | ✗ |
+| Custom rules (`klint.rules.ts`) | ✅ | ✗ | ✗ | ✗ |
+| Type-aware rules | ✅ | ✗ | ✗ | ✗ |
+
+**✅** supported · **—** the language has no equivalent construct · **✗** not supported yet
+
+A dash is not a gap. Swift has no dynamic import expression, no `import type`, and one module per declaration; Rust has no dynamic import and no type-only import. Those rows can never be filled. The `✗` rows are real limits: the rule set and custom rules are written against the TypeScript AST, and type-aware rules need a type checker that only the TS engine has.
+
+Imports are read off the AST in every language, so a specifier written inside a comment or a string is never an import — including nested Swift block comments. Only file discovery differs: the TS engine walks `.ts`/`.tsx`/`.js`/`.jsx`/`.mts`/`.cts`, so Python, Swift, and Rust files reach klint through the Rust engine, which `auto` mode selects for them automatically.
 
 ### Python Architecture Checks
 
@@ -401,9 +491,19 @@ arch:
 
 Python import checks support relative imports such as
 `from ..lib.auth import load_key` and project-resolvable absolute imports such
-as `from app.lib.auth import load_key`. External packages that do not resolve to
-project files, such as `requests`, are ignored. This is architecture
-enforcement, not full packaging or virtual-environment analysis.
+as `from app.lib.auth import load_key`. Every target of a multi-target statement
+is checked, so `import json, app.lib.auth` and `from . import helper, sibling`
+report per target rather than only the first one. Dynamic imports count too:
+`importlib.import_module("app.lib.auth")` and `__import__("app.lib.auth")` are
+read off the AST, including a renamed `from importlib import import_module as
+load`. A same-named call that is not bound to `importlib` — `self.import_module(…)` —
+is not an import and is left alone. A package import resolves through
+`<module>.py`, `<module>/__init__.py`, or a `<module>/` directory holding
+scanned `.py` files, so PEP 420 namespace packages with no `__init__.py` are
+covered. External packages that do not resolve to project files, such as
+`requests`, are ignored by `deny`/`allow` and are the target of `deny-packages`
+instead. This is architecture enforcement, not full packaging or
+virtual-environment analysis.
 
 ### Swift Architecture Checks
 
@@ -437,12 +537,64 @@ arch:
       message: "Use AppConfig"
 ```
 
-Swift import checks parse declarations such as `import Core`,
-`@_exported import Core`, and `import struct Models.User`. Imported modules
-resolve against discovered project Swift directories and file stems. System or
-package modules that are not present in the project, such as `Foundation`, are
-ignored. This is architecture enforcement, not full SwiftPM or Xcode build graph
-analysis.
+Swift import checks read declarations off the AST, covering `import Core`,
+`@_exported import Core`, `@testable import Core`, `import struct Models.User`,
+and submodule paths such as `import Core.Session`. Because the specifier comes
+from the parse tree, an `import` written inside a `//` or `/* */` comment is not
+an import — including nested block comments. Imported modules resolve against
+discovered project Swift directories and file stems. System or package modules
+that are not present in the project, such as `Foundation`, are ignored. This is
+architecture enforcement, not full SwiftPM or Xcode build graph analysis.
+
+Comment budget rules apply to Swift too, where `///` counts as a doc-comment
+alongside `/** */`.
+
+### Rust Architecture Checks
+
+The Rust engine can apply architecture rules to Rust crates:
+
+```yaml
+include: ["crates/**/*.rs", "!target/**"]
+
+rules: {}
+
+arch:
+  layers:
+    cli: ["crates/app/src/cli/**"]
+    domain: ["crates/app/src/domain/**"]
+    storage: ["crates/app/src/storage/**"]
+
+  imports:
+    - from: domain
+      deny: storage
+      message: "Domain logic must not reach into the storage layer"
+    - from: domain
+      deny-packages: ["reqwest", "tokio"]
+      message: "Keep I/O crates out of the domain layer"
+
+  maxLines:
+    - limit: 500
+      in: [cli, domain, storage]
+```
+
+Rust import checks read `use` declarations off the AST, and every target of a
+braced list becomes its own record — `use a::{b::{c, d}, e as f}` is checked as
+`a::b::c`, `a::b::d`, and `a::e`. Aliases contribute their path, `*` wildcards
+contribute the path they glob, and a bare `self` in a list names its own prefix.
+`pub use` re-exports are checked the same way as plain `use`.
+
+Paths starting with `crate::`, `self::`, or `super::` resolve against the
+directory tree by convention: klint walks down from the crate's `src` directory
+(the one holding `lib.rs` or `main.rs`), probing `foo.rs` then `foo/mod.rs` at
+each step and keeping the longest prefix that lands on a real file. Everything
+after that prefix is treated as an item inside the module. External crates have
+no file to resolve to and are ignored by `deny`/`allow`, which is what
+`deny-packages` is for — it matches on `::` segments, so `tokio` denies
+`tokio::sync::Mutex` but never `tokio_util`. This is architecture enforcement,
+not a Cargo build graph or `#[path]` attribute resolver.
+
+Comment budget rules apply to Rust too, where both `///` and `//!` count as
+doc-comments.
 
 ## Built-in Rules
 

package/core/arch-comments.ts

@@ -52,22 +52,40 @@ export function commentLineSet(
   return set;
 }
 
-/** Returns the first line at which a run of consecutive comment lines exceeds `limit`. */
+/**
+ * Comment lines whose source text matches an `ignore` pattern. They stay in the
+ * density denominator and keep a comment run contiguous, but count toward neither.
+ */
+export function ignoredCommentLines(
+  content: string,
+  commentLines: Iterable<number>,
+  matchesIgnore: (text: string) => boolean
+): Set<number> {
+  const sourceLines = content.split("\n");
+  const ignored = new Set<number>();
+  for (const line of commentLines) {
+    if (matchesIgnore(sourceLines[line - 1] ?? "")) ignored.add(line);
+  }
+  return ignored;
+}
+
+/**
+ * Returns the first line at which a run of consecutive comment lines exceeds
+ * `limit`. An ignored line neither counts toward the height nor breaks the run.
+ */
 export function firstCommentBlockOverrun(
   sortedLines: number[],
-  limit: number
+  limit: number,
+  ignored?: ReadonlySet<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;
+  let counted = 0;
+  let prev: number | undefined;
+  for (const line of sortedLines) {
+    if (prev !== undefined && line !== prev + 1) counted = 0;
     prev = line;
+    if (ignored?.has(line)) continue;
+    counted += 1;
+    if (counted > limit) return line;
   }
   return undefined;
 }

package/core/arch.ts

@@ -1,6 +1,10 @@
 import { dirname, isAbsolute, resolve } from "node:path";
 import ts from "typescript";
-import { commentLineSet, firstCommentBlockOverrun } from "./arch-comments";
+import {
+  commentLineSet,
+  firstCommentBlockOverrun,
+  ignoredCommentLines,
+} from "./arch-comments";
 import { walkAst } from "./ast";
 import { relativeSlashPath, toSlashPath } from "./paths";
 import type { ArchConfig, Severity, Violation } from "./types";
@@ -103,6 +107,12 @@ function resolveLayerFiles(
   );
 }
 
+function matchesPackage(specifier: string, entries: string[]): boolean {
+  return entries.some(
+    (entry) => specifier === entry || specifier.startsWith(`${entry}/`)
+  );
+}
+
 function inPrefixes(absPath: string, prefixes: string[]): boolean {
   return prefixes.some((p) => {
     if (absPath === p || absPath.startsWith(`${p}/`)) return true;
@@ -129,6 +139,11 @@ function scanImports(
         specifierNode = node.moduleSpecifier;
         isTypeOnly = node.importClause?.isTypeOnly ?? false;
       }
+    } else if (ts.isExportDeclaration(node)) {
+      if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+        specifierNode = node.moduleSpecifier;
+        isTypeOnly = node.isTypeOnly;
+      }
     } else if (
       ts.isCallExpression(node) &&
       node.expression.kind === ts.SyntaxKind.ImportKeyword &&
@@ -167,17 +182,30 @@ export function runArchRules(
   for (const rule of arch.imports ?? []) {
     const severity: Severity = rule.severity ?? "error";
     const fromFiles = resolveLayerFiles(rule.from, layers, root, allFiles);
+    const denyPackages = toArray(rule["deny-packages"] ?? []);
 
     for (const file of fromFiles) {
       const content = fileContents.get(file);
       if (!content) continue;
 
       for (const imp of scanImports(file, content, aliases)) {
-        if (isBareSpecifier(imp.resolved)) continue;
         if (rule["type-only"] === "allow" && imp.isTypeOnly) continue;
 
         const relFile = relativeSlashPath(root, file);
 
+        if (isBareSpecifier(imp.resolved)) {
+          if (matchesPackage(imp.path, denyPackages)) {
+            violations.push({
+              file: relFile,
+              line: imp.line,
+              message: rule.message ?? "Import of a denied package",
+              rule: "arch/imports",
+              severity,
+            });
+          }
+          continue;
+        }
+
         if (rule.deny !== undefined) {
           const denyPrefixes = resolveLayerPrefixes(rule.deny, layers, root);
           if (inPrefixes(imp.resolved, denyPrefixes)) {
@@ -285,6 +313,7 @@ export function runArchRules(
 
   for (const rule of arch.maxCommentDensity ?? []) {
     const severity: Severity = rule.severity ?? "error";
+    const ignoreMatcher = buildIgnoreMatcher(rule.ignore);
     const inFiles = resolveLayerFiles(rule.in, layers, root, allFiles);
     for (const file of inFiles) {
       const content = fileContents.get(file);
@@ -292,7 +321,11 @@ export function runArchRules(
       const total = countLines(content);
       if (total === 0) continue;
       const commentLines = commentLineSet(file, content, rule.countDocComments ?? false);
-      const density = (commentLines.size / total) * 100;
+      const ignored = ignoreMatcher
+        ? ignoredCommentLines(content, commentLines, ignoreMatcher)
+        : undefined;
+      const counted = commentLines.size - (ignored?.size ?? 0);
+      const density = (counted / total) * 100;
       if (density > rule.limit) {
         violations.push({
           file: relativeSlashPath(root, file),
@@ -309,6 +342,7 @@ export function runArchRules(
 
   for (const rule of arch.maxCommentBlock ?? []) {
     const severity: Severity = rule.severity ?? "error";
+    const ignoreMatcher = buildIgnoreMatcher(rule.ignore);
     const inFiles = resolveLayerFiles(rule.in, layers, root, allFiles);
     for (const file of inFiles) {
       const content = fileContents.get(file);
@@ -316,7 +350,10 @@ export function runArchRules(
       const commentLines = [
         ...commentLineSet(file, content, rule.countDocComments ?? false),
       ].sort((a, b) => a - b);
-      const overrun = firstCommentBlockOverrun(commentLines, rule.limit);
+      const ignored = ignoreMatcher
+        ? ignoredCommentLines(content, commentLines, ignoreMatcher)
+        : undefined;
+      const overrun = firstCommentBlockOverrun(commentLines, rule.limit, ignored);
       if (overrun !== undefined) {
         violations.push({
           file: relativeSlashPath(root, file),
@@ -378,6 +415,15 @@ function scanJsxElements(
 
 const REGEX_PREFIX = "re:";
 
+function buildIgnoreMatcher(
+  ignore: string | string[] | undefined
+): ((line: string) => boolean) | undefined {
+  const patterns = toArray(ignore ?? []);
+  if (patterns.length === 0) return undefined;
+  const matchers = patterns.map(buildLineMatcher);
+  return (line) => matchers.some((matches) => matches(line));
+}
+
 function buildLineMatcher(pattern: string): (line: string) => boolean {
   if (!pattern.startsWith(REGEX_PREFIX)) {
     return (line) => line.includes(pattern);

package/core/config.schema.ts

@@ -85,11 +85,14 @@ const ArchImportRuleSchema = z
     allow: StringOrStringArray.optional().describe(
       "Allowlist of layer name(s) / glob(s) the source may import from. Anything not matching `allow` is denied."
     ),
+    "deny-packages": StringOrStringArray.optional().describe(
+      "Package specifier(s) the source is not allowed to import — npm packages, `node:` builtins, Python pip packages and stdlib modules, Swift system frameworks, and external Rust crates, which `deny`/`allow` cannot reach because they never resolve to a project file. Matching is per segment: `/` in TypeScript/JavaScript, so `next` also covers `next/headers` while `nextra` is unaffected; `.` in Python and Swift, so `os` also covers `os.path` while `oscrypto` is unaffected; and `::` in Rust, so `tokio` also covers `tokio::sync::Mutex` while `tokio_util` is unaffected. Python, Swift, and Rust sources are checked by the Rust engine."
+    ),
     "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.'
+        'When set to "allow", `import type` statements that would otherwise be denied are permitted. In Python, imports inside an `if TYPE_CHECKING:` block are exempted the same way. Useful for type-only references across layers.'
       ),
     message: z
       .string()
@@ -244,6 +247,10 @@ const CountDocCommentsSchema = z
     "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 CommentIgnoreSchema = StringOrStringArray.optional().describe(
+  "Comment lines matching these patterns are structural, not prose — marker comments a build or codegen step reads, for example — and count toward neither limit. A literal substring by default; prefix with `re:` for a regex. Ignored lines still count in the density denominator (they are physical lines) and still hold a comment block together, so a marker cannot be used to split an over-tall block."
+);
+
 const ArchMaxCommentDensityRuleSchema = z
   .object({
     limit: z
@@ -254,6 +261,7 @@ const ArchMaxCommentDensityRuleSchema = z
         "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,
+    ignore: CommentIgnoreSchema,
     in: StringOrStringArray.describe(
       "Layer name(s) or glob(s) the limit applies to. Files outside the scope are not checked."
     ),
@@ -286,6 +294,7 @@ const ArchMaxCommentBlockRuleSchema = z
         "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,
+    ignore: CommentIgnoreSchema,
     in: StringOrStringArray.describe(
       "Layer name(s) or glob(s) the limit applies to. Files outside the scope are not checked."
     ),

package/core/types.ts

@@ -58,6 +58,7 @@ interface ArchImportRule {
   from: string | string[];
   deny?: string | string[];
   allow?: string | string[];
+  "deny-packages"?: string | string[];
   "type-only"?: "allow";
   message?: string;
   severity?: Exclude<Severity, "off">;
@@ -109,6 +110,8 @@ interface ArchCommentRuleBase {
   in: string | string[];
   /** Count doc-comments (`/** *​/` JSDoc, Python docstrings) toward the limit. Defaults to false. */
   countDocComments?: boolean;
+  /** Comment lines matching these patterns count toward neither limit. Literal substring, or `re:` for a regex. */
+  ignore?: string | string[];
   message?: string;
   severity?: Exclude<Severity, "off">;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konvert7/klint",
-  "version": "0.27.0",
+  "version": "0.29.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.27.0",
-    "@konvert7/klint-darwin-x64": "0.27.0",
-    "@konvert7/klint-linux-x64": "0.27.0",
-    "@konvert7/klint-win32-x64": "0.27.0"
+    "@konvert7/klint-darwin-arm64": "0.29.0",
+    "@konvert7/klint-darwin-x64": "0.29.0",
+    "@konvert7/klint-linux-x64": "0.29.0",
+    "@konvert7/klint-win32-x64": "0.29.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.7",

package/skill/klint-rules/SKILL.md

@@ -32,12 +32,15 @@ Wire it into `klint.yaml` for editor autocomplete and validation:
    |---|---|
    | Layer X must not import from layer Y | `arch.imports` + `deny` |
    | Layer X may only import from Y and Z | `arch.imports` + `allow` |
+   | Layer X must not import an npm package or `node:` builtin | `arch.imports` + `deny-packages` |
    | 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` |
+   | No file may be more than N% comments | `arch.maxCommentDensity` + `limit` |
+   | No comment block may stack more than N lines | `arch.maxCommentBlock` + `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.
 
@@ -78,13 +81,27 @@ arch:
       allow: ["src/dao/**", "src/prisma/**"]
       message: "DAO may only import from dao or prisma"
 
-    # type-only: allow — import type {} is permitted even when value imports are denied
+    # type-only: allow — import type {} and Python if TYPE_CHECKING: blocks stay permitted
     - from: core
       deny: targets
       type-only: allow
       message: "Core must not depend on agent-specific code"
+
+    # deny-packages: block npm packages and node: builtins, which deny/allow cannot reach
+    # because they never resolve to a project file. Composes with deny in the same rule.
+    - from: ["src/dao/**"]
+      deny-packages: ["next/headers", "node:fs"]
+      message: "Data access must not read request state or touch the filesystem"
 ```
 
+`deny-packages` matches per segment: `next` covers `next/headers`, `nextra` is unaffected, and
+`next/headers` does not match `next/navigation`. Python uses dotted segments, so `os` covers
+`os.path` and blocks pip packages and stdlib modules alike. Swift uses dotted segments too, at
+module granularity, which is what makes system frameworks like `UIKit` reachable. Rust splits on
+`::`, so `tokio` covers `tokio::sync::Mutex` while `tokio_util` is unaffected. The specifier is read off the AST, so
+static imports, dynamic `import()`, and `export … from` re-exports all count while a comment
+mentioning the package does not — unlike `forbidden` + `pattern`, which is a line-based text scan.
+
 ### 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.
@@ -154,10 +171,65 @@ arch:
 
 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.
 
+### Comment budget — cap explanatory prose
+
+Two ceilings on how much of a file may be comments. Use them to push intent into names and small
+functions rather than paragraphs that drift from the code they describe.
+
+```yaml
+arch:
+  # maxCommentDensity: what share of a file may be comment lines
+  maxCommentDensity:
+    - limit: 5                 # percent; required
+      in: ["src/**"]           # string OR array; supports ! negation
+      countDocComments: false  # optional — default false, so JSDoc/docstrings are exempt
+      message: "Encode intent in names and small functions, not prose"
+      severity: error          # optional — default error; use warn to record without blocking
+
+  # maxCommentBlock: how tall a single stack of comment lines may get
+  maxCommentBlock:
+    - limit: 2                 # consecutive comment lines; required
+      in: ["src/**"]
+      ignore: ["@codegen:"]    # optional — structural markers, not prose
+      message: "Extract a well-named function instead of stacking comment lines"
+```
+
+Required: `limit` + `in`. Density is a **percentage of total physical lines** (code + comments +
+blanks — the same denominator `maxLines` uses). Block height counts **consecutive** comment lines and
+is reported at the first offending line. Both exempt doc-comments by default — `/** … */` JSDoc and
+Python docstrings — so documentation is not penalised; ordinary `//`, `/* */`, and `#` comments always
+count. Set `countDocComments: true` to include them.
+
+The two are complementary: density catches a file that is 30% commented in scattered one-liners,
+block catches a ten-line essay above one function in an otherwise sparse file. Neither alone catches both.
+
+**`ignore` — comments that are machinery, not prose.** Some comments are load-bearing input to a
+build or codegen step (`// @codegen:region-start`, feature-strip markers, pragmas). They are comments to the
+lexer but structure to the project, and counting them makes both limits measure the wrong thing:
+
+```yaml
+arch:
+  maxCommentDensity:
+    - limit: 5
+      in: ["src/**"]
+      ignore: ["@codegen:"]         # literal substring, or "re:" for a regex
+```
+
+Two rules govern how an ignored line behaves, and both matter:
+
+- **It stays in the density denominator.** A marker is a physical line like code, so a 20-line file
+  with 4 markers and 1 real comment measures 1/20, not 1/16.
+- **It does not break a comment block.** `// a` / `// @marker` / `// b` / `// c` is a run of three
+  counted lines, not two runs. Otherwise sprinkling a marker every other line would defeat the cap.
+
+`ignore` tests the **physical source line**, so it only ever applies to lines already identified as
+comments — code containing the same text is untouched. Enforced identically in both engines.
+
 ## Pitfalls
 
 - `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.
+- `maxCommentDensity.limit` is a **percentage, not a line count** — `limit: 5` means 5% of the file, so a 40-line file is over budget at its third comment line. Measure before picking a number: land it as `severity: warn` first, read the reported densities, then tighten to `error`.
 - `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.