@konvert7/klint 0.11.0 → 0.12.0

package/cli.ts

@@ -13,7 +13,7 @@ import * as clack from "@clack/prompts";
 import { parse as parseYaml } from "yaml";
 import { applyFixes } from "./core/fixer";
 import { resolveNativePackageBinary } from "./core/native-binary";
-import { runKlint } from "./core/runner";
+import { type KlintDebugEvent, runKlint } from "./core/runner";
 import type { ArchConfig, KlintConfig, KlintRule, RuleConfigValue } from "./core/types";
 import { BUILT_IN_PLUGINS } from "./plugins/index";
 import { BUILT_IN_RULES } from "./rules/index";
@@ -40,12 +40,14 @@ export async function main(opts: CliOptions = {}): Promise<void> {
   let rulesFile = opts.rulesFile;
   let fix = false;
   let json = false;
+  let debug = false;
 
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--config" && args[i + 1]) configDir = resolve(args[++i]);
     else if (args[i] === "--rules" && args[i + 1]) rulesFile = resolve(args[++i]);
     else if (args[i] === "--fix") fix = true;
     else if (args[i] === "--json") json = true;
+    else if (args[i] === "--debug" || args[i] === "-debug") debug = true;
     else if (args[i] === "--help" || args[i] === "-h") {
       printHelp();
       process.exit(0);
@@ -111,7 +113,8 @@ export async function main(opts: CliOptions = {}): Promise<void> {
       rules: allRules,
       arch: raw.arch as ArchConfig | undefined,
     },
-    customRules
+    customRules,
+    { onDebug: debug ? writeDebugEvent : undefined }
   );
 
   if (json) {
@@ -140,7 +143,8 @@ export async function main(opts: CliOptions = {}): Promise<void> {
           rules: allRules,
           arch: raw.arch as ArchConfig | undefined,
         },
-        customRules
+        customRules,
+        { onDebug: debug ? writeDebugEvent : undefined }
       );
       if (current.every((v) => !v.fix)) break;
     }
