tewip-ai 0.30.0 → 0.31.0

package/README.md

@@ -552,6 +552,52 @@ With `--json` the verdict is **sealed**: editing `not-ready` to `ready` in the f
 fail, so a verdict that travels into a ticket or a release note can be checked rather than trusted. It is
 also an MCP tool, so an agent can ask whether its own work is done before saying that it is.
 
+## What will this migration do to a live database? (Phase 26)
+
+```bash
+tewip schema --diff main...HEAD      # or: tewip schema migrations/0002_drop_nickname.sql
+tewip schema --strict                # fails the build on a change that breaks the running version
+```
+
+The most expensive change in a pull request is usually not a test — it is a migration. A column dropped
+while the previous deployment is still selecting it. An index built without `CONCURRENTLY`, blocking every
+write to the busiest table. A `NOT NULL` added to a populated table. These are known, documented, and a
+tool can name every one of them from the text of the migration.
+
+```
+1 of 1 migration file(s) read. 1 change(s) would break the running version or destroy data
+
+## Breaks the version that is still running (1)
+- drops the column nickname from orders — migrations/0002_drop_nickname.sql:1
+  - Instead: deploy code that no longer selects or writes the column, then drop it in a later
+    migration. During a rolling deploy the old version is still running and will fail on a column
+    that is gone
+
+## Code that still uses what this takes away (1)
+- orders.nickname is still named in 1 file(s): app/orders.py
+```
+
+That last section is the part no SQL linter does: it searches your own code for what the migration takes
+away. "This drops `users.nickname`, and four files still read it" is a different sentence from "dropping a
+column is risky", and it is the one that stops the outage.
+
+It reads **SQL, Django, Rails and Alembic** migrations, judges **only the forward path** (a rollback step
+contains the mirror image of the change, so reading it says a migration that creates a table destroys
+one), and stays quiet when the team already did the safe thing — `atomic = False`, `algorithm:
+:concurrently`, `NOT VALID`, `postgresql_concurrently=True`. When it cannot read a migration it says so
+rather than passing it, and "read and nothing found" never looks like "not read".
+
+**Tried on real projects.** 200 Zulip migrations: 199 read, 19 changes that break the running version or
+destroy data, each sampled finding correct when read against the file — including a `DROP COLUMN` buried
+in raw SQL inside a Python data migration. 60 Mastodon migrations: it caught a `change_column` that
+rewrites a table, in a migration whose *name* says it only adds one.
+
+What it does not know, and says so: your table sizes and how busy the database is, so it reports what a
+statement **does** — rewrites the table, scans every row, blocks writes — and leaves the duration to the
+person who knows the data. In CI the findings go into the pull request comment, and anything that breaks
+the running version enters the evidence bundle as a refusal: a passing test suite does not verify a
+migration.
+
 ## Run only the tests that could notice this change (Phase 25)
 
 ```bash
@@ -588,6 +634,22 @@ test that would have caught the bug; on a monolith where every test imports the
 there is nothing to skip, rather than inventing a saving. It is also an MCP tool, so an agent can ask what
 to run before running anything.
 
+**In CI**, `mode: pick` runs before your tests and hands the workflow the files to run:
+
+```yaml
+- id: pick
+  uses: hmamut39/tewip@main
+  with: { mode: pick }        # needs fetch-depth: 0 on actions/checkout
+- run: npx jest ${{ steps.pick.outputs.tests }}
+  if: steps.pick.outputs.narrowed == 'true'
+- run: npx jest
+  if: steps.pick.outputs.narrowed != 'true'
+```
+
+Whatever it leaves out is written into the job summary with the reason beside it, so "why did CI not run
+that test" is answered by the run itself. When it will not narrow safely, `narrowed` is `false` and
+`tests` is empty - so a workflow that ignores the flag still runs everything, which is the safe default.
+
 ## Would your tests catch a bug? (Phase 23)
 
 ```bash

package/dist/cli/help.js

@@ -118,6 +118,13 @@ Usage:
                                     is what was asked for covered. Answers ready, not ready, or cannot
                                     say - and cannot say is never rounded up to ready. --json writes a
                                     sealed verdict that can be checked later. No model, no cost.
+  tewip schema [<files>] [--diff main...HEAD] [--strict] [--out schema.md]
+                                    What will this migration do to a live database? Names the changes
+                                    that break the version still running during a deploy, destroy data,
+                                    block writes while they run, or cannot be undone - and searches your
+                                    code for what still uses the column it takes away. Reads SQL, Django,
+                                    Rails and Alembic migrations, and says so when it cannot read one.
+                                    No model, no cost.
   tewip pick [--diff main...HEAD] [--list] [--out picked.md]
                                     Which tests could notice this change? Narrows a test run using
                                     facts rather than a prediction: a test runs when it imports a

package/dist/cli/tewip.js

@@ -199,6 +199,17 @@ async function main() {
             });
             return;
         }
