codependix-navigate

使用 codependix 浏览代码库

Codependix 可在 Nx 工作区、NestJS 容器以及 TypeScript 和 Python 的文件级导入之间构建并查询依赖图。询问“X 如何到达 Y？”“如果更改 Z 会造成什么影响？”或“这个软件包依赖什么？”时，可以使用 codependix 命令直接查询关系，或检查磁盘上已提交的图。

先用命令：查询依赖路径

使用 codependix path 在两个节点之间追踪有向依赖路径，无需解析图表或手动搜索源文件。每次调用都必须通过 --config <path> 指定配置——在本仓库中是 configuration/codependix.config.ts——因为该命令不会搜索配置，也没有默认配置。

# How does project-a reach project-c?
codependix path project-a project-c --config configuration/codependix.config.ts

# How does one file import another?
codependix path src/modules/auth/auth.service.ts src/modules/users/user.entity.ts --config configuration/codependix.config.ts

# What NestJS modules connect two modules in a container?
codependix path AuthModule DatabaseModule --config configuration/codependix.config.ts

路径查询标志和范围缩小

在整个工作区运行可能代价较高，因为它需要解析整个单体仓库中的 Nx 项目、TypeScript AST 和容器注册信息。使用范围缩小标志来限定运行范围并尽量缩短执行时间：

标志	用途
-f, --format <format>	输出格式：markdown（默认）、json 或 mermaid
--nx-projects / --no-nx-projects	开启或关闭 Nx 工作区项目依赖图搜索
--file-imports / --no-file-imports	开启或关闭内部文件级导入图搜索
--nestjs-modules / --no-nestjs-modules	开启或关闭 NestJS 容器模块图搜索
--projects <names>	要搜索的项目名称或 glob，以逗号分隔
-d, --directory <dir>	要读取其 Nx 工作区的目录
--include <globs> / --exclude <globs>	覆盖已配置的项目包含或排除 glob
--tags <tags>	要筛选的 Nx 项目标签，以逗号分隔
--config <path>	必填。 codependix 配置文件的路径；此处的每个示例都会传入该参数

路径结果

• 找到路径：输出连接 <from> 和 <to> 的最短有向路径（例如 project-a → project-b → project-c）。
• 未找到路径：报告 _No path connects "<from>" to "<to>"._（或在 JSON 中返回空列表），并以 0 退出。找不到路径也是一种答案，并非错误。

何时应读取已提交的图，而不是运行 CLI

运行 CLI 会根据源文件构建图表示。运行命令前，先检查磁盘上已提交的产物是否已经回答了问题：

1. 单体仓库中的每个软件包都会提交自己的图。 查看任意项目的 README.md 中的 ## 🕸️ Codependix 部分，或 `` 标记之间的内容。
2. 直接影响范围（1 跳）： 项目已提交的 Nx Neighborhood 图会列出所有直接的 dependencies（它会依赖哪些对象）和 dependents（其公共 API 更改后会影响哪些对象）。
3. 内部文件结构： 项目已提交的 File import graph 会列出该项目内所有文件之间的导入关系以及未连接的文件。
4. 容器结构： 项目已提交的 NestJS module graph 会列出已连接的容器模块。
5. 整个工作区结构： 仓库根目录的 README.md 包含已提交的工作区图。

成本经验法则：

• 单跳依赖、直接影响范围或本地文件布局：读取 README 图表或 JSON（无需构建，磁盘上的答案可立即获取）。
• 多跳传递路径、跨项目可达性、验证未暂存的更改，或生成机器可读的 JSON：运行 codependix path。

四种图类型及其回答的问题

图	范围	回答的问题
Nx Neighborhood	项目	一个项目依赖了什么，以及它发生变化时哪些项目会受影响
Workspace graph	工作区	高层架构分层和跨包关系
NestJS module graph	容器	DI 容器在运行时将哪些模块连接在一起
File import graph	项目文件	文件之间的导入关系、循环依赖和本地重构的影响范围

解读图表产物

Nx Neighborhood：影响范围

Neighborhood 覆盖焦点项目（图中高亮显示）两个方向各一跳：

• dependents 是破坏性变更的影响范围：列出的每个项目都必须针对新结构构建。对于跨越更深层级的破坏性变更，请逐层向外检查 Neighborhood，或运行 codependix path。
• dependencies 是允许使用的范围：项目只能导入此处声明的内容。
• 标记为 implicit 的边是 Nx 工作区配置依赖，而非代码导入。

File import graph：重构与移动

边严格表示同一项目内文件之间的关系：

• 按设计，不包含外部包和跨项目导入（它们属于 Nx Neighborhood）。
• isolatedFileNames 是待调查的文件列表，而非死代码。 孤立文件可能是入口点、外部导出项或配置文件。
• 循环依赖是真实存在的：项目内的导入循环会导致运行时绑定为 undefined，或引发初始化顺序错误。沿着循环依赖边查找需要解耦的位置。
• 要重命名文件？指向旧相对路径的边会显示确切的影响范围。

NestJS module graph：DI 容器连接关系

通过评估容器模块构建：

• 全局或环境模块：几乎被所有其他模块导入的模块（例如核心日志或配置模块）会省略单独的边，以减少视觉干扰；它们会列在 ambientModuleNames 下，并以圆角绘制。
• 动态包装模块：由 forRoot 或动态提供者创建的私有内部宿主模块会折叠到声明它们的模块中。
• 缺失的模块从未在容器层级中注册，这意味着其导出的提供者不可用。

信任已提交的图之前，先确认其时效性

已提交的图反映了上次运行 codependix map --write 时的仓库状态。要检查已提交的图是否为最新状态：

# Check if any committed reports are stale without modifying files
codependix map --check reports --config configuration/codependix.config.ts

# Update all committed graphs across the workspace
codependix map --write --config configuration/codependix.config.ts

如果已提交的图与近期本地编辑相比已经过时，请重新运行 codependix map --write，或使用 codependix path 进行实时查询。