generated from coulomb/repo-seed
Implement CE-WP-0001 Foundations: TS scaffold, lint boundaries, normalize v1, fixtures
T01 Toolchain — vite + pnpm 9.15 + React 18 + strict TS (ADR-0001).
T02 Folder layout — src/{shared,engine,anchor,source,binder,work,app}/
mirroring the future subsystem split, with path aliases.
T03 Boundary lint — eslint-plugin-boundaries enforcing the dependency
edges from wiki/DependencyMap.md §4; verified by a violating fixture.
T04 Canonical normalization v1 — src/shared/text/normalize.ts with
NORMALIZE_VERSION=1; 10/10 vitest covering ligatures, CRLF, soft
hyphens (including line-break reassembly), mixed whitespace.
T05 PDF fixture corpus — 7 user-supplied German PDFs in fixtures/pdfs/
(gitignored binaries) plus a manifest with verbatim known-good
quotes and page counts, ready for CE-WP-0002 selector tests.
T06 README upgrade — umbrella README points at wiki/docs/workplans
and documents the dev workflow.
T07 ADR-0002..0006 stubs in docs/decisions/.
Toolchain end-to-end: pnpm install + lint + typecheck + test all green.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
68
docs/decisions/ADR-0001-toolchain.md
Normal file
68
docs/decisions/ADR-0001-toolchain.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# ADR-0001 — Toolchain (Vite + pnpm + React 18 + strict TypeScript)
|
||||
|
||||
- Status: accepted
|
||||
- Date: 2026-05-24
|
||||
- Workplan: CE-WP-0001-T01
|
||||
|
||||
## Context
|
||||
|
||||
`citation-evidence` is the umbrella repo for an MVP that will eventually be
|
||||
segmented into six packages (`shared/engine`, `anchor`, `source`, `binder`,
|
||||
`work`, `app` per `wiki/DependencyMap.md`). We need a single toolchain that:
|
||||
|
||||
1. Gives a fast inner dev loop for a React-based reference workspace.
|
||||
2. Plays well with a future pnpm workspace split (so each `src/<name>/` folder
|
||||
can become a workspace package with a `git mv` and a `package.json` cut).
|
||||
3. Provides first-class TypeScript with the strictest practical settings — the
|
||||
shared contracts in `wiki/SharedContracts.md` only pay off if the type
|
||||
system actually enforces them.
|
||||
4. Has a credible unit-test story for the engine/anchor/source pure-logic code
|
||||
and an integration path for the UI later.
|
||||
|
||||
## Options considered
|
||||
|
||||
- **Vite + pnpm + React + Vitest** *(chosen)*
|
||||
- Fast HMR; well-supported React plugin; Vitest shares the Vite pipeline so
|
||||
tests use the same module resolution as the app.
|
||||
- pnpm workspaces are the most ergonomic path to the eventual multi-package
|
||||
split.
|
||||
- React 18 because the PRD's reference workspace is a desktop-class web app
|
||||
and the ecosystem (PDF viewer libraries, drag-and-drop, etc.) targets it.
|
||||
|
||||
- **Next.js (App Router)**
|
||||
- Heavier than needed for a local-first reference workspace; SSR/route
|
||||
handlers add complexity the MVP doesn't use.
|
||||
- Harder to split into independent packages later.
|
||||
|
||||
- **tsc-only + custom runner**
|
||||
- Simplest, but no HMR and we'd hand-roll the React + bundler integration.
|
||||
Pointless overhead for a UI-centric project.
|
||||
|
||||
- **Bun / Deno**
|
||||
- Toolchain bets that would add risk to the PDF/viewer integration spike,
|
||||
which is already the highest-risk part of the project (see
|
||||
`CE-WP-0002-T02`).
|
||||
|
||||
## Decision
|
||||
|
||||
Use **Vite 5** + **pnpm 9** + **React 18** + **TypeScript 5 with `strict`,
|
||||
`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noImplicitOverride`,
|
||||
`noFallthroughCasesInSwitch`, `verbatimModuleSyntax`** turned on. Use
|
||||
**Vitest 2** as the test runner. Node version pinned to **20.10.0 LTS** via
|
||||
`.nvmrc`. Path aliases (`@shared/*`, `@engine/*`, etc.) map to `src/<name>/*`
|
||||
so import sites read the same whether or not the folder is later extracted.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Bumping React or Node is a deliberate, ADR-worthy change.
|
||||
- The eventual pnpm workspace split keeps the same import names — each
|
||||
package's `name` becomes `@citation-evidence/<folder>` and the path aliases
|
||||
are replaced by package resolution. No source-code churn required.
|
||||
- Vitest's Vite-aware resolution means a contract test that imports across
|
||||
partitions will fail at the same boundary that production code would —
|
||||
there is no test-only loophole.
|
||||
- ESLint rules enforcing the dependency map (CE-WP-0001-T03) layer on top
|
||||
cleanly: `eslint-plugin-boundaries` reads the same `tsconfig` paths.
|
||||
- No application dependencies are installed in this task — only the toolchain.
|
||||
Subsequent workplans install PDF, drag-and-drop, etc. on demand and record
|
||||
them in their own ADRs where the choice is non-obvious.
|
||||
Reference in New Issue
Block a user