cargo-rail: stable plan/test caching + runner/profile pinning + docs

Author: loadingalias

Cargo.lock

@@ -47,6 +47,8 @@ rayon = "1.11.0"
 winnow = "0.7.14"
 chrono = "0.4.42"
 glob = "0.3.3"
+syn = { version = "2.0.106", features = ["full", "parsing", "extra-traits"] }
+quote = "1.0.40"
 
 [dev-dependencies]
 anyhow = "1.0.100"

Cargo.toml

@@ -190,6 +190,8 @@ infrastructure = [".github/**", "scripts/**", "*.sh"]
 
 Full reference: [docs/config.md](docs/config.md)
 
+Agent integration: [docs/agent-integration.md](docs/agent-integration.md)
+
 ---
 
 ## Real-World Results
@@ -271,7 +273,14 @@ Works via `cargo metadata`, which respects `.cargo/config.toml`.
 <details>
 <summary><strong>Does this replace Bazel/Buck2 for Rust teams?</strong></summary>
 
-For pure Rust workspaces, yes... it can. `cargo-rail` provides graph-aware testing, dependency unification, and crate extraction without learning a new build system. If you're using Bazel/Buck2 *only* for Rust (not polyglot builds), cargo-rail gives you the key benefits — affected analysis, hermetic builds via lockfiles, crate distribution — while staying in Cargo's ecosystem. I'm exploring the best way to build a proper cache feature (local will come first; remote will follow), as well.
+For pure Rust workspaces, yes... it can. `cargo-rail` provides graph-aware testing, dependency unification, and crate extraction without learning a new build system. If you're using Bazel/Buck2 *only* for Rust (not polyglot builds), cargo-rail gives you the key benefits — affected analysis, lockfile/toolchain-aware reuse, and crate distribution — while staying in Cargo's ecosystem.
+
+Today:
+- `cargo rail test` runs the minimal affected set and includes a conservative local cache for reusing successful test results (with explicit hit/miss reasons).
+- You can pin determinism-sensitive choices like the test runner via `--runner` or `[test].runner` in `rail.toml`.
+
+Next:
+- Policy-gated remote cache storage (Phase 4.3) to reuse across CI runners.
 </details>
 
 <details>

README.md

@@ -0,0 +1,86 @@
+# Agent Integration (Stable Interfaces)
+
+cargo-rail is designed to be consumed by automation and AI agents without scraping logs.
+
+## Output contract (important)
+
+- **stdout** is reserved for command results (e.g. JSON).
+- **stderr** is reserved for progress, warnings, and human explanations.
+
+See `docs/output.md`.
+
+## Machine interfaces
+
+Use these outputs for tooling:
+
+- `--format json` (or global `--json`) for structured output.
+- Treat JSON as an API: all machine outputs include:
+  - `schema` (string, e.g. `cargo-rail/context`)
+  - `schema_version` (integer)
+
+Compatibility rules and determinism expectations are defined in `docs/json-schemas.md`.
+
+## Recommended flow (no log scraping)
+
+### 1) Export context (ground truth)
+
+Generate a single workspace context artifact:
+
+```bash
+cargo rail context export --format json
+```
+
+This writes `target/cargo-rail/context.json` and prints the JSON.
+
+Use this artifact for:
+- workspace members list
+- toolchain/config/targets
+- workspace-member dependency edges
+- ownership roots summary
+- risk signals (proc-macro/build.rs/links)
+
+### 2) Ask targeted questions via `query`
+
+Use `query` when you need fast answers in stable formats:
+
+```bash
+cargo rail query owner <path> --format json
+cargo rail query deps <crate> --format json
+cargo rail query rdeps <crate> --format json
+cargo rail query path <from> <to> --format dot
+```
+
+Notes:
+- `owner` is the canonical “file → crate” mapping without heuristic log parsing.
+- `deps` / `rdeps` operate on workspace-member edges only (fast, stable).
+- `dot` is useful for graph visualization and tool ingestion where appropriate.
+
+### 3) Compute impact and actions (CI/agents)
+
+For change-driven workflows, prefer:
+
+```bash
+cargo rail affected --format json
+```
+
+Then use `query` to explain/visualize relationships as needed.
+
+### 4) Plan executable tasks (stable, explainable)
+
+When you need a deterministic “what should run?” artifact, use `plan`:
+
+```bash
+cargo rail plan test --format json
+```
+
+Notes:
+- `plan` emits stable task IDs and a machine-readable reason set for each task.
+- For deterministic snapshots across machines/runners, pin runner selection:
+  - `cargo rail plan test --runner cargo-test --format json`
+  - or configure `[test].runner = "cargo-test"` in `rail.toml`.
+
+## Consumer guidelines
+
+- Ignore unknown fields (forward compatible).
+- Treat unknown/missing `schema`/`schema_version` as unsupported.
+- Prefer `--format json` over parsing text output.

docs/agent-integration.md

@@ -161,6 +161,45 @@ Why layered? Layer 1 is fast and testable. Layer 2 adds graph awareness. Layer 3
 
 ---
 
+## Caching & Hermeticity (current state)
+
+cargo-rail is intentionally **not** a separate build system. It aims to make Cargo runs:
+- smaller (run less work for most diffs),
+- more deterministic (explicit runner/profile choices),
+- and more cacheable (auditable reuse decisions).
+
+### Local plan-result cache (Phase 4.2)
+
+`cargo rail test` includes a conservative local cache that can reuse prior **successful** test results when inputs match.
+
+Cache key = stable composition of:
+- A task identifier (stable hash of the runner command + selected packages + runner args).
+- A capsule (toolchain + configured targets + small env set + workspace manifest hash).
+- Safe inputs (base/head git SHAs + changed-paths hash + runner identity + flags like ignore-bin-crates).
+
+The cache is intentionally conservative:
+- Disabled when there are uncommitted tracked changes.
+- Disabled when `Cargo.lock` is missing.
+- Disabled in `--all` mode.
+
+Every run reports `cache: hit/miss/disabled (reason…)`.
+
+### Hermeticity (what we can and can’t claim today)
+
+cargo-rail does not claim fully hermetic builds yet. Today it can help teams get closer by:
+- Encouraging lockfile-driven dependency resolution (`Cargo.lock`).
+- Capturing toolchain intent (`rust-toolchain.toml`) and configured targets in the cache capsule.
+- Surfacing “risk” signals that often break hermeticity (proc-macros, build scripts, native `links` crates).
+
+However, true hermeticity also depends on:
+- system libraries and toolchains (e.g., native dependencies, linker state),
+- environment variables outside the capsule,
+- and CI runner images.
+
+Phase 4.3+ extends reuse beyond a single machine by adding policy-gated remote cache storage.
+
+---
+
 ## Unify Pipeline
 
 ```