@gordon.gan/specflow 1.8.0-beta → 1.8.2-beta

package/dist/core/approval/assemble.js

@@ -1,384 +0,0 @@
-import { createHash } from 'node:crypto';
-import { promises as fs } from 'node:fs';
-import yaml from 'js-yaml';
-import { parseApprovalIndex } from './index-schema.js';
-import { findForbiddenMatch } from './forbidden-patterns.js';
-import { getApprovalIndexPath, getApprovalManifestPath, getApprovalOutputPath, getApprovalPartPath, getApprovalPartsDir, } from './paths.js';
-const OPTIONAL_PREFIXES = {
-    s5: ['05-', '05.'],
-    s7: ['07-', '07.'],
-    s8: ['08-', '08.'],
-};
-const CHAPTER_HEADERS = {
-    '01-intro': '## 1. 绪论与边界 (Introduction & Boundaries)',
-    '02-design-review': '## 2. 技术方案评估 (Technical Design Review)',
-    '03-architecture': '## 3. 架构整体设计 (Architecture Design)',
-    '05-acceptance': '## 5. 验收标准 (Acceptance Criteria)',
-    '06-test': '## 6. 测试策略 (Test Strategy)',
-    '07-deploy': '## 7. 部署/发布/回滚方案 (Deployment & Release)',
-    '08-closed-loop': '## 8. 闭环性检查 (Closed-Loop Verification)',
-    '09-implementability': '## 9. 可实施性评估 (Implementability Assessment)',
-    '10-signoff': '## 10. 审批意见 (Approval Decision)',
-    'appendix-a': '## 附录 A: 产物溯源',
-};
-const SECTION4_HEADER = '## 4. 方案详细设计 (Detailed Design)';
-const MIN_PART_BYTES = {
-    '04.4': 200,
-    '04.5': 200,
-    '04.6': 150,
-    '05-': 100,
-};
-function sha256(content) {
-    return createHash('sha256').update(content, 'utf8').digest('hex');
-}
-function isOptionalPart(partId, optional) {
-    if (OPTIONAL_PREFIXES.s5.some((p) => partId.startsWith(p))) {
-        return !optional.s5;
-    }
-    if (OPTIONAL_PREFIXES.s7.some((p) => partId.startsWith(p))) {
-        return !optional.s7;
-    }
-    if (OPTIONAL_PREFIXES.s8.some((p) => partId.startsWith(p))) {
-        return !optional.s8;
-    }
-    return false;
-}
-function isSection4Part(partId) {
-    return partId === '04-detail-core' || partId.startsWith('04.');
-}
-function headerForPart(partId) {
-    if (isSection4Part(partId)) {
-        return null;
-    }
-    if (CHAPTER_HEADERS[partId]) {
-        return CHAPTER_HEADERS[partId];
-    }
-    for (const [key, header] of Object.entries(CHAPTER_HEADERS)) {
-        if (partId.startsWith(key)) {
-            return header;
-        }
-    }
-    return null;
-}
-function detectLazyContent(partId, content) {
-    const trimmed = content.trim();
-    if (trimmed.length < 20) {
-        return 'part content too short (< 20 chars)';
-    }
-    for (const prefix of Object.keys(MIN_PART_BYTES)) {
-        if (partId.startsWith(prefix) && trimmed.length < MIN_PART_BYTES[prefix]) {
-            return `part content below minimum for ${prefix} (${trimmed.length} bytes)`;
-        }
-    }
-    const forbidden = findForbiddenMatch(trimmed);
-    if (forbidden) {
-        return `lazy/stub pattern detected: ${forbidden.source}`;
-    }
-    if (/^#+\s*4\.\s/m.test(trimmed)) {
-        return 'part must not contain top-level "## 4." heading (assemble injects section 4)';
-    }
-    if (/^##\s+[1-9]\d?\./m.test(trimmed) && !partId.startsWith('05-c')) {
-        const match = trimmed.match(/^##\s+([1-9]\d?)\./m);
-        if (match && !partId.startsWith(`${match[1].padStart(2, '0')}`)) {
-            return 'part must not inject foreign chapter "## N." headings';
-        }
-    }
-    return null;
-}
-function partHasAppendixA(partContents) {
-    for (const content of partContents.values()) {
-        if (/^#{2,3}\s+附录\s*A/m.test(content)) {
-            return true;
-        }
-    }
-    return false;
-}
-function buildDocumentHeader(index) {
-    const meta = index.meta ?? {};
-    const lang = meta.language ?? 'en';
-    const stack = meta.tech_stack ?? 'unknown';
-    const projectMode = meta.project_mode ?? 'brownfield';
-    const modeNote = index.mode === 'segmented' ? 'segmented+assemble' : 'monolithic';
-    let multiRepoBlock = '';
-    const mr = index.multi_repo;
-    if (mr?.enabled && mr.repos.length >= 2) {
-        const mode = mr.document_mode ?? 'pending';
-        const primary = mr.primary_repo ?? '—';
-        const bundleNote = mr.bundle?.enabled ? ' | 合订: approval bundle (只读)' : '';
-        const repoLines = mr.repos
-            .map((r) => `- ${r.label} \`${r.id}/${r.change}\``)
-            .join('\n');
-        multiRepoBlock = `
-> **多仓范围** (${mode}${mode === 'unified' ? `, 主仓: ${primary}` : mr.bundle?.enabled ? `, bundle 主仓: ${primary}` : ''}${bundleNote}):
-${repoLines}
-`;
-    }
-    return `# 技术方案审批文档: ${index.change}
-${multiRepoBlock}
-> 本文档由 \`/specflow:approval\` 基于 refine 收敛后的四件套 + 现有代码与 spec 基线生成,
-> 含架构与详细设计等章节,供人工审批使用。AI 闭环/预审结论在对话中反馈,不写入本文。
-> 生成时间: ${index.generated_at} | phase: refined | 产物语言: ${lang} | 技术栈: ${stack} | 项目模式: ${projectMode} | 生成模式: ${modeNote}
-
-> **质量红线(必须满足)**:G1 超 5 行流程→图示 · G2 接口须有失败示例 · G3 JSON/新列须有存量填充策略 · G4 须有回滚数据兼容说明 · G5 有 UI 须有页面/路由清单+栈五元组 · G6 关键页须有空/加载/错态。  
-> **文风**:通俗中文、缩写首次注解、禁用含糊词;**正文禁止代码腔**(路径/函数名堆砌→可读中文)。
-
----
-`;
-}
-function buildAppendix() {
-    return `
----
-
-## 附录 A: 产物溯源
-
-| 章节 | 数据来源 | 处理方式 |
-|------|---------|---------|
-| 绪论与边界 | proposal + explore(可选) | AI 提炼 |
-| 技术方案评估 | design + 用户确认选型(若有) | 约束 + 技术选型 + 决策/风险/质量 |
-| 架构 / 详细设计 | design + specs + 锚点 + 约定 | 图+要点+数据/接口/前端 |
-| 验收标准 | specs | **可选** |
-| 测试策略 | §5 或 specs 名 | 分层矩阵 |
-| 部署/闭环 | 运行环境 / Pass 1–7 | **可选** |
-| 可实施性 | 四件套+代码 | 写入文档 |
-| 审批意见 | 人工 | 仅签字栏 |
-`;
-}
-export async function readApprovalIndex(changeDir) {
-    const raw = yaml.load(await fs.readFile(getApprovalIndexPath(changeDir), 'utf-8'));
-    return parseApprovalIndex(raw);
-}
-export async function readApprovalManifest(changeDir) {
-    const path = getApprovalManifestPath(changeDir);
-    try {
-        const raw = JSON.parse(await fs.readFile(path, 'utf-8'));
-        return raw;
-    }
-    catch {
-        return null;
-    }
-}
-export async function assembleApprovalDocument(options) {
-    const diagnostics = [];
-    const { changeDir, checkOnly = false, force = 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,
-            diagnostics: [
-                {
-                    code: 'missing_index',
-                    severity: 'error',
-                    message: `Cannot read approval/index.yaml: ${message}`,
-                },
-            ],
-        };
-    }
-    if (index.multi_repo?.enabled) {
-        const mr = index.multi_repo;
-        if (!mr.document_mode) {
-            diagnostics.push({
-                code: 'multi_repo_mode_missing',
-                severity: 'error',
-                message: 'multi_repo.enabled but document_mode not set; ask user unified vs per_repo before assemble',
-            });
-        }
-        if (mr.document_mode === 'unified') {
-            if (!mr.primary_repo) {
-                diagnostics.push({
-                    code: 'multi_repo_primary_missing',
-                    severity: 'error',
-                    message: 'multi_repo.document_mode=unified requires primary_repo',
-                });
-            }
-            else {
-                const primary = mr.repos.find((r) => r.id === mr.primary_repo);
-                if (primary && primary.change !== index.change) {
-                    diagnostics.push({
-                        code: 'multi_repo_change_mismatch',
-                        severity: 'warning',
-                        message: `index.change "${index.change}" differs from primary repo change "${primary.change}"; assemble in primary planning root`,
-                    });
-                }
-            }
-        }
-        if (mr.document_mode === 'per_repo' && !mr.outputs?.per_repo?.length) {
-            diagnostics.push({
-                code: 'multi_repo_outputs_missing',
-                severity: 'warning',
-                message: 'per_repo mode should list outputs.per_repo[] with each repo approval path',
-            });
-        }
-    }
-    const partsDir = getApprovalPartsDir(changeDir);
-    try {
-        await fs.access(partsDir);
-    }
-    catch {
-        diagnostics.push({
-            code: 'missing_parts_dir',
-            severity: 'error',
-            message: `Missing approval/parts/ directory at ${partsDir}`,
-        });
-        return { ok: false, diagnostics };
-    }
-    const partContents = new Map();
-    let section4Opened = false;
-    const body = [buildDocumentHeader(index)];
-    for (const partId of index.parts_order) {
-        if (isOptionalPart(partId, index.optional)) {
-            continue;
-        }
-        const partPath = getApprovalPartPath(changeDir, partId);
-        let content;
-        try {
-            content = await fs.readFile(partPath, 'utf-8');
-        }
-        catch {
-            diagnostics.push({
-                code: 'missing_part',
-                severity: 'error',
-                message: `Missing part file for "${partId}" at ${partPath}`,
-                part: partId,
-            });
-            continue;
-        }
-        if (validateLazy) {
-            const lazy = detectLazyContent(partId, content);
-            if (lazy) {
-                diagnostics.push({
-                    code: 'lazy_part_content',
-                    severity: 'error',
-                    message: `Part "${partId}": ${lazy}`,
-                    part: partId,
-                });
-            }
-        }
-        partContents.set(partId, content);
-        if (isSection4Part(partId)) {
-            if (!section4Opened) {
-                body.push(SECTION4_HEADER, '', '---', '');
-                section4Opened = true;
-            }
-            body.push(content.trim(), '');
-            continue;
-        }
-        const header = headerForPart(partId);
-        if (header) {
-            body.push(header, '');
-        }
-        body.push(content.trim(), '', '---', '');
-    }
-    if (!index.parts_order.includes('appendix-a') && !partHasAppendixA(partContents)) {
-        body.push(buildAppendix().trim());
-    }
-    for (const table of index.tables) {
-        if (!partContents.has(table.part)) {
-            diagnostics.push({
-                code: 'id_part_mismatch',
-                severity: 'error',
-                message: `Table "${table.id}" references missing part "${table.part}"`,
-                part: table.part,
-            });
-        }
-    }
-    for (const iface of index.interfaces) {
-        if (!partContents.has(iface.part)) {
-            diagnostics.push({
-                code: 'id_part_mismatch',
-                severity: 'error',
-                message: `Interface "${iface.id}" references missing part "${iface.part}"`,
-                part: iface.part,
-            });
-        }
-    }
-    if (index.ui_in_scope) {
-        for (const page of index.pages) {
-            if (!partContents.has(page.part)) {
-                diagnostics.push({
-                    code: 'id_part_mismatch',
-                    severity: 'error',
-                    message: `Page "${page.id}" references missing part "${page.part}"`,
-                    part: page.part,
-                });
-            }
-        }
-    }
-    for (const partId of index.parts_order) {
-        if (isOptionalPart(partId, index.optional)) {
-            continue;
-        }
-        if (!partContents.has(partId)) {
-            continue;
-        }
-    }
-    const diskParts = await fs.readdir(partsDir);
-    for (const file of diskParts) {
-        if (!file.endsWith('.md')) {
-            continue;
-        }
-        const id = file.replace(/\.md$/, '');
-        const optionalSkipped = isOptionalPart(id, index.optional);
-        const inOrder = index.parts_order.includes(id);
-        if (!inOrder && !optionalSkipped) {
-            diagnostics.push({
-                code: 'orphan_part',
-                severity: 'warning',
-                message: `Part file "${file}" exists but is not listed in index.parts_order`,
-                part: id,
-            });
-        }
-        if (optionalSkipped && inOrder) {
-            diagnostics.push({
-                code: 'optional_present_but_disabled',
-                severity: 'warning',
-                message: `Optional chapter disabled but part "${id}" is still in parts_order`,
-                part: id,
-            });
-        }
-    }
-    const hasError = diagnostics.some((d) => d.severity === 'error');
-    if (hasError) {
-        return { ok: false, diagnostics };
-    }
-    const markdown = body.join('\n').replace(/\n{3,}/g, '\n\n').trim() + '\n';
-    const outputPath = getApprovalOutputPath(changeDir);
-    if (checkOnly) {
-        return { ok: true, markdown, outputPath, diagnostics };
-    }
-    if (!force) {
-        try {
-            await fs.access(outputPath);
-            diagnostics.push({
-                code: 'output_exists',
-                severity: 'warning',
-                message: `${outputPath} already exists; use --force to overwrite`,
-            });
-            return { ok: false, diagnostics, markdown, outputPath };
-        }
-        catch {
-            // ok to write
-        }
-    }
-    await fs.writeFile(outputPath, markdown, 'utf-8');
-    const manifest = {
-        schema: 'specflow.approval.manifest/v1',
-        change: index.change,
-        parts: index.parts_order
-            .filter((id) => partContents.has(id))
-            .map((id) => ({
-            id,
-            path: `approval/parts/${id}.md`,
-            status: 'ok',
-            sha256: sha256(partContents.get(id)),
-            updated_at: index.generated_at,
-        })),
-        assembled_at: new Date().toISOString(),
-        approval_sha256: sha256(markdown),
-    };
-    await fs.writeFile(getApprovalManifestPath(changeDir), JSON.stringify(manifest, null, 2), 'utf-8');
-    return { ok: true, markdown, outputPath, diagnostics };
-}

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

