first commit
This commit is contained in:
106
docs/devtools/tooling/overview/README.md
Normal file
106
docs/devtools/tooling/overview/README.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# @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`.
|
||||
|
||||
Reference in New Issue
Block a user