@intentius/chant-lexicon-aws 0.27.0 → 0.29.0

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "9deee69f09d9cec4b892b1bb97a0dad9b3354bc794cab5acad4d6fa237a0a396",
+    "manifest.json": "eac9b0bddda5b4b10352c04ef292ce7f707f72d7b9fe74a06426331963c8c8c8",
     "meta.json": "8d6445b7ea5f7803c83cf49daab639b1df66388c1512f466b888b0ad57f60a9a",
     "types/index.d.ts": "da899ff303a18a7fdb270570bce784703283d4081f806e69ac8c9dfd4bac7c50",
     "rules/hardcoded-region.ts": "5a0eaf7ab391231fe6cd51426ece29539cb4b36f31c8dd060956638fed55722a",
@@ -59,5 +59,5 @@
     "skills/chant-aws-eks.md": "8789255709ff004ad0a875fd5999edcdc66fc6e33d710db058d9f42703bcfdfe",
     "skills/chant-aws-carve-terraform.md": "f4c6fe1c702250665f90d82b3bdaba5ea50ae75e380a8ae321dad6eb1c39683e"
   },
-  "composite": "60753f891c32263de6e6c9116b8acef09ddcc19d0fd93472d2008aec80052cfe"
+  "composite": "46d41420d193e652b241c1388259670efee2423e1a8026507cd1fd5b2d5175a4"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "aws",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "chantVersion": ">=0.1.0",
   "namespace": "AWS",
   "intrinsics": [

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAA+G,MAAM,0BAA0B,CAAC;AAwB3K;;sFAEsF;AACtF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,aAkxBvB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAkI,MAAM,0BAA0B,CAAC;AAwB9L;;sFAEsF;AACtF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,aAyyBvB,CAAC"}

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AAiYlG;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UAoE3B,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AA0YlG;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UAoE3B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-aws",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "AWS CloudFormation lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -80,7 +80,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.27.0",
+    "@intentius/chant": "^0.29.0",
     "typescript": "^5.9.3"
   }
 }

package/src/import/live-export-io.test.ts

@@ -2,10 +2,18 @@ import { describe, test, expect, vi, beforeEach } from "vitest";
 
 // AWS exportResources reaches the cloud through the runtime adapter's spawn
 // (not node:child_process), so the I/O seam is the runtime-adapter module.
+// Partial mock (`importOriginal`) rather than a full replacement: this module
+// is reachable — via `@intentius/chant`'s own root barrel, not just this
+// test's direct imports — from other real exports the plugin/import path
+// touches (e.g. `moduleDir`, which `../../lint/config.ts` calls at module
+// scope), so replacing the whole module wholesale breaks anything that
+// transitively loads one of those, for reasons entirely unrelated to what
+// this test is mocking (`spawn`).
 const spawnMock = vi.fn();
-vi.mock("@intentius/chant/runtime-adapter", () => ({
-  getRuntime: () => ({ spawn: spawnMock }),
-}));
+vi.mock("@intentius/chant/runtime-adapter", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@intentius/chant/runtime-adapter")>();
+  return { ...actual, getRuntime: () => ({ ...actual.getRuntime(), spawn: spawnMock }) };
+});
 
 import { awsPlugin } from "../plugin";
 

package/src/lifecycle-integration.test.ts

@@ -11,14 +11,25 @@ import { mkdtempSync, rmSync, readdirSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
+// Partial mock (`importOriginal`) rather than a full replacement: this module
+// is reachable — via `@intentius/chant`'s own root barrel, not just this
+// test's direct imports — from other real exports the plugin/import path
+// touches (e.g. `moduleDir`, which `../../lint/config.ts` calls at module
+// scope), so replacing the whole module wholesale breaks anything that
+// transitively loads one of those, for reasons entirely unrelated to what
+// this test is mocking (`spawn`).
 const spawnMock = vi.fn();
-vi.mock("@intentius/chant/runtime-adapter", () => ({
-  getRuntime: () => ({ spawn: spawnMock }),
-}));
+vi.mock("@intentius/chant/runtime-adapter", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@intentius/chant/runtime-adapter")>();
+  return { ...actual, getRuntime: () => ({ ...actual.getRuntime(), spawn: spawnMock }) };
+});
 
 const { awsPlugin } = await import("./plugin");
 const { liveImportFromPlugins } = await import("@intentius/chant/cli/commands/import");
 const { buildChangeSet } = await import("@intentius/chant/lifecycle/change-set");
