tablewalk 0.0.1

package/dist/shared/diff.js

@@ -0,0 +1,130 @@
+/**
+ * Two schemas, and what is different about them.
+ *
+ * The question is always the same and always urgent: *is staging the same
+ * shape as production?* Asked before a deploy, after a migration, or when one
+ * environment behaves differently for reasons nobody can name. The usual
+ * answer is two schema dumps and a text diff, which reports every difference
+ * in formatting as loudly as the missing column and buries it.
+ *
+ * This compares the model instead of the text: tables, columns and their
+ * types, nullability and defaults, foreign keys and their delete rules. So
+ * `varchar(40)` written on two lines is not a difference, and a column that
+ * became nullable is — which is the point.
+ *
+ * Direction matters and is named: `left` is what you have, `right` is what
+ * you are comparing against. "Only in production" and "only in staging" are
+ * different sentences with different consequences, and a diff that says
+ * "differs" is a diff that makes you go and look.
+ */
+import { primaryKey } from './schema.js';
+const describeKey = (fk) => `${fk.from.columns.join(', ')} → ${fk.to.table}(${fk.to.columns.join(', ')})`;
+/** A column's facts as strings, so a difference is a difference in one of them. */
+function facts(column, table) {
+    return {
+        type: column.type,
+        nullable: String(column.nullable),
+        default: column.default ?? '—',
+        key: String(primaryKey(table).includes(column.name)),
+        allowed: column.allowed?.length ? column.allowed.join(', ') : '—',
+    };
+}
+export function diffSchemas(left, right) {
+    const byId = (schema) => new Map(schema.tables.map((t) => [t.id, t]));
+    const leftTables = byId(left);
+    const rightTables = byId(right);
+    const tables = [];
+    /* Union of ids, in one order both sides agree on: a diff whose sections
+       move around between runs cannot be diffed itself. */
+    const ids = [...new Set([...leftTables.keys(), ...rightTables.keys()])].sort();
+    for (const id of ids) {
+        const a = leftTables.get(id);
+        const b = rightTables.get(id);
+        if (!a || !b) {
+            tables.push({ table: id, onlyIn: a ? 'left' : 'right' });
+            continue;
+        }
+        const diff = { table: id };
+        const aColumns = new Map(a.columns.map((c) => [c.name, c]));
+        const bColumns = new Map(b.columns.map((c) => [c.name, c]));
+        const onlyLeft = [...aColumns.keys()].filter((n) => !bColumns.has(n));
+        const onlyRight = [...bColumns.keys()].filter((n) => !aColumns.has(n));
+        if (onlyLeft.length)
+            diff.columnsOnlyLeft = onlyLeft;
+        if (onlyRight.length)
+            diff.columnsOnlyRight = onlyRight;
+        const changed = [];
+        for (const [name, column] of aColumns) {
+            const other = bColumns.get(name);
+            if (!other)
+                continue;
+            const mine = facts(column, a);
+            const theirs = facts(other, b);
+            for (const what of Object.keys(mine)) {
+                if (mine[what] !== theirs[what]) {
+                    changed.push({ column: name, what, left: mine[what], right: theirs[what] });
+                }
+            }
+        }
+        if (changed.length)
+            diff.changed = changed;
+        const keysOf = (schema, table) => new Map(schema.foreignKeys.filter((fk) => fk.from.table === table).map((fk) => [describeKey(fk), fk]));
+        const aKeys = keysOf(left, id);
+        const bKeys = keysOf(right, id);
+        const keysOnlyLeft = [...aKeys.keys()].filter((k) => !bKeys.has(k));
+        const keysOnlyRight = [...bKeys.keys()].filter((k) => !aKeys.has(k));
+        if (keysOnlyLeft.length)
+            diff.keysOnlyLeft = keysOnlyLeft;
+        if (keysOnlyRight.length)
+            diff.keysOnlyRight = keysOnlyRight;
+        /* A delete rule that changed is a foreign key that still exists and now
+           does something else on delete — invisible to a "which keys exist"
+           comparison, and the difference that turns a safe delete into a
+           cascade. */
+        const ruleChanges = [...aKeys.entries()]
+            .filter(([key, fk]) => bKeys.has(key) && (fk.onDelete ?? 'no action') !== (bKeys.get(key).onDelete ?? 'no action'))
+            .map(([key, fk]) => ({
+            key,
+            left: fk.onDelete ?? 'no action',
+            right: bKeys.get(key).onDelete ?? 'no action',
+        }));
+        if (ruleChanges.length)
+            diff.deleteRuleChanged = ruleChanges;
+        if (Object.keys(diff).length > 1)
+            tables.push(diff);
+    }
+    return { left: left.label, right: right.label, tables, same: tables.length === 0 };
+}
+/** The diff as a person reads it. */
+export function diffReport(diff) {
+    if (diff.same)
+        return `${diff.left} and ${diff.right} have the same shape.`;
+    const lines = [
+        `# ${diff.left} → ${diff.right}`,
+        '',
+        `${diff.tables.length} table${diff.tables.length === 1 ? ' differs' : 's differ'}. `
+            + `"Only in ${diff.left}" means it is missing from ${diff.right}.`,
+    ];
+    for (const table of diff.tables) {
+        lines.push('', `## ${table.table}`, '');
+        if (table.onlyIn) {
+            lines.push(`- Table exists only in **${table.onlyIn === 'left' ? diff.left : diff.right}**.`);
+            continue;
+        }
+        for (const column of table.columnsOnlyLeft ?? [])
+            lines.push(`- Column \`${column}\` only in ${diff.left}.`);
+        for (const column of table.columnsOnlyRight ?? [])
+            lines.push(`- Column \`${column}\` only in ${diff.right}.`);
+        for (const change of table.changed ?? []) {
+            lines.push(`- \`${change.column}\` ${change.what}: **${change.left}** → **${change.right}**`);
+        }
+        for (const key of table.keysOnlyLeft ?? [])
+            lines.push(`- Foreign key ${key} only in ${diff.left}.`);
+        for (const key of table.keysOnlyRight ?? [])
+            lines.push(`- Foreign key ${key} only in ${diff.right}.`);
+        for (const rule of table.deleteRuleChanged ?? []) {
+            lines.push(`- ${rule.key} on delete: **${rule.left}** → **${rule.right}**`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/shared/like.js

@@ -0,0 +1,29 @@
+/**
+ * The pattern behind `contains`, `starts with` and `ends with`.
+ *
+ * A user typing `contains 50%` means a literal percent sign. Interpolated
+ * straight into a LIKE pattern it becomes a wildcard, so the search matches
+ * every row and the tool reports a hit on data that does not contain the
+ * value — the worst shape of wrong answer, because nothing about it looks
+ * like a failure. `a_c` matching `abc` is the same bug, quieter.
+ *
+ * So the value is escaped and the statement declares an escape character.
+ * `#` rather than the conventional backslash: MySQL parses backslash escapes
+ * inside string literals unless NO_BACKSLASH_ESCAPES is set, which would make
+ * the `ESCAPE` clause itself dialect-specific text.
+ *
+ * Lives in shared/ because the SQL the adapters compile and the SQL the query
+ * bar *shows* you have to agree — a preview that promises a wildcard the
+ * compiler escapes is a lie in the one place the tool is teaching.
+ */
+export const LIKE_ESCAPE = '#';
+/** The wildcards, plus the escape character itself, which must escape too. */
+const SPECIAL = /[#%_]/g;
+export function likePattern(value, op) {
+    const literal = String(value ?? '').replace(SPECIAL, (ch) => `${LIKE_ESCAPE}${ch}`);
+    if (op === 'startsWith')
+        return `${literal}%`;
+    if (op === 'endsWith')
+        return `%${literal}`;
+    return `%${literal}%`;
+}

package/dist/shared/lint.js

@@ -0,0 +1,149 @@
+/**
+ * What the shape says about itself.
+ *
+ * Everything here is a fact tablewalk already holds — the tables, the keys,
+ * the indexes' leading columns, the delete rules — asked a different
+ * question: not "what is this" but "what will this cost the person who has
+ * to work with it". A foreign key with no index behind it is the reverse
+ * walk this whole tool is built on, run as a full scan every time. A table
+ * with no primary key is a row nobody can edit or link to. Neither is
+ * visible while browsing, because browsing a small table hides both.
+ *
+ * Deliberately narrow. Every rule is checkable from the catalog with no
+ * queries and no heuristics about intent, and each one names the consequence
+ * rather than the rule — "a schema lint that only cites style" is a lint
+ * people turn off. Anything requiring judgement about the domain (a column
+ * that should have been an enum, a table that should have been two) is left
+ * out on purpose: it would be guessing, and guessing at scale is noise.
+ */
+import { primaryKey, referencesFrom, } from './schema.js';
+/** The cost of each rule, said once. */
+export const WHY = {
+    'no-primary-key': 'No row here can be linked to, edited or deleted by this tool, and nothing else can point at it either.',
+    'unindexed-foreign-key': 'Every walk back from the referenced table scans this whole table, and so does deleting a referenced row.',
+    'no-delete-rule': 'Deleting a parent fails at the moment someone tries it rather than saying what it would do. Restrict, cascade or set null states the intent.',
+    'timestamp-without-zone': 'The same stored text is a different instant to a reader in another zone, and nothing records which one wrote it.',
+    'unreferenced-table': 'It cannot be reached by walking, only by naming it — either a lookup nobody wired up, or something meant to stand alone.',
+};
+/** `timestamp` without a zone: the same text means a different instant per reader. */
+const NAIVE_TIMESTAMP = /^timestamp( without time zone)?$/i;
+export function lintSchema(schema, options = {}) {
+    const skip = new Set(options.skip ?? []);
+    const findings = [];
+    const add = (finding) => {
+        if (!skip.has(finding.rule))
+            findings.push(finding);
+    };
+    for (const table of schema.tables) {
+        /* A view has no key, no index and no delete rule by definition, and
+           saying so about each one would bury the tables that can be fixed. */
+        if (table.isView)
+            continue;
+        if (!primaryKey(table).length) {
+            add({
+                rule: 'no-primary-key',
+                severity: 'high',
+                table: table.id,
+                message: `${table.name} has no primary key.`,
+                why: WHY['no-primary-key'],
+            });
+        }
+        for (const fk of referencesFrom(schema, table.id)) {
+            const lead = fk.from.columns[0];
+            /* `indexed` carries only each index's *leading* column, which is
+               exactly the question here: an index on (a, b) makes a lookup by `a`
+               free and does nothing for a lookup by `b` alone. Absent means the
+               adapter does not report indexes — that is "we did not look", not
+               "there are none", so it is not a finding. */
+            if (table.indexed && !table.indexed.includes(lead)) {
+                add({
+                    rule: 'unindexed-foreign-key',
+                    severity: 'high',
+                    table: table.id,
+                    columns: fk.from.columns,
+                    message: `${lead} → ${fk.to.table}, with no index leading on ${lead}.`,
+                    why: WHY['unindexed-foreign-key'],
+                });
+            }
+            if (!fk.onDelete || /^no action$/i.test(fk.onDelete)) {
+                add({
+                    rule: 'no-delete-rule',
+                    severity: 'medium',
+                    table: table.id,
+                    columns: fk.from.columns,
+                    message: `${fk.from.columns.join(', ')} → ${fk.to.table}, with no ON DELETE rule.`,
+                    why: WHY['no-delete-rule'],
+                });
+            }
+        }
+        for (const column of table.columns) {
+            if (NAIVE_TIMESTAMP.test(column.type)) {
+                add({
+                    rule: 'timestamp-without-zone',
+                    severity: 'medium',
+                    table: table.id,
+                    columns: [column.name],
+                    message: `${column.name} is a timestamp with no time zone.`,
+                    why: WHY['timestamp-without-zone'],
+                });
+            }
+        }
+    }
+    /* Islands last, and low: a table nothing points at and which points at
+       nothing is sometimes a lookup nobody wired up, and sometimes a log
+       that is meant to stand alone. Worth seeing, not worth alarming about. */
+    for (const table of schema.tables) {
+        if (table.isView)
+            continue;
+        if (referencesFrom(schema, table.id).length)
+            continue;
+        if (schema.foreignKeys.some((fk) => fk.to.table === table.id))
+            continue;
+        add({
+            rule: 'unreferenced-table',
+            severity: 'low',
+            table: table.id,
+            message: `Nothing points at ${table.name} and it points at nothing.`,
+            why: WHY['unreferenced-table'],
+        });
+    }
+    return findings;
+}
+const ORDER = { high: 0, medium: 1, low: 2 };
+/** Findings as a person reads them: worst first, grouped under their table. */
+export function lintReport(findings) {
+    if (!findings.length)
+        return 'Nothing to report: no missing keys, unindexed references or naive timestamps.';
+    /* By table, then by severity within it. Sorting the other way round splits
+       every table across three places in the document, and a schema is read
+       one table at a time. */
+    const sorted = [...findings].sort((a, b) => a.table.localeCompare(b.table) || ORDER[a.severity] - ORDER[b.severity]);
+    const counts = lintCounts(findings);
+    const lines = [
+        `${findings.length} finding${findings.length === 1 ? '' : 's'}: `
+            + `${counts.high} high, ${counts.medium} medium, ${counts.low} low.`,
+    ];
+    let table = '';
+    for (const finding of sorted) {
+        if (finding.table !== table) {
+            table = finding.table;
+            lines.push('', `## ${table}`, '');
+        }
+        lines.push(`- **${finding.severity}** ${finding.rule} — ${finding.message}`);
+    }
+    /* The costs once, at the end, rather than on every line. Seventeen
+       identical sentences is a list nobody reads past the third one. */
+    const rules = [...new Set(sorted.map((f) => f.rule))].sort();
+    lines.push('', '## Why these matter', '');
+    for (const rule of rules)
+        lines.push(`- **${rule}** — ${WHY[rule] ?? ''}`);
+    return lines.join('\n').trim();
+}
+/** How many of each, for a caller deciding whether to fail a build. */
+export function lintCounts(findings) {
+    return {
+        high: findings.filter((f) => f.severity === 'high').length,
+        medium: findings.filter((f) => f.severity === 'medium').length,
+        low: findings.filter((f) => f.severity === 'low').length,
+    };
+}

package/dist/shared/order.js

@@ -0,0 +1,133 @@
+/**
+ * What has to exist first, and what comes apart in which order.
+ *
+ * Every foreign key is a statement about time: a row cannot point at a row
+ * that is not there yet, and a row that is pointed at cannot leave before the
+ * rows pointing at it. Building test data means knowing that order, and
+ * deriving it by hand from a catalog is exactly the work this tool already
+ * did to draw the graph.
+ *
+ * A topological sort, with the two things a topological sort usually leaves
+ * out said out loud:
+ *
+ *   - **Cycles.** Two tables that point at each other have no order. Rather
+ *     than picking one and pretending, the cycle is named — and where one of
+ *     its edges is nullable, the way through is named too: insert with the
+ *     column null, then update it once the other row exists.
+ *   - **Self-references.** `work_order.parent_id → work_order` is not a
+ *     cycle between tables and does not affect the order at all, but it does
+ *     mean the rows inside that table have an order of their own. Reported
+ *     separately, because it is a different problem with a different answer.
+ *
+ * Ties break alphabetically. A stable answer is worth more than a marginally
+ * shorter one: an order that changes between runs makes a fixture that
+ * "sometimes works", which is the failure this exists to prevent.
+ */
+import { findTable } from './schema.js';
+/**
+ * @param tables The tables to order. Omitted means every table in the schema.
+ *   Names are resolved through `findTable`, so a bare name works where the
+ *   schema qualifies it.
+ */
+export function insertOrder(schema, tables) {
+    const wanted = tables?.length
+        ? tables.map((name) => findTable(schema, name)?.id ?? name)
+        : schema.tables.filter((t) => !t.isView).map((t) => t.id);
+    const inSet = new Set(wanted);
+    const requires = {};
+    const selfReferencing = [];
+    /* `after.get(a)` holds the tables that must come *after* a — the edges of
+       the sort, pointing the way an insert travels. */
+    const after = new Map(wanted.map((id) => [id, new Set()]));
+    const waitingOn = new Map(wanted.map((id) => [id, 0]));
+    for (const fk of schema.foreignKeys) {
+        const from = fk.from.table;
+        const to = fk.to.table;
+        if (!inSet.has(from))
+            continue;
+        if (from === to) {
+            if (!selfReferencing.includes(from))
+                selfReferencing.push(from);
+            continue;
+        }
+        /* A reference out of the set is still a requirement — the row it points
+           at has to exist — but it cannot be ordered, because it is not part of
+           what was asked about. It belongs in `requires` and not in the sort. */
+        const columns = findTable(schema, from)?.columns ?? [];
+        const optional = fk.from.columns.every((name) => columns.find((c) => c.name === name)?.nullable !== false);
+        (requires[from] ??= []).push({ table: to, via: fk.from.columns, optional });
+        if (!inSet.has(to))
+            continue;
+        if (after.get(to).has(from))
+            continue;
+        after.get(to).add(from);
+        waitingOn.set(from, (waitingOn.get(from) ?? 0) + 1);
+    }
+    const insert = [];
+    const ready = wanted.filter((id) => !waitingOn.get(id)).sort();
+    while (ready.length) {
+        const id = ready.shift();
+        insert.push(id);
+        /* Sorted on the way in, so the answer does not depend on the order the
+           catalog happened to list the keys in. */
+        for (const next of [...after.get(id)].sort()) {
+            const left = (waitingOn.get(next) ?? 0) - 1;
+            waitingOn.set(next, left);
+            if (left === 0) {
+                ready.push(next);
+                ready.sort();
+            }
+        }
+    }
+    /* Whatever is left is in a cycle, or behind one. Grouped so the answer
+       names the knot rather than listing its members. */
+    const stuck = wanted.filter((id) => !insert.includes(id));
+    const cycles = groupCycles(stuck, after);
+    for (const list of Object.values(requires)) {
+        list.sort((a, b) => a.table.localeCompare(b.table));
+    }
+    return {
+        insert,
+        remove: [...insert].reverse(),
+        requires,
+        cycles,
+        selfReferencing: selfReferencing.sort(),
+    };
+}
+/**
+ * The knots, as knots.
+ *
+ * Two tables pointing at each other and a third waiting behind them are one
+ * problem with one fix, and three lines saying "could not be ordered" is
+ * three problems to work out are the same one.
+ */
+function groupCycles(stuck, after) {
+    const left = new Set(stuck);
+    const groups = [];
+    while (left.size) {
+        const start = [...left].sort()[0];
+        const group = new Set([start]);
+        const queue = [start];
+        while (queue.length) {
+            const id = queue.shift();
+            for (const next of after.get(id) ?? []) {
+                if (!left.has(next) || group.has(next))
+                    continue;
+                group.add(next);
+                queue.push(next);
+            }
+            /* Both directions: a cycle is only visible if the walk can go back the
+               way the arrows came. */
+            for (const [other, targets] of after) {
+                if (!left.has(other) || group.has(other) || !targets.has(id))
+                    continue;
+                group.add(other);
+                queue.push(other);
+            }
+        }
+        for (const id of group)
+            left.delete(id);
+        groups.push([...group].sort());
+    }
+    return groups;
+}