v0.1.0

An evidence gate for open-source contributions: check whether the claims in a report correspond to anything real.

Install

pip install substantiate            # zero dependencies
pip install 'substantiate[treesitter]'   # recommended: resolves enum constants

Use

substantiate check report.md --repo ~/src/yourproject --ref v1.2.3

What it checks

	Checks	Resolved against
Tier 1	file paths, symbols, line numbers, version ranges, commit SHAs	the repository at --ref
Tier 2	CVE, CWE, RFC sections, link liveness	OSV, MITRE, RFC Editor (--online)

Symbols resolve as declarations, not as strings — a mention in a comment, or in the report's own quoted diff, does not substantiate itself.

Three things to know

It is a filter, not an oracle. A fabricated report citing only real files, real symbols and a real CVE passes every check. This removes the cheapest fiction, which is most of it today.

It never auto-closes. Exit status is 0 even when nothing resolves, deliberately, so it cannot be wired up as a gate that buries a real report. Automation that must branch on the outcome can opt into --exit-code and read the JSON.

The false positive is the enemy. Marking down an honest reporter costs them credibility they earned, so every miss the tool can explain carries a hint, and claims it has no standing to judge are skipped rather than reported.

Measured

Against curl's 206 published advisories — real, human-written, accepted as valid — 7.3% of tier-1 claims are unresolved and unexplained when checked at HEAD. Against 150 documents of curl's own documentation, 32.0%. Both numbers, including the one that is too high, are in the README with the reasons.

Run the benchmarks yourself:

python3 benchmarks/real_advisories.py ~/src/curl
python3 benchmarks/false_positives.py ~/src/curl docs --limit 150

Known gaps

• #3 — constants assembled by token pasting cannot be resolved without preprocessing
• #4 — tree-sitter drops enum constants near multi-line deprecation macros

Reports of genuine work marked down without a hint are bugs. Please open an issue with the report and the repository.