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)

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

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).

6.8 KiB Raw Blame History Unescape Escape