spectra-cli 4.1.1 → 4.3.0

package/dist/knowledge-graph/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Feature 151 — Knowledge Graph 模块顶层 API（FR-3 + Codex C-3 修订）
+ *
+ * 入口：buildUnifiedGraph(input)
+ *   - 收集所有 CallSite + callerFile
+ *   - call-resolver 派生 calls 边
+ *   - deriveImportEdges 派生 depends-on 边（Codex C-3：ModuleGraph 数据源）
+ *   - 装配 nodes / edges / metadata 输出 UnifiedGraph
+ *
+ * 单例 cache：
+ *   - setCurrentUnifiedGraph / getCurrentUnifiedGraph
+ *   - 让 panoramic 阶段（component-view-builder DI）能在不改 generate 签名的前提下消费
+ *   - batch-orchestrator 在生成 graph.json 之前 setCurrentUnifiedGraph(graph)
+ */
+import type { CodeSkeleton } from '../models/code-skeleton.js';
+import type { CallSite } from '../models/call-site.js';
+import { resolveCalls, type CallSiteWithFile } from './call-resolver.js';
+import { UNIFIED_GRAPH_SCHEMA_VERSION, defaultDirectionalForRelation, type UnifiedEdge, type UnifiedGraph, type UnifiedNode } from './unified-graph.js';
+export interface BuildUnifiedGraphInput {
+    projectRoot: string;
+    /** absoluteFilePath → CodeSkeleton */
+    codeSkeletons: ReadonlyMap<string, CodeSkeleton>;
+    /** 可选：复用已构建的节点（panoramic GraphNode → UnifiedNode 转换路径），避免重复枚举 */
+    preBuiltNodes?: ReadonlyArray<UnifiedNode>;
+}
+/**
+ * 顶层 API — 把 CodeSkeleton Map 转换为 UnifiedGraph。
+ *
+ * 输出 edges 同时含 calls + depends-on：
+ * - calls 边：来自 resolveCalls(callSites, skeletons)
+ * - depends-on 边：来自 deriveImportEdges(skeletons)
+ *
+ * 其他 relation（contains / cross-module / documents 等）由 graph-builder.ts
+ * 在 4 路合并阶段从 docGraph / architectureIR / crossReferenceLinks 注入。
+ */
+export declare function buildUnifiedGraph(input: BuildUnifiedGraphInput): UnifiedGraph;
+/**
+ * Feature 193 决策 1 — 对装配完的 UnifiedGraph 做统一相对化（in-place 返回新对象）。
+ *
+ * - node.id / node.filePath：relativizeSymbolId / relativizePosix 相对化；projectRoot 外的
+ *   节点保留绝对路径并标 metadata.external=true（FR-004）。
+ * - edge.source / edge.target：relativizeSymbolId 相对化（含 calls 边与 import 边）。
+ * - metadata.projectRoot：持久化为 '.'（schema 要求 min(1)，'.' 满足）。
+ *
+ * 幂等：已相对的 id / 路径原样返回（relativizePosix 对非绝对输入直接 POSIX 化返回）。
+ */
+export declare function relativizeGraph(graph: UnifiedGraph, projectRoot: string): UnifiedGraph;
+/**
+ * 从 CodeSkeleton.imports 派生 depends-on 边（Codex C-3 修订 + Feature 156 W1.0 importType 编码）。
+ *
+ * 设计动机：
+ * - ModuleGraph 派生（W1.4）需要 import 边数据源；如果 UnifiedGraph 只产 calls 边，
+ *   就无法派生 SCC / topologicalOrder / mermaidSource
+ * - batch-orchestrator / doc-graph-builder / delta-regenerator 等 8+ consumer 消费 import 边
+ *
+ * 实现：每个 CodeSkeleton.imports[].resolvedPath 派生一条
+ *   `${callerFile} -[depends-on]-> ${target}` 边，confidence='high'，directional=true
+ *
+ * Feature 156 W1.0 v2 / WARN-3 修订：
+ *   - evidence 字段保持纯 specifier（如 "./foo"），不再编码 importType 前缀
+ *     —— 避免污染 panoramic 消费方（graph-builder / component-view-builder 直接展示 evidenceText / note）
+ *   - importType 改写入 edge.metadata.importType 结构化字段（UnifiedEdge.metadata 已 schema 支持）
+ *   - module-derivation.deriveModuleGraph 从 metadata.importType 读，不再 split evidence
+ *
+ * 注：本函数不做 cross-module name resolution（那是 call-resolver 的工作）；
+ *     仅产 module-to-module 的 import 边。
+ */
+export declare function deriveImportEdges(codeSkeletons: ReadonlyMap<string, CodeSkeleton>): UnifiedEdge[];
+/**
+ * 设置当前 batch / pipeline 构建好的 UnifiedGraph。
+ * 由 batch-orchestrator 在生成 graph.json 之前调用，让下游 component-view-builder
+ * 等通过 getCurrentUnifiedGraph() 拿到同一份图。
+ */
+export declare function setCurrentUnifiedGraph(g: UnifiedGraph | null): void;
+/**
+ * 获取当前 batch / pipeline 已构建的 UnifiedGraph。
+ * 未设置时返回 null（生产 / 测试 / DI fallback）。
+ */
+export declare function getCurrentUnifiedGraph(): UnifiedGraph | null;
+export type { CallSite, UnifiedEdge, UnifiedGraph, UnifiedNode, CallSiteWithFile, };
+export { resolveCalls, UNIFIED_GRAPH_SCHEMA_VERSION, defaultDirectionalForRelation, };
+export { buildModuleSymbolIndex, buildClassMemberIndex, buildImportIndex, buildClassMroIndex, extractClassName, } from './call-resolver.js';
+export { CallSiteSchema, CalleeKindSchema, type CalleeKind, } from '../models/call-site.js';
+export { UnifiedGraphSchema, UnifiedNodeSchema, UnifiedNodeKindSchema, UnifiedEdgeSchema, UnifiedEdgeRelationSchema, ConfidenceTierSchema, type ConfidenceTier, type UnifiedNodeKind, type UnifiedEdgeRelation, } from './unified-graph.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/knowledge-graph/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/knowledge-graph/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EACL,YAAY,EACZ,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,4BAA4B,EAC5B,6BAA6B,EAC7B,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,oBAAoB,CAAC;AAO5B,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACjD,iEAAiE;IACjE,aAAa,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;CAC5C;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,YAAY,CAsB7E;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,GAAG,YAAY,CA2BtF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,GAC/C,WAAW,EAAE,CAqBf;AA0ED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,CAEnE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,YAAY,GAAG,IAAI,CAE5D;AAMD,YAAY,EACV,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,CAAC;AACF,OAAO,EACL,YAAY,EACZ,4BAA4B,EAC5B,6BAA6B,GAC9B,CAAC;AACF,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,KAAK,UAAU,GAChB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,yBAAyB,EACzB,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC"}

