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

package/dist/cli/index.js

@@ -16,7 +16,7 @@ import { registerStoreCommand } from './commands/store.js';
 import { registerShowCommand } from './commands/show.js';
 import { registerContextCommand } from './commands/context.js';
 import { registerWorksetCommand } from './commands/workset.js';
-import { registerApprovalAssembleCommand } from './commands/approval-assemble.js';
+import { registerDocumentRunCommand } from './commands/document-run.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf-8'));
@@ -44,7 +44,7 @@ registerStoreCommand(program);
 registerShowCommand(program);
 registerContextCommand(program);
 registerWorksetCommand(program);
-registerApprovalAssembleCommand(program);
+registerDocumentRunCommand(program);
 program.exitOverride();
 try {
     await program.parseAsync();

package/dist/core/artifact-language.js

@@ -18,13 +18,23 @@ export function requireArtifactLanguage(value) {
 }
 export function renderArtifactLanguageGuidance(language) {
     const narrativeLanguage = language === 'zh-CN' ? 'Simplified Chinese' : 'English';
+    const styleLines = language === 'zh-CN'
+        ? [
+            'Chinese narrative must be brief: one idea per sentence; no filler.',
+            'Write how-to / process / handling as numbered 1. 2. 3. steps (one sentence each).',
+            'Do not collapse multi-step flows into a paragraph.',
+            'Leave tables, Mermaid, DDL, HTTP examples, and protocol markers unchanged.',
+        ]
+        : ['Keep narrative concise. Use numbered steps for how-to. Leave tables and diagrams unchanged.'];
     return [
         '## Artifact language policy',
         '',
         `Write all non-protocol business content in ${narrativeLanguage}.`,
-        'This includes proposal narrative, requirement and scenario descriptions, text after WHEN/THEN, design rationale, and task descriptions.',
+        'This includes proposal narrative, requirement and scenario descriptions, text after WHEN/THEN, design rationale, task descriptions, explore, and approval.',
         'Do not mix narrative languages in the same artifact.',
         '',
+        ...styleLines,
+        '',
         'Keep SpecFlow protocol markers unchanged, including:',
         '- `ADDED Requirements`, `MODIFIED Requirements`, `REMOVED Requirements`, and `RENAMED Requirements`',
         '- `Requirement:`, `Scenario:`, `WHEN`, and `THEN`',

package/dist/core/document/asset-paths.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Document Engine — template asset path resolution.
+ *
+ * Templates (templates/document/chapters, templates/document/profiles) are loaded from two
+ * places, in priority order:
+ *   1. `<project-cwd>/templates` — user-overridable templates (e.g. a repo ships its own).
+ *   2. The specflow package's own `templates/` dir — so the CLI works from ANY directory
+ *      (multi-repo workspaces, repos initialized elsewhere) instead of failing when cwd
+ *      has no templates. This fixes "synthesize 因模板路径失败" when running in a workspace
+ *      that is not the specflow checkout.
+ */
+/** 候选模板根目录（含用户 cwd 覆盖与包内 fallback）。 */
+export declare function templateRoots(projectDir?: string): string[];
+/** 在模板根目录候选里找第一个存在的目录；都不存在则返回包内默认（让上层报可读错误）。 */
+export declare function resolveTemplateDir(subpath: string, projectDir?: string): Promise<string>;

package/dist/core/document/asset-paths.js

@@ -0,0 +1,38 @@
+/**
+ * Document Engine — template asset path resolution.
+ *
+ * Templates (templates/document/chapters, templates/document/profiles) are loaded from two
+ * places, in priority order:
+ *   1. `<project-cwd>/templates` — user-overridable templates (e.g. a repo ships its own).
+ *   2. The specflow package's own `templates/` dir — so the CLI works from ANY directory
+ *      (multi-repo workspaces, repos initialized elsewhere) instead of failing when cwd
+ *      has no templates. This fixes "synthesize 因模板路径失败" when running in a workspace
+ *      that is not the specflow checkout.
+ */
+import { promises as fs } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** specflow 包根：从当前模块（dist/core/document/*.js）上溯到包根（templates 所在层）。 */
+function packageRoot() {
+    const here = dirname(fileURLToPath(import.meta.url)); // <pkg>/dist/core/document
+    return dirname(dirname(dirname(here))); // <pkg>/dist/core → <pkg>/dist → <pkg>
+}
+/** 候选模板根目录（含用户 cwd 覆盖与包内 fallback）。 */
+export function templateRoots(projectDir = process.cwd()) {
+    return [join(projectDir, 'templates'), join(packageRoot(), 'templates')];
+}
+/** 在模板根目录候选里找第一个存在的目录；都不存在则返回包内默认（让上层报可读错误）。 */
+export async function resolveTemplateDir(subpath, projectDir) {
+    for (const root of templateRoots(projectDir)) {
+        const candidate = join(root, subpath);
+        try {
+            const st = await fs.stat(candidate);
+            if (st.isDirectory())
+                return candidate;
+        }
+        catch {
+            // not present → try next
+        }
+    }
+    return join(packageRoot(), 'templates', subpath);
+}

package/dist/core/document/chapters.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Document Engine — chapter component library loader.
+ * Loads templates/document/chapters/*.yaml, validates each parses, returns a Map.
+ */
+import { ChapterComponent } from './schemas.js';
+export declare function loadChapterLibrary(dir?: string): Promise<Map<string, ChapterComponent>>;

package/dist/core/document/chapters.js

@@ -0,0 +1,38 @@
+/**
+ * Document Engine — chapter component library loader.
+ * Loads templates/document/chapters/*.yaml, validates each parses, returns a Map.
+ */
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import yaml from 'js-yaml';
+import { parseChapterComponent } from './schemas.js';
+import { resolveTemplateDir } from './asset-paths.js';
+export async function loadChapterLibrary(dir) {
+    // 默认从「用户 cwd/templates 优先、包内 templates fallback」解析（多仓工作区也能跑）。
+    const resolvedDir = dir ?? (await resolveTemplateDir(join('document', 'chapters')));
+    const entries = await fs.readdir(resolvedDir, { withFileTypes: true });
+    const lib = new Map();
+    const seen = new Set();
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue; // 跳过目录（P2：避免 EISDIR）
+        const file = entry.name;
+        if (!file.endsWith('.yaml') && !file.endsWith('.yml'))
+            continue;
+        let raw;
+        try {
+            raw = yaml.load(await fs.readFile(join(resolvedDir, file), 'utf-8'));
+        }
+        catch (e) {
+            throw new Error(`Failed to parse chapter file ${file}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const ch = parseChapterComponent(raw);
+        // 重复 id 检测（P2）：Map.set 静默覆盖且覆盖顺序依赖目录枚举，id 碰撞会静默改变整条流水线。
+        if (seen.has(ch.id)) {
+            throw new Error(`Duplicate chapter id "${ch.id}" (in ${file}); chapter ids must be unique across templates/document/chapters/`);
+        }
+        seen.add(ch.id);
+        lib.set(ch.id, ch);
+    }
+    return lib;
+}

package/dist/core/document/coverage.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Document Engine — coverage completeness (decision 8·P1-B + decision 9·kind).
+ *
+ * Two channels:
+ *  - Structured (at generation): for kind=entity|mixed points, referenced entity ids must appear
+ *    in the chapter's structured entity contribution.
+ *  - Semantic (at review R14): for kind=narrative|mixed points, produces a checklist consumed by
+ *    the reviewer to verify the corresponding section exists and is non-stub.
+ */
+import { Outline, Entities } from './schemas.js';
+export interface CoverageDiagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+    chapter?: string;
+    point?: string;
+}
+/** Structured channel: verify referenced entities are present in the chapter's entity contribution. */
+export declare function checkStructuredCoverage(outline: Outline, chapterEntities: Map<string, Entities>): CoverageDiagnostic[];
+/** Semantic checklist for reviewer (R14): narrative|mixed points → must have a non-stub section. */
+export declare function semanticCoverageChecklist(outline: Outline): Array<{
+    chapter: string;
+    pointId: string;
+    text: string;
+}>;

package/dist/core/document/coverage.js

@@ -0,0 +1,49 @@
+/**
+ * Document Engine — coverage completeness (decision 8·P1-B + decision 9·kind).
+ *
+ * Two channels:
+ *  - Structured (at generation): for kind=entity|mixed points, referenced entity ids must appear
+ *    in the chapter's structured entity contribution.
+ *  - Semantic (at review R14): for kind=narrative|mixed points, produces a checklist consumed by
+ *    the reviewer to verify the corresponding section exists and is non-stub.
+ */
+/** Structured channel: verify referenced entities are present in the chapter's entity contribution. */
+export function checkStructuredCoverage(outline, chapterEntities) {
+    const diags = [];
+    for (const ch of outline.chapters) {
+        const ents = chapterEntities.get(ch.id) ?? { interfaces: [], tables: [], decisions: [] };
+        const present = new Set([
+            ...ents.interfaces.map((i) => i.id),
+            ...ents.tables.map((t) => t.id),
+            ...ents.decisions.map((d) => d.id),
+        ]);
+        for (const p of ch.points) {
+            if (p.kind === 'narrative')
+                continue; // narrative → semantic channel only
+            for (const ref of p.references ?? []) {
+                if (!present.has(ref)) {
+                    diags.push({
+                        code: 'entity_not_filled',
+                        severity: 'error',
+                        chapter: ch.id,
+                        point: p.id,
+                        message: `Point "${p.id}" references entity "${ref}" but chapter "${ch.id}" has no such entity`,
+                    });
+                }
+            }
+        }
+    }
+    return diags;
+}
+/** Semantic checklist for reviewer (R14): narrative|mixed points → must have a non-stub section. */
+export function semanticCoverageChecklist(outline) {
+    const list = [];
+    for (const ch of outline.chapters) {
+        for (const p of ch.points) {
+            if (p.kind === 'narrative' || p.kind === 'mixed') {
+                list.push({ chapter: ch.id, pointId: p.id, text: p.text });
+            }
+        }
+    }
+    return list;
+}

package/dist/core/document/digests.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Document Engine — dependency digests (decisions 2 + 8·P1-D + 9).
+ *
+ *  - extractConstraintList: deterministic constraint items (entity/decision/point ids) that a
+ *    chapter's digest MUST preserve (decision 8).
+ *  - generateDigest: bounded LLM summary carrying the constraint list; deterministic fallback.
+ *  - lintDigest: bidirectional lint — forward (digest ids exist in source) + reverse (constraint
+ *    items present in digest).
+ *  - recordDigestSources / affectedDownstream: invalidation propagation (decision 9).
+ */
+import { OutlineChapter, ConstraintItem, Entities } from './schemas.js';
+import type { DocumentLLM } from './llm.js';
+export declare function extractConstraintList(chapter: OutlineChapter, entities: Entities): ConstraintItem[];
+export interface DigestInput {
+    chapterId: string;
+    chapterTitle: string;
+    source: string;
+    constraints: ConstraintItem[];
+}
+export declare function generateDigest(llm: DocumentLLM, input: DigestInput): Promise<string>;
+/** Deterministic fallback: render entity registry as a one-line digest. */
+export declare function deterministicDigest(entities: Entities, ids: string[]): string;
+export interface DigestLintDiagnostic {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+}
+export declare function lintDigest(digest: string, constraints: ConstraintItem[], knownEntityIds: Set<string>): DigestLintDiagnostic[];
+export interface DigestSource {
+    chapterId: string;
+    /** entity ids this digest depends on (for granular invalidation). */
+    entityIds: string[];
+}
+export declare function recordDigestSources(chapter: OutlineChapter, sourceEntities: Entities): DigestSource;
+/**
+ * Given a changed chapter, return the set of downstream chapters whose digests are invalidated.
+ * (decision 9): only direct dependents whose digest references one of the changed entities are
+ * invalidated. Outline change → caller passes allDownstream (full invalidation).
+ */
+export declare function affectedDownstream(changedChapterId: string, changedEntityIds: string[], downstreamSources: DigestSource[]): string[];

package/dist/core/document/digests.js

@@ -0,0 +1,144 @@
+/**
+ * Document Engine — dependency digests (decisions 2 + 8·P1-D + 9).
+ *
+ *  - extractConstraintList: deterministic constraint items (entity/decision/point ids) that a
+ *    chapter's digest MUST preserve (decision 8).
+ *  - generateDigest: bounded LLM summary carrying the constraint list; deterministic fallback.
+ *  - lintDigest: bidirectional lint — forward (digest ids exist in source) + reverse (constraint
+ *    items present in digest).
+ *  - recordDigestSources / affectedDownstream: invalidation propagation (decision 9).
+ */
+// ============= Constraint extraction (T7.1) =============
+export function extractConstraintList(chapter, entities) {
+    const items = [];
+    for (const p of chapter.points) {
+        items.push({ kind: 'point', id: p.id, label: p.text.slice(0, 40) });
+        for (const ref of p.references ?? []) {
+            items.push({ kind: 'entity', id: ref, label: ref });
+        }
+    }
+    for (const d of entities.decisions) {
+        // A decision is preserved in this chapter's digest when the chapter references it
+        // (deterministic signal) or its text is mentioned in a point (heuristic fallback).
+        // (Previously wrapped in an always-true `|| true` outer condition — dead code removed.)
+        const referenced = chapter.points.some((p) => (p.references ?? []).includes(d.id));
+        const mentioned = chapter.points.some((p) => p.text.includes(d.text.slice(0, 20)));
+        if (referenced || mentioned) {
+            items.push({ kind: 'decision', id: d.id, label: d.text.slice(0, 40) });
+        }
+    }
+    // dedupe by kind+id
+    const seen = new Set();
+    return items.filter((it) => {
+        const k = `${it.kind}:${it.id}`;
+        if (seen.has(k))
+            return false;
+        seen.add(k);
+        return true;
+    });
+}
+// ============= Digest generation (T7.2) =============
+const DIGEST_SYSTEM = '你是依赖摘要生成器。为下游章节生成上游章节的紧凑摘要，必须逐项保留约束清单中的每一项（实体 id / 决策 id / 要点 id 及其一句话含义）。禁止引入上游没有的实体。';
+export async function generateDigest(llm, input) {
+    const constraintText = input.constraints.map((c) => `- ${c.kind} ${c.id}: ${c.label}`).join('\n');
+    const llmInput = {
+        system: DIGEST_SYSTEM,
+        messages: [
+            {
+                role: 'user',
+                content: `上游章节 ${input.chapterId}（${input.chapterTitle}）：\n${input.source.slice(0, 6000)}\n\n必须保留的约束清单：\n${constraintText}`,
+            },
+        ],
+    };
+    const res = await llm.complete(llmInput);
+    return res.content.trim();
+}
+/** Deterministic fallback: render entity registry as a one-line digest. */
+export function deterministicDigest(entities, ids) {
+    const lines = [];
+    for (const it of entities.interfaces) {
+        if (ids.length === 0 || ids.includes(it.id)) {
+            lines.push(`I ${it.id}: ${it.name} ${it.method} ${it.path}`);
+        }
+    }
+    for (const t of entities.tables) {
+        if (ids.length === 0 || ids.includes(t.id)) {
+            lines.push(`T ${t.id}: ${t.name}`);
+        }
+    }
+    for (const d of entities.decisions) {
+        if (ids.length === 0 || ids.includes(d.id)) {
+            lines.push(`D ${d.id}: ${d.text}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function lintDigest(digest, constraints, knownEntityIds) {
+    const diags = [];
+    // Reverse: every constraint item must appear in digest (decision 8).
+    // 用整词匹配（P2）：短 id 子串匹配会把 T1 误判为出现（T10/ST1/GET /api/T1），
+    // 或把 t1/D-1 误判为缺失 → 触发确定性回退丢弃约束。
+    for (const c of constraints) {
+        const re = new RegExp(`(^|[^A-Za-z0-9_])${escapeRegExp(c.id)}($|[^A-Za-z0-9_])`);
+        if (!re.test(digest)) {
+            diags.push({
+                code: 'constraint_missing',
+                severity: 'error',
+                message: `Digest missing constraint ${c.kind} ${c.id} (${c.label})`,
+            });
+        }
+    }
+    // Forward: any entity id mentioned in digest that we can detect must exist in known set.
+    // （P2 修复：此前 I\d+/T\d+ 被豁免导致前向检查恒不触发；现加入 D\d+ 且不再豁免。）
+    const mentioned = new Set();
+    for (const m of digest.matchAll(/`([A-Za-z0-9_.]+)`/g))
+        mentioned.add(m[1]);
+    for (const m of digest.matchAll(/\b(I\d+|T\d+|D\d+)\b/g))
+        mentioned.add(m[1]);
+    for (const id of mentioned) {
+        if (knownEntityIds.size > 0 && !knownEntityIds.has(id)) {
+            diags.push({
+                code: 'digest_hallucinated_entity',
+                severity: 'warning',
+                message: `Digest mentions unknown entity "${id}"`,
+            });
+        }
+    }
+    return diags;
+}
+/** 转义正则特殊字符（供整词匹配使用）。 */
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export function recordDigestSources(chapter, sourceEntities) {
+    const entityIds = new Set();
+    for (const p of chapter.points) {
+        for (const ref of p.references ?? [])
+            entityIds.add(ref);
+    }
+    // Include referenced entity ids that actually exist in source entities.
+    const known = new Set([
+        ...sourceEntities.interfaces.map((i) => i.id),
+        ...sourceEntities.tables.map((t) => t.id),
+    ]);
+    return {
+        chapterId: chapter.id,
+        entityIds: [...entityIds].filter((id) => known.has(id)),
+    };
+}
+/**
+ * Given a changed chapter, return the set of downstream chapters whose digests are invalidated.
+ * (decision 9): only direct dependents whose digest references one of the changed entities are
+ * invalidated. Outline change → caller passes allDownstream (full invalidation).
+ */
+export function affectedDownstream(changedChapterId, changedEntityIds, downstreamSources) {
+    const changed = new Set(changedEntityIds);
+    const affected = new Set();
+    for (const ds of downstreamSources) {
+        if (ds.chapterId === changedChapterId)
+            continue;
+        if (ds.entityIds.some((id) => changed.has(id)))
+            affected.add(ds.chapterId);
+    }
+    return [...affected];
+}

package/dist/core/document/engine.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Document Engine — unified orchestration entry (T11.2).
+ *
+ * runDocument wires Pass 0.5 → 1 → 2 → 3 → 4 + gates. Consumers inject the LLM,
+ * the work root, and the input. An `outlineOnly` mode stops after Pass 1 (for user gate).
+ */
+import { ScenarioProfile, ChapterComponent, Outline } from './schemas.js';
+import type { DocumentLLM } from './llm.js';
+import { SegmentableInput } from './input-digest.js';
+import { expandProfile } from './profiles.js';
+import { GateDiagnostic } from './gates.js';
+import { ExtractedContracts } from './extract.js';
+export interface RunDocumentOptions {
+    llm: DocumentLLM;
+    workRoot: string;
+    profile: ScenarioProfile;
+    library: Map<string, ChapterComponent>;
+    inputs: SegmentableInput[];
+    inputFeatures: Record<string, boolean>;
+    change: string;
+    outlineOnly?: boolean;
+    /** Skip Pass 3 AI review entirely (fast path; no findings applied, no review-result written). */
+    skipReview?: boolean;
+    /** User confirmation gate for the generated outline (T5.4). If absent, outline is auto-accepted
+     *  (non-interactive / test path). Return true to accept, false to reject (→ regenerate). */
+    outlineConfirmer?: (outline: Outline) => Promise<boolean>;
+    /** Incremental refill (decision 9 · invalidation propagation). When a chapter/entity changed,
+     *  only downstream chapters whose digests reference the changed entities are refilled; unaffected
+     *  chapters are reused from persisted `chapters/<id>.md` when present. Default: full refill. */
+    incremental?: {
+        changedChapterId?: string;
+        changedEntityIds?: string[];
+    };
+    maxRounds?: number;
+    renderHtmlOutput?: boolean;
+    outlinePrompt?: string;
+    reviewPrompt?: string;
+    /** Project root for deterministic contract extraction (OpenAPI/proto/DDL). Optional —
+     *  when set, engine extracts real contract entities and injects them into outline
+     *  generation as frozen candidates (grounding P0). */
+    projectRoot?: string;
+    /** Pre-extracted contracts (skip file scan). Useful for tests/hosts that already know them. */
+    extractedContracts?: ExtractedContracts;
+    /** Persist per-chapter files/entities to workRoot (default true). */
+    persist?: boolean;
+}
+export interface RunDocumentResult {
+    ok: boolean;
+    stage: string;
+    outline?: Outline;
+    documentMd?: string;
+    documentHtml?: string;
+    diagnostics: GateDiagnostic[];
+    tokenEstimate?: number;
+}
+export declare function runDocument(options: RunDocumentOptions): Promise<RunDocumentResult>;
+/** 附录覆盖校验（README §7.3）：profile.appendices 含 anti-ai 但自检条目为空/不足 → warning。 */
+export declare function appendixDiagnostics(profile: ScenarioProfile, antiAiContent: string): GateDiagnostic[];
+export interface AgentStep {
+    /** stable id: 'input-summary' | 'outline' | 'chapter:<id>' | 'review' */
+    id: string;
+    phase: 'prep' | 'outline' | 'fill' | 'review';
+    title: string;
+    description: string;
+    prompt: string;
+    inputFiles: string[];
+    outputFile: string;
+    required: boolean;
+}
+export interface PlanStepsInput {
+    profile: ScenarioProfile;
+    library: Map<string, ChapterComponent>;
+    inputFeatures: Record<string, boolean>;
+    inputs: SegmentableInput[];
+    workRoot: string;
+    /** Project root to resolve project conventions / IDE rules & skills (approval-era behaviour). */
+    projectRoot?: string;
+}
+/** Map a scene profile to the project-convention topics it should read (approval-era: 项目约定 > guidance > LLM). */
+export declare function sceneTopics(profileId: string): string[];
+export interface PlanStepsResult {
+    steps: AgentStep[];
+    chapters: string[];
+}
+/** Emit the Agent-executable step list (no LLM call — the Agent's IDE model does the work). */
+export declare function planSteps(options: PlanStepsInput): PlanStepsResult;
+export interface ValidateWorkInput {
+    profile: ScenarioProfile;
+    library: Map<string, ChapterComponent>;
+    workRoot: string;
+    renderHtmlOutput?: boolean;
+}
+export interface ValidateWorkResult {
+    ok: boolean;
+    diagnostics: GateDiagnostic[];
+    documentMd?: string;
+    documentHtml?: string;
+}
+/** Read Agent-written artifacts from workRoot, validate (lint/coverage/zod) and render. No LLM. */
+export declare function validateWork(options: ValidateWorkInput): Promise<ValidateWorkResult>;
+export { expandProfile };