@metaobjectsdev/cli 1.0.10 → 1.0.12

package/src/index.ts

@@ -41,6 +41,7 @@ COMMANDS:
   deps list             One line per locked dependency: name, version, hash, node/package summary
   types [query]         Search the metadata vocabulary (types, subtypes, @attrs) by name or description
   export                Flatten loaded metadata to one canonical JSON artifact
+  fmt [<file>...]       Rewrite metadata files into canonical form; --check lists drift, exits non-zero
   docs [<project-root>] --out <dir>  Generate neutral metadata documentation (entity + template pages; --site for HTML site)
   verify                Drift gate — subverbs: --templates / --db / --codegen / --docs / --deps (bare = --templates)
   upgrade               Rewrite retired metadata vocabulary (previews; --apply writes)
@@ -86,6 +87,21 @@ GEN FLAGS:
 EXPORT FLAGS:
   --out <file>          Write output to a file (default: stdout)
 
+FMT FLAGS:
+  [<file>...]           Optional explicit file(s) to format — must be members of this
+                        project's resolved metadata sources (resolveCollection()); omit
+                        to format every one of them.
+  --check               List files that are not canonical and exit non-zero; changes nothing.
+                        A file whose formatting would change the LOADED MODEL's meaning
+                        is never rewritten — reported as an error instead (safety check).
+                        A YAML file is always reported as skipped: no canonical YAML
+                        emitter exists yet (ADR-0006 — JSON is the canonical interchange
+                        form). A file declaring 'overlay: true' anywhere — whether or not
+                        a same-file base exists to merge into — is skipped too: a
+                        formatter never changes structure, and buildTree's ordinary
+                        find-or-reuse behavior would otherwise silently fold a same-file
+                        base + overlay into one node, dropping the overlay marker.
+
 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
