@intentius/chant-lexicon-k8s 0.44.12 → 0.44.13

package/dist/describe-resources.d.ts

@@ -90,6 +90,28 @@ export declare function revisionAttributes(obj: K8sObject): {
     lastAttemptedRevision?: string;
     artifactRevision?: string;
 };
+/**
+ * The declared repository protocol of a Flux HelmRepository (behold#298).
+ *
+ * A HelmRepository with `spec.type: oci` is never reconciled by
+ * source-controller — no conditions, no artifact, by design — so a consumer
+ * classifying health off conditions reads a healthy OCI repository exactly
+ * like one whose controller has not shown up. `spec.type` is the field that
+ * separates the two, and no spec field reached the wire before this. It rides
+ * the attributes flattened, as `type`, the same way `artifactRevision`
+ * flattens `status.artifact.revision`: every scalar on the wire is a plain
+ * key next to the others, and the wire stays lean — one field, not the spec.
+ *
+ * Kind-gated, unlike the module's usual read-by-path rule, because the PATH
+ * is not distinctive: a core Service's `spec.type` is
+ * `ClusterIP`/`LoadBalancer`, and forwarding that would change the wire shape
+ * of a kind this was never about. Only source.toolkit.fluxcd.io's
+ * HelmRepository speaks this meaning of the field.
+ */
+export declare function helmRepositoryTypeAttribute(gvk: {
+    apiVersion: string;
+    kind: string;
+}, obj: K8sObject): string | undefined;
 export interface DescribeResourcesOptions {
     environment: string;
     buildOutput: string;

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,CAuBtE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,SAAS,GAAG;IAClD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAUA;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;IACb;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,EACjC,OAAO,GAAE,YAAkC,GAC1C,OAAO,CAAC,iBAAiB,CAAC,CA6J5B"}
+{"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,CAuBtE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,SAAS,GAAG;IAClD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAUA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACzC,GAAG,EAAE,SAAS,GACb,MAAM,GAAG,SAAS,CAIpB;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;IACb;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,EACjC,OAAO,GAAE,YAAkC,GAC1C,OAAO,CAAC,iBAAiB,CAAC,CAgK5B"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "79f4f4af7c9611c5f4ca2843ae3e1222520dd8549c888a3c0b4ad4f20cab1a25",
+    "manifest.json": "b6c625f7af4e812f458d344b2a2a8bf8eccdb1508fbe9eaf7c42108bf5f8179e",
     "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": "052a02845dd4fcecbee0564f851a014f7d202f26750afcbae9e3492ec5c956c1"
+  "composite": "e9afd4601ffb6af967ef1826619470ff515e865d6c66ce1ce68bb8b8a3bedb7d"
 }

package/dist/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.44.12",
+  "version": "0.44.13",
   "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.12"
+    "@intentius/chant-k8s-client": "^0.44.13"
   },
   "devDependencies": {
     "@intentius/chant": "*",
@@ -84,7 +84,7 @@
   },
   "peerDependencies": {
     "zod": "^4.3.6",
-    "@intentius/chant": "^0.44.12",
+    "@intentius/chant": "^0.44.13",
     "typescript": "^5.9.3"
   }
 }

package/src/describe-resources.test.ts

@@ -15,7 +15,7 @@ vi.mock("@intentius/chant/config", () => ({
   loadChantConfig: (...args: unknown[]) => loadChantConfigMock(...args),
 }));
 
-const { describeResources, statusFromObject, unhappyConditions, revisionAttributes } = await import("./describe-resources");
+const { describeResources, statusFromObject, unhappyConditions, revisionAttributes, helmRepositoryTypeAttribute } = await import("./describe-resources");
 const { fakeCluster, objectKey, ownedObject } = await import("./api/fake-cluster");
 const { defaultK8sConnector } = await import("./api/connect");
 const { fakeKubeconfig, statusBody } = await import("@intentius/chant-k8s-client/testing");
@@ -1628,6 +1628,126 @@ describe("observed attributes carry the Flux revisions (#1632)", () => {
   });
 });
 
