@metaobjectsdev/metadata 0.6.0 → 0.7.0-rc.2

package/dist/core/yaml-positions-walker.js

@@ -0,0 +1,75 @@
+// FR5b — YAML AST → JS walker that preserves source positions.
+//
+// This module is the only place inside @metaobjectsdev/metadata that
+// imports the `yaml` package. It lives in core/ alongside parser-yaml.ts,
+// and is reached only via that parser — never via src/index.ts. The
+// browser-safety test guards this invariant.
+import { parseDocument, isAlias, isMap, isScalar, isSeq, LineCounter, } from "yaml";
+import { setPositionMap, } from "./yaml-positions.js";
+/** Parse YAML text and return a JS object with positions attached.
+ *
+ *  Mirrors the contract of `yaml.parse(text)` for the shapes the metaobjects
+ *  authoring grammar uses (mappings, sequences, scalars). Aliases and tags
+ *  are deferred via the underlying parseDocument call — i.e. they resolve as
+ *  the library normally would.
+ *
+ *  Throws on YAML syntax errors (same behavior as `yaml.parse`). */
+export function parseYamlWithPositions(text) {
+    const lineCounter = new LineCounter();
+    const doc = parseDocument(text, { lineCounter });
+    // Surface YAML syntax errors as a throw, matching `yaml.parse` behavior.
+    // (parseDocument collects them rather than throwing.)
+    if (doc.errors.length > 0) {
+        throw doc.errors[0];
+    }
+    const value = yamlNodeToJs(doc.contents, lineCounter, doc);
+    return { value, lineCounter };
+}
+// Walk a yaml AST node into a JS structure. For each YAMLMap, attach a
+// position-by-key map onto the resulting JS object — the position of each
+// key is the (line, col) of the KEY token in the YAML source.
+function yamlNodeToJs(node, lineCounter, doc) {
+    if (node === null || node === undefined)
+        return null;
+    if (isScalar(node)) {
+        // Honour the library's default scalar typing (numbers / booleans /
+        // strings / null all come through Scalar.value).
+        return node.value;
+    }
+    if (isAlias(node)) {
+        // Resolve an anchor alias (e.g. `*col` after `&col sku_code`) to its
+        // target value — same behaviour as the library's toJS().
+        const target = node.resolve(doc);
+        return yamlNodeToJs(target, lineCounter, doc);
+    }
+    if (isMap(node)) {
+        const out = {};
+        const positions = {};
+        let hasAnyPosition = false;
+        for (const pair of node.items) {
+            // Only string-keyed entries are valid in metaobjects authoring; ignore
+            // exotic keys (numeric / complex) — they'd already break the desugar.
+            if (!isScalar(pair.key))
+                continue;
+            const keyText = String(pair.key.value);
+            const valueJs = yamlNodeToJs(pair.value, lineCounter, doc);
+            out[keyText] = valueJs;
+            const keyRange = pair.key.range;
+            if (keyRange !== null && keyRange !== undefined) {
+                const pos = lineCounter.linePos(keyRange[0]);
+                positions[keyText] = { line: pos.line, col: pos.col };
+                hasAnyPosition = true;
+            }
+        }
+        if (hasAnyPosition)
+            setPositionMap(out, positions);
+        return out;
+    }
+    if (isSeq(node)) {
+        return node.items.map((item) => yamlNodeToJs(item, lineCounter, doc));
+    }
+    // Tags / unsupported — fall back to null. The metaobjects authoring
+    // grammar does not use them.
+    return null;
+}
+//# sourceMappingURL=yaml-positions-walker.js.map

package/dist/core/yaml-positions-walker.js.map

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

package/dist/core/yaml-positions.d.ts

@@ -0,0 +1,19 @@
+/** Cross-port well-known symbol key for the position-by-key map. */
+export declare const YAML_POSITION_BY_KEY: unique symbol;
+/** A YAML source position — 1-indexed line and column. */
+export interface YamlPosition {
+    readonly line: number;
+    readonly col: number;
+}
+/** The position-by-key map attached to a mapping object. */
+export type PositionMap = Record<string, YamlPosition>;
+/** Read the position-by-key map from a JS object, if present.
+ *  Returns undefined for primitives, arrays, null, and untagged objects. */
+export declare function getPositionMap(obj: unknown): PositionMap | undefined;
+/** Read the position for a specific key on a mapping object. */
+export declare function getYamlPosition(obj: unknown, key: string): YamlPosition | undefined;
+/** Attach (or replace) the position-by-key map on a mapping object. The map
+ *  property is non-enumerable so JSON.stringify and `for (const k in obj)`
+ *  loops do not see it. */
+export declare function setPositionMap(obj: Record<string, unknown>, positions: PositionMap): void;
+//# sourceMappingURL=yaml-positions.d.ts.map

