@metaobjectsdev/metadata 0.6.0 → 0.7.0-rc.10

package/src/core/yaml-positions.ts

@@ -0,0 +1,80 @@
+// 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",
+);
+
+/** 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 function getPositionMap(obj: unknown): PositionMap | undefined {
+  if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
+    return undefined;
+  }
+  return (obj as { [YAML_POSITION_BY_KEY]?: PositionMap })[YAML_POSITION_BY_KEY];
+}
+
+/** Read the position for a specific key on a mapping object. */
+export function getYamlPosition(
+  obj: unknown,
+  key: string,
+): YamlPosition | undefined {
+  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: Record<string, unknown>,
+  positions: PositionMap,
+): void {
+  Object.defineProperty(obj, YAML_POSITION_BY_KEY, {
+    value: positions,
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+}

package/src/core-types.ts

@@ -279,10 +279,13 @@ function registerCoreTypeDefs(registry: TypeRegistry): void {
     );
   }
 
-  // template — renderable text artifacts (FR-004). prompt + output; attr-only
-  // children. A single MetaTemplate class backs both subtypes (mirrors source);
-  // per-subtype attr schemas drive validation (both require @payloadRef +
-  // @textRef; @format is a closed enum; template.prompt adds the LLM overlay).
+  // template — renderable text artifacts (FR-004) + tool-call envelopes
+  // (ADR-0011). Three subtypes: prompt + output + toolcall; attr-only children.
+  // A single MetaTemplate class backs all three subtypes (mirrors source);
+  // per-subtype attr schemas drive validation (prompt + output require
+  // @payloadRef + @textRef + @format closed enum; prompt adds the LLM overlay;
+  // toolcall has its own set — @toolName + @payloadRef + @description, no
+  // @textRef requirement since toolcalls have no renderable body).
   for (const subType of TEMPLATE_SUBTYPES) {
     const templateAttrs = TEMPLATE_ATTRS_MAP.get(subType) ?? [];
     registry.register(

package/src/errors.ts

@@ -1,5 +1,7 @@
 // Typed error classes for the metadata parser.
 
+import type { ErrorSource, LoaderError, NodeContext } from "./source.js";
+
 /** Stable, language-neutral error codes — mirrors fixtures/conformance/ERROR-CODES.json. */
 // NOTE: The following codes are forward-declared (no emitting site in the current
 // TS parser/loader — the condition is not yet detected):
@@ -50,25 +52,72 @@ 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",
 ] as const;
 
+/** 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",
+] as const;
+export type WarningCode = (typeof WARNING_CODES)[number];
+
 export type ErrorCode = (typeof ERROR_CODES)[number];
 
-export class ParseError extends Error {
-  readonly source: string | undefined;
-  readonly path: string | undefined; // logical path within the JSON, e.g. "metadata.children[2].field"
-  readonly code: ErrorCode | undefined;
+/**
+ * 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 implements LoaderError {
+  readonly code: ErrorCode;
+  readonly source: ErrorSource;
+  readonly suggestions?: string[];
+  readonly fixture?: string;
+  readonly node?: NodeContext;
 
   constructor(
     message: string,
-    opts?: { source?: string; path?: string; code?: ErrorCode },
+    opts: {
+      code: ErrorCode;
+      source: ErrorSource;
+      suggestions?: string[];
+      fixture?: string;
+      node?: NodeContext;
+    },
   ) {
     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 as { suggestions?: string[] }).suggestions = opts.suggestions;
+    }
+    if (opts.fixture !== undefined) {
+      (this as { fixture?: string }).fixture = opts.fixture;
+    }
+    if (opts.node !== undefined) {
+      (this as { node?: NodeContext }).node = opts.node;
+    }
   }
 }
 

package/src/index.ts

@@ -150,13 +150,37 @@ export { resolveSuperRef } from "./super-resolve.js";
 // Loader hierarchy
 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";
 
+// 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 type { ErrorCode } from "./errors.js";
 
+// FR5a — loader error envelope + source-on-node (ADR-0009).
+// Re-exported from the package root so consumers that catch + repackage
+// ParseErrors (or narrow on `err.source.format === "json"`) can import the
+// envelope types alongside the runtime discriminator.
+export type {
+  ErrorSource,
+  LoaderError,
+  LoaderWarning,
+  NodeContext,
+  Contributor,
+} from "./source.js";
+export { codeSource } from "./source.js";
+
 // Attribute-schema validation pass (Phase A3)
 export { validateAttrSchema } from "./attr-schema-validate.js";
 export type { AttrSchemaValidationResult } from "./attr-schema-validate.js";
@@ -164,9 +188,10 @@ export type { AttrSchemaValidationResult } 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,
+  toSnakeCase, toKebabCase, pluralize,
+  applyColumnNamingStrategy, DEFAULT_COLUMN_NAMING_STRATEGY,
   resolveTableName, resolveColumnName, resolveTableSchema,
   buildNameMap,
   stripPackage,
 } from "./naming.js";
-export type { EntityNameMap } from "./naming.js";
+export type { EntityNameMap, ColumnNamingStrategy } from "./naming.js";

package/src/json-path.ts

@@ -0,0 +1,46 @@
+// 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_]*$/;
+
+type Segment =
+  | { kind: "key"; value: string }
+  | { kind: "index"; value: number };
+
+export class JsonPathBuilder {
+  private readonly segments: Segment[] = [];
+
+  pushKey(key: string): void {
+    this.segments.push({ kind: "key", value: key });
+  }
+
+  pushIndex(idx: number): void {
+    this.segments.push({ kind: "index", value: idx });
+  }
+
+  pop(): void {
+    this.segments.pop();
+  }
+
+  toString(): string {
+    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;
+  }
+}

package/src/loader/meta-data-loader.ts

@@ -14,15 +14,34 @@ import { coreProviders } from "../core-types.js";
 import { composeRegistry } from "../provider.js";
 import { TYPE_METADATA, SUBTYPE_ROOT } from "../shared/base-types.js";
 import { ParseError } from "../errors.js";
+import type { LoaderWarning } from "../source.js";
+import { codeSource, resolvedSource } from "../source.js";
 import { parseJson } from "../parser-json.js";
 import { validateDataGridSortFields, validateFilterableHasIndex, validateOriginPaths, validateDataGridFilterValues, validateFieldObjectStorage, validateTemplatePayloadRefs } from "./validation-passes.js";
 import { validateSourceRoles } from "../persistence/source/validate-source-roles.js";
 import { resolveDeferredSupers } from "../super-resolve.js";
 import { validateSubtypeRules } from "../subtype-rules.js";
 import { validateAttrSchema } from "../attr-schema-validate.js";
-import type { MetaDataSource } from "./meta-data-source.js";
+import type { MetaDataFormat, MetaDataSource } from "./meta-data-source.js";
+import { InMemoryStringSource } from "./meta-data-source.js";
 import type { ParseOptions, ParseResult } from "../parser-core.js";
 
+// Local mirror of DirectorySource's options shape. Deliberately inlined here
+// (instead of `import type`'d from ./sources/directory-source.js) so the
+// browser-safety crawler — which walks every `import|export from` it sees,
+// type-only or not — never follows a path into a node:fs-using file.
+// Keep field-for-field in sync with `DirectoryOptions` in `./sources/directory-source.ts`.
+type DirectoryFactoryOptions = {
+  exclude?: string[];
+  recurse?: boolean;
+};
+
+// YAML parser and node:fs-backed Source impls are loaded lazily (dynamic
+// import) inside the methods that need them. Reason: the package root
+// (src/index.ts) re-exports MetaDataLoader and must stay browser-safe —
+// the browser-safety test asserts that no file reachable from index.ts
+// statically imports `yaml` or `node:fs(/promises)`.
+
 // ---------------------------------------------------------------------------
 // Public API types
 // ---------------------------------------------------------------------------
@@ -41,7 +60,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[];
 }
 
@@ -75,6 +100,71 @@ export class MetaDataLoader {
     return composeRegistry(coreProviders);
   }
 
+  // ---------------------------------------------------------------------------
+  // Static factories — the 99% case (cross-language consistent)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * 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 async fromDirectory(
+    dir: string,
+    opts?: DirectoryFactoryOptions & LoadOptions,
+  ): Promise<LoadResult> {
+    const { exclude, recurse, ...loaderOpts } = opts ?? {};
+    // Conditional spreads honor exactOptionalPropertyTypes — only forward keys
+    // when the caller supplied a value, so DirectorySource's own defaults apply.
+    const dirOpts: DirectoryFactoryOptions = {
+      ...(exclude !== undefined && { exclude }),
+      ...(recurse !== undefined && { recurse }),
+    };
+    const { DirectorySource } = await import("./sources/directory-source.js");
+    const loader = new MetaDataLoader(loaderOpts);
+    try {
+      const sources = await new DirectorySource(dir, dirOpts).expand();
+      return loader.load(sources);
+    } catch (err) {
+      // Match the pre-unification contract: a missing/unreadable directory is
+      // surfaced as a collected error on the LoadResult, not a throw. The
+      // pipeline still completes with a synthetic empty root.
+      const emptyResult = await loader.load([]);
+      const expandErr =
+        err instanceof Error
+          ? err
+          : new Error(`MetaDataLoader.fromDirectory: ${String(err)}`);
+      return { ...emptyResult, errors: [expandErr, ...emptyResult.errors] };
+    }
+  }
+
+  /**
+   * 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 async fromUris(uris: string[], opts?: LoadOptions): Promise<LoadResult> {
+    const { UriSource } = await import("./sources/uri-source.js");
+    const sources = uris.map((u) => new UriSource(u));
+    return new MetaDataLoader(opts).load(sources);
+  }
+
+  /** Load a single in-memory string of the given format. */
+  static async fromString(
+    content: string,
+    format: MetaDataFormat,
+    opts?: LoadOptions,
+  ): Promise<LoadResult> {
+    return new MetaDataLoader(opts).load([new InMemoryStringSource(content, { format })]);
+  }
+
   // ---------------------------------------------------------------------------
   // Lifecycle
   // ---------------------------------------------------------------------------
@@ -156,10 +246,16 @@ export class MetaDataLoader {
   // ---------------------------------------------------------------------------
 
   /**
-   * 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,
@@ -169,12 +265,35 @@ export class MetaDataLoader {
     if (source.format === "json") {
       return parseJson(content, parseOpts);
     }
+    if (source.format === "yaml") {
+      const fn = MetaDataLoader._yamlParser;
+      if (fn === undefined) {
+        throw new Error(
+          `MetaDataLoader: YAML parser was not preloaded — this is an internal bug. ` +
+            `Source "${source.id}" declares format "yaml".`,
+        );
+      }
+      return fn(content, parseOpts);
+    }
     throw new Error(
-      `MetaDataLoader parses JSON only; format "${source.format}" for source ` +
-        `"${source.id}" requires FileMetaDataLoader (from @metaobjectsdev/metadata/core)`,
+      `MetaDataLoader: unsupported source format "${source.format}" ` +
+        `on source "${source.id}"`,
     );
   }
 
+  // Cached lazy YAML parser — populated by _ensureYamlParser() before
+  // parseSource is invoked on a YAML source. Module-level cache (one import
+  // per process) keeps the per-load cost negligible.
+  private static _yamlParser:
+    | ((content: string, opts: ParseOptions) => ParseResult)
+    | undefined;
+
+  private static async _ensureYamlParser(): Promise<void> {
+    if (MetaDataLoader._yamlParser !== undefined) return;
+    const mod = await import("../core/parser-yaml.js");
+    MetaDataLoader._yamlParser = mod.parseYaml;
+  }
+
   // ---------------------------------------------------------------------------
   // load — async pipeline over MetaDataSource[]
   // ---------------------------------------------------------------------------
@@ -202,6 +321,19 @@ export class MetaDataLoader {
     this._state = "loading";
     const warnings: string[] = [];
     const errors: Error[] = [];
+    // FR5c — envelope-shaped warnings (WARN_DUPLICATE_DECLARATION et al.)
+    // surface here untouched. Distinct from the legacy `warnings: string[]`
+    // channel: those are wrapped in a WARN_LEGACY envelope at the boundary,
+    // while these already carry their own code + source.
+    const envelopeWarnings: LoaderWarning[] = [];
+
+    // Pre-load the YAML parser via dynamic import if any source declares
+    // YAML format. This keeps `parseSource` synchronous and the package root
+    // (src/index.ts) browser-safe — yaml is never statically imported from a
+    // file reachable from the package entry. See `_ensureYamlParser`.
+    if (sources.some((s) => s.format === "yaml")) {
+      await MetaDataLoader._ensureYamlParser();
+    }
 
     let root: MetaRoot | undefined;
 
@@ -236,6 +368,10 @@ export class MetaDataLoader {
         const parseResult = this.parseSource(content, source, parseOpts);
         warnings.push(...parseResult.warnings);
         errors.push(...parseResult.errors);
+        // FR5c — collect envelope-shaped warnings (already carry code +
+        // source). The legacy `warnings` channel still flows into the
+        // WARN_LEGACY-wrapping path below for unchanged behavior.
+        envelopeWarnings.push(...parseResult.envelopeWarnings);
         root = parseResult.root;
       } catch (err) {
         errors.push(
@@ -252,10 +388,17 @@ export class MetaDataLoader {
     if (root !== undefined) {
       const failures = resolveDeferredSupers(root);
       for (const failure of failures) {
+        // FR5d — emit format=resolved with referrer + target. The referrer's
+        // parse-time source supplies files + jsonPath (the location of the
+        // broken `extends:` on disk); referrer = the declaring node's FQN;
+        // target = the unresolved supertype ref.
         errors.push(
           new ParseError(
             `the SuperClass '${failure.ref}' does not exist (referenced by ${failure.nodeFqn})`,
-            { code: "ERR_UNRESOLVED_SUPER" },
+            {
+              code: "ERR_UNRESOLVED_SUPER",
+              source: resolvedSource(failure.source, failure.nodeFqn, failure.ref),
+            },
           ),
         );
       }
@@ -316,6 +459,21 @@ export class MetaDataLoader {
     }
 
     this._root = root;
-    return { root, warnings, errors };
+    // Wrap legacy string warnings collected from parser-core / validators in
+    // LoaderWarning envelopes at the loader boundary. The parser/validator
+    // surface keeps its `string[]` shape internally (parser-core is shared
+    // with parseJson() / parseYaml() callers who consume string warnings
+    // directly). FR5c-onward sites emit proper envelopes via parseResult.
+    // envelopeWarnings (collected above) — those surface unchanged.
+    const wrappedLegacy: LoaderWarning[] = warnings.map((msg) => ({
+      code: "WARN_LEGACY",
+      message: msg,
+      source: codeSource("MetaDataLoader"),
+    }));
+    return {
+      root,
+      warnings: [...envelopeWarnings, ...wrappedLegacy],
+      errors,
+    };
   }
 }

package/src/loader/meta-data-source.ts

@@ -1,8 +1,8 @@
 // MetaDataSource — the raw-document unit consumed by the loader pipeline.
 //
-// A loader (FileMetaDataLoader, later UrlMetaDataLoader) discovers/acquires
-// sources; the MetaDataLoader pipeline calls read() on each. read() is async
-// so file/URL sources can do I/O; InMemorySource resolves immediately.
+// A loader (MetaDataLoader, fed by FileSource/DirectorySource/UriSource/
+// InMemoryStringSource) parses each source's content. read() is async so file
+// and URI sources can do I/O; InMemoryStringSource resolves immediately.
 
 /** Format of a source's content. Selects the parser. */
 export type MetaDataFormat = "json" | "yaml";
@@ -17,15 +17,19 @@ export interface MetaDataSource {
   read(): Promise<string>;
 }
 
-/** A metadata source backed by an in-memory string. */
-export class InMemorySource implements MetaDataSource {
+/**
+ * A metadata source backed by an in-memory string. The default identity is
+ * `"<inline>"` — matches the cross-language convention shared by the Java /
+ * C# / Python ports.
+ */
+export class InMemoryStringSource implements MetaDataSource {
   readonly id: string;
   readonly format: MetaDataFormat;
   private readonly _content: string;
 
   constructor(content: string, opts?: { id?: string; format?: MetaDataFormat }) {
     this._content = content;
-    this.id = opts?.id ?? "<in-memory>";
+    this.id = opts?.id ?? "<inline>";
     this.format = opts?.format ?? "json";
   }
 

package/src/loader/shortcuts.ts

@@ -0,0 +1,31 @@
+// Module-level loader shortcuts — one-liners that delegate to the
+// MetaDataLoader.from* static factories. Per the cross-language convention:
+// TS and Python expose both class statics AND module-level shortcuts; Java
+// and C# stay class-only.
+//
+// These functions do not statically import any node:fs- or yaml-using file;
+// MetaDataLoader.from* loads the underlying source impls via dynamic import,
+// preserving the package root's browser-safety contract.
+
+import { MetaDataLoader } from "./meta-data-loader.js";
+import type { LoadOptions, LoadResult } from "./meta-data-loader.js";
+import type { MetaDataFormat } from "./meta-data-source.js";
+
+export function loadDirectory(
+  dir: string,
+  opts?: { exclude?: string[]; recurse?: boolean } & LoadOptions,
+): Promise<LoadResult> {
+  return MetaDataLoader.fromDirectory(dir, opts);
+}
+
+export function loadUris(uris: string[], opts?: LoadOptions): Promise<LoadResult> {
+  return MetaDataLoader.fromUris(uris, opts);
+}
+
+export function loadString(
+  content: string,
+  format: MetaDataFormat,
+  opts?: LoadOptions,
+): Promise<LoadResult> {
+  return MetaDataLoader.fromString(content, format, opts);
+}