@cosmicdrift/kumiko-guards 0.339.0 → 0.340.0

package/README.md

@@ -15,6 +15,25 @@ repo's root. `--explain` prints the resolved repo and per-guard scan scope
 without running any guard; `--write-security-baseline` freezes current
 findings into the baseline file.
 
+## Raw-SQL markers
+
+`guard-raw-sql` blocks `.unsafe()` / `asRawClient()` outside `db/queries/*`,
+`bun-db/query.ts` and testing code. A `// kumiko-lint-ignore raw-sql <reason>`
+marker on the call's line or the line above only suppresses while its
+(file, reason) pair is frozen in `.kumiko-raw-sql-baseline.json` at the repo
+root. A new or reworded marker without a baseline entry fails the check, so
+every exception shows up as a baseline diff in review. Without a baseline file
+the guard only warns, so consumers do not break on bump. Prefer a typed
+`bun-db` helper; freeze a deliberate exception with:
+
+```
+bunx kumiko-guards checks --write-baseline --guard=guard-raw-sql
+```
+
+Rewording the reason is a new entry: re-run the command and review the diff.
+A removed marker leaves a stale entry that does not fail; the same command
+drops it.
+
 ## `kumiko-pre-push`
 
 A POSIX-sh pre-push hook, wired by copying the package's `hooks/pre-push`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.339.0",
+  "version": "0.340.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.339.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.340.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/_lib/guard-kit.ts

@@ -428,6 +428,8 @@ export type RepoCheck = {
   readonly name: string;
   readonly hint?: string;
   run(roots: readonly RepoRoot[]): RepoCheckOutcome | Promise<RepoCheckOutcome>;
+  /** Freezes the check's ratchet baseline(s); reachable via `checks --write-baseline --guard=<name>`. */
+  writeBaseline?(roots: readonly RepoRoot[]): void | Promise<void>;
 };
 
 const VACUOUS_MESSAGE =

package/src/_lib/sql-inventory.ts

@@ -6,7 +6,9 @@
  * Escape hatch for a justified raw-SQL call:
  *   // kumiko-lint-ignore raw-sql <reason>
  * on the call's own line or the line directly above. A bare tag with no
- * reason text after it does NOT suppress the finding.
+ * reason text after it does NOT suppress the finding. guard-raw-sql additionally
+ * requires each (file, reason) to be frozen in `.kumiko-raw-sql-baseline.json`;
+ * the hit carries `markerReason`/`markerLine` for that comparison.
  *
  * I/O: Bun.Glob + Bun.file; directoryExists uses node:fs (same as roots.ts).
  */
@@ -30,6 +32,10 @@ export type SqlInventoryHit = {
   readonly allowed: boolean;
   /** True when a `kumiko-lint-ignore raw-sql <reason>` marker suppresses this hit. */
   readonly markerSuppressed: boolean;
+  /** Trimmed reason text of the suppressing marker; set iff markerSuppressed. */
+  readonly markerReason?: string;
+  /** 1-based line of the suppressing marker; set iff markerSuppressed. */
+  readonly markerLine?: number;
   readonly snippet: string;
 };
 
