@getcodesentinel/codesentinel 1.17.2 → 1.17.4

package/README.md

@@ -419,12 +419,12 @@ Score direction:
 - Report views also include derived tiers: `riskTier` and `healthTier`.
 - `health.trace`: per-dimension factor traces with normalized metrics and evidence.
 
-Health v2 dimensions and weights:
+Health dimensions:
 
-- `modularity` (`0.35`): cycle density + fan/centrality concentration + structural-hotspot overlap.
-- `changeHygiene` (`0.30`): churn/volatility concentration + dense co-change clusters.
-- `testHealth` (`0.20`): test presence + test-to-source ratio + testing directory presence.
-- `ownershipDistribution` (`0.15`): top-author share + author entropy + single-author dominance signals.
+- `modularity`: cycle density + fan/centrality concentration + structural-hotspot overlap.
+- `changeHygiene`: churn/volatility concentration + dense co-change clusters.
+- `testHealth`: test presence + test-to-source ratio + testing directory presence.
+- `ownershipDistribution`: top-author share + author entropy + single-author dominance signals.
 
 Signal ingestion (deterministic, local):
 
@@ -438,18 +438,30 @@ Interpretation notes:
 - Scores are meant for within-repo prioritization and trend tracking.
 - Full model details and limits are in `packages/risk-engine/README.md`.
 
-### Score Guide
+### Risk Score Guide
 
 Use these ranges as operational guidance:
 
-- `0-20`: low fragility.
-- `20-40`: moderate fragility.
-- `40-60`: elevated fragility (prioritize top hotspots).
-- `60-80`: high fragility (expect higher change coordination cost).
-- `80-100`: very high fragility (investigate immediately).
+- `0-20`: low fragility (architectural and change pressure signals are generally contained).
+- `20-40`: moderate fragility (localized hotspots exist; monitor trend direction and concentration).
+- `40-60`: elevated fragility (prioritize top hotspots before introducing major concurrent change).
+- `60-80`: high fragility (expect higher coordination cost, regressions, and change coupling across areas).
+- `80-100`: very high fragility (treat as immediate triage; focus on stabilization before further expansion).
 
 These ranges are heuristics for triage, not incident probability.
 
+### Health Score Guide
+
+Use these ranges as operational guidance:
+
+- `0-20`: critical health posture (maintainability pressure is highly concentrated and debt is likely compounding).
+- `20-40`: weak health posture (key maintainability bottlenecks are visible; prioritize stabilization work).
+- `40-60`: fair health posture (baseline is workable, but concentrated architecture/change pressure can still slow delivery).
+- `60-80`: good health posture (most maintainability signals are stable, with targeted improvements still valuable).
+- `80-100`: excellent health posture (maintainability pressure is broadly distributed and sustainably controlled over time).
+
+These ranges are heuristics for prioritization, not absolute quality guarantees.
+
 ### What Moves Scores
 
 `risk.riskScore` and `risk.fileScores[*].score` increase when:

package/dist/index.js

@@ -703,6 +703,14 @@ var DEFAULT_OPTIONS = {
   maxEntryBytes: 4 * 1024 * 1024,
   sweepIntervalWrites: 25
 };