package/dist/core/yaml-positions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-positions.d.ts","sourceRoot":"","sources":["../../src/core/yaml-positions.ts"],"names":[],"mappings":"AAkCA,oEAAoE;AACpE,eAAO,MAAM,oBAAoB,eAEhC,CAAC;AAEF,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,4DAA4D;AAC5D,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAEvD;4EAC4E;AAC5E,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAKpE;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAC7B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,MAAM,GACV,YAAY,GAAG,SAAS,CAG1B;AAED;;2BAE2B;AAC3B,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,SAAS,EAAE,WAAW,GACrB,IAAI,CAON"}

package/dist/core/yaml-positions.js

@@ -0,0 +1,60 @@
+// FR5b — YAML authoring source-position carrier (per ADR-0009).
+//
+// This module is split into two layers so the browser bundle (which
+// imports from src/index.ts) stays free of the Node-only `yaml` package:
+//
+//   - yaml-positions.ts (this file) — pure types + Symbol + accessors. NO
+//     `yaml` import. Imported by parser-core.ts so the source-on-node
+//     stamper can read positions when stamping `format: "yaml"` envelopes.
+//   - yaml-positions-walker.ts — depends on `yaml`. Imported only by
+//     parser-yaml.ts (and parser-yaml itself only ships server-side).
+//
+// Source-map carrier (per the FR5b spec's "open question" §2): a
+// Symbol-keyed, non-enumerable property on the wrapper-mapping object. The
+// symbol is the well-known cross-port key
+// `Symbol.for("@metaobjectsdev/yamlPositionByKey")`, so any plugin that
+// touches the canonical JS can read positions if it knows to look. The
+// map's keys are the wrapper's own keys (e.g. "object.entity" for a
+// wrapper `{ "object.entity": { ... } }` or "name" / "package" /
+// "children" for the body keys of a node).
+//
+// Rationale for "symbol-keyed property" over a parallel sourcemap / wrapper
+// type:
+//   - Invisible to JSON.stringify and Object.keys (non-enumerable).
+//   - No parallel data structure to keep in sync — the position rides with
+//     the node it describes.
+//   - No wrapper type — desugar still operates on plain JS objects, so the
+//     existing Rule 1–5 logic does not need a rewrite.
+//
+// On desugar-synthesized nodes (Rule 2's scalar-body lift): the synthesized
+// body `{ name: rawScalar }` inherits the wrapper key's position from the
+// parent's position map. On any other synthesis (Rule 4's isArray stamping,
+// for example), the position survives because we shallow-copy via the
+// existing desugar path.
+/** Cross-port well-known symbol key for the position-by-key map. */
+export const YAML_POSITION_BY_KEY = Symbol.for("@metaobjectsdev/yamlPositionByKey");
+/** Read the position-by-key map from a JS object, if present.
+ *  Returns undefined for primitives, arrays, null, and untagged objects. */
+export function getPositionMap(obj) {
+    if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
+        return undefined;
+    }
+    return obj[YAML_POSITION_BY_KEY];
+}
+/** Read the position for a specific key on a mapping object. */
+export function getYamlPosition(obj, key) {
+    const map = getPositionMap(obj);
+    return map?.[key];
+}
+/** Attach (or replace) the position-by-key map on a mapping object. The map
+ *  property is non-enumerable so JSON.stringify and `for (const k in obj)`
+ *  loops do not see it. */
+export function setPositionMap(obj, positions) {
+    Object.defineProperty(obj, YAML_POSITION_BY_KEY, {
+        value: positions,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+    });
+}
+//# sourceMappingURL=yaml-positions.js.map

package/dist/core/yaml-positions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-positions.js","sourceRoot":"","sources":["../../src/core/yaml-positions.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,oEAAoE;AACpE,yEAAyE;AACzE,EAAE;AACF,0EAA0E;AAC1E,sEAAsE;AACtE,2EAA2E;AAC3E,qEAAqE;AACrE,sEAAsE;AACtE,EAAE;AACF,iEAAiE;AACjE,2EAA2E;AAC3E,0CAA0C;AAC1C,wEAAwE;AACxE,uEAAuE;AACvE,oEAAoE;AACpE,iEAAiE;AACjE,2CAA2C;AAC3C,EAAE;AACF,4EAA4E;AAC5E,QAAQ;AACR,oEAAoE;AACpE,2EAA2E;AAC3E,6BAA6B;AAC7B,2EAA2E;AAC3E,uDAAuD;AACvD,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,4EAA4E;AAC5E,sEAAsE;AACtE,yBAAyB;AAEzB,oEAAoE;AACpE,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAC5C,mCAAmC,CACpC,CAAC;AAWF;4EAC4E;AAC5E,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAQ,GAAgD,CAAC,oBAAoB,CAAC,CAAC;AACjF,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,eAAe,CAC7B,GAAY,EACZ,GAAW;IAEX,MAAM,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IAChC,OAAO,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;AACpB,CAAC;AAED;;2BAE2B;AAC3B,MAAM,UAAU,cAAc,CAC5B,GAA4B,EAC5B,SAAsB;IAEtB,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,oBAAoB,EAAE;QAC/C,KAAK,EAAE,SAAS;QAChB,UAAU,EAAE,KAAK;QACjB,QAAQ,EAAE,IAAI;QACd,YAAY,EAAE,IAAI;KACnB,CAAC,CAAC;AACL,CAAC"}