@@ -62,7 +68,6 @@ export const RAW_SQL_ALLOWLIST: ReadonlyArray<RegExp> = [
   /(^|\/)(packages\/[^/]+\/)?src\/bun-db\/query\.ts$/,
   /(^|\/)(packages\/[^/]+\/)?src\/testing\//,
   // ponytail: explicit enumeration — a blanket regex would auto-allow any new .unsafe()
-  /\/bundled-features\/src\/billing-foundation\/db\/queries\/subscription-projection\.ts$/,
   /\/bundled-features\/src\/config\/db\/queries\/resolver\.ts$/,
   /\/bundled-features\/src\/custom-fields\/db\/queries\/field-access\.ts$/,
   /\/bundled-features\/src\/custom-fields\/db\/queries\/projection\.ts$/,
@@ -73,7 +78,6 @@ export const RAW_SQL_ALLOWLIST: ReadonlyArray<RegExp> = [
   /\/bundled-features\/src\/form-draft\/db\/queries\/cleanup\.ts$/,
   /\/bundled-features\/src\/form-draft\/db\/queries\/draft-count\.ts$/,
   /\/bundled-features\/src\/form-draft\/db\/queries\/owned-file-refs\.ts$/,
-  /\/bundled-features\/src\/inbound-mail-foundation\/db\/queries\/inbound-projections\.ts$/,
   /\/bundled-features\/src\/secrets\/db\/queries\/read\.ts$/,
   /\/bundled-features\/src\/sessions\/db\/queries\/cleanup\.ts$/,
   /\/bundled-features\/src\/user\/db\/queries\/stream-tenant-backfill\.ts$/,
@@ -88,7 +92,7 @@ export const RAW_SQL_ALLOWLIST: ReadonlyArray<RegExp> = [
 /** Escape-hatch tag. Must be followed by whitespace + a non-empty reason to suppress. */
 const MARKER_TAG = "kumiko-lint-ignore raw-sql";
 // Marker must appear in a // comment — string literals describing the hatch must not suppress.
-const MARKER_WITH_REASON_RE = /(^|\s)\/\/\s*kumiko-lint-ignore raw-sql\s+\S/;
+const MARKER_WITH_REASON_RE = /(^|\s)\/\/\s*kumiko-lint-ignore raw-sql\s+(\S.*)$/;
 
 const SKIP_PATH_PARTS = ["/node_modules/", "/dist/", "/.kumiko/"] as const;
 
@@ -185,13 +189,18 @@ function scanFileText(relPath: string, text: string, hits: SqlInventoryHit[]): v
     // Documented hatch: marker on the call line or the line directly above.
     // Each marker line suppresses at most one subsequent hit (consumed), so a
     // second `.unsafe()` under the same comment is not silently covered.
-    let suppressed = false;
-    if (MARKER_WITH_REASON_RE.test(line)) {
-      suppressed = true;
-    } else if (i > 0 && MARKER_WITH_REASON_RE.test(lines[i - 1] ?? "")) {
+    let markerReason: string | undefined;
+    let markerLine: number | undefined;
+    const sameLineReason = MARKER_WITH_REASON_RE.exec(line)?.[2];
+    if (sameLineReason !== undefined) {
+      markerReason = sameLineReason.trim();
+      markerLine = i + 1;
+    } else if (i > 0) {
+      const aboveReason = MARKER_WITH_REASON_RE.exec(lines[i - 1] ?? "")?.[2];
       const markerIdx = i - 1;
-      if (!consumedMarkers.has(markerIdx)) {
-        suppressed = true;
+      if (aboveReason !== undefined && !consumedMarkers.has(markerIdx)) {
+        markerReason = aboveReason.trim();
+        markerLine = i;
         consumedMarkers.add(markerIdx);
       }
     }
@@ -211,7 +220,10 @@ function scanFileText(relPath: string, text: string, hits: SqlInventoryHit[]): v
         line: i + 1,
         kind,
         allowed: isRawSqlAllowed(relPath),
-        markerSuppressed: suppressed,
+        markerSuppressed: markerReason !== undefined,
+        ...(markerReason !== undefined && markerLine !== undefined
+          ? { markerReason, markerLine }
+          : {}),
         snippet: stripMarker(trimmed).slice(0, 120),
       });
     }

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.340.0",
+    "type": "improvement",
+    "title": "Raw-sql markers must be listed in a baseline",
+    "detail": "`guard-raw-sql` counts the markers that suppress a blocking hit per file and reason and compares them with `.kumiko-raw-sql-baseline.json` in the repo root. A marker without a baseline entry, or with a changed reason, fails the check. Without a baseline file the guard only warns. `kumiko-guards checks --write-baseline --guard=guard-raw-sql` writes the file.",
+    "migration": "Consumer: `--write-baseline` einmal laufen lassen (`bunx kumiko-guards checks --write-baseline --guard=guard-raw-sql`) und die erzeugte `.kumiko-raw-sql-baseline.json` committen."
+  },
   {
     "version": "0.339.0",
     "type": "fix",

package/src/cli.ts

@@ -29,6 +29,9 @@ function printHelp(): void {
   for (const sub of SUBCOMMANDS) {
     const flags = SUBCOMMAND_FLAGS[sub];
     console.log(`  ${sub}${flags.length > 0 ? ` [${flags.join("|")}]` : ""}`);
+    if (flags.includes("--write-baseline")) {
+      console.log(`    --write-baseline needs --guard=<name> (freezes one guard's baseline)`);
+    }
   }
 }
 

package/src/guard-raw-sql.ts

@@ -9,10 +9,23 @@
  * should otherwise route SQL through `db/queries/*` or typed
  * `bun-db/query` helpers.
  *
- * Plan: kumiko-platform/docs/plans/architecture/intern/sql-queries-consolidation.md
+ * A marker only suppresses while its (file, reason) pair is frozen in
+ * `.kumiko-raw-sql-baseline.json` at the repo root, so every new or reworded
+ * marker shows up as a baseline diff in review. Without a baseline file the
+ * guard only warns (consumers do not break on bump). Freeze with:
+ *   bun packages/guards/src/guard-raw-sql.ts --write-baseline
+ *   (or `kumiko-guards checks --write-baseline --guard=guard-raw-sql`)
  */
 
-import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import {
+  baselineRatchet,
+  type GuardViolation,
+  type RepoCheck,
+  reportResults,
+  runRepoChecks,
+} from "./_lib/guard-kit";
 import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 import {
   BLOCKING_SQL_KINDS,
@@ -29,22 +42,54 @@ export type RawSqlFinding = {
   readonly snippet: string;
 };
 
+const BASELINE_FILE = ".kumiko-raw-sql-baseline.json";
+
+type RootMarkers = {
+  readonly root: RepoRoot;
+  /** `<file>::<reason>` → distinct marker lines (1-based, ascending). */
+  readonly linesByKey: ReadonlyMap<string, readonly number[]>;
+};
+
+function ratchetFor(root: RepoRoot) {
+  return baselineRatchet({
+    file: path.join(root.absPath, BASELINE_FILE),
+    formatVersion: 1,
+    unit: "raw-sql marker(s)",
+  });
+}
+
+function countsOf(markers: RootMarkers): Record<string, number> {
+  return Object.fromEntries([...markers.linesByKey].map(([key, lines]) => [key, lines.length]));
+}
+
 async function scanAllRepos(roots: readonly RepoRoot[]): Promise<{
   readonly findings: RawSqlFinding[];
+  readonly markers: RootMarkers[];
   readonly scannedFiles: number;
 }> {
   const findings: RawSqlFinding[] = [];
+  const markers: RootMarkers[] = [];
   let scannedFiles = 0;
 
   for (const root of roots) {
     const report = await scanRepo(root.absPath, sqlScanDirsFor(root));
     scannedFiles += report.scannedFiles;
+    const markerLines = new Map<string, Set<number>>();
 
     for (const hit of report.hits) {
       if (hit.allowed) continue;
-      if (hit.markerSuppressed) continue;
       if (hit.file.includes("/__tests__/")) continue;
       if (!(BLOCKING_SQL_KINDS as readonly string[]).includes(hit.kind)) continue;
+      if (hit.markerSuppressed) {
+        // One line like `asRawClient(db).unsafe(` yields two hits for one marker.
+        if (hit.markerReason !== undefined && hit.markerLine !== undefined) {
+          const key = `${hit.file}::${hit.markerReason}`;
+          const lines = markerLines.get(key) ?? new Set<number>();
+          lines.add(hit.markerLine);
+          markerLines.set(key, lines);
+        }
+        continue;
+      }
       findings.push({
         repo: root.name,
         file: hit.file,
@@ -53,9 +98,16 @@ async function scanAllRepos(roots: readonly RepoRoot[]): Promise<{
         snippet: hit.snippet,
       });
     }
+
+    markers.push({
+      root,
+      linesByKey: new Map(
+        [...markerLines].map(([key, lines]) => [key, [...lines].sort((x, y) => x - y)]),
+      ),
+    });
   }
 
-  return { findings, scannedFiles };
+  return { findings, markers, scannedFiles };
 }
 
 export async function collectRawSqlFindings(
@@ -64,11 +116,19 @@ export async function collectRawSqlFindings(
   return (await scanAllRepos(roots)).findings;
 }
 
+const MARKER_REMEDIATION =
+  "New or reworded raw-sql marker. Use a typed bun-db helper (selectMany, selectInnerJoin, " +
+  "insertOnConflictDoNothing, upsertOnConflict, aggregateWhere, where jsonText …) if one fits; " +
+  "otherwise freeze the exception with `kumiko-guards checks --write-baseline --guard=guard-raw-sql` " +
+  "so the baseline diff shows up in review.";
+
 export const check: RepoCheck = {
   name: "guard-raw-sql",
   hint:
     "Rule: runtime SQL only in db/queries/*, bun-db/query.ts, testing/*, or with " +
-    "// kumiko-lint-ignore raw-sql <reason> on the line or the line above.",
+    "// kumiko-lint-ignore raw-sql <reason> on the line or the line above — and that " +
+    "(file, reason) must be frozen in .kumiko-raw-sql-baseline.json " +
+    "(`kumiko-guards checks --write-baseline --guard=guard-raw-sql`).",
   async run(roots) {
     // Only the deliberate exclusion is skipped; a repo whose declared source roots
     // are all missing stays in the scan so 0 files surfaces as vacuous.
@@ -76,20 +136,41 @@ export const check: RepoCheck = {
     if (applicableRoots.length === 0) {
       return { violations: [], matchedFiles: 0, notApplicable: true };
     }
-    const { findings, scannedFiles } = await scanAllRepos(applicableRoots);
+    const { findings, markers, scannedFiles } = await scanAllRepos(applicableRoots);
+    // A root without markers and without a baseline has nothing to freeze, so it
+    // skips the ratchet's "no baseline found" warning instead of nagging every consumer.
+    const markerViolations: GuardViolation[] = markers
+      .filter((m) => m.linesByKey.size > 0 || existsSync(path.join(m.root.absPath, BASELINE_FILE)))
+      .flatMap((m) =>
+        ratchetFor(m.root).check(countsOf(m), MARKER_REMEDIATION, {
+          resolveLine: (key) => m.linesByKey.get(key)?.[0] ?? 1,
+        }),
+      );
     return {
-      violations: findings.map((f) => ({
-        file: f.file,
-        line: f.line,
-        message: `[${f.kind}] ${f.snippet}`,
-      })),
+      violations: [
+        ...findings.map((f) => ({
+          file: f.file,
+          line: f.line,
+          message: `[${f.kind}] ${f.snippet}`,
+        })),
+        ...markerViolations,
+      ],
       matchedFiles: scannedFiles,
       notApplicable: false,
     };
   },
+  async writeBaseline(roots) {
+    const applicableRoots = roots.filter((r) => !isSqlScanExcluded(r));
+    const { markers } = await scanAllRepos(applicableRoots);
+    for (const m of markers) ratchetFor(m.root).write(countsOf(m));
+  },
 };
 
 if (import.meta.main) {
+  if (process.argv.slice(2).includes("--write-baseline")) {
+    await check.writeBaseline?.(resolveRepoRoots());
+    process.exit(0);
+  }
   const failed = reportResults(await runRepoChecks([check]));
   process.exit(failed > 0 ? 1 : 0);
 }

package/src/run-repo-checks.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { cliFlagsError, printGuardKitBanner, reportResults, runRepoChecks } from "./_lib/guard-kit";
+import { type RepoRoot, resolveRepoRoots } from "./_lib/roots";
 import { check as realProviderIsolation } from "./check-real-provider-isolation";
 // Standalone-`main()` guards ported as RepoCheck — run in-process, no
 // per-guard subprocess/project.
@@ -30,22 +31,55 @@ export const REPO_CHECKS = [
   singleRuntimeInstance,
 ];
 
-// No flags today — the array stays so an unknown flag still fails loud
-// instead of silently doing nothing, and so a future flag has one place to land.
-export const REPO_CHECK_FLAGS: readonly string[] = [];
+export const REPO_CHECK_FLAGS: readonly string[] = ["--write-baseline"];
+
+const GUARD_NAME_PREFIX = "--guard=";
 
 // Shared by the direct `bun run-repo-checks.ts` invocation below and by the
 // `checks` subcommand in cli.ts.
-export async function runRepoChecksCli(argv: readonly string[]): Promise<number> {
-  const flagsError = cliFlagsError("checks", argv, REPO_CHECK_FLAGS);
+export async function runRepoChecksCli(
+  argv: readonly string[],
+  roots?: readonly RepoRoot[],
+): Promise<number> {
+  const guardNameArg = argv.find((arg) => arg.startsWith(GUARD_NAME_PREFIX));
+  const flags = guardNameArg === undefined ? argv : argv.filter((arg) => arg !== guardNameArg);
+  const flagsError = cliFlagsError("checks", flags, REPO_CHECK_FLAGS);
   if (flagsError !== undefined) {
     console.error(flagsError);
     return 1;
   }
+  const writeBaseline = flags.includes("--write-baseline");
+  if (guardNameArg !== undefined && !writeBaseline) {
+    console.error("--guard=<name> is only valid with --write-baseline");
+    return 1;
+  }
+  if (writeBaseline) {
+    // Baselines freeze deliberately, one check at a time — never a refreeze-everything.
+    if (guardNameArg === undefined) {
+      console.error(
+        "--write-baseline needs --guard=<name>. Freeze a baseline only deliberately, one check at a time.",
+      );
+      return 1;
+    }
+    const checkName = guardNameArg.slice(GUARD_NAME_PREFIX.length);
+    const target = REPO_CHECKS.find((c) => c.name === checkName);
+    if (target === undefined) {
+      console.error(
+        `Unknown check "${checkName}". Known check names: ${REPO_CHECKS.map((c) => c.name).join(", ")}`,
+      );
+      return 1;
+    }
+    if (target.writeBaseline === undefined) {
+      console.error(`Check "${checkName}" has no ratchet baseline to write.`);
+      return 1;
+    }
+    await target.writeBaseline(roots ?? resolveRepoRoots());
+    return 0;
+  }
   // No shared ts-morph Project here — RepoCheck.run() does its own file
   // walk per check, so the banner omits the "Project: N files" line.
   printGuardKitBanner(REPO_CHECKS.length);
-  return reportResults(await runRepoChecks(REPO_CHECKS));
+  return reportResults(await runRepoChecks(REPO_CHECKS, roots));
 }
 
 if (import.meta.main) {