@intentius/chant 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/build.ts

@@ -143,6 +143,12 @@ export interface BuildOptions {
    * native metadata channel. Resolved from project config by the caller.
    */
   ownership?: OwnershipMarker;
+
+  /**
+   * The resolved project configuration, passed through to each serializer's
+   * {@link SerializeContext} so a dialect can read its lexicon-scoped settings.
+   */
+  config?: Record<string, unknown>;
 }
 
 export interface BuildResult {
@@ -553,10 +559,15 @@ export async function build(
         ...(outputsByLexicon.get(lexiconName) ?? []),
         ...unassignedOutputs,
       ];
-      outputs.set(
-        lexiconName,
-        serializer.serialize(lexiconEntities, lexiconLexiconOutputs, { ownership: options?.ownership }),
-      );
+      const serialized = serializer.serialize(lexiconEntities, lexiconLexiconOutputs, {
+        ownership: options?.ownership,
+        config: options?.config,
+      });
+      // Collect any non-fatal serializer diagnostics into the build warnings.
+      if (typeof serialized !== "string" && serialized.warnings) {
+        for (const w of serialized.warnings) warnings.push(w);
+      }
+      outputs.set(lexiconName, serialized);
     } else {
       warnings.push(`No serializer found for lexicon "${lexiconName}"`);
     }

package/src/cli/commands/build.test.ts

@@ -1,6 +1,7 @@
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
-import { buildCommand, type BuildOptions } from "./build";
+import { buildCommand, resolveBuildFormat, type BuildOptions } from "./build";
 import type { Serializer } from "../../serializer";
+import { parseYAML } from "../../yaml";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -199,4 +200,80 @@ export const testEntity = {
     expect(existsSync(join(testDir, "dist", "ops", "alb-deploy", "activities.ts"))).toBe(true);
     expect(existsSync(join(testDir, "dist", "ops", "alb-deploy", "worker.ts"))).toBe(true);
   });
+
+  // ── #284 bug 2: array-of-objects must serialize to valid YAML ──────────
+  test("yaml format serializes an array of objects to valid, round-trippable YAML", async () => {
+    // A serializer that emits a CloudFormation-shaped template with a tag list.
+    const cfnSerializer: Serializer = {
+      name: "test",
+      rulePrefix: "TEST",
+      serialize: () =>
+        JSON.stringify({
+          Resources: {
+            Bucket: {
+              Type: "AWS::S3::Bucket",
+              Properties: {
+                BucketName: "x",
+                Tags: [
+                  { Key: "team", Value: "infra" },
+                  { Key: "env", Value: "prod" },
+                ],
+              },
+            },
+          },
+        }),
+    };
+    await writeFile(
+      join(testDir, "test.infra.ts"),
+      `export const e = { lexicon: "test", entityType: "TestEntity", [Symbol.for("chant.declarable")]: true };`,
+    );
+    const yamlOut = join(testDir, "template.yaml");
+
+    const result = await buildCommand({
+      path: testDir,
+      output: yamlOut,
+      format: "yaml",
+      serializers: [cfnSerializer],
+    });
+
+    expect(result.success).toBe(true);
+    const content = readFileSync(yamlOut, "utf-8");
+    // The list item must not be inlined onto the `Tags:` line (same-line dash).
+    expect(content).not.toMatch(/Tags:[ \t]+-/);
+    // And it must round-trip through a real YAML parser to the intended shape.
+    const parsed = parseYAML(content) as {
+      Resources: { Bucket: { Properties: { Tags: Array<{ Key: string; Value: string }> } } };
+    };
+    expect(parsed.Resources.Bucket.Properties.Tags).toEqual([
+      { Key: "team", Value: "infra" },
+      { Key: "env", Value: "prod" },
+    ]);
+  });
+});
+
+// ── #284 bug 1: -o extension drives format when --format is absent ────────
+describe("resolveBuildFormat", () => {
+  test("infers yaml from .yaml / .yml extension", () => {
+    expect(resolveBuildFormat("", "template.yaml")).toEqual({ format: "yaml" });
+    expect(resolveBuildFormat("", "template.yml")).toEqual({ format: "yaml" });
+  });
+
+  test("infers json from .json extension", () => {
+    expect(resolveBuildFormat("", "template.json")).toEqual({ format: "json" });
+  });
+
+  test("defaults to json when there is no extension to infer from", () => {
+    expect(resolveBuildFormat("", undefined)).toEqual({ format: "json" });
+    expect(resolveBuildFormat("", "outdir")).toEqual({ format: "json" });
+  });
+
+  test("explicit --format wins, and a mismatch with the extension warns", () => {
+    const r = resolveBuildFormat("json", "template.yaml");
+    expect(r.format).toBe("json");
+    expect(r.warning).toMatch(/yaml/i);
+  });
+
+  test("explicit --format matching the extension does not warn", () => {
+    expect(resolveBuildFormat("yaml", "template.yaml")).toEqual({ format: "yaml" });
+  });
 });