@@ -127,6 +143,10 @@ VERIFY FLAGS (ADR-0021 D2 — explicit subverbs; combine any; exit 1 on ANY drif
   --no-requirement-lint Suppress the advisory requirement AUTHORING lint (not the gate)
   --no-overlay-lint     Suppress the advisory overlay-redeclaration AUTHORING lint
                         (never a gate — this lint can't fail the build)
+  --no-name-lint        Suppress the advisory node-name AUTHORING lint (whitespace
+                        in a name; never a gate — this lint can't fail the build)
+  --no-deprecation-lint Suppress the advisory deprecated-reference AUTHORING lint
+                        (never a gate — this lint can't fail the build)
   --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.
@@ -320,6 +340,10 @@ FLAGS:
   --no-requirement-lint Suppress the advisory requirement AUTHORING lint (not the gate)
   --no-overlay-lint     Suppress the advisory overlay-redeclaration AUTHORING lint —
                         never a gate; this lint can't fail the build
+  --no-name-lint        Suppress the advisory node-name AUTHORING lint (whitespace in
+                        a name) — never a gate; this lint can't fail the build
+  --no-deprecation-lint Suppress the advisory deprecated-reference AUTHORING lint —
+                        never a gate; this lint can't fail the build
   --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)
@@ -350,6 +374,21 @@ redeclaration lacks 'overlay: true' — today's default merge rule reuses it
 silently, but the same unflagged redeclaration silently becomes a NEW object
 the day the target is renamed or removed upstream. Warnings only — it can
 never fail the build. Opt out with --no-overlay-lint or META_NO_OVERLAY_LINT=1.
+
+verify also prints an ADVISORY node-name authoring lint, in its own section: any
+node (object, field, identity, relationship, ...) whose name contains whitespace.
+Leading or trailing whitespace is almost certainly a copy-paste accident — rename
+the node, and pin @column on a field whose physical column must keep its name.
+Requirement names are left to the requirement lint above. Warnings only — it can
+never fail the build. Opt out with --no-name-lint or META_NO_NAME_LINT=1.
+
+verify also prints an ADVISORY deprecated-reference authoring lint, in its own
+section: any node that depends on a node carrying the documentation @deprecated
+attr, via extends, @objectRef, @references, or an origin's @from/@of/@via. Where
+the deprecated node also carries @replacedBy, the finding names the replacement.
+A node referencing itself (a recursive FK, a same-entity passthrough) is not a
+finding. Warnings only — it can never fail the build. Opt out with
+--no-deprecation-lint or META_NO_DEPRECATION_LINT=1.
 `,
   export: `meta export — flatten loaded metadata to one canonical JSON artifact
 
@@ -359,6 +398,39 @@ USAGE:
 FLAGS:
   --out <file>          Write output to a file (default: stdout)
   --help, -h            Print this help
+`,
+  fmt: `meta fmt — rewrite metadata files into canonical form
+
+USAGE:
+  meta fmt [<file>...] [flags]
+
+Formats every JSON metadata file this project's resolved sources contain
+(resolveCollection() — never a hardcoded default directory), or just the
+files named. Each file is formatted as its OWN content (own-mode,
+declared-here layer only) — never inlining an inherited member or another
+file's overlay.
+
+FLAGS:
+  [<file>...]           Optional explicit file(s) — must be members of this project's
+                        resolved metadata sources; omit to format every one of them.
+  --check               List files that are not canonical and exit non-zero; changes
+                        nothing on disk.
+  --help, -h            Print this help
+
+SAFETY: before writing any file, fmt reloads the whole project with that file's
+candidate content swapped in and requires the loaded model's canonical form to
+be byte-identical to the untouched baseline. A file that fails this check is
+left exactly as it was and reported as an error — fmt never changes meaning.
+
+YAML: left untouched and reported as skipped — no canonical YAML emitter
+exists yet (ADR-0006: JSON is the canonical interchange form; YAML is an
+authoring format).
+
+OVERLAY: a file declaring 'overlay: true' ANYWHERE in its tree is reported as
+skipped — not only when no base exists in the same file. A formatter never
+changes structure: even when a same-file base IS present, merging it with
+the overlay (what the ordinary loader would do) would drop the overlay
+marker from the output, so fmt refuses that too and leaves the file as-is.
 `,
   docs: `meta docs — generate neutral metadata documentation (entity + template pages)
 
@@ -634,6 +706,10 @@ export async function run(argv: string[]): Promise<number> {
       const { exportCommand } = await import("./commands/export.js");
       return exportCommand(rest, cwd);
     }
+    case "fmt": {
+      const { fmtCommand } = await import("./commands/fmt.js");
+      return fmtCommand(rest, cwd);
+    }
     case "types": {
       const { typesCommand } = await import("./commands/types.js");
       return typesCommand(rest, explicitFormat);

package/src/lib/args.ts

@@ -190,6 +190,35 @@ export function parseExportArgs(argv: string[]): ExportFlags {
   };
 }
 
+// ---------------------------------------------------------------------------
+// fmt flags (#304)
+// ---------------------------------------------------------------------------
+
+export interface FmtFlags {
+  check: boolean;
+  /** Optional explicit file list — narrows the run to these files (must be
+   *  members of the project's resolved metadata sources). Empty = every file. */
+  files: string[];
+}
+
+/** The flag table `parseFmtArgs` parses. Exported so the help text can be gated against it. */
+export const FMT_OPTIONS = {
+  check: { type: "boolean", default: false },
+} as const;
+
+export function parseFmtArgs(argv: string[]): FmtFlags {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: FMT_OPTIONS,
+    strict: true,
+    allowPositionals: true,
+  });
+  return {
+    check: !!values.check,
+    files: positionals,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // shared DB-connection vocab (used by both verify --db and migrate)
 // ---------------------------------------------------------------------------
@@ -362,6 +391,20 @@ export interface VerifyFlags {
    * lint has no gate half at all — it can never fail the build).
    */
   noOverlayLint: boolean;
+  /**
+   * Suppress the advisory node-NAME authoring lint — whitespace in a node's
+   * `name` (a trailing space copied from legacy XML loads clean on every port).
+   * Advisory only, like its siblings: it has no gate half and can never fail
+   * the build.
+   */
+  noNameLint: boolean;
+  /**
+   * Suppress the advisory deprecated-REFERENCE authoring lint (#305) — a node
+   * depending (extends/@objectRef/@references/origin @from/@of/@via) on a
+   * `deprecated` node. Advisory only, like its siblings: it has no gate half
+   * and can never fail the build.
+   */
+  noDeprecationLint: boolean;
   /**
    * ADR-0023 strict-attr load opt-OUT (#96). `verify` is strict-by-default — an
    * undeclared/typo'd own `@attr` fails verify (ERR_UNKNOWN_ATTR). `--lax`
@@ -403,6 +446,8 @@ export const VERIFY_OPTIONS = {
   "no-antipatterns": { type: "boolean", default: false },
   "no-requirement-lint": { type: "boolean", default: false },
   "no-overlay-lint": { type: "boolean", default: false },
+  "no-name-lint": { type: "boolean", default: false },
+  "no-deprecation-lint": { type: "boolean", default: false },
   lax: { type: "boolean", default: false },
   "d1": { type: "string" },
   "remote": { type: "boolean", default: false },
@@ -487,6 +532,8 @@ export function parseVerifyArgs(argv: string[]): VerifyFlags {
     noAntipatterns: !!values["no-antipatterns"],
     noRequirementLint: !!values["no-requirement-lint"],
     noOverlayLint: !!values["no-overlay-lint"],
+    noNameLint: !!values["no-name-lint"],
+    noDeprecationLint: !!values["no-deprecation-lint"],
     lax: !!values.lax,
     d1: values.d1 as string | undefined,
     remote: !!values.remote,

package/src/lib/deprecation-lint.ts

@@ -0,0 +1,327 @@
+// `meta verify` — the deprecated-REFERENCE authoring lint (#305).
+//
+// `deprecated` / `replacedBy` are registered documentation common-attrs in every
+// port (doc-provider.ts) and nothing reads them: no validation pass, no `verify`
+// check, no codegen behavior. A deprecation you cannot enforce is a comment.
+//
+// Smallest useful version (approved scope): warn when a node DEPENDS on a node
+// carrying `deprecated`, through the reference kinds the metamodel already has —
+// `extends`, `@objectRef`, `@references`, and an origin's `@from` / `@of` / `@via`
+// path. Where the deprecated node also carries `replacedBy`, the diagnostic names
+// the replacement. Never fails the build — ADVISORY ONLY, the same discipline as
+// every sibling authoring lint in this directory (name-lint.ts, overlay-lint.ts,
+// requirement-lint.ts).
+//
+// Explicitly NOT in scope here (tracked separately): a deprecation DATE that
+// escalates warn -> error once passed, and per-finding suppressions with a
+// recorded reason (#302) — both need their own design.
+//
+// SELF-REFERENCE IS NOT A FINDING, but ONLY the literal case: the same node, or
+// one of the node's own ANCESTORS (the recursive-FK shape: `Category.parentId`
+// is a child of `Category` and points back at `Category` itself — not a
+// dependency on a different thing, it IS the deprecated thing). A DIFFERENT
+// node that merely happens to live under the same entity — e.g. a passthrough
+// field reading a DEPRECATED SIBLING field on its own entity — is a real
+// cross-node dependency and DOES warn; sharing an ancestor is not sharing an
+// identity. Guarded by `isSelfReference` below.
+//
+// Resolution reads the LOADED, FROZEN model only, via the RESOLVING accessors
+// (ADR-0039: `attr()`, `children()`, `superData`) — so a target that inherits
+// `deprecated` from its own abstract base still counts, and a reference
+// inherited through `extends` is reported once, at its declaration
+// (`ownChildren()`, the same sanctioned case name-lint.ts uses).
+
+import {
+  DOC_ATTR_DEPRECATED,
+  DOC_ATTR_REPLACED_BY,
+  TYPE_FIELD,
+  TYPE_IDENTITY,
+  TYPE_RELATIONSHIP,
+  TYPE_ORIGIN,
+  IDENTITY_SUBTYPE_REFERENCE,
+  IDENTITY_REFERENCE_ATTR_REFERENCES,
+  RELATIONSHIP_ATTR_OBJECT_REF,
+  FIELD_ATTR_OBJECT_REF,
+  // @via is spelled identically on every origin subtype (passthrough / aggregate /
+  // first); @of is identical on aggregate and first. One constant each, reused —
+  // see origin-constants.ts.
+  ORIGIN_PASSTHROUGH_ATTR_FROM,
+  ORIGIN_PASSTHROUGH_ATTR_VIA,
+  ORIGIN_AGGREGATE_ATTR_OF,
+  isMetaObject,
+  resolveObjectRef,
+  type MetaData,
+  type MetaObject,
+} from "@metaobjectsdev/metadata";
+import type { Diagnostic } from "./requirement-check.js";
+
+export const WARN_DEPRECATED_REFERENCE = "WARN_DEPRECATED_REFERENCE";
+
+function warn(path: string, message: string): Diagnostic {
+  return { severity: "warn", code: WARN_DEPRECATED_REFERENCE, path, message };
+}
+
+// ---------------------------------------------------------------------------
+// addressing — mirrors name-lint.ts's topLevelAddress/segment, applied to every
+// node (not only ones whose own name is the finding).
+// ---------------------------------------------------------------------------
+
+function packageOf(node: MetaData): string {
+  return node.package ?? node.fileDefaultPackage ?? "";
+}
+
+/** Walk up to the nearest enclosing `object.*` — every field/identity/relationship/
+ *  origin is nested under exactly one (objects are never nested in this metamodel). */
+function owningObject(node: MetaData): MetaObject | undefined {
+  let cur: MetaData | undefined = node.parent;
+  while (cur !== undefined && !isMetaObject(cur)) cur = cur.parent;
+  return cur;
+}
+
+/** A human-readable address for a node: the object's FQN, or `<object FQN>.<name>` for
+ *  something nested inside one. Falls back to the bare name (an abstract field
+ *  declared at root, outside any object) when there is no enclosing object. */
+function addressOf(node: MetaData): string {
+  if (isMetaObject(node)) return node.resolutionKey();
+  const owner = owningObject(node);
+  return owner !== undefined ? `${owner.resolutionKey()}.${node.name}` : node.name;
+}
+
+// ---------------------------------------------------------------------------
+// self-reference guard
+// ---------------------------------------------------------------------------
+
+function isAncestorOf(maybeAncestor: MetaData, node: MetaData): boolean {
+  let cur: MetaData | undefined = node.parent;
+  while (cur !== undefined) {
+    if (cur === maybeAncestor) return true;
+    cur = cur.parent;
+  }
+  return false;
+}
+
+/**
+ * True when `target` is not really an OTHER node from `referrer`'s point of
+ * view: the same node, or an ANCESTOR of it (the referrer's own enclosing
+ * object/field — the recursive-FK shape). Deliberately NOT symmetric: a
+ * DESCENDANT of `referrer` is a real, different thing to depend on (and no
+ * call site here ever resolves a target nested inside the specific referrer
+ * node anyway — a sibling field, the common case, is nested in the shared
+ * parent ENTITY, not in the referrer).
+ */
+function isSelfReference(referrer: MetaData, target: MetaData): boolean {
+  return referrer === target || isAncestorOf(target, referrer);
+}
+
+// ---------------------------------------------------------------------------
+// the check: does `target` carry `deprecated`, resolved?
+// ---------------------------------------------------------------------------
+
+/** Returns true when a finding was pushed — callers checking a MORE SPECIFIC
+ *  target first (e.g. a field) use this to decide whether to also check the
+ *  less-specific one (its entity): only when the specific one was silent. */
+function considerTarget(referrer: MetaData, referrerPath: string, verb: string, target: MetaData, out: Diagnostic[]): boolean {
+  if (isSelfReference(referrer, target)) return false;
+  // Registry contract (documentation-definition.embedded.ts): "Presence ⇒
+  // deprecated" — an empty-string reason still means deprecated (codegen-ts's
+  // jsdoc.ts reads it the same way, via `!== undefined`, not a truthiness
+  // check). Only an ABSENT attr (undefined) means "not deprecated".
+  const reason = target.attr(DOC_ATTR_DEPRECATED);
+  if (typeof reason !== "string") return false;
+  const replacedByRaw = target.attr(DOC_ATTR_REPLACED_BY);
+  const replacedBy = typeof replacedByRaw === "string" && replacedByRaw !== "" ? replacedByRaw : undefined;
+  const targetKind = `${target.type}.${target.subType}`;
+  const reasonClause = reason !== "" ? `: ${reason}` : "";
+  out.push(
+    warn(
+      referrerPath,
+      `${verb} deprecated ${targetKind} ${addressOf(target)}${reasonClause}` +
+        (replacedBy !== undefined ? ` Replaced by ${replacedBy}.` : ""),
+    ),
+  );
+  return true;
+}
+
+/** Split a dotted reference into its entity HEAD and member tail ("Entity.field" ->
+ *  "Entity" / "field"). `@objectRef` carries no tail (a pure object ref) and is
+ *  resolved whole by the caller; `@references`/`@from`/`@of`/`@via` do. */
+function headOf(raw: string): string {
+  const dot = raw.indexOf(".");
+  return dot === -1 ? raw : raw.slice(0, dot);
+}
+
+function resolveEntityRef(root: MetaData, ref: string, referrerPkg: string): MetaObject | undefined {
+  const node = resolveObjectRef(root, ref, referrerPkg).node;
+  return node !== undefined && isMetaObject(node) ? node : undefined;
+}
+
+/** The relationship / identity.reference CHILD on `entity` named `hopName` — a
+ *  `@via` path segment. Resolving `children()` (ADR-0039): an inherited hop still
+ *  counts. */
+function findHop(entity: MetaObject, hopName: string): MetaData | undefined {
+  return entity.children().find(
+    (c) =>
+      (c.type === TYPE_RELATIONSHIP || (c.type === TYPE_IDENTITY && c.subType === IDENTITY_SUBTYPE_REFERENCE)) &&
+      c.name === hopName,
+  );
+}
+
+/** The entity a resolved hop (relationship or identity.reference) points at, raw. */
+function hopTargetRef(hop: MetaData): string | undefined {
+  const v = hop.type === TYPE_RELATIONSHIP
+    ? hop.attr(RELATIONSHIP_ATTR_OBJECT_REF)
+    : hop.attr(IDENTITY_REFERENCE_ATTR_REFERENCES);
+  return typeof v === "string" && v !== "" ? headOf(v) : undefined;
+}
+
+/**
+ * Check a dotted "Entity" or "Entity.field" reference — shared by origin
+ * `@from`/`@of` AND identity.reference's `@references` (ADR-0042 §5: the
+ * dotted form is not origin-specific; `Team.code` names an explicit FK target
+ * field exactly the way `Country.name` names a passthrough source field — see
+ * `fixtures/conformance/relationship-one-two-refs-dotted-references/`). The
+ * field is the more specific target (checked first); the entity is checked
+ * independently so a field on an otherwise-fine entity, OR a whole deprecated
+ * entity, each warn. Resolution failure (either half) is silent — bias to
+ * under-flagging, the same stance every sibling advisory pass in this
+ * directory takes.
+ */
+function checkEntityFieldPath(
+  root: MetaData,
+  referrer: MetaData,
+  referrerPath: string,
+  verb: string,
+  raw: string,
+  referrerPkg: string,
+  out: Diagnostic[],
+): void {
+  const head = headOf(raw);
+  const entity = resolveEntityRef(root, head, referrerPkg);
+  if (entity === undefined) return;
+  const fieldName = raw.slice(head.length + 1);
+  const field = fieldName !== "" ? entity.fields().find((f) => f.name === fieldName) : undefined;
+  if (field !== undefined && considerTarget(referrer, referrerPath, verb, field, out)) {
+    return; // the field itself is the deprecated thing — don't ALSO warn about its (fine) entity.
+  }
+  considerTarget(referrer, referrerPath, verb, entity, out);
+}
+
+/**
+ * Walk an origin `@via` relationship path ("Entity.relOrRef[.relOrRef...]"),
+ * checking the head entity and every hop it names. Stops silently the moment a
+ * segment fails to resolve — a half-walked path still warned on everything it
+ * DID resolve, which is the right bias for an advisory that must never crash
+ * `meta verify` on a path shape it does not fully understand.
+ */
+function checkViaPath(
+  root: MetaData,
+  origin: MetaData,
+  referrerPath: string,
+  verb: string,
+  via: string,
+  referrerPkg: string,
+  out: Diagnostic[],
+): void {
+  const segments = via.split(".");
+  const headSegment = segments[0];
+  if (headSegment === undefined || headSegment === "") return;
+  let current = resolveEntityRef(root, headSegment, referrerPkg);
+  if (current === undefined) return;
+  considerTarget(origin, referrerPath, verb, current, out);
+  for (const hopName of segments.slice(1)) {
+    const hop = findHop(current, hopName);
+    if (hop === undefined) return;
+    considerTarget(origin, referrerPath, verb, hop, out);
+    const targetRef = hopTargetRef(hop);
+    if (targetRef === undefined) return;
+    const next = resolveEntityRef(root, targetRef, packageOf(current));
+    if (next === undefined) return;
+    considerTarget(origin, referrerPath, verb, next, out);
+    current = next;
+  }
+}
+
+function checkOrigin(root: MetaData, origin: MetaData, referrerPath: string, out: Diagnostic[]): void {
+  const referrerPkg = (() => {
+    const owner = owningObject(origin);
+    return owner !== undefined ? packageOf(owner) : "";
+  })();
+  const subtypeLabel = `origin.${origin.subType}`;
+
+  // ADR-0039: own — origin.* never inherits (ADR-0029), so own is correct (the
+  // same stance every origin accessor in meta-origin.ts takes).
+  const from = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_FROM);
+  if (typeof from === "string" && from !== "") {
+    checkEntityFieldPath(root, origin, referrerPath, `${subtypeLabel} @from references`, from, referrerPkg, out);
+  }
+  const of_ = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_OF);
+  if (typeof of_ === "string" && of_ !== "") {
+    checkEntityFieldPath(root, origin, referrerPath, `${subtypeLabel} @of references`, of_, referrerPkg, out);
+  }
+  const via = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_VIA);
+  if (typeof via === "string" && via !== "") {
+    checkViaPath(root, origin, referrerPath, `${subtypeLabel} @via references`, via, referrerPkg, out);
+  }
+}
+
+function checkNode(root: MetaData, node: MetaData, path: string, out: Diagnostic[]): void {
+  // extends — every node type may carry a resolved super (generic, type-agnostic).
+  if (node.superData !== undefined) {
+    considerTarget(node, path, "extends", node.superData, out);
+  }
+
+  // @objectRef — relationship.* (its target object) and field.object/value (a
+  // value-typed field's own objectRef). Same attr name on both (naming-refs.ts).
+  if (node.type === TYPE_RELATIONSHIP || node.type === TYPE_FIELD) {
+    const ref = node.attr(node.type === TYPE_RELATIONSHIP ? RELATIONSHIP_ATTR_OBJECT_REF : FIELD_ATTR_OBJECT_REF);
+    if (typeof ref === "string" && ref !== "") {
+      const owner = owningObject(node);
+      const target = resolveEntityRef(root, ref, owner !== undefined ? packageOf(owner) : "");
+      if (target !== undefined) considerTarget(node, path, "references (@objectRef)", target, out);
+    }
+  }
+
+  // @references — identity.reference's FK target. May be bare ("Entity",
+  // defaulting to the primary identity) or dotted ("Entity.field" /
+  // "Entity.fieldA,fieldB", an explicit field/compound target) — the dotted
+  // field half is a deprecation-relevant target in its own right (#305 review:
+  // `@references: "Team.code"` where only `code` is `@deprecated` was missed
+  // when this checked the entity head alone).
+  if (node.type === TYPE_IDENTITY && node.subType === IDENTITY_SUBTYPE_REFERENCE) {
+    const raw = node.attr(IDENTITY_REFERENCE_ATTR_REFERENCES);
+    if (typeof raw === "string" && raw !== "") {
+      const owner = owningObject(node);
+      checkEntityFieldPath(root, node, path, "references (@references)", raw, owner !== undefined ? packageOf(owner) : "", out);
+    }
+  }
+
+  // origin.* — @from / @of / @via.
+  if (node.type === TYPE_ORIGIN) {
+    checkOrigin(root, node, path, out);
+  }
+}
+
+/**
+ * Lint the loaded model for references INTO a `deprecated` node, across every
+ * reference kind the metamodel resolves: `extends`, `@objectRef`, `@references`,
+ * and an origin's `@from` / `@of` / `@via`. Returns `[]` for a model with no
+ * `deprecated` attr anywhere reachable from a reference (additive, opt-in).
+ */
+export function lintDeprecatedReferences(root: MetaData): Diagnostic[] {
+  const out: Diagnostic[] = [];
+  const walk = (n: MetaData, prefix: string): void => {
+    for (const c of n.ownChildren()) {
+      // origin carries no name of its own (always a singleton child of a field) —
+      // report against the FIELD it belongs to, not a path ending in a blank segment.
+      const path = c.type === TYPE_ORIGIN
+        ? prefix
+        : prefix === ""
+          ? c.resolutionKey()
+          : `${prefix}.${c.name}`;
+      checkNode(root, c, path, out);
+      walk(c, path);
+    }
+  };
+  walk(root, "");
+  return out;
+}

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

@@ -96,7 +96,10 @@ export function scanForUnindexedForeignKeys(root: MetaData, opts: UnindexedFkOpt
       });
       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("")}`;
+      // Entity-prefixed: an index name is schema-wide in Postgres, so a bare `by<Field>`
+      // suggested the SAME name to every entity sharing the FK field, and applying the advice
+      // verbatim failed `meta migrate` with ERR_DUPLICATE_SQL_NAME.
+      const indexName = `${entity.name.charAt(0).toLowerCase()}${entity.name.slice(1)}By${fields.map(pascal).join("")}`;
       const fieldList = fields.length === 1 ? fields[0]! : `[${fields.join(", ")}]`;
       out.push({
         file: files[0] ?? "",