@shortlink-org/portolan 0.3.0 → 0.4.0

package/scripts/README.md

@@ -37,7 +37,9 @@ and validates the union. Nothing here draws anything.
 - Read a plugin's stdout for anything but the one message, or its stderr for
   anything but notes; a warning is kept beside the step in the build report.
 - Draw the C4 model: `gen-likec4.mjs` writes `likec4/` from the same merged
-  catalog, and the site draws.
+  catalog, and the site draws. It runs as the last step of `gen.mjs` -
+  written, or in check mode held to the catalog like every generated page -
+  and on its own before `dev`.
 
 ## Files
 

package/scripts/delivery-presets.mjs

@@ -79,11 +79,23 @@ function repositoryName(remote, workspace) {
   return clean.split(/[/:]/).filter(Boolean).pop() || relative(dirname(workspace), workspace) || "repository";
 }
 
+// One ref listing answers three questions (where origin/HEAD points, whether
+// main or master exists) instead of one git process per question: a preview
+// spawns git while the test suite and the site build are already competing
+// for the machine, and every spawn costs seconds there.
 function defaultBranch(workspace) {
-  const remoteHead = git(workspace, ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]);
-  if (remoteHead.startsWith("origin/")) return remoteHead.slice("origin/".length);
+  const refs = new Map();
+  for (const line of git(workspace, [
+    "for-each-ref", "--format=%(refname)%09%(symref)",
+    "refs/remotes/origin/HEAD", "refs/heads/main", "refs/heads/master",
+  ]).split("\n")) {
+    const [name, symref = ""] = line.split("\t");
+    if (name) refs.set(name, symref);
+  }
+  const remoteHead = refs.get("refs/remotes/origin/HEAD") ?? "";
+  if (remoteHead.startsWith("refs/remotes/origin/")) return remoteHead.slice("refs/remotes/origin/".length);
   for (const candidate of ["main", "master"]) {
-    if (git(workspace, ["rev-parse", "--verify", `refs/heads/${candidate}`])) return candidate;
+    if (refs.has(`refs/heads/${candidate}`)) return candidate;
   }
   return git(workspace, ["branch", "--show-current"]) || "main";
 }
@@ -316,8 +328,29 @@ function mergeGitlab(existing, features) {
   return { content: block ? `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${block}` : existing };
 }
 