package/src/cli/commands/build.ts

@@ -34,6 +34,38 @@ export interface BuildOptions {
   env?: string;
 }
 
+/**
+ * Resolve the output format for `chant build`.
+ *
+ * When `--format` is not given, infer it from the `-o` file extension
+ * (`.yaml`/`.yml` → yaml, `.json` → json); fall back to json when there is no
+ * extension to infer from. An explicit `--format` always wins, but a mismatch
+ * with the output extension is surfaced as a warning.
+ */
+export function resolveBuildFormat(
+  explicit: string | undefined,
+  output: string | undefined,
+): { format: "json" | "yaml"; warning?: string } {
+  const inferred = output
+    ? /\.ya?ml$/i.test(output)
+      ? "yaml"
+      : /\.json$/i.test(output)
+        ? "json"
+        : undefined
+    : undefined;
+
+  if (explicit === "json" || explicit === "yaml") {
+    if (inferred && inferred !== explicit) {
+      return {
+        format: explicit,
+        warning: `Output file "${output}" looks like ${inferred} but --format ${explicit} was given; writing ${explicit}.`,
+      };
+    }
+    return { format: explicit };
+  }
+
+  return { format: inferred ?? "json" };
+}
 
 /**
  * Build command result
@@ -79,7 +111,10 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
     : [];
 
   // Run the build
-  const result = await build(infraPath, options.serializers, undefined, { ownership });
+  const result = await build(infraPath, options.serializers, undefined, {
+    ownership,
+    config: config as unknown as Record<string, unknown>,
+  });
 
   // Format errors
   for (const error of result.errors) {
@@ -105,11 +140,15 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
       const checks = plugin.postSynthChecks();
       if (checks.length === 0) continue;
 
-      // Scope outputs to this plugin's lexicon so cross-lexicon outputs don't interfere
+      // Scope outputs to this plugin's lexicon so cross-lexicon outputs don't
+      // interfere. Outputs are keyed by the serializer's lexicon name (the
+      // build partition key), which differs from plugin.name for a dialect like
+      // forgejo (plugin "forgejo", serializer "github").
+      const outputKey = plugin.serializer.name;
       const scopedOutputs = new Map<string, string | SerializerResult>();
-      const pluginOutput = result.outputs.get(plugin.name);
+      const pluginOutput = result.outputs.get(outputKey);
       if (pluginOutput !== undefined) {
-        scopedOutputs.set(plugin.name, pluginOutput);
+        scopedOutputs.set(outputKey, pluginOutput);
       }
 
       const scopedResult = { ...result, outputs: scopedOutputs };
@@ -326,7 +365,12 @@ function jsonToYaml(obj: unknown, indent = 0): string {
     return entries
       .map(([key, value]) => {
         const yamlValue = jsonToYaml(value, indent + 1);
-        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        // A non-empty container (object OR array) renders as a block: the key on
+        // its own line, the value indented beneath it. Arrays were previously
+        // excluded here, which inlined `Tags: - Key: t` as invalid YAML.
+        const isContainer = typeof value === "object" && value !== null;
+        const isEmpty = isContainer && (Array.isArray(value) ? value.length === 0 : Object.keys(value).length === 0);
+        if (isContainer && !isEmpty) {
           return `${spaces}${key}:\n${yamlValue}`;
         }
         return `${spaces}${key}: ${yamlValue.trimStart()}`;

package/src/cli/handlers/build.ts

@@ -1,4 +1,4 @@
-import { buildCommand, buildCommandWatch, printErrors, printWarnings } from "../commands/build";
+import { buildCommand, buildCommandWatch, printErrors, printWarnings, resolveBuildFormat } from "../commands/build";
 import { formatError, formatInfo } from "../format";
 import type { CommandContext } from "../registry";
 
@@ -15,11 +15,16 @@ export async function runBuild(ctx: CommandContext): Promise<number> {
     }
   }
 
-  const buildFormat = (args.format || "json") as "json" | "yaml";
-  if (buildFormat !== "json" && buildFormat !== "yaml") {
-    console.error(formatError({ message: `Invalid format for build: ${buildFormat}. Expected 'json' or 'yaml'.` }));
+  if (args.format && args.format !== "json" && args.format !== "yaml") {
+    console.error(formatError({ message: `Invalid format for build: ${args.format}. Expected 'json' or 'yaml'.` }));
     return 1;
   }
+  // Infer format from the -o extension when --format is not given; an explicit
+  // --format wins but a mismatch warns (#284 bug 1).
+  const { format: buildFormat, warning: formatWarningMsg } = resolveBuildFormat(args.format, args.output);
+  if (formatWarningMsg) {
+    console.error(formatInfo(formatWarningMsg));
+  }
 
   if (args.watch) {
     const cleanup = buildCommandWatch({

package/src/cli/handlers/lifecycle.ts

@@ -4,7 +4,7 @@ import { takeSnapshot } from "../../lifecycle/snapshot";
 import { readSnapshot, readEnvironmentSnapshots, listSnapshots, fetchLifecycle, StaleLifecycleBranchError } from "../../lifecycle/git";
 import { computeBuildDigest, diffDigests } from "../../lifecycle/digest";
 import { diffLive, diffLiveArtifacts, type LiveDiffResult, type LiveArtifactDiffResult } from "../../lifecycle/live-diff";
-import { buildChangeSet, renderChangeSet, type ChangeSet } from "../../lifecycle/change-set";
+import { buildChangeSet, renderChangeSet, gitlabMrReport, type ChangeSet } from "../../lifecycle/change-set";
 import { affectedStacks } from "../../lifecycle/affected";
 import { loadChantConfig } from "../../config";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
@@ -520,6 +520,14 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
 
   merged.entries.sort((a, b) => a.name.localeCompare(b.name));
 
+  // `--report gitlab-mr` emits the GitLab MR plan-widget artifact instead of the
+  // human render. Write it to a file (`tfplan.json`) in CI and declare it as
+  // `artifacts:reports:terraform` to light up the merge-request widget.
+  if (args.reportFile === "gitlab-mr") {
+    console.log(JSON.stringify(gitlabMrReport(merged)));
+    return 0;
+  }
+
   if (args.json) {
     console.log(JSON.stringify(merged, null, 2));
   } else {

package/src/cli/main.ts

@@ -227,6 +227,8 @@ Options:
   --json                Emit the structured run result as JSON (run command)
   --report              Print deployment report instead of running (run command)
                         OR with a path arg: SARIF report destination (migrate)
+                        OR '--report gitlab-mr': emit the GitLab MR plan-widget
+                        JSON (lifecycle plan)
   --from <name>         Source lexicon for migrate (default: github)
   --to <name>           Target lexicon for migrate (default: gitlab)
   --emit <fmt>          Migration output format: yaml (default) or ts

package/src/composite.ts

@@ -1,4 +1,5 @@
 import { isDeclarable, type Declarable } from "./declarable";
+import { setProvenance } from "./provenance";
 
 /**
  * Marker symbol for Composite type identification.
@@ -128,15 +129,20 @@ export function expandComposite(
   const result = new Map<string, Declarable>();
   const shared = (instance as unknown as Record<symbol, unknown>)[SHARED_PROPS] as Record<string, unknown> | undefined;
 
+  const compositeName = instance._definition?.compositeName;
+
   for (const [memberName, member] of Object.entries(instance.members)) {
     const fullName = `${prefix}${memberName[0].toUpperCase()}${memberName.slice(1)}`;
 
     if (isCompositeInstance(member)) {
       const nested = expandComposite(fullName, member);
       for (const [nestedName, nestedEntity] of nested) {
+        // Inner composite already stamped; `??=` keeps the most-specific one.
+        if (compositeName) setProvenance(nestedEntity, { composite: compositeName });
         result.set(nestedName, nestedEntity);
       }
     } else {
+      if (compositeName) setProvenance(member as Declarable, { composite: compositeName });
       result.set(fullName, member as Declarable);
     }
   }

package/src/discovery/collect.ts

@@ -2,6 +2,7 @@ import { isDeclarable, type Declarable } from "../declarable";
 import { isCompositeInstance, expandComposite } from "../composite";
 import { isLexiconOutput } from "../lexicon-output";
 import { DiscoveryError } from "../errors";
+import { setProvenance } from "../provenance";
 
 /**
  * Collects all declarable entities from imported modules.
@@ -32,6 +33,7 @@ export function collectEntities(
             );
           }
         } else {
+          setProvenance(value, { sourceFile: file });
           entities.set(name, value);
         }
       } else if (Array.isArray(value)) {
@@ -43,6 +45,7 @@ export function collectEntities(
             if (entities.has(indexedName) && entities.get(indexedName) !== item) {
               throw new DiscoveryError(file, `Duplicate entity name "${indexedName}"`, "resolution");
             }
+            setProvenance(item, { sourceFile: file });
             entities.set(indexedName, item);
           } else if (isCompositeInstance(item)) {
             const indexedName = `${name}_${i}`;
@@ -55,6 +58,7 @@ export function collectEntities(
                   "resolution",
                 );
               }
+              setProvenance(entity, { sourceFile: file });
               entities.set(expandedName, entity);
             }
           }
@@ -69,6 +73,7 @@ export function collectEntities(
               "resolution",
             );
           }
+          setProvenance(entity, { sourceFile: file });
           entities.set(expandedName, entity);
         }
       } else if (isLexiconOutput(value)) {

package/src/index.ts

@@ -6,6 +6,7 @@
 
 export * from "./declarable";
 export * from "./composite";
+export * from "./provenance";
 export * from "./intrinsic";
 export * from "./types";
 export * from "./errors";

package/src/lifecycle/change-set.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest";
-import { buildChangeSet, renderChangeSet, summarize } from "./change-set";
+import { buildChangeSet, renderChangeSet, summarize, gitlabMrReport } from "./change-set";
 import type { ResourceMetadata } from "../lexicon";
 
 const meta = (over: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
@@ -149,3 +149,41 @@ describe("summarize / renderChangeSet", () => {
     expect(out).toContain("orphan");
   });
 });
+
+describe("gitlabMrReport (#329)", () => {
+  test("counts only create/update/delete; adopt and noop are excluded", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["new-bucket", "drifted-queue", "stable-topic"]),
+      observedNow: {
+        "drifted-queue": meta({ status: "ACTIVE" }), // declared+live+drift → update
+        "stable-topic": meta({ status: "OK" }), // declared+live, no drift → noop
+        "owned-orphan": meta({ ownership: "owned" }), // owned orphan → delete
+        "foreign-orphan": meta({ ownership: "foreign" }), // foreign orphan → adopt
+        // new-bucket: declared, not live → create
+      },
+      observedThen: {
+        "drifted-queue": meta({ status: "CREATING" }),
+        "stable-topic": meta({ status: "OK" }),
+      },
+    });
+    expect(gitlabMrReport(cs)).toEqual({ create: 1, update: 1, delete: 1 });
+  });
+
+  test("empty plan reports all zeros", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(),
+      observedNow: {},
+      observedThen: undefined,
+    });
+    expect(gitlabMrReport(cs)).toEqual({ create: 0, update: 0, delete: 0 });
+  });
+
+  test("adopt-only plan reports zeros — the widget never shows undeclared resources", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(),
+      observedNow: { orphan: meta() }, // unknown ownership → adopt
+      observedThen: undefined,
+    });
+    expect(gitlabMrReport(cs)).toEqual({ create: 0, update: 0, delete: 0 });
+  });
+});

package/src/lifecycle/change-set.ts

@@ -142,6 +142,30 @@ export function summarize(cs: ChangeSet): Record<ChangeAction, number> {
   return counts;
 }
 
+/**
+ * GitLab MR plan widget report.
+ *
+ * GitLab renders an `artifacts:reports:terraform` artifact in the merge-request
+ * UI as "N to add, M to change, K to delete". The format is generic — any tool
+ * that emits this JSON gets the widget — and the chant plan maps onto it
+ * directly. Only the mutating actions count: `adopt` and `noop` are excluded,
+ * since the widget has no column for "live but undeclared" or "no change".
+ *
+ * The widget label reads "Terraform" regardless of producer; that is GitLab's
+ * fixed string, not a claim chant makes.
+ */
+export interface GitlabMrReport {
+  create: number;
+  update: number;
+  delete: number;
+}
+
+/** Project a change set onto the GitLab MR plan widget shape. Pure. */
+export function gitlabMrReport(cs: ChangeSet): GitlabMrReport {
+  const counts = summarize(cs);
+  return { create: counts.create, update: counts.update, delete: counts.delete };
+}
+
 /** Human-readable render of a change set. Pure — returns a string. */
 export function renderChangeSet(cs: ChangeSet): string {
   const counts = summarize(cs);

package/src/provenance.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "vitest";
+import { setProvenance, getProvenance } from "./provenance";
+import { Composite, expandComposite } from "./composite";
+import { collectEntities } from "./discovery/collect";
+import { DECLARABLE_MARKER, type Declarable } from "./declarable";
+
+const decl = (entityType: string): Declarable =>
+  ({ [DECLARABLE_MARKER]: true, lexicon: "test", entityType, kind: "resource", props: {} }) as unknown as Declarable;
+
+const Pair = Composite<{ n: string }>((props) => ({
+  first: decl(`Test::First:${props.n}`),
+  second: decl(`Test::Second:${props.n}`),
+}), "Pair");
+
+describe("provenance side channel", () => {
+  test("set then get returns the stamped fields", () => {
+    const e = decl("Test::Thing");
+    setProvenance(e, { sourceFile: "/proj/src/a.ts" });
+    setProvenance(e, { composite: "MyComposite" });
+    expect(getProvenance(e)).toEqual({ sourceFile: "/proj/src/a.ts", composite: "MyComposite" });
+  });
+
+  test("first writer wins (??= merge keeps the most specific)", () => {
+    const e = decl("Test::Thing");
+    setProvenance(e, { composite: "Inner" });
+    setProvenance(e, { composite: "Outer" });
+    expect(getProvenance(e)?.composite).toBe("Inner");
+  });
+
+  test("provenance is non-enumerable — invisible to spreads and JSON", () => {
+    const e = decl("Test::Thing");
+    setProvenance(e, { sourceFile: "/x.ts" });
+    expect(Object.keys(e)).not.toContain(Symbol.for("chant.provenance").toString());
+    expect(JSON.stringify(e)).not.toContain("provenance");
+  });
+
+  test("getProvenance is undefined when nothing was stamped", () => {
+    expect(getProvenance(decl("Test::Thing"))).toBeUndefined();
+  });
+});
+
+describe("composite expansion stamps composite provenance", () => {
+  test("expandComposite stamps each member with the composite name", () => {
+    const expanded = expandComposite("p", Pair({ n: "x" }));
+    for (const [, entity] of expanded) {
+      expect(getProvenance(entity)?.composite).toBe("Pair");
+    }
+  });
+
+  test("nested composites keep the innermost composite name", () => {
+    // expandComposite recurses on CompositeInstance members at runtime; the
+    // CompositeMembers type only models Declarable leaves, so cast the nested
+    // composite to satisfy the factory's static type.
+    const Wrapper = Composite<{ n: string }>((props) => ({
+      inner: Pair({ n: props.n }) as unknown as Declarable,
+    }), "Wrapper");
+    const expanded = expandComposite("w", Wrapper({ n: "y" }));
+    // Pair's members are the leaves; the inner (Pair) name must win over Wrapper.
+    for (const [, entity] of expanded) {
+      expect(getProvenance(entity)?.composite).toBe("Pair");
+    }
+  });
+});
+
+describe("collectEntities stamps the source file", () => {
+  test("direct exports get their declaring file", () => {
+    const a = decl("Test::A");
+    const entities = collectEntities([{ file: "/proj/src/infra.ts", exports: { a } }]);
+    expect(getProvenance(entities.get("a")!)?.sourceFile).toBe("/proj/src/infra.ts");
+  });
+
+  test("composite-expanded entities get both file and composite", () => {
+    const entities = collectEntities([{ file: "/proj/src/pipe.ts", exports: { p: Pair({ n: "z" }) } }]);
+    const member = entities.get("pFirst")!;
+    const prov = getProvenance(member);
+    expect(prov?.sourceFile).toBe("/proj/src/pipe.ts");
+    expect(prov?.composite).toBe("Pair");
+  });
+});

package/src/provenance.ts

@@ -0,0 +1,46 @@
+/**
+ * Build provenance: where a declared entity came from in the TypeScript source.
+ *
+ * Stamped during discovery as a non-enumerable, symbol-keyed side channel on the
+ * entity object, so it never serializes into the emitted YAML/JSON — it is build
+ * metadata, not declared configuration. Read it back with {@link getProvenance}.
+ *
+ * This is entity-level provenance (which file declared it, and which composite
+ * expanded it), not a YAML-line source map. It answers "where did this resource
+ * come from?", which is the question an agent asks before changing it.
+ */
+
+const PROVENANCE = Symbol.for("chant.provenance");
+
+export interface EntityProvenance {
+  /** Absolute path of the source file that declared (or exported) the entity. */
+  sourceFile?: string;
+  /** The composite that expanded this entity, when it came from one. */
+  composite?: string;
+}
+
+/**
+ * Merge provenance onto an entity. Non-enumerable so it is invisible to
+ * serializers and spreads. Existing fields win (`??=`), so the first/most
+ * specific writer — the innermost composite, the declaring file — is kept.
+ */
+export function setProvenance(entity: object, prov: EntityProvenance): void {
+  if (!Object.isExtensible(entity)) return;
+  const existing = (entity as Record<symbol, unknown>)[PROVENANCE] as EntityProvenance | undefined;
+  if (existing) {
+    existing.sourceFile ??= prov.sourceFile;
+    existing.composite ??= prov.composite;
+    return;
+  }
+  Object.defineProperty(entity, PROVENANCE, {
+    value: { ...prov },
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+}
+
+/** Read an entity's build provenance, if any was stamped. */
+export function getProvenance(entity: object): EntityProvenance | undefined {
+  return (entity as Record<symbol, unknown>)[PROVENANCE] as EntityProvenance | undefined;
+}

package/src/serializer.ts

@@ -12,6 +12,14 @@ export interface SerializeContext {
    * native metadata channel (AWS/Azure tags, K8s/GCP labels).
    */
   ownership?: OwnershipMarker;
+
+  /**
+   * The resolved project configuration, when a build was driven from a project
+   * with a `chant.config.*`. Lets a serializer read its own lexicon-scoped
+   * settings (e.g. the forgejo dialect's `forgejo.runnerLabels`). Undefined for
+   * ad-hoc builds (e.g. context tools) that pass no config.
+   */
+  config?: Record<string, unknown>;
 }
 
 /**
@@ -22,6 +30,12 @@ export interface SerializerResult {
   primary: string;
   /** Additional files keyed by filename (e.g. "network.template.json" → content) */
   files?: Record<string, string>;
+  /**
+   * Non-fatal diagnostics produced during serialization (e.g. a dialect
+   * dropping keys the target platform ignores). The build pipeline collects
+   * these into its `warnings` array.
+   */
+  warnings?: string[];
 }
 
 /**