@metaobjectsdev/metadata 0.6.0 → 0.7.0-rc.2

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);
+}

package/src/loader/sources/directory-source.ts

@@ -0,0 +1,90 @@
+// DirectorySource — expands a directory into a sorted list of FileSource.
+//
+// Discovers .json / .yaml / .yml files (case-insensitive on extension).
+// Recurses by default — matches Java/Python/C# DirectorySource behavior.
+// Sort order is ordinal-by-basename so the overlay merge is deterministic
+// across environments and language ports.
+
+import { readdir, stat } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+import { FileSource } from "./file-source.js";
+import type { MetaDataSource } from "../meta-data-source.js";
+
+export interface DirectoryOptions {
+  /** Filename patterns to exclude. Supports literal match and `*` / `**` globs. */
+  exclude?: string[];
+  /** Recurse into subdirectories. Default: true. */
+  recurse?: boolean;
+}
+
+const SUPPORTED_EXTS = new Set([".json", ".yaml", ".yml"]);
+
+/** Minimal glob matcher supporting `*` (any chars except `/`) and `**` (any chars). */
+function matchSimpleGlob(pattern: string, value: string): boolean {
+  const regexStr = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, "::DOUBLESTAR::")
+    .replace(/\*/g, "[^/]*")
+    .replace(/::DOUBLESTAR::/g, ".*");
+  return new RegExp(`^${regexStr}$`).test(value);
+}
+
+export class DirectorySource {
+  constructor(
+    public readonly directory: string,
+    public readonly opts: DirectoryOptions = {},
+  ) {}
+
+  async expand(): Promise<MetaDataSource[]> {
+    const recurse = this.opts.recurse ?? true;
+    const exclude = this.opts.exclude ?? [];
+
+    const files = await this.collect(this.directory, recurse);
+    const filtered: string[] = [];
+    for (const p of files) {
+      if (!SUPPORTED_EXTS.has(extname(p).toLowerCase())) continue;
+      const name = basename(p);
+      if (exclude.some((pat) => matchSimpleGlob(pat, name))) continue;
+      filtered.push(p);
+    }
+
+    // Sort by basename (ordinal) for deterministic overlay order. The
+    // pre-unification FileMetaDataLoader sorted readdir entries (basenames)
+    // for the same reason — that contract carries forward here.
+    filtered.sort((a, b) => {
+      const an = basename(a);
+      const bn = basename(b);
+      return an < bn ? -1 : an > bn ? 1 : 0;
+    });
+
+    return filtered.map((p) => new FileSource(p));
+  }
+
+  private async collect(dir: string, recurse: boolean): Promise<string[]> {
+    let entries: string[];
+    try {
+      entries = await readdir(dir);
+    } catch (err) {
+      throw new Error(
+        `DirectorySource: cannot read ${dir}: ${(err as Error).message}`,
+      );
+    }
+    const out: string[] = [];
+    for (const entry of entries) {
+      const full = join(dir, entry);
+      let s;
+      try {
+        s = await stat(full);
+      } catch {
+        // Entry vanished between readdir and stat (TOCTOU) or is not accessible.
+        continue;
+      }
+      if (s.isDirectory()) {
+        if (recurse) out.push(...(await this.collect(full, recurse)));
+      } else if (s.isFile()) {
+        out.push(full);
+      }
+    }
+    return out;
+  }
+}

package/src/{core → loader/sources}/file-source.ts

@@ -1,9 +1,9 @@
 // FileSource — a MetaDataSource backed by a file on disk. Server-side only
-// (touches node:fs); lives under src/core/ so the browser-safe root never
-// imports it.
+// (touches node:fs); lives under src/loader/sources/ alongside the other
+// MetaDataSource implementations.
 
 import { basename, extname } from "node:path";
-import type { MetaDataFormat, MetaDataSource } from "../loader/meta-data-source.js";
+import type { MetaDataFormat, MetaDataSource } from "../meta-data-source.js";
 
 /** Infer a source format from a file extension. `.yaml`/`.yml` → "yaml";
  *  everything else (including `.json`) → "json", the canonical default. */

package/src/loader/sources/index.ts

@@ -0,0 +1,6 @@
+// Barrel re-export for the MetaDataSource implementations.
+
+export { FileSource } from "./file-source.js";
+export { DirectorySource } from "./directory-source.js";
+export type { DirectoryOptions } from "./directory-source.js";
+export { UriSource } from "./uri-source.js";

package/src/loader/sources/uri-source.ts

@@ -0,0 +1,44 @@
+// UriSource — a MetaDataSource that fetches content from a URI.
+// Supports file://, http://, and https:// schemes.
+
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { extname } from "node:path";
+import type { MetaDataFormat, MetaDataSource } from "../meta-data-source.js";
+
+function inferFormat(uri: string): MetaDataFormat {
+  // URL constructor handles file://, http://, https:// uniformly.
+  // Strip query/fragment by reading .pathname.
+  try {
+    const pathname = new URL(uri).pathname;
+    const ext = extname(pathname).toLowerCase();
+    return ext === ".yaml" || ext === ".yml" ? "yaml" : "json";
+  } catch {
+    // If the URI isn't a valid URL, fall back to JSON.
+    return "json";
+  }
+}
+
+export class UriSource implements MetaDataSource {
+  readonly id: string;
+  readonly format: MetaDataFormat;
+
+  constructor(public readonly uri: string, format?: MetaDataFormat) {
+    this.id = uri;
+    this.format = format ?? inferFormat(uri);
+  }
+
+  async read(): Promise<string> {
+    if (this.uri.startsWith("file://")) {
+      return readFile(fileURLToPath(this.uri), "utf-8");
+    }
+    if (this.uri.startsWith("http://") || this.uri.startsWith("https://")) {
+      const res = await fetch(this.uri);
+      if (!res.ok) {
+        throw new Error(`UriSource: ${this.uri} -> HTTP ${res.status}`);
+      }
+      return res.text();
+    }
+    throw new Error(`UriSource: unsupported scheme on ${this.uri}`);
+  }
+}