@intentius/chant 0.70.1 → 0.71.1

package/src/components/fan-out.ts

@@ -0,0 +1,421 @@
+/**
+ * Fan a change out downstream, in an order derived from the source (#2417).
+ *
+ * The order was never the missing piece. `resolveComponentGraph` (./driver.ts)
+ * already Kahn-layers a component set by `dependsOn` into parallel-safe waves,
+ * flattens to a topological order, refuses a cycle by name and refuses a
+ * `dependsOn` it has not been given. What it cannot do is order a *subset*:
+ * hand it the affected components alone and it throws `UnknownDependencyError`,
+ * because a selected component still names a dependency that is not in the set.
+ *
+ * That is what this module is. Given every component in the project and the
+ * ones whose inputs moved, it derives who else has to run, in what order, what
+ * has to be seeded because it is deliberately not running, and one digest that
+ * identifies the whole derivation so a single gate can be bound to it.
+ *
+ * ## Why derived rather than declared
+ *
+ * The competing shape is a registry where you write down that component B
+ * depends on component A. That registry is a second statement of a relationship
+ * the source already makes, and it is wrong the first time somebody adds a
+ * reference without updating it. `dependsOn` is in the component; the graph is
+ * a walk over it.
+ *
+ * ## Three outcomes, never two
+ *
+ * A component is selected, skipped as unaffected, or **indeterminate** — the
+ * same third answer `../lifecycle/affected.ts` already refuses to collapse. A
+ * component whose inputs arrive at deploy time cannot be judged from a source
+ * diff, so it is reported rather than guessed at in either direction. Fanning
+ * out to everything on any change is easy to build, worth nothing, and reads
+ * exactly like diligence in a log.
+ *
+ * This plans; it does not run. Executing the plan is ./driver.ts's job.
+ */
+
+import { resolveComponentGraph, type DriverComponent } from "./driver";
+import { deployUnits } from "./deploy-units";
+import { computePlanDigest } from "../lifecycle/plan-digest";
+
+/** Thrown when `changed` or `indeterminate` names a component the project does not have. */
+export class UnknownComponentError extends Error {
+  constructor(
+    readonly field: "changed" | "indeterminate",
+    readonly component: string,
+    known: string[],
+  ) {
+    super(
+      `${field} names "${component}", which is not a component in this project ` +
+        `(known: ${known.join(", ") || "none"})`,
+    );
+    this.name = "UnknownComponentError";
+  }
+}
+
+/** Why a component is in the plan but not running. */
+export type FanOutSkipReason =
+  /** Nothing it depends on moved, and it did not move itself. */
+  | "unaffected"
+  /** Its inputs arrive at deploy time, so a source diff cannot judge it. */
+  | "indeterminate"
+  /** It already applied in an earlier attempt at this same fan-out. */
+  | "already-applied"
+  /** Something it depends on failed, so the value it would read never landed. */
+  | "blocked";
+
+export interface FanOutSkip {
+  component: string;
+  reason: FanOutSkipReason;
+  /** For `blocked`, the failed component the walk reached this one from. */
+  blockedBy?: string;
+}
+
+export interface FanOutRequest {
+  /** Every component in the project, `dependsOn` intact. The full graph is what makes a subset orderable. */
+  components: DriverComponent[];
+  /** Components whose own inputs moved. The walk starts here. */
+  changed: string[];
+  /**
+   * Components a source diff cannot judge (`../lifecycle/affected.ts`'s third
+   * category). One that the walk reaches anyway is selected like any other
+   * dependent — reachability is a fact about the graph, not about whether the
+   * component's own inputs could be read. One the walk does not reach is
+   * reported, never decided.
+   */
+  indeterminate?: string[];
+  /**
+   * Per-component input identity, when the caller has it. Folded into
+   * {@link FanOutPlan.digest} so an approval is bound to *what* would be
+   * applied and not only to who would run. Absent, the digest still identifies
+   * the derivation — the selection, the order and the edges it came from.
+   */
+  inputDigests?: Record<string, string>;
+}
+
+export interface FanOutPlan {
+  /** The components to run, every dependency before its dependents. */
+  order: string[];
+  /**
+   * Parallel-safe waves over the selected set. A dependency that is not
+   * selected is already satisfied — its outputs are seeded — so it does not
+   * hold its dependents back a wave.
+   */
+  waves: string[][];
+  /** Components deliberately not running, with why. Sorted by name. */
+  skipped: FanOutSkip[];
+  /**
+   * Dependencies of selected components that are not themselves selected.
+   * Their outputs have to be seeded for a reference to resolve, which is the
+   * price of running a subset rather than the whole graph.
+   */
+  seeds: string[];
+  /** Components a source diff could not judge and the walk did not reach. Reported, never decided. */
+  indeterminate: string[];
+  /** Identity of this derivation, for binding one approval to the whole fan-out (#2300's pattern). */
+  digest: string;
+}
+
+/** Reverse the `dependsOn` edges: who has to re-run when this one moves. */
+function consumersOf(components: DriverComponent[]): Map<string, string[]> {
+  const consumers = new Map<string, string[]>();
+  for (const c of components) {
+    for (const dep of c.dependsOn ?? []) {
+      const existing = consumers.get(dep);
+      if (existing) existing.push(c.name);
+      else consumers.set(dep, [c.name]);
+    }
+  }
+  return consumers;
+}
+
+/**
+ * Derive the fan-out for a change.
+ *
+ * Refuses a cycle and an unknown `dependsOn` before selecting anything, by
+ * resolving the **full** graph first — a broken graph is a broken graph whether
+ * or not the change happens to touch the broken part, and finding out halfway
+ * through a fan-out is worse than finding out before it starts.
+ */
+export function planFanOut(request: FanOutRequest): FanOutPlan {
+  const { components, changed, indeterminate = [], inputDigests } = request;
+
+  // Refuses DependencyCycleError / UnknownDependencyError over the whole graph.
+  // Its `order` is deliberately not used: `topoSort` walks in declaration
+  // order, so two projects with the same graph and a different file layout
+  // would derive different-looking fan-outs and digest differently. The waves
+  // below are canonical, and this plan's order is their flattening.
+  resolveComponentGraph(components);
+
+  const byName = new Map(components.map((c) => [c.name, c]));
+  for (const name of changed) {
+    if (!byName.has(name)) throw new UnknownComponentError("changed", name, [...byName.keys()].sort());
+  }
+  for (const name of indeterminate) {
+    if (!byName.has(name)) throw new UnknownComponentError("indeterminate", name, [...byName.keys()].sort());
+  }
+
+  // Everything reachable downstream of a changed component, transitively. A
+  // component reached by two paths is added once, which is the diamond case.
+  const consumers = consumersOf(components);
+  const selected = new Set<string>(changed);
+  const queue = [...changed];
+  while (queue.length > 0) {
+    const node = queue.shift()!;
+    for (const consumer of consumers.get(node) ?? []) {
+      if (selected.has(consumer)) continue;
+      selected.add(consumer);
+      queue.push(consumer);
+    }
+  }
+
+  // Waves over the selected subgraph only. An unselected dependency is already
+  // applied, so it is not a reason for its dependents to wait.
+  const remaining = new Set(selected);
+  const selectedDeps = new Map(
+    [...selected].map((name) => [name, new Set((byName.get(name)!.dependsOn ?? []).filter((d) => selected.has(d)))]),
+  );
+  const waves: string[][] = [];
+  while (remaining.size > 0) {
+    const wave = [...remaining]
+      .filter((n) => [...selectedDeps.get(n)!].every((d) => !remaining.has(d)))
+      .sort();
+    // resolveComponentGraph already refused every cycle in the full graph, and
+    // a subgraph of an acyclic graph is acyclic, so this cannot stall.
+    for (const n of wave) remaining.delete(n);
+    waves.push(wave);
+  }
+
+  // Every dependency lands in an earlier wave than its dependents, so the
+  // flattening is a topological order, and a sorted one.
+  const order = waves.flat();
+
+  const seeds = [
+    ...new Set(order.flatMap((name) => (byName.get(name)!.dependsOn ?? []).filter((d) => !selected.has(d)))),
+  ].sort();
+
+  const unreachedIndeterminate = indeterminate.filter((name) => !selected.has(name)).sort();
+  const indeterminateSet = new Set(unreachedIndeterminate);
+  const skipped: FanOutSkip[] = [...byName.keys()]
+    .filter((name) => !selected.has(name))
+    .sort()
+    .map((component) => ({
+      component,
+      reason: indeterminateSet.has(component) ? ("indeterminate" as const) : ("unaffected" as const),
+    }));
+
+  // What the approver is approving: who runs, in what order, off which edges,
+  // and — when the caller knows it — what each one would apply. Never the run
+  // id or the moment, per ../lifecycle/plan-digest.ts's rules, so re-deriving
+  // an unchanged fan-out does not expire an approval.
+  const digest = computePlanDigest("component-fan-out", {
+    order,
+    waves,
+    seeds,
+    edges: order.map((name) => ({ component: name, dependsOn: [...(byName.get(name)!.dependsOn ?? [])].sort() })),
+    ...(inputDigests
+      ? { inputs: order.map((name) => ({ component: name, digest: inputDigests[name] ?? null })) }
+      : {}),
+  });
+
+  return { order, waves, skipped, seeds, indeterminate: unreachedIndeterminate, digest };
+}
+
+// ── Joining the change signal to components ──────────────────────────────────
+
+/**
+ * `../lifecycle/affected.ts`'s answer, which is about **stacks**.
+ *
+ * `AffectedResult` itself is not imported: this takes the two fields the join
+ * needs, so a caller can also hand in a signal that did not come from a git
+ * diff (a CI system's own changed-paths answer, an operator naming a stack by
+ * hand) without manufacturing the rest of that shape.
+ */
+export interface ChangedUnits {
+  /** Stacks whose built artifact moved between base and head. */
+  changed: string[];
+  /** Stacks a source diff could not judge, because their inputs arrive at deploy time. */
+  indeterminate?: string[];
+}
+
+/** What {@link componentsForUnits} resolved, ready to hand to {@link planFanOut}. */
+export interface ComponentChangeSignal {
+  /** Components deploying at least one changed unit. */
+  changed: string[];
+  /** Components deploying no changed unit but at least one indeterminate one. */
+  indeterminate: string[];
+  /**
+   * Changed or indeterminate units no component claims. Reported rather than
+   * dropped: a stack that moved and belongs to nothing this project deploys is
+   * a hole in the fan-out's coverage, and a silent one is the failure mode
+   * this whole feature exists to avoid.
+   */
+  unclaimed: string[];
+}
+
+/**
+ * Join a stack-level change signal to the components that deploy those stacks.
+ *
+ * The key is `deployUnits` (./deploy-units.ts), which already answers "what
+ * live units does this component's composition target" for `chant components
+ * status --live`. Reusing it means a component's claim on a stack is stated
+ * once, by its deploy steps, rather than restated in a fan-out config — the
+ * same argument this module's doc makes about `dependsOn`.
+ *
+ * Changed beats indeterminate. A component deploying one stack that certainly
+ * moved and another that could not be judged is changed: the certainty already
+ * decides it, and reporting it as indeterminate would lose that.
+ */
+export function componentsForUnits(
+  components: DriverComponent[],
+  units: ChangedUnits,
+): ComponentChangeSignal {
+  const changedUnits = new Set(units.changed);
+  const indeterminateUnits = new Set(units.indeterminate ?? []);
+
+  const changed: string[] = [];
+  const indeterminate: string[] = [];
+  const claimed = new Set<string>();
+
+  for (const component of components) {
+    const names = deployUnits(component.deploy).map((u) => u.unit);
+    let touchesChanged = false;
+    let touchesIndeterminate = false;
+    for (const name of names) {
+      if (changedUnits.has(name)) {
+        touchesChanged = true;
+        claimed.add(name);
+      }
+      if (indeterminateUnits.has(name)) {
+        touchesIndeterminate = true;
+        claimed.add(name);
+      }
+    }
+    if (touchesChanged) changed.push(component.name);
+    else if (touchesIndeterminate) indeterminate.push(component.name);
+  }
+
+  const unclaimed = [...changedUnits, ...indeterminateUnits].filter((u) => !claimed.has(u));
+
+  return {
+    changed: changed.sort(),
+    indeterminate: indeterminate.sort(),
+    unclaimed: [...new Set(unclaimed)].sort(),
+  };
+}
+
+/**
+ * Components inside `within` that are transitively downstream of any of
+ * `roots`, each mapped to the **root** it was reached from rather than to its
+ * immediate parent — so a report names the one thing to fix instead of the
+ * nearest consequence of it.
+ *
+ * `roots` is sorted before the walk, so a component downstream of two separate
+ * roots always names the same one. Unsorted, the answer would depend on the
+ * order the caller listed them in, which is not a fact about anything.
+ *
+ * Shared by {@link remainingFanOut}, which needs it over a whole plan, and by
+ * the runner in ./fan-out-run.ts, which needs it as failures accumulate.
+ */
+export function downstreamWithin(
+  components: DriverComponent[],
+  within: Iterable<string>,
+  roots: readonly string[],
+): Map<string, string> {
+  const inside = new Set(within);
+  const consumers = consumersOf(components);
+  const rootSet = new Set(roots);
+  const reached = new Map<string, string>();
+  const queue = [...roots].sort();
+  while (queue.length > 0) {
+    const node = queue.shift()!;
+    const blamed = rootSet.has(node) ? node : reached.get(node)!;
+    for (const consumer of consumers.get(node) ?? []) {
+      if (!inside.has(consumer) || rootSet.has(consumer) || reached.has(consumer)) continue;
+      reached.set(consumer, blamed);
+      queue.push(consumer);
+    }
+  }
+  return reached;
+}
+
+// ── Finishing a fan-out that stopped ─────────────────────────────────────────
+
+export interface FanOutProgress {
+  /** Components that reached `ok` in an earlier attempt at this same plan. */
+  completed?: string[];
+  /** Components that failed. Everything downstream of one is blocked, not failed. */
+  failed?: string[];
+}
+
+/**
+ * Narrow a plan to what still has to run.
+ *
+ * **The digest does not change.** That is the whole point: an operator approved
+ * a fan-out, a component in the middle of it failed, and finishing the work
+ * they already approved must not ask them to approve it again. `remainingFanOut`
+ * returns the same `digest` the original derivation produced, so the standing
+ * resolution still satisfies the gate on the next attempt. Re-deriving with
+ * {@link planFanOut} would mint a new identity and invalidate the approval,
+ * which is why resume narrows a plan rather than recomputing one.
+ *
+ * **A component beneath a failure is `blocked`, never `failed`.** Nothing about
+ * it failed. It did not run because the value it would have read never landed,
+ * and the distinction is what makes the next attempt legible: an operator
+ * reading `blocked by "cluster-a"` knows to fix one thing, not fourteen.
+ *
+ * **Independent branches keep going.** The order was derived from the source,
+ * so a branch that shares no edge with the failure is *known* to be independent
+ * rather than assumed to be. Stopping it is the conservative-looking choice
+ * that throws away the reason for deriving the graph in the first place.
+ */
+export function remainingFanOut(
+  plan: FanOutPlan,
+  components: DriverComponent[],
+  progress: FanOutProgress,
+): FanOutPlan {
+  const byName = new Map(components.map((c) => [c.name, c]));
+  const planned = new Set(plan.order);
+  const completed = new Set((progress.completed ?? []).filter((n) => planned.has(n)));
+  const failed = new Set((progress.failed ?? []).filter((n) => planned.has(n)));
+
+  const blockedBy = downstreamWithin(components, planned, [...failed]);
+
+  const runnable = new Set(
+    plan.order.filter((n) => !completed.has(n) && !failed.has(n) && !blockedBy.has(n)),
+  );
+
+  // Re-layer what is left. A dependency that already applied is satisfied, so
+  // it does not hold its dependents back — the same rule the original
+  // derivation applies to a dependency outside the selection.
+  const remaining = new Set(runnable);
+  const deps = new Map(
+    [...runnable].map((n) => [n, new Set((byName.get(n)?.dependsOn ?? []).filter((d) => runnable.has(d)))]),
+  );
+  const waves: string[][] = [];
+  while (remaining.size > 0) {
+    const wave = [...remaining].filter((n) => [...deps.get(n)!].every((d) => !remaining.has(d))).sort();
+    for (const n of wave) remaining.delete(n);
+    waves.push(wave);
+  }
+  const order = waves.flat();
+
+  // A completed component's outputs have to be seeded for a reference to
+  // resolve, exactly like a component that was never selected.
+  const seeds = [
+    ...new Set([
+      ...plan.seeds,
+      ...order.flatMap((n) => (byName.get(n)?.dependsOn ?? []).filter((d) => !runnable.has(d))),
+    ]),
+  ].sort();
+
+  const carried = plan.skipped.filter((s) => !runnable.has(s.component));
+  const skipped: FanOutSkip[] = [
+    ...carried,
+    ...[...completed].sort().map((component) => ({ component, reason: "already-applied" as const })),
+    ...[...blockedBy.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([component, by]) => ({ component, reason: "blocked" as const, blockedBy: by })),
+  ].sort((a, b) => a.component.localeCompare(b.component));
+
+  return { order, waves, skipped, seeds, indeterminate: plan.indeterminate, digest: plan.digest };
+}

