@intentius/chant 0.80.0 → 0.81.0

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.ts

@@ -24,10 +24,14 @@
  * a project that names lexicons by package takes exactly the path it always did.
  */
 
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 
-/** One `lexicons` entry: a package-backed name, or a name plus the module that implements it. */
-export type LexiconDeclaration = string | { name: string; module: string };
+/**
+ * One `lexicons` entry: a package-backed name, or a name plus the module that
+ * implements it. `root` (chant#2590) names the directory the lexicon's files
+ * live in, for fold's trust; see {@link pathLexiconRoot}.
+ */
+export type LexiconDeclaration = string | { name: string; module: string; root?: string };
 
 /** The lexicon name an entry declares, whichever form it takes. */
 export function lexiconDeclarationName(entry: LexiconDeclaration): string {
@@ -44,6 +48,52 @@ export function lexiconNames(entries: readonly LexiconDeclaration[] | undefined)
 /** Name to absolute module path, for the lexicons declared by path in the configs loaded so far. */
 const modulePaths = new Map<string, string>();
 
+/** Name to the absolute directory fold trusts for that lexicon (chant#2590). Absent: only the module is trusted. */
+const moduleRoots = new Map<string, string>();
+
+/** True when `path` is `dir` itself or lies under it. Both are absolute. */
+function isWithin(path: string, dir: string): boolean {
+  const rel = relative(dir, path);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/**
+ * chant#2590 — the directory fold trusts for a lexicon declared by path.
+ *
+ * A package has a root that bounds its subpaths. A module path has none, so
+ * the directory is either the one `root` names, resolved like `module`, or the
+ * module's own directory. It must lie inside the project (`baseDir`, the
+ * directory holding `chant.config.ts`) and must not contain the project's
+ * source directory (`sourceDir`, relative to `baseDir`, default `.`). The
+ * module must lie inside it.
+ *
+ * Returns the directory, or `undefined` when only the module file is trusted.
+ * A declared `root` that breaks a rule returns a `problem` to report; the
+ * module's own directory breaking one (a module at the project root, say)
+ * just leaves the lexicon with its module file.
+ */
+export function pathLexiconRoot(
+  entry: { module: string; root?: string },
+  baseDir: string,
+  sourceDir = ".",
+): { root?: string; problem?: string } {
+  const modulePath = isAbsolute(entry.module) ? entry.module : resolve(baseDir, entry.module);
+  const declared = entry.root !== undefined;
+  const candidate = declared
+    ? isAbsolute(entry.root!)
+      ? resolve(entry.root!)
+      : resolve(baseDir, entry.root!)
+    : dirname(modulePath);
+  const project = resolve(baseDir);
+  const source = resolve(baseDir, sourceDir);
+  let problem: string | undefined;
+  if (!isWithin(candidate, project)) problem = `${candidate} is outside the project (${project})`;
+  else if (isWithin(source, candidate)) problem = `${candidate} contains the project's source directory (${source})`;
+  else if (!isWithin(modulePath, candidate)) problem = `the module ${modulePath} is not inside ${candidate}`;
+  if (problem === undefined) return { root: candidate };
+  return declared ? { problem } : {};
+}
+
 /**
  * Record the path-declared entries of one loaded config. `baseDir` is the
  * directory the config file sits in. A plain-string entry for a name removes
@@ -57,28 +107,65 @@ const modulePaths = new Map<string, string>();
 export function registerLexiconDeclarations(
   entries: readonly LexiconDeclaration[] | undefined,
   baseDir: string,
+  sourceDir?: string,
 ): Record<string, string> {
   const recorded: Record<string, string> = {};
   for (const entry of entries ?? []) {
     if (typeof entry === "string") {
       modulePaths.delete(entry);
+      moduleRoots.delete(entry);
       continue;
     }
-    const path = isAbsolute(entry.module) ? entry.module : resolve(baseDir, entry.module);
+    const path = declaredModulePath(entry, baseDir);
     modulePaths.set(entry.name, path);
     recorded[entry.name] = path;
+    const { root } = pathLexiconRoot(entry, baseDir, sourceDir);
+    if (root === undefined) moduleRoots.delete(entry.name);
+    else moduleRoots.set(entry.name, root);
   }
   return recorded;
 }
 
+function declaredModulePath(entry: { module: string }, baseDir: string): string {
+  return isAbsolute(entry.module) ? entry.module : resolve(baseDir, entry.module);
+}
+
+/**
+ * chant#2589 — the name-to-path map `entries` declare, without recording it.
+ * For a caller that must name path lexicons in its messages but must never
+ * let a loader import one (`chant audit` runs no project code).
+ */
+export function pathLexiconMap(entries: readonly LexiconDeclaration[], baseDir: string): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const entry of entries) {
+    if (typeof entry !== "string") map.set(entry.name, declaredModulePath(entry, baseDir));
+  }
+  return map;
+}
+
+/** A copy of the paths recorded so far in this process. */
+export function recordedLexiconModules(): Map<string, string> {
+  return new Map(modulePaths);
+}
+
 /** The absolute module path `name` was declared with, or `undefined` for a package-backed lexicon. */
 export function lexiconModulePath(name: string): string | undefined {
   return modulePaths.get(name);
 }
 
