@metaobjectsdev/metadata 1.0.10 → 1.0.12

package/dist/fmt.d.ts

@@ -0,0 +1,31 @@
+import type { TypeRegistry } from "./registry.js";
+export interface FormatFileOptions {
+    /** The registry this project loads against — core providers plus any the
+     *  project's own config registers, so a custom attr never false-positives. */
+    readonly registry: TypeRegistry;
+    /** ADR-0023 strict-attr loading. Default false (lenient), matching `meta gen`
+     *  rather than `meta verify` — fmt reformats whatever already loads; an
+     *  unrecognized `@attr` is `verify`'s job to flag, not fmt's to refuse on. */
+    readonly strict?: boolean;
+    /** The source id this file's nodes record provenance under — normally the
+     *  same id the full project load would use (basename, or a dependency's
+     *  `dep:<name>/<artifact>` id). Used only for error messages here. */
+    readonly sourceId: string;
+}
+export type FormatFileResult = {
+    readonly ok: true;
+    readonly text: string;
+} | {
+    readonly ok: false;
+    readonly overlay: boolean;
+    readonly message: string;
+};
+/**
+ * Format one file's own content into canonical JSON. Parses `content`
+ * standalone (no `intoRoot` — never merged with any other file) and, on a
+ * clean parse, returns the canonical serialization of the resulting file
+ * root. Never throws: a JSON syntax error, a structural parse error, or any
+ * `overlay: true` declaration all come back as `{ ok: false }`.
+ */
+export declare function formatMetadataFile(content: string, opts: FormatFileOptions): FormatFileResult;
+//# sourceMappingURL=fmt.d.ts.map

package/dist/fmt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fmt.d.ts","sourceRoot":"","sources":["../src/fmt.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,MAAM,WAAW,iBAAiB;IAChC;kFAC8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC;;kFAE8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;0EAEsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAiDhF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,gBAAgB,CAoD7F"}

package/dist/fmt.js

