@substrat-run/cli 0.45.0 → 0.46.0

package/dist/bump.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The semver bump a vertical's change calls for, computed from its artifacts of record (#2364).
+ *
+ * Choosing a bump is a judgement an agent makes with confidence and gets wrong, and a breaking
+ * change marked `patch` looks exactly like a green release. A vertical already checks in every
+ * fact the judgement needs — `model.json` (`lint:model`), `openapi.json` (`lint:api`) and
+ * `PERMISSIONS.md` (`lint:permissions`), each held to the source by a `--check` re-emit — so the
+ * bump is read off the diff of those three files instead of asked for.
+ *
+ * The rules, one level per change, the bump being the highest. An INPUT is what a caller sends
+ * (parameters, request bodies); an OUTPUT is what a caller reads (responses, stored rows in
+ * `model.json`, event payloads).
+ *
+ *   - **major**: something removed or narrowed. An operation, field, entity, state, transition,
+ *     response, media type, enum value, parent edge, derived handler or export; an input that
+ *     became required, tighter (`minLength` up, `maxLength` down, …), closed to unnamed
+ *     properties or `readOnly`; an output that may now be omitted, looser, or `writeOnly`; a
+ *     type, key, table, initial state or `operationId` changed; trash terms changed.
+ *   - **minor**: something added. An operation, field, entity, state, transition, enum value,
+ *     response or stamp; an input that became optional or looser; an output that became required
+ *     or tighter; a `default` added, changed or dropped (a caller who omits the value gets other
+ *     behaviour); `readOnly`/`writeOnly` dropped, or set in the direction that does not use the
+ *     field; `erasable` gained or lost (lost is flagged). Every permission change is at least
+ *     minor and FLAGGED for the human checkpoint (CLAUDE.md, "Two human checkpoints") — a
+ *     narrowing and a widening alike, since a key gaining a role is the risk surface it exists for.
+ *   - **patch**: only what describes: the schema keywords `description`, `title`, `examples`,
+ *     `example`, `$comment`, `deprecated` and any `x-*`; an operation's `summary`, `description`,
+ *     `tags`, `externalDocs` and `deprecated`; `info`; a permission key's description.
+ *
+ * **What it cannot read is major.** A keyword, section or key this module does not know is
+ * judged as a breaking change, never skipped. The CI check refuses a changeset that declares
+ * LESS than this, so an unknown shape that read as "no change" would let a real break ship as a
+ * patch. A false major costs a reviewed override line in the changeset; a false patch costs a
+ * broken consumer. Teach this file the new shape instead.
+ *
+ * Two known limits, both stated rather than fixed:
+ *
+ *   - **Alternatives reordered rank major.** `anyOf`/`oneOf`/`allOf` branches are compared by
+ *     position (the emitter writes them in declaration order), so a reorder with no other change
+ *     reads as every branch changing. The safe direction: a reviewed override covers it.
+ *   - **A component renamed with identical content ranks none.** `$ref`s are resolved before
+ *     comparing, so `#/components/schemas/A` → `B` is invisible, although a client generated from
+ *     `openapi.json` names its types after components. Nothing a caller sends or reads changed,
+ *     and this repo's browser client is generated from `spec/model.ts`, not from component names.
+ *
+ * Pure: two texts in, a classification out. The filesystem and git half is `changeset.ts`. It
+ * reads the artifacts, never the TypeScript, which is what keeps it valid across a change of
+ * authoring notation (`tools/model-diff.mts`). The same classifier is what `substrat changeset`
+ * writes, what `--check` holds a hand-written changeset to, and what a status line can show.
+ */
+export type Level = 'patch' | 'minor' | 'major';
+export type Bump = 'none' | Level;
+export type Artifact = 'model' | 'openapi' | 'permissions';
+export interface Change {
+    readonly level: Level;
+    readonly artifact: Artifact;
+    /** Where in the artifact, as a reader would name it (`POST /api/lists`, `entities.item.fields.text`). */
+    readonly path: string;
+    readonly detail: string;
+    /** A permission change the human checkpoint must read, whatever the bump. */
+    readonly flagged?: boolean;
+}
+export interface Classification {
+    readonly bump: Bump;
+    readonly changes: readonly Change[];
+}
+export declare const rank: (b: Bump) => number;
+export declare const maxBump: (a: Bump, b: Bump) => Bump;
+export declare const isBump: (s: string) => s is Bump;
+/**
+ * Every local `$ref` (`#/…`) replaced by its target, recursively, against `root`. Compared
+ * unresolved, a break inside a shared component reads as an unchanged `{"$ref": …}` on both
+ * sides. A reference that loops back is left as the reference.
+ */
+export declare function resolveRefs(node: unknown, root?: unknown, seen?: readonly string[]): unknown;
+/**
+ * Which way a schema's values travel. An `input` is what a caller SENDS: requiring more of it
+ * breaks the caller, accepting more does not. An `output` is what a caller READS (a response, a
+ * stored row, an event payload): promising less of it breaks the reader, promising more does not.
+ */
+export type Direction = 'input' | 'output';
+export declare function classifyModel(baseText: string | null, headText: string | null): Classification;
+export declare function classifyOpenApi(baseText: string | null, headText: string | null): Classification;
+/**
+ * The parts of `PERMISSIONS.md` that carry a fact: one map per section, from a row's first
+ * cell (a key, a role, an entity type, a scheduled operation) to the row.
+ */
+export interface PermissionSnapshot {
+    /** Permission key → its description and declaring module. */
+    readonly registry: Record<string, string[]>;
+    /** Role → the keys it holds. */
+    readonly roles: Record<string, string[]>;
+    /** Entity type → keys granted per entity, then its remaining cells as written. */
+    readonly grantShapes: Record<string, {
+        keys: string[];
+        terms: string[];
+    }>;
+    /** Scheduled operation → the keys its system principal holds, then the remaining cells. */
+    readonly schedules: Record<string, {
+        keys: string[];
+        terms: string[];
+    }>;
+    /** Sections this parser does not read, by heading, with their text: judged whole. */
+    readonly unread: Record<string, string>;
+}
+/**
+ * Parse a `PERMISSIONS.md` that `tools/permission-diff.mts` emitted. Sections are found by
+ * their heading's words, not their number: the numbering shifts with which sections a vertical
+ * has (§4 is grant shapes in one file and "not covered" in another).
+ */
+export declare function parsePermissions(text: string): PermissionSnapshot;
+export declare function classifyPermissions(baseText: string | null, headText: string | null): Classification;
+/** One vertical's three artifacts as text, `null` where the file does not exist. */
+export interface Artifacts {
+    readonly model: string | null;
+    readonly openapi: string | null;
+    readonly permissions: string | null;
+}
+export declare function classify(base: Artifacts, head: Artifacts): Classification;
+//# sourceMappingURL=bump.d.ts.map

package/dist/bump.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bump.d.ts","sourceRoot":"","sources":["../src/bump.ts"],"names":[],"mappings":"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"}