@metaobjectsdev/cli 0.24.4 → 0.25.0

package/src/index.ts

@@ -1,13 +1,24 @@
 import { resolve } from "node:path";
 import { log } from "./lib/log.js";
 import { cliVersion } from "./lib/version.js";
-import { resolveFormat, isValidFormat, VALID_FORMATS } from "./lib/format.js";
+import { resolveFormat, isValidFormat, VALID_FORMATS, type OutputFormat } from "./lib/format.js";
 import { resolveCollection } from "@metaobjectsdev/sdk";
 export { defineConfig } from "@metaobjectsdev/codegen-ts";
 export type { MetaobjectsGenConfig } from "@metaobjectsdev/codegen-ts";
 
 const VERSION = cliVersion();
 
+/**
+ * The commands that actually honor the global `--format`. Everything else prints
+ * text whatever is passed.
+ *
+ * This list exists because the flag was advertised globally and threaded to two
+ * commands: `meta verify --format json` parsed, validated, exited 0 and printed
+ * human text. It is named ONCE and used by both the warning below and the help
+ * text above, so the two cannot drift apart.
+ */
+const FORMAT_AWARE_COMMANDS: readonly string[] = ["gen", "verify", "migrate", "types"];
+
 const HELP_TEXT = `meta — MetaObjects CLI (v${VERSION})
 
 USAGE:
@@ -19,10 +30,12 @@ COMMANDS:
   init --config-only    Write only .metaobjects/config.json — for a Maven- or pip-rooted project
   agent-docs            Scaffold only the agent-context (.metaobjects/ + .claude/skills/) — canonical redirect target for all language ports
   gen [<entity>...]     Codegen TS targets from your declared metadata
+  eject <generator>     Copy a reference generator into codegen/generators/ to own it (any time after init)
+  eject --list          List every ejectable generator name, grouped by package
   types [query]         Search the metadata vocabulary (types, subtypes, @attrs) by name or description
   export                Flatten loaded metadata to one canonical JSON artifact
   docs [<project-root>] --out <dir>  Generate neutral metadata documentation (entity + template pages; --site for HTML site)
-  verify                Drift gate — subverbs: --templates / --db / --codegen (bare = --templates)
+  verify                Drift gate — subverbs: --templates / --db / --codegen / --docs (bare = --templates)
   upgrade               Rewrite retired metadata vocabulary (previews; --apply writes)
   prompt-snapshot       Snapshot rendered template.* output; --check gates drift
   migrate               Diff metadata vs live DB; emit migration SQL files
@@ -31,10 +44,21 @@ COMMANDS:
 
 GLOBAL OPTIONS:
   --cwd <path>, -C <path>   Run as if launched from <path> (default: current directory)
-  --format <toon|json|text> Output format (default: toon on non-TTY, text on TTY)
+  --format <toon|json|text> Output format (default: toon on non-TTY, text on TTY).
+                            Honored by ${FORMAT_AWARE_COMMANDS.join(", ")}; every other
+                            command prints text and says so if you pass it.
+                            \`types\` is the one exception to the default: it prints TEXT
+                            unless you ask for a format, on a TTY or not, because its
+                            text output is already the terse agent-facing rendering.
+                            A structured payload is never truncated — --limit is a
+                            TEXT-only display cap.
 
 GEN FLAGS:
   --dry-run             Compute and print, don't write
+  --no-antipatterns     Suppress the advisory "hand-rolled what MetaObjects can model" pass
+  --limit <n|all>       How many advisory lines TEXT output prints before it truncates
+                        (default 20). Never applies to --format toon/json, which
+                        carry every finding.
   <entity> [<entity>]   Positional filter on entity names
   (outDir, dialect, dbImport, extStyle are read from metaobjects.config.ts)
 
@@ -53,6 +77,11 @@ VERIFY FLAGS (ADR-0021 D2 — explicit subverbs; combine any; exit 1 on ANY drif
   --templates           Template/prompt {{field}}↔payload drift (the bare-verify default)
   --codegen             Codegen drift — regenerate to a temp dir and diff the committed
                         output (config outDir/targets). Needs metaobjects.config.ts; exit 2 if absent.
+  --docs                Docs drift — run 'meta docs' into a temp dir and diff the committed
+                        docs tree (docs.outDir). Reports a page that changed or that a fresh
+                        run would emit; never reports an extra file, because docs.outDir
+                        holds hand-written documentation MetaObjects did not write.
+                        Needs metaobjects.config.ts; exit 2 if absent.
   --db <url>            Schema drift — live DB URL enables the schema-drift gate.
                         Supports: file:, libsql:, postgres:, postgresql:. Omit to skip.
                         D1 has no URL — use --dialect d1 / --d1 <binding> instead.
@@ -66,6 +95,10 @@ VERIFY FLAGS (ADR-0021 D2 — explicit subverbs; combine any; exit 1 on ANY drif
                         the ONLY way to verify the actual deployed D1 database
   --no-antipatterns     Suppress the advisory "you hand-rolled what MetaObjects can
                         model" pass (aggregate/currency/enum hints; warnings only)
+  --no-requirement-lint Suppress the advisory requirement AUTHORING lint (not the gate)
+  --limit <n|all>       How many advisory lines TEXT output prints per section before
+                        it truncates (default 20). Never applies to --format
+                        toon/json, which carry every finding and every diagnostic.
 
 PROMPT-SNAPSHOT FLAGS:
   --check               Compare against committed snapshots; exit 1 on drift (CI gate)
@@ -103,6 +136,8 @@ USAGE:
 FLAGS:
   --dry-run             Compute and print, don't write
   --no-antipatterns     Suppress the advisory "hand-rolled what MetaObjects can model" pass
+  --limit <n|all>       Advisory lines TEXT output prints before truncating (default 20)
+  --format <toon|json|text>   Output format (global flag; default toon off-TTY)
   <entity> [<entity>]   Positional filter on entity names
   --help, -h            Print this help
 
@@ -112,7 +147,30 @@ and points you at the construct that models them (origin.aggregate / field.curre
 field.enum). Warnings only — it never fails the build. Opt out with --no-antipatterns
 or META_NO_ANTIPATTERNS=1.
 
+Text output caps that list at --limit lines (default 20) and says how many it held
+back. --format toon / --format json carry EVERY finding in the payload's
+antiPatterns block, uncapped — --limit is a display cap for a terminal, never a
+limit on the machine-readable result.
+
 NOTE: outDir, dialect, dbImport, extStyle are read from metaobjects.config.ts
+`,
+  eject: `meta eject — copy a reference generator into your repo so you own it
+
+USAGE:
+  meta eject <name>      Copy generator <name> into codegen/generators/<name>.ts
+  meta eject --list      List every ejectable generator name, grouped by package
+
+FLAGS:
+  --list                 List ejectable generators instead of copying one
+  --force                Overwrite an already-ejected file (default: never clobber)
+  --help, -h             Print this help
+
+\`meta init\` copies five generators (entity, queries, routes, barrel, names) into
+codegen/generators/ automatically (ADR-0034 scaffold-and-own). \`meta eject\` is
+the same operation for ANY generator — one you skipped at init time, a UI-tier
+generator like form/hooks/grid, or one a package gains later. It prints the
+import line to paste into metaobjects.config.ts, and it never overwrites a
+file you already own unless you pass --force.
 `,
   verify: `meta verify — drift gate (templates / DB schema / codegen / migration replay)
 
@@ -123,6 +181,8 @@ FLAGS:
   --templates           Template/prompt {{field}}↔payload drift (default when bare)
   --codegen             Codegen drift — regenerate to temp dir and diff committed output
                         Needs metaobjects.config.ts; exit 2 if absent.
+  --docs                Docs drift — run 'meta docs' to a temp dir and diff docs.outDir
+                        Needs metaobjects.config.ts; exit 2 if absent.
   --db <url>            Schema drift — live DB URL enables the schema-drift gate.
                         Supports: file:, libsql:, postgres:, postgresql:
                         D1 has no URL — use --dialect d1 / --d1 <binding> instead.
@@ -146,6 +206,14 @@ FLAGS:
                         the ONLY way to verify the actual deployed D1 database
   --no-antipatterns     Suppress the advisory "hand-rolled what MetaObjects can model" pass
   --no-requirement-lint Suppress the advisory requirement AUTHORING lint (not the gate)
+  --limit <n|all>       Advisory lines TEXT output prints PER SECTION before truncating
+                        (default 20; per-section so the authoring lint can never push
+                        the gate's own warnings off the end)
+  --format <toon|json|text>   Output format (global flag; default toon off-TTY).
+                        Emits one machine-readable document on stdout — every gate's
+                        verdict, every advisory finding, every requirement diagnostic,
+                        UNCAPPED — and moves narration to stderr so the payload parses.
+                        What it does NOT carry is listed in its own notRepresented[].
   --help, -h            Print this help
 
 A bare 'meta verify' also runs an ADVISORY anti-pattern pass: it scans your authored
@@ -186,6 +254,11 @@ FLAGS:
   --api                 Emit the markdown api surface (generated SDK reference)
   --requirements        Emit the declared requirement ledger (requirements.md + .toon).
                         Emits nothing when the project declares no requirement.* node.
+  --agent               Emit the agent surface — agent/schema.md (the physical schema),
+                        agent/ui.md (the generated forms and grids) and
+                        agent/requirements.md (the ledger plus a claimed-node index).
+                        Needs metaobjects.config.ts (the dialect and physical names come
+                        from it); each page is skipped when its tier has nothing to describe.
   --metamodel           Document the built-in metamodel vocabulary (no metadata needed)
   --site                Generate the browsable HTML documentation site (<out>/site/)
   --scaffold-site       Copy the site's templates + assets into codegen/docs-site/ to own (theme) them
@@ -284,9 +357,41 @@ export async function run(argv: string[]): Promise<number> {
     return 2;
   }
   const fmt = resolveFormat(formatFlag, process.stdout.isTTY ?? false);
+  // The flag as PASSED, before the TTY-aware default is applied. `meta types` takes this
+  // rather than `fmt`: its default is text whether or not stdout is a terminal, so that a
+  // pipe does not silently change what every existing scripted caller reads. See
+  // commands/types.ts for the reasoning; `gen` sets the same default on its own parameter.
+  const explicitFormat: OutputFormat | undefined =
+    formatFlag !== undefined && isValidFormat(formatFlag) ? formatFlag : undefined;
 
   const [cmd, ...rest] = cleaned;
 
+  // A bare `--json` / `--toon` / `--text` is the spelling an adopter reaches for
+  // when they want structured output, and every command's `parseArgs` runs
+  // `strict: true`, so today it dies as `Unknown option '--json'` — a message that
+  // names the flag that failed and not the flag that works. It is REJECTED rather
+  // than aliased, deliberately: `--format` is validated once, globally, for all
+  // three values, while an alias would have to be added to every command's own
+  // option table — the per-command scattering that let `--format` be honored by
+  // two commands and silently ignored by the rest. One spelling, and a refusal
+  // that names it. Exit 2, the same usage-error code the unknown option produced.
+  const formatAlias = cleaned.find((a) => a === "--json" || a === "--toon" || a === "--text");
+  if (formatAlias !== undefined) {
+    log.error(
+      `${formatAlias} is not a flag. Use \`--format ${formatAlias.slice(2)}\` — one global spelling for all three formats.`,
+    );
+    return 2;
+  }
+
+  // A `--format` a command does not honor is a no-op, and a silent no-op is the
+  // defect this release is fixing one level down: the adopter who guessed the right
+  // flag still lost, because nothing said the command ignores it. Say it.
+  if (formatFlag !== undefined && cmd !== undefined && !FORMAT_AWARE_COMMANDS.includes(cmd)) {
+    log.warn(
+      `--format is honored by: ${FORMAT_AWARE_COMMANDS.join(", ")}. \`meta ${cmd}\` ignores it and prints text.`,
+    );
+  }
+
   // Intercept per-subcommand --help / -h before dispatching (mirrors migrate's own pattern).
   if (cmd !== undefined && cmd !== "--help" && cmd !== "-h" && cmd !== "--version" && cmd !== "-v") {
     if (rest.includes("--help") || rest.includes("-h")) {
@@ -374,13 +479,17 @@ export async function run(argv: string[]): Promise<number> {
       const { genCommand } = await import("./commands/gen.js");
       return genCommand(rest, cwd, fmt);
     }
+    case "eject": {
+      const { ejectCommand } = await import("./commands/eject.js");
+      return ejectCommand(rest, cwd);
+    }
     case "export": {
       const { exportCommand } = await import("./commands/export.js");
       return exportCommand(rest, cwd);
     }
     case "types": {
       const { typesCommand } = await import("./commands/types.js");
-      return typesCommand(rest);
+      return typesCommand(rest, explicitFormat);
     }
     case "docs": {
       const { docsCommand } = await import("./commands/docs.js");
@@ -388,7 +497,7 @@ export async function run(argv: string[]): Promise<number> {
     }
     case "verify": {
       const { verifyCommand } = await import("./commands/verify.js");
-      return verifyCommand(rest, cwd);
+      return verifyCommand(rest, cwd, undefined, fmt);
     }
     case "upgrade": {
       const { upgradeCommand } = await import("./commands/upgrade.js");

package/src/lib/advisory.ts

@@ -0,0 +1,150 @@
+// Advisory reporting — the ONE display cap, the `--limit` parse, and the shapes
+// advisory findings ride in when the caller asked for a structured format.
+//
+// Why this module exists: the advisory passes (`scanSourceForAntiPatterns` and
+// the requirement diagnostics) found the work and then hid it. Three unshared
+// `const CAP = 10 | 20` literals truncated three sections independently, and the
+// findings never reached the structured payload at all — so `meta gen --format
+// json` on a run with hundreds of findings emitted a clean-looking document while
+// the findings went to stderr as text. An agent reading that payload is not being
+// careless when it reports "all green"; the payload was empty.
+//
+// Two rules follow, and they are the whole point of the module:
+//
+//   1. TEXT output caps, because a cap exists to spare a human's terminal. The cap
+//      is ONE constant, adjustable with `--limit`, so raising it cannot miss a
+//      section.
+//   2. STRUCTURED output NEVER caps. A machine has no terminal to spare, and a
+//      truncated machine payload is the defect this module was written to fix.
+//
+// Discipline inherited from `anti-patterns.ts`: ADVISORY ONLY. Nothing here may
+// reach an exit code.
+
+import { log } from "./log.js";
+import type { AntiPatternFinding } from "./anti-patterns.js";
+
+/**
+ * How many advisory lines TEXT output prints before it truncates.
+ *
+ * One value for every section (anti-patterns, the requirement gate's warnings,
+ * the requirement authoring lint). It is 20 rather than 10 deliberately: folding
+ * two literals into one must not take lines AWAY from a reader, and information
+ * loss is the direction of the defect being fixed. Raise it per-run with
+ * `--limit <n>`; `--limit all` removes it.
+ */
+export const DEFAULT_ADVISORY_LIMIT = 20;
+
+/** `--limit all` — the spelling that removes the text cap entirely. */
+export const ADVISORY_LIMIT_ALL = "all";
+
+/**
+ * Parse `--limit <n|all>` into a line budget. `all` (and any value ≥ the number of
+ * findings) means "print everything". Absent → the default cap.
+ *
+ * Throws on a value that is not a positive integer or `all`; the caller turns that
+ * into the usual exit-2 usage error, the same way `--dialect` and `--baseline` do.
+ */
+export function parseAdvisoryLimit(raw: string | undefined): number {
+  if (raw === undefined) return DEFAULT_ADVISORY_LIMIT;
+  if (raw === ADVISORY_LIMIT_ALL) return Number.POSITIVE_INFINITY;
+  // Reject "10.5", "1e3", "-1", "0" and "" — a limit is a count of lines.
+  if (!/^\d+$/.test(raw) || Number(raw) === 0) {
+    throw new Error(
+      `invalid --limit '${raw}'; expected a positive integer or '${ADVISORY_LIMIT_ALL}'`,
+    );
+  }
+  return Number(raw);
+}
+
+// ---------------------------------------------------------------------------
+// structured shapes
+// ---------------------------------------------------------------------------
+
+/** One anti-pattern finding as it appears in a structured payload. */
+export interface AdvisoryFindingRow {
+  file: string;
+  line: number;
+  rule: string;
+  /** The MetaObjects construct that replaces the hand-rolled site. */
+  construct: string;
+  message: string;
+}
+
+/** One requirement diagnostic as it appears in a structured payload. */
+export interface AdvisoryDiagnosticRow {
+  code: string;
+  /** The dotted child-name path, or "" for a diagnostic whose subject is not a
+   *  requirement (object coverage names the entity in its message instead). */
+  path: string;
+  severity: string;
+  /** "gate" — can fail the build; "lint" — advisory authoring warning, never can. */
+  source: "gate" | "lint";
+  message: string;
+}
+
+/**
+ * One advisory section's FULL result. `total` always equals the row count: a
+ * reader must never have to decide whether a list was truncated, which is exactly
+ * what "…and 229 more" forced on the adopter who reported this.
+ */
+export interface AdvisorySection<Row> {
+  /** "ran" — the pass executed. "skipped" — it did not, and `note` says why. */
+  status: "ran" | "skipped";
+  /** Present only when skipped. Stated rather than left to inference. */
+  note?: string;
+  total: number;
+  rows: Row[];
+}
+
+/** A section that did not run, carrying the reason. */
+export function skippedSection<Row>(note: string): AdvisorySection<Row> {
+  return { status: "skipped", note, total: 0, rows: [] };
+}
+
+/** A section that ran, carrying EVERY row (never capped — see the header). */
+export function ranSection<Row>(rows: Row[]): AdvisorySection<Row> {
+  return { status: "ran", total: rows.length, rows };
+}
+
+/** Project the scanner's findings into payload rows. `snippet` is deliberately
+ *  dropped: it is a copy of the reader's own source line, and `file`+`line`
+ *  already address it. */
+export function antiPatternRows(findings: readonly AntiPatternFinding[]): AdvisoryFindingRow[] {
+  return findings.map((f) => ({
+    file: f.file,
+    line: f.line,
+    rule: f.rule,
+    construct: f.construct,
+    message: f.message,
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// text output
+// ---------------------------------------------------------------------------
+
+/**
+ * Print a capped run of advisory lines to stderr.
+ *
+ * THE single truncation site. The tail line is the part that matters: it names
+ * how to reach what was withheld, which is what the three hand-rolled copies of
+ * this loop never did — an adopter tried `--help | grep`, an invented env var and
+ * `--json` before giving up on 96% of the report.
+ *
+ * @param structured true when the caller is ALSO emitting a machine-readable
+ *   payload on stdout; the tail then points at it, because that copy is complete.
+ */
+export function warnCapped(
+  lines: readonly string[],
+  limit: number,
+  opts: { structured: boolean },
+): void {
+  for (const line of lines.slice(0, limit)) log.warn(line);
+  const withheld = lines.length - Math.min(lines.length, limit);
+  if (withheld <= 0) return;
+  log.warn(
+    opts.structured
+      ? `  …and ${withheld} more — every finding is in the --format payload on stdout.`
+      : `  …and ${withheld} more. Raise the cap with --limit <n>, or --limit ${ADVISORY_LIMIT_ALL}.`,
+  );
+}

package/src/lib/anti-patterns.ts

@@ -28,14 +28,148 @@ export interface AntiPatternFinding {
 }
 
 // Directory segments and file patterns that are never authored app source.
+//
+// `migration` (SINGULAR) sits beside `migrations` because Flyway's own convention
+// is `src/main/resources/db/migration` — the exact directory THIS repo's Flyway
+// output adapter documents as its target (`migrate-ts/src/write-migration-flyway.ts`,
+// `WriteMigrationFlywayOptions.dir`). Without it MetaObjects emitted migrations into
+// a directory its own advisory scanner did not ignore, then flagged the files it had
+// just written as hand-rolled anti-patterns.
+//
+// Nothing else is added here on speculation. A directory list is a guess about
+// someone else's repository — the same failure `@verifiedBy`'s closed pattern list
+// shipped with and 0.23.1 had to correct — so the real coverage lives in
+// IMMUTABLE_MIGRATION_FILE below (a name, wherever it sits) and in the
+// project-declared `ignore` globs.
 const IGNORE_SEGMENTS = new Set([
   "node_modules", ".git", "dist", "build", "out", ".next", "coverage",
-  ".metaobjects", "generated", "migrations",
+  ".metaobjects", "generated", "migrations", "migration",
 ]);
 const SCAN_EXT = /\.(?:ts|tsx|js|sql)$/;
 const SKIP_FILE = /(?:\.d\.ts$|\.test\.|\.spec\.)/;
 const GENERATED_MARKER = "@generated";
 
+// --- immutable migration files ------------------------------------------------
+//
+// WHY THESE ARE EXCLUDED BY NAME, NOT ONLY BY DIRECTORY. A historical migration
+// that a runner has already applied CANNOT be edited: Flyway checksums each
+// versioned migration and refuses to start against a database whose recorded
+// checksum no longer matches, so "fix the CHECK constraint in V001__baseline.sql"
+// is not advice — it is a request to break every environment that has run it. A
+// finding nobody can act on trains the reader to skip the whole advisory section,
+// which is precisely how this advisory came to be ignored in an adopter estate
+// where it had 233 real hits. Under-flagging is the standing bias (module header);
+// nagging about the unfixable is the worst way to spend the reader's attention.
+//
+// A migration is identifiable by its own name wherever it lives, which is what
+// makes this rule better than another directory guess. Each pattern below names
+// the evidence it rests on; every one is either emitted by this repo itself or by
+// a tool whose naming is documented and unmistakable. Patterns that are merely
+// plausible are deliberately absent — a false exclusion silences a real finding,
+// which is the same failure pointed the other way. An unusual layout is the
+// project's to declare (`AntiPatternScanOptions.ignore`), not ours to guess.
+const IMMUTABLE_MIGRATION_FILE: readonly RegExp[] = [
+  // Flyway versioned (V) and undo (U). Source of truth for the version grammar is
+  // `VERSIONED_RE` in `migrate-ts/src/write-migration-flyway.ts` — restated rather
+  // than imported because that constant is module-private, and exporting it is a
+  // change to another package. Two deliberate differences from it: it matches `V`
+  // ONLY (matching `U` there would let the undo files it emits bump the version
+  // counter), whereas an undo file is every bit as un-editable as its up half; and
+  // the multi-part form `V1.1__` / `V1_0__` is carried over verbatim, because
+  // Flyway pads versions for comparison and both spellings are legal.
+  /^[VU]\d+(?:[._]\d+)*__/,
+  // Flyway REPEATABLE (`R__`) is deliberately NOT here, and the reason is the rule's
+  // name. Flyway re-applies a repeatable migration whenever its checksum changes, so
+  // editing one is the sanctioned workflow rather than a forbidden act — which makes a
+  // finding on it ACTIONABLE, and this list exists precisely to drop findings that are
+  // not. Excluding it would silence a real one. Repeatable scripts live in Flyway's
+  // `db/migration`, which IGNORE_SEGMENTS covers, so the practical effect is limited to
+  // a stray `R__` outside that tree — where scanning it is the correct answer.
+  // A 10+ digit leading number is a clock, not a count: epoch milliseconds (13,
+  // node-pg-migrate) or YYYYMMDDHHMMSS (14, Rails / Knex / Sequelize, and this
+  // repo's own default writer — see the directory rule below). Ten is the floor
+  // because that is epoch seconds; a four-digit lead would also match an ordinary
+  // `2024_q1_revenue.sql`, which is exactly the false exclusion to avoid.
+  /^\d{10,}[-_]/,
+  // A ZERO-PADDED sequence: `0000_lush_rockslide.sql` (Drizzle Kit, whose default
+  // `out` is `./drizzle` and so is caught by no directory name), `0001_init.sql`
+  // (this repo's own D1 adapter — `write-migration-d1.ts` pads to 4), and
+  // `000001_create_users.up.sql` (golang-migrate). The leading zero is what makes
+  // this safe: sequence numbers are padded so they sort, ordinary numbers are not,
+  // so a year or quarter prefix can never match.
+  /^0\d+[-_]/,
+  // The up/down halves of a migration pair. `up.sql` / `down.sql` is what this
+  // repo's own default writer emits (`migrate-ts/src/write-migration.ts`); the
+  // `<name>.up.sql` / `<name>.down.sql` suffix form is golang-migrate's. Kept to
+  // `.sql` on purpose — `up.ts` and `down.ts` are not migration names.
+  /^(?:up|down)\.sql$/i,
+  /\.(?:up|down)\.sql$/i,
+];
+
+// A per-migration DIRECTORY named by a timestamp. This repo's default writer
+// creates `<YYYYMMDDHHMMSS>-<slug>/` holding `up.sql` + `down.sql`
+// (`migrate-ts/src/write-migration.ts`), and Prisma creates
+// `<YYYYMMDDHHMMSS>_<slug>/` holding `migration.sql`. Both are already covered
+// when they sit under the default `migrations` root; this catches them under a
+// project-chosen `migrate.outDir`, and it is risk-free — nobody names a source
+// directory with a fourteen-digit timestamp.
+const IMMUTABLE_MIGRATION_DIR = /^\d{10,}[-_]/;
+
+function isImmutableMigrationFile(basename: string): boolean {
+  return IMMUTABLE_MIGRATION_FILE.some((re) => re.test(basename));
+}
+
+// --- project-declared ignore globs --------------------------------------------
+
+/** Options for {@link scanSourceForAntiPatterns}. */
+export interface AntiPatternScanOptions {
+  /**
+   * Extra path globs the scan skips entirely — the project's escape hatch for a
+   * layout the built-ins cannot know about (a vendored SQL archive, a migration
+   * tool with a house naming convention, a directory of read-only reference DDL).
+   *
+   * The built-in exclusions above are a CONVENIENCE, not an authority; the
+   * `@verifiedBy` fix in 0.23.1 established the shape — built-in defaults for the
+   * conventions that demonstrably exist, PLUS a project-declared list, because a
+   * closed list of guesses about someone else's repository will always be wrong
+   * somewhere. Declared globs ADD to the built-ins; they never replace them.
+   *
+   * Matched against forward-slash paths relative to the scan root: `**` spans
+   * separators, `*` does not, `?` is one non-separator character. A glob matching
+   * a directory path prunes that whole subtree.
+   *
+   * ```ts
+   * scanSourceForAntiPatterns(root, { ignore: ["drizzle/**", "db/legacy"] })
+   * ```
+   */
+  readonly ignore?: readonly string[];
+}
+
+/**
+ * A glob as permissive as the ones adopters actually write, anchored at the scan
+ * root and matched against forward-slash relative paths. Deliberately small:
+ * anything richer belongs to a glob library, and pulling one in for a knob this
+ * narrow is not worth the dependency. (Same grammar the retired `@verifiedBy`
+ * scan used for `verify.testFiles`, kept identical so a project that learned one
+ * spelling does not have to learn a second.)
+ */
+function globToRegExp(glob: string): RegExp {
+  let out = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i]!;
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        // `**/` may match zero segments, so `**/*.sql` matches a root-level file.
+        if (glob[i + 2] === "/") { out += "(?:.*/)?"; i += 2; } else { out += ".*"; i += 1; }
+      } else out += "[^/]*";
+      continue;
+    }
+    if (c === "?") { out += "[^/]"; continue; }
+    out += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${out}$`);
+}
+
 // --- rules: each tests one source line, returns a finding shape or null -------
 
 const MONEY_WORD = /\b(?:price|amount|cost|total|subtotal|fee|balance|cents|dollars)\w*/i;
@@ -86,7 +220,11 @@ function findingFor(file: string, lineNo: number, raw: string, isSql: boolean):
   };
 }
 
-function walk(dir: string, root: string, acc: AntiPatternFinding[]): void {
+function relPosix(root: string, abs: string): string {
+  return relative(root, abs).split(sep).join("/");
+}
+
+function walk(dir: string, root: string, ignore: readonly RegExp[], acc: AntiPatternFinding[]): void {
   let entries;
   try {
     entries = readdirSync(dir, { withFileTypes: true });
@@ -96,12 +234,25 @@ function walk(dir: string, root: string, acc: AntiPatternFinding[]): void {
   for (const e of entries) {
     if (e.isDirectory()) {
       if (IGNORE_SEGMENTS.has(e.name) || e.name.startsWith(".")) continue;
-      walk(join(dir, e.name), root, acc);
+      // A per-migration directory is excluded by its own name, wherever it sits.
+      if (IMMUTABLE_MIGRATION_DIR.test(e.name)) continue;
+      const dirRel = relPosix(root, join(dir, e.name));
+      if (ignore.some((re) => re.test(dirRel))) continue;
+      walk(join(dir, e.name), root, ignore, acc);
       continue;
     }
     if (!e.isFile()) continue;
     if (!SCAN_EXT.test(e.name) || SKIP_FILE.test(e.name)) continue;
+    // Filename shape wins over location, deliberately: a migration is identifiable
+    // by its own name, and a project that keeps its migrations somewhere we cannot
+    // guess should not be nagged about files it may not edit. The cost is bounded —
+    // these name shapes are not ones an ordinary query or schema file wears.
+    if (isImmutableMigrationFile(e.name)) continue;
     const abs = join(dir, e.name);
+    // Checked before the read: a declared ignore is a decision not to look at the
+    // file at all, so it should not cost an I/O either.
+    const rel = relPosix(root, abs);
+    if (ignore.some((re) => re.test(rel))) continue;
     let text: string;
     try {
       if (statSync(abs).size > 512 * 1024) continue; // skip very large files
@@ -111,7 +262,6 @@ function walk(dir: string, root: string, acc: AntiPatternFinding[]): void {
     }
     // Skip MetaObjects-generated output — it legitimately contains AVG/CHECK etc.
     if (text.slice(0, 600).includes(GENERATED_MARKER)) continue;
-    const rel = relative(root, abs).split(sep).join("/");
     const isSql = e.name.endsWith(".sql");
     const lines = text.split("\n");
     for (let i = 0; i < lines.length; i++) {
@@ -123,12 +273,17 @@ function walk(dir: string, root: string, acc: AntiPatternFinding[]): void {
 
 /**
  * Scan authored source under `cwd` for the high-precision anti-patterns above.
- * Returns every finding (advisory). Generated output, dependencies, build dirs,
- * and test files are skipped.
+ * Returns every finding (advisory — this never influences an exit code).
+ * Generated output, dependencies, build dirs, test files, immutable migration
+ * files, and anything matched by `options.ignore` are skipped.
  */
-export function scanSourceForAntiPatterns(cwd: string): AntiPatternFinding[] {
+export function scanSourceForAntiPatterns(
+  cwd: string,
+  options?: AntiPatternScanOptions,
+): AntiPatternFinding[] {
   const acc: AntiPatternFinding[] = [];
-  walk(cwd, cwd, acc);
+  const ignore = (options?.ignore ?? []).map(globToRegExp);
+  walk(cwd, cwd, ignore, acc);
   acc.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
   return acc;
 }