audit-crates

name

audit-crates

description

Audit and fix crate/package consistency in the amigo-native monorepo. Use whenever new crates are added, branches are merged that introduced new crates, or you need to verify every crate follows the reference conventions established by argon2/csv/sanitize-html/slugify/xxhash. Checks __conformance__ test infrastructure (parity.spec.ts/upstream.spec.ts + fuzz.spec.ts), package.json scripts (test:conformance, test:all) and dev-deps (fast-check), README presence, npm/ platform-stub directories (6 NAPI targets), docs/packages.json registration with all metadata fields, and marquee PACKAGES count. Flags the legacy __parity__/test:parity convention as outdated. After reporting gaps, this skill offers to apply the fix plan interactively — mechanical fixes (renames, script patches, npm stubs) get applied automatically, content fixes (README, docs entries, fuzz tests) get generated as templates the user reviews. Run this before publishing, before opening PRs that add crates, after merging feature branches, or when CI fails on test:conformance or missing platform binaries.

audit-crates

Verify every crates/* entry in the amigo-native monorepo conforms to the reference conventions established by argon2, csv, sanitize-html, slugify, and xxhash — then offer to fix the gaps.

When to use

• After adding a new crate under crates/
• After merging a branch that introduced new crates (conventions diverge easily in parallel work)
• Before publishing or opening a PR that touches package layout
• When CI complains about test:conformance or missing platform stubs
• When the GitHub Pages dashboard shows wrong package count or missing entries

Workflow — how Claude should run this skill

The skill is interactive. Don't just dump the report and stop — offer to apply the fix plan at the end. The concrete loop:

Step 1 — Run the audit

node .claude/skills/audit-crates/scripts/audit.mjs

The script exits non-zero if gaps exist. Read the output — you'll need it for step 3.

Step 2 — If clean, you're done

If the audit reports "All crates conform", confirm briefly to the user and stop.

Step 3 — If gaps exist, fetch the fix plan

node .claude/skills/audit-crates/scripts/audit.mjs --plan

The plan is grouped into sections:

1. Automatable — bash commands that run unattended (renames, script rewrites, napi create-npm-dirs, pnpm add -D fast-check, marquee updates)
2. README templates — per-crate markdown skeletons
3. docs/packages.json entries — JSON skeletons with TODO placeholders for description and speedup
4. fuzz.spec.ts skeleton — a fast-check property-test starting point

Step 4 — Ask the user, tersely

One line summary (e.g. "10 gaps: 10 READMEs, 10 docs entries, 10 fuzz skeletons"), then three options, nothing more:

A mechanical only · B full pass · C report only

Wait for the answer. Honour custom splits ("just READMEs"). No preamble, no recap.

Step 5 — Execute according to the answer

• A: Run section 1 commands. Verify with node .claude/skills/audit-crates/scripts/audit.mjs after. Report what's left.
• B: A, then for each content section walk crate-by-crate. For speedups, check docs/data.json — if unmeasured, write "TBD" rather than inventing numbers. For fuzz tests, read the crate's src/lib.rs and __test__/ to understand the API before writing properties.
• C: Stop. Leave the plan output visible so the user can work from it.

After any fix pass, commit using conventional commits (refactor:, feat:, docs:) — one commit per logical group (mechanical fixes, READMEs, docs entries) so the history stays reviewable.

What it checks

For each crate (excluding _template):

Check	Why it matters
__conformance__/ with parity.spec.ts or upstream.spec.ts	Drop-in parity coverage vs. the npm original (either pattern counts)
__conformance__/fuzz.spec.ts	Property-based tests that catch semantic drift
package.json scripts: test, test:conformance, test:all, bench	Reference-convention test entrypoints
fast-check in devDependencies	Only needed when fuzz.spec.ts exists
README.md	Every published package needs one
npm/ with 6 platform subdirs (darwin-arm64, darwin-x64, linux-arm64-gnu, linux-x64-gnu, linux-x64-musl, win32-x64-msvc)	NAPI-RS platform-stub packages — without them, npm install fails on that platform
__bench__/index.bench.ts	Vitest benchmark suite consumed by bench:report
Registered in docs/packages.json with all metadata fields	Appears on the GitHub Pages dashboard
WASM dual-target scaffolding (wasm/Cargo.toml, wasm/src/lib.rs, wasm/tests/web.rs, build:wasm script, browser export, the five underscored wasm/pkg/* entries in files, an "Install for the browser" README section, a declared amigo.targets)	Browser bundlers (Vite, webpack, Angular CLI) resolve the browser conditional export; the files entries make sure the tarball actually ships the WASM artifact. Required for every crate not in NODE_ONLY_CRATES.

Node.js server-only group

A small, explicit allow-list of crates intentionally stays Node-only and must NOT have a wasm/ directory:

Crate	Reason
argon2	Performance — ~2× slower in WASM than native (memory-hard hash); browser password hashing is an anti-pattern
jose	Server-only crypto — private signing keys must not ship to the browser
jwt	Server-only crypto — same as jose

The list is the single source of truth — duplicated as a constant in audit.mjs (NODE_ONLY_CRATES), scripts/sync-registry.mjs, scripts/build-all-wasm.mjs, scripts/scaffold-wasm-bench.mjs, .github/workflows/ci.yml, and .github/workflows/release.yml. To add or remove a crate from the group, edit all six spots together. See docs/specs/expansion-2026.md § Node.js server-only tier for the policy.

Globally:

• docs/packages.json marquee PACKAGES value equals the crate count (docs/data.json is auto-generated benchmark output; packages.json holds the hand-edited brand/marquee/registry)
• docs/packages.json marquee TARGETS reflects the dual-target / Node-only split
• Every crate is registered in release-please-config.json and .release-please-manifest.json (both hand-maintained; a missing entry means no release PRs / npm publishes)
• Legacy __parity__/ dirs or test:parity scripts are flagged as must modernize

Invocation flags

Flag	Purpose
(none)	Markdown report (default — what you show the user first)
--plan	Executable fix plan — bash commands + templates
--json	Machine-readable output for scripting or CI gates

All modes exit non-zero on gaps.

Why the conventions matter

The reference crates were set up so parity with the npm original can be verified independently per-crate (pnpm --filter <crate> run test:conformance) instead of only via a central script. Each crate owns its own conformance suite, and CI can gate on it selectively. fast-check enables property-based fuzz testing — that's how semantic drift gets caught automatically when upstream changes.

The npm/ platform stubs are what @napi-rs/cli publishes as optionalDependencies. Tiny metadata packages, but without them npm install fails on platforms with no matching binary — the publish is effectively broken.

And docs/packages.json is the single source of truth for the GitHub Pages dashboard. A package not listed there is invisible to users even if it's on npm.

A crate that drifts from the conventions will eventually cause a CI failure, a broken install on some platform, or an embarrassing gap on the landing page. This skill catches — and offers to fix — all three before they ship.

Extending the audit

If you add a new convention (e.g. a required CHANGELOG.md, a new lint step), add the check to scripts/audit.mjs in the auditCrate function, then extend the --plan output with the corresponding fix template. Keep checks cheap (no network, no subprocess) so the audit stays fast and CI-friendly.