+describe("helmRepositoryTypeAttribute — the one spec field on the wire (behold#298)", () => {
+  const gvk = { apiVersion: "source.toolkit.fluxcd.io/v1", kind: "HelmRepository" };
+
+  test("carries a HelmRepository's spec.type when set", () => {
+    expect(helmRepositoryTypeAttribute(gvk, { spec: { type: "oci" } } as never)).toBe("oci");
+    expect(helmRepositoryTypeAttribute(gvk, { spec: { type: "default" } } as never)).toBe("default");
+  });
+
+  test("says nothing when the field is absent — the CRD does not default it", () => {
+    expect(helmRepositoryTypeAttribute(gvk, { spec: { url: "https://charts.example.com" } } as never)).toBeUndefined();
+    expect(helmRepositoryTypeAttribute(gvk, {} as never)).toBeUndefined();
+  });
+
+  test("ignores non-string and empty values", () => {
+    expect(helmRepositoryTypeAttribute(gvk, { spec: { type: "" } } as never)).toBeUndefined();
+    expect(helmRepositoryTypeAttribute(gvk, { spec: { type: 7 } } as never)).toBeUndefined();
+  });
+
+  test("declines every other kind — spec.type is not a distinctive path", () => {
+    // A core Service HAS a spec.type; forwarding it would change a wire shape
+    // this field was never about.
+    expect(
+      helmRepositoryTypeAttribute({ apiVersion: "v1", kind: "Service" }, { spec: { type: "LoadBalancer" } } as never),
+    ).toBeUndefined();
+    // Same kind name in a foreign group claims nothing either.
+    expect(
+      helmRepositoryTypeAttribute({ apiVersion: "example.io/v1", kind: "HelmRepository" }, { spec: { type: "oci" } } as never),
+    ).toBeUndefined();
+  });
+});
+
+describe("observed attributes carry a HelmRepository's spec.type (behold#298)", () => {
+  test("an OCI HelmRepository reads type: 'oci'; a default one grows no type key", async () => {
+    // The behold#298 shape: `spec.type: oci` means source-controller never
+    // reconciles the object — no conditions, no artifact, by design — so a
+    // consumer classifying off conditions needs this field to tell a healthy
+    // OCI repository from a wedged default one.
+    const oci = {
+      apiVersion: "source.toolkit.fluxcd.io/v1",
+      kind: "HelmRepository",
+      metadata: { name: "charts-oci", namespace: "flux-system", uid: "hrepo-oci-uid" },
+      spec: { type: "oci", url: "oci://ghcr.io/example/charts" },
+      // No status at all — exactly what the API returns for an OCI one.
+    };
+    const plain = {
+      apiVersion: "source.toolkit.fluxcd.io/v1",
+      kind: "HelmRepository",
+      metadata: { name: "charts-http", namespace: "flux-system", uid: "hrepo-http-uid" },
+      // The CRD does not default spec.type: a default repository simply
+      // carries no `type` field, and the wire says nothing for it.
+      spec: { url: "https://charts.example.com" },
+      status: { conditions: [{ type: "Ready", status: "True" }], artifact: { revision: "sha256:abc123" } },
+    };
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("source.toolkit.fluxcd.io/v1", "HelmRepository", "charts-oci", "flux-system")]: oci,
+        [objectKey("source.toolkit.fluxcd.io/v1", "HelmRepository", "charts-http", "flux-system")]: plain,
+      },
+    });
+
+    const result = await describeResources(
+      {
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["chartsOci", "chartsHttp"],
+        entities: makeEntities([
+          {
+            name: "chartsOci",
+            entityType: "K8s::Flux::HelmRepository",
+            props: { metadata: { name: "charts-oci", namespace: "flux-system" }, spec: { type: "oci", url: "oci://ghcr.io/example/charts" } },
+          },
+          {
+            name: "chartsHttp",
+            entityType: "K8s::Flux::HelmRepository",
+            props: { metadata: { name: "charts-http", namespace: "flux-system" }, spec: { url: "https://charts.example.com" } },
+          },
+        ]),
+      },
+      cluster.connector,
+    );
+
+    expect(result.resources.chartsOci?.attributes).toMatchObject({ type: "oci" });
+    // No conditions is the healthy shape for OCI — nothing unhappy to carry.
+    expect(result.resources.chartsOci?.attributes).not.toHaveProperty("conditions");
+    // The default repository's attributes are byte-for-byte what they were:
+    // no `type` key appears, and its revision still rides #1632's path.
+    expect(result.resources.chartsHttp?.attributes).not.toHaveProperty("type");
+    expect(result.resources.chartsHttp?.attributes).toMatchObject({ artifactRevision: "sha256:abc123" });
+  });
+
+  test("no other kind grows a type attribute — a Service's spec.type stays off the wire", async () => {
+    const lb = {
+      apiVersion: "v1",
+      kind: "Service",
+      metadata: { name: "web-lb", namespace: "prod", uid: "lb-uid" },
+      spec: { type: "LoadBalancer", ports: [{ port: 80 }] },
+    };
+    const cluster = fakeCluster({ objects: { [objectKey("v1", "Service", "web-lb", "prod")]: lb } });
+
+    const result = await describeResources(
+      {
+        environment: "prod",
+        buildOutput: "",
+        entityNames: ["webLb"],
+        entities: makeEntities([
+          {
+            name: "webLb",
+            entityType: "K8s::Core::Service",
+            props: { metadata: { name: "web-lb", namespace: "prod" }, spec: { type: "LoadBalancer" } },
+          },
+        ]),
+      },
+      cluster.connector,
+    );
+
+    expect(result.resources.webLb).toBeDefined();
+    expect(result.resources.webLb?.attributes).not.toHaveProperty("type");
+  });
+});
+
 // The behold#221 shape (#1629): the estate's control-plane project declares
 // the Kustomization carrying `spec.targetNamespace`, and the app project
 // declares bare objects the controller stamps at apply time. Reading the app

