feat(conformance,ts): WARN envelope-shape assertion (FR5c-finalize follow-up)

dmealing · claude · dmealing · commit bf97ade82aea · 2026-05-27T11:37:25.000-04:00
Extend the cross-port conformance runner to assert envelope shape on
`warnings[]` (code + source.format + source.files + source.jsonPath), mirroring
the FR5a/FR5d error-side cross-port contract. Algorithm matches the error block:
per-element code first, then per-element source-field comparison in declaration
order. The block lives outside the `outcome.errors !== undefined` gate so ports
can adopt `warningEnvelopes` independently of error envelopes.

Migrate `warning-duplicate-declaration` to envelope shape via a new
`expected-errors.json#warnings[]`. The legacy `expected-warnings.json` (string
list) stays in place so unported runners (C#/Java/Python) keep passing — they
read the string list today; per-port follow-up will surface
`warningEnvelopes` from their adapters and drop the legacy file once all four
ports have converged.

Surface `warningEnvelopes` on TS's LoadOutcome by reusing the same envelope
normalization the error-side already applies (relativize files; carry
jsonPath / referrer / target when present).

Suppress the runner's "no expected-warnings.json → assert zero warnings"
fallback when the fixture uses envelope shape via `expected-errors.json`; the
envelope path asserts warning count + per-element shape already.

Tests:
- 4 new runner.test.ts unit tests (matching shape pass + 3 failure modes:
  mismatched code, mismatched files, count mismatch).
- 51 conformance package tests (47 → 51).
- 182/182 TS metamodel conformance.
- 1260/1260 TS metadata.

Cross-port re-verification (legacy string-list path still in play):
- C# 343/343 conformance
- Python 104/104 conformance
- Java 182/182 conformance

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/fixtures/conformance/warning-duplicate-declaration/expected-errors.json b/fixtures/conformance/warning-duplicate-declaration/expected-errors.json
@@ -0,0 +1,35 @@
+{
+  "errors": [],
+  "warnings": [
+    {
+      "code": "WARN_DUPLICATE_DECLARATION",
+      "source": {
+        "format": "merged",
+        "files": [
+          "meta.a.json",
+          "meta.b.json"
+        ]
+      }
+    },
+    {
+      "code": "WARN_DUPLICATE_DECLARATION",
+      "source": {
+        "format": "merged",
+        "files": [
+          "meta.a.json",
+          "meta.b.json"
+        ]
+      }
+    },
+    {
+      "code": "WARN_DUPLICATE_DECLARATION",
+      "source": {
+        "format": "merged",
+        "files": [
+          "meta.a.json",
+          "meta.b.json"
+        ]
+      }
+    }
+  ]
+}
diff --git a/server/typescript/packages/conformance/src/adapter.ts b/server/typescript/packages/conformance/src/adapter.ts
@@ -48,6 +48,15 @@ export interface LoadOutcome {
    * shape. When absent, the runner falls back to code-set comparison only.
    */
   readonly errors?: readonly ErrorEnvelopeRecord[];
+  /**
+   * Full warning envelopes (FR5c-finalize). Same shape as `errors` —
+   * `{ code, source: { format, files, jsonPath?, contributors? } }`. When
+   * present AND the fixture's expected-errors.json declares envelope-shape
+   * warnings, the runner asserts per-warning envelope alignment (mirrors the
+   * error-side assertion). When absent, the runner falls back to comparing
+   * `warnings` as a flat string list against expected-warnings.json.
+   */
+  readonly warningEnvelopes?: readonly ErrorEnvelopeRecord[];
 }
 
 export interface ConformanceAdapter {
diff --git a/server/typescript/packages/conformance/src/operation-script.ts b/server/typescript/packages/conformance/src/operation-script.ts
@@ -28,7 +28,13 @@ export interface ExpectedError {
 
 export interface ExpectedErrorsEnvelope {
   readonly errors: readonly ExpectedError[];
-  readonly warnings: readonly unknown[];
+  /**
+   * Warning entries. FR5c-finalize: when each entry is `{code, source}`,
+   * the runner asserts envelope shape on warnings (mirroring errors). Older
+   * fixtures may still carry an empty array; the cross-port runner falls
+   * back to flat string comparison against expected-warnings.json.
+   */
+  readonly warnings: readonly ExpectedError[];
   /** True when the file used the legacy `[{code}]` array shape (no source). */
   readonly legacy: boolean;
 }
@@ -124,7 +130,18 @@ export function parseExpectedErrors(raw: unknown): ExpectedErrorsEnvelope {
     const source = parseSource(r.source, i);
     return source !== undefined ? { code: r.code, source } : { code: r.code };
   });
-  const warnings = Array.isArray(env.warnings) ? env.warnings : [];
+  const rawWarnings = Array.isArray(env.warnings) ? env.warnings : [];
+  const warnings = rawWarnings.map((item, i): ExpectedError => {
+    if (typeof item !== "object" || item === null) {
+      throw new Error(`expected-errors.json warnings entry ${i} is not an object`);
+    }
+    const r = item as Record<string, unknown>;
+    if (typeof r.code !== "string") {
+      throw new Error(`expected-errors.json warnings entry ${i} missing string 'code' field`);
+    }
+    const source = parseSource(r.source, i);
+    return source !== undefined ? { code: r.code, source } : { code: r.code };
+  });
   return { errors, warnings, legacy: false };
 }
 
diff --git a/server/typescript/packages/conformance/src/runner.ts b/server/typescript/packages/conformance/src/runner.ts
@@ -116,15 +116,62 @@ export async function runFixture(
             }
           }
         }
