@opengsd/gsd-core 1.11.0 → 1.13.0

package/gsd-core/bin/lib/configuration.cjs

@@ -14,8 +14,18 @@ exports.DYNAMIC_KEY_PATTERNS = exports.RUNTIME_STATE_KEYS = exports.VALID_CONFIG
 exports.normalizeLegacyKeys = normalizeLegacyKeys;
 exports.mergeDefaults = mergeDefaults;
 exports.migrateOnDisk = migrateOnDisk;
+exports.isConfigSection = isConfigSection;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+// ⚠️ DO NOT add a sibling `.cjs` import to this module. `configuration.cjs` must load
+// from an install layout containing ONLY itself plus `bin/shared/*.manifest.json` —
+// that is the #3571 contract, pinned by "co-located bin/shared manifests let
+// configuration.cjs load without sdk/shared" in tests/install.test.cjs. A `require`
+// for a sibling that the installer does not co-locate fails at load time with
+// MODULE_NOT_FOUND. This is why #3760's out-of-band diagnostic is emitted by this
+// module's CALLERS (`cmdMigrateConfig` in config.cts, `loadConfigResolved` in
+// config-loader.cts) rather than here: `normalizeLegacyKeys` reports refusals
+// in-band via `skipped[]`, which keeps it both pure AND dependency-free.
 // In .cts (CommonJS output) files, `require` is available as a global.
 const _require = require;
 // ─── Manifest requires ───────────────────────────────────────────────────────
@@ -109,42 +119,107 @@ function deepMergeConfig(base, overlay) {
     }
     return result;
 }
