Jacobious52/veritas
GitHub: Jacobious52/veritas
veritas是一款用于AI编写和修改的软件的Tree-sitter测试预言机，提供自动化测试和AI辅助修复。
Stars: 1 | Forks: 0
# veritas
`veritas` 是一个用于 AI 编写和 AI 修改的软件的 Tree-sitter 测试预言机。
它是一个用于突变测试、属性测试、模糊测试、覆盖率反馈、语料库回放、差异行为检查和跨 Rust、Go、Python、TypeScript/JavaScript 以及未来 Tree-sitter 语言插件的进化分析的 CLI 框架。
它回答了普通测试运行经常忽略的问题：
`veritas` 将更改的代码映射到验证目标，生成可审查的框架，在预算下运行范围测试，并编写 CI 友好的报告以及 AI 准备的修复提示。
默认路径是确定的，不调用 LLM。在 `veritas` 仍拥有执行范围、预算和工件写入的情况下，可以启用可选的外部规划器钩子以进行 AI 辅助规划。
项目网站：[Jacobious52.github.io/veritas](https://jacobious52.github.io/veritas/)
## 为什么感觉不同
- 它为 AI 代理提供了一个具体的下一个测试队列，而不是模糊的“添加更多测试”警告。
- 它通过 `.veritas/` 工件和 `veritas cleanup` 保持生成的测试可审查和可删除。
- 它围绕一个通用的插件合同构建：Rust、Go、Python 和 TypeScript/JavaScript 今天工作，未来的语言可以通过 Tree-sitter 符号、行范围、命令预算、突变活动、回放和评分重用相同的报告。
- 它是为更大的仓库设计的：更改目标选择、包/工作区意识、命令预算、可选的 Rust cgroup/systemd 限制、阶段时间遥测、CI 配置文件、基准测试固定值和外部金丝雀。
## 安装
预构建的 Linux 和 macOS 二进制文件：
```
curl -fsSL https://github.com/Jacobious52/veritas/releases/latest/download/install.sh | sh
```
安装特定版本：
```
curl -fsSL https://github.com/Jacobious52/veritas/releases/latest/download/install.sh | VERSION=v0.1.1 sh
```
Cargo 回退：
```
cargo install veritas-cli --locked
```
从 Git 仓库：
```
cargo install --git https://github.com/Jacobious52/veritas veritas-cli --locked
```
本地开发：
```
git clone https://github.com/Jacobious52/veritas.git
cd veritas
cargo build --workspace
cargo run -p veritas-cli -- scan
```
可选工具：
```
# Go verification
go version
# Python verification
python3 --version
python3 -m coverage --version
# TypeScript/JavaScript verification
bun --version
# Rust coverage, only used when coverage_enabled = true
cargo install cargo-llvm-cov
```
## 快速入门
初始化仓库：
```
veritas init --ci --agent-instructions
```
在更改的分支上使用 `veritas`：
```
veritas review-ai
veritas verify --changed --profile ci
veritas score
veritas repair-prompt
veritas report --format markdown
```
验证特定目标：
```
veritas verify --lang rust --target src/lib.rs
veritas verify --lang go --target ./pkg/invoice
veritas verify --lang python --target invoice.py
veritas verify --lang typescript --target src/invoice.ts
```
解释和推广发现：
```
veritas explain
veritas promote-repro --dry-run
veritas evolve --dry-run
veritas evolve --index 0
veritas evolve --index 0 --evaluate
veritas replay-corpus --dry-run
veritas accept-quality-baseline
veritas accept-baseline --id
veritas cleanup
```
有用的运行看起来像：
```
mutation survived: refund_cents <= available_cents -> refund_cents < available_cents
fuzz seed saved: " 12.34 " reproduced parser drift
replay drift: AuthorizeRefund("support", 500) changed behavior
next agent step: promote assertion candidate, rerun, keep only if the mutant dies
```
## 文档
- [AI 代理指南](docs/ai-agents.md): 编码代理的复制粘贴说明和审查循环。
- [安装指南](docs/install.md): 发布二进制文件、cargo、git 和 GitHub Actions 设置。
- [AI 验证循环](docs/ai-verification-loops.md): 可感知的 Rust、Go、Python、TypeScript/JavaScript 和代理循环示例。
- [项目网站](docs/index.html): GitHub Pages 落地页和公开概述。
- [进化演示](docs/evolution.md): 来自 Go 进化固定值的真实先/候选/后循环。
- [生产指南](docs/production.md): 大型仓库 Go/Rust 操作、预算、CI 策略和主机安全。
- [架构](docs/architecture.md): 工作区布局、插件合同、工件和规划器模型。
- [插件 SDK](docs/plugin-sdk.md): 语言插件合同和 Python 插件路径。
- [信心指南](docs/confidence.md): 固定层、种子示例和外部金丝雀。
- [发布](docs/releasing.md): 通过 GitHub Actions 在 crates.io 上发布。
## CLI 表面
```
veritas scan
veritas init --ci --agent-instructions
veritas review-ai
veritas review-packet
veritas verify --changed
veritas verify --changed --profile ci
veritas verify --lang rust --target path/to/file.rs
veritas verify --lang go --target ./pkg/foo
veritas verify --lang python --target path/to/file.py
veritas verify --lang typescript --target path/to/file.ts
veritas generate --kind property --target path
veritas generate --kind fuzz --target path
veritas run
veritas report --format markdown
veritas report --format sarif
veritas report --format junit
veritas mutants list --lang rust --target src/lib.rs --diffs
veritas mutants list --lang rust --target . --format json --shard-index 0 --shard-count 4
veritas mutants list --lang go --target . --format json --domain database
veritas mutants run --lang rust --target src/lib.rs --from-campaign .veritas/mutations/rust_campaign.json --status lived
veritas mutants merge .veritas/mutations/shard-*/rust_campaign.json --output .veritas/mutations/rust_merged.json
veritas next --explain
veritas score
veritas score --mode all
veritas badge
veritas accept-quality-baseline
veritas replay-corpus
veritas repair-prompt
veritas agent-instructions --agent codex
veritas explain
veritas promote-repro
veritas promote-repro --index 0
veritas promote-regression
veritas promote-regression --index 0
veritas evolve --dry-run
veritas evolve --index 0
veritas evolve --all-selected
veritas evolve --all-selected --evaluate
veritas conformance
veritas accept-baseline --id
veritas accept-baseline --all
veritas bench --root examples
veritas bench --root examples --format json
veritas bench --root examples --suite veritas-confidence-suite.toml --format json
veritas cleanup
veritas cleanup --dry-run
```
## 功能
语言和插件模型：
- 今天提供 Rust、Go、Python 和 TypeScript/JavaScript 插件
- Tree-sitter 发现提供符号、方法、行范围和风险表面，其中语法支持它们
- 每个插件拥有特定语言的发现、生成的工件、命令执行、覆盖率、回放编译和突变运算符
- 核心拥有共享评分、策略、回放清单/结果、基线、语料库条目、突变活动记录、进化套件、SARIF/JUnit/Markdown 渲染和 AI 修复提示
- 未来的语言插件可以添加自己的 Tree-sitter 语法并将其映射到相同的目标/报告/工件合同
更改目标验证：
- 读取 git 差异、暂存更改和未跟踪文件
- 当行范围可用时，将更改的行映射到发现的 Rust/Go/Python/TypeScript/JavaScript 符号
- 将包命令范围限制为更改的包和存在的图数据中选定的反向依赖项
- 使用更改摘要和验证指南编写 AI 审查工件
Rust 验证：
- 通过 `Cargo.toml` 检测包和虚拟工作区
- 使用 Tree-sitter 发现公共免费函数和公共方法
- 为受支持公共免费函数编写包本地的 `proptest` 集成框架，包括允许它们的签名时无恐慌和确定输出属性
- 使用可配置的工作、测试线程、命令超时和可选 systemd 范围限制运行 `cargo test --all-targets`
- 运行 AST 范围突变探测，包括比较、边界、异步/任务、同步、数据库、重试、可测试性和脆性探测，然后从行为保留的脆性探测中单独报告正确性幸存者
- 当启用时收集 `cargo llvm-cov --summary-only`
- 在 `.veritas/symbol_graph/` 下编写 Rust 符号图工件
Go 验证：
- 检测一个或多个 `go.mod` 根
- 使用 Tree-sitter 发现导出的函数和方法
- 使用 `go list -json ./...` 构建包图
- 运行针对选定包的可配置 `go test` 命令以及可选的反向依赖项
- 发现手写和生成的模糊目标
- 为支持 Go 模糊参数类型和边缘情况种子行的导出免费函数编写 `testing.F` 模糊框架
- 在限制和超时内通过有界调度程序运行相关的 `go test -run=^$ -fuzz=...` 目标
- 将构建标签应用于 Go 列表、测试、模糊、覆盖率和突变命令
- 运行 AST 范围突变探测，包括比较、nil/error 分支、返回默认值、布尔连接符、算术和位运算符、赋值运算符、增量/减量语句、一元否定、循环控制、文字翻转、自我赋值、goroutine/defer/context 生命周期、锁、事务、租户/幂等字符串、重试/退避接缝和域标签风险表面
- 编写包图、包意识和符号图工件
Python 验证：
- 通过 `pyproject.toml` 或 Python 源根检测 Python 项目
- 使用 Tree-sitter 发现函数并发出符号图工件
- 当项目首选 pytest 并且已安装时，运行 `python3 -m pytest -q`，否则回退到 `python3 -m unittest discover`
- 当 `hypothesis` 和 `pytest` 都已安装时，编写可审查的 Hypothesis 属性候选者并执行它们，否则记录跳过的命令
- 当启用时通过 `coverage.py` 收集覆盖率
- 运行受支持比较、布尔连接符、默认返回、数据库字符串、异步/测试性接缝和脆性探测的可执行源范围突变检查
- 支持原始单参数和多参数公共函数的回放案例
TypeScript/JavaScript 验证：
- 通过 `package.json`、`tsconfig.json`、`jsconfig.json` 或 JS/TS 源根检测项目
- 使用 TypeScript、TSX 和 JavaScript 的 Tree-sitter 语法发现函数、类方法和箭头/函数表达式导出
- 使用签名、行范围、调用提示、参数和风险标签发出符号图工件
- 为受支持导出免费函数编写可执行的 Bun 属性检查，带有用于属性质量评分的确定/无抛出标记
- 运行源范围突变检查，包括比较、严格相等、布尔守卫、默认返回和字符串归一化
- 执行受支持原始导出免费函数的批量差异回放
- 通过 Bun、npm、pnpm 或 Yarn 运行项目测试命令；当可用时，Veritas 生成的 TS/JS 探测使用 Bun 并在运行时缺失时记录跳过的命令
- 收集可选 Bun lcov 覆盖率并将未覆盖的 TS/JS 范围转换为 AI 可读的断言焦点
- 突变 Tree-sitter 支持的 TS/JS 构造，包括比较、相等、布尔守卫、可选链、空值合并、异步/await、对象展开、环境/配置读取、数组边界、HTTP 方法、默认值和字符串归一化
报告和工件：
- 渲染 Markdown、JSON、SARIF 2.1.0 和紧凑的 JUnit XML
- 将最新报告保存到 `.veritas/report.json`
- 通过 `veritas mutants list` 列出和预览候选突变体，而无需执行测试，包括 JSON 输出、字节范围跨度、差异预览、分片/过滤器控制、风险注释和建议测试
- 从 `veritas-bench.toml` 运行基准测试套件，在临时项目副本中，并评分预期发现、命令、阈值和指标
- 在 `.veritas/report.json` 中报告突变评分归属/趋势、每个突变活动记录、每个运行幸存者差异/日志、断言候选者、语料库条目/回放、差异回放案例、预算跳过/超时、属性测试强度、模糊执行和持久化重播计数
- 使用 `veritas score` 总结当前信心和基线差异
- 编写 API 签名基线和接受发现基线
- 编写覆盖率反馈、突变反馈、断言候选者、语料库条目、回放清单/结果、预算计划、突变趋势 JSON、突变活动 JSON、在 `.veritas/mutations/runs/` 下的可尾随突变运行目录、进化候选套件和生成结果，包括适应性/选择信号、重播注释、候选验证补丁、回归注释、进化计划、推广回归脚手架和推广注释
- `veritas evolve --index --evaluate` 和 `--all-selected --evaluate` 现在发出先/后证明工件并删除回归或失败评估的生成候选者
- `veritas conformance` 检查插件合同中的稳定 ID、源相关路径、函数符号、行范围和现有目标文件
- 使用 `veritas cleanup` 清理生成的工件
规模和性能态势：
- 在全仓库扫描之前验证更改分支；`--changed` 是默认 CI 配置文件路径
- Go 包图和 Rust 工作区发现保持命令范围接近编辑表面
- 命令预算、模糊上限、突变上限、包上限和政策过滤器可以按仓库配置
- Rust 测试和覆盖率命令可以在 systemd 范围内运行，在共享主机上具有 CPU 和内存限制
- 目标发现编写 `.veritas/cache/_targets.json` 并将缓存命中作为 `target_cache` 工件报告，以便稳定的大仓库扫描可以避免重复的 Tree-sitter 发现
- 每个报告记录发现、生成、测试执行、覆盖率、回放、合成和总运行时间的阶段时间
- 基准测试套件和外部金丝雀跟踪 Veritas 是否在小型固定值之外仍然有效
- 近期性能目标是插件安全的并发、自适应突变采样以及跨运行可重用的语料库/基线数据
CI 行为：
- `.github/workflows/ci.yml` 在拉取请求和推送到 `main` 时运行格式、工作区测试、clippy 和 Rust/Go/Python/TypeScript 固定值扫描/验证烟雾检查
- CI 还在 Rust、Go、Python 和 TypeScript 固定值上运行 `veritas conformance`
- `veritas verify --profile ci` 假定 `--changed`
- CI 配置文件禁用完整覆盖率，收紧包/模糊/突变/时间上限，并默认启用基于策略的失败
- 策略过滤器可以选择严重性、语言、工件类型和目标风险
- 接受发现 ID 支持仅新发现的 CI 行为
消费者 GitHub Actions 入门：
```
name: Veritas
on: [pull_request]
jobs:
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
with:
fetch-depth: 0
- run: curl -fsSL https://github.com/Jacobious52/veritas/releases/latest/download/install.sh | sh
- run: veritas verify --changed --profile ci
- run: veritas repair-prompt --github-step-summary
if: always()
```
## 配置
在目标仓库中创建 `veritas.toml` 或 `.veritas.toml`：
```
[veritas]
budget_seconds = 120
write_generated_tests = true
fail_on_generated_test_failure = true
fail_on_findings = false
[planner]
mode = "deterministic"
# mode = "external_llm"
# command = "my-veritas-planner"
# fail_on_error = false
[policy]
fail_on_severity = "error"
fail_on_languages = []
fail_on_artifact_kinds = []
fail_on_target_risks = []
min_mutation_score = 70
min_mutation_efficacy = 70
min_mutant_coverage = 80
[mutation]
# Shared by language plugins. Operator names are intentionally generic so
# future Tree-sitter plugins can map their own AST mutations onto the same
# campaign/report model.
enabled_operators = []
disabled_operators = []
enabled_domains = []
disabled_domains = []
include_paths = []
exclude_paths = []
include_symbols = []
exclude_symbols = []
include_target_ids = []
exclude_target_ids = []
include_mutant_ids = []
exclude_mutant_ids = []
report_filtered = false
dry_run = false
max_mutants = 8
disable_test_selection = false # set true to run the broader verification package set for every mutant
baseline_timing = false # set true to derive mutation timeout metadata from the baseline test duration
workers = 1 # Rust/Go use isolated temp roots when workers > 1; keep small repos serial by default
isolation_exclude_paths = [] # extra names or relative paths to skip in isolated mutation copies
test_cpu = 1
timeout_coefficient = 1
timeout_min_seconds = 10
timeout_max_seconds = 120
shard_index = 0
shard_count = 1
output_statuses = [] # e.g. ["lived", "not_covered", "timed_out"]
[plugins.rust]
property_framework = "proptest"
command_timeout_seconds = 120
coverage_enabled = false
coverage_timeout_seconds = 120
cargo_jobs = 1
test_threads = 1
systemd_scope = false
memory_max = "4G"
cpu_quota = "200%"
[plugins.go]
fuzz_seconds = 10
fuzz_existing = true
fuzz_concurrency = 2
coverage_enabled = false
reverse_dependency_depth = 1
max_fuzz_targets = 20
command_timeout_seconds = 120
max_packages = 64
max_mutants = 8
build_tags = []
```
默认情况下，突变运行选择插件可以证明的最窄包级测试命令。Rust 使用符号/包所有权；Go 使用包图加上反向依赖项。当仓库具有全局集成固定值、隐藏的构建标签或跨包副作用使得广泛的突变命令比本地选择更安全时，设置 `disable_test_selection = true`。
突变过滤器首先评估为包含过滤器，然后评估为排除过滤器。模式接受 `exact:...`、`glob:...` 或 `*` 通配符，以及当活动插件支持时 `regex:...`；旧的前缀模式保留子串匹配。对于 `lang:path:symbol` 目标使用 `include_target_ids` / `exclude_target_ids`，对于稳定的每个突变 ID 使用 `include_mutant_ids` / `exclude_mutant_ids`。在 Rust、Go、Python 或 TypeScript/JavaScript 函数内部添加 `veritas:skip-mutation` 以抑制本地突变，并在筛选候选者应作为跳过记录出现时设置 `report_filtered = true`。
对于共享机器，除非需要，否则禁用 Rust 覆盖率，并启用 systemd 范围限制：
```
[plugins.rust]
coverage_enabled = false
systemd_scope = true
cargo_jobs = 1
test_threads = 1
memory_max = "4G"
cpu_quota = "200%"
```
## 开发
运行工作区检查：
```
cargo fmt --all
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
```
运行固定值检查：
```
cargo run -p veritas-cli -- scan --root fixtures/sample-rust
cargo run -p veritas-cli -- verify --root fixtures/sample-rust --lang rust --target src/lib.rs
cargo run -p veritas-cli -- cleanup --root fixtures/sample-rust --dry-run
cargo run -p veritas-cli -- verify --root fixtures/rust-workspace --lang rust --target .
cargo run -p veritas-cli -- scan --root fixtures/sample-go
cargo run -p veritas-cli -- verify --root fixtures/sample-go --lang go --target .
cargo run -p veritas-cli -- verify --root fixtures/go-multimodule --lang go --target services/billing/pkg/invoice
```
运行更丰富的示例床：
```
cargo test --manifest-path examples/rust-invoice/Cargo.toml
cargo run -p veritas-cli -- verify --root examples/rust-invoice --lang rust --target src/lib.rs
(cd examples/go-invoice && go test ./...)
cargo run -p veritas-cli -- verify --root examples/go-invoice --lang go --target .
cargo test --manifest-path examples/rust-commerce/Cargo.toml
cargo run -p veritas-cli -- verify --root examples/rust-commerce --lang rust --target src/lib.rs
(cd examples/go-api-service && go test ./...)
cargo run -p veritas-cli -- verify --root examples/go-api-service --lang go --target .
cargo test --manifest-path examples/rust-mutation-score/Cargo.toml
cargo run -p veritas-cli -- verify --root examples/rust-mutation-score --lang rust --target src/lib.rs
(cd examples/go-mutation-score && go test ./...)
cargo run -p veritas-cli -- verify --root examples/go-mutation-score --lang go --target .
cargo test --manifest-path examples/rust-risk-suite/Cargo.toml
cargo run -p veritas-cli -- verify --root examples/rust-risk-suite --lang rust --target src/lib.rs
(cd examples/go-risk-suite && go test ./...)
cargo run -p veritas-cli -- verify --root examples/go-risk-suite --lang go --target .
cargo run -p veritas-cli -- --root examples bench
cargo run -p veritas-cli -- --root examples bench --format json
```
示例项目故意包含隐藏的假设，而其手写测试通过，因此它们对于验证生成的属性/模糊工件和报告输出很有用。
运行具体的进化演示：
```
cargo run -p veritas-cli -- --root examples/go-evolution-loop verify --lang go --target .
cargo run -p veritas-cli -- --root examples/go-evolution-loop score
cargo run -p veritas-cli -- --root examples/go-evolution-loop evolve --dry-run
```
种子固定值以 `14` 个进化候选者、`12` 个选定候选者、`4` 个幸存突变体和 `55` 个信心分数开始。将顶级ParseInvoiceTotal` 候选者提升到拥有的断言将突变分数从 `58%` 提高到 `91%`，删除幸存突变体，并将信心分数提高到 `98`。有关确切的先/候选/后命令和工件路径，请参阅 [docs/evolution.md](docs/evolution.md)。
当您想要对真实固定仓库的信心时运行外部金丝雀烟雾检查：
```
./scripts/run-canaries.sh smoke
./scripts/run-canaries.sh large-smoke
./scripts/run-canaries.sh verify-fast
./scripts/run-canaries.sh verify
```
相同的金丝雀每周在 GitHub Actions 中运行一次，并可以从 `External Canaries` 工作流程手动启动。`large-smoke` 添加来自 `canaries/pinned-repos.json` 的固定更大的 Rust、Go 和 Python 仓库，默认情况下保持扫描-only。每个运行都编写 `target/external-fixtures/reports/canary-dashboard.md`，其中包含扫描/验证层和趋势差异。当金丝雀仪表板在错过阈值时应该失败 CI 时，设置 `VERITAS_CANARY_MIN_TIER`、`VERITAS_CANARY_MIN_CONFIDENCE` 或 `VERITAS_CANARY_MAX_FINDINGS`。
当您想要规模/性能信号时运行大型仓库基准测试：
```
./scripts/run-large-repo-benchmarks.py --manifest benchmarks/large-repos.toml --mode scan
./scripts/run-large-repo-benchmarks.py --manifest benchmarks/large-repos.toml --mode mutation-list
./scripts/run-large-repo-benchmarks.py --manifest benchmarks/large-repos.toml --mode mutation-inventory
./scripts/run-large-repo-benchmarks.py --manifest benchmarks/large-repos.toml --mode changed-only
```
此通道通过 SHA 锁定真实的 Rust、Go、Python 和 TypeScript/JavaScript 仓库，测量 Tree-sitter 发现、受支持的 capped 突变预览、文件级突变清单和仅更改的 AI 代理验证，然后编写 `target/large-repo-benchmarks/reports/large-repo-dashboard.md` 以及 JSON 趋势工件。TypeScript 通道目前包括 `axios/axios` 以进行扫描和突变清单规模。使用 `mutation-list` 进行快速有界样本；当您想要仓库级别的唯一突变机会、cap-hit 路径和域/运算符分布计数时，使用 `mutation-inventory`。
标签：AI软件验证, Anchore, Go, Python, Ruby工具, Rust, TLS抓取, Tree-sitter, TypeScript/JavaScript, 代码修复, 代码审查, 代码测试, 可视化界面, 属性测试, 开源框架, 持续集成, 无后门, 日志审计, 测试优化, 测试报告, 测试管理, 测试覆盖率, 突变测试, 网络流量审计, 行为差异检查, 覆盖率反馈, 语料库回放, 软件安全, 进化分析, 逆向工具, 通知系统