Consumer Experience Review

Consumer-experience review

You are auditing a library as the people who will cargo add / npm install / pip install it — not as its author. Internal tests pass through the crate's own privacy and import context and therefore cannot see the gaps a real consumer hits (missing root re-exports, trait-import friction, method-name collisions, feature-flag dead-ends, error types you can't name). The only reliable instrument is a separate project that depends on the library externally and uses it the way a reasonable-but-not-omniscient user would.

Core principle

Write the code a competent user would write on their first try — reaching for conventional names and paths — and let it fail. The natural call that doesn't compile is the finding. Do not pre-correct your consumer code with insider knowledge; that hides exactly what you're looking for. Evidence is a captured compiler error, not an assertion.

Procedure

1. Map the public surface (don't trust memory — read it)

Enumerate what a consumer actually sees:

• Crate-root re-exports vs what's only reachable via deeper paths (crate::stores::Foo). Asymmetry here is the #1 source of findings.
• Traits and every method signature — look for two traits that define the same method name (collides when both are in scope; common with sync/async pairs), and for &mut self where a consumer would expect &self.
• Constructors / builders — is Type::new() returning Type or a builder? Is the fallible path build() or try_build()? Is it consistent across sibling types?
• Error types — can the error returned by a public function be named via the same path the type came from? (cached::Foo but only cached::stores::FooBuildError is a classic gap.)
• Feature flags — what's gated, and does a natural feature combination leave a type unreferenceable or a macro unusable?
• Macros — re-exported at the crate root (use lib::thing;) or only under a submodule? Ecosystem convention is root.

2. Scaffold a throwaway external consumer

• Put it in $TMPDIR (or another scratch path) — never inside the repo, never in git. Do not pollute the project's examples/, tests/, or working tree.
• Depend on the library by path with a realistic feature set:
  • Rust: lib = { path = "/abs/path", features = [...] }
  • npm: npm link / file: dependency. Python: pip install -e. Same idea — external module resolution, real package boundary.
• Exercise the breadth: each macro, direct store/type use, sync and async paths, builders, error handling, and at least one less-common feature combination.

3. Write naive-but-reasonable consumer code

Deliberately reach for conventions first:

• Import the macro from the crate root (use lib::macro;) before trying submodule paths.
• Bring the obvious traits into scope together (or glob use lib::*;) — exactly what a real user does.
• Name the error type returned by a builder/constructor in a let _: Option<lib::TheError> = None; or a function signature.
• Guess builder method names by convention (max_size, capacity, with_*) — a wrong guess that the compiler can't help disambiguate is a discoverability finding.

4. Compile, run, capture exact errors

cargo build/run (or the ecosystem equivalent). For every failure, record the exact diagnostic code and message (error[E0034]: multiple applicable items, E0432: unresolved import, E0599, etc.). That verbatim error is the evidence in your report.

5. Isolate each gap in a minimal probe

For each suspected issue, create a tiny separate binary/module that triggers only that issue with the smallest natural snippet. This (a) proves it's real and not a side effect, and (b) gives you a clean before/after to re-run once a fix is proposed/applied.

6. Severity — weight the release window

Rank findings, and explicitly factor in the version context:

• Pre-1.0 / major bump: a hard compile error on a common operation, or any public-surface inconsistency, is high — this is the only non-breaking window to fix the method/type surface. Say so.
• Post-1.0 minor: a breaking fix is itself a cost; lean toward additive fixes (new re-exports, #[doc(alias)], deprecations) and documentation.
• Always separate: 🔴 blocks/forces ugly workarounds on common paths · 🟠 awkward but workable · 🟡 docs/discoverability.