testing-conventions 0.0.75__tar.gz → 0.0.78__tar.gz

{testing_conventions-0.0.75 → testing_conventions-0.0.78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: testing-conventions
-Version: 0.0.75
+Version: 0.0.78
 Requires-Dist: cosmic-ray
 Requires-Dist: coverage
 Summary: Enforce testing conventions in libraries (Python, TypeScript, and Rust).

{testing_conventions-0.0.75 → testing_conventions-0.0.78}/rust/CHANGELOG.md

@@ -5,8 +5,55 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## Unreleased
 
+### Changed
+
+- **E2E attestation is one branch-keyed decision per branch, not a SHA-fresh stamp per push.**
+  `e2e attest '<cmd>'` now writes `e2e-attestations/<branch-slug>.json` — keyed by the
+  branch so parallel pull requests write distinct files and never merge-conflict — recording the
+  command, timestamp, exit code, commit, and branch; it prunes the receipts other branches left
+  behind. The command is unrestricted and *is* the judgment being recorded: the full suite, a
+  subset, or a no-op are all valid receipts. `e2e verify --base <ref>` asks two content questions
+  of `<base>...HEAD`: a branch that left the scoped source untouched passes with no receipt owed,
+  and a branch that changed it passes when its diff adds or updates a receipt. It no longer
+  compares commit SHAs, so one receipt covers the branch — later pushes stay green, and rebases
+  and squash merges never disturb it. Without `--base`, `verify` checks receipt presence.
+  The filename derivation is public: **`e2e slug [branch]`** prints the standardized slug
+  (default: the checked-out branch), and `e2e::branch_slug` exposes it in the crate API;
+  `Attestation` gains a `branch` field recording the raw name. `attest` requires a checked-out
+  branch (a detached `HEAD` is an error naming the fix) and collects a committed legacy
+  `e2e-attestation.json` in the same receipt commit.
+  **Breaking:** the single `e2e-attestation.json` is replaced by the `e2e-attestations/`
+  directory (`e2e::ATTESTATION_PATH` by `e2e::RECEIPTS_DIR`), `Verification::Stale` is gone,
+  and the exact-match freshness contract is retired. See `MIGRATIONS.md`.
+
+- **The suite tiers derive from the package root** (#418). `integration lint` takes its subjects
+  from the standard suite directories — `<package root>/tests/integration/` and
+  `<package root>/tests/e2e/`, both run first-party code for real and so both are held to the
+  integration rules — where the package root is the nearest directory at or above the scanned
+  `path` holding the language's manifest (`pyproject.toml`, `package.json`, `Cargo.toml`; the walk
+  stops at the repository boundary). Rust scans the crate root's `tests/`, cargo's own layout. A
+  test file under `<package root>/tests/` outside a standard tier is flagged by the new
+  **`unknown-tier`** violation (waivable like any rule), so a suite the scan would silently miss
+  is an error instead. The unit-tier scans (`unit colocated-test`, its co-change variant,
+  `unit lint`) leave `<package root>/tests/` to the suites. A tree with no manifest — loose
+  scripts — is scanned at `path` directly, unchanged. One workflow call per package now runs every
+  tier from a single `path`. **Breaking:** integration suites are found via the package root
+  rather than the scanned `path`, integration-lint exemption paths resolve relative to the package
+  root, `config::Rule` gains a variant, and the unit-tier gates release their claim on
+  `<package root>/tests/`. See `MIGRATIONS.md`.
+
 ### Fixed
 
+- **The Rust-build cache in the suite-executing and packaging jobs now keys on the
+  workspace-aware `target/` location** (#410). Cargo resolves the target directory at the
+  *workspace* root regardless of the invoking working directory, but the cache path was always
+  `<package_root>/target` — so a crate that's a member of an ancestor Cargo workspace cached a
+  directory `cargo` never wrote to, and every job recompiled the same wheel from scratch. The
+  cache path now redirects to the workspace root's `target/` for a workspace member, and is
+  unchanged for a standalone crate (or one that's itself the workspace root). Every
+  `astral-sh/setup-uv@v7` step in these jobs also gains an explicit `enable-cache: true`. No
+  config or API change; the `uses:` call is unchanged. See `MIGRATIONS.md`.
+
 - **`e2e verify`: a `--scope` (or `--extra-scope`) that resolves to no tracked path is now an error
   instead of a silent false `Fresh`** (#391). The documented "`--scope` must be `path` or a
   descendant of it" constraint was never enforced: a typo'd or outside `--scope` fell through as a

{testing_conventions-0.0.75 → testing_conventions-0.0.78}/rust/Cargo.lock

@@ -1203,7 +1203,7 @@ dependencies = [
 
 [[package]]
 name = "testing-conventions"
-version = "0.0.75"
+version = "0.0.78"
 dependencies = [
  "anyhow",
  "clap",

{testing_conventions-0.0.75 → testing_conventions-0.0.78}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "testing-conventions"
-version = "0.0.75"
+version = "0.0.78"
 edition = "2021"
 license = "MIT"
 authors = ["Kevin Scott <me@thekevinscott.com>"]

{testing_conventions-0.0.75 → testing_conventions-0.0.78}/rust/MIGRATIONS.md

@@ -15,6 +15,31 @@ Each entry has five sections, in order:
 
 ### Summary
 
+Retires the exact-match e2e freshness contract in favor of **one branch-keyed decision per
+branch**. `e2e attest '<cmd>'` writes `e2e-attestations/<branch-slug>.json` — parallel
+pull requests write distinct files, so attestation merge conflicts are structurally gone — and
+prunes the receipts other branches left behind. The command is unrestricted and is itself the
+judgment being recorded: the full suite, a targeted subset, or a no-op are all valid receipts.
+`e2e verify --base <ref>` asks two content questions of `<base>...HEAD`: did the branch change
+the scoped source (no → pass, nothing owed), and does its diff add or update a receipt (yes →
+pass; no → fail, naming `attest` as the fix). Commit SHAs are no longer compared, so one receipt
+covers the branch — later pushes stay green, and rebases and squash merges never disturb it.
+Without `--base`, `verify` checks that a committed receipt is present.
+
+Derives the suite tiers from the package root (#418). `integration lint` takes its subjects from
+the standard suite directories — `<package root>/tests/integration/` and
+`<package root>/tests/e2e/`, both of which run first-party code for real and so are held to the
+integration rules — where the package root is the nearest directory at or above the scanned
+`path` holding the language's manifest (`pyproject.toml`, `package.json`, `Cargo.toml`), the walk
+stopping at the repository boundary. Rust scans the crate root's `tests/`, cargo's own layout. A
+test file under `<package root>/tests/` outside a standard tier is flagged by the new
+`unknown-tier` violation (waivable like any rule). The unit-tier scans (`unit colocated-test`,
+its co-change variant, `unit lint`) leave `<package root>/tests/` to the suites. A tree with no
+manifest — loose scripts — is scanned at `path` directly, unchanged. One workflow call per
+package now runs every tier from a single `path`; the split unit-job/integration-job pattern (a
+second `uses:` call with `path` pointed at the integration directory and a `gates` allowlist)
+collapses into the package's one call.
+
 Consolidates the reusable workflow's Python provisioning to uv (#399). The suite-executing jobs
 (`unit-coverage`, `coverage-changed`, `mutation`) provisioned Python two ways, selected by
 detect's `python_env`: `actions/setup-python` + `python -m pip install` for a plain package, or
@@ -700,6 +725,34 @@ and `--base` semantics are unchanged; only the consumer-visible **check names**
 
 ### Required changes
 
+**Re-attest once per open branch; delete the legacy `e2e-attestation.json`.** The single-file
+attestation is replaced by the `e2e-attestations/` directory. A branch open across the upgrade
+that changed scoped source runs `e2e attest '<cmd>'` once (writing its branch-keyed receipt); the
+legacy file at the package root is deleted whenever convenient — `verify` no longer reads it.
+`attest` must run on a checked-out branch: a detached `HEAD` is an error naming the fix.
+
+`e2e::Verification` loses its `Stale { attested, latest }` variant — freshness is no longer a
+SHA comparison — and `e2e::ATTESTATION_PATH` (the single-file location) is replaced by the
+receipts-directory constant. Exhaustive `match`es on `Verification` drop the `Stale` arm.
+
+**Move each suite to its standard tier, or exempt it** (#418). `integration lint` finds the
+integration and e2e suites at `<package root>/tests/integration/` and `<package root>/tests/e2e/`
+(Rust: the crate root's `tests/`). A Python/TypeScript package whose suites live elsewhere moves
+them into the standard directories; a test file left under `<package root>/tests/` outside a tier
+fails with `unknown-tier` (waivable per file with a reasoned `exempt` entry). A repo carrying a
+separate integration-lint `uses:` call (`path` pointed at the integration directory, narrowed with
+`gates`) drops it — the package's own call now lints the suites.
+
+**Re-root integration-lint exemption paths at the package root** (#418). With a derived package
+root, `integration lint` resolves `exempt` paths relative to the package root instead of the
+scanned `path`. An exemption for a suite file updates its `path` accordingly (e.g.
+`billing_test.py` scanned at `tests/integration` becomes `tests/integration/billing_test.py` on
+the package's single call). A loose-script tree (no manifest) keeps scan-root-relative resolution.
+
+`config::Rule` gains the `UnknownTier` variant (id `unknown-tier`) (#418). Exhaustive `match`es on
+`Rule` add an arm; `testing-conventions.toml` files parse unchanged, and `rules =
+["unknown-tier"]` is now accepted in an `exempt` entry.
+
 **Branch protection: swap the static-gate check names** (#410). The four static gates are now steps
 of one `Static checks (<language>)` job per language, so the four old per-language check names no
 longer appear. Any branch-protection required-check list (or merge-queue / status-check
@@ -952,6 +1005,35 @@ a deprecation cycle (pre-1.0, so no prior warning was shipped).
 
 ### Behavior changes without code changes
 
+The `e2e verify` gate re-demands a receipt only when scoped **content** changes, once per branch.
+A branch that attests and then pushes further scoped commits stays green (previously each scoped
+push re-demanded a fresh attestation naming its newest commit); a rebase or squash merge leaves a
+receipt standing (previously either could strand the recorded SHA and red the gate with nothing
+to re-run). The reusable workflow's e2e-verify job discovers receipts at `e2e-attestations/`
+instead of the single `e2e-attestation.json`, so a repo that has not yet re-attested with the new
+CLI has its gate skip (verify-if-present) rather than fail until its next scoped branch attests.
+
+`integration lint` scans the derived suite tiers instead of the scanned `path` (#418). Three
+verdicts can move at the same invocation: a suite beside the scanned source directory is now
+linted (violations it always carried now fail the gate — previously the scan never reached it); a
+colocated unit test under the scanned `path` is no longer an integration-lint subject (unit tests
+patch first-party collaborators by design, so a false red there disappears); and a test file
+under `<package root>/tests/` outside a standard tier fails with `unknown-tier` where it was
+previously invisible. The unit-tier gates release `<package root>/tests/`: `unit lint` stops
+flagging integration/e2e tests as un-isolated units, and `unit colocated-test` (and co-change)
+stop demanding colocated twins for suite helpers.
+
+The suite-executing jobs' (`unit-coverage`, `coverage-changed`, `mutation`) and `packaging`'s
+Rust-build cache now keys on the workspace-aware `target/` location, not the derived package root
+unconditionally (#410). Cargo resolves the target directory at the *workspace* root regardless of
+the invoking working directory, so a crate that's a member of an ancestor Cargo workspace now
+caches at that workspace root's `target/`; a standalone crate (or one that's itself the workspace
+root) is unaffected — its cache location is unchanged. A monorepo package whose crate is a
+workspace member (dirsql PR #410's own case) sees its `uv sync` maturin build's cache actually hit
+on the second run instead of archiving (and restoring) an empty directory every time. Every
+`astral-sh/setup-uv@v7` step in the suite/packaging jobs also gains an explicit `enable-cache:
+true`. The `uses:` call is unchanged; no config or API change.
+
 The reusable workflow provisions Python with uv in every suite-executing job (#399); the
 `actions/setup-python` + `python -m pip install` arm is gone. A plain (`python_env == 'pip'`)
 package's suite now runs from a `uv venv` at the derived package root instead of the runner's
@@ -1183,6 +1265,29 @@ Exemptions (#32) change runtime behavior:
 
 ### Verification
 
+```
+git checkout -b tc-migration-check
+testing-conventions e2e attest 'true'
+ls e2e-attestations/
+testing-conventions e2e verify --base origin/main
+```
+
+Expected: `attest` commits one `e2e-attestations/<branch-slug>.json` naming the branch;
+`verify` passes. Push a scoped source change on a second branch without attesting and `verify
+--base origin/main` fails there, naming `e2e attest` as the fix; rebasing the attested branch
+onto a moved `main` leaves its `verify` green.
+
+```
+testing-conventions integration lint --language python <package>/src
+testing-conventions unit lint --language python <package>
+```
+
+Expected: the first call reports violations from `<package>/tests/integration` and
+`<package>/tests/e2e` (and `unknown-tier` for any stray `*_test.py` under `<package>/tests/`)
+even though `path` is the source directory; the second reports nothing for files under
+`<package>/tests/` (#418). In-repo, the dogfood `checks` job (`internals/checks/src`) now lints
+`internals/checks/tests/integration` + `tests/e2e` on the same single call, green.
+
 ```
 uv run --project internals/checks tc-checks uv-provisioning-wired
 grep -c 'python -m pip install' .github/workflows/testing-conventions.yml || true

{testing_conventions-0.0.75 → testing_conventions-0.0.78}/rust/src/co_change.rs

@@ -50,6 +50,13 @@ pub fn stale_sources(
     // Every changed path, so a subject's expected test is a set lookup rather
     // than a second walk of the diff.
     let changed: BTreeSet<&str> = entries.iter().map(|(_, path)| path.as_str()).collect();
+    // `<package root>/tests/` belongs to the suite tiers (integration / e2e),
+    // so nothing under it is a co-change subject.
+    let suite_tests = match language {
+        Language::Python => crate::tiers::suite_tests_dir(repo, "pyproject.toml"),
+        Language::TypeScript => crate::tiers::suite_tests_dir(repo, "package.json"),
+        Language::Rust => None,
+    };
 
     let mut stale = Vec::new();
     for (status, rel) in &entries {
@@ -59,6 +66,12 @@ pub fn stale_sources(
         if !language.tracks(path) || language.is_test(path) || language.is_support(path) {
             continue;
         }
+        if suite_tests
+            .as_ref()
+            .is_some_and(|tests| repo.join(path).starts_with(tests))
+        {
+            continue;
+        }
         let expected = language
             .expected_test_path(path)
             .to_string_lossy()

{testing_conventions-0.0.75 → testing_conventions-0.0.78}/rust/src/colocated_test.rs

@@ -120,6 +120,17 @@ pub fn missing_unit_tests(
     let root = root.as_ref();
     let mut files = Vec::new();
     collect_files(root, language, &mut files)?;
+    // `<package root>/tests/` belongs to the suite tiers (integration / e2e),
+    // so nothing under it is a colocated-unit subject. Rust's walk already
+    // skips `tests/` (an integration-crate directory in cargo's own layout).
+    let manifest = match language {
+        Language::Python => Some("pyproject.toml"),
+        Language::TypeScript => Some("package.json"),
+        Language::Rust => None,
+    };
+    if let Some(tests) = manifest.and_then(|m| crate::tiers::suite_tests_dir(root, m)) {
+        files.retain(|file| !file.starts_with(&tests));
+    }
 
     // Every tracked path we found, so a subject's expected twin is a lookup
     // rather than a second pass over the filesystem.

{testing_conventions-0.0.75 → testing_conventions-0.0.78}/rust/src/config.rs

@@ -241,6 +241,9 @@ pub enum Rule {
     UntypedMock,
     /// `integration lint` — a `vi.mock` of a first-party module in a TS integration test.
     NoFirstPartyMock,
+    /// `integration lint` — a test file under `<package root>/tests/` outside a
+    /// standard suite tier (`tests/integration/`, `tests/e2e/`).
+    UnknownTier,
     /// `unit mutation` — a surviving mutant the unit suite didn't catch ([`crate::mutation`]).
     Mutation,
 }
@@ -272,6 +275,7 @@ impl Rule {
             Rule::UnmockedCollaborator => "unmocked-collaborator",
             Rule::UntypedMock => "untyped-mock",
             Rule::NoFirstPartyMock => "no-first-party-mock",
+            Rule::UnknownTier => "unknown-tier",
             Rule::Mutation => "mutation",
         }
     }
@@ -293,6 +297,7 @@ impl Rule {
             Rule::UnmockedCollaborator,
             Rule::UntypedMock,
             Rule::NoFirstPartyMock,
+            Rule::UnknownTier,
             Rule::Mutation,
         ]
         .into_iter()