2945e59bc2
The README listed 11 of fold's 17 detectors, never explained the confidence tiers every finding carries, did not mention the new exit code 2 / coverage reporting, and spent half its length on a performance roadmap. It now says what fold is, defines the five tiers (from include/fold/report/finding.hpp, including concrete-witness and latent), what "bounded" means after the loop-exit fix, a quick start, output formats and exit codes (0 none, 1 any unsuppressed finding, 2 unwritable report or any unanalysed translation unit), and links. The detector list defers to the complete table in docs/USAGE.md. The performance section moves to docs/architecture/performance.md, with one correction: the gold set was derived from fold's own reviewed output and is matched by detector kind and file, so it catches drift rather than measuring precision/recall independently. The lint pre-commit hook note moves to BUILD.md.
29 lines
1.6 KiB
Markdown
29 lines
1.6 KiB
Markdown
# Performance
|
|
|
|
Optimization is measurement-first and gate-guarded. Every candidate change runs
|
|
through the manifest-driven evaluation harness
|
|
(`tests/benchmarks/projects/*.json`), which enforces finding-fingerprint
|
|
stability, reviewed dispositions, wall-time and RSS regression baselines, and a
|
|
gold set (`bench/gold/`). The gold set was derived from fold's own reviewed
|
|
output and is matched by detector kind and file, so it catches drift; it is not
|
|
an independent precision or recall measure. A ledger of measured wins and
|
|
closed hypotheses is in
|
|
[the optimization loop](../research/optimization-loop-2026-07-30.md).
|
|
|
|
## Single-pass graph building
|
|
|
|
The one structural item on the roadmap is single-pass graph building. A source
|
|
scan currently parses each translation unit twice: once to build the project
|
|
call graph, and once to run detectors, because the detector pass consumes the
|
|
graph (cross-TU candidate expansion and summary priming). The planned change
|
|
collapses these into one parse per TU that produces graph contributions and runs
|
|
the intra-TU detectors in the same pass, keeping only light per-TU edge and
|
|
signature records, then runs the cross-TU-dependent closure after every TU. See
|
|
[the design](../research/single-pass-graph-design.md).
|
|
|
|
This is chosen over precompiled-header or module caching to preserve
|
|
portability: it introduces no Clang-version-locked serialized artifacts, no
|
|
SDK- or toolchain-locked module cache, and no `-std`/`-I`/`-D` flag-matching
|
|
bug surface, so every machine that consumes a `compile_commands.json` today
|
|
keeps working. Correctness parity for the deferred closure is policed by the
|
|
existing finding-fingerprint and gold gates.
|