package/dist/knowledge-graph/index.js

@@ -0,0 +1,198 @@
+import { resolveCalls, } from './call-resolver.js';
+import { UNIFIED_GRAPH_SCHEMA_VERSION, defaultDirectionalForRelation, } from './unified-graph.js';
+import { relativizePosix, relativizeSymbolId } from './relativize.js';
+/**
+ * 顶层 API — 把 CodeSkeleton Map 转换为 UnifiedGraph。
+ *
+ * 输出 edges 同时含 calls + depends-on：
+ * - calls 边：来自 resolveCalls(callSites, skeletons)
+ * - depends-on 边：来自 deriveImportEdges(skeletons)
+ *
+ * 其他 relation（contains / cross-module / documents 等）由 graph-builder.ts
+ * 在 4 路合并阶段从 docGraph / architectureIR / crossReferenceLinks 注入。
+ */
+export function buildUnifiedGraph(input) {
+    const callSites = collectCallSites(input.codeSkeletons);
+    const callEdges = resolveCalls(callSites, input.codeSkeletons);
+    const importEdges = deriveImportEdges(input.codeSkeletons);
+    const nodes = input.preBuiltNodes ?? deriveNodesFromSkeletons(input.codeSkeletons);
+    // Feature 193 决策 1：出口统一相对化 pass。
+    // 覆盖全部四条值来源（deriveNodesFromSkeletons 节点、resolveCalls calls 边、
+    // deriveImportEdges 边、preBuiltNodes 注入），把绝对路径前缀相对化为 POSIX 相对路径，
+    // 使 graph + 快照跨 worktree byte 可移植。call-resolver.ts 零改动（其输出在此被覆盖）。
+    // projectRoot 持久化为 '.'（相对标记）。pass 幂等：已相对的输入原样保留。
+    return relativizeGraph({
+        nodes: [...nodes],
+        edges: [...callEdges, ...importEdges],
+        metadata: {
+            generatedAt: new Date().toISOString(),
+            projectRoot: input.projectRoot,
+            schemaVersion: UNIFIED_GRAPH_SCHEMA_VERSION,
+        },
+    }, input.projectRoot);
+}
+/**
+ * Feature 193 决策 1 — 对装配完的 UnifiedGraph 做统一相对化（in-place 返回新对象）。
+ *
+ * - node.id / node.filePath：relativizeSymbolId / relativizePosix 相对化；projectRoot 外的
+ *   节点保留绝对路径并标 metadata.external=true（FR-004）。
+ * - edge.source / edge.target：relativizeSymbolId 相对化（含 calls 边与 import 边）。
+ * - metadata.projectRoot：持久化为 '.'（schema 要求 min(1)，'.' 满足）。
+ *
+ * 幂等：已相对的 id / 路径原样返回（relativizePosix 对非绝对输入直接 POSIX 化返回）。
+ */
+export function relativizeGraph(graph, projectRoot) {
+    const nodes = graph.nodes.map((n) => {
+        const idR = relativizeSymbolId(n.id, projectRoot);
+        const next = { ...n, id: idR.value };
+        if (n.filePath !== undefined) {
+            next.filePath = relativizePosix(n.filePath, projectRoot).value;
+        }
+        if (idR.external) {
+            next.metadata = { ...next.metadata, external: true };
+        }
+        return next;
+    });
+    const edges = graph.edges.map((e) => ({
+        ...e,
+        source: relativizeSymbolId(e.source, projectRoot).value,
+        target: relativizeSymbolId(e.target, projectRoot).value,
+    }));
+    return {
+        nodes,
+        edges,
+        metadata: {
+            ...graph.metadata,
+            projectRoot: '.',
+        },
+    };
+}
+/**
+ * 从 CodeSkeleton.imports 派生 depends-on 边（Codex C-3 修订 + Feature 156 W1.0 importType 编码）。
+ *
+ * 设计动机：
+ * - ModuleGraph 派生（W1.4）需要 import 边数据源；如果 UnifiedGraph 只产 calls 边，
+ *   就无法派生 SCC / topologicalOrder / mermaidSource
+ * - batch-orchestrator / doc-graph-builder / delta-regenerator 等 8+ consumer 消费 import 边
+ *
+ * 实现：每个 CodeSkeleton.imports[].resolvedPath 派生一条
+ *   `${callerFile} -[depends-on]-> ${target}` 边，confidence='high'，directional=true
+ *
+ * Feature 156 W1.0 v2 / WARN-3 修订：
+ *   - evidence 字段保持纯 specifier（如 "./foo"），不再编码 importType 前缀
+ *     —— 避免污染 panoramic 消费方（graph-builder / component-view-builder 直接展示 evidenceText / note）
+ *   - importType 改写入 edge.metadata.importType 结构化字段（UnifiedEdge.metadata 已 schema 支持）
+ *   - module-derivation.deriveModuleGraph 从 metadata.importType 读，不再 split evidence
+ *
+ * 注：本函数不做 cross-module name resolution（那是 call-resolver 的工作）；
+ *     仅产 module-to-module 的 import 边。
+ */
+export function deriveImportEdges(codeSkeletons) {
+    const edges = [];
+    for (const [callerFile, sk] of codeSkeletons) {
+        for (const imp of sk.imports) {
+            if (!imp.resolvedPath)
+                continue;
+            // 自引用过滤（一些 mapper 把同模块作 import 输出）
+            if (imp.resolvedPath === callerFile)
+                continue;
+            // W1.0 v2 / WARN-3：evidence 保持纯 specifier；importType 写 metadata
+            const edge = {
+                source: callerFile,
+                target: imp.resolvedPath,
+                relation: 'depends-on',
+                confidence: 'high',
+                directional: defaultDirectionalForRelation('depends-on'),
+                evidence: imp.moduleSpecifier,
+                ...(imp.importType ? { metadata: { importType: imp.importType } } : {}),
+            };
+            edges.push(edge);
+        }
+    }
+    return edges;
+}
+/**
+ * 收集所有 callSite + 附加 callerFile 上下文。
+ * 仅当 CodeSkeleton.callSites 字段存在时收集；空 / 缺失字段视为该文件未抽取 callSites。
+ */
+function collectCallSites(codeSkeletons) {
+    const out = [];
+    for (const [filePath, sk] of codeSkeletons) {
+        if (!sk.callSites || sk.callSites.length === 0)
+            continue;
+        for (const cs of sk.callSites) {
+            out.push({ ...cs, callerFile: filePath });
+        }
+    }
+    return out;
+}
+/**
+ * 从 CodeSkeleton 派生 module + symbol 节点（默认行为）。
+ *
+ * 仅当 input.preBuiltNodes 未提供时使用。
+ * 输出节点结构：
+ * - 每个 CodeSkeleton 派生 1 个 module 节点（id = filePath）
+ * - 每个 ExportSymbol 派生 1 个 symbol 节点（id = `${filePath}::${exp.name}`）
+ * - class 的 members 进一步派生 symbol 节点（id = `${filePath}::${exp.name}.${m.name}`）
+ */
+function deriveNodesFromSkeletons(codeSkeletons) {
+    const nodes = [];
+    for (const [filePath, sk] of codeSkeletons) {
+        nodes.push({
+            id: filePath,
+            label: filePath.split(/[/\\]/).pop() ?? filePath,
+            kind: 'module',
+            language: sk.language,
+            filePath,
+            metadata: {
+                callSitesCount: sk.callSites?.length ?? 0,
+            },
+        });
+        for (const exp of sk.exports) {
+            const symbolId = `${filePath}::${exp.name}`;
+            nodes.push({
+                id: symbolId,
+                label: exp.name,
+                kind: 'symbol',
+                language: sk.language,
+                filePath,
+            });
+            if (exp.members) {
+                for (const m of exp.members) {
+                    nodes.push({
+                        id: `${symbolId}.${m.name}`,
+                        label: `${exp.name}.${m.name}`,
+                        kind: 'symbol',
+                        language: sk.language,
+                        filePath,
+                    });
+                }
+            }
+        }
+    }
+    return nodes;
+}
+// ───────────────────────────────────────────────────────────
+// 单例 cache（FR-7 DI provider + Codex W-1 batch 直接路径）
+// ───────────────────────────────────────────────────────────
+let _cachedGraph = null;
+/**
+ * 设置当前 batch / pipeline 构建好的 UnifiedGraph。
+ * 由 batch-orchestrator 在生成 graph.json 之前调用，让下游 component-view-builder
+ * 等通过 getCurrentUnifiedGraph() 拿到同一份图。
+ */
+export function setCurrentUnifiedGraph(g) {
+    _cachedGraph = g;
+}
+/**
+ * 获取当前 batch / pipeline 已构建的 UnifiedGraph。
+ * 未设置时返回 null（生产 / 测试 / DI fallback）。
+ */
+export function getCurrentUnifiedGraph() {
+    return _cachedGraph;
+}
+export { resolveCalls, UNIFIED_GRAPH_SCHEMA_VERSION, defaultDirectionalForRelation, };
+export { buildModuleSymbolIndex, buildClassMemberIndex, buildImportIndex, buildClassMroIndex, extractClassName, } from './call-resolver.js';
+export { CallSiteSchema, CalleeKindSchema, } from '../models/call-site.js';
+export { UnifiedGraphSchema, UnifiedNodeSchema, UnifiedNodeKindSchema, UnifiedEdgeSchema, UnifiedEdgeRelationSchema, ConfidenceTierSchema, } from './unified-graph.js';
+//# sourceMappingURL=index.js.map

