Merge branch 'worktree-fr5a-ts-error-envelope'

Author: dmealing

CHANGELOG.md

@@ -8,6 +8,21 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ## [Unreleased]
 
 ### Added
+- **Loader error envelope + source-on-node** (`@metaobjectsdev/metadata`) —
+  per [ADR-0009](spec/decisions/ADR-0009-loader-error-envelope-and-source-on-node.md),
+  every `MetaData` node now carries a `source: ErrorSource` provenance field
+  (`{ format: "json", files: [...], jsonPath: "..." }` for loaded nodes;
+  `{ format: "code" }` for programmatically constructed). `ParseError` now
+  conforms to the cross-port `LoaderError` schema: required `code`, required
+  `message`, required `source` envelope. New `LoadResult.warnings:
+  LoaderWarning[]` channel (legacy parser/validator strings are wrapped at
+  the loader boundary as `WARN_LEGACY` envelopes; future overlay-merge
+  detection in FR5c will be the first feature to emit native envelope-shaped
+  warnings). New public exports from `@metaobjectsdev/metadata`:
+  `ErrorSource`, `LoaderError`, `LoaderWarning`, `NodeContext`, `Contributor`
+  types, plus the `codeSource()` helper. Foundation for FR5b (YAML
+  positions), FR5c (multi-file merge attribution), FR5d (reference-resolution
+  errors), FR5e (database-source errors).
 - **`outputParser()` stock generator** in `@metaobjectsdev/codegen-ts/generators` —
   for every declared `template.output`, emits a typed Zod parser file with a
   dual-API surface (`parseXxx(text)` throws, `safeParseXxx(text)` returns
@@ -42,6 +57,19 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   Enables Cloudflare Workers / edge consumers to drop their typecheck stubs;
   enables multi-tenant servers + test-isolated `db` setups. `routesFile()` is
   unchanged.
+- **BREAKING (metadata):** `ParseError` constructor signature changed. Was
+  `new ParseError(msg, { code?, source?: string, path? })`; now
+  `new ParseError(msg, { code, source: ErrorSource })`. Direct construction
+  outside the metadata package is rare (loader-internal API), but anyone
+  catching + repackaging a `ParseError` reads `.source` as the new envelope
+  type, not a string. Legacy `error.path` is gone — read
+  `error.source.jsonPath` instead.
+- **BREAKING (metadata):** `LoadResult.warnings` retyped from `string[]` to
+  `LoaderWarning[]` per ADR-0009. Consumers that inspected warning content
+  via `result.warnings[i].includes(...)` should now read
+  `result.warnings[i].message.includes(...)`. The public
+  `ExportResult.warnings` (returned by `loadAndExportJson()`) keeps its
+  `string[]` shape — extracted via `.map((w) => w.message)`.
 
 See [ADR-0010](spec/decisions/ADR-0010-template-output-parser-codegen.md)
 for the cross-port design.

server/typescript/packages/metadata/README.md

@@ -19,6 +19,57 @@ const result = await new MetaDataLoader().load([new InMemoryStringSource(json)])
 
 The public loader API is `MetaDataLoader` + `InMemoryStringSource`. A `MetaDataLoader` instance is single-use; construct a new one per load.
 
+## Loader errors (FR5a)
+
+Every loader error conforms to the cross-port `LoaderError` envelope
+(ADR-0009):
+
+```ts
+interface LoaderError {
+  code: string;            // ERR_UNKNOWN_TYPE, ERR_BAD_ATTR_VALUE, ...
+  message: string;
+  source: ErrorSource;     // always populated
+}
+
+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 };
+```
+
+Every `MetaData` node also carries a populated `source` field, so
+post-load consumers (drift detection, MCP, debug tools) can answer
+"where did this node come from?" without an extra lookup table.
+
+`LoadResult.warnings` is a parallel `LoaderWarning[]` channel — same
+envelope shape, `WARN_*` prefixed codes. Pre-FR5a string warnings are
+wrapped at the loader boundary as `WARN_LEGACY` envelopes; FR5c will
+retire the legacy code by routing each emit site through a proper
+envelope-shaped helper.
+
+The package re-exports the envelope types and the `codeSource()`
+helper for consumers that catch + repackage `ParseError`s or build
+synthetic envelopes for programmatic-construction tests:
+
+```ts
+import type {
+  ErrorSource,
+  LoaderError,
+  LoaderWarning,
+  NodeContext,
+  Contributor,
+} from "@metaobjectsdev/metadata";
+import { codeSource } from "@metaobjectsdev/metadata";
+```
+
+See [ADR-0009](../../../../spec/decisions/ADR-0009-loader-error-envelope-and-source-on-node.md)
+for the full schema and the FR5 family for the per-error-class
+rollout plan (5a JSON shape, 5b YAML positions, 5c multi-file merge
+attribution, 5d reference resolution, 5e database sources).
+
 ## Links
 
 - [Spec](https://github.com/metaobjectsdev/metaobjects/tree/main/spec)

server/typescript/packages/metadata/src/attr-schema-validate.ts

@@ -100,7 +100,7 @@ function validateNode(
         errors.push(
           new ParseError(
             `Common attr '${ca.name}' conflicts with per-type attr on ${typeKey}`,
-            { code: "ERR_PROVIDER_ATTR_CONFLICT" },
+            { code: "ERR_PROVIDER_ATTR_CONFLICT", source: node.source },
           ),
         );
         reportedConflicts.add(typeKey);
@@ -126,7 +126,7 @@ function validateNode(
       errors.push(
         new ParseError(
           `${nodeLabel(node)} is missing required attribute '@${spec.name}'`,
-          { code: "ERR_MISSING_REQUIRED_ATTR" },
+          { code: "ERR_MISSING_REQUIRED_ATTR", source: node.source },
         ),
       );
     }
@@ -145,7 +145,7 @@ function validateNode(
       const valueErrors = inst.validateValue(value);
       if (valueErrors.length > 0) {
         for (const ve of valueErrors) {
-          errors.push(new ParseError(`${nodeLabel(node)} ${ve.message}`, { code: "ERR_BAD_ATTR_VALUE" }));
+          errors.push(new ParseError(`${nodeLabel(node)} ${ve.message}`, { code: "ERR_BAD_ATTR_VALUE", source: node.source }));
         }
         continue; // type wrong → skip allowedValues
       }
@@ -159,7 +159,7 @@ function validateNode(
             `${nodeLabel(node)} attribute '@${inst.name}' has value ` +
               `'${String(value)}' which is not one of the allowed values: ` +
               `${spec.allowedValues.map((v) => String(v)).join(", ")}`,
-            { code: "ERR_BAD_ATTR_VALUE" },
+            { code: "ERR_BAD_ATTR_VALUE", source: node.source },
           ),
         );
       }
@@ -180,7 +180,7 @@ function validateNode(
         errors.push(
           new ParseError(
             `${nodeLabel(node)} must declare at least one value in '@${FIELD_ATTR_VALUES}'.`,
-            { code: "ERR_BAD_ATTR_VALUE" },
+            { code: "ERR_BAD_ATTR_VALUE", source: node.source },
           ),
         );
       } else {
@@ -194,14 +194,14 @@ function validateNode(
                 `${nodeLabel(node)} attribute '@${FIELD_ATTR_VALUES}' member '${member}' ` +
                   `is not a valid identifier (must match ${ENUM_MEMBER_PATTERN.source}). ` +
                   `Non-identifier-safe member strings require a symbol↔value mapping (deferred).`,
-                { code: "ERR_BAD_ATTR_VALUE" },
+                { code: "ERR_BAD_ATTR_VALUE", source: node.source },
               ),
             );
           } else if (seen.has(member)) {
             errors.push(
               new ParseError(
                 `${nodeLabel(node)} attribute '@${FIELD_ATTR_VALUES}' has duplicate member '${member}'.`,
-                { code: "ERR_BAD_ATTR_VALUE" },
+                { code: "ERR_BAD_ATTR_VALUE", source: node.source },
               ),
             );
           } else {

server/typescript/packages/metadata/src/core/export-json.ts

@@ -55,6 +55,9 @@ export async function loadAndExportJson(
   return {
     json,
     errors: result.errors,
-    warnings: result.warnings,
+    // FR5a: LoadResult.warnings is now LoaderWarning[]; ExportResult preserves
+    // its public string[] shape (callers print warnings as text). Extract the
+    // message for back-compat.
+    warnings: result.warnings.map((w) => w.message),
   };
 }

server/typescript/packages/metadata/src/core/parser-yaml.ts

@@ -7,10 +7,21 @@
 
 import { parse as parseYamlText } from "yaml";
 import { ParseError } from "../errors.js";
-import { buildTree, errOpts } from "../parser-core.js";
+import { buildTree } from "../parser-core.js";
 import type { ParseOptions, ParseResult } from "../parser-core.js";
+import type { ErrorSource } from "../source.js";
 import { desugar } from "./yaml-desugar.js";
 
+/** FR5a / ADR-0009 — build a YAML-source envelope rooted at "$".
+ *  yamlPosition is FR5b territory and not populated here. */
+function yamlSource(sourceName: string | undefined): ErrorSource {
+  return {
+    format: "yaml",
+    files: [sourceName ?? "<unknown>"],
+    jsonPath: "$",
+  };
+}
+
 export function parseYaml(content: string, opts: ParseOptions): ParseResult {
   // Strip UTF-8 BOM if present (consistent with parseJson).
   const normalizedContent =
@@ -24,7 +35,7 @@ export function parseYaml(content: string, opts: ParseOptions): ParseResult {
   } catch (err) {
     throw new ParseError(
       `Invalid YAML: ${(err as Error).message}`,
-      { ...errOpts(opts.sourceName), code: "ERR_MALFORMED_YAML" },
+      { code: "ERR_MALFORMED_YAML", source: yamlSource(opts.sourceName) },
     );
   }
 
@@ -37,7 +48,7 @@ export function parseYaml(content: string, opts: ParseOptions): ParseResult {
     const first = desugarErrors[0]!;
     throw new ParseError(
       first.message,
-      { ...errOpts(opts.sourceName), code: first.code ?? "ERR_MALFORMED_YAML" },
+      { code: first.code ?? "ERR_MALFORMED_YAML", source: yamlSource(opts.sourceName) },
     );
   }
 
@@ -50,8 +61,8 @@ export function parseYaml(content: string, opts: ParseOptions): ParseResult {
   const desugarParseErrors = desugarErrors.map(
     (e) =>
       new ParseError(e.message, {
-        ...errOpts(opts.sourceName),
         code: e.code ?? "ERR_MALFORMED_YAML",
+        source: yamlSource(opts.sourceName),
       }),
   );
   return {

server/typescript/packages/metadata/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):
@@ -55,20 +57,52 @@ export const ERROR_CODES = [
 
 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;
+    }
   }
 }
 

server/typescript/packages/metadata/src/index.ts

@@ -168,6 +168,19 @@ export {
 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";

server/typescript/packages/metadata/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;
+  }
+}