From 9ed338d40fe4c6811f5816e1a80e5bf6432facbe Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 10 Oct 2026 21:53:40 +0530 Subject: [PATCH 1/2] ci(coverage): make the per-file coverage gates real on v2.x (#396) Backport of #522. The gate never checked anything: the instrumented test run failed (lock tests could not find pid_ns_helper), the report was empty, and every module was skipped with a warning. It also parsed `--text` output, which has no per-file percentages. Run the suite with branch coverage on a pinned nightly, fail on a test failure, and check line and branch floors per file from coverage-thresholds.toml (measured on main, less one point) with scripts/coverage_gates.py. Port the v3 tests that apply to v2.x: the WAL fact-size test now reaches the limit, an entry claiming over 1M facts ends replay, a WAL writer in a missing directory fails, and two threads missing one cache page share one copy (that path was reached only by a race, so the gate flapped). Part of #396. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012wXxZguv7PgKQjMMH4yJ5h --- .github/workflows/coverage-gates.yml | 55 +++++++++----------- CHANGELOG.md | 1 + CLAUDE.md | 2 +- README.md | 2 +- ROADMAP.md | 2 +- coverage-thresholds.toml | 76 ++++++++++++++++++++++++++++ docs/TEST_COVERAGE.md | 13 +++-- scripts/coverage_gates.py | 61 ++++++++++++++++++++++ src/storage/cache.rs | 55 ++++++++++++++++++++ src/wal.rs | 42 +++++++++++---- 10 files changed, 260 insertions(+), 49 deletions(-) create mode 100644 coverage-thresholds.toml create mode 100644 scripts/coverage_gates.py diff --git a/.github/workflows/coverage-gates.yml b/.github/workflows/coverage-gates.yml index 4a4dc81f0d..ae7e23e90f 100644 --- a/.github/workflows/coverage-gates.yml +++ b/.github/workflows/coverage-gates.yml @@ -2,9 +2,9 @@ name: Coverage Gates on: push: - branches: ["main"] + branches: [ "main", "v[0-9]*" ] pull_request: - branches: ["main"] + branches: [ "main", "v[0-9]*" ] permissions: contents: read @@ -17,41 +17,32 @@ jobs: steps: - uses: actions/checkout@v4 - - name: Install Rust stable - uses: dtolnay/rust-toolchain@stable + # Branch coverage needs nightly. Pinned so a toolchain update cannot move + # the numbers under an unrelated PR; bump it on purpose and re-measure. + - name: Install Rust nightly + uses: dtolnay/rust-toolchain@master with: + toolchain: nightly-2026-10-01 components: llvm-tools-preview - name: Install cargo-llvm-cov uses: taiki-e/install-action@cargo-llvm-cov - - name: Generate coverage (text) - run: cargo llvm-cov --text 2>&1 > cov_text.txt || true + - name: Build the pid_ns_helper example used by lock tests + # cargo-llvm-cov puts test binaries where the lock tests' lookup of + # examples/ next to the test binary fails; same workaround as + # llvm-cov.yml. + run: cargo build --examples --target-dir /tmp/minigraf-lock-test-examples + # A failing test fails the job: a partial report must never be gated. + - name: Run the tests with branch coverage + env: + MINIGRAF_PID_NS_HELPER: /tmp/minigraf-lock-test-examples/debug/examples/pid_ns_helper + run: cargo llvm-cov --branch --no-report + + - name: Summarize coverage + run: cargo llvm-cov report --branch --json --summary-only --output-path coverage.json + + # Thresholds come from coverage-thresholds.toml (#396). - name: Check per-module thresholds - run: | - FAIL=0 - check_module() { - local file=$1 threshold=$2 - local pct - pct=$(grep "$file" cov_text.txt | grep -oP '\d+\.\d+(?=%)' | tail -1) - if [ -z "$pct" ]; then - echo "WARNING: $file not found in coverage report" - return 0 - fi - if python3 -c "import sys; sys.exit(0 if float('$pct') >= $threshold else 1)"; then - echo "OK: $file: ${pct}% >= ${threshold}%" - else - echo "FAIL: $file: ${pct}% < ${threshold}%" - return 1 - fi - } - # Thresholds from coverage-thresholds.toml - check_module "wal.rs" 75 || FAIL=1 - check_module "db.rs" 70 || FAIL=1 - check_module "persistent_facts" 70 || FAIL=1 - check_module "btree_v6" 65 || FAIL=1 - check_module "executor.rs" 75 || FAIL=1 - check_module "evaluator.rs" 75 || FAIL=1 - check_module "stratification" 75 || FAIL=1 - exit $FAIL + run: python3 scripts/coverage_gates.py coverage-thresholds.toml coverage.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 0161f4b603..4938b401af 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Tests - **Weekly soak test at scale (#392).** `tests/soak_test.rs` grows a file-backed database to 10M live facts in batches of 1–2,000 facts, then churns it for the rest of a 5-hour budget at 50 transactions a second (retracts, re-asserts, long histories on 32 hot entities), with a checkpoint every 20–200 transactions and a reopen every 2–10 minutes. Samples are checked against a reference through EAVT, entity and attribute, AVET, AEVT, `:as-of` and the transaction counter, with a full scan in a child process at 2M facts. RSS after a reopen is bounded relative to the fact versions held. Metrics go to a JSON-lines file that `.github/workflows/soak.yml` uploads weekly, alternating `main` (Saturday) and `v3` (Sunday). On v2.x no transaction writes two values of one entity and attribute, because of the known issue #371; the v3 workload fails here. It also checkpoints every 100–1,000 transactions and samples `:as-of` less, since both cost time in the database size on v2.x. `soak_short` runs the driver at 20K facts in the normal suite. +- **Coverage gates that gate (#396).** The per-module gate in `coverage-gates.yml` had never checked anything: the instrumented test run failed (the lock tests could not find `pid_ns_helper`), the report it grepped was empty, and every module was skipped with a warning, so the job passed. It also read `cargo llvm-cov --text`, which has no per-file percentages. The job now runs the whole suite with branch coverage on a pinned nightly, fails if any test fails, and checks each file's line and branch percentage against `coverage-thresholds.toml` with `scripts/coverage_gates.py`; a file missing from the report, or without branch data, fails. The floors are the measured values less one point, for the WAL, `db.rs`, `graph/storage.rs`, the storage files (except the v5 B+tree kept for migration) and the evaluator, executor and stratification. New tests check that WAL replay stops at an entry whose first fact is over 10 MB (the old test changed bytes inside the fact and never reached the limit) or that claims more than 1M facts, that a WAL writer cannot be opened in a missing directory, and that two threads missing the same page in the page cache get the one cached copy (before, only a lucky race reached that path). ## v2.0.4 — 2026-10-08 diff --git a/CLAUDE.md b/CLAUDE.md index 9c0d7e9e91..22d8885b11 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -174,7 +174,7 @@ Auto-migrates v1/v2/v3/v4/v5/v6 → v7 on open/checkpoint. ## Test Coverage -**1234 tests** (1225 passing, 9 ignored; unit + integration + doc). +**1237 tests** (1228 passing, 9 ignored; unit + integration + doc). See `docs/TEST_COVERAGE.md` for the full per-file breakdown. **Testing conventions** — see the Testing Conventions section below before writing any tests. diff --git a/README.md b/README.md index 2b2160260a..352ad4bd14 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,7 @@ let r2 = pq.execute(&[("tx", BindValue::TxCount(2)), ("entity", BindValue::Entit ```bash cargo run # interactive Datalog REPL -cargo test # run 1234 tests +cargo test # run 1237 tests cargo run < demos/demo_recursive.txt # recursive rules demo ``` diff --git a/ROADMAP.md b/ROADMAP.md index 4bad7607eb..8c214b10a6 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -81,7 +81,7 @@ Scope — release-gate testing and documentation: - Fault injection across save/WAL/recovery (#390) - Long-running soak test at scale (#392; `tests/soak_test.rs`, 10M facts and a 5-hour churn weekly, alternating `main` and `v3`) - Benchmarks at 100K–10M facts and a published performance envelope (#394) -- Higher storage/WAL coverage gates and branch-coverage gates (#396) +- Higher storage/WAL coverage gates and branch-coverage gates (#396; line and branch floors per file in `coverage-thresholds.toml`, checked on every PR) - Durability, recovery and operations guide (#398) --- diff --git a/coverage-thresholds.toml b/coverage-thresholds.toml new file mode 100644 index 0000000000..c54d7e82c9 --- /dev/null +++ b/coverage-thresholds.toml @@ -0,0 +1,76 @@ +# Per-file coverage floors, checked on every push and PR by +# .github/workflows/coverage-gates.yml (scripts/coverage_gates.py). The single +# source of truth for the gates (#396). +# +# Percentages of lines and branches covered by `cargo llvm-cov --branch` with +# the nightly pinned in that workflow, test modules included. Each floor is +# the measured value rounded down, minus one point of slack (none at 100%). +# A floor only goes up: raise it in the PR that adds the tests, and lower one +# only with the reason in the PR. +# +# v2.x (format v7) gets only data-integrity and security fixes, so these +# floors hold the line rather than climb; v3 raises its own. `btree.rs` (the +# v5 B+tree, read only for migration) is not gated. +# +# Known uncovered paths, left on purpose: +# - wal.rs `delete_file` retry sleep: Windows only (one attempt elsewhere). +# - wal.rs `scan_entries` read error other than EOF: needs a failing read on a +# regular file. + +# WAL and the public API + +[files."src/wal.rs"] +lines = 97 +branches = 93 + +[files."src/db.rs"] +lines = 94 +branches = 77 + +[files."src/graph/storage.rs"] +lines = 91 +branches = 77 + +# Storage engine + +[files."src/storage/backend/file.rs"] +lines = 85 +branches = 62 + +[files."src/storage/btree_v6.rs"] +lines = 82 +branches = 81 + +[files."src/storage/cache.rs"] +lines = 85 +branches = 75 + +[files."src/storage/index.rs"] +lines = 92 +branches = 100 + +[files."src/storage/mod.rs"] +lines = 92 +branches = 92 + +[files."src/storage/packed_pages.rs"] +lines = 73 +branches = 71 + +[files."src/storage/persistent_facts.rs"] +lines = 88 +branches = 66 + +# Query engine + +[files."src/query/datalog/evaluator.rs"] +lines = 88 +branches = 84 + +[files."src/query/datalog/executor.rs"] +lines = 93 +branches = 75 + +[files."src/query/datalog/stratification.rs"] +lines = 100 +branches = 100 diff --git a/docs/TEST_COVERAGE.md b/docs/TEST_COVERAGE.md index 7c5bdab061..fb0d919815 100644 --- a/docs/TEST_COVERAGE.md +++ b/docs/TEST_COVERAGE.md @@ -4,7 +4,7 @@ **Verified**: 2026-10-10 with `cargo test` -**Result**: 1,225 passing tests and 9 ignored tests (1,234 total), including the golden-file corpus (#391) +**Result**: 1,228 passing tests and 9 ignored tests (1,237 total), including the golden-file corpus (#391) Since v2.0.4, `tests/edge_cases_test.rs` checks that a file of 1 to 4,095 bytes is `STG-045`, unchanged and with no WAL, when it is a database cut below one page or foreign bytes, and opens as a new database that takes a write and reads it back after reopen when it is a prefix of the initial header or all zeros (#506). @@ -44,8 +44,13 @@ cargo test --quiet # Include the scheduled/ignored tests when the host supports them cargo test -- --include-ignored -# Generate a local branch-coverage report (requires cargo-llvm-cov) -cargo llvm-cov --branch --html +# Generate a local branch-coverage report (requires cargo-llvm-cov and a nightly toolchain) +cargo +nightly llvm-cov --branch --html + +# Check the per-file gates the way CI does +cargo +nightly llvm-cov --branch --no-report +cargo +nightly llvm-cov report --branch --json --summary-only --output-path coverage.json +python3 scripts/coverage_gates.py coverage-thresholds.toml coverage.json ``` -Coverage percentages are intentionally not fixed in this document: they depend on the current toolchain and instrumentation. The CI coverage gates and the command above are the source of truth for the current measurement. +Coverage percentages are intentionally not fixed in this document: they depend on the toolchain and instrumentation. `coverage-thresholds.toml` holds the per-file line and branch floors, measured with the nightly pinned in `.github/workflows/coverage-gates.yml`, and lists the paths left uncovered on purpose (#396). Delete `target/llvm-cov-target` after changing the toolchain or cargo-llvm-cov version: stale binaries from an older build are merged into the report and skew it. diff --git a/scripts/coverage_gates.py b/scripts/coverage_gates.py new file mode 100644 index 0000000000..a39eeb0f51 --- /dev/null +++ b/scripts/coverage_gates.py @@ -0,0 +1,61 @@ +#!/usr/bin/env python3 +"""Check per-file coverage floors from coverage-thresholds.toml (#396). + +Usage: coverage_gates.py + +The JSON is `cargo llvm-cov report --branch --json --summary-only`. Every file +named in the thresholds must be in the report, with branch data when it has a +branch floor; a missing file or missing branch data fails the gate instead of +being skipped, so an empty or partial report can never pass. +""" + +import json +import sys +import tomllib + + +def main() -> int: + thresholds_path, report_path = sys.argv[1], sys.argv[2] + with open(thresholds_path, "rb") as f: + floors = tomllib.load(f)["files"] + with open(report_path) as f: + report = json.load(f) + + by_path = {} + for entry in report["data"][0]["files"]: + name = entry["filename"].replace("\\", "/") + for path in floors: + if name.endswith("/" + path): + by_path[path] = entry["summary"] + + failures = 0 + print(f"{'file':<40} {'metric':<9} {'covered':>8} {'floor':>6}") + for path, floor in floors.items(): + summary = by_path.get(path) + if summary is None: + print(f"{path:<40} FAIL: not in the coverage report") + failures += 1 + continue + for metric in ("lines", "branches"): + if metric not in floor: + continue + counts = summary.get(metric, {}) + if not counts.get("count"): + print(f"{path:<40} {metric:<9} FAIL: no {metric} data") + failures += 1 + continue + pct = counts["percent"] + ok = pct >= floor[metric] + failures += not ok + mark = "" if ok else " FAIL" + print(f"{path:<40} {metric:<9} {pct:>7.2f}% {floor[metric]:>5}%{mark}") + + if failures: + print(f"\n{failures} coverage gate(s) failed. Add tests, or list a path " + "left uncovered, with its reason, in the thresholds file; lower a " + "floor only with the reason in the PR.") + return 1 if failures else 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/src/storage/cache.rs b/src/storage/cache.rs index b7fcebd127..5ed9061040 100644 --- a/src/storage/cache.rs +++ b/src/storage/cache.rs @@ -222,6 +222,61 @@ mod tests { vec![byte; PAGE_SIZE] } + /// Holds every `read_page` until two are in flight, so two threads miss + /// the same page before either caches it. + struct BarrierBackend { + inner: MemoryBackend, + barrier: std::sync::Barrier, + } + + impl StorageBackend for BarrierBackend { + fn write_page(&mut self, page_id: u64, data: &[u8]) -> Result<()> { + self.inner.write_page(page_id, data) + } + fn read_page(&self, page_id: u64) -> Result> { + self.barrier.wait(); + self.inner.read_page(page_id) + } + fn sync(&mut self) -> Result<()> { + Ok(()) + } + fn page_count(&self) -> Result { + self.inner.page_count() + } + fn close(&mut self) -> Result<()> { + Ok(()) + } + fn backend_name(&self) -> &'static str { + "barrier" + } + fn is_new(&self) -> bool { + false + } + } + + /// Two threads that miss the same page both load it; the second to take + /// the write lock returns the first one's cached copy. + #[test] + #[cfg_attr(target_os = "wasi", ignore = "spawns threads; WASI has no threads")] + fn test_concurrent_misses_share_one_cached_copy() { + let mut inner = MemoryBackend::new(); + inner.write_page(1, &make_page(0x5A)).unwrap(); + let backend = BarrierBackend { + inner, + barrier: std::sync::Barrier::new(2), + }; + let cache = PageCache::new(4); + let (a, b) = std::thread::scope(|s| { + let a = s.spawn(|| cache.get_or_load(1, &backend).unwrap()); + let b = s.spawn(|| cache.get_or_load(1, &backend).unwrap()); + (a.join().unwrap(), b.join().unwrap()) + }); + assert!(Arc::ptr_eq(&a, &b), "one copy cached and returned to both"); + assert_eq!(a[0], 0x5A); + let cached = cache.get_or_load(1, &backend.inner).unwrap(); + assert!(Arc::ptr_eq(&a, &cached)); + } + #[test] fn test_cache_miss_loads_from_backend() { let mut backend = MemoryBackend::new(); diff --git a/src/wal.rs b/src/wal.rs index 916676c256..3e07812d3f 100644 --- a/src/wal.rs +++ b/src/wal.rs @@ -842,22 +842,44 @@ mod tests { writer.append_entry(1, &[fact]).unwrap(); writer.file.sync_all().unwrap(); - // Manually corrupt the WAL to have a fact larger than MAX_FACT_SIZE + // Overwrite the first fact's length, after the entry's checksum, + // tx_count and num_facts, with one just over MAX_FACT_SIZE. let mut file = std::fs::OpenOptions::new().write(true).open(&path).unwrap(); - file.seek(std::io::SeekFrom::End(-20)).unwrap(); - // Overwrite the fact length to be huge - let huge_len: u32 = (10 * 1024 * 1024 + 1) as u32; // Just over MAX_FACT_SIZE + file.seek(std::io::SeekFrom::Start(WAL_HEADER_SIZE as u64 + 20)) + .unwrap(); + let huge_len: u32 = (10 * 1024 * 1024 + 1) as u32; file.write_all(&huge_len.to_le_bytes()).unwrap(); drop(file); - // Try to read - should fail gracefully + // Replay stops at the entry instead of allocating 10 MB. let mut reader = WalReader::open(&path).unwrap(); - let result = reader.read_entries(); - assert!( - result.is_err() || result.unwrap().is_empty(), - "Should fail or return empty on corrupted large fact" - ); + assert!(reader.read_entries().unwrap().is_empty()); + } + + #[test] + fn test_wal_entry_with_too_many_facts_ends_replay() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("test.wal"); + wal_with_entries(&path, 2); + let one_len = { + let p = dir.path().join("one.wal"); + wal_with_entries(&p, 1).len() + }; + // Entry 2's num_facts, after its checksum and tx_count. + let mut file = std::fs::OpenOptions::new().write(true).open(&path).unwrap(); + file.seek(std::io::SeekFrom::Start(one_len as u64 + 12)) + .unwrap(); + file.write_all(&1_000_001u64.to_le_bytes()).unwrap(); + drop(file); + assert_eq!(tx_counts(&path), [1]); + } + + #[test] + fn test_wal_writer_open_fails_in_a_missing_directory() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("missing").join("test.wal"); + assert!(WalWriter::open_or_create(&path, SyncMode::Full).is_err()); } // ── #360: WAL-0xx error code regression tests ────────────────────────── From d66c824510d263e6efbd5dc9ec326c7efe102017 Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Sat, 10 Oct 2026 21:58:01 +0530 Subject: [PATCH 2/2] ci(coverage): graph/storage.rs branch floor from the lowest run (#396) Random-input tests reach a few of its branches only in some runs: 78.6% locally, 75.7% in CI. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012wXxZguv7PgKQjMMH4yJ5h --- coverage-thresholds.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/coverage-thresholds.toml b/coverage-thresholds.toml index c54d7e82c9..cc3ba2ded4 100644 --- a/coverage-thresholds.toml +++ b/coverage-thresholds.toml @@ -29,7 +29,7 @@ branches = 77 [files."src/graph/storage.rs"] lines = 91 -branches = 77 +branches = 74 # random-input tests reach some branches only in some runs; lowest seen 75.7 # Storage engine