@gordon.gan/specflow 1.7.0-beta → 1.8.0-alpha

package/dist/core/document/review.js

@@ -0,0 +1,157 @@
+/**
+ * Document Engine — Pass 3 AI review (decision 9 · target + max_rounds + part_hashes).
+ *
+ * Fresh-context reviewer (separate from generator) produces findings with a `target`
+ * (entity|narrative|mixed). Findings apply by target; review-result is validated against
+ * part_hashes (post-review tamper detection) and max_rounds (infinite-loop guard).
+ */
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { parseReviewResult, } from './schemas.js';
+import { chapterPath } from './paths.js';
+import { semanticCoverageChecklist } from './coverage.js';
+export const AI_REVIEW_CHECKLIST = [
+    'R1 跨章命名一致',
+    'R2 决策落地',
+    'R3 实体↔正文',
+    'R4 深度均衡',
+    'R5 交叉引用稳定',
+    'R6 图文一致',
+    'R7 契约完整',
+    'R8 枚举闭合',
+    'R9 分支闭合',
+    'R10 UI↔API 对齐',
+    'R11 场景一致',
+    'R12 stub 清除',
+    'R13 结论一致',
+    'R14 大纲要点覆盖',
+];
+// ============= Packet (T8.1) =============
+export async function buildReviewPacket(workRoot, change, outline) {
+    const chapters = new Map();
+    for (const ch of outline.chapters) {
+        try {
+            chapters.set(ch.id, await fs.readFile(chapterPath(workRoot, ch.id), 'utf-8'));
+        }
+        catch {
+            chapters.set(ch.id, '');
+        }
+    }
+    return {
+        schema: 'specflow.document.review-packet/v1',
+        change,
+        outline,
+        chapters,
+        checklist: [...AI_REVIEW_CHECKLIST],
+        semanticChecklist: semanticCoverageChecklist(outline),
+    };
+}
+// ============= Review call (T8.2) =============
+export async function reviewWithAgent(llm, packet, prompt) {
+    const checklist = packet.checklist.join('\n');
+    const semantic = packet.semanticChecklist.length > 0
+        ? packet.semanticChecklist.map((s) => `- ${s.chapter} · ${s.pointId}: ${s.text}`).join('\n')
+        : '（无 narrative/mixed 要点）';
+    const content = [
+        `# Review packet`,
+        `change: ${packet.change}`,
+        `checklist:\n${checklist}`,
+        `## R14 语义覆盖核对清单（逐要点核对：对应小节存在且有实质内容）`,
+        semantic,
+        `outline: ${JSON.stringify(packet.outline)}`,
+        `chapters:\n${[...packet.chapters.entries()].map(([id, c]) => `### ${id}\n${c}`).join('\n\n')}`,
+    ].join('\n\n');
+    const input = {
+        system: prompt ?? '你是独立长文档审查者。按 checklist 审查，输出 review-result JSON。R14 必须逐要点核对语义覆盖清单。',
+        messages: [{ role: 'user', content }],
+    };
+    let res;
+    try {
+        res = await llm.complete(input);
+    }
+    catch (e) {
+        throw new Error(`reviewWithAgent: LLM call failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    try {
+        return parseReviewResult(JSON.parse(res.content));
+    }
+    catch (e) {
+        throw new Error(`reviewWithAgent: unparsable review result: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+// ============= Apply findings by target (T8.3) =============
+export async function applyFindings(workRoot, findings, apply) {
+    for (const f of findings) {
+        if (f.status === 'fixed') {
+            await apply(f);
+        }
+    }
+}
+// ============= Part hashes (T8.4) =============
+export function sha256(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+export async function computePartHashes(workRoot, chapterIds) {
+    const out = [];
+    for (const id of chapterIds) {
+        try {
+            const content = await fs.readFile(chapterPath(workRoot, id), 'utf-8');
+            out.push({ id, sha256: sha256(content) });
+        }
+        catch {
+            // missing chapter skipped
+        }
+    }
+    return out;
+}
+export async function checkReviewResult(workRoot, review, outline) {
+    const diags = [];
+    if (review.verdict === 'fail') {
+        diags.push({ code: 'review_verdict_fail', severity: 'error', message: 'review verdict is fail' });
+    }
+    // open critical/important findings
+    for (const f of review.findings) {
+        if (f.status === 'open' && f.severity !== 'minor') {
+            diags.push({ code: 'review_finding_open', severity: 'error', message: `[${f.id}] ${f.message}` });
+        }
+        if (f.status === 'waived' && !f.waiver_reason?.trim()) {
+            diags.push({ code: 'review_waiver_missing_reason', severity: 'error', message: `[${f.id}] waived finding must include waiver_reason` });
+        }
+    }
+    // part_hashes tamper detection (decision 9): review-result MUST include a hash for every chapter
+    // that exists on disk, so post-review changes are detected. Missing coverage for a persisted
+    // chapter = incomplete review (no tamper verification).
+    const currentHashes = await computePartHashes(workRoot, outline.chapters.map((c) => c.id));
+    const current = new Map(currentHashes.map((h) => [h.id, h.sha256]));
+    const reported = new Set((review.part_hashes ?? []).map((ph) => ph.id));
+    for (const [chId] of current) {
+        if (!reported.has(chId)) {
+            diags.push({
+                code: 'review_part_hashes_missing',
+                severity: 'error',
+                message: `review-result missing part_hashes for persisted chapter "${chId}" — cannot verify no post-review tampering`,
+            });
+        }
+    }
+    for (const ph of review.part_hashes ?? []) {
+        const now = current.get(ph.id);
+        if (now !== undefined && now !== ph.sha256) {
+            diags.push({ code: 'review_part_stale', severity: 'error', message: `Chapter "${ph.id}" changed after review; re-run review` });
+        }
+    }
+    return { ok: diags.every((d) => d.severity !== 'error'), diagnostics: diags };
+}
+// ============= Persistence (T8.5) =============
+export async function writeReviewResult(workRoot, review) {
+    await fs.writeFile(join(workRoot, 'review-result.json'), JSON.stringify(review, null, 2), 'utf-8');
+}
+export async function readReviewResult(workRoot) {
+    try {
+        const raw = JSON.parse(await fs.readFile(join(workRoot, 'review-result.json'), 'utf-8'));
+        return parseReviewResult(raw);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/document/scene-detect.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Document Engine — scene detection (decision: auto-detect 0to1 / bugfix / feature from
+ * natural language; confirm with the user when uncertain).
+ *
+ * Deterministic keyword scoring as a first pass. The Agent (IDE model) may refine and confirm
+ * when confidence is low. Returns the best match + confidence + candidates.
+ */
+export type SceneProfile = '0to1' | 'bugfix' | 'feature';
+export interface SceneDetectResult {
+    profile: SceneProfile | null;
+    confidence: number;
+    candidates: Array<{
+        profile: SceneProfile;
+        score: number;
+    }>;
+    reasons: string[];
+}
+/**
+ * Detect the most likely scene profile from natural language.
+ * - Returns a profile when its score clearly leads (≥ 2× runner-up, or score ≥ threshold).
+ * - Returns null when signals are weak/conflicting → caller should confirm with the user.
+ */
+export declare function detectScene(text: string): SceneDetectResult;
+/** The user-facing prompt when detection is uncertain. */
+export declare function confirmationPrompt(result: SceneDetectResult, text: string): string;

package/dist/core/document/scene-detect.js

@@ -0,0 +1,121 @@
+/**
+ * Document Engine — scene detection (decision: auto-detect 0to1 / bugfix / feature from
+ * natural language; confirm with the user when uncertain).
+ *
+ * Deterministic keyword scoring as a first pass. The Agent (IDE model) may refine and confirm
+ * when confidence is low. Returns the best match + confidence + candidates.
+ */
+const KEYWORDS = {
+    // 从零做一个产品/项目
+    '0to1': [
+        { text: '想做', weight: 3 },
+        { text: '想做一个', weight: 4 },
+        { text: '打算做', weight: 3 },
+        { text: '做一个', weight: 2 },
+        { text: '从零', weight: 3 },
+        { text: '新产品', weight: 2 },
+        { text: 'startup', weight: 2 },
+        { text: '想法', weight: 2 },
+        { text: 'idea', weight: 2 },
+        { text: '开始做', weight: 2 },
+        { text: '立项', weight: 2 },
+        { text: '技术选型', weight: 1 },
+        { text: 'mvp', weight: 1 },
+        { text: 'MVP', weight: 1 },
+    ],
+    // 修 bug / 排查故障
+    bugfix: [
+        { text: '报错', weight: 3 },
+        { text: '500', weight: 3 },
+        { text: '崩溃', weight: 3 },
+        { text: '挂了', weight: 3 },
+        { text: '修复', weight: 2 },
+        { text: '修一下', weight: 3 },
+        { text: 'bug', weight: 2 },
+        { text: 'BUG', weight: 2 },
+        { text: '异常', weight: 2 },
+        { text: '失败', weight: 2 },
+        { text: '闪退', weight: 3 },
+        { text: '无法使用', weight: 2 },
+        { text: '不工作', weight: 2 },
+        { text: '错误', weight: 2 },
+        { text: '故障', weight: 3 },
+        { text: '排查', weight: 2 },
+        { text: '定位问题', weight: 2 },
+        { text: 'debug', weight: 2 },
+    ],
+    // 给已有系统加功能
+    feature: [
+        { text: '新增', weight: 3 },
+        { text: '增加', weight: 2 },
+        { text: '加一个', weight: 3 },
+        { text: '加个', weight: 3 },
+        { text: '扩展', weight: 2 },
+        { text: '添加', weight: 2 },
+        { text: '支持', weight: 1 },
+        { text: '功能', weight: 1 },
+        { text: '开发一个功能', weight: 3 },
+        { text: 'feat', weight: 2 },
+    ],
+};
+/** Score a text against one profile's keywords. */
+function score(text, profile) {
+    let score = 0;
+    const hits = [];
+    for (const kw of KEYWORDS[profile]) {
+        if (text.includes(kw.text)) {
+            score += kw.weight;
+            hits.push(kw.text);
+        }
+    }
+    return { score, hits };
+}
+/**
+ * Detect the most likely scene profile from natural language.
+ * - Returns a profile when its score clearly leads (≥ 2× runner-up, or score ≥ threshold).
+ * - Returns null when signals are weak/conflicting → caller should confirm with the user.
+ */
+export function detectScene(text) {
+    const lower = text.toLowerCase();
+    const scores = Object.keys(KEYWORDS).map((p) => ({
+        profile: p,
+        score: score(lower, p).score,
+    }));
+    scores.sort((a, b) => b.score - a.score);
+    const best = scores[0];
+    const runner = scores[1];
+    const total = scores.reduce((s, x) => s + x.score, 0);
+    const reasons = [];
+    // Strong signal: clear winner.
+    if (best.score >= 3 && (runner.score === 0 || best.score >= runner.score * 2)) {
+        const confidence = Math.min(1, best.score / (best.score + runner.score + 1));
+        reasons.push(`匹配「${best.profile}」关键词 ${best.score} 分（次优 ${runner.profile} ${runner.score} 分）`);
+        return { profile: best.profile, confidence, candidates: scores, reasons };
+    }
+    // Conflicting/weak → uncertain.
+    if (total === 0) {
+        reasons.push('未检测到明显场景信号，需向用户确认');
+    }
+    else {
+        reasons.push(`场景信号较弱或冲突（${scores.map((s) => `${s.profile}:${s.score}`).join(', ')}），需确认`);
+    }
+    return { profile: null, confidence: 0, candidates: scores, reasons };
+}
+/** The user-facing prompt when detection is uncertain. */
+export function confirmationPrompt(result, text) {
+    const lines = [
+        `未能明确判断你的需求属于哪个场景：`,
+        `「${text.slice(0, 60)}${text.length > 60 ? '…' : ''}」`,
+        '',
+        `检测到的候选：`,
+        ...result.candidates
+            .filter((c) => c.score > 0)
+            .map((c) => `- ${c.profile}: ${c.score} 分`),
+        '',
+        `请选择场景（或直接输入新的需求描述）：`,
+        `- 0to1   → 从零启动一个产品/项目`,
+        `- bugfix → 排查并修复一个问题`,
+        `- feature → 给已有系统新增功能`,
+    ];
+    return lines.join('\n');
+}