@intentius/chant-lexicon-k8s 0.44.1 → 0.44.3

package/dist/describe-resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAwD,MAAM,0BAA0B,CAAC;AAGxH,OAAO,KAAK,EAAa,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAmBvE;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CA2CvD;AA4FD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CAetE;AAQD,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sFAAsF;IACtF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,EACjC,OAAO,GAAE,YAAkC,GAC1C,OAAO,CAAC,iBAAiB,CAAC,CAuH5B"}
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAwD,MAAM,0BAA0B,CAAC;AAGxH,OAAO,KAAK,EAAa,SAAS,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAmBvE;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CA2CvD;AA4FD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CAetE;AAQD,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sFAAsF;IACtF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,EACjC,OAAO,GAAE,YAAkC,GAC1C,OAAO,CAAC,iBAAiB,CAAC,CAoJ5B"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "df671e29d9407ee96948c664b023efdb945fe12b235b2d80e9068a21981ff8a9",
+    "manifest.json": "d94d393cea4fe4e3bebaa9590a85d8966e15e27d6cf2233ed07395182146501b",
     "meta.json": "f568fb8a0cbd4adf041baccaa3e1164c2e3c5c0090186236f887f0084f5521a8",
     "types/index.d.ts": "ef2c9df6a4d1ebfbe33f96c094fbbe3fc7909522ea38e086666fbf3c8ac477fd",
     "rules/argo-appset-single-project.ts": "afa9f310753aa2d475f35012b13135b2dfaebed2a35d44edbe185ebc07673674",
@@ -54,5 +54,5 @@
     "skills/chant-k8s-argo.md": "b1a0b826559d8c5033a479c5781efaf650320f0aee4419d8841170bd3393cea5",
     "skills/chant-k8s-flux.md": "9670efc2e9854bd14686b5adeb707396b9030a4dcaee6529b30abf56efe2c50c"
   },
-  "composite": "429fe4248b671efc49187546209d335f57c4483ed1e1cbf2e98fb61490f0b235"
+  "composite": "1031cf6d53da6ad5ddf631aaa8160f1a5ca914c95a124b0827e42b40b99ab270"
 }

package/dist/manifest.json

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

package/package.json

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

package/src/api/classify.test.ts

@@ -103,13 +103,30 @@ describe("classifyApiFailure", () => {
     }
   });
 