-        // warnings — assert length matches (the new envelope always carries
-        // a `warnings` array; FR5a fixtures all have []). Detailed warning
-        // envelope assertion lives in FR5c when WARN_* fixtures land.
-        if (envelope.warnings.length !== outcome.warnings.length) {
+      }
+      // FR5c-finalize — warnings: when the fixture's envelope declares
+      // warning entries with `source`, assert per-warning envelope shape
+      // (same algorithm as errors above). The block lives outside the
+      // `outcome.errors !== undefined` gate so a port that ships
+      // `warningEnvelopes` but not `errors` (rare) still gets the
+      // assertion. When the fixture declares only counts (warnings:
+      // [{code}] without source) or empty `[]`, the length check still
+      // runs; the per-element source assertion is skipped element-by-
+      // element when expected.source is undefined.
+      if (envelope !== undefined && !envelope.legacy) {
+        const expectedW = envelope.warnings;
+        const gotW = outcome.warningEnvelopes;
+        if (expectedW.length !== outcome.warnings.length) {
           checks.push({
-            kind: "expected-errors",
+            kind: "expected-warnings",
             passed: false,
-            detail: `warnings count: expected ${envelope.warnings.length}, got ${outcome.warnings.length}`,
+            detail: `warnings count: expected ${expectedW.length}, got ${outcome.warnings.length}`,
           });
+        } else if (gotW !== undefined && expectedW.length === gotW.length) {
+          for (let i = 0; i < expectedW.length; i++) {
+            const w = expectedW[i]!;
+            const g = gotW[i]!;
+            if (w.code !== g.code) {
+              checks.push({
+                kind: "expected-warnings",
+                passed: false,
+                detail: `warning[${i}].code: expected '${w.code}', got '${g.code}'`,
+              });
+              continue;
+            }
+            if (w.source === undefined) continue;
+            if (w.source.format !== g.source.format) {
+              checks.push({
+                kind: "expected-warnings",
+                passed: false,
+                detail: `warning[${i}].source.format: expected '${w.source.format}', got '${g.source.format}'`,
+              });
+            }
+            const wf = [...w.source.files];
+            const gf = [...g.source.files];
+            if (wf.length !== gf.length || !wf.every((f, j) => f === gf[j])) {
+              checks.push({
+                kind: "expected-warnings",
+                passed: false,
+                detail: `warning[${i}].source.files: expected [${wf.join(",")}], got [${gf.join(",")}]`,
+              });
+            }
+            if (w.source.jsonPath !== undefined && w.source.jsonPath !== g.source.jsonPath) {
+              checks.push({
+                kind: "expected-warnings",
+                passed: false,
+                detail: `warning[${i}].source.jsonPath: expected '${w.source.jsonPath}', got '${g.source.jsonPath}'`,
+              });
+            }
+          }
         }
       }
     }
@@ -218,8 +265,10 @@ export async function runFixture(
           ...(passed ? {} : { detail: `expected [${want}], got [${got}]` }),
         });
       }
