peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/openspec/coverage-evidence-reader.js

@@ -0,0 +1,386 @@
+/**
+ * Coverage Evidence reader for c8 `coverage-summary.json` (Fix-6B).
+ *
+ * Slice rid-Fix-6B / sub-slice T1:
+ *   - pure helper module, no side effects beyond FS reads
+ *   - reads the istanbul-reporter JSON shape emitted by `c8 --reporter=json-summary`
+ *     (the project's coverage tool — see scripts/coverage-c8.mjs)
+ *   - resolves a `coverage-summary.json` from a fixed discovery order
+ *   - validates per-capability coverage against a `## Capability Mapping` block
+ *
+ * The module is hermetic: every function takes its inputs explicitly and returns
+ * either a typed success result or a typed error code. There is no global state.
+ * Throws only when the input shape is structurally malformed (the caller cannot
+ * recover by branching on a Result variant); otherwise returns Result<T, Code>.
+ *
+ * Conventions:
+ *   - All paths are POSIX-normalized for JSON safety.
+ *   - The c8 summary's per-file keys are project-root-relative POSIX paths
+ *     (e.g. `src/services/openspec/openspec-archive-service.ts`).
+ *   - Capability mapping `source` field is also project-root-relative, may be
+ *     a file (`foo.ts`) or a directory (`src/services/openspec/`).
+ */
+import { posix, relative, resolve } from 'node:path';
+import { readFile, stat } from 'node:fs/promises';
+import { isDirectory } from 'peaks-loop-shared/fs';
+import { ok, err } from './artifact-boundary.js';
+// ---------------------------------------------------------------------------
+// Discovery
+// ---------------------------------------------------------------------------
+const DEFAULT_DISCOVERY = [
+    (root) => `${root}/coverage/coverage-summary.json`,
+    (root) => `${root}/openspec/coverage-summary.json`,
+];
+/**
+ * Resolve the path to a coverage-summary.json.
+ *
+ * Discovery order (per Fix-6B AC1):
+ *   1. `explicitPath` (passed via `--coverage-summary`)
+ *   2. `<projectRoot>/coverage/coverage-summary.json` (c8 wrapper default)
+ *   3. `<projectRoot>/openspec/coverage-summary.json` (per-project override)
+ *
+ * Returns:
+ *   - `{ ok: true, value: path }` when the file exists.
+ *   - `{ ok: false, error: { code: 'missing', triedPaths } }` otherwise.
+ */
+export async function resolveCoverageSummaryPath(input) {
+    const triedPaths = [];
+    if (input.explicitPath !== undefined) {
+        const abs = resolve(input.explicitPath);
+        triedPaths.push(abs);
+        if (await isReadable(abs)) {
+            return ok(abs);
+        }
+        return err({ code: 'not-readable', path: abs, message: `Cannot read coverage summary at ${abs}` });
+    }
+    for (const factory of DEFAULT_DISCOVERY) {
+        const candidate = factory(toPosix(input.projectRoot));
+        triedPaths.push(candidate);
+        if (await isReadable(candidate)) {
+            return ok(candidate);
+        }
+    }
+    return err({ code: 'missing', triedPaths });
+}
+function toPosix(p) {
+    return p.replace(/\\/g, '/').replace(/\/$/, '');
+}
+async function isReadable(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Parse
+// ---------------------------------------------------------------------------
+/**
+ * Read and parse a coverage-summary.json into a typed `CoverageSummary`.
+ *
+ * Expected istanbul-reporter shape:
+ *
+ *     {
+ *       "total": { "lines": { "pct": 100, ... }, ... },
+ *       "src/foo.ts": { "lines": { "pct": 100, ... }, ... },
+ *       ...
+ *     }
+ *
+ * Throws only on structural malformation (caller cannot branch on a Result).
+ * The fix-6B gate handles a missing summary via the discovery layer, not here.
+ */
+export async function readC8Summary(path) {
+    const raw = await readFile(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`coverage summary at ${path} is not a JSON object`);
+    }
+    const obj = parsed;
+    const files = new Map();
+    for (const [key, value] of Object.entries(obj)) {
+        if (key === 'total')
+            continue;
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            continue;
+        const entry = value;
+        const lines = asMetric(entry['lines']);
+        const statements = asMetric(entry['statements']);
+        const functions = asMetric(entry['functions']);
+        const branches = asMetric(entry['branches']);
+        if (lines === null || statements === null || functions === null || branches === null) {
+            continue;
+        }
+        const normalizedKey = posix.normalize(key.replace(/\\/g, '/'));
+        files.set(normalizedKey, {
+            path: normalizePathSep(normalizedKey),
+            relativePath: normalizedKey,
+            statements,
+            branches,
+            functions,
+            lines,
+        });
+    }
+    const stat_ = await stat(path);
+    return {
+        path,
+        capturedAt: stat_.mtime.toISOString(),
+        files,
+    };
+}
+function asMetric(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        return null;
+    const obj = input;
+    const pct = obj['pct'];
+    const covered = obj['covered'];
+    const total = obj['total'];
+    if (typeof pct !== 'number' || typeof covered !== 'number' || typeof total !== 'number')
+        return null;
+    return { pct, covered, total };
+}
+function normalizePathSep(p) {
+    return p.replace(/\\/g, '/');
+}
+// ---------------------------------------------------------------------------
+// Capability Mapping block parser (proposal.md)
+// ---------------------------------------------------------------------------
+/**
+ * Parse the `## Capability Mapping` block out of a proposal.md.
+ *
+ * Accepted shape (markdown table):
+ *
+ *     ## Capability Mapping
+ *
+ *     | capability | source | testAnchor |
+ *     | --- | --- | --- |
+ *     | quality-gates | src/services/openspec/openspec-archive-service.ts | tests/unit/openspec-archive-service.test.ts |
+ *     | artifact-workspace | src/services/openspec/artifact-boundary.ts | tests/unit/services/openspec/artifact-boundary.test.ts |
+ *
+ * Returns `{ present: false }` when the heading is missing (Fix-6B back-compat:
+ * the change does not declare a mapping, so no per-capability check is possible
+ * and the gate stays at Fix-6A's declarative level).
+ */
+export async function parseCapabilityMapping(proposalPath) {
+    let raw;
+    try {
+        raw = await readFile(proposalPath, 'utf8');
+    }
+    catch {
+        return { rows: [], present: false };
+    }
+    const lines = raw.split(/\r?\n/);
+    const headingIdx = lines.findIndex((line) => /^##\s+Capability\s+Mapping\s*$/.test(line));
+    if (headingIdx === -1) {
+        return { rows: [], present: false };
+    }
+    const rows = [];
+    let i = headingIdx + 1;
+    let inFence = false;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line === undefined)
+            break;
+        if (!inFence && /^##\s+/.test(line))
+            break;
+        if (/^```/.test(line.trim())) {
+            inFence = !inFence;
+            i += 1;
+            continue;
+        }
+        const parsed = parseCapabilityRow(line);
+        if (parsed !== null) {
+            rows.push({ ...parsed, line: i + 1 });
+        }
+        i += 1;
+    }
+    return { rows, present: true };
+}
+function parseCapabilityRow(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|'))
+        return null;
+    const cells = trimmed.split('|').slice(1, -1).map((c) => c.trim());
+    if (cells.length < 2)
+        return null;
+    const capability = cells[0];
+    const source = cells[1];
+    const testAnchor = cells[2];
+    if (capability === undefined || source === undefined)
+        return null;
+    if (capability.toLowerCase() === 'capability' && source.toLowerCase() === 'source')
+        return null;
+    if (/^-+$/.test(capability.replace(/\s+/g, '')))
+        return null;
+    const row = {
+        capability,
+        source: source.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, ''),
+    };
+    if (testAnchor !== undefined && testAnchor !== '') {
+        row.testAnchor = testAnchor;
+    }
+    return row;
+}
+// ---------------------------------------------------------------------------
+// Resolve files for a capability row
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the source files that a capability row covers.
+ *
+ * - File path: returns `[file]`.
+ * - Directory path: returns every `*.ts` file recursively under it (relative
+ *   to `projectRoot`, POSIX separators). Non-TS files are excluded because
+ *   c8 only collects coverage on TS source modules.
+ */
+export async function resolveCapabilityFiles(input) {
+    const abs = resolve(input.projectRoot, input.row.source);
+    if (!(await isDirectory(abs))) {
+        const rel = relative(input.projectRoot, abs).replace(/\\/g, '/');
+        return [rel];
+    }
+    return await walkTsFiles(abs, input.projectRoot);
+}
+async function walkTsFiles(absRoot, projectRoot) {
+    // Lightweight walk; avoids pulling in fast-glob for one offscreen consumer.
+    const { readdir } = await import('node:fs/promises');
+    const out = [];
+    const stack = [absRoot];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = `${dir}/${entry.name}`;
+            if (entry.isDirectory()) {
+                stack.push(full);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.ts')) {
+                const rel = relative(projectRoot, full).replace(/\\/g, '/');
+                out.push(rel);
+            }
+        }
+    }
+    return out.sort();
+}
+// ---------------------------------------------------------------------------
+// Validate
+// ---------------------------------------------------------------------------
+/**
+ * Validate per-capability coverage. Each capability row's `source` is resolved
+ * to one or more files; each file must appear in the c8 summary with all four
+ * metrics at exactly 100%.
+ *
+ * Returns `{ ok: true }` when every capability passes; `{ ok: false, mismatches }`
+ * otherwise. The caller is responsible for rendering the mismatches into the
+ * `OPENSPEC_COVERAGE_EVIDENCE_MISMATCH` error envelope.
+ */
+export async function validateCapabilityCoverage(input) {
+    const mismatches = [];
+    for (const row of input.rows) {
+        const files = await resolveCapabilityFiles({ projectRoot: input.projectRoot, row });
+        const failing = [];
+        for (const file of files) {
+            const entry = input.summary.files.get(file);
+            if (entry === undefined) {
+                failing.push({
+                    path: file,
+                    actual: { statements: 0, branches: 0, functions: 0, lines: 0 },
+                    reason: 'missing-from-summary',
+                });
+                continue;
+            }
+            if (entry.statements.pct !== 100 ||
+                entry.branches.pct !== 100 ||
+                entry.functions.pct !== 100 ||
+                entry.lines.pct !== 100) {
+                failing.push({
+                    path: file,
+                    actual: {
+                        statements: entry.statements.pct,
+                        branches: entry.branches.pct,
+                        functions: entry.functions.pct,
+                        lines: entry.lines.pct,
+                    },
+                    reason: 'below-threshold',
+                });
+            }
+        }
+        if (failing.length > 0) {
+            mismatches.push({
+                capability: row.capability,
+                source: row.source,
+                failingFiles: failing,
+            });
+        }
+    }
+    if (mismatches.length === 0) {
+        return { ok: true };
+    }
+    return { ok: false, mismatches };
+}
+// ---------------------------------------------------------------------------
+// Freshness
+// ---------------------------------------------------------------------------
+/**
+ * Compare the mtime of every spec/proposal/tasks file under the change against
+ * the mtime of the c8 summary. If any change file is newer than the summary,
+ * the captured V8 counters no longer match the source on disk and the summary
+ * is stale.
+ *
+ * Returns the list of stale files (project-root-relative POSIX paths). An empty
+ * array means the summary is fresh.
+ */
+export async function findStaleChangeFiles(input) {
+    const { stat: statFn } = await import('node:fs/promises');
+    const summaryMtime = (await statFn(input.summary.path)).mtimeMs;
+    const changeRoot = `${input.openspecRoot.replace(/\\/g, '/').replace(/\/$/, '')}/changes/${input.changeId}`;
+    const candidates = [
+        `${changeRoot}/proposal.md`,
+        `${changeRoot}/tasks.md`,
+        `${changeRoot}/design.md`,
+    ];
+    // spec files
+    const specsRoot = `${changeRoot}/specs`;
+    if (await isDirectory(specsRoot)) {
+        const { readdir } = await import('node:fs/promises');
+        const stack = [specsRoot];
+        while (stack.length > 0) {
+            const dir = stack.pop();
+            let entries;
+            try {
+                entries = await readdir(dir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                const full = `${dir}/${entry.name}`;
+                if (entry.isDirectory()) {
+                    stack.push(full);
+                }
+                else if (entry.isFile() && entry.name === 'spec.md') {
+                    candidates.push(full);
+                }
+            }
+        }
+    }
+    const stale = [];
+    for (const candidate of candidates) {
+        try {
+            const m = (await statFn(candidate)).mtimeMs;
+            if (m > summaryMtime) {
+                stale.push(relative(input.projectRoot, candidate).replace(/\\/g, '/'));
+            }
+        }
+        catch {
+            // file does not exist — not stale, just absent
+        }
+    }
+    return stale;
+}

package/dist/services/openspec/openspec-archive-service.d.ts

@@ -0,0 +1,82 @@
+import type { OpenSpecScanOptions } from './openspec-scan-service.js';
+import { type CapabilityCoverageMismatch, type CapabilityMappingRow } from './coverage-evidence-reader.js';
+export type OpenSpecArchiveOptions = OpenSpecScanOptions & {
+    apply?: boolean;
+    /**
+     * Skip the Pre-cond 2 (Coverage Evidence) gate even when the change declares
+     * requirements. Use only when the operator has confirmed the gap is acceptable
+     * for this archive operation. Default: false (gate enforced).
+     */
+    force?: boolean;
+    /**
+     * Override coverage-summary.json discovery (Fix-6B AC1.1).
+     * When omitted, discovery order is:
+     *   1. <projectRoot>/coverage/coverage-summary.json
+     *   2. <projectRoot>/openspec/coverage-summary.json
+     */
+    coverageSummaryPath?: string;
+    archiveDirName?: string;
+};
+export type CoverageRequirementRow = {
+    /** Spec delta name (e.g. `quality-gates`). */
+    capability: string;
+    /** Requirement heading under which the row was declared. */
+    requirement: string;
+    /** One of `covered`, `partial`, `uncovered`. */
+    status: 'covered' | 'partial' | 'uncovered';
+    /** Optional test anchor — file path or test name. */
+    testAnchor?: string;
+    /** Source line for diagnostics. */
+    line: number;
+};
+export type CoverageEvidence = {
+    /** Rows parsed out of the `## Coverage Evidence` block in proposal.md. */
+    rows: ReadonlyArray<CoverageRequirementRow>;
+    /** True when a `## Coverage Evidence` block existed in the proposal. */
+    present: boolean;
+    /** Rows parsed out of the `## Capability Mapping` block in proposal.md. */
+    capabilityRows: ReadonlyArray<CapabilityMappingRow>;
+    /** Resolved coverage-summary.json absolute path (Fix-6B). */
+    summaryPath?: string;
+    /** Freshness status of the c8 summary relative to change files. */
+    summaryStatus: 'missing' | 'stale' | 'fresh' | 'unavailable';
+    /** Per-capability validation outcome. */
+    capabilityValidation: 'ok' | 'mismatch' | 'no-mapping' | 'not-enforced';
+    /** Files under the change that are newer than the summary (only when stale). */
+    staleFiles: ReadonlyArray<string>;
+    /** Per-capability failing detail (only when mismatch). */
+    mismatches: ReadonlyArray<CapabilityCoverageMismatch>;
+};
+export type OpenSpecArchiveResult = {
+    changeId: string;
+    from: string;
+    to: string;
+    applied: boolean;
+    coverage?: CoverageEvidence;
+    /** Set when `applied === true` and the gate was bypassed via `--force`. */
+    coverageGateBypassed?: boolean;
+    /** Set when `applied === true` and the Fix-6B mismatch gate was bypassed via `--force`. */
+    coverageMismatchBypassed?: boolean;
+};
+export declare class OpenSpecArchiveError extends Error {
+    readonly code: 'OPENSPEC_COVERAGE_GATE_FAILED' | 'OPENSPEC_COVERAGE_GATE_PARTIAL' | 'OPENSPEC_COVERAGE_EVIDENCE_MALFORMED' | 'OPENSPEC_COVERAGE_EVIDENCE_MISSING' | 'OPENSPEC_COVERAGE_EVIDENCE_STALE' | 'OPENSPEC_COVERAGE_EVIDENCE_MISMATCH';
+    readonly detail: Record<string, unknown>;
+    constructor(code: 'OPENSPEC_COVERAGE_GATE_FAILED' | 'OPENSPEC_COVERAGE_GATE_PARTIAL' | 'OPENSPEC_COVERAGE_EVIDENCE_MALFORMED' | 'OPENSPEC_COVERAGE_EVIDENCE_MISSING' | 'OPENSPEC_COVERAGE_EVIDENCE_STALE' | 'OPENSPEC_COVERAGE_EVIDENCE_MISMATCH', message: string, detail?: Record<string, unknown>);
+}
+/**
+ * Parse the `## Coverage Evidence` block out of a proposal.md.
+ *
+ * Accepted shape (markdown table):
+ *
+ *     ## Coverage Evidence
+ *
+ *     | capability | requirement | status | testAnchor |
+ *     | --- | --- | --- | --- |
+ *     | quality-gates | 100% coverage for included modules | covered | tests/unit/quality-gates.test.ts |
+ *
+ * Returns `{ present: false }` when the heading is missing. Throws
+ * `OpenSpecArchiveError` with `code: 'OPENSPEC_COVERAGE_EVIDENCE_MALFORMED'`
+ * when the heading is present but no parsable rows are extracted.
+ */
+export declare function parseCoverageEvidence(proposalPath: string): Promise<CoverageEvidence>;
+export declare function archiveOpenSpecChange(changeId: string, options?: OpenSpecArchiveOptions): Promise<OpenSpecArchiveResult | null>;