@cosmicdrift/kumiko-guards 0.356.0 → 0.358.0

package/src/_lib/security-baseline.ts

@@ -56,22 +56,42 @@ function isFindingsShape(value: unknown): value is SecurityBaseline["findings"]
   });
 }
 
+type BaselineCore = Pick<SecurityBaseline, "format" | "repo" | "generated" | "total" | "findings">;
+
+function hasBaselineCore(raw: object): raw is BaselineCore {
+  return (
+    "format" in raw &&
+    raw.format === SECURITY_BASELINE_FORMAT &&
+    "repo" in raw &&
+    typeof raw.repo === "string" &&
+    "generated" in raw &&
+    typeof raw.generated === "string" &&
+    "total" in raw &&
+    typeof raw.total === "number" &&
+    "findings" in raw &&
+    isFindingsShape(raw.findings)
+  );
+}
+
+// {} is allowed (guard has no current findings); any entry means it isn't done migrating yet.
+function isValidHardFail(
+  hardFail: unknown,
+  findings: SecurityBaseline["findings"],
+): hardFail is readonly string[] {
+  if (!isStringArrayNoDuplicates(hardFail)) return false;
+  return hardFail.every((guardName) => {
+    const perFile = findings[guardName];
+    return !(perFile && Object.keys(perFile).length > 0);
+  });
+}
+
 export function parseSecurityBaseline(raw: unknown): SecurityBaseline | undefined {
   if (typeof raw !== "object" || raw === null) return undefined;
-  if (!("format" in raw) || raw.format !== SECURITY_BASELINE_FORMAT) return undefined;
-  if (!("repo" in raw) || typeof raw.repo !== "string") return undefined;
-  if (!("generated" in raw) || typeof raw.generated !== "string") return undefined;
-  if (!("total" in raw) || typeof raw.total !== "number") return undefined;
-  if (!("findings" in raw) || !isFindingsShape(raw.findings)) return undefined;
+  if (!hasBaselineCore(raw)) return undefined;
 
   let hardFail: readonly string[] | undefined;
   if ("hardFail" in raw && raw.hardFail !== undefined) {
-    if (!isStringArrayNoDuplicates(raw.hardFail)) return undefined;
-    for (const guardName of raw.hardFail) {
-      const perFile = raw.findings[guardName];
-      // {} is allowed (guard has no current findings); any entry means it isn't done migrating yet.
-      if (perFile && Object.keys(perFile).length > 0) return undefined;
-    }
+    if (!isValidHardFail(raw.hardFail, raw.findings)) return undefined;
     hardFail = raw.hardFail;
   }
 
@@ -107,7 +127,7 @@ export function loadSecurityBaseline(repo: string, repoDir: string): SecurityBas
   }
   const parsed = parseSecurityBaseline(raw);
   if (!parsed) {
-    return { kind: "invalid", file, reason: "unexpected baseline format (format/repo/findings)" };
+    return { kind: "invalid", file, reason: "unexpected_baseline_shape" };
   }
   if (parsed.repo !== repo) {
     return {
@@ -133,36 +153,36 @@ export function locateFinding(
   return { repo: root.name, relPath: relative(root.absPath, abs).split(sep).join("/") };
 }
 
-export function applySecurityBaseline(args: {
-  readonly guardName: string;
-  readonly violations: readonly GuardViolation[];
-  readonly roots: readonly { readonly name: string; readonly absPath: string }[];
-  readonly cwd: string;
-  readonly load: (repo: string) => SecurityBaselineLoad;
-  /** Also fail on baseline headroom (current < baseline) across every root, not just repos with current findings. */
-  readonly strict?: boolean;
-}): { readonly blocking: GuardViolation[]; readonly frozen: number; readonly reduced: number } {
-  const { guardName, violations, roots, cwd, load, strict } = args;
+type RepoRootList = readonly { readonly name: string; readonly absPath: string }[];
 
-  type Located = {
-    readonly relPath: string;
-    readonly index: number;
-    readonly violation: GuardViolation;
-  };
-  const byRepo = new Map<string, Map<string, Located[]>>();
-  // (sortKey, violation) so the final blocking list preserves the original
-  // violation order even after synthetic baseline-file entries are spliced in.
-  const blockingEntries: Array<[number, GuardViolation]> = [];
+type LocatedViolation = {
+  readonly relPath: string;
+  readonly index: number;
+  readonly violation: GuardViolation;
+};
+
+type FindingsByRepo = Map<string, Map<string, LocatedViolation[]>>;
+
+// (sortKey, violation) so the final blocking list preserves the original
+// violation order even after synthetic baseline-file entries are spliced in.
+type BlockingEntry = [number, GuardViolation];
 
-  violations.forEach((violation, index) => {
+function groupFindingsByRepo(
+  violations: readonly GuardViolation[],
+  roots: RepoRootList,
+  cwd: string,
+  blockingEntries: BlockingEntry[],
+): FindingsByRepo {
+  const byRepo: FindingsByRepo = new Map();
+  for (const [index, violation] of violations.entries()) {
     if (violation.neverFrozen) {
       blockingEntries.push([index, violation]);
-      return;
+      continue;
     }
     const located = locateFinding(violation.file, roots, cwd);
     if (!located) {
       blockingEntries.push([index, violation]);
-      return;
+      continue;
     }
     let perRepo = byRepo.get(located.repo);
     if (!perRepo) {
@@ -172,110 +192,167 @@ export function applySecurityBaseline(args: {
     const bucket = perRepo.get(located.relPath) ?? [];
     bucket.push({ relPath: located.relPath, index, violation });
     perRepo.set(located.relPath, bucket);
-  });
+  }
+  return byRepo;
+}
 
-  const loadCache = new Map<string, SecurityBaselineLoad>();
-  const loadOnce = (repo: string): SecurityBaselineLoad => {
-    const cached = loadCache.get(repo);
-    if (cached) return cached;
-    const result = load(repo);
-    loadCache.set(repo, result);
-    return result;
+function invalidBaselineViolation(
+  baseline: Extract<SecurityBaselineLoad, { kind: "invalid" }>,
+): GuardViolation {
+  return {
+    file: baseline.file,
+    line: 1,
+    message: `Security baseline unreadable or invalid: ${baseline.reason}. Fix the file; a broken baseline must not release any findings.`,
   };
+}
 
-  let frozen = 0;
-  let reduced = 0;
+function countsPerPath(
+  byPath: ReadonlyMap<string, readonly LocatedViolation[]>,
+): Record<string, number> {
+  const current: Record<string, number> = {};
+  for (const [relPath, entries] of byPath) current[relPath] = entries.length;
+  return current;
+}
 
-  for (const [repo, byPath] of byRepo) {
-    const baseline = loadOnce(repo);
-    const allEntries = [...byPath.values()].flat();
-    if (baseline.kind === "invalid") {
-      const minIndex = Math.min(...allEntries.map((e) => e.index));
+function applyRepoBaseline(args: {
+  readonly guardName: string;
+  readonly repo: string;
+  readonly byPath: ReadonlyMap<string, readonly LocatedViolation[]>;
+  readonly baseline: SecurityBaselineLoad;
+  readonly blockingEntries: BlockingEntry[];
+}): { readonly frozen: number; readonly reduced: number } {
+  const { guardName, repo, byPath, baseline, blockingEntries } = args;
+  const allEntries = [...byPath.values()].flat();
+  if (baseline.kind === "invalid") {
+    const minIndex = Math.min(...allEntries.map((e) => e.index));
+    blockingEntries.push([minIndex - 0.5, invalidBaselineViolation(baseline)]);
+    for (const e of allEntries) blockingEntries.push([e.index, e.violation]);
+    return { frozen: 0, reduced: 0 };
+  }
+  if (baseline.hardFail.includes(guardName)) {
+    for (const e of allEntries) {
       blockingEntries.push([
-        minIndex - 0.5,
+        e.index,
         {
-          file: baseline.file,
-          line: 1,
-          message: `Security baseline unreadable or invalid: ${baseline.reason}. Fix the file; a broken baseline must not release any findings.`,
+          ...e.violation,
+          message: `${e.violation.message} (security baseline ${repo}: ${guardName} finished migrating — no baseline tolerance)`,
         },
       ]);
-      for (const e of allEntries) blockingEntries.push([e.index, e.violation]);
-      continue;
     }
-    if (baseline.hardFail.includes(guardName)) {
-      for (const e of allEntries) {
+    return { frozen: 0, reduced: 0 };
+  }
+  const baselineForGuard = baseline.findings[guardName] ?? {};
+  const { regressions, reduced } = compareToBaseline(countsPerPath(byPath), baselineForGuard);
+  const regressionByPath = new Map(regressions.map((r) => [r.file, r]));
+  let frozen = 0;
+  for (const [relPath, entries] of byPath) {
+    const regression = regressionByPath.get(relPath);
+    if (regression) {
+      for (const e of entries) {
         blockingEntries.push([
           e.index,
           {
             ...e.violation,
-            message: `${e.violation.message} (security baseline ${repo}: ${guardName} finished migrating — no baseline tolerance)`,
+            message: `${e.violation.message} (security baseline ${repo}: allowed=${regression.baseline}, current=${regression.current})`,
           },
         ]);
       }
+    } else {
+      frozen += entries.length;
+    }
+  }
+  return { frozen, reduced };
+}
+
+// Strict mode also visits repos without current findings, so baseline headroom
+// there fails too. Returns the headroom that counts as reduced.
+function applyStrictHeadroom(args: {
+  readonly guardName: string;
+  readonly roots: RepoRootList;
+  readonly byRepo: FindingsByRepo;
+  readonly loadOnce: (repo: string) => SecurityBaselineLoad;
+  readonly firstSortKey: number;
+  readonly blockingEntries: BlockingEntry[];
+}): number {
+  const { guardName, roots, byRepo, loadOnce, firstSortKey, blockingEntries } = args;
+  let strictIndex = 0;
+  let reduced = 0;
+  for (const root of roots) {
+    const baseline = loadOnce(root.name);
+    const byPath = byRepo.get(root.name);
+    if (baseline.kind === "invalid") {
+      // Repos with current findings already got this entry in the per-repo pass.
+      if (byPath) continue;
+      blockingEntries.push([firstSortKey + strictIndex++, invalidBaselineViolation(baseline)]);
       continue;
     }
-    const current: Record<string, number> = {};
-    for (const [relPath, entries] of byPath) current[relPath] = entries.length;
+    const current = byPath ? countsPerPath(byPath) : {};
     const baselineForGuard = baseline.findings[guardName] ?? {};
-    const { regressions, reduced: repoReduced } = compareToBaseline(current, baselineForGuard);
-    reduced += repoReduced;
-    const regressionByPath = new Map(regressions.map((r) => [r.file, r]));
-    for (const [relPath, entries] of byPath) {
-      const regression = regressionByPath.get(relPath);
-      if (regression) {
-        for (const e of entries) {
-          blockingEntries.push([
-            e.index,
-            {
-              ...e.violation,
-              message: `${e.violation.message} (security baseline ${repo}: allowed=${regression.baseline}, current=${regression.current})`,
-            },
-          ]);
-        }
-      } else {
-        frozen += entries.length;
-      }
+    const { reductions } = compareToBaseline(current, baselineForGuard);
+    if (!byPath) {
+      reduced += reductions.reduce((sum, r) => sum + (r.baseline - r.current), 0);
     }
+    for (const r of reductions) {
+      blockingEntries.push([
+        firstSortKey + strictIndex++,
+        {
+          file: join(root.absPath, r.file),
+          line: 1,
+          message: `Security baseline stale: ${root.name}/${r.file} allows ${r.baseline}, found ${r.current} — run \`--write-security-baseline\` and commit, otherwise the headroom covers new findings.`,
+        },
+      ]);
+    }
+  }
+  return reduced;
+}
+
+export function applySecurityBaseline(args: {
+  readonly guardName: string;
+  readonly violations: readonly GuardViolation[];
+  readonly roots: RepoRootList;
+  readonly cwd: string;
+  readonly load: (repo: string) => SecurityBaselineLoad;
+  /** Also fail on baseline headroom (current < baseline) across every root, not just repos with current findings. */
+  readonly strict?: boolean;
+}): { readonly blocking: GuardViolation[]; readonly frozen: number; readonly reduced: number } {
+  const { guardName, violations, roots, cwd, load, strict } = args;
+
+  const blockingEntries: BlockingEntry[] = [];
+  const byRepo = groupFindingsByRepo(violations, roots, cwd, blockingEntries);
+
+  const loadCache = new Map<string, SecurityBaselineLoad>();
+  const loadOnce = (repo: string): SecurityBaselineLoad => {
+    const cached = loadCache.get(repo);
+    if (cached) return cached;
+    const result = load(repo);
+    loadCache.set(repo, result);
+    return result;
+  };
+
+  let frozen = 0;
+  let reduced = 0;
+
+  for (const [repo, byPath] of byRepo) {
+    const repoResult = applyRepoBaseline({
+      guardName,
+      repo,
+      byPath,
+      baseline: loadOnce(repo),
+      blockingEntries,
+    });
+    frozen += repoResult.frozen;
+    reduced += repoResult.reduced;
   }
 
   if (strict === true) {
-    let strictIndex = 0;
-    for (const root of roots) {
-      const baseline = loadOnce(root.name);
-      const byPath = byRepo.get(root.name);
-      if (baseline.kind === "invalid") {
-        // Repos with current findings already got this entry in the loop above.
-        if (byPath) continue;
-        blockingEntries.push([
-          violations.length + strictIndex++,
-          {
-            file: baseline.file,
-            line: 1,
-            message: `Security baseline unreadable or invalid: ${baseline.reason}. Fix the file; a broken baseline must not release any findings.`,
-          },
-        ]);
-        continue;
-      }
-      const current: Record<string, number> = {};
-      if (byPath) {
-        for (const [relPath, entries] of byPath) current[relPath] = entries.length;
-      }
-      const baselineForGuard = baseline.findings[guardName] ?? {};
-      const { reductions } = compareToBaseline(current, baselineForGuard);
-      if (!byPath) {
-        reduced += reductions.reduce((sum, r) => sum + (r.baseline - r.current), 0);
-      }
-      for (const r of reductions) {
-        blockingEntries.push([
-          violations.length + strictIndex++,
-          {
-            file: join(root.absPath, r.file),
-            line: 1,
-            message: `Security baseline stale: ${root.name}/${r.file} allows ${r.baseline}, found ${r.current} — run \`--write-security-baseline\` and commit, otherwise the headroom covers new findings.`,
-          },
-        ]);
-      }
-    }
+    reduced += applyStrictHeadroom({
+      guardName,
+      roots,
+      byRepo,
+      loadOnce,
+      firstSortKey: violations.length,
+      blockingEntries,
+    });
   }
 
   blockingEntries.sort((a, b) => a[0] - b[0]);
@@ -314,7 +391,7 @@ export function buildSecurityBaseline(
   return {
     format: SECURITY_BASELINE_FORMAT,
     repo,
-    generated: new Date().toISOString().slice(0, 10),
+    generated: Temporal.Now.instant().toString().slice(0, 10),
     total,
     ...(sortedHardFail.length > 0 ? { hardFail: sortedHardFail } : {}),
     findings: Object.fromEntries(Object.entries(findings).sort(([a], [b]) => a.localeCompare(b))),

package/src/_lib/sql-inventory.ts

@@ -174,6 +174,35 @@ function stripMarker(trimmed: string): string {
   return trimmed.slice(0, idx).trimEnd();
 }
 
+type LineMarker = { readonly reason: string; readonly line: number };
+
+// 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.
+function markerForLine(
+  lines: readonly string[],
+  i: number,
+  consumedMarkers: Set<number>,
+): LineMarker | undefined {
+  const sameLineReason = MARKER_WITH_REASON_RE.exec(lines[i] ?? "")?.[2];
+  if (sameLineReason !== undefined) return { reason: sameLineReason.trim(), line: i + 1 };
+  if (i === 0) return undefined;
+  const aboveReason = MARKER_WITH_REASON_RE.exec(lines[i - 1] ?? "")?.[2];
+  const markerIdx = i - 1;
+  if (aboveReason === undefined || consumedMarkers.has(markerIdx)) return undefined;
+  consumedMarkers.add(markerIdx);
+  return { reason: aboveReason.trim(), line: i };
+}
+
+function isCommentOnlyLine(trimmed: string): boolean {
+  return (
+    trimmed.startsWith("//") ||
+    trimmed.startsWith("*") ||
+    trimmed.startsWith("/**") ||
+    trimmed.startsWith("/*")
+  );
+}
+
 function scanFileText(relPath: string, text: string, hits: SqlInventoryHit[]): void {
   const lines = text.split("\n");
   const consumedMarkers = new Set<number>();
@@ -185,34 +214,9 @@ function scanFileText(relPath: string, text: string, hits: SqlInventoryHit[]): v
     // a marker placed on its own comment line (the common case: the line
     // ABOVE the offending call) must still be seen even though that line
     // itself never reaches the pattern loop.
-    //
-    // 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 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 (aboveReason !== undefined && !consumedMarkers.has(markerIdx)) {
-        markerReason = aboveReason.trim();
-        markerLine = i;
-        consumedMarkers.add(markerIdx);
-      }
-    }
+    const marker = markerForLine(lines, i, consumedMarkers);
 
-    if (
-      trimmed.startsWith("//") ||
-      trimmed.startsWith("*") ||
-      trimmed.startsWith("/**") ||
-      trimmed.startsWith("/*")
-    ) {
-      continue;
-    }
+    if (isCommentOnlyLine(trimmed)) continue;
     for (const { kind, re } of PATTERNS) {
       if (!re.test(line)) continue;
       hits.push({
@@ -220,10 +224,8 @@ function scanFileText(relPath: string, text: string, hits: SqlInventoryHit[]): v
         line: i + 1,
         kind,
         allowed: isRawSqlAllowed(relPath),
-        markerSuppressed: markerReason !== undefined,
-        ...(markerReason !== undefined && markerLine !== undefined
-          ? { markerReason, markerLine }
-          : {}),
+        markerSuppressed: marker !== undefined,
+        ...(marker !== undefined ? { markerReason: marker.reason, markerLine: marker.line } : {}),
         snippet: stripMarker(trimmed).slice(0, 120),
       });
     }
@@ -259,7 +261,7 @@ export async function scanRepo(
   }
 
   return {
-    scannedAt: new Date().toISOString(),
+    scannedAt: Temporal.Now.instant().toString(),
     root: repoRoot,
     hits,
     scannedFiles: relFiles.length,

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.357.0",
+    "type": "fix",
+    "title": "comment-lang reports an unreadable or non-object baseline instead of crashing",
+    "detail": "`kumiko-guards comment-lang` with a baseline file that is not valid JSON, is `null` or has a `null` perFile now prints a baseline-format message and exits 1 instead of throwing a TypeError. A security baseline with the wrong shape now reports the reason `unexpected_baseline_shape`."
+  },
   {
     "version": "0.355.0",
     "type": "breaking",