@mnmal-ai/cortext 0.0.0 → 1.0.0-alpha.0

package/dist/release-surface.d.ts

@@ -0,0 +1,206 @@
+/**
+ * The plugin-facing surface, snapshotted so a release can be SIZED rather than
+ * judged.
+ *
+ * ## Why this exists
+ *
+ * A release-class guard that defines the surface as a list of paths passes a
+ * major as a patch with a green check the moment a type moves out of those
+ * paths: `git diff` on the stale path is empty, so it approves.
+ *
+ * cortext's propagation is heavy — a
+ * `packages/cortext/src` change reaches consumers as an npm tarball loaded by
+ * the substrate runtime from `SUBSTRATE_PLUGIN_DIR`, needing a publish **and** a
+ * runtime deploy. npm publishes are immutable, so a mis-sized release cannot be
+ * withdrawn, only superseded.
+ *
+ * ## Why it resolves through the code, not through paths
+ *
+ * A path list rots silently. This calls
+ * `buildClaudeNamespace()` and walks what it returns, so the surface is
+ * DERIVED from the thing it describes. A type or field cannot move out from
+ * under it, because there is no "under it" — moving a declaration between files
+ * changes nothing here, and that is the point.
+ *
+ * The committed `release-surface.json` is kept honest by
+ * `test/release-surface.test.ts`, exactly as `config.schema.json` is kept
+ * honest by `schema-parity.test.ts`. So the release script never has to execute
+ * TypeScript or parse a declaration: it diffs two committed JSON snapshots.
+ *
+ * ## What counts as breaking, and why `indexed` is in here
+ *
+ * Removing a type or field, making an optional field REQUIRED, narrowing an
+ * enum, or moving the substrate contract range are all breaks for someone holding
+ * data or code against this schema.
+ *
+ * `indexed` is included and it is not cosmetic: un-indexing a field turns a
+ * working `where` filter into an `unindexed_field` rejection. That is a
+ * runtime break for a caller who changed nothing, and it would otherwise be
+ * invisible to a version-bump decision.
+ */
+/** One field, reduced to the properties a consumer can break against. */
+export interface SurfaceField {
+    kind: string;
+    type?: string;
+    /** crossRef target type. */
+    target?: string;
+    nullable: boolean;
+    hasDefault: boolean;
+    readonly: boolean;
+    serverSet: boolean;
+    indexed: boolean;
+    enum?: string[];
+    /** Not (nullable | default | readonly | serverSet) — the write contract. */
+    required: boolean;
+}
+/**
+ * The published TypeScript API of one package.
+ *
+ * Two signals with deliberately different precision, because one alone is not
+ * enough and the gap between them is where a real break just hid:
+ *
+ * - `exports` is PRECISE. A name that disappears is a hard break; a name that
+ *   appears is additive. No ambiguity either way.
+ * - `dtsDigest` NEVER MISSES. It hashes every emitted declaration, so any
+ *   signature change anywhere moves it — but it cannot say WHICH export moved.
+ *
+ * The digest exists because of a live miss: `auditObjects` kept its name and
+ * changed its return type from `Finding[]` to `{ findings, checked }`. Names
+ * alone saw nothing. A schema-only surface saw nothing. It is exported from
+ * the kernel plugin's entry point, so it is a published break, and it was
+ * about to ship under a patch.
+ *
+ * A digest change therefore raises the floor to MINOR and is reported for a
+ * human to read — never auto-major, because it cannot tell a widened return
+ * type from a narrowed one.
+ */
+export interface PackageApi {
+    /**
+     * Exported names qualified by the subpath that publishes them, as
+     * `<subpath>:<name>` — e.g. `.:buildReleaseSurface`, `./bootstrap:bootstrap`.
+     *
+     * Qualified rather than a bare union because the union cannot see a MOVE.
+     * A name relocated from `.` to `./bootstrap` breaks every existing importer
+     * while leaving a union identical; qualified, it reads as one removal and one
+     * addition, which is exactly what it is. The set diff below needs no change
+     * to get that right — the qualification does all the work.
+     */
+    exports: string[];
+    dtsDigest: string;
+}
+/**
+ * Format marker for the `api` section.
+ *
+ * Bumped when the SHAPE of `api` changes rather than its content. The exports
+ * list moved from bare names to subpath-qualified ones, which would otherwise
+ * read as every export being removed and re-added — a fake MAJOR generated by a
+ * tooling change that touched no published API.
+ *
+ * `classifySurfaceChange` treats a format mismatch as NOT COMPARED, the same
+ * way it already treats an absent `api`. That is the honest reading and it is
+ * an existing precedent in this file rather than a special case invented for
+ * this bump.
+ */
+export declare const SURFACE_FORMAT = 2;
+export interface ReleaseSurface {
+    contractVersion: string;
+    types: Record<string, Record<string, SurfaceField>>;
+    api?: Record<string, PackageApi>;
+    /** Absent means format 1 — bare, root-entry-only export names. */
+    surfaceFormat?: number;
+}
+/** One published entry point: the subpath a consumer imports, and its `.d.ts`. */
+export interface SurfaceEntry {
+    subpath: string;
+    dts: string;
+}
+/**
+ * Resolve the `.d.ts` each published subpath points at, from a package's
+ * `exports` map.
+ *
+ * ## Why this exists
+ *
+ * The previous version assumed one entry per package and read `dist/index.d.ts`.
+ * Every publishable package here is multi-entry, so `./bootstrap`'s three
+ * exports — `bootstrap`, `CortextBootstrapConfig`,
+ * `CortextBootstrapConfigSchema` — were never in the exports list at all.
+ * Measured against the real classifier before fixing:
+ *
+ *     additive change in ./bootstrap    guard MINOR   correct MINOR   right
+ *     export REMOVED from ./bootstrap   guard MINOR   correct MAJOR   UNDER-SIZED
+ *     export removed from "."           guard MAJOR   correct MAJOR   right
+ *
+ * The middle row is the defect. It survived because the `dtsDigest` half of the
+ * two-signal design DOES cover every emitted declaration, so the change was
+ * never invisible — it was merely floored at minor by a review item. A guard
+ * that is wrong in one direction only is the hard kind to notice.
+ *
+ * ## Returns nothing rather than guessing
+ *
+ * A package with no `exports` map gets the conventional single entry. A subpath
+ * publishing no `types` condition contributes nothing — it exposes no
+ * TypeScript surface to compare. Neither is an error.
+ *
+ * Missing FILES are an error, and that is deliberate: silently skipping a
+ * declared subpath whose layout does not match the assumption would recreate
+ * exactly the blind spot this function removes — an unread surface reporting
+ * clean. The caller supplies `exists` so this stays pure.
+ */
+export declare function resolveSurfaceEntries(exportsMap: unknown, exists: (relPath: string) => boolean): Array<{
+    subpath: string;
+    dtsPath: string;
+}>;
+/**
+ * Build the canonical surface.
+ *
+ * Keys are sorted so the committed JSON is stable — an unstable snapshot would
+ * produce diff noise on every regeneration and train its reader to skim, which
+ * is the failure this whole file is guarding against one level down.
+ */
+export declare function buildReleaseSurface(namespace?: string): ReleaseSurface;
+/**
+ * Extract the public export NAMES from an entry `.d.ts`.
+ *
+ * Handles the two forms tsdown emits: re-export lists (`export { a, type B }
+ * from './x.js'`) and direct declarations (`export declare function f`). The
+ * `type` modifier and `as` aliases are normalised to the exported name, since
+ * that is what a consumer writes.
+ */
+export declare function parseDtsExports(dts: string): string[];
+/**
+ * Build the published-API section.
+ *
+ * File reading is the CALLER's job — this stays pure so the rules are testable
+ * without a build directory, matching every other classifier in this file.
+ *
+ * @param entries One per published package: EVERY published entry point (see
+ *   `resolveSurfaceEntries`), plus the text of every emitted declaration file
+ *   for the digest.
+ * @param digest A hashing function; injected so this module needs no node
+ *   built-ins and can run anywhere the rest of it can.
+ */
+export declare function buildApiSurface(entries: ReadonlyArray<{
+    name: string;
+    entries: ReadonlyArray<SurfaceEntry>;
+    allDts: ReadonlyArray<string>;
+}>, digest: (input: string) => string): Record<string, PackageApi>;
+export type ReleaseClass = 'major' | 'minor' | 'patch';
+export interface SurfaceChange {
+    class: ReleaseClass;
+    breaking: string[];
+    additive: string[];
+    /** Changes a human must read: real, but not classifiable from a digest. */
+    review: string[];
+}
+/**
+ * Classify the difference between two surfaces.
+ *
+ * Reports EVERY reason rather than the first, because a release usually carries
+ * several and a guard that stops at one teaches its reader to fix-and-rerun
+ * instead of reading.
+ */
+export declare function classifySurfaceChange(before: ReleaseSurface, after: ReleaseSurface): SurfaceChange;
+/** Is `proposed` at least as large as `required`? */
+export declare function classSatisfies(proposed: ReleaseClass, required: ReleaseClass): boolean;
+/** The class implied by a version bump. Returns null when it is not a bump. */
+export declare function bumpClass(from: string, to: string): ReleaseClass | null;