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.
1.6 KiB
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.
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.
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.