@cosmicdrift/kumiko-guards 0.403.0 → 0.404.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.403.0",
+  "version": "0.404.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": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -36,7 +36,7 @@
     "kumiko-pre-push": "./src/pre-push.sh"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.403.0",
+    "@cosmicdrift/kumiko-types": "0.404.0",
     "ts-morph": "^28.0.0",
     "zod": "^4.6.7"
   },
@@ -52,7 +52,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.403.0"
+    "@cosmicdrift/kumiko-framework": "0.404.0"
   },
   "peerDependenciesMeta": {
     "@cosmicdrift/kumiko-framework": {
@@ -60,6 +60,6 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.403.0"
+    "@cosmicdrift/kumiko-framework": "0.404.0"
   }
 }

package/src/_lib/dependency-exceptions.ts

@@ -108,7 +108,7 @@ function readExceptionEntries(source: ExceptionSource, filename: string): unknow
 export function loadExceptionEntries<T>(options: {
   readonly filename: string;
   readonly roots: readonly string[];
-  readonly parse: (field: (key: string) => string) => T;
+  readonly parse: (field: (key: string) => string, source: ExceptionSource) => T;
   readonly bundledDir?: string;
 }): T[] {
   const merged: T[] = [];
@@ -121,7 +121,7 @@ export function loadExceptionEntries<T>(options: {
             const value = entry[key];
             if (typeof value !== "string" || value.trim() === "") throw new MissingFieldError(key);
             return value;
-          }),
+          }, source),
         );
       } catch (err) {
         if (!(err instanceof MissingFieldError)) throw err;

package/src/_lib/security-audit.ts

@@ -1,7 +1,11 @@
 /**
  * Parse and evaluate `bun audit --json` reports with exception support.
  */
-import { isExceptionValid, matchesPackageName } from "./dependency-exceptions";
+import {
+  type ExceptionSource,
+  isExceptionValid,
+  matchesPackageName,
+} from "./dependency-exceptions";
 
 export type Severity = "critical" | "high" | "moderate" | "low" | "info";
 
@@ -29,6 +33,7 @@ export type SecurityException = {
   readonly reason: string;
   readonly reviewedBy: string;
   readonly expires: string;
+  readonly source: ExceptionSource;
 };
 
 export type SecurityEvaluation = {

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.404.0",
+    "type": "improvement",
+    "title": "Security check warns about unused repo exceptions",
+    "detail": "kumiko-guards security lists every exception from the repo's dependency-security-exceptions.json that suppressed no advisory in the run, with package, advisory and file. The warning does not block; exceptions bundled with the guards package never warn because they cover consumers that may not have the package. Remove the listed entries once the advisory is fixed or withdrawn."
+  },
   {
     "version": "0.402.0",
     "type": "improvement",

package/src/check-security.ts

@@ -34,12 +34,13 @@ export function loadSecurityExceptions(
     filename: SECURITY_EXCEPTIONS_FILE,
     roots,
     bundledDir,
-    parse: (field) => ({
+    parse: (field, source) => ({
       advisory: field("advisory"),
       package: field("package"),
       reason: field("reason"),
       reviewedBy: field("reviewedBy"),
       expires: field("expires"),
+      source,
     }),
   }).filter((exception) => {
     const hasDate = expiryEndMs(exception.expires) !== undefined;
@@ -67,6 +68,42 @@ export function shouldBlock(
   return evaluation.blocking.length > 0 || expiringUrgent.length > 0;
 }
 
+// Bundled exceptions apply to every consumer, including those without the package, so only repo-local ones can be stale.
+function findUnusedRepoExceptions(
+  exceptions: readonly SecurityException[],
+  used: readonly SecurityException[],
+): SecurityException[] {
+  return exceptions.filter((ex) => ex.source.origin === "repo" && !used.includes(ex));
+}
+
+function printExceptionWarnings(
+  evaluation: SecurityEvaluation,
+  exceptions: readonly SecurityException[],
+  expiringUrgent: readonly SecurityException[],
+  nowMs: number,
+): void {
+  const urgentKeys = new Set(expiringUrgent.map((ex) => `${ex.package}|${ex.advisory}`));
+  const expiringSoon = findExpiringSoon(exceptions, 30, nowMs).filter(
+    (ex) => !urgentKeys.has(`${ex.package}|${ex.advisory}`),
+  );
+  if (expiringSoon.length > 0) {
+    console.log("\n  WARN: security exceptions expire within 30 days — re-review:");
+    for (const ex of expiringSoon) {
+      console.log(`    ${ex.package}  ${ex.advisory}  expires=${ex.expires}`);
+    }
+  }
+
+  const unusedRepoExceptions = findUnusedRepoExceptions(exceptions, evaluation.usedExceptions);
+  if (unusedRepoExceptions.length > 0) {
+    console.log(
+      "\n  WARN: security exceptions suppressed no advisory in this run — remove the entry if it is obsolete:",
+    );
+    for (const ex of unusedRepoExceptions) {
+      console.log(`    ${ex.package}  ${ex.advisory}  (${ex.source.file})`);
+    }
+  }
+}
+
 function printReport(
   evaluation: SecurityEvaluation,
   exceptions: readonly SecurityException[],
@@ -112,16 +149,7 @@ function printReport(
     }
   }
 
-  const urgentKeys = new Set(expiringUrgent.map((ex) => `${ex.package}|${ex.advisory}`));
-  const expiringSoon = findExpiringSoon(exceptions, 30, nowMs).filter(
-    (ex) => !urgentKeys.has(`${ex.package}|${ex.advisory}`),
-  );
-  if (expiringSoon.length > 0) {
-    console.log("\n  WARN: security exceptions expire within 30 days — re-review:");
-    for (const ex of expiringSoon) {
-      console.log(`    ${ex.package}  ${ex.advisory}  expires=${ex.expires}`);
-    }
-  }
+  printExceptionWarnings(evaluation, exceptions, expiringUrgent, nowMs);
 
   if (shouldBlock(evaluation, expiringUrgent)) {
     console.error(