@cosmicdrift/kumiko-guards 0.345.0 → 0.347.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.345.0",
+  "version": "0.347.0",
   "description": "AST-based security guards for Kumiko repos: direct-fs/fetch, tenant escalation, admin-API, escape hatches and related checks, run over a shared ts-morph project.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -28,7 +28,7 @@
     "kumiko-pre-push": "./src/pre-push.sh"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-repo-manifest": "0.345.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.347.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.347.0",
+    "type": "improvement",
+    "title": "New kumiko-guards comment-lang subcommand replaces the kumiko-guard-comment-lang bin",
+    "detail": "`kumiko-guards comment-lang` runs the comment-language ratchet\nThe subcommand takes `--touched --base=<ref>`, `--list`, `--write-baseline` and `--no-baseline`. The pre-push hook calls it instead of the separate `kumiko-guard-comment-lang` bin."
+  },
   {
     "version": "0.341.0",
     "type": "breaking",

package/src/cli.ts

@@ -5,17 +5,19 @@
 // flags, which each runner's own *Cli function validates and applies so this
 // bin and the direct `bun run-*.ts` invocation can never drift apart.
 import { buildGuardKitInventory, cliFlagsError } from "./_lib/guard-kit";
+import { COMMENT_LANG_FLAGS, runCommentLangCli } from "./guard-comment-lang";
 import { GUARD_FLAGS, GUARDS, runGuardsCli } from "./run-guards";
 import { REPO_CHECK_FLAGS, REPO_CHECKS, runRepoChecksCli } from "./run-repo-checks";
 import { runUiGuardsCli, UI_GUARD_FLAGS, UI_GUARDS } from "./run-ui-guards";
 
-const SUBCOMMANDS = ["guards", "ui", "checks", "list"] as const;
+const SUBCOMMANDS = ["guards", "ui", "checks", "comment-lang", "list"] as const;
 type Subcommand = (typeof SUBCOMMANDS)[number];
 
 const SUBCOMMAND_FLAGS: Record<Subcommand, readonly string[]> = {
   guards: GUARD_FLAGS,
   ui: UI_GUARD_FLAGS,
   checks: REPO_CHECK_FLAGS,
+  "comment-lang": [...COMMENT_LANG_FLAGS, "--base=<ref>"],
   list: [],
 };
 
@@ -24,7 +26,7 @@ function isSubcommand(value: string): value is Subcommand {
 }
 
 function printHelp(): void {
-  console.log("Usage: kumiko-guards [guards|ui|checks|list] [flags]");
+  console.log("Usage: kumiko-guards [guards|ui|checks|comment-lang|list] [flags]");
   console.log();
   for (const sub of SUBCOMMANDS) {
     const flags = SUBCOMMAND_FLAGS[sub];
@@ -71,6 +73,11 @@ async function main(): Promise<void> {
     return;
   }
 
+  // Not part of the no-subcommand run: it needs a baseline or a git base ref.
+  if (subcommand === "comment-lang") {
+    process.exit(runCommentLangCli(flags));
+  }
+
   let failed = 0;
   if (subcommand === undefined || subcommand === "guards") {
     failed += runGuardsCli(subcommand === "guards" ? flags : []);

package/src/guard-comment-lang.ts

@@ -0,0 +1,392 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+import { ts } from "ts-morph";
+import { gitEnv } from "./_lib/git-env";
+import { cliFlagsError, isLocalFinding } from "./_lib/guard-kit";
+import { resolveRepoRoots } from "./_lib/roots";
+import { type ScanSpec, scanFiles } from "./_lib/scan-scope";
+
+// Comment-language ratchet: no new German comments in product code. No NLP —
+// German markers are common function words or umlaut characters in the comment text.
+// Baseline mode compares per-file counts against a frozen file (more than the
+// baseline fails, fewer is allowed but does not rewrite it); `--touched` fails
+// on any German comment that overlaps a line added since `--base`.
+
+export const COMMENT_LANG_FLAGS: readonly string[] = [
+  "--touched",
+  "--list",
+  "--write-baseline",
+  "--no-baseline",
+];
+
+const BASE_FLAG_PREFIX = "--base=";
+const BASELINE_FILE = ".kumiko-comment-lang-baseline.json";
+const BASELINE_FORMAT_VERSION = 1;
+const LIST_LIMIT = 200;
+const IGNORE_TAG = "kumiko-lint-ignore comment-lang";
+
+const SCAN: ScanSpec = {
+  scope: "source",
+  extensions: ["ts", "tsx"],
+  frameworkWithin: ["packages/*/src/**"],
+};
+
+const EXCLUDE = /(\.d\.(ts|tsx)$|\/dist\/)/;
+
+const DE_MARKER_RE =
+  /\b(und|oder|für|wenn|nicht|dann|auch|noch|wird|sind|mit|zum|zur|bei|nach|ohne|über|kein|eine|einen|dieser|diese)\b/i;
+const UMLAUT_RE = /[äöüÄÖÜß]/;
+
+export function isGermanComment(text: string): boolean {
+  return DE_MARKER_RE.test(text) || UMLAUT_RE.test(text);
+}
+
+export type Site = {
+  readonly file: string;
+  readonly line: number;
+  /** Last line of a multi-line comment: touched mode must catch a German sentence added mid-comment, not only on the opening line. */
+  readonly endLine: number;
+  readonly snippet: string;
+};
+
+// Template substitutions can nest braces (object literals, arrow bodies, other
+// templates). The raw scanner tokenizes a `}` as a plain CloseBraceToken and
+// never resumes template mode, so reScanTemplateToken() must run once brace
+// depth returns to the level the substitution opened at.
+export function scanGermanComments(fullText: string, file: string): Site[] {
+  const sites: Site[] = [];
+  const scanner = ts.createScanner(
+    ts.ScriptTarget.Latest,
+    /* skipTrivia */ false,
+    ts.LanguageVariant.Standard,
+    fullText,
+  );
+
+  const templateBraceDepths: number[] = [];
+  let braceDepth = 0;
+
+  let kind = scanner.scan();
+  while (kind !== ts.SyntaxKind.EndOfFileToken) {
+    switch (kind) {
+      case ts.SyntaxKind.SingleLineCommentTrivia:
+      case ts.SyntaxKind.MultiLineCommentTrivia: {
+        const text = scanner.getTokenText();
+        if (!text.includes(IGNORE_TAG) && isGermanComment(text)) {
+          const line = fullText.slice(0, scanner.getTokenStart()).split("\n").length;
+          sites.push({
+            file,
+            line,
+            endLine: line + (text.match(/\n/g)?.length ?? 0),
+            snippet: text.length > 80 ? `${text.slice(0, 77)}...` : text,
+          });
+        }
+        break;
+      }
+      case ts.SyntaxKind.SlashToken:
+      case ts.SyntaxKind.SlashEqualsToken: {
+        // The raw scanner always yields SlashToken for `/`; without the rescan a
+        // regex body like /\{/ would shift braceDepth and end a template early.
+        const reScanned = scanner.reScanSlashToken();
+        if (reScanned === ts.SyntaxKind.RegularExpressionLiteral) kind = reScanned;
+        break;
+      }
+      case ts.SyntaxKind.TemplateHead:
+      case ts.SyntaxKind.TemplateMiddle:
+        templateBraceDepths.push(braceDepth);
+        break;
+      case ts.SyntaxKind.OpenBraceToken:
+        braceDepth++;
+        break;
+      case ts.SyntaxKind.CloseBraceToken:
+        if (
+          templateBraceDepths.length > 0 &&
+          braceDepth === templateBraceDepths[templateBraceDepths.length - 1]
+        ) {
+          templateBraceDepths.pop();
+          kind = scanner.reScanTemplateToken(false);
+          continue;
+        }
+        if (braceDepth > 0) braceDepth--;
+        break;
+      default:
+        break;
+    }
+    kind = scanner.scan();
+  }
+  return sites;
+}
+
+// `--unified=0` hunks carry only changed lines, so `+newStart,newLines` alone
+// is the added range. `newLines` omitted means 1; `,0` is a pure deletion.
+export function parseAddedLineRanges(diffText: string): Set<number> {
+  const added = new Set<number>();
+  const hunkHeaderRe = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
+  for (const line of diffText.split("\n")) {
+    const match = hunkHeaderRe.exec(line);
+    if (!match) continue;
+    const newStart = Number(match[1]);
+    const newLines = match[2] !== undefined ? Number(match[2]) : 1;
+    for (let i = 0; i < newLines; i++) added.add(newStart + i);
+  }
+  return added;
+}
+
+export function sitesTouchedByAddedLines(
+  sites: readonly Site[],
+  addedLines: ReadonlySet<number>,
+): Site[] {
+  return sites.filter((site) => {
+    for (let line = site.line; line <= site.endLine; line++) {
+      if (addedLines.has(line)) return true;
+    }
+    return false;
+  });
+}
+
+type GitResult = { readonly exitCode: number; readonly stdout: string; readonly stderr: string };
+
+function runGit(args: readonly string[], cwd: string): GitResult {
+  const proc = Bun.spawnSync(["git", ...args], {
+    cwd,
+    env: gitEnv(),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return {
+    exitCode: proc.exitCode ?? 1,
+    stdout: proc.stdout.toString(),
+    stderr: proc.stderr.toString(),
+  };
+}
+
+class CommentLangFailure extends Error {}
+
+function gitOrFail(args: readonly string[], cwd: string, message: string): string {
+  const result = runGit(args, cwd);
+  if (result.exitCode !== 0)
+    throw new CommentLangFailure(`${message}\n    ${result.stderr.trim()}`);
+  return result.stdout;
+}
+
+const REWRITE_HINT = `Translate new German comments to English (why, not what), or if deliberate:\n    // ${IGNORE_TAG} <reason>`;
+
+function runTouchedMode(
+  all: readonly Site[],
+  argv: readonly string[],
+  root: string,
+  repoLocalScannedFiles: number,
+): number {
+  const baseArg = argv.find((arg) => arg.startsWith(BASE_FLAG_PREFIX));
+  const baseRef = baseArg ? baseArg.slice(BASE_FLAG_PREFIX.length) : "origin/main";
+  if (baseRef.startsWith("-")) {
+    throw new CommentLangFailure(
+      `--base must not start with "-" (${baseRef}): it would be read as a git option, not a ref.`,
+    );
+  }
+
+  // No repo-local file scanned at all must not read as clean (vacuous pass).
+  if (repoLocalScannedFiles === 0) {
+    console.log("  Touched mode: 0 repo-local files scanned — not applicable, no failure.");
+    return 0;
+  }
+
+  const gitToplevel = gitOrFail(
+    ["rev-parse", "--show-toplevel"],
+    root,
+    "Touched mode: no git repository found.",
+  ).trim();
+  const mergeBase = gitOrFail(
+    ["merge-base", baseRef, "HEAD"],
+    gitToplevel,
+    `Touched mode: git merge-base ${baseRef} HEAD failed — is ${baseRef} known locally? On shallow checkouts fetch the full history or the ref.`,
+  ).trim();
+  // -z: NUL-terminated and unquoted, so non-ASCII paths still match the lookup below.
+  const touchedFiles = gitOrFail(
+    ["diff", "--name-only", "-z", "--diff-filter=ACMR", mergeBase],
+    gitToplevel,
+    "Touched mode: git diff --name-only failed.",
+  )
+    .split("\0")
+    .filter(Boolean);
+
+  // Sites are keyed relative to root, git output relative to the toplevel;
+  // a silent mismatch would read as "no violations".
+  const sitesByGitFile = new Map<string, Site[]>();
+  for (const site of all.filter(isLocalFinding)) {
+    const gitRelPath = path.relative(gitToplevel, path.resolve(root, site.file));
+    sitesByGitFile.set(gitRelPath, [...(sitesByGitFile.get(gitRelPath) ?? []), site]);
+  }
+
+  const violations: Array<{ file: string; sites: Site[] }> = [];
+  for (const file of touchedFiles) {
+    const candidates = sitesByGitFile.get(file);
+    if (!candidates || candidates.length === 0) continue;
+    // --literal-pathspecs: filenames with glob magic must match themselves.
+    const addedLines = parseAddedLineRanges(
+      gitOrFail(
+        ["--literal-pathspecs", "diff", "--unified=0", mergeBase, "--", file],
+        gitToplevel,
+        `Touched mode: git diff --unified=0 failed for ${file}.`,
+      ),
+    );
+    const touchedSites = sitesTouchedByAddedLines(candidates, addedLines);
+    if (touchedSites.length > 0) violations.push({ file, sites: touchedSites });
+  }
+
+  if (violations.length === 0) {
+    console.log(
+      `  ✓ Touched mode: no new German comments in ${touchedFiles.length} changed file(s) since ${baseRef}.`,
+    );
+    return 0;
+  }
+  console.log(
+    `\n  TOUCHED-MODE REGRESSION: ${violations.length} changed file(s) with new German comments (since ${baseRef}):`,
+  );
+  for (const violation of violations) {
+    console.log(`    ${violation.file}`);
+    for (const site of violation.sites) console.log(`      :${site.line}  ${site.snippet}`);
+  }
+  console.log(`\n  ${REWRITE_HINT}`);
+  return 1;
+}
+
+type Baseline = {
+  readonly format: number;
+  readonly generated: string;
+  readonly total: number;
+  readonly perFile: Record<string, number>;
+};
+
+function sumCounts(counts: Readonly<Record<string, number>>): number {
+  return Object.values(counts).reduce((total, count) => total + count, 0);
+}
+
+function runBaselineMode(all: readonly Site[], argv: readonly string[], root: string): number {
+  const baselinePath = path.join(root, BASELINE_FILE);
+  const countByFile: Record<string, number> = {};
+  for (const site of all.filter(isLocalFinding)) {
+    countByFile[site.file] = (countByFile[site.file] ?? 0) + 1;
+  }
+  const currentTotal = sumCounts(countByFile);
+
+  if (argv.includes("--write-baseline")) {
+    const payload: Baseline = {
+      format: BASELINE_FORMAT_VERSION,
+      generated: new Date().toISOString().slice(0, 10),
+      total: currentTotal,
+      perFile: Object.fromEntries(
+        Object.entries(countByFile).sort(([a], [b]) => a.localeCompare(b)),
+      ),
+    };
+    writeFileSync(baselinePath, `${JSON.stringify(payload, null, 2)}\n`);
+    console.log(`  Baseline written: ${baselinePath} (total ${currentTotal})`);
+    return 0;
+  }
+  if (argv.includes("--no-baseline")) {
+    console.log("  Baseline comparison skipped (--no-baseline).");
+    return 0;
+  }
+  if (!existsSync(baselinePath)) {
+    console.log("  No baseline found. Freeze one first with `--write-baseline`.");
+    return 1;
+  }
+
+  const rawBaseline: Partial<Baseline> = JSON.parse(readFileSync(baselinePath, "utf-8"));
+  if (rawBaseline.format !== BASELINE_FORMAT_VERSION || rawBaseline.perFile === undefined) {
+    console.log(
+      `  Baseline format drift: expected format=${BASELINE_FORMAT_VERSION}, got format=${rawBaseline.format ?? "<missing>"}.`,
+    );
+    console.log("  Rewrite it once with: kumiko-guards comment-lang --write-baseline");
+    return 1;
+  }
+  const baselinePerFile = rawBaseline.perFile;
+
+  const regressions: Array<{ file: string; baseline: number; current: number }> = [];
+  let reduced = 0;
+  for (const file of new Set([...Object.keys(countByFile), ...Object.keys(baselinePerFile)])) {
+    const expected = baselinePerFile[file] ?? 0;
+    const current = countByFile[file] ?? 0;
+    if (current > expected) regressions.push({ file, baseline: expected, current });
+    else if (current < expected) reduced += expected - current;
+  }
+
+  if (regressions.length > 0) {
+    console.log(
+      `\n  REGRESSION: ${regressions.length} file(s) have more German comments than the baseline:`,
+    );
+    for (const regression of regressions) {
+      console.log(
+        `    ${regression.file}  baseline=${regression.baseline} current=${regression.current} (+${regression.current - regression.baseline})`,
+      );
+      for (const site of all.filter((candidate) => candidate.file === regression.file)) {
+        console.log(`      :${site.line}  ${site.snippet}`);
+      }
+    }
+    console.log(`\n  ${REWRITE_HINT}`);
+    return 1;
+  }
+
+  console.log(`  ✓ Baseline (${rawBaseline.total}) — current ${currentTotal}`);
+  if (reduced > 0) {
+    console.log(
+      `  ✓ ${reduced} German comment(s) removed since the baseline. Consider \`--write-baseline\`.`,
+    );
+  }
+  return 0;
+}
+
+// `cwd` resolves the repo to scan and the baseline path; KUMIKO_PUSH_REPO_ROOT
+// overrides it because the pre-push hook cds into the parent workspace first.
+export function runCommentLangCli(
+  argv: readonly string[],
+  cwd: string = process.cwd(),
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): number {
+  const knownFlags = argv.filter((arg) => !arg.startsWith(BASE_FLAG_PREFIX));
+  const flagsError = cliFlagsError("comment-lang", knownFlags, COMMENT_LANG_FLAGS);
+  if (flagsError !== undefined) {
+    console.error(flagsError);
+    return 1;
+  }
+
+  const pushRoot = env["KUMIKO_PUSH_REPO_ROOT"];
+  const root = pushRoot && existsSync(pushRoot) ? pushRoot : cwd;
+
+  try {
+    const all: Site[] = [];
+    let scanned = 0;
+    let repoLocalScanned = 0;
+    for (const absPath of scanFiles(SCAN, resolveRepoRoots(root))) {
+      if (EXCLUDE.test(absPath)) continue;
+      scanned++;
+      const file = path.relative(root, absPath);
+      if (isLocalFinding({ file })) repoLocalScanned++;
+      all.push(...scanGermanComments(readFileSync(absPath, "utf-8"), file));
+    }
+
+    // Zero scanned files must not read as a clean pass (misresolved root, empty scope).
+    if (scanned === 0) {
+      throw new CommentLangFailure("Scanned 0 files — repo root or scan scope did not resolve.");
+    }
+
+    console.log(
+      `Comment-Language Audit: ${scanned} files checked, ${all.length} German comment(s) found.`,
+    );
+
+    if (argv.includes("--touched")) return runTouchedMode(all, argv, root, repoLocalScanned);
+    if (argv.includes("--list")) {
+      for (const site of all.slice(0, LIST_LIMIT)) {
+        console.log(`  ${site.file}:${site.line}  ${site.snippet}`);
+      }
+      if (all.length > LIST_LIMIT) console.log(`  ... (${all.length - LIST_LIMIT} more)`);
+      return 0;
+    }
+    return runBaselineMode(all, argv, root);
+  } catch (error) {
+    if (error instanceof CommentLangFailure) {
+      console.log(`  ${error.message}`);
+      return 1;
+    }
+    throw error;
+  }
+}

package/src/pre-push.sh

@@ -7,7 +7,7 @@
 #   2. Else if running inside a worktree under the parent workspace (no
 #      check-wt.sh), run this worktree's own package.json scripts
 #      (typecheck, lint, test, test:dom) plus the consumer-CI guards
-#      (kumiko-guards guards/checks, kumiko-guard-comment-lang) directly —
+#      (kumiko-guards guards/checks/comment-lang) directly —
 #      the parent's `bun check` would otherwise check the main checkout
 #      instead of the worktree.
 #   3. Else if running inside the cosmicdriftgamestudio Parent-Workspace,
@@ -175,7 +175,7 @@ if [ "$(git rev-parse --path-format=absolute --git-dir)" != "$GIT_COMMON_DIR" ]
   done
   run_guard_bin guards kumiko-guards guards
   run_guard_bin checks kumiko-guards checks
-  run_guard_bin comment-lang kumiko-guard-comment-lang --touched --base=origin/main
+  run_guard_bin comment-lang kumiko-guards comment-lang --touched --base=origin/main
   if [ -n "$FAILED" ]; then
     echo "[pre-push] worktree check failed:$FAILED" >&2
     exit 1