@metaobjectsdev/metadata 0.5.0-rc.1

package/src/provider.ts

@@ -0,0 +1,85 @@
+// Type provider model — provider-based, extensible metamodel registration.
+//
+// A MetaDataTypeProvider contributes (and/or extends) registered types. The
+// contract is cross-language identical (Java MetaDataTypeProvider parity);
+// discovery is per-language — for TS it is explicit composition via
+// composeRegistry. See docs/superpowers/specs/2026-05-17-type-provider-model-design.md.
+
+import { TypeRegistry } from "./registry.js";
+import { MetaModelError } from "./errors.js";
+
+/** A unit of metamodel registration. One provider per package. */
+export interface MetaDataTypeProvider {
+  /** Stable id; other providers reference it in `dependencies`. */
+  readonly id: string;
+  /** Ids of providers that must register before this one. Default: none. */
+  readonly dependencies?: readonly string[];
+  /** Human/AI-facing description of what this provider contributes. */
+  readonly description?: string;
+  /** Register new types and/or extend existing ones. */
+  registerTypes(registry: TypeRegistry): void;
+}
+
+/**
+ * Build a TypeRegistry by composing providers. Providers are topologically
+ * sorted by their `dependencies`; the sort is stable — providers with no
+ * ordering constraint between them keep input order. Throws on a duplicate
+ * provider id, a missing dependency, or a dependency cycle.
+ */
+export function composeRegistry(
+  providers: readonly MetaDataTypeProvider[],
+): TypeRegistry {
+  const ordered = topoSortProviders(providers);
+  const registry = new TypeRegistry();
+  for (const provider of ordered) {
+    provider.registerTypes(registry);
+  }
+  return registry;
+}
+
+function topoSortProviders(
+  providers: readonly MetaDataTypeProvider[],
+): MetaDataTypeProvider[] {
+  // Duplicate-id check.
+  const ids = new Set<string>();
+  for (const p of providers) {
+    if (ids.has(p.id)) {
+      throw new MetaModelError(`composeRegistry: duplicate provider id "${p.id}"`, { code: "ERR_PROVIDER_DUPLICATE_ID" });
+    }
+    ids.add(p.id);
+  }
+  // Missing-dependency check.
+  for (const p of providers) {
+    for (const dep of p.dependencies ?? []) {
+      if (!ids.has(dep)) {
+        throw new MetaModelError(
+          `composeRegistry: provider "${p.id}" depends on "${dep}", which is not in the provider set`,
+          { code: "ERR_PROVIDER_MISSING_DEPENDENCY" },
+        );
+      }
+    }
+  }
+  // Stable topological sort: repeatedly emit the first (input-order) provider
+  // whose dependencies are all already emitted. O(n^2) — n is a handful.
+  const result: MetaDataTypeProvider[] = [];
+  const emitted = new Set<string>();
+  while (result.length < providers.length) {
+    const next = providers.find(
+      (p) =>
+        !emitted.has(p.id) &&
+        (p.dependencies ?? []).every((d) => emitted.has(d)),
+    );
+    if (next === undefined) {
+      const stuck = providers
+        .filter((p) => !emitted.has(p.id))
+        .map((p) => p.id);
+      throw new MetaModelError(
+        `composeRegistry: dependency cycle among providers [${stuck.join(", ")}]`,
+        { code: "ERR_PROVIDER_DEPENDENCY_CYCLE" },
+      );
+    }
+    result.push(next);
+    emitted.add(next.id);
+  }
+  return result;
+}

package/src/registry.ts

