Skip to content

01-v0.1-shakedown.aps.md

Latest commit

 

History

History
308 lines (265 loc) · 15.7 KB

01-v0.1-shakedown.aps.md

File metadata and controls

308 lines (265 loc) · 15.7 KB
Raw

v0.1 Shakedown

Prove the plugin end-to-end on a real consumer workspace, then ship the first npm release.

ID Owner Status
NXRUST eddacraft Complete

Purpose

The nxrust plugin is feature-complete for v0.1: seven executors, five generators, a working createNodesV2 + createDependencies graph plugin, a unit-test suite, and review findings addressed. What it has not done yet:

  1. Been driven end-to-end against a real Rust crate in a real Nx 22 workspace outside this repo
  2. Shipped to npm
  3. Replaced any in-place workspace-link copies in validation consumers

This module closes the gap between implementation and a supported public release.

Why this matters:

  1. Downstream consumers depend on this. Workspaces validating nxrust via a pnpm workspace link cannot bump Nx independently of the plugin until a real release is on npm.
  2. Nx 22 needs a maintained Rust plugin. Shipping nxrust under Apache-2.0 gives mixed TypeScript + Rust workspaces a current option.
  3. Review findings need real-world validation. target/ caching and cargo metadata performance need validation in a real workspace.

In Scope

  • Smoke-test the plugin end-to-end in a consumer workspace via pnpm workspace protocol; run one representative crate through the full executor set; assert cache hit on second run
  • Roll the validation shape out to the remaining crates in the consumer workspace
  • CI smoke test in this repo (nxrust): build + run all unit tests + run the executor smoke test against a fixture crate held inside e2e/
  • Add a dependent-repo smoke job to the consumer workspace's CI that runs pnpm exec nx run <crate>:check against the linked plugin
  • First npm publish of @eddacraft/nxrust@0.1.0
  • Consumer switches from workspace:* link to the published version