+const { normalizeObservation } = await import("@intentius/chant/observation");
+const { liveEvidenceFromChangeSet, reconcileStatus } = await import("@intentius/chant/lifecycle/status");
+const { describeObservationConformance } = await import("@intentius/chant-test-utils");
 
 const liveTemplate = {
   AWSTemplateFormatVersion: "2010-09-09",
@@ -76,12 +87,18 @@ describe("aws lifecycle integration (#163)", () => {
       return Promise.resolve(ok(JSON.stringify({ Stacks: [{ Outputs: [] }] })));
     });
 
-    const observedNow = await awsPlugin.describeResources!({
-      environment: "prod",
-      buildOutput: "",
-      entityNames: ["MyBucket"],
-    });
+    const { resources: observedNow } = normalizeObservation(
+      await awsPlugin.describeResources!({
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["MyBucket"],
+        entities: new Map(),
+      }),
+    );
     expect(observedNow.MyBucket?.type).toBe("AWS::S3::Bucket");
+    // Ownership verdicts are total (#1089): describe-stack-resources carries no
+    // tags, so the verdict is an explicit `unknown`, not a missing field.
+    expect(observedNow.MyBucket?.ownership).toBe("unknown");
 
     // Declared "MyQueue" is absent from live → create; live "MyBucket" is
     // undeclared and unmarked → adopt (never delete without ownership).
@@ -136,4 +153,129 @@ describe("aws lifecycle integration (#163)", () => {
       expect(obs).toBeNull();
     });
   });
+
+  /**
+   * The #1089 chain on the real plugin: a CloudFormation read that fails for
+   * any reason other than "stack does not exist" reports every declared entity
+   * NOT-OBSERVED, and that survives describe → plan → component status.
+   */
+  test("tri-state chain: a failed stack read stays unobserved through describe → plan → status (#1089)", async () => {
+    spawnMock.mockResolvedValue({ stdout: "", stderr: "Unable to locate credentials", exitCode: 255 });
+
+    const observed = normalizeObservation(
+      await awsPlugin.describeResources!({
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["MyBucket", "MyQueue"],
+        entities: new Map(),
+      }),
+    );
+    expect(observed.resources).toEqual({});
+    expect(observed.unobserved.MyBucket.reason).toBe("no-credentials");
+
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["MyBucket", "MyQueue"]),
+      observedNow: observed.resources,
+      observedThen: undefined,
+      unobserved: observed.unobserved,
+    });
+    expect(cs.entries.map((e) => e.action)).toEqual(["unobserved", "unobserved"]);
+
+    const rows = reconcileStatus("prod", [
+      { component: "MyBucket", env: "prod", digest: "sha256:abc", gitSha: "g", runId: "r", timestamp: "2026-01-01T00:00:00Z", actor: "ci" },
+    ], { liveEvidence: liveEvidenceFromChangeSet(cs) });
+    expect(rows[0].reconciliation).toBe("unknown");
+    expect(rows[0].live).toBeUndefined();
+    expect(rows[0].unobserved?.reason).toBe("no-credentials");
+  });
+
+  test("a stack that does not exist is a real absence — every declared entity is a create", async () => {
+    spawnMock.mockResolvedValue({ stdout: "", stderr: "ValidationError: Stack with id prod does not exist", exitCode: 255 });
+
+    const observed = normalizeObservation(
+      await awsPlugin.describeResources!({
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["MyBucket"],
+        entities: new Map(),
+      }),
+    );
+    expect(observed.resources).toEqual({});
+    expect(observed.unobserved).toEqual({});
+
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["MyBucket"]),
+      observedNow: observed.resources,
+      observedThen: undefined,
+      unobserved: observed.unobserved,
+    });
+    expect(cs.entries[0].action).toBe("create");
+  });
+});
+
+// The shared conformance suite (#1089).
+describeObservationConformance({
+  lexicon: "aws",
+  scenarios: [
+    {
+      name: "a stack read that fails on credentials",
+      declared: ["MyBucket", "MyQueue"],
+      expectUnobserved: ["MyBucket", "MyQueue"],
+      run: () => {
+        spawnMock.mockResolvedValue({ stdout: "", stderr: "Unable to locate credentials", exitCode: 255 });
+        return awsPlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["MyBucket", "MyQueue"],
+          entities: new Map(),
+        });
+      },
+    },
+    {
+      name: "a stack that does not exist yet",
+      declared: ["MyBucket"],
+      expectAbsent: ["MyBucket"],
+      run: () => {
+        spawnMock.mockResolvedValue({ stdout: "", stderr: "ValidationError: Stack with id prod does not exist", exitCode: 255 });
+        return awsPlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["MyBucket"],
+          entities: new Map(),
+        });
+      },
+    },
+    {
+      name: "a healthy stack read",
+      declared: ["MyBucket"],
+      expectPresent: ["MyBucket"],
+      run: () => {
+        spawnMock.mockImplementation((argv?: string[]) =>
+          Promise.resolve(
+            argv?.includes("describe-stack-resources")
+              ? ok(
+                  JSON.stringify({
+                    StackResources: [
+                      {
+                        LogicalResourceId: "MyBucket",
+                        ResourceType: "AWS::S3::Bucket",
+                        PhysicalResourceId: "my-bucket",
+                        ResourceStatus: "CREATE_COMPLETE",
+                        Timestamp: "2026-01-01T00:00:00Z",
+                      },
+                    ],
+                  }),
+                )
+              : ok(JSON.stringify({ Stacks: [{ Outputs: [] }] })),
+          ),
+        );
+        return awsPlugin.describeResources!({
+          environment: "prod",
+          buildOutput: "",
+          entityNames: ["MyBucket"],
+          entities: new Map(),
+        });
+      },
+    },
+  ],
 });

