@intentius/chant-lexicon-k8s 0.1.14 → 0.1.15

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

@@ -28,6 +28,9 @@ import { wk8306 } from "./wk8306";
 import { wk8401 } from "./wk8401";
 import { wk8402 } from "./wk8402";
 import { wk8403 } from "./wk8403";
+import { argo002 } from "./argo002";
+import { argo003 } from "./argo003";
+import { argo005 } from "./argo005";
 
 function makeCtx(yaml: string): PostSynthContext {
   return {
@@ -43,6 +46,11 @@ function makeCtx(yaml: string): PostSynthContext {
   };
 }
 
+/** Join several manifests (objects) into a multi-document YAML string. */
+function manifestsCtx(...objs: unknown[]): PostSynthContext {
+  return makeCtx(objs.map((o) => JSON.stringify(o)).join("\n---\n"));
+}
+
 // ── WK8005: Secrets in env ──────────────────────────────────────────
 // Note: Tests with nested container properties (env, resources, securityContext,
 // ports, probes) use JSON format because the core parseYAML line-based parser
@@ -1476,3 +1484,118 @@ describe("WK8403: spec.rayVersion does not match image tag", () => {
     expect(diags.filter((d) => d.checkId === "WK8403").length).toBe(0);
   });
 });
+
+// ── ARGO002: Application.spec.project references a declared AppProject ─────────
+
+function argoApp(name: string, spec: Record<string, unknown>) {
+  return { apiVersion: "argoproj.io/v1alpha1", kind: "Application", metadata: { name }, spec };
+}
+function appProject(name: string) {
+  return { apiVersion: "argoproj.io/v1alpha1", kind: "AppProject", metadata: { name }, spec: {} };
+}
+const inClusterDest = { server: "https://kubernetes.default.svc", namespace: "demo" };
+
+describe("ARGO002: Application project references a declared AppProject", () => {
+  test("metadata", () => {
+    expect(argo002.id).toBe("ARGO002");
+  });
+
+  test("flags an Application referencing an undeclared project", () => {
+    const ctx = manifestsCtx(argoApp("api", { project: "team-a", destination: inClusterDest }));
+    const diags = argo002.check(ctx);
+    expect(diags.length).toBe(1);
+    expect(diags[0].checkId).toBe("ARGO002");
+    expect(diags[0].message).toContain("team-a");
+  });
+
+  test("passes when the AppProject is declared in the same build", () => {
+    const ctx = manifestsCtx(
+      appProject("team-a"),
+      argoApp("api", { project: "team-a", destination: inClusterDest }),
+    );
+    expect(argo002.check(ctx).length).toBe(0);
+  });
+
+  test("does NOT flag the built-in default project", () => {
+    const ctx = manifestsCtx(argoApp("api", { project: "default", destination: inClusterDest }));
+    expect(argo002.check(ctx).length).toBe(0);
+  });
+});
+
+// ── ARGO003: Application destination references a registered cluster ──────────
+
+function clusterSecret(name: string, server: string) {
+  return {
+    apiVersion: "v1",
+    kind: "Secret",
+    metadata: { name, labels: { "argocd.argoproj.io/secret-type": "cluster" } },
+    stringData: { name, server },
+  };
+}
+
+describe("ARGO003: Application destination references a registered cluster", () => {
+  test("metadata", () => {
+    expect(argo003.id).toBe("ARGO003");
+  });
+
+  test("does NOT flag the in-cluster destination", () => {
+    const ctx = manifestsCtx(argoApp("api", { project: "default", destination: inClusterDest }));
+    expect(argo003.check(ctx).length).toBe(0);
+  });
+
+  test("flags an unregistered cluster server", () => {
+    const ctx = manifestsCtx(
+      argoApp("api", { project: "default", destination: { server: "https://prod.example.com", namespace: "demo" } }),
+    );
+    const diags = argo003.check(ctx);
+    expect(diags.length).toBe(1);
+    expect(diags[0].checkId).toBe("ARGO003");
+    expect(diags[0].message).toContain("prod.example.com");
+  });
+
+  test("passes when the cluster is registered via a cluster Secret", () => {
+    const ctx = manifestsCtx(
+      clusterSecret("prod", "https://prod.example.com"),
+      argoApp("api", { project: "default", destination: { server: "https://prod.example.com", namespace: "demo" } }),
+    );
+    expect(argo003.check(ctx).length).toBe(0);
+  });
+
+  test("flags a destination with neither server nor name", () => {
+    const ctx = manifestsCtx(argoApp("api", { project: "default", destination: { namespace: "demo" } }));
+    expect(argo003.check(ctx).length).toBe(1);
+  });
+});
+
+// ── ARGO005: Application source.path resolves to an existing directory ────────
+
+describe("ARGO005: Application source path exists", () => {
+  test("metadata", () => {
+    expect(argo005.id).toBe("ARGO005");
+  });
+
+  test("does NOT flag a path that exists under the build root", () => {
+    // `lexicons` is a directory at the repo root (the vitest cwd).
+    const ctx = manifestsCtx(
+      argoApp("api", { project: "default", destination: inClusterDest, source: { repoURL: "x", path: "lexicons" } }),
+    );
+    expect(argo005.check(ctx).length).toBe(0);
+  });
+
+  test("warns on a path that does not resolve to a directory", () => {
+    const ctx = manifestsCtx(
+      argoApp("api", { project: "default", destination: inClusterDest, source: { repoURL: "x", path: "no-such-argo-dir-xyz" } }),
+    );
+    const diags = argo005.check(ctx);
+    expect(diags.length).toBe(1);
+    expect(diags[0].checkId).toBe("ARGO005");
+    expect(diags[0].severity).toBe("warning");
+  });
+
+  test("skips Helm chart sources", () => {
+    const ctx = manifestsCtx(
+      argoApp("api", { project: "default", destination: inClusterDest, source: { repoURL: "x", chart: "redis" } }),
+    );
+    expect(argo005.check(ctx).length).toBe(0);
+  });
+});

