@metaobjectsdev/metadata 0.6.0 → 0.7.0-rc.10

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

package/src/loader/validation-passes.ts

@@ -11,6 +11,7 @@
 
 import type { MetaData } from "../shared/meta-data.js";
 import { ParseError } from "../errors.js";
+import { resolvedSource, type ErrorSource } from "../source.js";
 import {
   TYPE_OBJECT,
   TYPE_FIELD,
@@ -24,6 +25,7 @@ import {
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_REQUIRED_SLOTS,
 } from "../template/template-constants.js";
+import { OBJECT_SUBTYPE_VALUE } from "../core/object/object-constants.js";
 import {
   LAYOUT_SUBTYPE_DATA_GRID,
   LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD,
@@ -72,7 +74,7 @@ export function validateDataGridSortFields(root: MetaData): ParseError[] {
           new ParseError(
             `dataGrid layout "${layout.name}" on entity "${obj.name}" has @defaultSortField "${sortField}" ` +
             `but no such field exists on "${obj.name}". Available fields: ${[...fieldNames].join(", ")}`,
-            { code: "ERR_BAD_DEFAULT_SORT_FIELD" },
+            { code: "ERR_BAD_DEFAULT_SORT_FIELD", source: layout.source },
           ),
         );
       }
@@ -98,11 +100,16 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
     const payloadRef = tmpl.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
     if (typeof payloadRef !== "string") continue; // absence handled by the required-attr schema check
     const payload = root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === payloadRef);
