qubu 0.4.3 → 0.5.0

package/dist/index-C_BQNvbT.d.mts

@@ -1,202 +0,0 @@
-import { T as SnapshotJsonValue, m as SnapshotDialect, n as SchemaSnapshot } from "./types-C0VkiwpR.mjs";
-import { S as CompleteSnapshotObjectKind, t as CompleteSchemaSnapshot } from "./complete-types-CY0KbzNw.mjs";
-//#region src/diff/types.d.ts
-/** Object families understood by the snapshot diff engine. */
-type SnapshotDiffObjectKind = CompleteSnapshotObjectKind;
-/** A path into a canonical snapshot or one of its object records. */
-type SnapshotDiffPath = readonly (string | number)[];
-/** A stable reference to an object in a rename hint. */
-interface SnapshotRenameTarget {
-  /** Stable logical ID, when the source or target snapshot has one. */
-  readonly id?: string;
-  /** Physical name evidence used when logical IDs changed. */
-  readonly physicalName?: string;
-  /** Optional exact object path for a repeated ID in a nested scope. */
-  readonly path?: SnapshotDiffPath;
-}
-/**
- * An explicit, serializable physical-rename mapping.
- *
- * `namespace` and `kind` are part of the key. A hint never crosses either boundary, and a hint is
- * only authoritative after both targets resolve to exactly one object.
- */
-interface SnapshotRenameHint {
-  readonly namespace?: string;
-  readonly kind: SnapshotDiffObjectKind;
-  readonly from: string | SnapshotRenameTarget;
-  readonly to: string | SnapshotRenameTarget;
-}
-/** Input accepted by the diff and hint helpers. */
-type SnapshotDiffInput = SchemaSnapshot | CompleteSchemaSnapshot | string | Readonly<Record<string, unknown>>;
-/** Evidence attached to an object, match, operation, or diagnostic. */
-interface SnapshotDiffEvidence {
-  readonly kind: "logical-id" | "physical-name" | "physical-reference" | "provenance" | "dialect" | "canonical" | "explicit-hint" | "structural" | "ambiguity";
-  readonly path?: SnapshotDiffPath;
-  readonly value?: SnapshotJsonValue;
-  readonly message?: string;
-  readonly confidence?: number;
-}
-/** An immutable object view retained by a diff result. */
-interface SnapshotDiffObject {
-  readonly kind: SnapshotDiffObjectKind;
-  /** The deferred or opaque kind observed by an adapter, if any. */
-  readonly observedKind?: string;
-  readonly namespace?: string;
-  readonly path: SnapshotDiffPath;
-  readonly parent?: SnapshotDiffObjectReference;
-  readonly id: string;
-  readonly physicalName?: string;
-  readonly physicalReference?: SnapshotJsonValue;
-  readonly dialect: SnapshotDialect;
-  readonly provenance?: SnapshotJsonValue;
-  /** The original validated object record, retained as immutable data. */
-  readonly value: Readonly<Record<string, SnapshotJsonValue>>;
-  readonly evidence: readonly SnapshotDiffEvidence[];
-}
-/** A logical object reference used in parent and related-object evidence. */
-interface SnapshotDiffObjectReference {
-  readonly kind: SnapshotDiffObjectKind;
-  readonly id: string;
-  readonly namespace?: string;
-}
-/** One changed property in a matched object pair. */
-interface SnapshotDiffPropertyChange {
-  readonly path: SnapshotDiffPath;
-  readonly before?: SnapshotJsonValue;
-  readonly after?: SnapshotJsonValue;
-}
-/** Categories of emitted diff operations. */
-type SnapshotDiffOperationType = "add" | "remove" | "property-change" | "physical-rename";
-/** A diff operation. All variants retain both object identity and evidence. */
-interface SnapshotDiffOperation {
-  readonly type: SnapshotDiffOperationType;
-  /** Alias for callers that use operation terminology. */
-  readonly operation: SnapshotDiffOperationType;
-  readonly classification: SnapshotDiffOperationType;
-  readonly changeKind: SnapshotDiffOperationType;
-  readonly kind: SnapshotDiffObjectKind;
-  readonly objectKind: SnapshotDiffObjectKind;
-  readonly namespace?: string;
-  readonly path: SnapshotDiffPath;
-  readonly dialect: SnapshotDialect;
-  readonly physicalReference?: SnapshotJsonValue;
-  readonly provenance?: SnapshotJsonValue;
-  readonly before?: SnapshotDiffObject;
-  readonly after?: SnapshotDiffObject;
-  readonly object?: SnapshotDiffObject;
-  readonly logicalId?: string;
-  readonly physicalName?: string;
-  readonly changedProperties?: readonly SnapshotDiffPropertyChange[];
-  readonly evidence: readonly SnapshotDiffEvidence[];
-  readonly source: "stable-id" | "explicit-hint";
-  readonly destructive: boolean;
-}
-/** A conservative structural match suggestion. It is never an operation. */
-interface SnapshotRenameSuggestion {
-  readonly type: "rename-suggestion";
-  readonly operation: "rename-suggestion";
-  readonly kind: SnapshotDiffObjectKind;
-  readonly objectKind: SnapshotDiffObjectKind;
-  readonly namespace?: string;
-  readonly before: SnapshotDiffObject;
-  readonly after: SnapshotDiffObject;
-  readonly confidence: number;
-  readonly evidence: readonly SnapshotDiffEvidence[];
-}
-/** Diagnostic categories emitted by snapshot comparison and hint validation. */
-type SnapshotDiffDiagnosticCode = "ambiguous" | "destructive" | "unsupported" | "unknown" | "lossy" | "invalid-snapshot" | "invalid-rename-hint" | "rename-conflict" | "dialect-mismatch";
-/** A path-addressed diff diagnostic with object and dialect context. */
-interface SnapshotDiffDiagnostic {
-  readonly code: SnapshotDiffDiagnosticCode;
-  readonly category: SnapshotDiffDiagnosticCode;
-  readonly severity: "error" | "warning";
-  readonly message: string;
-  readonly path: SnapshotDiffPath;
-  readonly relatedPaths?: readonly SnapshotDiffPath[];
-  readonly kind?: SnapshotDiffObjectKind;
-  readonly objectKind?: SnapshotDiffObjectKind;
-  readonly namespace?: string;
-  readonly logicalId?: string;
-  readonly physicalName?: string;
-  readonly dialect?: SnapshotDialect;
-  readonly evidence?: readonly SnapshotDiffEvidence[];
-}
-/** Options controlling explicit hints and conservative suggestions. */
-interface SnapshotDiffOptions {
-  /** Authoritative mappings. `renames` is accepted as an ergonomic alias. */
-  readonly renameHints?: readonly SnapshotRenameHint[];
-  readonly renames?: readonly SnapshotRenameHint[];
-  /** Disable structural suggestions while retaining stable and explicit matches. */
-  readonly suggestions?: boolean;
-  /** Minimum score for a unique heuristic suggestion. Defaults to 0.75. */
-  readonly suggestionThreshold?: number;
-}
-/** The complete immutable output of `diffSnapshots`. */
-interface SnapshotDiff {
-  readonly equal: boolean;
-  readonly beforeVersion?: 1 | 2;
-  readonly afterVersion?: 1 | 2;
-  readonly beforeDialect?: SnapshotDialect;
-  readonly afterDialect?: SnapshotDialect;
-  readonly beforeDigest?: string;
-  readonly afterDigest?: string;
-  readonly operations: readonly SnapshotDiffOperation[];
-  readonly changes: readonly SnapshotDiffOperation[];
-  readonly additions: readonly SnapshotDiffOperation[];
-  readonly removals: readonly SnapshotDiffOperation[];
-  readonly propertyChanges: readonly SnapshotDiffOperation[];
-  readonly renames: readonly SnapshotDiffOperation[];
-  readonly added: readonly SnapshotDiffOperation[];
-  readonly removed: readonly SnapshotDiffOperation[];
-  readonly changed: readonly SnapshotDiffOperation[];
-  readonly physicalRenames: readonly SnapshotDiffOperation[];
-  readonly suggestions: readonly SnapshotRenameSuggestion[];
-  readonly diagnostics: readonly SnapshotDiffDiagnostic[];
-  readonly issues: readonly SnapshotDiffDiagnostic[];
-  readonly renameHints: readonly SnapshotRenameHint[];
-  readonly hints: readonly SnapshotRenameHint[];
-}
-/** Result returned by serializable rename-hint validation/decoding helpers. */
-type SnapshotRenameHintResult = {
-  readonly ok: true;
-  readonly value: readonly SnapshotRenameHint[];
-  readonly diagnostics: readonly SnapshotDiffDiagnostic[];
-} | {
-  readonly ok: false;
-  readonly value: readonly SnapshotRenameHint[];
-  readonly diagnostics: readonly SnapshotDiffDiagnostic[];
-};
-/** Decode diagnostics without throwing, suitable for editor and CLI callers. */
-type SnapshotDiffDecodeResult = {
-  readonly ok: true;
-  readonly version: 1 | 2;
-  readonly value: SchemaSnapshot | CompleteSchemaSnapshot;
-} | {
-  readonly ok: false;
-  readonly diagnostics: readonly SnapshotDiffDiagnostic[];
-};
-//#endregion
-//#region src/diff/diff.d.ts
-/**
- * Compare Snapshot v1 or v2 values and return immutable, reviewable data.
- *
- * The function never opens a connection, renders SQL, or turns a heuristic match into a rename.
- * Invalid input and malformed hints are represented by diagnostics in the returned value.
- */
-declare function diffSnapshots(beforeInput: SnapshotDiffInput, afterInput: SnapshotDiffInput, options?: SnapshotDiffOptions): SnapshotDiff;
-/** Alias that reads naturally in comparison-oriented callers. */
-declare const compareSnapshots: typeof diffSnapshots;
-/** Decode and normalize a Snapshot v1 or v2 value without throwing. */
-declare function decodeSnapshotForDiff(input: SnapshotDiffInput): SnapshotDiffDecodeResult;
-/** Validate rename hints and return a frozen, serializable list. */
-declare function validateSnapshotRenameHints(hints: readonly SnapshotRenameHint[] | unknown): SnapshotRenameHintResult;
-/** Serialize validated rename hints as deterministic JSON. */
-declare function encodeSnapshotRenameHints(hints: readonly SnapshotRenameHint[]): string;
-/** Decode deterministic rename-hint JSON without throwing. */
-declare function decodeSnapshotRenameHints(input: string | unknown): SnapshotRenameHintResult;
-/** Short aliases for callers that keep rename helpers beside `diffSnapshots`. */
-declare const validateRenameHints: typeof validateSnapshotRenameHints;
-declare const encodeRenameHints: typeof encodeSnapshotRenameHints;
-declare const decodeRenameHints: typeof decodeSnapshotRenameHints;
-//#endregion
-export { SnapshotDiffPropertyChange as C, SnapshotRenameTarget as D, SnapshotRenameSuggestion as E, SnapshotDiffPath as S, SnapshotRenameHintResult as T, SnapshotDiffObjectKind as _, diffSnapshots as a, SnapshotDiffOperationType as b, validateRenameHints as c, SnapshotDiffDecodeResult as d, SnapshotDiffDiagnostic as f, SnapshotDiffObject as g, SnapshotDiffInput as h, decodeSnapshotRenameHints as i, validateSnapshotRenameHints as l, SnapshotDiffEvidence as m, decodeRenameHints as n, encodeRenameHints as o, SnapshotDiffDiagnosticCode as p, decodeSnapshotForDiff as r, encodeSnapshotRenameHints as s, compareSnapshots as t, SnapshotDiff as u, SnapshotDiffObjectReference as v, SnapshotRenameHint as w, SnapshotDiffOptions as x, SnapshotDiffOperation as y };

