@intentius/chant 0.1.7 → 0.1.9

package/src/state/snapshot.test.ts

@@ -0,0 +1,171 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import { createMockPlugin, staticDescribeResources, staticListArtifacts } from "@intentius/chant-test-utils";
+import type { BuildResult } from "../build";
+
+const writeSnapshotMock = vi.fn();
+const getHeadCommitMock = vi.fn();
+const pushStateMock = vi.fn();
+
+vi.mock("./git", () => ({
+  writeSnapshot: (...args: unknown[]) => writeSnapshotMock(...args),
+  getHeadCommit: () => getHeadCommitMock(),
+  pushState: () => pushStateMock(),
+}));
+
+const { takeSnapshot } = await import("./snapshot");
+
+function makeBuildResult(entitiesByLexicon: Record<string, string[]>): BuildResult {
+  const entities = new Map();
+  for (const [lexicon, names] of Object.entries(entitiesByLexicon)) {
+    for (const name of names) entities.set(name, { lexicon, entityType: `${lexicon}::Mock`, props: {} });
+  }
+  return {
+    outputs: new Map(Object.keys(entitiesByLexicon).map((l) => [l, "{}"])),
+    entities,
+    dependencies: new Map(),
+    errors: [],
+    warnings: [],
+    manifest: { lexicons: Object.keys(entitiesByLexicon), outputs: {}, deployOrder: [] },
+    sourceFileCount: 1,
+  } as unknown as BuildResult;
+}
+
+describe("takeSnapshot", () => {
+  beforeEach(() => {
+    writeSnapshotMock.mockReset();
+    getHeadCommitMock.mockReset();
+    pushStateMock.mockReset();
+    writeSnapshotMock.mockResolvedValue("commit-sha");
+    getHeadCommitMock.mockResolvedValue("head-sha");
+    pushStateMock.mockResolvedValue(true);
+  });
+
+  test("happy path: writes snapshot per plugin with describeResources", async () => {
+    const plugin = createMockPlugin({
+      name: "aws",
+      describeResources: staticDescribeResources({
+        bucket: { type: "AWS::S3::Bucket", status: "CREATE_COMPLETE", physicalId: "bucket-1" },
+      }),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["bucket"] }));
+    expect(result.snapshots).toHaveLength(1);
+    expect(result.snapshots[0]).toMatchObject({
+      lexicon: "aws",
+      environment: "prod",
+      commit: "head-sha",
+      resources: { bucket: { type: "AWS::S3::Bucket", status: "CREATE_COMPLETE" } },
+    });
+    expect(writeSnapshotMock).toHaveBeenCalledTimes(1);
+    expect(pushStateMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("plugin without describeResources is skipped", async () => {
+    const plugin = createMockPlugin({ name: "aws" });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["x"] }));
+    expect(result.snapshots).toEqual([]);
+    expect(writeSnapshotMock).not.toHaveBeenCalled();
+  });
+
+  test("plugin throws → captured as error, other plugins still proceed", async () => {
+    const broken = createMockPlugin({
+      name: "broken",
+      describeResources: async () => { throw new Error("boom"); },
+    });
+    const ok = createMockPlugin({
+      name: "ok",
+      describeResources: staticDescribeResources({ x: { type: "T", status: "OK" } }),
+    });
+    const result = await takeSnapshot("prod", [broken, ok], makeBuildResult({ broken: ["b"], ok: ["x"] }));
+    expect(result.errors.some((e) => e.includes("broken") && e.includes("boom"))).toBe(true);
+    expect(result.snapshots.map((s) => s.lexicon)).toEqual(["ok"]);
+  });
+
+  test("plugin returns no valid resources → error and no snapshot", async () => {
+    const plugin = createMockPlugin({
+      name: "aws",
+      describeResources: async () => ({}), // empty
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: [] }));
+    expect(result.snapshots).toEqual([]);
+    expect(result.errors.some((e) => e.includes("aws") && e.includes("no valid"))).toBe(true);
+  });
+
+  test("resources missing required type/status are dropped with warning", async () => {
+    const plugin = createMockPlugin({
+      name: "aws",
+      describeResources: staticDescribeResources({
+        valid:   { type: "T", status: "OK" },
+        bad:     { type: "", status: "OK" } as never,
+      }),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["valid"] }));
+    expect(result.snapshots[0].resources).toEqual({ valid: { type: "T", status: "OK" } });
+    expect(result.warnings.some((w) => w.includes("Dropped bad"))).toBe(true);
+  });
+
+  test("emits sensitive-data warnings for suspect attribute names", async () => {
+    const plugin = createMockPlugin({
+      name: "aws",
+      describeResources: staticDescribeResources({
+        cred: {
+          type: "T",
+          status: "OK",
+          attributes: { connectionString: "redacted", regularAttr: "x" },
+        },
+      }),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ aws: ["cred"] }));
+    expect(result.warnings.some((w) => w.toLowerCase().includes("sensitive"))).toBe(true);
+  });
+
+  // ── listArtifacts() integration (#51) ─────────────────────────────────────
+
+  test("calls listArtifacts when implemented and stores artifacts in snapshot", async () => {
+    const plugin = createMockPlugin({
+      name: "helm",
+      listArtifacts: staticListArtifacts({
+        "release/default/web": { type: "Helm::Release", physicalId: "default/web", status: "deployed" },
+      }),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ helm: [] }));
+    expect(result.snapshots).toHaveLength(1);
+    expect(result.snapshots[0].artifacts).toEqual({
+      "release/default/web": { type: "Helm::Release", physicalId: "default/web", status: "deployed" },
+    });
+    expect(result.snapshots[0].resources).toEqual({});
+  });
+
+  test("plugin can implement both describeResources and listArtifacts", async () => {
+    const plugin = createMockPlugin({
+      name: "k8s",
+      describeResources: staticDescribeResources({
+        web: { type: "K8s::Apps::Deployment", status: "READY" },
+      }),
+      listArtifacts: staticListArtifacts({
+        "release/default/proxy": { type: "Helm::Release", status: "deployed" },
+      }),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ k8s: ["web"] }));
+    expect(result.snapshots[0].resources).toEqual({
+      web: { type: "K8s::Apps::Deployment", status: "READY" },
+    });
+    expect(result.snapshots[0].artifacts).toBeDefined();
+    expect(result.snapshots[0].artifacts!["release/default/proxy"]).toBeDefined();
+  });
+
+  test("plugin with neither method is skipped (existing behavior preserved)", async () => {
+    const plugin = createMockPlugin({ name: "noop" });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ noop: ["x"] }));
+    expect(result.snapshots).toEqual([]);
+  });
+
+  test("listArtifacts only, empty result → error 'no valid resources or artifacts returned'", async () => {
+    const plugin = createMockPlugin({
+      name: "helm",
+      listArtifacts: async () => ({}),
+    });
+    const result = await takeSnapshot("prod", [plugin], makeBuildResult({ helm: [] }));
+    expect(result.errors.some((e) => e.includes("helm") && e.includes("no valid"))).toBe(true);
+    expect(result.snapshots).toEqual([]);
+  });
+});

