spectra-cli 4.2.0 → 4.3.0

package/dist/core/import-resolver.d.ts

@@ -1,90 +1,93 @@
-import { Node } from 'ts-morph';
 /**
- * 4 类 TS/JS import 的语义类型（FR-28 / AC-11）。
- *
- * - 'static'：标准 ES Module 静态 import（`import { foo } from 'x'`）
- * - 'dynamic'：动态 import 表达式（`await import('x')`）
- * - 'type-only'：类型导入（`import type { T } from 'x'`）
- * - 'commonjs-require'：CommonJS require 调用（`const x = require('x')`）
- *
- * 注：ModuleEdge.importType 枚举为 ['static', 'dynamic', 'type-only']，
- * commonjs-require 在 module-derivation 派生时会归并到 'static'（CommonJS 视为同步加载）。
+ * import 路径解析结果。
+ * resolvedPath 为相对 projectRoot 的 POSIX 路径；external/unresolved 时为 null。
+ * 当 projectRoot 为空字符串（独立 AST 调用）时，resolvedPath 为绝对路径（调用方自行归一）。
  */
-export type ImportType = 'static' | 'dynamic' | 'type-only' | 'commonjs-require';
+export interface ResolveResult {
+    /** 解析后的目标文件路径（相对 projectRoot 的 POSIX 相对路径；projectRoot 空时为绝对路径）。 */
+    resolvedPath: string | null;
+    kind: 'module' | 'package-init' | 'relative-sibling' | 'relative' | 'paths-alias' | 'absolute' | 'external' | 'unresolved';
+}
 /**
- * resolveTsJsImport 选项。
- *
- * pathAliases 历史兼容：
- *   - 单值形式 Record<string, string>（旧调用方）—— 内部包装为 [value] 单候选数组
- *   - 多值形式 Record<string, string[]>（CRIT-2 v2 新增）—— tsconfig.compilerOptions.paths
- *     原生格式，支持 monorepo 多候选（如 alias '@app/star' 映射到 ['./packages/app/star', './apps/star/src']）
- *
- * baseUrl（CRIT-2 v2 新增）：
- *   - tsconfig 的 compilerOptions.baseUrl 解析后的绝对路径
- *   - 当 specifier 不是相对路径且没有 alias 命中时，作为最后的非相对 module 解析根
- *     （如 baseUrl='./src'，specifier='utils/foo' → 尝试 src/utils/foo.ts/tsx 等）
+ * TypeScript/JavaScript tsconfig.json 解析上下文。
+ * 由 findNearestTsConfig + buildTsConfigContext 协作生成。
  */