@@ -0,0 +1,190 @@
+import type { AttrValue, MetaData } from "./shared/meta-data.js";
+import { SUBTYPE_BASE, TYPE_ATTR } from "./shared/base-types.js";
+import { CHILD_RULE_WILDCARD } from "./shared/structural.js";
+import { type AttrSubType } from "./core/attr/attr-constants.js";
+import type { DataType } from "./data-type.js";
+import { MetaModelError } from "./errors.js";
+
+export class TypeId {
+  constructor(
+    public readonly type: string,
+    public readonly subType: string,
+  ) {}
+
+  toString(): string {
+    return `${this.type}.${this.subType}`;
+  }
+
+  equals(other: TypeId): boolean {
+    return this.type === other.type && this.subType === other.subType;
+  }
+}
+
+export interface ChildRule {
+  /** `"*"` matches any type. */
+  childType: string;
+  /** `"*"` matches any subtype. */
+  childSubType: string;
+  /** `"*"` matches any name. */
+  childName: string;
+}
+
+export interface AttrSchema {
+  /** Attribute name WITHOUT the "@" prefix (e.g. "dbColumn", "currency"). */
+  name: string;
+  /**
+   * The attribute's value type — one of the registered attr subtypes.
+   *
+   * Optional: when absent, the attr is declared-but-untyped (no parse-time
+   * coercion; value stored raw via `toAttrValue`). Use this for polymorphic
+   * attrs whose value type is determined by the owning node at consumption
+   * time (e.g. `@default`, which is typed by its owning field's subtype).
+   *
+   * `SUBTYPE_BASE` ("base") MUST NOT be used here — it is the universal root
+   * subtype for object/field/etc. nodes and carries no "untyped" semantics for
+   * attrs. Attempting to register an AttrSchema with `valueType: "base"` throws.
+   */
+  valueType?: AttrSubType;
+  /** Whether this attribute must be present on the node. */
+  required: boolean;
+  /** Default value applied when the attribute is absent. Optional. */
+  default?: AttrValue;
+  /** When set, the attribute's value must be one of these (a closed enum). Optional. */
+  allowedValues?: readonly AttrValue[];
+  /** Human/AI-facing description of what the attribute means. */
+  description: string;
+}
+
+export interface TypeDefinition {
+  typeId: TypeId;
+  description: string;
+  factory: (typeId: TypeId, name: string) => MetaData;
+  childRules: ChildRule[];
+  attributes: AttrSchema[];
+  /** The coarse value-type classification, for (type, subType)s whose nodes
+   *  carry a typed value (field, attr). Absent for non-value-bearing types. */
+  dataType?: DataType;
+}
+
+export class TypeRegistry {
+  /** Keyed by `"type.subType"`. */
+  private readonly _defs = new Map<string, TypeDefinition>();
+
+  /** Per-type insertion-ordered subtype lists. */
+  private readonly _subTypes = new Map<string, string[]>();
+
+  /** Per-type designated default subType (queried by the YAML desugar). */
+  private readonly _defaultSubTypes = new Map<string, string>();
+
+  register(def: TypeDefinition): void {
+    const key = def.typeId.toString();
+    if (this._defs.has(key)) {
+      throw new Error(
+        `TypeRegistry: duplicate registration for "${key}" (type="${def.typeId.type}", subType="${def.typeId.subType}")`,
+      );
+    }
+
+    // Reject SUBTYPE_BASE as an attr valueType. "base" is the universal root
+    // subtype for object/field/etc. nodes; it must NOT be used as an attr value
+    // type because it carries no meaningful type semantics for attrs (its DataType
+    // resolves to DATA_TYPE_STRING, silently coercing boolean/number defaults to
+    // strings). Polymorphic attrs (e.g. @default) must omit valueType instead.
+    for (const attr of def.attributes) {
+      if (attr.valueType === SUBTYPE_BASE) {
+        throw new Error(
+          `TypeRegistry.register: attr "${attr.name}" on "${key}" declares valueType "${SUBTYPE_BASE}", ` +
+          `which is not valid for attrs. Use no valueType (omit the field) for a polymorphic/untyped attr.`,
+        );
+      }
+    }
+
+    this._defs.set(key, def);
+
+    const list = this._subTypes.get(def.typeId.type);
+    if (list !== undefined) {
+      list.push(def.typeId.subType);
+    } else {
+      this._subTypes.set(def.typeId.type, [def.typeId.subType]);
+    }
+  }
+
+  find(type: string, subType: string): TypeDefinition | undefined {
+    return this._defs.get(`${type}.${subType}`);
+  }
+
+  has(type: string, subType: string): boolean {
+    return this.find(type, subType) !== undefined;
+  }
+
+  allTypes(): TypeId[] {
+    return Array.from(this._defs.values()).map((def) => def.typeId);
+  }
+
+  allSubTypesOf(type: string): string[] {
+    return [...(this._subTypes.get(type) ?? [])];
+  }
+
+  /** Designate the default subType for a bare `type` key (used by YAML authoring sugar). */
+  setDefaultSubType(type: string, subType: string): void {
+    this._defaultSubTypes.set(type, subType);
+  }
+
+  /** The designated default subType for a type, or undefined if none was designated. */
+  defaultSubTypeOf(type: string): string | undefined {
+    return this._defaultSubTypes.get(type);
+  }
+
+  /** The declared attribute schema for a (type, subType), or [] if the
+   *  pair is unregistered or declares no attributes. */
+  attrsOf(type: string, subType: string): AttrSchema[] {
+    return [...(this.find(type, subType)?.attributes ?? [])];
+  }
+
+  /**
+   * Additively enrich an already-registered (type, subType): append attributes
+   * and/or child rules. Does NOT touch factory / typeId / dataType / default
+   * subType — a type's identity belongs to whoever registered it. Used by
+   * providers to extend types another provider defined.
+   */
+  extend(
+    type: string,
+    subType: string,
+    ext: { attributes?: AttrSchema[]; childRules?: ChildRule[] },
+  ): void {
+    const def = this.find(type, subType);
+    if (def === undefined) {
+      throw new Error(
+        `TypeRegistry.extend: no registered type "${type}.${subType}" to extend`,
+      );
+    }
+    for (const attr of ext.attributes ?? []) {
+      if (attr.valueType === SUBTYPE_BASE) {
+        throw new Error(
+          `TypeRegistry.extend: attr "${attr.name}" being added to "${type}.${subType}" declares valueType "${SUBTYPE_BASE}", ` +
+          `which is not valid for attrs. Use no valueType (omit the field) for a polymorphic/untyped attr.`,
+        );
+      }
+      if (def.attributes.some((a) => a.name === attr.name)) {
+        throw new MetaModelError(
+          `TypeRegistry.extend: attribute "${attr.name}" is already declared on "${type}.${subType}"`,
+          { code: "ERR_PROVIDER_ATTR_CONFLICT" },
+        );
+      }
+      def.attributes.push(attr);
+    }
+    for (const rule of ext.childRules ?? []) {
+      def.childRules.push(rule);
+    }
+  }
+}
+
+export function childRuleMatches(
+  rule: ChildRule,
+  child: { type: string; subType: string; name: string },
+): boolean {
+  return (
+    (rule.childType === CHILD_RULE_WILDCARD || rule.childType === child.type) &&
+    (rule.childSubType === CHILD_RULE_WILDCARD || rule.childSubType === child.subType) &&
+    (rule.childName === CHILD_RULE_WILDCARD || rule.childName === child.name)
+  );
+}