@@ -1,9 +0,0 @@
-import type { ApprovalBundleResult } from './types.js';
-export interface BundleApprovalOptions {
-    readonly workspaceRoot: string;
-    readonly changeDir: string;
-    readonly playbookPath: string;
-    readonly write?: boolean;
-}
-export declare function bundleApprovalDocument(options: BundleApprovalOptions): Promise<ApprovalBundleResult>;
-export declare function resolvePlaybookPath(changeDir: string, explicitPath?: string): Promise<string>;

package/dist/core/approval/bundle.js

@@ -1,172 +0,0 @@
-import { createHash } from 'node:crypto';
-import { promises as fs } from 'node:fs';
-import { join, dirname } from 'node:path';
-import yaml from 'js-yaml';
-import { parseApprovalPlaybook } from './playbook-schema.js';
-import { readApprovalIndex } from './assemble.js';
-import { getApprovalPartPath, getApprovalWorkspaceDir, getChangeDirectory, } from './paths.js';
-function sha256(content) {
-    return createHash('sha256').update(content, 'utf8').digest('hex');
-}
-function resolveSourceChangeDir(workspaceRoot, source) {
-    const planningRoot = source.root ?? workspaceRoot;
-    return getChangeDirectory(planningRoot, source.change);
-}
-async function loadSourceParts(changeDir, includeParts) {
-    const index = await readApprovalIndex(changeDir);
-    const partIds = includeParts === 'all'
-        ? [...index.parts_order]
-        : includeParts.filter((id) => index.parts_order.includes(id));
-    const results = [];
-    for (const partId of partIds) {
-        try {
-            const content = await fs.readFile(getApprovalPartPath(changeDir, partId), 'utf-8');
-            results.push({ partId, content });
-        }
-        catch {
-            // skip missing
-        }
-    }
-    return results;
-}
-export async function bundleApprovalDocument(options) {
-    const diagnostics = [];
-    const { workspaceRoot, changeDir, playbookPath, write = true } = options;
-    let playbook;
-    let indexOutputOverride;
-    try {
-        const raw = yaml.load(await fs.readFile(playbookPath, 'utf-8'));
-        playbook = parseApprovalPlaybook(raw);
-        try {
-            const index = await readApprovalIndex(changeDir);
-            indexOutputOverride = index.multi_repo?.bundle?.output;
-        }
-        catch {
-            // index optional for bundle-only dry runs
-        }
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return {
-            ok: false,
-            diagnostics: [
-                { code: 'invalid_playbook', severity: 'error', message: `Invalid playbook: ${message}` },
-            ],
-        };
-    }
-    const body = [];
-    body.push(`# ${playbook.title}`);
-    body.push('');
-    body.push(`> **合订视图** (read-only bundle) | change: \`${playbook.change}\``);
-    body.push(`> 生成方式: \`specflow approval bundle\` — 确定性拼接，禁止 LLM Reduce`);
-    body.push(`> 主仓: \`${playbook.primary_repo}\``);
-    body.push('');
-    body.push('---');
-    body.push('');
-    if (playbook.overlay && playbook.overlay.length > 0) {
-        const approvalDir = getApprovalWorkspaceDir(changeDir);
-        for (const overlayRel of playbook.overlay) {
-            const overlayPath = join(approvalDir, overlayRel);
-            try {
-                const content = await fs.readFile(overlayPath, 'utf-8');
-                if (playbook.assemble.inject_headers !== false) {
-                    body.push(`## Overlay · ${overlayRel}`);
-                    body.push('');
-                }
-                body.push(content.trim());
-                body.push('');
-                body.push('---');
-                body.push('');
-            }
-            catch {
-                diagnostics.push({
-                    code: 'overlay_missing',
-                    severity: 'error',
-                    message: `Overlay file not found: ${overlayPath}`,
-                });
-            }
-        }
-    }
-    for (const source of playbook.sources) {
-        const sourceChangeDir = resolveSourceChangeDir(workspaceRoot, source);
-        try {
-            await fs.access(sourceChangeDir);
-        }
-        catch {
-            diagnostics.push({
-                code: 'source_change_missing',
-                severity: 'error',
-                message: `Source change not found: ${sourceChangeDir} (repo=${source.repo})`,
-            });
-            continue;
-        }
-        const includeParts = source.include_parts ?? 'all';
-        const parts = await loadSourceParts(sourceChangeDir, includeParts);
-        if (parts.length === 0) {
-            diagnostics.push({
-                code: 'source_parts_empty',
-                severity: 'warning',
-                message: `No parts loaded for source ${source.repo}/${source.change}`,
-            });
-        }
-        if (playbook.assemble.inject_headers !== false) {
-            body.push(`## 来源 · ${source.repo} (\`${source.change}\`)`);
-            body.push('');
-        }
-        for (const { partId, content } of parts) {
-            body.push(`<!-- bundle-source: ${source.repo}/${source.change}/${partId} -->`);
-            body.push(content.trim());
-            body.push('');
-        }
-        body.push('---');
-        body.push('');
-    }
-    if (diagnostics.some((d) => d.severity === 'error')) {
-        return { ok: false, diagnostics };
-    }
-    let markdown = body.join('\n').replace(/\n{3,}/g, '\n\n').trim() + '\n';
-    if (playbook.assemble.dedupe_appendix !== false) {
-        const appendixMatches = markdown.match(/^##\s+附录\s*A/mg);
-        if (appendixMatches && appendixMatches.length > 1) {
-            diagnostics.push({
-                code: 'duplicate_appendix',
-                severity: 'warning',
-                message: `Bundle output contains ${appendixMatches.length} "## 附录 A" headings`,
-            });
-        }
-    }
-    if (playbook.assemble.readonly) {
-        markdown =
-            `> **READ-ONLY VIEW** — apply 请使用各仓 \`approval.md\` 真源，勿直接消费本合订文件。\n\n` +
-                markdown;
-    }
-    const outputRel = indexOutputOverride ?? playbook.assemble.output;
-    const outputPath = join(changeDir, outputRel);
-    if (!write) {
-        return { ok: true, markdown, outputPath, diagnostics };
-    }
-    await fs.mkdir(dirname(outputPath), { recursive: true });
-    await fs.writeFile(outputPath, markdown, 'utf-8');
-    const bundleManifestPath = join(getApprovalWorkspaceDir(changeDir), 'bundle-manifest.json');
-    await fs.writeFile(bundleManifestPath, JSON.stringify({
-        schema: 'specflow.approval.bundle-manifest/v1',
-        change: playbook.change,
-        playbook: playbookPath,
-        output: outputRel,
-        sha256: sha256(markdown),
-        assembled_at: new Date().toISOString(),
-        sources: playbook.sources.map((s) => ({ repo: s.repo, change: s.change })),
-    }, null, 2), 'utf-8');
-    return { ok: true, markdown, outputPath, diagnostics };
-}
-export async function resolvePlaybookPath(changeDir, explicitPath) {
-    if (explicitPath) {
-        return explicitPath;
-    }
-    const index = await readApprovalIndex(changeDir);
-    const fromIndex = index.multi_repo?.bundle?.playbook;
-    if (fromIndex) {
-        return join(getApprovalWorkspaceDir(changeDir), fromIndex);
-    }
-    return join(getApprovalWorkspaceDir(changeDir), 'approval-playbook.yaml');
-}

package/dist/core/approval/forbidden-patterns.js

@@ -1,40 +0,0 @@
-/** Shared stub / inconsistency patterns for assemble lazy-check and approval lint. */
-export const FORBIDDEN_STUB_PATTERNS = [
-    /\bTODO\b/i,
-    /待补充/,
-    /待 refine 澄清(?!.*\[)/,
-    /此处省略/,
-    /详见\s*(?:上文|下文|附件)(?!.*§)/,
-    /略\s*[。.]?$/,
-    /TBD\s*[。.]?$/,
-    /(?:^|\n)\s*\.{3}\s*(?:\n|$)/,
-    /(?:^|\n)\s*(?:同上|同前)\s*[。.]?\s*(?:\n|$)/,
-    /实现时(?:命名|对齐)/,
-    /(?:RPC|rpc).*暂定/,
-    /暂定\s*[`']?\w+[`']?/,
-    /\b如\s+[A-Z]\w*(?:Result|Request|Response)/,
-    /内部(?:经|调用)\s*I\d+[^.\n]{0,40}(?:一行|代替|省略)/,
-];
-/** Semantic inconsistency hints (warnings unless strict mode) — long-document generic. */
-export const INCONSISTENCY_HINT_PATTERNS = [
-    /约\s*\d+\s*次/,
-    /\b(?:等|etc\.?)\s*[。.)]/,
-    /(?:status|状态|enum|枚举)[^.\n]{0,30}(?:等|etc)/i,
-    /(?:^|[\s，。；])同前(?!缀)/,
-    /(?:^|[\s，。；])同上(?!所述)/,
-    /(?:^|[\s，。；])见上(?!游)/,
-    /\b(?:待定|未定)\b/i,
-    /(?<![无未不否])\bTBD\b/i,
-    /\d+\s*[或\\/]\s*\d+\s*(?:均可|都行)/,
-];
-export function findForbiddenMatch(content) {
-    for (const pattern of FORBIDDEN_STUB_PATTERNS) {
-        if (pattern.test(content)) {
-            return pattern;
-        }
-    }
-    return null;
-}
-export function findInconsistencyHints(content) {
-    return INCONSISTENCY_HINT_PATTERNS.filter((p) => p.test(content));
-}