Initial Commit
This commit is contained in:
178
openspec/archive/2026-05-25-enterprise-overview/proposal.md
Normal file
178
openspec/archive/2026-05-25-enterprise-overview/proposal.md
Normal file
@@ -0,0 +1,178 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user