package/src/serializer-json.ts

@@ -0,0 +1,210 @@
+// Canonical JSON serializer — redesigned (post-v0.3) format.
+//
+// Every node serializes to a single-key map { "<type>.<subType>": <body> }.
+// The wrapper key fuses type and subType. The body emits keys in the canonical
+// order, each included only when non-default:
+//   1. name      2. package   3. extends   4. abstract
+//   5. overlay   6. isArray   7. @-attrs (alphabetical)   8. children
+
+import type { MetaData, AttrValue } from "./shared/meta-data.js";
+import {
+  ATTR_PREFIX,
+  TYPE_SUBTYPE_SEPARATOR,
+  RESERVED_KEY_NAME,
+  RESERVED_KEY_PACKAGE,
+  RESERVED_KEY_EXTENDS,
+  RESERVED_KEY_ABSTRACT,
+  RESERVED_KEY_IS_ARRAY,
+  RESERVED_KEY_CHILDREN,
+} from "./shared/structural.js";
+import {
+  ATTR_SUBTYPE_STRING,
+  ATTR_SUBTYPE_INT,
+  ATTR_SUBTYPE_LONG,
+  ATTR_SUBTYPE_DOUBLE,
+  ATTR_SUBTYPE_BOOLEAN,
+  ATTR_SUBTYPE_STRINGARRAY,
+} from "./core/attr/attr-constants.js";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface SerializeOptions {
+  /** Pretty-print indent. 0 = no whitespace. Default 2. */
+  indent?: number;
+}
+
+export function serializeJson(model: MetaData, opts?: SerializeOptions): string {
+  const indent = opts?.indent ?? 2;
+
+  const nodeObj = serializeNode(model, false);
+  return JSON.stringify(nodeObj, null, indent === 0 ? undefined : indent);
+}
+
+// ---------------------------------------------------------------------------
+// Infer attr subType from a JS value (for child-node form when subType isn't known)
+// ---------------------------------------------------------------------------
+
+// Java int range — used for distinguishing int vs long subtypes.
+const JAVA_INT_MAX = 2 ** 31 - 1;
+const JAVA_INT_MIN = -(2 ** 31);
+
+export function inferAttrSubType(value: AttrValue): string {
+  if (Array.isArray(value)) return ATTR_SUBTYPE_STRINGARRAY;
+  if (typeof value === "boolean") return ATTR_SUBTYPE_BOOLEAN;
+  if (typeof value === "number") {
+    if (!Number.isInteger(value)) return ATTR_SUBTYPE_DOUBLE;
+    return value >= JAVA_INT_MIN && value <= JAVA_INT_MAX
+      ? ATTR_SUBTYPE_INT
+      : ATTR_SUBTYPE_LONG;
+  }
+  return ATTR_SUBTYPE_STRING;
+}
+
+/** Build a fused `type.subType` wrapper key. */
+function fusedKey(type: string, subType: string): string {
+  return `${type}${TYPE_SUBTYPE_SEPARATOR}${subType}`;
+}
+
+// ---------------------------------------------------------------------------
+// Serialize a single node — returns { "<type>.<subType>": { ...body } }
+// ---------------------------------------------------------------------------
+
+function serializeNode(
+  model: MetaData,
+  effective: boolean,
+): Record<string, unknown> {
+  const inner = serializeNodeInner(model, effective);
+  return { [fusedKey(model.type, model.subType)]: inner };
+}
+
+function serializeNodeInner(
+  model: MetaData,
+  effective: boolean,
+): Record<string, unknown> {
+  // Canonical body-key order:
+  //   1. name  2. package  3. extends  4. abstract
+  //   5. overlay  6. isArray  7. inline @-attrs  8. children
+
+  const obj: Record<string, unknown> = {};
+
+  if (model.name !== "") {
+    obj[RESERVED_KEY_NAME] = model.name;
+  }
+
+  if (model.package !== undefined && model.package !== "") {
+    obj[RESERVED_KEY_PACKAGE] = model.package;
+  }
+
+  if (model.superRef !== undefined) {
+    obj[RESERVED_KEY_EXTENDS] = model.superRef;
+  }
+
+  if (model.isAbstract === true) {
+    obj[RESERVED_KEY_ABSTRACT] = true;
+  }
+
+  // NOTE: `overlay` is an authoring-time parser directive, not a property of
+  // the resolved tree. After a merge, the merged node is a normal node — the
+  // canonical serialization is the merged RESULT, which carries no overlay
+  // semantics. Re-emitting `overlay: true` would break round-trip stability
+  // (re-parsing would seek a non-existent node to merge into). So it is
+  // deliberately NOT serialized.
+
+  if (model.isArray === true) {
+    obj[RESERVED_KEY_IS_ARRAY] = true;
+  }
+
+  // In effective mode use children()/attrs() (own + inherited via super chain);
+  // in own mode use ownChildren()/ownAttrs() (declared on this node only).
+  const childList = effective ? model.children() : model.ownChildren();
+  const attrMap = effective ? model.attrs() : model.ownAttrs();
+
+  const serializedChildren: Record<string, unknown>[] = [];
+  for (const child of childList) {
+    // Attrs never appear in children(); only structural nodes recurse.
+    serializedChildren.push(serializeNode(child, effective));
+  }
+
+  // Attrs ALWAYS emit inline @name (D5 — attrs have no children, one canonical form).
+  for (const [attrName, attrValue] of attrMap) {
+    obj[`${ATTR_PREFIX}${attrName}`] = attrValue;
+  }
+
+  if (serializedChildren.length > 0) {
+    obj[RESERVED_KEY_CHILDREN] = serializedChildren;
+  }
+  return obj;
+}
+
+// ---------------------------------------------------------------------------
+// canonicalSerialize — deterministic serializer for cross-language conformance
+//
+// Wraps serializeJson with two extra guarantees:
+//   1. Inline @-attrs are emitted in alphabetical order (not Map iteration order).
+//   2. Output ends with exactly one trailing newline.
+//
+// Both behaviors are required so Java/Python/C# implementations can produce
+// byte-identical output from the same input metamodel.
+// ---------------------------------------------------------------------------
+
+export function canonicalSerialize(model: MetaData): string {
+  const raw = serializeJson(model, { indent: 2 });
+
+  const parsed = JSON.parse(raw) as unknown;
+  const sorted = sortAttrKeys(parsed);
+  const out = JSON.stringify(sorted, null, 2);
+
+  return out + "\n";
+}
+
+/**
+ * Like canonicalSerialize, but emits the EFFECTIVE tree — children() and
+ * attrs() at every node (own + inherited via the super chain), so the
+ * super-chain merge is materialized in the output.
+ * Used by the conformance harness's expected-effective fixtures.
+ */
+export function canonicalSerializeEffective(model: MetaData): string {
+  const nodeObj = serializeNode(model, true);
+  const raw = JSON.stringify(nodeObj, null, 2);
+
+  const parsed = JSON.parse(raw) as unknown;
+  const sorted = sortAttrKeys(parsed);
+  const out = JSON.stringify(sorted, null, 2);
+
+  return out + "\n";
+}
+
+function sortAttrKeys(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(sortAttrKeys);
+  }
+  if (value !== null && typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj);
+
+    const structuralKeys: string[] = [];
+    const attrKeys: string[] = [];
+    for (const k of keys) {
+      if (k.startsWith(ATTR_PREFIX)) attrKeys.push(k);
+      else structuralKeys.push(k);
+    }
+    attrKeys.sort();
+
+    const result: Record<string, unknown> = {};
+    const hasChildren = structuralKeys.includes(RESERVED_KEY_CHILDREN);
+    for (const k of structuralKeys) {
+      if (k === RESERVED_KEY_CHILDREN) continue;
+      result[k] = sortAttrKeys(obj[k]);
+    }
+    for (const k of attrKeys) {
+      result[k] = sortAttrKeys(obj[k]);
+    }
+    if (hasChildren) {
+      result[RESERVED_KEY_CHILDREN] = sortAttrKeys(obj[RESERVED_KEY_CHILDREN]);
+    }
+    return result;
+  }
+  return value;
+}