@@ -0,0 +1,144 @@
+// meta fmt (#304) — format a single metadata FILE's own content.
+//
+// The canonical serializer (serializer-json.ts) already produces deterministic,
+// cross-port byte-identical JSON for a loaded MetaData node — that is what the
+// conformance corpora byte-match against. `meta fmt` surfaces it as a per-file
+// formatter: each file is parsed STANDALONE (never merged with its siblings)
+// and re-emitted via `canonicalSerialize`, so the output is strictly that
+// file's own declared content — own-mode, declared-here layer only (ADR-0039).
+//
+// Two properties fall out of parsing a file standalone rather than loading the
+// whole project and slicing the merged tree:
+//
+//   - A cross-file `extends` ref (the common `extends: "BaseEntity"` pattern,
+//     where the base lives in another file) is never an error here: super
+//     resolution is deferred and this module never runs the second pass that
+//     would fail an UNRESOLVED ref. Own-mode serialization only needs the raw
+//     `superRef` string, never the resolved target.
+//   - A file declaring `overlay: true` ANYWHERE in its tree is never
+//     formatted — reported as `overlay: true` so a caller can leave it
+//     untouched rather than guess at a merge. This is true REGARDLESS of
+//     whether a same-(type,name) base exists elsewhere in the file: a
+//     formatter must never change STRUCTURE, and buildTree's ordinary
+//     find-or-reuse behavior would happily fold a plain declaration and a
+//     same-file `overlay: true` redeclaration into one merged node —
+//     silently dropping the overlay marker from the output. Checking the
+//     raw document for `overlay: true` BEFORE buildTree ever runs (see
+//     `hasOverlayDeclaration` below) catches that case too, not just the
+//     no-local-target one buildTree's own ERR_OVERLAY_NO_TARGET reports. A
+//     MIXED file (plain + overlay declarations together, anywhere) is
+//     reported as `overlay: true` too — fmt does not partially format a file.
+import { buildTree } from "./parser-core.js";
+import { canonicalSerialize } from "./serializer-json.js";
+import { JSON_KEY_SCHEMA, RESERVED_KEY_CHILDREN, RESERVED_KEY_OVERLAY } from "./shared/structural.js";
+/** The code `buildTree`'s overlay drain raises when a queued `overlay: true`
+ *  declaration finds no same-(type,name) base in the tree being built — here,
+ *  always because the base lives in a file this standalone parse never sees.
+ *  Kept as a defensive second signal; `hasOverlayDeclaration` below is what
+ *  actually decides the common case (a local base DOES exist). */
+const OVERLAY_NO_TARGET_CODE = "ERR_OVERLAY_NO_TARGET";
+/**
+ * Whether `doc` (an already-`JSON.parse`d canonical document) declares an
+ * `overlay: true` node anywhere in its tree — the top-level declaration
+ * itself, or any descendant reached by walking `children` arrays.
+ *
+ * A purely STRUCTURAL check, independent of the registry and run BEFORE
+ * `buildTree`: fmt must never attempt a same-file merge of a plain
+ * declaration and an `overlay: true` redeclaration of the same (type, name)
+ * — buildTree's ordinary find-or-reuse behavior would silently fold the two
+ * into one node, dropping the overlay marker, which is exactly the
+ * "formatter changes structure" outcome `meta fmt` must never produce. This
+ * catches that case (a local base exists) as well as the no-target one
+ * buildTree's own `ERR_OVERLAY_NO_TARGET` reports — the two are the same
+ * refusal from a caller's point of view: this file is not fmt's to format.
+ */
+function hasOverlayDeclaration(doc) {
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc))
+        return false;
+    for (const [key, body] of Object.entries(doc)) {
+        if (key === JSON_KEY_SCHEMA)
+            continue;
+        if (typeof body !== "object" || body === null || Array.isArray(body))
+            continue;
+        if (bodyHasOverlay(body))
+            return true;
+    }
+    return false;
+}
+function bodyHasOverlay(body) {
+    const children = body[RESERVED_KEY_CHILDREN];
+    if (!Array.isArray(children))
+        return false;
+    for (const child of children) {
+        if (typeof child !== "object" || child === null || Array.isArray(child))
+            continue;
+        for (const childBody of Object.values(child)) {
+            if (typeof childBody !== "object" || childBody === null || Array.isArray(childBody))
+                continue;
+            const cb = childBody;
+            if (cb[RESERVED_KEY_OVERLAY] === true)
+                return true;
+            if (bodyHasOverlay(cb))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Format one file's own content into canonical JSON. Parses `content`
+ * standalone (no `intoRoot` — never merged with any other file) and, on a
+ * clean parse, returns the canonical serialization of the resulting file
+ * root. Never throws: a JSON syntax error, a structural parse error, or any
+ * `overlay: true` declaration all come back as `{ ok: false }`.
+ */
+export function formatMetadataFile(content, opts) {
+    // Strip a UTF-8 BOM before parsing (mirrors parseJson's own front-end,
+    // parser-json.ts) — a BOM-prefixed file is otherwise a flat JSON.parse
+    // syntax error, and Java-authored files often carry one.
+    const normalized = content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
+    let parsed;
+    try {
+        parsed = JSON.parse(normalized);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            overlay: false,
+            message: `invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (hasOverlayDeclaration(parsed)) {
+        return {
+            ok: false,
+            overlay: true,
+            message: "this file declares an overlay fmt cannot resolve standalone",
+        };
+    }
+    try {
+        const result = buildTree(parsed, {
+            registry: opts.registry,
+            strict: opts.strict ?? false,
+            sourceName: opts.sourceId,
+            // Never resolved here — see module header. A cross-file `extends` must
+            // not become an error just because this file is formatted in isolation.
+            deferSuperResolution: true,
+        });
+        if (result.errors.length > 0) {
+            const overlay = result.errors.some((e) => e.code === OVERLAY_NO_TARGET_CODE);
+            return {
+                ok: false,
+                overlay,
+                message: result.errors.map((e) => e.message).join("; "),
+            };
+        }
+        return { ok: true, text: canonicalSerialize(result.root) };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            overlay: false,
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+//# sourceMappingURL=fmt.js.map

package/dist/fmt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fmt.js","sourceRoot":"","sources":["../src/fmt.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -92,6 +92,8 @@ export type { ParseOptions, ParseResult } from "./parser-core.js";
 export { parseJson } from "./parser-json.js";
 export { serializeJson, canonicalSerialize, canonicalSerializeEffective, serializeSharedDocument, inferAttrSubType } from "./serializer-json.js";
 export type { SerializeOptions } from "./serializer-json.js";
+export { formatMetadataFile } from "./fmt.js";
+export type { FormatFileOptions, FormatFileResult } from "./fmt.js";
 export { resolveSuperRef } from "./super-resolve.js";
 export { expandRef, isRelativeRef, refMatchesObject, resolveObjectRef, didYouMeanHint, REF_BEARING_ATTR_NAMES } from "./naming-refs.js";
 export { MetaDataLoader, declaredTopLevelKeys } from "./loader/meta-data-loader.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -117,6 +117,8 @@ export { buildTree } from "./parser-core.js";
 export { parseJson } from "./parser-json.js";
 // Serializer
 export { serializeJson, canonicalSerialize, canonicalSerializeEffective, serializeSharedDocument, inferAttrSubType } from "./serializer-json.js";
+// Formatter (#304) — per-file canonical formatting, built on the serializer above.
+export { formatMetadataFile } from "./fmt.js";
 // Super resolution helper (most resolution moved into parser; this is the lookup utility)
 export { resolveSuperRef } from "./super-resolve.js";
 // FR-032 (ADR-0032) — canonical reference expansion + FQN object matching.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/metadata",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Metamodel loader, types, and constants for the MetaObjects standard.",
   "type": "module",
   "main": "./dist/index.js",

package/src/fmt.ts

@@ -0,0 +1,160 @@
+// meta fmt (#304) — format a single metadata FILE's own content.
+//
+// The canonical serializer (serializer-json.ts) already produces deterministic,
+// cross-port byte-identical JSON for a loaded MetaData node — that is what the
+// conformance corpora byte-match against. `meta fmt` surfaces it as a per-file
+// formatter: each file is parsed STANDALONE (never merged with its siblings)
+// and re-emitted via `canonicalSerialize`, so the output is strictly that
+// file's own declared content — own-mode, declared-here layer only (ADR-0039).
+//
+// Two properties fall out of parsing a file standalone rather than loading the
+// whole project and slicing the merged tree:
+//
+//   - A cross-file `extends` ref (the common `extends: "BaseEntity"` pattern,
+//     where the base lives in another file) is never an error here: super
+//     resolution is deferred and this module never runs the second pass that
+//     would fail an UNRESOLVED ref. Own-mode serialization only needs the raw
+//     `superRef` string, never the resolved target.
+//   - A file declaring `overlay: true` ANYWHERE in its tree is never
+//     formatted — reported as `overlay: true` so a caller can leave it
+//     untouched rather than guess at a merge. This is true REGARDLESS of
+//     whether a same-(type,name) base exists elsewhere in the file: a
+//     formatter must never change STRUCTURE, and buildTree's ordinary
+//     find-or-reuse behavior would happily fold a plain declaration and a
+//     same-file `overlay: true` redeclaration into one merged node —
+//     silently dropping the overlay marker from the output. Checking the
+//     raw document for `overlay: true` BEFORE buildTree ever runs (see
+//     `hasOverlayDeclaration` below) catches that case too, not just the
+//     no-local-target one buildTree's own ERR_OVERLAY_NO_TARGET reports. A
+//     MIXED file (plain + overlay declarations together, anywhere) is
+//     reported as `overlay: true` too — fmt does not partially format a file.
+import { buildTree } from "./parser-core.js";
+import { canonicalSerialize } from "./serializer-json.js";
+import type { TypeRegistry } from "./registry.js";
+import { JSON_KEY_SCHEMA, RESERVED_KEY_CHILDREN, RESERVED_KEY_OVERLAY } from "./shared/structural.js";
+
+export interface FormatFileOptions {
+  /** The registry this project loads against — core providers plus any the
+   *  project's own config registers, so a custom attr never false-positives. */
+  readonly registry: TypeRegistry;
+  /** ADR-0023 strict-attr loading. Default false (lenient), matching `meta gen`
+   *  rather than `meta verify` — fmt reformats whatever already loads; an
+   *  unrecognized `@attr` is `verify`'s job to flag, not fmt's to refuse on. */
+  readonly strict?: boolean;
+  /** The source id this file's nodes record provenance under — normally the
+   *  same id the full project load would use (basename, or a dependency's
+   *  `dep:<name>/<artifact>` id). Used only for error messages here. */
+  readonly sourceId: string;
+}
+
+export type FormatFileResult =
+  | { readonly ok: true; readonly text: string }
+  | { readonly ok: false; readonly overlay: boolean; readonly message: string };
+
+/** The code `buildTree`'s overlay drain raises when a queued `overlay: true`
+ *  declaration finds no same-(type,name) base in the tree being built — here,
+ *  always because the base lives in a file this standalone parse never sees.
+ *  Kept as a defensive second signal; `hasOverlayDeclaration` below is what
+ *  actually decides the common case (a local base DOES exist). */
+const OVERLAY_NO_TARGET_CODE = "ERR_OVERLAY_NO_TARGET";
+
+/**
+ * Whether `doc` (an already-`JSON.parse`d canonical document) declares an
+ * `overlay: true` node anywhere in its tree — the top-level declaration
+ * itself, or any descendant reached by walking `children` arrays.
+ *
+ * A purely STRUCTURAL check, independent of the registry and run BEFORE
+ * `buildTree`: fmt must never attempt a same-file merge of a plain
+ * declaration and an `overlay: true` redeclaration of the same (type, name)
+ * — buildTree's ordinary find-or-reuse behavior would silently fold the two
+ * into one node, dropping the overlay marker, which is exactly the
+ * "formatter changes structure" outcome `meta fmt` must never produce. This
+ * catches that case (a local base exists) as well as the no-target one
+ * buildTree's own `ERR_OVERLAY_NO_TARGET` reports — the two are the same
+ * refusal from a caller's point of view: this file is not fmt's to format.
+ */
+function hasOverlayDeclaration(doc: unknown): boolean {
+  if (typeof doc !== "object" || doc === null || Array.isArray(doc)) return false;
+  for (const [key, body] of Object.entries(doc as Record<string, unknown>)) {
+    if (key === JSON_KEY_SCHEMA) continue;
+    if (typeof body !== "object" || body === null || Array.isArray(body)) continue;
+    if (bodyHasOverlay(body as Record<string, unknown>)) return true;
+  }
+  return false;
+}
+
+function bodyHasOverlay(body: Record<string, unknown>): boolean {
+  const children = body[RESERVED_KEY_CHILDREN];
+  if (!Array.isArray(children)) return false;
+  for (const child of children) {
+    if (typeof child !== "object" || child === null || Array.isArray(child)) continue;
+    for (const childBody of Object.values(child as Record<string, unknown>)) {
+      if (typeof childBody !== "object" || childBody === null || Array.isArray(childBody)) continue;
+      const cb = childBody as Record<string, unknown>;
+      if (cb[RESERVED_KEY_OVERLAY] === true) return true;
+      if (bodyHasOverlay(cb)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Format one file's own content into canonical JSON. Parses `content`
+ * standalone (no `intoRoot` — never merged with any other file) and, on a
+ * clean parse, returns the canonical serialization of the resulting file
+ * root. Never throws: a JSON syntax error, a structural parse error, or any
+ * `overlay: true` declaration all come back as `{ ok: false }`.
+ */
+export function formatMetadataFile(content: string, opts: FormatFileOptions): FormatFileResult {
+  // Strip a UTF-8 BOM before parsing (mirrors parseJson's own front-end,
+  // parser-json.ts) — a BOM-prefixed file is otherwise a flat JSON.parse
+  // syntax error, and Java-authored files often carry one.
+  const normalized = content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(normalized);
+  } catch (err) {
+    return {
+      ok: false,
+      overlay: false,
+      message: `invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  if (hasOverlayDeclaration(parsed)) {
+    return {
+      ok: false,
+      overlay: true,
+      message: "this file declares an overlay fmt cannot resolve standalone",
+    };
+  }
+
+  try {
+    const result = buildTree(parsed, {
+      registry: opts.registry,
+      strict: opts.strict ?? false,
+      sourceName: opts.sourceId,
+      // Never resolved here — see module header. A cross-file `extends` must
+      // not become an error just because this file is formatted in isolation.
+      deferSuperResolution: true,
+    });
+
+    if (result.errors.length > 0) {
+      const overlay = result.errors.some((e) => e.code === OVERLAY_NO_TARGET_CODE);
+      return {
+        ok: false,
+        overlay,
+        message: result.errors.map((e) => e.message).join("; "),
+      };
+    }
+
+    return { ok: true, text: canonicalSerialize(result.root) };
+  } catch (err) {
+    return {
+      ok: false,
+      overlay: false,
+      message: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/src/index.ts

@@ -243,6 +243,10 @@ export { parseJson } from "./parser-json.js";
 export { serializeJson, canonicalSerialize, canonicalSerializeEffective, serializeSharedDocument, inferAttrSubType } from "./serializer-json.js";
 export type { SerializeOptions } from "./serializer-json.js";
 
+// Formatter (#304) — per-file canonical formatting, built on the serializer above.
+export { formatMetadataFile } from "./fmt.js";
+export type { FormatFileOptions, FormatFileResult } from "./fmt.js";
+
 // Super resolution helper (most resolution moved into parser; this is the lookup utility)
 export { resolveSuperRef } from "./super-resolve.js";