generated from coulomb/repo-seed
tegwick
697bc90780
Resolve ADR-0002 in umbrella, add install docs, contract sync runbook, publishing checklist, and package files whitelist.
112 lines
3.1 KiB
Markdown
112 lines
3.1 KiB
Markdown
# citation-engine
|
|
|
|
Core domain model and engine services for the citation-evidence ecosystem.
|
|
|
|
This package provides the shared vocabulary (`Document`, `Selector`, `Annotation`,
|
|
`EvidenceItem`, `EvidenceLink`, `EvidenceSet`, state enums, branded IDs,
|
|
canonical text normalization) together with in-memory repositories, orchestration
|
|
services, the event bus, and citation card renderers.
|
|
|
|
Published as **`@citation-evidence/engine`**.
|
|
|
|
## Layout
|
|
|
|
```
|
|
src/
|
|
shared/ # types, enums, pure helpers
|
|
engine/ # services, repositories, rendering, persistence
|
|
wiki/
|
|
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
|
|
pnpm install
|
|
pnpm test
|
|
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 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`.
|
|
|
|
## 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
|
|
|
|
- [`citation-evidence`](../citation-evidence/) — umbrella reference workspace
|
|
- [`evidence-anchor`](../evidence-anchor/) — selector creation and resolution
|
|
- [`evidence-source`](../evidence-source/) — document ingestion
|
|
- [`citation-work`](../citation-work/) — review workspace UX
|
|
- [`evidence-binder`](../evidence-binder/) — evidence-to-field linking |