package/dist/errors.d.ts

@@ -1,14 +1,37 @@
+import type { ErrorSource, LoaderError, NodeContext } from "./source.js";
 /** Stable, language-neutral error codes — mirrors fixtures/conformance/ERROR-CODES.json. */
-export declare const ERROR_CODES: readonly ["ERR_TOP_LEVEL_NOT_OBJECT", "ERR_UNKNOWN_TYPE", "ERR_UNKNOWN_SUBTYPE", "ERR_MISSING_SUBTYPE", "ERR_DUPLICATE_NAME", "ERR_UNRESOLVED_SUPER", "ERR_INVALID_SUBTYPE_CHILD", "ERR_UNKNOWN_ATTR", "ERR_BAD_ATTR_VALUE", "ERR_BAD_DEFAULT_SORT_FIELD", "ERR_PROVIDER_DEPENDENCY_CYCLE", "ERR_PROVIDER_DUPLICATE_ID", "ERR_PROVIDER_MISSING_DEPENDENCY", "ERR_PROVIDER_ATTR_CONFLICT", "ERR_MALFORMED_JSON", "ERR_MISSING_REQUIRED_ATTR", "ERR_SUBTYPE_RULE_VIOLATION", "ERR_OVERLAY_NO_TARGET", "ERR_MALFORMED_YAML", "ERR_INVALID_ORIGIN", "ERR_INVALID_TEMPLATE", "ERR_VAR_NOT_ON_PAYLOAD", "ERR_PARTIAL_UNRESOLVED", "ERR_REQUIRED_SLOT_UNUSED", "ERR_OUTPUT_TAG_MISSING", "ERR_BAD_ATTR_FILTER", "ERR_STORAGE_FLATTENED_ARRAY", "ERR_STORAGE_WITHOUT_OBJECT_REF", "ERR_RESERVED_ATTR", "ERR_SOURCE_NO_PRIMARY", "ERR_SOURCE_MULTIPLE_PRIMARY", "ERR_YAML_COERCION", "ERR_UNKNOWN"];
+export declare const ERROR_CODES: readonly ["ERR_TOP_LEVEL_NOT_OBJECT", "ERR_UNKNOWN_TYPE", "ERR_UNKNOWN_SUBTYPE", "ERR_MISSING_SUBTYPE", "ERR_DUPLICATE_NAME", "ERR_UNRESOLVED_SUPER", "ERR_INVALID_SUBTYPE_CHILD", "ERR_UNKNOWN_ATTR", "ERR_BAD_ATTR_VALUE", "ERR_BAD_DEFAULT_SORT_FIELD", "ERR_PROVIDER_DEPENDENCY_CYCLE", "ERR_PROVIDER_DUPLICATE_ID", "ERR_PROVIDER_MISSING_DEPENDENCY", "ERR_PROVIDER_ATTR_CONFLICT", "ERR_MALFORMED_JSON", "ERR_MISSING_REQUIRED_ATTR", "ERR_SUBTYPE_RULE_VIOLATION", "ERR_OVERLAY_NO_TARGET", "ERR_MALFORMED_YAML", "ERR_INVALID_ORIGIN", "ERR_INVALID_TEMPLATE", "ERR_VAR_NOT_ON_PAYLOAD", "ERR_PARTIAL_UNRESOLVED", "ERR_REQUIRED_SLOT_UNUSED", "ERR_OUTPUT_TAG_MISSING", "ERR_BAD_ATTR_FILTER", "ERR_STORAGE_FLATTENED_ARRAY", "ERR_STORAGE_WITHOUT_OBJECT_REF", "ERR_RESERVED_ATTR", "ERR_SOURCE_NO_PRIMARY", "ERR_SOURCE_MULTIPLE_PRIMARY", "ERR_YAML_COERCION", "ERR_MERGE_CONFLICT", "ERR_UNKNOWN"];
+/** Warning codes — same envelope shape as errors but advisory. */
+export declare const WARNING_CODES: readonly ["WARN_DUPLICATE_DECLARATION", "WARN_LEGACY"];
+export type WarningCode = (typeof WARNING_CODES)[number];
 export type ErrorCode = (typeof ERROR_CODES)[number];
