@pareto4/pp-core 1.5.0

package/pp-core/bin/lib/phase-id.cjs

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Pure phase-id parsing/matching helpers — normalize, token match,
+ * milestone/phase-dir id parsing, phase-markdown regex builders.
+ *
+ * Extracted from core.cts (ADR-857 rollout phase 2a / issue #865).
+ * The hand-written bodies are preserved byte-for-behaviour; only the module
+ * boundary moved. The core.cjs re-export spine was retired in epic #1267;
+ * callers import phase-id helpers from phase-id.cjs directly.
+ *
+ * Dependencies: none (pure string/regex, no Node built-ins required).
+ */
+// ─── Phase-id helpers ─────────────────────────────────────────────────────────
+function escapeRegex(value) {
+    return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function normalizePhaseName(phase) {
+    const str = String(phase);
+    // Strip optional project_code prefix (e.g., 'CK-01' → '01')
+    const stripped = str.replace(/^[A-Z]{1,6}-(?=\d)/, '');
+    // Milestone-prefixed phase IDs: M-NN or M-N-N (deep decomposition).
+    const milestoneMatch = stripped.match(/^(\d+)((?:-\d+)+)([A-Z]?(?:\.\d+)*)$/i);
+    if (milestoneMatch) {
+        const major = milestoneMatch[1].padStart(2, '0');
+        const subSegments = milestoneMatch[2].slice(1).split('-').map(s => s.padStart(2, '0'));
+        const suffix = milestoneMatch[3] || '';
+        return `${major}-${subSegments.join('-')}${suffix}`;
+    }
+    // Standard numeric phases: 1, 01, 12A, 12.1
+    const match = stripped.match(/^(\d+)([A-Z])?((?:\.\d+)*)/i);
+    if (match) {
+        const padded = match[1].padStart(2, '0');
+        // Preserve original case of letter suffix (#1962).
+        const letter = match[2] || '';
+        const decimal = match[3] || '';
+        return padded + letter + decimal;
+    }
+    // Custom phase IDs (e.g. PROJ-42, AUTH-101): return as-is
+    return str;
+}
+function getMilestoneFromPhaseId(phaseId) {
+    const str = String(phaseId);
+    const stripped = str.replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+    const m = stripped.match(/^0*(\d+)-\d/);
+    if (!m)
+        return null;
+    const major = parseInt(m[1], 10);
+    if (major === 0 || major === 999)
+        return null;
+    return `v${major}.0`;
+}
+function getPhaseDirFromPhaseId(phaseId, phaseName, projectCode) {
+    const str = String(phaseId);
+    const stripped = str.replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+    const m = stripped.match(/^0*(\d+)-(0*(\d+(?:-\d+)*))$/);
+    if (!m)
+        return null;
+    const milestone = String(parseInt(m[1], 10)).padStart(2, '0');
+    const subParts = m[2].split('-').map(p => String(parseInt(p, 10)).padStart(2, '0'));
+    const sub = subParts.join('-');
+    const slug = phaseName
+        ? phaseName.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+        : '';
+    const parts = [milestone, sub, slug].filter(Boolean);
+    const base = parts.join('-');
+    return projectCode ? `${projectCode}-${base}` : base;
+}
+/**
+ * Render a regex source fragment matching a phase number against ROADMAP/STATE
+ * prose regardless of zero-padding on either side.
+ */
+function phaseMarkdownRegexSource(phaseNum) {
+    const stripped = String(phaseNum).replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+    // Milestone-prefixed IDs: M-NN or M-N-N (deep).
+    const milestoneSegments = stripped.match(/^(\d+)((?:-\d+)*)([A-Z]?(?:\.\d+)*)$/i);
+    if (milestoneSegments && milestoneSegments[2]) {
+        const majorUnpadded = milestoneSegments[1].replace(/^0+/, '') || '0';
+        const subParts = milestoneSegments[2].slice(1).split('-');
+        const subFragments = subParts.map(s => {
+            const unpadded = s.replace(/^0+/, '') || '0';
+            return `0*${escapeRegex(unpadded)}`;
+        });
+        const suffix = milestoneSegments[3] || '';
+        const suffixFragment = suffix ? escapeRegex(suffix) : '';
+        return `0*${escapeRegex(majorUnpadded)}-${subFragments.join('-')}${suffixFragment}`;
+    }
+    // Plain numeric phase: 1, 01, 12A, 12.1
+    const match = stripped.match(/^0*(\d+)([A-Z])?((?:\.\d+)*)$/i);
+    if (!match)
+        return escapeRegex(phaseNum);
+    const integer = match[1].replace(/^0+/, '') || '0';
+    const letter = match[2] ? escapeRegex(match[2]) : '';
+    const decimal = match[3] ? escapeRegex(match[3]) : '';
+    return `0*${escapeRegex(integer)}${letter}${decimal}`;
+}
+/**
+ * #3599: when the caller passed a project-code-prefixed ID like `PROJ-42`,
+ * return the exact-escaped form.
+ */
+function phaseMarkdownRegexSourceExact(phaseNum) {
+    const raw = String(phaseNum);
+    if (!/^[A-Z]{1,6}-(?=\d)/i.test(raw))
+        return null;
+    return escapeRegex(raw);
+}
+function comparePhaseNum(a, b) {
+    // Strip optional project_code prefix before comparing
+    const sa = String(a).replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+    const sb = String(b).replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+    const milestoneA = sa.match(/^(\d+)((?:-\d+)+)([A-Z]?(?:\.\d+)*)$/i);
+    const milestoneB = sb.match(/^(\d+)((?:-\d+)+)([A-Z]?(?:\.\d+)*)$/i);
+    if (milestoneA && milestoneB) {
+        const segsA = [parseInt(milestoneA[1], 10), ...milestoneA[2].slice(1).split('-').map(s => parseInt(s, 10))];
+        const segsB = [parseInt(milestoneB[1], 10), ...milestoneB[2].slice(1).split('-').map(s => parseInt(s, 10))];
+        const maxSegs = Math.max(segsA.length, segsB.length);
+        for (let i = 0; i < maxSegs; i++) {
+            const av = segsA[i] !== undefined ? segsA[i] : 0;
+            const bv = segsB[i] !== undefined ? segsB[i] : 0;
+            if (av !== bv)
+                return av - bv;
+        }
+        const sufA = milestoneA[3] || '';
+        const sufB = milestoneB[3] || '';
+        if (sufA !== sufB)
+            return sufA < sufB ? -1 : 1;
+        return 0;
+    }
+    if (milestoneA || milestoneB)
+        return String(a).localeCompare(String(b));
+    const pa = sa.match(/^(\d+)([A-Z])?((?:\.\d+)*)/i);
+    const pb = sb.match(/^(\d+)([A-Z])?((?:\.\d+)*)/i);
+    if (!pa || !pb)
+        return String(a).localeCompare(String(b));
+    const intDiff = parseInt(pa[1], 10) - parseInt(pb[1], 10);
+    if (intDiff !== 0)
+        return intDiff;
+    const la = (pa[2] || '').toUpperCase();
+    const lb = (pb[2] || '').toUpperCase();
+    if (la !== lb) {
+        if (!la)
+            return -1;
+        if (!lb)
+            return 1;
+        return la < lb ? -1 : 1;
+    }
+    const aDecParts = pa[3] ? pa[3].slice(1).split('.').map(p => parseInt(p, 10)) : [];
+    const bDecParts = pb[3] ? pb[3].slice(1).split('.').map(p => parseInt(p, 10)) : [];
+    const maxLen = Math.max(aDecParts.length, bDecParts.length);
+    if (aDecParts.length === 0 && bDecParts.length > 0)
+        return -1;
+    if (bDecParts.length === 0 && aDecParts.length > 0)
+        return 1;
+    for (let i = 0; i < maxLen; i++) {
+        const av = Number.isFinite(aDecParts[i]) ? aDecParts[i] : 0;
+        const bv = Number.isFinite(bDecParts[i]) ? bDecParts[i] : 0;
+        if (av !== bv)
+            return av - bv;
+    }
+    return 0;
+}
+/**
+ * Extract the phase token from a directory name.
+ */
+function extractPhaseToken(dirName) {
+    const codePrefixMatch = dirName.match(/^([A-Z]{1,6})-(\d.*)/i);
+    let prefix = '';
+    let rest = dirName;
+    if (codePrefixMatch) {
+        prefix = codePrefixMatch[1] + '-';
+        rest = codePrefixMatch[2];
+    }
+    const segments = rest.split('-');
+    const tokenSegments = [];
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        if (/^\d/.test(seg) || (i === 0 && /^[A-Za-z]{1,3}\d/.test(seg))) {
+            tokenSegments.push(seg);
+        }
+        else {
+            break;
+        }
+    }
+    if (tokenSegments.length === 0) {
+        return dirName;
+    }
+    return prefix + tokenSegments.join('-');
+}
+/**
+ * Check if a directory name's phase token matches the normalized phase exactly.
+ */
+function phaseTokenMatches(dirName, normalized) {
+    const token = extractPhaseToken(dirName);
+    if (token.toUpperCase() === normalized.toUpperCase())
+        return true;
+    const stripped = dirName.replace(/^[A-Z]{1,6}-(?=\d)/i, '');
+    if (stripped !== dirName) {
+        const strippedToken = extractPhaseToken(stripped);
+        if (strippedToken.toUpperCase() === normalized.toUpperCase())
+            return true;
+    }
+    return false;
+}
+module.exports = {
+    escapeRegex,
+    normalizePhaseName,
+    getMilestoneFromPhaseId,
+    getPhaseDirFromPhaseId,
+    phaseMarkdownRegexSource,
+    phaseMarkdownRegexSourceExact,
+    comparePhaseNum,
+    extractPhaseToken,
+    phaseTokenMatches,
+};

package/pp-core/bin/lib/phase-lifecycle.cjs

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Phase Lifecycle Pure Helpers — pure-computation functions extracted from
+ * the phase-lifecycle SDK handler (ADR-457 build-at-publish: the hand-written
+ * bin/lib/phase-lifecycle.cjs collapsed to a TypeScript source of truth).
+ * Behaviour is preserved byte-for-behaviour from the prior hand-written .cjs;
+ * only types are added.
+ *
+ * I/O adapter pattern (ADR-3524 Section 4): each side supplies its own I/O
+ * (sync readFileSync for CJS, async readFile for SDK); the pure computation
+ * logic is shared via this generated artifact.
+ *
+ * Scope:
+ *   - deriveProgressFromRoadmap(roadmapContent): count Complete rows => idempotent
+ *   - clampPercent(completed, total): percent with 100 ceiling
+ *
+ * These two functions are the root-cause fix for issue #4.
+ *
+ * References:
+ *   - ADR-3524 (docs/adr/3524-cjs-sdk-hard-seam.md)
+ *   - Issue #4 (upstream gsd-core)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveProgressFromRoadmap = deriveProgressFromRoadmap;
+exports.clampPercent = clampPercent;
+/**
+ * Derive completed_phases, total_phases, and total_plans from ROADMAP content.
+ * Root cause fix for issue #4 — see gen-phase-lifecycle.mjs for full documentation.
+ */
+function deriveProgressFromRoadmap(roadmapContent) {
+    let completedPhases = null;
+    let totalPhases = null;
+    let totalPlans = null;
+    try {
+        // Count Complete rows in the progress table (Status column = "Complete").
+        // Pattern: row where the phase cell starts with a digit (data row, not header),
+        // followed by any cell content, then a "Complete" status cell.
+        // Handles both short form ("| 4. |") and long form ("| 01. Foundation |").
+        // See phase-lifecycle.ts ~line 1655 for the original SDK pattern.
+        const tableCompletePattern = /\|\s*\d+[^|]*\|\s*[^|]*\|\s*Complete\s*\|/gi;
+        const completeMatches = roadmapContent.match(tableCompletePattern);
+        completedPhases = completeMatches ? completeMatches.length : null;
+        // Count total phase rows in the progress table.
+        // Identify the table by looking for Phase|...|Status|...|Completed header.
+        const progressTableMatch = roadmapContent.match(/\|\s*Phase\s*\|[^|]*\|[^|]*Status[^|]*\|[^|]*Completed[^|]*\|[\s\S]*?(?=\n\n|\n##|$)/i);
+        if (progressTableMatch) {
+            const tableText = progressTableMatch[0];
+            // Count data rows (rows starting with pipe then a phase number)
+            const dataRowPattern = /^\|\s*\d+/gm;
+            const dataRows = tableText.match(dataRowPattern);
+            totalPhases = dataRows ? dataRows.length : null;
+        }
+        // Sum plan counts from M/N columns in progress table
+        let totalPlansSum = 0;
+        const planCellPattern = /\|\s*\d+[^|]*\|\s*(\d+)\/(\d+)\s*\|/gi;
+        let pm;
+        while ((pm = planCellPattern.exec(roadmapContent)) !== null) {
+            totalPlansSum += parseInt(pm[2], 10);
+        }
+        if (totalPlansSum > 0)
+            totalPlans = totalPlansSum;
+    }
+    catch { /* intentionally empty — fall through to existing values */ }
+    return { completedPhases, totalPhases, totalPlans };
+}
+/**
+ * Compute progress percent clamped to 100.
+ * Root cause fix for issue #4 — see gen-phase-lifecycle.mjs for full documentation.
+ */
+function clampPercent(completed, total) {
+    if (!total || total <= 0)
+        return 0;
+    return Math.min(100, Math.round((completed / total) * 100));
+}

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

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Phase Locator — Phase-directory search and location
+ *
+ * ADR-857 rollout phase 2d: extracted from core.cts (issue #881).
+ * Owns active-phase discovery against the `.planning/phases/` tree
+ * (`searchPhaseInDir`, `findPhaseInternal`) and archived-phase-dir
+ * enumeration (`getArchivedPhaseDirs`), matching phase ids/tokens against
+ * the filesystem. Behaviour is preserved byte-for-behaviour from the prior
+ * location; only the module boundary moved. The core.cjs re-export spine
+ * was retired in epic #1267; callers import phase-locator helpers directly.
+ *
+ * Dependencies (leaf modules only — no loadConfig):
+ *   - node:fs / node:path (stdlib)
+ *   - ./phase-id.cjs       (normalizePhaseName, phaseTokenMatches, extractPhaseToken)
+ *   - ./core-utils.cjs     (readSubdirectories, getPhaseFileStats, extractCanonicalPlanId, toPosixPath)
+ *   - ./planning-workspace.cjs (planningDir)
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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 { normalizePhaseName, phaseTokenMatches, extractPhaseToken } = phaseIdModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const coreUtilsModule = require("./core-utils.cjs");
+const { readSubdirectories, getPhaseFileStats, extractCanonicalPlanId, toPosixPath } = coreUtilsModule;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspace = require("./planning-workspace.cjs");
+const { planningDir } = planningWorkspace;
+// ─── Phase search helpers ─────────────────────────────────────────────────────
+function searchPhaseInDir(baseDir, relBase, normalized) {
+    try {
+        const dirs = readSubdirectories(baseDir, true);
+        const match = dirs.find(d => phaseTokenMatches(d, normalized));
+        if (!match)
+            return null;
+        const phaseToken = extractPhaseToken(match);
+        const phaseNumber = phaseToken || normalized;
+        const afterToken = match.slice(phaseToken ? phaseToken.length : 0).replace(/^-/, '');
+        const phaseName = afterToken || null;
+        const phaseDir = node_path_1.default.join(baseDir, match);
+        const { plans: unsortedPlans, summaries: unsortedSummaries, hasResearch, hasContext, hasVerification, hasReviews } = getPhaseFileStats(phaseDir);
+        const plans = unsortedPlans.sort();
+        const summaries = unsortedSummaries.sort();
+        const completedPlanIds = new Set(summaries.flatMap(s => {
+            const exact = s.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
+            const canonical = extractCanonicalPlanId(s);
+            return canonical === exact ? [exact] : [exact, canonical];
+        }));
+        const incompletePlans = plans.filter(p => {
+            const planId = p.replace('-PLAN.md', '').replace('PLAN.md', '');
+            const canonical = extractCanonicalPlanId(p);
+            return !completedPlanIds.has(planId) && !completedPlanIds.has(canonical);
+        });
+        return {
+            found: true,
+            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,
+            plans,
+            summaries,
+            incomplete_plans: incompletePlans,
+            has_research: hasResearch,
+            has_context: hasContext,
+            has_verification: hasVerification,
+            has_reviews: hasReviews,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function findPhaseInternal(cwd, phase) {
+    if (!phase)
+        return null;
+    const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
+    const normalized = normalizePhaseName(phase);
+    const relPhasesDir = toPosixPath(node_path_1.default.relative(cwd, phasesDir));
+    const current = searchPhaseInDir(phasesDir, relPhasesDir, normalized);
+    if (current)
+        return current;
+    const milestonesDir = node_path_1.default.join(cwd, '.planning', 'milestones');
+    if (!node_fs_1.default.existsSync(milestonesDir))
+        return null;
+    try {
+        const milestoneEntries = node_fs_1.default.readdirSync(milestonesDir, { withFileTypes: true });
+        const archiveDirs = milestoneEntries
+            .filter(e => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name))
+            .map(e => e.name)
+            .sort()
+            .reverse();
+        for (const archiveName of archiveDirs) {
+            const versionMatch = archiveName.match(/^(v[\d.]+)-phases$/);
+            const version = versionMatch[1];
+            const archivePath = node_path_1.default.join(milestonesDir, archiveName);
+            const relBase = '.planning/milestones/' + archiveName;
+            const result = searchPhaseInDir(archivePath, relBase, normalized);
+            if (result) {
+                result.archived = version;
+                return result;
+            }
+        }
+    }
+    catch { /* intentionally empty */ }
+    return null;
+}
+function getArchivedPhaseDirs(cwd) {
+    const milestonesDir = node_path_1.default.join(cwd, '.planning', 'milestones');
+    const results = [];
+    if (!node_fs_1.default.existsSync(milestonesDir))
+        return results;
+    try {
+        const milestoneEntries = node_fs_1.default.readdirSync(milestonesDir, { withFileTypes: true });
+        const phaseDirs = milestoneEntries
+            .filter(e => e.isDirectory() && /^v[\d.]+-phases$/.test(e.name))
+            .map(e => e.name)
+            .sort()
+            .reverse();
+        for (const archiveName of phaseDirs) {
+            const versionMatch = archiveName.match(/^(v[\d.]+)-phases$/);
+            const version = versionMatch[1];
+            const archivePath = node_path_1.default.join(milestonesDir, archiveName);
+            const dirs = readSubdirectories(archivePath, true);
+            for (const dir of dirs) {
+                results.push({
+                    name: dir,
+                    milestone: version,
+                    basePath: node_path_1.default.join('.planning', 'milestones', archiveName),
+                    fullPath: node_path_1.default.join(archivePath, dir),
+                });
+            }
+        }
+    }
+    catch { /* intentionally empty */ }
+    return results;
+}
+module.exports = {
+    searchPhaseInDir,
+    findPhaseInternal,
+    getArchivedPhaseDirs,
+};