# Neith Release Developer Guide

This guide is for contributors extending `@neith/release`.

## Package Layout

```text
libs/neith/release/
  src/
    pipeline/      release authoring, rollout, and lifecycle logic
    distribution/  artifact hosting, integrity, update, and licensing flows
    platform/      packaging and store/marketplace publishing helpers
    performance/   benchmark scenarios and budget reports
    types.ts       shared release-domain types
    index.ts       public package surface
  tests/
    *.spec.ts      package verification, including documentation coverage
```

## Development Rules

- Keep modules pure and data-driven where possible. Most package APIs generate
  plans, manifests, commands, or reports rather than performing network I/O.
- Prefer deterministic outputs. Tests depend on stable artifact names, generated
  commands, and release workflow text.
- Preserve semantic versioning guarantees for exported types and classes.
- When adding a new module, update the relevant barrel export, external docs,
  and the coverage audit in
  `docs/domains/neith/release/documentation-coverage.md`.

## Extending Pipeline Features

Pipeline modules model release control-plane concerns:

- `branching-strategy.ts` and `version-numbering.ts` define release-train and
  semantic-version behavior.
- `release-automation.ts`, `release-candidates.ts`, and `staged-rollouts.ts`
  define gated execution and promotion flows.
- `feature-gates.ts`, `rollback.ts`, `hotfix.ts`, and `security-releases.ts`
  cover safe rollout, incident response, and security handling.
- `lts-support.ts`, `end-of-life.ts`, `upgrade-paths.ts`, and
  `compatibility-matrix.ts` model lifecycle support obligations.

When you add a pipeline capability:

1. Add or extend the module in `src/pipeline/`.
2. Export it from `src/pipeline/index.ts` and `src/index.ts` when appropriate.
3. Add or expand Vitest coverage in `tests/pipeline.spec.ts`.
4. Update the API reference and documentation coverage matrix.

## Extending Distribution Features

Distribution modules materialize operational release assets:

- `download-infrastructure.ts`, `cdn.ts`, and `mirror-network.ts` cover artifact
  delivery paths.
- `checksum.ts` and `signature.ts` handle integrity and authenticity evidence.
- `installer.ts`, `offline-installer.ts`, and `package-repos.ts` generate
  installable release formats and repository metadata.
- `auto-update.ts`, `delta-updates.ts`, and `enterprise-distribution.ts` cover
  update channels and managed deployment.
- `site-licensing.ts`, `volume-licensing.ts`, `trial-versions.ts`, and
  `freemium.ts` handle commercial packaging strategies.

Prefer composable data structures over embedding platform policy into tests.

## Extending Platform Publishing

Each module in `src/platform/` represents a publishing target or packaging
surface. Keep interfaces platform-specific and keep generated command lists or
manifest objects explicit so downstream automation can inspect them.

The web module is special because it also owns:

- cache and security-header defaults
- WCAG 2.1 AA accessibility auditing
- accessibility statement generation

Any change to the web distribution surface should extend
`tests/platform.spec.ts`.

## Performance And Documentation Gates

- `tests/performance.benchmark.spec.ts` enforces budget compliance for the
  benchmark scenarios in `src/performance/release-benchmarks.ts`.
- The same benchmark suite also enforces the certified `< 5%` regression gate
  against the stabilized baseline ledger in
  `src/performance/release-benchmarks.ts`.
- `tests/documentation.spec.ts` enforces source-file documentation coverage and
  validates doc links in the release docs hub.

Keep both gates green before merging.

## Local Workflow

```bash
pnpm nx run @neith/release:typecheck
pnpm nx run @neith/release:lint
pnpm nx run @neith/release:test
pnpm nx run @neith/release:benchmark
```

For documentation changes, also check formatting:

```bash
pnpm exec prettier --check \
  docs/domains/neith/README.md \
  docs/domains/neith/release/**/*.md \
  libs/neith/release/README.md
```
