Merge branch 'main' into worktree-documentation-provider

Author: dmealing

fixtures/conformance/ERROR-CODES.json

@@ -32,6 +32,7 @@
     "ERR_RESERVED_ATTR": "An @-prefixed reserved structural keyword (e.g. @name, @isArray, @children) was used as an inline attribute.",
     "ERR_SOURCE_NO_PRIMARY": "An object declares source nodes but none has role=primary.",
     "ERR_SOURCE_MULTIPLE_PRIMARY": "An object declares more than one source node with role=primary.",
+    "ERR_YAML_COERCION": "A YAML 1.2 silent type coercion produced a JS value whose runtime type differs from the attribute's declared valueType (e.g. an unquoted `column: TRUE` parsed as boolean for a string-typed attr). TS-only emitter — YAML is a TypeScript-side front-end; canonical JSON is unaffected.",
     "ERR_UNKNOWN": "An internal loader error with no stable error code."
   }
 }

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

@@ -34,17 +34,25 @@ export function parseYaml(content: string, opts: ParseOptions): ParseResult {
   // If the desugar could not produce a usable document at all, surface the
   // first desugar error as a throw — parallels parseJson's top-level throws.
   if (Object.keys(canonical).length === 0) {
+    const first = desugarErrors[0]!;
     throw new ParseError(
-      desugarErrors[0]!,
-      { ...errOpts(opts.sourceName), code: "ERR_MALFORMED_YAML" },
+      first.message,
+      { ...errOpts(opts.sourceName), code: first.code ?? "ERR_MALFORMED_YAML" },
     );
   }
 
   const result = buildTree(canonical, opts);
 
   // Merge collected desugar errors ahead of buildTree's own collected errors.
+  // Each CollectedError carries its own stable code when set (e.g.
+  // ERR_YAML_COERCION from the D2 type-coercion guard); the malformed-document
+  // shape errors fall back to ERR_MALFORMED_YAML.
   const desugarParseErrors = desugarErrors.map(
-    (msg) => new ParseError(msg, { ...errOpts(opts.sourceName), code: "ERR_MALFORMED_YAML" }),
+    (e) =>
+      new ParseError(e.message, {
+        ...errOpts(opts.sourceName),
+        code: e.code ?? "ERR_MALFORMED_YAML",
+      }),
   );
   return {
     root: result.root,

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

@@ -2,37 +2,71 @@
 //
 // desugar() turns the sugared authoring object (from yaml.parse) into the
 // canonical-shaped object that buildTree (parser-core.ts) consumes. It applies
-// the four format-spec sugar rules:
+// the five format-spec sugar rules (ADR-0006):
 //   1. Fused key, subType omittable — a bare `type` key resolves to the type's
 //      registry default subType.
 //   2. Scalar-or-map body — a scalar body becomes { name: <scalar> }.
 //   3. Omit empties — absent keys stay absent; the desugar invents nothing.
 //   4. `[]` arrays — a trailing `[]` on the key strips to isArray: true.
+//   5. Sigil-free attributes (ADR-0006 D1) — every body key not in
+//      RESERVED_KEYS is treated as an inline attribute and re-prefixed with `@`
+//      when lowering to canonical JSON. Keys already prefixed with `@` are
+//      left as-is (backward-compat). Reserved structural keywords (name,
+//      package, extends, abstract, overlay, isArray, children, value) stay
+//      bare. Note: an already-`@`-prefixed reserved word remains an error
+//      downstream — parser-core's ERR_RESERVED_ATTR check fires.
 //
-// Pure and total: it never throws. Malformed fragments are collected as error
-// strings and a safe placeholder is substituted so buildTree does not
-// double-report.
+// In addition, the desugar runs the ADR-0006 D2 type-coercion guard: for every
+// inline attr whose owning (type, subType) has a declared schema, if the raw
+// JS value's type does not match the declared valueType AND the JS value is
+// one of YAML 1.2's silently coerced shapes (boolean/number/null), the
+// desugar collects an ERR_YAML_COERCION error telling the author to quote the
+// value. The check protects against the classic YAML footgun (e.g. an unquoted
+// `column: TRUE` becoming the boolean `true` instead of the string "TRUE").
+//
+// Pure and total: it never throws. Malformed fragments are collected as
+// CollectedError entries (a string message + optional stable error code) and a
+// safe placeholder is substituted so buildTree does not double-report.
 
-import type { TypeRegistry } from "../registry.js";
+import type { TypeRegistry, AttrSchema } from "../registry.js";
+import type { ErrorCode } from "../errors.js";
 import {
+  ATTR_PREFIX,
+  RESERVED_KEYS,
   RESERVED_KEY_CHILDREN,
   RESERVED_KEY_NAME,
   RESERVED_KEY_IS_ARRAY,
   TYPE_SUBTYPE_SEPARATOR,
 } from "../shared/structural.js";
+import {
+  ATTR_SUBTYPE_STRING,
+  ATTR_SUBTYPE_CLASS,
+  ATTR_SUBTYPE_INT,
+  ATTR_SUBTYPE_LONG,
+  ATTR_SUBTYPE_DOUBLE,
+  ATTR_SUBTYPE_BOOLEAN,
+  ATTR_SUBTYPE_STRINGARRAY,
+} from "./attr/attr-constants.js";
 
 const ARRAY_SUFFIX = "[]";
 
+/** A collected desugar problem — message plus optional stable error code. */
+export interface CollectedError {
+  message: string;
+  /** Optional stable code; absent values map to ERR_MALFORMED_YAML in parser-yaml.ts. */
+  code?: ErrorCode;
+}
+
 export interface DesugarResult {
   /** The canonical-shaped object; `{}` when the document was unusable. */
   canonical: Record<string, unknown>;
   /** Collected desugar problems (never thrown). */
-  errors: string[];
+  errors: CollectedError[];
 }
 
 /** Desugar a parsed-YAML authoring document into a canonical-shaped object. */
 export function desugar(input: unknown, registry: TypeRegistry): DesugarResult {
-  const errors: string[] = [];
+  const errors: CollectedError[] = [];
   const node = desugarNode(input, registry, errors, "<root>");
   return { canonical: node ?? {}, errors };
 }
@@ -43,21 +77,22 @@ export function desugar(input: unknown, registry: TypeRegistry): DesugarResult {
 function desugarNode(
   input: unknown,
   registry: TypeRegistry,
-  errors: string[],
+  errors: CollectedError[],
   path: string,
 ): Record<string, unknown> | undefined {
   if (typeof input !== "object" || input === null || Array.isArray(input)) {
-    errors.push(`Node at ${path} must be a mapping with one type key`);
+    errors.push({ message: `Node at ${path} must be a mapping with one type key` });
     return undefined;
   }
 
   const entries = Object.keys(input as Record<string, unknown>);
   if (entries.length !== 1) {
-    errors.push(
-      `Node at ${path} must have exactly one type key (found: ${
-        entries.length === 0 ? "none" : entries.join(", ")
-      })`,
-    );
+    errors.push({
+      message:
+        `Node at ${path} must have exactly one type key (found: ${
+          entries.length === 0 ? "none" : entries.join(", ")
+        })`,
+    });
     return undefined;
   }
 
@@ -76,7 +111,7 @@ function desugarNode(
   const canonicalKey = resolveKey(key, registry, errors, path);
 
   // Rule 2: a scalar body → { name: <scalar> }.
-  const body = desugarBody(rawBody, errors, path);
+  const body = desugarBody(rawBody, registry, canonicalKey, errors, path);
 
   // Rule 4 (cont.): stamp isArray onto the canonical body.
   if (isArray) body[RESERVED_KEY_IS_ARRAY] = true;
@@ -103,25 +138,36 @@ function desugarNode(
 function resolveKey(
   key: string,
   registry: TypeRegistry,
-  errors: string[],
+  errors: CollectedError[],
   path: string,
 ): string {
   if (key.includes(TYPE_SUBTYPE_SEPARATOR)) return key; // already fused
   const subType = registry.defaultSubTypeOf(key);
   if (subType === undefined) {
-    errors.push(
-      `Cannot resolve subType for bare type key '${key}' at ${path} — ` +
+    errors.push({
+      message:
+        `Cannot resolve subType for bare type key '${key}' at ${path} — ` +
         `type '${key}' has no default subType; write the full 'type.subType'`,
-    );
+    });
     return key; // pass through; buildTree reports the unknown type
   }
   return `${key}${TYPE_SUBTYPE_SEPARATOR}${subType}`;
 }
 
-// Rule 2 — normalize a node body into a canonical mapping.
+// Rule 2 + 5 — normalize a node body into a canonical mapping. Reserved
+// structural keys stay bare; every other key is treated as an inline attribute
+// and `@`-prefixed (Rule 5 / ADR-0006 D1). Keys already starting with `@` are
+// kept as-authored so the awkward "@column: foo" form remains accepted.
+//
+// Also runs the D2 type-coercion guard: for each inline attr that the owning
+// (type, subType) declares with a typed `valueType`, if the raw JS value's
+// type was silently coerced by YAML 1.2 to something incompatible (e.g. a
+// `boolean` for a `string`-declared attr), an ERR_YAML_COERCION is collected.
 function desugarBody(
   rawBody: unknown,
-  errors: string[],
+  registry: TypeRegistry,
+  canonicalKey: string,
+  errors: CollectedError[],
   path: string,
 ): Record<string, unknown> {
   if (
@@ -136,10 +182,146 @@ function desugarBody(
     return {};
   }
   if (Array.isArray(rawBody)) {
-    errors.push(`Node body at ${path} must be a scalar or mapping, not a list`);
+    errors.push({
+      message: `Node body at ${path} must be a scalar or mapping, not a list`,
+    });
     return {};
   }
   // A mapping — shallow-copy so isArray / children replacement do not mutate
-  // the caller's parsed-YAML object.
-  return { ...(rawBody as Record<string, unknown>) };
+  // the caller's parsed-YAML object, AND apply Rule 5 (sigil-free attrs) +
+  // Rule D2 (type-coercion guard).
+  const src = rawBody as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  const schemaIndex = attrSchemaIndex(registry, canonicalKey);
+  for (const key of Object.keys(src)) {
+    if (RESERVED_KEYS.has(key) || key.startsWith(ATTR_PREFIX)) {
+      out[key] = src[key];
+      // D2 also applies to author-written @-keys (the awkward form).
+      const attrName = key.startsWith(ATTR_PREFIX) ? key.slice(ATTR_PREFIX.length) : "";
+      if (attrName !== "" && !RESERVED_KEYS.has(attrName)) {
+        checkCoercion(attrName, src[key], schemaIndex, errors, path);
+      }
+    } else {
+      out[`${ATTR_PREFIX}${key}`] = src[key];
+      checkCoercion(key, src[key], schemaIndex, errors, path);
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// D2 — YAML type-coercion guard
+// ---------------------------------------------------------------------------
+
+// Build a name → AttrSchema map for the given canonical key (type.subType).
+// Returns undefined when the key has no declared attrs (open schema).
+function attrSchemaIndex(
+  registry: TypeRegistry,
+  canonicalKey: string,
+): Map<string, AttrSchema> | undefined {
+  // canonicalKey is "type.subType" — split on the FIRST dot only so a subType
+  // that happens to contain a dot still works.
+  const dot = canonicalKey.indexOf(TYPE_SUBTYPE_SEPARATOR);
+  if (dot < 0) return undefined;
+  const type = canonicalKey.slice(0, dot);
+  const subType = canonicalKey.slice(dot + 1);
+  const schema = registry.attrsOf(type, subType);
+  if (schema.length === 0) return undefined;
+  const idx = new Map<string, AttrSchema>();
+  for (const spec of schema) idx.set(spec.name, spec);
+  return idx;
+}
+
+// Check a single attr value against its declared schema's `valueType`. Emits
+// an ERR_YAML_COERCION when the JS type was silently changed by YAML 1.2's
+// core schema (boolean/number/null where a string/stringarray was declared,
+// or vice versa for booleans/numbers).
+function checkCoercion(
+  attrName: string,
+  raw: unknown,
+  schemaIndex: Map<string, AttrSchema> | undefined,
+  errors: CollectedError[],
+  path: string,
+): void {
+  if (schemaIndex === undefined) return;
+  const spec = schemaIndex.get(attrName);
+  if (spec === undefined || spec.valueType === undefined) return;
+
+  switch (spec.valueType) {
+    case ATTR_SUBTYPE_STRING:
+    case ATTR_SUBTYPE_CLASS:
+      if (typeof raw !== "string") emitCoercion(attrName, raw, "string", errors, path);
+      return;
+    case ATTR_SUBTYPE_BOOLEAN:
+      if (typeof raw !== "boolean") emitCoercion(attrName, raw, "boolean", errors, path);
+      return;
+    case ATTR_SUBTYPE_INT:
+    case ATTR_SUBTYPE_LONG:
+    case ATTR_SUBTYPE_DOUBLE:
+      if (typeof raw !== "number") emitCoercion(attrName, raw, "number", errors, path);
+      return;
+    case ATTR_SUBTYPE_STRINGARRAY:
+      // A bare string at the value position is the legitimate one-element
+      // authoring shorthand for a string-array attr (StringArrayAttr.coerce
+      // wraps it into a one-element array). It is NOT a coercion. A
+      // non-string non-array scalar (boolean/number/null), however, is.
+      if (typeof raw === "string") return;
+      if (!Array.isArray(raw)) {
+        emitCoercion(attrName, raw, "string-array (or single string)", errors, path);
+        return;
+      }
+      // For an array, check every element. A non-string element is a YAML
+      // coercion (e.g. unquoted `true` in a string-array list).
+      for (let i = 0; i < raw.length; i++) {
+        if (typeof raw[i] !== "string") {
+          emitCoercion(
+            `${attrName}[${i}]`,
+            raw[i],
+            "string (in string-array)",
+            errors,
+            path,
+          );
+        }
+      }
+      return;
+    default:
+      // Object-shaped attrs (properties, filter) — accept any object/array,
+      // no YAML coercion path applies.
+      return;
+  }
+}
+
+// Build the "quote this value" error. The shape is intentionally explicit so
+// AI authors can act on it: it identifies the attr, the (coerced) JS value,
+// its JS type, the declared expected type, and a one-line fix hint.
+function emitCoercion(
+  attrName: string,
+  raw: unknown,
+  expected: string,
+  errors: CollectedError[],
+  path: string,
+): void {
+  const actualType = coercedTypeName(raw);
+  const literal = literalRepr(raw);
+  errors.push({
+    message:
+      `Attribute '@${attrName}' at ${path}: expected ${expected} but got ${actualType} (${literal}). ` +
+      `YAML 1.2 silently coerced an unquoted value — quote it in YAML: ` +
+      `'@${attrName}: "${literal}"' not '@${attrName}: ${literal}'.`,
+    code: "ERR_YAML_COERCION",
+  });
+}
+
+function coercedTypeName(raw: unknown): string {
+  if (raw === null) return "null";
+  if (Array.isArray(raw)) return "array";
+  return typeof raw;
+}
+
+function literalRepr(raw: unknown): string {
+  if (raw === null) return "null";
+  if (typeof raw === "boolean") return raw ? "true" : "false";
+  if (typeof raw === "number") return String(raw);
+  if (typeof raw === "string") return raw;
+  return JSON.stringify(raw);
 }

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

@@ -47,6 +47,9 @@ export const ERROR_CODES = [
   "ERR_RESERVED_ATTR",
   "ERR_SOURCE_NO_PRIMARY",
   "ERR_SOURCE_MULTIPLE_PRIMARY",
+  // ADR-0006 D2 — YAML type-coercion guard (TS-only emitter; YAML is a TS
+  // front-end). Registered here so the code vocabulary stays single-sourced.
+  "ERR_YAML_COERCION",
   "ERR_UNKNOWN",
 ] as const;
 

server/typescript/packages/metadata/test/fixtures/yaml-conformance/error-yaml-coerced-bool-in-string/expected-errors.json

@@ -0,0 +1,3 @@
+[
+  { "code": "ERR_YAML_COERCION" }
+]

server/typescript/packages/metadata/test/fixtures/yaml-conformance/error-yaml-coerced-bool-in-string/input.yaml

@@ -0,0 +1,8 @@
+metadata:
+  children:
+    - object.entity:
+        name: Product
+        children:
+          - field.string:
+              name: active
+              column: TRUE

server/typescript/packages/metadata/test/fixtures/yaml-conformance/error-yaml-coerced-num-in-enum/expected-errors.json

@@ -0,0 +1,4 @@
+[
+  { "code": "ERR_YAML_COERCION" },
+  { "code": "ERR_BAD_ATTR_VALUE" }
+]

server/typescript/packages/metadata/test/fixtures/yaml-conformance/error-yaml-coerced-num-in-enum/input.yaml

@@ -0,0 +1,8 @@
+metadata:
+  children:
+    - object.entity:
+        name: Product
+        children:
+          - field.enum:
+              name: status
+              values: ["DRAFT", 42, "PUBLISHED"]

server/typescript/packages/metadata/test/fixtures/yaml-conformance/error-yaml-reserved-as-attr/expected-errors.json

@@ -0,0 +1,3 @@
+[
+  { "code": "ERR_RESERVED_ATTR" }
+]

server/typescript/packages/metadata/test/fixtures/yaml-conformance/error-yaml-reserved-as-attr/input.yaml

@@ -0,0 +1,5 @@
+metadata:
+  children:
+    - object.entity:
+        name: Product
+        "@isArray": true