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

<!-- begin:auto-docs -->
## Documentation tree

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

## Install

```sh
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

```ts
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`.