@intentius/chant 0.79.0 → 0.81.0

package/src/discovery/walk.ts

@@ -0,0 +1,334 @@
+/**
+ * The one discovery walk (chant#2527).
+ *
+ * Every command that decides which files chant reads walks the tree here:
+ * source discovery (`./files.ts`'s `findInfraFiles`, behind build, graph,
+ * list, explain and lexicon detection), `chant lint`, component discovery,
+ * Op discovery and the `chant audit` walk. They used to have five walkers
+ * with five sets of rules. v0.80.0 warned about every file whose status the
+ * convergence changes (#2571), and this module is that convergence. It is on
+ * #2525's level-0 exception list.
+ *
+ * The rules, for every walker:
+ *
+ * - `node_modules` and `.git` are never entered.
+ * - Dot-directories are skipped. The audit walk keeps `.github` and
+ *   `.forgejo`, which hold the CI files it audits.
+ * - `dist` is skipped.
+ * - Git-ignored paths are skipped, nested `.gitignore` files, `.git/info/exclude`
+ *   and the global excludes file included, the way git itself decides. Only
+ *   paths below the scan root are asked about: when the scan root is itself
+ *   ignored, nothing under it is dropped for being ignored, so building or
+ *   linting an ignored directory still reads it.
+ * - When the scan root is inside a chant project, a child directory holding a
+ *   project config is a boundary and is not entered. A `chant.config.json`
+ *   holding only lint keys is a fragment, not a project config, and is not a
+ *   boundary. A `chant.config.ts` always is one, since telling a lint-only one
+ *   apart would mean running it. When the scan root is outside every project,
+ *   every child project is read. Op discovery always stops at child projects
+ *   below its root.
+ * - The project's `exclude` globs (#2519) drop what they match, and its
+ *   `include` globs re-admit what `exclude` or any rule above would skip.
+ *   `node_modules`, `.git` and workspace members are the exceptions: include
+ *   never re-admits them.
+ * - Workspace members and group matches leave the root project's walk
+ *   (#2525 rule 3), and only when a workspace declaration exists. Without one nothing is loaded and
+ *   nothing is excluded; see {@link workspaceMemberDirs}.
+ *
+ * The walk is synchronous: the audit walk it replaced was, and the glob and
+ * ignore facts are gathered once before it starts.
+ */
+
+import { execFileSync } from "node:child_process";
+import { closeSync, existsSync, openSync, readdirSync, readSync, statSync, type Dirent } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+// @ts-ignore — picomatch has no types declaration
+import picomatch from "picomatch";
+import { findProjectConfig, findWorkspaceRoot } from "../project-root";
+import { isLintOnlyFragment, type DiscoveryGlobs } from "../config";
+
+/** The commands that walk the tree. */
+export type DiscoveryWalker = "source" | "lint" | "components" | "ops" | "audit";
+
+/** Dot-directories the audit walk enters anyway, since they hold the CI files it audits. */
+export const AUDIT_DOT_DIRS: ReadonlySet<string> = new Set([".github", ".forgejo"]);
+
+/** Directories no rule and no glob ever lets the walk into. */
+const NEVER_ENTER = new Set(["node_modules", ".git"]);
+
+/** One walk: which walker, where from, which files it wants, and the facts only some walkers have. */
+export interface WalkOptions {
+  walker: DiscoveryWalker;
+  /** The directory the walk starts from. Joined onto, never resolved, so relative roots give relative paths. */
+  root: string;
+  /**
+   * Which files the walker wants, by name and full path. Called only for a
+   * file every rule above has let through, so a marker check here reads only
+   * files that could be returned.
+   */
+  accept: (name: string, fullPath: string) => boolean;
+  /**
+   * The project's discovery globs. Omitted, none apply. Callers that can load
+   * the project config resolve them with `resolveDiscoveryGlobs`.
+   */
+  globs?: DiscoveryGlobs;
+  /** Sort each directory's entries by name. The audit walk does, for a stable limit. */
+  sorted?: boolean;
+  /** Follow symlinked directories and files. `chant lint` always did; the others never did. */
+  followSymlinks?: boolean;
+  /**
+   * The audit walk's file limit. Every file the walk takes counts, accepted or
+   * not; `truncated` is set once a file past the limit is met.
+   */
+  limit?: { max: number; truncated: boolean };
+  /**
+   * Called for a dot-directory the walk skips. Returning true takes the
+   * directory's own path as a file without entering it (the audit walk's
+   * `.terraform`, which TF023 reports by its presence).
+   */
+  takeSkippedDir?: (name: string, fullPath: string) => boolean;
+  /**
+   * Paths the git-ignore rule leaves alone, to be judged by the caller. The
+   * audit walk keeps Terraform state paths for TF023, which has its own
+   * `.gitignore` reading.
+   */
+  keepIgnored?: (fullPath: string) => boolean;
+  /** Directories that leave this walk, absolute. See {@link workspaceMemberDirs}. */
+  excludeDirs?: readonly string[];
+}
+
+// ── Globs ────────────────────────────────────────────────────────────────────
+
+/** A project's `exclude` and `include` globs, compiled against the config's directory. */
+interface CompiledGlobs {
+  /** True when an `exclude` pattern matches the path or a directory above it. */
+  excluded(full: string): boolean;
+  /** True when an `include` pattern matches the path or a directory above it. */
+  included(full: string): boolean;
+  /** True when some `include` pattern names a path strictly below directory `full`. */
+  includeBelow(full: string): boolean;
+}
+
+/** Path parts below `home`, or undefined for `home` itself or a path outside it. */
+function partsBelow(home: string, full: string): string[] | undefined {
+  const rel = relative(home, resolve(full));
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return undefined;
+  return rel.split(sep);
+}
+
+function compileGlobs(globs: DiscoveryGlobs | undefined): CompiledGlobs | undefined {
+  if (!globs || (globs.exclude.length === 0 && globs.include.length === 0)) return undefined;
+  const home = resolve(globs.root);
+  const matcher = (patterns: string[]): ((full: string) => boolean) => {
+    if (patterns.length === 0) return () => false;
+    const match: (p: string) => boolean = picomatch(patterns, { dot: true });
+    return (full) => {
+      const parts = partsBelow(home, full);
+      return parts !== undefined && parts.some((_, i) => match(parts.slice(0, i + 1).join("/")));
+    };
+  };
+  // The literal directory part of each include pattern: `.cache/keep/**`
+  // gives `.cache/keep`. The walk enters a skipped directory on the way to it.
+  const bases = globs.include.map((p) => (picomatch.scan(p) as { base: string }).base).filter((b) => b !== "");
+  return {
+    excluded: matcher(globs.exclude),
+    included: matcher(globs.include),
+    includeBelow: (full) => {
+      const parts = partsBelow(home, full);
+      if (parts === undefined) return false;
+      const rel = parts.join("/");
+      return bases.some((b) => b.startsWith(`${rel}/`));
+    },
+  };
+}
+
+// ── Git ──────────────────────────────────────────────────────────────────────
+
+/**
+ * The untracked paths git ignores under `root`, absolute, with fully ignored
+ * directories listed once. One `git ls-files` call. A tree outside git, a
+ * missing `git`, or a root that is itself ignored yields an empty set: ignore
+ * rules are asked only about paths below the scan root.
+ */
+export function gitIgnoredBelow(root: string): Set<string> {
+  let out: string;
+  try {
+    out = execFileSync("git", ["ls-files", "-z", "--others", "--ignored", "--exclude-standard", "--directory"], {
+      cwd: root,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 256 * 1024 * 1024,
+    });
+  } catch {
+    return new Set();
+  }
+  const ignored = new Set<string>();
+  const abs = resolve(root);
+  for (const entry of out.split("\0")) {
+    if (entry === "") continue;
+    const rel = entry.endsWith("/") ? entry.slice(0, -1) : entry;
+    // `./` (or `.`): the scan root is itself ignored.
+    if (rel === "." || rel === "") return new Set();
+    ignored.add(join(abs, rel));
+  }
+  return ignored;
+}
+
+// ── Boundaries ───────────────────────────────────────────────────────────────
+
+/** A directory that holds a project config: `chant.config.ts`, or a `chant.config.json` that is not a lint-only fragment. */
+export function isProjectBoundary(dir: string): boolean {
+  if (existsSync(join(dir, "chant.config.ts"))) return true;
+  const json = join(dir, "chant.config.json");
+  return existsSync(json) && !isLintOnlyFragment(json);
+}
+
+/** Whether child projects end the walk from `root`: always for Ops, otherwise when `root` is inside a project. */
+export function childProjectsAreBoundaries(walker: DiscoveryWalker, root: string): boolean {
+  return walker === "ops" || findProjectConfig(root).configPath !== undefined;
+}
+
+// ── Workspace members ────────────────────────────────────────────────────────
+
+/**
+ * The directories a workspace declaration moves out of the root project's
+ * discovery (#2525 rule 3), absolute and strictly below `root`, or none:
+ * every member's directory but the root's, and every group match
+ * (`rootExclusions` in `../workspace/declaration.ts`).
+ *
+ * Level 0 pays for `findWorkspaceRoot`, which only tests whether a
+ * `chant.workspace.json` or `.jsonc` exists from `root` up to the git root,
+ * and loads nothing. Only when a declaration is found are the workspace
+ * modules loaded to read it. A declaration that fails to read excludes
+ * nothing here; `chant workspace ls` is where its errors are reported. This
+ * is the only place discovery asks about workspaces; the walkers pass the
+ * result as `excludeDirs`.
+ */
+export async function workspaceMemberDirs(root: string): Promise<string[]> {
+  const found = findWorkspaceRoot(root);
+  if (!found) return [];
+  const start = resolve(root);
+  const [{ readDeclaration, resolveGroups, rootExclusions }, { workingTree }] = await Promise.all([
+    import("../workspace/declaration"),
+    import("../workspace/tree"),
+  ]);
+  let dirs: string[];
+  try {
+    const tree = workingTree(found.dir);
+    const declaration = readDeclaration(tree);
+    dirs = rootExclusions(declaration, resolveGroups(declaration, tree)).map((e) => resolve(found.dir, e.dir));
+  } catch {
+    return [];
+  }
+  return dirs.filter((d) => partsBelow(start, d) !== undefined);
+}
+
+// ── Markers ──────────────────────────────────────────────────────────────────
+
+/** The first `bytes` of a file as UTF-8, or "" when it can't be read. */
+export function readHead(file: string, bytes: number): string {
+  let fd: number | undefined;
+  try {
+    fd = openSync(file, "r");
+    const buf = Buffer.alloc(bytes);
+    const n = readSync(fd, buf, 0, bytes, 0);
+    return buf.toString("utf8", 0, n);
+  } catch {
+    return "";
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+// ── The walk ─────────────────────────────────────────────────────────────────
+
+/** Walk `opts.root` under the rules in the module doc and return the files `accept` took. */
+export function walkDiscovery(opts: WalkOptions): string[] {
+  const out: string[] = [];
+  const globs = compileGlobs(opts.globs);
+  const ignored = gitIgnoredBelow(opts.root);
+  const boundaries = childProjectsAreBoundaries(opts.walker, opts.root);
+  const excludeDirs = new Set((opts.excludeDirs ?? []).map((d) => resolve(d)));
+  const dotDirsKept = opts.walker === "audit" ? AUDIT_DOT_DIRS : new Set<string>();
+  const limit = opts.limit;
+
+  const isIgnored = (full: string): boolean => ignored.size > 0 && ignored.has(resolve(full));
+
+  /** Take a path; false once the limit is reached. */
+  const take = (full: string): boolean => {
+    if (limit && out.length >= limit.max) {
+      limit.truncated = true;
+      return false;
+    }
+    out.push(full);
+    return true;
+  };
+
+  const kind = (dir: string, e: Dirent): "dir" | "file" | undefined => {
+    if (e.isDirectory()) return "dir";
+    if (e.isFile()) return "file";
+    if (opts.followSymlinks && e.isSymbolicLink()) {
+      try {
+        const s = statSync(join(dir, e.name));
+        return s.isDirectory() ? "dir" : s.isFile() ? "file" : undefined;
+      } catch {
+        return undefined;
+      }
+    }
+    return undefined;
+  };
+
+  /**
+   * Walk `dir`. `probing` is true below a directory a rule skipped that the
+   * walk entered only because an `include` pattern names something inside
+   * it: there, only what `include` matches is taken.
+   */
+  const walk = (dir: string, probing: boolean): boolean => {
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return true;
+    }
+    if (opts.sorted) entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const e of entries) {
+      if (limit?.truncated) return false;
+      const full = join(dir, e.name);
+      const type = kind(dir, e);
+      if (type === "dir") {
+        if (NEVER_ENTER.has(e.name) || excludeDirs.has(resolve(full))) continue;
+        const dotSkip = e.name.startsWith(".") && !dotDirsKept.has(e.name);
+        if (dotSkip && opts.takeSkippedDir?.(e.name, full)) {
+          if (!take(full)) return false;
+          continue;
+        }
+        const ruleSkip =
+          dotSkip ||
+          e.name === "dist" ||
+          (isIgnored(full) && !opts.keepIgnored?.(full)) ||
+          (boundaries && isProjectBoundary(full));
+        if (ruleSkip || probing) {
+          if (globs?.included(full)) {
+            if (!walk(full, false)) return false;
+          } else if (globs?.includeBelow(full)) {
+            if (!walk(full, true)) return false;
+          }
+          continue;
+        }
+        if (!walk(full, false)) return false;
+      } else if (type === "file") {
+        const skipped =
+          probing ||
+          (isIgnored(full) && !opts.keepIgnored?.(full)) ||
+          (globs?.excluded(full) ?? false);
+        if (skipped && !globs?.included(full)) continue;
+        if (!opts.accept(e.name, full)) continue;
+        if (!take(full)) return false;
+      }
+    }
+    return true;
+  };
+
+  walk(opts.root, false);
+  return out;
+}

