@metaobjectsdev/cli 1.0.0-rc.5 → 1.0.0-rc.7

package/src/commands/verify.ts

@@ -12,12 +12,14 @@ import { parseVerifyArgs, type MigrateFlags } from "../lib/args.js";
 import { log } from "../lib/log.js";
 import { emitStructured, type OutputFormat } from "../lib/format.js";
 import {
-  antiPatternRows, ranSection, skippedSection, warnCapped,
+  antiPatternRows, missingBaseUrlRows, ranSection, skippedSection, warnCapped,
   type AdvisoryDiagnosticRow, type AdvisoryFindingRow, type AdvisorySection,
 } from "../lib/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 { replayRemedy } from "../lib/replay-remedy.js";
 import { FileProvider } from "../lib/file-provider.js";
 import { derivePayloadFieldTree } from "../lib/payload-field-tree.js";
 import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenCollection, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
@@ -85,6 +87,7 @@ import {
   REQUIREMENT_STATUSES,
 } from "@metaobjectsdev/metadata";
 import { verify, ERR_REQUIRED_SLOT_UNUSED, ERR_PARTIAL_UNRESOLVED } from "@metaobjectsdev/render";
+import { describeLoadError, reportLoadError } from "../lib/load-error.js";
 
 const DEFAULT_PROMPTS_DIR = "prompts";
 
