Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
744da05
store: the quality layers on, the coverage lift and the error arms
VirtualMachinist Nov 14, 2026
8c4a5e6
Keep each use lookup answer within one resolve pass
VirtualMachinist Nov 14, 2026
35aab17
Test the resolve store texts and how index, probe and diff fail
VirtualMachinist Nov 14, 2026
6d353e3
Test that an unresolved use beats an external one for one name
VirtualMachinist Nov 14, 2026
0db4b84
Give every git a test spawns an explicit identity
VirtualMachinist Nov 14, 2026
6ad406f
Give each analyze test temp dir a per-process count
VirtualMachinist Nov 14, 2026
3fced3d
Split the fuzz smoke into 200 shards of ten cases
VirtualMachinist Nov 14, 2026
4755af8
Turn on coverage, CRAP and mutation in four crates
VirtualMachinist Nov 14, 2026
4e4bd2e
extract: move the hand-built bucket cases out of the scorer test
VirtualMachinist Nov 14, 2026
279fcd7
Turn on coverage, CRAP and mutation for the CLI and proto crates
VirtualMachinist Nov 14, 2026
10f3709
Pin the map budget bound and the show member cap boundary
VirtualMachinist Nov 14, 2026
5cf0c19
Record the cargo-tops version the gate runs with
VirtualMachinist Nov 14, 2026
fbcefcb
Give every git the tests spawn a fixed identity and no outside config
VirtualMachinist Nov 14, 2026
314e25e
Pin that a client response gets no reply and a methodless message is …
VirtualMachinist Nov 14, 2026
4e1467d
Pin that map over a damaged index answers or fails with one envelope
VirtualMachinist Nov 15, 2026
a03a762
Fail the framing and server loop tests when a read never returns
VirtualMachinist Nov 15, 2026
34b470d
store: make the two lock race tests hold on every box
VirtualMachinist Nov 15, 2026
f90a1b4
store: split the scorer reads into a row reader and a mapper
VirtualMachinist Nov 15, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 90 additions & 0 deletions RUST-TOPS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# Rust-TOPS

Rust-TOPS is a testing and quality protocol for Rust crates. Each crate
states its class, its test layers and their thresholds in a
`rust-tops.yaml` beside its `Cargo.toml`, and `cargo-tops` checks that file
and runs the enabled layers in a fixed order. Protocol and tooling:
<https://github.com/Hedronite/rust-tops>.

## Versions

- **Protocol:** rust-tops 1.1.0, spec
`https://github.com/Hedronite/rust-tops/blob/v0.2.0/RUST_TOPS.md`, as each
crate's `protocol` block states it.
- **Gate:** run with cargo-tops 0.2.0, cargo-llvm-cov 0.9.1, cargo-crap
0.5.0 and cargo-mutants 27.1.0. cargo-tops 0.2.0 enforces no coverage or
CRAP threshold, so the grade comes from the measured cargo-llvm-cov,
cargo-crap and cargo-mutants figures, not from the gate's exit.

## Crates and thresholds

Coverage is line, region and per-file line, in percent. CRAP is the
production and agent threshold. Mutation is the kill rate on the diff, in
percent, and the most unexplained survivors.

| Crate | Class | Line | Region | Per-file | CRAP | Mutation |
|---|---|---|---|---|---|---|
| `phantom-fractal` | binary-cli | 80 | 75 | 90 | 6 / 6 | 85, 0 |
| `phantom-fractal-proto` | library-core | 95 | 90 | 90 | 6 / 6 | 95, 0 |
| `phantom-fractal-lang` | library-core | 95 | 90 | 90 | 6 / 6 | 95, 0 |
| `phantom-fractal-lang-rust` | library-core | 95 | 90 | 90 | 6 / 6 | 95, 0 |
| `phantom-fractal-extract` | library-core | 95 | 90 | 90 | 6 / 6 | 95, 0 |
| `phantom-fractal-analyze` | library-core | 95 | 90 | 90 | 6 / 6 | 95, 0 |
| `phantom-fractal-store` | library-core | 95 | 90 | 90 | 6 / 6 | 95, 0 |
| `phantom-fractal-git` | library-core | 95 | 90 | 90 | 6 / 6 | 95, 0 |

Each crate's yaml governs. Coverage, CRAP and mutation are on in every
crate.

## Running the gate