package/dist/knowledge-graph/index.js.map

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

package/dist/knowledge-graph/module-derivation.d.ts

@@ -0,0 +1,252 @@
+/**
+ * module-derivation.ts — UnifiedGraph 派生 ModuleGraph 工具（Feature 156 W1.4 atomic switch）
+ *
+ * 角色：UnifiedGraph 的合法计算工具，不是过渡 shim。
+ *   - 输入：UnifiedGraph（唯一 source of truth）
+ *   - 输出：ModuleGraph 视图（含 inDegree / outDegree / level / SCC / topologicalOrder /
+ *     mermaidSource，是 panoramic / batch / index-generator 等 17 consumer 的消费形态）
+ *
+ * 设计原则（FR-22 / AC-5 / NG-7）：
+ *   - ModuleGraph 与 UnifiedGraph 并行存在，是 UnifiedGraph 的派生视图（不是双轨数据源）
+ *   - 类型名以 "Module" 为前缀，与 UnifiedGraph 的语义边界清晰分离
+ *
+ * 关键约束（FR-31）：
+ *   - 派生函数必须从**当次输入**（UnifiedGraph 参数）派生
+ *   - 禁止读取 getCurrentUnifiedGraph() 全局 cache
+ */
+import { z } from 'zod';
+import type { UnifiedGraph } from './unified-graph.js';
+import type { CodeSkeleton } from '../models/code-skeleton.js';
+/** import 语义类型（commonjs-require 在 module 视图中归并到 static） */
+export declare const ModuleImportTypeSchema: z.ZodEnum<["static", "dynamic", "type-only"]>;
+export type ModuleImportType = z.infer<typeof ModuleImportTypeSchema>;
+/** 模块图节点（kind === 'module' 的 UnifiedNode 派生） */
+export declare const ModuleNodeSchema: z.ZodObject<{
+    source: z.ZodString;
+    isOrphan: z.ZodBoolean;
+    inDegree: z.ZodNumber;
+    outDegree: z.ZodNumber;
+    level: z.ZodNumber;
+    /** 节点所属的编程语言（多语言图合并时使用） */
+    language: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    isOrphan: boolean;
+    inDegree: number;
+    outDegree: number;
+    level: number;
+    language?: string | undefined;
+}, {
+    source: string;
+    isOrphan: boolean;
+    inDegree: number;
+    outDegree: number;
+    level: number;
+    language?: string | undefined;
+}>;
+export type ModuleNode = z.infer<typeof ModuleNodeSchema>;
+/** 模块间依赖边（depends-on 关系的 UnifiedEdge 派生） */
+export declare const ModuleEdgeSchema: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    isCircular: z.ZodBoolean;
+    importType: z.ZodEnum<["static", "dynamic", "type-only"]>;
+}, "strip", z.ZodTypeAny, {
+    importType: "static" | "dynamic" | "type-only";
+    from: string;
+    to: string;
+    isCircular: boolean;
+}, {
+    importType: "static" | "dynamic" | "type-only";
+    from: string;
+    to: string;
+    isCircular: boolean;
+}>;
+export type ModuleEdge = z.infer<typeof ModuleEdgeSchema>;
+/** 模块图强连通分量 */
+export declare const ModuleStronglyConnectedSetSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    modules: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    id: number;
+    modules: string[];
+}, {
+    id: number;
+    modules: string[];
+}>;
+export type ModuleStronglyConnectedSet = z.infer<typeof ModuleStronglyConnectedSetSchema>;
+/** 模块依赖图（UnifiedGraph 派生视图） */
+export declare const ModuleGraphSchema: z.ZodObject<{
+    projectRoot: z.ZodString;
+    modules: z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        isOrphan: z.ZodBoolean;
+        inDegree: z.ZodNumber;
+        outDegree: z.ZodNumber;
+        level: z.ZodNumber;
+        /** 节点所属的编程语言（多语言图合并时使用） */
+        language: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        source: string;
+        isOrphan: boolean;
+        inDegree: number;
+        outDegree: number;
+        level: number;
+        language?: string | undefined;
+    }, {
+        source: string;
+        isOrphan: boolean;
+        inDegree: number;
+        outDegree: number;
+        level: number;
+        language?: string | undefined;
+    }>, "many">;
+    edges: z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        isCircular: z.ZodBoolean;
+        importType: z.ZodEnum<["static", "dynamic", "type-only"]>;
+    }, "strip", z.ZodTypeAny, {
+        importType: "static" | "dynamic" | "type-only";
+        from: string;
+        to: string;
+        isCircular: boolean;
+    }, {
+        importType: "static" | "dynamic" | "type-only";
+        from: string;
+        to: string;
+        isCircular: boolean;
+    }>, "many">;
+    topologicalOrder: z.ZodArray<z.ZodString, "many">;
+    sccs: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        modules: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        id: number;
+        modules: string[];
+    }, {
+        id: number;
+        modules: string[];
+    }>, "many">;
+    totalModules: z.ZodNumber;
+    totalEdges: z.ZodNumber;
+    analyzedAt: z.ZodString;
+    mermaidSource: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    analyzedAt: string;
+    projectRoot: string;
+    edges: {
+        importType: "static" | "dynamic" | "type-only";
+        from: string;
+        to: string;
+        isCircular: boolean;
+    }[];
+    modules: {
+        source: string;
+        isOrphan: boolean;
+        inDegree: number;
+        outDegree: number;
+        level: number;
+        language?: string | undefined;
+    }[];
+    topologicalOrder: string[];
+    sccs: {
+        id: number;
+        modules: string[];
+    }[];
+    totalModules: number;
+    totalEdges: number;
+    mermaidSource: string;
+}, {
+    analyzedAt: string;
+    projectRoot: string;
+    edges: {
+        importType: "static" | "dynamic" | "type-only";
+        from: string;
+        to: string;
+        isCircular: boolean;
+    }[];
+    modules: {
+        source: string;
+        isOrphan: boolean;
+        inDegree: number;
+        outDegree: number;
+        level: number;
+        language?: string | undefined;
+    }[];
+    topologicalOrder: string[];
+    sccs: {
+        id: number;
+        modules: string[];
+    }[];
+    totalModules: number;
+    totalEdges: number;
+    mermaidSource: string;
+}>;
+export type ModuleGraph = z.infer<typeof ModuleGraphSchema>;
+/**
+ * 把 UnifiedGraph 派生成 ModuleGraph 视图。
+ *
+ * @param unified - 源 UnifiedGraph（必传，禁止从全局 cache 取）
+ * @param projectRoot - 项目根目录
+ * @returns ModuleGraph 视图
+ */
+export declare function deriveModuleGraph(unified: UnifiedGraph, projectRoot: string): ModuleGraph;
+/**
+ * 从 CodeSkeleton Map 一站式派生 ModuleGraph。
+ *
+ * 适用场景：调用方已自行解析好 imports[].resolvedPath（如 python-adapter），
+ * 直接喂给 buildUnifiedGraph 派生 module 节点 + depends-on 边。
+ *
+ * @param codeSkeletons - filePath（相对项目根）→ CodeSkeleton（含 resolvedPath）
+ * @param projectRoot - 项目根目录（绝对路径）
+ * @param language - 可选：给所有 module 节点统一打 language 标签
+ */
+export declare function buildModuleGraphFromCodeSkeletons(codeSkeletons: ReadonlyMap<string, CodeSkeleton>, projectRoot: string, language?: CodeSkeleton['language']): ModuleGraph;
+/**
+ * 创建空的 ModuleGraph（用于无文件或解析全失败的兜底场景）
+ */
+export declare function createEmptyModuleGraph(projectRoot: string): ModuleGraph;
+/**
+ * F183 修复 3（Codex W1 修正）：探测 monorepo per-package tsconfig。
+ * 仅扫 workspace 约定目录的直接子目录是否含 tsconfig.json——batch per-file nearest 会命中、
+ * 而 module-derivation root-only 会漏的子包配置信号。不再误判根级 tsconfig.base.json 等单包 config-split。
+ * fs 探针通过 io 参数注入，便于零全局 mock 单测（避免污染 scanFiles 的 Dirent 调用，Codex C-2）。
+ * 返回命中的子包相对路径（如 ['packages/core','apps/web']）。
+ */
+export declare function findMonorepoPackageTsConfigDirs(root: string, io?: {
+    readdirSync: (p: string) => Array<{
+        name: string;
+        isDirectory: () => boolean;
+    }>;
+    existsSync: (p: string) => boolean;
+}): string[];
+/**
+ * TS/JS 项目级 ModuleGraph 构建器（W1.4：取代 legacy src/graph/dependency-graph.ts）。
+ *
+ * 流程：
+ *   1. scanFiles 收集 TS/JS 源文件
+ *   2. analyzeFileInternal（ast-analyzer + import-resolver）产出 CodeSkeleton（含 resolvedPath）
+ *   3. buildUnifiedGraph 派生 calls + depends-on 边
+ *   4. deriveModuleGraph 派生 ModuleGraph 视图
+ */
+export interface BuildModuleGraphOptions {
+    /** 用于过滤分析文件的 Glob 模式（默认 '^src/'） */
+    includeOnly?: string;
+    /** 排除模式 */
+    excludePatterns?: string[];
+    /** tsconfig.json 路径 */
+    tsConfigPath?: string;
+}
+export declare class ProjectNotFoundError extends Error {
+    constructor(projectRoot: string);
+}
+/**
+ * 构建项目级 TS/JS ModuleGraph（取代 legacy buildGraph）。
+ *
+ * @param projectRoot - 项目根目录
+ * @param options - 构建选项
+ * @returns ModuleGraph
+ */
+export declare function buildModuleGraphForProject(projectRoot: string, options?: BuildModuleGraphOptions): Promise<ModuleGraph>;
+//# sourceMappingURL=module-derivation.d.ts.map