@@ -250,7 +253,10 @@ export async function verifyCommand(
     });
   } catch (err) {
     const msg = (err as Error).message;
-    log.error(`failed to load metadata: ${msg}`);
+    // Everything the loader's envelope carried, not just the message: the stable code a
+    // CI job keys on, and the FILE + json path the message itself can never name.
+    const report = describeLoadError(err);
+    log.error(`failed to load metadata: ${report.text}`);
     // Strict-load rejection (ADR-0023). Two different failures reach here and they need
     // different advice:
     //
@@ -263,8 +269,11 @@ export async function verifyCommand(
     // retired attribute and the author gets a green `meta verify` over a value that now
     // reaches nothing: a correct, loud failure converted into a quiet, wrong pass. That is
     // strictly worse than the error it replaced.
-    const code = (err as { code?: string }).code;
-    const suggestions = (err as { suggestions?: string[] }).suggestions;
+    // Off the REPORT, not the raw error a second time: `describeLoadError` has already
+    // decided what the envelope carried (and filtered empty entries), so re-reading the
+    // throwable would be a second answer to a question already answered above.
+    const code = report.code;
+    const suggestions = report.suggestions;
     const strictHint =
       "meta verify is strict (ADR-0023): every authored @attr must be declared. " +
       "Fix: register the attr on a metadata provider, OR move arbitrary " +
@@ -280,6 +289,14 @@ export async function verifyCommand(
     // report — only why there is none.
     emitStructured({
       error: `failed to load metadata: ${msg}`,
+      // ADR-0009 promises a stable `code`, and the docs name codes a CI job is meant to
+      // branch on — but this payload used to carry the message string and nothing else,
+      // so there was nothing to branch on. Each field is present only when the loader
+      // actually supplied it; absence here means the loader had none, never that it was
+      // dropped in transit.
+      ...(report.code !== undefined ? { code: report.code } : {}),
+      ...(report.files !== undefined ? { files: [...report.files] } : {}),
+      ...(report.jsonPath !== undefined ? { jsonPath: report.jsonPath } : {}),
       hint: suggestions !== undefined && suggestions.length > 0
         ? suggestions.join(" ")
         : isStrictAttr ? strictHint : "fix the metadata error above and re-run",
@@ -449,11 +466,7 @@ export async function verifyCommand(
         applied = await applyPending(engine.db, dir, { dryRun: false, dialect });
       } catch (err) {
         log.error(`meta verify --replay: ${(err as Error).message}`);
-        log.error(
-          `meta verify --replay: the committed chain does not apply to an empty database. ` +
-            `Applied migrations are immutable, so fix this with a NEW migration that creates the ` +
-            `missing object — not by editing a committed up.sql.`,
-        );
+        for (const line of replayRemedy(err)) log.error(`meta verify --replay: ${line}`);
         return 1;
       }
 
@@ -711,13 +724,33 @@ export async function verifyCommand(
       antiPatternSection = skippedSection(`the scan failed: ${(err as Error).message}`);
       return;
     }
-    antiPatternSection = ranSection(antiPatternRows(findings));
-    if (findings.length === 0) return;
-    log.warn(
-      `meta verify — ${findings.length} place(s) hand-roll what MetaObjects can model ` +
-        `(advisory — does not fail the build):`,
-    );
-    warnCapped(findings.map((f) => `  ${f.message}`), flags.limit, { structured });
+    // F52 — the one gate that can see a provider silently missing its base. Folded into
+    // this pass rather than given its own, because it is the same KIND of finding (a
+    // teachable warning that never touches the exit code) and one --no-antipatterns
+    // should suppress the whole advisory tier, not half of it.
+    let baseUrl: BaseUrlFinding[] = [];
+    try {
+      baseUrl = scanForMissingBaseUrl(projectRoot, forgeConfig?.apiPrefix ?? "");
+    } catch {
+      // Same discipline as above: an advisory scan never breaks verify. The anti-pattern
+      // half already ran, so its rows are still reported rather than lost to this catch.
+    }
+
+    antiPatternSection = ranSection([...antiPatternRows(findings), ...missingBaseUrlRows(baseUrl)]);
+    if (findings.length > 0) {
+      log.warn(
+        `meta verify — ${findings.length} place(s) hand-roll what MetaObjects can model ` +
+          `(advisory — does not fail the build):`,
+      );
+      warnCapped(findings.map((f) => `  ${f.message}`), flags.limit, { structured });
+    }
+    if (baseUrl.length > 0) {
+      log.warn(
+        `meta verify — ${baseUrl.length} entity-fetcher provider(s) mounted with no baseUrl ` +
+          `while apiPrefix is "${forgeConfig?.apiPrefix ?? ""}" (advisory — does not fail the build):`,
+      );
+      warnCapped(baseUrl.map((f) => `  ${f.message}`), flags.limit, { structured });
+    }
   }
 
   // -- template (prompt / output) drift --------------------------------------
@@ -1200,11 +1233,11 @@ export async function verifyCommand(
           strict: !flags.lax,
         });
       } catch (err) {
-        log.error(`verify --codegen: failed to load this package's metadata: ${(err as Error).message}`);
-        // The second door onto the same strict load. It carried no remedy at all, which
-        // meant a retirement diagnosed here told the author what broke and nothing about
-        // how to fix it — the half-true rule this file's sibling comment warns about.
-        for (const s of (err as { suggestions?: string[] }).suggestions ?? []) log.error(`  ${s}`);
+        // The second door onto the same strict load, and it must carry the same provenance
+        // as the first: the ADR-0009 code, the FILE and json path the message cannot name,
+        // and the loader's own remedies. It printed a bare message plus a hand-rolled
+        // suggestions read — the half-true rule this file's sibling comment warns about.
+        reportLoadError(log, "verify --codegen: failed to load this package's metadata", err);
         return 2;
       }
     }
@@ -1223,7 +1256,11 @@ export async function verifyCommand(
     }
 
     if (result.clean) {
-      say("meta verify — generated output is in sync with the metadata (no codegen drift).");
+      // Says what it CHECKED, not more. Since 0.24.3 this gate asks whether each file's
+      // GENERATED contribution is current — a hand edit `meta gen` preserves is exempt —
+      // so "output is in sync with the metadata" claimed a stronger property than it had
+      // verified, and did so over a file whose committed content contradicted the model.
+      say("meta verify — every file's generated contribution is current (no codegen drift).");
       return 0;
     }
 
@@ -1231,7 +1268,21 @@ export async function verifyCommand(
       `meta verify — codegen drift (${result.driftedFiles.length} file(s) differ from a fresh regen):`,
     );
     for (const line of result.lines) log.error(`  ${line}`);
-    log.error("Run 'meta gen' to regenerate, then commit the result.");
+    // The remedy is PER CONVICTION KIND, not one line for the whole gate. `meta gen`
+    // fixes stale generated output; it cannot fix a hand-edited names artifact, because
+    // it MERGES the edit and exits 0 — so prescribing it there was the unbreakable loop
+    // the hand-edit exemption exists to end, reintroduced for the one file the exemption
+    // deliberately excludes. Both lines print when the drift set holds both kinds.
+    if (result.driftedFiles.length > result.handEditedNames.length) {
+      log.error("Run 'meta gen' to regenerate, then commit the result.");
+    }
+    if (result.handEditedNames.length > 0) {
+      log.error(
+        "For the names artifact(s) above, 'meta gen' will NOT help — it preserves a hand " +
+          "edit by design. Revert the edit (or delete the file and re-run 'meta gen' to " +
+          "re-emit it), and keep constants of your own in a file of your own.",
+      );
+    }
     return 1;
   }
 

