skills/docs/devtools/tooling/overview/README.md

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