@opengsd/gsd-core 1.11.0 → 1.13.0

package/gsd-core/bin/lib/phase-locator.cjs

@@ -29,7 +29,7 @@ const coreUtilsModule = require("./core-utils.cjs");
 const { readSubdirectories, getPhaseFileStats, extractCanonicalPlanId, toPosixPath, findUnsummarizedPlans } = coreUtilsModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
-const { planningDir } = planningWorkspace;
+const { planningDir, planningRoot } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatterModule = require("./frontmatter.cjs");
 const { extractFrontmatter } = frontmatterModule;
@@ -95,24 +95,56 @@ function compareArchiveVersionDesc(aName, bName) {
     }
     return 0;
 }
-function listArchiveVersionDirs(cwd) {
-    const milestonesDir = node_path_1.default.join(planningDir(cwd), 'milestones');
-    if (!node_fs_1.default.existsSync(milestonesDir))
-        return [];
+function listArchiveVersionDirs(cwd, wsOverride) {
+    // #3804: enumerate BOTH archive shapes under the CURRENT SCOPE's milestones
+    // tree (planningDir — GSD_WORKSTREAM/GSD_PROJECT-aware, exactly the
+    // #2855 scoping findPhaseInternal and getArchivedPhaseDirs rely on):
+    //   flat:               <scope>/milestones/vX.Y-phases/<phase-dir>/
+    //   workstream archive: <scope>/milestones/ws-<slug>-<date>/phases/<phase-dir>/
+    // Pre-#3804 only the flat shape matched, so workstream-archived milestones
+    // were invisible (the reporter's repo: 20 hidden phase artifacts). The
+    // ws-* shape's phase dirs sit one level deeper (under phases/) and its dir
+    // name fails ^v[\d.]+-phases$ — both the name AND the level are modeled.
+    // Version labels: flat keeps the bare vX.Y; ws-* shapes carry the dir name
+    // (no numeric version). Flat-newest-first (compareArchiveVersionDesc), then
+    // ws dirs by name descending — deterministic. The AUDIT's cross-workstream
+    // enumeration (audit.cts listAuditPhaseTargets) calls this helper once per
+    // tree (root + each workstream) rather than widening this scope — the
+    // #2855 no-leak contract for findPhaseInternal/getArchivedPhaseDirs is
+    // preserved untouched.
+    const milestonesDir = node_path_1.default.join(planningDir(cwd, wsOverride ?? undefined), 'milestones');
+    const out = [];
+    const seen = new Set();
+    const pushVersion = (version, archivePath) => {
+        const rel = toPosixPath(node_path_1.default.relative(cwd, archivePath));
+        if (seen.has(rel))
+            return;
+        seen.add(rel);
+        out.push({ version, archivePath });
+    };
+    let entries;
     try {
-        const milestoneEntries = node_fs_1.default.readdirSync(milestonesDir, { withFileTypes: true });
-        return milestoneEntries
-            .filter(e => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name))
-            .map(e => e.name)
-            .sort(compareArchiveVersionDesc)
-            .map(archiveName => ({
-            version: archiveName.match(/^(v[\d.]+)-phases$/)[1],
-            archivePath: node_path_1.default.join(milestonesDir, archiveName),
-        }));
+        entries = node_fs_1.default.readdirSync(milestonesDir, { withFileTypes: true });
     }
     catch {
         return [];
     }
+    const flat = entries
+        .filter(e => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name))
+        .map(e => e.name)
+        .sort(compareArchiveVersionDesc);
+    for (const archiveName of flat) {
+        pushVersion(archiveName.match(/^(v[\d.]+)-phases$/)[1], node_path_1.default.join(milestonesDir, archiveName));
+    }
+    const wsDirs = entries
+        .filter(e => e.isDirectory() && /^ws-/.test(e.name))
+        .map(e => e.name)
+        .sort()
+        .reverse();
+    for (const wsName of wsDirs) {
+        pushVersion(wsName, node_path_1.default.join(milestonesDir, wsName, 'phases'));
+    }
+    return out;
 }
 function searchPhaseInDir(baseDir, relBase, normalized) {
     try {
@@ -211,7 +243,12 @@ function searchPhaseInDir(baseDir, relBase, normalized) {
             directory: toPosixPath(node_path_1.default.join(relBase, match)),
             phase_number: phaseNumber,
             phase_name: phaseName,
-            phase_slug: phaseName ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') : null,
+            // #3883 (ADR-3473 §8.3): delegate to the canonical slug formula
+            // (generateSlugInternal, core-utils.cts) rather than re-implementing
+            // it. `maxLen: null` preserves this site's pre-migration untruncated
+            // contract — the 60-char default would drop an on-disk phase slug's
+            // reported value out of sync with the real directory name.
+            phase_slug: phaseName ? coreUtilsModule.generateSlugInternal(phaseName, null) : null,
             plans,
             summaries,
             incomplete_plans: incompletePlans,
@@ -339,13 +376,56 @@ function listMilestonePhaseDirs(phasesDir, opts = {}) {
         .sort((a, b) => comparePhaseNum(a, b));
     return { value, scope };
 }
-function getArchivedPhaseDirs(cwd) {
+/**
+ * #3882 (ADR-3473 §8.2, issue #3882): the single owner of "the PHYSICAL set
+ * of phase directories on disk, entirely un-windowed" — the OTHER axis
+ * `listMilestonePhaseDirs` above deliberately does not offer. That owner
+ * refuses sentinels UNCONDITIONALLY (see its own doc comment); it has no way
+ * to say "physical set, sentinels included". That is exactly what an
+ * archival, lookup-index, or health-sweep caller needs — e.g. a heading ->
+ * directory lookup index that must resolve a directory regardless of
+ * milestone window (`cmdRoadmapAnalyze`'s `_phaseDirNames`,
+ * `cmdInitMilestoneOp`'s `diskPhaseDirs`) — which is why those callers used
+ * to hand-roll a `readdirSync` instead of calling either owner.
+ *
+ * `includeSentinels` is REQUIRED, with no default value. #3882/ADR-3473 §8.2:
+ * "a caller that wants sentinels asks for them explicitly" — obtaining
+ * sentinel-inclusion by silent omission is exactly the defect class this
+ * axis exists to close, so the call site is refused at COMPILE TIME without
+ * it, not merely documented against it here.
+ *
+ * Mirrors `listMilestonePhaseDirs`'s own absent/unreadable handling
+ * (ADR-3180 Decision 2): an ABSENT `phasesDir` is a real empty (a project
+ * with no phase directories yet), `scope: SCOPE.COMPLETE`; a `phasesDir`
+ * that EXISTS but cannot be read is a NON-answer, `scope: SCOPE.UNREADABLE`
+ * — a caller must not treat that empty list as "this project has no
+ * phases."
+ */
+function listAllPhaseDirs(phasesDir, opts) {
+    const { includeSentinels, phaseIdConvention = null } = opts;
+    if (!node_fs_1.default.existsSync(phasesDir))
+        return { value: [], scope: SCOPE.COMPLETE };
+    let names;
+    try {
+        names = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return { value: [], scope: SCOPE.UNREADABLE };
+    }
+    const value = names
+        .filter((name) => includeSentinels || !isSentinelPhaseId(name, phaseIdConvention ?? undefined))
+        .sort((a, b) => comparePhaseNum(a, b));
+    return { value, scope: SCOPE.COMPLETE };
+}
+function getArchivedPhaseDirs(cwd, wsOverride) {
     // #2855: same workstream-scoped resolution as findPhaseInternal above, via
     // the shared listArchiveVersionDirs helper. `phase.list --include-archived`
     // (the primary non-init consumer) must not leak a different workstream's
     // archive either.
     const results = [];
-    for (const { version, archivePath } of listArchiveVersionDirs(cwd)) {
+    for (const { version, archivePath } of listArchiveVersionDirs(cwd, wsOverride)) {
         const dirs = readSubdirectories(archivePath, true);
         for (const dir of dirs) {
             results.push({
@@ -358,9 +438,50 @@ function getArchivedPhaseDirs(cwd) {
     }
     return results;
 }
+/**
+ * #3804 — the CROSS-WORKSTREAM archive enumeration the audit surfaces need.
+ * getArchivedPhaseDirs above is deliberately #2855-SCOPED (an ambient
+ * workstream must not leak other trees' phases to findPhaseInternal), but
+ * audit-uat's charter (#2766: outstanding items do not stop mattering) is
+ * cross-workstream: enumerate the project root plus every workstream's own
+ * milestones tree, labeling workstream entries '<ws>/<version>' so
+ * acknowledge-by-label stays unambiguous. Deduped by full path (the same
+ * tree cannot be reached twice, but the guard keeps the invariant explicit).
+ */
+function getAllArchivedPhaseDirs(cwd) {
+    const out = [];
+    const seen = new Set();
+    const collect = (labelPrefix, wsOverride) => {
+        for (const archived of getArchivedPhaseDirs(cwd, wsOverride)) {
+            const rel = toPosixPath(node_path_1.default.relative(cwd, archived.fullPath));
+            if (seen.has(rel))
+                continue;
+            seen.add(rel);
+            out.push({ ...archived, milestone: `${labelPrefix}${archived.milestone}` });
+        }
+    };
+    collect('', null);
+    const workstreamsDir = node_path_1.default.join(planningRoot(cwd), 'workstreams');
+    try {
+        const wsEntries = node_fs_1.default.readdirSync(workstreamsDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort()
+            .reverse();
+        for (const ws of wsEntries) {
+            collect(`${ws}/`, ws);
+        }
+    }
+    catch {
+        /* no workstreams dir — the root pass above already ran */
+    }
+    return out;
+}
 module.exports = {
     searchPhaseInDir,
     findPhaseInternal,
     getArchivedPhaseDirs,
+    getAllArchivedPhaseDirs,
     listMilestonePhaseDirs,
+    listAllPhaseDirs,
 };