-export interface ResolveTsJsImportOptions {
-    /** 尝试的扩展名顺序（默认 ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']） */
-    extensions?: readonly string[];
-    /** index 文件名顺序（默认 ['index.ts', 'index.tsx', 'index.js', 'index.jsx']） */
-    indexFiles?: readonly string[];
-    /**
-     * tsconfig paths 映射。支持单值（向后兼容）和多候选数组形式。
-     * key 中 star 通配符等价 tsconfig 中的星号；value 同理。
-     */
-    pathAliases?: Record<string, string | readonly string[]>;
+export interface TsConfigResolutionContext {
+    /** tsconfig.json 所在目录的绝对路径 */
+    configDir: string;
     /**
-     * tsconfig.compilerOptions.baseUrl 解析后的绝对路径。
-     * 设置后，未命中 alias 的非相对 specifier 也会尝试基于 baseUrl 解析。
+     * baseUrl 配置（经 ts.parseJsonConfigFileContent 解析，通常为绝对路径）。
+     * 用户未配置 baseUrl → null（跳过 baseUrl 解析）。
+     * 注：alias 算法用 path.resolve(configDir, baseUrl, replacement)，绝对 baseUrl 会正确覆盖 configDir。
      */
-    baseUrl?: string;
+    baseUrl: string | null;
+    /** paths 映射（含 wildcard），key/value 保留原始 tsconfig 相对字符串 */
+    paths: Map<string, string[]>;
 }
+/** 将路径转换为 POSIX 格式（确保跨平台 resolvedPath 始终用 '/' 分隔符）。 */
+export declare function toPosix(p: string): string;
 /**
- * 把 TS/JS import specifier 解析为绝对文件路径。
+ * 判断 candidate 路径是否严格在 projectRoot 子树内（C-5 + N-2）。
+ *
+ * 用 path.relative 逐 component 检查第一段是否为 '..'，避免字典序误判（/proj vs /projection）。
+ * candidate === projectRoot 返回 false（projectRoot 自身不算"在子树内"）。
+ */
+export declare function isInsideProjectRoot(candidate: string, projectRoot: string): boolean;
+/**
+ * 判断路径是否指向非源文件目标（W-1）。
+ * .json 和 .d.ts 文件不进入 callSites graph，返回 external。
+ */
+export declare function isNonSourceTarget(p: string): boolean;
+/**
+ * 解析 TypeScript/JavaScript import 路径（单一权威实现，Feature 181）。
  *
  * 解析顺序：
- *   1. node 内置模块（如 'fs'）/ npm 包（不带相对前缀且无 alias 命中）→ null
- *   2. tsconfig path alias 命中 → 替换前缀后按相对路径流程解析
- *   3. 相对路径（`./xxx` / `../xxx` / `/xxx`）→ 基于 fromFile 拼接
+ *   1. node: 内置 → external
+ *   2. 磁盘绝对路径（'/' 前缀）→ 文件候选 + projectRoot 守卫
+ *   3. 相对路径（'./' '../'）→ 文件候选 + projectRoot 守卫；.json/.d.ts → external
+ *   4. 非相对：tsconfig paths alias（最长前缀 + 多候选 + baseUrl 叠加）→ baseUrl 解析 → external/unresolved
  *
- * 文件存在性检查：
- *   - 直接命中（specifier 已含 .ts/.js 等扩展名）
- *   - 扩展名补全（依次尝试 options.extensions）
- *   - 目录 + index 文件 fallback（如果 specifier 指向目录）
+ * 守卫策略（逐分支复刻历史 kg）：relative / disk-absolute 分支启用 isInsideProjectRoot
+ * （仅 projectRoot 为真时）；paths-alias / baseUrl 分支不加守卫（保持 alias 语义）。
  *
- * 失败时静默返回 null，不抛异常（FR-28 best-effort 语义）。
+ * @param moduleSpec      - import 说明符（如 './engine'、'~/utils'、'express'）
+ * @param callerFile      - 调用方文件的绝对路径
+ * @param projectRoot     - 项目根目录绝对路径（空字符串：返回绝对路径 + 跳过守卫）
+ * @param tsConfigContext - tsconfig 解析上下文（null/undefined：仅走相对/绝对路径）
+ * @returns ResolveResult（失败返回 { resolvedPath: null, kind: 'unresolved' }，不抛异常）
+ */
+export declare function resolveTsJsImport(moduleSpec: string, callerFile: string, projectRoot: string, tsConfigContext?: TsConfigResolutionContext | null): ResolveResult;
+/**
+ * AST 消费方便捷封装：解析并归一为**绝对路径**。
  *
- * @param specifier - import 字符串字面量（如 './foo'）
- * @param fromFile - 发起 import 的源文件绝对路径
- * @param projectRoot - 项目根目录（用于 alias 相对路径解析；可为空字符串，alias 失效）
- * @param options - 扩展名 / index 文件 / alias 配置
- * @returns 解析到的绝对路径；外部模块或解析失败返回 null
+ * 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 declare function resolveTsJsImport(specifier: string, fromFile: string, projectRoot: string, options?: ResolveTsJsImportOptions): string | null;
+export declare function resolveTsJsImportToAbsolute(moduleSpec: string, callerFile: string, projectRoot: string, tsConfigContext?: TsConfigResolutionContext | null): string | null;
 /**
- * 从 ts-morph 节点派生 ImportType 字面量（FR-28 / plan §2.5）。
+ * 从 filePath 向上查找最近的 tsconfig.json（monorepo-aware）。
  *
- * 判断规则：
- *   1. 'type-only'：ImportDeclaration 且 isTypeOnly()=true
- *   2. 'dynamic'：CallExpression 且 callee 为 import 关键字（SyntaxKind.ImportKeyword）
- *   3. 'commonjs-require'：CallExpression 且 callee 文本 = "require"
- *   4. 'static'：默认（标准 ImportDeclaration）
+ * 上溯范围：从 path.dirname(filePath) 向上，直到 projectRoot 边界（含 projectRoot 本身）。
+ * 越过 projectRoot 停止，不抛异常。
  *
- * 注：tree-sitter / 正则降级路径不调用此函数，由调用点直接根据 query 节点类型映射
- * （tree-sitter typescript-mapper 仅处理 import_statement，importType 始终为 'static' 或 'type-only'，
- * 由 isTypeOnly 字段派生）。
+ * @returns tsconfig.json 的绝对路径；未找到返回 null
  */
-export declare function detectImportType(node: Node): ImportType;
-import type { ImportReference } from '../models/code-skeleton.js';
+export declare function findNearestTsConfig(filePath: string, projectRoot: string): string | 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 declare function resolveImportsForFile(imports: ImportReference[], fromFile: string, projectRoot: string, options?: ResolveTsJsImportOptions): ImportReference[];
+export declare function buildTsConfigContext(configPath: string): TsConfigResolutionContext | null;
 //# sourceMappingURL=import-resolver.d.ts.map

package/dist/core/import-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-resolver.d.ts","sourceRoot":"","sources":["../../src/core/import-resolver.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,IAAI,EAAsC,MAAM,UAAU,CAAC;AAMpE;;;;;;;;;;GAUG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,kBAAkB,CAAC;AAEjF;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,wBAAwB;IACvC,kEAAkE;IAClE,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,yEAAyE;IACzE,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC;IACzD;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAsBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,wBAAwB,GACjC,MAAM,GAAG,IAAI,CAqCf;AA6GD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,UAAU,CASvD;AAoCD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,eAAe,EAAE,EAC1B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,wBAAwB,GACjC,eAAe,EAAE,CAkBnB"}
+{"version":3,"file":"import-resolver.d.ts","sourceRoot":"","sources":["../../src/core/import-resolver.ts"],"names":[],"mappings":"AAiDA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,EACA,QAAQ,GACR,cAAc,GACd,kBAAkB,GAClB,UAAU,GACV,aAAa,GACb,UAAU,GACV,UAAU,GACV,YAAY,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,yDAAyD;IACzD,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC9B;AA8BD,uDAAuD;AACvD,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAOnF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEpD;AA6ED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,eAAe,CAAC,EAAE,yBAAyB,GAAG,IAAI,GACjD,aAAa,CAgFf;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,eAAe,CAAC,EAAE,yBAAyB,GAAG,IAAI,GACjD,MAAM,GAAG,IAAI,CAMf;AAuED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmBxF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,yBAAyB,GAAG,IAAI,CAmCzF"}