@intentius/chant 0.44.13 → 0.45.0

package/src/observation.ts

@@ -112,6 +112,24 @@ export interface ObservationResult {
    * namespace, endpoint or region was read, not the one the resource lives in.
    */
   queried?: Record<string, string>;
+  /**
+   * Notices about the read as a whole, not about any one entity (#1265) —
+   * "the ownership filter could not be applied on this surface" is the
+   * canonical one. A note is a property of the environment or the read path,
+   * so core says each distinct note once per run, after the answer, however
+   * many stacks or lexicons reported it. A lexicon returns it here instead of
+   * printing, so the note cannot land ahead of the rows it qualifies.
+   */
+  notes?: string[];
+  /**
+   * What the deployable unit publishes, keyed by the stack that publishes it
+   * (#1279) — a CloudFormation stack's outputs, for instance. Stack-level, so it
+   * lives here once rather than on every resource: a node's `attributes` are
+   * that resource's own properties, and a VPC that carried the stack's
+   * `expWebIp` beside no `CidrBlock` of its own was answering the wrong
+   * question. Values are already scrubbed of anything that looks secret.
+   */
+  stackExports?: Record<string, Record<string, unknown>>;
 }
 
 /**
@@ -126,6 +144,10 @@ export interface NormalizedObservation {
   unobserved: Record<string, UnobservedEntity>;
   /** Resolved query address per entity name (#1620). Empty when the lexicon reported none. */
   queried: Record<string, string>;
+  /** Run-level notices (#1265), distinct. Empty when the lexicon reported none. */
+  notes: string[];
+  /** Per-stack exports (#1279), keyed by stack name. Absent when the lexicon reported none. */
+  stackExports?: Record<string, Record<string, unknown>>;
 }
 
 /** True when `value` is the versioned {@link ObservationResult} envelope. */
@@ -145,12 +167,16 @@ export function observation(
   resources: Record<string, ResourceMetadata>,
   unobserved?: Record<string, UnobservedEntity>,
   queried?: Record<string, string>,
+  notes?: string[],
+  stackExports?: Record<string, Record<string, unknown>>,
 ): ObservationResult {
   return {
     observation: "v1",
     resources,
     ...(unobserved && Object.keys(unobserved).length > 0 ? { unobserved } : {}),
     ...(queried && Object.keys(queried).length > 0 ? { queried } : {}),
+    ...(notes && notes.length > 0 ? { notes } : {}),
+    ...(stackExports && Object.keys(stackExports).length > 0 ? { stackExports } : {}),
   };
 }
 