+var DEFAULT_BUCKET = "default";
+var normalizeBucket = (value) => {
+  const trimmed = value.trim().toLowerCase();
+  if (trimmed.length === 0) {
+    return DEFAULT_BUCKET;
+  }
+  return trimmed.replace(/[^a-z0-9_-]/g, "_");
+};
 var FileCacheStore = class {
   constructor(directoryPath, options = DEFAULT_OPTIONS) {
     this.directoryPath = directoryPath;
@@ -712,13 +720,22 @@ var FileCacheStore = class {
   inFlightWrites = /* @__PURE__ */ new Map();
   writesSinceSweep = 0;
   sweepPromise = Promise.resolve();
+  bucketForKey(key) {
+    const configured = this.options.bucketForKey?.(key);
+    if (configured === void 0) {
+      return DEFAULT_BUCKET;
+    }
+    return normalizeBucket(configured);
+  }
   toEntryPath(key) {
+    const bucket = this.bucketForKey(key);
     const digest = createHash("sha256").update(key).digest("hex");
-    return join3(this.directoryPath, `${digest}.json`);
+    return join3(this.directoryPath, bucket, `${digest}.json`);
   }
   async writeEntry(key, entry) {
     const filePath = this.toEntryPath(key);
-    await mkdir(this.directoryPath, { recursive: true });
+    const bucketPath = join3(this.directoryPath, this.bucketForKey(key));
+    await mkdir(bucketPath, { recursive: true });
     const tempPath = `${filePath}.tmp`;
     const payload = {
       key,
@@ -745,34 +762,74 @@ var FileCacheStore = class {
     await this.sweepPromise;
   }
   async evictToSizeLimit() {
+    const nowMs = Date.now();
     let entries;
     try {
-      const dirEntries = await readdir(this.directoryPath, { withFileTypes: true });
+      const bucketEntries = await readdir(this.directoryPath, { withFileTypes: true });
+      const bucketNames = bucketEntries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
       entries = (await Promise.all(
-        dirEntries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map(async (entry) => {
-          const path = join3(this.directoryPath, entry.name);
-          const info = await stat(path);
-          return { path, size: info.size, mtimeMs: info.mtimeMs };
+        bucketNames.map(async (bucket) => {
+          const bucketPath = join3(this.directoryPath, bucket);
+          const files = await readdir(bucketPath, { withFileTypes: true });
+          return await Promise.all(
+            files.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map(async (entry) => {
+              const path = join3(bucketPath, entry.name);
+              const info = await stat(path);
+              return {
+                path,
+                size: info.size,
+                mtimeMs: info.mtimeMs,
+                bucket
+              };
+            })
+          );
         })
-      )).filter((entry) => Number.isFinite(entry.size) && entry.size > 0);
+      )).flat().filter((entry) => Number.isFinite(entry.size) && entry.size > 0);
     } catch {
       return;
     }
+    if (this.options.maxAgeMsByBucket !== void 0) {
+      const retained = [];
+      let deletedAny2 = false;
+      for (const entry of entries) {
+        const maxAgeMs = this.options.maxAgeMsByBucket[entry.bucket];
+        const expired = typeof maxAgeMs === "number" && Number.isFinite(maxAgeMs) && nowMs - entry.mtimeMs > maxAgeMs;
+        if (!expired) {
+          retained.push(entry);
+          continue;
+        }
+        try {
+          await unlink(entry.path);
+          deletedAny2 = true;
+        } catch {
+          retained.push(entry);
+        }
+      }
+      entries = retained;
+      if (deletedAny2) {
+        this.byKey.clear();
+      }
+    }
     let totalBytes = entries.reduce((sum, entry) => sum + entry.size, 0);
     if (totalBytes <= this.options.maxBytes) {
       return;
     }
     entries.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    let deletedAny = false;
     for (const entry of entries) {
       if (totalBytes <= this.options.maxBytes) {
         break;
       }
       try {
         await unlink(entry.path);
+        deletedAny = true;
         totalBytes -= entry.size;
       } catch {
       }
     }
+    if (deletedAny) {
+      this.byKey.clear();
+    }
   }
   async get(key) {
     if (this.byKey.has(key)) {
@@ -808,7 +865,7 @@ var FileCacheStore = class {
 };
 var SIX_HOURS_MS = 6 * 60 * 60 * 1e3;
 var ONE_DAY_MS = 24 * 60 * 60 * 1e3;
-var DEFAULT_MAX_BYTES = 100 * 1024 * 1024;
+var DEFAULT_MAX_BYTES = 20 * 1024 * 1024;
 var DEFAULT_MAX_ENTRY_BYTES = 4 * 1024 * 1024;
 var DEFAULT_SWEEP_INTERVAL_WRITES = 25;
 var cacheStoreSingleton;
@@ -835,6 +892,8 @@ var getNpmMetadataCacheStore = () => {
     return cacheStoreSingleton;
   }
   const path = join4(resolveCodesentinelCacheDir(process.env), "npm-metadata-v2");
+  const packumentTtlMs = getPackumentCacheTtlMs();
+  const downloadsTtlMs = getWeeklyDownloadsCacheTtlMs();
   cacheStoreSingleton = new FileCacheStore(path, {
     maxBytes: parsePositiveIntegerFromEnv(
       process.env["CODESENTINEL_CACHE_MAX_BYTES"],
@@ -847,7 +906,20 @@ var getNpmMetadataCacheStore = () => {
     sweepIntervalWrites: parsePositiveIntegerFromEnv(
       process.env["CODESENTINEL_CACHE_SWEEP_INTERVAL_WRITES"],
       DEFAULT_SWEEP_INTERVAL_WRITES
-    )
+    ),
+    bucketForKey: (key) => {
+      if (key.startsWith("npm:downloads:last-week:")) {
+        return "downloads";
+      }
+      if (key.startsWith("npm:packument:")) {
+        return "packument";
+      }
+      return "default";
+    },
+    maxAgeMsByBucket: {
+      downloads: downloadsTtlMs,
+      packument: packumentTtlMs
+    }
   });
   return cacheStoreSingleton;
 };