Out of Scope

  • Adding any new executor or generator beyond what already exists in src/executors/** and src/generators/**
  • napi, wasm-pack, preset, add-napi, add-wasm — monodon-parity items deferred to module 02-monodon-parity
  • cargo-nextest executor, bench executor, glob edge cases in workspace-member detection — deferred to module 03-v0.2-polish
  • crates.io publishing — the release-publish executor exists and is unit-tested; it stays "unvalidated against a real token" until a consumer exercises it

Interfaces

Depends On

  • @nx/devkit ^22.6.5 (already in package.json)
  • A real Nx 22 consumer workspace to validate against
  • npm publish credentials for the chosen scope — needed only at R4

Exposes (at the end of this module)

  • @eddacraft/nxrust@0.1.0 on npm
  • A dependent-repo smoke job in the consumer workspace's CI that fails loud if a nxrust release breaks the consumer
  • The consumer workspace running on the plugin-inferred project graph (no per-crate project.json files required)

Constraints

  • Zero regressions on the consumer. Every cargo check/test/clippy/fmt call that passes today must still pass after the plugin wraps it. If validation shows a regression, the consumer change reverts — it does not press on.
  • No code changes to nxrust during validation unless validation exposes a real defect. Cosmetic edits wait for v0.2.
  • Consumer switchover happens in one PR, reversible with a single git revert. Do not interleave the switchover with unrelated consumer-side work.
  • Published package ships LICENSE, README.md, CHANGELOG.md, dist/**, and the top-level executors.json / generators.json — nothing else.

Ready Checklist

  • Plugin unit tests green (pnpm test)
  • Plugin typechecks (pnpm typecheck / tsc --noEmit)
  • Plugin builds to ./dist with pnpm build
  • Entrypoint smoke: createNodesV2 + createDependencies loadable; all 7 executors and 5 generators require.resolve cleanly
  • Review findings addressed or documented
  • LICENSE (Apache-2.0), README.md, CHANGELOG.md at repo root
  • This APS plan written
  • Consumer workspace reachable with a clean working tree

Work Items

NXRUST-R1: Validate on smallest crate [Complete: 2026-04-21]

  • Intent: Drive the full plugin end-to-end against the smallest real crate before touching any of the others
  • Expected Outcome: the consumer workspace's nx.json registers nxrust as a plugin; pnpm exec nx run <crate>:<target> matches cargo <cmd> -p <crate> for check/test/clippy/fmt-check; second local run reports cache hit; nx graph --focus=<crate> renders the correct edges
  • Scope: consumer workspace — nx.json (register plugin), root package.json + pnpm-lock.yaml (add nxrust dev-dep)
  • Validation: All four checks above pass
  • Confidence: medium
  • Risks: target/ caching is notoriously fragile. If the second run rebuilds instead of cache-hitting, narrow the outputs declaration on the affected target rather than abandon the cache.
  • Non-scope: Other crates in the workspace
  • Resolution: Linked into the consumer workspace via pnpm add -Dw nxrust@file:../../nxrust; registered {"plugin": "nxrust", "options": {}} in its nx.json. pnpm exec nx show projects listed every Rust crate alongside the TS projects. Ran check (cold → cache hit on re-run), test, clippy, fmt-check — all clean. Graph focus matched cargo dependency reality. No plugin defects surfaced. Two reconciliations captured: (a) Cargo package names map directly to Nx project keys; (b) the plugin auto-infers projects from Cargo.toml — no manual project.json files needed. Workspace-specific timings, branch names, and crate names are intentionally omitted from the public plan.

NXRUST-R2: Verify full-workspace run-many [Complete: 2026-05-05]

  • Intent: Confirm every Rust crate in the consumer workspace participates correctly in the inferred project graph, then exercise nx run-many and nx affected across the workspace
  • Expected Outcome: pnpm exec nx show projects lists every Rust project; pnpm exec nx run-many -t check and :test complete green; a targeted nx affected -t check --files=<crate>/src/lib.rs runs that crate and its dependents only
  • Scope: consumer workspace — validation only; no per-crate project.json files needed
  • Dependencies: NXRUST-R1
  • Validation: Both run-many commands exit 0; the affected probe excludes unrelated crates from the task list
  • Confidence: high (R1 already proved the shape on one crate)
  • Non-scope: Feature flags, profiles, cross-compile matrix; any project.json overrides
  • Resolution: Pilot workspace dependencies installed cleanly and pnpm exec nx show projects listed the inferred Rust projects. Full pnpm exec nx run-many -t check completed green for all 16 Rust check targets. Full pnpm exec nx run-many -t test completed green across the workspace. A targeted nx affected -t check probe ran only the changed crate and its dependent crate, excluding unrelated crates.

NXRUST-R3: CI smoke test in both repos [Complete: 2026-05-08]

  • Intent: Catch nxrust regressions before they reach consumers, and catch consumer drift before it reaches a release
  • Expected Outcome:
    • In nxrust: A GitHub Actions workflow runs pnpm install, pnpm build, pnpm test, and a fixture-driven end-to-end that runs nx run <fixture>:check against a tiny crate held in e2e/
    • In the validation consumer: the consumer's Rust CI workflow gains a job that runs pnpm exec nx run <crate>:check against the linked plugin
  • Scope: nxrust/.github/workflows/**, nxrust/e2e/** (new fixture crate + project.json), consumer Rust CI workflow
  • Dependencies: NXRUST-R2
  • Validation: Both workflows green on a canary PR; package metadata and executor resolution failures are caught by CI
  • Confidence: high
  • Resolution: Added nxrust CI with pnpm install --frozen-lockfile, pnpm build, pnpm test, and pnpm e2e. The e2e smoke packs the publishable @eddacraft/nxrust tarball, installs it into a checked-in fixture workspace via a frozen fixture lockfile, clears fixture Nx state, and runs nx run smoke:check --skip-nx-cache. Added the consumer Rust workflow smoke job that runs an Nx-backed Rust check target against the linked plugin. Local validation passed for pnpm build, pnpm test, pnpm e2e, and the consumer smoke command. CI smoke subsequently validated by the 0.1.1 release flow (prepublishOnly runs build + test + e2e before every publish).

NXRUST-R4: First npm publish of @eddacraft/nxrust@0.1.0 [Complete: 2026-05-08]

  • Intent: Ship v0.1.0 to npm so consumers can install it without pnpm workspace protocol or git refs
  • Expected Outcome: @eddacraft/nxrust@0.1.0 published; npm view <package> versions shows 0.1.0; package tarball contains dist/**, executors.json, generators.json, LICENSE, THIRD-PARTY-NOTICES.md (if any monodon code was borrowed during R1–R3), README.md, CHANGELOG.md and nothing else
  • Scope: nxrust — package publish scripts, CI default-branch trigger, CHANGELOG.md entry
  • Dependencies: NXRUST-R3
  • Validation: pnpm release:dry-run passes; npm whoami confirms a logged-in publisher; fresh pnpm dlx create-nx-workspace + pnpm add -D @eddacraft/nxrust, then pnpm exec nx g @eddacraft/nxrust:init exits 0
  • Confidence: medium
  • Risks: Scope ownership — confirm scope is registered and publishable from the CI runner or a local account before attempting
  • Non-scope: Semantic-release automation — v0.1 is a manual pnpm publish; automation is a v0.2 concern
  • Resolution: @eddacraft/nxrust@0.1.0 published to npm on 2026-05-08; npm view @eddacraft/nxrust dist-tags reports latest: 0.1.0. Defects discovered post-publish are tracked in NXRUST-R4.1.

NXRUST-R4.1: Patch release @eddacraft/nxrust@0.1.1 [Complete: 2026-05-08]

  • Intent: Ship a patch release fixing two defects surfaced in 0.1.0 by the downstream Anvil consumer. 0.1.0 cannot be republished (npm forbids overwriting a published version), so the fixes ship as 0.1.1.
  • Expected Outcome: @eddacraft/nxrust@0.1.1 published with dist-tags.latest = 0.1.1. Anvil's previously failing CI jobs (Check/Format and Test/Unit Tests) re-run green against @eddacraft/nxrust@^0.1.1.
  • Scope: nxrust — package.json version bump, CHANGELOG entry, inferProjectConfig (pin cargo package on every target), buildCargoArgs (per-subcommand option allowlist), specs for both. PR #6 against main.
  • Dependencies: NXRUST-R4
  • Validation: pnpm test 47/47 green (including new specs); pnpm typecheck clean; pnpm build clean; CI smoke green on PR #6; pnpm publish from main after merge; Anvil's failing CI jobs re-run green against the patched version.
  • Confidence: high
  • Risks: Anvil's CI may surface a third defect. If so, treat the same way — patch nxrust, ship 0.1.2, before unblocking R5.
  • Defects fixed:
    • cargo -p got the Nx project name. When @nx/js claimed a sibling package.json's name (napi-rs bindings), the cargo executor fed -p @scope/name to cargo and got back unexpected prerelease field. Fixed by pinning { package: pkg.name } on every inferred target.
    • buildCargoArgs emitted every option key as a cargo flag. nx run-many -t test --run --coverage in a mixed JS+Rust workspace leaked vitest's --run / --coverage into cargo test --run --coverage [object Object]. Fixed by adding a per-subcommand allowlist that's unioned with the base cargo keys; everything outside that union is dropped.
  • Resolution: PR #6 merged to main 2026-05-08; pnpm publish shipped @eddacraft/nxrust@0.1.1 on 2026-05-08. npm view @eddacraft/nxrust dist-tags reports latest: 0.1.1 and versions lists [0.1.0, 0.1.1]. Consumer re-run against ^0.1.1 confirmed under R5. An ancillary defect was found and fixed during the release: the e2e smoke (tools/e2e-smoke.mjs) hard-coded the 0.1.0 tarball filename, so the version bump initially broke the smoke job — the script now derives the tarball name from package.json.

NXRUST-R5: Switch consumer onto published package [Complete: 2026-05-12]

  • Intent: Remove the consumer's in-place workspace link and consume the published package instead, so the consumer can bump Nx independently
  • Expected Outcome: Consumer root package.json pulls @eddacraft/nxrust@^0.1.0 from npm; the in-place link directory is deleted; pnpm install && pnpm exec nx run-many -t test,lint,build passes
  • Scope: consumer workspace — root package.json, pnpm-lock.yaml, the in-place plugin directory (delete), pnpm-workspace.yaml if needed
  • Dependencies: NXRUST-R4
  • Validation: Above; single-revert rollback verified on a throwaway branch
  • Confidence: medium
  • Risks: Drift between the in-place copy and the extracted nxrust repo — treat any drift as a bug feeding back into NXRUST-R1, patch nxrust, and re-publish before deleting the in-place copy
  • Resolution: Consumer switched from workspace:* link to @eddacraft/nxrust@^0.1.0 (resolving to 0.1.1). Switchover confirmed by the package owner; the in-place link directory is gone.

Risks & Mitigations

Risk Impact Likelihood Mitigation
Consumer validation exposes a defect that forces nxrust code changes mid-module medium medium Patch nxrust, re-link, and rerun validation rather than suppressing real defects.
npm scope not registered medium low Verify before R4; fall back to a different scope or unscoped if unavailable
Consumer switchover PR pulls in unrelated changes low medium Keep R5 to one PR, scoped strictly to package.json + lockfile + in-place plugin deletion
target/ caching defeats the affected story on rollout high medium Narrow outputs per target; cache reports not binaries where binaries embed absolute paths. Resolved 2026-05-12 for test (now outputs: []); build retains target/ outputs deliberately.

Decisions

  • D-M1: Validate first on the smallest crate (no internal deps) rather than a crate that touches everything. Accepted.
  • D-M2: Publish and consume via npm, not via git ref. Git refs work but hide drift. Accepted.

Open Questions

  • Do we want a release-please/changesets-driven release flow from v0.1, or is manual pnpm publish fine until v0.2?
  • Should the e2e/ fixture crate be generated at CI time via the crate generator (more realistic) or checked in (faster, more deterministic)?