feat(contract): analysis.json schema, generated types and validator

[jundymek]

Adds the analysis.json contract: the frozen draft 2020-12 JSON Schema, the
TypeScript types generated from it, a compiled-once ajv validator and the
intermediate pipeline types. This is the single interface between modules
(AD-1) — every other package now has one machine-checked truth to build
against.

The schema is the source; the types are generated (AD-9).
scripts/generate-types.mjs writes src/generated/analysis.ts, which is
committed with a do-not-edit banner and excluded from ESLint. A new CI step
regenerates it and runs git diff --exit-code, so hand-edited drift cannot
reach the base branch. The hand-written intermediate types derive from the
generated ones via Pick/Omit, which turns a future schema change into a
compile error in scanner/deps/githist/cli rather than silent divergence.

validateAnalysis compiles the schema once at module load, because both the
cli (validating what it just assembled) and the Viewer (validating what it just
fetched) sit on a hot path. It narrows to AnalysisDocument on success, and
missing-property errors are rewritten to point at the absent field
(/nodes/0/loc) instead of at its parent object, so an AD-7 cli message can
print the pointer verbatim.

The package stays environment-neutral (AC-5): no node: import anywhere under
src/, enforced structurally by a tsconfig with neither DOM lib nor node
types, and verified by the viz browser bundle building with the contract
imported. scripts/ is build tooling, outside the runtime path, and uses Node
freely.

Decisions worth a reviewer's attention

• Co-change count is bounded >= 1 in the schema, not >= 3. FR-7 marks
  that threshold as tunable analyzer policy; baking it into a frozen schema
  would make tuning a version bump. githist (2.3) must enforce it — the
  contract will not.
• repo.stats.languages is a share map (name → 0..1), per FR-7's
  "language shares". scanner (2.1) must normalize, not emit raw counts.
• lastChangedAt is nullable — the zero-history fixture has no commit
  instant and AD-13 forbids clock reads, so there is no fallback. Story 1.3's
  zero-history fixture relies on this.
• description/descriptionSource are typed null, required-present, per
  FR-8. Widening them to string | null stays the describe layer's own minor,
  non-breaking act.
• The date-time format is deliberately narrower than RFC 3339: it rejects
  a leap second (23:59:60), which §5.6 permits. Nothing on either side can
  represent one — git stores POSIX epoch seconds, and
  new Date("2026-12-31T23:59:60Z") is Invalid Date — so accepting it would
  move the failure from validation time to a NaN in the Viewer's panel. The
  governing rule is stated as an invariant and asserted by test: every instant
  the contract accepts parses with new Date(...). Five Codex review passes
  drove this, each one correct; the format began as a digit-placement regex that
  accepted 2026-99-99T25:61:61Z. Year 0000 is rejected on the same reasoning:
  it parses, but a zero year is an upstream parsing bug, not a commit timestamp.
• Per-story docs follow the spec's docs/dev/epic-1/… path rather than the
  generic checklist's docs/features/epic-1-omdb-data-layer/…, which belongs
  to another project's map.

The schema-change protocol — when a change is minor versus major, and what a
major bump obliges — is written up in
docs/dev/epic-1/1.2-contract-schema/README.md.

Manual verification

Not applicable, and deliberately so rather than skipped: this story ships no
UI, no CLI entry point and no observable runtime behaviour. Its whole surface is
a JSON Schema, types generated from it, and one pure function
unknown -> ValidationResult. Every acceptance criterion is a statement about
which documents validate — exactly what a unit test expresses and what clicking
cannot. The two criteria that are not pure unit assertions were executed anyway:

• AC-2 (type freshness): ran the CI step locally —
  pnpm --filter @gitnebula/contract generate then
  git diff --exit-code -- packages/contract/src/generated → no drift.
• AC-5 (environment neutrality): ran pnpm build — the vite browser bundle
  builds with the contract imported, and src/ contains no node: import.

Automated: 82 tests pass; root pnpm lint, pnpm typecheck, pnpm test and
pnpm build are clean. The suite was mutation-checked rather than merely
observed passing — eight separate mutations of the validator and schema each
fail between 1 and 35 tests (details in the story's Dev Agent Record).

Codex review: 4 findings total, 4 fixed, 0 dismissed, 0 escalated, across five
passes — every one on the date-time format. The concurrent auto-review of the
same tree reported no actionable regressions.

Refs: 1.2-contract-schema
Agent: bob (terminal-agents, claude-opus-5)