tonythethompson/dependency-chain-substrate

# Dependency Chain Substrate (DCS) **静态依赖注入图提取、迁移验证和漂移分析 —— 无需构建你的项目。** [](https://github.com/tonythethompson/dependency-chain-substrate/actions/workflows/ci.yml) ## 关于 Dependency Chain Substrate 是一个用于依赖注入 (DI) 的**迁移验证器**。它从任意 git commit 中读取源代码，构建注册图，并报告框架迁移（例如 WinUI → Avalonia）是否仍存在**泄漏**、**重复**或**损坏**的连接。 该工具诞生于真实的失败场景：在一次从 WinUI 到 Avalonia 的迁移过程中，完整的 DI 图是不可见的，并行的 shell 注册了相同的服务，而人类和智能体都宣称迁移已经“完成”，但事实并非如此。DCS 的存在是为了用客观的、精确到文件和代码行的证据，来**反驳“我们没问题”这种虚假声明**。 ### 它的功能 | 功能 | 命令 | 用途 | |------------|---------|---------| | **框架边界探测** | `dcs analyze` | 检测已声明框架标签中的 `LEAKED`、`DUPLICATE`、`BROKEN`、`ORPHANED` 和 `CYCLE` 发现 | | **漂移扫描器 / 迁移 Diff** | `dcs diff` | 在两个 commit 之间比较注册图，支持感知重命名匹配 | | **注册图集** | `dcs atlas`, `dcs dump-ir` | 人类可读的列表和带版本的 JSON IR 导出 | | **拓扑视图** | `dcs viz` | 在 Trackdub 规模（300+ 节点）下生成立自足的交互式 HTML 图表 | | **路径挖掘器** | `dcs path` | 从组合根到目标注册的最短依赖路径 | | **拓扑视图（路径）** | `dcs viz --path-to` | 在交互式 HTML 图表上高亮显示相同的路径 | | **自动修复（预览/应用）** | `dcs fix` | 针对重复、孤立和简单的损坏注册问题，提供安全的 C# 修复 | ### 与众不同之处 - **静态优先，git 原生** —— 通过 LibGit2Sharp 读取任意 commit 的 blob；无需 checkout，分析也无需 MSBuild 还原。 - **专注于迁移的语义** —— 跨框架泄漏和重复的抽象 token 是一等（first-class）发现，而不是通用的代码异味。 - **诚实的盲点** —— 工厂 lambda、条件注册和未解析的注入会被作为 `BLIND_SPOT` / `DEGRADED` 呈现出来，而不是被静默丢弃。 - **适配 CI** —— 发生错误时返回非零退出码；提供用于自动化的 JSON 报告 schema。 - **多语言 IR** —— C# (Roslyn) 和 Java/Spring (tree-sitter) 解析器共享同一个带版本的图模型。 DCS **不是**运行时分析器、SonarQube 替代品或通用架构 linter。它对 DI 注册调用点及其之间的边进行建模。 ## 快速开始 ### 前置条件 - [.NET SDK 8.0+](https://dotnet.microsoft.com/download)（为了完整的 C# 语义门控，推荐使用 10.0） - Git（用于仓库分析） ### 构建 ``` git clone https://github.com/tonythethompson/dependency-chain-substrate.git cd dependency-chain-substrate dotnet build ``` ### 作为全局工具安装 **从 NuGet 安装**（发布后）： ``` dotnet tool install --global DependencyChainSubstrate.Cli --version 0.1.1 dcs --help ``` **从 GitHub Release 安装**（在发布到 NuGet.org 之前可用）： ``` # PowerShell — 下载 .nupkg 然后进行安装（不要从 repo 根目录使用 --add-source .） .\scripts\install-dcs-from-release.ps1 -Version 0.1.1 ``` 或者手动安装： ``` gh release download v0.1.1 -p "*.nupkg" -D artifacts/release dotnet tool install --global DependencyChainSubstrate.Cli --add-source .\artifacts\release --version 0.1.1 ``` **从本地构建安装**（开发或预发布版本）： ``` dotnet pack src/DCS.Cli/DCS.Cli.csproj -c Release -o artifacts/nupkg dotnet tool install --global DependencyChainSubstrate.Cli --add-source ./artifacts/nupkg dcs --help ``` 升级：`dotnet tool update --global DependencyChainSubstrate.Cli` 卸载：`dotnet tool uninstall --global DependencyChainSubstrate.Cli` 全局命令是 **`dcs`**。包 ID：`DependencyChainSubstrate.Cli`（版本说明请参阅 [CHANGELOG.md](CHANGELOG.md)）。 ### 运行 CLI **使用全局工具**（安装后）： ``` dcs analyze /path/to/your/repo ``` **不安装运行**（开发模式）： ``` dotnet run --project src/DCS.Cli -- analyze /path/to/your/repo ``` 或者构建一次，然后直接调用 `src/DCS.Cli/bin/Debug/net8.0/dcs`。 ### 分析特定 commit ``` dcs analyze /path/to/repo --commit abc1234 ``` 如果未使用全局工具，可使用 `dotnet run --project src/DCS.Cli -- analyze ...`。 退出码 **0** = 没有阻断性错误。退出码 **1** = 发现 `LEAKED` 或 `BROKEN` 问题（CI 门控）。退出码 **2** = 用法错误。 ## 示例工作流 迁移过程中的桌面应用，同时运行 WinUI 和 Avalonia shell： ``` # 1. 在固定的 mid-migration commit 处进行全面分析 dotnet run --project src/DCS.Cli -- analyze ./my-app --commit 3c4e374d --verbosity actionable # 2. Multi-target-framework 摘要（portable + windows TFMs） dotnet run --project src/DCS.Cli -- analyze ./my-app --commit 3c4e374d --context all --metrics # 3. 跟踪 service 是如何到达 shell 的 dotnet run --project src/DCS.Cli -- analyze ./my-app --commit 3c4e374d --context "csharp|net10.0" dotnet run --project src/DCS.Cli -- path ./my-app --commit 3c4e374d --to VoiceCloneConsentCoordinator --context "csharp|net10.0-windows10.0.19041.0" # 4. 停用旧 shell 前后的 Diff dotnet run --project src/DCS.Cli -- diff ./my-app --from 3c4e374d --to 316614b8 # 5. 用于审查的交互式图表 dotnet run --project src/DCS.Cli -- viz ./my-app --commit 3c4e374d --out graph.html # 6. 用于 CI 的 JSON 报告 dotnet run --project src/DCS.Cli -- analyze ./my-app --commit 3c4e374d \ --format json --report-out report.json --text-out report.txt ``` 文本输出示例部分（按严重程度排序）： ``` LEAKED BROKEN CHAINS DUPLICATE REGISTRATIONS ORPHANED CYCLES BLIND SPOTS SUMMARY ``` ## CLI 参考 运行 `dotnet run --project src/DCS.Cli -- --help` 获取完整用法。 | 命令 | 描述 | |---------|-------------| | `analyze ` | 提取 DI 图并运行泄漏分析 | | `atlas ` | 人类可读的注册列表 | | `dump-ir ` | 不进行分析直接导出 IR JSON | | `diff --from --to ` | 对比两个 commit | | `path --to ` | 指向某项注册的依赖路径 | | `enrich --runtime-log ` | 将静态 IR 与运行时 JSONL 解析日志合并 | | `viz ` | 生成立自足的 HTML 可视化 | | `fix ` | 预览/应用 C# 修复：重复、孤立、损坏、泄漏 | ### 常用选项 | 标志 | 适用范围 | 描述 | |------|------------|-------------| | `--commit ` | analyze, atlas, dump-ir, path, viz, fix (预览) | 将源代码固定到某个 git commit (读取 blob) | | `--language auto\|csharp\|java` | analyze, diff, atlas, viz | 选择解析器 | | `--context ` | analyze, path, fix | 选择 TFM/上下文（使用 `all` 查看汇总） | | `--target-framework ` | analyze | 单个 TFM 图 | | `--all-target-frameworks` | analyze | 为发现的每个 TFM 生成一个图 | | `--frameworks ` | analyze, diff | 附加的自定义框架边界配置 | | `--format text\|json` | analyze, path | 输出格式 | | `--report-out ` | analyze | 写入结构化报告 | | `--verbosity summary\|actionable\|full` | analyze | 发现详情的详细程度 | | `--strict` | analyze | 禁用噪音抑制（审计模式） | | `--metrics` | analyze | 在 stderr 上打印提取质量指标 | | `--cache-dir ` | 仓库命令 | 覆盖提取缓存 | | `--no-cache` | 仓库命令 | 绕过缓存（在更新解析器后使用） | | `--preview` / `--apply` | fix | 预览 diff 或写入更改（`--apply` 需要干净的工作区） | | `--fix-class ` | fix | `duplicate` (默认), `orphaned`, `broken`, `leaked` | | `--token ` | fix | 将修复限制在单个注册 token | | `--all-duplicates` | fix | 预览/应用所有严格重复修复 | | `--verify-build` | fix | 在 `--apply` 之后，运行 `dotnet build`；失败时回滚补丁 | **PowerShell 注意：** 引号括住上下文 ID 中的管道符：`--context "csharp|net10.0"`。 **路径消歧义：** `--to VoiceCloneConsentCoordinator` 可能会匹配跨 shell 的多个注册。请使用注册 ID 或完全限定名，或者使用 `--context` 缩小范围。 ## 架构 ``` ┌─────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Git blobs │────▶│ Parser layer │────▶│ IR (DCS.Core) │ │ (LibGit2) │ │ C# / Java │ │ schema 1.2.0 │ └─────────────┘ └──────────────────┘ └────────┬────────┘ │ ┌───────────────────────────────┼───────────────────────────────┐ ▼ ▼ ▼ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ DCS.Analysis │ │ DCS.Diff │ │ DCS.Viz │ │ leakage, path │ │ commit diff │ │ HTML graph │ └───────┬───────┘ └───────────────┘ └───────────────┘ │ ▼ ┌───────────────┐ │ DCS.Cli │ │ dcs analyze… │ └───────────────┘ ``` ### 仓库布局 | 路径 | 职责 | |------|------| | `src/DCS.Core` | IR 类型、序列化、提取缓存 | | `src/DCS.Parser.CSharp` | Roslyn 静态 + 语义提取 | | `src/DCS.Parser.Java` | Spring Boot / tree-sitter 提取 | | `src/DCS.Analysis` | 图分析、发现、路径查找器 | | `src/DCS.Diff` | 跨 commit 图比较器 | | `src/DCS.Viz` | 立自足的 HTML 可视化 | | `src/DCS.Fix` | DUPLICATE 注册 codemod | | `src/DCS.Cli` | `dcs` 命令行入口点 | | `tests/` | 单元、fixture 和语料库门控测试 | | `docs/DESIGN.md` | 设计文档（问题、IR、模块） | | `docs/decisions/` | 架构决策记录 (ADR) | | `docs/schemas/` | JSON schema（例如 `analysis-report-1.0.json`） | | `vscode-extension/` | 阶段 7 VS Code 扩展脚手架（报告 JSON 消费者） | | `PLAN.md` | 里程碑跟踪器和阶段门控 | ## 语言和范围 ### 当前支持范围内 - **C#** —— `Microsoft.Extensions.DependencyInjection` 调用点模式；每个 TFM 的语义类型解析；内置框架标签（WinUI、Avalonia、WPF、ASP.NET Core 等） - **Java / Spring Boot** —— `@Bean`、构造型、`@Autowired` 装配；PetClinic 集成门控 ### 明确不在支持范围内 (v1) - 通用运行时容器性能分析（阶段 9 发布了针对性的 MS.DI 运行时增强叠加层） - IDE 扩展（推迟至阶段 7） - TypeScript / Python 解析器（已搁置） - LEAKED 自动修复和超出当前 C# DUPLICATE / ORPHANED / 简单 BROKEN 修复类别的广泛 codemod - 完全依赖项目构建的语义 MSBuildWorkspace ## 基准事实与验证 DCS 是针对真实的迁移语料库进行验证的，而不仅仅是简单的测试 fixture。 | 语料库 | 角色 | 门控 | |--------|------|------| | **Trackdub** | 私有的 WinUI→Avalonia 迁移中参考 | 解析器、运行时、diff-rename 和修复语料库门控 | | **StabilityMatrix** | 公开 Avalonia 单 shell 负对照 | `CsharpNegativeControlGateTests` (`csharp-negative-control`) | | **Spring PetClinic** | Java/Spring IR 冒烟测试 | `SpringPetClinicIntegrationTests` | | **di-patterns fixtures** | 解析器模式目录回归 | Golden CLI/JSON 测试 | Trackdub pin: `b57fc832` (GitHub 上 WinUI 退役后迁移的 head；参见 `tests/verification/TrackdubPin.cs`) StabilityMatrix pin: `d97f6ccb9634a7ccfa7513be083aa70653112147` (分析 `StabilityMatrix/` 子项目) ### 在本地运行语料库门控 语料库 pin 和 CI 矩阵条目定义在 [`ci/corpus-gates.json`](ci/corpus-gates.json) 中。门控测试使用 xUnit 特征进行标记——不按类名过滤。 **C# 迁移语料库 (`csharp-migration`)：** ``` set CORPUS_CSHARP_MIGRATION_PATH=A:\Trackdub # Windows # 或者：export CORPUS_CSHARP_MIGRATION_PATH=/path/to/trackdub dotnet test tests/DCS.Parser.CSharp.Tests --filter "Category=CorpusGate&CorpusId=csharp-migration" dotnet test tests/DCS.Runtime.Tests --filter "Category=CorpusGate&CorpusId=csharp-migration" dotnet test tests/DCS.Diff.Tests --filter "Category=CorpusGate&CorpusId=csharp-migration" dotnet test tests/DCS.Fix.Tests --filter "Category=CorpusGate&CorpusId=csharp-migration" ``` 旧版的 `TRACKDUB_PATH` 仍然受支持。 **C# 负对照语料库 (`csharp-negative-control`)：** ``` git clone https://github.com/LykosAI/StabilityMatrix.git cd StabilityMatrix && git checkout d97f6ccb9634a7ccfa7513be083aa70653112147 set CORPUS_CSHARP_NEGATIVE_CONTROL_PATH=C:\path\to\StabilityMatrix dotnet test tests/DCS.Parser.CSharp.Tests --filter "Category=CorpusGate&CorpusId=csharp-negative-control" ``` **Java Spring 语料库 (`java-spring`)：** ``` set CORPUS_JAVA_SPRING_PATH=/path/to/spring-petclinic dotnet test tests/DCS.Parser.Java.Tests --filter "Category=CorpusGate&CorpusId=java-spring" ``` 旧版的 `PETCLINIC_PATH` 仍然受支持。 CI 将每个语料库检出在 `corpus//` 下，并设置 `DCS_CORPUS_PATH`。私有仓库需要 `CORPUS_CHECKOUT_PAT` 仓库密钥（或旧版的 `TRACKDUB_PAT`）。 ## 发布 | 渠道 | 安装方式 | |---------|----------------| | **全局工具 (NuGet)** | `dotnet tool install --global DependencyChainSubstrate.Cli --version 0.1.1` | | **GitHub Releases** | `.\scripts\install-dcs-from-release.ps1 -Version 0.1.1` 或从 [Releases](https://github.com/tonythethompson/dependency-chain-substrate/releases) 下载 `.nupkg` 到一个文件夹中，然后执行 `dotnet tool install --global DependencyChainSubstrate.Cli --add-source .\that-folder --version 0.1.1` | | **从源码** |dotnet pack src/DCS.Cli/DCS.Cli.csproj -c Release -o artifacts/nupkg` | 版本历史：[CHANGELOG.md](CHANGELOG.md)。 ### 发布新版本（维护者） 1. 提升 `src/DCS.Cli/DCS.Cli.csproj` 中的 ``，并在 [CHANGELOG.md](CHANGELOG.md) 中添加一个部分。 2. Commit，合并到 `main`，然后打 tag： git tag v0.1.0 git push origin v0.1.0 3. [发布工作流](.github/workflows/release.yml) 在 `v*` 标签上运行：单元测试 → 打包 → GitHub Release（附带 `.nupkg`）→ 通过**可信发布者**推送到 NuGet.org。 **NuGet.org：** 在 [nuget.org](https://www.nuget.org) 上配置可信发布者 → GitHub → `tonythethompson/dependency-chain-substrate` → 工作流文件 **`release.yml`**（仅文件名）。将 GitHub 仓库密钥 **`NUGET_USER`** 设置为你的 [nuget.org 个人资料名](https://www.nuget.org/users/account)（不是你的邮箱）。该工作流使用 [`NuGet/login@v1`](https://github.com/NuGet/login) (OIDC)，然后执行 `dotnet nuget push`。在 NuGet 任务失败后重新发布：Actions → **release** → **Run workflow**，版本为 `0.1.1`（运行打包 + NuGet；手动运行时的 GitHub Release 为草稿状态）。 **手动起草发布：** Actions → **release** → **Run workflow**，输入与 csproj 匹配的版本（创建一个草稿状态的 GitHub Release 用于冒烟测试）。 ## 开发 ``` dotnet restore dotnet build dotnet test ``` CI 在 push/PR 到 `main` 时运行： | 工作流 | 触发条件 | |----------|---------| | [`ci.yml`](../.github/workflows/ci.yml) | push, pull_request | | [`release.yml`](../.github/workflows/release.yml) | push tag `v*`, 手动触发 | push/PR 时的 CI 作业类型： 1. **build-test** (Windows, .NET 8) —— 单元测试和 fixture 测试，不包括语料库门控 2. **corpus-matrix** —— 从 [`ci/corpus-gates.json`](ci/corpus-gates.json) 加载门控定义 3. **corpus-gate** —— 每个配置的基准事实语料库对应一个矩阵分支（运行器和 SDK 因门控而异） 关于添加门控或在本地运行门控，请参阅 [`ci/README.md`](ci/README.md)。 ### 智能体和设计纪律 本仓库使用明确的 **设计 (Designed) → 实现 → 测试 → 验证** 门控。智能体工作流规则请参阅 [`AGENTS.md`](AGENTS.md)，里程碑状态请参阅 [`PLAN.md`](PLAN.md)。 关键设计产出物： - [`docs/DESIGN.md`](docs/DESIGN.md) —— 问题陈述、IR 模型、模块规范 - [`docs/decisions/`](docs/decisions/) —— 关于提取策略、身份、形态、语义解析等方面的 ADR - [`planning/00-plan-of-plan.md`](planning/00-plan-of-plan.md) —— 起源故事和阶段划分理由 ## 当前状态 截至 2026-06-30，**阶段 0–13** 和 **阶段 9（运行时叠加层 MVP）** 已实现，包括： - 带有语义 Roslyn 解析的静态 C# 提取（在 Trackdub 聚合上约 92%） - 跨 TFM 项目引用编译闭包 - 工厂 lambda 浅层依赖追踪 - 结构化 JSON 分析报告 - `dcs path` 路径挖掘器 MVP - Spring Boot 解析器（阶段 6） - `dcs fix` DUPLICATE + ORPHANED + 简单 BROKEN 预览/应用（阶段 8 / 8.1b / 8.1d） - 可选的 `dcs fix --apply --verify-build` 编译验证，并在构建失败时回滚 - 运行时增强叠加层 —— `DcsRuntimeEventListener` + `dcs enrich`（阶段 9 已在 Trackdub @ pin 上**验证**） **已搁置/推迟：** IDE 扩展，TypeScript/Python 解析器。 在 [`PLAN.md`](PLAN.md) 中跟踪进度。 ## 贡献 1. 在进行架构更改之前，请阅读 [`AGENTS.md`](AGENTS.md) 和相关的 ADR。 2. 保持更改聚焦；在没有测试证据的情况下不要提升里程碑状态。 3. 对于语料库门控工作，请从 [`ci/corpus-gates.json`](ci/corpus-gates.json) 设置路径环境变量，或使用旧版的 `TRACKDUB_PATH` / `PETCLINIC_PATH`。 4. 建议使用约定式提交（`feat:`, `fix:`, `docs:`, `test:`, `chore:`）。 欢迎提交 Issue 和 pull request。 ## 许可证 [MIT](LICENSE) © 2026 [tonythethompson](https://github.com/tonythethompson)

标签：JS文件枚举, Spring, 云安全监控, 依赖注入, 多人体追踪, 架构, 重构, 静态分析