@depic/core

JS/TS 代码依赖分析核心引擎。基于 SWC 解析源码，构建项目依赖图。

English | 中文

特性

• Parser — 通过 SWC AST 提取 import/export/require，支持 15+ 种语法
• Resolver — 解析 specifier：相对路径、tsconfig paths（含嵌套）、node_modules、monorepo workspace 包
• Graph — 有向图，支持环检测、传递依赖、依赖路径、符号溯源（re-export / export * 链路）
• Monorepo — 自动检测 package.json 边界，支持 include/exclude glob 过滤
• 符号级分析 — 可选 symbolLevel，resolveSymbol() 追踪符号原始定义
• 变更影响分析 — 将 unified diff 映射到入口或 monorepo package，返回可能受影响目标及依赖链

安装

npm install @depic/core

使用

import { analyze } from '@depic/core';

const graph = await analyze({ root: '/path/to/project' });

// 循环依赖检测
graph.getCircularDependencies();

// 谁依赖了某个文件
graph.getDependents('/path/to/file.ts');

// 两个文件间的所有依赖路径
graph.getDependencyChain('a.ts', 'b.ts');

// 符号溯源
graph.resolveSymbol('index.ts', 'formatDate');

// 统计
graph.stats(); // { fileCount, edgeCount, externalCount, ... }

// 导出
graph.toJSON();
graph.toDot();

变更影响分析

传入变更后的项目工作区、unified diff 和影响目标。entry 目标由框架工具或官方 depic-impact-analysis Agent Skill 识别；package 目标使用 Depic 自动发现的 monorepo 包名。共享目标统一放在根目录 depic.config.json 的 impact.targets 中。

Git 生成的 pathname 会在 diff --git、--- / +++ 及 rename/copy metadata 中统一解码，支持 Git C-style quoted UTF-8 八进制字节、空格、引号和 POSIX 反斜杠。非法 escape、无效 UTF-8、绝对路径和 .. traversal 会在依赖图或文件系统 查询前被拒绝；当前不支持任意非 UTF-8 Git 文件名。

Skill 是上游适配器：利用 AI 检查框架约定，并让用户确认有意义的目标。 @depic/core 保持确定性和框架无关，只根据已确认的目标节点计算可达性与依赖链。

import { analyzeImpact } from '@depic/core';

const report = await analyzeImpact({
  root: '/path/to/project',
  diff: diffText,
});

report.impacts; // [{ target, impact, dependencyChains, ... }]

EntryTarget.file 相对于 root。默认忽略 type-only 导入；需要分析类型契约影响时传入 includeTypeOnly: true。package.json 等配置变更会以全局影响返回。依赖链按最短路径优先，纯 re-export barrel 不会把直接影响误分为传递影响。完整约定见仓库中的 IMPACT-ANALYSIS-FEATURES.md。

从 0.1.8 起，analyzeImpact() 自动尝试符号级精化：校验 diff 与当前源码一致， 将编辑行映射到声明，追踪私有 helper、具名/别名 re-export、export * 和静态 namespace 成员（含字符串字面量访问）。report.symbolEvidence 为每个候选“目标/变更文件”记录 precision、affected、changedSymbols、受影响符号 chain 或保守回退的 fallbackReason；被剔除目标也保留证据。

这不是通用 JS 数据流分析：动态访问、namespace 整体传递、导出歧义/循环、副作用、 不支持的语法（包括 class 和复杂初始化）、失配/缺失 hunk、模块结构变化及预算耗尽 都保留文件级结果。目标自身/所属包变更仍直接命中，0.1.8 的类型契约分析仍按文件传播。 EntryTarget.symbol 仍是标识，入口内所有声明都作为起点；现有 dependencyChains 和图 API 仍是文件级，符号来源看 symbolEvidence.chain。无需新增配置， excludeChangedFiles 仍是独立的主动排除策略。

类型契约与纯注释/格式变更（0.1.9+）

开启 includeTypeOnly: true 后，支持 interface/type-alias、类型注解及类型导入/re-export 的声明级精化。修改 UserConfig 可排除同文件其他类型的消费者，但所有使用 UserConfig 的目标仍命中，不区分字段。索引访问、条件/映射/import type、声明合并/重名、副作用和 来源歧义继续回退；类型/运行时导入切换不会丢失。默认 includeTypeOnly: false 不变。

