@suaveplan/overview - Machine-readable Suaveplan project manifest: typed PackageRecord / SuavePlanManifest / WorkspaceGraph, Zod schemas, tier inference, filesystem discovery (server sub-path), graph utilities (topo, cycle detection, transitive closure, leaves, roots), plugin/category/tier roll-ups, six OVERVIEW.* error codes, three OTel counters + one histogram.

Machine-readable project manifest + graph utilities for the Suaveplan project.

@suaveplan/overview turns a populated packages/<category>/<plugin>/<pkg>/package.json tree into a typed, Zod-validated SuavePlanManifest and gives you graph utilities — forward / reverse adjacency, topological order, cycle detection, transitive closure, leaves, roots, plugin / category / tier roll-ups — for everything downstream.

It is the library form of the data model produced by scripts/folder-reorg/generate-manifest.ts (whose own header comment names this package as the eventual replacement).

The pure-data surface lives at the root entry. Filesystem-walking code (which needs node:fs / node:path) lives behind the ./discover sub-path so the root entry stays universal.

Documentation tree

discover — Implements the filesystem walker that produces a validated SuavePlanManifest from a populated `packages//<pl…
- discover — Implements the filesystem walker that produces a validated SuavePlanManifest from a populated `packages//<pl…
errors — Defines the stable error-code registry and the concrete OverviewError subclass of SuaveplanError. Every public entr…
- errors — Defines the stable error-code registry and the concrete OverviewError subclass of SuaveplanError. Every public entr…
graph — Implements the graph utilities that operate on a WorkspaceGraph built from a list of PackageRecords. Covers the ana…
- graph — Implements the graph utilities that operate on a WorkspaceGraph built from a list of PackageRecords. Covers the ana…
rollups — Provides the three aggregate views over a PackageRecord[] that the manifest needs: plugin roll-ups (one row per `(cat…
- rollups — Provides the three aggregate views over a PackageRecord[] that the manifest needs: plugin roll-ups (one row per `(cat…
schemas — Provides Zod schemas (and one helper, parseTier) for every public shape that @suaveplan/overview produces or accept…
- schemas — Provides Zod schemas (and one helper, parseTier) for every public shape that @suaveplan/overview produces or accept…
telemetry — Owns the OpenTelemetry meter for @suaveplan/overview and exposes the three counters and one histogram that the spec r…
- telemetry — Owns the OpenTelemetry meter for @suaveplan/overview and exposes the three counters and one histogram that the spec r…
tier — Computes the deterministic Tier label for a package given its shortname and the parsed package.json shape. The infe…
- tier — Computes the deterministic Tier label for a package given its shortname and the parsed package.json shape. The infe…
types — Declares the type-level vocabulary of @suaveplan/overview: the closed Tier union, the PackageRecord row, the `Plu…
- types — Declares the type-level vocabulary of @suaveplan/overview: the closed Tier union, the PackageRecord row, the `Plu…

Install

bun add @suaveplan/overview

Surfaces

Sub-path	Use
`@suaveplan/overview`	Types, schemas, errors, graph utilities, roll-ups, telemetry — all universal
`@suaveplan/overview/discover`	`discoverPackages` + `discoverPackagesIter` — server-tier (touches `node:fs`)
`@suaveplan/overview/errors`	`OVERVIEW_CODES`, `OverviewError`
`@suaveplan/overview/schemas`	Zod schemas + `parseTier`
`@suaveplan/overview/tier`	`inferTier`, `SERVER_DEP_HINTS`
`@suaveplan/overview/graph`	Graph utilities
`@suaveplan/overview/rollups`	`byPlugin`, `byCategory`, `byTier`
`@suaveplan/overview/telemetry`	OTel instruments

Example

import { discoverPackages } from "@suaveplan/overview/discover";
import {
  buildGraph,
  topologicalOrder,
  byTier,
} from "@suaveplan/overview";

const manifest = discoverPackages({ root: process.cwd() });
const graph = buildGraph(manifest.packages);
const order = topologicalOrder(graph);
const buckets = byTier(manifest.packages);

console.log(`Packages: ${manifest.packages.length}`);
console.log(`Universal: ${buckets.universal.length}`);
console.log(`Build order (deps first): ${order.slice(0, 5).join(", ")} …`);

Error codes

Code	Thrown by
`OVERVIEW.PARSE_FAILED`	`discoverPackages` — `package.json` failed `JSON.parse`
`OVERVIEW.INVALID_RECORD`	`discoverPackages` — row failed `PackageRecordSchema`
`OVERVIEW.CYCLE_DETECTED`	`topologicalOrder`
`OVERVIEW.UNKNOWN_PACKAGE`	`transitiveDependencies` / `transitiveDependents`
`OVERVIEW.DISCOVERY_ABORTED`	`discoverPackagesIter`
`OVERVIEW.INVALID_TIER`	`parseTier`

Telemetry

Three counters and one histogram, scoped to meter @suaveplan/overview@0.1.0:

overview.packages_discovered_total
overview.records_rejected_total{reason}
overview.graph_builds_total
overview.discover_duration_ms

Plug @opentelemetry/sdk-metrics in your runtime to harvest them.

Tier

Universal at the root entry; server at ./discover.