package/src/effect-receipt.ts

@@ -38,7 +38,7 @@
  * `sha256:<hex>` like the build-ledger digests in ./lifecycle/build-ledger.ts).
  */
 
-import { createHash } from "node:crypto";
+import { contentDigest } from "./content-digest";
 import { DECLARABLE_MARKER, type Declarable } from "./declarable";
 import { isIntrinsic, type Intrinsic } from "./intrinsic";
 
@@ -293,7 +293,7 @@ function encodeCanonical(value: unknown, path: string, seen: Set<object>): strin
 }
 
 function sha256Digest(canonical: string): string {
-  return `sha256:${createHash("sha256").update(canonical, "utf8").digest("hex")}`;
+  return contentDigest(canonical);
 }
 
 // ─────────────────────────────────────────────────────────────────────────

package/src/graph-ir.ts

@@ -230,7 +230,10 @@ export interface IRExport {
 /** A cross-stack import this stack consumes — a `Parameter` fed from another
  * stack's output at deploy time. A viewer matches an import `name` to another
  * stack's export `name` to draw the cross-stack edge; the parameter's in-stack
- * consumers are ordinary `$ref` edges to `node` (#513). */
+ * consumers are ordinary `$ref` edges to `node` (#513). A reader that infers
+ * that match by name uses `joinKey()` from `./join-key.ts` and labels the edge
+ * `exact` or `folded`, the way `chant workspace graph` labels joins across
+ * members (#2539, ws-008). */
 export interface IRImport {
   /** Parameter name — the cross-stack handle (e.g. "clusterArn"). */
   name: string;
@@ -290,8 +293,22 @@ export interface IRPipeline {
   edges: IRPipelineEdge[];
 }
 
+/**
+ * The version `chant graph --format ir` writes on its output (#2529, #2524 D8).
+ * The format changes only additively: a new field or edge kind never bumps
+ * it, and a consumer ignores the fields and edge kinds it does not know. The
+ * number moves only for a change a consumer could not ignore.
+ */
+export const GRAPH_IR_VERSION = 1;
+
 /** The full graph IR for a project at the default (declarable) detail level. */
 export interface GraphIR {
+  /**
+   * {@link GRAPH_IR_VERSION}, stamped by `chant graph --format ir` when it
+   * writes the IR (#2529). Absent on an IR built in memory, and on output
+   * from a chant older than the field, which a reader treats as version 1.
+   */
+  version?: number;
   nodes: IRNode[];
   edges: IREdge[];
   groups: IRGroups;

package/src/join-key.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "vitest";
+import { joinKey, joinLabel } from "./join-key";
+
+describe("joinKey (#2539, ws-008)", () => {
+  test("folds case and punctuation", () => {
+    for (const name of ["ClusterArn", "clusterArn", "cluster_arn", "cluster-arn", "CLUSTER.ARN", "Cluster Arn"]) {
+      expect(joinKey(name)).toBe("clusterarn");
+    }
+  });
+
+  test("keeps digits and letters outside ASCII", () => {
+    expect(joinKey("Subnet1")).toBe("subnet1");
+    expect(joinKey("Subnet1")).not.toBe(joinKey("Subnet2"));
+    expect(joinKey("Größe")).toBe("größe");
+  });
+
+  test("labels a join exact or folded, and says when names don't join", () => {
+    expect(joinLabel("ClusterArn", "ClusterArn")).toBe("exact");
+    expect(joinLabel("clusterArn", "ClusterArn")).toBe("folded");
+    expect(joinLabel("vpc_id", "VpcId")).toBe("folded");
+    expect(joinLabel("VpcId", "SubnetId")).toBeUndefined();
+    expect(joinLabel("", "")).toBeUndefined();
+    expect(joinLabel("--", "__")).toBeUndefined();
+  });
+});

package/src/join-key.ts

@@ -0,0 +1,39 @@
+/**
+ * The one join key for names matched across projects (#2524 D6, ws-008).
+ *
+ * A consumer's parameter and a producer's output are joined by name when
+ * nobody wrote the join down. Deploy matches names exactly, and real projects
+ * rarely spell both sides the same (`clusterArn` against `ClusterArn`), so an
+ * inferred join compares {@link joinKey}s and says how it matched: `exact`
+ * when the names are equal, `folded` when only case or punctuation differ.
+ * A declared member link is always compared exactly and never uses this.
+ *
+ * Before this module, core only published the handles (a graph IR's
+ * `exports` and `imports`) and each viewer matched them with its own rule.
+ * Every reader that infers a join by name uses this function instead, so the
+ * same workspace shows the same inferred edges everywhere. It imports nothing,
+ * so any reader can load it through `@intentius/chant/join-key`.
+ */
+
+/** How an inferred join matched its two names. */
+export type JoinLabel = "exact" | "folded";
+
+/**
+ * The key two names are joined on: Unicode-normalised, lowercased, with every
+ * character that is not a letter or a digit removed. `ClusterArn`,
+ * `clusterArn`, `cluster_arn` and `cluster-arn` share the key `clusterarn`.
+ */
+export function joinKey(name: string): string {
+  return name.normalize("NFKC").toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+}
+
+/**
+ * How `a` and `b` join: `exact` when they are the same string, `folded` when
+ * only their {@link joinKey}s are equal, and undefined when they don't join.
+ * Names whose key is empty never join.
+ */
+export function joinLabel(a: string, b: string): JoinLabel | undefined {
+  if (a === b) return a === "" ? undefined : "exact";
+  const key = joinKey(a);
+  return key !== "" && key === joinKey(b) ? "folded" : undefined;
+}

package/src/lexicon-module.test.ts

@@ -0,0 +1,203 @@
+/**
+ * chant #2520 — a lexicon declared by module path in `chant.config.ts`
+ * (`{ name, module }`) loads with no `@intentius/chant-lexicon-<name>`
+ * package, for build, lint, run and the capability registry.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { createRequire } from "node:module";
+import { join, resolve } from "node:path";
+import { loadChantConfig } from "./config";
+import { lexiconModulePath, lexiconNames, resetLexiconModules } from "./lexicon-module";
+import { loadPlugins, resolveProjectLexicons, loadPlugin } from "./cli/plugins";
+import { loadActivities } from "./op/activity-registry";
+import { loadActivityContracts } from "./op/activity-contract-registry";
+import { loadGatePolicyEvaluator } from "./op/gate-approval";
+import { buildCapabilityRegistry } from "./components/capability-plugin-loader";
+import { buildCommand } from "./cli/commands/build";
+import { lintCommand } from "./cli/commands/lint";
+
+const activityContractModule = resolve(import.meta.dirname, "op/activity-contract.ts");
+const zodModule = createRequire(import.meta.url).resolve("zod");
+
+/** The whole project-local lexicon, in one module, importing core by absolute path so it needs no package. */
+function lexiconSource(pluginName = "site"): string {
+  return `
+import { z } from ${JSON.stringify(zodModule)};
+import { activityContract } from ${JSON.stringify(activityContractModule)};
+
+export const sitePlugin = {
+  name: ${JSON.stringify(pluginName)},
+  serializer: {
+    name: "site",
+    rulePrefix: "SITE",
+    serialize: (entities) => JSON.stringify({ pages: [...entities.keys()].sort() }),
+  },
+  generate: async () => {},
+  validate: async () => {},
+  coverage: async () => {},
+  package: async () => {},
+  activities: () => ({ siteDeploy: async (args) => ({ deployed: args.target }) }),
+  activityContracts: () => [activityContract("siteDeploy", z.strictObject({ target: z.string() }))],
+};
+
+export const siteCapabilities = {
+  name: "site-capabilities",
+  version: "0.0.0",
+  capabilities: () => [{ kind: "site-publish", run: async () => ({}) }],
+};
+
+export async function evaluateGatePolicy() {
+  return { decision: "allow", determiningPolicies: [], errors: [] };
+}
+`;
+}
+
+function opSource(args: Record<string, unknown>): string {
+  return `
+export default {
+  [Symbol.for("chant.declarable")]: true,
+  entityType: "Chant::Op",
+  lexicon: "chant",
+  kind: "resource",
+  props: {
+    name: "publish",
+    overview: "test",
+    phases: [
+      { name: "Publish", steps: [{ kind: "activity", fn: "siteDeploy", args: ${JSON.stringify(args)} }] },
+    ],
+  },
+};
+`;
+}
+
+describe("lexicons declared by module path (#2520)", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    resetLexiconModules();
+    dir = await mkdtemp(join(tmpdir(), "chant-lexicon-module-"));
+    await mkdir(join(dir, "lexicon"));
+    await writeFile(join(dir, "lexicon", "index.ts"), lexiconSource());
+    await writeFile(
+      join(dir, "chant.config.ts"),
+      `export default { lexicons: [{ name: "site", module: "./lexicon/index.ts" }] };\n`,
+    );
+    await writeFile(
+      join(dir, "main.ts"),
+      `export const home = { lexicon: "site", entityType: "Site::Page", kind: "resource", props: {}, [Symbol.for("chant.declarable")]: true };\n`,
+    );
+  });
+
+  afterEach(async () => {
+    resetLexiconModules();
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("the loaded config holds the name, and the module path is recorded against the config's directory", async () => {
+    const { config } = await loadChantConfig(dir);
+    expect(config.lexicons).toEqual(["site"]);
+    expect(config.lexiconModules).toEqual({ site: join(dir, "lexicon", "index.ts") });
+    expect(lexiconModulePath("site")).toBe(join(dir, "lexicon", "index.ts"));
+  });
+
+  test("a config of plain names comes back as written, with nothing recorded", async () => {
+    const plain = join(dir, "plain");
+    await mkdir(plain);
+    await writeFile(join(plain, "chant.config.ts"), `export default { lexicons: ["aws"] };\n`);
+    const { config } = await loadChantConfig(plain);
+    expect(config).toEqual({ lexicons: ["aws"] });
+    expect(lexiconModulePath("aws")).toBeUndefined();
+  });
+
+  test("a later config naming the lexicon as a package drops the recorded path", async () => {
+    await loadChantConfig(dir);
+    expect(lexiconModulePath("site")).toBeDefined();
+    // A second project; a config file is a module, cached by path.
+    const other = join(dir, "other");
+    await mkdir(other);
+    await writeFile(join(other, "chant.config.ts"), `export default { lexicons: ["site"] };\n`);
+    await loadChantConfig(other);
+    expect(lexiconModulePath("site")).toBeUndefined();
+  });
+
+  test("an entry with an unknown key is rejected", async () => {
+    const pinned = join(dir, "pinned");
+    await mkdir(pinned);
+    await writeFile(
+      join(pinned, "chant.config.ts"),
+      `export default { lexicons: [{ name: "site", module: "./lexicon/index.ts", pin: "x" }] };\n`,
+    );
+    await expect(loadChantConfig(pinned)).rejects.toThrow(/Invalid chant config/);
+  });
+
+  test("lexiconNames reads both entry forms", () => {
+    expect(lexiconNames(["aws", { name: "site", module: "./x.ts" }])).toEqual(["aws", "site"]);
+  });
+
+  test("build: the plugin loads from the module and the project builds with it", async () => {
+    const names = await resolveProjectLexicons(dir);
+    expect(names).toEqual(["site"]);
+    const plugins = await loadPlugins(names);
+    expect(plugins.map((p) => p.name)).toEqual(["site"]);
+
+    await writeFile(join(dir, "publish.op.ts"), opSource({ target: "prod" }));
+    const result = await buildCommand({
+      path: dir,
+      format: "json",
+      serializers: plugins.map((p) => p.serializer),
+      plugins,
+    });
+    expect(result.errors).toEqual([]);
+    expect(result.success).toBe(true);
+    // The page and the Op.
+    expect(result.resourceCount).toBe(2);
+  });
+
+  test("a plugin whose name differs from the declared name is refused", async () => {
+    await writeFile(join(dir, "lexicon", "index.ts"), lexiconSource("other"));
+    await loadChantConfig(dir);
+    await expect(loadPlugin("site")).rejects.toThrow(/plugin it exports is named "other"/);
+  });
+
+  test("run: the plugin's activities are loaded by name, with no op/activities subpath", async () => {
+    await loadChantConfig(dir);
+    const activities = await loadActivities(["site"]);
+    expect(await activities.get("siteDeploy")?.({ target: "prod" })).toEqual({ deployed: "prod" });
+    // Core's base activities are still there.
+    expect(activities.get("shellCmd")).toBeDefined();
+  });
+
+  test("activity contracts are found by name, with no op/activity-contracts subpath", async () => {
+    await loadChantConfig(dir);
+    const contracts = await loadActivityContracts(["site"]);
+    expect(contracts.get("siteDeploy")).toBeDefined();
+  });
+
+  test("lint: the plugin's contract validates an Op step calling its activity", async () => {
+    await writeFile(join(dir, "publish.op.ts"), opSource({ target: 42 }));
+    const bad = await lintCommand({ path: dir, format: "stylish" });
+    expect(
+      bad.diagnostics.some((d) => d.ruleId === "OPS012" && d.message.includes("siteDeploy")),
+    ).toBe(true);
+
+    // A fresh path: ES modules are cached by URL, so the corrected Op needs its own file.
+    await rm(join(dir, "publish.op.ts"));
+    await writeFile(join(dir, "publish2.op.ts"), opSource({ target: "prod" }));
+    const good = await lintCommand({ path: dir, format: "stylish" });
+    expect(good.diagnostics.filter((d) => d.ruleId === "OPS012")).toEqual([]);
+  });
+
+  test("the capability registry registers the module's capability plugin", async () => {
+    await loadChantConfig(dir);
+    const registry = await buildCapabilityRegistry({ lexicons: ["site"] });
+    expect(registry.has("site-publish")).toBe(true);
+  });
+
+  test("the gate policy evaluator is read from the module", async () => {
+    await loadChantConfig(dir);
+    const evaluator = await loadGatePolicyEvaluator("site");
+    expect(typeof evaluator.evaluateGatePolicy).toBe("function");
+  });
+});