@@ -212,6 +216,11 @@ function runRustEngine({
   }
 
   const command = resolveRustEngineCommand(configDir);
+  if (process.argv.includes("--debug") || process.argv.includes("-debug")) {
+    process.stderr.write(
+      `[klint:debug] rust engine: ${command.bin} ${command.args.join(" ")}\n`
+    );
+  }
   const result = spawnSync(command.bin, command.args, {
     cwd: import.meta.dir,
     encoding: "utf-8",
@@ -222,6 +231,36 @@ function runRustEngine({
   process.exit(result.status ?? 1);
 }
 
+function writeDebugEvent(event: KlintDebugEvent): void {
+  switch (event.type) {
+    case "walk:start":
+      process.stderr.write(`[klint:debug] walk ${event.dir}\n`);
+      break;
+    case "walk:done":
+      process.stderr.write(`[klint:debug] walked ${event.dir} (${event.files} files)\n`);
+      break;
+    case "files:resolved":
+      process.stderr.write(`[klint:debug] resolved ${event.files} files\n`);
+      break;
+    case "rule:start":
+      process.stderr.write(
+        `[klint:debug] rule ${event.rule} start (${event.files} files)\n`
+      );
+      break;
+    case "rule:done":
+      process.stderr.write(
+        `[klint:debug] rule ${event.rule} done (${event.violations} violations)\n`
+      );
+      break;
+    case "arch:start":
+      process.stderr.write(`[klint:debug] arch start (${event.files} files)\n`);
+      break;
+    case "arch:done":
+      process.stderr.write(`[klint:debug] arch done (${event.violations} violations)\n`);
+      break;
+  }
+}
+
 interface RustEngineCommand {
   bin: string;
   args: string[];
@@ -396,6 +435,7 @@ function printHelp(): void {
       "  --rules  <file>  custom rules file (default: <configDir>/klint.rules.ts if present)",
       "  --fix            apply auto-fixes for fixable violations in-place",
       "  --json           emit structured JSON to stdout (for agent/CI consumption)",
+      "  --debug          print file resolution and rule progress to stderr",
       "",
       "  install-skill    install the rule-authoring skill into agent config directories",
       "                   --agents <list>  comma-separated: claude,opencode,cursor,codex (default: all)",

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 (e.g. `console.log(`)."
+        "Literal substring to search for in source. No regex — exact substring match (for example, a console logging call)."
       ),
     in: StringOrStringArray.describe(
       "Layer name(s) or glob(s) the pattern is forbidden in. Files outside the scope are not checked."
@@ -153,7 +153,7 @@ const ArchForbiddenRuleSchema = z
   )
   .meta({
     examples: [
-      'arch:\n  forbidden:\n    - pattern: "console.log("\n      in: core\n      message: "Leaks into the agent event stream"',
+      'arch:\n  forbidden:\n    - pattern: "debugLog("\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."',
     ],
   });

package/core/runner.ts

@@ -12,23 +12,49 @@ import type {
   Violation,
 } from "./types";
 
-function walk(dir: string): string[] {
+export type KlintDebugEvent =
+  | { type: "walk:start"; dir: string }
+  | { type: "walk:done"; dir: string; files: number }
+  | { type: "files:resolved"; files: number }
+  | { type: "rule:start"; rule: string; files: number }
+  | { type: "rule:done"; rule: string; violations: number }
+  | { type: "arch:start"; files: number }
+  | { type: "arch:done"; violations: number };
+
+export interface RunKlintOptions {
+  onDebug?: (event: KlintDebugEvent) => void;
+}
+
+function walk(dir: string, root: string, excludes: string[] = []): string[] {
   const out: string[] = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     const full = join(dir, entry.name);
-    if (entry.isDirectory()) out.push(...walk(full));
-    else if (/\.(tsx?|jsx?|mts|cts)$/.test(entry.name))
+    const rel = relative(root, full).replaceAll("\\", "/");
+    if (entry.isDirectory()) {
+      if (excludes.some((pattern) => matchPattern(rel, pattern))) continue;
+      out.push(...walk(full, root, excludes));
+    } else if (/\.(tsx?|jsx?|mts|cts)$/.test(entry.name))
       out.push(full.replaceAll("\\", "/"));
   }
   return out;
 }
 
-function resolveFiles(include: string[], root: string): string[] {
+function resolveFiles(
+  include: string[],
+  root: string,
+  onDebug?: (event: KlintDebugEvent) => void
+): string[] {
   const files = new Set<string>();
+  const excludes = include.filter((p) => p.startsWith("!")).map((p) => p.slice(1));
   for (const pattern of include) {
-    const dir = resolve(root, pattern.split("/**")[0].split("/*")[0]);
+    if (pattern.startsWith("!")) continue;
+    const base = pattern.split("/**")[0].split("/*")[0];
+    const dir = resolve(root, base === "**" ? "." : base);
     try {
-      for (const file of walk(dir)) files.add(file);
+      onDebug?.({ type: "walk:start", dir });
+      const before = files.size;
+      for (const file of walk(dir, root, excludes)) files.add(file);
+      onDebug?.({ type: "walk:done", dir, files: files.size - before });
     } catch {
       // directory doesn't exist — skip
     }
@@ -41,8 +67,17 @@ function matchPattern(relPath: string, pattern: string): boolean {
   const p = pattern.replaceAll("\\", "/");
   if (p === "." || p === "**") return true;
   if (p.endsWith("/**")) return norm.startsWith(`${p.slice(0, -3)}/`);
-  if (p.startsWith("**/")) return norm.endsWith(p.slice(2));
-  return norm === p || norm.startsWith(`${p}/`);
+  if (!p.includes("*")) return norm === p || norm.startsWith(`${p}/`);
+  return globToRegExp(p).test(norm);
+}
+
+function globToRegExp(pattern: string): RegExp {
+  const escaped = pattern
+    .replace(/[.+?^${}()|[\]\\]/g, "\\$&")
+    .replaceAll("**/", "(?:.*/)?")
+    .replaceAll("**", ".*")
+    .replaceAll("*", "[^/]*");
+  return new RegExp(`^${escaped}$`);
 }
 
 function applyPatterns(files: string[], patterns: string[], root: string): string[] {
@@ -66,7 +101,8 @@ function resolveInclude(value: RuleConfigValue): string[] | undefined {
 
 export function runKlint(
   config: KlintConfig,
-  customRules: Record<string, KlintRule> = {}
+  customRules: Record<string, KlintRule> = {},
+  options: RunKlintOptions = {}
 ): Violation[] {
   clearAstCache();
 
@@ -94,10 +130,11 @@ export function runKlint(
   };
 
   const allFiles = applyPatterns(
-    resolveFiles(config.include, config.root),
+    resolveFiles(config.include, config.root, options.onDebug),
     config.include,
     config.root
   );
+  options.onDebug?.({ type: "files:resolved", files: allFiles.length });
   const fileContents = new Map(allFiles.map((f) => [f, readFileSync(f, "utf-8")]));
   const violations: Violation[] = [];
 
@@ -112,12 +149,17 @@ export function runKlint(
     const files = include ? applyPatterns(allFiles, include, config.root) : allFiles;
 
     const batch: Omit<Violation, "severity">[] = [];
+    options.onDebug?.({ type: "rule:start", rule: ruleName, files: files.length });
     rule.check({ files, root: config.root, fileContents }, batch);
+    options.onDebug?.({ type: "rule:done", rule: ruleName, violations: batch.length });
     for (const v of batch) violations.push({ ...v, rule: ruleName, severity });
   }
 
   if (config.arch) {
-    violations.push(...runArchRules(config.arch, allFiles, fileContents, config.root));
+    options.onDebug?.({ type: "arch:start", files: allFiles.length });
+    const archViolations = runArchRules(config.arch, allFiles, fileContents, config.root);
+    options.onDebug?.({ type: "arch:done", violations: archViolations.length });
+    violations.push(...archViolations);
   }
 
   return violations;

package/package.json

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

package/tools/prepare-native-release.ts

@@ -49,16 +49,17 @@ try {
     fail(`Missing native release binaries:\n${missing.join("\n")}`);
   }
 
-  process.stdout.write(
-    `${[
-      `native release dry-run ok (${options.version})`,
-      `output: ${options.outDir}`,
-      `native packages: ${nativeResults.length}`,
-      missing.length > 0
-        ? `missing binaries: ${missing.join(", ")}`
-        : "missing binaries: none",
-    ].join("\n")}\n`
-  );
+  const missingMessage =
+    missing.length > 0
+      ? `missing binaries: ${missing.join(", ")}`
+      : "missing binaries: none";
+  const outputLines = [
+    `native release dry-run ok (${options.version})`,
+    `output: ${options.outDir}`,
+    `native packages: ${nativeResults.length}`,
+    missingMessage,
+  ];
+  process.stdout.write(`${outputLines.join("\n")}\n`);
 } finally {
   if (!options.keep) {
     rmSync(options.outDir, { recursive: true, force: true });
@@ -125,7 +126,12 @@ function validateNativePackage(packageJson: PackageJson): void {
 }
 
 function readPackageJson(path: string): PackageJson {
-  return JSON.parse(readFileSync(path, "utf-8")) as PackageJson;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as PackageJson;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    fail(`Failed to read package JSON at ${path}: ${message}`);
+  }
 }
 
 function writeJson(path: string, value: unknown): void {