@metaobjectsdev/cli 1.0.8 → 1.0.9-rc.1

package/src/commands/migrate.ts

@@ -16,7 +16,6 @@ import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } fro
 import { collectionLoadOptions } from "../lib/collection-load-options.js";
 import { exclusionNotes, importedOption, migrateScopeMismatch } from "../lib/migrate-scope.js";
 import {
-  allowOptionFor,
   isBlockedChangesError,
   isPrimaryKeyChangeError,
   isDeclaredRenameError,
@@ -35,7 +34,6 @@ import {
   readSnapshot,
   writeSnapshot,
   qualifiedDbName,
-  type BlockedChangesError,
   renderD1,
   writeMigrationD1,
   writeMigrationFlyway,
@@ -62,7 +60,7 @@ import {
   type WranglerRunner,
 } from "../lib/wrangler.js";
 import { buildProjectionViews } from "@metaobjectsdev/codegen-ts";
-import { ALLOW_TOKEN_MAP, tokensToAllowOptions, describeChange } from "../lib/allow.js";
+import { tokensToAllowOptions, blockedEntriesFor, blockedHintLines } from "../lib/allow.js";
 import { reportLoadError } from "../lib/load-error.js";
 
 /**
@@ -108,6 +106,9 @@ MIGRATE FLAGS:
                        drop-check,drop-view,drop-view-cascade,
                        adopt-view,nullable-to-not-null,drop-identity-default,
                        drop-unmanaged
+                       drop-column DELETES the column and every value in it. If
+                       the column was RENAMED, use --rename-column instead: it
+                       keeps the data.
                        drop-unmanaged permits dropping a table/view the committed
                        snapshot never contained — one this toolchain never managed.
                        Without it that drop is refused, because the migration it
@@ -436,21 +437,10 @@ async function snapshotAbsentDrops(changes: Change[], snapPath: string): Promise
   return absent;
 }
 
-/** The `--allow` token that unblocks `c`. migrate-ts picks the permission by what blocked the
- *  change (a type change can be blocked by the auto-sequence default it carries), so this only
- *  maps that permission back to its CLI token. */
-function allowFlagFor(c: Change): string {
-  const option = allowOptionFor(c);
-  const token = Object.keys(ALLOW_TOKEN_MAP).find((t) => ALLOW_TOKEN_MAP[t] === option);
-  return token ?? c.kind;
-}
-
-function blockedToEntries(err: BlockedChangesError): BlockedEntry[] {
-  return err.blocked.map((c) => ({
-    kind: c.kind,
-    description: describeChange(c),
-    allowFlag: allowFlagFor(c),
-  }));
+/** Report blocked changes on stderr, one hint per change, rename-first (see `blockedHintLines`). */
+function logBlocked(entries: readonly BlockedEntry[]): void {
+  log.error(`migrate: ${entries.length} destructive change(s) blocked; nothing written`);
+  for (const e of entries) for (const l of blockedHintLines(e)) log.error(`migrate:   ${l}`);
 }
 
 function ambiguousToEntries(amb: AmbiguousChange[]): AmbiguousEntry[] {
@@ -873,7 +863,7 @@ export async function migrateCommand(
         });
       } catch (err) {
         if (isBlockedChangesError(err)) {
-          blocked = blockedToEntries(err);
+          blocked = blockedEntriesFor(err.blocked, diffResult.changes);
           exitCode = 1;
         } else {
           throw err;
@@ -1351,7 +1341,7 @@ export async function runOfflineGenerate(
   logOutOfScope(plan.outOfScope, plan.importedOutOfScope ?? [], fmt);
 
   if (diffResult.blocked.length > 0) {
-    log.error(`migrate: ${diffResult.blocked.length} destructive change(s) blocked; re-run with --allow <tokens>`);
+    logBlocked(blockedEntriesFor(diffResult.blocked, diffResult.changes));
     return 1;
   }
   if (diffResult.changes.length === 0) {
@@ -1631,10 +1621,7 @@ async function runD1Migrate(
     emitResult = renderD1(diffResult.changes, expected, actual.meta, actual);
   } catch (err) {
     if (isBlockedChangesError(err)) {
-      const entries = blockedToEntries(err);
-      for (const e of entries) {
-        log.error(`migrate: blocked '${e.kind}' on ${e.description} (allow with --allow ${e.allowFlag})`);
-      }
+      logBlocked(blockedEntriesFor(err.blocked, diffResult.changes));
       return 1;
     }
     throw err;

package/src/commands/verify.ts

@@ -7,7 +7,7 @@
 // silently break a prompt" guarantee, enforced at the last fixed point before
 // the text ships. Required-slot misses are warnings (don't fail the build).
 
-import { join, resolve as resolvePath } from "node:path";
+import { join, relative, resolve as resolvePath } from "node:path";
 import { parseVerifyArgs, type MigrateFlags } from "../lib/args.js";
 import { log } from "../lib/log.js";
 import { emitStructured, type OutputFormat } from "../lib/format.js";
@@ -15,15 +15,17 @@ import {
   antiPatternRows, missingBaseUrlRows, removedPropRows, ranSection, skippedSection, warnCapped,
   type AdvisoryDiagnosticRow, type AdvisoryFindingRow, type AdvisorySection,
   libraryPrefixRows,
+  unindexedFkRows,
 } from "../lib/advisory.js";
 import { scanForUnprovenancedLibraryPrefix } from "../lib/library-prefix-advisory.js";
+import { scanForUnindexedForeignKeys, type UnindexedFkFinding } from "../lib/fk-index-advisory.js";
 import { warnIfAgentContextStale } from "../lib/agent-context-staleness.js";
 import { warnIfManifestIgnored } from "../lib/manifest-ignored-check.js";
 import { scanSourceForAntiPatterns } from "../lib/anti-patterns.js";
 import { scanForMissingBaseUrl, type BaseUrlFinding } from "../lib/base-url-advisory.js";
 import { scanForRemovedProps, type RemovedPropFinding } from "../lib/removed-prop-advisory.js";
 import { replayRemedy } from "../lib/replay-remedy.js";
-import { FileProvider } from "../lib/file-provider.js";
+import { FileProvider, mustacheTagLine } from "../lib/file-provider.js";
 import { derivePayloadFieldTree } from "../lib/payload-field-tree.js";
 import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenCollection, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
 import { collectionLoadOptions } from "../lib/collection-load-options.js";
@@ -396,22 +398,33 @@ export async function verifyCommand(
     replayExit,
   );
 
+  const gates: VerifyGateRow[] = [
+    { gate: "templates", ran: runTemplates, ok: templateExit === 0 },
+    // The schema gate decides internally whether it is selected (--db, or
+    // --dialect d1), so "ran" is read off the same signals rather than
+    // restated: a payload that claims a gate ran when it did not is the
+    // failure mode this whole change exists to remove.
+    { gate: "schema", ran: ranSchemaGate, ok: schemaExit === 0 },
+    { gate: "codegen", ran: runCodegen, ok: codegenExit === 0 },
+    { gate: "docs", ran: runDocs, ok: docsExit === 0 },
+    { gate: "deps", ran: runDeps, ok: depsExit === 0 },
+    { gate: "requirements", ran: true, ok: requirementExit === 0 },
+    { gate: "replay", ran: flags.replay || flags.replaySnapshot, ok: replayExit === 0 },
+  ];
+
+  // Naming a gate runs ONLY the gates named (ADR-0021 D2), so `verify --codegen --db <url>`
+  // exits 0 without ever looking at the prompt templates. A green partial run must not read
+  // as a full one: say which gates did not run and how to select each. A bare `verify` has
+  // already said so in its default note above.
+  if (flags.anyExplicit) {
+    const note = notRunNote(gates);
+    if (note !== undefined) say(note);
+  }
+
   if (structured) {
     emitStructured(
       buildVerifyPayload({
-        gates: [
-          { gate: "templates", ran: runTemplates, ok: templateExit === 0 },
-          // The schema gate decides internally whether it is selected (--db, or
-          // --dialect d1), so "ran" is read off the same signals rather than
-          // restated: a payload that claims a gate ran when it did not is the
-          // failure mode this whole change exists to remove.
-          { gate: "schema", ran: ranSchemaGate, ok: schemaExit === 0 },
-          { gate: "codegen", ran: runCodegen, ok: codegenExit === 0 },
-          { gate: "docs", ran: runDocs, ok: docsExit === 0 },
-          { gate: "deps", ran: runDeps, ok: depsExit === 0 },
-          { gate: "requirements", ran: true, ok: requirementExit === 0 },
-          { gate: "replay", ran: flags.replay || flags.replaySnapshot, ok: replayExit === 0 },
-        ],
+        gates,
         exitCode,
         requirements: requirementSection,
         requirementCounts,
@@ -839,11 +852,28 @@ export async function verifyCommand(
       // Same discipline as its siblings: an advisory scan never breaks verify.
     }
 
+    // Foreign keys migrate emits with no index on the referencing columns. Advisory: an
+    // automatic index would propose a migration to every existing adopter, so this names
+    // each one and says how to declare it (`index.lookup`) instead. Read off the SAME
+    // expected schema `meta migrate` builds, so "covered" means covered in its DDL.
+    let unindexedFks: UnindexedFkFinding[] = [];
+    try {
+      unindexedFks = scanForUnindexedForeignKeys(root, {
+        dialect: flags.dialect ?? forgeConfig?.dialect ?? "postgres",
+        columnNamingStrategy: forgeConfig?.columnNamingStrategy ?? "snake_case",
+        skip: collection.imported,
+      });
+    } catch {
+      // Same discipline as its siblings: an advisory scan never breaks verify. A model the
+      // schema builder refuses is migrate's to report, with its own message.
+    }
+
     antiPatternSection = ranSection([
       ...antiPatternRows(findings),
       ...missingBaseUrlRows(baseUrl),
       ...removedPropRows(removedProps),
       ...libraryPrefixRows(libraryPrefix),
+      ...unindexedFkRows(unindexedFks),
     ]);
     if (findings.length > 0) {
       log.warn(
@@ -866,6 +896,13 @@ export async function verifyCommand(
       );
       warnCapped(removedProps.map((f) => `  ${f.message}`), flags.limit, { structured });
     }
+    if (unindexedFks.length > 0) {
+      log.warn(
+        `meta verify — ${unindexedFks.length} foreign key(s) with no index on the referencing ` +
+          `column(s) (advisory — does not fail the build):`,
+      );
+      warnCapped(unindexedFks.map((f) => `  ${f.message}`), flags.limit, { structured });
+    }
     if (libraryPrefix.length > 0) {
       log.warn(
         `meta verify — ${libraryPrefix.length} node(s) declared under "metaobjects::" with ` +
@@ -987,12 +1024,22 @@ export async function verifyCommand(
         }
         const drift = verify(text, fieldTree, { provider, requiredSlots, requiredTags });
         anyBodyChecked = true;
+        // WHERE to look. The {code, path} diagnostic is pinned by the cross-port verify
+        // corpus, so the location is added here, in the display only: the body's file
+        // (project-relative) and the line the variable's tag first appears on, when the
+        // tag is in this body rather than a partial.
+        const bodyFile = provider.pathOf(ref);
+        const where = (varPath: string): string => {
+          if (bodyFile === undefined) return "";
+          const line = mustacheTagLine(text, varPath);
+          return ` (${relative(projectRoot, bodyFile)}${line !== undefined ? `:${line}` : ""})`;
+        };
         for (const e of drift) {
           if (e.code === ERR_REQUIRED_SLOT_UNUSED) {
-            log.warn(`[${tmpl.name}] (${label}) ${e.code}: ${e.path}`);
+            log.warn(`[${tmpl.name}] (${label}) ${e.code}: ${e.path}${where(e.path)}`);
             warnCount++;
           } else {
-            log.error(`[${tmpl.name}] (${label}) ${e.code}: ${e.path}`);
+            log.error(`[${tmpl.name}] (${label}) ${e.code}: ${e.path}${where(e.path)}`);
             errorCount++;
             anyErrorHere = true;
           }
@@ -1617,6 +1664,30 @@ interface VerifyGateRow {
   ok: boolean;
 }
 
+/** The flag that selects each gate, for the "not run" note. `requirements` always runs. */
+const GATE_SELECTOR: Record<string, string> = {
+  templates: "--templates",
+  schema: "--db <url>",
+  codegen: "--codegen",
+  docs: "--docs",
+  deps: "--deps",
+  replay: "--replay",
+};
+
+/**
+ * One line naming every gate this run did NOT run, each with the flag that selects it —
+ * undefined when every gate ran. Exported for its test.
+ */
+export function notRunNote(gates: readonly VerifyGateRow[]): string | undefined {
+  const skipped = gates.filter((g) => !g.ran);
+  if (skipped.length === 0) return undefined;
+  const named = skipped.map((g) => {
+    const flag = GATE_SELECTOR[g.gate];
+    return flag !== undefined ? `${g.gate} (${flag})` : g.gate;
+  });
+  return `meta verify — not run: ${named.join(", ")}`;
+}
+
 /**
  * Format one `Diagnostic` as a printed TEXT line. Named `formatDiagnostic`, not
  * `fmt`: `fmt` is this command's OUTPUT FORMAT parameter, and a shadow of it

package/src/index.ts

@@ -142,6 +142,8 @@ MIGRATE FLAGS:
                         drop-column,drop-table,type-change,drop-index,drop-fk,
                         drop-check,drop-view,drop-view-cascade,
                         adopt-view,nullable-to-not-null,drop-identity-default
+                        drop-column DELETES the column's data; for a renamed
+                        column use --rename-column, which keeps it
   --on-ambiguous abort|rename|drop-add   Default abort
   --rename-table [schema.]old=new         Declare a table rename (repeatable)
   --rename-column [schema.]table.old=new  Declare a column rename; keeps its data (repeatable)
@@ -151,8 +153,7 @@ MIGRATE FLAGS:
   --yes                 Skip the --remote --apply confirmation pause
   --dry-run             Print SQL to stdout, don't write
 
-Other commands (ingest, mcp, serve, install-hooks, audit, capture, promote)
-ship in later sub-projects. See https://metaobjects.com for docs.
+See https://metaobjects.com for docs.
 `;
 
 /** Focused per-subcommand usage slices shown by `<cmd> --help`. */
@@ -323,6 +324,8 @@ FLAGS:
 A bare 'meta verify' also runs an ADVISORY anti-pattern pass: it scans your authored
 source for hand-rolled aggregates, money-as-float, and CHECK-IN enums and points you
 at the construct that models them (origin.aggregate / field.currency / field.enum).
+The same pass names every foreign key with no index on its referencing column(s)
+and the index.lookup that would cover it (migrate never adds one on its own).
 Warnings only — it never fails the build. Opt out with --no-antipatterns or
 META_NO_ANTIPATTERNS=1.
 

package/src/lib/advisory.ts

@@ -163,6 +163,23 @@ export function libraryPrefixRows(
   }));
 }
 
+/**
+ * Unindexed foreign keys in the same row shape. `construct` is `<entity FQN>.<reference>`,
+ * the node the author edits to declare the index. There is no line: the finding is about the
+ * loaded model, which does not carry source positions.
+ */
+export function unindexedFkRows(
+  findings: readonly { file: string; construct: string; message: string }[],
+): AdvisoryFindingRow[] {
+  return findings.map((f) => ({
+    file: f.file,
+    line: 0,
+    rule: "unindexed-foreign-key",
+    construct: f.construct,
+    message: f.message,
+  }));
+}
+
 // ---------------------------------------------------------------------------
 // text output
 // ---------------------------------------------------------------------------

package/src/lib/allow.ts

@@ -2,7 +2,9 @@
 // both `meta migrate` and `meta verify --db`. Keeping a single copy avoids the
 // two commands drifting on which `--allow` tokens exist or how a change reads.
 
-import type { AllowOptions, Change } from "@metaobjectsdev/migrate-ts";
+import { allowOptionFor, suggestColumnRenames } from "@metaobjectsdev/migrate-ts";
+import type { AllowOptions, Change, ColumnRenameSuggestion } from "@metaobjectsdev/migrate-ts";
+import type { BlockedEntry } from "./output.js";
 
 // Map CLI allow tokens → migrate-ts AllowOptions field names.
 // Exported (not just module-local) so allow-tokens-pinned.test.ts can pin its
@@ -83,3 +85,57 @@ export function describeChange(c: Change): string {
     default: return JSON.stringify(c);
   }
 }
+
+/** The `--allow` token that unblocks `c`. migrate-ts picks the permission by what blocked the
+ *  change (a type change can be blocked by the auto-sequence default it carries), so this only
+ *  maps that permission back to its CLI token. */
+export function allowFlagFor(c: Change): string {
+  const option = allowOptionFor(c);
+  const token = Object.keys(ALLOW_TOKEN_MAP).find((t) => ALLOW_TOKEN_MAP[t] === option);
+  return token ?? c.kind;
+}
+
+/** `--rename-column [schema.]table.old=new`, spelled with the pair's real names. */
+export function renameColumnFlag(r: ColumnRenameSuggestion): string {
+  return `--rename-column ${r.schema !== undefined ? `${r.schema}.` : ""}${r.table}.${r.from}=${r.to}`;
+}
+
+/**
+ * One reportable entry per blocked change. `changes` is the whole diff the blocked ones came
+ * from: a blocked drop-column that pairs with an add-column in the same table may be a column
+ * the author RENAMED, and `--allow drop-column` would delete its data — so that entry carries
+ * the declared-rename flag, which every renderer prints FIRST.
+ */
+export function blockedEntriesFor(blocked: readonly Change[], changes: readonly Change[]): BlockedEntry[] {
+  const renames = suggestColumnRenames(changes);
+  return blocked.map((c) => {
+    const entry: BlockedEntry = { kind: c.kind, description: describeChange(c), allowFlag: allowFlagFor(c) };
+    if (c.kind !== "drop-column") return entry;
+    const r = renames.find((x) => x.from === c.column && x.table === c.table && x.schema === c.schema);
+    if (r === undefined) return entry;
+    return {
+      ...entry,
+      renameFlag: renameColumnFlag(r),
+      renameTo: `${r.table}.${r.to}`,
+      ...(r.shapeChange !== undefined ? { shapeChange: r.shapeChange } : {}),
+    };
+  });
+}
+
+/**
+ * The hint for one blocked entry, as the lines a renderer prints in order. A rename-pairable
+ * drop leads with the declared rename and names `--allow drop-column` as what deletes the data;
+ * every other entry is the one-line `--allow` hint it always was.
+ */
+export function blockedHintLines(e: BlockedEntry): string[] {
+  if (e.renameFlag === undefined) {
+    return [`blocked '${e.kind}' on ${e.description} (allow with --allow ${e.allowFlag})`];
+  }
+  const shape = e.shapeChange !== undefined
+    ? ` (its ${e.shapeChange} also changes: rename first with the old shape still declared, then change the shape in a second migration)`
+    : "";
+  return [
+    `${e.description} is dropped and ${e.renameTo ?? "a column"} is added in the same table. If it was renamed, keep its data: re-run with ${e.renameFlag}${shape}`,
+    `  (--allow ${e.allowFlag} instead DELETES ${e.description} and all its data)`,
+  ];
+}

package/src/lib/catalog-listing.ts

@@ -334,6 +334,11 @@ export const REFERENCE_HELPER_NOTE: readonly string[] = [
   "render) is not a generator and is not listed here.",
 ];
 
+/** The footer line explaining the `package-only` row mark. */
+export const PACKAGE_ONLY_NOTE =
+  "package-only = no reference template ships for it yet, so `meta eject` cannot copy it; " +
+  "import it from its package instead.";
+
 /** The human rendering: grouped by layer, because layer is the axis you select by. */
 export function renderCatalogText(rows: CatalogRow[], probed: boolean): string {
   const lines: string[] = [];
@@ -352,6 +357,7 @@ export function renderCatalogText(rows: CatalogRow[], probed: boolean): string {
     const marks: string[] = [];
     if (r.framework !== undefined) marks.push(r.framework);
     if (r.tier === "neutral") marks.push("neutral");
+    if (!r.source.ejectable) marks.push("package-only");
     if (r.project?.wired) marks.push("WIRED");
     if (r.source.owned) marks.push("owned");
     if (probed && r.project?.wouldEmit !== null && r.project?.wouldEmit !== undefined) {
@@ -372,6 +378,7 @@ export function renderCatalogText(rows: CatalogRow[], probed: boolean): string {
   lines.push("");
   lines.push("`meta eject <name...>` copies a generator into codegen/generators/ and prints");
   lines.push("the import to add, the entry to wire, and what to install.");
+  if (generators.some((r) => !r.source.ejectable)) lines.push(PACKAGE_ONLY_NOTE);
   if (!probed) {
     lines.push("Add --probe to see how many files each would emit for YOUR model.");
   }

package/src/lib/file-provider.ts

@@ -16,13 +16,23 @@ export class FileProvider implements Provider {
   constructor(private readonly baseDir: string) {}
 
   resolve(ref: string): string | undefined {
+    const path = this.pathOf(ref);
+    return path === undefined ? undefined : readFileSync(path, "utf8");
+  }
+
+  /**
+   * The file `ref` resolves to, or undefined. `resolve` reads exactly this file, so a
+   * diagnostic that names it names the body that was checked.
+   */
+  pathOf(ref: string): string | undefined {
     // `group/source` → <baseDir>/group/source<ext>; node:path.join normalizes
     // the embedded "/" separators for the host OS.
     for (const ext of EXTENSIONS) {
       const path = join(this.baseDir, ref) + ext;
       if (existsSync(path)) {
         try {
-          return readFileSync(path, "utf8");
+          readFileSync(path, "utf8");
+          return path;
         } catch {
           // unreadable — fall through and try the next candidate
         }
@@ -31,3 +41,19 @@ export class FileProvider implements Provider {
     return undefined;
   }
 }
+
+/**
+ * The 1-based line of the first mustache tag naming `path` in `text` — `{{path}}`,
+ * `{{{path}}}`, `{{& path}}`, `{{#path}}`, `{{^path}}` — trying the full dotted path and then
+ * its head segment (a dotted drift is reported on the path, but the tag may open a section on
+ * the head). Undefined when no tag matches, e.g. the variable lives in a partial.
+ */
+export function mustacheTagLine(text: string, path: string): number | undefined {
+  const esc = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const head = path.split(".")[0] ?? path;
+  for (const name of path === head ? [path] : [path, head]) {
+    const m = new RegExp(`\\{\\{\\{?\\s*[#^&]?\\s*${esc(name)}\\s*\\}`).exec(text);
+    if (m !== null) return text.slice(0, m.index).split("\n").length;
+  }
+  return undefined;
+}

package/src/lib/fk-index-advisory.ts

@@ -0,0 +1,112 @@
+// Foreign keys with no index covering their columns — an advisory authoring lint.
+//
+// `meta migrate` emits a FOREIGN KEY constraint for every enforced `identity.reference`
+// and no index on its columns: neither Postgres nor SQLite indexes the referencing side
+// of a foreign key. Every join from the parent, and every ON DELETE cascade / set-null /
+// restrict check from it, then scans the child table. Generating the index automatically
+// would propose a migration to every existing adopter the release it shipped, so this is
+// advice, never a gate: it names each such key and says how to declare the index.
+//
+// Coverage is read off the EXPECTED SCHEMA migrate itself builds (primary key, every
+// `identity.secondary`, every `index.lookup`, every `@unique` field), not re-derived from
+// the metadata — so "covered" means covered in the DDL migrate would emit. An index covers
+// a key when its leading columns are exactly the key's columns, in any order. Expression
+// indexes are not counted; partial ones are (bias to under-flagging).
+
+import {
+  INDEX_SUBTYPE_LOOKUP,
+  TYPE_INDEX,
+  TYPE_SUBTYPE_SEPARATOR,
+} from "@metaobjectsdev/metadata/constants";
+import {
+  isMetaObject,
+  resolveColumnName,
+  type ColumnNamingStrategy,
+  type MetaData,
+} from "@metaobjectsdev/metadata";
+import {
+  buildExpectedSchemaWithProvenance,
+  qualifiedDbName,
+  type Dialect,
+  type TableDescriptor,
+} from "@metaobjectsdev/migrate-ts";
+
+export interface UnindexedFkFinding {
+  /** The metadata file declaring the entity ("" when the loader recorded none). */
+  file: string;
+  /** `<entity FQN>.<reference name>`. */
+  construct: string;
+  message: string;
+}
+
+export interface UnindexedFkOptions {
+  dialect: Dialect;
+  columnNamingStrategy: ColumnNamingStrategy;
+  /** Skip an entity by FQN — imported (dependency) metadata is not the adopter's to index. */
+  skip?: (fqn: string) => boolean;
+}
+
+const INDEX_LOOKUP = `${TYPE_INDEX}${TYPE_SUBTYPE_SEPARATOR}${INDEX_SUBTYPE_LOOKUP}`;
+
+function covered(table: TableDescriptor, fkColumns: readonly string[]): boolean {
+  const want = new Set(fkColumns);
+  const prefixes = [
+    table.primaryKey,
+    ...table.indexes.filter((i) => i.expr === undefined).map((i) => i.columns),
+  ];
+  return prefixes.some((cols) =>
+    cols.length >= want.size && cols.slice(0, want.size).every((c) => want.has(c)));
+}
+
+function pascal(s: string): string {
+  return s.length === 0 ? s : s[0]!.toUpperCase() + s.slice(1);
+}
+
+export function scanForUnindexedForeignKeys(root: MetaData, opts: UnindexedFkOptions): UnindexedFkFinding[] {
+  const { snapshot, provenance } = buildExpectedSchemaWithProvenance(root, {
+    dialect: opts.dialect,
+    columnNamingStrategy: opts.columnNamingStrategy,
+  });
+  // ADR-0039: effective children — resolve rather than rely on root being unextended.
+  const objectsByFqn = new Map(
+    root.children().filter(isMetaObject).map((o) => [o.resolutionKey(), o] as const),
+  );
+
+  const out: UnindexedFkFinding[] = [];
+  for (const table of snapshot.tables) {
+    const fqn = provenance.get(qualifiedDbName(table));
+    if (fqn === undefined || opts.skip?.(fqn) === true) continue;
+    const entity = objectsByFqn.get(fqn);
+    if (entity === undefined) continue;
+    const files = "files" in entity.source ? entity.source.files : [];
+    // A node a shipped library contributed is the library's design, not the adopter's.
+    if (files.some((f) => f.startsWith("library:"))) continue;
+
+    for (const fk of table.foreignKeys) {
+      if (covered(table, fk.columns)) continue;
+      // Name the key in the author's terms: the reference and its FIELDS, not columns.
+      // A TPH subtype's reference folds into its base's table and is not on `entity`;
+      // it is then reported by column, which is still enough to act on.
+      const ref = entity.referenceIdentities().find((r) => {
+        const cols = r.fields.map((f) => {
+          const field = entity.fields().find((x) => x.name === f);
+          return field !== undefined ? resolveColumnName(field, opts.columnNamingStrategy) : f;
+        });
+        return cols.length === fk.columns.length && cols.every((c, i) => c === fk.columns[i]);
+      });
+      const fields = ref !== undefined ? ref.fields : fk.columns;
+      const label = ref !== undefined ? `${entity.name}.${ref.name}` : `${entity.name} (${fk.name})`;
+      const indexName = `by${fields.map(pascal).join("")}`;
+      const fieldList = fields.length === 1 ? fields[0]! : `[${fields.join(", ")}]`;
+      out.push({
+        file: files[0] ?? "",
+        construct: `${fqn}.${ref?.name ?? fk.name}`,
+        message:
+          `${label}: foreign key (${fields.join(", ")}) → ${fk.refTable} has no index covering it, ` +
+          `so joins from ${fk.refTable} and its ON DELETE checks scan ${table.name}. ` +
+          `Declare one on ${entity.name}: ${INDEX_LOOKUP}: { name: ${indexName}, fields: ${fieldList} }`,
+      });
+    }
+  }
+  return out;
+}

package/src/lib/output.ts

@@ -6,6 +6,7 @@
 import type { Dialect } from "./kysely.js";
 import { toonEncode } from "./format.js";
 import { skippedSection, type AdvisoryFindingRow, type AdvisorySection } from "./advisory.js";
+import { blockedHintLines } from "./allow.js";
 
 export interface FormatOptions {
   isTTY: boolean;
@@ -154,6 +155,15 @@ export interface BlockedEntry {
   kind: string;
   description: string;
   allowFlag: string;
+  /**
+   * Set on a blocked drop-column that pairs with an add-column in the same table: the exact
+   * `--rename-column` flag that keeps the data. Printed BEFORE `--allow`, which deletes it.
+   */
+  renameFlag?: string;
+  /** `table.column` the dropped column may have been renamed to. */
+  renameTo?: string;
+  /** The shape difference that forces the rename and the reshape into two migrations. */
+  shapeChange?: string;
 }
 
 export interface AmbiguousEntry {
@@ -204,9 +214,14 @@ export function formatMigrateResult(result: MigrateResultShape, _opts: FormatOpt
   }
 
   if (result.blocked.length > 0) {
-    lines.push("  Blocked (re-run with --allow):");
+    const anyRename = result.blocked.some((b) => b.renameFlag !== undefined);
+    lines.push(anyRename ? "  Blocked (re-run with the flag shown):" : "  Blocked (re-run with --allow):");
     for (const b of result.blocked) {
-      lines.push(`    ${b.kind}  ${b.description}  (--allow ${b.allowFlag})`);
+      if (b.renameFlag === undefined) {
+        lines.push(`    ${b.kind}  ${b.description}  (--allow ${b.allowFlag})`);
+      } else {
+        for (const l of blockedHintLines(b)) lines.push(`    ${l}`);
+      }
     }
     lines.push("");
   }
@@ -328,8 +343,15 @@ export function migrateResultToData(result: MigrateResultShape): {
   let help: string[];
   if (isBlocked) {
     summary = `${changeSummary}; not applied`;
+    // A rename-pairable drop leads: its `--allow` would delete the data the rename keeps.
+    const renames = result.blocked.filter((b) => b.renameFlag !== undefined);
+    const others = result.blocked.filter((b) => b.renameFlag === undefined);
     help = [
-      ...result.blocked.map((b) => `re-run with --allow ${b.allowFlag} to apply: ${b.description}`),
+      ...renames.map((b) =>
+        `if ${b.description} was renamed to ${b.renameTo ?? "the added column"}, re-run with ${b.renameFlag} to keep its data` +
+        `${b.shapeChange !== undefined ? ` (its ${b.shapeChange} also changes: rename first, reshape in a second migration)` : ""}` +
+        `; --allow ${b.allowFlag} instead DELETES the column and all its data`),
+      ...others.map((b) => `re-run with --allow ${b.allowFlag} to apply: ${b.description}`),
       ...result.ambiguous.map((a) => `re-run with --on-ambiguous to resolve: ${a.hint}`),
     ];
   } else if (result.dryRun) {