package/src/plugin.ts

@@ -1,6 +1,6 @@
 import { createRequire } from "module";
 import { detectTemplate } from "./detect";
-import type { LexiconPlugin, IntrinsicDef, ResourceMetadata, ExportedTemplate, ResourceSelector, InitTemplateSet, StackStatusObservation } from "@intentius/chant/lexicon";
+import type { LexiconPlugin, IntrinsicDef, ObservationResult, ResourceMetadata, ExportedTemplate, ResourceSelector, InitTemplateSet, StackStatusObservation } from "@intentius/chant/lexicon";
 const require = createRequire(import.meta.url);
 import type { LintRule } from "@intentius/chant/lint/rule";
 import type { TemplateParser } from "@intentius/chant/import/parser";
@@ -534,8 +534,9 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     entityNames: string[];
     stack?: string;
     owned?: boolean;
-  }): Promise<Record<string, ResourceMetadata>> {
+  }): Promise<ObservationResult> {
     const { getRuntime } = await import("@intentius/chant/runtime-adapter");
+    const { observation, unobservedAll } = await import("@intentius/chant/observation");
     const rt = getRuntime();
     const resources: Record<string, ResourceMetadata> = {};
 
@@ -544,7 +545,7 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
       // determined here. Degrade to detect-only rather than silently filtering.
       // eslint-disable-next-line no-console
       console.warn(
-        "[aws] ownership filter unavailable on describeResources (no tags from describe-stack-resources) — returning all; use `chant import --from <env> --owned` for ownership-filtered export",
+        "[aws] ownership filter unavailable on describeResources (no tags from describe-stack-resources) — returning all, each with an explicit `unknown` verdict; use `chant import --from <env> --owned` for ownership-filtered export",
       );
     }
 
