generated from coulomb/repo-seed
tegwick
2f25f99cae
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>
69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# 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.
|