@metaobjectsdev/cli 1.0.11 → 1.0.13

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/fmt-engine.ts

@@ -0,0 +1,179 @@
+// server/typescript/packages/cli/src/lib/fmt-engine.ts
+//
+// `meta fmt` (#304) orchestration: resolve the project's own metadata files
+// (resolveCollection — never a hardcoded `metaobjects/`), format each one
+// standalone (@metaobjectsdev/metadata's formatMetadataFile — own-mode,
+// declared-here layer only), and gate every rewrite behind a whole-project
+// reload-and-compare safety check before it ever touches disk.
+//
+// The safety check (design rule 4): swap a candidate in via an in-memory
+// source carrying the SAME file id the real load would use, reload the WHOLE
+// project, and require both that it loads with no errors AND that its
+// canonical serialization is byte-identical to the untouched baseline. Only
+// then is the candidate written — so `--check` (which skips the write) and a
+// real run share one code path, and a bug in the formatter can only ever
+// leave a file unchanged plus an error, never a corrupted file.
+import { basename, extname, resolve as resolvePath } from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
+import type { MetaDataTypeProvider } from "@metaobjectsdev/metadata";
+import {
+  composeRegistry,
+  MetaDataLoader,
+  InMemoryStringSource,
+  canonicalSerialize,
+  formatMetadataFile,
+} from "@metaobjectsdev/metadata";
+import { FileSource } from "@metaobjectsdev/metadata/core";
+import { resolveCollection, defaultLoadMemoryProviders, type Collection } from "@metaobjectsdev/sdk";
+import { loadMetaobjectsConfig, loadMemoryOptionsFrom } from "./load-metaobjects-config.js";
+
+export type FmtFileStatus =
+  | "formatted"
+  | "would-format"
+  | "unchanged"
+  | "skipped-yaml"
+  | "skipped-overlay"
+  | "error";
+
+export interface FmtFileReport {
+  readonly path: string;
+  readonly status: FmtFileStatus;
+  readonly detail?: string;
+}
+
+export interface FmtRunResult {
+  readonly files: readonly FmtFileReport[];
+  /** Set when the run could not even start — an unresolvable collection, an
+   *  explicit file argument outside the project's sources, or metadata that
+   *  does not currently load cleanly. Nothing was attempted. */
+  readonly fatal?: string;
+}
+
+export interface FmtRunOptions {
+  readonly projectRoot: string;
+  readonly check: boolean;
+  /** Explicit paths (cwd-relative or absolute) narrowing the run. Omit/empty
+   *  for every file the project owns. */
+  readonly files?: readonly string[];
+}
+
+async function projectProviders(collection: Collection): Promise<readonly MetaDataTypeProvider[]> {
+  try {
+    const cfg = await loadMetaobjectsConfig(collection.configDir);
+    return loadMemoryOptionsFrom(cfg).providers ?? [];
+  } catch {
+    // No metaobjects.config.ts (common for a non-TS-server project running
+    // `meta fmt` just for schema-neutral formatting) — format against the
+    // core vocabulary only, exactly like a project with no custom providers.
+    return [];
+  }
+}
+
+export async function runFmt(opts: FmtRunOptions): Promise<FmtRunResult> {
+  let collection: Collection;
+  try {
+    collection = await resolveCollection(opts.projectRoot);
+  } catch (err) {
+    return { files: [], fatal: err instanceof Error ? err.message : String(err) };
+  }
+
+  const providers = await projectProviders(collection);
+  const registry = composeRegistry([...defaultLoadMemoryProviders, ...providers]);
+
+  let targets: readonly string[];
+  if (opts.files !== undefined && opts.files.length > 0) {
+    const want = new Set(opts.files.map((f) => resolvePath(opts.projectRoot, f)));
+    const owned = new Set(collection.ownFiles);
+    const missing = [...want].filter((f) => !owned.has(f));
+    if (missing.length > 0) {
+      return {
+        files: [],
+        fatal:
+          `not among this project's resolved metadata sources: ${missing.join(", ")}\n` +
+          "meta fmt only formats files resolveCollection() already resolves — pass no " +
+          "arguments to format every one of them.",
+      };
+    }
+    targets = collection.ownFiles.filter((f) => want.has(f));
+  } else {
+    targets = collection.ownFiles;
+  }
+
+  const sourceId = (p: string): string => collection.fileIds.get(p) ?? basename(p);
+
+  const libSources =
+    collection.libraries.length > 0
+      ? (await import("@metaobjectsdev/metadata/library")).librarySources([...collection.libraries])
+      : [];
+
+  const buildSources = (overridePath?: string, overrideText?: string) => [
+    ...libSources,
+    ...collection.files.map((p) => {
+      const id = sourceId(p);
+      return overridePath !== undefined && p === overridePath
+        ? new InMemoryStringSource(overrideText ?? "", { id })
+        : new FileSource(p, { id });
+    }),
+  ];
+
+  const baseline = await new MetaDataLoader({ registry }).load(buildSources());
+  if (baseline.errors.length > 0) {
+    return {
+      files: [],
+      fatal:
+        "this project's metadata does not currently load cleanly — fix the error(s) below, " +
+        "then re-run fmt:\n" +
+        baseline.errors.map((e) => `  ${e.message}`).join("\n"),
+    };
+  }
+  const baselineCanonical = canonicalSerialize(baseline.root);
+
+  const reports: FmtFileReport[] = [];
+  for (const path of targets) {
+    const ext = extname(path).toLowerCase();
+    if (ext === ".yaml" || ext === ".yml") {
+      reports.push({
+        path,
+        status: "skipped-yaml",
+        detail: "no canonical YAML emitter exists (ADR-0006: JSON is the canonical interchange form) — left untouched",
+      });
+      continue;
+    }
+
+    const content = await readFile(path, "utf8");
+    const formatted = formatMetadataFile(content, { registry, sourceId: sourceId(path) });
+    if (!formatted.ok) {
+      reports.push(
+        formatted.overlay
+          ? { path, status: "skipped-overlay", detail: formatted.message }
+          : { path, status: "error", detail: formatted.message },
+      );
+      continue;
+    }
+
+    if (formatted.text === content) {
+      reports.push({ path, status: "unchanged" });
+      continue;
+    }
+
+    const testLoad = await new MetaDataLoader({ registry }).load(buildSources(path, formatted.text));
+    const safe = testLoad.errors.length === 0 && canonicalSerialize(testLoad.root) === baselineCanonical;
+    if (!safe) {
+      reports.push({
+        path,
+        status: "error",
+        detail: "formatting this file would change the loaded model's meaning — left unchanged",
+      });
+      continue;
+    }
+
+    if (opts.check) {
+      reports.push({ path, status: "would-format" });
+    } else {
+      await writeFile(path, formatted.text, "utf8");
+      reports.push({ path, status: "formatted" });
+    }
+  }
+
+  return { files: reports };
+}