package/src/index.ts

@@ -57,10 +57,12 @@ GEN FLAGS:
   --dry-run             Compute and print, don't write
   --list                Print the generator registry (name, tier, options) and exit —
                         no config or metadata required
-  --baseline <default|fresh>
-                        First-time-on-existing-file behavior. Default: write-if-different,
-                        adopting existing content as the canonical baseline. "fresh"
-                        overwrites and re-baselines.
+  --baseline <default|adopt|fresh>
+                        First-time-on-existing-file behavior. Default: refuse a file that
+                        cannot be proved to be generated output. "adopt" records the files
+                        you have as the merge base and writes NOTHING — the first run a
+                        project with no committed .hashes.json can perform. "fresh"
+                        overwrites them with fresh output and re-baselines (discards edits).
   --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
@@ -75,7 +77,11 @@ DOCS FLAGS:
   [<project-root>]      PROJECT ROOT to resolve metadata from — the directory that CONTAINS
                         your metadata, NOT the metadata directory. Passing it SCOPES the run
                         (default: cwd)
-  --out <dir>, -o       Output directory for the pages (default: ./docs)
+  --out <dir>, -o       Output directory for THIS run (default: ./docs/generated). It does
+                        NOT survive the run — set 'docs: { outDir }' in metaobjects.config.ts
+                        for a directory that persists, which is what 'meta verify --docs'
+                        measures. The default is a sub-directory on purpose: these pages are
+                        regenerated and overwritten, and 'docs/' itself is usually yours.
   --templates <dir>     Project root to resolve adopter templates/ overrides (default: <project-root>)
   --prompts <dir>       Extra dir holding prompt .mustache sources for --site (e.g. data/templates/)
 
@@ -143,10 +149,12 @@ FLAGS:
   --dry-run             Compute and print, don't write
   --list                Print the generator registry (name, tier, options) and exit —
                         no config or metadata required
-  --baseline <default|fresh>
-                        First-time-on-existing-file behavior. Default: write-if-different,
-                        adopting existing content as the canonical baseline. "fresh"
-                        overwrites and re-baselines.
+  --baseline <default|adopt|fresh>
+                        First-time-on-existing-file behavior. Default: refuse a file that
+                        cannot be proved to be generated output. "adopt" records the files
+                        you have as the merge base and writes NOTHING — the first run a
+                        project with no committed .hashes.json can perform. "fresh"
+                        overwrites them with fresh output and re-baselines (discards edits).
   --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)
@@ -191,7 +199,10 @@ USAGE:
 
 FLAGS:
   --templates           Template/prompt {{field}}↔payload drift (default when bare)
-  --codegen             Codegen drift — regenerate to temp dir and diff committed output
+  --codegen             Codegen drift — is the GENERATED contribution current? A hand
+                        edit 'meta gen' preserves is not drift; a stale generated part is.
+                        An <Entity>.names.ts artifact is the exception: it must match a
+                        fresh regen exactly — a hand edit in it is itself the defect.
                         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. A page the
