# fold

Bounded symbolic static analysis for C++: dead-branch and hazard detection
(null dereference, division by zero, integer overflow, out-of-bounds, and more),
clone and equivalence detection, and taint tracking, built on Clang LibTooling
and the Z3 solver. Rust (HIR), Swift and binary scan modes also exist; the Rust
detectors are heuristic today.

Every finding carries a confidence tier that says how it was established:

| Tier | Meaning |
| --- | --- |
| `concrete-witness` | A fuzzer ran the solver's witness under a sanitizer and produced a correlated crash. |
| `proved` | An exact bounded model proved it: SAT for a hazard witness, or UNSAT for a negated invariant. |
| `latent` | Proved inside the function, but only reachable if a caller supplies a value the callee never guards. |
| `heuristic` | Some part of the model was over-approximated. |
| `syntactic` | An AST pattern or hash match only. |

"Bounded" is literal: loops are unrolled to a fixed depth, and a condition that
depends on a loop's exit is never reported as proved. The contract behind each
tier is in [docs/research/soundness.md](docs/research/soundness.md).

## Quick start

```sh
./setup.sh release     # needs LLVM/Clang 18+ and libz3 headers; Conan handles the rest
fold scan --compile-db compile_commands.json \
  --detectors null-deref --detectors div-by-zero \
  --format sarif --output findings.sarif
fold grep "null pointer" findings.sarif --field message --ignore-case
```

Per-platform install lines and a Docker validation harness are in
[BUILD.md](BUILD.md).

Output formats are `sarif`, versioned `findings-json`, and `markdown`. Both
machine formats record which translation units were analysed. A scan exits `0`
with no findings, `1` with any unsuppressed finding, and `2` when a report could
not be written or any translation unit was not analysed (compile errors,
frontend failure, crash, timeout): no findings from an incomplete scan is not
evidence of no bugs.

## Documentation

- [Usage](docs/USAGE.md): the full CLI (scan modes, scopes, confirmation,
  fuzzing), every detector with its CWE and method, MCP/LSP, and project
  evaluation.
- [MCP tools](docs/mcp-tools.md) and [compatibility](docs/compatibility.md)
  (deprecated names and removal criteria).
- [Positioning](docs/positioning.md) and [prior art](docs/research/prior-art.md):
  how fold relates to other analyzers.
- [Performance](docs/architecture/performance.md): the evaluation gates and the
  single-pass graph-building plan.
- [Architecture](docs/architecture/) and [research](docs/research/) notes.

## License

GPL-3.0-only