@intentius/chant-lexicon-k8s 0.98.0 → 0.99.0

package/dist/import/embedded.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Where a Kubernetes manifest embeds another lexicon's content, for
+ * `chant import` (#2962).
+ *
+ * The parser offers two kinds of place to core's embedded-content resolver:
+ *
+ * - every `data` value of a ConfigMap, as text (a collector's `config.yaml`,
+ *   a Prometheus rule file, a Grafana dashboard's JSON);
+ * - a `monitoring.coreos.com` PrometheusRule's `spec.groups`, as the rule file
+ *   `{ groups }` those groups would make.
+ *
+ * Which lexicon imports the content is decided by core at run time, from the
+ * lexicons that register an `embeddedImporters()`; this module names none of
+ * them as a dependency. The `expectedOwner` hints below are the conventions
+ * k8s manifests follow, used only to warn when the owner is not installed.
+ */
+import type { EmbeddedContentResolver } from "@intentius/chant/import/embedded";
+/** The `grafana_dashboard` label the Grafana dashboard sidecar looks for (kube-prometheus-stack, the Grafana Helm chart). */
+export declare const GRAFANA_DASHBOARD_LABEL = "grafana_dashboard";
+/**
+ * Offer the embedded content of one resource to `embedded`, replacing each
+ * value an owner imports with the reference it returns. `properties` is the
+ * resource's IR properties, changed in place (with fresh copies of the
+ * objects on the way down).
+ */
+export declare function delegateEmbedded(type: string, kind: string, properties: Record<string, unknown>, embedded: EmbeddedContentResolver): void;
+//# sourceMappingURL=embedded.d.ts.map

package/dist/import/embedded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedded.d.ts","sourceRoot":"","sources":["../../src/import/embedded.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAmB,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAOjG,6HAA6H;AAC7H,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAwB3D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,QAAQ,EAAE,uBAAuB,GAChC,IAAI,CA2CN"}

package/dist/import/generator.d.ts

@@ -10,6 +10,8 @@ import type { TemplateIR } from "@intentius/chant/import/parser";
  * Generate TypeScript source code from a Kubernetes IR.
  */
 export declare class K8sGenerator implements TypeScriptGenerator {
+    /** The imports for embedded content the current `generate()` call references (#2962). */
+    private scope;
     generate(ir: TemplateIR): GeneratedFile[];
     /**
      * Resolve a K8s type name to a constructor class name.

package/dist/import/generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/import/generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAC5F,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,gCAAgC,CAAC;AAyF7E;;GAEG;AACH,qBAAa,YAAa,YAAW,mBAAmB;IACtD,QAAQ,CAAC,EAAE,EAAE,UAAU,GAAG,aAAa,EAAE;IA2CzC;;;OAGG;IACH,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,yBAAyB;IAmCjC,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,SAAS;IAyBjB,OAAO,CAAC,oBAAoB;IAuB5B,OAAO,CAAC,WAAW;CA4BpB"}
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/import/generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAC5F,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,gCAAgC,CAAC;AAqG7E;;GAEG;AACH,qBAAa,YAAa,YAAW,mBAAmB;IACtD,yFAAyF;IACzF,OAAO,CAAC,KAAK,CAA+B;IAE5C,QAAQ,CAAC,EAAE,EAAE,UAAU,GAAG,aAAa,EAAE;IAuDzC;;;OAGG;IACH,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,yBAAyB;IAmCjC,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,SAAS;IA0BjB,OAAO,CAAC,oBAAoB;IAuB5B,OAAO,CAAC,WAAW;CA6BpB"}

package/dist/import/parser.d.ts

@@ -5,7 +5,7 @@
  * TemplateIR format, mapping K8s resources to the K8s::{Group}::{Kind} type
  * convention.
  */
-import type { TemplateParser, TemplateIR } from "@intentius/chant/import/parser";
+import type { TemplateParser, TemplateIR, ParseContext } from "@intentius/chant/import/parser";
 /**
  * Kubernetes YAML parser implementation.
  *
@@ -13,7 +13,13 @@ import type { TemplateParser, TemplateIR } from "@intentius/chant/import/parser"
  * to be a standard Kubernetes object with apiVersion, kind, and metadata.
  */
 export declare class K8sParser implements TemplateParser {
-    parse(content: string): TemplateIR;
+    /**
+     * With `context.embedded` (`chant import`), content another lexicon owns
+     * is offered to it: every ConfigMap `data` value and a PrometheusRule's
+     * `spec.groups` (see ./embedded.ts). Without it, everything is kept as
+     * written.
+     */
+    parse(content: string, context?: ParseContext): TemplateIR;
     private parseDocument;
 }
 //# sourceMappingURL=parser.d.ts.map

package/dist/import/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/import/parser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAc,MAAM,gCAAgC,CAAC;AAyH7F;;;;;GAKG;AACH,qBAAa,SAAU,YAAW,cAAc;IAC9C,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;IAoClC,OAAO,CAAC,aAAa;CA8BtB"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/import/parser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAc,YAAY,EAAE,MAAM,gCAAgC,CAAC;AA2H3G;;;;;GAKG;AACH,qBAAa,SAAU,YAAW,cAAc;IAC9C;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,UAAU;IAoC1D,OAAO,CAAC,aAAa;CAgCtB"}

package/dist/import/testdata/embedded/fixtures.d.ts

@@ -0,0 +1,21 @@
+import { type ImportResult } from "@intentius/chant/cli/commands/import";
+export declare const pkgDir: string;
+export declare const repoRoot: string;
+export declare const read: (name: string) => string;
+export interface Imported {
+    result: ImportResult;
+    /** The project directory; the generated source is in `src/`. The caller removes it. */
+    dir: string;
+    srcDir: string;
+    /** Every generated file by its path under `src/`. */
+    files: Record<string, string>;
+}
+/**
+ * `chant import manifest.yaml --lexicon k8s` into a fresh project, or with
+ * `detect`, `chant import manifest.yaml` with the lexicon detected.
+ */
+export declare function importManifest(yaml: string, options?: {
+    detect?: boolean;
+}): Promise<Imported>;
+export declare function removeDir(dir: string): void;
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/import/testdata/embedded/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../../../src/import/testdata/embedded/fixtures.ts"],"names":[],"mappings":"AASA,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAExF,eAAO,MAAM,MAAM,QAA8C,CAAC;AAClE,eAAO,MAAM,QAAQ,QAA2B,CAAC;AACjD,eAAO,MAAM,IAAI,GAAI,MAAM,MAAM,WAA2D,CAAC;AAE7F,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,YAAY,CAAC;IACrB,uFAAuF;IACvF,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAUD;;;GAGG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAYxG;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE3C"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "9f1a030dc4c3e8445b98c0fd9bdb6187c0252d6cc392364bb5ce3ac1750bde08",
+    "manifest.json": "1a8204a45d432f44bf6760aff2619dba20707d1e4c2f5fcb1aea1d5aa53daf96",
     "meta.json": "8b999bc142f448b0b627ecdc9e2388bbe672c8a1f7aae5303135624cf2fe65e3",
     "types/index.d.ts": "5f67de738adb455805e72600948940af9c664283785fb68c9fd8f5ea90d42cc3",
     "rules/argo-appset-single-project.ts": "afa9f310753aa2d475f35012b13135b2dfaebed2a35d44edbe185ebc07673674",
@@ -69,5 +69,5 @@
     "skills/chant-k8s-argo.md": "24c9a85b78a2fc5c6657424baac9cc6d6caff6f47605b8146b2c0082133181cf",
     "skills/chant-k8s-flux.md": "9670efc2e9854bd14686b5adeb707396b9030a4dcaee6529b30abf56efe2c50c"
   },
-  "composite": "73356750d92da8d9fb98a6bcfbe0021c556ea16aa5559b2fa3c84b456fbb3e26"
+  "composite": "5680cfa0b7d42111693a68a763446b0351130e6050a629ddcbf9387075214303"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "k8s",
-  "version": "0.98.0",
+  "version": "0.99.0",
   "chantVersion": ">=0.1.0",
   "namespace": "K8s",
   "intrinsics": [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.98.0",
+  "version": "0.99.0",
   "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -78,7 +78,7 @@
     "@types/js-yaml": "^4.0.9"
   },
   "optionalDependencies": {
-    "@intentius/chant-k8s-client": "^0.98.0"
+    "@intentius/chant-k8s-client": "^0.99.0"
   },
   "devDependencies": {
     "@intentius/chant": "*",
@@ -86,7 +86,7 @@
   },
   "peerDependencies": {
     "zod": "^4.3.6",
-    "@intentius/chant": "^0.98.0",
+    "@intentius/chant": "^0.99.0",
     "typescript": "^5.9.3"
   }
 }

