memex-verify

# Verify the Memex Repo Before Committing Run memex's three CI gates locally — `cargo fmt --check`, `cargo clippy` with warnings denied, and the workspace test suite — so a red CI is caught on your machine before you push. Optionally extend the run with the Postgres-gated integration suite. This complements, and does not replace, memex's own CI (`.github/workflows/ci.yml`); CI stays the authority. ## When to Use - Immediately before invoking `commit-changes` on a memex working tree. - After editing any Rust source under `crates/` (cli, sync, db, mcp, extract), `Cargo.toml`, or `rust-toolchain.toml`. - When a memex CI run went red and you want to reproduce the failing gate locally with the same toolchain. - Before opening a pull request against `pjt222/memex`. ## Inputs - **Required**: A checkout of the memex repo (a clone of `github.com/pjt222/memex`) with `cwd` set to the repo root. The gates read `rust-toolchain.toml` (pinned `1.96.0` + rustfmt/clippy components), so run from the root, not a subcrate. - **Required**: A Rust toolchain on `PATH` (`rustup` provisions the pinned channel via `rustup show`). Confirm with `command -v cargo`. - **Optional (integration gate only)**: A running Postgres+pgvector on `:5433` (the `memex-pg` container) and a sourced `.env` supplying `MEMEX_TEST_PG_URL` (and `VOYAGE_API_KEY` for embedding-backed tests). ## Procedure ### Step 1: Confirm the toolchain and working directory The gates must run from the repo root so `rust-toolchain.toml` selects the pinned `1.96.0` toolchain — local and CI rustfmt/clippy then match. ```bash # From the memex repo root test -f rust-toolchain.toml || { echo "not at memex repo root"; exit 1; } rustup show # provisions/reports the pinned 1.96.0 toolchain command -v cargo # toolchain must be on PATH ``` **Expected:** `rust-toolchain.toml` exists, `rustup show` reports the active toolchain as `1.96.0`, and `cargo` resolves to a path. **On failure:** If you are not at the repo root, `cd` there first. If `cargo` is missing, add it to `PATH` (e.g. `export PATH="$HOME/.cargo/bin:$PATH"`) and re-run. ### Step 2: Gate 1 — format check Mirrors the CI `rustfmt` job (`cargo fmt --all --check`). Read-only: it reports formatting drift without rewriting files. ```bash cargo fmt --all --check ``` **Expected:** Exit 0 and no diff output — the tree is already formatted. **On failure:** Non-zero exit prints the unformatted hunks. Apply the fix with `cargo fmt --all`, re-stage, and re-run this gate. Mark the overall verify FAIL until this gate is clean. ### Step 3: Gate 2 — clippy with warnings denied Mirrors the CI clippy step (`cargo clippy --workspace --all-targets -- -D warnings`). `--all-targets` lints tests and examples too; `-D warnings` makes any lint a hard error, matching CI exactly. ```bash cargo clippy --workspace --all-targets -- -D warnings ``` **Expected:** Exit 0 with no warnings emitted. **On failure:** Each warning is promoted to an error and listed with its lint name and source span. Fix the code (or, only when justified, add a scoped `#[allow(...)]`), then re-run. Mark the overall verify FAIL until clean. ### Step 4: Gate 3 — workspace unit tests Mirrors the CI unit-tests step (`cargo test --workspace`). This runs the non-ignored suite across every crate. ```bash cargo test --workspace ``` **Expected:** Exit 0 and a `test result: ok.` line for each crate's test binary. The unit count is **~49 at v0.4.0** and **grows per milestone** (M5 adds watcher tests). Treat the count as informational only — assert on exit 0 / `test result: ok`, never on a specific number. **On failure:** A non-zero exit and `test result: FAILED.` name the failing tests. Reproduce a single one with `cargo test --workspace <test_name> -- --nocapture`, fix, and re-run. Mark the overall verify FAIL. ### Step 5: Gate 4 (optional) — Postgres-gated integration suite The `#[ignore]`-gated integration suite is omitted from CI today (it needs a Postgres+pgvector service and a `VOYAGE_API_KEY` secret — see `docs/CONTINUE_HERE.md` §5). Run it locally only when the database and `.env` are available; skip this gate otherwise without failing verify. ```bash # Only when the memex-pg container is up and .env is sourced: docker start memex-pg # idempotent if already running set -a && . ./.env && set +a # exports MEMEX_TEST_PG_URL, VOYAGE_API_KEY, ... MEMEX_TEST_PG_URL="$MEMEX_TEST_PG_URL" cargo test --workspace -- --include-ignored ``` **Expected:** Exit 0 with `test result: ok.` including the integration binaries. The total is **~60 at v0.4.0** (unit + ~11 integration) and also grows per milestone — informational only. **On failure:** If the suite fails because Postgres is unreachable or `MEMEX_TEST_PG_URL` is unset, that is an environment gap — note it as "integration gate skipped" rather than a code FAIL. If it fails with actual `test result: FAILED.`, treat it as a real FAIL and fix. ### Step 6: Report per-gate results and the overall verdict Summarize each gate (PASS/SKIP/FAIL) and the rolled-up verdict. ```bash # Conceptual rollup: overall is non-zero if ANY required gate failed. echo "fmt: <PASS|FAIL> clippy: <PASS|FAIL> unit-tests: <PASS|FAIL> integration: <PASS|SKIP|FAIL>" ``` **Expected:** Gates 1–3 (required) all PASS. The integration gate is PASS or SKIP. Overall verdict PASS. **On failure:** Exit non-zero overall if ANY required gate (1–3) or a non-skipped integration run failed. Do not proceed to `commit-changes` until the verdict is PASS. ## Validation - [ ] Run from the memex repo root (`rust-toolchain.toml` present; `rustup show` reports `1.96.0`) - [ ] `cargo fmt --all --check` exits 0 with no diff - [ ] `cargo clippy --workspace --all-targets -- -D warnings` exits 0 - [ ] `cargo test --workspace` exits 0 with `test result: ok.` per crate - [ ] Test counts reported as informational (`~49` unit / `~60` total at v0.4.0), never asserted as a pass/fail threshold - [ ] Integration gate either run (Postgres up + `.env` sourced) and green, or explicitly recorded as SKIPPED - [ ] Overall verdict is non-zero if any required gate failed ## Common Pitfalls - **Asserting a fixed test count.** Counts grow each milestone; a literal `assert 49` turns a healthy run red. Assert exit 0 / `test result: ok` and report the count as `~N at v0.4.0`. - **Running from a subcrate.** Outside the repo root, `rust-toolchain.toml` is not picked up, so local fmt/clippy can drift from CI's `1.96.0` and give false greens or reds. Always run from the root. - **Treating a skipped integration gate as a failure.** No Postgres / no `.env` means SKIP, not FAIL. Only `test result: FAILED.` on a run that actually executed is a real failure. - **Dropping `--all-targets` from clippy.** Without it, lints in test and example code are missed, so local clippy passes while CI fails. Match CI's `--workspace --all-targets -- -D warnings` exactly. - **Treating this as a CI replacement.** This is a local early-warning gate. The authority remains `.github/workflows/ci.yml`; a green local run does not exempt a PR from CI. - **Forgetting to source `.env` before the integration gate.** A `.env`-loading gotcha is documented in `docs/OBSERVATIONS.md`; export the file (`set -a && . ./.env && set +a`) so `MEMEX_TEST_PG_URL` reaches the test process. ## Related Skills - `memex` — the umbrella skill for agent-native shared memory; this gate guards commits made within its workflow. - `memex-wrap` — session-close ritual; run memex-verify as its pre-commit gate before the wrap commits. - `memex-init` — session-start ritual that pairs with this close-side gate. - `commit-changes` — the next step once all required gates pass.