@@ -565,12 +566,26 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
     if (listResult.exitCode !== 0) {
       // A stack that doesn't exist yet is the pre-first-apply state: nothing is
       // deployed for this env, so there are no live resources (every declared
-      // resource is "pending") — not an error. Returning empty lets `lifecycle
-      // diff --live` / the overlay show pending nodes instead of failing hard.
+      // resource is "pending") — not an error. That is a real absence, so the
+      // empty result is the honest one and `create` is the right proposal.
       if (stackDoesNotExist(listResult.stderr)) {
-        return resources;
+        return observation(resources);
       }
-      throw new Error(`Failed to describe stack "${stackName}": ${listResult.stderr}`);
+      // Any other failure (credentials, throttling, a region that can't be
+      // reached) establishes nothing about what is deployed. Reporting every
+      // declared entity as NOT-OBSERVED (#1089) is what keeps a broken read
+      // from arriving downstream as "none of this exists".
+      const reason = /credential|token|expired|AccessDenied|not authorized|UnauthorizedOperation/i.test(listResult.stderr)
+        ? "no-credentials"
+        : "read-failed";
+      return observation(
+        {},
+        unobservedAll(
+          options.entityNames,
+          reason,
+          `describe-stack-resources failed for stack "${stackName}": ${listResult.stderr.trim().split("\n")[0] ?? ""}`,
+        ),
+      );
     }
 
     const data = JSON.parse(listResult.stdout) as {
@@ -627,11 +642,19 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
         physicalId: stackResource.PhysicalResourceId,
         status: stackResource.ResourceStatus,
         lastUpdated: stackResource.Timestamp,
+        // Total verdict (#1089): describe-stack-resources returns no tags, so
+        // this path cannot read the ownership marker. Say `unknown` explicitly
+        // rather than leaving the field off and letting each consumer guess —
+        // the change set never escalates `unknown` to a delete.
+        ownership: "unknown",
         attributes: Object.keys(attributes).length > 0 ? attributes : undefined,
       };
     }
 
-    return resources;
+    // Every entity the stack answered for was answered for: an entity the
+    // template doesn't carry is genuinely not in this stack, which is an
+    // absence, not a hole.
+    return observation(resources);
   },
 
   async describeStackStatus(options: { environment: string; stack: string }): Promise<StackStatusObservation | null> {

package/src/serializer.test.ts

@@ -941,3 +941,31 @@ describe("default tags serialization", () => {
     expect(template.Resources.MyBucket.Properties.Tags).toBeUndefined();
   });
 });
+
+
+describe("stack output exports and literals", () => {
+  test("exportName emits Output.Export.Name", () => {
+    const bucket = new MockBucket({ BucketName: "my-bucket" });
+    const arnRef = new AttrRef(bucket, "Arn");
+    arnRef._setLogicalName("MyBucket");
+    const output = stackOutput(arnRef, { exportName: "my-stack-BucketArn" });
+
+    const entities = new Map<string, Declarable>();
+    entities.set("MyBucket", bucket);
+    entities.set("MyBucketArn", output as unknown as Declarable);
+
+    const template = JSON.parse(awsSerializer.serialize(entities) as string);
+    expect(template.Outputs.MyBucketArn.Export).toEqual({ Name: "my-stack-BucketArn" });
+  });
+
+  test("literal output serializes its string value with export", () => {
+    const output = stackOutput("22", { lexicon: "aws", exportName: "my-stack-OpenSSHPort" });
+
+    const entities = new Map<string, Declarable>();
+    entities.set("OpenSSHPort", output as unknown as Declarable);
+
+    const template = JSON.parse(awsSerializer.serialize(entities) as string);
+    expect(template.Outputs.OpenSSHPort.Value).toBe("22");
+    expect(template.Outputs.OpenSSHPort.Export).toEqual({ Name: "my-stack-OpenSSHPort" });
+  });
+});

package/src/serializer.ts

@@ -341,7 +341,10 @@ function serializeToTemplate(
       // AttrRef type resolves across the workspace/published boundary.
       const ref: unknown = stackOutput.sourceRef;
       let value: unknown;
-      if (isAttrRefLike(ref)) {
+      if (typeof ref === "string") {
+        // Literal output (constants a stack publishes, e.g. a port number).
+        value = ref;
+      } else if (isAttrRefLike(ref)) {
         const logicalName = ref.getLogicalName();
         if (!logicalName) continue;
         // Use Ref for primary identifier ("Id") since not all resources
@@ -359,6 +362,12 @@ function serializeToTemplate(
       if (stackOutput.description) {
         output.Description = stackOutput.description;
       }
+      // Read defensively: a project may pair this lexicon with an older
+      // published core whose StackOutput type predates exportName.
+      const exportName = (stackOutput as { exportName?: string }).exportName;
+      if (exportName) {
+        output.Export = { Name: exportName };
+      }
       template.Outputs[name] = output;
     }
   }