peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/openspec/artifact-boundary.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Artifact boundary helpers for peaks-loop.
+ *
+ * Slice rid-009:
+ *   - sub-slice 1: change-id validation (`validateChangeId`).
+ *   - sub-slice 2: artifact path planning (`planArtifactPath` + `isPathInsideArtifactRoot` re-export).
+ *   - sub-slice 3: workspace-unavailable response (`buildWorkspaceUnavailable`).
+ *
+ * The colocated single-file layout avoids creating two competing path-safety
+ * layers — `src/shared/path-safety.ts` already owns the primitive
+ * `isPathInsideArtifactRoot` which we re-export unchanged.
+ *
+ * Conventions:
+ *   - `Result<T, E>` is hand-rolled in this file (no `neverthrow` dep).
+ *   - All errors are typed unions — no thrown exceptions for validation.
+ *   - The change-id format mirrors the pre-existing
+ *     `[A-Za-z0-9][A-Za-z0-9._-]*` regex used by
+ *     `openspec-validate-service.ts` so the refactor (task 3) preserves
+ *     the exact error message byte-for-byte.
+ *   - Path planning uses `posix.normalize` to keep semantics stable across
+ *     win32/posix runners; JSON output always uses `/`.
+ */
+import { isPathInsideArtifactRoot as _isPathInsideArtifactRoot } from '../../shared/path-safety.js';
+export type Result<T, E> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+export declare function ok<T>(value: T): Result<T, never>;
+export declare function err<E>(error: E): Result<never, E>;
+export declare function isOk<T, E>(result: Result<T, E>): result is {
+    ok: true;
+    value: T;
+};
+export type ChangeIdError = {
+    code: 'change-id-empty';
+    message: string;
+} | {
+    code: 'change-id-format';
+    message: string;
+} | {
+    code: 'change-id-reserved';
+    message: string;
+};
+export type BoundaryError = ChangeIdError | {
+    code: 'workspace-unconfigured';
+    message: string;
+} | {
+    code: 'path-outside-artifact-root';
+    path: string;
+    root: string;
+    message: string;
+} | {
+    code: 'unsafe-path-input';
+    message: string;
+};
+/**
+ * Validate a change-id string. Returns a typed `Result`; the error code
+ * distinguishes "empty" / "format" / "reserved" so callers can branch on
+ * the cause without re-parsing the message.
+ *
+ * Acceptance contract (rid-009 §3.3.1, task 1):
+ *   - accepts `[A-Za-z0-9][A-Za-z0-9._-]*` (existing regex semantics)
+ *   - rejects empty string with `change-id-empty`
+ *   - rejects `.` and `..` with `change-id-reserved`
+ *   - rejects everything else that does not match the regex with
+ *     `change-id-format`
+ *
+ * The format-error message is byte-for-byte identical to the pre-refactor
+ * string produced at `openspec-validate-service.ts:55` so existing
+ * `OpenSpecValidationIssue` consumers do not break.
+ */
+export declare function validateChangeId(id: string): Result<{
+    changeId: string;
+}, ChangeIdError>;
+/**
+ * Re-export of `src/shared/path-safety.ts#isPathInsideArtifactRoot`.
+ *
+ * Single source of truth: the primitive is owned by `src/shared/path-safety.ts`;
+ * this module owns the *domain* helpers (change-id + path planner) that consume
+ * the primitive. Tests in `tests/unit/services/openspec/artifact-boundary.test.ts`
+ * exercise the RE-EXPORT wiring; the primitive's own correctness is covered by
+ * its native test file.
+ */
+export { _isPathInsideArtifactRoot as isPathInsideArtifactRoot };
+/**
+ * Input for `planArtifactPath`. The caller MUST supply `changeId`, `workspaceRoot`,
+ * `role`, and `requestId`. Exactly one of `absolutePath` or `relativePath` may be
+ * supplied; if neither is supplied, a default template `"<changeId>/<role>/<requestId>"`
+ * is used. `template` overrides the default placeholder substitution when both
+ * `absolutePath` and `relativePath` are absent.
+ */
+export type PlanArtifactPathInput = {
+    changeId: string;
+    workspaceRoot: string;
+    role: string;
+    requestId: string;
+    absolutePath?: string;
+    relativePath?: string;
+    template?: string;
+};
+export type PlanArtifactPathOutput = {
+    absolutePath: string;
+    relativePath: string;
+    jsonSafeRelativePath: string;
+};
+/**
+ * Plan an artifact-relative path under the configured Peaks artifact workspace.
+ *
+ * Semantics (rid-009 §3.3.2, tasks 5–9):
+ *   - Backslashes in the candidate path are normalized to forward slashes for
+ *     JSON safety; empty segments (`foo//bar`) are collapsed by `posix.normalize`.
+ *   - If the resolved absolute path is NOT contained under `workspaceRoot`
+ *     (per `isPathInsideArtifactRoot`), returns
+ *     `BoundaryError.path-outside-artifact-root` — NO silent fallback to cwd.
+ *   - JSON output (`jsonSafeRelativePath`) ALWAYS uses `/` so it round-trips
+ *     cleanly through `JSON.stringify` on Windows.
+ *
+ * Path math only — this helper never touches the filesystem, so it is fully
+ * hermetic and safe to call on paths that do not exist yet.
+ */
+export declare function planArtifactPath(input: PlanArtifactPathInput): Result<PlanArtifactPathOutput, BoundaryError>;
+export type WorkspaceUnavailableResponse = {
+    ok: false;
+    mode: 'preview-only' | 'blocked';
+    reason: 'artifact-workspace-unavailable';
+    nextActions: string[];
+};
+/**
+ * Build the explicit response used when no artifact workspace is configured.
+ * The next action is static natural language so callers can surface remediation
+ * without requiring the user to type a CLI command or hand-author data.
+ */
+export declare function buildWorkspaceUnavailable(input: {
+    mode: WorkspaceUnavailableResponse['mode'];
+}): WorkspaceUnavailableResponse;

