
Why codeint · How it works · Quick start · Guide · Reference · Programmatic API · Plugins · llms.txt
为什么选择 codeint
编码智能体能够非常快速地写出局部有效的代码。每个拉取请求都能通过测试和 linter,同时悄悄加入复制粘贴的代码块、冗余分支、更深的函数和纠缠的导入。经过数十次变更后,这种结构性拖累会不断累积,直到人类和智能体都慢下来。
codeint 直接从源代码的形态测量软件熵,让你在它复合增长之前看到它增长。它内置了针对 TypeScript/JavaScript、Rust、PHP、Dart 和 Python 的 Language 插件,以及用于其他语言和自定义 Metrics 的沙箱化 WebAssembly Plugins。
工作原理
四个独立的 Metrics,而非一个混合评分
codeint 并列报告四个 Metrics,绝不将它们合并为一个等级或指数(ADR 0003)。单一评分会在一个 Metric 改善而另一个恶化时掩盖回归。
- Erosion:环复杂度超过 10 的函数中,函数质量(cyclomatic_complexity * sqrt(source_lines))所占的份额。
- Duplication:Clone 组中的源代码行所占的份额(至少 75 个归一化 token 且 14 个不同的归一化 token,可捕捉重命名后的复制粘贴,同时忽略导入列表和数据表)。
- Verbosity:零误报的 Flagged 行或 Clone 组中的源代码行所占的份额。
- Import cycles:至少处于一个运行时 Import 循环中的模块所占的份额。
基于基线的棘轮式执行
- 2023 年前的 Reference 范围:每种内置语言都针对 20 个固定在 2023-01-01 之前的公共仓库进行校准(第 10 到第 90 百分位),因此原始数字有可靠的上下文。
- 严格的 Source-set 分离:每个文件都属于 production、test、generated 或 vendored,因此测试夹具和生成代码绝不会扭曲 Production 比率。
- Budgets 和 Regressions:Budgets 在 codeint check 中限制绝对熵,而 codeint diff <base> 让每个拉取请求对照其 Git merge-base 进行棘轮式约束。
- 无版本解析:内置 Language 插件解析各语言家族的现代超集,无需在 codeint.json 中固定语言版本。
为速度和安全而构建
codeint 用安全的 Rust 编写(#![forbid(unsafe_code)],ADR 0004),围绕两个清晰的接缝:Language 插件将源文件降为语言中立的 Code 模型,Metric 插件在该模型上计算 Metrics 和 Findings。它直接从 Git 对象读取跟踪的文件和提交历史,而不修改你的工作树,在 Apple Silicon 上扫描 laravel/framework(132k Production 行)用时 0.47s,扫描 flutter/packages(434k Production 行)用时 3.68s。第三方 WebAssembly Plugins 运行时强制进行 SHA-256 验证,零宿主能力,并具有可配置的内存和时间上限。
阅读 docs/guide/philosophy-and-architecture.md 了解完整架构图和设计理由。
校准的 Reference 范围
每种语言或 Vue 代际的 20 个 2023 年前开源仓库的第 10 到第 90 百分位(ADR 0008、ADR 0010、ADR 0011、ADR 0012、ADR 0013、ADR 0014、ADR 0015):
| 语言 | 侵蚀 | 重复 | 冗余度 | 循环导入 |
|---|---|---|---|---|
| TypeScript / JavaScript | 35.2% 至 60.0% | 1.7% 至 34.6% | 1.8% 至 34.7% | 0.0% 至 30.8% |
| Vue 2 ( .vue ) | 2.0% 至 45.2% | 3.6% 至 19.2% | 3.6% 至 19.2% | 0.0% 至 11.4% |
| Vue 3 ( .vue ) | 1.9% 至 38.8% | 2.3% 至 34.5% | 2.4% 至 34.6% | 0.0% 至 7.7% |
| Rust | 38.0% 至 64.2% | 5.0% 至 32.5% | 6.0% 至 32.9% | 2.1% 至 50.6% |
| PHP | 5.5% 至 67.7% | 4.1% 至 29.0% | 4.2% 至 29.2% | 0.0% 至 10.7% |
| Dart | 4.7% 至 41.9% | 7.3% 至 25.6% | 8.0% 至 25.9% | 7.3% 至 52.4% |
| Python | 14.4% 至 62.4% | 1.2% 至 20.1% | 1.4% 至 20.4% | 0.0% 至 32.1% |
各语言的规则和示例仓库运行耗时请参见 docs/guide/languages.md。
快速开始
在 macOS 或 Linux、Windows 上安装独立二进制文件,或直接使用 npx 运行:
curl -fsSL https://github.com/avidianity/codeint/releases/latest/download/install.sh | bash
irm https://github.com/avidianity/codeint/releases/latest/download/install.ps1 | iex
npx codeint check
在任意 Git 仓库中运行 codeint:
codeint init
codeint check
codeint diff main
codeint trend
- codeint init 会生成一个带有版本化 $schema 的初始 codeint.json。
- codeint check 会度量工作区,并打印每个 Metric 及其 Findings。
- codeint diff main 会将工作区与 main 的 merge-base 进行比较,并在出现 Regression 时失败。
- codeint trend 会打印最近主线提交中每个 Metric 的情况。
也可以通过 JavaScript/TypeScript(npm install codeint)或 Rust(codeint-cli)以编程方式调用 codeint:
import { check, diff } from "codeint";
const report = await check();
const prDiff = await diff({ base: "main" });
文档
- 指南:模块化的逐步讲解,涵盖 Philosophy and Architecture、Getting Started、Configuration (codeint.json)、Built-in Languages,以及 CI and GitHub Actions。
- 参考:经过测试的参考文档,涵盖每个命令、标志、退出码、报告格式(toon、json、sarif、markdown)以及 codeint.json 的每个键。
- 编程 API:JavaScript/TypeScript SDK 和 Rust 库 API。
- 插件:构建、哈希、声明和测试外部 WebAssembly Language 和 Metric 插件。
- 术语表:本页所有领域术语的规范定义。
- llms.txt:面向编码代理和 LLM 工具的紧凑文档索引。
开发
你需要通过 rustup 安装的 Rust(rust-toolchain.toml)、Node.js 24 和 npm(package.json),以及位于 PATH 中的 gitleaks 和 lychee。
npm ci
npx lefthook install
cargo test --workspace --locked
代理和人员遵循相同的规则:从 .rules 开始。仓库检查项列于 docs/checks/README.md。