@intentius/chant 0.49.0 → 0.50.0

package/src/lint/output-docs.test.ts

@@ -0,0 +1,220 @@
+import { describe, test, expect } from "vitest";
+import { parseOutputDocs, pick, get } from "./output-docs";
+import type { SerializerResult } from "../serializer";
+
+describe("parseOutputDocs", () => {
+  test("parses a single JSON output as one document", () => {
+    const outputs = new Map<string, string | SerializerResult>([
+      ["aws", JSON.stringify({ AWSTemplateFormatVersion: "2010-09-09", Resources: {} })],
+    ]);
+    const docs = parseOutputDocs(outputs);
+    expect(docs).toHaveLength(1);
+    expect(docs[0]).toMatchObject({
+      lexicon: "aws",
+      index: 0,
+      format: "json",
+    });
+    expect(docs[0].error).toBeUndefined();
+    expect((docs[0].value as { Resources: unknown }).Resources).toEqual({});
+  });
+
+  test("splits multi-document YAML on `---` into one OutputDoc per document", () => {
+    const yaml = [
+      "apiVersion: v1",
+      "kind: Namespace",
+      "metadata:",
+      "  name: ns-a",
+      "---",
+      "apiVersion: apps/v1",
+      "kind: Deployment",
+      "metadata:",
+      "  name: web",
+    ].join("\n");
+    const outputs = new Map<string, string | SerializerResult>([["k8s", yaml]]);
+    const docs = parseOutputDocs(outputs);
+    expect(docs).toHaveLength(2);
+    expect(docs[0]).toMatchObject({ lexicon: "k8s", index: 0, format: "yaml" });
+    expect(docs[1]).toMatchObject({ lexicon: "k8s", index: 1, format: "yaml" });
+    expect((docs[0].value as { kind: string }).kind).toBe("Namespace");
+    expect((docs[1].value as { kind: string }).kind).toBe("Deployment");
+  });
+
+  test("handles a leading `---` document separator before any content", () => {
+    const yaml = ["---", "kind: Namespace", "---", "kind: Deployment"].join("\n");
+    const outputs = new Map<string, string | SerializerResult>([["k8s", yaml]]);
+    const docs = parseOutputDocs(outputs);
+    expect(docs).toHaveLength(2);
+    expect((docs[0].value as { kind: string }).kind).toBe("Namespace");
+    expect((docs[1].value as { kind: string }).kind).toBe("Deployment");
+  });
+
+  test("drops empty documents between/around separators without erroring", () => {
+    const yaml = ["---", "", "---", "kind: Deployment", "---", ""].join("\n");
+    const outputs = new Map<string, string | SerializerResult>([["k8s", yaml]]);
+    const docs = parseOutputDocs(outputs);
+    expect(docs).toHaveLength(1);
+    expect((docs[0].value as { kind: string }).kind).toBe("Deployment");
+  });
+
+  test("parses SerializerResult.files as additional, separately-indexed documents", () => {
+    const output: SerializerResult = {
+      primary: JSON.stringify({ kind: "root" }),
+      files: {
+        "nested.template.json": JSON.stringify({ kind: "nested-a" }),
+        "sidecar.yaml": "kind: nested-b\n---\nkind: nested-c",
+      },
+    };
+    const outputs = new Map<string, string | SerializerResult>([["aws", output]]);
+    const docs = parseOutputDocs(outputs);
+
+    const primaryDocs = docs.filter((d) => d.file === undefined);
+    expect(primaryDocs).toHaveLength(1);
+    expect((primaryDocs[0].value as { kind: string }).kind).toBe("root");
+
+    const nestedJson = docs.filter((d) => d.file === "nested.template.json");
+    expect(nestedJson).toHaveLength(1);
+    expect((nestedJson[0].value as { kind: string }).kind).toBe("nested-a");
+
+    // The sidecar YAML file is itself multi-document — index resets to 0
+    // within that file, since index is scoped to its own source.
+    const sidecarDocs = docs.filter((d) => d.file === "sidecar.yaml");
+    expect(sidecarDocs).toHaveLength(2);
+    expect(sidecarDocs[0].index).toBe(0);
+    expect(sidecarDocs[1].index).toBe(1);
+    expect((sidecarDocs[0].value as { kind: string }).kind).toBe("nested-b");
+    expect((sidecarDocs[1].value as { kind: string }).kind).toBe("nested-c");
+
+    expect(docs.every((d) => d.lexicon === "aws")).toBe(true);
+  });
+
+  test("skips a source with no files entries and no primary content", () => {
+    const outputs = new Map<string, string | SerializerResult>([["empty", ""]]);
+    expect(parseOutputDocs(outputs)).toEqual([]);
+  });
+
+  test("parses every ctx.outputs entry, tagging each with its own lexicon key", () => {
+    const outputs = new Map<string, string | SerializerResult>([
+      ["aws", JSON.stringify({ kind: "aws-thing" })],
+      ["k8s", "kind: k8s-thing"],
+    ]);
+    const docs = parseOutputDocs(outputs);
+    expect(docs.map((d) => d.lexicon).sort()).toEqual(["aws", "k8s"]);
+  });
+
+  describe("malformed documents — marker, not throw", () => {
+    test("a bare scalar document is marked with an error instead of being treated as a manifest", () => {
+      // "42" is syntactically fine (valid YAML/JSON) but is a scalar, not an
+      // object/array — not something a manifest-shaped check can walk.
+      const yaml = ["kind: Deployment", "---", "42", "---", "kind: Service"].join("\n");
+      const outputs = new Map<string, string | SerializerResult>([["k8s", yaml]]);
+      const docs = parseOutputDocs(outputs);
+
+      expect(docs).toHaveLength(3);
+      expect(docs[0].error).toBeUndefined();
+      expect(docs[2].error).toBeUndefined();
+
+      // The malformed middle document is a marker: present, flagged, no value.
+      expect(docs[1].error).toBeDefined();
+      expect(docs[1].value).toBeUndefined();
+      expect(docs[1].format).toBe("yaml");
+
+      // Filtering it out is one line, and leaves the good documents intact.
+      const usable = docs.filter((d) => !d.error);
+      expect(usable).toHaveLength(2);
+      expect((usable[0].value as { kind: string }).kind).toBe("Deployment");
+      expect((usable[1].value as { kind: string }).kind).toBe("Service");
+    });
+
+    test("a lone scalar as the entire output is marked with an error, not thrown", () => {
+      // Valid JSON ("true" parses fine) but not an object/array — the
+      // whole-content JSON path hits the same isUsableDoc guard.
+      const outputs = new Map<string, string | SerializerResult>([["weird", "true"]]);
+      expect(() => parseOutputDocs(outputs)).not.toThrow();
+      const docs = parseOutputDocs(outputs);
+      expect(docs).toHaveLength(1);
+      expect(docs[0].format).toBe("json");
+      expect(docs[0].error).toBeDefined();
+      expect(docs[0].value).toBeUndefined();
+    });
+
+    test("a malformed document in one files entry does not affect the others", () => {
+      const output: SerializerResult = {
+        primary: "kind: root",
+        files: {
+          "good.yaml": "kind: good",
+          "bad.yaml": "null",
+        },
+      };
+      const outputs = new Map<string, string | SerializerResult>([["k8s", output]]);
+      const docs = parseOutputDocs(outputs);
+
+      const good = docs.find((d) => d.file === "good.yaml")!;
+      const bad = docs.find((d) => d.file === "bad.yaml")!;
+      expect(good.error).toBeUndefined();
+      expect((good.value as { kind: string }).kind).toBe("good");
+      expect(bad.error).toBeDefined();
+      expect(bad.value).toBeUndefined();
+    });
+  });
+});
+
+describe("pick", () => {
+  interface Widget {
+    kind: string;
+    name: string;
+    extra: unknown;
+  }
+
+  test("returns only the named keys that are present", () => {
+    const value = { kind: "Deployment", name: "web", other: "ignored" };
+    expect(pick<Widget>(value, ["kind", "name"])).toEqual({ kind: "Deployment", name: "web" });
+  });
+
+  test("omits a named key that is absent — no invented default", () => {
+    const value = { kind: "Deployment" };
+    expect(pick<Widget>(value, ["kind", "name"])).toEqual({ kind: "Deployment" });
+  });
+
+  test("returns an empty object for a non-object value", () => {
+    expect(pick<Widget>(null, ["kind"])).toEqual({});
+    expect(pick<Widget>("a string", ["kind"])).toEqual({});
+    expect(pick<Widget>(undefined, ["kind"])).toEqual({});
+  });
+
+  test("copies values through unvalidated, whatever their actual shape", () => {
+    const value = { kind: 42 }; // wrong runtime type for `kind: string`
+    expect(pick<Widget>(value, ["kind"])).toEqual({ kind: 42 });
+  });
+});
+
+describe("get", () => {
+  test("walks a dotted path through nested objects", () => {
+    const value = { spec: { template: { spec: { containers: [] } } } };
+    expect(get(value, "spec.template.spec")).toEqual({ containers: [] });
+  });
+
+  test("returns undefined as soon as a segment is missing", () => {
+    const value = { spec: {} };
+    expect(get(value, "spec.template.spec")).toBeUndefined();
+  });
+
+  test("returns undefined when an intermediate value is not indexable", () => {
+    const value = { spec: "not-an-object" };
+    expect(get(value, "spec.template")).toBeUndefined();
+  });
+
+  test("indexes into arrays with a numeric path segment", () => {
+    const value = { items: [{ name: "first" }, { name: "second" }] };
+    expect(get(value, "items.1.name")).toBe("second");
+  });
+
+  test("returns the value itself for an empty path", () => {
+    const value = { a: 1 };
+    expect(get(value, "")).toBe(value);
+  });
+
+  test("does not throw on null/undefined input", () => {
+    expect(get(null, "a.b")).toBeUndefined();
+    expect(get(undefined, "a.b")).toBeUndefined();
+  });
+});