@@ -269,7 +280,11 @@ FLAGS:
                         it SCOPES the run to that directory's own sources; no ancestor
                         .metaobjects/config.json is consulted. Omitted (default), the project
                         is discovered by walking up.
-  --out <dir>, -o       Output directory for the pages (default: ./docs)
+  --out <dir>, -o       Output directory for THIS run (default: ./docs/generated). It does
+                        NOT survive the run — set 'docs: { outDir }' in metaobjects.config.ts
+                        for a directory that persists, which is what 'meta verify --docs'
+                        measures. The default is a sub-directory on purpose: these pages are
+                        regenerated and overwritten, and 'docs/' itself is usually yours.
   --model               Emit the markdown model surface (entity + template pages)
   --api                 Emit the markdown api surface (generated SDK reference)
   --requirements        Emit the declared requirement ledger (requirements.md + .toon).
@@ -278,7 +293,9 @@ FLAGS:
                         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.
+                        from it); each page is skipped when its tier has nothing to describe
+                        — agent/ui.md needs a UI generator (a form, hook or grid) in the
+                        suite, not merely objects that could have one.
   --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
@@ -297,10 +314,12 @@ FLAGS:
   --docs-only           Write only the agent-context files — no metadata sources, no
                         codegen scaffold, no config. Pair with --refresh-docs to update
                         an existing project after upgrading.
-  --server <lang>       Declare a server language for the agent context (repeatable;
-                        e.g. csharp, kotlin, python, node)
-  --client <fw>         Declare a client framework for the agent context (repeatable;
-                        e.g. react, vue)
+  --server <lang>       Declare a server language for the agent context (repeatable):
+                        typescript | java | kotlin | csharp | python
+                        ('node' is accepted as an alias for typescript; an unknown
+                        value is refused, never dropped)
+  --client <fw>         Declare a client framework for the agent context (repeatable):
+                        react | tanstack | angular
   --no-skills           Skip the .claude/skills/ scaffold
   --force               Overwrite existing files
   --quiet               Suppress output
@@ -317,8 +336,8 @@ USAGE:
   meta agent-docs [--server <lang>]... [--client <fw>]... [--out <dir>] [flags]
 
 FLAGS:
-  --server <lang>       Server language (repeatable; e.g. csharp, kotlin, python, node)
-  --client <fw>         Client framework (repeatable; e.g. react, vue)
+  --server <lang>       Server language (repeatable): typescript|java|kotlin|csharp|python
+  --client <fw>         Client framework (repeatable): react|tanstack|angular
   --out <dir>           Output directory (default: current directory)
   --no-skills           Skip .claude/skills/ scaffold
   --no-wire-root        Skip wiring root CLAUDE.md @import

package/src/lib/advisory.ts

@@ -22,6 +22,7 @@
 
 import { log } from "./log.js";
 import type { AntiPatternFinding } from "./anti-patterns.js";
+import type { BaseUrlFinding } from "./base-url-advisory.js";
 
 /**
  * How many advisory lines TEXT output prints before it truncates.
@@ -119,6 +120,20 @@ export function antiPatternRows(findings: readonly AntiPatternFinding[]): Adviso
   }));
 }
 
+/**
+ * F52 findings in the same row shape, so the structured payload has ONE advisory list
+ * rather than a second one a consumer has to learn about. `rule` is the discriminator.
+ */
+export function missingBaseUrlRows(findings: readonly BaseUrlFinding[]): AdvisoryFindingRow[] {
+  return findings.map((f) => ({
+    file: f.file,
+    line: f.line,
+    rule: "missing-base-url",
+    construct: f.construct,
+    message: f.message,
+  }));
+}
+
 // ---------------------------------------------------------------------------
 // text output
 // ---------------------------------------------------------------------------

package/src/lib/anti-patterns.ts

@@ -16,7 +16,9 @@
 // nag a legitimate one.
 
 import { readdirSync, readFileSync, statSync } from "node:fs";
