soloforge 1.2.2 → 1.2.4

package/dist/engine/job_manager.js

@@ -0,0 +1,225 @@
+/**
+ * 长任务 Job 管理 — checkpoint、heartbeat、resume/cancel、认知锚点。
+ * advisory: 不 hard block，提供恢复和监控能力。
+ *
+ * 职责:
+ * - 创建/更新/查询 job checkpoint
+ * - heartbeat 检测活跃状态
+ * - 从 checkpoint 恢复任务
+ * - 认知锚点（上下文摘要）
+ */
+import fs from "node:fs/promises";
+import fss from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+export class JobManager {
+    stateDir;
+    constructor(stateDir) {
+        this.stateDir = stateDir;
+        fss.mkdirSync(stateDir, { recursive: true });
+    }
+    /**
+     * 创建新 job，分配 job_id 并写入初始 checkpoint。
+     */
+    async createJob(taskId, phase, initialSummary) {
+        const jobId = `job-${crypto.randomUUID().slice(0, 8)}`;
+        const now = new Date().toISOString();
+        const checkpoint = {
+            job_id: jobId,
+            task_id: taskId,
+            phase,
+            heartbeat_at: now,
+            checkpoint_number: 1,
+            cognitive_anchor: {
+                phase,
+                summary: initialSummary,
+                key_decisions: [],
+                pending_actions: [],
+                created_at: now,
+            },
+            state_snapshot: {},
+        };
+        await this.writeCheckpoint(checkpoint);
+        return checkpoint;
+    }
+    /**
+     * 更新 checkpoint — 记录心跳和阶段进展。
+     */
+    async updateCheckpoint(jobId, taskId, phase, anchor, stateSnapshot) {
+        const existing = await this.loadLatestCheckpoint(jobId, taskId);
+        if (!existing)
+            return null;
+        const now = new Date().toISOString();
+        const checkpoint = {
+            job_id: jobId,
+            task_id: taskId,
+            phase,
+            heartbeat_at: now,
+            checkpoint_number: existing.checkpoint_number + 1,
+            cognitive_anchor: {
+                phase,
+                summary: anchor.summary ?? existing.cognitive_anchor.summary,
+                key_decisions: anchor.key_decisions ?? existing.cognitive_anchor.key_decisions,
+                pending_actions: anchor.pending_actions ?? existing.cognitive_anchor.pending_actions,
+                created_at: now,
+            },
+            state_snapshot: stateSnapshot ?? existing.state_snapshot,
+        };
+        await this.writeCheckpoint(checkpoint);
+        return checkpoint;
+    }
+    /**
+     * 心跳 — 只更新 heartbeat_at 时间戳。
+     */
+    async heartbeat(jobId, taskId) {
+        const existing = await this.loadLatestCheckpoint(jobId, taskId);
+        if (!existing)
+            return false;
+        existing.heartbeat_at = new Date().toISOString();
+        await this.writeCheckpoint(existing);
+        return true;
+    }
+    /**
+     * 查询 job 状态 — 包括是否活跃、距上次心跳时间。
+     */
+    async getJobStatus(jobId, taskId, maxAgeMs = 5 * 60 * 1000) {
+        const checkpoint = await this.loadLatestCheckpoint(jobId, taskId);
+        if (!checkpoint)
+            return null;
+        const lastHeartbeat = new Date(checkpoint.heartbeat_at).getTime();
+        const elapsed = Date.now() - lastHeartbeat;
+        return {
+            job_id: jobId,
+            task_id: taskId,
+            is_alive: elapsed < maxAgeMs,
+            last_heartbeat_ms_ago: elapsed,
+            current_phase: checkpoint.phase,
+            checkpoint_count: checkpoint.checkpoint_number,
+            latest_anchor: checkpoint.cognitive_anchor,
+        };
+    }
+    /**
+     * 从最新 checkpoint 恢复 — 返回 checkpoint 数据供调用方恢复状态。
+     */
+    async resumeFromCheckpoint(jobId, taskId) {
+        return this.loadLatestCheckpoint(jobId, taskId);
+    }
+    /**
+     * 取消 job — 删除所有 checkpoint 文件。
+     */
+    async cancelJob(jobId, taskId) {
+        const pattern = `${jobId}`;
+        const dir = path.join(this.stateDir, "jobs");
+        if (!fss.existsSync(dir))
+            return false;
+        const files = await fs.readdir(dir);
+        let removed = false;
+        for (const f of files) {
+            if (f.includes(pattern) && f.endsWith(".json")) {
+                await fs.unlink(path.join(dir, f));
+                removed = true;
+            }
+        }
+        return removed;
+    }
+    /**
+     * 列出所有活跃 job。
+     */
+    async listActiveJobs(maxAgeMs = 5 * 60 * 1000) {
+        const dir = path.join(this.stateDir, "jobs");
+        if (!fss.existsSync(dir))
+            return [];
+        const files = await fs.readdir(dir);
+        const checkpoints = [];
+        for (const f of files.filter((f) => f.endsWith(".json"))) {
+            try {
+                const data = await fs.readFile(path.join(dir, f), "utf-8");
+                checkpoints.push(JSON.parse(data));
+            }
+            catch {
+                // skip corrupt files
+            }
+        }
+        // Group by job_id, take latest per job
+        const latest = new Map();
+        for (const cp of checkpoints) {
+            const existing = latest.get(cp.job_id);
+            if (!existing || cp.checkpoint_number > existing.checkpoint_number) {
+                latest.set(cp.job_id, cp);
+            }
+        }
+        const statuses = [];
+        for (const cp of latest.values()) {
+            const elapsed = Date.now() - new Date(cp.heartbeat_at).getTime();
+            if (elapsed >= maxAgeMs)
+                continue;
+            statuses.push({
+                job_id: cp.job_id,
+                task_id: cp.task_id,
+                is_alive: true,
+                last_heartbeat_ms_ago: elapsed,
+                current_phase: cp.phase,
+                checkpoint_count: cp.checkpoint_number,
+                latest_anchor: cp.cognitive_anchor,
+            });
+        }
+        return statuses;
+    }
+    /**
+     * 仅凭 job_id 反查 task_id — 扫描 checkpoint 文件，返回最新一条的 task_id。
+     * 用于 sf_status 在不传 task_id 时自动推导。
+     */
+    async resolveTaskId(jobId) {
+        const dir = this.getJobsDir();
+        const files = await fs.readdir(dir);
+        const matching = files
+            .filter((f) => f.startsWith(jobId) && f.endsWith(".json"))
+            .sort()
+            .reverse();
+        for (const f of matching) {
+            try {
+                const data = JSON.parse(await fs.readFile(path.join(dir, f), "utf-8"));
+                return data.task_id;
+            }
+            catch {
+                // skip corrupt
+            }
+        }
+        return null;
+    }
+    // ── Internal ──
+    getJobsDir() {
+        const dir = path.join(this.stateDir, "jobs");
+        fss.mkdirSync(dir, { recursive: true });
+        return dir;
+    }
+    async writeCheckpoint(checkpoint) {
+        const dir = this.getJobsDir();
+        const filename = `${checkpoint.job_id}-${checkpoint.checkpoint_number.toString().padStart(4, "0")}.json`;
+        const filePath = path.join(dir, filename);
+        const tmpPath = `${filePath}.tmp`;
+        await fs.writeFile(tmpPath, JSON.stringify(checkpoint, null, 2));
+        await fs.rename(tmpPath, filePath);
+    }
+    async loadLatestCheckpoint(jobId, taskId) {
+        const dir = this.getJobsDir();
+        const files = await fs.readdir(dir);
+        const matching = files
+            .filter((f) => f.startsWith(jobId) && f.endsWith(".json"))
+            .sort()
+            .reverse();
+        for (const f of matching) {
+            try {
+                const data = await fs.readFile(path.join(dir, f), "utf-8");
+                const cp = JSON.parse(data);
+                if (cp.task_id === taskId)
+                    return cp;
+            }
+            catch {
+                // skip corrupt
+            }
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=job_manager.js.map

package/dist/engine/job_manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job_manager.js","sourceRoot":"","sources":["../../src/engine/job_manager.ts"],"names":[],"mappings":"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"}

package/dist/engine/knowledge_sovereignty.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Knowledge Sovereignty — 知识主权: drafts/quarantine/core 三级生命周期。
+ * R10 advisory: 不 hard block，只产出 advisory 报告。
+ *
+ * 职责:
+ * - quarantineGate: 检查知识条目是否在 quarantine 期
+ * - promoteToQuarantine: 从 drafts 晋升到 quarantine（自动）
+ * - promoteToCore: 从 quarantine 晋级到 core（需人工确认）
+ * - 查询 quarantine 状态
+ */
+export declare const DEFAULT_QUARANTINE_DAYS = 7;
+export type KnowledgeTier = "draft" | "quarantine" | "core";
+export interface KnowledgeSovereigntyEntry {
+    name: string;
+    file_path: string;
+    tier: KnowledgeTier;
+    quarantined_at: string | null;
+    quarantine_expires_at: string | null;
+    can_reference: boolean;
+    advisory: string;
+}
+export interface SovereigntyReport {
+    total_entries: number;
+    by_tier: Record<KnowledgeTier, number>;
+    quarantine_entries: KnowledgeSovereigntyEntry[];
+    can_promote_to_core: Array<{
+        name: string;
+        file_path: string;
+    }>;
+    summary: string;
+}
+/**
+ * 检查条目是否在 quarantine 期 — advisory only, 不 hard block。
+ * quarantine 期间条目可被引用，但标记为 advisory。
+ */
+export declare function quarantineGate(entry: KnowledgeSovereigntyEntry): {
+    allowed: boolean;
+    advisory: string;
+};
+/**
+ * 将 drafts 中的条目晋升到 quarantine — 自动，不需要人工确认。
+ */
+export declare function promoteToQuarantine(draftPath: string, knowledgeDir: string, quarantineDays?: number): Promise<KnowledgeSovereigntyEntry | null>;
+/**
+ * 将 quarantine 中的条目晋级到 core — 需要人工确认。
+ * confirm=false 时只返回预览，不执行晋级。
+ */
+export declare function promoteToCore(quarantinePath: string, knowledgeDir: string, confirm: {
+    confirmed: boolean;
+    confirmed_by: string;
+    reason: string;
+}): Promise<{
+    success: boolean;
+    target_path: string;
+    advisory: string;
+}>;
+/**
+ * 扫描 knowledge 目录，生成主权报告。
+ */
+export declare function generateSovereigntyReport(knowledgeDir: string): Promise<SovereigntyReport>;
+//# sourceMappingURL=knowledge_sovereignty.d.ts.map

package/dist/engine/knowledge_sovereignty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge_sovereignty.d.ts","sourceRoot":"","sources":["../../src/engine/knowledge_sovereignty.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,YAAY,GAAG,MAAM,CAAC;AAE5D,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,aAAa,CAAC;IACpB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IACvC,kBAAkB,EAAE,yBAAyB,EAAE,CAAC;IAChD,mBAAmB,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,yBAAyB,GAC/B;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAgCxC;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,cAAc,SAA0B,GACvC,OAAO,CAAC,yBAAyB,GAAG,IAAI,CAAC,CAmC3C;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE;IACP,SAAS,EAAE,OAAO,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB,GACA,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA0DtE;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAyD5B"}

package/dist/engine/knowledge_sovereignty.js

@@ -0,0 +1,190 @@
+/**
+ * Knowledge Sovereignty — 知识主权: drafts/quarantine/core 三级生命周期。
+ * R10 advisory: 不 hard block，只产出 advisory 报告。
+ *
+ * 职责:
+ * - quarantineGate: 检查知识条目是否在 quarantine 期
+ * - promoteToQuarantine: 从 drafts 晋升到 quarantine（自动）
+ * - promoteToCore: 从 quarantine 晋级到 core（需人工确认）
+ * - 查询 quarantine 状态
+ */
+import fs from "node:fs/promises";
+import fss from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+export const DEFAULT_QUARANTINE_DAYS = 7;
+/**
+ * 检查条目是否在 quarantine 期 — advisory only, 不 hard block。
+ * quarantine 期间条目可被引用，但标记为 advisory。
+ */
+export function quarantineGate(entry) {
+    if (entry.tier === "core") {
+        return { allowed: true, advisory: "core tier, unrestricted" };
+    }
+    if (entry.tier === "draft") {
+        return {
+            allowed: true,
+            advisory: "advisory: draft tier, not yet quarantined — reference with caution",
+        };
+    }
+    if (entry.tier === "quarantine") {
+        if (!entry.quarantine_expires_at) {
+            return { allowed: true, advisory: "advisory: quarantine, no expiry set" };
+        }
+        const now = Date.now();
+        const expires = new Date(entry.quarantine_expires_at).getTime();
+        if (now < expires) {
+            const daysLeft = Math.ceil((expires - now) / (24 * 60 * 60 * 1000));
+            return {
+                allowed: true,
+                advisory: `advisory: quarantine tier, ${daysLeft} day(s) remaining — reference with caution`,
+            };
+        }
+        return {
+            allowed: true,
+            advisory: "quarantine expired, eligible for core promotion",
+        };
+    }
+    return { allowed: true, advisory: "unknown tier" };
+}
+/**
+ * 将 drafts 中的条目晋升到 quarantine — 自动，不需要人工确认。
+ */
+export async function promoteToQuarantine(draftPath, knowledgeDir, quarantineDays = DEFAULT_QUARANTINE_DAYS) {
+    if (!fss.existsSync(draftPath))
+        return null;
+    const raw = await fs.readFile(draftPath, "utf-8");
+    const { data: frontmatter, content: body } = matter(raw);
+    const quarantineDir = path.join(knowledgeDir, "quarantine");
+    fss.mkdirSync(quarantineDir, { recursive: true });
+    const now = new Date();
+    const expires = new Date(now.getTime() + quarantineDays * 24 * 60 * 60 * 1000);
+    frontmatter.tier = "quarantine";
+    frontmatter.quarantined_at = now.toISOString();
+    frontmatter.quarantine_expires_at = expires.toISOString();
+    const filename = path.basename(draftPath);
+    const targetPath = path.join(quarantineDir, filename);
+    const updated = matter.stringify(body, frontmatter);
+    const tmpPath = `${targetPath}.tmp`;
+    await fs.writeFile(tmpPath, updated, "utf-8");
+    await fs.rename(tmpPath, targetPath);
+    await fs.unlink(draftPath).catch(() => { });
+    return {
+        name: frontmatter.name ?? filename,
+        file_path: targetPath,
+        tier: "quarantine",
+        quarantined_at: now.toISOString(),
+        quarantine_expires_at: expires.toISOString(),
+        can_reference: true,
+        advisory: "newly quarantined, reference with caution",
+    };
+}
+/**
+ * 将 quarantine 中的条目晋级到 core — 需要人工确认。
+ * confirm=false 时只返回预览，不执行晋级。
+ */
+export async function promoteToCore(quarantinePath, knowledgeDir, confirm) {
+    if (!fss.existsSync(quarantinePath)) {
+        return {
+            success: false,
+            target_path: "",
+            advisory: `file not found: ${quarantinePath}`,
+        };
+    }
+    if (!confirm.confirmed || !confirm.confirmed_by) {
+        return {
+            success: false,
+            target_path: quarantinePath,
+            advisory: "core promotion requires human confirmation (confirmed=true, confirmed_by non-empty)",
+        };
+    }
+    const raw = await fs.readFile(quarantinePath, "utf-8");
+    const { data: frontmatter, content: body } = matter(raw);
+    // Check quarantine has expired
+    if (frontmatter.quarantine_expires_at) {
+        const now = Date.now();
+        const expires = new Date(frontmatter.quarantine_expires_at).getTime();
+        if (now < expires) {
+            return {
+                success: false,
+                target_path: quarantinePath,
+                advisory: "quarantine period not yet expired, cannot promote to core",
+            };
+        }
+    }
+    const coreDir = path.join(knowledgeDir, "patterns", "core");
+    fss.mkdirSync(coreDir, { recursive: true });
+    frontmatter.tier = "core";
+    frontmatter.promoted_at = new Date().toISOString();
+    frontmatter.promoted_by = confirm.confirmed_by;
+    frontmatter.promotion_reason = confirm.reason;
+    delete frontmatter.quarantine_expires_at;
+    delete frontmatter.quarantined_at;
+    const filename = path.basename(quarantinePath);
+    const targetPath = path.join(coreDir, filename);
+    const updated = matter.stringify(body, frontmatter);
+    const tmpPath = `${targetPath}.tmp`;
+    await fs.writeFile(tmpPath, updated, "utf-8");
+    await fs.rename(tmpPath, targetPath);
+    await fs.unlink(quarantinePath).catch(() => { });
+    return {
+        success: true,
+        target_path: targetPath,
+        advisory: `promoted to core by ${confirm.confirmed_by}: ${confirm.reason}`,
+    };
+}
+/**
+ * 扫描 knowledge 目录，生成主权报告。
+ */
+export async function generateSovereigntyReport(knowledgeDir) {
+    const entries = [];
+    const tiers = ["draft", "quarantine", "core"];
+    const tierDirs = {
+        draft: path.join(knowledgeDir, "drafts"),
+        quarantine: path.join(knowledgeDir, "quarantine"),
+        core: path.join(knowledgeDir, "patterns", "core"),
+    };
+    const tierCounts = { draft: 0, quarantine: 0, core: 0 };
+    const canPromoteToCore = [];
+    for (const tier of tiers) {
+        const dir = tierDirs[tier];
+        if (!fss.existsSync(dir))
+            continue;
+        const files = await fs.readdir(dir);
+        for (const f of files.filter((f) => f.endsWith(".md"))) {
+            const filePath = path.join(dir, f);
+            try {
+                const raw = await fs.readFile(filePath, "utf-8");
+                const { data } = matter(raw);
+                const entry = {
+                    name: data.name ?? f,
+                    file_path: filePath,
+                    tier,
+                    quarantined_at: data.quarantined_at ?? null,
+                    quarantine_expires_at: data.quarantine_expires_at ?? null,
+                    can_reference: true,
+                    advisory: "",
+                };
+                tierCounts[tier]++;
+                if (tier === "quarantine" && data.quarantine_expires_at) {
+                    const expires = new Date(data.quarantine_expires_at).getTime();
+                    if (Date.now() >= expires) {
+                        canPromoteToCore.push({ name: entry.name, file_path: filePath });
+                    }
+                }
+                entries.push(entry);
+            }
+            catch {
+                // skip unparseable files
+            }
+        }
+    }
+    return {
+        total_entries: entries.length,
+        by_tier: tierCounts,
+        quarantine_entries: entries.filter((e) => e.tier === "quarantine"),
+        can_promote_to_core: canPromoteToCore,
+        summary: `${entries.length} entries (${tierCounts.draft} drafts, ${tierCounts.quarantine} quarantine, ${tierCounts.core} core)`,
+    };
+}
+//# sourceMappingURL=knowledge_sovereignty.js.map

package/dist/engine/knowledge_sovereignty.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge_sovereignty.js","sourceRoot":"","sources":["../../src/engine/knowledge_sovereignty.ts"],"names":[],"mappings":"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"}

package/dist/engine/mutation_audit.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 变异审计真实化 — 需求绑定变异点 + mutant killed 证据。
+ * R9 advisory: 不 hard block，只产出 advisory 报告。
+ *
+ * 职责:
+ * - computeMutationAudit: 从变更文件 + 需求点 + 源码计算变异证据
+ * - 产出 MutationAuditEvidence: mutant_killed_count / mutant_total_count / per-requirement 绑定
+ */
+import type { RequirementPoint } from "../types.js";
+export interface MutationPoint {
+    file_path: string;
+    line_number: number;
+    original_line: string;
+    requirement_point_id?: string;
+}
+export interface MutationAuditEntry {
+    requirement_point_id: string;
+    mutation_points: number;
+    mutants_killed: number;
+    mutants_total: number;
+    advisory: string;
+}
+export interface MutationAuditEvidence {
+    mutant_killed_count: number;
+    mutant_total_count: number;
+    kill_ratio: number;
+    per_requirement: MutationAuditEntry[];
+    uncovered_requirements: string[];
+    summary: string;
+}
+/**
+ * 从源码中提取变异候选点，并尝试关联到需求点。
+ * 关联策略: 文件路径与需求点描述关键词匹配。
+ */
+export declare function extractMutationPoints(sourceFiles: Array<{
+    file_path: string;
+    content: string;
+}>, requirementPoints: RequirementPoint[]): MutationPoint[];
+/**
+ * 计算变异审计证据 — 每个需求点的变异覆盖状态。
+ */
+export declare function computeMutationAudit(mutationPoints: MutationPoint[], requirementPoints: RequirementPoint[], killedCount: number, totalCount: number): MutationAuditEvidence;
+//# sourceMappingURL=mutation_audit.d.ts.map

package/dist/engine/mutation_audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation_audit.d.ts","sourceRoot":"","sources":["../../src/engine/mutation_audit.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,kBAAkB,EAAE,CAAC;IACtC,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,OAAO,EAAE,MAAM,CAAC;CACjB;AA6BD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,KAAK,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,EAC1D,iBAAiB,EAAE,gBAAgB,EAAE,GACpC,aAAa,EAAE,CAuBjB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,cAAc,EAAE,aAAa,EAAE,EAC/B,iBAAiB,EAAE,gBAAgB,EAAE,EACrC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,qBAAqB,CAmEvB"}

package/dist/engine/mutation_audit.js

@@ -0,0 +1,118 @@
+/**
+ * 变异审计真实化 — 需求绑定变异点 + mutant killed 证据。
+ * R9 advisory: 不 hard block，只产出 advisory 报告。
+ *
+ * 职责:
+ * - computeMutationAudit: 从变更文件 + 需求点 + 源码计算变异证据
+ * - 产出 MutationAuditEvidence: mutant_killed_count / mutant_total_count / per-requirement 绑定
+ */
+const CANDIDATE_PATTERNS = [
+    /\b(if|else|switch|case)\b/.source,
+    /(===|!==|==|!=|>=|<=|>|<)/.source,
+    /(&&|\|\|)/.source,
+    /\breturn\b/.source,
+];
+const CANDIDATE_RE = new RegExp(CANDIDATE_PATTERNS.join("|"));
+const EXCLUDE_PATTERNS = [
+    /^\s*\/\//,
+    /^\s*\*/,
+    /^\s*\/\*/,
+    /^\s*import /,
+    /^\s*export /,
+    /^\s*console\./,
+    /^\s*(interface|type|enum|declare) /,
+    /^\s*debugger/,
+];
+function isCandidateLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return false;
+    if (EXCLUDE_PATTERNS.some((p) => p.test(trimmed)))
+        return false;
+    return CANDIDATE_RE.test(trimmed);
+}
+/**
+ * 从源码中提取变异候选点，并尝试关联到需求点。
+ * 关联策略: 文件路径与需求点描述关键词匹配。
+ */
+export function extractMutationPoints(sourceFiles, requirementPoints) {
+    const points = [];
+    for (const file of sourceFiles) {
+        const lines = file.content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            if (!isCandidateLine(lines[i]))
+                continue;
+            const matchedRp = requirementPoints.find((rp) => {
+                const keywords = rp.description.toLowerCase().split(/\s+/);
+                return keywords.some((kw) => kw.length > 2 && file.file_path.toLowerCase().includes(kw));
+            });
+            points.push({
+                file_path: file.file_path,
+                line_number: i + 1,
+                original_line: lines[i].trim(),
+                requirement_point_id: matchedRp?.id,
+            });
+        }
+    }
+    return points;
+}
+/**
+ * 计算变异审计证据 — 每个需求点的变异覆盖状态。
+ */
+export function computeMutationAudit(mutationPoints, requirementPoints, killedCount, totalCount) {
+    const perRequirement = [];
+    const coveredRpIds = new Set();
+    for (const rp of requirementPoints) {
+        const rpPoints = mutationPoints.filter((mp) => mp.requirement_point_id === rp.id);
+        const rpTotal = rpPoints.length;
+        if (rpTotal > 0) {
+            coveredRpIds.add(rp.id);
+            // Distribute killed proportionally
+            const rpKilled = Math.min(Math.round((rpTotal / Math.max(totalCount, 1)) * killedCount), rpTotal);
+            perRequirement.push({
+                requirement_point_id: rp.id,
+                mutation_points: rpTotal,
+                mutants_killed: rpKilled,
+                mutants_total: rpTotal,
+                advisory: rpKilled === rpTotal
+                    ? "all mutants killed"
+                    : `advisory: ${rpTotal - rpKilled}/${rpTotal} mutants not killed for ${rp.id}`,
+            });
+        }
+        else {
+            perRequirement.push({
+                requirement_point_id: rp.id,
+                mutation_points: 0,
+                mutants_killed: 0,
+                mutants_total: 0,
+                advisory: `advisory: no mutation points found for requirement ${rp.id}`,
+            });
+        }
+    }
+    // Also include mutation points not bound to any requirement
+    const unboundPoints = mutationPoints.filter((mp) => !mp.requirement_point_id);
+    if (unboundPoints.length > 0) {
+        perRequirement.push({
+            requirement_point_id: "_unbound",
+            mutation_points: unboundPoints.length,
+            mutants_killed: 0,
+            mutants_total: unboundPoints.length,
+            advisory: `advisory: ${unboundPoints.length} mutation points not bound to any requirement`,
+        });
+    }
+    const uncoveredRequirements = requirementPoints
+        .filter((rp) => !coveredRpIds.has(rp.id))
+        .map((rp) => rp.id);
+    const killRatio = totalCount > 0 ? killedCount / totalCount : 1;
+    return {
+        mutant_killed_count: killedCount,
+        mutant_total_count: totalCount,
+        kill_ratio: killRatio,
+        per_requirement: perRequirement,
+        uncovered_requirements: uncoveredRequirements,
+        summary: uncoveredRequirements.length > 0
+            ? `advisory: ${uncoveredRequirements.length} requirement(s) have no killed mutants: ${uncoveredRequirements.join(", ")}`
+            : `mutation audit: ${killedCount}/${totalCount} killed (ratio: ${(killRatio * 100).toFixed(0)}%)`,
+    };
+}
+//# sourceMappingURL=mutation_audit.js.map