-  test("the context note survives the one-line cap rather than truncating with the message (#1488)", () => {
+  test("the context note leads the detail, so it survives the one-line cap and any consumer truncation (#1488, #1620)", () => {
     const err = new K8sApiError(500, "InternalError", "x".repeat(500));
     err.contextNote = 'context "prod-eks" (bound by k8s.profiles.prod.context)';
     const outcome = classifyApiFailure(err);
     expect(outcome.kind).toBe("unobserved");
     if (outcome.kind === "unobserved") {
-      expect(outcome.detail.endsWith('context "prod-eks" (bound by k8s.profiles.prod.context)')).toBe(true);
+      expect(outcome.detail.startsWith('context "prod-eks" (bound by k8s.profiles.prod.context)')).toBe(true);
+      // The error itself still follows — leading with the cluster does not
+      // cost the message.
+      expect(outcome.detail).toContain("xxx");
+    }
+  });
+
+  test("the context appears within the first 160 chars of a long multi-line error's detail (#1620)", () => {
+    // behold's estate overlay truncates a reason to its first line / 160 chars;
+    // the context must land inside that window or it vanishes exactly on the
+    // failures long enough to need it.
+    const err = new K8sApiError(500, "InternalError", `${"y".repeat(300)}\n${"z".repeat(300)}`);
+    err.contextNote = 'context "prod-eks" (bound by k8s.profiles.prod.context)';
+    const outcome = classifyApiFailure(err);
+    expect(outcome.kind).toBe("unobserved");
+    if (outcome.kind === "unobserved") {
+      const firstLine = outcome.detail.split("\n")[0];
+      expect(firstLine.slice(0, 160)).toContain('context "prod-eks" (bound by k8s.profiles.prod.context)');
     }
   });
 

package/src/api/classify.ts

@@ -145,7 +145,10 @@ function detailOf(err: unknown): string {
   const capped = line.length > 200 ? `${line.slice(0, 197)}...` : line;
   // #1488 — a reason that does not say which cluster was read turned an
   // ambient-context switch into an afternoon. The client stamps the context it
-  // resolved onto every failure; append it after the cap so it never truncates.
+  // resolved onto every failure. The note LEADS the detail (#1620): consumers
+  // truncate a reason to its first line and ~160 chars, and a note appended
+  // after a long error is cut off exactly when the error is long enough to
+  // need it. Leading, it survives any suffix truncation.
   const note = shapeOf(err).contextNote;
-  return note ? `${capped} — ${note}` : capped;
+  return note ? `${note} — ${capped}` : capped;
 }

package/src/describe-resources.test.ts

@@ -105,6 +105,81 @@ describe("k8s describeResources", () => {
     expect(result.unobserved ?? {}).toEqual({});
   });
 
+  // The behold#192 shape (#1620): a Flux-deployed object declares no
+  // metadata.namespace (the controller stamps targetNamespace at apply), so the
+  // live read scopes to the client's default namespace, finds nothing, and
+  // correctly reports absence. Every layer is spec-correct and the picture
+  // still says the opposite of the truth — unless the report carries the
+  // address it actually asked, which is what `queried` is.
+  test("an absent verdict carries the resolved query address, namespace defaulted and visible (#1620)", async () => {
+    const cluster = fakeCluster({
+      // The object lives where Flux put it — not where the read will look.
+      objects: { [objectKey("apps/v1", "Deployment", "web", "flux-target")]: web },
+    });
+    const result = await describeResources(
+      {
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["web"],
+        entities: makeEntities([
+          // No metadata.namespace declared — Flux stamps it at apply time.
+          { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web" } } },
+        ]),
+      },
+      cluster.connector,
+    );
+
+    // Still a clean absence: in neither map, the tri-state unshifted.
+    expect(result.resources).toEqual({});
+    expect(result.unobserved ?? {}).toEqual({});
+    // But the report can now explain itself: the read went to `default`.
+    expect(result.queried?.web).toBe("/apis/apps/v1/namespaces/default/deployments/web");
+  });
+
+  test("a present entity carries its query address too — the map is total over issued reads (#1620)", async () => {
+    const cluster = fakeCluster({
+      objects: { [objectKey("apps/v1", "Deployment", "web", "prod")]: web },
+    });
+    const result = await describeResources(
+      {
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["web"],
+        entities: makeEntities([
+          { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } },
+        ]),
+      },
+      cluster.connector,
+    );
+    expect(result.resources.web).toBeDefined();
+    expect(result.queried?.web).toBe("/apis/apps/v1/namespaces/prod/deployments/web");
+  });
+
+  test("a read-failed unobserved entry carries the address the failing read was issued against (#1620)", async () => {
+    const cluster = fakeCluster({
+      respond: (req) =>
+        req.path.endsWith("/deployments/web")
+          ? { status: 500, body: statusBody(500, "InternalError", "etcdserver: request timed out") }
+          : undefined,
+    });
+    const result = await describeResources(
+      {
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["web"],
+        entities: makeEntities([
+          { name: "web", entityType: "K8s::Apps::Deployment", props: { metadata: { name: "web", namespace: "prod" } } },
+        ]),
+      },
+      cluster.connector,
+    );
+    expect(result.unobserved?.web).toMatchObject({
+      reason: "read-failed",
+      queried: "/apis/apps/v1/namespaces/prod/deployments/web",
+    });
+    expect(result.queried?.web).toBe("/apis/apps/v1/namespaces/prod/deployments/web");
+  });
+
   // The headline of chant #1074: the twenty-entry map is gone, so a CRD is an
   // ordinary read rather than a permanent hole.
   test("a CRD is observed like anything else — no KUBECTL_RESOURCE entry required", async () => {

package/src/describe-resources.ts

@@ -255,6 +255,14 @@ export async function describeResources(
 ): Promise<ObservationResult> {
   const resources: Record<string, ResourceMetadata> = {};
   const unobserved: Record<string, UnobservedEntity> = {};
+  // The resolved query address per declared entity (#1620) — the exact request
+  // path each read was issued against, with the namespace the client actually
+  // defaulted to when the declaration carries none. This is what lets an
+  // absence explain itself: a Flux-deployed object declaring no
+  // metadata.namespace reads from `default`, correctly comes back 404, and
+  // without the address the report says "not there" when the truth is "not
+  // looked for where it lives".
+  const queried: Record<string, string> = {};
 
   const declared: Declared[] = [...options.entities].map(([entityName, entity]) => ({
     entityName,
@@ -323,13 +331,27 @@ export async function describeResources(
       return;
     }
 
+    const ref = {
+      apiVersion: operation.apiVersion,
+      kind: operation.kind,
+      name,
+      ...(metadata?.namespace ? { namespace: metadata.namespace } : {}),
+    };
+
+    // Resolve the address BEFORE the read, so every verdict below — present,
+    // absent, filtered, read-failed — carries the same record of what was
+    // asked. Resolution rides the client's cached discovery; a kind discovery
+    // does not serve has no path, and a resolution failure classifies through
+    // the read below, never here.
+    try {
+      const address = typeof client.pathFor === "function" ? await client.pathFor(ref) : undefined;
+      if (address) queried[entityName] = address;
+    } catch {
+      // The read below hits the same resolution and classifies its failure.
+    }
+
     try {
-      const obj = await client.read({
-        apiVersion: operation.apiVersion,
-        kind: operation.kind,
-        name,
-        ...(metadata?.namespace ? { namespace: metadata.namespace } : {}),
-      });
+      const obj = await client.read(ref);
 
       // owned filter: withhold resources not carrying chant's marker label.
       // Withheld is not absent (chant #1089) — this object exists, it just
@@ -340,6 +362,7 @@ export async function describeResources(
           type: entityType,
           reason: "filtered",
           detail: "live object carries no chant ownership marker and --owned was requested",
+          ...(queried[entityName] ? { queried: queried[entityName] } : {}),
         };
         return;
       }
@@ -361,16 +384,22 @@ export async function describeResources(
     } catch (err) {
       const outcome = classifyApiFailure(err);
       if (outcome.kind === "unobserved") {
-        unobserved[entityName] = { type: entityType, reason: outcome.reason, detail: outcome.detail };
+        unobserved[entityName] = {
+          type: entityType,
+          reason: outcome.reason,
+          detail: outcome.detail,
+          ...(queried[entityName] ? { queried: queried[entityName] } : {}),
+        };
       }
       // `absent` deliberately records nothing: in neither map is how the
-      // contract spells "asked, and it is not there".
+      // contract spells "asked, and it is not there". Its address stays in
+      // `queried` (#1620), which is the only record an absence gets.
     }
   });
 
   await addRuntimeChildren(client, resources, unobserved, options.owned, declared);
 
-  return observation(resources, unobserved);
+  return observation(resources, unobserved, queried);
 }
 
 /**