generated from coulomb/repo-seed
tegwick
dd2f2115bd
Add link: dependency on citation-engine, retarget @shared/@engine aliases, remove in-repo shared/engine copies. ADR-0002 accepted (option B). 172 tests, typecheck, and lint pass.
74 lines
3.3 KiB
Markdown
74 lines
3.3 KiB
Markdown
# ADR-0002 — Monorepo vs polyrepo for the six subsystems
|
|
|
|
- Status: accepted
|
|
- Date: 2026-05-24
|
|
- Decided: 2026-06-22
|
|
- Workplan: CENG-WP-0002-T01
|
|
|
|
## Context
|
|
|
|
The umbrella-first MVP lives entirely in `citation-evidence/` under
|
|
`src/{anchor,source,binder,work,app}/` with shared types and engine services
|
|
in the extracted `@citation-evidence/engine` package (`citation-engine` repo).
|
|
|
|
Each remaining folder is named after its eventual extracted package. At some
|
|
point — driven by an external consumer needing one subsystem, or by independent
|
|
release cadence — code will move out into its sister repo.
|
|
|
|
We need a written answer to: when that moment comes, do we (a) keep one
|
|
repository with pnpm workspaces, (b) split into six independent repos with
|
|
published packages, or (c) something in between?
|
|
|
|
The decision affects: dependency management, release cadence, CI surface
|
|
area, contributor friction, and how `wiki/SharedContracts.md` is enforced
|
|
across the boundary.
|
|
|
|
## Options
|
|
|
|
- **A. Single repo, pnpm workspaces**
|
|
- Pros: one CI, one version of every dep, atomic cross-package PRs, easy
|
|
refactors. Shared contracts enforced by the type checker.
|
|
- Cons: any consumer outside this repo needs a private registry or
|
|
git-tag-based installs. Release cadence is shared.
|
|
|
|
- **B. Six independent repos, published packages**
|
|
- Pros: clean external publish story, independent versioning. Forces the
|
|
contract to be a real package boundary.
|
|
- Cons: dependency upgrades require coordinated PR trains. Refactors that
|
|
span subsystems become multi-repo dances. Hard to keep
|
|
`SharedContracts.md` in sync across repos.
|
|
|
|
- **C. Hybrid — monorepo with publishable workspaces**
|
|
- Pros: best of both: one repo for dev, but `pnpm publish` from any
|
|
workspace package. Tools: changesets / nx / turbo.
|
|
- Cons: more tooling to learn; per-workspace `package.json` cuts to
|
|
maintain.
|
|
|
|
## Decision
|
|
|
|
**B — six independent repos with published packages**, using **`link:` sibling
|
|
dependencies during local development** until a registry is configured.
|
|
|
|
Rationale:
|
|
|
|
1. The ecosystem is already organized as six sister repos plus the umbrella;
|
|
independent repos match the documented architecture.
|
|
2. `citation-engine` extraction (`CENG-WP-0001`) and umbrella wireup
|
|
(`CE-WP-0009`) prove the `link:../citation-engine` dev workflow.
|
|
3. Publishing can be deferred — no registry is configured yet — without
|
|
blocking extraction of the remaining subsystems.
|
|
4. Option C adds tooling overhead before any external consumer exists.
|
|
|
|
## Consequences
|
|
|
|
- **Local dev:** sister repos sit as siblings under `~/` (or equivalent).
|
|
Consumers declare `"@citation-evidence/engine": "link:../citation-engine"`.
|
|
- **Publishing:** when a registry is chosen, bump `@citation-evidence/engine`
|
|
semver and replace `link:` with the registry version in consumer repos.
|
|
- **Contracts:** `citation-evidence/wiki/SharedContracts.md` stays authoritative;
|
|
`citation-engine/wiki/SharedContracts.md` is a conformance copy (see
|
|
`citation-engine/wiki/README.md`).
|
|
- **Versioning:** engine package semver tracks API/contract changes; umbrella
|
|
and sister repos pin or range-pin on publish.
|
|
- **CI:** each repo runs its own test/lint pipeline; cross-repo integration
|
|
tests remain in `citation-evidence` until subsystems extract fully. |