first commit

docs/devtools/tooling/overview/src/errors/errors.md

@@ -0,0 +1,86 @@
+# `errors/errors.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Defines the stable error-code registry and the concrete `OverviewError`
+subclass of `SuaveplanError`. Every public entry point in `@suaveplan/overview`
+that throws does so through this class, so callers can rely on a single
+`instanceof OverviewError` check and a literal-typed `code` field for
+discrimination.
+
+The registry has six entries — one per failure mode that the package can
+detect — and the §2c "never delete spec elements to satisfy a gate" rule means
+each entry is exercised by a real call site somewhere in `src/`, asserted by
+the static test `every code has a real call site in src/`.
+
+## Features
+
+- Six stable codes registered through `defineCodes("OVERVIEW", [...])`
+- Frozen, fully-inferred code record — `OVERVIEW_CODES.PARSE_FAILED` is the
+  literal `"OVERVIEW.PARSE_FAILED"`
+- `OverviewCode` closed union for exhaustive switch statements
+- `OverviewError` extends `SuaveplanError<OverviewCode>` so `instanceof`
+  narrows `error.code`
+- Preserves cause chain, context, and trace-id propagation via
+  `SuaveplanErrorOptions`
+
+## Usage: Basic
+
+```ts
+import { OverviewError, OVERVIEW_CODES } from "@suaveplan/overview";
+
+throw new OverviewError(
+  OVERVIEW_CODES.UNKNOWN_PACKAGE,
+  "overview.unknown_package",
+  { context: { pkg: "@suaveplan/missing" } },
+);
+```
+
+## Usage: Advanced
+
+```ts
+import { OverviewError } from "@suaveplan/overview";
+
+try {
+  // ...
+} catch (err) {
+  if (err instanceof OverviewError) {
+    switch (err.code) {
+      case "OVERVIEW.CYCLE_DETECTED":
+        // type-narrowed; safe to read err.context?.cycle
+        break;
+      case "OVERVIEW.PARSE_FAILED":
+        break;
+      default:
+        break;
+    }
+  }
+  throw err;
+}
+```
+
+The exhaustive `switch` benefits from `OverviewCode` being a closed union —
+adding a new code without handling it in a downstream `switch` is a TypeScript
+error.
+
+## API Reference
+
+- `OVERVIEW_CODES` — `Readonly<{PARSE_FAILED, INVALID_RECORD, CYCLE_DETECTED,
+  UNKNOWN_PACKAGE, DISCOVERY_ABORTED, INVALID_TIER}>` with literal `OVERVIEW.<X>`
+  values
+- `type OverviewCode` — closed union of every value in `OVERVIEW_CODES`
+- `class OverviewError extends SuaveplanError<OverviewCode>` — constructor
+  `(code, messageKey, options?)`
+
+## Implementation Notes
+
+The `defineCodes` helper from `@suaveplan/error` freezes its return value so the
+registry cannot be mutated at runtime. `OverviewError` deliberately re-exposes
+the `protected` constructor of `SuaveplanError` as `public` (the language
+requires each subclass to do this explicitly) so callers can `new` an instance
+directly without a factory. The class is final by convention — sub-classing it
+would dilute `instanceof` narrowing.