package/src/lint/output-docs.ts

@@ -0,0 +1,204 @@
+/**
+ * Parsed-output view for post-synth checks (chant #975).
+ *
+ * `PostSynthContext.outputs` carries raw serialized strings — a `chant build`
+ * consumer has to parse YAML/JSON itself before it can reason about
+ * structure. Every lexicon that needs this today rolls its own splitter
+ * (`parseK8sManifests` in k8s, hand-rolled `JSON.parse` in aws's
+ * `cf-refs.ts`), and each of the ~30 k8s post-synth checks reparses the same
+ * output independently. This module is the shared, parse-once primitive:
+ * `parseOutputDocs` turns `ctx.outputs` into a flat list of `OutputDoc`s,
+ * and `PostSynthContext.docs` (see `./post-synth.ts`) memoizes one call to it
+ * per build so every check — lexicon-shipped or project-authored policy —
+ * shares the same parse.
+ *
+ * `pick`/`get` are the "look at only the fields you care about" ergonomic
+ * from the issue's `,remain`-style framing — a partial, unvalidated view of
+ * an already-parsed tree, not a query DSL. Selector languages over the
+ * *source* AST stay in `./declarative.ts`; this module is output-side only.
+ */
+
+import type { SerializerResult } from "../serializer";
+import { parseYAML } from "../yaml";
+
+/**
+ * One parsed document from a build's serialized output.
+ *
+ * A single `ctx.outputs` entry can yield more than one `OutputDoc`: a
+ * multi-document YAML stream (`---`-separated) yields one per document, and
+ * a `SerializerResult` with `files` yields further docs for each nested
+ * file (a CloudFormation nested stack template, a sidecar manifest).
+ */
+export interface OutputDoc {
+  /** The `ctx.outputs` map key this document came from. */
+  lexicon: string;
+  /** Position of this document within its source (primary output or one
+   *  `files` entry) — 0 for a single-document source, 0..n-1 for a
+   *  multi-document YAML stream. */
+  index: number;
+  /** Whether this document was decoded as YAML or as whole-content JSON. */
+  format: "yaml" | "json";
+  /** The parsed tree. `undefined` when parsing failed — see `error`. */
+  value: unknown;
+  /**
+   * Set when this document came from a `SerializerResult.files` entry rather
+   * than the primary output — the file's key in that map (e.g. a nested
+   * stack template's filename).
+   */
+  file?: string;
+  /**
+   * Set when this document could not be parsed into a usable tree. The
+   * document is still returned (a marker, not a throw) so a caller can see
+   * that something in the build output failed to parse, rather than the
+   * failure disappearing silently the way `parseK8sManifests` has always
+   * swallowed it. `value` is `undefined` on an errored document. Filter with
+   * `ctx.docs.filter((d) => !d.error)` to get only usable documents.
+   */
+  error?: string;
+}
+
+/**
+ * Parse every output in `outputs` into a flat list of `OutputDoc`s: one call,
+ * shared by every post-synth check via `PostSynthContext.docs`.
+ *
+ * Format detection is whole-source, not per-document: if the entire source
+ * parses as JSON, it is one `"json"` document (CloudFormation, most non-k8s
+ * serializers). Otherwise the source is treated as a YAML stream — split on
+ * `---` document separators — and each resulting document is parsed as YAML
+ * (`format: "yaml"`), even one that happens to also be valid JSON, since
+ * JSON is a YAML subset. `SerializerResult.files` entries (nested templates,
+ * sidecar manifests) are parsed the same way, tagged with `file`.
+ *
+ * A document that fails to parse into a non-null object/array — malformed
+ * input, or a bare scalar where a manifest was expected — is not thrown:
+ * it is included with `error` set and `value: undefined`. See `OutputDoc`.
+ */
+export function parseOutputDocs(outputs: Map<string, string | SerializerResult>): OutputDoc[] {
+  const docs: OutputDoc[] = [];
+  for (const [lexicon, output] of outputs) {
+    const primary = typeof output === "string" ? output : output.primary;
+    docs.push(...parseSource(primary, lexicon));
+
+    const files = typeof output === "string" ? undefined : output.files;
+    for (const [file, content] of Object.entries(files ?? {})) {
+      docs.push(...parseSource(content, lexicon, file));
+    }
+  }
+  return docs;
+}
+
+/** Split a YAML stream on `---` document-separator lines (own line, optional
+ *  trailing whitespace) — including a leading separator before any content,
+ *  which `"\n---\n"`-style splitting misses. Empty documents (two separators
+ *  back to back, or a leading/trailing one) are dropped. */
+function splitYamlDocuments(source: string): string[] {
+  return source
+    .split(/^---[ \t]*$/m)
+    .map((doc) => doc.trim())
+    .filter((doc) => doc.length > 0);
+}
+
+/** True for a value a document is usable as — a non-null object or array.
+ *  A bare scalar ("just a string") parses without error but is not a
+ *  document a check can walk, so it is treated as malformed. */
+function isUsableDoc(value: unknown): boolean {
+  return typeof value === "object" && value !== null;
+}
+
+/**
+ * Parse one source string (a primary output, or one `files` entry) into its
+ * `OutputDoc`s, trying whole-content JSON first and falling back to a
+ * (possibly multi-document) YAML stream. Never throws — a parse failure or
+ * an unusable result becomes a marker document with `error` set.
+ */
+function parseSource(source: string, lexicon: string, file?: string): OutputDoc[] {
+  const trimmed = source.trim();
+  if (trimmed === "") return [];
+
+  try {
+    const value = JSON.parse(trimmed);
+    if (isUsableDoc(value)) {
+      return [{ lexicon, index: 0, format: "json", value, ...(file && { file }) }];
+    }
+    return [
+      {
+        lexicon,
+        index: 0,
+        format: "json",
+        value: undefined,
+        error: "parsed JSON is not an object or array",
+        ...(file && { file }),
+      },
+    ];
+  } catch {
+    // Not whole-content JSON — fall through to the YAML stream path.
+  }
+
+  return splitYamlDocuments(trimmed).map((segment, index) => {
+    try {
+      const value = parseYAML(segment);
+      if (isUsableDoc(value)) {
+        return { lexicon, index, format: "yaml" as const, value, ...(file && { file }) };
+      }
+      return {
+        lexicon,
+        index,
+        format: "yaml" as const,
+        value: undefined,
+        error: "parsed YAML document is not an object or array",
+        ...(file && { file }),
+      };
+    } catch (err) {
+      return {
+        lexicon,
+        index,
+        format: "yaml" as const,
+        value: undefined,
+        error: err instanceof Error ? err.message : String(err),
+        ...(file && { file }),
+      };
+    }
+  });
+}
+
+/**
+ * Partial typed decode — the `,remain`-style ergonomic from `ma91n/tfpolicy`:
+ * decode the fields you care about, leave everything else in place,
+ * unvalidated. Returns a shallow, top-level view of `value` narrowed to the
+ * keys named in `shape`. A key absent from `value` (or `value` not being a
+ * plain object) is simply absent from the result — no default is invented.
+ *
+ * This is NOT runtime validation: a key that IS present is copied as-is,
+ * whatever its actual shape, and cast to `T`'s declared type for that key.
+ * Use `get` for a deeper walk into one of the picked values.
+ */
+export function pick<T extends object>(value: unknown, shape: (keyof T)[]): Partial<T> {
+  const result: Partial<T> = {};
+  if (typeof value !== "object" || value === null) return result;
+  const source = value as Record<string, unknown>;
+  for (const key of shape) {
+    const propertyName = key as string;
+    if (propertyName in source) {
+      (result as Record<string, unknown>)[propertyName] = source[propertyName];
+    }
+  }
+  return result;
+}
+
+/**
+ * Dotted-path getter for the common walk over a parsed doc, e.g.
+ * `get(doc.value, "spec.template.spec")`. Not a query DSL — no wildcards,
+ * no predicates, no array-flattening. An array index is just a numeric path
+ * segment (`get(value, "items.0.name")`), since JS indexes arrays by string
+ * key underneath. Returns `undefined` as soon as any segment is missing or
+ * the value at that point isn't indexable — it never throws on a bad path.
+ */
+export function get(value: unknown, path: string): unknown {
+  if (path === "") return value;
+  let current: unknown = value;
+  for (const segment of path.split(".")) {
+    if (typeof current !== "object" || current === null) return undefined;
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}

package/src/lint/post-synth.test.ts

@@ -145,3 +145,100 @@ describe("isPostSynthCheck", () => {
 // chant #1138 — `applyConfiguredSeverity` (the `lint.rules` severity-override
 // pass over `PostSynthDiagnostic`s) is tested in `./config.test.ts`, where the
 // function itself now lives — see `./config.ts`'s doc comment for why.
+
+// ── chant #975 — ctx.docs: lazy, memoized, shared across every check ───────
+describe("ctx.docs (chant #975)", () => {
+  /** A Map subclass that counts how many times it was iterated — the only
+   *  way `parseOutputDocs` reads its outputs — so the tests below can prove
+   *  "parsed once" without reaching into module internals. */
+  class CountingOutputs extends Map<string, string> {
+    iterations = 0;
+    [Symbol.iterator](): IterableIterator<[string, string]> {
+      this.iterations++;
+      return super[Symbol.iterator]();
+    }
+  }
+
+  test("is not computed until first accessed", () => {
+    const outputs = new CountingOutputs([["k8s", "kind: Namespace"]]);
+    const check: PostSynthCheck = {
+      id: "PS-DOCS-1",
+      description: "never touches ctx.docs",
+      check() {
+        return [];
+      },
+    };
+    runPostSynthChecks([check], createBuildResult({ outputs: outputs as never }));
+    expect(outputs.iterations).toBe(0);
+  });
+
+  test("is parsed exactly once even when read by multiple checks", () => {
+    const outputs = new CountingOutputs([
+      ["k8s", "apiVersion: v1\nkind: Namespace\nmetadata:\n  name: ns-a"],
+    ]);
+    let seenByFirst: unknown;
+    let seenBySecond: unknown;
+    const checks: PostSynthCheck[] = [
+      {
+        id: "PS-DOCS-2A",
+        description: "reads ctx.docs once",
+        check(ctx) {
+          seenByFirst = ctx.docs;
+          return [];
+        },
+      },
+      {
+        id: "PS-DOCS-2B",
+        description: "reads ctx.docs again, and a second time in the same check",
+        check(ctx) {
+          seenBySecond = ctx.docs;
+          void ctx.docs; // a second read within the same check — still no reparse
+          return [];
+        },
+      },
+    ];
+    runPostSynthChecks(checks, createBuildResult({ outputs: outputs as never }));
+    expect(outputs.iterations).toBe(1);
+    // Every reader gets the exact same array instance, not an equal copy.
+    expect(seenByFirst).toBe(seenBySecond);
+  });
+
+  test("parses ctx.outputs into the expected OutputDoc shape", () => {
+    const outputs = new Map<string, string>([
+      ["k8s", "apiVersion: v1\nkind: Namespace\nmetadata:\n  name: ns-a"],
+    ]);
+    const check: PostSynthCheck = {
+      id: "PS-DOCS-3",
+      description: "reads a manifest field off ctx.docs",
+      check(ctx) {
+        const doc = (ctx.docs ?? [])[0];
+        return [
+          {
+            checkId: "PS-DOCS-3",
+            severity: "info",
+            message: `kind=${(doc.value as { kind?: string }).kind}`,
+          },
+        ];
+      },
+    };
+    const diags = runPostSynthChecks([check], createBuildResult({ outputs: outputs as never }));
+    expect(diags[0].message).toBe("kind=Namespace");
+  });
+
+  test("two independent runPostSynthChecks calls each get their own cache", () => {
+    const outputsA = new CountingOutputs([["k8s", "kind: Namespace"]]);
+    const outputsB = new CountingOutputs([["k8s", "kind: Deployment"]]);
+    const reader: PostSynthCheck = {
+      id: "PS-DOCS-4",
+      description: "reads ctx.docs",
+      check(ctx) {
+        void ctx.docs;
+        return [];
+      },
+    };
+    runPostSynthChecks([reader], createBuildResult({ outputs: outputsA as never }));
+    runPostSynthChecks([reader], createBuildResult({ outputs: outputsB as never }));
+    expect(outputsA.iterations).toBe(1);
+    expect(outputsB.iterations).toBe(1);
+  });
+});

package/src/lint/post-synth.ts

@@ -1,6 +1,9 @@
 import type { Declarable } from "../declarable";
 import type { SerializerResult } from "../serializer";
 import type { Severity } from "./rule";
+import { parseOutputDocs, type OutputDoc } from "./output-docs";
+
+export { parseOutputDocs, pick, get, type OutputDoc } from "./output-docs";
 
 /**
  * Context provided to post-synthesis checks.
@@ -16,6 +19,25 @@ export interface PostSynthContext {
    * e.g. "no public buckets in prod". Undefined when no environment is set.
    */
   env?: string;
+  /**
+   * Parsed output documents (chant #975) — `ctx.outputs` run through
+   * `parseOutputDocs` once and cached. A lazy `readonly` getter, not a plain
+   * field: computed on first access and shared across every check in the
+   * run, so a check that only reads `entities` pays nothing, and no two
+   * checks re-parse the same YAML/JSON. See `./output-docs.ts`.
+   *
+   * Optional at the type level — NOT because it can be absent from a real
+   * build. Every context chant itself constructs (`runPostSynthChecks`
+   * below, `@intentius/chant-test-utils`'s `createPostSynthContext` and
+   * `makePostSynthCtx*`) wires it up via `createDocsAccessor` and it is
+   * always present there. It is typed optional only so the many lexicon
+   * tests that build a `PostSynthContext` object literal by hand (predating
+   * this field) keep compiling unchanged, per this issue's own "existing
+   * checks compile unchanged" constraint — a new check that wants `ctx.docs`
+   * should still get a real array from every context chant builds; guard
+   * with `ctx.docs ?? []` only when a context's provenance is unknown.
+   */
+  readonly docs?: OutputDoc[];
   /** Raw build result object */
   buildResult: {
     outputs: Map<string, string | SerializerResult>;
@@ -26,6 +48,25 @@ export interface PostSynthContext {
   };
 }
 
+/**
+ * Build the lazy, memoized `docs` accessor shared by `runPostSynthChecks`
+ * (below) and `@intentius/chant-test-utils`'s `createPostSynthContext` — the
+ * two places a `PostSynthContext` gets constructed. Returns a zero-arg
+ * function suitable for a `get docs()` object-literal accessor; the first
+ * call parses, every later call returns the same cached array.
+ */
+export function createDocsAccessor(
+  outputs: Map<string, string | SerializerResult>,
+): () => OutputDoc[] {
+  let cached: OutputDoc[] | undefined;
+  return () => {
+    if (cached === undefined) {
+      cached = parseOutputDocs(outputs);
+    }
+    return cached;
+  };
+}
+
 /**
  * Extract the primary content string from a serializer output.
  */
@@ -115,11 +156,15 @@ export function runPostSynthChecks(
   buildResult: PostSynthContext["buildResult"],
   env?: string,
 ): PostSynthDiagnostic[] {
+  const getDocs = createDocsAccessor(buildResult.outputs);
   const ctx: PostSynthContext = {
     outputs: buildResult.outputs,
     entities: buildResult.entities,
     env,
     buildResult,
+    get docs(): OutputDoc[] {
+      return getDocs();
+    },
   };
 
   const diagnostics: PostSynthDiagnostic[] = [];

package/src/lint/rules/__fixtures__/comp/comp003/pass/agent-turn.component.ts

@@ -0,0 +1,26 @@
+import type { Component } from "../../../../../../components/component";
+import { phase } from "../../../../../../components/component";
+
+/**
+ * COMP003 pass case (#1944): a bare "run-agent" step with no "noRollback"
+ * opt-out and no component-level "rollback" — must pass COMP003 because
+ * "run-agent"'s rollbackPolicy is "native" (#1941), not "needs-opt-out". This
+ * is the regression test proving the registry's declared rollbackPolicy for
+ * "run-agent" is wired correctly into ctx.rollbackPolicies, the same seam
+ * COMP005 uses for ctx.knownKinds — see comp.test.ts's FIXTURE_ROLLBACK_POLICIES.
+ */
+export const agentTurn: Component = {
+  name: "agent-turn",
+  archetype: "infra",
+  dependsOn: [],
+  deploy: [
+    phase("Run", [
+      {
+        kind: "run-agent",
+        agent: "claude",
+        task: { prompt: "run the migration script and report the result" },
+        workspace: {},
+      },
+    ]),
+  ],
+};