package/dist/services/openspec/artifact-boundary.js

@@ -0,0 +1,150 @@
+/**
+ * Artifact boundary helpers for peaks-loop.
+ *
+ * Slice rid-009:
+ *   - sub-slice 1: change-id validation (`validateChangeId`).
+ *   - sub-slice 2: artifact path planning (`planArtifactPath` + `isPathInsideArtifactRoot` re-export).
+ *   - sub-slice 3: workspace-unavailable response (`buildWorkspaceUnavailable`).
+ *
+ * The colocated single-file layout avoids creating two competing path-safety
+ * layers — `src/shared/path-safety.ts` already owns the primitive
+ * `isPathInsideArtifactRoot` which we re-export unchanged.
+ *
+ * Conventions:
+ *   - `Result<T, E>` is hand-rolled in this file (no `neverthrow` dep).
+ *   - All errors are typed unions — no thrown exceptions for validation.
+ *   - The change-id format mirrors the pre-existing
+ *     `[A-Za-z0-9][A-Za-z0-9._-]*` regex used by
+ *     `openspec-validate-service.ts` so the refactor (task 3) preserves
+ *     the exact error message byte-for-byte.
+ *   - Path planning uses `posix.normalize` to keep semantics stable across
+ *     win32/posix runners; JSON output always uses `/`.
+ */
+import { posix, relative, resolve, isAbsolute as nodeIsAbsolute } from 'node:path';
+import { isPathInsideArtifactRoot as _isPathInsideArtifactRoot } from '../../shared/path-safety.js';
+export function ok(value) {
+    return { ok: true, value };
+}
+export function err(error) {
+    return { ok: false, error };
+}
+export function isOk(result) {
+    return result.ok;
+}
+const CHANGE_ID_FORMAT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * Validate a change-id string. Returns a typed `Result`; the error code
+ * distinguishes "empty" / "format" / "reserved" so callers can branch on
+ * the cause without re-parsing the message.
+ *
+ * Acceptance contract (rid-009 §3.3.1, task 1):
+ *   - accepts `[A-Za-z0-9][A-Za-z0-9._-]*` (existing regex semantics)
+ *   - rejects empty string with `change-id-empty`
+ *   - rejects `.` and `..` with `change-id-reserved`
+ *   - rejects everything else that does not match the regex with
+ *     `change-id-format`
+ *
+ * The format-error message is byte-for-byte identical to the pre-refactor
+ * string produced at `openspec-validate-service.ts:55` so existing
+ * `OpenSpecValidationIssue` consumers do not break.
+ */
+export function validateChangeId(id) {
+    if (id === '') {
+        return err({ code: 'change-id-empty', message: 'changeId is empty' });
+    }
+    if (id === '.' || id === '..') {
+        return err({ code: 'change-id-reserved', message: `changeId ${id} is reserved` });
+    }
+    if (id.startsWith('.') || id.endsWith('.')) {
+        return err({
+            code: 'change-id-format',
+            message: `changeId ${id} does not match [A-Za-z0-9][A-Za-z0-9._-]*`
+        });
+    }
+    if (!CHANGE_ID_FORMAT_PATTERN.test(id)) {
+        return err({
+            code: 'change-id-format',
+            message: `changeId ${id} does not match [A-Za-z0-9][A-Za-z0-9._-]*`
+        });
+    }
+    return ok({ changeId: id });
+}
+/**
+ * Re-export of `src/shared/path-safety.ts#isPathInsideArtifactRoot`.
+ *
+ * Single source of truth: the primitive is owned by `src/shared/path-safety.ts`;
+ * this module owns the *domain* helpers (change-id + path planner) that consume
+ * the primitive. Tests in `tests/unit/services/openspec/artifact-boundary.test.ts`
+ * exercise the RE-EXPORT wiring; the primitive's own correctness is covered by
+ * its native test file.
+ */
+export { _isPathInsideArtifactRoot as isPathInsideArtifactRoot };
+const DEFAULT_TEMPLATE = '<changeId>/<role>/<requestId>';
+function interpolateTemplate(template, changeId, role, requestId) {
+    return template
+        .replaceAll('<changeId>', changeId)
+        .replaceAll('<role>', role)
+        .replaceAll('<requestId>', requestId);
+}
+/**
+ * Plan an artifact-relative path under the configured Peaks artifact workspace.
+ *
+ * Semantics (rid-009 §3.3.2, tasks 5–9):
+ *   - Backslashes in the candidate path are normalized to forward slashes for
+ *     JSON safety; empty segments (`foo//bar`) are collapsed by `posix.normalize`.
+ *   - If the resolved absolute path is NOT contained under `workspaceRoot`
+ *     (per `isPathInsideArtifactRoot`), returns
+ *     `BoundaryError.path-outside-artifact-root` — NO silent fallback to cwd.
+ *   - JSON output (`jsonSafeRelativePath`) ALWAYS uses `/` so it round-trips
+ *     cleanly through `JSON.stringify` on Windows.
+ *
+ * Path math only — this helper never touches the filesystem, so it is fully
+ * hermetic and safe to call on paths that do not exist yet.
+ */
+export function planArtifactPath(input) {
+    const workspaceRoot = input.workspaceRoot;
+    const candidateRaw = input.absolutePath !== undefined
+        ? input.absolutePath
+        : input.relativePath !== undefined
+            ? input.relativePath
+            : interpolateTemplate(input.template ?? DEFAULT_TEMPLATE, input.changeId, input.role, input.requestId);
+    // Always normalize separators to forward-slashes for the JSON-safe output,
+    // then run posix.normalize so empty segments (foo//bar) and `..` segments
+    // collapse to canonical form.
+    const forwardSlashed = candidateRaw.replace(/\\/g, '/');
+    const normalized = posix.normalize(forwardSlashed);
+    // Resolve against workspaceRoot. If the candidate is already absolute,
+    // posix.normalize preserves the leading `/`; `resolve` keeps it absolute
+    // without prepending workspaceRoot (Node's path.resolve treats absolute
+    // candidates as already-resolved).
+    const absolutePath = nodeIsAbsolute(normalized)
+        ? resolve(normalized)
+        : resolve(workspaceRoot, normalized);
+    if (!_isPathInsideArtifactRoot(absolutePath, workspaceRoot)) {
+        return err({
+            code: 'path-outside-artifact-root',
+            path: absolutePath,
+            root: workspaceRoot,
+            message: `path "${absolutePath}" resolves outside artifact root "${workspaceRoot}"`
+        });
+    }
+    const relativePath = relative(workspaceRoot, absolutePath);
+    const jsonSafeRelativePath = relativePath.replace(/\\/g, '/');
+    return ok({ absolutePath, relativePath, jsonSafeRelativePath });
+}
+const WORKSPACE_UNAVAILABLE_NEXT_ACTIONS = [
+    'Configure artifact workspace by describing where Peaks should store artifacts.'
+];
+/**
+ * Build the explicit response used when no artifact workspace is configured.
+ * The next action is static natural language so callers can surface remediation
+ * without requiring the user to type a CLI command or hand-author data.
+ */
+export function buildWorkspaceUnavailable(input) {
+    return {
+        ok: false,
+        mode: input.mode,
+        reason: 'artifact-workspace-unavailable',
+        nextActions: [...WORKSPACE_UNAVAILABLE_NEXT_ACTIONS]
+    };
+}