package/src/describe-resources.ts

@@ -280,6 +280,33 @@ export function revisionAttributes(obj: K8sObject): {
   };
 }
 
+/**
+ * The declared repository protocol of a Flux HelmRepository (behold#298).
+ *
+ * A HelmRepository with `spec.type: oci` is never reconciled by
+ * source-controller — no conditions, no artifact, by design — so a consumer
+ * classifying health off conditions reads a healthy OCI repository exactly
+ * like one whose controller has not shown up. `spec.type` is the field that
+ * separates the two, and no spec field reached the wire before this. It rides
+ * the attributes flattened, as `type`, the same way `artifactRevision`
+ * flattens `status.artifact.revision`: every scalar on the wire is a plain
+ * key next to the others, and the wire stays lean — one field, not the spec.
+ *
+ * Kind-gated, unlike the module's usual read-by-path rule, because the PATH
+ * is not distinctive: a core Service's `spec.type` is
+ * `ClusterIP`/`LoadBalancer`, and forwarding that would change the wire shape
+ * of a kind this was never about. Only source.toolkit.fluxcd.io's
+ * HelmRepository speaks this meaning of the field.
+ */
+export function helmRepositoryTypeAttribute(
+  gvk: { apiVersion: string; kind: string },
+  obj: K8sObject,
+): string | undefined {
+  if (gvk.kind !== "HelmRepository" || !gvk.apiVersion.startsWith("source.toolkit.fluxcd.io/")) return undefined;
+  const type = (obj.spec as { type?: unknown } | undefined)?.type;
+  return typeof type === "string" && type.length > 0 ? type : undefined;
+}
+
 interface Declared {
   entityName: string;
   entityType: string;
@@ -454,6 +481,9 @@ export async function describeResources(
           // What a GitOps controller says it has applied and is applying
           // (#1632) — the convergence signal conditions cannot carry.
           ...revisionAttributes(obj),
+          // A HelmRepository's spec.type — `oci` means "no conditions is
+          // healthy", and only this field can say so (behold#298).
+          type: helmRepositoryTypeAttribute(operation, obj),
         }),
       };
     } catch (err) {
@@ -750,6 +780,10 @@ async function addRuntimeChildren(
           labels: obj.metadata?.labels,
           resourceVersion: obj.metadata?.resourceVersion,
           conditions: unhappyConditions(obj),
+          // The same one spec field the declared read forwards (behold#298):
+          // a swept HelmRepository (Flux's own bootstrap manages them through
+          // a Kustomization) must not read differently from a declared one.
+          type: helmRepositoryTypeAttribute(swept, obj),
         }),
       };
     });