+        case 'schema': {
+            const { runSchema } = await import('../engine/schema/schema-command.js');
+            runSchema({
+                root: process.cwd(),
+                diff: flag(args, 'diff') ?? 'main...HEAD',
+                files: args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--diff' && args[i - 1] !== '--out'),
+                out: flag(args, 'out'),
+                strict: args.includes('--strict'),
+            });
+            return;
+        }
         case 'pick': {
             const { runPick } = await import('../engine/pick/pick-command.js');
             runPick({

package/dist/engine/schema/frameworks.js

@@ -0,0 +1,230 @@
+export function dialectOf(file, text) {
+    const path = file.split('\\').join('/').toLowerCase();
+    if (path.endsWith('.sql'))
+        return 'sql';
+    // `class Migration(migrations.Migration)` is what makes a file a Django migration. Keying only on the
+    // operation names left Zulip's data migrations unread - and a data migration is exactly the kind that
+    // runs for an hour with a transaction held open.
+    if (/\bmigrations\.Migration\b|\bmigrations\.(?:CreateModel|AddField|RemoveField|AlterField|RenameField|RunSQL|RunPython|DeleteModel|RenameModel)\b/.test(text))
+        return 'django';
+    if (/\bActiveRecord::Migration\b|\bdef\s+(?:up|change)\b[\s\S]*\b(?:add_column|remove_column|add_index|change_column|rename_column|drop_table)\b/.test(text))
+        return 'rails';
+    if (/\bop\.(?:drop_column|add_column|create_index|alter_column|drop_table|rename_table|execute)\b/.test(text))
+        return 'alembic';
+    if (/(^|\/)(migrations?|db\/migrate)\//.test(path))
+        return 'unknown';
+    return 'unknown';
+}
+const STR = String.raw `['"]([\w.]+)['"]`;
+/** Django's operations. `model_name` and `name` are the table and the column. */
+const DJANGO = [
+    {
+        find: new RegExp(String.raw `migrations\.RemoveField\([\s\S]{0,200}?model_name=${STR}[\s\S]{0,200}?name=${STR}`, 'i'),
+        risk: 'breaks-old-code',
+        what: (m) => `removes the field ${m[2]} from ${m[1]}`,
+        instead: 'stop reading and writing the field, deploy that, then remove it in a later migration. The version still running during a rolling deploy will select a column that no longer exists',
+        table: (m) => m[1],
+        column: (m) => m[2],
+    },
+    {
+        find: new RegExp(String.raw `migrations\.RenameField\([\s\S]{0,200}?model_name=${STR}[\s\S]{0,200}?old_name=${STR}`, 'i'),
+        risk: 'breaks-old-code',
+        what: (m) => `renames ${m[1]}.${m[2]}`,
+        instead: 'add the new field, write to both, move the readers, then remove the old one',
+        table: (m) => m[1],
+        column: (m) => m[2],
+    },
+    {
+        find: new RegExp(String.raw `migrations\.DeleteModel\([\s\S]{0,120}?${STR}`, 'i'),
+        risk: 'destroys-data',
+        what: (m) => `deletes the model ${m[1]} and its table`,
+        instead: 'stop using it, ship that, confirm nothing reads it, and delete it later',
+        table: (m) => m[1],
+    },
+    {
+        find: new RegExp(String.raw `migrations\.AddField\([\s\S]{0,400}?null=False(?![\s\S]{0,400}?default=)`, 'i'),
+        risk: 'breaks-old-code',
+        what: () => 'adds a field that cannot be null and has no default',
+        instead: 'add it with null=True or a default. Without one, Django rewrites the table and every insert from the running version fails',
+    },
+    {
+        find: new RegExp(String.raw `migrations\.AlterField\([\s\S]{0,400}?null=False`, 'i'),
+        risk: 'locks-writes',
+        what: () => 'makes an existing field NOT NULL, which reads every row under a lock',
+        instead: 'backfill first, add a validated constraint, then alter - or use SeparateDatabaseAndState with the safe SQL',
+    },
+    {
+        // A data migration. Django wraps a migration in one transaction, so this holds it open for as long as
+        // the work takes - fine for a hundred rows, an outage for a hundred million.
+        find: /migrations\.RunPython\(/,
+        unless: /atomic\s*=\s*False/,
+        risk: 'slow',
+        what: () => 'runs application code against the data inside the migration transaction',
+        instead: 'for a large table, work in batches with atomic = False on the migration and make it resumable. For a small one this is fine - Tewip cannot see how many rows there are',
+    },
+    {
+        find: /AddIndex\(|AddConstraint\(/i,
+        unless: /AddIndexConcurrently|AddConstraintNotValid|atomic\s*=\s*False/,
+        risk: 'locks-writes',
+        what: () => 'adds an index or constraint, which Django builds with a lock unless told otherwise',
+        instead: 'AddIndexConcurrently / AddConstraintNotValid from django.contrib.postgres.operations, with atomic = False on the migration',
+    },
+];
+/** Rails migrations. */
+const RAILS = [
+    {
+        find: new RegExp(String.raw `remove_column\s*[\s(]\s*:?(\w+)\s*,\s*:?(\w+)`, 'i'),
+        risk: 'breaks-old-code',
+        what: (m) => `removes ${m[1]}.${m[2]}`,
+        instead: "ignore the column in the model (self.ignored_columns), deploy that, then remove it. Rails caches the column list, so the running version keeps selecting it",
+        table: (m) => m[1],
+        column: (m) => m[2],
+    },
+    {
+        find: new RegExp(String.raw `rename_column\s*[\s(]\s*:?(\w+)\s*,\s*:?(\w+)`, 'i'),
+        risk: 'breaks-old-code',
+        what: (m) => `renames ${m[1]}.${m[2]}`,
+        instead: 'add the new column, write to both, move the readers, then remove the old one',
+        table: (m) => m[1],
+        column: (m) => m[2],
+    },
+    {
+        find: new RegExp(String.raw `drop_table\s*[\s(]\s*:?(\w+)`, 'i'),
+        risk: 'destroys-data',
+        what: (m) => `drops the table ${m[1]}`,
+        instead: 'stop using it, ship that, then drop it later',
+        table: (m) => m[1],
+    },
+    {
+        find: /add_index\s*[\s(]/i,
+        unless: /algorithm:\s*:concurrently/,
+        risk: 'locks-writes',
+        what: () => 'adds an index without algorithm: :concurrently, so writes to the table block while it builds',
+        instead: 'add_index ..., algorithm: :concurrently, with disable_ddl_transaction! on the migration',
+    },
+    {
+        find: new RegExp(String.raw `change_column\s*[\s(]\s*:?(\w+)\s*,\s*:?(\w+)`, 'i'),
+        risk: 'locks-writes',
+        what: (m) => `changes the type of ${m[1]}.${m[2]}, which usually rewrites the table`,
+        instead: 'add a new column, backfill in batches, switch the readers, then drop the old one',
+        table: (m) => m[1],
+        column: (m) => m[2],
+    },
+    {
+        find: new RegExp(String.raw `change_column_null\s*[\s(]\s*:?(\w+)\s*,\s*:?(\w+)\s*,\s*false`, 'i'),
+        risk: 'locks-writes',
+        what: (m) => `makes ${m[1]}.${m[2]} NOT NULL, which reads every row under a lock`,
+        instead: 'add a validated check constraint first, then set the column NOT NULL',
+        table: (m) => m[1],
+        column: (m) => m[2],
+    },
+];
+/** Alembic. */
+const ALEMBIC = [
+    {
+        find: new RegExp(String.raw `op\.drop_column\(\s*${STR}\s*,\s*${STR}`, 'i'),
+        risk: 'breaks-old-code',
+        what: (m) => `drops ${m[1]}.${m[2]}`,
+        instead: 'stop reading and writing it, deploy that, then drop it in a later revision',
+        table: (m) => m[1],
+        column: (m) => m[2],
+    },
+    {
+        find: new RegExp(String.raw `op\.drop_table\(\s*${STR}`, 'i'),
+        risk: 'destroys-data',
+        what: (m) => `drops the table ${m[1]}`,
+        instead: 'stop using it, ship that, then drop it later',
+        table: (m) => m[1],
+    },
+    {
+        find: new RegExp(String.raw `op\.alter_column\([\s\S]{0,300}?nullable=False`, 'i'),
+        risk: 'locks-writes',
+        what: () => 'makes a column NOT NULL, which reads every row under a lock',
+        instead: 'backfill, add a validated constraint, then alter the column',
+    },
+    {
+        find: /op\.create_index\(/i,
+        unless: /postgresql_concurrently\s*=\s*True/,
+        risk: 'locks-writes',
+        what: () => 'builds an index without postgresql_concurrently, so writes block while it builds',
+        instead: 'op.create_index(..., postgresql_concurrently=True) with a non-transactional revision',
+    },
+    {
+        find: new RegExp(String.raw `op\.rename_table\(\s*${STR}`, 'i'),
+        risk: 'breaks-old-code',
+        what: (m) => `renames the table ${m[1]}`,
+        instead: 'move the readers first, or keep a view with the old name',
+        table: (m) => m[1],
+    },
+];
+const BY_DIALECT = { django: DJANGO, rails: RAILS, alembic: ALEMBIC };
+/** Findings from a framework migration, with the line each one sits on. */
+export function readFramework(dialect, text) {
+    const lines = text.split(String.fromCharCode(10));
+    const out = [];
+    for (const operation of BY_DIALECT[dialect]) {
+        const hit = operation.find.exec(text);
+        if (!hit)
+            continue;
+        if (operation.unless?.test(text))
+            continue;
+        // The line the match starts on, so the reader can go straight to it.
+        const before = text.slice(0, hit.index ?? 0).split(String.fromCharCode(10)).length;
+        out.push({
+            statement: (lines[before - 1] ?? hit[0]).trim().slice(0, 300),
+            line: before,
+            risk: operation.risk,
+            what: operation.what(hit),
+            instead: operation.instead,
+            table: operation.table?.(hit) ?? '',
+            column: operation.column?.(hit) ?? '',
+        });
+    }
+    return out;
+}
+/** A migration that cannot be rolled back by running its own down step. */
+export function irreversible(dialect, text) {
+    if (dialect === 'django')
+        return /migrations\.RunPython\([^)]*\)/.test(text) && !/reverse_code|RunPython\.noop/.test(text);
+    if (dialect === 'alembic')
+        return /def\s+downgrade\(\)[\s\S]{0,120}?(?:pass|raise\s+NotImplementedError)/.test(text);
+    if (dialect === 'rails')
+        return /\braise\s+ActiveRecord::IrreversibleMigration\b/.test(text);
+    return false;
+}
+/**
+ * The forward path only, with the rollback blanked out.
+ *
+ * A migration's `down` step is what runs if the change is undone, and it necessarily contains the mirror
+ * image of the change - a drop_table for a create_table, a remove_column for an add_column. Reading it as
+ * part of the change produces exactly the wrong answer, and Mastodon's own migration proved it: a file
+ * that creates a table was reported as destroying one, because its rollback drops it.
+ *
+ * The region is blanked rather than removed so every remaining line keeps its number.
+ */
+export function forwardOnly(dialect, text) {
+    const lines = text.split(String.fromCharCode(10));
+    const blankFrom = (start, until, indent) => {
+        for (let i = start; i < lines.length; i += 1) {
+            if (i > start && until(lines[i], indent))
+                return;
+            lines[i] = '';
+        }
+    };
+    const indentOf = (line) => line.length - line.trimStart().length;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const down = (dialect === 'rails' && /^\s*def\s+down\b/.test(line)) ||
+            (dialect === 'alembic' && /^\s*def\s+downgrade\s*\(/.test(line)) ||
+            (dialect === 'sql' && /^\s*--\s*(?:\+migrate\s+Down|\+goose\s+Down|\/\/@UNDO|Down\b)/i.test(line));
+        if (down) {
+            // To the end of the block: the next line at the same indentation or less that starts something new.
+            blankFrom(i, (l, indent) => l.trim() !== '' && indentOf(l) <= indent && !/^\s*(end|\})\s*$/.test(l), indentOf(line));
+            continue;
+        }
+        // Rails's `direction.down { ... }` is usually one line.
+        if (dialect === 'rails' && /direction\.down\b/.test(line))
+            lines[i] = '';
+    }
+    return lines.join(String.fromCharCode(10));
+}

package/dist/engine/schema/schema-command.js

@@ -0,0 +1,174 @@
+// `tewip schema --diff main...HEAD`: what this migration will do to a live database.
+//
+// The part that no SQL linter does, and the reason this belongs in Tewip rather than in a linter: it
+// looks for the code that still uses what the migration takes away. "This drops users.nickname, and four
+// files still read it" is a different sentence from "dropping a column is risky", and it is the one that
+// stops the outage.
+//
+// That check is a search of the repository, so it is evidence rather than proof, and it is worded as
+// such. A mention in a comment counts as a mention; Tewip says where it looked and lets the reader judge.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { changeSummary } from '../quality/grounding.js';
+import { dialectOf, forwardOnly, irreversible, readFramework } from './frameworks.js';
+import { readSql } from './statements.js';
+const MIGRATION = /(^|\/)(migrations?|db\/migrate|prisma\/migrations|alembic|flyway|sql)\//i;
+const SCHEMA_FILE = /\.(sql)$|(^|\/)(migrations?|db\/migrate)\/.*\.(py|rb|js|ts)$/i;
+/** The schema files in this change. */
+export function schemaFiles(cmd) {
+    const given = cmd.files && cmd.files.length > 0 ? cmd.files : (changeSummary(cmd.root, cmd.diff)?.files ?? []);
+    return given
+        .map((f) => f.split('\\').join('/'))
+        .filter((f) => (SCHEMA_FILE.test(f) || MIGRATION.test(f)) && existsSync(resolve(cmd.root, f)));
+}
+export function readMigration(root, file) {
+    let text = '';
+    try {
+        text = readFileSync(resolve(root, file), 'utf8');
+    }
+    catch {
+        return { file, dialect: 'unknown', findings: [], unread: 'the file could not be read', irreversible: false };
+    }
+    const dialect = dialectOf(file, text);
+    // Only the forward path: a rollback step contains the mirror image of the change, and reading it as
+    // part of the change says a migration that creates a table destroys one.
+    const forward = forwardOnly(dialect, text);
+    if (dialect === 'sql')
+        return { file, dialect, findings: readSql(forward), unread: '', irreversible: false };
+    if (dialect === 'unknown') {
+        return {
+            file,
+            dialect,
+            findings: [],
+            unread: 'Tewip does not recognise how this migration is written, so it says nothing about it rather than passing it. It reads SQL, Django, Rails and Alembic migrations',
+            irreversible: false,
+        };
+    }
+    const findings = readFramework(dialect, forward);
+    // A migration that only runs raw SQL through the framework is still readable: the SQL is the migration.
+    // Raw SQL, however it reaches the database: through the framework, or through a cursor inside a data
+    // migration, which is where most large projects put the dangerous parts.
+    const raw = [...forward.matchAll(/(?:RunSQL|op\.execute|execute|cursor\.execute)\(\s*(?:r?["'`]{1,3})([\s\S]*?)["'`]{1,3}\s*[,)]/g)].map((m) => m[1]).join(';');
+    if (raw.trim())
+        findings.push(...readSql(raw));
+    return { file, dialect, findings, unread: '', irreversible: irreversible(dialect, text) };
+}
+/**
+ * Code outside the migrations that still names a table or column this change takes away.
+ *
+ * `git grep` because it respects the repository's own ignore rules and is fast on a large tree. A column
+ * named `name` or `id` is not searched for: everything matches it, and a finding that always fires teaches
+ * a reader to ignore the whole report.
+ */
+export function stillUsed(root, findings) {
+    const out = [];
+    const tooCommon = new Set(['id', 'name', 'type', 'value', 'data', 'key', 'status', 'state', 'date', 'time', 'user', 'count', 'index', 'order', 'group', 'text', 'url', 'size', 'code']);
+    for (const finding of findings) {
+        if (finding.risk !== 'breaks-old-code' && finding.risk !== 'destroys-data')
+            continue;
+        const what = finding.column || finding.table;
+        if (!what || what.length < 4 || tooCommon.has(what.toLowerCase()))
+            continue;
+        if (out.some((u) => u.table === finding.table && u.column === finding.column))
+            continue;
+        let files = grepFor(root, what);
+        // A bare column name is too weak on its own. Dropping `fasp_providers.capabilities` from Mastodon
+        // matched 37 files including a Dockerfile and an emoji module, because "capabilities" is an ordinary
+        // word - and noise in the one section meant to be the differentiator is worse than silence. So when a
+        // column is named, the file has to mention the table as well.
+        if (finding.column && finding.table) {
+            const named = new Set([...grepFor(root, finding.table), ...grepFor(root, singular(finding.table))]);
+            files = files.filter((f) => named.has(f));
+        }
+        if (files.length > 0)
+            out.push({ table: finding.table, column: finding.column, files });
+    }
+    return out;
+}
+/** Files naming this word, excluding migrations and documentation. */
+function grepFor(root, word) {
+    if (!word || word.length < 4)
+        return [];
+    const found = spawnSync('git', ['grep', '-l', '-w', '--', word], { cwd: root, encoding: 'utf8', timeout: 60_000 });
+    return (found.stdout ?? '')
+        .split(String.fromCharCode(10))
+        .map((l) => l.trim().split(String.fromCharCode(92)).join('/'))
+        .filter((l) => l && !MIGRATION.test(l) && !/\.(md|txt|lock|json)$/i.test(l));
+}
+/** `fasp_providers` is the table; the code calls the model `FaspProvider`, so the singular is searched too. */
+const singular = (table) => (table.endsWith('ies') ? table.slice(0, -3) + 'y' : table.endsWith('s') && !table.endsWith('ss') ? table.slice(0, -1) : table);
+const ORDER = ['breaks-old-code', 'destroys-data', 'locks-writes', 'slow', 'irreversible', 'fine'];
+const TITLES = {
+    'breaks-old-code': 'Breaks the version that is still running',
+    'destroys-data': 'Destroys data',
+    'locks-writes': 'Blocks writes while it runs',
+    slow: 'Holds a long transaction',
+    irreversible: 'Cannot be undone',
+    fine: 'Worth knowing',
+};
+export function renderSchema(migrations, used) {
+    const all = migrations.flatMap((m) => m.findings);
+    const serious = all.filter((f) => f.risk === 'breaks-old-code' || f.risk === 'destroys-data');
+    const lines = [
+        '# What this migration does to a live database',
+        '',
+        migrations.length === 0
+            ? 'No migration or schema file in this change.'
+            : `${migrations.filter((m) => !m.unread).length} of ${migrations.length} migration file(s) read. **${serious.length}** change(s) would break the running version or destroy data; ${all.length - serious.length} other finding(s).`,
+        '',
+        // "Read, and nothing found" must never look like "not read". A reader who cannot tell them apart will
+        // take silence for safety, which is the one thing this report must not allow.
+        ...(migrations.length > 0 && all.length === 0 && migrations.every((m) => !m.unread)
+            ? [`All ${migrations.length} were read, and nothing in them breaks the running version, destroys data, blocks writes or holds a long transaction.`]
+            : []),
+        '',
+    ];
+    for (const risk of ORDER) {
+        const group = all.filter((f) => f.risk === risk);
+        if (group.length === 0)
+            continue;
+        lines.push(`## ${TITLES[risk]} (${group.length})`, '');
+        for (const finding of group) {
+            const where = migrations.find((m) => m.findings.includes(finding));
+            lines.push(`- **${finding.what}** — \`${where?.file ?? ''}:${finding.line}\``);
+            lines.push(`  - \`${finding.statement.replace(/`/g, "'")}\``);
+            lines.push(`  - Instead: ${finding.instead}`);
+        }
+        lines.push('');
+    }
+    if (used.length > 0) {
+        lines.push(`## Code that still uses what this takes away (${used.length})`, '', 'Found by searching the repository, so it is evidence rather than proof - a match may be a comment or', 'an unrelated name. Each one is worth opening before this ships.', '');
+        for (const u of used) {
+            lines.push(`- **${u.column ? `${u.table}.${u.column}` : u.table}** is still named in ${u.files.length} file(s): ${u.files.slice(0, 6).join(', ')}${u.files.length > 6 ? `, and ${u.files.length - 6} more` : ''}`);
+        }
+        lines.push('');
+    }
+    const irreversibles = migrations.filter((m) => m.irreversible);
+    if (irreversibles.length > 0) {
+        lines.push(`## Cannot be rolled back by its own down step (${irreversibles.length})`, '', ...irreversibles.map((m) => `- \`${m.file}\``), '');
+    }
+    const unread = migrations.filter((m) => m.unread);
+    if (unread.length > 0) {
+        lines.push(`## Not read (${unread.length})`, '', ...unread.map((m) => `- \`${m.file}\`: ${m.unread}`), '');
+    }
+    lines.push('---', '', 'Every line above is read from the migration itself; no model was called and nothing was guessed.', '', 'What this does not know: how large your tables are, how busy the database is, and therefore how long', 'any of this takes. It says what a statement does - rewrites the table, scans every row, blocks writes -', 'and leaves the duration to the person who knows the data. It also cannot see a deployment order, so', '"breaks the running version" means during a rolling deploy, which is the usual case.');
+    return lines.join(String.fromCharCode(10));
+}
+export function runSchema(cmd) {
+    const files = schemaFiles(cmd);
+    const migrations = files.map((file) => readMigration(cmd.root, file));
+    const used = stillUsed(cmd.root, migrations.flatMap((m) => m.findings));
+    const report = renderSchema(migrations, used);
+    console.log(report);
+    if (cmd.out) {
+        mkdirSync(dirname(resolve(cmd.out)), { recursive: true });
+        writeFileSync(resolve(cmd.out), report + String.fromCharCode(10), 'utf8');
+    }
+    const serious = migrations.flatMap((m) => m.findings).filter((f) => f.risk === 'breaks-old-code' || f.risk === 'destroys-data').length;
+    if (cmd.strict && serious > 0) {
+        console.error(String.fromCharCode(10) + `${serious} change(s) here would break the running version or destroy data.`);
+        process.exitCode = 1;
+    }
+    return { serious };
+}

package/dist/engine/schema/statements.js

@@ -0,0 +1,164 @@
+const CLEAN = (s) => s.replace(/\s+/g, ' ').trim();
+const NAME = String.raw `[\w."\[\]` + "`" + String.raw `]+`;
+/**
+ * What a statement does. Ordered: the first rule that matches decides, so the most serious reading of a
+ * statement wins over a milder one.
+ */
+const RULES = [
+    {
+        find: new RegExp(String.raw `\bDROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?(${NAME})`, 'i'),
+        risk: 'destroys-data',
+        what: (m) => `drops the table ${bare(m[1])} and everything in it`,
+        instead: 'stop writing to it, ship that, confirm nothing reads it, and drop it in a later release - a drop cannot be rolled back by deploying the old code again',
+        table: (m) => bare(m[1]),
+    },
+    {
+        find: new RegExp(String.raw `\bTRUNCATE\s+(?:TABLE\s+)?(${NAME})`, 'i'),
+        risk: 'destroys-data',
+        what: (m) => `empties the table ${bare(m[1])}`,
+        instead: 'delete in batches if this is cleanup, or keep the rows and stop reading them',
+        table: (m) => bare(m[1]),
+    },
+    {
+        find: new RegExp(String.raw `\bALTER\s+TABLE\s+(${NAME})[\s\S]*?\bDROP\s+(?:COLUMN\s+)?(?:IF\s+EXISTS\s+)?(${NAME})`, 'i'),
+        risk: 'breaks-old-code',
+        what: (m) => `drops the column ${bare(m[2])} from ${bare(m[1])}`,
+        instead: 'deploy code that no longer selects or writes the column, then drop it in a later migration. During a rolling deploy the old version is still running and will fail on a column that is gone',
+        table: (m) => bare(m[1]),
+        column: (m) => bare(m[2]),
+    },
+    {
+        find: new RegExp(String.raw `\bALTER\s+TABLE\s+(${NAME})\s+RENAME\s+(?:COLUMN\s+)?(${NAME})\s+TO\s+(${NAME})`, 'i'),
+        risk: 'breaks-old-code',
+        what: (m) => `renames ${bare(m[1])}.${bare(m[2])} to ${bare(m[3])}`,
+        instead: 'add the new column, write to both, move readers over, then remove the old one. A rename is a drop and an add at the same instant, and no deployment is that instant',
+        table: (m) => bare(m[1]),
+        column: (m) => bare(m[2]),
+    },
+    {
+        find: new RegExp(String.raw `\bALTER\s+TABLE\s+(${NAME})\s+RENAME\s+TO\s+(${NAME})`, 'i'),
+        risk: 'breaks-old-code',
+        what: (m) => `renames the table ${bare(m[1])} to ${bare(m[2])}`,
+        instead: 'create a view with the old name, or move readers first. Every query naming the old table fails the moment this runs',
+        table: (m) => bare(m[1]),
+    },
+    {
+        find: new RegExp(String.raw `\bCREATE\s+(?:UNIQUE\s+)?INDEX\s+(?!CONCURRENTLY)(?:IF\s+NOT\s+EXISTS\s+)?(${NAME})?\s*ON\s+(${NAME})`, 'i'),
+        risk: 'locks-writes',
+        what: (m) => `builds an index on ${bare(m[2])} while holding a lock that blocks writes to it`,
+        instead: 'CREATE INDEX CONCURRENTLY (Postgres), or ALGORITHM=INPLACE LOCK=NONE (MySQL). On a large table the plain form blocks every write until it finishes',
+        table: (m) => bare(m[2]),
+    },
+    {
+        find: new RegExp(String.raw `\bALTER\s+TABLE\s+(${NAME})\s+(?:ALTER|MODIFY)\s+(?:COLUMN\s+)?(${NAME})[\s\S]*?\bSET\s+NOT\s+NULL`, 'i'),
+        risk: 'locks-writes',
+        what: (m) => `makes ${bare(m[1])}.${bare(m[2])} NOT NULL, which reads every existing row under a lock`,
+        instead: 'add a CHECK (column IS NOT NULL) NOT VALID, VALIDATE CONSTRAINT separately, then set NOT NULL (Postgres 12+). The direct form scans the whole table while blocking writes',
+        table: (m) => bare(m[1]),
+        column: (m) => bare(m[2]),
+    },
+    {
+        find: new RegExp(String.raw `\bALTER\s+TABLE\s+(${NAME})\s+(?:ALTER|MODIFY|CHANGE)\s+(?:COLUMN\s+)?(${NAME})[\s\S]*?\b(?:TYPE|SET\s+DATA\s+TYPE)\b`, 'i'),
+        risk: 'locks-writes',
+        what: (m) => `changes the type of ${bare(m[1])}.${bare(m[2])}, which usually rewrites the whole table`,
+        instead: 'add a new column of the new type, backfill in batches, switch the readers, then drop the old one. A type change holds an exclusive lock for the rewrite',
+        table: (m) => bare(m[1]),
+        column: (m) => bare(m[2]),
+    },
+    {
+        find: new RegExp(String.raw `\bALTER\s+TABLE\s+(${NAME})\s+ADD\s+(?:CONSTRAINT\s+${NAME}\s+)?FOREIGN\s+KEY(?![\s\S]*NOT\s+VALID)`, 'i'),
+        risk: 'locks-writes',
+        what: (m) => `adds a foreign key to ${bare(m[1])}, which checks every existing row under a lock on both tables`,
+        instead: 'ADD CONSTRAINT ... NOT VALID, then VALIDATE CONSTRAINT, which takes a weaker lock',
+        table: (m) => bare(m[1]),
+    },
+    {
+        find: new RegExp(String.raw `\bALTER\s+TABLE\s+(${NAME})\s+ADD\s+(?:COLUMN\s+)?(${NAME})[\s\S]*?\bNOT\s+NULL\b(?![\s\S]*\bDEFAULT\b)`, 'i'),
+        risk: 'breaks-old-code',
+        what: (m) => `adds ${bare(m[2])} to ${bare(m[1])} as NOT NULL with no default`,
+        instead: 'add it nullable or with a default. Without one, every insert from code that does not know about the column fails - including the version still running during the deploy',
+        table: (m) => bare(m[1]),
+        column: (m) => bare(m[2]),
+    },
+    {
+        find: new RegExp(String.raw `\bALTER\s+TABLE\s+(${NAME})\s+ADD\s+(?:CONSTRAINT\s+${NAME}\s+)?UNIQUE`, 'i'),
+        risk: 'locks-writes',
+        what: (m) => `adds a unique constraint to ${bare(m[1])}, which builds an index under a lock`,
+        instead: 'CREATE UNIQUE INDEX CONCURRENTLY first, then add the constraint using that index',
+        table: (m) => bare(m[1]),
+    },
+    {
+        find: /\bVACUUM\s+FULL\b|\bCLUSTER\b|\bREINDEX\b(?!\s+CONCURRENTLY)/i,
+        risk: 'locks-writes',
+        what: () => 'rewrites the table or index while holding an exclusive lock on it',
+        instead: 'run it in a maintenance window, or use the CONCURRENTLY form where the database offers one',
+    },
+    {
+        find: new RegExp(String.raw `\bUPDATE\s+(${NAME})\s+SET\b(?![\s\S]*\bWHERE\b)`, 'i'),
+        risk: 'slow',
+        what: (m) => `updates every row of ${bare(m[1])} in one statement`,
+        instead: 'update in batches with a WHERE on the primary key. One statement over a large table holds its locks and its transaction open until it finishes',
+        table: (m) => bare(m[1]),
+    },
+    {
+        find: new RegExp(String.raw `\bDELETE\s+FROM\s+(${NAME})\b(?![\s\S]*\bWHERE\b)`, 'i'),
+        risk: 'destroys-data',
+        what: (m) => `deletes every row of ${bare(m[1])}`,
+        instead: 'say what should go with a WHERE, or keep the rows and stop reading them',
+        table: (m) => bare(m[1]),
+    },
+];
+/** `"users"` and `` `users` `` and `[users]` are all the table users. */
+const bare = (name) => name.replace(/["`[\]]/g, '').trim();
+/** The statements of a SQL file, with the line each one starts on and comments removed. */
+export function statementsOf(sql) {
+    // Comments are blanked rather than removed, so every remaining character keeps its original position
+    // and a statement can be reported on the line a reader will actually find it. Deleting them instead
+    // shifted everything upwards: a statement on line 3 was reported as line 1.
+    const blanked = sql
+        .split(String.fromCharCode(10))
+        .map((line) => line.replace(/--.*$/, (m) => ' '.repeat(m.length)))
+        .join(String.fromCharCode(10))
+        // A block comment keeps its newlines so later lines are still numbered correctly.
+        .replace(/\/\*[\s\S]*?\*\//g, (m) => m.split(String.fromCharCode(10)).map((l) => ' '.repeat(l.length)).join(String.fromCharCode(10)));
+    const lineOf = (index) => blanked.slice(0, index).split(String.fromCharCode(10)).length;
+    const out = [];
+    let start = 0;
+    for (let i = 0; i <= blanked.length; i += 1) {
+        if (i < blanked.length && blanked[i] !== ';')
+            continue;
+        const segment = blanked.slice(start, i);
+        const text = CLEAN(segment);
+        if (text) {
+            // Where the statement itself begins, not where the segment did.
+            const offset = segment.length - segment.replace(/^\s+/, '').length;
+            out.push({ text, line: lineOf(start + offset) });
+        }
+        start = i + 1;
+    }
+    return out;
+}
+/** What this one statement does, or nothing when it is not a statement worth a word. */
+export function judge(statement, line) {
+    for (const rule of RULES) {
+        const hit = rule.find.exec(statement);
+        if (!hit)
+            continue;
+        return {
+            statement: statement.slice(0, 300),
+            line,
+            risk: rule.risk,
+            what: rule.what(hit),
+            instead: rule.instead,
+            table: rule.table?.(hit) ?? '',
+            column: rule.column?.(hit) ?? '',
+        };
+    }
+    return null;
+}
+/** Every finding in a SQL migration. */
+export function readSql(sql) {
+    return statementsOf(sql)
+        .map(({ text, line }) => judge(text, line))
+        .filter((f) => f !== null);
+}

package/dist/mcp/server.js

@@ -197,4 +197,23 @@ server.registerTool('which_tests_to_run', {
         return `Nothing changed in ${range}, or that range could not be read here.`;
     return renderPick(chosen.picked, chosen.total, chosen.command, chosen.noHistory);
 }));
+server.registerTool('what_will_this_migration_do', {
+    title: 'What will this migration do to a live database?',
+    description: "Reads the migrations in a change and names what will happen when they run against a live database: a column dropped while the version still running keeps selecting it, a table dropped, an index built under a lock that blocks writes, a NOT NULL added to a populated table, a type change that rewrites it, a foreign key validated against every row, a data migration holding a transaction open, a step that cannot be undone. It also searches the repository for code that still uses the column being taken away. Reads SQL, Django, Rails and Alembic, judges only the forward path, and says plainly when it cannot read a migration. It does not know your table sizes, so it says what a statement does rather than how long it will take.",
+    inputSchema: {
+        project,
+        diff: z.string().optional().describe('A git range, e.g. main...HEAD (the default)'),
+        files: z.array(z.string()).optional().describe('Migration files to read, when they do not come from a git range'),
+    },
+    annotations: readOnly,
+}, ({ project: root, diff, files }) => answer(async () => {
+    if (!isAbsolute(root) || !existsSync(root))
+        throw new Error(`project must be an existing absolute path, got "${root}"`);
+    const { readMigration, renderSchema, schemaFiles, stillUsed } = await import('../engine/schema/schema-command.js');
+    const cmd = { root, diff: diff ?? 'main...HEAD', files };
+    const migrations = schemaFiles(cmd).map((file) => readMigration(root, file));
+    if (migrations.length === 0)
+        return 'No migration or schema file in that change.';
+    return renderSchema(migrations, stillUsed(root, migrations.flatMap((m) => m.findings)));
+}));
 await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tewip-ai",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Tewip finds why each failing test failed - real bug, flaky test, environment, test data or changed selector - for any stack, from the command line, CI, or your editor.",
   "keywords": [
     "test-failures",