50 lines
2.2 KiB
Markdown
50 lines
2.2 KiB
Markdown
# OpenSpec Change: enterprise-overview
|
|
|
|
- **Change ID**: enterprise-overview
|
|
- **Package**: `@suaveplan/overview`
|
|
- **Category**: universal
|
|
- **Target path**: `universal/docs/overview`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-19
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/overview.md`
|
|
|
|
## Summary
|
|
|
|
Documentation-only package publishing a curated, machine-readable description of the whole monorepo: every package name, one-line purpose, category, dependency edges, layer index, and current genesis status. Consumed by dashboards, README generators, and AI agents (including `openspec/AGENTS.md` tooling). Zero runtime code — ships a typed JSON manifest plus a validator.
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
Does not exist on genesis. Genesis currently has `CLAUDE.md` / `FOLDERS.yml` as the authoritative monorepo map; this package turns them into a consumable data artifact.
|
|
|
|
## Dependencies
|
|
|
|
- Workspace: none (leaf)
|
|
- External (via catalog): `zod` → `catalog:forms`
|
|
- Dev (via catalog): `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata` → `catalog:testing`
|
|
|
|
## Preserved public surface
|
|
|
|
### Data artifact
|
|
- `manifest.json` — top-level `{ generatedAt, version, categories: Category[], packages: Package[] }`
|
|
- `Category` — `{ slug, title, parentCategory?, description }`
|
|
- `Package` — `{ name, category, path, layer, summary, dependsOn: string[], status: 'genesis' | 'pending' | 'archived', version }`
|
|
|
|
### Runtime API
|
|
- `loadManifest(path?)` — load and Zod-validate a manifest file.
|
|
- `validateManifest(obj)` — `ManifestSchema.parse`.
|
|
- `layerFor(name, manifest)` — returns the topological layer (0 = leaves).
|
|
- `dependentsOf(name, manifest)`, `dependenciesOf(name, manifest)` — graph walkers.
|
|
- `ManifestSchema`, `CategorySchema`, `PackageSchema` — Zod schemas.
|
|
|
|
## New genesis additions
|
|
|
|
- Codes via `defineCodes`: `OVERVIEW.MANIFEST_INVALID`, `OVERVIEW.CYCLE_DETECTED`, `OVERVIEW.PACKAGE_NOT_FOUND`.
|
|
- Property-based tests (fast-check): cycle detection on random DAGs, topo-layer correctness.
|
|
- Build step reads `FOLDERS.yml` + every workspace `package.json` and regenerates `manifest.json` at the repo root.
|
|
|
|
## Impact
|
|
|
|
- Adds one new package: `universal/docs/overview`
|
|
- Adds one new spec capability: `overview`
|
|
- Does not depend on anything.
|