@intentius/chant 0.79.0 → 0.81.0

package/src/lexicon-module.ts

@@ -0,0 +1,215 @@
+/**
+ * Lexicons declared by module path (chant #2520).
+ *
+ * A `lexicons` entry has always been a bare name, and chant resolves a name to
+ * the package `@intentius/chant-lexicon-<name>`. A project that writes its own
+ * lexicon in the same repo can instead point at the module:
+ *
+ * ```ts
+ * export default {
+ *   lexicons: ["fly", { name: "site", module: "./lexicon/index.ts" }],
+ * } satisfies ChantConfig;
+ * ```
+ *
+ * The path is resolved against the directory holding `chant.config.ts`. That
+ * module is the whole lexicon: its `LexiconPlugin` export is the plugin, the
+ * plugin's `activities()` and `activityContracts()` members stand in for the
+ * `op/activities` and `op/activity-contracts` subpaths, a `CapabilityPlugin`
+ * export feeds the capability registry, and an `evaluateGatePolicy` export
+ * stands in for the `gate-policy` subpath.
+ *
+ * Loaders take lexicon names, so the config loader records each path-declared
+ * name here and every loader asks {@link lexiconModulePath} before falling back
+ * to the package name. A name declared as a plain string is never recorded, so
+ * a project that names lexicons by package takes exactly the path it always did.
+ */
+
+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. `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 {
+  return typeof entry === "string" ? entry : entry.name;
+}
+
+/** Every entry's name, in declaration order. `undefined` in, `undefined` out. */
+export function lexiconNames(entries: readonly LexiconDeclaration[]): string[];
+export function lexiconNames(entries: readonly LexiconDeclaration[] | undefined): string[] | undefined;
+export function lexiconNames(entries: readonly LexiconDeclaration[] | undefined): string[] | undefined {
+  return entries?.map(lexiconDeclarationName);
+}
+
+/** 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
+ * any path recorded for it earlier in this process, so loading a second
+ * project (the example harness does) cannot leave the first one's module in
+ * place of a package.
+ *
+ * Returns the recorded name-to-path map for this config, empty when every
+ * entry is a plain name.
+ */
+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 = 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();
+}
+
+/**
+ * Import the module a path-declared lexicon names. Returns `undefined` when
+ * `name` is package-backed, so a caller falls through to its package import.
+ * An import failure is thrown with the declared path in the message.
+ */
+export async function importLexiconModule(name: string): Promise<Record<string, unknown> | undefined> {
+  const path = modulePaths.get(name);
+  if (path === undefined) return undefined;
+  try {
+    return (await import(path)) as Record<string, unknown>;
+  } catch (err) {
+    throw new Error(
+      `lexicon "${name}" is declared with module ${path}, which could not be loaded: ` +
+        (err instanceof Error ? err.message : String(err)),
+    );
+  }
+}
+
+/**
+ * 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. `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(),
+  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. `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

@@ -486,6 +486,93 @@ export interface ComponentPipelineOptions {
    * this too when the file should land under some other name than its stage.
    */
   opsFileName?: string;
+  /**
+   * An environment to promote to after the deploy (#2575). The component
+   * generators add one job that needs every component job and runs
+   * `chant components promote --from <env> --to <promoteTo>`. Each component
+   * job also uploads the files its build steps wrote (see
+   * `promoteArchivePaths` in `components/promote.ts`), and the promote job
+   * downloads them, since a promote publishes from the archive on disk.
+   * Unset, the pipeline has no promote job and is unchanged.
+   */
+  promoteTo?: string;
+  /**
+   * The promote job's command as argv, when `promoteTo` is set. Default
+   * `["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). */
@@ -939,6 +1026,17 @@ export interface LexiconPlugin {
    */
   activityContracts?(): ActivityContract[];
 
+  /**
+   * Op activity implementations, keyed by the name a step's `fn` calls them
+   * by (chant #2520). Read only for a lexicon declared by module path
+   * (`{ name, module }` in `chant.config.ts`), which has no
+   * `@intentius/chant-lexicon-<name>/op/activities` subpath for
+   * `loadActivities` to import. A package-backed lexicon keeps using the
+   * subpath and leaves this out.
+   */
+  activities?(): Record<string, (args: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown>>
+    | Promise<Record<string, (args: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown>>>;
+
   /**
    * Audit catalog metadata (title/tier/fix/authority/category) for this
    * lexicon's `postSynthChecks`, keyed by check id — the per-provider half of
@@ -1912,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,6 +55,7 @@
  */
 
 import { sortedJsonReplacer } from "../utils";
+import { flagLegacyDigest, warnOnLegacyDigests, withoutReadFlags } from "./legacy-digest";
 import { writeBlobToPath, readBlobFromPath, listFilesInDir } from "./git";
 import type { BuildArchiveManifest } from "../components/verbs/build-archive";
 
@@ -86,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 };
 }
@@ -104,11 +106,20 @@ export async function readBuildManifest(
 ): Promise<BuildArchiveManifest | null> {
   const content = await readBlobFromPath(BUILDS_DIR, manifestFilename(manifestDigest), opts);
   if (!content) return null;
+  let manifest: BuildArchiveManifest;
   try {
-    return JSON.parse(content) as BuildArchiveManifest;
+    manifest = JSON.parse(content) as BuildArchiveManifest;
   } catch {
     return null;
   }
+  // 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);