-    } else if (fix.hasExpected) {
+    } else if (fix.hasExpected && !fix.hasExpectedErrors) {
       // Happy-path fixture with no expected-warnings.json — assert no warnings.
+      // Skip when the fixture uses expected-errors.json (envelope shape); that
+      // block above already asserted warning count + per-element envelope.
       const passed = outcome.warnings.length === 0;
       if (!passed) {
         checks.push({
diff --git a/server/typescript/packages/conformance/test/runner.test.ts b/server/typescript/packages/conformance/test/runner.test.ts
@@ -217,3 +217,135 @@ test("malformed script.json (bad JSON) → failed check, no throw", async () =>
   expect(errCheck!.passed).toBe(false);
   expect(errCheck!.detail).toMatch(/parse error/);
 });
+
+// ── FR5c-finalize — warning envelope-shape assertion ────────────────────────
+
+test("expected-errors warnings: matching envelope shape → pass", async () => {
+  const warnAdapter: ConformanceAdapter = {
+    ...fake,
+    async loadFixture() {
+      return {
+        tree: { ok: true },
+        errorCodes: [],
+        warnings: ["dup decl"],
+        warningEnvelopes: [{
+          code: "WARN_DUPLICATE_DECLARATION",
+          source: { format: "merged", files: ["meta.a.json", "meta.b.json"] },
+        }],
+      };
+    },
+  };
+  const root = await fixture({
+    "input/m.json": "{}",
+    "expected.json": '{"ok":true}',
+    "expected-errors.json": JSON.stringify({
+      errors: [],
+      warnings: [{
+        code: "WARN_DUPLICATE_DECLARATION",
+        source: { format: "merged", files: ["meta.a.json", "meta.b.json"] },
+      }],
+    }),
+  });
+  const [fix] = await discoverFixtures(root);
+  const report = await runFixture(fix!, warnAdapter);
+  expect(report.status).toBe("pass");
+});
+
+test("expected-errors warnings: mismatched code → fail with warning[i].code detail", async () => {
+  const warnAdapter: ConformanceAdapter = {
+    ...fake,
+    async loadFixture() {
+      return {
+        tree: { ok: true },
+        errorCodes: [],
+        warnings: ["something else"],
+        warningEnvelopes: [{
+          code: "WARN_SOMETHING_ELSE",
+          source: { format: "merged", files: ["meta.a.json"] },
+        }],
+      };
+    },
+  };
+  const root = await fixture({
+    "input/m.json": "{}",
+    "expected.json": '{"ok":true}',
+    "expected-errors.json": JSON.stringify({
+      errors: [],
+      warnings: [{
+        code: "WARN_DUPLICATE_DECLARATION",
+        source: { format: "merged", files: ["meta.a.json"] },
+      }],
+    }),
+  });
+  const [fix] = await discoverFixtures(root);
+  const report = await runFixture(fix!, warnAdapter);
+  expect(report.status).toBe("fail");
+  const detail = report.checks.filter((c) => !c.passed).map((c) => c.detail).join("; ");
+  expect(detail).toMatch(/warning\[0\]\.code/);
+});
+
+test("expected-errors warnings: mismatched files → fail with warning[i].source.files detail", async () => {
+  const warnAdapter: ConformanceAdapter = {
+    ...fake,
+    async loadFixture() {
+      return {
+        tree: { ok: true },
+        errorCodes: [],
+        warnings: ["dup decl"],
+        warningEnvelopes: [{
+          code: "WARN_DUPLICATE_DECLARATION",
+          source: { format: "merged", files: ["meta.a.json", "meta.c.json"] },
+        }],
+      };
+    },
+  };
+  const root = await fixture({
+    "input/m.json": "{}",
+    "expected.json": '{"ok":true}',
+    "expected-errors.json": JSON.stringify({
+      errors: [],
+      warnings: [{
+        code: "WARN_DUPLICATE_DECLARATION",
+        source: { format: "merged", files: ["meta.a.json", "meta.b.json"] },
+      }],
+    }),
+  });
+  const [fix] = await discoverFixtures(root);
+  const report = await runFixture(fix!, warnAdapter);
+  expect(report.status).toBe("fail");
+  const detail = report.checks.filter((c) => !c.passed).map((c) => c.detail).join("; ");
+  expect(detail).toMatch(/warning\[0\]\.source\.files/);
+});
+
+test("expected-errors warnings: count mismatch → fail with warnings count detail", async () => {
+  const warnAdapter: ConformanceAdapter = {
+    ...fake,
+    async loadFixture() {
+      return {
+        tree: { ok: true },
+        errorCodes: [],
+        warnings: ["only one"],
+        warningEnvelopes: [{
+          code: "WARN_DUPLICATE_DECLARATION",
+          source: { format: "merged", files: ["meta.a.json"] },
+        }],
+      };
+    },
+  };
+  const root = await fixture({
+    "input/m.json": "{}",
+    "expected.json": '{"ok":true}',
+    "expected-errors.json": JSON.stringify({
+      errors: [],
+      warnings: [
+        { code: "WARN_DUPLICATE_DECLARATION", source: { format: "merged", files: ["meta.a.json"] } },
+        { code: "WARN_DUPLICATE_DECLARATION", source: { format: "merged", files: ["meta.a.json"] } },
+      ],
+    }),
+  });
+  const [fix] = await discoverFixtures(root);
+  const report = await runFixture(fix!, warnAdapter);
+  expect(report.status).toBe("fail");
+  const detail = report.checks.filter((c) => !c.passed).map((c) => c.detail).join("; ");
+  expect(detail).toMatch(/warnings count: expected 2, got 1/);
+});
diff --git a/server/typescript/packages/metadata/test/conformance/adapter.ts b/server/typescript/packages/metadata/test/conformance/adapter.ts
@@ -95,6 +95,29 @@ export const tsAdapter: ConformanceAdapter = {
         source: { format: "json", files: [], jsonPath: "$" },
       };
     });
+    // FR5c-finalize — surface warning envelopes (same envelope shape as
+    // errors). Loader warnings already carry full `LoaderWarning` envelopes;
+    // mirror the error-envelope normalization (relativize files; preserve
+    // jsonPath / referrer / target when present on the source variant).
+    const warningEnvelopes: ErrorEnvelopeRecord[] = result.warnings.map((w) => {
+      const src = w.source;
+      if (src.format === "json" || src.format === "yaml"
+        || src.format === "merged" || src.format === "resolved") {
+        const files = src.files.map(relativize);
+        const jp = (src as { jsonPath?: string }).jsonPath;
+        const referrer = (src as { referrer?: string }).referrer;
+        const target = (src as { target?: string }).target;
+        const source: ErrorEnvelopeRecord["source"] = {
+          format: src.format,
+          files,
+          ...(jp !== undefined ? { jsonPath: jp } : {}),
+          ...(referrer !== undefined ? { referrer } : {}),
+          ...(target !== undefined ? { target } : {}),
+        };
+        return { code: w.code, source };
+      }
+      return { code: w.code, source: { format: src.format, files: [] } };
+    });
     return {
       tree: result.root,
       errorCodes: result.errors.map(errorCode),
@@ -103,6 +126,7 @@ export const tsAdapter: ConformanceAdapter = {
       // message for cross-port string-equality comparison.
       warnings: result.warnings.map((w) => w.message),
       errors: envelopes,
+      warningEnvelopes,
     };
   },
 
diff --git a/spec/conformance-tests.md b/spec/conformance-tests.md
@@ -123,7 +123,7 @@ Finalized 2026-05-27 across all four ports (TS / C# / Java / Python). When a fix
 
 Last-writer-wins still governs non-conflicting attr overlays (one side unset, or both sides set to the same value). When both contributors set the same `@attr` to *different* non-empty values, the loader raises `ERR_MERGE_CONFLICT` with a `format: "merged"` envelope listing both contributors. When two files declare a node and the second contributes no semantic change (per the FR5a `semantic_diff`), the loader emits `WARN_DUPLICATE_DECLARATION` and the merged node's `source` is **not** upgraded to `format: "merged"`.
 
-**WARN envelope-shape assertion**: as of FR5c-finalize the cross-port runners assert envelope shape on `errors[]` but compare `warnings[]` as a flat string list against `expected-warnings.json`. The error-side envelope assertion (code + source.format + source.files + source.jsonPath) is the cross-port contract; lifting the same assertion onto warnings is queued as follow-up work and is gated on a fixture migration from `expected-warnings.json` (string array) to `expected-errors.json#warnings[]` (envelope shape). All four ports currently exercise the FR5c `warning-duplicate-declaration` fixture under the string-list contract.
+**WARN envelope-shape assertion** (TS reference; cross-port follow-up): the conformance runner asserts envelope shape on `warnings[]` (code + source.format + source.files + source.jsonPath) when the fixture's `expected-errors.json` declares warning entries with `source`. Algorithm mirrors errors: per-warning code first, then per-element source-field comparison in declaration order. The `warning-duplicate-declaration` fixture is the reference (migrated from `expected-warnings.json` string list to `expected-errors.json#warnings[]` envelope). Ports that have not yet surfaced `warningEnvelopes` on their `LoadOutcome` get the warnings count check only; per-element source assertions activate as each port's adapter populates the field.
 
 ## TS conformance runner
 