package/src/import/embedded-roundtrip.test.ts

@@ -0,0 +1,231 @@
+/**
+ * Embedded content through `chant import` (#2962): a manifest holding a
+ * collector config, rule groups or dashboard JSON imports as the owning
+ * lexicon's typed declarations, referenced from the k8s resource, and
+ * `chant build` gives back the same content.
+ *
+ * Fixtures (testdata/embedded/, provenance in its README.md): the
+ * opentelemetry-collector Helm chart's rendered daemonset-only example, the
+ * node-exporter PrometheusRule of kube-prometheus, a kube-prometheus
+ * dashboard ConfigMap with the Grafana sidecar label, and the k8s build
+ * output of examples/agent-observability.
+ *
+ * "The same" is per owner: a collector config equal as parsed YAML, rule
+ * groups equal as parsed YAML, a dashboard equal after the grafana lexicon's
+ * `normalizeDashboard` with its importer's edits applied (the grafana round
+ * trip's own measure). Content no lexicon claims must come back as the same
+ * text. embedded-types.e2e.test.ts type-checks the generated source.
+ */
+
+import { describe, expect, test } from "vitest";
+import { join } from "path";
+import { load, loadAll } from "js-yaml";
+import { build } from "@intentius/chant/build";
+import type { SerializerResult } from "@intentius/chant/serializer";
+import { lintCommand } from "@intentius/chant/cli/commands/lint";
+import { otelSerializer } from "@intentius/chant-lexicon-otel";
+import { prometheusSerializer } from "@intentius/chant-lexicon-prometheus";
+import { grafanaSerializer } from "@intentius/chant-lexicon-grafana";
+import { parseGrafana, type DashboardResourceMetadata } from "@intentius/chant-lexicon-grafana/import/parser";
+import { applyEdits } from "@intentius/chant-lexicon-grafana/import/edits";
+import { normalizeDashboard } from "@intentius/chant-lexicon-grafana/import/normalize";
+import { k8sSerializer } from "../serializer";
+import { importManifest, read, removeDir, type Imported } from "./testdata/embedded/fixtures";
+
+type Json = Record<string, unknown>;
+
+interface RoundTrip extends Imported {
+  /** The source manifest's documents. */
+  input: Json[];
+  /** The rebuilt k8s documents. */
+  output: Json[];
+  buildErrors: unknown[];
+}
+
+function primary(out: string | SerializerResult | undefined): string {
+  if (out === undefined) return "";
+  return typeof out === "string" ? out : out.primary;
+}
+
+async function roundTrip(fixture: string): Promise<RoundTrip> {
+  const yaml = read(fixture);
+  const imported = await importManifest(yaml);
+  try {
+    expect(imported.result.error).toBeUndefined();
+    expect(imported.result.success).toBe(true);
+    const result = await build(imported.srcDir, [k8sSerializer, otelSerializer, prometheusSerializer, grafanaSerializer]);
+    return {
+      ...imported,
+      input: (loadAll(yaml) as Json[]).filter((d) => d),
+      output: (loadAll(primary(result.outputs.get("k8s"))) as Json[]).filter((d) => d),
+      buildErrors: result.errors,
+    };
+  } finally {
+    removeDir(imported.dir);
+  }
+}
+
+function find(docs: Json[], kind: string, name: string): Json {
+  const doc = docs.find((d) => d.kind === kind && (d.metadata as Json | undefined)?.name === name);
+  if (!doc) throw new Error(`no ${kind} ${name}`);
+  return doc;
+}
+
+/** A collector config as the collector reads it: an empty component is `{}` whether written `{}` or left null. */
+function collectorConfig(text: string): Json {
+  const doc = (load(text) ?? {}) as Json;
+  for (const section of ["receivers", "processors", "exporters", "connectors", "extensions"]) {
+    const s = doc[section] as Json | undefined;
+    if (!s) continue;
+    for (const id of Object.keys(s)) if (s[id] === null) s[id] = {};
+  }
+  return doc;
+}
+
+/** A dashboard as the grafana round trip compares it: the importer's edits applied to the source, both normalized. */
+function dashboards(source: string, rebuilt: string): { expected: Json; actual: Json } {
+  const [resource] = parseGrafana(source).resources;
+  const meta = resource.metadata as unknown as DashboardResourceMetadata;
+  return {
+    expected: normalizeDashboard(applyEdits(meta.source as Json, meta.edits)),
+    actual: normalizeDashboard(JSON.parse(rebuilt) as Json),
+  };
+}
+
+/** The directories of the generated source holding an owner's modules. */
+function embeddedDirs(files: Record<string, string>): string[] {
+  return [...new Set(Object.keys(files).filter((p) => p.includes("/")).map((p) => p.split("/")[0]))].sort();
+}
+
+describe("manifest -> TypeScript -> manifest, with embedded content imported by its owner", () => {
+  test("a collector's ConfigMap becomes typed otel declarations, and the DaemonSet comes back whole", async () => {
+    const out = await roundTrip("otel-collector-daemonset.yaml");
+    expect(out.buildErrors).toEqual([]);
+    expect(out.result.warnings).toEqual([]);
+
+    const main = out.files["main.ts"];
+    expect(main).toContain('import { collectorYaml } from "@intentius/chant-lexicon-otel";');
+    expect(main).toMatch(/relay: collectorYaml\(\[\s+jaeger,/);
+    expect(main).toContain('from "./example-opentelemetry-collector-agent/receivers";');
+    expect(out.files["example-opentelemetry-collector-agent/receivers.ts"]).toContain("new OtlpReceiver(");
+    expect(out.files["example-opentelemetry-collector-agent/pipelines.ts"]).toContain("new Pipeline(");
+
+    const name = "example-opentelemetry-collector-agent";
+    const before = find(out.input, "ConfigMap", name).data as Json;
+    const after = find(out.output, "ConfigMap", name).data as Json;
+    expect(collectorConfig(after.relay as string)).toEqual(collectorConfig(before.relay as string));
+
+    // The whole DaemonSet comes back, pod template included. The chart renders
+    // `spec:` followed by a whitespace-only line, which core's YAML reader
+    // used to read as the end of the template's spec, moving its keys up to
+    // the DaemonSet's spec (#2991).
+    const daemonSet = find(out.output, "DaemonSet", name);
+    expect(daemonSet).toEqual(find(out.input, "DaemonSet", name));
+    const template = (daemonSet.spec as Json).template as Json;
+    expect((template.spec as Json).serviceAccountName).toBe("example-opentelemetry-collector");
+  });
+
+  test("a PrometheusRule's spec.groups become prometheus RuleGroups", async () => {
+    const out = await roundTrip("node-exporter-prometheusrule.yaml");
+    expect(out.buildErrors).toEqual([]);
+    expect(out.result.warnings).toEqual([]);
+
+    const main = out.files["main.ts"];
+    expect(main).toContain('from "./node-exporter-rules/rules";');
+    expect(main).toMatch(/groups: \[[\s\S]*nodeExporter/);
+    expect(out.files["node-exporter-rules/rules.ts"]).toContain("new RuleGroup(");
+
+    const before = find(out.input, "PrometheusRule", "node-exporter-rules");
+    const after = find(out.output, "PrometheusRule", "node-exporter-rules");
+    expect(after).toEqual(before);
+  });
+
+  test("a dashboard ConfigMap with the sidecar label becomes a grafana Dashboard", async () => {
+    const out = await roundTrip("grafana-dashboard-configmap.yaml");
+    expect(out.buildErrors).toEqual([]);
+
+    const main = out.files["main.ts"];
+    expect(main).toContain('import { dashboardJson } from "@intentius/chant-lexicon-grafana";');
+    expect(main).toMatch(/"alertmanager-overview\.json": dashboardJson\(\w+\)/);
+    expect(out.files["grafana-dashboard-alertmanager-overview/dashboard.ts"]).toContain("new Dashboard(");
+
+    const name = "grafana-dashboard-alertmanager-overview";
+    const before = find(out.input, "ConfigMap", name);
+    const after = find(out.output, "ConfigMap", name);
+    expect(after.metadata).toEqual(before.metadata);
+    const { expected, actual } = dashboards(
+      (before.data as Json)["alertmanager-overview.json"] as string,
+      (after.data as Json)["alertmanager-overview.json"] as string,
+    );
+    expect(actual).toEqual(expected);
+  });
+
+  test("examples/agent-observability's k8s output: every ConfigMap value comes back, the owned ones typed", async () => {
+    const out = await roundTrip("agent-observability.yaml");
+    expect(out.buildErrors).toEqual([]);
+    expect(embeddedDirs(out.files)).toEqual([
+      "grafana-dashboard-genai-agents",
+      "grafana-dashboard-red-traces-span-metrics",
+      "grafana-dashboard-slo-support-agent-runs",
+      "otel-agent-config",
+      "otel-gateway-config",
+      "prometheus-config-rules",
+    ]);
+    // The rule group an Slo() built comes back as that Slo, referenced by its rules.
+    expect(out.files["prometheus-config-rules/slos.ts"]).toContain("Slo(");
+    expect(Object.values(out.files).join("\n")).toMatch(/ruleFileYaml\(\[\w+\.rules\]\)/);
+
+    const configMaps = out.input.filter((d) => d.kind === "ConfigMap");
+    expect(configMaps.length).toBeGreaterThanOrEqual(7);
+    for (const before of configMaps) {
+      const name = (before.metadata as Json).name as string;
+      const after = find(out.output, "ConfigMap", name);
+      const data = before.data as Record<string, string>;
+      expect(Object.keys(after.data as Json).sort(), name).toEqual(Object.keys(data).sort());
+      for (const [key, text] of Object.entries(data)) {
+        const rebuilt = (after.data as Record<string, string>)[key];
+        const at = `${name} ${key}`;
+        if (key.endsWith(".json")) {
+          const { expected, actual } = dashboards(text, rebuilt);
+          expect(actual, at).toEqual(expected);
+        } else if (name.startsWith("otel-")) {
+          expect(collectorConfig(rebuilt), at).toEqual(collectorConfig(text));
+        } else {
+          expect(load(rebuilt), at).toEqual(load(text));
+        }
+      }
+    }
+  });
+
+  test("a detected manifest delegates the same way", async () => {
+    const imported = await importManifest(read("node-exporter-prometheusrule.yaml"), { detect: true });
+    try {
+      expect(imported.result.lexicon).toBe("k8s");
+      expect(imported.result.detected).toBe(true);
+      expect(imported.result.generatedFiles).toEqual(["main.ts", "node-exporter-rules/rules.ts"]);
+    } finally {
+      removeDir(imported.dir);
+    }
+  });
+
+  test("the owners' modules lint clean", async () => {
+    const yaml = [
+      read("otel-collector-daemonset.yaml"),
+      read("node-exporter-prometheusrule.yaml"),
+      read("grafana-dashboard-configmap.yaml"),
+    ].join("\n---\n");
+    const imported = await importManifest(yaml);
+    try {
+      const dirs = embeddedDirs(imported.files);
+      expect(dirs).toEqual(["example-opentelemetry-collector-agent", "grafana-dashboard-alertmanager-overview", "node-exporter-rules"]);
+      for (const dir of dirs) {
+        const lint = await lintCommand({ path: join(imported.srcDir, dir), format: "stylish" });
+        if (lint.errorCount + lint.warningCount > 0) console.log(lint.output);
+        expect(lint.errorCount, dir).toBe(0);
+        expect(lint.warningCount, dir).toBe(0);
+      }
+    } finally {
+      removeDir(imported.dir);
+    }
+  });
+});

package/src/import/embedded-types.e2e.test.ts

@@ -0,0 +1,43 @@
+/**
+ * What `chant import` generates for manifests with embedded content (#2962)
+ * type-checks: the k8s module that references the owners' declarations, and
+ * the owners' modules. Compiling takes longer than the unit-test budget
+ * allows, so this runs with the e2e tests.
+ */
+import { describe, expect, test } from "vitest";
+import { join } from "path";
+import * as ts from "typescript";
+import { importManifest, read, removeDir, repoRoot } from "./testdata/embedded/fixtures";
+
+/** Type errors in the generated files, compiled with the repo's compiler options. */
+function typeErrors(srcDir: string, paths: string[]): string[] {
+  const files = paths.map((p) => join(srcDir, p));
+  const configFile = ts.readConfigFile(join(repoRoot, "tsconfig.json"), ts.sys.readFile);
+  const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, repoRoot);
+  const program = ts.createProgram(files, { ...parsed.options, noEmit: true });
+  const real = (f: string) => ts.sys.realpath?.(f) ?? f;
+  const fileSet = new Set(files.map(real));
+  // A program that saw none of the files would pass vacuously.
+  expect(files.every((f) => program.getSourceFile(f) !== undefined)).toBe(true);
+  return ts
+    .getPreEmitDiagnostics(program)
+    .filter((d) => d.file && fileSet.has(real(d.file.fileName)))
+    .map((d) => `${real(d.file!.fileName).slice(real(srcDir).length + 1)}: ${ts.flattenDiagnosticMessageText(d.messageText, "\n")}`);
+}
+
+describe("the source generated for embedded content type-checks", () => {
+  test.each([
+    "otel-collector-daemonset.yaml",
+    "node-exporter-prometheusrule.yaml",
+    "grafana-dashboard-configmap.yaml",
+    "agent-observability.yaml",
+  ])("%s", async (fixture) => {
+    const imported = await importManifest(read(fixture));
+    try {
+      expect(imported.result.success).toBe(true);
+      expect(typeErrors(imported.srcDir, Object.keys(imported.files))).toEqual([]);
+    } finally {
+      removeDir(imported.dir);
+    }
+  }, 180_000);
+});

package/src/import/embedded.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, test } from "vitest";
+import { EmbeddedImports, type EmbeddedContent, type EmbeddedContentImporter } from "@intentius/chant/import/embedded";
+import { K8sParser } from "./parser";
+import { K8sGenerator } from "./generator";
+
+const MANIFEST = `
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: otel-agent
+  labels:
+    app.kubernetes.io/name: otel-agent
+data:
+  config.yaml: |
+    receivers:
+      otlp: {}
+    exporters:
+      debug: {}
+    service:
+      pipelines:
+        traces:
+          receivers: [otlp]
+          exporters: [debug]
+  plain.txt: just text
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: dashboards
+  labels:
+    grafana_dashboard: "1"
+data:
+  api.json: '{"title": "API", "panels": [], "schemaVersion": 41}'
+---
+apiVersion: monitoring.coreos.com/v1
+kind: PrometheusRule
+metadata:
+  name: api-rules
+spec:
+  groups:
+    - name: api
+      rules:
+        - alert: Down
+          expr: up == 0
+`;
+
+/** Claims every offered piece of content, recording it, as `fake.ts` exporting `thing`. */
+function claimAll(seen: EmbeddedContent[]): EmbeddedContentImporter {
+  return {
+    what: "anything",
+    matches: () => true,
+    import: (c) => {
+      seen.push(c);
+      return {
+        files: [{ path: "fake.ts", content: "const thing = 1;\n\nexport { thing };\n" }],
+        value: { bindings: [{ from: "fake.ts", name: "thing" }], shape: "single", through: { from: "@acme/fake", name: "render" } },
+      };
+    },
+  };
+}
+
+describe("k8s import offers embedded content (#2962)", () => {
+  test("without a resolver, everything is kept as written", () => {
+    const ir = new K8sParser().parse(MANIFEST);
+    expect((ir.resources[0].properties.data as Record<string, unknown>)["config.yaml"]).toContain("receivers:");
+  });
+
+  test("ConfigMap values that parse as documents, and a PrometheusRule's groups, are offered", () => {
+    const seen: EmbeddedContent[] = [];
+    const embedded = new EmbeddedImports([{ lexicon: "acme", importer: claimAll(seen) }]);
+    new K8sParser().parse(MANIFEST, { embedded });
+
+    // plain.txt is not a document and is not offered.
+    expect(seen.map((c) => [c.location, c.directory, c.select, c.expectedOwner?.lexicon])).toEqual([
+      ['ConfigMap otel-agent data["config.yaml"]', "otel-agent-config", undefined, "otel"],
+      ['ConfigMap dashboards data["api.json"]', "dashboards", undefined, "grafana"],
+      ["PrometheusRule api-rules spec.groups", "api-rules", "groups", "prometheus"],
+    ]);
+    expect(seen[1].labels).toEqual({ grafana_dashboard: "1" });
+    expect(seen[2].document).toEqual({ groups: [{ name: "api", rules: [{ alert: "Down", expr: "up == 0" }] }] });
+    expect(embedded.files.map((f) => f.path)).toEqual(["otel-agent-config/fake.ts", "dashboards/fake.ts", "api-rules/fake.ts"]);
+  });
+
+  test("the generator references what the owner declared, and quotes keys that are not identifiers", () => {
+    const embedded = new EmbeddedImports([{ lexicon: "acme", importer: claimAll([]) }]);
+    const ir = new K8sParser().parse(MANIFEST, { embedded });
+    const [main] = new K8sGenerator().generate(ir);
+    expect(main.content).toContain('import { render } from "@acme/fake";');
+    expect(main.content).toContain('import { thing } from "./otel-agent-config/fake";');
+    expect(main.content).toContain('import { thing as thing2 } from "./dashboards/fake";');
+    expect(main.content).toContain('"config.yaml": render(thing),');
+    expect(main.content).toContain('"api.json": render(thing2),');
+    expect(main.content).toContain("groups: render(thing3),");
+    expect(main.content).toContain('"plain.txt": "just text",');
+    expect(main.content).toContain('"app.kubernetes.io/name": "otel-agent",');
+  });
+
+  test("when no installed lexicon imports it, the content is kept and the expected owner is named", () => {
+    const embedded = new EmbeddedImports([]);
+    const ir = new K8sParser().parse(MANIFEST, { embedded });
+    expect((ir.resources[0].properties.data as Record<string, unknown>)["config.yaml"]).toContain("receivers:");
+    expect(embedded.warnings).toHaveLength(3);
+    expect(embedded.warnings[0]).toMatch(/^ConfigMap otel-agent data\["config.yaml"\] looks like an OpenTelemetry Collector config/);
+    expect(embedded.warnings[0]).toContain("@intentius/chant-lexicon-otel");
+    expect(embedded.warnings[1]).toContain("@intentius/chant-lexicon-grafana");
+    expect(embedded.warnings[2]).toContain("@intentius/chant-lexicon-prometheus");
+    const [main] = new K8sGenerator().generate(ir);
+    expect(main.content).not.toContain("import { render");
+  });
+});
+
+describe("the k8s generator's imports", () => {
+  test("a constructor named inside a string value is not imported", () => {
+    const ir = new K8sParser().parse(`
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: app
+data:
+  main.js: 'const x = new Widget("a");'
+`);
+    const [main] = new K8sGenerator().generate(ir);
+    expect(main.content.split("\n")[0]).toBe('import { ConfigMap } from "@intentius/chant-lexicon-k8s";');
+  });
+});

package/src/import/embedded.ts

@@ -0,0 +1,104 @@
+/**
+ * Where a Kubernetes manifest embeds another lexicon's content, for
+ * `chant import` (#2962).
+ *
+ * The parser offers two kinds of place to core's embedded-content resolver:
+ *
+ * - every `data` value of a ConfigMap, as text (a collector's `config.yaml`,
+ *   a Prometheus rule file, a Grafana dashboard's JSON);
+ * - a `monitoring.coreos.com` PrometheusRule's `spec.groups`, as the rule file
+ *   `{ groups }` those groups would make.
+ *
+ * Which lexicon imports the content is decided by core at run time, from the
+ * lexicons that register an `embeddedImporters()`; this module names none of
+ * them as a dependency. The `expectedOwner` hints below are the conventions
+ * k8s manifests follow, used only to warn when the owner is not installed.
+ */
+
+import type { EmbeddedContent, EmbeddedContentResolver } from "@intentius/chant/import/embedded";
+import { embeddedDocument } from "@intentius/chant/import/embedded";
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** The `grafana_dashboard` label the Grafana dashboard sidecar looks for (kube-prometheus-stack, the Grafana Helm chart). */
+export const GRAFANA_DASHBOARD_LABEL = "grafana_dashboard";
+
+function looksLikeRuleGroups(groups: unknown): boolean {
+  return Array.isArray(groups) && groups.length > 0 && groups.every((g) => isObject(g) && typeof g.name === "string" && Array.isArray(g.rules));
+}
+
+/** Whose content a ConfigMap value looks like, by the conventions manifests follow. */
+function hintFor(key: string, doc: unknown, labels: Record<string, string>): EmbeddedContent["expectedOwner"] {
+  if (!isObject(doc)) return undefined;
+  if (Array.isArray(doc.panels) && (GRAFANA_DASHBOARD_LABEL in labels || key.endsWith(".json"))) {
+    return { lexicon: "grafana", what: "a Grafana dashboard" };
+  }
+  if (isObject(doc.service) && isObject(doc.service.pipelines)) {
+    return { lexicon: "otel", what: "an OpenTelemetry Collector config" };
+  }
+  if (looksLikeRuleGroups(doc.groups)) return { lexicon: "prometheus", what: "a Prometheus rule file" };
+  return undefined;
+}
+
+function stringLabels(metadata: unknown): Record<string, string> {
+  const labels = isObject(metadata) && isObject(metadata.labels) ? metadata.labels : {};
+  return Object.fromEntries(Object.entries(labels).filter((e): e is [string, string] => typeof e[1] === "string"));
+}
+
+/**
+ * Offer the embedded content of one resource to `embedded`, replacing each
+ * value an owner imports with the reference it returns. `properties` is the
+ * resource's IR properties, changed in place (with fresh copies of the
+ * objects on the way down).
+ */
+export function delegateEmbedded(
+  type: string,
+  kind: string,
+  properties: Record<string, unknown>,
+  embedded: EmbeddedContentResolver,
+): void {
+  const metadata = properties.metadata;
+  const name = isObject(metadata) && typeof metadata.name === "string" ? metadata.name : kind.toLowerCase();
+  const labels = stringLabels(metadata);
+
+  if (type === "K8s::Core::ConfigMap" && isObject(properties.data)) {
+    const keys = Object.keys(properties.data);
+    const data: Record<string, unknown> = { ...properties.data };
+    for (const key of keys) {
+      const text = data[key];
+      if (typeof text !== "string") continue;
+      const doc = embeddedDocument(text);
+      if (!isObject(doc)) continue;
+      const ref = embedded.resolve({
+        host: "k8s",
+        hostType: type,
+        location: `ConfigMap ${name} data[${JSON.stringify(key)}]`,
+        directory: keys.length === 1 ? name : `${name}-${key.replace(/\.[^.]*$/, "")}`,
+        text,
+        document: doc,
+        labels,
+        expectedOwner: hintFor(key, doc, labels),
+      });
+      if (ref) data[key] = ref;
+    }
+    properties.data = data;
+    return;
+  }
+
+  if (type === "K8s::Monitoring::PrometheusRule" && isObject(properties.spec) && Array.isArray(properties.spec.groups)) {
+    const groups = properties.spec.groups;
+    const ref = embedded.resolve({
+      host: "k8s",
+      hostType: type,
+      location: `PrometheusRule ${name} spec.groups`,
+      directory: name,
+      document: { groups },
+      select: "groups",
+      labels,
+      expectedOwner: { lexicon: "prometheus", what: "Prometheus rule groups" },
+    });
+    if (ref) properties.spec = { ...properties.spec, groups: ref };
+  }
+}