peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/scan/acceptance-coverage-service.js

@@ -0,0 +1,140 @@
+import { join } from 'node:path';
+import { pathExists, readText } from 'peaks-loop-shared/fs';
+import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
+const ACCEPTANCE_SECTION_PATTERN = /^##\s+(?:Acceptance criteria|验收标准|Acceptance Criteria)\s*$/m;
+function extractAcceptanceItems(prdBody) {
+    const lines = prdBody.split(/\r?\n/);
+    const startMatch = ACCEPTANCE_SECTION_PATTERN.exec(prdBody);
+    if (startMatch === null) {
+        return [];
+    }
+    // Find the line where the header starts.
+    let headerLine = 0;
+    for (let i = 0; i < lines.length; i += 1) {
+        if (ACCEPTANCE_SECTION_PATTERN.test((lines[i] ?? '') + '\n')) {
+            headerLine = i;
+            break;
+        }
+    }
+    const items = [];
+    let counter = 0;
+    for (let i = headerLine + 1; i < lines.length; i += 1) {
+        const raw = lines[i] ?? '';
+        if (/^##\s/.test(raw))
+            break; // next section
+        const bulletMatch = /^\s*-\s+(.+?)\s*$/.exec(raw);
+        if (bulletMatch === null)
+            continue;
+        const text = bulletMatch[1] ?? '';
+        if (text.length === 0)
+            continue;
+        // Skip placeholder-only bullets ("...", "<...>", etc.)
+        if (/^\.{2,}$/.test(text) || /^<[^>]+>$/.test(text))
+            continue;
+        counter += 1;
+        items.push({ id: `A${counter}`, text, line: i + 1 });
+    }
+    return items;
+}
+const TEST_CASE_HEADER_PATTERN = /^##\s+Test Case:\s*(.+?)\s*$/;
+const ACCEPTANCE_FIELD_PATTERN = /^\s*-\s+\*\*Acceptance:\*\*\s+(.+?)\s*$/i;
+function extractTestCases(qaBody) {
+    const lines = qaBody.split(/\r?\n/);
+    const cases = [];
+    let current = null;
+    for (let i = 0; i < lines.length; i += 1) {
+        const raw = lines[i] ?? '';
+        const headerMatch = TEST_CASE_HEADER_PATTERN.exec(raw);
+        if (headerMatch !== null) {
+            if (current !== null) {
+                cases.push({ title: current.title, acceptanceIds: current.ids, line: current.line });
+            }
+            current = { title: (headerMatch[1] ?? '').trim(), line: i + 1, ids: [] };
+            continue;
+        }
+        if (current === null)
+            continue;
+        const acceptanceMatch = ACCEPTANCE_FIELD_PATTERN.exec(raw);
+        if (acceptanceMatch !== null) {
+            const refs = (acceptanceMatch[1] ?? '').split(/[,\s]+/).map((part) => part.trim()).filter((part) => part.length > 0);
+            current.ids.push(...refs);
+        }
+    }
+    if (current !== null) {
+        cases.push({ title: current.title, acceptanceIds: current.ids, line: current.line });
+    }
+    return cases;
+}
+function buildCoverage(items, cases) {
+    const itemMap = new Map();
+    for (const item of items)
+        itemMap.set(item.id, item);
+    const coverageMap = new Map();
+    for (const item of items)
+        coverageMap.set(item.id, []);
+    const invalidReferences = [];
+    for (const testCase of cases) {
+        for (const ref of testCase.acceptanceIds) {
+            const normalized = ref.toUpperCase();
+            if (!itemMap.has(normalized)) {
+                invalidReferences.push({ testCaseTitle: testCase.title, reference: ref });
+                continue;
+            }
+            coverageMap.get(normalized)?.push(testCase.title);
+        }
+    }
+    const coverage = items.map((item) => ({
+        acceptanceId: item.id,
+        acceptanceText: item.text,
+        testCases: coverageMap.get(item.id) ?? []
+    }));
+    const uncovered = items.filter((item) => (coverageMap.get(item.id) ?? []).length === 0);
+    return { coverage, uncovered, invalidReferences };
+}
+export async function getAcceptanceCoverage(options) {
+    const showOptions = {
+        projectRoot: options.projectRoot,
+        role: 'prd',
+        requestId: options.requestId
+    };
+    if (options.sessionId !== undefined) {
+        showOptions.sessionId = options.sessionId;
+    }
+    const prdArtifact = await showRequestArtifact(showOptions);
+    if (prdArtifact === null) {
+        return { kind: 'prd-not-found' };
+    }
+    // As of slice 2026-06-05-change-id-as-unit-of-work, test-cases live
+    // under the same change-id dir as the PRD itself (the on-disk scope),
+    // not under the body's `- session:` line. Slice
+    // 2026-06-29-change-id-root-removal stripped the legacy
+    // `.peaks/_runtime/change/<id>/` indirection — test-cases now live
+    // under the canonical session dir `.peaks/_runtime/<sid>/qa/test-cases/`.
+    // `prdArtifact.sessionId` is the bare session id (the dir the PRD was
+    // found in), so we route through `_runtime/` here.
+    const sessionId = prdArtifact.sessionId;
+    const testCasesPath = join(options.projectRoot, '.peaks', '_runtime', sessionId, 'qa', 'test-cases', `${options.requestId}.md`);
+    if (!(await pathExists(testCasesPath))) {
+        return { kind: 'test-cases-not-found', expectedPath: testCasesPath };
+    }
+    const qaBody = await readText(testCasesPath);
+    const acceptanceItems = extractAcceptanceItems(prdArtifact.content);
+    const testCases = extractTestCases(qaBody);
+    const { coverage, uncovered, invalidReferences } = buildCoverage(acceptanceItems, testCases);
+    const unlinkedTestCases = testCases.filter((testCase) => testCase.acceptanceIds.length === 0);
+    const ok = uncovered.length === 0 && invalidReferences.length === 0 && acceptanceItems.length > 0;
+    return {
+        ok,
+        prdPath: prdArtifact.path,
+        testCasesPath,
+        acceptanceItems,
+        testCases,
+        coverage,
+        uncovered,
+        unlinkedTestCases,
+        invalidReferences
+    };
+}
+export function isAcceptanceCoverageError(value) {
+    return value.kind !== undefined;
+}

package/dist/services/scan/api-surface-service.d.ts

@@ -0,0 +1,69 @@
+/**
+ * API surface scan service.
+ *
+ * Walks the project for CLI subcommands, service-level public exports,
+ * public types, and module-level constants. Output feeds the tech-doc
+ * "Existing API / Component Inventory" section. Read-only — no writes.
+ *
+ * Pattern follows `libraries-service.ts` (readFileSync + readdir; pure
+ * data shape; no AST parsing). karpathy §2: minimum code, no abstractions.
+ */
+export type ApiSurfaceOptions = {
+    projectRoot: string;
+    /** Maximum entries per kind in output (after filtering). */
+    maxPerKind?: number;
+    /** Comma-separated globs (substring match) to limit the walk. */
+    includeDirs?: string;
+};
+export type CliEntry = {
+    name: string;
+    description: string;
+    sourceFile: string;
+};
+export type ServiceEntry = {
+    name: string;
+    kind: 'function' | 'class' | 'const';
+    isAsync: boolean;
+    sourceFile: string;
+    line: number;
+};
+export type TypeEntry = {
+    name: string;
+    kind: 'interface' | 'type' | 'enum';
+    sourceFile: string;
+    line: number;
+};
+export type ConstantEntry = {
+    name: string;
+    sourceFile: string;
+    line: number;
+};
+export type ApiSurfaceReport = {
+    projectRoot: string;
+    scannedAt: string;
+    counts: {
+        cli: number;
+        service: number;
+        type: number;
+        constant: number;
+    };
+    cli: CliEntry[];
+    service: ServiceEntry[];
+    type: TypeEntry[];
+    constant: ConstantEntry[];
+    warnings: string[];
+};
+/**
+ * Scan the project for API surfaces. Read-only. Never throws; failures
+ * surface as warnings in the report.
+ */
+export declare function scanApiSurface(options: ApiSurfaceOptions): Promise<ApiSurfaceReport>;
+export declare function formatApiSurfaceMarkdown(report: ApiSurfaceReport, opts?: {
+    maxPerKind?: number;
+    truncatedCounts?: {
+        cli: number;
+        service: number;
+        type: number;
+        constant: number;
+    };
+}): string;

package/dist/services/scan/api-surface-service.js

@@ -0,0 +1,239 @@
+/**
+ * API surface scan service.
+ *
+ * Walks the project for CLI subcommands, service-level public exports,
+ * public types, and module-level constants. Output feeds the tech-doc
+ * "Existing API / Component Inventory" section. Read-only — no writes.
+ *
+ * Pattern follows `libraries-service.ts` (readFileSync + readdir; pure
+ * data shape; no AST parsing). karpathy §2: minimum code, no abstractions.
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+const DEFAULT_DIRS = ['src/cli', 'src/services'];
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage']);
+const COMMAND_RE = /\.command\(\s*['"]([^'"]+)['"]\s*\)\s*\.description\(\s*['"]([^'"]+)['"]/g;
+const EXPORT_FUNCTION_RE = /^export\s+(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/gm;
+const EXPORT_CLASS_RE = /^export\s+class\s+([A-Za-z_$][\w$]*)/gm;
+const EXPORT_CONST_RE = /^export\s+const\s+([A-Za-z_$][\w$]*)/gm;
+const EXPORT_INTERFACE_RE = /^export\s+interface\s+([A-Za-z_$][\w$]*)/gm;
+const EXPORT_TYPE_RE = /^export\s+type\s+([A-Za-z_$][\w$]*)/gm;
+const EXPORT_ENUM_RE = /^export\s+enum\s+([A-Za-z_$][\w$]*)/gm;
+async function walkProject(projectRoot, includeDirs) {
+    const files = [];
+    for (const rel of includeDirs) {
+        const abs = join(projectRoot, rel);
+        if (!(await isDir(abs)))
+            continue;
+        await walkDir(abs, projectRoot, files);
+    }
+    return files;
+}
+async function walkDir(dir, projectRoot, out) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (SKIP_DIRS.has(entry.name))
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            await walkDir(full, projectRoot, out);
+        }
+        else if (entry.isFile() && entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
+            out.push(relative(projectRoot, full));
+        }
+    }
+}
+async function isDir(p) {
+    try {
+        return (await stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function lineOf(content, matchIndex) {
+    return content.slice(0, matchIndex).split('\n').length;
+}
+function uniqueByName(items) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        if (seen.has(item.name))
+            continue;
+        seen.add(item.name);
+        out.push(item);
+    }
+    return out;
+}
+function parseIncludeDirs(raw) {
+    if (!raw)
+        return [...DEFAULT_DIRS];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Scan the project for API surfaces. Read-only. Never throws; failures
+ * surface as warnings in the report.
+ */
+export async function scanApiSurface(options) {
+    const includeDirs = parseIncludeDirs(options.includeDirs);
+    const maxPerKind = options.maxPerKind ?? Number.POSITIVE_INFINITY;
+    const warnings = [];
+    const files = await walkProject(options.projectRoot, includeDirs);
+    const cli = [];
+    const service = [];
+    const types = [];
+    const constants = [];
+    for (const rel of files) {
+        const full = join(options.projectRoot, rel);
+        let content;
+        try {
+            content = await readFile(full, 'utf8');
+        }
+        catch (error) {
+            warnings.push(`unreadable: ${rel}: ${error.message}`);
+            continue;
+        }
+        if (rel.startsWith('src/cli/commands/')) {
+            let m;
+            COMMAND_RE.lastIndex = 0;
+            while ((m = COMMAND_RE.exec(content)) !== null) {
+                cli.push({
+                    name: m[1],
+                    description: m[2].slice(0, 120),
+                    sourceFile: rel
+                });
+            }
+        }
+        if (rel.startsWith('src/services/')) {
+            for (const re of [EXPORT_FUNCTION_RE, EXPORT_CLASS_RE, EXPORT_CONST_RE,
+                EXPORT_INTERFACE_RE, EXPORT_TYPE_RE, EXPORT_ENUM_RE]) {
+                re.lastIndex = 0;
+            }
+            let m;
+            while ((m = EXPORT_FUNCTION_RE.exec(content)) !== null) {
+                service.push({
+                    name: m[1],
+                    kind: 'function',
+                    isAsync: /export\s+async\s+function/.test(content.slice(Math.max(0, m.index - 10), m.index + 30)),
+                    sourceFile: rel,
+                    line: lineOf(content, m.index)
+                });
+            }
+            while ((m = EXPORT_CLASS_RE.exec(content)) !== null) {
+                service.push({
+                    name: m[1],
+                    kind: 'class',
+                    isAsync: false,
+                    sourceFile: rel,
+                    line: lineOf(content, m.index)
+                });
+            }
+            while ((m = EXPORT_INTERFACE_RE.exec(content)) !== null) {
+                types.push({
+                    name: m[1],
+                    kind: 'interface',
+                    sourceFile: rel,
+                    line: lineOf(content, m.index)
+                });
+            }
+            while ((m = EXPORT_TYPE_RE.exec(content)) !== null) {
+                types.push({
+                    name: m[1],
+                    kind: 'type',
+                    sourceFile: rel,
+                    line: lineOf(content, m.index)
+                });
+            }
+            while ((m = EXPORT_ENUM_RE.exec(content)) !== null) {
+                types.push({
+                    name: m[1],
+                    kind: 'enum',
+                    sourceFile: rel,
+                    line: lineOf(content, m.index)
+                });
+            }
+            while ((m = EXPORT_CONST_RE.exec(content)) !== null) {
+                constants.push({
+                    name: m[1],
+                    sourceFile: rel,
+                    line: lineOf(content, m.index)
+                });
+            }
+        }
+    }
+    const cliUnique = uniqueByName(cli).sort((a, b) => a.name.localeCompare(b.name));
+    const serviceUnique = uniqueByName(service).sort((a, b) => a.sourceFile.localeCompare(b.sourceFile) || a.name.localeCompare(b.name));
+    const typeUnique = uniqueByName(types).sort((a, b) => a.name.localeCompare(b.name));
+    const constantUnique = uniqueByName(constants).sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        projectRoot: options.projectRoot,
+        scannedAt: new Date().toISOString(),
+        counts: {
+            cli: cliUnique.length,
+            service: serviceUnique.length,
+            type: typeUnique.length,
+            constant: constantUnique.length
+        },
+        cli: Number.isFinite(maxPerKind) ? cliUnique.slice(0, maxPerKind) : cliUnique,
+        service: Number.isFinite(maxPerKind) ? serviceUnique.slice(0, maxPerKind) : serviceUnique,
+        type: Number.isFinite(maxPerKind) ? typeUnique.slice(0, maxPerKind) : typeUnique,
+        constant: Number.isFinite(maxPerKind) ? constantUnique.slice(0, maxPerKind) : constantUnique,
+        warnings
+    };
+}
+export function formatApiSurfaceMarkdown(report, opts = {}) {
+    const max = opts.maxPerKind ?? Number.POSITIVE_INFINITY;
+    const truncated = opts.truncatedCounts;
+    const lines = [];
+    lines.push('## API surface inventory');
+    lines.push('');
+    lines.push(`**Project:** ${report.projectRoot}`);
+    lines.push(`**Generated:** ${report.scannedAt}`);
+    lines.push(`**Counts:** cli=${report.counts.cli} service=${report.counts.service} type=${report.counts.type} constant=${report.counts.constant}`);
+    lines.push('');
+    const sections = [
+        ['CLI subcommands', report.counts.cli, (n) => `\`peaks ${n}\``],
+        ['Service exports', report.counts.service, (n) => `\`${n}\``],
+        ['Public types', report.counts.type, (n) => `\`${n}\``],
+        ['Module constants', report.counts.constant, (n) => `\`${n}\``]
+    ];
+    const arrays = [report.cli, report.service, report.type, report.constant];
+    const trunc = truncated
+        ? [truncated.cli - report.cli.length, truncated.service - report.service.length, truncated.type - report.type.length, truncated.constant - report.constant.length]
+        : [0, 0, 0, 0];
+    for (let i = 0; i < sections.length; i++) {
+        const [title, count, fmt] = sections[i];
+        const arr = arrays[i];
+        const more = trunc[i];
+        lines.push(`### ${title} (${count})`);
+        lines.push('');
+        for (const entry of arr) {
+            if (title === 'CLI subcommands') {
+                const e = entry;
+                lines.push(`- ${fmt(e.name)} — ${e.description}`);
+            }
+            else if (title === 'Service exports') {
+                const e = entry;
+                lines.push(`- \`${e.sourceFile}:${e.name}\` — ${e.isAsync ? 'async ' : ''}${e.kind}`);
+            }
+            else {
+                const e = entry;
+                lines.push(`- ${fmt(e.name)} — \`${e.kind ?? 'const'}\` (from \`${e.sourceFile}\`)`);
+            }
+        }
+        if (more > 0) {
+            lines.push(`- ... and ${more} more`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/dist/services/scan/archetype-service.d.ts

@@ -0,0 +1,5 @@
+import type { ArchetypeReport } from './scan-types.js';
+export type ArchetypeScanOptions = {
+    projectRoot: string;
+};
+export declare function scanArchetype(options: ArchetypeScanOptions): Promise<ArchetypeReport>;