-    if (!payload) {
+    if (!payload || payload.subType !== OBJECT_SUBTYPE_VALUE) {
+      // FR5d — @payloadRef is a reference; emit format=resolved with
+      // referrer=template FQN, target=the unresolved payloadRef string.
       errors.push(
         new ParseError(
-          `template "${tmpl.name}" @payloadRef "${payloadRef}" does not resolve to a known object in this model`,
-          { code: "ERR_INVALID_TEMPLATE" },
+          `template "${tmpl.name}" @payloadRef "${payloadRef}" does not resolve to an object.value at root`,
+          {
+            code: "ERR_INVALID_TEMPLATE",
+            source: resolvedSource(tmpl.source, tmpl.fqn(), payloadRef),
+          },
         ),
       );
       continue;
@@ -114,11 +121,17 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
     const slotList = Array.isArray(slots) ? slots : typeof slots === "string" ? [slots] : [];
     for (const slot of slotList) {
       if (typeof slot === "string" && !fieldNames.has(slot)) {
+        // FR5d — @requiredSlots is a field-on-payload reference; emit
+        // format=resolved with referrer=template FQN, target=`payloadRef.slot`
+        // (the dotted ref that did not resolve to a payload field).
         errors.push(
           new ParseError(
             `template "${tmpl.name}" @requiredSlots "${slot}" is not a field on payload "${payloadRef}". ` +
             `Available fields: ${[...fieldNames].join(", ")}`,
-            { code: "ERR_INVALID_TEMPLATE" },
+            {
+              code: "ERR_INVALID_TEMPLATE",
+              source: resolvedSource(tmpl.source, tmpl.fqn(), `${payloadRef}.${slot}`),
+            },
           ),
         );
       }
@@ -194,17 +207,28 @@ function _findRelationship(obj: MetaData, name: string): MetaData | undefined {
 function _validateFromPath(
   fromAttr: string,
   root: MetaData,
-  projectionName: string,
+  projection: MetaData,
   fieldName: string,
+  originSource: ErrorSource,
   errors: ParseError[],
   label: string = "origin.passthrough.@from",
 ): void {
+  const projectionName = projection.name;
+  // FR5d — referrer is `<projection-FQN>::<fieldName>` (the canonical
+  // "where the broken reference lives" identifier).
+  const referrer = `${projection.fqn()}::${fieldName}`;
   const dotIdx = fromAttr.indexOf(".");
   if (dotIdx < 1 || dotIdx === fromAttr.length - 1) {
+    // Malformed shape (not "Entity.field") — not a reference resolution
+    // failure per se, but emit format=resolved with target=the bad string
+    // so consumers see the same envelope shape across all FR5d sites.
     errors.push(
       new ParseError(
         `${label} "${fromAttr}" on ${projectionName}.${fieldName}: must be of form "Entity.field".`,
-        { code: "ERR_INVALID_ORIGIN" },
+        {
+          code: "ERR_INVALID_ORIGIN",
+          source: resolvedSource(originSource, referrer, fromAttr),
+        },
       ),
     );
     return;
@@ -213,20 +237,28 @@ function _validateFromPath(
   const targetFieldName = fromAttr.slice(dotIdx + 1);
   const sourceObj = _findObject(root, entityName);
   if (!sourceObj) {
+    // FR5d — entity half of the ref didn't resolve. target = full ref.
     errors.push(
       new ParseError(
         `${label} "${fromAttr}" on ${projectionName}.${fieldName}: no such entity "${entityName}".`,
-        { code: "ERR_INVALID_ORIGIN" },
+        {
+          code: "ERR_INVALID_ORIGIN",
+          source: resolvedSource(originSource, referrer, fromAttr),
+        },
       ),
     );
     return;
   }
   const sourceField = _findField(sourceObj, targetFieldName);
   if (!sourceField) {
+    // FR5d — entity resolved, field on it did not. target = full ref.
     errors.push(
       new ParseError(
         `${label} "${fromAttr}" on ${projectionName}.${fieldName}: no such field "${targetFieldName}" on ${entityName}.`,
-        { code: "ERR_INVALID_ORIGIN" },
+        {
+          code: "ERR_INVALID_ORIGIN",
+          source: resolvedSource(originSource, referrer, fromAttr),
+        },
       ),
     );
   }
@@ -235,16 +267,23 @@ function _validateFromPath(
 function _validateViaPath(
   viaAttr: string,
   root: MetaData,
-  projectionName: string,
+  projection: MetaData,
   fieldName: string,
+  originSource: ErrorSource,
   errors: ParseError[],
 ): void {
+  const projectionName = projection.name;
+  // FR5d — referrer is `<projection-FQN>::<fieldName>`.
+  const referrer = `${projection.fqn()}::${fieldName}`;
   const segments = viaAttr.split(".");
   if (segments.length < 2) {
     errors.push(
       new ParseError(
         `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: must be of form "Entity.relationship[.relationship...]".`,
-        { code: "ERR_INVALID_ORIGIN" },
+        {
+          code: "ERR_INVALID_ORIGIN",
+          source: resolvedSource(originSource, referrer, viaAttr),
+        },
       ),
     );
     return;
@@ -255,18 +294,32 @@ function _validateViaPath(
     errors.push(
       new ParseError(
         `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: no such entity "${entityName}".`,
-        { code: "ERR_INVALID_ORIGIN" },
+        {
+          code: "ERR_INVALID_ORIGIN",
+          source: resolvedSource(originSource, referrer, viaAttr),
+        },
       ),
     );
     return;
   }
+  // FR5d — track the deepest-valid-prefix as we walk. The prefix grows
+  // segment-by-segment; on a hop failure the error message names the prefix
+  // that DID resolve, so authors can fix multi-hop typos quickly.
+  // After the entity lookup above, the deepest valid prefix is just the
+  // entity name; each successful relationship hop appends a segment.
+  const validSegments: string[] = [entityName];
   for (const relName of relSegments) {
     const rel = _findRelationship(currentObj, relName);
     if (!rel) {
+      const prefix = validSegments.join(".");
       errors.push(
         new ParseError(
-          `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: no such relationship "${relName}" on ${currentObj.name}.`,
-          { code: "ERR_INVALID_ORIGIN" },
+          `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: no such relationship "${relName}" on ${currentObj.name}. ` +
+          `Deepest valid prefix was "${prefix}".`,
+          {
+            code: "ERR_INVALID_ORIGIN",
+            source: resolvedSource(originSource, referrer, viaAttr),
+          },
         ),
       );
       return;
@@ -276,21 +329,32 @@ function _validateViaPath(
       errors.push(
         new ParseError(
           `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: relationship "${relName}" on ${currentObj.name} is missing @objectRef.`,
-          { code: "ERR_INVALID_ORIGIN" },
+          {
+            code: "ERR_INVALID_ORIGIN",
+            source: resolvedSource(originSource, referrer, viaAttr),
+          },
         ),
       );
       return;
     }
     const nextObj = _findObject(root, refTarget);
     if (!nextObj) {
+      // FR5d — relationship's @objectRef points at a missing entity. This
+      // is the @objectRef-resolution edge of the via-path walk (the "5th
+      // site" in FR5d's scope list for @objectRef references encountered
+      // transitively).
       errors.push(
         new ParseError(
           `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: relationship "${relName}" points to non-existent entity "${refTarget}".`,
-          { code: "ERR_INVALID_ORIGIN" },
+          {
+            code: "ERR_INVALID_ORIGIN",
+            source: resolvedSource(originSource, referrer, refTarget),
+          },
         ),
       );
       return;
     }
+    validSegments.push(relName);
     currentObj = nextObj;
   }
 }
@@ -303,18 +367,20 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
         if (origin.subType === ORIGIN_SUBTYPE_PASSTHROUGH) {
           const from = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_FROM);
           if (typeof from !== "string" || from === "") {
+            // Missing-attr (not a reference resolution failure) — keep the
+            // node's own source envelope (json/yaml/merged).
             errors.push(
               new ParseError(
                 `origin.passthrough on ${obj.name}.${field.name}: missing @from.`,
-                { code: "ERR_INVALID_ORIGIN" },
+                { code: "ERR_INVALID_ORIGIN", source: origin.source },
               ),
             );
             continue;
           }
-          _validateFromPath(from, root, obj.name, field.name, errors);
+          _validateFromPath(from, root, obj, field.name, origin.source, errors);
           const via = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_VIA);
           if (typeof via === "string" && via !== "") {
-            _validateViaPath(via, root, obj.name, field.name, errors);
+            _validateViaPath(via, root, obj, field.name, origin.source, errors);
           }
         } else if (origin.subType === ORIGIN_SUBTYPE_AGGREGATE) {
           const of_ = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_OF);
@@ -322,23 +388,23 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
             errors.push(
               new ParseError(
                 `origin.aggregate on ${obj.name}.${field.name}: missing @of.`,
-                { code: "ERR_INVALID_ORIGIN" },
+                { code: "ERR_INVALID_ORIGIN", source: origin.source },
               ),
             );
             continue;
           }
-          _validateFromPath(of_, root, obj.name, field.name, errors, "origin.aggregate.@of");
+          _validateFromPath(of_, root, obj, field.name, origin.source, errors, "origin.aggregate.@of");
           const via = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_VIA);
           if (typeof via !== "string" || via === "") {
             errors.push(
               new ParseError(
                 `origin.aggregate on ${obj.name}.${field.name}: missing @via (aggregates require a relationship path).`,
-                { code: "ERR_INVALID_ORIGIN" },
+                { code: "ERR_INVALID_ORIGIN", source: origin.source },
               ),
             );
             continue;
           }
-          _validateViaPath(via, root, obj.name, field.name, errors);
+          _validateViaPath(via, root, obj, field.name, origin.source, errors);
         }
       }
     }
@@ -371,7 +437,7 @@ export function validateFieldObjectStorage(root: MetaData): ParseError[] {
         errors.push(
           new ParseError(
             `field "${obj.name}.${field.name}" sets @storage but has no @objectRef`,
-            { code: "ERR_STORAGE_WITHOUT_OBJECT_REF" },
+            { code: "ERR_STORAGE_WITHOUT_OBJECT_REF", source: field.source },
           ),
         );
       }
@@ -379,7 +445,7 @@ export function validateFieldObjectStorage(root: MetaData): ParseError[] {
         errors.push(
           new ParseError(
             `field "${obj.name}.${field.name}" sets @storage "flattened" with isArray=true; flattened storage requires a single nested value`,
-            { code: "ERR_STORAGE_FLATTENED_ARRAY" },
+            { code: "ERR_STORAGE_FLATTENED_ARRAY", source: field.source },
           ),
         );
       }
@@ -413,7 +479,7 @@ export function validateDataGridFilterValues(root: MetaData): ParseError[] {
       const filter = layout.ownAttr(LAYOUT_DATA_GRID_ATTR_FILTER);
       // Type errors (e.g. legacy string form) are reported by validateAttrSchema.
       if (typeof filter !== "object" || filter === null || Array.isArray(filter)) continue;
-      checkFilterClauses(filter as Record<string, unknown>, allow, obj.name, layout.name, errors);
+      checkFilterClauses(filter as Record<string, unknown>, allow, obj.name, layout.name, layout.source, errors);
     }
   }
   return errors;
@@ -424,6 +490,7 @@ function checkFilterClauses(
   allow: Map<string, readonly string[]>,
   entityName: string,
   layoutName: string,
+  layoutSource: ErrorSource,
   errors: ParseError[],
 ): void {
   for (const [key, clause] of Object.entries(filter)) {
@@ -431,7 +498,7 @@ function checkFilterClauses(
       if (Array.isArray(clause)) {
         for (const sub of clause) {
           if (typeof sub === "object" && sub !== null && !Array.isArray(sub)) {
-            checkFilterClauses(sub as Record<string, unknown>, allow, entityName, layoutName, errors);
+            checkFilterClauses(sub as Record<string, unknown>, allow, entityName, layoutName, layoutSource, errors);
           }
         }
       }
@@ -443,7 +510,7 @@ function checkFilterClauses(
         new ParseError(
           `dataGrid layout "${layoutName}" on entity "${entityName}" has @filter over ` +
             `non-filterable field "${key}". Filterable fields: ${[...allow.keys()].join(", ") || "(none)"}`,
-          { code: "ERR_BAD_ATTR_FILTER" },
+          { code: "ERR_BAD_ATTR_FILTER", source: layoutSource },
         ),
       );
       continue;
@@ -457,7 +524,7 @@ function checkFilterClauses(
             new ParseError(
               `dataGrid layout "${layoutName}" on entity "${entityName}" @filter uses disallowed ` +
                 `op "${key}.${op}". Allowed ops for "${key}": ${allowedOps.join(", ")}`,
-              { code: "ERR_BAD_ATTR_FILTER" },
+              { code: "ERR_BAD_ATTR_FILTER", source: layoutSource },
             ),
           );
         }

package/src/naming.ts

@@ -28,6 +28,31 @@ export function toSnakeCase(s: string): string {
     .toLowerCase();
 }
 
+export function toKebabCase(s: string): string {
+  return toSnakeCase(s).replace(/_/g, "-");
+}
+
+/**
+ * Column-naming strategy applied by the persistence layer to fields with no
+ * explicit `@column` override. Persistence-layer config (set on
+ * ObjectManager / buildExpectedSchema / codegen config), not a metadata attr —
+ * the same metadata can drive snake_case (PG convention) or literal (EF
+ * convention) consumers. TS port defaults to snake_case; C# port defaults to
+ * literal.
+ */
+export type ColumnNamingStrategy = "snake_case" | "literal" | "kebab-case";
+
+/** Single source of truth for the TS-port default. */
+export const DEFAULT_COLUMN_NAMING_STRATEGY: ColumnNamingStrategy = "snake_case";
+
+export function applyColumnNamingStrategy(name: string, strategy: ColumnNamingStrategy): string {
+  switch (strategy) {
+    case "literal":     return name;
+    case "kebab-case":  return toKebabCase(name);
+    case "snake_case":  return toSnakeCase(name);
+  }
+}
+
 export function pluralize(s: string): string {
   if (/(s|x|z|ch|sh)$/i.test(s)) return s + "es";
   if (/[^aeiou]y$/i.test(s)) return s.slice(0, -1) + "ies";
@@ -35,20 +60,24 @@ export function pluralize(s: string): string {
 }
 
 export function resolveTableName(entity: MetaData): string {
-  // Primary writable source carries the physical table name (@table).
+  // Primary source carries the physical table/view name (@table). Writability
+  // (table vs view/storedProc/tableFunction) only affects write-routing — for
+  // SELECT-side name resolution, a read-only primary source is the right answer.
   const source = entity.ownChildren().find(
-    (c): c is MetaSource =>
-      c instanceof MetaSource && c.isWritable() && c.role === SOURCE_ROLE_PRIMARY,
+    (c): c is MetaSource => c instanceof MetaSource && c.role === SOURCE_ROLE_PRIMARY,
   );
   const name = source?.tableName;
   if (typeof name === "string" && name !== "") return name;
   return pluralize(toSnakeCase(entity.name));
 }
 
-export function resolveColumnName(field: MetaData): string {
+export function resolveColumnName(
+  field: MetaData,
+  strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
+): string {
   const col = field.ownAttr(FIELD_ATTR_COLUMN);
   if (typeof col === "string" && col) return col;
-  return toSnakeCase(field.name);
+  return applyColumnNamingStrategy(field.name, strategy);
 }
 
 /**
@@ -75,12 +104,15 @@ export interface EntityNameMap {
   dbToJs: Map<string, string>;
 }
 
-export function buildNameMap(entity: MetaData): EntityNameMap {
+export function buildNameMap(
+  entity: MetaData,
+  strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
+): EntityNameMap {
   const jsToDb = new Map<string, string>();
   const dbToJs = new Map<string, string>();
   for (const child of entity.ownChildren()) {
     if (child.type !== TYPE_FIELD) continue;
-    const dbCol = resolveColumnName(child);
+    const dbCol = resolveColumnName(child, strategy);
     jsToDb.set(child.name, dbCol);
     dbToJs.set(dbCol, child.name);
   }