package/src/shared/base-types.ts

@@ -0,0 +1,52 @@
+// Base type vocabulary — the 11 registered base types + universal/metadata subtypes.
+
+// ---------------------------------------------------------------------------
+// Base type names (the 11 registered base types — Java metaobjects-core vocabulary)
+// ---------------------------------------------------------------------------
+
+export const TYPE_METADATA = "metadata";
+export const TYPE_OBJECT = "object";
+export const TYPE_FIELD = "field";
+export const TYPE_ATTR = "attr";
+export const TYPE_VALIDATOR = "validator";
+export const TYPE_VIEW = "view";
+export const TYPE_IDENTITY = "identity";
+export const TYPE_RELATIONSHIP = "relationship";
+export const TYPE_LAYOUT = "layout";
+export const TYPE_SOURCE = "source";
+export const TYPE_ORIGIN = "origin";
+
+export const BASE_TYPES = [
+  TYPE_METADATA,
+  TYPE_OBJECT,
+  TYPE_FIELD,
+  TYPE_ATTR,
+  TYPE_VALIDATOR,
+  TYPE_VIEW,
+  TYPE_IDENTITY,
+  TYPE_RELATIONSHIP,
+  TYPE_LAYOUT,
+  TYPE_SOURCE,
+  TYPE_ORIGIN,
+] as const;
+export type BaseType = (typeof BASE_TYPES)[number];
+
+// ---------------------------------------------------------------------------
+// Universal subtype
+// ---------------------------------------------------------------------------
+
+export const SUBTYPE_BASE = "base";
+
+// ---------------------------------------------------------------------------
+// Metadata subtypes (1)
+// ---------------------------------------------------------------------------
+
+/**
+ * The metadata document root subtype. The root node is `metadata.root` in the
+ * canonical format. (Distinct from the universal SUBTYPE_BASE — the redesigned
+ * format spec confirms the root subtype is `root`, not `base`.)
+ */
+export const SUBTYPE_ROOT = "root";
+
+export const METADATA_SUBTYPES = [SUBTYPE_ROOT] as const;
+export type MetadataSubType = (typeof METADATA_SUBTYPES)[number];