@intentius/chant 0.38.0 → 0.39.0

package/src/lifecycle/replay.ts

@@ -15,6 +15,7 @@
  */
 
 import { readEnvironmentSnapshots } from "./git";
+import { unqualifiedKey } from "./identity";
 import type { LiveObservation } from "../graph-ir";
 import type { LifecycleSnapshot } from "./types";
 
@@ -72,16 +73,35 @@ export async function replaySnapshots(
   // account-level: the default security group three stacks each recorded is one
   // group, not three. Managed resources are stack-qualified below and cannot
   // collide, so only the unqualified ones need this.
+  //
+  // "Account-level" is the part that needed qualifying (#1416): a resource that
+  // records a region is regional, and two regions' copies are two resources
+  // however equal their ids look. `unqualifiedKey` keys those by region, so the
+  // set below still collapses one region's resource seen from two stacks and no
+  // longer collapses two regions'.
   const seenUnqualified = new Set<string>();
+  // One recorded stack is one region, so there is nothing to merge and nothing
+  // to disambiguate — its ids stay exactly what they were recorded as, which is
+  // also what `chant search --live` gives that project.
+  const merging = stored.size > 1;
   // A stack's snapshot could only exclude what THAT stack manages, so a stack
   // declaring no security groups reported the neighbouring stack's as ambient.
   // The union is only knowable here, with every snapshot in hand.
   const managedPhysicalIds = new Set<string>();
+  // Where a managed resource ends up, by physical id. A duplicate is dropped
+  // below rather than rendered twice, and anything that pointed at the
+  // duplicate has to be re-pointed at the survivor — dropping the node alone
+  // would take its edges with it, since `buildLiveGraphIr` discards an edge
+  // whose endpoints were not both observed.
+  const managedKeyOf = new Map<string, string>();
   for (const content of stored.values()) {
     const snap = JSON.parse(content) as LifecycleSnapshot;
-    for (const meta of Object.values(snap.resources ?? {})) {
+    const snapStack = snap.stack;
+    const snapQualifies = snapStack !== undefined && scopedStacks.has(snapStack);
+    for (const [id, meta] of Object.entries(snap.resources ?? {})) {
       if (!meta.ambient && !meta.referencedBy?.length && meta.physicalId) {
         managedPhysicalIds.add(meta.physicalId);
+        managedKeyOf.set(meta.physicalId, snapQualifies ? `${snapStack}::${id}` : id);
       }
     }
   }
@@ -97,32 +117,60 @@ export async function replaySnapshots(
     // collide, and none of them join the declared canvas, which qualifies.
     const stack = snapshot.stack;
     const qualify = stack !== undefined && scopedStacks.has(stack);
-    // Dependencies (#1273) are keyed by physical id and are account-level: the
-    // default VPC's route table is one resource however many stacks route
-    // through it. Qualifying those would split it per stack and break the
-    // edges into it.
-    const managed = (id: string, meta: { referencedBy?: string[]; ambient?: boolean }): string =>
-      qualify && !meta.ambient && !(meta.referencedBy && meta.referencedBy.length > 0)
-        ? `${stack}::${id}`
-        : id;
+    // Dependencies (#1273) and ambient resources (#1278) are keyed by physical
+    // id and are NOT stack-qualified: the default VPC's route table is one
+    // resource however many stacks route through it, and qualifying it would
+    // split it per stack and break the edges into it.
+    const unqualifiedByNature = (meta: { referencedBy?: string[]; ambient?: boolean }): boolean =>
+      Boolean(meta.ambient) || Boolean(meta.referencedBy && meta.referencedBy.length > 0);
+    // Region qualification (#1416) applies to exactly those, and never to a
+    // managed resource: an unscoped project's declared canvas joins on bare
+    // ids, so re-keying `web` to `us-east-1::web` would unjoin it from its own
+    // declaration.
+    const keyOf = (id: string, meta: { referencedBy?: string[]; ambient?: boolean; attributes?: Record<string, unknown> }): string => {
+      if (unqualifiedByNature(meta)) return merging ? unqualifiedKey(id, meta) : id;
+      return qualify ? `${stack}::${id}` : id;
+    };
     const resources: Record<string, (typeof snapshot.resources)[string]> = {};
+    // Duplicates dropped here, and where they went, so edges can follow.
+    const merged = new Map<string, string>();
     for (const [id, meta] of Object.entries(snapshot.resources ?? {})) {
-      const key = managed(id, meta);
-      if (key === id) {
-        // Ambient means "nothing manages this". Another stack managing it makes
-        // that false, and reporting it twice would inflate any count over it.
-        if (meta.ambient && meta.physicalId && managedPhysicalIds.has(meta.physicalId)) continue;
-        // Unqualified: account-level, so first sighting wins and the rest are
-        // the same resource seen again from another stack's snapshot.
-        if (seenUnqualified.has(id)) continue;
-        seenUnqualified.add(id);
+      const key = keyOf(id, meta);
+      if (!qualify || unqualifiedByNature(meta)) {
+        // Ambient means "nothing manages this", and being referenced means "the
+        // estate reaches this" — neither stops it being managed. When a stack
+        // manages the same physical resource, this entry is that resource seen
+        // from outside, and rendering both inflates any count over it.
+        //
+        // The dependency half of that was missing, and it was not cosmetic: a
+        // subnet declared by its stack was also recorded as `subnet-9af06b90`
+        // with `referencedBy`, so an estate with 13 subnets replayed as 16 and
+        // "which subnets have no network interfaces" answered 11 where the
+        // truth was 8. The three extra were occupied subnets whose second copy
+        // had no interface pointing at it — a duplicate reads as empty, because
+        // the edges resolved to the other one.
+        const duplicate = Boolean(meta.ambient) || Boolean(meta.referencedBy && meta.referencedBy.length > 0);
+        if (duplicate && meta.physicalId && managedPhysicalIds.has(meta.physicalId)) {
+          const survivor = managedKeyOf.get(meta.physicalId);
+          if (survivor && survivor !== key) merged.set(id, survivor);
+          continue;
+        }
+        // Unqualified: one resource per key, so first sighting wins and the
+        // rest are the same resource seen again from another stack's snapshot.
+        // The key carries the region when there is one, so "the same resource"
+        // no longer spans regions.
+        if (seenUnqualified.has(key)) continue;
+        seenUnqualified.add(key);
       }
       resources[key] = meta;
     }
     const known = new Set(Object.keys(snapshot.resources ?? {}));
     const requalify = (id: string): string => {
+      // A dropped duplicate's edges belong to the resource that survived it.
+      const survivor = merged.get(id);
+      if (survivor) return survivor;
       const meta = (snapshot.resources ?? {})[id];
-      return known.has(id) && meta ? managed(id, meta) : id;
+      return known.has(id) && meta ? keyOf(id, meta) : id;
     };
     const edges = (snapshot.edges ?? []).map((e) => ({ ...e, from: requalify(e.from), to: requalify(e.to) }));
     observations.push({

package/src/lifecycle/types.ts

@@ -97,6 +97,18 @@ export interface ResourceDigest {
 export interface BuildDigest {
   /** Per-resource digest keyed by logical name */
   resources: Record<string, ResourceDigest>;
+  /**
+   * chant #1442 — lexicon name → version that produced this build.
+   *
+   * Recorded once per lexicon rather than on every {@link ResourceDigest},
+   * which would repeat one string across every resource of a stack for no
+   * added information.
+   *
+   * Optional because a digest read back from an older snapshot will not have
+   * it. Absent and empty are different: absent means "recorded before this
+   * existed", empty means "recorded, and no plugins were loaded".
+   */
+  lexiconVersions?: Record<string, string>;
   /** Resource-level dependency graph */
   dependencies: Record<string, string[]>;
   /** Cross-lexicon output bridges from BuildManifest */
@@ -117,4 +129,18 @@ export interface DigestDiff {
   changed: string[];
   /** Resources where propsHash matches */
   unchanged: string[];
+  /**
+   * chant #1442 — lexicons whose VERSION moved between the two digests, even
+   * where every resource is unchanged.
+   *
+   * A build whose only difference is the lexicon that emitted it is a real
+   * difference: the lexicon is a generated artifact pinned to an upstream
+   * spec, so a bump can change output with no source change. Reported
+   * separately from `changed` because no resource's declaration moved — the
+   * interpreter did.
+   *
+   * Empty when neither digest recorded versions, so a comparison against a
+   * pre-#1442 snapshot reports nothing rather than inventing a change.
+   */
+  lexiconVersionChanges: Array<{ lexicon: string; previous?: string; current?: string }>;
 }

package/src/managed-fields.test.ts

@@ -155,6 +155,11 @@ describe("pruneByOwnership — the shared three-question rule", () => {
     chantOwned: new Set(["metadata.labels.tier"]),
     foreignOwned: new Set(["spec.replicas", "metadata.annotations.noise"]),
     foreignContested: new Set(["spec.replicas"]),
+    owners: new Map([
+      ["metadata.labels.tier", "chant"],
+      ["spec.replicas", "hpa-controller"],
+      ["metadata.annotations.noise", "kube-controller-manager"],
+    ]),
   };
 
   test("never prunes the declared side", () => {
@@ -177,3 +182,48 @@ describe("pruneByOwnership — the shared three-question rule", () => {
     expect(pruneByOwnership(node({ path: "spec.selector", pattern: "spec.selector" }), sets)).toBe(false);
   });
 });
+
+// #1189 — the three sets answer "which category owns this path". A reader needs
+// the other question: `hpa-controller` and `kubectl-client-side-apply` are the
+// same category and mean opposite things to an operator.
+describe("buildOwnershipSets — owning manager per path (#1189)", () => {
+  const entries = [
+    { manager: "chant", operation: "Apply", fieldsV1: { "f:metadata": { "f:labels": { "f:tier": {} } } } },
+    { manager: "hpa-controller", operation: "Apply", fieldsV1: { "f:spec": { "f:replicas": {} } } },
+    {
+      manager: "kubectl-client-side-apply",
+      operation: "Update",
+      fieldsV1: { "f:spec": { "f:template": { "f:spec": { "f:containers": {} } } } },
+    },
+  ];
+
+  test("records which manager owns each path", () => {
+    const sets = buildOwnershipSets(
+      entries,
+      { metadata: { labels: { tier: "web" } }, spec: { replicas: 3, template: { spec: { containers: [] } } } },
+      { metadata: { labels: { tier: "web" } }, spec: { replicas: 2 } },
+      (m) => m === "chant",
+    );
+    expect(sets.owners.get("metadata.labels.tier")).toBe("chant");
+    expect(sets.owners.get("spec.replicas")).toBe("hpa-controller");
+    expect(sets.owners.get("spec.template.spec.containers")).toBe("kubectl-client-side-apply");
+  });
+
+  test("the categories are unchanged by recording owners", () => {
+    const sets = buildOwnershipSets(
+      entries,
+      { metadata: { labels: { tier: "web" } }, spec: { replicas: 3, template: { spec: { containers: [] } } } },
+      { metadata: { labels: { tier: "web" } }, spec: { replicas: 2 } },
+      (m) => m === "chant",
+    );
+    expect(sets.chantOwned.has("metadata.labels.tier")).toBe(true);
+    expect(sets.foreignOwned.has("spec.replicas")).toBe(true);
+    // Declared AND foreign-owned — contested, so still diffable.
+    expect(sets.foreignContested.has("spec.replicas")).toBe(true);
+  });
+
+  test("is empty when the object carries no managedFields at all", () => {
+    const sets = buildOwnershipSets([], { spec: {} }, { spec: {} }, (m) => m === "chant");
+    expect(sets.owners.size).toBe(0);
+  });
+});

package/src/managed-fields.ts

@@ -144,6 +144,17 @@ export interface OwnershipSets {
   foreignOwned: ReadonlySet<string>;
   /** The subset of `foreignOwned` where the declared manifest also sets the path — drift-relevant despite foreign ownership. */
   foreignContested: ReadonlySet<string>;
+  /**
+   * Path → the name of the manager that owns it (#1189).
+   *
+   * The three sets above answer *which category* owns a path, which is all the
+   * prune rule needs. A reader needs the other question — "owned by
+   * `kubectl-client-side-apply`" and "owned by `hpa-controller`" are the same
+   * category and mean very different things to an operator. Last writer wins
+   * where several managers touch one path, matching what the API server itself
+   * reports.
+   */
+  owners: ReadonlyMap<string, string>;
 }
 
 function sameJson(a: unknown, b: unknown): boolean {
@@ -188,6 +199,9 @@ function walkOwnership(
   path: string,
   owned: Set<string>,
   contested: Set<string>,
+  /** Records path → manager as it walks (#1189); omitted by callers that only need the sets. */
+  owners?: Map<string, string>,
+  manager?: string,
 ): void {
   if (fieldsNode === null || typeof fieldsNode !== "object" || Array.isArray(fieldsNode)) return;
 
@@ -196,6 +210,7 @@ function walkOwnership(
       if (path !== "") {
         owned.add(path);
         if (declaredNode !== undefined) contested.add(path);
+        if (owners && manager) owners.set(path, manager);
       }
       continue;
     }
@@ -208,7 +223,8 @@ function walkOwnership(
       const childPath = joinField(path, name);
       owned.add(childPath);
       if (childDeclared !== undefined) contested.add(childPath);
-      walkOwnership(child, childLive, childDeclared, childPath, owned, contested);
+      if (owners && manager) owners.set(childPath, manager);
+      walkOwnership(child, childLive, childDeclared, childPath, owned, contested, owners, manager);
       continue;
     }
 
@@ -220,7 +236,8 @@ function walkOwnership(
       const childPath = joinIndex(path, idx);
       owned.add(childPath);
       if (childDeclared !== undefined) contested.add(childPath);
-      walkOwnership(child, childLive, childDeclared, childPath, owned, contested);
+      if (owners && manager) owners.set(childPath, manager);
+      walkOwnership(child, childLive, childDeclared, childPath, owned, contested, owners, manager);
       continue;
     }
 
@@ -255,7 +272,8 @@ function walkOwnership(
       const childPath = joinIndex(path, liveIdx);
       owned.add(childPath);
       if (childDeclared !== undefined) contested.add(childPath);
-      walkOwnership(child, childLive, childDeclared, childPath, owned, contested);
+      if (owners && manager) owners.set(childPath, manager);
+      walkOwnership(child, childLive, childDeclared, childPath, owned, contested, owners, manager);
       continue;
     }
     // An unrecognized prefix (a future fieldsV1 encoding) — skip.
@@ -286,6 +304,7 @@ export function buildOwnershipSets(
   const chantOwned = new Set<string>();
   const foreignOwned = new Set<string>();
   const foreignContested = new Set<string>();
+  const owners = new Map<string, string>();
 
   for (const entry of entries) {
     if (typeof entry.manager !== "string" || entry.manager.length === 0) continue;
@@ -294,13 +313,13 @@ export function buildOwnershipSets(
     if (isChantManager(entry.manager)) {
       // Chant-owned paths are always diffable, regardless of who else is
       // involved — "contested" only matters for a *foreign* owner.
-      walkOwnership(entry.fieldsV1, liveRoot, declaredRoot, "", chantOwned, new Set());
+      walkOwnership(entry.fieldsV1, liveRoot, declaredRoot, "", chantOwned, new Set(), owners, entry.manager);
     } else {
-      walkOwnership(entry.fieldsV1, liveRoot, declaredRoot, "", foreignOwned, foreignContested);
+      walkOwnership(entry.fieldsV1, liveRoot, declaredRoot, "", foreignOwned, foreignContested, owners, entry.manager);
     }
   }
 
-  return { chantOwned, foreignOwned, foreignContested };
+  return { chantOwned, foreignOwned, foreignContested, owners };
 }
 
 /**

package/src/meta/peer-deps.test.ts

@@ -4,26 +4,123 @@ import { fileURLToPath } from "url";
 import { join } from "path";
 
 /**
- * The lexicon packages are published in lockstep with core, so their
- * `@intentius/*` peerDependencies must track the current core version. They were
- * once frozen at `^0.1.0` while shipping at 0.7.0, which made a clean
- * `npm install` fail (#411). This locks the invariant so it can't drift again.
+ * The lexicon packages declare `@intentius/*` peers, and a range frozen at an
+ * old version makes a clean `npm install` fail — they were once stuck at
+ * `^0.1.0` while shipping at 0.7.0 (#411). This locks the invariant so it
+ * cannot drift again.
+ *
+ * The range must track the version of the package that PROVIDES the peer, not
+ * core's version for every peer alike. Two providers exist: core backs
+ * `@intentius/chant`, and `lexicons/github` backs
+ * `@intentius/chant-lexicon-github` (forgejo and gitlab both peer on it).
+ * `just release-lexicon` writes exactly that — `^$core` for the core peer,
+ * `^$github_lexicon` for the github one — because a single-lexicon release
+ * moves one package without moving the others, so pinning every peer to core
+ * would demand a version that was never published.
+ *
+ * Asserting against core for both passed only while the whole workspace
+ * happened to sit on one version. `just release-lexicon github patch` alone is
+ * enough to separate them, and the old assertion then failed on a tree the
+ * release recipe had written correctly.
  */
 const repoRoot = fileURLToPath(new URL("../../../../", import.meta.url));
-const coreVersion = JSON.parse(readFileSync(join(repoRoot, "packages/core/package.json"), "utf-8")).version as string;
-const expected = `^${coreVersion}`;
+
+function versionOf(packageDir: string): string {
+  return JSON.parse(readFileSync(join(repoRoot, packageDir, "package.json"), "utf-8")).version as string;
+}
 
 const lexiconsDir = join(repoRoot, "lexicons");
 const lexicons = readdirSync(lexiconsDir).filter((name) => existsSync(join(lexiconsDir, name, "package.json")));
 
-describe("lexicon peerDependencies track the core version", () => {
-  test.each(lexicons)("%s pins @intentius/* peers to the current version", (lexicon) => {
-    const pkg = JSON.parse(readFileSync(join(lexiconsDir, lexicon, "package.json"), "utf-8"));
-    const peers: Record<string, string> = pkg.peerDependencies ?? {};
-    for (const [dep, range] of Object.entries(peers)) {
-      if (dep.startsWith("@intentius/")) {
-        expect(range, `${lexicon}: peer ${dep} should be ${expected}`).toBe(expected);
-      }
+/** Which workspace package publishes each `@intentius/*` peer a lexicon can declare. */
+const providerDir: Record<string, string> = {
+  "@intentius/chant": join("packages", "core"),
+  "@intentius/chant-lexicon-github": join("lexicons", "github"),
+};
+
+function intentiusPeersOf(lexicon: string): [string, string][] {
+  const pkg = JSON.parse(readFileSync(join(lexiconsDir, lexicon, "package.json"), "utf-8"));
+  const peers: Record<string, string> = pkg.peerDependencies ?? {};
+  // Third-party peers (typescript) aren't ours to track.
+  return Object.entries(peers).filter(([dep]) => dep.startsWith("@intentius/"));
+}
+
+describe("lexicon peerDependencies track the version of the package providing them", () => {
+  test.each(lexicons)("%s pins @intentius/* peers to their provider's version", (lexicon) => {
+    for (const [dep, range] of intentiusPeersOf(lexicon)) {
+      const dir = providerDir[dep];
+      expect(
+        dir,
+        `${lexicon} peers ${dep}, which no workspace package is registered as providing — ` +
+          `add it to providerDir so its range is checked`,
+      ).toBeDefined();
+
+      expect(range, `${lexicon}: peer ${dep} should be ^${versionOf(dir)}`).toBe(`^${versionOf(dir)}`);
     }
   });
+
+  test("every @intentius/* peer declared anywhere has a registered provider", () => {
+    // Guards the map itself: a new cross-lexicon peer added without a
+    // providerDir entry would be reported per-lexicon above, but only if that
+    // lexicon is reached — this states the whole set in one place.
+    const declared = new Set(lexicons.flatMap((l) => intentiusPeersOf(l).map(([dep]) => dep)));
+    expect([...declared].sort()).toEqual(Object.keys(providerDir).sort());
+  });
+
+});
+
+/**
+ * The rule itself, over fixtures rather than the real tree — the tree sits on
+ * one version today, so it cannot demonstrate the skew this exists to handle.
+ */
+function rangeViolations(
+  versions: Record<string, string>,
+  peers: Record<string, Record<string, string>>,
+): string[] {
+  const out: string[] = [];
+  for (const [lexicon, declared] of Object.entries(peers)) {
+    for (const [dep, range] of Object.entries(declared)) {
+      if (!dep.startsWith("@intentius/")) continue;
+      if (range !== `^${versions[dep]}`) out.push(`${lexicon}:${dep}`);
+    }
+  }
+  return out;
+}
+
+describe("the provider-aware rule, over fixtures", () => {
+  // `just release-lexicon github patch`: github moves, core does not, and the
+  // recipe rewrites forgejo's github peer to the new github version.
+  const skewed = { "@intentius/chant": "0.38.0", "@intentius/chant-lexicon-github": "0.38.1" };
+
+  test("accepts a provider ahead of core when its dependents track it", () => {
+    expect(
+      rangeViolations(skewed, {
+        forgejo: { "@intentius/chant": "^0.38.0", "@intentius/chant-lexicon-github": "^0.38.1" },
+      }),
+    ).toEqual([]);
+    // This is the case the old core-for-everything assertion rejected: it
+    // demanded ^0.38.0 for the github peer, on a tree release-lexicon wrote.
+    expect(`^${skewed["@intentius/chant-lexicon-github"]}`).not.toBe(`^${skewed["@intentius/chant"]}`);
+  });
+
+  test("still catches a range left behind by its provider", () => {
+    expect(
+      rangeViolations(skewed, {
+        forgejo: { "@intentius/chant": "^0.38.0", "@intentius/chant-lexicon-github": "^0.38.0" },
+      }),
+    ).toEqual(["forgejo:@intentius/chant-lexicon-github"]);
+  });
+
+  test("catches the #411 case — every range frozen at an old version", () => {
+    expect(
+      rangeViolations(skewed, {
+        aws: { "@intentius/chant": "^0.1.0" },
+        k8s: { "@intentius/chant": "^0.1.0" },
+      }),
+    ).toEqual(["aws:@intentius/chant", "k8s:@intentius/chant"]);
+  });
+
+  test("ignores third-party peers", () => {
+    expect(rangeViolations(skewed, { aws: { typescript: ">=5.0.0" } })).toEqual([]);
+  });
 });