generated from coulomb/repo-seed
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:
80
README.md
80
README.md
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user