@gordon.gan/specflow 1.4.6-beta → 1.7.0-beta

package/dist/core/approval/lint.d.ts

@@ -0,0 +1,10 @@
+import type { ApprovalDiagnostic } from './types.js';
+export interface ApprovalLintOptions {
+    readonly changeDir: string;
+    readonly strict?: boolean;
+}
+export interface ApprovalLintResult {
+    readonly ok: boolean;
+    readonly diagnostics: readonly ApprovalDiagnostic[];
+}
+export declare function lintApprovalDocument(options: ApprovalLintOptions): Promise<ApprovalLintResult>;

package/dist/core/approval/lint.js

@@ -0,0 +1,302 @@
+import { promises as fs } from 'node:fs';
+import { findForbiddenMatch, findInconsistencyHints } from './forbidden-patterns.js';
+import { readApprovalIndex } from './assemble.js';
+import { getApprovalAnalysisPath, getApprovalPartPath } from './paths.js';
+async function readPartContents(changeDir, index) {
+    const parts = new Map();
+    for (const partId of index.parts_order) {
+        try {
+            parts.set(partId, await fs.readFile(getApprovalPartPath(changeDir, partId), 'utf-8'));
+        }
+        catch {
+            // missing parts handled by assemble check
+        }
+    }
+    return parts;
+}
+function allPartsText(parts) {
+    return [...parts.values()].join('\n');
+}
+export async function lintApprovalDocument(options) {
+    const diagnostics = [];
+    const { changeDir, strict = false } = options;
+    let index;
+    try {
+        index = await readApprovalIndex(changeDir);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            diagnostics: [
+                {
+                    code: 'missing_index',
+                    severity: 'error',
+                    message: `Cannot read approval/index.yaml: ${message}`,
+                },
+            ],
+        };
+    }
+    const partContents = await readPartContents(changeDir, index);
+    const combined = allPartsText(partContents);
+    // C3: design_points referenced somewhere in parts
+    for (const point of index.design_points) {
+        const id = point.replace(/^P/, 'P');
+        const pattern = new RegExp(`\\b${escapeRegExp(id)}\\b`);
+        if (!pattern.test(combined)) {
+            diagnostics.push({
+                code: 'design_point_unreferenced',
+                severity: strict ? 'error' : 'warning',
+                message: `Design point "${id}" listed in index but not referenced in any part`,
+            });
+        }
+    }
+    // C3b: decisions referenced in parts
+    for (const decision of index.decisions) {
+        const id = decision.replace(/^D/, 'D');
+        const pattern = new RegExp(`\\b${escapeRegExp(id)}\\b`);
+        if (!pattern.test(combined)) {
+            diagnostics.push({
+                code: 'decision_unreferenced',
+                severity: strict ? 'error' : 'warning',
+                message: `Decision "${id}" listed in index but not referenced in any part`,
+            });
+        }
+    }
+    // C3c: tables / capabilities referenced in assigned parts
+    for (const table of index.tables) {
+        const partText = partContents.get(table.part) ?? '';
+        if (partText.length === 0) {
+            continue;
+        }
+        const hasRef = partText.includes(table.id) ||
+            partText.includes(table.name) ||
+            new RegExp(`\\b${escapeRegExp(table.id)}\\b`).test(partText);
+        if (!hasRef) {
+            diagnostics.push({
+                code: 'table_unreferenced',
+                severity: strict ? 'error' : 'warning',
+                message: `Table "${table.id}" (${table.name}) not referenced in part "${table.part}"`,
+                part: table.part,
+            });
+        }
+    }
+    for (const cap of index.capabilities) {
+        const partText = partContents.get(cap.part) ?? '';
+        if (partText.length === 0) {
+            continue;
+        }
+        if (!partText.includes(cap.id)) {
+            diagnostics.push({
+                code: 'capability_unreferenced',
+                severity: strict ? 'error' : 'warning',
+                message: `Capability "${cap.id}" not referenced in part "${cap.part}"`,
+                part: cap.part,
+            });
+        }
+    }
+    // C4: page apis exist as interface ids
+    const interfaceIds = new Set(index.interfaces.map((i) => i.id));
+    for (const page of index.pages) {
+        for (const apiId of page.apis) {
+            if (!interfaceIds.has(apiId)) {
+                diagnostics.push({
+                    code: 'page_api_missing',
+                    severity: 'error',
+                    message: `Page "${page.id}" references api "${apiId}" not in index.interfaces`,
+                    part: page.part,
+                });
+            }
+        }
+    }
+    // C1 + C2: frozen fields and pairs_with
+    for (const iface of index.interfaces) {
+        const frozen = iface.frozen;
+        const partText = partContents.get(iface.part) ?? '';
+        if (frozen?.rpc) {
+            const rpcShort = frozen.rpc.split('.').pop() ?? frozen.rpc;
+            if (partText.length > 0 && !partText.includes(frozen.rpc) && !partText.includes(rpcShort)) {
+                diagnostics.push({
+                    code: 'frozen_rpc_missing',
+                    severity: 'error',
+                    message: `Interface "${iface.id}" frozen.rpc "${frozen.rpc}" not found in part "${iface.part}"`,
+                    part: iface.part,
+                });
+            }
+        }
+        if (frozen?.http_path) {
+            const pathOnly = frozen.http_path.replace(/^(GET|POST|PUT|PATCH|DELETE)\s+/i, '');
+            if (partText.length > 0 && !partText.includes(pathOnly)) {
+                diagnostics.push({
+                    code: 'frozen_http_path_missing',
+                    severity: 'error',
+                    message: `Interface "${iface.id}" frozen.http_path "${frozen.http_path}" not found in part "${iface.part}"`,
+                    part: iface.part,
+                });
+            }
+        }
+        if (frozen?.status_enum && frozen.status_enum.length > 0) {
+            for (const status of frozen.status_enum) {
+                if (partText.length > 0 && !partText.includes(status)) {
+                    diagnostics.push({
+                        code: 'frozen_status_enum_missing',
+                        severity: strict ? 'error' : 'warning',
+                        message: `Interface "${iface.id}" frozen status "${status}" not mentioned in part "${iface.part}"`,
+                        part: iface.part,
+                    });
+                }
+            }
+        }
+        if (iface.pairs_with) {
+            const pair = index.interfaces.find((i) => i.id === iface.pairs_with);
+            if (!pair) {
+                diagnostics.push({
+                    code: 'pairs_with_missing',
+                    severity: 'error',
+                    message: `Interface "${iface.id}" pairs_with "${iface.pairs_with}" not in index.interfaces`,
+                    part: iface.part,
+                });
+            }
+            else if (!partContents.has(pair.part)) {
+                diagnostics.push({
+                    code: 'pairs_with_part_missing',
+                    severity: 'error',
+                    message: `Interface "${iface.id}" pairs_with part "${pair.part}" file missing`,
+                    part: iface.part,
+                });
+            }
+            else {
+                const pairText = partContents.get(pair.part) ?? '';
+                if (partText.length > 0 && !partText.includes(iface.pairs_with)) {
+                    diagnostics.push({
+                        code: 'pairs_with_unref',
+                        severity: 'warning',
+                        message: `Interface "${iface.id}" part does not cross-ref pairs_with "${iface.pairs_with}"`,
+                        part: iface.part,
+                    });
+                }
+                if (pairText.length > 0 && !pairText.includes(iface.id)) {
+                    diagnostics.push({
+                        code: 'pairs_with_unref',
+                        severity: 'warning',
+                        message: `Interface "${iface.pairs_with}" part does not cross-ref pair "${iface.id}"`,
+                        part: pair.part,
+                    });
+                }
+            }
+        }
+    }
+    // C6: feature_slices — all listed parts exist + depth parity
+    if (index.acp?.feature_slices) {
+        for (const slice of index.acp.feature_slices) {
+            const byteLengths = [];
+            for (const partId of slice.parts) {
+                const content = partContents.get(partId);
+                if (!content) {
+                    diagnostics.push({
+                        code: 'feature_slice_part_missing',
+                        severity: 'error',
+                        message: `Feature slice "${slice.id}" references missing part "${partId}"`,
+                        part: partId,
+                    });
+                }
+                else {
+                    byteLengths.push(Buffer.byteLength(content, 'utf8'));
+                }
+            }
+            if (byteLengths.length >= 2) {
+                const min = Math.min(...byteLengths);
+                const max = Math.max(...byteLengths);
+                if (min > 0 && max / min >= 8) {
+                    diagnostics.push({
+                        code: 'feature_slice_depth_imbalance',
+                        severity: strict ? 'error' : 'warning',
+                        message: `Feature slice "${slice.id}" has large depth imbalance across parts (max/min bytes ≥ 8)`,
+                    });
+                }
+            }
+        }
+    }
+    // C6b: context budget hint (acp/v2)
+    const budget = index.acp?.context_budget_tokens;
+    if (budget && budget > 0) {
+        const approxTokens = Math.ceil(combined.length / 4);
+        if (approxTokens > budget * 1.5) {
+            diagnostics.push({
+                code: 'context_budget_exceeded',
+                severity: 'warning',
+                message: `Combined parts ~${approxTokens} tokens exceed acp.context_budget_tokens (${budget}) — consider smaller Map batches`,
+            });
+        }
+    }
+    // C7: analysis.json frozen_rpc aligns with index
+    try {
+        const analysisRaw = JSON.parse(await fs.readFile(getApprovalAnalysisPath(changeDir), 'utf-8'));
+        if (analysisRaw.frozen_rpc) {
+            const rpcInterfaces = index.interfaces.filter((i) => i.frozen?.rpc);
+            if (rpcInterfaces.length > 0) {
+                const mismatch = rpcInterfaces.some((i) => i.frozen.rpc !== analysisRaw.frozen_rpc);
+                if (mismatch) {
+                    diagnostics.push({
+                        code: 'analysis_frozen_rpc_mismatch',
+                        severity: 'warning',
+                        message: `analysis.json frozen_rpc "${analysisRaw.frozen_rpc}" differs from index interface frozen.rpc values`,
+                    });
+                }
+            }
+        }
+    }
+    catch {
+        // analysis optional for lint
+    }
+    // C8: multi_repo — each repo has at least one entity or part tagged
+    if (index.multi_repo?.enabled) {
+        for (const repo of index.multi_repo.repos) {
+            const hasEntity = index.interfaces.some((i) => i.repo === repo.id) ||
+                index.pages.some((p) => p.repo === repo.id) ||
+                index.tables.some((t) => t.repo === repo.id);
+            if (!hasEntity && index.multi_repo.document_mode === 'per_repo') {
+                diagnostics.push({
+                    code: 'multi_repo_repo_unrepresented',
+                    severity: 'warning',
+                    message: `Multi-repo entry "${repo.id}" has no interfaces/pages/tables with repo tag`,
+                });
+            }
+        }
+    }
+    // C5: forbidden patterns per part
+    for (const [partId, content] of partContents) {
+        const forbidden = findForbiddenMatch(content);
+        if (forbidden) {
+            diagnostics.push({
+                code: 'forbidden_pattern',
+                severity: 'error',
+                message: `Part "${partId}": forbidden stub pattern (${forbidden.source})`,
+                part: partId,
+            });
+        }
+        for (const hint of findInconsistencyHints(content)) {
+            diagnostics.push({
+                code: 'inconsistency_hint',
+                severity: strict ? 'error' : 'warning',
+                message: `Part "${partId}": possible semantic inconsistency (${hint.source})`,
+                part: partId,
+            });
+        }
+    }
+    // C9: appendix duplication in signoff
+    const signoff = partContents.get('10-signoff') ?? '';
+    if (/附录\s*A/i.test(signoff)) {
+        diagnostics.push({
+            code: 'appendix_in_signoff',
+            severity: 'warning',
+            message: 'Part "10-signoff" contains 附录 A; assemble will skip auto-appendix — ensure no duplicate in output',
+            part: '10-signoff',
+        });
+    }
+    const hasError = diagnostics.some((d) => d.severity === 'error');
+    return { ok: !hasError, diagnostics };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/core/approval/paths.d.ts

