179 lines
6.8 KiB
Markdown
179 lines
6.8 KiB
Markdown
# OpenSpec Change: enterprise-overview
|
||
|
||
- **Change ID**: enterprise-overview
|
||
- **Package**: `@suaveplan/overview`
|
||
- **Category / plugin**: `devtools/tooling`
|
||
- **Target path**: `packages/devtools/tooling/overview`
|
||
- **Status**: PROPOSED
|
||
- **Date**: 2026-05-25
|
||
- **Design**: ./design.md
|
||
- **Spec delta**: ./specs/overview/spec.md
|
||
- **Reference docs**:
|
||
- `/mnt/s/web/suaveplan/enterprise/overview.md` (enterprise contract)
|
||
- `/mnt/s/web/suaveplan/packages/universal/overview/` (upstream — documentation-only bundle)
|
||
- `scripts/folder-reorg/generate-manifest.ts` (genesis data model — the script
|
||
explicitly notes "Replaces @suaveplan/overview"; this migration restores
|
||
`overview` as the **library form** of that same data model)
|
||
- `CLAUDE.md` foundation listing: "**overview** — machine-readable monorepo
|
||
manifest with Zod schemas + graph utilities. Leaf."
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
Migrate `@suaveplan/overview` onto genesis as a fresh, enterprise-grade
|
||
universal-tier **machine-readable monorepo manifest + graph-utilities library**.
|
||
|
||
The upstream main-branch package is a documentation bundle (≈90 ad-hoc `.md`
|
||
files plus a 27-line `postinstall.ts` that rewrites links). It carries no
|
||
runtime API, no tests, no schemas. That artefact is not enterprise-grade and
|
||
cannot be ported as-is.
|
||
|
||
The genesis form is a different package by name only: a typed library that
|
||
discovers every `packages/<category>/<plugin>/<pkg>/package.json` on disk,
|
||
parses each into a Zod-validated `PackageRecord`, exposes a typed
|
||
`SuavePlanManifest`, and provides graph utilities (forward / reverse adjacency,
|
||
topological order, cycle detection, transitive closure, leaf / root detection,
|
||
tier overlay, plugin and category roll-ups).
|
||
|
||
The same data model is currently produced ad-hoc by
|
||
`scripts/folder-reorg/generate-manifest.ts`, whose own header comment says
|
||
"Replaces @suaveplan/overview". This change re-introduces `overview` as the
|
||
**library** form of that script — single source of truth, exported as a typed
|
||
API, fully testable, with full enterprise instrumentation. The script can later
|
||
be refactored to consume the library; that refactor is out of scope for this
|
||
change.
|
||
|
||
---
|
||
|
||
## Current-state audit (genesis)
|
||
|
||
- Package directory does not exist on genesis.
|
||
- `STATUS.md` lists `@suaveplan/overview` as `–` (yet to migrate) under
|
||
`devtools/tooling`.
|
||
- `scripts/folder-reorg/assignment.yml` line 665 confirms `tooling/overview`.
|
||
- `MANIFEST.md` does not yet contain an `@suaveplan/overview` row.
|
||
- `CLAUDE.md` foundation listing already describes the intended genesis shape
|
||
(machine-readable manifest + Zod schemas + graph utilities) — this change
|
||
realises that description.
|
||
|
||
**Verified by:** `ls packages/devtools/tooling/` (no `overview/`),
|
||
`grep -n "overview" STATUS.md` (one `–` row).
|
||
|
||
---
|
||
|
||
## Parity & enhancement checklist
|
||
|
||
The upstream package has no runtime surface, so this is functionally a
|
||
**genesis-original** library aligned to the data model already encoded by
|
||
`scripts/folder-reorg/generate-manifest.ts`. Every column below has a
|
||
compensating enhancement; nothing is dropped.
|
||
|
||
| Capability | Upstream | Migrated | Notes |
|
||
|---|---|---|---|
|
||
| `.md` documentation bundle | ✅ docs-only | 🚫 dropped | Genesis ships per-package `README.md` + co-located `.md`; central doc bundle is obsolete. Replaced by **machine-readable manifest** as the cross-package index. |
|
||
| `postinstall.ts` link-rewriter | ✅ | 🚫 dropped | No `dist/*.md` to rewrite on genesis. Replaced by typed API. |
|
||
| Package discovery | 🚫 | ⬆️ NEW | `discoverPackages(root)` walks `packages/<category>/<plugin>/<pkg>/package.json`. |
|
||
| Zod schemas for every type | 🚫 | ⬆️ NEW | `PackageRecordSchema`, `SuavePlanManifestSchema`, `TierSchema`, `PluginSummarySchema`. |
|
||
| Tier inference | 🚫 | ⬆️ NEW | python → r3f → react → browser → server → universal (matches `openspec/specs/monorepo-structure/spec.md`). |
|
||
| Graph utilities | 🚫 | ⬆️ NEW | forward / reverse adjacency, topo sort, cycle detection, transitive closure, leaves, roots. |
|
||
| Plugin + category roll-ups | 🚫 | ⬆️ NEW | `byPlugin()`, `byCategory()`, `byTier()`. |
|
||
| Stable error codes via `defineCodes` | 🚫 | ⬆️ NEW | 6 `OVERVIEW.*` codes — each thrown from a real call site. |
|
||
| OpenTelemetry counters + histogram | 🚫 | ⬆️ NEW | 3 counters + 1 histogram. |
|
||
| `AbortSignal` support on async I/O | 🚫 | ⬆️ NEW | `discover` accepts `signal`; aborts mid-walk. |
|
||
| 100/100/100/100 Istanbul coverage | 🚫 | ⬆️ NEW | Test gate. |
|
||
| Co-located `.md` per implementation `.ts` | 🚫 | ⬆️ NEW | §4 docs rule. |
|
||
| Universal tier (zero Node-only run-time imports in library code) | n/a | ✅ | I/O helpers are server-tier and gated behind a sub-path entry; pure data + graph code is universal. |
|
||
|
||
No 🚫 entry without compensating ⬆️ enhancement.
|
||
|
||
---
|
||
|
||
## Available workspace deps on genesis
|
||
|
||
| Package | Role |
|
||
|---|---|
|
||
| `@suaveplan/error` (`workspace:^`) | `SuaveplanError` base + `defineCodes` |
|
||
| `@suaveplan/types` (`workspace:^`) | shared `Clock`-style types |
|
||
| `tslib` (`catalog:build`) | runtime helpers |
|
||
| `zod` (`catalog:forms`) | schemas |
|
||
| `@opentelemetry/api` (`catalog:observability`) | counters + histogram |
|
||
|
||
Dev deps: `@suaveplan/testing` (`workspace:^`), `vitest`,
|
||
`@vitest/coverage-istanbul`, `typescript`, `vite`, `vite-plugin-dts`.
|
||
|
||
---
|
||
|
||
## Public API surface (summary)
|
||
|
||
```ts
|
||
import {
|
||
// schemas
|
||
PackageRecordSchema,
|
||
SuavePlanManifestSchema,
|
||
TierSchema,
|
||
// discovery (server sub-path: "@suaveplan/overview/discover")
|
||
discoverPackages,
|
||
// graph
|
||
buildGraph,
|
||
topologicalOrder,
|
||
detectCycles,
|
||
transitiveDependencies,
|
||
transitiveDependents,
|
||
leafPackages,
|
||
rootPackages,
|
||
// roll-ups
|
||
byPlugin,
|
||
byCategory,
|
||
byTier,
|
||
// errors
|
||
OVERVIEW_CODES,
|
||
OverviewError,
|
||
} from "@suaveplan/overview";
|
||
|
||
// Types
|
||
import type {
|
||
PackageRecord,
|
||
SuavePlanManifest,
|
||
Tier,
|
||
PluginSummary,
|
||
WorkspaceGraph,
|
||
} from "@suaveplan/overview";
|
||
```
|
||
|
||
---
|
||
|
||
## File layout
|
||
|
||
```text
|
||
packages/devtools/tooling/overview/
|
||
package.json, tsconfig.lib.json, vite.config.ts, vitest.config.ts, README.md
|
||
src/
|
||
index.ts
|
||
types/types.ts, types.md
|
||
errors/errors.{ts,md,test.ts}
|
||
schemas/schemas.{ts,md,test.ts}
|
||
tier/tier.{ts,md,test.ts}
|
||
discover/discover.{ts,md,test.ts}
|
||
graph/graph.{ts,md,test.ts}
|
||
rollups/rollups.{ts,md,test.ts}
|
||
telemetry/telemetry.{ts,md,test.ts}
|
||
tests/setup/polyfills.ts
|
||
```
|
||
|
||
---
|
||
|
||
## Impact
|
||
|
||
### Affected dependents
|
||
|
||
- No `@suaveplan/*` consumer currently imports `@suaveplan/overview` on
|
||
genesis. The library is consumable by `scripts/folder-reorg/generate-manifest.ts`
|
||
in a future cleanup change (out of scope here).
|
||
- Downstream tools (CLI dashboards, dependency-graph visualisers, ratings
|
||
dashboards) can adopt the typed API instead of re-implementing manifest
|
||
discovery.
|
||
|
||
**Breaking changes**: none (new package on genesis; upstream was docs-only
|
||
with no runtime API).
|