@intentius/chant-lexicon-cpln 0.53.0

package/src/plugin.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+import { isLexiconPlugin } from "@intentius/chant/lexicon";
+import { cplnPlugin } from "./plugin";
+import { cplnAuditCatalog } from "./lint/audit-catalog";
+import { KINDS } from "./kinds";
+
+describe("cpln plugin", () => {
+  it("is a valid LexiconPlugin", () => {
+    expect(isLexiconPlugin(cplnPlugin)).toBe(true);
+  });
+
+  it("has the correct name and serializer", () => {
+    expect(cplnPlugin.name).toBe("cpln");
+    expect(cplnPlugin.serializer.name).toBe("cpln");
+    expect(cplnPlugin.serializer.rulePrefix).toBe("CPL");
+  });
+
+  it("registers lint rules and post-synth checks", () => {
+    expect(cplnPlugin.lintRules?.()?.length).toBeGreaterThan(0);
+    expect(cplnPlugin.postSynthChecks?.()?.length).toBeGreaterThanOrEqual(15);
+  });
+
+  it("gives every rule an id under the declared prefix", () => {
+    // Ids must not collide when lexicons load together, which is what the
+    // prefix is for. A stray id here is invisible until two lexicons meet.
+    const prefixes = [cplnPlugin.serializer.rulePrefix, ...(cplnPlugin.serializer.extraRulePrefixes ?? [])];
+    const ids = [
+      ...(cplnPlugin.lintRules?.() ?? []).map((rule) => rule.id),
+      ...(cplnPlugin.postSynthChecks?.() ?? []).map((check) => check.id),
+    ];
+
+    expect(ids.length).toBeGreaterThan(0);
+    for (const id of ids) {
+      expect(prefixes.some((prefix) => id.startsWith(prefix)), `${id} is outside ${prefixes.join("/")}`).toBe(true);
+    }
+  });
+
+  it("has no duplicate rule ids", () => {
+    const ids = [
+      ...(cplnPlugin.lintRules?.() ?? []).map((rule) => rule.id),
+      ...(cplnPlugin.postSynthChecks?.() ?? []).map((check) => check.id),
+    ];
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it("covers every registered check in the audit catalog", () => {
+    // A check with no catalog entry contributes nothing to `chant audit`, and
+    // does so silently — which is exactly the failure mode this asserts away.
+    const ids = [
+      ...(cplnPlugin.lintRules?.() ?? []).map((rule) => rule.id),
+      ...(cplnPlugin.postSynthChecks?.() ?? []).map((check) => check.id),
+    ];
+
+    for (const id of ids) {
+      expect(cplnAuditCatalog[id], `${id} has no audit catalog entry`).toBeDefined();
+    }
+  });
+
+  it("has no audit catalog entry without a check", () => {
+    const ids = new Set([
+      ...(cplnPlugin.lintRules?.() ?? []).map((rule) => rule.id),
+      ...(cplnPlugin.postSynthChecks?.() ?? []).map((check) => check.id),
+    ]);
+
+    for (const id of Object.keys(cplnAuditCatalog)) {
+      expect(ids.has(id), `${id} is catalogued but not registered`).toBe(true);
+    }
+  });
+
+  it("registers LSP providers", () => {
+    // Registration is what `chant serve lsp` dispatches through — a file in
+    // src/lsp/ that nothing registers is unreachable in an editor.
+    expect(typeof cplnPlugin.completionProvider).toBe("function");
+    expect(typeof cplnPlugin.hoverProvider).toBe("function");
+  });
+
+  it("registers docs, detection and init templates", () => {
+    expect(typeof cplnPlugin.docs).toBe("function");
+    expect(typeof cplnPlugin.detectTemplate).toBe("function");
+    expect(typeof cplnPlugin.initTemplates).toBe("function");
+  });
+
+  it("ships at least three skills, each with content", () => {
+    const skills = cplnPlugin.skills?.() ?? [];
+    expect(skills.length).toBeGreaterThanOrEqual(3);
+    for (const skill of skills) {
+      expect(skill.content.length, `${skill.name} loaded empty`).toBeGreaterThan(0);
+      expect(skill.description.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("ships at least three init templates that differ", () => {
+    const names = ["default", "secrets", "stateful"];
+    const sources = names.map((name) => cplnPlugin.initTemplates?.(name)?.src["infra.ts"] ?? "");
+    for (const source of sources) expect(source.length).toBeGreaterThan(0);
+    expect(new Set(sources).size).toBe(names.length);
+  });
+
+  it("namespaces MCP tools and resources under `cpln`", () => {
+    for (const tool of cplnPlugin.mcpTools?.() ?? []) {
+      expect(tool.name.startsWith("cpln:")).toBe(true);
+    }
+    for (const resource of cplnPlugin.mcpResources?.() ?? []) {
+      expect(resource.uri.startsWith("cpln:")).toBe(true);
+    }
+  });
+
+  it("declares an ownership channel whose read paths it implements", () => {
+    const channel = cplnPlugin.ownershipChannel;
+    expect(channel).toBeDefined();
+    expect(channel!.keys.managedBy).toBe("chant.intentius.io/managed-by");
+    expect(channel!.keys.stack).toBeTruthy();
+    expect(channel!.keys.env).toBeTruthy();
+
+    // Declaring a path the plugin cannot resolve a verdict on would be a lie
+    // the completeness checker cannot catch.
+    expect(channel!.reads).toContain("describeResources");
+    expect(typeof cplnPlugin.describeResources).toBe("function");
+    for (const path of channel!.reads) {
+      if (path === "observeResourcesDeep") expect(cplnPlugin.observeResourcesDeep).toBeDefined();
+      if (path === "exportResources") expect(cplnPlugin.exportResources).toBeDefined();
+    }
+  });
+
+  it("declares reference-catalog identities for every modelled kind", () => {
+    const identities = new Set(cplnPlugin.referenceCatalog?.identities.map((entry) => entry.kind));
+    for (const kind of KINDS) {
+      expect(identities.has(kind.typeName), `${kind.typeName} has no identity rule`).toBe(true);
+    }
+  });
+});

package/src/plugin.ts

@@ -0,0 +1,187 @@
+import type {
+  LexiconPlugin,
+  SkillDefinition,
+  InitTemplateSet,
+  DescribeResourcesResult,
+} from "@intentius/chant/lexicon";
+import type { LintRule } from "@intentius/chant/lint/rule";
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+import type { CompletionContext, CompletionItem, HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import type { McpToolContribution, McpResourceContribution } from "@intentius/chant/mcp/types";
+import type { OwnershipChannel } from "@intentius/chant/ownership";
+import { createSkillsLoader, createDiffTool, createCatalogResource } from "@intentius/chant/lexicon-plugin-helpers";
+import { cplnSerializer } from "./serializer";
+import { rules } from "./lint/rules";
+import { postSynthChecks } from "./lint/post-synth";
+import { cplnAuditCatalog } from "./lint/audit-catalog";
+import { cplnReferenceCatalog } from "./reference-catalog";
+import { CPLN_TAG_OWNERSHIP_KEYS } from "./ownership";
+import { detectCplnTemplate } from "./detect";
+import { cplnInitTemplates } from "./init-templates";
+import { completions } from "./lsp/completions";
+import { hover } from "./lsp/hover";
+
+/**
+ * The cpln lexicon plugin.
+ *
+ * Control Plane's `tags` map is the ownership channel, and unusually it works
+ * on the thin read: every kind carries `tags` and every read path returns
+ * them, so `describeResources` resolves a real verdict rather than `unknown`.
+ * That is why `describeResources` is declared among the channel's read paths
+ * where aws — whose `describe-stack-resources` returns no tags at all — cannot
+ * declare it.
+ *
+ * `observeResourcesDeep` and `exportResources` are not implemented yet, so
+ * they are absent from `reads` rather than listed optimistically: the contract
+ * is that a declared path resolves a verdict, and claiming one this plugin has
+ * no implementation for would be a lie the checker cannot catch.
+ */
+const ownershipChannel: OwnershipChannel = {
+  keys: CPLN_TAG_OWNERSHIP_KEYS,
+  reads: ["describeResources"],
+};
+
+export const cplnPlugin: LexiconPlugin = {
+  name: "cpln",
+  serializer: cplnSerializer,
+
+  // ── Required lifecycle methods ────────────────────────────────
+
+  async generate(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
+    const { generate, writeGeneratedFiles } = await import("./codegen/generate");
+    const { dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+
+    const result = await generate(options);
+    writeGeneratedFiles(result, dirname(dirname(fileURLToPath(import.meta.url))));
+  },
+
+  async validate(): Promise<void> {
+    const { validate } = await import("./validate");
+    const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+    printValidationResult(await validate());
+  },
+
+  async coverage(options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
+    const { analyzeCplnCoverage } = await import("./coverage");
+    await analyzeCplnCoverage(options);
+  },
+
+  async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
+    const { packageLexicon } = await import("./codegen/package");
+    const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+    const { join, dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+
+    const { spec, stats } = await packageLexicon(options);
+    const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    writeBundleSpec(spec, join(pkgDir, "dist"));
+
+    console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+  },
+
+  // ── Lint and audit ────────────────────────────────────────────
+
+  lintRules(): LintRule[] {
+    return rules;
+  },
+
+  postSynthChecks(): PostSynthCheck[] {
+    return postSynthChecks;
+  },
+
+  auditCatalog: () => cplnAuditCatalog,
+
+  // ── Observation ───────────────────────────────────────────────
+
+  ownershipChannel,
+
+  referenceCatalog: cplnReferenceCatalog,
+
+  async describeResources(options): Promise<DescribeResourcesResult> {
+    const { describeResources } = await import("./describe-resources");
+    return describeResources({
+      environment: options.environment,
+      buildOutput: options.buildOutput,
+      entityNames: options.entityNames,
+      entities: options.entities,
+      owned: options.owned,
+    });
+  },
+
+  // ── Language surface ──────────────────────────────────────────
+
+  completionProvider(ctx: CompletionContext): CompletionItem[] {
+    return completions(ctx);
+  },
+
+  hoverProvider(ctx: HoverContext): HoverInfo | undefined {
+    return hover(ctx);
+  },
+
+  // ── Import and project surface ────────────────────────────────
+
+  detectTemplate(data: unknown): boolean {
+    return detectCplnTemplate(data);
+  },
+
+  /**
+   * The three `chant init` scaffolds, named at the plugin surface so the
+   * available set is visible where a reader looks for it rather than only
+   * inside the switch that resolves them. An unrecognised name falls through
+   * to the default — `chant init` treats it as a hint, not a key.
+   */
+  initTemplates(template?: string): InitTemplateSet {
+    if (template === "secrets") return cplnInitTemplates("secrets");
+    if (template === "stateful") return cplnInitTemplates("stateful");
+    return cplnInitTemplates();
+  },
+
+  skills: createSkillsLoader(import.meta.url, [
+    {
+      file: "chant-cpln.md",
+      name: "chant-cpln",
+      description:
+        "Declare Control Plane (cpln) infrastructure from chant — the kinds, GVC scoping, links, and what the serializer emits",
+    },
+    {
+      file: "chant-cpln-workloads.md",
+      name: "chant-cpln-workloads",
+      description:
+        "Choose a Control Plane workload type and configure autoscaling, Capacity AI, resources and probes correctly",
+    },
+    {
+      file: "chant-cpln-secrets.md",
+      name: "chant-cpln-secrets",
+      description:
+        "Wire Control Plane secrets, identities and policies so a workload can actually read them",
+    },
+  ]) as () => SkillDefinition[],
+
+  mcpTools(): McpToolContribution[] {
+    return [
+      createDiffTool(
+        cplnSerializer,
+        "Diff the current cpln manifests against the previous build output",
+        "cpln",
+      ),
+    ];
+  },
+
+  mcpResources(): McpResourceContribution[] {
+    return [
+      createCatalogResource(
+        import.meta.url,
+        "Control Plane Resource Catalog",
+        "Every cpln resource and property type, with its Control Plane type name",
+        "lexicon-cpln.json",
+        "cpln",
+      ),
+    ];
+  },
+
+  async docs(options?: { verbose?: boolean }): Promise<void> {
+    const { generateDocs } = await import("./codegen/docs");
+    return generateDocs(options);
+  },
+};

package/src/reference-catalog.ts

@@ -0,0 +1,110 @@
+/**
+ * How observed cpln resources reference each other, so `chant graph --live` can
+ * rebuild the topology from a bag of nodes.
+ *
+ * Control Plane addresses resources by **link string**
+ * (`//gvc/prod/identity/api`), and edge reconstruction matches identifiers
+ * exactly, so a raw link never equals the `name` it points at. Rather than add
+ * an enrichment pass, `describeResources` resolves each link down to the bare
+ * name it ends in and files it under a stable attribute — `refs.identity`,
+ * `refs.gvc`, `refs.pullSecrets` — and the rules below read those. See
+ * {@link referenceAttributes} in `describe-resources.ts`.
+ *
+ * Names are unique per kind within an org (per GVC for the GVC-scoped kinds),
+ * so `name` is the identity for every kind and `targetKind` disambiguates the
+ * cases where two kinds could hold the same name.
+ *
+ * Containment vs reference matters for the picture: "this workload is in this
+ * GVC" is a boundary the renderer draws as a box, not a line from every
+ * resource to its GVC. It still declares `viaAttr` so a traversal can walk it —
+ * "which GVCs have no workloads" is a containment question.
+ */
+
+import type { ReferenceCatalog } from "@intentius/chant/lexicon";
+import { KINDS, kindByName } from "./kinds";
+
+const typeOf = (kind: string): string => kindByName(kind)!.typeName;
+
+export const cplnReferenceCatalog: ReferenceCatalog = {
+  identities: KINDS.map((kind) => ({ kind: kind.typeName, ids: ["name"] })),
+
+  refs: [
+    // Every GVC-scoped resource lives inside its GVC — a boundary, not a line.
+    ...KINDS.filter((kind) => kind.gvcScoped).map((kind) => ({
+      from: kind.typeName,
+      path: "refs.gvc",
+      targetKind: typeOf("gvc"),
+      relation: "containment" as const,
+      label: "in GVC",
+      viaAttr: "gvc",
+    })),
+
+    // A workload runs as one identity.
+    {
+      from: typeOf("workload"),
+      path: "refs.identity",
+      targetKind: typeOf("identity"),
+      relation: "reference",
+      label: "identity",
+      viaAttr: "identityLink",
+    },
+
+    // A GVC pulls private images with org-scoped secrets.
+    {
+      from: typeOf("gvc"),
+      path: "refs.pullSecrets[]",
+      targetKind: typeOf("secret"),
+      relation: "reference",
+      label: "pull secret",
+      viaAttr: "pullSecretLinks",
+    },
+
+    // A domain routes into a GVC, or straight at a stateful workload.
+    {
+      from: typeOf("domain"),
+      path: "refs.gvc",
+      targetKind: typeOf("gvc"),
+      relation: "reference",
+      label: "routes to",
+      viaAttr: "gvcLink",
+    },
+    {
+      from: typeOf("domain"),
+      path: "refs.workloads[]",
+      targetKind: typeOf("workload"),
+      relation: "reference",
+      label: "routes to",
+      viaAttr: "workloadLink",
+    },
+
+    // A policy's explicit target links.
+    {
+      from: typeOf("policy"),
+      path: "refs.targets[]",
+      targetKind: typeOf("secret"),
+      relation: "reference",
+      label: "grants on",
+      viaAttr: "targetLinks",
+    },
+
+    // An IP set fronts the workload it is bound to.
+    {
+      from: typeOf("ipset"),
+      path: "refs.workloads[]",
+      targetKind: typeOf("workload"),
+      relation: "reference",
+      label: "fronts",
+      viaAttr: "link",
+    },
+
+    // A workload mounts volume sets.
+    {
+      from: typeOf("workload"),
+      path: "refs.volumeSets[]",
+      targetKind: typeOf("volumeset"),
+      relation: "reference",
+      label: "mounts",
+      viaAttr: "volumes",
+    },
+  ],
+};

package/src/serializer.test.ts

@@ -0,0 +1,233 @@
+import { describe, expect, it } from "vitest";
+import type { Declarable } from "@intentius/chant/declarable";
+import { cplnSerializer, cplnLink } from "./serializer";
+import { Gvc, Workload, Identity, Secret, Policy, VolumeSet } from "./generated/index";
+import { kindByName } from "./kinds";
+
+/** Build the entity map the serializer is handed. */
+function entities(pairs: Array<[string, unknown]>): Map<string, Declarable> {
+  return new Map(pairs as Array<[string, Declarable]>);
+}
+
+/** Split the emitted multi-document YAML into documents. */
+function documents(yaml: string): string[] {
+  return yaml
+    .split(/^---$/m)
+    .map((doc) => doc.trim())
+    .filter(Boolean);
+}
+
+describe("cpln serializer", () => {
+  it("has the correct name and rule prefix", () => {
+    expect(cplnSerializer.name).toBe("cpln");
+    expect(cplnSerializer.rulePrefix).toBe("CPL");
+  });
+
+  it("serializes an empty map to an empty string", () => {
+    expect(cplnSerializer.serialize(new Map())).toBe("");
+  });
+
+  it("emits kind and name first", () => {
+    const gvc = new Gvc({ name: "prod", spec: { staticPlacement: { locationLinks: ["//location/aws-us-east-1"] } } });
+    const output = cplnSerializer.serialize(entities([["gvc", gvc]]));
+
+    expect(output.startsWith("kind: gvc\nname: prod\n")).toBe(true);
+  });
+
+  it("emits the gvc key for a GVC-scoped kind", () => {
+    const workload = new Workload({ name: "web", gvc: "prod", spec: { type: "serverless" } });
+    const output = cplnSerializer.serialize(entities([["web", workload]]));
+
+    expect(output).toContain("kind: workload");
+    expect(output).toContain("gvc: prod");
+  });
+
+  it("falls back to the entity name when no name is declared", () => {
+    const secret = new Secret({ type: "opaque" } as never);
+    const output = cplnSerializer.serialize(entities([["fallback-name", secret]]));
+
+    expect(output).toContain("name: fallback-name");
+    expect(output).not.toContain("undefined");
+  });
+
+  it("never emits server-side fields", () => {
+    // Control Plane's own guidance: `status`, `id`, `created`, `lastModified`
+    // and `links` break `cpln apply`. They are attributes here, so they cannot
+    // reach a document — this asserts that stays true.
+    const workload = new Workload({ name: "web", gvc: "prod", spec: { type: "serverless" } });
+    const output = cplnSerializer.serialize(entities([["web", workload]]));
+
+    for (const field of ["status:", "id:", "created:", "lastModified:", "links:", "version:"]) {
+      expect(output, `${field} reached the manifest`).not.toContain(field);
+    }
+  });
+
+  it("orders documents dependency-first and sorts within a kind", () => {
+    const gvc = new Gvc({ name: "prod" });
+    const secret = new Secret({ name: "db", type: "opaque" });
+    const beta = new Workload({ name: "beta", gvc: "prod", spec: { type: "serverless" } });
+    const alpha = new Workload({ name: "alpha", gvc: "prod", spec: { type: "serverless" } });
+
+    const output = cplnSerializer.serialize(
+      entities([
+        ["beta", beta],
+        ["gvc", gvc],
+        ["alpha", alpha],
+        ["secret", secret],
+      ]),
+    );
+
+    const kinds = documents(output).map((doc) => doc.split("\n")[0]);
+    expect(kinds).toEqual(["kind: gvc", "kind: secret", "kind: workload", "kind: workload"]);
+
+    const workloadNames = documents(output)
+      .filter((doc) => doc.startsWith("kind: workload"))
+      .map((doc) => doc.split("\n")[1]);
+    expect(workloadNames).toEqual(["name: alpha", "name: beta"]);
+  });
+
+  it("resolves a resource reference to its Control Plane link", () => {
+    const identity = new Identity({ name: "api-identity", gvc: "prod" });
+    const workload = new Workload({
+      name: "api",
+      gvc: "prod",
+      spec: { type: "serverless", identityLink: identity as never },
+    });
+
+    const output = cplnSerializer.serialize(
+      entities([
+        ["identity", identity],
+        ["api", workload],
+      ]),
+    );
+
+    // The GVC-qualified form specifically: the bare //identity/NAME is
+    // silently ignored by Control Plane.
+    expect(output).toContain("identityLink: //gvc/prod/identity/api-identity");
+    expect(output).not.toContain("identityLink: //identity/");
+  });
+
+  it("uses the declared name, not the entity name, when building a link", () => {
+    const secret = new Secret({ name: "db-password", type: "opaque" });
+    const policy = new Policy({
+      name: "grants",
+      targetKind: "secret",
+      targetLinks: [secret as never],
+    });
+
+    const output = cplnSerializer.serialize(
+      entities([
+        ["secretEntity", secret],
+        ["grants", policy],
+      ]),
+    );
+
+    expect(output).toContain("//secret/db-password");
+  });
+
+  it("stamps the ownership marker even when no tags are declared", () => {
+    const gvc = new Gvc({ name: "prod" });
+    const output = cplnSerializer.serialize(entities([["gvc", gvc]]), undefined, {
+      ownership: { stack: "demo", env: "prod" },
+    });
+
+    expect(output).toContain("chant.intentius.io/managed-by: chant");
+    expect(output).toContain("chant.intentius.io/stack: demo");
+    expect(output).toContain("chant.intentius.io/env: prod");
+  });
+
+  it("merges the ownership marker with declared tags", () => {
+    const gvc = new Gvc({ name: "prod", tags: { team: "platform" } });
+    const output = cplnSerializer.serialize(entities([["gvc", gvc]]), undefined, {
+      ownership: { stack: "demo" },
+    });
+
+    expect(output).toContain("team: platform");
+    expect(output).toContain("chant.intentius.io/managed-by: chant");
+    // No env in the marker means no env key, not an empty one.
+    expect(output).not.toContain("chant.intentius.io/env");
+  });
+
+  it("emits no tags block when there is nothing to stamp", () => {
+    const gvc = new Gvc({ name: "prod" });
+    expect(cplnSerializer.serialize(entities([["gvc", gvc]]))).not.toContain("tags:");
+  });
+
+  it("ignores entities from other lexicons", () => {
+    const foreign = { entityType: "K8s::Apps::Deployment", props: { name: "x" } };
+    const gvc = new Gvc({ name: "prod" });
+    const output = cplnSerializer.serialize(
+      entities([
+        ["foreign", foreign],
+        ["gvc", gvc],
+      ]),
+    );
+
+    expect(documents(output)).toHaveLength(1);
+  });
+
+  it("refuses to serialize an attribute reference", () => {
+    const gvc = new Gvc({ name: "prod" });
+    // The build pipeline assigns logical names before serializing; doing it
+    // here is what routes the walker into the visitor's `attrRef` rather than
+    // failing earlier on an unnamed ref.
+    (gvc.id as unknown as { _setLogicalName(name: string): void })._setLogicalName("gvc");
+
+    const workload = new Workload({
+      name: "web",
+      gvc: "prod",
+      spec: { type: "serverless", identityLink: gvc.id as never },
+    });
+
+    expect(() =>
+      cplnSerializer.serialize(
+        entities([
+          ["gvc", gvc],
+          ["web", workload],
+        ]),
+      ),
+    ).toThrow(/no.*template-time reference language/i);
+  });
+
+  it("serializes a volume set mount alongside its workload", () => {
+    const volumeSet = new VolumeSet({
+      name: "data",
+      gvc: "prod",
+      spec: { initialCapacity: 20, fileSystemType: "ext4", performanceClass: "general-purpose-ssd" },
+    });
+    const workload = new Workload({
+      name: "db",
+      gvc: "prod",
+      spec: {
+        type: "stateful",
+        containers: [
+          { name: "main", image: "postgres:17", volumes: [{ uri: "cpln://volumeset/data", path: "/data" }] },
+        ],
+      },
+    });
+
+    const output = cplnSerializer.serialize(
+      entities([
+        ["db", workload],
+        ["data", volumeSet],
+      ]),
+    );
+
+    const kinds = documents(output).map((doc) => doc.split("\n")[0]);
+    expect(kinds).toEqual(["kind: volumeset", "kind: workload"]);
+    expect(output).toContain("uri: cpln://volumeset/data");
+  });
+});
+
+describe("cplnLink", () => {
+  it("builds each kind's link form", () => {
+    expect(cplnLink(kindByName("gvc")!, "prod")).toBe("//gvc/prod");
+    expect(cplnLink(kindByName("secret")!, "db")).toBe("//secret/db");
+    expect(cplnLink(kindByName("workload")!, "web", "prod")).toBe("//gvc/prod/workload/web");
+    expect(cplnLink(kindByName("identity")!, "api", "prod")).toBe("//gvc/prod/identity/api");
+  });
+
+  it("refuses a GVC-scoped link with no resolvable GVC", () => {
+    expect(() => cplnLink(kindByName("identity")!, "api")).toThrow(/silently ignored/);
+  });
+});