From a crate's directory:

```sh
cargo-tops check # validate rust-tops.yaml against the protocol schema
cargo-tops gate # fmt, clippy, deny, nextest, coverage, CRAP, mutation, advisories
```

Call the `cargo-tops` binary directly, not `cargo tops`. Cargo passes
`tops` as the first argument to a subcommand binary, and cargo-tops 0.2.0
does not strip it, so `cargo tops gate` fails with
`unrecognized subcommand 'tops'`.

An exit of 0 is not a pass. The coverage layer writes
`target/coverage/lcov.info` and the CRAP layer writes `target/crap.json`;
neither applies a threshold. The figures are read from the cargo-llvm-cov
summary, `target/crap.json` and the cargo-mutants report, and compared
with the crate's yaml. Mutation runs on the diff against `origin/main`.

## The CRAP rule

CRAP is CC² × (1 − coverage)³ + CC, so it is never below a function's
cyclomatic complexity.

1. Every production function added or changed since `61236dc` has CRAP at
or below its crate's threshold.
2. No existing function's CRAP rises above its value at `61236dc`.
3. The per-function list at `61236dc` (187 production functions over 6),
kept with the project's quality measurements, is a burn-down list and
is not graded. It moves to `target/crap-baseline.json` once cargo-crap
supports a baseline file.
4. A new or changed exhaustive enum dispatch match (one arm per variant,
no guards, each arm one call or expression) that cannot reach the
threshold without a split made only for CRAP takes an `exemptions`
entry in its crate's yaml, with layer `crap`, a reason and an expiry.

No function is split only to lower its CRAP.

## Exemptions in force

None.

## Known deviations

- **Fuzz and property runs.** A std-only fuzz harness and map property
run, driven by a seeded splitmix64 generator, stand in for cargo-fuzz
and proptest. They add no package and need no nightly toolchain.
- **No CI quality job.** Coverage, CRAP and mutation run on the build box,
not in CI.
- **CLI crate CRAP.** `phantom-fractal` holds CRAP 6, tighter than the
binary-cli class default of 8.
11 changes: 5 additions & 6 deletions crates/phantom-fractal-analyze/rust-tops.yaml
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
# Rust-TOPS 1.1.0 instance for phantom-fractal-analyze (library-core).
# Scaffold slice: laws, coverage, CRAP, and mutation stay off until the
# crate has code they can measure.

# Layers: lint, unit and security-advisory stay on; coverage, CRAP and
# mutation turn on with the thresholds the R1 ruling keeps.
protocol:
id: rust-tops
version: "1.1.0"
Expand Down Expand Up @@ -31,9 +30,9 @@ layers:
- { id: acceptance, enabled: false, tier: 1, runner: "assert_cmd journeys", scope: tests }
- { id: snapshot, enabled: false, tier: 2, runner: insta, scope: tests }
- { id: compile-fail, enabled: false, tier: 2, runner: trybuild, scope: tests }
- { id: coverage, enabled: false, tier: 0, runner: cargo-llvm-cov, scope: lib }
- { id: crap, enabled: false, tier: 0, runner: cargo-crap, scope: lib }
- { id: mutation, enabled: false, tier: 1, runner: cargo-mutants, scope: diff }
- { id: coverage, enabled: true, tier: 0, runner: cargo-llvm-cov, scope: lib }
- { id: crap, enabled: true, tier: 0, runner: cargo-crap, scope: lib }
- { id: mutation, enabled: true, tier: 1, runner: cargo-mutants, scope: diff }
- { id: property, enabled: false, tier: 1, runner: proptest, scope: lib }
- { id: fuzz, enabled: false, tier: 3, runner: cargo-fuzz, scope: lib }
- { id: concurrency, enabled: false, tier: 3, runner: loom, scope: lib }
Expand Down
9 changes: 7 additions & 2 deletions crates/phantom-fractal-analyze/tests/fixture.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
use std::fs;
use std::path::{Path, PathBuf};
use std::process;
use std::sync::atomic::{AtomicU32, Ordering};
use std::time::{SystemTime, UNIX_EPOCH};

use phantom_fractal_analyze::{Hit, Impact, ImpactOptions, impact};
Expand All @@ -19,12 +20,16 @@ struct TempDir(PathBuf);

