spectra-cli 4.2.0 → 4.3.0

package/dist/core/import-resolver.js

@@ -1,35 +1,58 @@
 /**
- * import-resolver.ts — TS/JS import specifier 解析（Feature 156 W1.0 / CRITICAL-1 关闭）
+ * import-resolver.ts — TS/JS import specifier 单一权威解析（Feature 181 收口）
  *
- * 背景：
- *   ast-analyzer.ts:376 与 tree-sitter-fallback.ts / typescript-mapper.ts 在提取 import 时
- *   把 `resolvedPath` 置为 null（"不解析路径，性能优化"）。删除 dependency-cruiser 后，
- *   knowledge-graph/index.ts 的 deriveImportEdges 跳过 `resolvedPath=null` 的 import，
- *   导致 TS/JS depends-on 边数为 0。
- *
- * 本模块提供两个核心能力：
- *   1. resolveTsJsImport — specifier → 绝对路径（无法解析返回 null）
- *      - 覆盖 4 类 import：static / dynamic / commonjs-require / type-only（路径解析逻辑相同）
- *      - 支持相对路径、扩展名补全、index.{ts,js} fallback、tsconfig path alias
- *      - node_modules / 外部包：返回 null（不解析外部依赖）
- *   2. detectImportType — 从 ts-morph 节点派生 ImportType 字面量
- *      - 用于 CodeSkeleton.imports[].importType + ModuleEdge.importType
+ * 背景（Feature 181 单一权威收口）：
+ *   历史上 `core/import-resolver.ts` 与 `knowledge-graph/import-resolver.ts` 各有一份
+ *   `resolveTsJsImport`，行为分叉（core 返回绝对路径无 projectRoot 守卫 + ESM ext map；
+ *   kg 返回相对 POSIX + kind + isInsideProjectRoot 守卫）。两者经 AST 路径
+ *   （ast-analyzer / tree-sitter-*）与 batch 路径（collect / module-derivation）都进 graph.json。
+ *   本模块收口为唯一权威实现，合并两侧能力：
+ *     - 相对解析：ESM ext map（`./foo.js`→`foo.ts`）+ 直接命中 + .mjs/.cjs（源自 core）
+ *     - alias/baseUrl：tsconfig paths（最长前缀 + 多候选 + baseUrl 叠加，TS 官方语义）
+ *     - projectRoot 边界守卫（防图污染，源自 kg；relative / disk-absolute 分支启用）
+ *     - kind 分类 + external/unresolved 区分 + .json/.d.ts → external
  *
  * 设计约束：
- *   - 不引入新 npm 依赖（仅用 node:fs / node:path）
- *   - 不抛异常（无法解析返回 null + 静默忽略）
- *   - 跨平台：path.resolve / path.posix 兼容 win32 + posix
+ *   - 纯 node:fs / node:path（+ typescript 仅用于 tsconfig 解析，含 extends 链）
+ *   - 不抛异常（无法解析返回 { resolvedPath: null, kind: 'unresolved' }）
+ *   - 跨平台：resolvedPath 输出统一为相对 projectRoot 的 POSIX 路径；
+ *     projectRoot 为空（独立 AST 调用）时返回绝对路径且跳过守卫（保持历史 core 行为）
+ *
+ * 注：Python import 解析（resolvePythonImport）不在本次收口范围，仍在
+ *   knowledge-graph/import-resolver.ts；其依赖的 ResolveResult / toPosix / isInsideProjectRoot
+ *   由本模块导出供其下行 import（knowledge-graph → core，层级方向干净）。
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { Node, SyntaxKind } from 'ts-morph';
-const DEFAULT_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
-const DEFAULT_INDEX_FILES = ['index.ts', 'index.tsx', 'index.js', 'index.jsx'];
+// 复用 ts-morph 再导出的 typescript 命名空间（避免新增对 'typescript' 的直接运行时依赖；
+// ts-morph 已是本仓运行时依赖）
+import { ts } from 'ts-morph';
+import { createLogger } from '../panoramic/utils/logger.js';
+// F183 修复 2：buildTsConfigContext 失败时不再静默——warn 出 configPath + error 摘要。
+const logger = createLogger('import-resolver');
+// 仅缓存已 warn 的 configPath 做 emission 限频（monorepo 同一损坏 tsconfig 会被每个
+// import-resolve 循环触发，造成日志洪泛）。注意：仅限频 warn，绝不跳过解析——
+// buildTsConfigContext 始终尝试解析，失败仍 return null。
+const warnedConfigPaths = new Set();
+/** 同一 configPath 仅发一次 warn（emission 限频，不影响解析）。 */
+function warnTsConfigFailureOnce(configPath, errorSummary) {
+    if (warnedConfigPaths.has(configPath))
+        return;
+    logger.warn(`[import-resolver] buildTsConfigContext 失败（${configPath}）：${errorSummary}`);
+    warnedConfigPaths.add(configPath);
+}
+// ───────────────────────────────────────────────────────────
+// 常量
+// ───────────────────────────────────────────────────────────
+/** TS/JS 候补扩展名顺序（含 .mjs/.cjs，源自历史 core 实现） */
+const TS_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
+/** index 文件名顺序 */
+const TS_INDEX_FILES = ['index.ts', 'index.tsx', 'index.js', 'index.jsx'];
+/** alias-like 前缀列表（C-2）：以这些前缀开头的 moduleSpec 无 paths 命中时返回 unresolved */
+const ALIAS_PREFIXES = ['~/', '#/', '$/'];
 /**
- * Feature 156 W1.0 v2 / CRIT-1：TypeScript ESM 惯例下，`import './foo.js'` 实际指向 `./foo.ts`。
- *
- * 当 specifier 以 JS 扩展名结尾时，先尝试对应的 TS 扩展名候选；命中则返回，否则 fallback
- * 到原扩展名继续走标准解析流程（保持非 TS 项目的兼容性）。
+ * TypeScript ESM 惯例：`import './foo.js'` 实际指向 `./foo.ts`（Feature 156 CRIT-1）。
+ * specifier 以 JS 扩展名结尾时，先尝试对应 TS 扩展名候选；命中即返回，否则 fallback 标准解析。
  */
 const ESM_TS_EXT_MAP = {
     '.js': ['.ts', '.tsx'],
@@ -38,107 +61,65 @@ const ESM_TS_EXT_MAP = {
     '.cjs': ['.cts'],
 };
 // ───────────────────────────────────────────────────────────
-// resolveTsJsImport — specifier → 绝对路径
+// 共享辅助（导出供 knowledge-graph Python resolver 下行复用）
 // ───────────────────────────────────────────────────────────
+/** 将路径转换为 POSIX 格式（确保跨平台 resolvedPath 始终用 '/' 分隔符）。 */
+export function toPosix(p) {
+    return p.split(path.sep).join('/');
+}
 /**
- * 把 TS/JS import specifier 解析为绝对文件路径。
+ * 判断 candidate 路径是否严格在 projectRoot 子树内（C-5 + N-2）。
  *
- * 解析顺序：
- *   1. node 内置模块（如 'fs'）/ npm 包（不带相对前缀且无 alias 命中）→ null
- *   2. tsconfig path alias 命中 → 替换前缀后按相对路径流程解析
- *   3. 相对路径（`./xxx` / `../xxx` / `/xxx`）→ 基于 fromFile 拼接
- *
- * 文件存在性检查：
- *   - 直接命中（specifier 已含 .ts/.js 等扩展名）
- *   - 扩展名补全（依次尝试 options.extensions）
- *   - 目录 + index 文件 fallback（如果 specifier 指向目录）
- *
- * 失败时静默返回 null，不抛异常（FR-28 best-effort 语义）。
- *
- * @param specifier - import 字符串字面量（如 './foo'）
- * @param fromFile - 发起 import 的源文件绝对路径
- * @param projectRoot - 项目根目录（用于 alias 相对路径解析；可为空字符串，alias 失效）
- * @param options - 扩展名 / index 文件 / alias 配置
- * @returns 解析到的绝对路径；外部模块或解析失败返回 null
+ * 用 path.relative 逐 component 检查第一段是否为 '..'，避免字典序误判（/proj vs /projection）。
+ * candidate === projectRoot 返回 false（projectRoot 自身不算"在子树内"）。
  */
-export function resolveTsJsImport(specifier, fromFile, projectRoot, options) {
-    if (!specifier || typeof specifier !== 'string')
-        return null;
-    const extensions = options?.extensions ?? DEFAULT_EXTENSIONS;
-    const indexFiles = options?.indexFiles ?? DEFAULT_INDEX_FILES;
-    // 1. node 内置模块（'fs', 'path', 'node:fs'）→ null（不解析外部依赖）
-    if (specifier.startsWith('node:'))
-        return null;
-    // 2. 尝试 tsconfig path alias（多候选最长前缀匹配，CRIT-2 v2）
-    const aliasCandidates = resolveAliasCandidates(specifier, projectRoot, options?.pathAliases);
-    for (const cand of aliasCandidates) {
-        const hit = tryFilePathVariants(cand, extensions, indexFiles);
-        if (hit)
-            return hit;
-    }
-    // 3. 相对路径前缀（'.', '..', '/'）才进入文件系统解析
-    if (specifier.startsWith('.') || specifier.startsWith('/')) {
-        const fromDir = path.dirname(path.resolve(fromFile));
-        const baseSpecifier = path.resolve(fromDir, specifier);
-        return tryFilePathVariants(baseSpecifier, extensions, indexFiles);
-    }
-    // 4. baseUrl fallback（CRIT-2 v2）：未命中 alias / 非相对路径，
-    //    若 baseUrl 提供，则按非相对 module 解析（baseUrl + specifier）
-    if (options?.baseUrl) {
-        const baseRel = path.resolve(options.baseUrl, specifier);
-        const hit = tryFilePathVariants(baseRel, extensions, indexFiles);
-        if (hit)
-            return hit;
-    }
-    // 5. 不带相对前缀、无 alias / baseUrl 命中：视为 npm 包 / 外部模块 → null
-    return null;
+export function isInsideProjectRoot(candidate, projectRoot) {
+    const rel = path.relative(projectRoot, candidate);
+    if (rel.length === 0)
+        return false; // candidate === projectRoot
+    if (path.isAbsolute(rel))
+        return false; // 跨盘符（Windows）
+    const firstSeg = rel.split(path.sep)[0];
+    if (firstSeg === '..')
+        return false;
+    return true;
 }
 /**
- * 尝试 alias 替换，返回所有候选绝对路径列表（CRIT-2 v2）。
- *
- * 改进：
- *   1. 支持单值与多候选数组（`Record<string, string | readonly string[]>`）
- *   2. 最长前缀匹配（`@app/utils/foo` 命中 `@app/utils/*` 优先于 `@app/*`）
- *   3. 一个 alias 可对应多个目标，全部作为候选返回（调用方逐个 tryFilePathVariants）
- *
- * @returns 候选绝对路径列表（按优先级排序：最长前缀优先 + 配置顺序）；未命中返回空数组
+ * 判断路径是否指向非源文件目标（W-1）。
+ * .json 和 .d.ts 文件不进入 callSites graph，返回 external。
  */
-function resolveAliasCandidates(specifier, projectRoot, pathAliases) {
-    if (!pathAliases || !projectRoot)
-        return [];
-    // 收集所有命中的 alias，按 prefix 长度降序（最长前缀优先）
-    const matched = [];
-    for (const [aliasPattern, targetValue] of Object.entries(pathAliases)) {
-        const aliasPrefix = aliasPattern.replace(/\*$/, '');
-        if (!specifier.startsWith(aliasPrefix))
-            continue;
-        const remainder = specifier.slice(aliasPrefix.length);
-        const targets = Array.isArray(targetValue) ? targetValue : [targetValue];
-        matched.push({ prefixLen: aliasPrefix.length, remainder, targets });
+export function isNonSourceTarget(p) {
+    return p.endsWith('.json') || p.endsWith('.d.ts');
+}
+// ───────────────────────────────────────────────────────────
+// 内部：文件候选尝试（合并 core ESM ext map + 直接命中 + 扩展名 + index）
+// ───────────────────────────────────────────────────────────
+function existsAndIsFile(p) {
+    try {
+        return fs.statSync(p).isFile();
     }
-    if (matched.length === 0)
-        return [];
-    matched.sort((a, b) => b.prefixLen - a.prefixLen);
-    const candidates = [];
-    for (const m of matched) {
-        for (const target of m.targets) {
-            const targetPrefix = target.replace(/\*$/, '');
-            const joined = path.posix.join(targetPrefix, m.remainder);
-            // target 可能已是绝对路径（ts.parseJsonConfigFileContent 解析后）；保留绝对路径不再 join projectRoot
-            candidates.push(path.isAbsolute(joined) ? joined : path.resolve(projectRoot, joined));
-        }
+    catch {
+        return false;
+    }
+}
+function existsAndIsDir(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
     }
-    return candidates;
 }
 /**
- * 给定一个 base 路径，依次尝试：
- *   1. base 直接存在（含扩展名）
- *   2. base + 扩展名（.ts, .tsx, .js, ...）
- *   3. base / index.ts、base / index.js 等
+ * 给定 base 路径，依次尝试（顺序严格复刻历史 core，护 graph.json byte-identical）：
+ *   1. ESM TS ext map（若 base 以 JS 扩展名结尾，先试 .ts/.tsx 等 TS 候选）
+ *   2. base 直接命中（已含扩展名）
+ *   3. base + 扩展名（.ts → .cjs）
+ *   4. base/index.{ts,tsx,js,jsx}
+ * @returns 命中的绝对路径；否则 null
  */
-function tryFilePathVariants(base, extensions, indexFiles) {
-    // CRIT-1：TS ESM 惯例 — 若 base 以 JS 扩展名结尾，先尝试 TS 候选（如 foo.js → foo.ts）
-    // 命中则直接返回；不命中再 fallback 到原 base 走后续标准解析流程
+function tryFilePathVariants(base) {
+    // 1. ESM TS ext map（如 foo.js → foo.ts）
     const sourceExt = path.extname(base);
     const tsCandidatesExts = ESM_TS_EXT_MAP[sourceExt];
     if (tsCandidatesExts) {
@@ -148,20 +129,19 @@ function tryFilePathVariants(base, extensions, indexFiles) {
             if (existsAndIsFile(tsCandidate))
                 return tsCandidate;
         }
-        // TS 候选未命中：继续 fallback 到下方标准解析（直接命中 / 扩展名补全 / index）
     }
-    // 1. 直接命中
+    // 2. 直接命中
     if (existsAndIsFile(base))
         return base;
-    // 2. 扩展名补全
-    for (const ext of extensions) {
+    // 3. 扩展名补全
+    for (const ext of TS_EXTENSIONS) {
         const candidate = base + ext;
         if (existsAndIsFile(candidate))
             return candidate;
     }
-    // 3. 目录 + index 文件
+    // 4. 目录 + index 文件
     if (existsAndIsDir(base)) {
-        for (const idxFile of indexFiles) {
+        for (const idxFile of TS_INDEX_FILES) {
             const candidate = path.join(base, idxFile);
             if (existsAndIsFile(candidate))
                 return candidate;
@@ -169,105 +149,266 @@ function tryFilePathVariants(base, extensions, indexFiles) {
     }
     return null;
 }
-function existsAndIsFile(p) {
-    try {
-        const st = fs.statSync(p);
-        return st.isFile();
+/**
+ * 把命中绝对路径归一为 ResolveResult。
+ * projectRoot 为真：相对 POSIX；projectRoot 为空：保留绝对路径（历史 core 独立调用行为）。
+ */
+function makeHit(absHit, projectRoot, kind) {
+    return {
+        resolvedPath: projectRoot ? toPosix(path.relative(projectRoot, absHit)) : absHit,
+        kind,
+    };
+}
+// ───────────────────────────────────────────────────────────
+// Public API — resolveTsJsImport（单一权威）
+// ───────────────────────────────────────────────────────────
+/**
+ * 解析 TypeScript/JavaScript import 路径（单一权威实现，Feature 181）。
+ *
+ * 解析顺序：
+ *   1. node: 内置 → external
+ *   2. 磁盘绝对路径（'/' 前缀）→ 文件候选 + projectRoot 守卫
+ *   3. 相对路径（'./' '../'）→ 文件候选 + projectRoot 守卫；.json/.d.ts → external
+ *   4. 非相对：tsconfig paths alias（最长前缀 + 多候选 + baseUrl 叠加）→ baseUrl 解析 → external/unresolved
+ *
+ * 守卫策略（逐分支复刻历史 kg）：relative / disk-absolute 分支启用 isInsideProjectRoot
+ * （仅 projectRoot 为真时）；paths-alias / baseUrl 分支不加守卫（保持 alias 语义）。
+ *
+ * @param moduleSpec      - import 说明符（如 './engine'、'~/utils'、'express'）
+ * @param callerFile      - 调用方文件的绝对路径
+ * @param projectRoot     - 项目根目录绝对路径（空字符串：返回绝对路径 + 跳过守卫）
+ * @param tsConfigContext - tsconfig 解析上下文（null/undefined：仅走相对/绝对路径）
+ * @returns ResolveResult（失败返回 { resolvedPath: null, kind: 'unresolved' }，不抛异常）
+ */
+export function resolveTsJsImport(moduleSpec, callerFile, projectRoot, tsConfigContext) {
+    if (!moduleSpec || typeof moduleSpec !== 'string') {
+        return { resolvedPath: null, kind: 'unresolved' };
     }
-    catch {
-        return false;
+    // 1. node 内置模块 → external（不解析外部依赖）
+    if (moduleSpec.startsWith('node:')) {
+        return { resolvedPath: null, kind: 'external' };
     }
-}
-function existsAndIsDir(p) {
-    try {
-        const st = fs.statSync(p);
-        return st.isDirectory();
+    // 2. 磁盘绝对路径（罕见）
+    if (moduleSpec.startsWith('/')) {
+        const hit = tryFilePathVariants(moduleSpec);
+        if (hit) {
+            // 守卫：候选必须在 projectRoot 内（仅 projectRoot 为真时启用）
+            if (projectRoot && !isInsideProjectRoot(hit, projectRoot)) {
+                return { resolvedPath: null, kind: 'unresolved' };
+            }
+            return makeHit(hit, projectRoot, 'absolute');
+        }
+        return { resolvedPath: null, kind: 'unresolved' };
     }
-    catch {
-        return false;
+    // 3. 相对路径（./ 或 ../）
+    if (moduleSpec.startsWith('./') || moduleSpec.startsWith('../') || moduleSpec.startsWith('.')) {
+        // W-1：moduleSpec 自身已带 .json / .d.ts 后缀 → external
+        if (isNonSourceTarget(moduleSpec)) {
+            return { resolvedPath: null, kind: 'external' };
+        }
+        const base = path.resolve(path.dirname(callerFile), moduleSpec);
+        const hit = tryFilePathVariants(base);
+        if (hit) {
+            if (projectRoot && !isInsideProjectRoot(hit, projectRoot)) {
+                return { resolvedPath: null, kind: 'unresolved' };
+            }
+            // 命中 .json / .d.ts（如 base 无扩展名却命中同名 .d.ts）双保险 external
+            if (isNonSourceTarget(hit)) {
+                return { resolvedPath: null, kind: 'external' };
+            }
+            return makeHit(hit, projectRoot, 'relative');
+        }
+        // 候补失败但 base 本身指向 .json / .d.ts → external
+        if (isNonSourceTarget(base)) {
+            return { resolvedPath: null, kind: 'external' };
+        }
+        return { resolvedPath: null, kind: 'unresolved' };
+    }
+    // 4. 非相对路径：先 paths alias，再 baseUrl，再判定 external/unresolved
+    if (tsConfigContext) {
+        const aliasHit = resolvePathsAlias(moduleSpec, projectRoot, tsConfigContext);
+        if (aliasHit)
+            return aliasHit;
+        // baseUrl 解析（baseUrl 为字符串时）
+        if (typeof tsConfigContext.baseUrl === 'string') {
+            const absBase = path.resolve(tsConfigContext.configDir, tsConfigContext.baseUrl, moduleSpec);
+            const hit = tryFilePathVariants(absBase);
+            if (hit) {
+                return makeHit(hit, projectRoot, 'absolute');
+            }
+        }
+    }
+    // C-2：区分 alias-like（unresolved）与 bare npm package（external）
+    if (ALIAS_PREFIXES.some((p) => moduleSpec.startsWith(p)) || moduleSpec.startsWith('@/')) {
+        return { resolvedPath: null, kind: 'unresolved' };
+    }
+    // 合法 npm 包判定
+    const firstSeg = moduleSpec.split('/')[0] ?? '';
+    if (firstSeg.startsWith('@')) {
+        // scoped 包形如 @org/lib
+        return { resolvedPath: null, kind: 'external' };
+    }
+    if (/^[a-z0-9][a-z0-9-_.]*$/.test(firstSeg)) {
+        return { resolvedPath: null, kind: 'external' };
     }
+    // 含 '/' 但首段不是合法 npm 包名 → alias-like 配置缺失
+    return { resolvedPath: null, kind: 'unresolved' };
+}
+/**
+ * AST 消费方便捷封装：解析并归一为**绝对路径**。
+ *
+ * ast-analyzer / tree-sitter-analyzer / tree-sitter-fallback 三处历史上把
+ * resolvedPath 以绝对路径写入 CodeSkeleton.imports[]（module-derivation.normalizeSkeletonPaths
+ * 期望绝对输入再相对化；collect EC-10 亦绝对）。本封装保持该形态：
+ *   - projectRoot 为真：把权威 resolver 的相对 POSIX 结果 path.resolve 回绝对
+ *   - projectRoot 为空：权威 resolver 已返回绝对路径，原样返回
+ * external/unresolved（resolvedPath=null）统一返回 null（与历史 core string|null 语义一致）。
+ */
+export function resolveTsJsImportToAbsolute(moduleSpec, callerFile, projectRoot, tsConfigContext) {
+    const r = resolveTsJsImport(moduleSpec, callerFile, projectRoot, tsConfigContext);
+    if (!r.resolvedPath)
+        return null;
+    return path.isAbsolute(r.resolvedPath)
+        ? r.resolvedPath
+        : path.resolve(projectRoot, r.resolvedPath);
 }
-// ───────────────────────────────────────────────────────────
-// detectImportType — 从 ts-morph 节点派生 ImportType
-// ───────────────────────────────────────────────────────────
 /**
- * 从 ts-morph 节点派生 ImportType 字面量（FR-28 / plan §2.5）。
+ * tsconfig paths alias 解析（最长前缀 + 多候选 + baseUrl 叠加，TS 官方语义）。
  *
- * 判断规则：
- *   1. 'type-only'：ImportDeclaration 且 isTypeOnly()=true
- *   2. 'dynamic'：CallExpression 且 callee 为 import 关键字（SyntaxKind.ImportKeyword）
- *   3. 'commonjs-require'：CallExpression 且 callee 文本 = "require"
- *   4. 'static'：默认（标准 ImportDeclaration）
+ * 合并历史两侧：
+ *   - 最长前缀匹配（core：`@app/utils/*` 优先于 `@app/*`；精确 key 因 prefixLen 最长天然居首）
+ *   - 多候选数组逐个尝试（core + kg）
+ *   - replacement 叠加 baseUrl：path.resolve(configDir, baseUrl ?? '.', replacement)（kg C-3）
+ *   - 文件候选用统一 tryFilePathVariants（含 ESM ext map / .mjs.cjs / index）
  *
- * 注：tree-sitter / 正则降级路径不调用此函数，由调用点直接根据 query 节点类型映射
- * （tree-sitter typescript-mapper 仅处理 import_statement，importType 始终为 'static' 或 'type-only'，
- * 由 isTypeOnly 字段派生）。
+ * @returns 命中的 ResolveResult（kind='paths-alias'）；未命中返回 null
  */
-export function detectImportType(node) {
-    if (Node.isImportDeclaration(node)) {
-        return detectImportDeclarationType(node);
+function resolvePathsAlias(moduleSpec, projectRoot, ctx) {
+    // 收集所有命中 alias，排序规则（TS 官方语义）：
+    //   1. 最长前缀优先（`@app/utils/*` 胜过 `@app/*`）
+    //   2. 同前缀长度时精确 key（无 wildcard）优先于 wildcard（`react` 胜过 `react*`）
+    const matched = [];
+    for (const [pattern, replacements] of ctx.paths) {
+        const tail = matchPathsPattern(moduleSpec, pattern);
+        if (tail === null)
+            continue;
+        const isWildcard = pattern.includes('*');
+        const prefixLen = isWildcard ? pattern.indexOf('*') : pattern.length;
+        matched.push({ prefixLen, isWildcard, tail, replacements });
     }
-    if (Node.isCallExpression(node)) {
-        return detectCallExpressionImportType(node);
+    if (matched.length === 0)
+        return null;
+    matched.sort((a, b) => {
+        if (b.prefixLen !== a.prefixLen)
+            return b.prefixLen - a.prefixLen;
+        return (a.isWildcard ? 1 : 0) - (b.isWildcard ? 1 : 0); // 同前缀长度：exact 优先
+    });
+    const baseUrl = typeof ctx.baseUrl === 'string' ? ctx.baseUrl : '.';
+    for (const m of matched) {
+        for (const replacement of m.replacements) {
+            const resolved = replacement.includes('*') ? replacement.replace('*', m.tail) : replacement;
+            const absBase = path.resolve(ctx.configDir, baseUrl, resolved);
+            const hit = tryFilePathVariants(absBase);
+            if (hit) {
+                return makeHit(hit, projectRoot, 'paths-alias');
+            }
+        }
     }
-    // 兜底：未识别节点视为 static（保持非破坏性行为）
-    return 'static';
+    return null;
 }
-function detectImportDeclarationType(decl) {
-    // (a) 顶层 `import type` 关键字
-    if (decl.isTypeOnly())
-        return 'type-only';
-    // WARN-1 修订：混合 import（含 default 或 namespace）即使 named import 全是 type-only，
-    // 也保留 'static' 语义 —— default / namespace 在运行时仍是值导入。
-    // 仅当 (a) 没有 default + 没有 namespace + (b) 有 named import 且全为 type-only 才归 type-only。
-    const hasDefaultImport = decl.getDefaultImport() != null;
-    const hasNamespaceImport = decl.getNamespaceImport() != null;
-    if (hasDefaultImport || hasNamespaceImport) {
-        return 'static';
-    }
-    const named = decl.getNamedImports();
-    if (named.length > 0 && named.every((n) => n.isTypeOnly())) {
-        return 'type-only';
+/**
+ * 匹配 tsconfig paths pattern（精确 key + wildcard）。
+ * @returns null（不匹配），或 wildcard 截取的尾缀（精确 key 时为 ''）
+ */
+function matchPathsPattern(moduleSpec, pattern) {
+    if (pattern.includes('*')) {
+        const starIdx = pattern.indexOf('*');
+        const prefix = pattern.slice(0, starIdx);
+        const suffix = pattern.slice(starIdx + 1);
+        if (moduleSpec.startsWith(prefix) && moduleSpec.endsWith(suffix) &&
+            moduleSpec.length >= prefix.length + suffix.length) {
+            return moduleSpec.slice(prefix.length, moduleSpec.length - suffix.length);
+        }
+        return null;
     }
-    return 'static';
+    return moduleSpec === pattern ? '' : null;
 }
-function detectCallExpressionImportType(call) {
-    if (!Node.isCallExpression(call))
-        return 'static';
-    const expr = call.getExpression();
-    // 动态 import：callee 为 ImportKeyword
-    if (expr.getKind() === SyntaxKind.ImportKeyword)
-        return 'dynamic';
-    // CommonJS require：callee 为 Identifier("require")
-    if (Node.isIdentifier(expr) && expr.getText() === 'require')
-        return 'commonjs-require';
-    return 'static';
+// ───────────────────────────────────────────────────────────
+// Public API — tsconfig loader（单一实现：ts.parseJsonConfigFileContent，含 extends 链）
+// ───────────────────────────────────────────────────────────
+/**
+ * 从 filePath 向上查找最近的 tsconfig.json（monorepo-aware）。
+ *
+ * 上溯范围：从 path.dirname(filePath) 向上，直到 projectRoot 边界（含 projectRoot 本身）。
+ * 越过 projectRoot 停止，不抛异常。
+ *
+ * @returns tsconfig.json 的绝对路径；未找到返回 null
+ */
+export function findNearestTsConfig(filePath, projectRoot) {
+    let dir = path.dirname(filePath);
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        // 边界检查先于 fs 操作（C-3：避免越界路径误读）
+        if (dir !== projectRoot && !isInsideProjectRoot(dir, projectRoot)) {
+            break;
+        }
+        const candidate = path.join(dir, 'tsconfig.json');
+        if (fs.existsSync(candidate)) {
+            return candidate;
+        }
+        if (dir === projectRoot)
+            break;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // 文件系统根
+        dir = parent;
+    }
+    return null;
 }
 /**
- * 给定一个文件的 imports 列表，逐项调用 resolveTsJsImport 填充 resolvedPath。
+ * 解析 tsconfig.json 为 TsConfigResolutionContext（单一 loader，ts API 处理 extends 链）。
+ *
+ * 用 ts.readConfigFile + ts.parseJsonConfigFileContent：
+ *   - 自动处理 extends 链（优于历史 kg 手写 JSON.parse 的 YAGNI 无 extends）
+ *   - baseUrl 解析为绝对路径（alias 算法 path.resolve 正确覆盖 configDir）
+ *   - paths 保留原始相对字符串（由 alias 算法做唯一一次 resolve，避免双重 resolve）
  *
- * 复用动机：ast-analyzer / tree-sitter-analyzer / tree-sitter-fallback 三处都需要
- * 在 imports 收集完毕后批量 resolve；提取此 helper 避免重复实现。
+ * 失败时返回 null（不抛异常，按未配置 alias 处理）。
  *
- * - importType 默认从 `isTypeOnly` 派生（type-only / static）；ts-morph 路径可在调用前覆盖。
- * - 仅处理 TS/JS 语言；其他语言（Python / Go / Java）应跳过此函数。
+ * @param configPath - tsconfig.json 的绝对路径（由 findNearestTsConfig / 调用方提供）
  */
-export function resolveImportsForFile(imports, fromFile, projectRoot, options) {
-    return imports.map((imp) => {
-        // 已 resolve 过则保留（如 ts-morph 路径已在 ast-analyzer 中显式调用）
-        const alreadyResolved = imp.resolvedPath != null && imp.resolvedPath !== '';
-        const resolvedPath = alreadyResolved
-            ? imp.resolvedPath
-            : resolveTsJsImport(imp.moduleSpecifier, fromFile, projectRoot, options);
-        // 如果未显式设置 importType，从 isTypeOnly 派生
-        const inferredImportType = imp.isTypeOnly ? 'type-only' : 'static';
-        return {
-            ...imp,
-            resolvedPath: resolvedPath ?? null,
-            // ImportReferenceSchema 已扩展 importType?: ImportType（v152 W1.0）
-            importType: imp.importType
-                ?? inferredImportType,
-        };
-    });
+export function buildTsConfigContext(configPath) {
+    try {
+        const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+        if (configFile.error || !configFile.config) {
+            // 解析失败仍 return null（行为不变），但不再静默——首次为该 configPath 发一次 warn
+            const errorSummary = configFile.error
+                ? ts.flattenDiagnosticMessageText(configFile.error.messageText, ' ')
+                : 'config 为空';
+            warnTsConfigFailureOnce(configPath, errorSummary);
+            return null;
+        }
+        const configDir = path.dirname(configPath);
+        const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, configDir);
+        const compilerOptions = parsed.options;
+        const baseUrl = typeof compilerOptions.baseUrl === 'string' ? compilerOptions.baseUrl : null;
+        const paths = new Map();
+        if (compilerOptions.paths) {
+            for (const [key, value] of Object.entries(compilerOptions.paths)) {
+                if (Array.isArray(value)) {
+                    const strs = value.filter((s) => typeof s === 'string');
+                    if (strs.length > 0)
+                        paths.set(key, strs);
+                }
+            }
+        }
+        return { configDir, baseUrl, paths };
+    }
+    catch (err) {
+        // 解析抛错仍 return null（行为不变），但不再静默——首次为该 configPath 发一次 warn
+        const errorSummary = err instanceof Error ? err.message : String(err);
+        warnTsConfigFailureOnce(configPath, errorSummary);
+        return null;
+    }
 }
 //# sourceMappingURL=import-resolver.js.map