soloforge 1.2.8 → 1.2.10

package/dist/engine/main_path_integration_contract.js

@@ -0,0 +1,1581 @@
+/**
+ * Main Path Integration Contract
+ *
+ * 新增能力主链路接入防孤岛机制。
+ * 任何新增生产代码不能只证明"文件存在、单测通过"，必须证明它已经进入
+ * 真实主链路，并能被用户入口触发、被生产代码调用、留下可观测证据、通过集成验证。
+ *
+ * 核心完成定义:
+ * Done = implemented + wired + reachable + observable + verified
+ */
+// ── 常量定义 ──
+/** 不被承认为"接入"的引用类型 */
+const NON_INTEGRATION_REFERENCES = [
+    "test_import",
+    "index_export",
+    "registry_declaration",
+    "type_reference",
+    "barrel_export",
+    "readme",
+    "design_doc",
+    "demo",
+    "example",
+];
+export { NON_INTEGRATION_REFERENCES };
+/** 允许豁免的文件模式 */
+const EXEMPT_PATTERNS = [
+    { pattern: /\.d\.ts$/, reason: "类型声明文件" },
+    { pattern: /\/types\//, reason: "类型目录" },
+    { pattern: /\.test\./, reason: "测试文件不应在 src" },
+    { pattern: /\.spec\./, reason: "测试文件不应在 src" },
+    { pattern: /\/fixtures?\//, reason: "测试 fixture" },
+];
+export { EXEMPT_PATTERNS };
+/** SoloForge 机制层特殊规则: 能力类型 → 必须接入的目标 */
+const SOLOFORGE_WIRING_RULES = {
+    contract: "Unified Contract Registry 或明确为 advisory/experimental",
+    guard: "Guard Evaluation",
+    verifier: "Guard Evaluation",
+    workflow: "Workflow Contract Registry 和真实编排",
+    knowledge_rule: "Knowledge Injection Boundary 或明确 manual_reference",
+    cli_command: "bin/soloforge",
+    adapter_behavior: "对应 adapter 模板和 adapter 测试",
+    diagnostic_code: "真实路径产出",
+    governance_report: "真实命令或真实 workflow 输出",
+    business_service: "controller/job/page/consumer/public API 入口",
+    other: "生产调用路径",
+};
+export { SOLOFORGE_WIRING_RULES };
+/** hard_fail 的状态 */
+const HARD_FAIL_STATUSES = [
+    "implemented_not_integrated",
+    "dead_code_candidate",
+];
+/** 允许的状态 */
+const ALLOW_STATUSES = [
+    "integrated",
+];
+/** warning 的状态 */
+const WARNING_STATUSES = [
+    "experimental_isolated",
+    "planned_integration",
+];
+// ── Query functions ──
+/**
+ * 判断文件是否为豁免文件。
+ * @param modulePath - 模块路径
+ * @returns 豁免结果及原因
+ */
+export function isExemptFile(modulePath) {
+    for (const { pattern, reason } of EXEMPT_PATTERNS) {
+        if (pattern.test(modulePath)) {
+            return { exempt: true, reason };
+        }
+    }
+    return { exempt: false };
+}
+/**
+ * 判断引用类型是否为非接入引用。
+ * @param refType - 引用类型
+ * @returns 是否为非接入引用
+ */
+export function isNonIntegrationReference(refType) {
+    return NON_INTEGRATION_REFERENCES.includes(refType);
+}
+/**
+ * 获取指定能力类型的接入要求。
+ * @param kind - 能力类型
+ * @returns 接入要求描述
+ */
+export function getWiringRequirement(kind) {
+    return SOLOFORGE_WIRING_RULES[kind];
+}
+/** 判断模块是否只被测试导入 */
+export function isTestOnlyModule(modulePath, importers) {
+    const prodImporters = importers.filter((i) => !i.path.startsWith("tests/") &&
+        !i.path.includes(".test.") &&
+        !i.path.includes(".spec.") &&
+        !isNonIntegrationReference(i.ref_type));
+    return prodImporters.length === 0 && importers.length > 0;
+}
+/** 判断模块是否只有 registry/index export 引用 */
+export function isRegistryOnlyModule(modulePath, importers) {
+    const realImporters = importers.filter((i) => !isNonIntegrationReference(i.ref_type));
+    return realImporters.length === 0 && importers.length > 0;
+}
+/** 判断是否有入口链路 */
+/**
+ * 判断契约是否有入口链路。
+ * @param contract - 主链路接入契约
+ * @returns 是否有入口链路
+ */
+export function hasEntryTrace(contract) {
+    return contract.entry_traces.length > 0 &&
+        contract.entry_traces.some((t) => t.call_chain.length > 0);
+}
+/** 判断是否有可观测证据 */
+/**
+ * 判断契约是否有可观测证据。
+ * @param contract - 主链路接入契约
+ * @returns 是否有可观测证据
+ */
+export function hasObservability(contract) {
+    return contract.observability_refs.length > 0;
+}
+/** 判断是否有集成测试 */
+/**
+ * 判断契约是否有集成测试。
+ * @param contract - 主链路接入契约
+ * @returns 是否有集成测试
+ */
+export function hasIntegrationTest(contract) {
+    return contract.integration_tests.length > 0;
+}
+/** 判断是否有生产调用 */
+/**
+ * 判断契约是否有生产调用。
+ * @param contract - 主链路接入契约
+ * @returns 是否有生产调用
+ */
+export function hasProductionImport(contract) {
+    return contract.production_imports.length > 0;
+}
+// ── Orphan Implementation Gate ──
+/**
+ * 孤岛模块门禁检查。
+ * 检查模块是否存在只被测试导入、无入口链路等问题。
+ * @param contract - 主链路接入契约
+ * @param capabilityKind - 能力类型（可选）
+ * @returns 集成发现列表
+ */
+export function orphanGate(contract, capabilityKind) {
+    const findings = [];
+    const path = contract.module_path;
+    console.error(`[soloForge] 主链路接入: 开始孤岛门禁检查 — ${path}`);
+    // 豁免文件始终允许
+    const exempt = isExemptFile(path);
+    if (exempt.exempt) {
+        console.error("[soloForge] 主链路接入: 孤岛门禁 — 豁免文件 " + path + " (" + exempt.reason + ")");
+        findings.push({
+            severity: "allow",
+            module_path: path,
+            reason: `豁免文件: ${exempt.reason}`,
+            recommended_action: "allow",
+        });
+        return findings;
+    }
+    // 规则 1: 只被测试导入 → hard_fail
+    if (contract.production_imports.length === 0 && contract.integration_tests.length > 0) {
+        console.error("[soloForge] 主链路接入: 孤岛门禁 — 规则1命中: " + path + " 只被测试导入");
+        findings.push({
+            severity: "hard_fail",
+            module_path: path,
+            reason: `模块 ${path} 只被测试导入，无生产代码调用`,
+            recommended_action: "wire_to_main_path",
+        });
+    }
+    // 规则 1b: 被导入但从未被调用（仅导入）→ hard_fail
+    if (contract.production_imports.length === 0 && contract.status === "implemented_not_integrated") {
+        console.error("[soloForge] 主链路接入: 孤岛门禁 — 规则1b命中: " + path + " 被导入但从未被调用");
+        findings.push({
+            severity: "hard_fail",
+            module_path: path,
+            reason: `模块 ${path} 被导入但从未被调用，无真实调用证据`,
+            recommended_action: "wire_to_main_path",
+        });
+    }
+    // 规则 2: enforced 能力无入口链路 → hard_fail
+    if (contract.status === "implemented_not_integrated" && !hasEntryTrace(contract)) {
+        console.error("[soloForge] 主链路接入: 孤岛门禁 — 规则2命中: " + path + " 无入口链路");
+        findings.push({
+            severity: "hard_fail",
+            module_path: path,
+            reason: `新增 enforced 能力 ${path} 无入口链路`,
+            recommended_action: "add_entry_trace",
+        });
+    }
+    // 规则 3: guard/verifier/contract 只被测试调用 → hard_fail
+    if (capabilityKind &&
+        (capabilityKind === "guard" || capabilityKind === "verifier" || capabilityKind === "contract") &&
+        !hasProductionImport(contract)) {
+        console.error("[soloForge] 主链路接入: 孤岛门禁 — 规则3命中: " + capabilityKind + " " + path + " 只被测试调用");
+        findings.push({
+            severity: "hard_fail",
+            module_path: path,
+            reason: `新增 ${capabilityKind} ${path} 只被测试调用`,
+            recommended_action: "wire_to_main_path",
+        });
+    }
+    // 规则 4: 影响交付结论但无可观测证据 → hard_fail
+    if (contract.status === "integrated" &&
+        !hasObservability(contract) &&
+        (capabilityKind === "contract" || capabilityKind === "guard" || capabilityKind === "verifier")) {
+        findings.push({
+            severity: "hard_fail",
+            module_path: path,
+            reason: `新增代码影响交付结论但无可观测证据: ${path}`,
+            recommended_action: "add_entry_trace",
+        });
+    }
+    // 规则 5: 无集成测试 → hard_fail (experimental_isolated 降级 warning)
+    if (!hasIntegrationTest(contract) && contract.status !== "experimental_isolated") {
+        console.error("[soloForge] 主链路接入: 孤岛门禁 — 规则5命中: " + path + " 缺少集成测试");
+        findings.push({
+            severity: "hard_fail",
+            module_path: path,
+            reason: `模块 ${path} 缺少集成/契约测试`,
+            recommended_action: "add_integration_test",
+        });
+    }
+    // 规则 6: experimental_isolated 无入口 → warning (not hard_fail)
+    if (contract.status === "experimental_isolated" && !hasEntryTrace(contract)) {
+        findings.push({
+            severity: "warning",
+            module_path: path,
+            reason: `experimental 代码 ${path} 无入口但已明确隔离`,
+            recommended_action: "mark_experimental",
+        });
+    }
+    // 规则 7: dead_code_candidate
+    if (contract.status === "dead_code_candidate") {
+        findings.push({
+            severity: "warning",
+            module_path: path,
+            reason: `模块 ${path} 为 dead_code_candidate`,
+            recommended_action: "retire_dead_code",
+        });
+    }
+    console.error("[soloForge] 主链路接入: 孤岛门禁完成 — " + path + " 发现 " + findings.length + " 个问题");
+    return findings;
+}
+// ── Integration Audit ──
+/**
+ * 集成审计。
+ * 审计所有契约的接入状态，生成审计报告。
+ * @param contracts - 主链路接入契约列表
+ * @param capabilityKinds - 模块路径到能力类型的映射（可选）
+ * @returns 集成审计报告
+ */
+export function auditIntegration(contracts, capabilityKinds) {
+    console.error(`[soloForge] 主链路接入: 开始集成审计 — 共 ${contracts.length} 个契约`);
+    const report = {
+        orphan_modules: [],
+        registry_only_modules: [],
+        test_only_modules: [],
+        unreachable_capabilities: [],
+        missing_observability: [],
+        required_entry_traces: [],
+        findings: [],
+    };
+    for (const c of contracts) {
+        const kind = capabilityKinds?.get(c.module_path);
+        const gateFindings = orphanGate(c, kind);
+        report.findings.push(...gateFindings);
+        // 孤岛模块: 仅测试导入
+        if (c.production_imports.length === 0 && c.integration_tests.length > 0) {
+            report.orphan_modules.push(c.module_path);
+        }
+        // 仅注册表: 只有注册表/index 引用
+        if (c.production_imports.length === 0 && c.entry_traces.length === 0) {
+            report.registry_only_modules.push(c.module_path);
+        }
+        // 仅测试模块
+        if (!hasProductionImport(c) && c.integration_tests.length > 0) {
+            report.test_only_modules.push(c.module_path);
+        }
+        // 不可达能力: 状态非 integrated 且无入口链路
+        if (!hasEntryTrace(c) && c.status !== "experimental_isolated") {
+            report.unreachable_capabilities.push(c.module_path);
+        }
+        // 缺少可观测性
+        if (!hasObservability(c) && c.status === "integrated") {
+            report.missing_observability.push(c.module_path);
+        }
+        // 非接入模块需要的入口链路
+        if (!hasEntryTrace(c) && c.status !== "integrated" && c.status !== "experimental_isolated") {
+            report.required_entry_traces.push({
+                entry_type: "cli",
+                entry_id: `required-for-${c.module_path}`,
+                call_chain: [],
+                trigger_example: `需要为 ${c.module_path} 建立入口链路`,
+            });
+        }
+    }
+    console.error("[soloForge] 主链路接入: 集成审计完成 — 孤岛 " + report.orphan_modules.length + ", 注册表 " + report.registry_only_modules.length + ", 仅测试 " + report.test_only_modules.length + ", 不可达 " + report.unreachable_capabilities.length);
+    return report;
+}
+// ── Factory ──
+/**
+ * 创建主链路接入契约。
+ * @param params.module_path - 模块路径
+ * @param params.owner - 负责人
+ * @returns 主链路接入契约
+ */
+export function createMainPathIntegrationContract(params) {
+    return {
+        module_path: params.module_path,
+        capability_id: params.capability_id,
+        contract_id: params.contract_id,
+        issue_id: params.issue_id,
+        status: params.status ?? "implemented_not_integrated",
+        production_imports: params.production_imports ?? [],
+        entry_traces: params.entry_traces ?? [],
+        observability_refs: params.observability_refs ?? [],
+        integration_tests: params.integration_tests ?? [],
+        allowed_isolation_reason: params.allowed_isolation_reason,
+        owner: params.owner,
+    };
+}
+/**
+ * 创建入口链路追踪记录。
+ * @param params - 入口追踪参数
+ * @returns 入口链路追踪
+ */
+export function createEntryPointTrace(params) {
+    return {
+        entry_type: params.entry_type,
+        entry_id: params.entry_id,
+        call_chain: params.call_chain,
+        trigger_example: params.trigger_example,
+        evidence_ref: params.evidence_ref,
+    };
+}
+/**
+ * 验证交付答案。
+ * @param answers - 交付答案
+ * @returns 集成发现列表
+ */
+export function validateDeliveryAnswers(answers) {
+    const findings = [];
+    for (const mod of answers.new_modules) {
+        if (answers.called_by.length === 0) {
+            findings.push({
+                severity: "hard_fail",
+                module_path: mod,
+                reason: `新增模块 ${mod} 没有被任何生产代码调用`,
+                recommended_action: "wire_to_main_path",
+            });
+        }
+        if (!answers.user_trigger) {
+            findings.push({
+                severity: "hard_fail",
+                module_path: mod,
+                reason: `新增模块 ${mod} 没有用户触发路径`,
+                recommended_action: "add_entry_trace",
+            });
+        }
+    }
+    for (const f of answers.test_only_files) {
+        findings.push({
+            severity: "hard_fail",
+            module_path: f,
+            reason: `文件 ${f} 只被测试导入`,
+            recommended_action: "wire_to_main_path",
+        });
+    }
+    for (const r of answers.registered_not_executed) {
+        findings.push({
+            severity: "hard_fail",
+            module_path: r,
+            reason: `能力 ${r} 只注册未执行`,
+            recommended_action: "wire_to_main_path",
+        });
+    }
+    for (const s of answers.non_integrated_statuses) {
+        if (s === "implemented_not_integrated" || s === "dead_code_candidate") {
+            findings.push({
+                severity: "warning",
+                module_path: "*",
+                reason: `存在 ${s} 状态的模块`,
+                recommended_action: "wire_to_main_path",
+            });
+        }
+    }
+    return findings;
+}
+// ── Chinese Labels ──
+/**
+ * 获取接入状态的中文标签。
+ * @param status - 接入状态
+ * @returns 中文标签
+ */
+export function statusLabel(status) {
+    const labels = {
+        integrated: "已接入",
+        implemented_not_integrated: "已实现未接入",
+        experimental_isolated: "实验性隔离",
+        planned_integration: "计划接入",
+        dead_code_candidate: "废弃候选",
+    };
+    return labels[status];
+}
+/**
+ * 获取入口类型的中文标签。
+ * @param type - 入口类型
+ * @returns 中文标签
+ */
+export function entryTypeLabel(type) {
+    const labels = {
+        cli: "CLI 命令",
+        mcp_tool: "MCP 工具",
+        workflow: "工作流",
+        adapter_prompt: "Adapter 提示",
+        frontend_route: "前端路由",
+        backend_route: "后端路由",
+        job: "后台任务",
+        consumer: "消费者",
+        cron: "定时任务",
+        webhook: "Webhook",
+        public_api: "公开 API",
+        command: "命令",
+    };
+    return labels[type];
+}
+/**
+ * 构建集成反馈信息。
+ * @param contract - 主链路接入契约
+ * @returns 格式化的反馈文本
+ */
+export function buildIntegrationFeedback(contract) {
+    const lines = [];
+    lines.push(`模块: ${contract.module_path}`);
+    lines.push(`状态: ${statusLabel(contract.status)}`);
+    lines.push(`负责人: ${contract.owner}`);
+    if (contract.entry_traces.length > 0) {
+        lines.push(`入口链路:`);
+        for (const t of contract.entry_traces) {
+            lines.push(`  - ${entryTypeLabel(t.entry_type)}: ${t.entry_id}`);
+            lines.push(`    调用链: ${t.call_chain.join(" -> ")}`);
+            lines.push(`    触发示例: ${t.trigger_example}`);
+        }
+    }
+    else {
+        lines.push(`入口链路: 无 (模块未接入主链路)`);
+    }
+    lines.push(`生产调用: ${contract.production_imports.length > 0 ? contract.production_imports.join(", ") : "无"}`);
+    lines.push(`可观测: ${contract.observability_refs.length > 0 ? contract.observability_refs.join(", ") : "无"}`);
+    lines.push(`集成测试: ${contract.integration_tests.length > 0 ? contract.integration_tests.join(", ") : "无"}`);
+    if (contract.allowed_isolation_reason) {
+        lines.push(`豁免原因: ${contract.allowed_isolation_reason}`);
+    }
+    return lines.join("\n");
+}
+// ── Governance Validation ──
+/**
+ * 验证主链路接入。
+ * @param options.contracts - 主链路接入契约列表
+ * @param options.capabilityKinds - 模块路径到能力类型的映射（可选）
+ * @returns 治理发现列表
+ */
+export function validateMainPathIntegration(options) {
+    const findings = [];
+    console.error(`[soloForge] 主链路接入: 开始治理验证 — 共 ${options.contracts.length} 个契约`);
+    for (const c of options.contracts) {
+        const kind = options.capabilityKinds?.get(c.module_path);
+        // 规则 1: 新增 src/** 生产代码只被测试导入 → hard_fail
+        if (c.module_path.startsWith("src/") && !hasProductionImport(c) && c.integration_tests.length > 0 && !isExemptFile(c.module_path).exempt) {
+            findings.push({
+                severity: "hard_fail",
+                rule: "gc-test-only-module",
+                module_path: c.module_path,
+                message: `新增 src/ 生产代码 ${c.module_path} 只被测试导入，必须 hard_fail`,
+            });
+        }
+        // 规则 2: enforced contract/guard/verifier/workflow 无入口链路 → hard_fail
+        if (kind &&
+            (kind === "contract" || kind === "guard" || kind === "verifier" || kind === "workflow") &&
+            c.status !== "experimental_isolated" &&
+            !hasEntryTrace(c)) {
+            findings.push({
+                severity: "hard_fail",
+                rule: "gc-enforced-no-entry",
+                module_path: c.module_path,
+                message: `新增 enforced ${kind} ${c.module_path} 没有入口链路和真实编排路径`,
+            });
+        }
+        // 规则 3: registry-only / manifest-only / index-export-only 不得视为完成
+        if (c.status === "integrated" &&
+            !hasProductionImport(c) &&
+            !hasEntryTrace(c)) {
+            findings.push({
+                severity: "hard_fail",
+                rule: "gc-registry-only-completion",
+                module_path: c.module_path,
+                message: `模块 ${c.module_path} 只有 registry/index export 引用，不得标记为 integrated`,
+            });
+        }
+        // 规则 4: 必须有至少一条集成测试证明真实入口触发
+        if (c.status === "integrated" &&
+            !hasIntegrationTest(c) &&
+            !isExemptFile(c.module_path).exempt) {
+            findings.push({
+                severity: "hard_fail",
+                rule: "gc-no-integration-test",
+                module_path: c.module_path,
+                message: `已接入模块 ${c.module_path} 必须有集成测试证明真实入口能触发`,
+            });
+        }
+        // 规则 5: 必须有可观测痕迹
+        if (c.status === "integrated" &&
+            !hasObservability(c) &&
+            kind &&
+            (kind === "contract" || kind === "guard" || kind === "verifier" || kind === "diagnostic_code" || kind === "governance_report")) {
+            findings.push({
+                severity: "hard_fail",
+                rule: "gc-no-observability",
+                module_path: c.module_path,
+                message: `新增 ${kind} ${c.module_path} 缺少可观测痕迹`,
+            });
+        }
+        // 规则 6: diagnostic_code 必须能由真实路径产出
+        if (kind === "diagnostic_code" && !hasEntryTrace(c)) {
+            findings.push({
+                severity: "hard_fail",
+                rule: "gc-diagnostic-no-path",
+                module_path: c.module_path,
+                message: `新增诊断码 ${c.module_path} 无法由真实路径产出`,
+            });
+        }
+        // 规则 7: workflow 没有实际编排路径 → hard_fail
+        if (kind === "workflow" && c.status !== "experimental_isolated" && !hasEntryTrace(c)) {
+            findings.push({
+                severity: "hard_fail",
+                rule: "gc-workflow-no-orchestration",
+                module_path: c.module_path,
+                message: `新增 workflow ${c.module_path} 没有实际编排路径`,
+            });
+        }
+        // 规则 8: 新增 CLI 能力必须接入 bin/soloforge
+        if (kind === "cli_command" && !c.entry_traces.some(t => t.entry_type === "cli")) {
+            findings.push({
+                severity: "hard_fail",
+                rule: "gc-cli-no-bin",
+                module_path: c.module_path,
+                message: `新增 CLI 能力 ${c.module_path} 必须接入 bin/soloforge`,
+            });
+        }
+        // 规则 9: advisory 能力有 registry 但暂无入口 → warning
+        if (c.status === "experimental_isolated" && !hasEntryTrace(c)) {
+            findings.push({
+                severity: "warning",
+                rule: "gc-advisory-no-entry",
+                module_path: c.module_path,
+                message: `advisory/experimental 能力 ${c.module_path} 有 registry 但暂无入口`,
+            });
+        }
+        // 规则 10: implemented_not_integrated 不应标记完成
+        if (c.status === "implemented_not_integrated") {
+            findings.push({
+                severity: "warning",
+                rule: "gc-not-integrated-status",
+                module_path: c.module_path,
+                message: `模块 ${c.module_path} 状态为 implemented_not_integrated，不能标记完成`,
+            });
+        }
+    }
+    console.error(`[soloForge] 主链路接入: 治理验证完成 — 发现 ${findings.length} 个问题`);
+    return findings;
+}
+// ═══════════════════════════════════════════════════════════════
+// Real Scanning Infrastructure — 真实主链路接入扫描
+// ═══════════════════════════════════════════════════════════════
+import fs from "node:fs";
+import fspath from "node:path";
+/** 生产源码扩展名 */
+const PRODUCTION_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".java", ".kt", ".go", ".py"]);
+/** 表示非生产文件的匹配模式 */
+const NON_PRODUCTION_PATTERNS = [
+    /\.d\.ts$/,
+    /\.test\./,
+    /\.spec\./,
+    /\/tests\//,
+    /^tests?\//,
+    /\/__tests__\//,
+    /\/fixtures?\//,
+    /\/demo\//,
+    /(?:^|\/src\/)examples?\//,
+    /\/docs?\//,
+    /\/mocks?\//,
+];
+/**
+ * Determine if a file is a production source file.
+ * Uses config scope, extension, and exclusion patterns.
+ */
+/**
+ * 判断文件是否为生产源码文件。
+ * @param filePath - 文件路径
+ * @param config - 扫描配置（可选）
+ * @returns 是否为生产文件
+ */
+export function isProductionFile(filePath, config) {
+    const normalized = filePath.replace(/\\/g, "/");
+    const ext = fspath.extname(normalized);
+    if (!PRODUCTION_EXTENSIONS.has(ext)) {
+        return { isProd: false, reason: `非生产扩展名: ${ext}` };
+    }
+    for (const p of NON_PRODUCTION_PATTERNS) {
+        if (p.test(normalized)) {
+            return { isProd: false, reason: `非生产文件: ${p.source}` };
+        }
+    }
+    const exempt = isExemptFile(normalized);
+    if (exempt.exempt) {
+        return { isProd: false, reason: exempt.reason };
+    }
+    // 如果提供了配置，检查作用域
+    if (config) {
+        const inScope = isInScope(normalized, config);
+        if (!inScope) {
+            return { isProd: false, reason: "不在项目 scope 范围内" };
+        }
+    }
+    return { isProd: true };
+}
+function isInScope(normalizedPath, config) {
+    const scopes = [];
+    if (config.scope?.backend)
+        scopes.push(...config.scope.backend);
+    if (config.scope?.frontend)
+        scopes.push(...config.scope.frontend);
+    for (const repo of config.repos ?? []) {
+        if (repo.scope)
+            scopes.push(...repo.scope);
+        scopes.push(repo.path.replace(/\\/g, "/"));
+    }
+    if (scopes.length === 0)
+        return normalizedPath.startsWith("src/");
+    return scopes.some((s) => {
+        const ns = s.replace(/\\/g, "/").replace(/^\.\//, "");
+        return normalizedPath.startsWith(ns);
+    });
+}
+/**
+ * Walk a directory recursively, collecting all file paths.
+ */
+/**
+ * 递归遍历目录，收集所有文件路径。
+ * @param dir - 目录路径
+ * @returns 文件路径列表
+ */
+export function walkDir(dir) {
+    console.error("[soloForge] 主链路接入: 遍历目录 — " + dir);
+    const results = [];
+    if (!fs.existsSync(dir)) {
+        console.error("[soloForge] 主链路接入: 遍历目录 — 目录不存在: " + dir);
+        return results;
+    }
+    try {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = fspath.join(dir, entry.name);
+            if (entry.isDirectory())
+                results.push(...walkDir(full));
+            else
+                results.push(full);
+        }
+    }
+    catch (e) {
+        console.error("[soloForge] 主链路接入: 遍历目录异常 — " + dir + ": " + (e instanceof Error ? e.message : String(e)));
+    }
+    console.error("[soloForge] 主链路接入: 遍历目录完成 — " + dir + " 共 " + results.length + " 个文件");
+    return results;
+}
+// ── Call Evidence Detection ──
+/** 从 TS/JS 导入语句中提取导入的符号名称 */
+function extractImportedNames(content, targetNorm) {
+    const names = [];
+    const modBasename = targetNorm.split("/").pop();
+    const modJsExt = modBasename.replace(/\.ts$/, ".js");
+    const escaped = modBasename.replace(/\./g, "\\.");
+    const escapedJs = modJsExt.replace(/\./g, "\\.");
+    const namedRe = new RegExp(`import\\s+\\{([^}]+)\\}\\s+from\\s+['"][^'"]*(?:${escaped}|${escapedJs})[^'"]*['"]`, "g");
+    let m;
+    while ((m = namedRe.exec(content)) !== null) {
+        for (const name of m[1].split(",")) {
+            const trimmed = name.trim().replace(/\s+as\s+\w+/, "").trim();
+            if (trimmed)
+                names.push(trimmed);
+        }
+    }
+    const defaultRe = new RegExp(`import\\s+(\\w+)\\s+from\\s+['"][^'"]*(?:${escaped}|${escapedJs})[^'"]*['"]`, "g");
+    while ((m = defaultRe.exec(content)) !== null)
+        names.push(m[1]);
+    const nsRe = new RegExp(`import\\s+\\*\\s+as\\s+(\\w+)\\s+from\\s+['"][^'"]*(?:${escaped}|${escapedJs})[^'"]*['"]`, "g");
+    while ((m = nsRe.exec(content)) !== null)
+        names.push(m[1]);
+    return [...new Set(names)];
+}
+/** 从 Java/Kotlin 导入语句中提取导入的符号名称（全限定名 → 简单名称） */
+function extractJavaImportedNames(content, targetFqn) {
+    const names = [];
+    const parts = targetFqn.split(".");
+    const simpleName = parts[parts.length - 1];
+    if (content.includes(simpleName))
+        names.push(simpleName);
+    return names;
+}
+/** Extract imported names from Go import */
+function extractGoImportedNames(_content, _pkgPath) {
+    return [];
+}
+/** Extract imported names from Python import */
+function extractPythonImportedNames(content, modulePath) {
+    const names = [];
+    const parts = modulePath.split(".");
+    const modName = parts[parts.length - 1];
+    const asRe = new RegExp(`import\\s+${modName}\\s+as\\s+(\\w+)`);
+    const asMatch = content.match(asRe);
+    if (asMatch)
+        names.push(asMatch[1]);
+    if (content.includes(modName))
+        names.push(modName);
+    return [...new Set(names)];
+}
+/**
+ * Detect call evidence in TS/JS/TSX/JSX content.
+ * Returns list of evidence pattern descriptions.
+ */
+function detectTsCallEvidence(content, names) {
+    // 移除 import/export 行以避免导入路径误报（例如 "noop.js"）
+    const codeOnly = content.replace(/^import\s.+$/gm, "").replace(/^export\s+\{[^}]*\}\s+from\s+.+$/gm, "");
+    const evidence = [];
+    for (const name of names) {
+        if (new RegExp(`\\b${name}\\s*\\(`).test(codeOnly))
+            evidence.push(`${name}()`);
+        if (new RegExp(`new\\s+${name}\\s*[\\(\\{]`).test(codeOnly))
+            evidence.push(`new ${name}()`);
+        if (new RegExp(`\\b${name}\\s*\\.`).test(codeOnly))
+            evidence.push(`${name}.method()`);
+        if (new RegExp(`<${name}[\\s/>]`).test(codeOnly))
+            evidence.push(`<${name} />`);
+    }
+    return evidence;
+}
+/** Detect call evidence in Java/Kotlin content */
+function detectJavaCallEvidence(content, names) {
+    const evidence = [];
+    for (const name of names) {
+        const nameRe = name.replace(/\./g, "\\.");
+        // new ServiceClass(...) 或 Kotlin: ServiceClass(...)
+        if (new RegExp(`(?:new\\s+)?${nameRe}\\s*\\(`).test(content)) {
+            evidence.push(new RegExp(`new\\s+${nameRe}`).test(content) ? `new ${name}()` : `${name}()`);
+        }
+        // 方法调用: service.method(...)
+        if (new RegExp(`\\b${nameRe}\\s*\\.`).test(content))
+            evidence.push(`${name}.method()`);
+        // @Inject / @Autowired 字段
+        if (new RegExp(`@(?:Inject|Autowired|Resource)\\b.*${nameRe}`).test(content))
+            evidence.push(`@Inject ${name}`);
+        // 构造函数参数或字段类型
+        if (new RegExp(`\\b${nameRe}\\s+\\w+[,)=]`).test(content))
+            evidence.push(`${name} param`);
+    }
+    return evidence;
+}
+/** Detect call evidence in Python content */
+function detectPythonCallEvidence(content, names) {
+    const evidence = [];
+    for (const name of names) {
+        if (new RegExp(`\\b${name}\\s*\\(`).test(content))
+            evidence.push(`${name}()`);
+        if (new RegExp(`\\b${name}\\s*\\.`).test(content))
+            evidence.push(`${name}.method()`);
+    }
+    return evidence;
+}
+/** Detect call evidence in Go content */
+function detectGoCallEvidence(content, names) {
+    const evidence = [];
+    for (const name of names) {
+        if (new RegExp(`\\b${name}\\s*\\.`).test(content))
+            evidence.push(`${name}.Method()`);
+        if (new RegExp(`\\b${name}\\s*\\(`).test(content))
+            evidence.push(`${name}()`);
+    }
+    return evidence;
+}
+// ── Import Resolution ──
+/**
+ * Extract import/require paths from source content.
+ */
+/**
+ * 从源码内容中提取 import/require 路径。
+ * @param content - 源码内容
+ * @param filePath - 文件路径
+ * @returns 导入路径列表
+ */
+export function extractImportPaths(content, filePath) {
+    console.error("[soloForge] 主链路接入: 提取导入路径 — " + filePath);
+    const paths = [];
+    const ext = fspath.extname(filePath);
+    if (ext === ".java" || ext === ".kt") {
+        const re = /import\s+([\w.]+)\s*;?/g;
+        let m;
+        while ((m = re.exec(content)) !== null)
+            paths.push(m[1]);
+    }
+    else if (ext === ".go") {
+        // import "path" 和 import ( ... "path" ... )
+        const singleRe = /import\s+"([^"]+)"/g;
+        let m;
+        while ((m = singleRe.exec(content)) !== null)
+            paths.push(m[1]);
+        const multiRe = /import\s*\(\s*([\s\S]*?)\)/g;
+        while ((m = multiRe.exec(content)) !== null) {
+            const inner = m[1];
+            const lines = inner.match(/"([^"]+)"/g);
+            if (lines)
+                for (const l of lines)
+                    paths.push(l.replace(/"/g, ""));
+        }
+    }
+    else if (ext === ".py") {
+        const fromRe = /from\s+([\w.]+)\s+import/g;
+        let m;
+        while ((m = fromRe.exec(content)) !== null)
+            paths.push(m[1]);
+        const importRe = /\bimport\s+([\w.]+)/g;
+        while ((m = importRe.exec(content)) !== null)
+            paths.push(m[1]);
+    }
+    else {
+        // TypeScript/JavaScript
+        const fromRe = /(?:import|export)\s+(?:type\s+)?[^'"]*?\s+from\s+['"]([^'"]+)['"]/g;
+        let m;
+        while ((m = fromRe.exec(content)) !== null)
+            paths.push(m[1]);
+        const reqRe = /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+        while ((m = reqRe.exec(content)) !== null)
+            paths.push(m[1]);
+    }
+    console.error("[soloForge] 主链路接入: 提取导入路径完成 — " + filePath + " 共 " + paths.length + " 条");
+    return paths;
+}
+/**
+ * Resolve a relative import to a normalized project-relative path.
+ */
+/**
+ * 将相对导入解析为标准化的项目相对路径。
+ * @param importSpecifier - 导入指定器
+ * @param fromFileRel - 来源文件的相对路径
+ * @param projectPath - 项目根路径
+ * @returns 解析后的相对路径
+ */
+export function resolveImportPath(importSpecifier, fromFileRel, projectPath) {
+    if (!importSpecifier.startsWith("."))
+        return null;
+    console.error("[soloForge] 主链路接入: 解析导入路径 — " + importSpecifier + " (from " + fromFileRel + ")");
+    let spec = importSpecifier;
+    // 去除 .js/.jsx 扩展名 — 实际文件可能是 .ts 或 .tsx
+    const hasExt = /\.(ts|tsx|js|jsx)$/.test(spec);
+    if (spec.endsWith(".js"))
+        spec = spec.slice(0, -3);
+    else if (spec.endsWith(".jsx"))
+        spec = spec.slice(0, -4);
+    const fromDir = fspath.dirname(fspath.resolve(projectPath, fromFileRel));
+    const resolved = fspath.resolve(fromDir, spec);
+    // 优先尝试精确匹配（如果指定器有直接映射的扩展名）
+    if (hasExt && fs.existsSync(resolved)) {
+        return fspath.relative(projectPath, resolved).replace(/\\/g, "/");
+    }
+    // 尝试所有生产扩展名
+    for (const ext of [".ts", ".tsx", ".js", ".jsx"]) {
+        const p = resolved + ext;
+        if (fs.existsSync(p))
+            return fspath.relative(projectPath, p).replace(/\\/g, "/");
+    }
+    for (const idx of ["index.ts", "index.tsx", "index.js", "index.jsx"]) {
+        const p = fspath.join(resolved, idx);
+        if (fs.existsSync(p))
+            return fspath.relative(projectPath, p).replace(/\\/g, "/");
+    }
+    return null;
+}
+/** Normalize a module path by stripping extension for comparison */
+function normalizeModulePath(p) {
+    return p.replace(/\.(ts|tsx|js|jsx)$/, "").replace(/\\/g, "/");
+}
+// ── Java/Kotlin FQN Resolution ──
+/**
+ * Compute the Fully Qualified Name of a Java/Kotlin file from its package + class.
+ */
+/**
+ * 从 Java/Kotlin 文件计算全限定名。
+ * @param filePath - 文件路径
+ * @param projectPath - 项目根路径
+ * @returns 全限定名
+ */
+export function computeJavaFqn(filePath, projectPath) {
+    console.error("[soloForge] 主链路接入: 计算Java全限定名 — " + filePath);
+    let content;
+    try {
+        content = fs.readFileSync(fspath.join(projectPath, filePath), "utf-8");
+    }
+    catch (e) {
+        console.error("[soloForge] 主链路接入: 计算Java全限定名失败 — " + filePath + ": " + (e instanceof Error ? e.message : String(e)));
+        return null;
+    }
+    const pkgMatch = content.match(/package\s+([\w.]+)\s*;?/);
+    if (!pkgMatch) {
+        console.error("[soloForge] 主链路接入: 计算Java全限定名 — 未找到 package 声明: " + filePath);
+        return null;
+    }
+    const pkg = pkgMatch[1];
+    const classMatch = content.match(/(?:public\s+)?(?:class|interface|enum|record)\s+(\w+)/);
+    if (!classMatch) {
+        console.error("[soloForge] 主链路接入: 计算Java全限定名 — 未找到类声明: " + filePath);
+        return null;
+    }
+    const fqn = `${pkg}.${classMatch[1]}`;
+    console.error("[soloForge] 主链路接入: 计算Java全限定名完成 — " + fqn);
+    return fqn;
+}
+/**
+ * Match a Java FQN against import statements in another Java file.
+ */
+function matchJavaFqn(importerContent, targetFqn) {
+    const fqnImport = "import " + targetFqn;
+    const wildcardImport = "import " + targetFqn.split(".").slice(0, -1).join(".") + ".*";
+    return importerContent.includes(fqnImport + ";") ||
+        importerContent.includes(fqnImport + "\n") ||
+        importerContent.includes(wildcardImport + ";") ||
+        importerContent.includes(wildcardImport + "\n");
+}
+// ── Python Module Path Resolution ──
+/**
+ * Compute Python module path from file path.
+ * e.g. src/services/user.py → services.user
+ */
+function computePythonModulePath(filePath) {
+    const normalized = filePath.replace(/\\/g, "/");
+    const noExt = normalized.replace(/\.py$/, "");
+    const parts = noExt.split("/");
+    // 去除常见前缀如 src/
+    const srcIdx = parts.findIndex(p => p === "src");
+    if (srcIdx >= 0)
+        return parts.slice(srcIdx + 1).join(".");
+    return parts.join(".");
+}
+// ── Go Package Path Resolution ──
+/**
+ * Resolve Go import path from file path and module name.
+ * Simplified: returns directory-based package path.
+ */
+function computeGoPkgPath(filePath) {
+    return fspath.dirname(filePath.replace(/\\/g, "/")).replace(/\\/g, "/");
+}
+// ── Core Scanning ──
+/**
+ * Scan all project files to find who imports a given module.
+ * Classifies each importer and detects call evidence.
+ */
+/**
+ * 扫描项目中所有文件，查找谁导入了指定模块。
+ * @param projectPath - 项目根路径
+ * @param moduleRelPath - 模块相对路径
+ * @returns 导入者扫描结果
+ */
+export function scanModuleImporters(projectPath, moduleRelPath) {
+    console.error("[soloForge] 主链路接入: 扫描模块导入者 — " + moduleRelPath);
+    const result = {
+        production_imports: [],
+        production_calls: [],
+        test_imports: [],
+        barrel_exports: [],
+        registry_declarations: [],
+        import_only: [],
+    };
+    const targetNorm = normalizeModulePath(moduleRelPath);
+    const moduleExt = fspath.extname(moduleRelPath);
+    const allFiles = walkDir(projectPath);
+    // 预计算 Java/Kotlin 目标全限定名
+    let targetJavaFqn = null;
+    if (moduleExt === ".java" || moduleExt === ".kt") {
+        targetJavaFqn = computeJavaFqn(moduleRelPath, projectPath);
+    }
+    // 预计算 Python 目标模块路径
+    let targetPyModule = null;
+    if (moduleExt === ".py") {
+        targetPyModule = computePythonModulePath(moduleRelPath);
+    }
+    // 预计算 Go 包路径
+    let targetGoPkg = null;
+    if (moduleExt === ".go") {
+        targetGoPkg = computeGoPkgPath(moduleRelPath);
+    }
+    for (const file of allFiles) {
+        const rel = fspath.relative(projectPath, file).replace(/\\/g, "/");
+        if (normalizeModulePath(rel) === targetNorm)
+            continue;
+        const ext = fspath.extname(file);
+        if (![".ts", ".tsx", ".js", ".jsx", ".java", ".kt", ".go", ".py"].includes(ext))
+            continue;
+        let content;
+        try {
+            content = fs.readFileSync(file, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        // ── Match imports using language-specific resolution ──
+        let matched = false;
+        let importedNames = [];
+        if (moduleExt === ".java" || moduleExt === ".kt") {
+            // Java/Kotlin: 通过全限定名匹配
+            if (targetJavaFqn && matchJavaFqn(content, targetJavaFqn)) {
+                matched = true;
+                importedNames = extractJavaImportedNames(content, targetJavaFqn);
+            }
+        }
+        else if (moduleExt === ".py") {
+            // Python: 通过模块路径匹配
+            if (targetPyModule) {
+                const importerPaths = extractImportPaths(content, rel);
+                for (const imp of importerPaths) {
+                    if (imp === targetPyModule || imp.startsWith(targetPyModule + ".")) {
+                        matched = true;
+                        importedNames = extractPythonImportedNames(content, targetPyModule);
+                        break;
+                    }
+                }
+            }
+        }
+        else if (moduleExt === ".go") {
+            // Go: 通过包路径匹配
+            if (targetGoPkg) {
+                const importerPaths = extractImportPaths(content, rel);
+                for (const imp of importerPaths) {
+                    if (imp.endsWith(targetGoPkg) || imp === targetGoPkg) {
+                        matched = true;
+                        importedNames = extractGoImportedNames(content, targetGoPkg);
+                        break;
+                    }
+                }
+            }
+        }
+        else {
+            // TS/JS/TSX/JSX: 通过相对导入解析匹配
+            const imports = extractImportPaths(content, rel);
+            for (const imp of imports) {
+                if (!imp.startsWith("."))
+                    continue;
+                const resolved = resolveImportPath(imp, rel, projectPath);
+                if (resolved && normalizeModulePath(resolved) === targetNorm) {
+                    matched = true;
+                    importedNames = extractImportedNames(content, targetNorm);
+                    break;
+                }
+            }
+        }
+        if (!matched)
+            continue;
+        // ── Classify the importer ──
+        const isTest = /\.test\.|\.spec\.|\/tests\/|\/__tests__\//.test(rel);
+        if (isTest) {
+            result.test_imports.push(rel);
+            continue;
+        }
+        if (isOnlyReExport(content, targetNorm, ext)) {
+            result.barrel_exports.push(rel);
+            continue;
+        }
+        if (isRegistryOnlyImport(content, targetNorm, ext)) {
+            result.registry_declarations.push(rel);
+            continue;
+        }
+        // ── Detect call evidence ──
+        let callEvidence = [];
+        if (ext === ".java" || ext === ".kt") {
+            callEvidence = detectJavaCallEvidence(content, importedNames);
+        }
+        else if (ext === ".py") {
+            callEvidence = detectPythonCallEvidence(content, importedNames);
+        }
+        else if (ext === ".go") {
+            callEvidence = detectGoCallEvidence(content, importedNames);
+        }
+        else {
+            callEvidence = detectTsCallEvidence(content, importedNames);
+        }
+        if (callEvidence.length > 0) {
+            result.production_imports.push(rel);
+            result.production_calls.push({ importer: rel, patterns: callEvidence });
+        }
+        else {
+            // 仅导入，无调用证据
+            result.import_only.push(rel);
+        }
+    }
+    console.error("[soloForge] 主链路接入: 扫描模块导入者完成 — " + moduleRelPath + " 生产导入 " + result.production_imports.length + " 测试导入 " + result.test_imports.length + " 调用证据 " + result.production_calls.length);
+    return result;
+}
+/** Check if a file only re-exports the module (barrel export) */
+function isOnlyReExport(content, targetNorm, ext) {
+    if (ext === ".java" || ext === ".kt" || ext === ".go" || ext === ".py")
+        return false;
+    const modBasename = targetNorm.split("/").pop();
+    const escaped = modBasename.replace(/\./g, "\\.");
+    const escapedJs = modBasename.replace(/\.ts$/, ".js").replace(/\./g, "\\.");
+    const reExportRe = new RegExp(`export\\s+(?:\\*|\\{[^}]*\\})\\s+from\\s+['"][^'"]*(?:${escaped}|${escapedJs})[^'"]*['"]`);
+    if (!reExportRe.test(content))
+        return false;
+    const usageRe = new RegExp(`(?<!export\\s)(?<!from\\s['"])${modBasename.replace(/\./g, "\\.")}`, "g");
+    const usageMatches = content.match(usageRe);
+    return !usageMatches || usageMatches.length <= 2;
+}
+/** Check if a file only has registry-style declarations for the module */
+function isRegistryOnlyImport(content, targetNorm, ext) {
+    if (ext === ".java" || ext === ".kt" || ext === ".go" || ext === ".py")
+        return false;
+    const modBasename = targetNorm.split("/").pop();
+    const modJsExt = modBasename.replace(/\.ts$/, ".js");
+    const escaped = modBasename.replace(/\./g, "\\.");
+    const escapedJs = modJsExt.replace(/\./g, "\\.");
+    const regPatterns = [
+        new RegExp(`\\.push\\s*\\(`, "s"),
+        new RegExp(`register\\s*\\(`, "s"),
+        new RegExp(`entries\\s*[:=]`, "s"),
+    ];
+    const hasRegistry = regPatterns.some(p => p.test(content));
+    if (!hasRegistry)
+        return false;
+    const importLineRe = new RegExp(`import\\s+.*from\\s+['"][^'"]*(?:${escaped}|${escapedJs})[^'"]*['"]`);
+    const lines = content.split("\n");
+    let importCount = 0;
+    let usageCount = 0;
+    for (const line of lines) {
+        if (importLineRe.test(line)) {
+            importCount++;
+            continue;
+        }
+        if (line.includes(modBasename))
+            usageCount++;
+    }
+    return usageCount <= 1 && importCount > 0;
+}
+/**
+ * Identify entry points in the project by directory/file naming conventions.
+ */
+/**
+ * 通过目录/文件命名约定识别项目入口点。
+ * @param projectPath - 项目根路径
+ * @returns 入口点追踪列表
+ */
+export function identifyProjectEntryPoints(projectPath) {
+    console.error("[soloForge] 主链路接入: 识别项目入口点 — " + projectPath);
+    const eps = [];
+    const allFiles = walkDir(projectPath);
+    const patterns = [
+        { test: /adapters\/.*tools?\.ts$/, type: "mcp_tool", example: "MCP tool handler" },
+        { test: /\/bin\//, type: "cli", example: "CLI command" },
+        { test: /\/cli\//, type: "cli", example: "CLI entry" },
+        { test: /\/commands?\//, type: "command", example: "Command handler" },
+        { test: /\/routes?\//, type: "backend_route", example: "HTTP route" },
+        { test: /\/controllers?\//, type: "backend_route", example: "Controller" },
+        { test: /\/api\//, type: "public_api", example: "API endpoint" },
+        { test: /\/pages?\//, type: "frontend_route", example: "Page component" },
+        { test: /\/app\//, type: "frontend_route", example: "App entry" },
+        { test: /\/jobs?\//, type: "job", example: "Background job" },
+        { test: /\/consumers?\//, type: "consumer", example: "Event consumer" },
+        { test: /\/workers?\//, type: "job", example: "Worker" },
+        { test: /\/crons?\//, type: "cron", example: "Cron job" },
+        { test: /\/webhooks?\//, type: "webhook", example: "Webhook handler" },
+    ];
+    for (const file of allFiles) {
+        const rel = fspath.relative(projectPath, file).replace(/\\/g, "/");
+        const ext = fspath.extname(file);
+        if (!PRODUCTION_EXTENSIONS.has(ext))
+            continue;
+        if (/\.test\.|\.spec\.|\.d\.ts/.test(rel))
+            continue;
+        if (!fs.existsSync(file))
+            continue;
+        for (const { test, type, example } of patterns) {
+            if (test.test(rel)) {
+                eps.push(createEntryPointTrace({
+                    entry_type: type,
+                    entry_id: rel,
+                    call_chain: [rel],
+                    trigger_example: example,
+                }));
+                break;
+            }
+        }
+    }
+    console.error("[soloForge] 主链路接入: 识别项目入口点完成 — 共 " + eps.length + " 个入口");
+    return eps;
+}
+/**
+ * Trace from entry points to a target module via import chains.
+ * Uses DFS with depth limit to prevent infinite loops.
+ * Supports TS/JS, Java/Kotlin (FQN), Python, Go.
+ */
+/**
+ * 从入口点通过导入链追踪到目标模块。
+ * @param projectPath - 项目根路径
+ * @param moduleRelPath - 模块相对路径
+ * @param entryPoints - 入口点列表
+ * @returns 可达的入口点列表
+ */
+export function traceModuleReachability(projectPath, moduleRelPath, entryPoints) {
+    console.error("[soloForge] 主链路接入: 追踪模块可达性 — " + moduleRelPath + " 从 " + entryPoints.length + " 个入口");
+    const targetNorm = normalizeModulePath(moduleRelPath);
+    const moduleExt = fspath.extname(moduleRelPath);
+    const reachable = [];
+    let targetJavaFqn = null;
+    if (moduleExt === ".java" || moduleExt === ".kt") {
+        targetJavaFqn = computeJavaFqn(moduleRelPath, projectPath);
+    }
+    let targetPyModule = null;
+    if (moduleExt === ".py") {
+        targetPyModule = computePythonModulePath(moduleRelPath);
+    }
+    let targetGoPkg = null;
+    if (moduleExt === ".go") {
+        targetGoPkg = computeGoPkgPath(moduleRelPath);
+    }
+    for (const ep of entryPoints) {
+        const epFile = fspath.resolve(projectPath, ep.entry_id);
+        if (!fs.existsSync(epFile))
+            continue;
+        const chain = [];
+        const visited = new Set();
+        if (dfsTrace(epFile, targetNorm, projectPath, visited, chain, targetJavaFqn, targetPyModule, targetGoPkg)) {
+            reachable.push({
+                ...ep,
+                call_chain: [ep.entry_id, ...chain],
+            });
+        }
+    }
+    console.error("[soloForge] 主链路接入: 追踪模块可达性完成 — " + moduleRelPath + " 可达 " + reachable.length + " 个入口");
+    return reachable;
+}
+function dfsTrace(currentFile, targetNorm, projectPath, visited, chain, targetJavaFqn, targetPyModule, targetGoPkg, depth = 0) {
+    if (depth > 15)
+        return false;
+    const abs = fspath.resolve(currentFile);
+    if (visited.has(abs))
+        return false;
+    visited.add(abs);
+    let content;
+    try {
+        content = fs.readFileSync(abs, "utf-8");
+    }
+    catch {
+        return false;
+    }
+    const rel = fspath.relative(projectPath, abs).replace(/\\/g, "/");
+    const ext = fspath.extname(rel);
+    // 检查当前文件是否直接导入了目标模块
+    if (targetJavaFqn && (ext === ".java" || ext === ".kt")) {
+        if (matchJavaFqn(content, targetJavaFqn)) {
+            if (depth > 0)
+                chain.push(rel);
+            return true;
+        }
+    }
+    else if (targetPyModule && ext === ".py") {
+        const importerPaths = extractImportPaths(content, rel);
+        for (const imp of importerPaths) {
+            if (imp === targetPyModule || imp.startsWith(targetPyModule + ".")) {
+                if (depth > 0)
+                    chain.push(rel);
+                return true;
+            }
+        }
+    }
+    else if (targetGoPkg && ext === ".go") {
+        const importerPaths = extractImportPaths(content, rel);
+        for (const imp of importerPaths) {
+            if (imp.endsWith(targetGoPkg) || imp === targetGoPkg) {
+                if (depth > 0)
+                    chain.push(rel);
+                return true;
+            }
+        }
+    }
+    else {
+        // TS/JS: 检查相对导入
+        const imports = extractImportPaths(content, rel);
+        for (const imp of imports) {
+            if (!imp.startsWith("."))
+                continue;
+            const resolved = resolveImportPath(imp, rel, projectPath);
+            if (resolved && normalizeModulePath(resolved) === targetNorm) {
+                chain.push(resolved);
+                return true;
+            }
+        }
+    }
+    // 递归: 跟随 TS/JS 文件的导入链
+    if (!targetJavaFqn && !targetPyModule && !targetGoPkg) {
+        const imports = extractImportPaths(content, rel);
+        for (const imp of imports) {
+            if (!imp.startsWith("."))
+                continue;
+            const resolved = resolveImportPath(imp, rel, projectPath);
+            if (!resolved)
+                continue;
+            const nextAbs = fspath.resolve(projectPath, resolved);
+            if (dfsTrace(nextAbs, targetNorm, projectPath, visited, chain, null, null, null, depth + 1)) {
+                chain.unshift(resolved);
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Collect observability evidence for a module.
+ */
+/**
+ * 收集模块的可观测性证据。
+ * @param projectPath - 项目根路径
+ * @param moduleRelPath - 模块相对路径
+ * @returns 可观测性引用列表
+ */
+export function collectModuleObservability(projectPath, moduleRelPath) {
+    console.error("[soloForge] 主链路接入: 收集模块可观测性 — " + moduleRelPath);
+    const refs = [];
+    const fullPath = fspath.join(projectPath, moduleRelPath);
+    let content;
+    try {
+        content = fs.readFileSync(fullPath, "utf-8");
+    }
+    catch (e) {
+        console.error("[soloForge] 主链路接入: 收集模块可观测性失败 — " + moduleRelPath + ": " + (e instanceof Error ? e.message : String(e)));
+        return refs;
+    }
+    const patterns = [
+        { re: /VerifyResult|TaskContext|GovernanceReport|DeliveryResult/, desc: "结果类型引用" },
+        { re: /main_path_integration/, desc: "main_path_integration 字段" },
+        { re: /summary\s*[:+=]/, desc: "summary 生成" },
+        { re: /console\.|logger\.|log\(/, desc: "日志输出" },
+    ];
+    for (const { re, desc } of patterns) {
+        if (re.test(content))
+            refs.push(`${moduleRelPath}: ${desc}`);
+    }
+    const modBasename = fspath.basename(moduleRelPath, fspath.extname(moduleRelPath));
+    const allFiles = walkDir(projectPath);
+    for (const file of allFiles) {
+        const rel = fspath.relative(projectPath, file).replace(/\\/g, "/");
+        if (normalizeModulePath(rel) === normalizeModulePath(moduleRelPath))
+            continue;
+        if (/\.test\.|\.spec\.|\/tests\//.test(rel))
+            continue;
+        try {
+            const fc = fs.readFileSync(file, "utf-8");
+            if (fc.includes(modBasename) && /result|response|output|report|evidence/.test(fc)) {
+                refs.push(`referenced in ${rel}`);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    console.error("[soloForge] 主链路接入: 收集模块可观测性完成 — " + moduleRelPath + " 共 " + refs.length + " 条证据");
+    return refs;
+}
+/**
+ * Find integration test files for a module.
+ */
+function stripComments(source) {
+    let s = source.replace(/\/\/.*$/gm, "");
+    s = s.replace(/\/\*[\s\S]*?\*\//g, "");
+    return s;
+}
+/**
+ * Determine if a test file constitutes integration/contract test evidence
+ * for the target module. Uses structural analysis, not basename text matching.
+ *
+ * Integration test: test imports an entry point that can reach the target module.
+ * Contract test:    test directly imports the target module AND has real call evidence.
+ * Mere mentions in comments or strings are ignored.
+ */
+/**
+ * 查找模块的集成测试文件。
+ * @param projectPath - 项目根路径
+ * @param moduleRelPath - 模块相对路径
+ * @returns 集成测试文件路径列表
+ */
+export function findIntegrationTests(projectPath, moduleRelPath) {
+    console.error("[soloForge] 主链路接入: 查找集成测试 — " + moduleRelPath);
+    const tests = [];
+    const allFiles = walkDir(projectPath);
+    const moduleExt = fspath.extname(moduleRelPath);
+    const normalized = moduleRelPath.replace(/\\/g, "/");
+    const entryPoints = identifyProjectEntryPoints(projectPath);
+    for (const file of allFiles) {
+        const rel = fspath.relative(projectPath, file).replace(/\\/g, "/");
+        if (!/\.test\.|\.spec\.|\/tests?\/|[Tt]est\.(?:ts|tsx|js|jsx|java|kt)|(?:integration|contract)[._-]/i.test(rel))
+            continue;
+        let content;
+        try {
+            content = fs.readFileSync(file, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const ext = fspath.extname(rel);
+        const codeOnly = stripComments(content);
+        if (ext === ".java" || ext === ".kt") {
+            const targetFqn = computeJavaFqn(normalized, projectPath);
+            if (!targetFqn)
+                continue;
+            if (!matchJavaFqn(codeOnly, targetFqn))
+                continue;
+            const importedNames = extractJavaImportedNames(codeOnly, targetFqn);
+            if (importedNames.length === 0)
+                continue;
+            const callEvidence = detectJavaCallEvidence(codeOnly, importedNames);
+            if (callEvidence.length > 0)
+                tests.push(rel);
+        }
+        else if (ext === ".py") {
+            const targetPyModule = computePythonModulePath(normalized);
+            const imports = extractImportPaths(codeOnly, rel);
+            const hasImport = imports.some((imp) => imp === targetPyModule || imp.endsWith("." + targetPyModule.split(".").pop()));
+            if (!hasImport)
+                continue;
+            const names = extractPythonImportedNames(codeOnly, targetPyModule);
+            const callEvidence = detectPythonCallEvidence(codeOnly, names);
+            if (callEvidence.length > 0)
+                tests.push(rel);
+        }
+        else {
+            // TS/JS: 两种路径
+            // 路径 1: integration test — test imports an entry point that can reach the module
+            const testImports = extractImportPaths(codeOnly, rel);
+            let isIntegrationTest = false;
+            for (const imp of testImports) {
+                if (!imp.startsWith("."))
+                    continue;
+                const resolved = resolveImportPath(imp, rel, projectPath);
+                if (!resolved)
+                    continue;
+                const epMatch = entryPoints.find((ep) => ep.entry_id === resolved);
+                if (epMatch) {
+                    const traces = traceModuleReachability(projectPath, normalized, [epMatch]);
+                    if (traces.length > 0) {
+                        isIntegrationTest = true;
+                        break;
+                    }
+                }
+            }
+            if (isIntegrationTest) {
+                tests.push(rel);
+                continue;
+            }
+            // 路径 2: contract test — test directly imports the target module with call evidence
+            const targetNorm = normalizeModulePath(normalized);
+            const importedNames = extractImportedNames(codeOnly, normalized);
+            if (importedNames.length === 0)
+                continue;
+            const callEvidence = detectTsCallEvidence(codeOnly, importedNames);
+            if (callEvidence.length > 0)
+                tests.push(rel);
+        }
+    }
+    console.error("[soloForge] 主链路接入: 查找集成测试完成 — " + moduleRelPath + " 共 " + tests.length + " 个测试");
+    return tests;
+}
+/**
+ * Build real MainPathIntegrationContracts from filesystem scanning.
+ * This is the main entry point for integration checking.
+ *
+ * integrated requires BOTH call evidence AND entry_traces.
+ * Import-only (no call) or no entry trace → implemented_not_integrated.
+ */
+/**
+ * 通过文件系统扫描构建真实的主链路接入契约。
+ * @param projectPath - 项目根路径
+ * @param changedFiles - 变更文件列表
+ * @param config - 扫描配置（可选）
+ * @returns 主链路接入契约列表
+ */
+export function buildMainPathIntegrationContracts(projectPath, changedFiles, config) {
+    const contracts = [];
+    console.error(`[soloForge] 主链路接入: 开始扫描变更文件 — 共 ${changedFiles.length} 个文件`);
+    const entryPoints = identifyProjectEntryPoints(projectPath);
+    for (const filePath of changedFiles) {
+        const normalized = filePath.replace(/\\/g, "/");
+        const prodCheck = isProductionFile(normalized, config);
+        if (!prodCheck.isProd)
+            continue;
+        console.error("[soloForge] 主链路接入: 扫描生产文件 — " + normalized);
+        const fullPath = fspath.join(projectPath, normalized);
+        if (!fs.existsSync(fullPath)) {
+            console.error("[soloForge] 主链路接入: 文件不存在 — " + normalized);
+            continue;
+        }
+        // 步骤 1: Scan who imports this module
+        const scanResult = scanModuleImporters(projectPath, normalized);
+        // 步骤 2: Trace reachability from entry points
+        const entryTraces = traceModuleReachability(projectPath, normalized, entryPoints);
+        // 步骤 3: Determine integration status
+        // integrated 需要同时满足: 真实调用证据 (production_imports) 和入口链路 (entry_traces)
+        const hasCallEvidence = scanResult.production_imports.length > 0;
+        const hasEntryTrace = entryTraces.length > 0;
+        let status;
+        if (hasCallEvidence && hasEntryTrace) {
+            status = "integrated";
+        }
+        else if (hasCallEvidence && !hasEntryTrace) {
+            // 有调用证据但无入口链路 → 未完全接入
+            status = "implemented_not_integrated";
+        }
+        else if (scanResult.import_only.length > 0) {
+            // 仅被导入从未被调用
+            status = "implemented_not_integrated";
+        }
+        else if (scanResult.barrel_exports.length > 0 || scanResult.registry_declarations.length > 0) {
+            status = "implemented_not_integrated";
+        }
+        else if (scanResult.test_imports.length > 0) {
+            status = "implemented_not_integrated";
+        }
+        else {
+            status = "implemented_not_integrated";
+        }
+        console.error("[soloForge] 主链路接入: 状态判定 — " + normalized + " → " + status);
+        // 步骤 4: Collect observability evidence
+        const observabilityRefs = collectModuleObservability(projectPath, normalized);
+        // 步骤 5: Find integration tests
+        const intTests = findIntegrationTests(projectPath, normalized);
+        contracts.push({
+            module_path: normalized,
+            status,
+            production_imports: scanResult.production_imports,
+            entry_traces: entryTraces,
+            observability_refs: observabilityRefs,
+            integration_tests: intTests,
+            owner: "",
+        });
+    }
+    console.error("[soloForge] 主链路接入: 扫描变更文件完成 — 共 " + contracts.length + " 个契约");
+    return contracts;
+}
+/**
+ * Collect all production files across repos and scopes.
+ */
+/**
+ * 收集所有生产文件。
+ * @param projectPath - 项目根路径
+ * @param config - 扫描配置（可选）
+ * @returns 生产文件路径列表
+ */
+export function collectAllProductionFiles(projectPath, config) {
+    console.error("[soloForge] 主链路接入: 收集所有生产文件 — " + projectPath);
+    const files = [];
+    const allFiles = walkDir(projectPath);
+    for (const file of allFiles) {
+        const rel = fspath.relative(projectPath, file).replace(/\\/g, "/");
+        const prodCheck = isProductionFile(rel, config);
+        if (prodCheck.isProd) {
+            files.push(rel);
+        }
+    }
+    console.error("[soloForge] 主链路接入: 收集所有生产文件完成 — 共 " + files.length + " 个文件");
+    return files;
+}
+//# sourceMappingURL=main_path_integration_contract.js.map