package/src/components/index.ts

@@ -100,6 +100,39 @@ export {
   UnknownDependencyError,
   DriverRunFailure,
 } from "./driver";
+export {
+  type FanOutRequest,
+  type FanOutPlan,
+  type FanOutSkip,
+  type FanOutSkipReason,
+  type ChangedUnits,
+  type ComponentChangeSignal,
+  type FanOutProgress,
+  planFanOut,
+  componentsForUnits,
+  remainingFanOut,
+  downstreamWithin,
+  UnknownComponentError,
+} from "./fan-out";
+export {
+  type FanOutGate,
+  type FanOutRunOptions,
+  type FanOutRunResult,
+  runFanOut,
+} from "./fan-out-run";
+export {
+  type FanOutGateRef,
+  type FanOutRenderOptions,
+  renderFanOutPlan,
+  renderFanOutHuman,
+  renderFanOutJson,
+} from "./fan-out-output";
+export {
+  type DeriveFanOutOptions,
+  type DerivedFanOut,
+  deriveFanOut,
+  fanOutRegistry,
+} from "./fan-out-support";
 export {
   EcsFargateComponent,
   type EcsFargateComponentConfig,

package/src/discovery/fold-import.ts

@@ -1247,6 +1247,21 @@ interface ResolveCtx {
    * behavior doesn't depend on it.
    */
   crossFileFailures: Map<string, string>;
+  /**
+   * chant #2422/#2423 — for a same-file `const x = new T(...)` whose pre-build
+   * ({@link preresolveResourceConsts}) failed, WHY, located.
+   *
+   * The pre-build swallows a failed construction by design, so the name stays
+   * absent from {@link externals} and the first reference to it rejects with
+   * "same-file resource `x` used as a value", at the reference. That rejection
+   * is right, and it points at the consequence: the located cause is on the
+   * `new` line, which the reader never sees. `F-Reason` asks a reason to carry
+   * the innermost located cause, so {@link describeFoldFailure} appends this.
+   *
+   * Present only on the one context the pre-build runs in. Purely cosmetic;
+   * nothing about whether a file folds depends on it.
+   */
+  prebuildFailures?: Map<string, string>;
   /**
    * chant #1020 hang fix — session-wide {@link importModule} memo (see
    * {@link FoldSession.importCache}'s doc). Every constructor/composite-
@@ -3235,9 +3250,16 @@ async function preresolveResourceConsts(ctx: ResolveCtx): Promise<Map<ts.Express
       stampParamDependencies(instance, initializer, ctx);
       built.set(initializer, instance);
       ctx.externals.set(name, instance);
-    } catch {
+    } catch (err) {
       // Not constructible here (an unresolvable constructor import, a prop
-      // outside the fold subset, a --sandbox refusal). Leave the name alone.
+      // outside the fold subset, a --sandbox refusal). Leave the name alone:
+      // the failure is deliberately not fatal, and the first reference to the
+      // name rejects on its own terms.
+      //
+      // chant#2423 — but keep the located reason. Without it the file's only
+      // reported cause is the reference site, which is where the consequence
+      // is, not where the problem is.
+      ctx.prebuildFailures?.set(name, describeFoldFailure(err, ctx));
     }
   }
   return built;
@@ -3292,6 +3314,9 @@ async function resolveResourceEntity(
 
 const UNRESOLVED_IDENTIFIER_RE = /unresolved identifier: (\S+)$/;
 
+/** The rejection a reference to a const whose pre-build failed produces (chant#2423). */
+const SAME_FILE_RESOURCE_RE = /same-file resource `([^`]+)` used as a value is not foldable/;
+
 /**
  * Enrich an otherwise-generic "unresolved identifier: X" failure when X is a
  * name whose OWN cross-file resolution was attempted and failed for a known
@@ -3306,6 +3331,13 @@ function describeFoldFailure(err: unknown, ctx: ResolveCtx): string {
     const reason = ctx.crossFileFailures.get(match[1]);
     if (reason) return `${err.message} (${reason})`;
   }
+  // chant#2423 — the reference rejected because the pre-build never produced
+  // the instance. Say what stopped the pre-build, at the line it stopped on.
+  const sameFile = SAME_FILE_RESOURCE_RE.exec(err.message);
+  if (sameFile) {
+    const cause = ctx.prebuildFailures?.get(sameFile[1]);
+    if (cause) return `${err.message} (${cause})`;
+  }
   return err.message;
 }
 
@@ -3635,6 +3667,10 @@ async function tryFoldFileCore(file: string, session: FoldSession): Promise<Fold
       sandbox: session.sandbox,
       session,
       interpretDepth: 0,
+      // chant#2423 — filled by the pre-build below, read by
+      // `describeFoldFailure` when a reference rejects for a const it could
+      // not build.
+      prebuildFailures: new Map<string, string>(),
     };
 
     // chant #1169 — every same-file `const x = new Type(...)`, built once, in
@@ -4034,6 +4070,37 @@ export async function planFoldTaintWithEdges(
   return { tainted, reachedBy };
 }
 
+/**
+ * The rest of the session a whole-build fold needs, mirroring the same fields
+ * on `DiscoveryOptions` (chant#2422).
+ *
+ * Without them {@link foldProject} answered a strictly harsher question than a
+ * real `chant build --fold` does. `lexiconPackages` was always empty, and per
+ * its own contract an empty set "disables lexicon-package resolution entirely
+ * rather than falling back to something more permissive", so no file that reads
+ * a lexicon data export as a value could fold through this entry. `buildParams`
+ * was always unset, so no file reading `params` could either. Both fold under a
+ * real build, and 21 corpus files flipped from `run` to `fold` at
+ * `chant-v0.70.1` once the list was supplied.
+ *
+ * `../build.ts` already threads all three into `../discovery/index.ts`; this is
+ * the same three reaching the same `createFoldSession` by the other route.
+ */
+export interface FoldProjectOptions {
+  /**
+   * Lexicon NAMES active for this build (`["aws", "k8s"]`), as
+   * `resolveProjectLexicons()` returns them. A caller building through core has
+   * to supply these itself, the same way `examples/differential-corpus.ts`
+   * reproduces the CLI's `options.plugins.map((p) => p.name)` step, or the fold
+   * is measured without the bare-specifier allowlist a real build gives it.
+   */
+  readonly lexicons?: readonly string[];
+  /** Resolved build-time parameter values, so a file reading `params.<name>` folds. */
+  readonly buildParams?: Readonly<Record<string, BuildParamValue>>;
+  /** chant #1093: this build asked for the sandbox, so fold may not reach outside the trusted allowlist. */
+  readonly sandbox?: boolean;
+}
+
 /** One file's place in a whole-build fold, as {@link foldProject} reports it. */
 export interface FoldProjectVerdict {
   /** What the build does with this file. */
@@ -4063,12 +4130,23 @@ export interface FoldProjectVerdict {
  * Same session, same memo, same taint walk as a real build — this is not a
  * second implementation of the rules, it is the existing one with its
  * intermediate results kept instead of consumed.
+ *
+ * `options` carries the rest of what a build's session holds (chant#2422).
+ * Omitting it answers a harsher question than a real build asks: with no
+ * lexicon list nothing reading a lexicon data export folds, and with no build
+ * parameters nothing reading `params` does. See {@link FoldProjectOptions}.
  */
 export async function foldProject(
   files: readonly string[],
   intrinsics: readonly IntrinsicDef[] = [],
+  options: FoldProjectOptions = {},
 ): Promise<Map<string, FoldProjectVerdict>> {
-  const session = createFoldSession(intrinsics);
+  const session = createFoldSession(
+    intrinsics,
+    options.buildParams,
+    options.lexicons ?? [],
+    options.sandbox ?? false,
+  );
   const attempts = new Map<string, FoldFileResult>();
   for (const file of files) attempts.set(file, await tryFoldFile(file, intrinsics, session));
 

package/src/fold/subset-public-export.test.ts

@@ -25,3 +25,34 @@ describe("findSubsetViolation is exported from the package entry", () => {
     expect(chant.findSubsetViolation(initializerOf("export const x = cfg[key];"))?.ruleId).toBe("EVL003");
   });
 });
+
+/**
+ * chant#2424 — the specification's conformance adapter reads `SPEC_VERSION`
+ * off exactly this namespace:
+ *
+ * ```ts
+ * specVersion: (chant as { SPEC_VERSION?: string }).SPEC_VERSION ?? "undeclared",
+ * ```
+ *
+ * so a suite that finds nothing there reports chant as `undeclared` rather
+ * than as implementing anything. The barrel is the thing that can silently
+ * drop it, which is what this pins.
+ */
+describe("SPEC_VERSION is declared on the package entry (chant#2424)", () => {
+  test("the public namespace carries it", () => {
+    expect(typeof chant.SPEC_VERSION).toBe("string");
+    expect(chant.SPEC_VERSION).not.toBe("");
+  });
+
+  test("it is a specification version, not a chant release", () => {
+    // `spec/VERSION` carries a two-part version that moves separately from
+    // chant's own releases (INTENTIUS/typescript-as-data#18), so a value that
+    // looks like a package version is the mistake worth catching.
+    expect(chant.SPEC_VERSION).toMatch(/^\d+\.\d+$/);
+  });
+
+  test("and it is the same string the subset module defines", async () => {
+    const { SPEC_VERSION } = await import("./subset");
+    expect(chant.SPEC_VERSION).toBe(SPEC_VERSION);
+  });
+});

package/src/fold/subset.ts

@@ -147,7 +147,30 @@ import { intrinsicCallFolds, intrinsicCallFoldsEagerly, type IntrinsicDef } from
  * folder would actually accept) — never the reverse. Making EVL
  * flow-sensitive would mean re-implementing an evaluator inside a lint
  * rule; out of scope here. See #1024.
+ *
+ * ## Which version of the specification this is
+ *
+ * A specification version names a set of rules and moves on its own schedule,
+ * separately from chant's releases (INTENTIUS/typescript-as-data#18). The
+ * version chant implements is {@link SPEC_VERSION}, and it is exported from
+ * `@intentius/chant`'s public entry so the specification's conformance suite
+ * can read it. A suite that finds no declaration reports the implementation as
+ * `undeclared` rather than assuming it is current, which is the right default
+ * and a useless answer to get from an implementation that does know.
+ *
+ * Raising it is part of adopting a new version of the rules, alongside the
+ * spec-first change process above: land the rule there, implement it here
+ * citing the identifier, then move this constant.
+ */
+
+/**
+ * The version of the TypeScript-as-Data specification chant implements
+ * (chant#2424).
+ *
+ * `spec/VERSION` in the specification repository carries the same string, and
+ * the conformance adapter reads this one to fill its `specVersion` field.
  */
+export const SPEC_VERSION = "1.0";
 
 /** The two EVL rule ids a shape violation can be attributed to. */
 export type SubsetRuleId = "EVL001" | "EVL003";

package/src/index.ts

@@ -44,6 +44,11 @@ export * from "./fold/fold";
 // half of the fold subset a conformance adapter needs that `fold()` alone
 // does not expose. INTENTIUS/typescript-as-data#11.
 export { findSubsetViolation, checkObjectMember, type SubsetViolation, type SubsetRuleId } from "./fold/subset";
+// The version of the TypeScript-as-Data specification chant implements
+// (INTENTIUS/typescript-as-data#18, chant#2424). The specification's
+// conformance adapter reads this off the public entry; without it a suite
+// reports chant as `undeclared` rather than as implementing anything.
+export { SPEC_VERSION } from "./fold/subset";
 // The whole-build fold. `fold()` and `foldModule()` answer one expression and
 // one file; neither cross-file rule is observable at that granularity — the
 // forward rule needs an importer, the reverse rule needs a capturing sibling,
@@ -52,6 +57,7 @@ export { findSubsetViolation, checkObjectMember, type SubsetViolation, type Subs
 export {
   foldProject,
   planFoldTaintWithEdges,
+  type FoldProjectOptions,
   type FoldProjectVerdict,
   type TaintPlan,
   type TaintEdgeKind,