对非全局的修改文件，校验 diff 并比较完整运行时和类型 AST；仅整个文件结构相同且指令 注释保持不变时，才从传播中移除，包括目标自身/所属包文件。semantic-noop 诊断列出路径， 这些路径不再进入 changedFiles，但图节点保留。这表示“已检查”，不是配置排除的“未分析”。 字面量原始内容、工具指令和未知标记注释受保护；指令变化/移动、解析不确定、过期 hunk、 混合有效变更等继续保守处理，全局配置规则仍优先。AST 等价不是对所有源码读取工具或 运行时反射的行为证明；暂不逐 hunk 消除语义噪声。这两项能力需要 0.1.9 或更高版本。

从 0.1.10 起（Issue #25），未改变的顶层指令包装按声明边界归属，而不是绝对代码 偏移比较，类型增长本身不再阻断精化。指令原文/顺序、相邻声明和相邻空白仍受保护； 下一行指令/未知标记还保留物理行位置，嵌套或不确定归属仍严格回退。纯文本标签的 HTTP(S) Markdown 文档链接可以变化而不阻断经校验的 no-op，未知标记和包含指令的注释仍受保护。 diff 还原保留未改变的文件末尾换行。这些修复需要 0.1.10 或更高版本。

从 0.1.12 起（Issue #27），重命名目标路径会作为 head 依赖图中的保守文件级变更， 因此可为当前消费者产生正常的 changedFiles、impacts 和依赖链证据。 renamed-file 诊断仍会标明目标路径，并在消息中包含旧路径，因为仍引用旧模块的消费者 需要基线依赖图。删除文件仍只输出诊断；重命名目标不做符号级精化或 semantic no-op 检查。

从 0.1.13 起（Issue #31），Oxlint 控制注释按受保护指令处理。新增、删除、修改、 改序或移动都会阻止 semantic-noop 剔除并保守传播。未变化的 oxlint-disable / oxlint-enable 范围包装使用稳定的声明边界 attachment；只要指令控制范围不变， 被包装代码的受支持符号级与类型精化仍然可用。

从 0.1.14 起（Issue #33），安全的导出对象字面量及其静态成员读取会建模为 client.fetchA 这类限定符号，因此修改一个成员时可剔除只使用其他成员的消费者。 支持静态字符串键读取；动态/计算访问、写入、整体对象逃逸、spread、getter/setter、 不支持的成员值和结构变化仍明确回退为文件级影响。

从 0.1.15 起（Issue #34），每个截断 target 都单独产生 chain-limit-reached 诊断，其结构化 chainLimit 包含已返回/已知至少链数、当前 target/报告总限制、限制来源、 一条已证明遗漏的链以及可复制的 CLI/config 恢复设置。截断的 TargetImpact 还包含 knownMinimumPathCount；报告总预算耗尽后，已证明受影响的后续 target 不再被静默隐藏。

从 0.1.16 起（Issue #35），缺失的变更文件会按最终生效的 discovery 配置分类。 被 include 命中且未被 exclude 排除，或属于默认/自定义源码 extensions 的路径， 仍产生醒目的 unmapped-file warning；其余文档和产物路径产生 info 级 non-source-file。两类都会保留在 JSON 报告中，后者不是隐式忽略，也不证明无影响。

从 0.1.17 起（Issue #40），ImpactOptions.baselineRoot 指向变更前 checkout。Depic 构建第二张图，使用旧图反向依赖分析删除路径，也支持只存在于 baseline 的目标。旧图证明的 影响带 analysisBasis: "baseline"，与 head 证据合并时为 "mixed"。缺少可用证据时， 顶层 analysisStatus 为 "incomplete"，删除路径仍保留在 changedFiles，并通过 unresolvedChanges 给出稳定 reason 与 recovery action。baseline 路径只作为运行时输入， 不写入共享配置。

analyze() 和 analyzeImpact() 都会读取 depic.config.json。该文件可配置 include、exclude、tsconfigPath、extensions、symbolLevel、 workspace 与 impact；显式 API 参数优先。

若需要主动忽略生成文件的变更，可向 analyzeImpact() 传入 excludeChangedFiles: ['src/generated/**']，或在根配置设置 impact.excludeChangedFiles。API 列表覆盖配置列表，显式 [] 可禁用配置中的过滤。 模式相对于 root：* 不跨目录，** 可跨目录，**/ 可匹配零层目录；其余字符按字面匹配， 可选的 ./ 和 Windows 分隔符会被规范化。0.1.6 及更早版本不支持该选项。

过滤发生在全局影响判断之前，只作用于 diff 路径，不修改图发现或遍历。被过滤文件不进入 changedFiles；diagnostics 中的 excluded-changed-files warning 通过 files 列出排序、去重后的路径。即使影响数量为零，也只能解释为“未分析”，不能解释为“无影响”。 该能力是主动排除策略，不是符号级精度提升，也不会自动识别生成代码噪声。

License

MIT