+// A file that is entirely new or entirely gone needs no diff algorithm: every
+// line is added or removed. Writing that hunk here saves a git process per
+// file, and a GitHub preset is mostly such files.
+function wholeFileDiff(path, content, sign) {
+  const body = content.endsWith("\n") ? content.slice(0, -1) : content;
+  const lines = body.split("\n");
+  const count = lines.length === 1 ? "1" : `1,${lines.length}`;
+  const range = sign === "+" ? `-0,0 +${count}` : `-${count} +0,0`;
+  return [
+    `diff --git a/${path} b/${path}`,
+    `--- a/${path}`,
+    `+++ b/${path}`,
+    `@@ ${range} @@`,
+    ...lines.map((line) => `${sign}${line}`),
+    ...(content.endsWith("\n") ? [] : ["\"]),
+    "",
+  ].join("\n");
+}
+
 function textDiff(path, before, after) {
   if (before === after) return "";
+  if (before === "") return wholeFileDiff(path, after, "+");
+  if (after === "") return wholeFileDiff(path, before, "-");
   const holder = mkdtempSync(join(tmpdir(), "portolan-preset-diff-"));
   const left = join(holder, "before");
   const right = join(holder, "after");

package/scripts/gen-likec4.mjs

@@ -7,16 +7,24 @@
 //
 //   node scripts/gen-likec4.mjs
 
-import { writeFileSync, mkdirSync } from "node:fs";
+import { writeFileSync, mkdirSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import { loadCatalog } from "./catalog-sources.mjs";
 import reserved from "../src/likec4/reserved.json" with { type: "json" };
 import { catalogProfiles } from "../src/catalog-profile.ts";
+import { allDeployments, deploys, environmentOf } from "../src/catalog-model.ts";
 
 // Every source, not one file: a service that publishes its own facts gets a
 // C4 view like any other, and generating from a single file would leave it out
 // of the pictures while the rest of the app knows about it.
-const { catalog, manifest } = await loadCatalog();
+//
+// The sources come back as files rather than being written here, so that
+// `gen` can settle them the way it settles every generated page - written,
+// or in check mode compared and reported as drift - and `likec4:gen` can
+// still write them on its own before the dev server starts.
+export async function likec4Sources({ catalog, manifest }) {
 const profiles = catalogProfiles(manifest);
 
 // --- ids (mirrors src/likec4/ids.ts; kept in step by src/likec4/ids.test.ts) ---
@@ -36,6 +44,8 @@ const flowCrossViewId = (flow) => `${flowViewId(flow)}_cross`;
 const contextViewId = (c) => `ctx_${safeId(c.id)}`;
 const serviceViewId = (s) => `svc_${safeId(s.id)}`;
 const serviceInsideViewId = (s) => `${serviceViewId(s)}_inside`;
+const deploymentViewId = (environment) => `deploy_${safeId(environment)}`;
+const serviceDeployViewId = (s) => `deploy_svc_${safeId(s.id)}`;
 const LANDSCAPE_VIEW = "landscape";
 const CONTAINERS_VIEW = "containers";
 const profileLandscapeViewId = (profile) =>
@@ -248,6 +258,18 @@ spec.push("  element unknown {");
 spec.push("    style { shape rectangle  color unresolved  border dashed }");
 spec.push("  }");
 spec.push("");
+// Where a service runs (portolan.0012): three nested places, drawn as
+// frames around the instances they hold, from the deployer's snapshot.
+spec.push("  deploymentNode environment {");
+spec.push("    style { shape rectangle  opacity 5%  border dashed }");
+spec.push("  }");
+spec.push("  deploymentNode cluster {");
+spec.push("    style { shape rectangle  opacity 10%  border dashed  color muted }");
+spec.push("  }");
+spec.push("  deploymentNode namespace {");
+spec.push("    style { shape rectangle  opacity 15%  color muted }");
+spec.push("  }");
+spec.push("");
 for (const kind of RELATION_KINDS) spec.push(`  relationship ${kind}`);
 spec.push("}");
 
@@ -1050,20 +1072,131 @@ for (const flow of catalog.flows) {
   views.push("  }");
   views.push("");
 }
+// ---------------------------------------------------------------------------
+// deployment: where the services run (portolan.0012)
+// ---------------------------------------------------------------------------
+// One tree per environment, the cluster and the namespace as frames inside
+// it, and an instance of the service in the namespace it stands in. The
+// relations are the model's own: LikeC4 draws between two instances what the
+// model declares between their elements, so an environment's picture shows
+// the calls both ends of which are deployed there, and nothing a reader
+// would have to fold by hand. One view per environment, and one per service
+// that runs somewhere: its instances with the frames around them.
+const deployment = [];
+const deployTree = new Map(); // environment -> cluster -> namespace -> Map(service id -> {service, deployment})
+const placesOfService = new Map(); // service id -> [fqn of instance]
+const framesOfEnvironment = new Map(); // environment -> Set(fqn of every node under it)
+for (const placed of allDeployments(catalog)) {
+  for (const service of allServices) {
+    if (!deploys(placed, service)) continue;
+    const env = environmentOf(placed);
+    const clusters = deployTree.get(env) ?? new Map();
+    deployTree.set(env, clusters);
+    const namespaces = clusters.get(placed.cluster) ?? new Map();
+    clusters.set(placed.cluster, namespaces);
+    const instances = namespaces.get(placed.namespace) ?? new Map();
+    namespaces.set(placed.namespace, instances);
+    // Two Applications of one service in one place is one instance: the
+    // picture is about where it runs, and it runs there once.
+    if (!instances.has(service.id)) instances.set(service.id, { service, deployment: placed });
+  }
+}
+const environments = [...deployTree.keys()].sort();
+const sorted = (map) => [...map.keys()].sort();
+if (environments.length > 0) {
+  deployment.push("deployment {");
+  for (const env of environments) {
+    const envId = safeId(env);
+    deployment.push(`  environment ${envId} ${q(env)} {`);
+    const clusters = deployTree.get(env);
+    for (const cluster of sorted(clusters)) {
+      const path = [envId];
+      let indent = "    ";
+      if (cluster) {
+        path.push(safeId(cluster));
+        deployment.push(`${indent}cluster ${safeId(cluster)} ${q(cluster)} {`);
+        indent += "  ";
+      }
+      const namespaces = clusters.get(cluster);
+      for (const namespace of sorted(namespaces)) {
+        const nsPath = [...path];
+        let nsIndent = indent;
+        if (namespace) {
+          nsPath.push(safeId(namespace));
+          deployment.push(`${nsIndent}namespace ${safeId(namespace)} ${q(namespace)} {`);
+          nsIndent += "  ";
+        }
+        const instances = namespaces.get(namespace);
+        for (const serviceId of sorted(instances)) {
+          const { service, deployment: placed } = instances.get(serviceId);
+          const instanceId = safeId(service.id);
+          const revision = /^[0-9a-f]{40}$/.test(placed.revision) ? placed.revision.slice(0, 7) : placed.revision;
+          const about = [placed.name, revision ? `at ${revision}` : ""].filter(Boolean).join(" ");
+          deployment.push(`${nsIndent}${instanceId} = instanceOf ${fqn(service.id)} {`);
+          deployment.push(`${nsIndent}  description ${q(about)}`);
+          deployment.push(`${nsIndent}}`);
+          const places = placesOfService.get(service.id) ?? [];
+          places.push([...nsPath, instanceId].join("."));
+          placesOfService.set(service.id, places);
+          const frames = framesOfEnvironment.get(env) ?? new Set();
+          for (let depth = 2; depth <= nsPath.length; depth += 1) frames.add(nsPath.slice(0, depth).join("."));
+          frames.add([...nsPath, instanceId].join("."));
+          framesOfEnvironment.set(env, frames);
+        }
+        if (namespace) deployment.push(`${indent}}`);
+      }
+      if (cluster) deployment.push("    }");
+    }
+    deployment.push("  }");
+  }
+  deployment.push("}");
+
+  views.push("");
+  for (const env of environments) {
+    // Every frame under the environment, named one by one rather than as
+    // `env.**`: a descendant wildcard draws the instances alone and folds
+    // the cluster and namespace away, and where a thing runs is the point.
+    views.push(`  deployment view ${deploymentViewId(env)} {`);
+    views.push(`    title ${q(`${env} — deployed`)}`);
+    views.push(`    include ${[...framesOfEnvironment.get(env)].join(", ")}`);
+    views.push("  }");
+  }
+  for (const service of allServices) {
+    const places = placesOfService.get(service.id);
+    if (!places) continue;
+    // The frames around each instance, named one by one: a node named with
+    // its children is drawn as the frame it is, and a reader can tell the
+    // two boxes apart by where they sit.
+    const frames = new Set();
+    for (const place of places) {
+      const segments = place.split(".");
+      for (let depth = 1; depth <= segments.length; depth += 1) frames.add(segments.slice(0, depth).join("."));
+    }
+    views.push(`  deployment view ${serviceDeployViewId(service)} {`);
+    views.push(`    title ${q(`${service.name} — where it runs`)}`);
+    views.push(`    include ${[...frames].join(", ")}`);
+    views.push("  }");
+  }
+}
 views.push("}");
 
-mkdirSync("likec4", { recursive: true });
-writeFileSync("likec4/spec.c4", `${spec.join("\n")}\n`);
-writeFileSync(
-  "likec4/model.c4",
-  `// GENERATED — do not edit.\n${model.join("\n")}\n`,
-);
-writeFileSync(
-  "likec4/views.c4",
-  `// GENERATED — do not edit.\n${views.join("\n")}\n`,
-);
+return [
+  { name: "deployment.c4", contents: `// GENERATED — do not edit.\n${deployment.join("\n")}\n` },
+  { name: "spec.c4", contents: `${spec.join("\n")}\n` },
+  { name: "model.c4", contents: `// GENERATED — do not edit.\n${model.join("\n")}\n` },
+  { name: "views.c4", contents: `// GENERATED — do not edit.\n${views.join("\n")}\n` },
+];
+}
 
-console.log(
-  `wrote likec4/spec.c4, likec4/model.c4, likec4/views.c4 ` +
-    `(${catalog.flows.length * 2} dynamic views, ${relations.length} relations)`,
-);
+// Run as a script - `npm run likec4:gen`, before the dev server starts - the
+// sources are written under likec4/ here and now.
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const bundle = await loadCatalog();
+  const files = await likec4Sources(bundle);
+  mkdirSync("likec4", { recursive: true });
+  for (const file of files) writeFileSync(join("likec4", file.name), file.contents);
+  console.log(
+    `wrote ${files.map((file) => `likec4/${file.name}`).join(", ")} ` +
+      `(${bundle.catalog.flows.length * 2} dynamic views)`,
+  );
+}

package/scripts/gen-likec4.test.mjs

@@ -6,6 +6,8 @@ import { execFileSync } from "node:child_process";
 
 import { describe, expect, it } from "vitest";
 
+import { likec4Sources } from "./gen-likec4.mjs";
+
 const generator = fileURLToPath(new URL("./gen-likec4.mjs", import.meta.url));
 const likec4 = join(
   dirname(dirname(generator)),
@@ -38,9 +40,22 @@ function generate(catalog) {
     spec: readFileSync(join(root, "likec4", "spec.c4"), "utf8"),
     model: readFileSync(join(root, "likec4", "model.c4"), "utf8"),
     views: readFileSync(join(root, "likec4", "views.c4"), "utf8"),
+    deployment: readFileSync(join(root, "likec4", "deployment.c4"), "utf8"),
   };
 }
 
+describe("the LikeC4 generator as a step of gen", () => {
+  it("hands back the four sources as files rather than writing them, so gen can settle them", async () => {
+    const files = await likec4Sources({
+      catalog: { generatedAt: "2026-09-06T00:00:00Z", commit: "0", adrs: [], defs: {}, contexts: [], flows: [] },
+      manifest: { sources: ["data/*.json"] },
+    });
+    expect(files.map((file) => file.name)).toEqual(["deployment.c4", "spec.c4", "model.c4", "views.c4"]);
+    expect(files.find((file) => file.name === "views.c4")?.contents).toContain("view landscape");
+    expect(files.every((file) => file.contents.endsWith("\n"))).toBe(true);
+  });
+});
+
 describe("the LikeC4 generator", () => {
   it("emits valid fallback views for an empty catalog", () => {
     const { model, views } = generate({ contexts: [], flows: [] });
@@ -432,4 +447,85 @@ describe("the LikeC4 generator", () => {
       /view svc_shop_oms of shop\.oms \{\n    title[^\n]*\n    include \*, -> \*, \* ->\n  \}/,
     );
   });
+
+  it("places every deployed service in its environment, cluster and namespace, and draws the frames by name", () => {
+    const service = (slug, path) => ({
+      id: `shop.${slug}`,
+      slug,
+      name: slug,
+      repo: "github.com/acme/shop",
+      path,
+      readme: "",
+      provides: [],
+      consumes: [],
+      aggregates: [],
+    });
+    const placed = (name, environment, cluster, namespace, path) => ({
+      id: `argocd/${name}`,
+      name,
+      project: "shop",
+      environment,
+      cluster,
+      namespace,
+      repo: "github.com/acme/shop",
+      path,
+      targetRevision: "main",
+      revision: "a".repeat(40),
+      tool: "kustomize",
+      url: `https://argocd.example.com/applications/argocd/${name}`,
+    });
+    const { spec, deployment, views } = generate({
+      contexts: [
+        {
+          id: "shop",
+          slug: "shop",
+          name: "Shop",
+          summary: "",
+          services: [service("cart", "services/cart"), service("oms", "services/oms")],
+        },
+      ],
+      flows: [],
+      deployments: [
+        placed("cart", "prod", "in-cluster", "shop", "services/cart/deploy"),
+        placed("cart-staging", "staging", "staging-eu", "shop", "services/cart/deploy"),
+        placed("oms", "prod", "in-cluster", "shop", "services/oms/deploy"),
+        // Deploys a repository nobody in the estate claims: placed nowhere.
+        placed("grafana", "prod", "in-cluster", "monitoring", "charts/grafana"),
+      ],
+    });
+    expect(spec).toContain("deploymentNode environment");
+    expect(deployment).toContain(
+      "  environment prod 'prod' {\n" +
+        "    cluster in_cluster 'in-cluster' {\n" +
+        "      namespace shop 'shop' {\n" +
+        "        shop_cart = instanceOf shop.cart {\n" +
+        "          description 'cart at aaaaaaa'\n" +
+        "        }\n" +
+        "        shop_oms = instanceOf shop.oms {",
+    );
+    expect(deployment).toContain("environment staging 'staging'");
+    expect(deployment).not.toContain("grafana");
+    expect(deployment).not.toContain("monitoring");
+    // The environment view names every frame under it; a descendant wildcard
+    // would fold the cluster and the namespace away.
+    expect(views).toContain(
+      "  deployment view deploy_prod {\n" +
+        "    title 'prod — deployed'\n" +
+        "    include prod.in_cluster, prod.in_cluster.shop, prod.in_cluster.shop.shop_cart, prod.in_cluster.shop.shop_oms\n" +
+        "  }",
+    );
+    expect(views).toContain(
+      "  deployment view deploy_svc_shop_cart {\n" +
+        "    title 'cart — where it runs'\n" +
+        "    include prod, prod.in_cluster, prod.in_cluster.shop, prod.in_cluster.shop.shop_cart, staging, staging.staging_eu, staging.staging_eu.shop, staging.staging_eu.shop.shop_cart\n" +
+        "  }",
+    );
+    expect(views).not.toContain("deploy_svc_shop_grafana");
+  });
+
+  it("writes an empty deployment file and no deployment view when nothing is placed", () => {
+    const { deployment, views } = generate({ contexts: [], flows: [] });
+    expect(deployment.trim()).toBe("// GENERATED — do not edit.");
+    expect(views).not.toContain("deployment view");
+  });
 });

package/scripts/gen.mjs

@@ -36,6 +36,7 @@ import {
 } from "./output-path.mjs";
 import { builtinPlugin } from "./builtin-plugins.mjs";
 import { diagnoseWarnings } from "./warning-policy.mjs";
+import { likec4Sources } from "./gen-likec4.mjs";
 
 const PORTOLAN_VERSION = "0.1.0";
 const EVENTS = process.env.PORTOLAN_EVENTS === "1";
@@ -63,6 +64,10 @@ function event(value) {
 // in one run is drift that never happened.
 const MANIFEST = ".portolan-manifest";
 
+// The one step no manifest declares: the app's own pictures, generated from
+// every source, keyed by its own name in likec4/.portolan-manifest.
+const LIKEC4_STEP = { plugin: "likec4", out: "likec4", key: "likec4" };
+
 const check = process.argv.includes("--check");
 const manifestSha256 = createHash("sha256")
   .update(readFileSync("portolan.json"))
@@ -194,6 +199,15 @@ async function generate() {
     { inputs: generated.sources.map((source) => source.path), excludes: [] });
   }
 
+  // The LikeC4 sources are pages of the catalog like any the generators
+  // write: committed, reviewed as a diff, and held to the catalog by the
+  // check. They used to be written only before the dev server started,
+  // which left a flow a verifier had just changed with a picture of the
+  // flow before - and a run from the page with no picture of a new flow.
+  await executeStep("generate", LIKEC4_STEP, "likec4 → likec4", async () => ({
+    files: await likec4Sources({ catalog, manifest }),
+  }), { inputs: sources.map((source) => source.path), excludes: [] });
+
   sweepAll();
 }
 
@@ -208,6 +222,17 @@ function sweepAll() {
   }
 }
 
+/**
+ * The keys of the steps that write into a directory this run: the manifest's,
+ * and the likec4 step's in its own directory, which no manifest declares and
+ * the sweep would otherwise take for a step that was dropped.
+ */
+function liveKeysIn(out) {
+  const live = new Set(keys.liveIn(out));
+  if (out === LIKEC4_STEP.out) live.add(LIKEC4_STEP.key);
+  return live;
+}
+
 /** Every file the sweep would remove, in every directory a step writes into. */
 function staleAll() {
   const outs = new Set(
@@ -230,7 +255,7 @@ function staleAll() {
  */
 function staleIn(out) {
   const listing = previous(out);
-  const live = keys.liveIn(out);
+  const live = liveKeysIn(out);
   const dead = Object.keys(listing).filter((key) => !live.has(key));
   if (dead.length === 0) return [];
 
@@ -267,7 +292,7 @@ async function executeStep(phase, step, label, work, reads) {
       project: projectForStep(step),
       phase,
     });
-    const changes = apply(files, step.out, keys.keyOf(step), check);
+    const changes = apply(files, step.out, step.key ?? keys.keyOf(step), check);
     const since = changes.length > 0 ? whyChanged(step, files.map((file) => join(step.out, file.name)), reads) : null;
     const changed = summarise(label, files, changes, diagnostics, since);
     drifted = changed || drifted;
@@ -436,6 +461,8 @@ function whyChanged(step, outputs, reads) {
 
 /** Whether the manifest at `commit` told this step the same thing it is told now. */
 function stepEntryChanged(commit, step) {
+  // A step no manifest declares has no entry to have changed.
+  if (step.key) return false;
   let then;
   try {
     then = JSON.parse(fileAt(process.cwd(), commit, "portolan.json"));
@@ -552,7 +579,7 @@ function apply(files, out, key, checkOnly) {
 function sweep(out, checkOnly) {
   const changes = [];
   const listing = previous(out);
-  const live = keys.liveIn(out);
+  const live = liveKeysIn(out);
   const dead = Object.keys(listing).filter((key) => !live.has(key));
   if (dead.length === 0) return changes;
 

package/scripts/gitops-example.test.mjs

@@ -0,0 +1,108 @@
+// The example GitOps tree, rendered the way Argo CD would render it.
+//
+// Every overlay under examples/gitops/envs/*/shop/* is built with kustomize
+// - the binary when it is on the PATH, kubectl's copy otherwise - and what
+// the environment says (the tag, the replica count, the variable) has to be
+// what comes out. Then the tree is held to the snapshot in examples/argocd:
+// an overlay that no Application in the snapshot deploys, or an Application
+// pointing at a directory that is not here, is the two examples drifting
+// apart, which is the one thing an example must not do.
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+const gitops = join(root, "examples", "gitops");
+
+/** kustomize itself, else the copy kubectl ships; the output is the same. */
+function kustomizeCommand() {
+  for (const candidate of ["kustomize"]) {
+    try {
+      execFileSync(candidate, ["version"], { stdio: "ignore" });
+      return [candidate, "build"];
+    } catch {
+      // Not on the PATH.
+    }
+  }
+  return ["kubectl", "kustomize"];
+}
+
+const [command, ...args] = kustomizeCommand();
+const build = (dir) => execFileSync(command, [...args, dir], { encoding: "utf8" });
+
+/** `<env>/shop/<service>` for every overlay in the tree, sorted. */
+function overlays() {
+  const out = [];
+  for (const env of readdirSync(join(gitops, "envs")).sort()) {
+    const shop = join(gitops, "envs", env, "shop");
+    if (!existsSync(shop)) continue;
+    for (const service of readdirSync(shop).sort()) {
+      if (existsSync(join(shop, service, "kustomization.yaml"))) out.push({ env, service, dir: join(shop, service) });
+    }
+  }
+  return out;
+}
+
+describe("the example GitOps tree", () => {
+  it("has an overlay for cart in both environments and pricing in prod only", () => {
+    expect(overlays().map((o) => `${o.env}/${o.service}`)).toEqual(["prod/cart", "prod/pricing", "staging/cart"]);
+  });
+
+  it("renders cart in prod at the tag prod runs, three replicas, labelled with the environment", () => {
+    const rendered = build(join(gitops, "envs", "prod", "shop", "cart"));
+    expect(rendered).toContain("image: ghcr.io/shortlink-org/cart:2.1.0");
+    expect(rendered).toContain("replicas: 3");
+    expect(rendered).toContain("env: prod");
+    expect(rendered).toContain("app.kubernetes.io/part-of: shop");
+    // The base's names and namespace survive the overlay.
+    expect(rendered).toMatch(/kind: Ingress[\s\S]*namespace: shop/);
+  });
+
+  it("renders cart in staging as the release candidate, one replica, NODE_ENV restated and nothing else lost", () => {
+    const rendered = build(join(gitops, "envs", "staging", "shop", "cart"));
+    expect(rendered).toContain("image: ghcr.io/shortlink-org/cart:2.2.0-rc.1");
+    expect(rendered).toContain("replicas: 1");
+    expect(rendered).toMatch(/name: NODE_ENV\n\s+value: staging/);
+    // Merged by name: the other variables the base declares are still there.
+    expect(rendered).toMatch(/name: PRICING_ADDR\n\s+value: pricing\.shop\.svc:9090/);
+    expect(rendered).not.toContain("value: production");
+  });
+
+  it("renders pricing in prod with the longer cache and the secret untouched", () => {
+    const rendered = build(join(gitops, "envs", "prod", "shop", "pricing"));
+    expect(rendered).toContain("image: ghcr.io/shortlink-org/pricing:1.4.2");
+    expect(rendered).toContain("PRICE_LIST_TTL: 1h");
+    expect(rendered).toContain("OTEL_EXPORTER_OTLP_ENDPOINT");
+    expect(rendered).toContain("kind: Secret");
+  });
+
+  it("is what the snapshot in examples/argocd was recorded from", () => {
+    const snapshot = JSON.parse(readFileSync(join(root, "examples", "argocd", "argocd.apps.json"), "utf8"));
+    const placed = snapshot.deployments.filter((d) => d.project === "shop");
+    // One Application per overlay, named as the ApplicationSet names it,
+    // pointing at the overlay, labelled onto the service.
+    expect(placed.map((d) => [d.name, d.environment, d.path, d.service]).sort()).toEqual(
+      overlays().map((o) => [`shop-${o.service}-${o.env}`, o.env, `examples/gitops/envs/${o.env}/shop/${o.service}`, `shop.${o.service}`]).sort(),
+    );
+    // The image the snapshot says runs is the image the overlay renders.
+    for (const deployment of placed) {
+      const rendered = build(join(root, deployment.path));
+      for (const image of deployment.images ?? []) expect(rendered).toContain(`image: ${image}`);
+    }
+    // The clusters the environments name are the ones the snapshot places in.
+    for (const { env } of overlays()) {
+      const cluster = readFileSync(join(gitops, "envs", env, "cluster.yaml"), "utf8").match(/^\s+name: (.+)$/m)?.[1];
+      for (const deployment of placed.filter((d) => d.environment === env)) expect(deployment.cluster).toBe(cluster);
+    }
+  });
+
+  it("names every Application in the shop ApplicationSet with the labels the fetcher places by", () => {
+    const appset = readFileSync(join(gitops, "appsets", "shop.yaml"), "utf8");
+    expect(appset).toContain("app.kubernetes.io/part-of: shop");
+    expect(appset).toContain('app.kubernetes.io/name: "{{.path.basename}}"');
+    expect(appset).toContain('name: "shop-{{.path.basename}}-{{.env}}"');
+    expect(appset).toContain("path: examples/gitops/envs/*/cluster.yaml");
+  });
+});