package/src/state/snapshot.ts

@@ -2,7 +2,7 @@
  * Snapshot orchestration: queries plugins for deployed resource metadata,
  * assembles StateSnapshots, computes build digests, and writes to git.
  */
-import type { LexiconPlugin, ResourceMetadata } from "../lexicon";
+import type { LexiconPlugin, ResourceMetadata, ArtifactMetadata } from "../lexicon";
 import type { BuildResult } from "../build";
 import type { SerializerResult } from "../serializer";
 import type { StateSnapshot } from "./types";
@@ -95,7 +95,7 @@ export async function takeSnapshot(
   const digest = computeBuildDigest(buildResult);
 
   for (const plugin of plugins) {
-    if (!plugin.describeResources) continue;
+    if (!plugin.describeResources && !plugin.listArtifacts) continue;
 
     // Get serialized build output for this lexicon
     const rawOutput = buildResult.outputs.get(plugin.name);
@@ -106,33 +106,52 @@ export async function takeSnapshot(
           ? rawOutput
           : (rawOutput as SerializerResult).primary;
 
-    // Get entity names for this lexicon
+    // Get entity names + entity props for this lexicon
     const entityNames: string[] = [];
+    const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
     for (const [name, entity] of buildResult.entities) {
       if (entity.lexicon === plugin.name) {
         entityNames.push(name);
+        entities.set(name, {
+          entityType: entity.entityType,
+          props: ("props" in entity && entity.props != null
+            ? entity.props
+            : {}) as Record<string, unknown>,
+        });
       }
     }
 
-    try {
-      const resources = await plugin.describeResources({
-        environment,
-        buildOutput,
-        entityNames,
-      });
+    let resources: Record<string, ResourceMetadata> = {};
+    let artifacts: Record<string, ArtifactMetadata> = {};
 
-      const { valid, dropped, warnings: validationWarnings } =
-        validateResources(resources);
-      warnings.push(...validationWarnings);
+    try {
+      if (plugin.describeResources) {
+        const raw = await plugin.describeResources({
+          environment,
+          buildOutput,
+          entityNames,
+          entities,
+        });
+        const { valid, dropped, warnings: validationWarnings } = validateResources(raw);
+        warnings.push(...validationWarnings);
+        if (dropped.length > 0) {
+          warnings.push(`${plugin.name}: dropped ${dropped.length} invalid resource(s)`);
+        }
+        resources = valid;
+      }
 
-      if (dropped.length > 0) {
-        warnings.push(
-          `${plugin.name}: dropped ${dropped.length} invalid resource(s)`,
-        );
+      if (plugin.listArtifacts) {
+        const raw = await plugin.listArtifacts({ environment, entities });
+        const { valid, dropped, warnings: validationWarnings } = validateResources(raw);
+        warnings.push(...validationWarnings);
+        if (dropped.length > 0) {
+          warnings.push(`${plugin.name}: dropped ${dropped.length} invalid artifact(s)`);
+        }
+        artifacts = valid;
       }
 
-      if (Object.keys(valid).length === 0) {
-        errors.push(`${plugin.name}: no valid resources returned`);
+      if (Object.keys(resources).length === 0 && Object.keys(artifacts).length === 0) {
+        errors.push(`${plugin.name}: no valid resources or artifacts returned`);
         continue;
       }
 
@@ -141,7 +160,8 @@ export async function takeSnapshot(
         environment,
         commit: headCommit,
         timestamp,
-        resources: valid,
+        resources,
+        ...(Object.keys(artifacts).length > 0 && { artifacts }),
         digest,
       };
 

package/src/state/types.ts

@@ -1,6 +1,6 @@
-import type { ResourceMetadata } from "../lexicon";
+import type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
 
-export type { ResourceMetadata } from "../lexicon";
+export type { ResourceMetadata, ArtifactMetadata } from "../lexicon";
 
 /**
  * State snapshot for a single lexicon in an environment.
@@ -14,6 +14,8 @@ export interface StateSnapshot {
   timestamp: string;
   /** Resource metadata keyed by logical name */
   resources: Record<string, ResourceMetadata>;
+  /** Artifact metadata keyed by server-side identifier (lexicon-specific). */
+  artifacts?: Record<string, ArtifactMetadata>;
   /** Build digest at snapshot time — what was declared when this snapshot was taken */
   digest?: BuildDigest;
 }