impl TempDir {
fn new() -> Self {
static NEXT: AtomicU32 = AtomicU32::new(0);
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|dur| dur.as_nanos())
.unwrap_or(0);
let path =
std::env::temp_dir().join(format!("phantom-fractal-analyze-{}-{nanos}", process::id()));
let path = std::env::temp_dir().join(format!(
"phantom-fractal-analyze-{}-{nanos}-{}",
process::id(),
NEXT.fetch_add(1, Ordering::Relaxed)
));
fs::create_dir_all(&path).expect("temp dir");
Self(path)
}
Expand Down
11 changes: 8 additions & 3 deletions crates/phantom-fractal-analyze/tests/map.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ use std::fs;
use std::io::ErrorKind;
use std::path::{Path, PathBuf};
use std::process;
use std::sync::atomic::{AtomicU32, Ordering};
use std::time::{SystemTime, UNIX_EPOCH};

use phantom_fractal_analyze::{
Expand All @@ -26,18 +27,22 @@ const DETAILS: [(Detail, &str); 3] = [
(Detail::Full, "full"),
];

/// A fresh directory under the system temp dir, removed on drop.
/// A fresh directory under the system temp dir, removed on drop. Its name
/// carries the process id, the time and a per-process count, so tests
/// that share one process, as libtest runs them, never share a path.
struct TempDir(PathBuf);

impl TempDir {
fn new(tag: &str) -> Self {
static NEXT: AtomicU32 = AtomicU32::new(0);
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|dur| dur.as_nanos())
.unwrap_or(0);
let path = std::env::temp_dir().join(format!(
"phantom-fractal-analyze-map-{tag}-{}-{nanos}",
process::id()
"phantom-fractal-analyze-map-{tag}-{}-{nanos}-{}",
process::id(),
NEXT.fetch_add(1, Ordering::Relaxed)
));
fs::create_dir_all(&path).expect("temp dir");
Self(path)
Expand Down
12 changes: 10 additions & 2 deletions crates/phantom-fractal-analyze/tests/map_git.rs
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ use std::fs;
use std::io::Write as _;
use std::path::{Path, PathBuf};
use std::process::{self, Command, Stdio};
use std::sync::atomic::{AtomicU32, Ordering};
use std::time::{SystemTime, UNIX_EPOCH};

use phantom_fractal_analyze::{Detail, MapRequest, estimate_tokens, packing_budget, render};
Expand All @@ -52,13 +53,15 @@ struct TempDir(PathBuf);

impl TempDir {
fn new(tag: &str) -> Self {
static NEXT: AtomicU32 = AtomicU32::new(0);
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|dur| dur.as_nanos())
.unwrap_or(0);
let path = std::env::temp_dir().join(format!(
"phantom-fractal-analyze-map-git-{tag}-{}-{nanos}",
process::id()
"phantom-fractal-analyze-map-git-{tag}-{}-{nanos}-{}",
process::id(),
NEXT.fetch_add(1, Ordering::Relaxed)
));
fs::create_dir_all(path.join("repo")).expect("temp dir");
fs::create_dir_all(path.join("home")).expect("temp home");
Expand All @@ -81,6 +84,11 @@ fn git(dir: &Path, home: &Path, args: &[&str], stdin: Option<&[u8]>) {
.env("HOME", home)
.env("GIT_CONFIG_NOSYSTEM", "1")
.env("GIT_CONFIG_GLOBAL", "/dev/null")
.env("XDG_CONFIG_HOME", home)
.env("GIT_AUTHOR_NAME", "Test")
.env("GIT_AUTHOR_EMAIL", "test@example.invalid")
.env("GIT_COMMITTER_NAME", "Test")
.env("GIT_COMMITTER_EMAIL", "test@example.invalid")
.env("LC_ALL", "C")
.args([
"-c",
Expand Down
7 changes: 5 additions & 2 deletions crates/phantom-fractal-analyze/tests/rank_store.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ use std::fs;
use std::io::ErrorKind;
use std::path::{Path, PathBuf};
use std::process;
use std::sync::atomic::{AtomicU32, Ordering};
use std::time::{SystemTime, UNIX_EPOCH};

use phantom_fractal_analyze::{EdgeKind, RankSource, personalised, rank};
Expand All @@ -21,13 +22,15 @@ struct TempDir(PathBuf);

impl TempDir {
fn new(tag: &str) -> Self {
static NEXT: AtomicU32 = AtomicU32::new(0);
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|dur| dur.as_nanos())
.unwrap_or(0);
let path = std::env::temp_dir().join(format!(
"phantom-fractal-analyze-{tag}-{}-{nanos}",
process::id()
"phantom-fractal-analyze-{tag}-{}-{nanos}-{}",
process::id(),
NEXT.fetch_add(1, Ordering::Relaxed)
));
fs::create_dir_all(&path).expect("temp dir");
Self(path)
Expand Down
11 changes: 5 additions & 6 deletions crates/phantom-fractal-extract/rust-tops.yaml
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
# Rust-TOPS 1.1.0 instance for phantom-fractal-extract (library-core).
# Scaffold slice: laws, coverage, CRAP, and mutation stay off until the
# crate has code they can measure.

# Layers: lint, unit and security-advisory stay on; coverage, CRAP and
# mutation turn on with the thresholds the R1 ruling keeps.
protocol:
id: rust-tops
version: "1.1.0"
Expand Down Expand Up @@ -31,9 +30,9 @@ layers:
- { id: acceptance, enabled: false, tier: 1, runner: "assert_cmd journeys", scope: tests }
- { id: snapshot, enabled: false, tier: 2, runner: insta, scope: tests }
- { id: compile-fail, enabled: false, tier: 2, runner: trybuild, scope: tests }
- { id: coverage, enabled: false, tier: 0, runner: cargo-llvm-cov, scope: lib }
- { id: crap, enabled: false, tier: 0, runner: cargo-crap, scope: lib }
- { id: mutation, enabled: false, tier: 1, runner: cargo-mutants, scope: diff }
- { id: coverage, enabled: true, tier: 0, runner: cargo-llvm-cov, scope: lib }
- { id: crap, enabled: true, tier: 0, runner: cargo-crap, scope: lib }
- { id: mutation, enabled: true, tier: 1, runner: cargo-mutants, scope: diff }
- { id: property, enabled: false, tier: 1, runner: proptest, scope: lib }
- { id: fuzz, enabled: false, tier: 3, runner: cargo-fuzz, scope: lib }
- { id: concurrency, enabled: false, tier: 3, runner: loom, scope: lib }
Expand Down
35 changes: 35 additions & 0 deletions crates/phantom-fractal-extract/tests/diff.rs
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,11 @@ impl Repo {
.env("HOME", self.home.path())
.env("GIT_CONFIG_NOSYSTEM", "1")
.env("GIT_CONFIG_GLOBAL", "/dev/null")
.env("XDG_CONFIG_HOME", self.home.path())
.env("GIT_AUTHOR_NAME", "Test")
.env("GIT_AUTHOR_EMAIL", "test@example.invalid")
.env("GIT_COMMITTER_NAME", "Test")
.env("GIT_COMMITTER_EMAIL", "test@example.invalid")
.env("LC_ALL", "C")
.args([
"-c",
Expand Down Expand Up @@ -505,3 +510,33 @@ fn common_snapshot(roots: &[&Path]) -> Vec<(PathBuf, u64, std::time::SystemTime,
out.sort();
out
}

#[test]
fn a_target_beside_a_nested_manifest_is_pruned_and_one_elsewhere_is_not() {
// SPEC-w9 G2a: a base file under `target` counts only when that
// `target` is neither at the root nor beside a `Cargo.toml`.
let repo = Repo::new();
repo.commit(
"main",
T0 + 60,
&[
("crates/tool/Cargo.toml", MANIFEST),
("crates/tool/target/built.rs", "pub fn built() {}\n"),
("src/target/kept.rs", "pub fn kept() {}\n"),
],
);
repo.git(&["reset", "-q", "--hard", "main"], None);
fs::remove_file(repo.root().join("crates/tool/target/built.rs")).expect("delete built");
fs::remove_file(repo.root().join("src/target/kept.rs")).expect("delete kept");
let found = repo.diff(&Base::Head);
let keys: Vec<(&str, FileChange)> = found
.changed
.iter()
.map(|symbol| (symbol.key.as_str(), symbol.change))
.collect();
assert_eq!(
keys,
[("src/target/kept.rs#kept#function#0", FileChange::Removed)]
);
assert!(found.files_only.is_empty(), "{:?}", found.files_only);
}
Loading
Loading