@@ -161,11 +187,17 @@ export function observation(
  * {@link unobservedAll} rather than returning nothing.
  */
 export function normalizeObservation(value: DescribeResourcesResult | undefined): NormalizedObservation {
-  if (!value) return { resources: {}, unobserved: {}, queried: {} };
+  if (!value) return { resources: {}, unobserved: {}, queried: {}, notes: [] };
   if (isObservationResult(value)) {
-    return { resources: value.resources ?? {}, unobserved: value.unobserved ?? {}, queried: value.queried ?? {} };
+    return {
+      resources: value.resources ?? {},
+      unobserved: value.unobserved ?? {},
+      queried: value.queried ?? {},
+      notes: [...new Set(value.notes ?? [])],
+      ...(value.stackExports && Object.keys(value.stackExports).length > 0 ? { stackExports: value.stackExports } : {}),
+    };
   }
-  return { resources: value, unobserved: {}, queried: {} };
+  return { resources: value, unobserved: {}, queried: {}, notes: [] };
 }
 
 /**
@@ -205,15 +237,27 @@ export function mergeObservations(parts: Iterable<NormalizedObservation>): Norma
   const resources: Record<string, ResourceMetadata> = {};
   const unobserved: Record<string, UnobservedEntity> = {};
   const queried: Record<string, string> = {};
+  // A note is about the read, not a stack; four stacks saying the same thing
+  // is one note (#1265).
+  const notes = new Set<string>();
+  const stackExports: Record<string, Record<string, unknown>> = {};
   for (const part of parts) {
     Object.assign(resources, part.resources);
     Object.assign(unobserved, part.unobserved);
     Object.assign(queried, part.queried);
+    for (const n of part.notes) notes.add(n);
+    Object.assign(stackExports, part.stackExports ?? {});
   }
   // Present wins: a stack that could not be read does not un-observe a resource
   // another stack returned.
   for (const name of Object.keys(resources)) delete unobserved[name];
-  return { resources, unobserved, queried };
+  return {
+    resources,
+    unobserved,
+    queried,
+    notes: [...notes],
+    ...(Object.keys(stackExports).length > 0 ? { stackExports } : {}),
+  };
 }
 
 /** One-line human phrasing of a reason, for CLI output. */

package/src/op/builders-exports.test.ts

@@ -0,0 +1,60 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import * as opIndex from "./index";
+import * as builders from "./builders";
+
+/**
+ * chant #1715 — `op/index.ts` re-exports the step builders from `./builders`
+ * by name, in a hand-maintained list of forty-odd identifiers. `waitForReady`
+ * — the CRD-aware readiness builder #365 added, with its own readiness spec,
+ * kstatus default and per-kind overrides — was defined in `builders.ts` and
+ * missing from that list, so no project could reach it from the day it landed.
+ * The activity behind it had been registered in the k8s lexicon the whole
+ * time; nothing noticed because every readiness wait in the repo predates it.
+ *
+ * The list drifting from the thing it lists is the bug, not the one missing
+ * name. Same shape as #1347's assertion over the `LexiconPlugin` optional-member
+ * table.
+ */
+describe("op builders are all reachable (#1715)", () => {
+  test("every value exported from builders.ts is re-exported from op/index.ts", () => {
+    const missing = Object.keys(builders).filter((name) => !(name in opIndex));
+    expect(
+      missing,
+      `builders.ts exports these, and op/index.ts does not re-export them — add them to the ` +
+        `export list at the top of op/index.ts, or a project cannot use them:\n  ${missing.join("\n  ")}`,
+    ).toEqual([]);
+  });
+
+  test("the temporal lexicon re-exports the same set", () => {
+    // The lexicon is what a project actually imports from
+    // (`@intentius/chant-lexicon-temporal`), and it re-states the list a third
+    // time rather than re-exporting wholesale — so it can drift independently.
+    const src = readFileSync(
+      join(import.meta.dirname, "../../../../lexicons/temporal/src/index.ts"),
+      "utf-8",
+    );
+    const block = src.match(/export \{([^}]*)\} from "@intentius\/chant\/op";/)?.[1] ?? "";
+    const reExported = new Set(
+      block.split(",").map((s) => s.trim()).filter(Boolean),
+    );
+    // The sprites family reaches projects through the fly lexicon, not this
+    // one. Named rather than prefix-matched, because `listCheckpoints` is one
+    // of them and does not look like one — which this test caught on its
+    // first run.
+    const FLY_SURFACE = new Set([
+      "spriteCreate", "spriteExec", "spriteCheckpoint", "spriteRestore",
+      "listCheckpoints", "spriteDestroy", "spriteWriteFile", "spriteReadFile",
+      "spriteListDir", "spriteRemove", "spriteApplyNetworkPolicy",
+      "spriteApplyServices", "spriteTaskCreate", "spriteTaskRefresh",
+      "spriteTaskRelease", "spritesUp", "spritesDown",
+    ]);
+    const expected = Object.keys(builders).filter((n) => !FLY_SURFACE.has(n));
+    const missing = expected.filter((name) => !reExported.has(name));
+    expect(
+      missing,
+      `lexicons/temporal/src/index.ts does not re-export these builders:\n  ${missing.join("\n  ")}`,
+    ).toEqual([]);
+  });
+});

package/src/op/index.ts

