@intentius/chant 0.70.0 → 0.71.0

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
@@ -3949,7 +3985,40 @@ export async function planFoldTaint(
   files: readonly string[],
   wouldFold: ReadonlyMap<string, boolean>,
   liveSources?: ReadonlyMap<string, ReadonlySet<string>>,
-): Promise<Set<string>> {
+): Promise<ReadonlySet<string>> {
+  return (await planFoldTaintWithEdges(files, wouldFold, liveSources)).tainted;
+}
+
+/** Which of the two rules put a file on the run path. */
+export type TaintEdgeKind =
+  /** A file this one imports, directly or transitively, falls back to run (#1023). */
+  | "importer"
+  /** This file captured the objects of a file that falls back to run (#1044). */
+  | "capture";
+
+export interface TaintPlan {
+  /** Every file that must run: the seed, plus everything reachable from it. */
+  readonly tainted: ReadonlySet<string>;
+  /**
+   * For a file the walk reached (never for a seed file), the file whose taint
+   * reached it and by which rule. chant#2406: the fallback reason has to name
+   * the actual edge — a reverse-tainted file is not imported by anything that
+   * runs, and saying it is sends a reader looking for an importer that does
+   * not exist.
+   */
+  readonly reachedBy: ReadonlyMap<string, { from: string; kind: TaintEdgeKind }>;
+}
+
+/**
+ * {@link planFoldTaint}'s walk, keeping the edge that fired for each file it
+ * reaches. Split out for two consumers that need to say *why*: the fallback
+ * reason in `discover()`, and {@link foldProject}'s verdicts.
+ */
+export async function planFoldTaintWithEdges(
+  files: readonly string[],
+  wouldFold: ReadonlyMap<string, boolean>,
+  liveSources?: ReadonlyMap<string, ReadonlySet<string>>,
+): Promise<TaintPlan> {
   const fileSet = new Set(files);
 
   // file -> set of OTHER discovered files it relatively imports OR re-exports
@@ -3958,7 +4027,9 @@ export async function planFoldTaint(
 
   // chant #1044 — reverse edges: consumed-file -> the folded files that
   // captured its objects. Same taint set, same fixpoint walk; see this
-  // function's doc for the crash this closes.
+  // function's doc for the crash this closes. Kept in their own map as well,
+  // so the walk below can tell which rule an edge belongs to.
+  const reverse = new Map<string, Set<string>>();
   for (const [consumer, sources] of liveSources ?? []) {
     if (!fileSet.has(consumer)) continue;
     for (const source of sources) {
@@ -3969,20 +4040,139 @@ export async function planFoldTaint(
         edges.set(source, back);
       }
       back.add(consumer);
+      let mine = reverse.get(source);
+      if (!mine) {
+        mine = new Set<string>();
+        reverse.set(source, mine);
+      }
+      mine.add(consumer);
     }
   }
 
   const tainted = new Set<string>(files.filter((f) => wouldFold.get(f) !== true));
+  const reachedBy = new Map<string, { from: string; kind: TaintEdgeKind }>();
   const queue = [...tainted];
   while (queue.length > 0) {
     const current = queue.shift()!;
     for (const target of edges.get(current) ?? []) {
       if (!tainted.has(target)) {
         tainted.add(target);
+        // A forward edge means `current` imports `target`; the reverse map is
+        // consulted second so a file reachable both ways is reported as the
+        // importer case, the one a reader can see in its own source.
+        const forward = !reverse.get(current)?.has(target);
+        reachedBy.set(target, { from: current, kind: forward ? "importer" : "capture" });
         queue.push(target);
       }
     }
   }
 
-  return tainted;
+  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. */
+  readonly verdict: "fold" | "run";
+  /** What the file's own fold attempt concluded, before the taint walk. */
+  readonly tentative: "fold" | "run";
+  /** Present when `tentative` is "run": the located reason its own fold gave. */
+  readonly reason?: string;
+  /** Present when the file would have folded and taint overruled it. */
+  readonly taintedBy?: { from: string; kind: TaintEdgeKind };
+  /** The file's complete export namespace, present only when `verdict` is "fold". */
+  readonly exports?: ReadonlyMap<string, unknown>;
+}
+
+/**
+ * Fold a whole set of project files and report every file's verdict
+ * (chant#2408).
+ *
+ * `discover()` does this as part of building, and its per-file decisions are
+ * not addressable from outside. Anything that wants to *check* the
+ * cross-file rules needs the whole picture: the forward rule (#1023) needs an
+ * importer, the reverse rule (#1044) needs a capturing sibling, and the
+ * fixpoint needs the whole set, so none of the three is observable one file at
+ * a time. The conformance suite of the specification is the first such caller
+ * (INTENTIUS/typescript-as-data#62).
+ *
+ * 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,
+    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));
+
+  const plan = await planFoldTaintWithEdges(
+    files,
+    new Map(files.map((file) => [file, attempts.get(file)?.ok === true])),
+    new Map(files.flatMap((file) => {
+      const attempt = attempts.get(file);
+      return attempt?.ok === true ? [[file, attempt.liveSources] as const] : [];
+    })),
+  );
+
+  const out = new Map<string, FoldProjectVerdict>();
+  for (const file of files) {
+    const attempt = attempts.get(file)!;
+    const tentative = attempt.ok ? "fold" : "run";
+    if (attempt.ok && !plan.tainted.has(file)) {
+      out.set(file, { verdict: "fold", tentative, exports: attempt.exportedValues });
+      continue;
+    }
+    out.set(file, {
+      verdict: "run",
+      tentative,
+      reason: attempt.ok ? undefined : attempt.reason,
+      taintedBy: attempt.ok ? plan.reachedBy.get(file) : undefined,
+    });
+  }
+  return out;
 }

package/src/discovery/index.ts

@@ -1,3 +1,4 @@
+import { relative } from "node:path";
 import type { Declarable } from "../declarable";
 import type { DiscoveryError } from "../errors";
 import type { IntrinsicDef } from "../lexicon";
@@ -6,7 +7,7 @@ import { importModule } from "./import";
 import { collectEntities } from "./collect";
 import { resolveAttrRefs } from "./resolve";
 import { buildDependencyGraph } from "./graph";
-import { tryFoldFile, planFoldTaint, createFoldSession } from "./fold-import";
+import { tryFoldFile, planFoldTaintWithEdges, createFoldSession } from "./fold-import";
 import { getProvenance } from "../provenance";
 import type { BuildParamProvenance } from "../provenance";
 import { buildParamValues } from "../build-params";
@@ -270,8 +271,8 @@ export async function discover(path: string, options?: DiscoveryOptions): Promis
       foldAttempts.set(file, await tryFoldFile(file, options.intrinsics, foldSession));
     }
   }
-  const taintedFiles = options?.fold
-    ? await planFoldTaint(
+  const taintPlan = options?.fold
+    ? await planFoldTaintWithEdges(
         files,
         new Map(files.map((file) => [file, foldAttempts.get(file)?.ok === true])),
         // chant #1044 — which files' OBJECTS each successful fold captured,
@@ -284,7 +285,8 @@ export async function discover(path: string, options?: DiscoveryOptions): Promis
           }),
         ),
       )
-    : new Set<string>();
+    : { tainted: new Set<string>(), reachedBy: new Map() };
+  const taintedFiles = taintPlan.tainted;
 
   for (const file of files) {
     if (options?.fold) {
@@ -307,9 +309,15 @@ export async function discover(path: string, options?: DiscoveryOptions): Promis
         foldDecisions.push({ file, mode: "fold", resourceCount: folded.entities.length });
         continue;
       }
+      // chant#2406 — name the edge that actually fired. A reverse-tainted file
+      // is not imported by anything that falls back; saying so sends a reader
+      // looking for an importer that does not exist.
+      const edge = taintPlan.reachedBy.get(file);
       const reason = !folded.ok
         ? folded.reason
-        : `would fold in isolation, but a file that imports it (directly or transitively) falls back to run — folding independently would create a duplicate, non-identical instance`;
+        : edge?.kind === "capture"
+          ? `would fold in isolation, but it captured objects from ${relative(process.cwd(), edge.from)}, which falls back to run — folding independently would hold an instance the build never collects`
+          : `would fold in isolation, but a file that imports it (directly or transitively) falls back to run — folding independently would create a duplicate, non-identical instance`;
       foldDecisions.push({ file, mode: "run", reason, reverseTainted: folded.ok });
     }
 

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,24 @@ 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,
+// and the fixpoint needs the whole set. chant#2408,
+// INTENTIUS/typescript-as-data#62.
+export {
+  foldProject,
+  planFoldTaintWithEdges,
+  type FoldProjectOptions,
+  type FoldProjectVerdict,
+  type TaintPlan,
+  type TaintEdgeKind,
+} from "./discovery/fold-import";
 export * from "./lint/parser";
 export * from "./lint/rule";
 export * from "./lint/rules";

package/src/lifecycle/affected.test.ts

@@ -138,6 +138,124 @@ describe("affectedStacks — baseDir (caller-supplied)", () => {
   });
 });
 
+// A second lexicon, so a stack that serializes through two of them can be shown
+// folding into one artifact.
+const fakeSerializer2: Serializer = {
+  name: "fake2",
+  rulePrefix: "FAKE2",
+  serialize: (entities) =>
+    JSON.stringify([...entities.keys()].sort().map((k) => ({ k, t: entities.get(k)!.entityType }))),
+};
+
+function otherWidget(type: string): string {
+  return `export const bar = { lexicon: "fake2", entityType: "${type}", [Symbol.for("chant.declarable")]: true };\n`;
+}
+
+function deployTimeParam(): string {
+  return `export const p = { lexicon: "fake", entityType: "Param", parameterType: "String", [Symbol.for("chant.declarable")]: true };\n`;
+}
+
+describe("affectedStacks — per-stack mode (#2420)", () => {
+  let root: string;
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "chant-affected-stacks-"));
+  });
+  afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+  // A project root holding one source directory per stack, as ChantConfig.stacks
+  // describes it: { api: <infra.ts contents>, worker: ... }.
+  const project = (name: string, sources: Record<string, string>): string => {
+    const dir = join(root, name);
+    for (const [stack, content] of Object.entries(sources)) {
+      mkdirSync(join(dir, stack), { recursive: true });
+      writeFileSync(join(dir, stack, "infra.ts"), content);
+    }
+    return dir;
+  };
+
+  const stacks = [
+    { name: "api-stack", src: "api" },
+    { name: "worker-stack", src: "worker" },
+  ];
+
+  test("a stacks[] entry whose src is not there is refused by name at head", async () => {
+    const base = project("base", { api: widget("Widget"), worker: widget("Queue") });
+    const head = project("head", { api: widget("Gadget") });
+    await expect(
+      affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer], stacks }),
+    ).rejects.toThrow(/stack "worker-stack" declares src "worker", which does not exist/);
+  });
+
+  test("a stack added since base is changed, rather than refused for having no base source", async () => {
+    const base = project("base", { api: widget("Widget") });
+    const head = project("head", { api: widget("Widget"), worker: widget("Queue") });
+    const r = await affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer], stacks });
+    expect(r.changed).toEqual(["worker-stack"]);
+  });
+
+  test("names the changed stack, not its lexicon — and leaves the untouched stack out", async () => {
+    const base = project("base", { api: widget("Widget"), worker: widget("Queue") });
+    const head = project("head", { api: widget("Gadget"), worker: widget("Queue") });
+    const r = await affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer], stacks });
+    expect(r.changed).toEqual(["api-stack"]);
+    expect(r.changed).not.toContain("fake"); // the lexicon name is not an answer
+  });
+
+  test("a no-output-change refactor in the changed stack's own directory is NOT affected", async () => {
+    const base = project("base", { api: widget("Widget"), worker: widget("Queue") });
+    const head = project("head", { api: "// a harmless refactor\n" + widget("Widget"), worker: widget("Queue") });
+    const r = await affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer], stacks });
+    expect(r.changed).toEqual([]);
+  });
+
+  test("a stack spanning two lexicons folds into one artifact keyed by the stack", async () => {
+    const both = (type: string) => widget("Widget") + otherWidget(type);
+    const base = project("base", { api: both("Topic"), worker: widget("Queue") });
+    // Only the second lexicon's partition moves; the stack is still what changed.
+    const head = project("head", { api: both("Bus"), worker: widget("Queue") });
+    const r = await affectedStacks({
+      projectPath: head,
+      baseDir: base,
+      serializers: [fakeSerializer, fakeSerializer2],
+      stacks,
+    });
+    expect(r.changed).toEqual(["api-stack"]);
+  });
+
+  test("a deploy-time Parameter is reported as indeterminate under the stack name", async () => {
+    const base = project("base", { api: deployTimeParam(), worker: widget("Queue") });
+    const head = project("head", { api: deployTimeParam(), worker: widget("Queue") });
+    const r = await affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer], stacks });
+    expect(r.indeterminate).toEqual(["api-stack"]);
+  });
+
+  test("dependents stay empty — the stack-to-stack relation is not in the build", async () => {
+    const base = project("base", { api: widget("Widget"), worker: widget("Queue") });
+    const head = project("head", { api: widget("Gadget"), worker: widget("Queue") });
+    const r = await affectedStacks({
+      projectPath: head,
+      baseDir: base,
+      serializers: [fakeSerializer],
+      stacks,
+      includeDependents: true,
+    });
+    expect(r.changed).toEqual(["api-stack"]);
+    expect(r.dependents).toEqual([]);
+  });
+
+  test("an empty stacks list keeps the single-root, lexicon-keyed answer", async () => {
+    const base = project("base", { api: widget("Widget") });
+    const head = project("head", { api: widget("Gadget") });
+    const r = await affectedStacks({
+      projectPath: join(head, "api"),
+      baseDir: join(base, "api"),
+      serializers: [fakeSerializer],
+      stacks: [],
+    });
+    expect(r.changed).toEqual(["fake"]);
+  });
+});
+
 describe("affectedStacks — baseRef (git worktree)", () => {
   let repo: string;
   beforeEach(async () => {