package/dist/services/openspec/coverage-evidence-reader.d.ts

@@ -0,0 +1,191 @@
+/**
+ * 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 { type Result } from './artifact-boundary.js';
+export type CoverageSummaryPathError = {
+    code: 'missing';
+    triedPaths: ReadonlyArray<string>;
+} | {
+    code: 'not-readable';
+    path: string;
+    message: string;
+};
+export type CoverageSummary = {
+    /** Resolved absolute path to the summary file. */
+    path: string;
+    /** ISO timestamp of the summary file's mtime. */
+    capturedAt: string;
+    /** Project-root-relative per-file coverage entries. */
+    files: ReadonlyMap<string, CoverageFileEntry>;
+};
+export type CoverageFileEntry = {
+    /** Absolute path the c8 entry covers (POSIX). */
+    path: string;
+    /** Project-root-relative POSIX path (the key the summary uses). */
+    relativePath: string;
+    statements: {
+        pct: number;
+        covered: number;
+        total: number;
+    };
+    branches: {
+        pct: number;
+        covered: number;
+        total: number;
+    };
+    functions: {
+        pct: number;
+        covered: number;
+        total: number;
+    };
+    lines: {
+        pct: number;
+        covered: number;
+        total: number;
+    };
+};
+/**
+ * A single row from the proposal.md `## Capability Mapping` table.
+ * Mirror shape of CoverageRequirementRow (Fix-6A) for symmetry.
+ */
+export type CapabilityMappingRow = {
+    /** Capability name (e.g. `quality-gates`). */
+    capability: string;
+    /** Project-root-relative source path — file or directory. */
+    source: string;
+    /** Optional test anchor (informational; Fix-6B does not validate). */
+    testAnchor?: string;
+    /** Source line for diagnostics. */
+    line: number;
+};
+export type CapabilityCoverageMismatch = {
+    capability: string;
+    source: string;
+    failingFiles: ReadonlyArray<{
+        path: string;
+        actual: {
+            statements: number;
+            branches: number;
+            functions: number;
+            lines: number;
+        };
+        reason: 'below-threshold' | 'missing-from-summary';
+    }>;
+};
+export type CoverageValidation = {
+    ok: true;
+} | {
+    ok: false;
+    mismatches: ReadonlyArray<CapabilityCoverageMismatch>;
+};
+/**
+ * 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 declare function resolveCoverageSummaryPath(input: {
+    projectRoot: string;
+    explicitPath?: string;
+}): Promise<Result<string, CoverageSummaryPathError>>;
+/**
+ * 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 declare function readC8Summary(path: string): Promise<CoverageSummary>;
+/**
+ * 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 declare function parseCapabilityMapping(proposalPath: string): Promise<{
+    rows: ReadonlyArray<CapabilityMappingRow>;
+    present: boolean;
+}>;
+/**
+ * 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 declare function resolveCapabilityFiles(input: {
+    projectRoot: string;
+    row: CapabilityMappingRow;
+}): Promise<ReadonlyArray<string>>;
+/**
+ * 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 declare function validateCapabilityCoverage(input: {
+    projectRoot: string;
+    summary: CoverageSummary;
+    rows: ReadonlyArray<CapabilityMappingRow>;
+}): Promise<CoverageValidation>;
+/**
+ * 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 declare function findStaleChangeFiles(input: {
+    projectRoot: string;
+    openspecRoot: string;
+    changeId: string;
+    summary: CoverageSummary;
+}): Promise<ReadonlyArray<string>>;