spectra-cli 4.1.1 → 4.2.0

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,238 @@
+/**
+ * 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;
+/**
+ * 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;AAe/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;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,CAqGtB"}

package/dist/knowledge-graph/module-derivation.js

@@ -0,0 +1,418 @@
+/**
+ * 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 * as path from 'node:path';
+import * as fs from 'node:fs';
+import { ts } from 'ts-morph';
+import { detectSCCs, topologicalSort } from '../graph/topological-sort.js';
+import { renderModuleGraph } from '../graph/mermaid-renderer.js';
+import { buildUnifiedGraph } from './index.js';
+import { analyzeFileInternal } from '../core/ast-analyzer.js';
+import { scanFiles } from '../utils/file-scanner.js';
+import { LanguageAdapterRegistry } from '../adapters/language-adapter-registry.js';
+import { createLogger } from '../panoramic/utils/logger.js';
+const logger = createLogger('module-derivation');
+// ───────────────────────────────────────────────────────────
+// ModuleGraph schema
+// ───────────────────────────────────────────────────────────
+/** import 语义类型（commonjs-require 在 module 视图中归并到 static） */
+export const ModuleImportTypeSchema = z.enum(['static', 'dynamic', 'type-only']);
+/** 模块图节点（kind === 'module' 的 UnifiedNode 派生） */
+export const ModuleNodeSchema = z.object({
+    source: z.string().min(1),
+    isOrphan: z.boolean(),
+    inDegree: z.number().int().nonnegative(),
+    outDegree: z.number().int().nonnegative(),
+    level: z.number().int().nonnegative(),
+    /** 节点所属的编程语言（多语言图合并时使用） */
+    language: z.string().optional(),
+});
+/** 模块间依赖边（depends-on 关系的 UnifiedEdge 派生） */
+export const ModuleEdgeSchema = z.object({
+    from: z.string().min(1),
+    to: z.string().min(1),
+    isCircular: z.boolean(),
+    importType: ModuleImportTypeSchema,
+});
+/** 模块图强连通分量 */
+export const ModuleStronglyConnectedSetSchema = z.object({
+    id: z.number().int().nonnegative(),
+    modules: z.array(z.string().min(1)).min(1),
+});
+/** 模块依赖图（UnifiedGraph 派生视图） */
+export const ModuleGraphSchema = z.object({
+    projectRoot: z.string().min(1),
+    modules: z.array(ModuleNodeSchema),
+    edges: z.array(ModuleEdgeSchema),
+    topologicalOrder: z.array(z.string()),
+    sccs: z.array(ModuleStronglyConnectedSetSchema),
+    totalModules: z.number().int().nonnegative(),
+    totalEdges: z.number().int().nonnegative(),
+    analyzedAt: z.string().datetime(),
+    mermaidSource: z.string(),
+});
+// ───────────────────────────────────────────────────────────
+// 派生 API
+// ───────────────────────────────────────────────────────────
+/**
+ * 把 UnifiedGraph 派生成 ModuleGraph 视图。
+ *
+ * @param unified - 源 UnifiedGraph（必传，禁止从全局 cache 取）
+ * @param projectRoot - 项目根目录
+ * @returns ModuleGraph 视图
+ */
+export function deriveModuleGraph(unified, projectRoot) {
+    // ── 1. 过滤 module 节点 + depends-on 边 ──
+    const moduleIds = new Set();
+    for (const n of unified.nodes) {
+        if (n.kind === 'module')
+            moduleIds.add(n.id);
+    }
+    const dependsOnEdges = unified.edges.filter((e) => e.relation === 'depends-on');
+    // ── 2. 过滤掉指向非 module 节点的边 + 自引用 ──
+    const moduleEdges = dependsOnEdges.filter((e) => moduleIds.has(e.source) && moduleIds.has(e.target) && e.source !== e.target);
+    const edgeDrafts = moduleEdges.map((e) => ({
+        from: e.source,
+        to: e.target,
+        importType: parseImportType(e.metadata, e.evidence),
+    }));
+    // ── 4. 计算 inDegree / outDegree（线性扫描）──
+    const inDegrees = new Map();
+    const outDegrees = new Map();
+    for (const id of moduleIds) {
+        inDegrees.set(id, 0);
+        outDegrees.set(id, 0);
+    }
+    for (const e of edgeDrafts) {
+        outDegrees.set(e.from, (outDegrees.get(e.from) ?? 0) + 1);
+        inDegrees.set(e.to, (inDegrees.get(e.to) ?? 0) + 1);
+    }
+    // ── 5. 构造初始 ModuleNode 列表（level 暂置 0，topologicalSort 后回填）──
+    const nodes = [];
+    for (const id of moduleIds) {
+        const inDeg = inDegrees.get(id) ?? 0;
+        const outDeg = outDegrees.get(id) ?? 0;
+        nodes.push({
+            source: id,
+            isOrphan: inDeg === 0 && outDeg === 0,
+            inDegree: inDeg,
+            outDegree: outDeg,
+            level: 0,
+        });
+    }
+    // ── 6. 构造临时 ModuleGraph 供 detectSCCs / topologicalSort 消费 ──
+    const tempEdges = edgeDrafts.map((d) => ({
+        from: d.from,
+        to: d.to,
+        isCircular: false,
+        importType: d.importType,
+    }));
+    const tempGraph = {
+        projectRoot,
+        modules: nodes,
+        edges: tempEdges,
+        topologicalOrder: [],
+        sccs: [],
+        totalModules: nodes.length,
+        totalEdges: tempEdges.length,
+        analyzedAt: new Date().toISOString(),
+        mermaidSource: '',
+    };
+    // ── 7. SCC + topologicalSort（既有 Tarjan + Kahn 算法）──
+    const sccs = detectSCCs(tempGraph);
+    const sortResult = topologicalSort(tempGraph);
+    // ── 8. SCC 反查：构造 nodeId → sccIndex 映射；
+    //     仅当 source / target 在**同一** size>1 SCC 才标 isCircular = true。
+    const nodeToSccIndex = new Map();
+    for (let idx = 0; idx < sccs.length; idx++) {
+        const scc = sccs[idx];
+        if (scc.modules.length > 1) {
+            for (const m of scc.modules)
+                nodeToSccIndex.set(m, idx);
+        }
+    }
+    // ── 9. 重建最终 edges：填 isCircular（仅同一 SCC 内边标 true） ──
+    const finalEdges = edgeDrafts.map((d) => {
+        const fromScc = nodeToSccIndex.get(d.from);
+        const toScc = nodeToSccIndex.get(d.to);
+        const isCircular = fromScc !== undefined && fromScc === toScc;
+        return {
+            from: d.from,
+            to: d.to,
+            isCircular,
+            importType: d.importType,
+        };
+    });
+    // ── 10. 回填节点 level ──
+    for (const node of nodes) {
+        node.level = sortResult.levels.get(node.source) ?? 0;
+    }
+    // ── 11. 渲染 mermaid 源码 ──
+    const finalGraph = {
+        projectRoot,
+        modules: nodes,
+        edges: finalEdges,
+        topologicalOrder: sortResult.order,
+        sccs,
+        totalModules: nodes.length,
+        totalEdges: finalEdges.length,
+        analyzedAt: new Date().toISOString(),
+        mermaidSource: '',
+    };
+    finalGraph.mermaidSource = renderModuleGraph(finalGraph);
+    return finalGraph;
+}
+/**
+ * 从 CodeSkeleton Map 一站式派生 ModuleGraph。
+ *
+ * 适用场景：调用方已自行解析好 imports[].resolvedPath（如 python-adapter），
+ * 直接喂给 buildUnifiedGraph 派生 module 节点 + depends-on 边。
+ *
+ * @param codeSkeletons - filePath（相对项目根）→ CodeSkeleton（含 resolvedPath）
+ * @param projectRoot - 项目根目录（绝对路径）
+ * @param language - 可选：给所有 module 节点统一打 language 标签
+ */
+export function buildModuleGraphFromCodeSkeletons(codeSkeletons, projectRoot, language) {
+    if (codeSkeletons.size === 0) {
+        return createEmptyModuleGraph(projectRoot);
+    }
+    const unified = buildUnifiedGraph({ projectRoot, codeSkeletons });
+    const derived = deriveModuleGraph(unified, projectRoot);
+    if (language) {
+        for (const node of derived.modules) {
+            node.language = language;
+        }
+    }
+    else {
+        const registry = LanguageAdapterRegistry.getInstance();
+        for (const node of derived.modules) {
+            const adapter = registry.getAdapter(node.source);
+            if (adapter)
+                node.language = adapter.id;
+        }
+    }
+    return derived;
+}
+/**
+ * 创建空的 ModuleGraph（用于无文件或解析全失败的兜底场景）
+ */
+export function createEmptyModuleGraph(projectRoot) {
+    return {
+        projectRoot,
+        modules: [],
+        edges: [],
+        topologicalOrder: [],
+        sccs: [],
+        totalModules: 0,
+        totalEdges: 0,
+        analyzedAt: new Date().toISOString(),
+        mermaidSource: '',
+    };
+}
+export class ProjectNotFoundError extends Error {
+    constructor(projectRoot) {
+        super(`项目目录不存在: ${projectRoot}`);
+        this.name = 'ProjectNotFoundError';
+    }
+}
+/**
+ * 构建项目级 TS/JS ModuleGraph（取代 legacy buildGraph）。
+ *
+ * @param projectRoot - 项目根目录
+ * @param options - 构建选项
+ * @returns ModuleGraph
+ */
+export async function buildModuleGraphForProject(projectRoot, options = {}) {
+    const resolvedRoot = path.resolve(projectRoot);
+    if (!fs.existsSync(resolvedRoot)) {
+        throw new ProjectNotFoundError(projectRoot);
+    }
+    // ── 1. 扫描 TS/JS 源文件 ──
+    const registry = LanguageAdapterRegistry.getInstance();
+    const tsJsAdapter = registry.getAllAdapters().find((a) => a.id === 'ts-js');
+    const tsJsExts = tsJsAdapter
+        ? new Set(tsJsAdapter.extensions)
+        : new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts']);
+    const includeOnlyRe = options.includeOnly ? new RegExp(options.includeOnly) : /^src\//;
+    const srcDir = path.join(resolvedRoot, 'src');
+    const scanRoot = fs.existsSync(srcDir) ? srcDir : resolvedRoot;
+    let scanResult;
+    try {
+        scanResult = scanFiles(scanRoot, {
+            projectRoot: resolvedRoot,
+            extensions: tsJsExts,
+        });
+    }
+    catch (err) {
+        logger.warn(`scanFiles 失败，回退到空模块图: ${String(err)}`);
+        return createEmptyModuleGraph(resolvedRoot);
+    }
+    const testPattern = tsJsAdapter?.getTestPatterns().filePattern;
+    const tsJsFiles = [];
+    for (const relToScan of scanResult.files) {
+        const absFile = path.isAbsolute(relToScan) ? relToScan : path.join(scanRoot, relToScan);
+        const rel = path.relative(resolvedRoot, absFile).split(path.sep).join('/');
+        if (!includeOnlyRe.test(rel))
+            continue;
+        if (testPattern && testPattern.test(rel))
+            continue;
+        if (rel.includes('__tests__') || rel.includes('__mocks__'))
+            continue;
+        tsJsFiles.push(rel);
+    }
+    if (tsJsFiles.length === 0) {
+        return createEmptyModuleGraph(resolvedRoot);
+    }
+    // ── 2. 解析 tsconfig path alias + baseUrl ──
+    const tsConfigPath = options.tsConfigPath
+        ?? (fs.existsSync(path.join(resolvedRoot, 'tsconfig.json'))
+            ? path.join(resolvedRoot, 'tsconfig.json')
+            : undefined);
+    const tsConfigInfo = tsConfigPath ? loadTsconfigAliases(tsConfigPath) : undefined;
+    const pathAliases = tsConfigInfo?.paths;
+    const baseUrl = tsConfigInfo?.baseUrl;
+    // ── 3. 调用 ast-analyzer 提取每个文件的 CodeSkeleton ──
+    const codeSkeletons = new Map();
+    const ANALYZE_CONCURRENCY = 8;
+    const analyzerOpts = {
+        projectRoot: resolvedRoot,
+        ...(pathAliases ? { pathAliases } : {}),
+        ...(baseUrl ? { baseUrl } : {}),
+    };
+    for (let i = 0; i < tsJsFiles.length; i += ANALYZE_CONCURRENCY) {
+        const batch = tsJsFiles.slice(i, i + ANALYZE_CONCURRENCY);
+        const batchResults = await Promise.all(batch.map(async (rel) => {
+            const absPath = path.join(resolvedRoot, rel);
+            try {
+                const sk = await analyzeFileInternal(absPath, analyzerOpts);
+                return { rel, sk };
+            }
+            catch (err) {
+                logger.warn(`analyzeFile 失败（${rel}）: ${String(err)}`);
+                return { rel, sk: null };
+            }
+        }));
+        for (const { rel, sk } of batchResults) {
+            if (sk) {
+                codeSkeletons.set(rel, normalizeSkeletonPaths(sk, resolvedRoot, rel));
+            }
+        }
+    }
+    if (codeSkeletons.size === 0) {
+        return createEmptyModuleGraph(resolvedRoot);
+    }
+    // ── 4. 构建 UnifiedGraph ──
+    const unified = buildUnifiedGraph({
+        projectRoot: resolvedRoot,
+        codeSkeletons,
+    });
+    // ── 5. 派生 ModuleGraph + 给节点回填 language ──
+    const derived = deriveModuleGraph(unified, resolvedRoot);
+    for (const node of derived.modules) {
+        const adapter = registry.getAdapter(node.source);
+        if (adapter) {
+            node.language = adapter.id;
+        }
+    }
+    return derived;
+}
+// ───────────────────────────────────────────────────────────
+// 内部辅助
+// ───────────────────────────────────────────────────────────
+/**
+ * 从 UnifiedEdge 解析 importType。
+ *
+ * 优先级：
+ *   1. edge.metadata.importType（结构化字段）
+ *   2. evidence 前缀（旧产物兼容）
+ *   3. 默认 'static'
+ */
+function parseImportType(metadata, evidence) {
+    const metaType = metadata?.importType;
+    if (typeof metaType === 'string') {
+        if (metaType === 'type-only')
+            return 'type-only';
+        if (metaType === 'dynamic')
+            return 'dynamic';
+        if (metaType === 'commonjs-require')
+            return 'static';
+        if (metaType === 'static')
+            return 'static';
+    }
+    if (evidence) {
+        if (evidence.startsWith('type-only:'))
+            return 'type-only';
+        if (evidence.startsWith('dynamic:'))
+            return 'dynamic';
+        if (evidence.startsWith('commonjs-require:'))
+            return 'static';
+        if (evidence.startsWith('static:'))
+            return 'static';
+    }
+    return 'static';
+}
+/**
+ * 把 CodeSkeleton 中的 imports[].resolvedPath 从绝对路径归一化为相对路径，
+ * 使其与 codeSkeletons Map 的 key（相对路径）对齐。
+ */
+function normalizeSkeletonPaths(sk, projectRoot, callerRel) {
+    const newImports = sk.imports.map((imp) => {
+        if (!imp.resolvedPath)
+            return imp;
+        const rel = path.relative(projectRoot, imp.resolvedPath).split(path.sep).join('/');
+        return { ...imp, resolvedPath: rel.startsWith('..') ? imp.resolvedPath : rel };
+    });
+    return { ...sk, filePath: callerRel, imports: newImports };
+}
+/**
+ * 解析 tsconfig.json（用 ts.parseJsonConfigFileContent，自动处理 extends 链 / baseUrl / paths）。
+ *
+ * 失败时返回 undefined（不阻断，按未配置 alias 处理）。
+ */
+function loadTsconfigAliases(tsconfigPath) {
+    try {
+        const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+        if (configFile.error || !configFile.config) {
+            return undefined;
+        }
+        const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path.dirname(tsconfigPath));
+        const compilerOptions = parsedConfig.options;
+        const out = {};
+        if (compilerOptions.baseUrl) {
+            out.baseUrl = compilerOptions.baseUrl;
+        }
+        if (compilerOptions.paths) {
+            const paths = {};
+            for (const [k, v] of Object.entries(compilerOptions.paths)) {
+                if (Array.isArray(v) && v.length > 0) {
+                    const baseForPaths = compilerOptions.baseUrl ?? path.dirname(tsconfigPath);
+                    paths[k] = v
+                        .filter((s) => typeof s === 'string')
+                        .map((s) => (path.isAbsolute(s) ? s : path.resolve(baseForPaths, s)));
+                }
+            }
+            if (Object.keys(paths).length > 0) {
+                out.paths = paths;
+            }
+        }
+        return Object.keys(out).length > 0 ? out : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=module-derivation.js.map