docs: test taxonomy + final ARCHITECTURE/AGENTS/README refresh — v1 prep 3/3#3
Merged
Merged
Conversation
Tests were already split along the standard taxonomy in practice
(cli-e2e.test.ts is e2e; vite/next/esbuild plugin tests are
integration; types.test.ts is a TS contract check; everything else
is unit) but nothing labelled the split, so 'I only changed the
vite plugin, do I need to wait for cli-e2e?' had no clear answer.
Adds the four scripts (all reuse the existing vitest.config.ts;
they just filter by --include / --exclude):
pnpm test:unit 213 unit tests (~1s)
pnpm test:integ 27 integ tests (~2s)
pnpm test:e2e 37 e2e tests (~5s)
pnpm test:contract 17 type tests (<1s)
pnpm test (all categories) and pnpm test:coverage (with thresholds)
behave exactly as before — CI keeps using test:coverage so coverage
floors are still enforced on every PR.
Documents the taxonomy in docs/ARCHITECTURE.md ('Testing strategy'
section reworked: category table + decision tree + conventions)
and surfaces the new scripts from CONTRIBUTING.md's 'Dev loop'.
vitest.config.ts coverage exclude list trimmed: src/utils/index.ts
and src/loaders/vite-env.ts no longer exist (removed in 28284d3),
so referencing them was stale.
…README appeal Brings the documentation set in sync with the refactored codebase and foregrounds the patterns that distinguish this library. New docs/TESTING.md (dedicated test-strategy reference): - unit / contract / integration / e2e taxonomy with file counts and per-category pnpm scripts - the nine-layer verify chain laid out as a single table - decision tree for placing new tests - coverage philosophy (why the floor sits just below current %) - mutation testing setup and exclusions - 'When tests don't catch a bug' triage flow docs/ARCHITECTURE.md refresh: - Error-throwing section reworked around ERROR_CATALOG: explains what flows from a single catalog entry (type union, severity getter, docsUrl, reportError output, doc table, verify pass). - New 'Single-source-of-truth as a recurring discipline' section catalogues the four places the package applies the pattern. - Two new code patterns documented: dispatch registry (#8) for cli/generate.ts and shared workspace runner (#9) for the three --workspace-capable subcommands. - Testing strategy section trimmed to a summary that defers to docs/TESTING.md. AGENTS.md sync: - Import map adds ERROR_CATALOG, reportError, ErrorSeverity, ErrorReport, esbuild plugin. - Error-handling section leads with severity buckets and the reportError() recipe instead of duplicating the catalog table. - File map regenerated: adds report-error.ts, presets.ts, todo.ts, cli/workspace-runner.ts, every generator, both build-tool adapters. - Verification layers table updated from seven entries to nine (verify:docs and verify:errors are now first-class). README.md refresh — the part users see first: - New 'Design principles' section foregrounds the four cross-cutting patterns (single source of truth, fail-at-the-earliest-moment, stable contract / evolving messages, frozen + layered). - New 'Error handling' section: severity-bucket table, reportError() example, sample ErrorReport payload. Replaces the previous bullet in 'Why use this'. - 'Why use this' bullets sharpened; the schema-first claim now lists all seven downstream artifacts. - Comparison table gains rows for the severity-aware error catalog and the CI-enforced contract checks. - Documentation section reorganised into users / contributors / meta groups; surfaces ARCHITECTURE.md and TESTING.md prominently. - Test count 292 -> 294, coverage 87% -> 89% in badges.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Final of three stacked PRs. Documentation + test-script categorisation — no source-code changes beyond the new
pnpm test:*scripts.Test categories made explicit
Tests already split along the standard unit / contract / integration / e2e taxonomy in practice (cli-e2e.test.ts was e2e; vite/next/esbuild plugin tests were integration; types.test.ts was a TS contract; everything else was unit) but nothing labelled the split. Adds four scripts that reuse the existing
vitest.config.tsand filter by path:pnpm test:unitpnpm test:integpnpm test:e2epnpm test:contractexpectTypeOf)pnpm testpnpm test:coverageCI keeps using
pnpm test:coverageso coverage floors are enforced on every PR.Documentation
docs/TESTING.md— dedicated test-strategy reference. Covers the taxonomy, the 9-layer verify chain, coverage philosophy, mutation testing, decision tree for new tests, "when tests don't catch a bug" triage flow.docs/ARCHITECTURE.mdrefresh — Testing section now defers todocs/TESTING.md; in its place, two new pattern entries: dispatch registry (🧊 Object.freeze() only freezes the top level — nested config is still mutable #8,cli/generate.ts) and shared workspace runner (😵 Confusing runtime error when envKey field uses .transform() #9,cli/workspace-runner.ts). Error-throwing section reworked aroundERROR_CATALOG. New "Single-source-of-truth as a recurring discipline" section catalogues the four places the package applies the pattern.AGENTS.mdsync — import map addsERROR_CATALOG,reportError,ErrorSeverity,ErrorReport. Error-handling section leads with severity buckets andreportError(err)instead of duplicating the ERRORS.md table. File map regenerated withreport-error.ts,presets.ts,todo.ts,cli/workspace-runner.ts, every generator, all build-tool adapters. Verification layers table updated 7 → 9.README.mdrefresh — the part users see first:reportError()example, sampleErrorReportpayload.Commits
Stacked PR
This is 3/3, stacked on
feat/error-catalog-v1(PR #2), which is stacked onrefactor/internal-patterns(PR #1).Merge order: #1 → #2 → #3. After #1 and #2 merge, GitHub will auto-update this PR's base to
main.Test plan
pnpm test:unit/:integ/:e2e/:contract— each runs the expected subset.pnpm test— 294 passing.pnpm verify— full 9-layer chain.docs/TESTING.mdend-to-end — does the decision tree match your intuition for "where does this test go?"README.md"Design principles" — does it accurately sell what we've built?