package/src/lint/rules/argo-appset-single-project.ts

@@ -0,0 +1,66 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import { findResourceLiterals, getNestedObject, getNestedString, lineCol } from "./argo-ast";
+
+/**
+ * ARGO004: ApplicationSet template must scope to a single AppProject
+ *
+ * An `ApplicationSet` generates many Applications from one template. The
+ * template's `spec.project` should name a single, static `AppProject` so every
+ * generated Application lands in the same security boundary. If `project` is
+ * missing, the generated Applications fall back to whatever default and dodge
+ * project-level RBAC; if it is templated with a generator placeholder
+ * (`{{...}}`) the set sprays Applications across many projects, which defeats
+ * the point of an AppProject as a guardrail.
+ *
+ * Bad:  new ApplicationSet({ spec: { template: { spec: { repoURL: "..." } } } })          // no project
+ * Bad:  new ApplicationSet({ spec: { template: { spec: { project: "{{path.basename}}" } } } }) // templated
+ * Good: new ApplicationSet({ spec: { template: { spec: { project: "team-a" } } } })
+ */
+
+export const argoAppSetSingleProjectRule: LintRule = {
+  id: "ARGO004",
+  severity: "warning",
+  category: "correctness",
+  description:
+    "ApplicationSet template must scope to a single static AppProject (spec.template.spec.project)",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    for (const { literal } of findResourceLiterals(sourceFile, new Set(["ApplicationSet"]))) {
+      const templateSpec = getNestedObject(literal, ["spec", "template", "spec"]);
+      // No template/spec to inspect — leave it to other tooling.
+      if (!templateSpec) continue;
+
+      const project = getNestedString(literal, ["spec", "template", "spec", "project"]);
+      const { line, column } = lineCol(sourceFile, templateSpec);
+
+      if (project === undefined) {
+        diagnostics.push({
+          file: sourceFile.fileName,
+          line,
+          column,
+          ruleId: "ARGO004",
+          severity: "warning",
+          message:
+            "ApplicationSet template has no spec.project — scope it to a single AppProject so every generated Application inherits the same RBAC boundary.",
+        });
+        continue;
+      }
+
+      if (project.includes("{{")) {
+        diagnostics.push({
+          file: sourceFile.fileName,
+          line,
+          column,
+          ruleId: "ARGO004",
+          severity: "warning",
+          message: `ApplicationSet template scopes spec.project to a generator placeholder ("${project}"), spraying Applications across projects. Pin it to a single static AppProject.`,
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/rules/argo-ast.ts

@@ -0,0 +1,121 @@
+/**
+ * Shared AST helpers for the Argo declarative lint rules (ARGO001, ARGO004).
+ *
+ * The Argo CRDs are constructed like any other k8s resource —
+ * `new Application({ metadata, spec })` / `new ApplicationSet({ ... })`. These
+ * helpers walk the object-literal first argument so a rule can read a nested
+ * property by path without re-implementing the traversal each time.
+ */
+import * as ts from "typescript";
+
+/**
+ * Find the object-literal first argument of every `new <Kind>(...)` expression
+ * in the file, where Kind is one of the supplied resource kinds.
+ */
+export function findResourceLiterals(
+  sourceFile: ts.SourceFile,
+  kinds: Set<string>,
+): Array<{ kind: string; literal: ts.ObjectLiteralExpression; node: ts.NewExpression }> {
+  const found: Array<{ kind: string; literal: ts.ObjectLiteralExpression; node: ts.NewExpression }> = [];
+
+  function visit(node: ts.Node): void {
+    if (
+      ts.isNewExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      kinds.has(node.expression.text) &&
+      node.arguments &&
+      node.arguments.length > 0 &&
+      ts.isObjectLiteralExpression(node.arguments[0])
+    ) {
+      found.push({
+        kind: node.expression.text,
+        literal: node.arguments[0],
+        node,
+      });
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return found;
+}
+
+/** Read the initializer node for `key` on an object literal, if present. */
+export function getProp(
+  obj: ts.ObjectLiteralExpression,
+  key: string,
+): ts.Expression | undefined {
+  for (const prop of obj.properties) {
+    if (
+      ts.isPropertyAssignment(prop) &&
+      (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) &&
+      prop.name.text === key
+    ) {
+      return prop.initializer;
+    }
+  }
+  return undefined;
+}
+
+/** Read a nested object literal by walking `path` (each segment an object). */
+export function getNestedObject(
+  obj: ts.ObjectLiteralExpression,
+  path: string[],
+): ts.ObjectLiteralExpression | undefined {
+  let current: ts.ObjectLiteralExpression | undefined = obj;
+  for (const segment of path) {
+    if (!current) return undefined;
+    const next = getProp(current, segment);
+    current = next && ts.isObjectLiteralExpression(next) ? next : undefined;
+  }
+  return current;
+}
+
+/** Read a string-literal property value by path (last segment is the key). */
+export function getNestedString(
+  obj: ts.ObjectLiteralExpression,
+  path: string[],
+): string | undefined {
+  const key = path[path.length - 1];
+  const parent = getNestedObject(obj, path.slice(0, -1));
+  if (!parent) return undefined;
+  const value = getProp(parent, key);
+  return value && ts.isStringLiteral(value) ? value.text : undefined;
+}
+
+/** Read a boolean-literal property value by path (last segment is the key). */
+export function getNestedBoolean(
+  obj: ts.ObjectLiteralExpression,
+  path: string[],
+): boolean | undefined {
+  const key = path[path.length - 1];
+  const parent = getNestedObject(obj, path.slice(0, -1));
+  if (!parent) return undefined;
+  const value = getProp(parent, key);
+  if (!value) return undefined;
+  if (value.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (value.kind === ts.SyntaxKind.FalseKeyword) return false;
+  return undefined;
+}
+
+/**
+ * True if the literal carries the given annotation key under
+ * `metadata.annotations`, regardless of value.
+ */
+export function hasAnnotation(
+  obj: ts.ObjectLiteralExpression,
+  annotationKey: string,
+): boolean {
+  const annotations = getNestedObject(obj, ["metadata", "annotations"]);
+  if (!annotations) return false;
+  return getProp(annotations, annotationKey) !== undefined;
+}
+
+/** Line/column (1-based) for a node, for diagnostics. */
+export function lineCol(
+  sourceFile: ts.SourceFile,
+  node: ts.Node,
+): { line: number; column: number } {
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+  return { line: line + 1, column: character + 1 };
+}

package/src/lint/rules/argo-automated-prune.ts

@@ -0,0 +1,75 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import {
+  findResourceLiterals,
+  getNestedBoolean,
+  getNestedString,
+  getProp,
+  hasAnnotation,
+  lineCol,
+} from "./argo-ast";
+import * as ts from "typescript";
+
+/**
+ * ARGO001: Production Application must not enable automated prune
+ *
+ * An Argo CD `Application` whose `syncPolicy.automated.prune` is `true` lets the
+ * controller delete live resources that disappear from git. On a production
+ * Application that is a foot-gun — a bad merge can sweep away running
+ * infrastructure. Require `prune: false` for prod Applications unless the author
+ * opts in explicitly with the `argocd.chant.dev/allow-prune` annotation.
+ *
+ * "Production" is inferred from the Application name, its `metadata.namespace`,
+ * or its `spec.destination.namespace` containing `prod`.
+ *
+ * Bad:  new Application({ metadata: { name: "api-prod" }, spec: { syncPolicy: { automated: { prune: true } } } })
+ * Good: new Application({ metadata: { name: "api-prod" }, spec: { syncPolicy: { automated: { prune: false } } } })
+ * Good: new Application({ metadata: { name: "api-prod", annotations: { "argocd.chant.dev/allow-prune": "true" } }, spec: { syncPolicy: { automated: { prune: true } } } })
+ */
+
+export const ALLOW_PRUNE_ANNOTATION = "argocd.chant.dev/allow-prune";
+
+function looksProd(obj: ts.ObjectLiteralExpression): boolean {
+  const candidates = [
+    getNestedString(obj, ["metadata", "name"]),
+    getNestedString(obj, ["metadata", "namespace"]),
+    getNestedString(obj, ["spec", "destination", "namespace"]),
+  ];
+  return candidates.some((v) => v !== undefined && /prod/i.test(v));
+}
+
+export const argoAutomatedPruneRule: LintRule = {
+  id: "ARGO001",
+  severity: "warning",
+  category: "correctness",
+  description:
+    "Production Argo Application must not enable syncPolicy.automated.prune without the allow-prune override annotation",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    for (const { literal } of findResourceLiterals(sourceFile, new Set(["Application"]))) {
+      const prune = getNestedBoolean(literal, ["spec", "syncPolicy", "automated", "prune"]);
+      if (prune !== true) continue;
+      if (!looksProd(literal)) continue;
+      if (hasAnnotation(literal, ALLOW_PRUNE_ANNOTATION)) continue;
+
+      // Anchor the diagnostic at the `prune` assignment when we can find it.
+      const automated = getProp(literal, "spec");
+      const anchor: ts.Node = automated ?? literal;
+      const { line, column } = lineCol(sourceFile, anchor);
+
+      const name = getNestedString(literal, ["metadata", "name"]) ?? "(unnamed)";
+      diagnostics.push({
+        file: sourceFile.fileName,
+        line,
+        column,
+        ruleId: "ARGO001",
+        severity: "warning",
+        message: `Production Application "${name}" enables automated prune. Set syncPolicy.automated.prune=false, or opt in explicitly with the "${ALLOW_PRUNE_ANNOTATION}" annotation.`,
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/rules/rules.test.ts

@@ -2,6 +2,8 @@ import { describe, test, expect } from "vitest";
 import { hardcodedNamespaceRule } from "./hardcoded-namespace";
 import { latestImageTagRule } from "./latest-image-tag";
 import { missingResourceLimitsRule } from "./missing-resource-limits";
+import { argoAutomatedPruneRule } from "./argo-automated-prune";
+import { argoAppSetSingleProjectRule } from "./argo-appset-single-project";
 import * as ts from "typescript";
 
 function createContext(code: string) {
@@ -259,3 +261,110 @@ describe("WK8003: Missing Resource Limits", () => {
     expect(diags.length).toBe(2);
   });
 });
+
+describe("ARGO001: Production Application automated prune", () => {
+  test("rule metadata", () => {
+    expect(argoAutomatedPruneRule.id).toBe("ARGO001");
+    expect(argoAutomatedPruneRule.severity).toBe("warning");
+    expect(argoAutomatedPruneRule.category).toBe("correctness");
+  });
+
+  test("flags prod Application with automated prune and no override", () => {
+    const ctx = createContext(`
+      new Application({
+        metadata: { name: "api-prod" },
+        spec: { syncPolicy: { automated: { prune: true, selfHeal: true } } },
+      });
+    `);
+    const diags = argoAutomatedPruneRule.check(ctx);
+    expect(diags.length).toBe(1);
+    expect(diags[0].ruleId).toBe("ARGO001");
+    expect(diags[0].message).toContain("api-prod");
+  });
+
+  test("does NOT flag when prune is false", () => {
+    const ctx = createContext(`
+      new Application({
+        metadata: { name: "api-prod" },
+        spec: { syncPolicy: { automated: { prune: false } } },
+      });
+    `);
+    expect(argoAutomatedPruneRule.check(ctx).length).toBe(0);
+  });
+
+  test("does NOT flag prod Application carrying the allow-prune override annotation", () => {
+    const ctx = createContext(`
+      new Application({
+        metadata: { name: "api-prod", annotations: { "argocd.chant.dev/allow-prune": "true" } },
+        spec: { syncPolicy: { automated: { prune: true } } },
+      });
+    `);
+    expect(argoAutomatedPruneRule.check(ctx).length).toBe(0);
+  });
+
+  test("does NOT flag a non-prod Application with automated prune", () => {
+    const ctx = createContext(`
+      new Application({
+        metadata: { name: "api-staging" },
+        spec: { syncPolicy: { automated: { prune: true } } },
+      });
+    `);
+    expect(argoAutomatedPruneRule.check(ctx).length).toBe(0);
+  });
+
+  test("infers prod from destination namespace", () => {
+    const ctx = createContext(`
+      new Application({
+        metadata: { name: "api" },
+        spec: {
+          destination: { namespace: "production" },
+          syncPolicy: { automated: { prune: true } },
+        },
+      });
+    `);
+    expect(argoAutomatedPruneRule.check(ctx).length).toBe(1);
+  });
+});
+
+describe("ARGO004: ApplicationSet single AppProject", () => {
+  test("rule metadata", () => {
+    expect(argoAppSetSingleProjectRule.id).toBe("ARGO004");
+    expect(argoAppSetSingleProjectRule.severity).toBe("warning");
+    expect(argoAppSetSingleProjectRule.category).toBe("correctness");
+  });
+
+  test("does NOT flag a static single project", () => {
+    const ctx = createContext(`
+      new ApplicationSet({
+        metadata: { name: "team-a-apps" },
+        spec: { template: { spec: { project: "team-a", repoURL: "https://example.com/repo" } } },
+      });
+    `);
+    expect(argoAppSetSingleProjectRule.check(ctx).length).toBe(0);
+  });
+
+  test("flags a missing template project", () => {
+    const ctx = createContext(`
+      new ApplicationSet({
+        metadata: { name: "team-a-apps" },
+        spec: { template: { spec: { repoURL: "https://example.com/repo" } } },
+      });
+    `);
+    const diags = argoAppSetSingleProjectRule.check(ctx);
+    expect(diags.length).toBe(1);
+    expect(diags[0].ruleId).toBe("ARGO004");
+    expect(diags[0].message).toContain("no spec.project");
+  });
+
+  test("flags a templated (generator placeholder) project", () => {
+    const ctx = createContext(`
+      new ApplicationSet({
+        metadata: { name: "per-cluster" },
+        spec: { template: { spec: { project: "{{path.basename}}" } } },
+      });
+    `);
+    const diags = argoAppSetSingleProjectRule.check(ctx);
+    expect(diags.length).toBe(1);
+    expect(diags[0].message).toContain("placeholder");
+  });
+});

package/src/plugin.test.ts

@@ -33,7 +33,12 @@ describe("k8sPlugin", () => {
   test("postSynthChecks() returns array of post-synth checks", () => {
     const checks = k8sPlugin.postSynthChecks!();
     expect(Array.isArray(checks)).toBe(true);
-    expect(checks.length).toBe(26);
+    // Auto-discovered from src/lint/post-synth — assert a floor and representative
+    // IDs rather than an exact count, so adding a check doesn't break this test.
+    expect(checks.length).toBeGreaterThanOrEqual(26);
+    const ids = checks.map((c) => c.id);
+    expect(ids).toContain("WK8101");
+    expect(ids).toContain("ARGO002");
   });
 
   test("intrinsics() returns empty array", () => {

package/src/plugin.ts

@@ -15,6 +15,8 @@ import { k8sSerializer } from "./serializer";
 import { hardcodedNamespaceRule } from "./lint/rules/hardcoded-namespace";
 import { latestImageTagRule } from "./lint/rules/latest-image-tag";
 import { missingResourceLimitsRule } from "./lint/rules/missing-resource-limits";
+import { argoAutomatedPruneRule } from "./lint/rules/argo-automated-prune";
+import { argoAppSetSingleProjectRule } from "./lint/rules/argo-appset-single-project";
 import { k8sCompletions } from "./lsp/completions";
 import { k8sHover } from "./lsp/hover";
 import { K8sParser } from "./import/parser";
@@ -25,7 +27,13 @@ export const k8sPlugin: LexiconPlugin = {
   serializer: k8sSerializer,
 
   lintRules(): LintRule[] {
-    return [hardcodedNamespaceRule, latestImageTagRule, missingResourceLimitsRule];
+    return [
+      hardcodedNamespaceRule,
+      latestImageTagRule,
+      missingResourceLimitsRule,
+      argoAutomatedPruneRule,
+      argoAppSetSingleProjectRule,
+    ];
   },
 
   postSynthChecks() {
@@ -566,10 +574,45 @@ const { deployment, service, serviceMonitor, prometheusRule } = MonitoredService
           },
         ],
       },
+      {
+        file: "chant-k8s-argo.md",
+        name: "chant-k8s-argo",
+        description: "Argo CD composites — ArgoAppFor, ArgoAppSetForRegions, AppProject scoping, cluster registration, and the Argo-vs-Temporal split",
+        triggers: [
+          { type: "context", value: "argo" },
+          { type: "context", value: "argo cd" },
+          { type: "context", value: "argocd" },
+          { type: "context", value: "gitops" },
+          { type: "context", value: "application" },
+          { type: "context", value: "applicationset" },
+          { type: "context", value: "appproject" },
+          { type: "context", value: "reconcile" },
+        ],
+        parameters: [],
+        examples: [
+          {
+            title: "Application from a build target",
+            description: "Reconcile a Chant build target with Argo CD",
+            input: "Deploy my api target through Argo CD",
+            output: "import { ArgoAppFor } from \"@intentius/chant-lexicon-k8s\";\n\nexport const api = ArgoAppFor(\"api\", {\n  repo: \"https://github.com/acme/infra\",\n  path: \"dist/api\",\n  destination: { server: \"https://kubernetes.default.svc\", namespace: \"api\" },\n});",
+          },
+          {
+            title: "Per-region ApplicationSet",
+            description: "Fan one app out across regional clusters",
+            input: "Deploy crdb to east, central, and west clusters via Argo",
+            output: "import { ArgoAppSetForRegions } from \"@intentius/chant-lexicon-k8s\";\n\nexport const crdb = ArgoAppSetForRegions(\n  [\"east\", \"central\", \"west\"],\n  (region) => ({ server: servers[region], namespace: `crdb-${region}`, path: `dist/${region}` }),\n  { name: \"crdb\", repo: \"https://github.com/acme/infra\", project: \"crdb\" },\n);",
+          },
+        ],
+      },
     ]),
 
   async describeResources(options) {
     const { describeResources } = await import("./describe-resources");
     return describeResources(options);
   },
+
+  async exportResources(options) {
+    const { exportResources } = await import("./export-resources");
+    return exportResources(options);
+  },
 };

package/src/serializer-ownership.test.ts

@@ -0,0 +1,44 @@
+import { describe, test, expect } from "vitest";
+import { k8sSerializer } from "./serializer";
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+
+function mockResource(entityType: string, props: Record<string, unknown>): any {
+  return { [DECLARABLE_MARKER]: true, lexicon: "k8s", entityType, kind: "resource", props };
+}
+
+describe("k8sSerializer ownership stamping (#119)", () => {
+  test("stamps the ownership marker as labels when context.ownership is set", () => {
+    const entities = new Map<string, any>([
+      ["web", mockResource("K8s::Apps::Deployment", { metadata: { name: "web" }, spec: { replicas: 1 } })],
+    ]);
+    const yaml = k8sSerializer.serialize(entities, [], { ownership: { stack: "billing", env: "prod" } });
+    expect(yaml).toContain("app.kubernetes.io/managed-by: chant");
+    expect(yaml).toContain("chant.intentius.io/stack: billing");
+    expect(yaml).toContain("chant.intentius.io/env: prod");
+  });
+
+  test("explicit resource labels still win over the stamped marker", () => {
+    const entities = new Map<string, any>([
+      [
+        "web",
+        mockResource("K8s::Apps::Deployment", {
+          metadata: { name: "web", labels: { "app.kubernetes.io/managed-by": "argocd" } },
+          spec: { replicas: 1 },
+        }),
+      ],
+    ]);
+    const yaml = k8sSerializer.serialize(entities, [], { ownership: { stack: "billing" } });
+    expect(yaml).toContain("app.kubernetes.io/managed-by: argocd");
+    // stack identity still stamped (no explicit override)
+    expect(yaml).toContain("chant.intentius.io/stack: billing");
+  });
+
+  test("no ownership context → no chant labels", () => {
+    const entities = new Map<string, any>([
+      ["web", mockResource("K8s::Apps::Deployment", { metadata: { name: "web" }, spec: { replicas: 1 } })],
+    ]);
+    const yaml = k8sSerializer.serialize(entities, []);
+    expect(yaml).not.toContain("app.kubernetes.io/managed-by: chant");
+    expect(yaml).not.toContain("chant.intentius.io/stack");
+  });
+});