package/dist/migration.d.mts

@@ -1,214 +0,0 @@
-import { T as SnapshotJsonValue, m as SnapshotDialect } from "./types-C0VkiwpR.mjs";
-import { S as SnapshotDiffPath, _ as SnapshotDiffObjectKind, b as SnapshotDiffOperationType, f as SnapshotDiffDiagnostic, g as SnapshotDiffObject, m as SnapshotDiffEvidence, u as SnapshotDiff } from "./index-C_BQNvbT.mjs";
-//#region src/migration/types.d.ts
-/** The versioned envelope tag for dialect-neutral migration plans. */
-declare const migrationPlanFormat: "qubu-migration-plan";
-/** The first strict migration-plan format version. */
-declare const migrationPlanVersion: 1;
-/** Safety classifications carried by every planned operation. */
-type MigrationSafety = "safe" | "review-required" | "destructive" | "unsupported" | "unknown";
-/** Lock strength required by a planned operation. */
-type MigrationLockRequirement = "none" | "shared" | "exclusive" | "unknown";
-/** Transaction behavior required by a planned operation. */
-type MigrationTransactionRequirement = "required" | "optional" | "forbidden" | "unknown";
-/** Operations that can appear in a migration plan. */
-type MigrationOperationType = "add" | "remove" | "property-change" | "physical-rename" | "custom-sql";
-/** A condition a later executor must check before applying an operation. */
-type MigrationPreconditionType = "snapshot-digest" | "object-present" | "object-absent" | "property-equals";
-/** An immutable, serializable migration precondition. */
-interface MigrationPrecondition {
-  readonly type: MigrationPreconditionType;
-  readonly path: SnapshotDiffPath;
-  readonly kind: SnapshotDiffObjectKind | "custom-sql";
-  readonly namespace?: string;
-  readonly logicalId?: string;
-  readonly physicalName?: string;
-  readonly digest?: string;
-  readonly property?: SnapshotDiffPath;
-  readonly value?: SnapshotJsonValue;
-}
-/** The explicit custom SQL escape hatch for one planned operation. */
-interface MigrationCustomSql {
-  readonly sql: string;
-  readonly dialect: SnapshotDialect;
-  readonly safety: MigrationSafety;
-  readonly position: number;
-  readonly reason: string;
-  readonly reversible: boolean;
-}
-/** Input accepted when attaching explicit custom SQL to a plan. */
-interface MigrationCustomSqlInput {
-  readonly sql: string;
-  readonly dialect: SnapshotDialect;
-  readonly safety: MigrationSafety;
-  readonly reason: string;
-  readonly reversible?: boolean;
-  /** Target an operation by deterministic ID when it already exists. */
-  readonly operationId?: string;
-  /** Or target a diff object by kind, namespace, and path. */
-  readonly kind?: SnapshotDiffObjectKind;
-  readonly namespace?: string;
-  readonly path?: SnapshotDiffPath;
-  /** Explicit dependency position. It does not render or execute SQL. */
-  readonly position?: number;
-  readonly dependsOn?: readonly string[];
-}
-/** A user's explicit decision for an unsafe or incomplete fact. */
-interface MigrationDecision {
-  readonly action: "allow" | "skip";
-  readonly reason: string;
-  readonly operationId?: string;
-  readonly kind?: SnapshotDiffObjectKind;
-  readonly namespace?: string;
-  readonly path?: SnapshotDiffPath;
-  readonly code?: MigrationDiagnosticCode;
-}
-/** Why a plan was blocked or needs review. */
-type MigrationDiagnosticCode = "decision-required" | "dependency-cycle" | "invalid-plan" | "unknown" | "lossy" | "unsupported" | "destructive" | "ambiguous" | "custom-sql" | "dialect-mismatch" | "non-canonical";
-/** A structured plan diagnostic that keeps source diff context. */
-interface MigrationDiagnostic {
-  readonly code: MigrationDiagnosticCode;
-  readonly severity: "error" | "warning";
-  readonly message: string;
-  readonly path: SnapshotDiffPath;
-  readonly operationId?: string;
-  readonly kind?: SnapshotDiffObjectKind | "custom-sql";
-  readonly namespace?: string;
-  readonly logicalId?: string;
-  readonly physicalName?: string;
-  readonly dialect?: SnapshotDialect;
-  readonly evidence?: readonly SnapshotDiffEvidence[];
-  readonly source?: SnapshotDiffDiagnostic;
-}
-/** The source facts preserved on each non-custom migration operation. */
-interface MigrationOperationOrigin {
-  readonly type: SnapshotDiffOperationType;
-  readonly kind: SnapshotDiffObjectKind;
-  readonly namespace?: string;
-  readonly path: SnapshotDiffPath;
-  readonly logicalId?: string;
-  readonly physicalName?: string;
-  readonly physicalReference?: SnapshotJsonValue;
-  readonly provenance?: SnapshotJsonValue;
-  readonly before?: SnapshotDiffObject;
-  readonly after?: SnapshotDiffObject;
-  readonly evidence: readonly SnapshotDiffEvidence[];
-}
-/** One immutable operation in a migration plan. */
-interface MigrationOperation {
-  readonly id: string;
-  readonly type: MigrationOperationType;
-  readonly kind: SnapshotDiffObjectKind | "custom-sql";
-  readonly objectKind: SnapshotDiffObjectKind | "custom-sql";
-  readonly namespace?: string;
-  readonly path: SnapshotDiffPath;
-  readonly logicalId?: string;
-  readonly physicalName?: string;
-  readonly physicalReference?: SnapshotJsonValue;
-  readonly provenance?: SnapshotJsonValue;
-  readonly dialect: SnapshotDialect;
-  readonly safety: MigrationSafety;
-  readonly lock: MigrationLockRequirement;
-  readonly transaction: MigrationTransactionRequirement;
-  readonly reversible: boolean;
-  readonly reversibility: "reversible" | "irreversible";
-  readonly irreversibleReason?: string;
-  readonly preconditions: readonly MigrationPrecondition[];
-  readonly dependsOn: readonly string[];
-  readonly evidence: readonly SnapshotDiffEvidence[];
-  readonly origin?: MigrationOperationOrigin;
-  readonly customSql?: MigrationCustomSql;
-  readonly decision?: MigrationDecision;
-  readonly status: "approved" | "decision-required" | "skipped";
-  readonly position: number;
-}
-/** A dependency edge. `from` must appear before `to`. */
-interface MigrationDependency {
-  readonly from: string;
-  readonly to: string;
-  readonly reason: "parent-before-child" | "child-before-parent" | "reference-before-dependent" | "explicit-custom-sql";
-}
-/** Immutable migration plan data. It contains no executor or SQL renderer. */
-interface MigrationPlan {
-  readonly format: typeof migrationPlanFormat;
-  readonly version: typeof migrationPlanVersion;
-  readonly dialect: SnapshotDialect;
-  readonly beforeDigest?: string;
-  readonly afterDigest?: string;
-  readonly safety: MigrationSafety;
-  readonly ready: boolean;
-  readonly operations: readonly MigrationOperation[];
-  readonly dependencies: readonly MigrationDependency[];
-  readonly decisions: readonly MigrationDecision[];
-  readonly diagnostics: readonly MigrationDiagnostic[];
-}
-/** Options for converting a resolved diff into a migration plan. */
-interface MigrationPlanOptions {
-  readonly decisions?: readonly MigrationDecision[];
-  readonly customSql?: readonly MigrationCustomSqlInput[];
-  readonly allowUnknown?: boolean;
-  readonly allowLossy?: boolean;
-  readonly allowUnsupported?: boolean;
-  readonly allowDestructive?: boolean;
-  readonly allowReviewRequired?: boolean;
-}
-/** A plan result retains a blocked plan so callers can inspect and review it. */
-type MigrationPlanResult = {
-  readonly ok: true;
-  readonly plan: MigrationPlan;
-  readonly diagnostics: readonly MigrationDiagnostic[];
-} | {
-  readonly ok: false;
-  readonly plan: MigrationPlan;
-  readonly diagnostics: readonly MigrationDiagnostic[];
-};
-/** Result returned by strict plan decoding. */
-type MigrationPlanDecodeResult = {
-  readonly ok: true;
-  readonly value: MigrationPlan;
-} | {
-  readonly ok: false;
-  readonly diagnostics: readonly MigrationDiagnostic[];
-};
-/** Result returned by non-throwing plan validation. */
-type MigrationPlanValidationResult = MigrationPlanDecodeResult;
-/** A validation error raised by throwing plan APIs. */
-declare class MigrationPlanValidationError extends TypeError {
-  readonly name = "MigrationPlanValidationError";
-  readonly diagnostics: readonly MigrationDiagnostic[];
-  readonly issues: readonly MigrationDiagnostic[];
-  constructor(diagnostics: readonly MigrationDiagnostic[]);
-}
-//#endregion
-//#region src/migration/plan.d.ts
-/**
- * Convert a resolved SnapshotDiff into an immutable migration plan.
- *
- * This function only describes operations. It does not render SQL, open a connection, execute a
- * transaction, or infer SQL from opaque snapshot data. A plan that still needs a safety decision is
- * returned with `ok: false` so it can be reviewed without being mistaken for an executable plan.
- */
-declare function createMigrationPlan(diff: SnapshotDiff, options?: MigrationPlanOptions): MigrationPlanResult;
-/** Alias for callers that treat plan creation as the main migration action. */
-declare const planMigration: typeof createMigrationPlan;
-declare const createPlan: typeof createMigrationPlan;
-/** Build a plan or throw one structured validation error when it is blocked. */
-declare function assertMigrationPlanFromDiff(diff: SnapshotDiff, options?: MigrationPlanOptions): MigrationPlan;
-/** Return a fixed-order immutable plan after strict validation. */
-declare function canonicalizeMigrationPlan(input: MigrationPlan): MigrationPlan;
-/** Encode a validated plan as deterministic JSON. */
-declare function encodeMigrationPlan(input: MigrationPlan): string;
-/** Decode and strictly validate a migration-plan JSON value. */
-declare function decodeMigrationPlan(input: string | unknown): MigrationPlanDecodeResult;
-/** Validate a plan without throwing. */
-declare function validateMigrationPlan(input: unknown): MigrationPlanValidationResult;
-/** Validate a plan and throw one structured error on failure. */
-declare function assertMigrationPlan(input: unknown): MigrationPlan;
-/** Compute a deterministic digest for cache keys and fixture assertions. */
-declare function migrationPlanDigest(input: MigrationPlan | string): string;
-declare const encodePlan: typeof encodeMigrationPlan;
-declare const decodePlan: typeof decodeMigrationPlan;
-declare const assertPlan: typeof assertMigrationPlan;
-declare const digestMigrationPlan: typeof migrationPlanDigest;
-//#endregion
-export { MigrationCustomSql, MigrationCustomSqlInput, MigrationDecision, MigrationDependency, MigrationDiagnostic, MigrationDiagnosticCode, MigrationLockRequirement, MigrationOperation, MigrationOperationOrigin, MigrationOperationType, MigrationPlan, MigrationPlanDecodeResult, MigrationPlanOptions, MigrationPlanResult, MigrationPlanValidationError, MigrationPlanValidationResult, MigrationPrecondition, MigrationPreconditionType, MigrationSafety, MigrationTransactionRequirement, type SnapshotDiff, assertMigrationPlan, assertMigrationPlanFromDiff, assertPlan, canonicalizeMigrationPlan, createMigrationPlan, createPlan, decodeMigrationPlan, decodePlan, digestMigrationPlan, encodeMigrationPlan, encodePlan, migrationPlanDigest, migrationPlanFormat, migrationPlanVersion, planMigration, validateMigrationPlan };