@@ -6,3 +6,8 @@ export declare function getApprovalPartsDir(changeDir: string): string;
 export declare function getApprovalPartPath(changeDir: string, partId: string): string;
 export declare function getApprovalOutputPath(changeDir: string): string;
 export declare function getApprovalAnalysisPath(changeDir: string): string;
+export declare function getApprovalReviewPacketPath(changeDir: string): string;
+export declare function getApprovalReviewPath(changeDir: string): string;
+export declare function getApprovalPlaybookPath(changeDir: string): string;
+export declare function getApprovalBundleOutputPath(changeDir: string, relativePath: string): string;
+export declare function getApprovalHtmlOutputPath(changeDir: string): string;

package/dist/core/approval/paths.js

@@ -26,3 +26,18 @@ export function getApprovalOutputPath(changeDir) {
 export function getApprovalAnalysisPath(changeDir) {
     return join(getApprovalWorkspaceDir(changeDir), 'analysis.json');
 }
+export function getApprovalReviewPacketPath(changeDir) {
+    return join(getApprovalWorkspaceDir(changeDir), 'review-packet.json');
+}
+export function getApprovalReviewPath(changeDir) {
+    return join(getApprovalWorkspaceDir(changeDir), 'review-result.json');
+}
+export function getApprovalPlaybookPath(changeDir) {
+    return join(getApprovalWorkspaceDir(changeDir), 'approval-playbook.yaml');
+}
+export function getApprovalBundleOutputPath(changeDir, relativePath) {
+    return join(changeDir, relativePath);
+}
+export function getApprovalHtmlOutputPath(changeDir) {
+    return join(changeDir, 'approval.html');
+}

package/dist/core/approval/pipeline.d.ts

@@ -0,0 +1,28 @@
+import type { ApprovalDiagnostic } from './types.js';
+export type ApprovalFinalizeStage = 'lint' | 'review-pack' | 'review-required' | 'review-check' | 'check' | 'assemble' | 'bundle' | 'done';
+export interface FinalizeApprovalOptions {
+    readonly changeDir: string;
+    readonly workspaceRoot?: string;
+    readonly strict?: boolean;
+    readonly skipReview?: boolean;
+    readonly force?: boolean;
+    readonly bundle?: boolean | 'auto';
+    readonly playbook?: string;
+    readonly dryRun?: boolean;
+    readonly validateLazy?: boolean;
+}
+export interface FinalizeApprovalResult {
+    readonly ok: boolean;
+    readonly paused?: boolean;
+    readonly stage: ApprovalFinalizeStage;
+    readonly change: string;
+    readonly outputPath?: string;
+    readonly bundlePath?: string;
+    readonly reviewPacketPath?: string;
+    readonly diagnostics: readonly ApprovalDiagnostic[];
+}
+/**
+ * One-shot ACP finalize: lint → review gate → check → assemble → optional bundle.
+ * When AI review is required but review-result.json is missing, pauses after review-pack.
+ */
+export declare function finalizeApprovalDocument(options: FinalizeApprovalOptions): Promise<FinalizeApprovalResult>;

package/dist/core/approval/pipeline.js

@@ -0,0 +1,146 @@
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { assembleApprovalDocument, readApprovalIndex } from './assemble.js';
+import { lintApprovalDocument } from './lint.js';
+import { bundleApprovalDocument, resolvePlaybookPath } from './bundle.js';
+import { checkApprovalReview, generateReviewPacket } from './review-pack.js';
+import { getApprovalReviewPath } from './paths.js';
+function mergeDiagnostics(target, next) {
+    target.push(...next);
+    return next.some((d) => d.severity === 'error');
+}
+async function reviewResultExists(changeDir) {
+    try {
+        await fs.access(getApprovalReviewPath(changeDir));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function shouldRunBundle(bundleOption, multiRepoBundleEnabled) {
+    if (bundleOption === true) {
+        return true;
+    }
+    if (bundleOption === false) {
+        return false;
+    }
+    return multiRepoBundleEnabled === true;
+}
+/**
+ * One-shot ACP finalize: lint → review gate → check → assemble → optional bundle.
+ * When AI review is required but review-result.json is missing, pauses after review-pack.
+ */
+export async function finalizeApprovalDocument(options) {
+    const diagnostics = [];
+    const { changeDir, workspaceRoot = join(changeDir, '..', '..', '..'), strict = true, skipReview = false, force = true, bundle = 'auto', dryRun = false, validateLazy = true, } = options;
+    let index;
+    try {
+        index = await readApprovalIndex(changeDir);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            stage: 'lint',
+            change: '',
+            diagnostics: [
+                { code: 'missing_index', severity: 'error', message: `Cannot read index: ${message}` },
+            ],
+        };
+    }
+    const lintResult = await lintApprovalDocument({ changeDir, strict });
+    if (mergeDiagnostics(diagnostics, lintResult.diagnostics) || !lintResult.ok) {
+        return { ok: false, stage: 'lint', change: index.change, diagnostics };
+    }
+    const reviewEnabled = !skipReview &&
+        (index.acp?.review?.enabled === true || index.acp?.review?.required_pass === true);
+    let reviewPacketPath;
+    if (reviewEnabled) {
+        const hasReviewResult = await reviewResultExists(changeDir);
+        if (!hasReviewResult) {
+            const packResult = await generateReviewPacket({ changeDir });
+            reviewPacketPath = packResult.packetPath;
+            mergeDiagnostics(diagnostics, packResult.diagnostics);
+            if (!packResult.ok) {
+                return {
+                    ok: false,
+                    stage: 'review-pack',
+                    change: index.change,
+                    reviewPacketPath,
+                    diagnostics,
+                };
+            }
+            diagnostics.push({
+                code: 'review_required',
+                severity: 'error',
+                message: 'AI review required: read prompts/approval/ai-review.md, fix parts, write approval/review-result.json, then re-run specflow approval finalize',
+            });
+            return {
+                ok: false,
+                paused: true,
+                stage: 'review-required',
+                change: index.change,
+                reviewPacketPath,
+                diagnostics,
+            };
+        }
+        const reviewCheck = await checkApprovalReview({
+            changeDir,
+            requirePass: true,
+            forceRequire: index.acp?.review?.required_pass === true,
+        });
+        if (mergeDiagnostics(diagnostics, reviewCheck.diagnostics) || !reviewCheck.ok) {
+            return { ok: false, stage: 'review-check', change: index.change, diagnostics };
+        }
+    }
+    const checkResult = await assembleApprovalDocument({
+        changeDir,
+        checkOnly: true,
+        validateLazy,
+    });
+    if (mergeDiagnostics(diagnostics, checkResult.diagnostics) || !checkResult.ok) {
+        return { ok: false, stage: 'check', change: index.change, diagnostics };
+    }
+    if (dryRun) {
+        return { ok: true, stage: 'done', change: index.change, diagnostics };
+    }
+    const assembleResult = await assembleApprovalDocument({
+        changeDir,
+        checkOnly: false,
+        force,
+        validateLazy,
+    });
+    if (mergeDiagnostics(diagnostics, assembleResult.diagnostics) || !assembleResult.ok) {
+        return { ok: false, stage: 'assemble', change: index.change, diagnostics };
+    }
+    let bundlePath;
+    if (shouldRunBundle(bundle, index.multi_repo?.bundle?.enabled)) {
+        const playbookPath = await resolvePlaybookPath(changeDir, options.playbook);
+        const bundleResult = await bundleApprovalDocument({
+            workspaceRoot,
+            changeDir,
+            playbookPath,
+            write: true,
+        });
+        bundlePath = bundleResult.outputPath;
+        if (mergeDiagnostics(diagnostics, bundleResult.diagnostics) || !bundleResult.ok) {
+            return {
+                ok: false,
+                stage: 'bundle',
+                change: index.change,
+                outputPath: assembleResult.outputPath,
+                bundlePath,
+                diagnostics,
+            };
+        }
+    }
+    return {
+        ok: true,
+        stage: 'done',
+        change: index.change,
+        outputPath: assembleResult.outputPath,
+        bundlePath,
+        diagnostics,
+    };
+}