+/**
+ * chant#2590 — the directory fold trusts for a path-declared lexicon, or
+ * `undefined` when only its module file is trusted (or `name` is package-backed).
+ * See {@link pathLexiconRoot}.
+ */
+export function lexiconModuleRoot(name: string): string | undefined {
+  return moduleRoots.get(name);
+}
+
 /** Forget every recorded path. For tests. */
 export function resetLexiconModules(): void {
   modulePaths.clear();
+  moduleRoots.clear();
 }
 
 /**
@@ -102,16 +189,27 @@ export async function importLexiconModule(name: string): Promise<Record<string,
 /**
  * chant#2578 — how a message should name a lexicon. A package-backed name is
  * its npm package; a lexicon declared by path is that path, relative to
- * `fromDir` when it sits under it.
+ * `fromDir` when it sits under it. `paths` defaults to the paths recorded in
+ * this process; see {@link pathLexiconMap} for a map that is not recorded.
  */
-export function lexiconSourceLabel(name: string, fromDir: string = process.cwd()): string {
-  const path = modulePaths.get(name);
+export function lexiconSourceLabel(
+  name: string,
+  fromDir: string = process.cwd(),
+  paths: ReadonlyMap<string, string> = modulePaths,
+): string {
+  const path = paths.get(name);
   if (path === undefined) return `@intentius/chant-lexicon-${name}`;
   const rel = relative(fromDir, path);
   return rel === "" || rel.startsWith("..") || isAbsolute(rel) ? path : `./${rel.split(sep).join("/")}`;
 }
 
-/** The npm packages that provide `names`, leaving out every lexicon declared by path: those have nothing to install. */
-export function lexiconPackagesToInstall(names: readonly string[]): string[] {
-  return names.filter((name) => !modulePaths.has(name)).map((name) => `@intentius/chant-lexicon-${name}`);
+/**
+ * The npm packages that provide `names`, leaving out every lexicon declared by
+ * path: those have nothing to install. `paths` as in {@link lexiconSourceLabel}.
+ */
+export function lexiconPackagesToInstall(
+  names: readonly string[],
+  paths: ReadonlyMap<string, string> = modulePaths,
+): string[] {
+  return names.filter((name) => !paths.has(name)).map((name) => `@intentius/chant-lexicon-${name}`);
 }

package/src/lexicon.ts

@@ -501,6 +501,78 @@ export interface ComponentPipelineOptions {
    * `["chant", "components", "promote", "--from", <env>, "--to", <promoteTo>]`.
    */
   promoteCommand?: string[];
+  /**
+   * The workspace member this pipeline belongs to (#2542, #2524 D19). Core
+   * sets it when the project sits in a member of a `chant.workspace.json`;
+   * a caller never needs to. Unset, every generator's output is unchanged.
+   * Set, the pipeline keeps the triggers it has without a member, and the
+   * ones that can take a path filter (an Op's `push` and `pull_request`, and
+   * GitLab's job rules) are limited to the member's files and the pipeline
+   * file. Its jobs run in the member's directory, and its names carry the
+   * member's name so two members' pipelines never collide.
+   */
+  member?: PipelineMember;
+}
+
+/** Where a workspace member sits, for a generated pipeline (#2542). */
+export interface PipelineMember {
+  /** The member's name in the declaration. */
+  name: string;
+  /**
+   * The member's directory relative to the repository root, with `/`
+   * separators, or `"."` for a member at the root.
+   */
+  dir: string;
+  /**
+   * Directories (repository-relative) that belong to other members or to
+   * example groups. Only a member at `"."` uses them: its path filter is the
+   * whole repository minus these.
+   */
+  exclude?: string[];
+  /** The generated component pipeline's path, repository-relative. Added to the path filter. */
+  file?: string;
+  /**
+   * The directory (repository-relative) the generated Op pipeline files land
+   * in. Each file's own path is added to its path filter.
+   */
+  fileDir?: string;
+}
+
+/** `path` (relative to the member's directory) made relative to the repository root. Absolute paths pass through. */
+export function memberRepoPath(member: PipelineMember, path: string): string {
+  if (path.startsWith("/") || member.dir === "." || member.dir === "") return path;
+  const rest = path.replace(/^\.\/+/, "").replace(/\/+$/, "");
+  return rest === "" || rest === "." ? member.dir : `${member.dir}/${rest}`;
+}
+
+/**
+ * The path filter for a member's `push` or `pull_request` trigger in GitHub
+ * Actions syntax (also Forgejo's): the member's directory and the pipeline
+ * file. A member at
+ * `"."` gets every path, minus the other members' directories.
+ */
+export function memberPathFilter(member: PipelineMember, file: string | undefined = member.file): string[] {
+  const paths =
+    member.dir === "." || member.dir === ""
+      ? ["**", ...(member.exclude ?? []).map((d) => `!${d}/**`)]
+      : [`${member.dir}/**`];
+  if (file && !paths.includes(file)) paths.push(file);
+  return paths;
+}
+
+/**
+ * The `rules: changes:` list for a member's GitLab jobs, or undefined for a
+ * member at `"."`: GitLab's `changes` has no exclusions, so the root member's
+ * jobs run on every change.
+ */
+export function memberGitlabChanges(member: PipelineMember, file: string | undefined = member.file): string[] | undefined {
+  if (member.dir === "." || member.dir === "") return undefined;
+  return [`${member.dir}/**/*`, ...(file ? [file] : [])];
+}
+
+/** A shell word for `cd` into the member's directory. */
+export function memberShellDir(member: PipelineMember): string {
+  return /^[A-Za-z0-9._\/-]+$/.test(member.dir) ? member.dir : `'${member.dir.replace(/'/g, `'\\''`)}'`;
 }
 
 /** The synthesized CI pipeline for a component graph (generate mode). */
@@ -1938,7 +2010,13 @@ export interface ResourceMetadata {
   status: string;
   /** ISO timestamp of last update */
   lastUpdated?: string;
-  /** Cloud-assigned output properties */
+  /**
+   * Cloud-assigned output properties. Two keys are read by `components status
+   * --live` (#2513): `digest` (the artifact digest serving now) and `gitSha`
+   * (the commit it was built from). Set them when the live read knows them; a
+   * value that differs from the recorded release reports the component
+   * `drifted`. See `LIVE_IDENTITY_ATTRIBUTES` in lifecycle/status.ts.
+   */
   attributes?: Record<string, unknown>;
   /**
    * Live ownership verdict from the resource's marker (#119/#120). `owned` =

package/src/lifecycle/build-ledger-store.ts

@@ -55,7 +55,7 @@
  */
 
 import { sortedJsonReplacer } from "../utils";
-import { warnOnLegacyDigests } from "./legacy-digest";
+import { flagLegacyDigest, warnOnLegacyDigests, withoutReadFlags } from "./legacy-digest";
 import { writeBlobToPath, readBlobFromPath, listFilesInDir } from "./git";
 import type { BuildArchiveManifest } from "../components/verbs/build-archive";
 
@@ -87,7 +87,8 @@ export async function persistBuildManifest(
   manifest: BuildArchiveManifest,
   opts?: { cwd?: string },
 ): Promise<{ commit: string }> {
-  const json = JSON.stringify(manifest, sortedJsonReplacer);
+  // `flags` are read-side only (#2514); a manifest read back and persisted again never keeps them.
+  const json = JSON.stringify(withoutReadFlags(manifest), sortedJsonReplacer);
   const commit = await writeBlobToPath(BUILDS_DIR, manifestFilename(manifest.manifestDigest), json, "Build manifest", opts);
   return { commit };
 }
@@ -111,14 +112,14 @@ export async function readBuildManifest(
   } catch {
     return null;
   }
-  // chant #2514 — a release ahead of real SHA-256 digests, say once that
-  // the persisted manifests hold values in the old form.
-  warnOnLegacyDigests(
-    [manifest.manifestDigest, ...(Array.isArray(manifest.contents) ? manifest.contents.map((e) => e?.digest) : [])],
-    "build manifests",
-    opts?.cwd,
-  );
-  return manifest;
+  // chant #2514 — a manifest whose digests predate real SHA-256 is flagged
+  // legacy-digest, never re-keyed, and the project is warned once.
+  const digests = [
+    manifest.manifestDigest,
+    ...(Array.isArray(manifest.contents) ? manifest.contents.map((e) => e?.digest) : []),
+  ];
+  warnOnLegacyDigests(digests, "build manifests", opts?.cwd);
+  return flagLegacyDigest(manifest, digests);
 }
 
 /** List the `manifestDigest` of every build manifest persisted on the orphan branch. */

package/src/lifecycle/digest.ts

@@ -7,15 +7,19 @@
 import type { BuildResult } from "../build";
 import type { Declarable } from "../declarable";
 import type { BuildDigest, ResourceDigest, DigestDiff } from "./types";
-import { sortedJsonReplacer } from "../utils";
-import { getRuntime } from "../runtime-adapter";
+import { canonicalJson } from "../effect-receipt";
+import { contentDigest } from "../content-digest";
 
 /**
- * Hash an entity's props deterministically.
+ * Hash an entity's props deterministically: bare hex SHA-256 over their
+ * `canonicalJson` (chant #2514). Props are first passed through
+ * `JSON.stringify`, which applies `toJSON` and drops what JSON cannot hold
+ * (a function-valued prop, say), so a prop that serialises today still
+ * hashes rather than throwing.
  */
 export function hashProps(props: unknown): string {
-  const json = JSON.stringify(props, sortedJsonReplacer);
-  return getRuntime().hash(json);
+  const plain: unknown = JSON.parse(JSON.stringify(props) ?? "null");
+  return contentDigest(canonicalJson(plain)).slice("sha256:".length);
 }
 
 /**

package/src/lifecycle/gate-ledger.test.ts

@@ -253,6 +253,26 @@ describe("lifecycle/gate-ledger — pending facts (#2119)", () => {
       expect(resolutions).toEqual([]);
     });
   });
+
+  // #2574: an environment that is present but not a string would read as an
+  // approval bound to no environment, which a component gate treats differently.
+  test("a line whose environment is not a string is malformed", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeBlobToPath(
+        "_gates", "search-service.jsonl",
+        [
+          JSON.stringify({ version: 1, op: "search-service", gate: "g", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z", environment: 7 }),
+          JSON.stringify({ version: 1, op: "search-service", gate: "g", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z", environment: "prod" }),
+        ].join("\n"),
+        "hand-written",
+        { cwd: dir },
+      );
+      const { resolutions, malformed } = await readGateLedger("search-service", { cwd: dir });
+      expect(malformed).toBe(1);
+      expect(resolutions.map((r) => r.environment)).toEqual(["prod"]);
+    });
+  });
 });
 
 /**

package/src/lifecycle/gate-ledger.ts

@@ -140,6 +140,13 @@ export interface GateResolutionRecord {
    * such a record proves is that somebody approved *something*.
    */
   planDigest?: string;
+  /**
+   * The environment this approval is for (#2574), copied off the pending fact
+   * it answers. Set for a component gate, whose ledger is keyed by component
+   * rather than by environment. A component gate counts only a resolution
+   * recorded for its own environment and plan.
+   */
+  environment?: string;
   /**
    * The channel this resolution was authored on (chant#2384) — set by the
    * writer, never by the caller. `chant approve` records `"cli"`, the
@@ -217,10 +224,18 @@ export interface PendingGateRecord {
    * resolution by default, so approving the standing fact approves the plan
    * the approver was shown rather than the next run's.
    *
-   * Absent when the gate binds no plan (a component gate, an authored `gate`
-   * step with no `plan`), which is the shape every gate had before #2300.
+   * Absent when the gate binds no plan (an authored Op `gate` step with no
+   * `plan`), which is the shape every gate had before #2300. A component gate
+   * binds one since #2574.
    */
   planDigest?: string;
+  /**
+   * The environment the run reached this gate in (#2574). Set by the
+   * component driver, whose gate ledger is keyed by component, so pending
+   * facts for staging and prod stand side by side and `chant approve --env`
+   * can pick one.
+   */
+  environment?: string;
   /**
    * The channel the run that reached this gate was driven from (chant#2384).
    *
@@ -260,8 +275,8 @@ function filename(op: string): string {
  * fact was appended to (#2243) rather than describing it in prose that drifts
  * from `DIR`.
  */
-export function gateLedgerPath(op: string): string {
-  return `${DIR}/${filename(op)}`;
+export function gateLedgerPath(op: string, memberPrefix = ""): string {
+  return `${memberPrefix}${DIR}/${filename(op)}`;
 }
 
 /** Append one immutable gate-resolution record. Does not push to the remote — call `pushLifecycle` (./git.ts) afterward, same two-step shape every other ledger write here uses. Retries on `RefCASConflictError` the same way `appendConvergeRecord` does (./converge-ledger.ts) — a concurrent writer to a different op's/env's file on the same orphan branch is the ordinary case, not an edge case. The baseline read must be `readPathSha` + `readBlobBySha` rather than `readBlobFromPath`, so the exact sha `existing` came from can be passed as `expectPriorPathSha` — see `writeBlobToPath` (./git.ts) for the race that closes. */
@@ -361,6 +376,13 @@ export async function readGateLedger(
         malformed++;
         continue;
       }
+      // #2574: the same reasoning for the environment a component gate
+      // approval is bound to.
+      const rawEnv: unknown = (parsed as { environment?: unknown }).environment;
+      if (rawEnv !== undefined && typeof rawEnv !== "string") {
+        malformed++;
+        continue;
+      }
       if (parsed.kind === "pending") {
         if (typeof parsed.expiresAt !== "string") {
           malformed++;
@@ -442,8 +464,8 @@ export interface PlanBoundResolution {
  * which a run answers yes to no matter what has changed since, and this asks
  * "is there an approval of *this*".
  *
- * - `planDigest` `undefined` — the gate binds no plan (a component gate, a
- *   `gate` step authored with no `plan`). Falls straight through to
+ * - `planDigest` `undefined` — the gate binds no plan (an Op `gate` step
+ *   authored with no `plan`). Falls straight through to
  *   {@link latestResolutionSince}: gates that never claimed to bind a plan
  *   behave exactly as they did before #2300.
  * - A resolution whose `planDigest` equals `planDigest` answers the gate.

package/src/lifecycle/git.test.ts

@@ -1,7 +1,7 @@
 import { describe, test, expect } from "vitest";
 import { withTestDir } from "@intentius/chant-test-utils";
 import { spawnSync } from "node:child_process";
-import { writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
@@ -130,6 +130,18 @@ describe("lifecycle/git", () => {
       });
     });
 
+    test("a write from a subdirectory of the repository keeps the rest of the branch (#2550)", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await writeBlobToPath("_builds", "a.json", "{}", "m", { cwd: dir });
+        const sub = join(dir, "project");
+        mkdirSync(sub);
+        await writeBlobToPath("_gates", "op.jsonl", "{}", "m", { cwd: sub });
+        expect(await listFilesInDir("_builds", { cwd: sub })).toEqual(["a.json"]);
+        expect(await readBlobFromPath("_gates", "op.jsonl", { cwd: dir })).toBe("{}");
+      });
+    });
+
     test("readBlobFromPath returns null for a missing directory/file", async () => {
       await withTestDir(async (dir) => {
         await initRepo(dir);