@konvert7/klint 0.10.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.10.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": {
@@ -39,6 +39,7 @@
     "pack:check": "bun tests/pack-check.ts",
     "native:stage": "bun tests/stage-native-binary.ts",
     "native:smoke": "bun tests/smoke-native-binary.ts",
+    "native:release:dry-run": "bun tools/prepare-native-release.ts --version 0.0.0-dry-run",
     "check": "biome check",
     "check-write": "biome check --write",
     "knip": "knip-bun",
@@ -59,6 +60,12 @@
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },
+  "optionalDependencies": {
+    "@konvert7/klint-darwin-arm64": "*",
+    "@konvert7/klint-darwin-x64": "*",
+    "@konvert7/klint-linux-x64": "*",
+    "@konvert7/klint-win32-x64": "*"
+  },
   "devDependencies": {
     "@biomejs/biome": "2.4.7",
     "@commitlint/cli": "^20.5.3",

package/tools/prepare-native-release.ts

@@ -0,0 +1,168 @@
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { nativePackages } from "../core/native-binary";
+
+interface PackageJson {
+  name: string;
+  version: string;
+  private?: boolean;
+  optionalDependencies?: Record<string, string>;
+}
+
+interface Options {
+  version: string;
+  outDir: string;
+  requireBinaries: boolean;
+  keep: boolean;
+}
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+const options = parseArgs();
+
+if (existsSync(options.outDir)) {
+  rmSync(options.outDir, { recursive: true, force: true });
+}
+mkdirSync(options.outDir, { recursive: true });
+
+try {
+  const releaseRootPackageJson = prepareRootPackageJson();
+  const nativeResults = nativePackages().map(prepareNativePackage);
+
+  validateRootPackageJson(releaseRootPackageJson);
+  for (const result of nativeResults) validateNativePackage(result.packageJson);
+
+  const missing = nativeResults
+    .filter((result) => !result.binaryCopied)
+    .map((result) => result.packageJson.name);
+
+  if (options.requireBinaries && missing.length > 0) {
+    fail(`Missing native release binaries:\n${missing.join("\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 });
+  }
+}
+
+function prepareRootPackageJson(): PackageJson {
+  const packageJson = readPackageJson(join(root, "package.json"));
+  packageJson.version = options.version;
+  packageJson.optionalDependencies = Object.fromEntries(
+    nativePackages().map((nativePackage) => [nativePackage.packageName, options.version])
+  );
+
+  const outPath = join(options.outDir, "package.json");
+  writeJson(outPath, packageJson);
+  return packageJson;
+}
+
+function prepareNativePackage(nativePackage: ReturnType<typeof nativePackages>[number]): {
+  binaryCopied: boolean;
+  packageJson: PackageJson;
+} {
+  const packageDirName = `${nativePackage.platform}-${nativePackage.arch}`;
+  const sourceDir = join(root, "npm", "native", packageDirName);
+  const outDir = join(options.outDir, "npm", "native", packageDirName);
+  mkdirSync(outDir, { recursive: true });
+
+  const packageJson = readPackageJson(join(sourceDir, "package.json"));
+  packageJson.version = options.version;
+  packageJson.private = false;
+  writeJson(join(outDir, "package.json"), packageJson);
+
+  const sourceBinary = join(sourceDir, nativePackage.binaryPath);
+  const outBinary = join(outDir, nativePackage.binaryPath);
+  const binaryCopied = existsSync(sourceBinary);
+  if (binaryCopied) {
+    mkdirSync(dirname(outBinary), { recursive: true });
+    copyFileSync(sourceBinary, outBinary);
+  }
+
+  return { binaryCopied, packageJson };
+}
+
+function validateRootPackageJson(packageJson: PackageJson): void {
+  const optionalDependencies = packageJson.optionalDependencies ?? {};
+  for (const nativePackage of nativePackages()) {
+    if (optionalDependencies[nativePackage.packageName] !== options.version) {
+      fail(
+        `Root optional dependency ${nativePackage.packageName} is not pinned to ${options.version}`
+      );
+    }
+  }
+}
+
+function validateNativePackage(packageJson: PackageJson): void {
+  if (packageJson.version !== options.version) {
+    fail(
+      `${packageJson.name} version is ${packageJson.version}, expected ${options.version}`
+    );
+  }
+  if (packageJson.private !== false) {
+    fail(`${packageJson.name} private must be false in release prep output`);
+  }
+}
+
+function readPackageJson(path: string): 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 {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function parseArgs(): Options {
+  const args = process.argv.slice(2);
+  const version = valueAfter(args, "--version");
+  if (!version) {
+    fail(
+      "Usage: bun tools/prepare-native-release.ts --version <version> [--out <dir>] [--require-binaries] [--keep]"
+    );
+  }
+
+  return {
+    version,
+    outDir: resolve(
+      valueAfter(args, "--out") ?? mkdtempSync(join(tmpdir(), "klint-native-release-"))
+    ),
+    requireBinaries: args.includes("--require-binaries"),
+    keep: args.includes("--keep"),
+  };
+}
+
+function valueAfter(args: string[], name: string): string | undefined {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+function fail(message: string): never {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}

package/tools/semantic-release-root-npm.js

@@ -0,0 +1,52 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export async function verifyConditions(_, context) {
+  const cwd = context.cwd ?? process.cwd();
+  const packageJson = readPackageJson(cwd);
+
+  if (!packageJson.name) {
+    throw new Error("Root package.json must have a name before npm publish");
+  }
+}
+
+export async function prepare(_, context) {
+  const cwd = context.cwd ?? process.cwd();
+  const version = context.nextRelease?.version;
+
+  if (!version) {
+    throw new Error("semantic-release did not provide nextRelease.version");
+  }
+
+  const packageJson = readPackageJson(cwd);
+  packageJson.version = version;
+  writePackageJson(cwd, packageJson);
+}
+
+export async function publish(_, context) {
+  const cwd = context.cwd ?? process.cwd();
+
+  if (context.options?.dryRun) {
+    context.logger?.log("Dry run: skipping npm publish");
+    return;
+  }
+
+  const result = spawnSync("npm", ["publish", "--access", "public"], {
+    cwd,
+    encoding: "utf-8",
+    stdio: "inherit",
+  });
+
+  if ((result.status ?? -1) !== 0) {
+    throw new Error(`npm publish failed with exit code ${result.status ?? -1}`);
+  }
+}
+
+function readPackageJson(cwd) {
+  return JSON.parse(readFileSync(join(cwd, "package.json"), "utf-8"));
+}
+
+function writePackageJson(cwd, packageJson) {
+  writeFileSync(join(cwd, "package.json"), `${JSON.stringify(packageJson, null, 2)}\n`);
+}