-import { join, relative, sep } from "node:path";
+import { join } from "node:path";
+import { relPosix } from "./rel-posix.js";
+import { looksBundled } from "./authored-source.js";
 
 export interface AntiPatternFinding {
   file: string; // path relative to the scan root (posix-ish, sep-normalized)
@@ -220,10 +222,6 @@ function findingFor(file: string, lineNo: number, raw: string, isSql: boolean):
   };
 }
 
-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 {
@@ -262,6 +260,10 @@ function walk(dir: string, root: string, ignore: readonly RegExp[], acc: AntiPat
     }
     // Skip MetaObjects-generated output — it legitimately contains AVG/CHECK etc.
     if (text.slice(0, 600).includes(GENERATED_MARKER)) continue;
+    // …and skip a BUNDLE, which is nobody's source. The 512KB gate above is about cost, not
+    // authorship: a 300KB minified file passes it while being just as unfixable. Same rule
+    // the base-URL advisory applies, from the same module. See lib/authored-source.ts.
+    if (looksBundled(text)) continue;
     const isSql = e.name.endsWith(".sql");
     const lines = text.split("\n");
     for (let i = 0; i < lines.length; i++) {

package/src/lib/args.ts

@@ -100,10 +100,10 @@ export function parseAgentDocsArgs(argv: string[]): AgentDocsFlags {
 export interface GenFlags {
   dryRun: boolean;
   entities: string[];
-  /** First-time-on-existing-file behavior. Default: write-if-different
-   *  (existing content becomes the canonical baseline). "fresh" → overwrite
-   *  and re-baseline. */
-  baseline: "default" | "fresh";
+  /** First-time-on-existing-file behavior. Default: refuse a file that cannot be
+   *  proved to be ours. "adopt" → record the file as the merge base and write
+   *  nothing. "fresh" → overwrite from fresh output and re-baseline. */
+  baseline: "default" | "fresh" | "adopt";
   /** ADR-0021 D3 — print the stable-name generator registry and exit without
    *  running codegen. */
   list: boolean;
@@ -134,15 +134,20 @@ export function parseGenArgs(argv: string[]): GenFlags {
     allowPositionals: true,
   });
   const baselineRaw = values.baseline as string | undefined;
-  if (baselineRaw !== undefined && baselineRaw !== "default" && baselineRaw !== "fresh") {
+  if (
+    baselineRaw !== undefined &&
+    baselineRaw !== "default" &&
+    baselineRaw !== "fresh" &&
+    baselineRaw !== "adopt"
+  ) {
     throw new Error(
-      `invalid --baseline '${baselineRaw}'; expected 'default' or 'fresh'`,
+      `invalid --baseline '${baselineRaw}'; expected 'default', 'adopt' or 'fresh'`,
     );
   }
   return {
     dryRun: !!values["dry-run"],
     entities: positionals,
-    baseline: (baselineRaw as "default" | "fresh" | undefined) ?? "default",
+    baseline: (baselineRaw as "default" | "fresh" | "adopt" | undefined) ?? "default",
     list: !!values.list,
     noAntipatterns: !!values["no-antipatterns"],
     // Throws on a bad value; the command layer reports it and exits 2, exactly as
@@ -263,7 +268,7 @@ export interface VerifyFlags {
   // command layer applies the bare-verify default (= --templates) when none are.
   /** Run the template/prompt {{field}}↔payload drift gate. */
   templates: boolean;
-  /** Run the codegen-drift gate (regenerate-to-temp and diff committed output). */
+  /** Run the codegen-drift gate: is the GENERATED contribution of each file current? */
   codegen: boolean;
   /**
    * Run the docs-drift gate: regenerate the `meta docs` surfaces into a temp dir and diff
@@ -272,8 +277,9 @@ export interface VerifyFlags {
    * A SEPARATE subverb rather than part of `--codegen`, because they check different
    * trees under different ownership rules: `--codegen` regenerates `outDir`/`targets` and
    * must respect the hand edits `meta gen` preserves, while the docs tree has no merge,
-   * no manifest, and lives in a directory (`./docs` by default) full of hand-written
-   * files it does not own. Folding them together would have to pick one of those rules
+   * no manifest, and lives in a directory the adopter chose (`./docs/generated` by
+   * default) that may hold hand-written files it does not own. Folding them together
+   * would have to pick one of those rules
    * for both.
    */
   docs: boolean;
@@ -309,11 +315,19 @@ export interface VerifyFlags {
    */
   lax: boolean;
   /**
-   * How many advisory lines TEXT output prints per SECTION before truncating
-   * (`DEFAULT_ADVISORY_LIMIT`, or Infinity for `--limit all`). Per-section, never
-   * shared across them — the reason the two caps were separate in the first place
-   * is that one shared budget lets the authoring lint push every gate warning off
-   * the end. It never applies to a structured payload, which carries everything.
+   * How many advisory lines TEXT output prints per printed LIST before truncating
+   * (`DEFAULT_ADVISORY_LIMIT`, or Infinity for `--limit all`). Never shared across
+   * lists — one shared budget lets the biggest list push every other finding off the
+   * end. It never applies to a structured payload, which carries everything.
+   *
+   * Per LIST, not per section, and the distinction is real rather than pedantic: the
+   * anti-pattern tier prints TWO separately-headed lists (the hand-rolling findings and
+   * the F52 missing-`baseUrl` findings) while being ONE section everywhere else — one
+   * structured list keyed by `rule`, one `--no-antipatterns` muting both. So that
+   * section's text output can reach a MULTIPLE of the cap. Deliberate: a project with 200
+   * money-float sites would otherwise never see its `baseUrl` advisory, which is the one
+   * that silently drops the API prefix from every generated hook, and starving the small
+   * list is the worse failure. Pinned in advisory-structured-output.test.ts.
    */
   limit: number;
 }
@@ -323,7 +337,7 @@ export const VERIFY_OPTIONS = {
   prompts: { type: "string" },
   db: { type: "string" },
   dialect: { type: "string" },
-  allow: { type: "string" },
+  allow: { type: "string", multiple: true },
   "skip-schema": { type: "boolean", default: false },
   templates: { type: "boolean", default: false },
   codegen: { type: "boolean", default: false },
@@ -338,6 +352,33 @@ export const VERIFY_OPTIONS = {
   "limit": { type: "string" },
 } as const;
 
+/**
+ * The `--allow` tokens for one invocation, from EVERY occurrence of the flag.
+ *
+ * `--allow` is comma-separated, and repeating it is the natural reading (it is what
+ * `--server` does). It used to take the LAST occurrence only, so
+ * `--allow drop-fk --allow drop-view` silently discarded `drop-fk` and then printed
+ * "re-run with --allow drop-fk to apply" seven times — an instruction the user had just
+ * followed. Both spellings, and any mixture of them, now mean the union.
+ *
+ * Duplicates collapse: asking for the same permission twice is one permission.
+ */
+function parseAllowTokens(raw: string | string[] | undefined): AllowToken[] {
+  const occurrences = raw === undefined ? [] : Array.isArray(raw) ? raw : [raw];
+  const seen = new Set<string>();
+  for (const occurrence of occurrences) {
+    for (const tok of occurrence.split(",").map((t) => t.trim()).filter((t) => t.length > 0)) {
+      if (!ALLOW_TOKENS.includes(tok as AllowToken)) {
+        throw new Error(
+          `invalid --allow token '${tok}'; expected one of: ${ALLOW_TOKENS.join(", ")}`,
+        );
+      }
+      seen.add(tok);
+    }
+  }
+  return [...seen] as AllowToken[];
+}
+
 export function parseVerifyArgs(argv: string[]): VerifyFlags {
   const { values } = parseArgs({
     args: argv,
@@ -351,17 +392,7 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
     throw new Error(`invalid --dialect '${dialect}'; expected: ${DIALECTS.join(", ")}`);
   }
 
-  const allowRaw = (values.allow as string | undefined) ?? "";
-  const allowTokens = allowRaw.length === 0
-    ? []
-    : allowRaw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
-  for (const tok of allowTokens) {
-    if (!ALLOW_TOKENS.includes(tok as AllowToken)) {
-      throw new Error(
-        `invalid --allow token '${tok}'; expected one of: ${ALLOW_TOKENS.join(", ")}`,
-      );
-    }
-  }
+  const allowTokens = parseAllowTokens(values.allow as string | string[] | undefined);
 
   const templates = !!values.templates;
   const codegen = !!values.codegen;
@@ -472,7 +503,7 @@ export const MIGRATE_OPTIONS = {
   "migration-format": { type: "string" },
   "out-dir": { type: "string" },
   "slug": { type: "string" },
-  "allow": { type: "string" },
+  "allow": { type: "string", multiple: true },
   "on-ambiguous": { type: "string" },
   "dry-run": { type: "boolean", default: false },
   "from-db": { type: "boolean", default: false },
@@ -518,17 +549,7 @@ export function parseMigrateArgs(argv: string[]): MigrateFlags {
     throw new Error(`invalid --on-ambiguous '${onAmb}'; expected: ${ON_AMBIGUOUS.join(", ")}`);
   }
 
-  const allowRaw = (values.allow as string | undefined) ?? "";
-  const allowTokens = allowRaw.length === 0
-    ? []
-    : allowRaw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
-  for (const tok of allowTokens) {
-    if (!ALLOW_TOKENS.includes(tok as AllowToken)) {
-      throw new Error(
-        `invalid --allow token '${tok}'; expected one of: ${ALLOW_TOKENS.join(", ")}`,
-      );
-    }
-  }
+  const allowTokens = parseAllowTokens(values.allow as string | string[] | undefined);
 
   return {
     db: values.db as string | undefined,

package/src/lib/authored-source.ts

@@ -0,0 +1,45 @@
+/**
+ * Is this file text a HUMAN wrote, or a bundler's output?
+ *
+ * Both advisory scanners — the base-URL one and the anti-pattern one — exist to teach the
+ * author of a file something about the file. A bundle is not authored: nobody can act on a
+ * finding in it, the fix belongs in the source it was built from, and naming a generated
+ * artifact spends the scanners' whole false-positive budget in one line.
+ *
+ * The rule is a property of the ARTIFACT, not of a directory name. An estate proved why:
+ * its build output is `public/`, which no ignore list would have guessed (the lists cover
+ * `dist`, `build`, `.next`, `.output`, `out`), so `meta verify` reported
+ * `public/main.js:243 — <EntityFetcherProvider> is mounted with no baseUrl` while
+ * `client/src/main.tsx:26` — the source, the file a person edits — passes `baseUrl="/api"`
+ * correctly. Adding `public` to a list would have fixed that estate and nobody else.
+ *
+ * The two scanners keep their own walkers, deliberately (they diverge on eight axes and
+ * unifying them needs ~6 options for two callers). What they share is this judgment, so it
+ * lives here once rather than being decided twice.
+ */
+
+/**
+ * Bundlers emit lines in the thousands-to-hundreds-of-thousands of characters; the estate
+ * bundle that produced the false positive has a longest line of 266,226. Authored source
+ * does not reach 5,000 — the threshold sits an order of magnitude above the longest line
+ * any human writes and an order of magnitude below what minification produces, so it is a
+ * wide gap rather than a tuned one.
+ *
+ * NOT `>= 512KB`, which `anti-patterns.ts` already applies for a different reason (cost):
+ * that gate is about how much work a scan does, and a 300KB bundle sails through it while
+ * being exactly as unauthored as a 700KB one.
+ */
+const BUNDLED_LINE_LENGTH = 5000;
+
+/** True when `text` looks like build output rather than source someone edits. */
+export function looksBundled(text: string): boolean {
+  // Scan for a long line without splitting the whole file: a 700KB bundle would otherwise
+  // allocate an array of it, and this runs per file on every `meta verify` / `meta gen`.
+  let lineStart = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (text.charCodeAt(i) !== 10 /* \n */) continue;
+    if (i - lineStart >= BUNDLED_LINE_LENGTH) return true;
+    lineStart = i + 1;
+  }
+  return text.length - lineStart >= BUNDLED_LINE_LENGTH;
+}