@@ -1,4 +1,4 @@
-export { Op, phase, activity, gate, build, kubectlApply, helmInstall, waitForStack,
+export { Op, phase, activity, gate, build, kubectlApply, helmInstall, waitForStack, waitForReady,
          gitlabPipeline, lifecycleSnapshot, shell, teardown, k3dUp, k3dDown, flociUp, flociDown,
          flociAzUp, flociAzDown, flociGcpUp, flociGcpDown, httpCheck,
          azGroupEnsure, azGroupDelete, azApply, azDelete, awsApply, awsDelete, gcpApply, gcpDelete, policyGate,

package/src/ownership.test.ts

@@ -9,7 +9,12 @@ import {
   OWNERSHIP_MANAGED_BY_VALUE,
   type ChannelKeys,
 } from "./ownership";
-import { resolveOwnershipMarker } from "./config";
+import {
+  resolveOwnershipMarker,
+  resolveOwnershipEnv,
+  resolveOwnershipStack,
+  ownershipEnvDisagreement,
+} from "./config";
 
 // A stand-in for a lexicon-provided convention (e.g. AWS's colon keys), to
 // prove the core helpers are generic over any `ChannelKeys` — the per-provider
@@ -105,3 +110,60 @@ describe("resolveOwnershipMarker (config opt-in)", () => {
     expect(resolveOwnershipMarker({ ownership: { stack: "billing", enabled: false } })).toBeUndefined();
   });
 });
+
+describe("ownership.env as a build-parameter reference (#1396)", () => {
+  const config = {
+    ownership: { stack: "fountain", env: { param: "env" } },
+    buildParams: { env: { type: "string" as const, default: "dev", env: "FOUNTAIN_ENV" } },
+  };
+
+  test("takes the resolved parameter value — --param env=prod drives the marker", () => {
+    expect(resolveOwnershipMarker(config, [{ name: "env", value: "prod", source: "cli" }])).toEqual({
+      stack: "fountain",
+      env: "prod",
+    });
+    expect(resolveOwnershipMarker(config, [{ name: "env", value: "dev", source: "default" }])).toEqual({
+      stack: "fountain",
+      env: "dev",
+    });
+  });
+
+  test("a reference to an undeclared parameter is an error, not an env-less marker", () => {
+    expect(() => resolveOwnershipMarker({ ownership: { stack: "s", env: { param: "env" } } }, [])).toThrow(
+      /does not declare/,
+    );
+  });
+
+  test("a reference to a parameter that resolved to nothing is an error", () => {
+    expect(() => resolveOwnershipMarker(config, [])).toThrow(
+      /resolved to no value.*--param env=<value>.*FOUNTAIN_ENV/,
+    );
+  });
+
+  test("the stack-only resolver needs no parameters", () => {
+    expect(resolveOwnershipStack(config)).toBe("fountain");
+    expect(resolveOwnershipStack({ ownership: { stack: "s", enabled: false } })).toBeUndefined();
+  });
+
+  test("a literal env is returned untouched, with or without parameters", () => {
+    expect(resolveOwnershipEnv({ ownership: { stack: "s", env: "prod" } }, undefined)).toBe("prod");
+    expect(resolveOwnershipEnv({ ownership: { stack: "s" } }, [])).toBeUndefined();
+  });
+
+  test("a literal env disagreeing with an env parameter is reported", () => {
+    const literal = {
+      ownership: { stack: "fountain", env: "dev" },
+      buildParams: { env: { type: "string" as const, default: "dev" } },
+    };
+    expect(ownershipEnvDisagreement(literal, [{ name: "env", value: "dev", source: "default" }])).toBeUndefined();
+    expect(ownershipEnvDisagreement(literal, [{ name: "env", value: "prod", source: "cli" }])).toMatch(
+      /ownership\.env is "dev" but the env build parameter resolved to "prod" \(cli\)/,
+    );
+    // A reference never disagrees — there is one source.
+    expect(ownershipEnvDisagreement(config, [{ name: "env", value: "prod", source: "cli" }])).toBeUndefined();
+    // Marking off — nothing is stamped, nothing to disagree with.
+    expect(
+      ownershipEnvDisagreement({ ownership: { env: "dev" } }, [{ name: "env", value: "prod", source: "cli" }]),
+    ).toBeUndefined();
+  });
+});

