@descryy/core 0.1.0

package/dist/validation/migrations.js

@@ -0,0 +1,315 @@
+/**
+ * The format half of §15.3's rollback-readiness check — migrations read from the
+ * repository as text.
+ *
+ * Same argument as `sources.ts`: DDL is a **format, not a language**, so reading
+ * it names nothing the Canonical IR boundary forbids. Same limit, too — this half
+ * sees only what is written as DDL, and DEC-122 measured exactly how little that
+ * is: **zero `.sql` files inside a migration directory across fifteen reference
+ * repositories**, against 3,301 migrations written as program code. The code half
+ * arrives through `attrs.migrationOps` and is an adapter's to produce.
+ *
+ * ## The scope fence, which is what makes this Class A
+ *
+ * Appendix B.3 settles rollback readiness as Class A against two sources that
+ * called it B, and the resolution turns entirely on what is claimed:
+ *
+ * > **"this migration contains a destructive operation"** — a fact, and a
+ * > deterministic pattern match establishes it.
+ * >
+ * > **"this migration is unsafe to roll back"** — an inference, requiring the
+ * > consumer-impact analysis §15.3 explicitly separates this check from.
+ *
+ * Every sentence produced here is written to stay behind that fence. The finding
+ * names the operation, the object and the line; it does not characterise risk.
+ *
+ * ## What counts as destructive, and the things deliberately left out
+ *
+ * Only operations that **destroy data**. `DROP INDEX`, `DROP CONSTRAINT`,
+ * `DROP VIEW`, `DROP TRIGGER` and `DROP FUNCTION` are all recoverable by
+ * re-running the definition and none of them loses a row, so including them
+ * would triple the finding count with statements nobody needs to see. A rename
+ * is carried separately: the data survives, so it is not the same claim as a
+ * drop, but every reader of the old name breaks.
+ *
+ * ## Section detection is tool-blind on purpose
+ *
+ * Directional migrations mark their halves with a comment directive. Matching a
+ * specific tool's spelling would put that tool's name in engine code — rule 1,
+ * the violation the boundary lint already caught once in this directory. So the
+ * **shape** is matched instead: a comment carrying a directive word followed by
+ * an up/down keyword, in either the `+name Up` form or a bare `-- Up`. Any tool
+ * using that shape works; none of them is named.
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { skipDirectory } from "./sources.js";
+const DEFAULT_MAX_DEPTH = 8;
+const DEFAULT_MAX_FILES = 20_000;
+/**
+ * A directory holding migrations.
+ *
+ * Path-based rather than content-based, and named after what the directory *is*
+ * rather than after any tool that creates it. A `.sql` file in a `schema/`
+ * directory is a definition, not a change, and reading it as one would report
+ * every `CREATE`-then-`DROP` setup script in the repository.
+ */
+const MIGRATION_DIRECTORY = /(^|\/)(migrations?|migrate|versions|changelogs?)(\/|$)/i;
+/** A directive comment carrying a direction, in either common shape. */
+const SECTION_MARKER = /^\s*--\s*(?:\+\w+\s+)?(up|down)\b/i;
+/**
+ * Split DDL on `;`, ignoring separators inside strings, quoted identifiers and
+ * comments.
+ *
+ * A plain split would cut a statement in half at the first semicolon inside a
+ * default value, which is a real thing to find in a migration.
+ *
+ * **This duplicates the splitter in `adapter-sql`, deliberately and with the
+ * cost recorded** (DEC-122). `@descryy/core` cannot depend on an adapter —
+ * adapters depend on core — so the alternative to a second copy is inverting the
+ * boundary the repository split exists to hold. If a third caller appears, the
+ * right home is `@descryy/ir`.
+ */
+export function statements(sql) {
+    const found = [];
+    let buffer = "";
+    let line = 1;
+    let startLine = 1;
+    let quote = null;
+    let comment = null;
+    const flush = () => {
+        if (buffer.trim() !== "")
+            found.push({ text: buffer.trim(), line: startLine });
+        buffer = "";
+        startLine = line;
+    };
+    for (let i = 0; i < sql.length; i += 1) {
+        const char = sql[i];
+        const next = sql[i + 1];
+        if (char === "\n")
+            line += 1;
+        if (comment === "line") {
+            if (char === "\n")
+                comment = null;
+            continue;
+        }
+        if (comment === "block") {
+            if (char === "*" && next === "/") {
+                comment = null;
+                i += 1;
+            }
+            continue;
+        }
+        if (quote !== null) {
+            buffer += char;
+            if (char === quote)
+                quote = null;
+            continue;
+        }
+        if (char === "-" && next === "-") {
+            comment = "line";
+            continue;
+        }
+        if (char === "/" && next === "*") {
+            comment = "block";
+            i += 1;
+            continue;
+        }
+        if (char === "'" || char === '"' || char === "`") {
+            quote = char;
+            buffer += char;
+            continue;
+        }
+        if (char === ";") {
+            flush();
+            continue;
+        }
+        if (buffer.trim() === "" && char.trim() === "") {
+            startLine = line;
+            continue;
+        }
+        buffer += char;
+    }
+    flush();
+    return found;
+}
+function unquote(identifier) {
+    return identifier.replace(/^["`[]+|["`\]]+$/g, "").toLowerCase();
+}
+/**
+ * Classify one statement.
+ *
+ * Returns `null` for everything unrecognised, which is the overwhelming
+ * majority and is correct: an unclassified statement is not a silent pass, it is
+ * counted by the caller and disclosed.
+ */
+export function classifyStatement(text, line, section) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    const guarded = /\bIF\s+EXISTS\b/i.test(flat);
+    // ALTER TABLE … DROP COLUMN — checked before the bare DROP forms, because
+    // "ALTER TABLE x DROP COLUMN y" also contains the substring "DROP".
+    //
+    // The negative lookahead is not decoration. `ALTER TABLE t DROP CONSTRAINT c`
+    // has the same shape with the keyword omitted, and without the guard the
+    // constraint name is read as a column name — a data-loss claim about a
+    // statement that loses no data. Found by a test, which is where it belongs.
+    const dropColumn = /^ALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?([\w."`[\]]+)\s+DROP\s+(?:COLUMN\s+)?(?:IF\s+EXISTS\s+)?(?!CONSTRAINT\b|INDEX\b|CHECK\b|PRIMARY\b|FOREIGN\b|UNIQUE\b|DEFAULT\b|NOT\b|PARTITION\b)([\w."`[\]]+)/i.exec(flat);
+    if (dropColumn !== null) {
+        return {
+            kind: "DROP_COLUMN",
+            target: `${unquote(dropColumn[1])}.${unquote(dropColumn[2])}`,
+            line,
+            section,
+            guarded,
+        };
+    }
+    const rename = /^ALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?([\w."`[\]]+)\s+RENAME\s+(?:COLUMN\s+)?([\w."`[\]]+)?/i.exec(flat);
+    if (rename !== null) {
+        const object = rename[2];
+        return {
+            kind: "RENAME",
+            target: object === undefined
+                ? unquote(rename[1])
+                : `${unquote(rename[1])}.${unquote(object)}`,
+            line,
+            section,
+            guarded,
+        };
+    }
+    const dropTable = /^DROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?([\w."`[\]]+)/i.exec(flat);
+    if (dropTable !== null) {
+        return { kind: "DROP_TABLE", target: unquote(dropTable[1]), line, section, guarded };
+    }
+    const dropSchema = /^DROP\s+SCHEMA\s+(?:IF\s+EXISTS\s+)?([\w."`[\]]+)/i.exec(flat);
+    if (dropSchema !== null) {
+        return { kind: "DROP_SCHEMA", target: unquote(dropSchema[1]), line, section, guarded };
+    }
+    const truncate = /^TRUNCATE\s+(?:TABLE\s+)?(?:ONLY\s+)?([\w."`[\]]+)/i.exec(flat);
+    if (truncate !== null) {
+        return { kind: "TRUNCATE", target: unquote(truncate[1]), line, section, guarded };
+    }
+    return null;
+}
+/** Objects a statement brings into existence, so a later drop can be discounted. */
+function created(text) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    const table = /^CREATE\s+(?:\w+\s+)*TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?([\w."`[\]]+)/i.exec(flat);
+    if (table !== null)
+        return unquote(table[1]);
+    const schema = /^CREATE\s+SCHEMA\s+(?:IF\s+NOT\s+EXISTS\s+)?([\w."`[\]]+)/i.exec(flat);
+    if (schema !== null)
+        return unquote(schema[1]);
+    return null;
+}
+/** Read one migration file's operations, tracking which section each sits in. */
+export function readMigration(text) {
+    const lines = text.split(/\r?\n/);
+    // Section boundaries are line-based, because the marker is a comment and the
+    // splitter discards comments. Built first, then applied by line number.
+    const boundaries = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const marker = SECTION_MARKER.exec(lines[i] ?? "");
+        if (marker === null)
+            continue;
+        boundaries.push({
+            line: i + 1,
+            section: marker[1].toLowerCase() === "down" ? "reverse" : "forward",
+        });
+    }
+    const directional = boundaries.length > 0;
+    const sectionAt = (line) => {
+        if (!directional)
+            return "unknown";
+        let current = "unknown";
+        for (const boundary of boundaries) {
+            if (boundary.line > line)
+                break;
+            current = boundary.section;
+        }
+        return current;
+    };
+    const ops = [];
+    const creates = [];
+    for (const statement of statements(text)) {
+        const create = created(statement.text);
+        if (create !== null) {
+            creates.push({ name: create, line: statement.line });
+            continue;
+        }
+        const op = classifyStatement(statement.text, statement.line, sectionAt(statement.line));
+        if (op !== null)
+            ops.push(op);
+    }
+    return { ops, creates, directional };
+}
+/** Walk the repository for migration files written as DDL. */
+export function scanMigrations(root, options = {}) {
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+    const noiseDirectories = options.noiseDirectories ?? [];
+    const files = [];
+    const unreadable = [];
+    let seen = 0;
+    let truncated = false;
+    let unparsed = 0;
+    const walk = (dir, depth) => {
+        if (truncated || depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir).sort();
+        }
+        catch {
+            unreadable.push(rel(root, dir));
+            return;
+        }
+        for (const entry of entries) {
+            if (truncated)
+                return;
+            const full = join(dir, entry);
+            let directory = false;
+            try {
+                directory = statSync(full).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (directory) {
+                if (!skipDirectory(entry, noiseDirectories))
+                    walk(full, depth + 1);
+                continue;
+            }
+            if (++seen > maxFiles) {
+                truncated = true;
+                return;
+            }
+            if (!/\.sql$/i.test(entry))
+                continue;
+            const path = rel(root, full);
+            if (!MIGRATION_DIRECTORY.test(path))
+                continue;
+            let text;
+            try {
+                text = readFileSync(full, "utf8");
+            }
+            catch {
+                unreadable.push(path);
+                continue;
+            }
+            const parsed = readMigration(text);
+            if (parsed.ops.length === 0) {
+                unparsed += 1;
+                continue;
+            }
+            files.push({ file: path, ...parsed });
+        }
+    };
+    walk(root, 0);
+    files.sort((a, b) => a.file.localeCompare(b.file));
+    return { files, unreadable, truncated, unparsed };
+}
+function rel(root, full) {
+    const r = relative(root, full);
+    return r === "" ? "." : r.split(sep).join("/");
+}
+//# sourceMappingURL=migrations.js.map

package/dist/validation/migrations.js.map

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

package/dist/validation/nodes.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Which node stands for a file — a question, not a value.
+ *
+ * Split into its own module because all three checks in this directory ask it,
+ * and because the answer was wrong in all three for a day. See below.
+ */
+import type { IRNode } from "@descryy/ir";
+import type { AdjacencyProvider } from "../query/provider.ts";
+/**
+ * The node types that stand for a whole file.
+ *
+ * **Every shipped adapter emits `MODULE` for a file and not one of them emits
+ * `FILE`** — verified across all nine, not assumed. The checks in this directory
+ * were written against `FILE` alone, their tests minted `FILE` nodes, their
+ * benches minted `FILE` nodes, and all three gates passed while the graph half of
+ * every check was unable to fire on any real repository. The number stayed right
+ * and the reason for it had stopped being true.
+ *
+ * Asking for a list of types is what rule 8 warns about — *"a node type is a
+ * question, not a value"* — and the correct home for the question is a predicate
+ * in `@descryy/ir` beside `isTypeLikeNodeType` and `isCallableNodeType`. That is a
+ * shared-package change, so it is **requested rather than taken**: see
+ * `REQUEST-D-file-scoped-nodes.md`. This constant is the local stand-in and it
+ * carries the debt visibly rather than hiding it.
+ */
+export declare const FILE_SCOPED_NODE_TYPES: readonly ["MODULE", "FILE"];
+/** Every file-scoped node, across the types that carry one. */
+export declare function fileScopedNodes(provider: AdjacencyProvider, limit?: number): {
+    readonly nodes: readonly IRNode[];
+    readonly truncated: boolean;
+};
+//# sourceMappingURL=nodes.d.ts.map

package/dist/validation/nodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.d.ts","sourceRoot":"","sources":["../../src/validation/nodes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,sBAAsB,6BAA8B,CAAC;AAElE,+DAA+D;AAC/D,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,CAAC,EAAE,MAAM,GACb;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAgBpE"}

package/dist/validation/nodes.js

@@ -0,0 +1,45 @@
+/**
+ * Which node stands for a file — a question, not a value.
+ *
+ * Split into its own module because all three checks in this directory ask it,
+ * and because the answer was wrong in all three for a day. See below.
+ */
+/**
+ * The node types that stand for a whole file.
+ *
+ * **Every shipped adapter emits `MODULE` for a file and not one of them emits
+ * `FILE`** — verified across all nine, not assumed. The checks in this directory
+ * were written against `FILE` alone, their tests minted `FILE` nodes, their
+ * benches minted `FILE` nodes, and all three gates passed while the graph half of
+ * every check was unable to fire on any real repository. The number stayed right
+ * and the reason for it had stopped being true.
+ *
+ * Asking for a list of types is what rule 8 warns about — *"a node type is a
+ * question, not a value"* — and the correct home for the question is a predicate
+ * in `@descryy/ir` beside `isTypeLikeNodeType` and `isCallableNodeType`. That is a
+ * shared-package change, so it is **requested rather than taken**: see
+ * `REQUEST-D-file-scoped-nodes.md`. This constant is the local stand-in and it
+ * carries the debt visibly rather than hiding it.
+ */
+export const FILE_SCOPED_NODE_TYPES = ["MODULE", "FILE"];
+/** Every file-scoped node, across the types that carry one. */
+export function fileScopedNodes(provider, limit) {
+    const nodes = [];
+    let truncated = false;
+    const seen = new Set();
+    for (const type of FILE_SCOPED_NODE_TYPES) {
+        const set = limit === undefined ? provider.nodesOfType(type) : provider.nodesOfType(type, limit);
+        truncated = truncated || set.truncated;
+        for (const node of set.nodes) {
+            // A repository with both types would otherwise count a path twice, and a
+            // dependent count is a set property.
+            if (node.file !== null && seen.has(node.file))
+                continue;
+            if (node.file !== null)
+                seen.add(node.file);
+            nodes.push(node);
+        }
+    }
+    return { nodes, truncated };
+}
+//# sourceMappingURL=nodes.js.map

package/dist/validation/nodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.js","sourceRoot":"","sources":["../../src/validation/nodes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAU,CAAC;AAElE,+DAA+D;AAC/D,MAAM,UAAU,eAAe,CAC7B,QAA2B,EAC3B,KAAc;IAEd,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,sBAAsB,EAAE,CAAC;QAC1C,MAAM,GAAG,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACjG,SAAS,GAAG,SAAS,IAAI,GAAG,CAAC,SAAS,CAAC;QACvC,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YAC7B,yEAAyE;YACzE,qCAAqC;YACrC,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,SAAS;YACxD,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;gBAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC5C,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAC9B,CAAC"}

package/dist/validation/rollback.d.ts

@@ -0,0 +1,124 @@
+/**
+ * §15.3's rollback-readiness check — *"pattern-match migrations against a known
+ * list of destructive operations"*.
+ *
+ * Class A at R0, and **deliberately the easy half of consumer impact**: a
+ * destructive operation is a pattern in a migration, not an inference about who
+ * reads the column. The scope fence that makes that classification safe is stated
+ * in `migrations.ts` and every sentence below stays behind it.
+ *
+ * ## The trap, measured before this was written
+ *
+ * The env check's trap was a variable read and never declared. This one is
+ * larger, and DEC-122 counted it:
+ *
+ * | repository | migrations | with a reverse section |
+ * | --- | --- | --- |
+ * | `outline` | 300 | **300** |
+ * | `dispatch` | 162 | **162** |
+ * | `directus` | 112 | 110 |
+ *
+ * **Effectively every migration in these projects declares a reverse, and a
+ * destructive operation in the reverse is supposed to be there** — it undoes the
+ * forward migration. A check that matched destructive operations without knowing
+ * which half it was reading would report `outline`'s 202 destructive files, and
+ * most of those matches are a drop that undoes a create three lines above.
+ *
+ * So `section` is to this check what `required` was to the env check: the field
+ * without which the whole thing is wrong on nearly every file it sees. And
+ * `unknown` is not a synonym for `forward`. Two of the reference repositories
+ * declare no direction at all — they hand the framework a reversal callback — and
+ * their operations are **counted and disclosed, never reported**. That refusal
+ * alone withholds 192 files' worth of matches, and it is the honest treatment:
+ * an operation whose half cannot be determined is not evidence of a forward
+ * destructive change.
+ *
+ * ## Two further refusals, both from the only real DDL in the corpus
+ *
+ * - **`DROP … IF EXISTS` paired with a `CREATE` of the same object** is an
+ *   idempotent setup script, not a data-losing change. Both destructive lines in
+ *   the one genuine `.sql` file found across fifteen repositories are exactly
+ *   this shape.
+ * - **Dropping an object created in the same migration** is not a finding. The
+ *   object did not exist before the file ran.
+ *
+ * ## Where the input comes from
+ *
+ * Two sources, and DEC-122 measured that the one the architecture implies is the
+ * smaller: **0 `.sql` files inside a migration directory** across the reference
+ * corpus, against **3,301** migrations written as program code. The format half
+ * runs today and needs no adapter; the code half arrives as `attrs.migrationOps`
+ * and is an adapter's to produce. When neither is present the check says so and
+ * does not report a clean result.
+ */
+import type { ResolutionLevel } from "@descryy/ir";
+import type { AdjacencyProvider, QueryResult } from "../query/provider.ts";
+import type { DestructiveKind, MigrationOp, MigrationScan } from "./migrations.ts";
+export interface RollbackFinding {
+    readonly kind: DestructiveKind;
+    /** The table, column or schema named by the statement. */
+    readonly target: string;
+    readonly file: string;
+    readonly line: number;
+    /**
+     * The sentence a developer reads.
+     *
+     * Stays behind the §15.3 fence: it states that the operation is present, never
+     * that the migration is unsafe to roll back.
+     */
+    readonly detail: string;
+    readonly resolution: ResolutionLevel;
+}
+export interface RollbackReport {
+    readonly findings: readonly RollbackFinding[];
+    /** The count before `maxFindings` capped it — P27's disclosed remainder: a structured field, not only a prose note. */
+    readonly findingsTotal: number;
+    readonly examined: {
+        /** Migration files read as DDL from the repository. */
+        readonly fromSource: number;
+        /** Migration files whose operations came from an adapter. */
+        readonly fromGraph: number;
+        /** Destructive operations seen, before any refusal. */
+        readonly operations: number;
+    };
+    /**
+     * Every operation the check declined to report, by reason.
+     *
+     * The counts are the point: they are the size of what this check chose not to
+     * say, and each has a different cause a reader can act on.
+     */
+    readonly withheld: {
+        /** In a reverse section — undoing a forward migration. */
+        readonly reverse: number;
+        /** The file declares no direction, so the half is unknown. */
+        readonly undirected: number;
+        /** Guarded by `IF EXISTS` alongside a create of the same object. */
+        readonly idempotent: number;
+        /** The object was created by the same migration. */
+        readonly selfCreated: number;
+    };
+    /** True when at least one source supplied operations. */
+    readonly ran: boolean;
+    /** Named, in plain words, when `ran` is false. */
+    readonly blockers: readonly string[];
+}
+export interface RollbackOptions {
+    readonly maxFindings?: number;
+    /** Restrict to these repo-relative files — the scoped-subgraph run. */
+    readonly files?: readonly string[];
+    readonly limit?: number;
+}
+/**
+ * Pull `attrs.migrationOps` off a file node, refusing anything malformed.
+ *
+ * A row with no `section`, or an unrecognised one, is **dropped rather than
+ * treated as forward**. Defaulting it would manufacture exactly the claim the
+ * reverse-section fence exists to withhold, on a corpus where the reverse
+ * section is present in effectively every file.
+ */
+export declare function readMigrationOps(attrs: Readonly<Record<string, unknown>>): {
+    readonly ops: readonly MigrationOp[];
+    readonly malformed: number;
+};
+export declare function checkRollbackReadiness(provider: AdjacencyProvider, scan: MigrationScan, options?: RollbackOptions): QueryResult<RollbackReport>;
+//# sourceMappingURL=rollback.d.ts.map

package/dist/validation/rollback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback.d.ts","sourceRoot":"","sources":["../../src/validation/rollback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,KAAK,EAAE,iBAAiB,EAAc,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEvF,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EACX,aAAa,EAEd,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;CACtC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,uHAAuH;IACvH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE;QACjB,uDAAuD;QACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,6DAA6D;QAC7D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,uDAAuD;QACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE;QACjB,0DAA0D;QAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,8DAA8D;QAC9D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,oEAAoE;QACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,oDAAoD;QACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;KAC9B,CAAC;IACF,yDAAyD;IACzD,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAgBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACvC;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,WAAW,EAAE,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAsCtE;AASD,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,aAAa,EACnB,OAAO,GAAE,eAAoB,GAC5B,WAAW,CAAC,cAAc,CAAC,CAoN7B"}