CodeLaser/maddi
GitHub: CodeLaser/maddi
maddi 是一个针对 Java/Kotlin 的整程序静态分析器，通过数据流追踪自动推导代码的可变性级别和独立性，帮助开发者精准了解代码的不可变状态及改进方向。
Stars: 0 | Forks: 0
# maddi
**maddi 能够分析出你的 Java 代码库中到底什么是真正不可变的——并告诉你为什么它不是。**
它是一个针对 Java（以及通过共享语法树支持的 Kotlin）的整程序静态分析器。你不需要
编写注解；maddi 会*计算*出它们。它会读取你的源代码和 classpath，追踪对象是如何
在字段、参数和返回值之间流动的，并为每个类型、方法和字段推导出 `@Immutable`、`@Container`、
`@Modified` 和 `@Independent`。
## 为什么不直接判断“是否不可变”
真实的代码很少是深度不可变的，而简单的“是/否”结论会丢弃所有有用的信息。maddi
会计算出一个**级别**，因此它可以告诉你你的进度以及阻碍你的原因。
```
public final class Config {
private final Map settings;
public Config(Map settings) {
this.settings = settings; // (1)
}
public String get(String key) {
return settings.get(key);
}
}
```
将第 (1) 行修改为 `Map.copyOf(settings)`，结论就会上升一个级别：
这种区分正是该项目的核心所在。如果一个工具对这两个版本都得出“不可变”的结论，
那么它完全没有告诉你它们之间的区别。
这四个级别分别是 `@Mutable` → `@FinalFields` → `@Immutable(hc=true)` → `@Immutable`，此外
还有一个单独的独立性维度，以及针对 builder/freeze 模式的**最终不可变性**
（`@Mark`、`@Only`、`@Immutable(after=…)`）——即那些在构造期间可变，但在此之后永远
不可变的类型。这些概念在
[*The Road to Immutability*](road-to-immutability/src/docs/asciidoc/) 中有详细阐述；
[精简摘要](road-to-immutability/llm-summary.md) 是最快的入门途径。
## 状态 — 2026 年 7 月
maddi **尚未达到生产就绪状态**，本节的内容是有意保持客观真实的。
| 部分 | 状态 |
|---|---|
| 概念与书籍 | 稳定 |
| 解析器/解析器 (javac 前端) | 健壮；已在许多开源项目和一个 300 万行的闭源代码库上经过验证 |
| 修改与不可变性分析 | 已在验证用的基准语料库（Timefold、LangChain4j、Fernflower、Guava、ActiveMQ、Jenkins、Camel）上运行至经认证的不动点。尚未准备好用于通用场景 |
| Kotlin 前端 | 可用；仅通过混合 CLI 发布 |
| Gradle / Maven 插件 | 功能正常，但近期关注较少 |
| 发布版本 | 暂无 — 请从源码构建（见下文）。请参阅 [`PUBLISHING.md`](PUBLISHING.md) |
如果你今天在自己的代码上运行它，预计会遇到一些粗糙之处。非常欢迎提交 Issue 和提问。
## 试一试
需要 `JAVA_HOME` 指向较新的 JDK（开发环境基于 JDK 26；无需 Gradle 工具链
配置）。目前还没有发布制品，因此请先进行构建：
```
git clone https://github.com/CodeLaser/maddi.git && cd maddi
./gradlew build # compile + fast tests
```
然后分析一些自包含的内容——例如 maddi 自身的 CST API，针对 `java.base`：
```
./gradlew :maddi-run-openjdk:run --args="\
--jmod=java.base \
--source=$PWD/maddi-cst-api/src/main/java \
--analysis-steps=prep"
```
要让它分析*你的*项目，请捕获构建实际编译的内容并将其交给 maddi ——
无需构建工具集成：
```
./gradlew :your-module:compileJava --debug 2>&1 | grep 'Compiler arguments:' > build.log
maddi --compile-log build.log --analysis-steps modification --analysis-results-dir out
```
更多实战示例，包含两个无需检出项目即可直接运行的内置 Maven 构建日志：[`maddi-run-openjdk/running-examples.md`](maddi-run-openjdk/running-examples.md)。
Gradle 和 Maven 插件、配置及退出代码详见用户手册
（`./gradlew :maddi-manual:buildDocs`）。
## 文档
| 你想要… | 请阅读 |
|---|---|
| 理解相关概念（级别、修改、链接、独立性） | [`road-to-immutability/llm-summary.md`](road-to-immutability/llm-summary.md)，然后阅读[书籍](road-to-immutability/src/docs/asciidoc/) |
| 在你自己的项目中运行 maddi | 用户手册，[`maddi-manual/src/docs/asciidoc/`](maddi-manual/src/docs/asciidoc/) |
| 理解代码库（流水线、约 40 个模块，从何处开始） | [`ARCHITECTURE.md`](ARCHITECTURE.md) |
| 构建、测试、贡献 | [`CONTRIBUTING.md`](CONTRIBUTING.md) |
| 使用 AI 助手进行开发 | [`AGENTS.md`](AGENTS.md) / [`CLAUDE.md`](CLAUDE.md) |
跨模块的设计说明和计划已在 [`docs/README.md`](docs/README.md) 中建立索引。
## 背景
maddi 重新实现了 [e2immu](https://www.e2immu.org)，后者从 2020 年一直运行直到被归档。
根 Java 包仍然沿用前身的命名，为 `org.e2immu.*`。
maddi 由 [Bart Naudts](mailto:bart.naudts@codelaser.io) 在
[CodeLaser](https://codelaser.io) 开发，并且是并将保持开源。**分析器**采用
LGPL-3.0 协议。**注解**（`maddi-support`）——这也是你的代码在编译时唯一需要依赖的制品——
将采用宽松的开源协议发布，因此依赖它不会带来任何义务。
CodeLaser 的商业产品 Refactor 正是基于此引擎构建的；而该引擎将一直留在这里，并采用
此协议。欢迎提出问题、用例和批评——可以通过邮件或提交 Issue 联系我们。
(C) 版权所有 Bart Naudts，2020-2026。
标签：JS文件枚举, Kotlin, 不可变性分析, 云安全监控, 代码质量检测, 后台面板检测, 域名枚举, 编译器前端, 静态分析