mandrel 2.56.0 → 2.57.0

package/.agents/scripts/lib/crap-utils.js

@@ -348,6 +348,12 @@ function projectScanRow(relPath, mr) {
  * skipped from the returned rows so the baseline never contains
  * partially-scored entries. Both counters surface for reporting.
  *
+ * A file neither path could score at all — unreadable, untranspilable, or one
+ * the kernel could not parse — is dropped and counted in `unscorableFiles`
+ * (Story #5311). Unscorable is not scored-as-nothing: without this counter a
+ * dropped file is indistinguishable from a file with no methods, which is what
+ * let a whole parse-failure class leave the baseline silently.
+ *
  * When `scopeFiles` is provided (the `--changed-since` code path) files
  * discovered via directory walking are filtered against that set before any
  * I/O or scoring happens — so pre-push / PR-CI runs never pay the
@@ -385,6 +391,7 @@ function projectScanRow(relPath, mr) {
  *   scannedFiles: number,
  *   skippedFilesNoCoverage: number,
  *   skippedMethodsNoCoverage: number,
+ *   unscorableFiles: number,
  * }}
  */
 export async function scanAndScore({
@@ -442,9 +449,16 @@ export async function scanAndScore({
   const rows = [];
   let skippedFilesNoCoverage = 0;
   let skippedMethodsNoCoverage = 0;
+  let unscorableFiles = 0;
   const resolution = newResolutionAccumulator();
   for (const { item, result } of perFile) {
-    if (!result) continue; // unrecoverable per-file failure: drop silently to match pre-pool semantics
+    if (!result) {
+      // Unrecoverable per-file failure (a pool-level error the worker never
+      // answered). Dropped like any other unscorable file, and counted — the
+      // point of the counter is that no drop is silent.
+      unscorableFiles += 1;
+      continue;
+    }
     if (result.skippedFileNoCoverage) {
       skippedFilesNoCoverage += 1;
       continue;
@@ -453,6 +467,7 @@ export async function scanAndScore({
       // read/transpile/parse failure: drop and move on, but if the worker
       // attached an error message (calculateCrapForSource throw) surface it
       // so the run isn't silent on the ops side.
+      unscorableFiles += 1;
       if (result.error) {
         Logger.warn(
           `[crap-utils] failed to score ${item.relPath}: ${result.error}`,
@@ -479,6 +494,7 @@ export async function scanAndScore({
     scannedFiles,
     skippedFilesNoCoverage,
     skippedMethodsNoCoverage,
+    unscorableFiles,
     resolution: summarizeResolution(resolution),
   };
 }

package/.agents/scripts/lib/cyclomatic-ceiling.js

@@ -1,6 +1,6 @@
 /**
- * cyclomatic-ceiling.js — the enforcing core behind
- * `delivery.quality.codingGuardrails.cyclomaticMustFix` (Story #4923).
+ * cyclomatic-ceiling.js — the enforcing core behind the cyclomatic ceiling
+ * ratchet (Story #4923; fixed ceiling since Story #5313).
  *
  * The two `codingGuardrails` cyclomatic knobs shipped schema-validated,
  * bootstrap-defaulted and resolver-resolved, and were then read by nothing:
@@ -9,6 +9,12 @@
  * nothing enforces is worse than no ceiling, because the workflow docs promise
  * the merge will be refused.
  *
+ * Story #5313 retired the `cyclomaticMustFix` config key: the ratchet's
+ * ceiling is the fixed {@link CYCLOMATIC_CEILING} (12), so a consumer cannot
+ * bound this gate by tuning a number, and `cyclomaticFlag` is the one
+ * advisory knob — `quality-preview.js` reports over-flag methods and exits 0
+ * on them.
+ *
  * This module is that enforcement, shaped as a **ratchet** rather than a
  * cliff. The repository already carries dozens of functions above the
  * must-fix ceiling; failing every one of them at once would have made the
@@ -37,6 +43,13 @@ import { scanDirectory } from './maintainability-utils.js';
 /** Default location of the committed breach baseline. */
 export const DEFAULT_CYCLOMATIC_BASELINE = 'baselines/cyclomatic.json';
 
+/**
+ * The per-function cyclomatic ceiling the ratchet enforces. Fixed — not a
+ * config key — since Story #5313.
+ * @type {number}
+ */
+export const CYCLOMATIC_CEILING = 12;
+
 /** Baseline `$schema` marker, matching the sibling ratchet baselines. */
 const CYCLOMATIC_BASELINE_SCHEMA =
   'https://mandrel.dev/baselines/cyclomatic.schema.json';
@@ -44,10 +57,9 @@ const CYCLOMATIC_BASELINE_SCHEMA =
 /**
  * Resolve the enforcement policy from a resolved `delivery.quality` block.
  *
- * `mustFix` and `flag` come straight from `resolveCodingGuardrails`, so a
- * consumer that tunes either knob tunes this gate — which is the whole point
- * of the Story. `targetDirs` / `ignoreGlobs` are borrowed from the
- * maintainability gate (see the module note).
+ * `mustFix` is the fixed {@link CYCLOMATIC_CEILING}; `flag` comes from
+ * `resolveCodingGuardrails` (advisory only). `targetDirs` / `ignoreGlobs`
+ * are borrowed from the maintainability gate (see the module note).
  *
  * @param {object | null | undefined} quality resolved `delivery.quality`
  * @returns {{ mustFix: number, flag: number, targetDirs: string[], ignoreGlobs: string[] }}
@@ -56,7 +68,7 @@ export function resolveCyclomaticPolicy(quality) {
   const guardrails = quality?.codingGuardrails ?? {};
   const mi = quality?.maintainability ?? {};
   return {
-    mustFix: Number(guardrails.cyclomaticMustFix ?? 12),
+    mustFix: CYCLOMATIC_CEILING,
     flag: Number(guardrails.cyclomaticFlag ?? 8),
     targetDirs: Array.isArray(mi.targetDirs) ? mi.targetDirs : [],
     ignoreGlobs: Array.isArray(mi.ignoreGlobs) ? mi.ignoreGlobs : [],