+/** Type name for a report — `'array'` for arrays, otherwise `typeof`. */
+function describeSectionType(value) {
+    return Array.isArray(value) ? 'array' : typeof value;
+}
+/**
+ * Is `value` usable as a config SECTION — something a nested key can be written into?
+ *
+ * Three cases, and the distinction between the second and third is the whole of #3760:
+ *
+ *  - `null` / `undefined` — ABSENT. Not a section yet, but nothing is lost by creating one.
+ *    Callers substitute `{}`; this predicate reports `false` and callers check for absence
+ *    separately, so the two are never conflated.
+ *  - a non-null, non-array `object` — a SECTION. Spreading it is safe and correct.
+ *  - anything else (string, number, boolean, array) — a PRESENT NON-OBJECT, i.e. user data
+ *    that a spread would destroy. `{...'main'}` is `{0:'m',1:'a',2:'i',3:'n'}`; `{...7}` is
+ *    `{}`. An array is included here because `typeof [] === 'object'` and `{...['a']}` is
+ *    `{0:'a'}` — the identical expansion a bare `typeof` guard would wave through.
+ *
+ * This is the nested-section analog of the top-level shape check ADR-227 already requires
+ * in `_readConfigFile` (`config-loader.cts`): valid JSON is not the same as a config object.
+ * It lives here, exported, rather than being copied into `config-loader.cts`, because two
+ * hand-rolled copies of one predicate is `DEFECT.GENERATIVE-FIX` by construction — the same
+ * reasoning that made `unusable-input.cts` a shared seam.
+ */
+function isConfigSection(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
 // ─── Exported functions ───────────────────────────────────────────────────────
+/**
+ * Hoist a legacy top-level key into its canonical nested section.
+ *
+ * Refuses — and reports the refusal — when the destination section is present but is not an
+ * object. Refusing means leaving BOTH the section and the legacy key exactly as they were and
+ * pushing no `Normalization`, so this block never marks the config dirty and nothing it
+ * touched can be written back. That is the #3760 contract: never expand, never drop, never
+ * persist a shape the user did not write.
+ */
+function hoistLegacyKey(result, normalizations, skipped, legacyKey, section, field) {
+    const raw = result[section];
+    // `null`/`undefined` mean "no section yet" and have always been treated as absent here.
+    // They carry no user data, so creating the section loses nothing.
+    const absent = raw === null || raw === undefined;
+    if (!absent && !isConfigSection(raw)) {
+        skipped.push({
+            from: legacyKey,
+            to: `${section}.${field}`,
+            section,
+            reason: 'non_object_section',
+            value: result[legacyKey],
+            sectionType: describeSectionType(raw),
+        });
+        return;
+    }
+    // `raw` is already narrowed by the isConfigSection guard above.
+    const existing = absent ? {} : raw;
+    const value = result[legacyKey];
+    // Canonical nested wins when it is already set; otherwise the legacy value is hoisted.
+    result[section] = existing[field] === undefined
+        ? { ...existing, [field]: value }
+        : { ...existing };
+    delete result[legacyKey];
+    normalizations.push({ from: legacyKey, to: `${section}.${field}`, value });
+}
 function normalizeLegacyKeys(parsed) {
     const result = { ...parsed };
     const normalizations = [];
+    const skipped = [];
     // 1. branching_strategy → git.branching_strategy
     if (Object.prototype.hasOwnProperty.call(result, 'branching_strategy')) {
-        const value = result['branching_strategy'];
-        const git = (result['git'] ?? {});
-        if (git['branching_strategy'] === undefined) {
-            result['git'] = { ...git, branching_strategy: value };
-        }
-        else {
-            // canonical nested wins — just delete the stale top-level
-            result['git'] = { ...git };
-        }
-        delete result['branching_strategy'];
-        normalizations.push({ from: 'branching_strategy', to: 'git.branching_strategy', value });
+        hoistLegacyKey(result, normalizations, skipped, 'branching_strategy', 'git', 'branching_strategy');
     }
     // 2. top-level sub_repos → planning.sub_repos
     if (Object.prototype.hasOwnProperty.call(result, 'sub_repos')) {
-        const value = result['sub_repos'];
-        const planning = (result['planning'] ?? {});
-        if (planning['sub_repos'] === undefined) {
-            result['planning'] = { ...planning, sub_repos: value };
-        }
-        else {
-            // canonical nested wins — just drop the stale top-level
-            result['planning'] = { ...planning };
-        }
-        delete result['sub_repos'];
-        normalizations.push({ from: 'sub_repos', to: 'planning.sub_repos', value });
+        hoistLegacyKey(result, normalizations, skipped, 'sub_repos', 'planning', 'sub_repos');
     }
     // 3. multiRepo: true → marker (filesystem detection deferred to migrateOnDisk / caller)
     if (result['multiRepo'] === true) {
-        delete result['multiRepo'];
-        normalizations.push({ from: 'multiRepo', to: 'planning.sub_repos', value: true, requiresFilesystem: true });
+        // #3760: refuse here too, for the same reason as blocks 1 and 2 — and it must be
+        // decided HERE, not in the caller. The caller is the one that runs filesystem
+        // detection, but whether `planning` can receive the result is knowable from the
+        // parsed config alone. Deciding it later meant `multiRepo` had already been
+        // deleted and a Normalization already pushed: the config was written, the
+        // sub_repos injection silently no-opped against the non-object section, and the
+        // user's `multiRepo: true` was consumed with nothing to show for it and no
+        // diagnostic. Refusing here keeps the marker, keeps the config clean of a
+        // migration that did not happen, and gives all three callers the same report.
+        const planning = result['planning'];
+        if (planning !== null && planning !== undefined && !isConfigSection(planning)) {
+            skipped.push({
+                from: 'multiRepo',
+                to: 'planning.sub_repos',
+                section: 'planning',
+                reason: 'non_object_section',
+                value: true,
+                sectionType: describeSectionType(planning),
+            });
+        }
+        else {
+            delete result['multiRepo'];
+            normalizations.push({ from: 'multiRepo', to: 'planning.sub_repos', value: true, requiresFilesystem: true });
+        }
     }
     // 4. top-level depth → granularity
     if (Object.prototype.hasOwnProperty.call(result, 'depth') && !Object.prototype.hasOwnProperty.call(result, 'granularity')) {
@@ -154,26 +229,36 @@ function normalizeLegacyKeys(parsed) {
         delete result['depth'];
         normalizations.push({ from: 'depth', to: 'granularity', value: mapped });
     }
-    return { parsed: result, normalizations };
+    // 5. top-level base_branch → git.base_branch
+    if (Object.prototype.hasOwnProperty.call(result, 'base_branch')) {
+        hoistLegacyKey(result, normalizations, skipped, 'base_branch', 'git', 'base_branch');
+    }
+    return { parsed: result, normalizations, skipped };
 }
 function mergeDefaults(parsed) {
     // Start with a deep clone of defaults, then overlay parsed
     const defaults = structuredClone(CONFIG_DEFAULTS);
     return deepMergeConfig(defaults, parsed);
 }
-function migrateOnDisk(cwd, workstream) {
-    const configPath = (0, node_path_1.join)(planningDir(cwd, workstream), 'config.json');
+function migrateOnDisk(cwd, workstream, configPathOverride) {
+    // #3749: the caller (cmdMigrateConfig in config.cts) supplies the config
+    // path resolved through planning-workspace's PROJECT-aware planningDir.
+    // This module cannot import that sibling (#3571 install-layout contract),
+    // and its own local planningDir above is deliberately workstream-only —
+    // resolving here through the local copy made migrate-config under
+    // GSD_PROJECT rewrite the ROOT config instead of the scoped one.
+    const configPath = configPathOverride ?? (0, node_path_1.join)(planningDir(cwd, workstream), 'config.json');
     let raw;
     try {
         raw = (0, node_fs_1.readFileSync)(configPath, 'utf-8');
     }
     catch {
         // File missing — nothing to migrate
-        return { migrated: false, normalizations: [], wrote: null };
+        return { migrated: false, normalizations: [], wrote: null, skipped: [] };
     }
     const trimmed = raw.trim();
     if (trimmed === '') {
-        return { migrated: false, normalizations: [], wrote: null };
+        return { migrated: false, normalizations: [], wrote: null, skipped: [] };
     }
     let parsed;
     try {
@@ -181,23 +266,30 @@ function migrateOnDisk(cwd, workstream) {
     }
     catch {
         // Malformed — can't migrate
-        return { migrated: false, normalizations: [], wrote: null };
-    }
-    const { parsed: normalized, normalizations } = normalizeLegacyKeys(parsed);
-    if (normalizations.length === 0) {
-        return { migrated: false, normalizations: [], wrote: null };
+        return { migrated: false, normalizations: [], wrote: null, skipped: [] };
     }
+    const { parsed: normalized, normalizations, skipped } = normalizeLegacyKeys(parsed);
     // Resolve multiRepo filesystem detection
     const result = { ...normalized };
     for (const norm of normalizations) {
         if (norm.requiresFilesystem) {
             const detected = detectSubRepos(cwd);
             if (detected.length > 0) {
-                const planning = (result['planning'] ?? {});
-                result['planning'] = { ...planning, sub_repos: detected, commit_docs: false };
+                // #3760: `requiresFilesystem` is pushed by block 3 only when `planning` was
+                // absent or an object, and nothing between there and here changes it — so
+                // `isConfigSection` picks between merge and create, and never has to discard.
+                const planning = result['planning'];
+                const existing = isConfigSection(planning) ? planning : {};
+                result['planning'] = { ...existing, sub_repos: detected, commit_docs: false };
             }
         }
     }
+    if (normalizations.length === 0) {
+        // Nothing changed — and that now includes the case where every legacy key was
+        // REFUSED. Returning early here is what keeps the corrupted-section input from
+        // reaching writeFileSync at all.
+        return { migrated: false, normalizations: [], wrote: null, skipped };
+    }
     try {
         (0, node_fs_1.writeFileSync)(configPath, JSON.stringify(result, null, 2));
     }
@@ -205,5 +297,5 @@ function migrateOnDisk(cwd, workstream) {
         const msg = err instanceof Error ? err.message : String(err);
         throw new Error(`Failed to write migrated config at ${configPath}: ${msg}`);
     }
-    return { migrated: true, normalizations, wrote: configPath };
+    return { migrated: true, normalizations, wrote: configPath, skipped };
 }

package/gsd-core/bin/lib/core-utils.cjs

@@ -15,6 +15,22 @@
  *   - node:fs / node:path (stdlib)
  *   - ./phase-id.cjs       (comparePhaseNum, used by readSubdirectories)
  *   - ./planning-workspace.cjs (findContextMdIn, used by getPhaseFileStats)
+ *
+ * #3883 (ADR-3473 §8.3): two of this module's cyclic partners require
+ * generateSlugInternal, the canonical slug formula:
+ *   - phase-id.cjs requires this module directly.
+ *   - planning-workspace.cjs is a cyclic partner via a longer path:
+ *     core-utils.cjs -> planning-workspace.cjs -> active-workstream-store.cjs
+ *     -> workstream-name-policy.cjs -> core-utils.cjs.
+ * Both are genuine circular requires. They are safe ONLY because every side
+ * accesses the other's exports lazily, through the live module-namespace
+ * object (`phaseIdModule.foo(...)` / `planningWorkspace.foo(...)`) inside a
+ * function body, never via a top-level destructure — a top-level
+ * `const { foo } = require(...)` copies the binding at import time and would
+ * silently capture `undefined` whichever module loses the load-order race.
+ * This is an absolute rule with no exception in this file: every cyclic
+ * partner's export is accessed through its module-namespace object, never
+ * destructured at the top level.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -23,12 +39,63 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdModule = require("./phase-id.cjs");
-const { comparePhaseNum, scopeToPhase } = phaseIdModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
-const { findContextMdIn } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const shellCommandProjection = require("./shell-command-projection.cjs");
+// planning-scope.cjs is a leaf module (no imports of its own — see its file
+// header), so importing it here directly cannot introduce a cycle.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningScopeMod = require("./planning-scope.cjs");
+const { SCOPE } = planningScopeMod;
+// ─── Line-ending normalization ─────────────────────────────────────────────────
+/**
+ * Normalize every line ending in `content` to a bare `\n`, ONCE — the shared
+ * seam every document-READ boundary in this codebase should route through
+ * (#3707-CR follow-up MAJOR).
+ *
+ * CommonMark treats a lone CR (no paired LF) as a line ending — such a
+ * document RENDERS as separate lines to a human reader — but a parser that
+ * splits/tokenizes/scans on `\n` alone treats a lone-CR-separated document as
+ * ONE unbroken line, hiding every row boundary in it. `src/uat.cts` originally
+ * carried this exact fix as a PRIVATE, unexported function applied inside two
+ * of its own parse functions (`parseUatItemsWithStats`, `parseCurrentTest`) —
+ * which is why two OTHER read sites in the same module (`cmdAuditUat`'s
+ * VERIFICATION and deferred-items.md ingresses) were missed: normalizing
+ * per-parser means every new parser must remember to call it. Promoted here,
+ * to the shared leaf module every document consumer can reach without a new
+ * dependency edge, so normalization can be applied at the READ boundary
+ * instead — every current and future parser fed from a boundary that calls
+ * this gets normalized text by construction.
+ *
+ * `/\r\n?/g` is deliberately ONE alternation, not two separate replaces: a
+ * two-pass `replace(/\r\n/g,'\n').replace(/\r/g,'\n')` is equivalent here
+ * because the first pass already consumes every CRLF pair before the second
+ * pass ever runs, but a single regex avoids relying on pass ORDER and matches
+ * greedily left-to-right in one scan, so a CRLF is always consumed as ONE
+ * unit (never left as a stray trailing `\r` after the `\n` half is matched
+ * first) and a lone CR — including one immediately followed by nothing, i.e.
+ * at EOF, or by another lone CR — is still replaced.
+ *
+ * This is deliberately NOT a length-preserving transform (CRLF, two UTF-16
+ * units, becomes LF, one), so any offsets a caller computes must be compared
+ * only against THIS normalized string, never against the original raw text.
+ *
+ * U+2028 LINE SEPARATOR / U+2029 PARAGRAPH SEPARATOR (#3078-CR) are
+ * DELIBERATELY NOT folded here, unlike `\r`/`\r\n`. Folding is unnecessary:
+ * `String.prototype.split('\n')` never treats U+2028/U+2029 as a delimiter,
+ * so an exotic separator can never manufacture a fake line start for a
+ * consumer that scans lines produced by `split('\n')`, rather than anchoring
+ * a multiline (`/m`) regex directly over unsplit text. Only the latter
+ * pattern is vulnerable to the ECMA-262 LineTerminator set including these
+ * two code points. This module performs no line-anchored matching of its
+ * own; a caller that scans lines should split first and match per-line
+ * rather than anchor `/m` over unsplit text — this comment makes no claim
+ * about whether any particular caller currently does so.
+ */
+function normalizeLineEndings(content) {
+    return content.replace(/\r\n?/g, '\n');
+}
 // ─── Path helpers ────────────────────────────────────────────────────────────
 /**
  * Normalize a relative path to always use forward slashes (cross-platform).
@@ -108,7 +175,19 @@ function pathExistsInternal(cwd, targetPath) {
         return false;
     }
 }
-function generateSlugInternal(text) {
+/**
+ * #3883 (ADR-3473 §8.3 remediation): `maxLen` lets a caller state its own
+ * truncation contract instead of being forced into this function's
+ * historical 60-char cap. Some call sites truncated at 60 before the #3883
+ * consolidation (commands.cts:cmdGenerateSlug) and some never truncated at
+ * all (phase-id.cts toDir/getPhaseDirFromPhaseId, the init.cts/phase-locator
+ * phase_slug sites, workstream-name-policy.cts toWorkstreamSlug) — collapsing
+ * every caller onto a single hard-coded 60 introduced two identity
+ * collisions (distinct >60-char names/phase-slugs truncating to the same
+ * value) that did not exist pre-migration. `maxLen: 60` remains the default
+ * so untouched callers keep prior behavior; pass `null` for no truncation.
+ */
+function generateSlugInternal(text, maxLen = 60) {
     if (!text)
         return null;
     // #2849: strip leading/trailing hyphens AFTER truncation, not only before.
@@ -116,7 +195,9 @@ function generateSlugInternal(text) {
     // the strip step exists to prevent. Truncation cannot add a leading hyphen, so
     // running the full ^-+|-+$ pass last is equivalent for leading hyphens and
     // fixes the trailing-hyphen-after-truncation case.
-    return transliterateForSlug(text).replace(/[^a-z0-9]+/g, '-').substring(0, 60).replace(/^-+|-+$/g, '');
+    const collapsed = transliterateForSlug(text).replace(/[^a-z0-9]+/g, '-');
+    const truncated = maxLen === null ? collapsed : collapsed.substring(0, maxLen);
+    return truncated.replace(/^-+|-+$/g, '');
 }
 // ─── Transliteration (#2848) ─────────────────────────────────────────────────
 //
@@ -195,16 +276,38 @@ function transliterateForSlug(text) {
  * Degrades on an unreadable directory instead of throwing: empty arrays,
  * every flag false, scope UNREADABLE (mirroring scanPhasePlans's own
  * degrade path).
+ *
+ * #4014 (epic #3473 B4-unreadable): this function's OWN readdirSync used to
+ * catch its own failure and then return `scope: scan.scope` — the scope of
+ * the UNRELATED, already-successful scanPhasePlans call — silently dropping
+ * that THIS read failed. The own-readdirSync is now routed through
+ * findContextMdIn's directory-string form (which never throws and reports
+ * its own SCOPE.UNREADABLE), and the two independently-scoped answers are
+ * combined into the worse of the two below — never letting a successful
+ * scan.scope mask this function's own failed read.
+ *
+ * The combination is written out as a two-value comparison rather than
+ * calling planning-snapshot.cts's `worstScope` directly: that module
+ * requires core-utils.cjs (for `findOrphanSummaries`) at its own top level,
+ * so importing it back here would create a tight, direct
+ * core-utils.cjs <-> planning-snapshot.cjs cycle — a materially different
+ * (and riskier) shape than this file's existing, documented lazy-access
+ * cyclic partners (planning-workspace.cjs, phase-id.cjs), which
+ * planning-snapshot.cts sits *above* in the dependency graph, not beside.
+ * `findContextMdIn`'s directory-string form can only ever report
+ * SCOPE.COMPLETE or SCOPE.UNREADABLE (a single readdirSync is binary — see
+ * its own doc comment), so per planning-snapshot.cts's SCOPE_SEVERITY
+ * ordering (UNREADABLE is maximal), `worstScope(scan.scope, ownScope)` is
+ * exactly `ownScope === UNREADABLE ? UNREADABLE : scan.scope` — the
+ * expression below is that identity, not a re-derivation of the ordering.
  */
 function getPhaseFileStats(phaseDir) {
     // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
     const scanPhasePlans = require('./plan-scan.cjs');
     const scan = scanPhasePlans(phaseDir);
-    let files;
-    try {
-        files = node_fs_1.default.readdirSync(phaseDir);
-    }
-    catch {
+    const { files, scope: ownScope } = planningWorkspace.findContextMdIn(phaseDir);
+    const scope = ownScope === SCOPE.UNREADABLE ? SCOPE.UNREADABLE : scan.scope;
+    if (ownScope === SCOPE.UNREADABLE) {
         return {
             plans: scan.planFiles,
             summaries: scan.summaryFiles,
@@ -212,18 +315,18 @@ function getPhaseFileStats(phaseDir) {
             hasContext: false,
             hasVerification: false,
             hasReviews: false,
-            scope: scan.scope,
+            scope,
         };
     }
-    const scopedFiles = scopeToPhase(files, node_path_1.default.basename(phaseDir));
+    const scopedFiles = phaseIdModule.scopeToPhase(files, node_path_1.default.basename(phaseDir));
     return {
         plans: scan.planFiles,
         summaries: scan.summaryFiles,
         hasResearch: scopedFiles.some(f => f.endsWith('-RESEARCH.md') || f === 'RESEARCH.md'),
-        hasContext: findContextMdIn(scopedFiles) !== null,
+        hasContext: planningWorkspace.findContextMdIn(scopedFiles) !== null,
         hasVerification: scopedFiles.some(f => f.endsWith('-VERIFICATION.md') || f === 'VERIFICATION.md'),
         hasReviews: scopedFiles.some(f => f.endsWith('-REVIEWS.md') || f === 'REVIEWS.md'),
-        scope: scan.scope,
+        scope,
     };
 }
 /**
@@ -235,7 +338,7 @@ function readSubdirectories(dirPath, sort = false) {
     try {
         const entries = node_fs_1.default.readdirSync(dirPath, { withFileTypes: true });
         const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
-        return sort ? dirs.sort((a, b) => comparePhaseNum(a, b)) : dirs;
+        return sort ? dirs.sort((a, b) => phaseIdModule.comparePhaseNum(a, b)) : dirs;
     }
     catch {
         return [];
@@ -415,6 +518,7 @@ function findOrphanSummaries(planFiles, summaryFiles) {
 }
 module.exports = {
     toPosixPath,
+    normalizeLineEndings,
     detectSubRepos,
     extractOneLinerFromBody,
     pathExistsInternal,