package/dist/knowledge-graph/module-derivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-derivation.d.ts","sourceRoot":"","sources":["../../src/knowledge-graph/module-derivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAkB/D,2DAA2D;AAC3D,eAAO,MAAM,sBAAsB,+CAA6C,CAAC;AACjF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,gDAAgD;AAChD,eAAO,MAAM,gBAAgB;;;;;;IAM3B,2BAA2B;;;;;;;;;;;;;;;;EAE3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;EAK3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAe;AACf,eAAO,MAAM,gCAAgC;;;;;;;;;EAG3C,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAE1F,+BAA+B;AAC/B,eAAO,MAAM,iBAAiB;;;;;;;;QAtB5B,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgC3B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAM5D;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,EACrB,WAAW,EAAE,MAAM,GAClB,WAAW,CAkHb;AAED;;;;;;;;;GASG;AACH,wBAAgB,iCAAiC,CAC/C,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,EAChD,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,YAAY,CAAC,UAAU,CAAC,GAClC,WAAW,CAmBb;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAYvE;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,MAAM,EACZ,EAAE,GAAE;IACF,WAAW,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,OAAO,CAAA;KAAE,CAAC,CAAC;IAChF,UAAU,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CAIpC,GACA,MAAM,EAAE,CAiBV;AAMD;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW;IACX,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,uBAAuB;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,WAAW,EAAE,MAAM;CAIhC;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,WAAW,CAAC,CA+GtB"}