-export declare class ParseError extends Error {
-    readonly source: string | undefined;
-    readonly path: string | undefined;
-    readonly code: ErrorCode | undefined;
-    constructor(message: string, opts?: {
-        source?: string;
-        path?: string;
-        code?: ErrorCode;
+/**
+ * Loader error carrying the ADR-0009 LoaderError envelope.
+ *
+ * Public shape (FR5a):
+ *   new ParseError(message, { code, source, suggestions?, fixture?, node? })
+ *
+ * - `code` and `source` are required.
+ * - `source` is the ErrorSource discriminated union (json/yaml/merged/resolved/
+ *   database/code) — the same envelope every cross-language port emits.
+ * - `suggestions[]`, `fixture`, `node` are optional per ADR-0009 §RECOMMENDED;
+ *   FR5a does not populate them, FR5b–FR5e may.
+ *
+ * Legacy fields (`path?: string`, `source?: string`) were superseded by the
+ * envelope's `jsonPath` and `files` and have been dropped — see CHANGELOG.
+ */
+export declare class ParseError extends Error implements LoaderError {
+    readonly code: ErrorCode;
+    readonly source: ErrorSource;
+    readonly suggestions?: string[];
+    readonly fixture?: string;
+    readonly node?: NodeContext;
+    constructor(message: string, opts: {
+        code: ErrorCode;
+        source: ErrorSource;
+        suggestions?: string[];
+        fixture?: string;
+        node?: NodeContext;
     });
 }
 /**

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,4FAA4F;AAc5F,eAAO,MAAM,WAAW,41BAqCd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;gBAGnC,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,SAAS,CAAA;KAAE;CAQ9D;AAED;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;gBAEzB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,SAAS,CAAA;KAAE;CAKzD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEzE,4FAA4F;AAc5F,eAAO,MAAM,WAAW,k3BAwCd,CAAC;AAEX,kEAAkE;AAClE,eAAO,MAAM,aAAa,wDAQhB,CAAC;AACX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,UAAW,SAAQ,KAAM,YAAW,WAAW;IAC1D,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC;gBAG1B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;QACJ,IAAI,EAAE,SAAS,CAAC;QAChB,MAAM,EAAE,WAAW,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,WAAW,CAAC;KACpB;CAiBJ;AAED;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC;gBAEzB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,SAAS,CAAA;KAAE;CAKzD"}

package/dist/errors.js

@@ -49,18 +49,57 @@ export const ERROR_CODES = [
     // ADR-0006 D2 — YAML type-coercion guard. Emitted by every port's YAML
     // loader when a coerced scalar mismatches the schema-declared type.
     "ERR_YAML_COERCION",
+    // FR5c — multi-file overlay merge produced a conflicting attribute value:
+    // two contributors set the same @attr to different non-empty values.
+    "ERR_MERGE_CONFLICT",
     "ERR_UNKNOWN",
 ];
+/** Warning codes — same envelope shape as errors but advisory. */
+export const WARNING_CODES = [
+    // FR5c — two contributors declared the same node identically (no semantic
+    // change). Emitted at the overlay-merge boundary.
+    "WARN_DUPLICATE_DECLARATION",
+    // Pre-FR5c legacy: parser/validator messages still surface as plain
+    // strings; wrapped at the loader boundary into the envelope shape with
+    // this code. Retired as those sites are migrated to envelopes.
+    "WARN_LEGACY",
+];
+/**
+ * Loader error carrying the ADR-0009 LoaderError envelope.
+ *
+ * Public shape (FR5a):
+ *   new ParseError(message, { code, source, suggestions?, fixture?, node? })
+ *
+ * - `code` and `source` are required.
+ * - `source` is the ErrorSource discriminated union (json/yaml/merged/resolved/
+ *   database/code) — the same envelope every cross-language port emits.
+ * - `suggestions[]`, `fixture`, `node` are optional per ADR-0009 §RECOMMENDED;
+ *   FR5a does not populate them, FR5b–FR5e may.
+ *
+ * Legacy fields (`path?: string`, `source?: string`) were superseded by the
+ * envelope's `jsonPath` and `files` and have been dropped — see CHANGELOG.
+ */
 export class ParseError extends Error {
-    source;
-    path; // logical path within the JSON, e.g. "metadata.children[2].field"
     code;
+    source;
+    suggestions;
+    fixture;
+    node;
     constructor(message, opts) {
         super(message);
         this.name = "ParseError";
-        this.source = opts?.source;
-        this.path = opts?.path;
-        this.code = opts?.code;
+        this.code = opts.code;
+        this.source = opts.source;
+        // exactOptionalPropertyTypes: only assign when defined.
+        if (opts.suggestions !== undefined) {
+            this.suggestions = opts.suggestions;
+        }
+        if (opts.fixture !== undefined) {
+            this.fixture = opts.fixture;
+        }
+        if (opts.node !== undefined) {
+            this.node = opts.node;
+        }
     }
 }
 /**

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAE/C,4FAA4F;AAC5F,kFAAkF;AAClF,yDAAyD;AACzD,4FAA4F;AAC5F,gGAAgG;AAChG,2EAA2E;AAC3E,0FAA0F;AAC1F,EAAE;AACF,oFAAoF;AACpF,uFAAuF;AACvF,mFAAmF;AACnF,uFAAuF;AACvF,uFAAuF;AACvF,0BAA0B;AAC1B,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,0BAA0B;IAC1B,kBAAkB;IAClB,qBAAqB;IACrB,qBAAqB;IACrB,oBAAoB;IACpB,sBAAsB;IACtB,2BAA2B;IAC3B,kBAAkB;IAClB,oBAAoB;IACpB,4BAA4B;IAC5B,+BAA+B;IAC/B,2BAA2B;IAC3B,iCAAiC;IACjC,4BAA4B;IAC5B,oBAAoB;IACpB,2BAA2B;IAC3B,4BAA4B;IAC5B,uBAAuB;IACvB,oBAAoB;IACpB,oBAAoB;IACpB,sBAAsB;IACtB,wBAAwB;IACxB,wBAAwB;IACxB,0BAA0B;IAC1B,wBAAwB;IACxB,qBAAqB;IACrB,6BAA6B;IAC7B,gCAAgC;IAChC,qFAAqF;IACrF,mBAAmB;IACnB,uBAAuB;IACvB,6BAA6B;IAC7B,uEAAuE;IACvE,oEAAoE;IACpE,mBAAmB;IACnB,aAAa;CACL,CAAC;AAIX,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC1B,MAAM,CAAqB;IAC3B,IAAI,CAAqB,CAAC,kEAAkE;IAC5F,IAAI,CAAwB;IAErC,YACE,OAAe,EACf,IAA2D;QAE3D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC;IACzB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAwB;IAErC,YAAY,OAAe,EAAE,IAA2B;QACtD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC;IACzB,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAI/C,4FAA4F;AAC5F,kFAAkF;AAClF,yDAAyD;AACzD,4FAA4F;AAC5F,gGAAgG;AAChG,2EAA2E;AAC3E,0FAA0F;AAC1F,EAAE;AACF,oFAAoF;AACpF,uFAAuF;AACvF,mFAAmF;AACnF,uFAAuF;AACvF,uFAAuF;AACvF,0BAA0B;AAC1B,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,0BAA0B;IAC1B,kBAAkB;IAClB,qBAAqB;IACrB,qBAAqB;IACrB,oBAAoB;IACpB,sBAAsB;IACtB,2BAA2B;IAC3B,kBAAkB;IAClB,oBAAoB;IACpB,4BAA4B;IAC5B,+BAA+B;IAC/B,2BAA2B;IAC3B,iCAAiC;IACjC,4BAA4B;IAC5B,oBAAoB;IACpB,2BAA2B;IAC3B,4BAA4B;IAC5B,uBAAuB;IACvB,oBAAoB;IACpB,oBAAoB;IACpB,sBAAsB;IACtB,wBAAwB;IACxB,wBAAwB;IACxB,0BAA0B;IAC1B,wBAAwB;IACxB,qBAAqB;IACrB,6BAA6B;IAC7B,gCAAgC;IAChC,qFAAqF;IACrF,mBAAmB;IACnB,uBAAuB;IACvB,6BAA6B;IAC7B,uEAAuE;IACvE,oEAAoE;IACpE,mBAAmB;IACnB,0EAA0E;IAC1E,qEAAqE;IACrE,oBAAoB;IACpB,aAAa;CACL,CAAC;AAEX,kEAAkE;AAClE,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,0EAA0E;IAC1E,kDAAkD;IAClD,4BAA4B;IAC5B,oEAAoE;IACpE,uEAAuE;IACvE,+DAA+D;IAC/D,aAAa;CACL,CAAC;AAKX;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC1B,IAAI,CAAY;IAChB,MAAM,CAAc;IACpB,WAAW,CAAY;IACvB,OAAO,CAAU;IACjB,IAAI,CAAe;IAE5B,YACE,OAAe,EACf,IAMC;QAED,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,wDAAwD;QACxD,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YAClC,IAAmC,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACtE,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC9B,IAA6B,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QACxD,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC3B,IAA+B,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACpD,CAAC;IACH,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAwB;IAErC,YAAY,OAAe,EAAE,IAA2B;QACtD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC;IACzB,CAAC;CACF"}

package/dist/index.d.ts

@@ -64,12 +64,15 @@ export type { SerializeOptions } from "./serializer-json.js";
 export { resolveSuperRef } from "./super-resolve.js";
 export { MetaDataLoader } from "./loader/meta-data-loader.js";
 export type { LoadOptions, LoadResult, LoadingState } from "./loader/meta-data-loader.js";
-export { InMemorySource } from "./loader/meta-data-source.js";
+export { InMemoryStringSource } from "./loader/meta-data-source.js";
 export type { MetaDataSource, MetaDataFormat } from "./loader/meta-data-source.js";
+export { loadDirectory, loadUris, loadString, } from "./loader/shortcuts.js";
 export { ParseError, MetaModelError, ERROR_CODES } from "./errors.js";
 export type { ErrorCode } from "./errors.js";
+export type { ErrorSource, LoaderError, LoaderWarning, NodeContext, Contributor, } from "./source.js";
+export { codeSource } from "./source.js";
 export { validateAttrSchema } from "./attr-schema-validate.js";
 export type { AttrSchemaValidationResult } from "./attr-schema-validate.js";
-export { toSnakeCase, pluralize, resolveTableName, resolveColumnName, resolveTableSchema, buildNameMap, stripPackage, } from "./naming.js";
-export type { EntityNameMap } from "./naming.js";
+export { toSnakeCase, toKebabCase, pluralize, applyColumnNamingStrategy, DEFAULT_COLUMN_NAMING_STRATEGY, resolveTableName, resolveColumnName, resolveTableSchema, buildNameMap, stripPackage, } from "./naming.js";
+export type { EntityNameMap, ColumnNamingStrategy } from "./naming.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -71,12 +71,19 @@ export { serializeJson, canonicalSerialize, inferAttrSubType } from "./serialize
 export { resolveSuperRef } from "./super-resolve.js";
 // Loader hierarchy
 export { MetaDataLoader } from "./loader/meta-data-loader.js";
-export { InMemorySource } from "./loader/meta-data-source.js";
+export { InMemoryStringSource } from "./loader/meta-data-source.js";
+// Module-level loader shortcuts — delegate to MetaDataLoader.from* static
+// factories. The shortcuts honor the ergonomic per-port pattern (TS and
+// Python expose both class statics AND module-level functions); Java/C# stay
+// class-only. Browser safety is preserved: the underlying sources are
+// loaded via dynamic import inside MetaDataLoader.from*.
+export { loadDirectory, loadUris, loadString, } from "./loader/shortcuts.js";
 // Errors
 export { ParseError, MetaModelError, ERROR_CODES } from "./errors.js";
+export { codeSource } from "./source.js";
 // Attribute-schema validation pass (Phase A3)
 export { validateAttrSchema } from "./attr-schema-validate.js";
 // Naming — hoisted from runtime-ts in v0.2.3 so multiple consumers (runtime-ts, migrate-ts, codegen-ts)
 // share identical name resolution. See spec §4.1.
-export { toSnakeCase, pluralize, resolveTableName, resolveColumnName, resolveTableSchema, buildNameMap, stripPackage, } from "./naming.js";
+export { toSnakeCase, toKebabCase, pluralize, applyColumnNamingStrategy, DEFAULT_COLUMN_NAMING_STRATEGY, resolveTableName, resolveColumnName, resolveTableSchema, buildNameMap, stripPackage, } from "./naming.js";
 //# sourceMappingURL=index.js.map

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/dist/json-path.d.ts

@@ -0,0 +1,8 @@
+export declare class JsonPathBuilder {
+    private readonly segments;
+    pushKey(key: string): void;
+    pushIndex(idx: number): void;
+    pop(): void;
+    toString(): string;
+}
+//# sourceMappingURL=json-path.d.ts.map

package/dist/json-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-path.d.ts","sourceRoot":"","sources":["../src/json-path.ts"],"names":[],"mappings":"AAiBA,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAE1C,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI1B,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI5B,GAAG,IAAI,IAAI;IAIX,QAAQ,IAAI,MAAM;CAanB"}

package/dist/json-path.js

@@ -0,0 +1,39 @@
+// server/typescript/packages/metadata/src/json-path.ts
+//
+// FR5a / ADR-0009 — Canonical JSONPath builder.
+//
+// Construction rules (cross-port-aligned):
+//   - Root is `$`.
+//   - Object keys matching /^[A-Za-z_][A-Za-z0-9_]*$/ use dot notation: `.foo`.
+//   - All other keys use single-quoted bracket form: `['my-key']`, `['@attr']`.
+//   - Array indices use bracket form: `[N]`.
+//   - No trailing dots, no whitespace.
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export class JsonPathBuilder {
+    segments = [];
+    pushKey(key) {
+        this.segments.push({ kind: "key", value: key });
+    }
+    pushIndex(idx) {
+        this.segments.push({ kind: "index", value: idx });
+    }
+    pop() {
+        this.segments.pop();
+    }
+    toString() {
+        let out = "$";
+        for (const seg of this.segments) {
+            if (seg.kind === "index") {
+                out += `[${seg.value}]`;
+            }
+            else if (IDENT_RE.test(seg.value)) {
+                out += `.${seg.value}`;
+            }
+            else {
+                out += `['${seg.value.replace(/'/g, "\\'")}']`;
+            }
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=json-path.js.map

package/dist/json-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-path.js","sourceRoot":"","sources":["../src/json-path.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,EAAE;AACF,gDAAgD;AAChD,EAAE;AACF,2CAA2C;AAC3C,mBAAmB;AACnB,gFAAgF;AAChF,gFAAgF;AAChF,6CAA6C;AAC7C,uCAAuC;AAEvC,MAAM,QAAQ,GAAG,0BAA0B,CAAC;AAM5C,MAAM,OAAO,eAAe;IACT,QAAQ,GAAc,EAAE,CAAC;IAE1C,OAAO,CAAC,GAAW;QACjB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,SAAS,CAAC,GAAW;QACnB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,GAAG;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC;IACtB,CAAC;IAED,QAAQ;QACN,IAAI,GAAG,GAAG,GAAG,CAAC;QACd,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChC,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBACzB,GAAG,IAAI,IAAI,GAAG,CAAC,KAAK,GAAG,CAAC;YAC1B,CAAC;iBAAM,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBACpC,GAAG,IAAI,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YACzB,CAAC;iBAAM,CAAC;gBACN,GAAG,IAAI,KAAK,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC;YACjD,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;CACF"}

package/dist/loader/meta-data-loader.d.ts

@@ -1,8 +1,13 @@
 import type { MetaData } from "../shared/meta-data.js";
 import { MetaRoot } from "../shared/meta-root.js";
 import { TypeRegistry } from "../registry.js";
-import type { MetaDataSource } from "./meta-data-source.js";
+import type { LoaderWarning } from "../source.js";
+import type { MetaDataFormat, MetaDataSource } from "./meta-data-source.js";
 import type { ParseOptions, ParseResult } from "../parser-core.js";
+type DirectoryFactoryOptions = {
+    exclude?: string[];
+    recurse?: boolean;
+};
 /** Loader lifecycle state. Mirrors Java's MetaDataLoader phase enum. */
 export type LoadingState = "uninitialized" | "loading" | "loaded" | "error";
 export interface LoadOptions {
@@ -15,7 +20,13 @@ export interface LoadOptions {
 }
 export interface LoadResult {
     root: MetaRoot;
-    warnings: string[];
+    /** Cross-port-aligned warning envelopes per ADR-0009.
+     *  FR5a creates the channel; FR5c (overlay-merge duplicate detection)
+     *  will be the first feature to populate it. Legacy string warnings
+     *  collected during parse/validation are wrapped at the loader boundary
+     *  with `code: "WARN_LEGACY"` and `source: { format: "code" }` so the
+     *  channel always presents the envelope shape to consumers. */
+    warnings: LoaderWarning[];
     errors: Error[];
 }
 export declare class MetaDataLoader {
@@ -26,6 +37,27 @@ export declare class MetaDataLoader {
     private _root;
     constructor(opts?: LoadOptions);
     private static _defaultRegistry;
+    /**
+     * Load every supported file (`.json` / `.yaml` / `.yml`) under `dir` in
+     * deterministic ordinal-basename order. Recurses by default.
+     *
+     * Convenience for the typical "load a directory of metadata" path. The
+     * `DirectorySource` impl is loaded lazily to keep the package root
+     * browser-safe (the underlying source uses node:fs).
+     *
+     * A missing/unreadable directory is surfaced as a collected entry in
+     * `result.errors`; the loader returns a synthetic empty root rather than
+     * throwing — preserves the `meta export` CLI exit-code contract.
+     */
+    static fromDirectory(dir: string, opts?: DirectoryFactoryOptions & LoadOptions): Promise<LoadResult>;
+    /**
+     * Load each URI as a {@link UriSource}. Supports `file://`, `http://`,
+     * `https://` schemes. The source impl is loaded lazily to keep the package
+     * root browser-safe.
+     */
+    static fromUris(uris: string[], opts?: LoadOptions): Promise<LoadResult>;
+    /** Load a single in-memory string of the given format. */
+    static fromString(content: string, format: MetaDataFormat, opts?: LoadOptions): Promise<LoadResult>;
     /** Current loading state. */
     get state(): LoadingState;
     /**
@@ -65,12 +97,20 @@ export declare class MetaDataLoader {
      */
     childrenOfType(type: string): MetaData[];
     /**
-     * Parse one source's raw content into a ParseResult. The base loader handles
-     * JSON only; a non-JSON format throws. Subclasses override this seam to add
-     * formats — e.g. FileMetaDataLoader (in @metaobjectsdev/metadata/core) adds YAML.
-     * This keeps the browser-safe base loader free of the YAML parser.
+     * Parse one source's raw content into a ParseResult. Dispatches on the
+     * source's declared `format` — `"json"` runs the canonical JSON parser,
+     * `"yaml"` desugars the authoring YAML into canonical JSON via parseYaml.
+     * Cross-language consistent: the same format vocabulary is honored by the
+     * Java / C# / Python MetaDataLoaders.
+     *
+     * The YAML parser is loaded lazily so the browser-safe root entry never
+     * statically pulls in the `yaml` dependency — see the module-header comment.
+     * `parseYaml` is preloaded inside `load()` if any source declares YAML
+     * format so the call here can stay synchronous.
      */
     protected parseSource(content: string, source: MetaDataSource, parseOpts: ParseOptions): ParseResult;
+    private static _yamlParser;
+    private static _ensureYamlParser;
     /**
      * Load metadata from one or more MetaDataSource instances. Sources are read
      * in order; each source's content is parsed and merged into the accumulating
@@ -84,4 +124,5 @@ export declare class MetaDataLoader {
      */
     load(sources: MetaDataSource[]): Promise<LoadResult>;
 }
+export {};
 //# sourceMappingURL=meta-data-loader.d.ts.map

package/dist/loader/meta-data-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meta-data-loader.d.ts","sourceRoot":"","sources":["../../src/loader/meta-data-loader.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAU,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAWtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAMnE,wEAAwE;AACxE,MAAM,MAAM,YAAY,GAAG,eAAe,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE5E,MAAM,WAAW,WAAW;IAC1B,0GAA0G;IAC1G,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAcD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAElC,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,KAAK,CAAuB;gBAExB,IAAI,CAAC,EAAE,WAAW;IAM9B,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAQ/B,6BAA6B;IAC7B,IAAI,KAAK,IAAI,YAAY,CAExB;IAED;;;;;;;OAOG;IACH,IAAI,QAAQ,IAAI,YAAY,CAE3B;IAED;;;;OAIG;IACH,IAAI,IAAI,IAAI,QAAQ,CAGnB;IAED;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAK9C;;;OAGG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAKnE;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE;IASxC;;;;;OAKG;IACH,SAAS,CAAC,WAAW,CACnB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,YAAY,GACtB,WAAW;IAcd;;;;;;;;;;OAUG;IACG,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;CAgI3D"}
+{"version":3,"file":"meta-data-loader.d.ts","sourceRoot":"","sources":["../../src/loader/meta-data-loader.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAU,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAKtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAQlD,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5E,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAOnE,KAAK,uBAAuB,GAAG;IAC7B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAYF,wEAAwE;AACxE,MAAM,MAAM,YAAY,GAAG,eAAe,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE5E,MAAM,WAAW,WAAW;IAC1B,0GAA0G;IAC1G,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,CAAC;IACf;;;;;mEAK+D;IAC/D,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAcD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAElC,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,KAAK,CAAuB;gBAExB,IAAI,CAAC,EAAE,WAAW;IAM9B,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAQ/B;;;;;;;;;;;OAWG;WACU,aAAa,CACxB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,uBAAuB,GAAG,WAAW,GAC3C,OAAO,CAAC,UAAU,CAAC;IA0BtB;;;;OAIG;WACU,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAM9E,0DAA0D;WAC7C,UAAU,CACrB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,cAAc,EACtB,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,UAAU,CAAC;IAQtB,6BAA6B;IAC7B,IAAI,KAAK,IAAI,YAAY,CAExB;IAED;;;;;;;OAOG;IACH,IAAI,QAAQ,IAAI,YAAY,CAE3B;IAED;;;;OAIG;IACH,IAAI,IAAI,IAAI,QAAQ,CAGnB;IAED;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAK9C;;;OAGG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAKnE;;;OAGG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE;IASxC;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,WAAW,CACnB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,YAAY,GACtB,WAAW;IAuBd,OAAO,CAAC,MAAM,CAAC,WAAW,CAEZ;mBAEO,iBAAiB;IAUtC;;;;;;;;;;OAUG;IACG,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;CAuK3D"}