package/src/yaml.test.ts

@@ -10,6 +10,21 @@ describe("emitYAML", () => {
     expect(emitYAML(undefined, 0)).toBe("null");
   });
 
+  test("an undefined object value drops the key, an explicit null keeps it (#1371)", () => {
+    // Matches `JSON.stringify`: `{ a: undefined }` is `{}`; an unset optional
+    // build parameter passed straight into a resource must not ship as
+    // `a: null`.
+    expect(emitYAML({ a: undefined, b: 1 }, 0)).toBe("\nb: 1");
+    expect(emitYAML({ a: null, b: 1 }, 0)).toBe("\na: null\nb: 1");
+    expect(emitYAML({ a: undefined }, 0)).toBe("{}");
+    expect(emitYAML({ spec: { baseImageArn: undefined, name: "x" } }, 0)).toBe("\nspec:\n  name: x");
+  });
+
+  test("an undefined inside an array-item object drops the key; a bare undefined element is null", () => {
+    expect(emitYAML([{ a: undefined, b: 1 }, { c: undefined, d: 2, e: 3 }], 0)).toBe("\n- b: 1\n- d: 2\n  e: 3");
+    expect(emitYAML([undefined, 1], 0)).toBe("\n- null\n- 1");
+  });
+
   test("booleans", () => {
     expect(emitYAML(true, 0)).toBe("true");
     expect(emitYAML(false, 0)).toBe("false");

package/src/yaml.ts

@@ -19,9 +19,26 @@
  *   with `\n` so the caller can append it after a key.
  * - Tagged values `{ tag, value }` emit `!tag [...]` or `!tag scalar`.
  */
+/**
+ * An object's entries minus those whose value is `undefined`. An `undefined`
+ * property is "not supplied" in TypeScript (a declared-but-unset optional
+ * build parameter, `{ x: cond ? v : undefined }`), which `JSON.stringify`
+ * already omits; the YAML emitter must agree, or the same source ships
+ * `key: null` under `-o out.yaml` and no key at all under `-o out.json`. An
+ * explicit `null` is a value and is kept (chant #1371).
+ */
+function definedEntries(obj: Record<string, unknown>): [string, unknown][] {
+  return Object.entries(obj).filter(([, val]) => val !== undefined);
+}
+
 export function emitYAML(value: unknown, indent: number): string {
   const prefix = "  ".repeat(indent);
 
+  // `undefined` only reaches here as a top-level value or an array element —
+  // an object entry whose value is `undefined` is dropped below, the same way
+  // `JSON.stringify` omits it. A bare `undefined` renders as `null` for the
+  // same reason `JSON.stringify([undefined])` is `[null]`: YAML has no way to
+  // say "absent" in a sequence slot.
   if (value === null || value === undefined) {
     return "null";
   }
@@ -74,7 +91,7 @@ export function emitYAML(value: unknown, indent: number): string {
     for (const item of value) {
       if (typeof item === "object" && item !== null && !Array.isArray(item)) {
         // Object items in arrays
-        const entries = Object.entries(item as Record<string, unknown>);
+        const entries = definedEntries(item as Record<string, unknown>);
         if (entries.length > 0) {
           const [firstKey, firstVal] = entries[0];
           const firstEmitted = emitYAML(firstVal, indent + 2);
@@ -111,7 +128,7 @@ export function emitYAML(value: unknown, indent: number): string {
       return `${obj.tag} ${emitYAML(obj.value, indent)}`;
     }
 
-    const entries = Object.entries(obj);
+    const entries = definedEntries(obj);
     if (entries.length === 0) return "{}";
     const lines: string[] = [];
     for (const [key, val] of entries) {