Implement CENG-WP-0002: package distribution and publish readiness

Resolve ADR-0002 in umbrella, add install docs, contract sync runbook,
publishing checklist, and package files whitelist.
This commit is contained in:
2026-06-22 19:45:11 +02:00
parent a9e3b76a38
commit 697bc90780
5 changed files with 110 additions and 14 deletions

View File

@@ -7,6 +7,8 @@ This package provides the shared vocabulary (`Document`, `Selector`, `Annotation
canonical text normalization) together with in-memory repositories, orchestration
services, the event bus, and citation card renderers.
Published as **`@citation-evidence/engine`**.
## Layout
```
@@ -14,9 +16,58 @@ src/
shared/ # types, enums, pure helpers
engine/ # services, repositories, rendering, persistence
wiki/
SharedContracts.md # conformance reference (enum lists, normalization rules)
SharedContracts.md # conformance copy (authoritative: citation-evidence)
```
## Installing
### Local development (sibling checkout)
Repos are expected as siblings:
```
~/citation-evidence/
~/citation-engine/
~/evidence-anchor/
...
```
In the consumer's `package.json`:
```json
{
"dependencies": {
"@citation-evidence/engine": "link:../citation-engine"
}
}
```
Then `pnpm install`. TypeScript path aliases in consumers typically map
`@shared/*` and `@engine/*` to `../citation-engine/src/shared/*` and
`../citation-engine/src/engine/*` (see `CE-WP-0009` in citation-evidence).
### Registry install (when published)
```bash
pnpm add @citation-evidence/engine
```
Registry host TBD. See [Publishing checklist](#publishing-checklist) below.
### evidence-anchor (placeholder)
When `evidence-anchor` extracts, it will depend on engine types only:
```json
{
"dependencies": {
"@citation-evidence/engine": "link:../citation-engine"
}
}
```
Import shared types via `@shared/*` path aliases or `@citation-evidence/engine/shared`.
## Development
```bash
@@ -26,14 +77,31 @@ pnpm typecheck
pnpm lint
```
## Contract sync
See [`wiki/README.md`](wiki/README.md). Changes to shared contracts land in
`citation-evidence/wiki/SharedContracts.md` first, then sync here.
## Extraction status
Code was extracted from `citation-evidence/src/shared/` and `citation-evidence/src/engine/`
after the umbrella MVP (CE-WP-0001..0008) stabilized. The umbrella repo still carries
a copy during the transition; this repository is the canonical home going forward.
Code lives in `src/shared/` and `src/engine/`, extracted from the umbrella
MVP per `workplans/CENG-WP-0001-intent-placeholder.md`. The umbrella consumes
this package via `link:` per `CE-WP-0009`.
Contract changes belong in `citation-evidence/wiki/SharedContracts.md` first, then
sync to `wiki/SharedContracts.md` here.
## Publishing checklist
Use when a package registry is configured (ADR-0002: independent repos + publish).
- [ ] Set `private: false` (or scoped private per org policy)
- [ ] Confirm `files` in `package.json` includes `src/`, `wiki/`, `README.md`, `LICENSE`
- [ ] Decide: TypeScript sources via `exports` (current) vs `tsc` emit to `dist/`
- [ ] Bump semver: patch for fixes, minor for additive contracts, major for breaks
- [ ] Run `pnpm test && pnpm typecheck && pnpm lint` before publish
- [ ] Update consumers from `link:` to registry version
- [ ] Document registry URL and auth in org runbook (not in this repo)
No publish CI step is configured yet — credentials and registry choice are
out of scope until an external consumer requires it.
## Related repos