@opengsd/gsd-core 1.10.0 → 1.12.0

package/gsd-core/bin/lib/estimate-cli.cjs

@@ -21,7 +21,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CALIBRATION_FILENAME = void 0;
+exports.PhasesUnreadableError = exports.CALIBRATION_FILENAME = void 0;
 exports.readSmartZoneBudget = readSmartZoneBudget;
 exports.readCalibrationSamples = readCalibrationSamples;
 exports.parseTokensFlag = parseTokensFlag;
@@ -39,9 +39,15 @@ const estimation = require("./phase-estimation.cjs");
 const planningWorkspace = require("./planning-workspace.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- config-loader.cjs is an export= CommonJS module
 const configLoader = require("./config-loader.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-locator.cjs is an export= CommonJS module
+const phaseLocator = require("./phase-locator.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-scope.cjs is an export= CommonJS module
+const planningScopeMod = require("./planning-scope.cjs");
 const { output, error, ERROR_REASON } = io;
 const { planningDir } = planningWorkspace;
 const { CONFIG_DEFAULTS } = configLoader;
+const { listMilestonePhaseDirs } = phaseLocator;
+const { SCOPE } = planningScopeMod;
 // WIN-1 parity (DEFECT.WINDOWS-FS-OPS): on Windows a concurrent reader, indexer,
 // or AV scanner can transiently hold the rename target open. Retry the transient
 // errnos with backoff, matching the writeLedger / writeConsentStore idiom.
@@ -192,6 +198,24 @@ function cmdEstimateCheck(cwd, args, raw) {
         sample_count: calibration.sampleCount,
     }, raw);
 }
+/**
+ * Thrown by `collectCalibrationSamples` when the phases directory EXISTS but
+ * could not be read (EACCES/EIO, `scope: SCOPE.UNREADABLE`). #3882/ADR-3473
+ * §8.5: that is a NON-answer, not "zero completed phases" — silently
+ * returning `[]` here would make an unreadable directory output-identical to
+ * a genuinely empty one, which is exactly the defect class §8.5 exists to
+ * end. `cmdEstimateCalibrate` catches this and refuses the rebuild instead
+ * of persisting a phantom empty calibration.
+ */
+class PhasesUnreadableError extends Error {
+    phasesRoot;
+    constructor(phasesRoot) {
+        super(`phases directory exists but could not be read: ${phasesRoot}`);
+        this.phasesRoot = phasesRoot;
+        this.name = 'PhasesUnreadableError';
+    }
+}
+exports.PhasesUnreadableError = PhasesUnreadableError;
 /**
  * Pair each completed phase's PLAN estimate with its SUMMARY actuals.
  *
@@ -199,18 +223,25 @@ function cmdEstimateCheck(cwd, args, raw) {
  * A plan with no `estimate` block, a summary with no `actuals`, or a malformed
  * value is skipped rather than guessed — a fabricated sample would silently
  * steer every future estimate.
+ *
+ * #3882 (ADR-3473 §8.2): this used to hand-roll a raw `readdirSync` over the
+ * phases directory, treating every directory (including sentinel phases —
+ * milestone 0 / 999, SENTINEL_RANGES) as a completed phase. A sentinel's
+ * PLAN/SUMMARY pair then silently contributed a phantom sample to the
+ * CALIBRATION FACTOR applied to every future estimate. Routed through the
+ * canonical owner (`listMilestonePhaseDirs`, `src/phase-locator.cts`) called
+ * with NO `cwd` — that combination is already "all milestone windows,
+ * sentinels excluded", exactly what this caller needs; no new API was
+ * required for this half (see the design doc's §3, corrected after
+ * measurement). It also inherits the `scope` discriminator for free, so an
+ * unreadable phases directory is no longer indistinguishable from a real
+ * empty one.
  */
 function collectCalibrationSamples(cwd) {
     const phasesRoot = node_path_1.default.join(planningDir(cwd), 'phases');
-    let phases;
-    try {
-        phases = node_fs_1.default.readdirSync(phasesRoot, { withFileTypes: true })
-            .filter((d) => d.isDirectory())
-            .map((d) => d.name)
-            .sort();
-    }
-    catch {
-        return [];
+    const { value: phases, scope } = listMilestonePhaseDirs(phasesRoot);
+    if (scope === SCOPE.UNREADABLE) {
+        throw new PhasesUnreadableError(phasesRoot);
     }
     const readBlock = (file, key) => {
         let text;
@@ -277,7 +308,20 @@ function collectCalibrationSamples(cwd) {
  * next estimate reads the result.
  */
 function cmdEstimateCalibrate(cwd, _args, raw) {
-    const samples = collectCalibrationSamples(cwd);
+    let samples;
+    try {
+        samples = collectCalibrationSamples(cwd);
+    }
+    catch (err) {
+        if (err instanceof PhasesUnreadableError) {
+            // #3882/ADR-3473 §8.5: refuse rather than silently rebuild the
+            // calibration document from a phantom empty sample set — an
+            // unreadable phases directory must never look output-identical to a
+            // project with genuinely zero completed phases.
+            error(err.message, ERROR_REASON.ESTIMATE_PHASES_UNREADABLE);
+        }
+        throw err;
+    }
     const calibration = estimation.computeCalibration(samples);
     const target = node_path_1.default.join(planningDir(cwd), exports.CALIBRATION_FILENAME);
     let written = true;

package/gsd-core/bin/lib/exit-code-registry.cjs

@@ -0,0 +1,98 @@
+'use strict';
+
+// GENERATED FILE — DO NOT EDIT BY HAND.
+// Source of truth: gsd-core/bin/shared/exit-codes.json. Regenerate with:
+//   node scripts/gen-exit-code-registry.cjs --write
+// This exact content is emitted to THREE locations — gsd-core/bin/lib/exit-code-registry.cjs,
+// scripts/lib/exit-code-registry.cjs, and hooks/lib/exit-code-registry.js (the latter two
+// committed so scripts/ and hooks/ consumers work on an unbuilt clone) — all byte-compared by
+// `npm run lint:generated-sync` (#3905 ADR-3889 Phase 1; #3906 Phase 2 added the second copy;
+// #3911 ADR-3889 Phase 7 added the hooks/lib/ copy).
+//
+// exitCodeFor(name) / nameForExitCode(code) are pure and total over this
+// closed table — each throws for anything not registered here.
+
+const EXIT_CODES = Object.freeze([
+  Object.freeze({
+    code: 2,
+    name: "HOOK_DENY",
+    meaning: "Hook protocol deny — the harness blocks the tool call",
+    owner: "hook-adapter",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 64,
+    name: "USAGE",
+    meaning: "Caller error — bad argv, unknown subcommand, missing argument",
+    owner: "generic",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 66,
+    name: "NO_INPUT",
+    meaning: "Ran; zero units were in scope, and that emptiness is known to be genuine",
+    owner: "generic",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 69,
+    name: "UNAVAILABLE",
+    meaning: "Could not run — prerequisite absent, input unreadable, scope unestablished",
+    owner: "generic",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 70,
+    name: "INTERNAL",
+    meaning: "Self-failure — crash, timeout, killed subprocess",
+    owner: "generic",
+    authorizedBy: "ADR-3889",
+  }),
+  Object.freeze({
+    code: 80,
+    name: "DEGRADED",
+    meaning: "Ran to completion and is reporting a condition through its result payload rather than as a process failure",
+    owner: "gsd-tools",
+    authorizedBy: "ADR-3889 + ADR-2980",
+  })
+]);
+
+const NAME_TO_CODE = new Map(EXIT_CODES.map((entry) => [entry.name, entry.code]));
+const CODE_TO_NAME = new Map(EXIT_CODES.map((entry) => [entry.code, entry.name]));
+
+/**
+ * Resolve the registered exit code for a symbolic name. Pure, total: throws
+ * for anything not an exact, registered, exact-case key — including
+ * non-strings, the empty string, untrimmed strings, wrong case, and
+ * prototype-chain names like `__proto__`/`constructor`/`toString` (a Map
+ * lookup never touches the prototype chain, so these are indistinguishable
+ * from any other unregistered name).
+ *
+ * @param {string} name
+ * @returns {number}
+ */
+function exitCodeFor(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error(`exitCodeFor: name must be a non-empty string, received ${JSON.stringify(name)}`);
+  }
+  if (!NAME_TO_CODE.has(name)) {
+    throw new Error(`exitCodeFor: unregistered exit code name: ${JSON.stringify(name)}`);
+  }
+  return NAME_TO_CODE.get(name);
+}
+
+/**
+ * Reverse of exitCodeFor: resolve the symbolic name for a registered exit
+ * code. Pure, total: throws for anything not an exact, registered code.
+ *
+ * @param {number} code
+ * @returns {string}
+ */
+function nameForExitCode(code) {
+  if (!CODE_TO_NAME.has(code)) {
+    throw new Error(`nameForExitCode: unregistered exit code: ${JSON.stringify(code)}`);
+  }
+  return CODE_TO_NAME.get(code);
+}
+
+module.exports = { EXIT_CODES, exitCodeFor, nameForExitCode };

package/gsd-core/bin/lib/fallow-runner.cjs

@@ -8,6 +8,13 @@
  *
  * Parses the real fallow `audit --format json` schema (schema_version 3
  * envelope, nested dead_code/duplication sections). See fallow 2.70.0+.
+ *
+ * #3411 Phase 2 (#3618): binary resolution no longer lives here — it delegates
+ * to the platform seam's `resolveExecutableBinary` (shell-command-projection.cts).
+ * This file's prior private resolver deliberately included an extensionless
+ * `fallow` as a win32 candidate; the seam does not, and that is a fix, not a
+ * regression — an extensionless file sitting beside `fallow.cmd` is npm's POSIX
+ * `sh` shim, which `CreateProcess` cannot run (#3275).
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -19,51 +26,20 @@ exports.normalizeFallowReport = normalizeFallowReport;
 exports.normalizeFallowReportFile = normalizeFallowReportFile;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-function candidateNames() {
-    return process.platform === 'win32'
-        ? ['fallow.exe', 'fallow.cmd', 'fallow.bat', 'fallow']
-        : ['fallow'];
-}
-function isExecutableFile(filePath) {
-    try {
-        const stat = node_fs_1.default.statSync(filePath);
-        if (!stat.isFile())
-            return false;
-        if (process.platform === 'win32')
-            return true;
-        node_fs_1.default.accessSync(filePath, node_fs_1.default.constants.X_OK);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function findInPath(envPath) {
-    if (!envPath)
-        return null;
-    const names = candidateNames();
-    const segments = envPath.split(node_path_1.default.delimiter).filter(Boolean);
-    for (const segment of segments) {
-        for (const name of names) {
-            const candidate = node_path_1.default.join(segment, name);
-            if (isExecutableFile(candidate))
-                return candidate;
-        }
-    }
-    return null;
-}
-function findInNodeModules(cwd) {
-    const names = candidateNames();
-    const binDir = node_path_1.default.join(cwd, 'node_modules', '.bin');
-    for (const name of names) {
-        const candidate = node_path_1.default.join(binDir, name);
-        if (isExecutableFile(candidate))
-            return candidate;
-    }
-    return null;
-}
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 function resolveFallowBinary({ cwd, envPath = process.env['PATH'] ?? '' }) {
-    return findInNodeModules(cwd) || findInPath(envPath) || null;
+    return (0, shell_command_projection_cjs_1.resolveExecutableBinary)('fallow', {
+        prependPaths: [node_path_1.default.join(cwd, 'node_modules', '.bin')],
+        // #3619 (epic #3411 Phase 3): pathOverride carries envPath as the search
+        // path while leaving `env` unset, so the seam falls back to its default
+        // `env` (process.env) for everything else — PATHEXT included. Ambient
+        // PATHEXT therefore still governs win32 resolution exactly as before, but
+        // this file never reads it itself: that's what keeps this module clean
+        // under local/no-private-binary-resolution, which forbids a PATHEXT read
+        // outside the seam.
+        pathOverride: envPath,
+        requireExecutable: true,
+    });
 }
 function requireFallowBinary({ cwd, envPath = process.env['PATH'] ?? '' }) {
     const binary = resolveFallowBinary({ cwd, envPath });