@metaobjectsdev/metadata 0.6.0-rc.1 → 0.7.0-rc.1

package/src/source.ts

@@ -0,0 +1,61 @@
+// server/typescript/packages/metadata/src/source.ts
+//
+// FR5a — Loader error envelope + source-on-node (ADR-0009).
+//
+// Cross-port-aligned types: every metaobjects port emits the same envelope
+// shape so a tool consuming errors from multiple language ports can compare
+// them byte-identically.
+
+/** Discriminated union over the provenance variants a metadata node or error
+ *  can carry. See ADR-0009 §Decision for the canonical shape. */
+export type ErrorSource =
+  | { format: "json"; files: [string]; jsonPath: string }
+  | { format: "yaml"; files: [string]; jsonPath: string;
+      yamlPosition?: { line: number; col: number } }
+  | { format: "merged"; files: string[]; jsonPath: string;
+      contributors: Contributor[] }
+  | { format: "resolved"; files: string[]; jsonPath?: string;
+      referrer?: string; target?: string }
+  | { format: "database"; dbLocation: { table: string; id: string };
+      jsonPath?: string }
+  | { format: "code"; caller?: string };
+
+export interface Contributor {
+  file: string;
+  role: "overlay-base" | "overlay-extension" | "extends-base" | "extends-extension";
+}
+
+export interface NodeContext {
+  type?: string;
+  subtype?: string;
+  name?: string;
+  fqn?: string;
+}
+
+/** Envelope shape every loader error conforms to. */
+export interface LoaderError {
+  // REQUIRED — conformance-enforced.
+  code: string;
+  message: string;
+  source: ErrorSource;
+  // RECOMMENDED — optional per ADR-0009 §What ports are NOT required to do.
+  suggestions?: string[];
+  fixture?: string;
+  node?: NodeContext;
+}
+
+/** Warning envelope — same shape as LoaderError but a `WARN_*` code. */
+export interface LoaderWarning {
+  code: string;
+  message: string;
+  source: ErrorSource;
+  suggestions?: string[];
+  fixture?: string;
+  node?: NodeContext;
+}
+
+/** Canonical synthetic envelope for programmatic / test-constructed nodes.
+ *  `caller` is an optional human label (e.g. "QueriesTest.makePost"). */
+export function codeSource(caller?: string): ErrorSource {
+  return caller ? { format: "code", caller } : { format: "code" };
+}

package/src/subtype-rules.ts

@@ -35,7 +35,7 @@ function walk(model: MetaData, errors: ParseError[], warnings: string[]): void {
         new ParseError(
           `value object '${model.fqn()}' must not have a primary identity ` +
             `(use subType: "entity" for records with identity)`,
-          { code: "ERR_SUBTYPE_RULE_VIOLATION" },
+          { code: "ERR_SUBTYPE_RULE_VIOLATION", source: model.source },
         ),
       );
     } else if (

package/src/super-resolve.ts

@@ -100,6 +100,8 @@ export interface DeferredSuperFailure {
   nodeFqn: string;
   /** The raw super ref string that didn't resolve. */
   ref: string;
+  /** ADR-0009 provenance envelope of the referencing node (FR5a). */
+  source: import("./source.js").ErrorSource;
 }
 
 /**
@@ -128,7 +130,7 @@ export function resolveDeferredSupers(root: MetaData): DeferredSuperFailure[] {
         // Frozen — ignore; the loader should resolve before freeze.
       }
     } else {
-      failures.push({ nodeFqn: node.fqn(), ref: node.superRef });
+      failures.push({ nodeFqn: node.fqn(), ref: node.superRef, source: node.source });
     }
   });
   return failures;

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

@@ -1,89 +0,0 @@
-// FileMetaDataLoader — discovers file-backed MetaDataSources and runs the
-// MetaDataLoader pipeline over them. A UrlMetaDataLoader will slot in the
-// same way later.
-
-import type { Stats } from "node:fs";
-import { readdir, stat } from "node:fs/promises";
-import { join } from "node:path";
-import { MetaDataLoader, type LoadResult } from "../loader/meta-data-loader.js";
-import { FileSource } from "./file-source.js";
-import { parseYaml } from "./parser-yaml.js";
-import type { ParseOptions, ParseResult } from "../parser-core.js";
-import type { MetaDataSource } from "../loader/meta-data-source.js";
-
-/** 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 FileMetaDataLoader extends MetaDataLoader {
-  /** Adds YAML parsing on top of the base loader's JSON-only `parseSource`. */
-  protected override parseSource(
-    content: string,
-    source: MetaDataSource,
-    parseOpts: ParseOptions,
-  ): ParseResult {
-    if (source.format === "yaml") {
-      return parseYaml(content, parseOpts);
-    }
-    return super.parseSource(content, source, parseOpts);
-  }
-
-  /**
-   * Load every `.json` / `.yaml` / `.yml` file in a directory (non-recursive),
-   * in deterministic ordinal filename order.
-   * @param opts.exclude glob patterns (relative to dir) to skip — `*` / `**`.
-   */
-  async loadDirectory(dir: string, opts?: { exclude?: string[] }): Promise<LoadResult> {
-    let entries: string[];
-    try {
-      // Sorted for deterministic multi-file load order: the overlay merge is
-      // order-sensitive (last-writer-wins on attr conflicts), so the scan must
-      // not depend on filesystem readdir order. Ordinal filename sort is
-      // reproducible across the Java/Python/C# ports.
-      entries = (await readdir(dir)).sort();
-    } catch (err) {
-      // Surface the I/O failure as a collected error via the empty-source path.
-      const emptyResult = await this.load([]);
-      return {
-        ...emptyResult,
-        errors: [
-          new Error(`loadDirectory: cannot read ${dir}: ${(err as Error).message}`),
-          ...emptyResult.errors,
-        ],
-      };
-    }
-
-    const excludes = opts?.exclude ?? [];
-    const paths: string[] = [];
-    for (const entry of entries) {
-      const lower = entry.toLowerCase();
-      if (!lower.endsWith(".json") && !lower.endsWith(".yaml") && !lower.endsWith(".yml")) {
-        continue;
-      }
-      const filePath = join(dir, entry);
-      let statResult: Stats;
-      try {
-        statResult = await stat(filePath);
-      } catch {
-        // Entry vanished between readdir and stat (TOCTOU) or is not accessible.
-        // Skip it rather than breaking the no-throw contract of loadDirectory.
-        continue;
-      }
-      if (!statResult.isFile()) continue;
-      if (excludes.some((p) => matchSimpleGlob(p, entry))) continue;
-      paths.push(filePath);
-    }
-    return this.loadFiles(paths);
-  }
-
-  /** Load an explicit list of file paths, in order. */
-  async loadFiles(paths: string[]): Promise<LoadResult> {
-    return this.load(paths.map((p) => new FileSource(p)));
-  }
-}