@intentius/chant 0.124.13 → 0.124.15

package/dist/discovery/fold-rank.js

@@ -0,0 +1,292 @@
+import { relative } from "node:path";
+import { buildProjectImportEdges } from "./fold-import.js";
+/**
+ * chant #1083 — rank fold blockers by dominator retained-count over the
+ * import graph discovery already builds.
+ *
+ * ## Why dominators, not a flat "files downstream of X" count
+ *
+ * The import graph is a DAG (occasionally cyclic, when project source
+ * itself has an import cycle), not a tree: a file can be reachable through
+ * several paths, so naively summing "files that import X, transitively"
+ * double-counts every diamond and the totals stop meaning anything. The
+ * fix is the same one heap snapshot tools use for object retained sizes
+ * (Cooper–Harvey–Kennedy immediate dominators, prior art: spicypath's
+ * `src/heap-dominators.js`, cited on chant #1083): file `d` dominates file
+ * `n` when every causal path to `n`'s failure passes through `d`. A file's
+ * retained count is then the size of its dominator subtree — the number of
+ * files that would fold if `d` folded — and every node lands in exactly one
+ * dominator subtree, so retained counts are conserved: they sum to the
+ * total across the tree's top-level blockers, with nothing counted twice
+ * through a diamond, and a file with two INDEPENDENT blockers (no common
+ * ancestor besides the synthetic root) inflates neither.
+ *
+ * ## One direction only
+ *
+ * This models FORWARD contagion only: file `n` fails to fold because one of
+ * its own imports, `d`, also fails — an unresolved cross-file reference.
+ * The edge direction for dominance purposes is therefore `d -> n` (the
+ * blocker points at what it blocks), which is the REVERSE of the literal
+ * import edge `n -> d` (n imports d).
+ *
+ * Fold has a second, opposite-direction rule (chant #1044, implemented in
+ * {@link import("./fold-import.js").planFoldTaint}): a file that WOULD fold
+ * fine in isolation is forced back to run anyway because some file that
+ * imports it (directly or transitively) itself runs — folding it
+ * independently would create a second, non-identical instance. That is
+ * contagion from importER to importEE, the opposite of the direction this
+ * tree models, and a dominator tree over import edges cannot express it: a
+ * fix to the "blocker" here wouldn't actually unblock the reverse-tainted
+ * file (it was never broken on its own terms), so crediting it would
+ * overstate the fix's blast radius. Every file discovery marked
+ * {@link FoldDecision.reverseTainted} is therefore excluded from the tree
+ * entirely and reported in {@link FoldRankResult.reverseTainted} instead —
+ * see chant #1083's re-scope comment.
+ */
+/** Sentinel "file path" for the synthetic dominator-tree root. Never a real file — file paths never contain NUL. */
+const ROOT = "\0chant-fold-rank-root\0";
+/**
+ * Compute immediate dominators for `nodes` over `edges` (blocker -> blocked,
+ * i.e. flowing in the CAUSAL direction, not the import direction), rooted at
+ * a synthetic {@link ROOT}. Handles a cyclic/irreducible graph correctly —
+ * Cooper–Harvey–Kennedy's iterative algorithm converges on any graph, not
+ * just reducible ones (this is exactly why it's the right tool here: an
+ * import graph can have cycles).
+ *
+ * `rootChildren` must already guarantee every node in `nodes` is reachable
+ * from {@link ROOT} via `rootChildren` + `edges` — see `rankFoldBlockers`'s
+ * two-phase root-selection below.
+ */
+function computeImmediateDominators(nodes, edges, rootChildren) {
+    const succ = (n) => (n === ROOT ? rootChildren : edges.get(n) ?? new Set());
+    // Predecessors, including the synthetic ROOT edge into every root child.
+    const preds = new Map();
+    for (const n of nodes)
+        preds.set(n, new Set());
+    for (const [from, targets] of edges) {
+        for (const to of targets) {
+            if (!preds.has(to))
+                preds.set(to, new Set());
+            preds.get(to).add(from);
+        }
+    }
+    for (const rc of rootChildren)
+        preds.get(rc)?.add(ROOT);
+    // Reverse-postorder numbering via one DFS from ROOT — every node in
+    // `nodes` must be reached (guaranteed by the caller's root selection).
+    const postorderNumber = new Map();
+    const visited = new Set([ROOT]);
+    let counter = 0;
+    const visitStack = [
+        { node: ROOT, iter: succ(ROOT).values() },
+    ];
+    while (visitStack.length > 0) {
+        const top = visitStack[visitStack.length - 1];
+        const next = top.iter.next();
+        if (next.done) {
+            postorderNumber.set(top.node, counter++);
+            visitStack.pop();
+            continue;
+        }
+        const child = next.value;
+        if (!visited.has(child)) {
+            visited.add(child);
+            visitStack.push({ node: child, iter: succ(child).values() });
+        }
+    }
+    const rpo = [...nodes, ROOT].filter((n) => postorderNumber.has(n));
+    rpo.sort((a, b) => postorderNumber.get(b) - postorderNumber.get(a)); // reverse postorder: highest number first
+    const idom = new Map();
+    idom.set(ROOT, ROOT);
+    const intersect = (a, b) => {
+        let finger1 = a;
+        let finger2 = b;
+        while (finger1 !== finger2) {
+            while (postorderNumber.get(finger1) < postorderNumber.get(finger2))
+                finger1 = idom.get(finger1);
+            while (postorderNumber.get(finger2) < postorderNumber.get(finger1))
+                finger2 = idom.get(finger2);
+        }
+        return finger1;
+    };
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const node of rpo) {
+            if (node === ROOT)
+                continue;
+            let newIdom;
+            for (const p of preds.get(node) ?? []) {
+                if (!idom.has(p))
+                    continue; // not yet processed this pass
+                newIdom = newIdom === undefined ? p : intersect(newIdom, p);
+            }
+            if (newIdom !== undefined && idom.get(node) !== newIdom) {
+                idom.set(node, newIdom);
+                changed = true;
+            }
+        }
+    }
+    idom.delete(ROOT);
+    return idom;
+}
+/**
+ * Rank fold blockers by dominator retained-count over the (forward-only)
+ * import graph among this build's `"run"`-mode files. See this module's doc
+ * for the model. `decisions` is expected to be a `--fold` build's complete
+ * {@link FoldDecision}[] — every discovered file, fold or run.
+ */
+export async function rankFoldBlockers(decisions) {
+    const allFiles = decisions.map((d) => d.file);
+    const reverseTainted = decisions
+        .filter((d) => d.mode === "run" && d.reverseTainted === true)
+        .map((d) => ({ file: d.file, reason: d.reason }))
+        .sort((a, b) => a.file.localeCompare(b.file));
+    const nodeDecisions = decisions.filter((d) => d.mode === "run" && d.reverseTainted !== true);
+    const reasonByFile = new Map(nodeDecisions.map((d) => [d.file, d.reason]));
+    const nodes = nodeDecisions.map((d) => d.file).sort((a, b) => a.localeCompare(b));
+    const nodeSet = new Set(nodes);
+    // file -> the OTHER discovered files it imports (real import direction).
+    const importEdges = await buildProjectImportEdges(allFiles);
+    // Cause graph, blocker -> blocked: importee -> importer, restricted to
+    // both endpoints being forward-tree nodes (a fold-mode or reverse-tainted
+    // file is neither a blocker nor blocked in this tree).
+    const causeEdges = new Map();
+    for (const n of nodes)
+        causeEdges.set(n, new Set());
+    for (const [importer, targets] of importEdges) {
+        if (!nodeSet.has(importer))
+            continue;
+        for (const target of targets) {
+            if (!nodeSet.has(target))
+                continue;
+            causeEdges.get(target).add(importer);
+        }
+    }
+    // Predecessor count, to find true root causes (a blocked file that is
+    // itself never blocked by another tree node).
+    const predCount = new Map();
+    for (const n of nodes)
+        predCount.set(n, 0);
+    for (const targets of causeEdges.values()) {
+        for (const t of targets)
+            predCount.set(t, (predCount.get(t) ?? 0) + 1);
+    }
+    // Two-phase root selection, so every node is reachable from ROOT even
+    // across an import cycle with no external entry point (chant #1083's doc
+    // cites spicypath's dominators working over a graph that is "cyclic and
+    // irreducible" as the precedent this needs to match).
+    const rootChildren = new Set();
+    const reached = new Set();
+    const expandFrom = (start) => {
+        if (reached.has(start))
+            return;
+        const stack = [start];
+        reached.add(start);
+        while (stack.length > 0) {
+            const cur = stack.pop();
+            for (const next of causeEdges.get(cur) ?? []) {
+                if (!reached.has(next)) {
+                    reached.add(next);
+                    stack.push(next);
+                }
+            }
+        }
+    };
+    for (const n of nodes) {
+        if (predCount.get(n) === 0) {
+            rootChildren.add(n);
+            expandFrom(n);
+        }
+    }
+    for (const n of nodes) {
+        if (!reached.has(n)) {
+            rootChildren.add(n);
+            expandFrom(n);
+        }
+    }
+    const idom = computeImmediateDominators(nodes, causeEdges, rootChildren);
+    // Dominator-tree children, to compute retained (subtree size) bottom-up.
+    const domChildren = new Map();
+    for (const n of nodes)
+        domChildren.set(n, []);
+    for (const [n, parent] of idom) {
+        if (parent !== ROOT)
+            domChildren.get(parent).push(n);
+    }
+    const retained = new Map();
+    const computeRetained = (n) => {
+        const cached = retained.get(n);
+        if (cached !== undefined)
+            return cached;
+        let size = 1;
+        for (const child of domChildren.get(n) ?? [])
+            size += computeRetained(child);
+        retained.set(n, size);
+        return size;
+    };
+    for (const n of nodes)
+        computeRetained(n);
+    const blockers = nodes.map((file) => {
+        const parent = idom.get(file);
+        const topLevel = parent === undefined || parent === ROOT;
+        return {
+            file,
+            reason: reasonByFile.get(file),
+            retained: retained.get(file),
+            topLevel,
+            dominatedBy: topLevel ? undefined : parent,
+        };
+    });
+    blockers.sort((a, b) => b.retained - a.retained || a.file.localeCompare(b.file));
+    return { blockers, reverseTainted, totalBlocked: nodes.length };
+}
+/** `file -> dominatedBy` lookup built from a {@link FoldRankResult}, for reconstructing a blocker's dominator-chain (used by {@link toCollapsedFormat}). */
+function dominatorChain(result, file) {
+    const dominatedByFile = new Map(result.blockers.map((b) => [b.file, b.dominatedBy]));
+    const chain = [file];
+    let current = file;
+    const guard = new Set([file]);
+    for (;;) {
+        const parent = dominatedByFile.get(current);
+        if (parent === undefined)
+            break;
+        if (guard.has(parent))
+            break; // defensive: never trust a cycle in the tree itself
+        chain.push(parent);
+        guard.add(parent);
+        current = parent;
+    }
+    return chain.reverse(); // top-level ancestor first, `file` last
+}
+/** A collapsed-format frame may not contain `;` (the frame separator) or a newline; sanitize rather than silently mis-render. */
+function sanitizeFrame(label) {
+    return label.replace(/[\n\r]/g, " ").replace(/;/g, ",");
+}
+/**
+ * Export the dominator tree in Brendan Gregg collapsed stack format
+ * (`frame;frame;...;frame count`), weighted by retained count, so it opens
+ * in any flame or icicle graph viewer with no chant-specific tooling (the
+ * seam is the file format, per chant #1083's original scope).
+ *
+ * One line per blocker, `count` always `1`: each file's stack is the chain
+ * of dominators from the top-level blocker down to itself. Folding
+ * identical prefixes — what every collapsed-format consumer does — then
+ * reproduces each blocker's retained count as that prefix's total weight,
+ * with nothing double-counted through a diamond. `rootLabel` is a single
+ * synthetic top frame (default `"fold"`) so every top-level blocker renders
+ * under one shared root instead of the viewer showing several disconnected
+ * trees; pass `relativeTo` (typically the build's infra path) to shorten
+ * frame labels to project-relative paths.
+ */
+export function toCollapsedFormat(result, options) {
+    const rootLabel = options?.rootLabel ?? "fold";
+    const toLabel = (file) => sanitizeFrame(options?.relativeTo ? relative(options.relativeTo, file) || file : file);
+    return result.blockers
+        .slice()
+        .sort((a, b) => a.file.localeCompare(b.file))
+        .map((blocker) => {
+        const chain = dominatorChain(result, blocker.file).map(toLabel);
+        return `${sanitizeFrame(rootLabel)};${chain.join(";")} 1`;
+    });
+}

package/dist/discovery/graph.js

@@ -0,0 +1,115 @@
+import { isDeclarable } from "../declarable.js";
+import { isAttrRefLike } from "../utils.js";
+/**
+ * Builds a dependency graph from a collection of entities
+ * @param entities - Map of export name to Declarable entity
+ * @returns Map of entity name to set of entity names it depends on
+ */
+export function buildDependencyGraph(entities) {
+    const graph = new Map();
+    // Initialize graph with all entity names
+    for (const name of entities.keys()) {
+        graph.set(name, new Set());
+    }
+    // Build reverse lookup: entity -> name
+    const entityToName = new Map();
+    for (const [name, entity] of entities.entries()) {
+        entityToName.set(entity, name);
+    }
+    // Find dependencies for each entity
+    for (const [name, entity] of entities.entries()) {
+        const dependencies = graph.get(name);
+        const visited = new Set();
+        // Scan the root entity's properties
+        scanProperties(entity, entities, entityToName, dependencies, visited, entity);
+    }
+    return graph;
+}
+/**
+ * Scans properties of an object for dependencies
+ */
+function scanProperties(obj, entities, entityToName, dependencies, visited, rootEntity) {
+    // Mark this object as visited (but not if it's a Declarable, we'll handle that in findDependencies)
+    if (!isDeclarable(obj) && !visited.has(obj)) {
+        visited.add(obj);
+    }
+    // Recurse into arrays
+    if (Array.isArray(obj)) {
+        for (const item of obj) {
+            findDependencies(item, entities, entityToName, dependencies, visited, rootEntity);
+        }
+        return;
+    }
+    // Recurse into object properties
+    for (const prop in obj) {
+        if (Object.prototype.hasOwnProperty.call(obj, prop)) {
+            const propValue = obj[prop];
+            findDependencies(propValue, entities, entityToName, dependencies, visited, rootEntity);
+        }
+    }
+}
+/**
+ * Recursively finds all dependencies in a value
+ */
+function findDependencies(value, entities, entityToName, dependencies, visited, rootEntity) {
+    // Avoid infinite recursion on circular references
+    if (value === null || value === undefined) {
+        return;
+    }
+    // For primitives, nothing to do
+    if (typeof value !== "object") {
+        return;
+    }
+    // Check if this is an AttrRef. Duck-type, not `instanceof` (chant #1137):
+    // a lexicon built against a separate copy of `@intentius/chant` produces
+    // AttrRefs that fail `instanceof AttrRef` here but carry the same shape.
+    // Without this, the dependency edge is silently dropped instead of
+    // recorded, which can misorder — or fail to detect a cycle in — the
+    // file-discovery build order this graph exists to compute.
+    if (isAttrRefLike(value)) {
+        if (visited.has(value)) {
+            return;
+        }
+        visited.add(value);
+        const parent = value.parent.deref();
+        if (parent && isDeclarable(parent) && parent !== rootEntity) {
+            const parentName = entityToName.get(parent);
+            if (parentName) {
+                dependencies.add(parentName);
+            }
+        }
+        return;
+    }
+    // Check if this is a Declarable entity reference
+    if (isDeclarable(value)) {
+        // If this is the root entity itself, skip it but don't mark as visited
+        // so we can detect it if referenced again (self-reference)
+        if (value === rootEntity) {
+            if (visited.has(value)) {
+                // We've seen this self-reference before, record it as a dependency
+                const referencedName = entityToName.get(value);
+                if (referencedName) {
+                    dependencies.add(referencedName);
+                }
+                return;
+            }
+            // First time seeing the root entity, mark as visited and continue scanning
+            visited.add(value);
+            scanProperties(value, entities, entityToName, dependencies, visited, rootEntity);
+            return;
+        }
+        // It's a different Declarable entity - record as dependency
+        const referencedName = entityToName.get(value);
+        if (referencedName) {
+            dependencies.add(referencedName);
+        }
+        // Don't recurse into other declarable entities
+        return;
+    }
+    // Check if we've already visited this object
+    if (visited.has(value)) {
+        return;
+    }
+    // Recurse into the object's properties
+    scanProperties(value, entities, entityToName, dependencies, visited, rootEntity);
+}

package/dist/discovery/host-composite.d.ts

@@ -0,0 +1,35 @@
+import { type Declarable } from "../declarable.js";
+/**
+ * Mark `members` as the instance a host's composite produced, and return it
+ * unchanged.
+ *
+ * chant#3608 — every declarable member, and every member of a nested host
+ * instance, is also stamped with the composite, the way `expandComposite`
+ * stamps a chant instance's members. A destructured member is never expanded,
+ * so this is the only record it has that a composite wrote it, and without
+ * it a path the fold did not attribute reads as authored and so `direct`.
+ * `setProvenance` keeps the first writer, and a nested instance was marked
+ * when its own call returned, so a member keeps its innermost composite.
+ */
+export declare function markHostCompositeInstance(members: Record<string, unknown>, compositeName: string): Record<string, unknown>;
+/** The composite name a host composite instance was marked with, or `undefined` for any other value. */
+export declare function hostCompositeName(value: unknown): string | undefined;
+/**
+ * chant#3598, chant#3612 — a host composite instance's members as entities,
+ * for `collectEntities`.
+ *
+ * `collectEntities` is the one place `build()` and `foldProject` turn exports
+ * into entities, so expanding here is what makes the two report the same set:
+ * `export const archive = Archive({...})` gives `archiveBucket` to both.
+ *
+ * The members are named and stamped the way `expandComposite` names and stamps
+ * a chant instance: `${exportName}${Member}`, a nested host instance expanded
+ * in place under its member's name (`siteMainBucket`), with a whole-entity
+ * `composite` origin under the paths the fold already attributed. That origin
+ * is written before `collectEntities` adds its own record, and the first
+ * writer wins, so a path the fold did not attribute is `unknown` rather than
+ * `direct`. Every member belongs to the top-level `instance`; its composite is
+ * the innermost one, which {@link markHostCompositeInstance} already stamped.
+ */
+export declare function expandHostComposite(prefix: string, members: Record<string, unknown>, instance?: string): Array<[string, Declarable]>;
+//# sourceMappingURL=host-composite.d.ts.map

package/dist/discovery/host-composite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-composite.d.ts","sourceRoot":"","sources":["../../src/discovery/host-composite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAoB9D;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,aAAa,EAAE,MAAM,GACpB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB;AAUD,wGAAwG;AACxG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAIpE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,GAAE,MAAe,GACxB,KAAK,CAAC,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAiB7B"}

package/dist/discovery/host-composite.js

@@ -0,0 +1,93 @@
+import { isDeclarable } from "../declarable.js";
+import { getProvenance, setPathProvenance, setProvenance } from "../provenance.js";
+/**
+ * chant#3598 — a host composite instance's own marker. Non-enumerable and
+ * symbol-keyed, like provenance, so nothing that serializes or compares the
+ * exports sees it. It carries the composite's name, which the members object
+ * otherwise has no record of once it is returned.
+ *
+ * Only the fold path sets it: a host's registration form (chant#2442) returns
+ * the members object the factory built, not a chant `CompositeInstance`, and
+ * chant knows the object came from a composite only because the fold resolved
+ * the call. A file that runs instead has no such knowledge.
+ */
+const HOST_COMPOSITE_INSTANCE = Symbol.for("chant.fold.hostCompositeInstance");
+function isPlainIndexable(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Mark `members` as the instance a host's composite produced, and return it
+ * unchanged.
+ *
+ * chant#3608 — every declarable member, and every member of a nested host
+ * instance, is also stamped with the composite, the way `expandComposite`
+ * stamps a chant instance's members. A destructured member is never expanded,
+ * so this is the only record it has that a composite wrote it, and without
+ * it a path the fold did not attribute reads as authored and so `direct`.
+ * `setProvenance` keeps the first writer, and a nested instance was marked
+ * when its own call returned, so a member keeps its innermost composite.
+ */
+export function markHostCompositeInstance(members, compositeName) {
+    if (Object.isExtensible(members) && !Object.prototype.hasOwnProperty.call(members, HOST_COMPOSITE_INSTANCE)) {
+        Object.defineProperty(members, HOST_COMPOSITE_INSTANCE, {
+            value: compositeName,
+            enumerable: false,
+            configurable: true,
+        });
+    }
+    stampHostCompositeMembers(members, compositeName);
+    return members;
+}
+/** Stamp `composite` on each declarable member of a host instance, descending into nested host instances. */
+function stampHostCompositeMembers(members, compositeName) {
+    for (const member of Object.values(members)) {
+        if (isDeclarable(member))
+            setProvenance(member, { composite: compositeName });
+        else if (hostCompositeName(member) !== undefined)
+            stampHostCompositeMembers(member, compositeName);
+    }
+}
+/** The composite name a host composite instance was marked with, or `undefined` for any other value. */
+export function hostCompositeName(value) {
+    if (!isPlainIndexable(value))
+        return undefined;
+    const name = value[HOST_COMPOSITE_INSTANCE];
+    return typeof name === "string" ? name : undefined;
+}
+/**
+ * chant#3598, chant#3612 — a host composite instance's members as entities,
+ * for `collectEntities`.
+ *
+ * `collectEntities` is the one place `build()` and `foldProject` turn exports
+ * into entities, so expanding here is what makes the two report the same set:
+ * `export const archive = Archive({...})` gives `archiveBucket` to both.
+ *
+ * The members are named and stamped the way `expandComposite` names and stamps
+ * a chant instance: `${exportName}${Member}`, a nested host instance expanded
+ * in place under its member's name (`siteMainBucket`), with a whole-entity
+ * `composite` origin under the paths the fold already attributed. That origin
+ * is written before `collectEntities` adds its own record, and the first
+ * writer wins, so a path the fold did not attribute is `unknown` rather than
+ * `direct`. Every member belongs to the top-level `instance`; its composite is
+ * the innermost one, which {@link markHostCompositeInstance} already stamped.
+ */
+export function expandHostComposite(prefix, members, instance = prefix) {
+    const out = [];
+    const compositeName = hostCompositeName(members);
+    for (const [memberName, member] of Object.entries(members)) {
+        if (memberName.length === 0)
+            continue;
+        const fullName = `${prefix}${memberName[0].toUpperCase()}${memberName.slice(1)}`;
+        if (hostCompositeName(member) !== undefined) {
+            out.push(...expandHostComposite(fullName, member, instance));
+            continue;
+        }
+        if (!isDeclarable(member))
+            continue;
+        setProvenance(member, { composite: compositeName, compositeInstance: instance });
+        const composite = getProvenance(member)?.composite ?? compositeName;
+        setPathProvenance(member, "", { kind: "composite", composite, instance });
+        out.push([fullName, member]);
+    }
+    return out;
+}

package/dist/discovery/import.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../src/discovery/import.ts"],"names":[],"mappings":"AA4BA;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAalC"}
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../src/discovery/import.ts"],"names":[],"mappings":"AA6BA;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAclC"}

package/dist/discovery/import.js

@@ -0,0 +1,65 @@
+import { DiscoveryError } from "../errors.js";
+import { ensureTypeScriptLoader } from "../ts-loader.js";
+/**
+ * Modules whose evaluation threw, and the error each threw with (#2368).
+ *
+ * The ES module spec says an evaluation failure is recorded on the module
+ * record and re-thrown on every later import of the same specifier, forever,
+ * in that realm. Node implements it — including after the file is edited, so a
+ * module that threw keeps throwing until the process restarts.
+ *
+ * Vitest's module runner does not. It caches the module as *evaluated* and
+ * hands later importers a namespace carrying whichever bindings were
+ * initialized before the throw, so the second import resolves with
+ * half-initialized exports and no error at all.
+ *
+ * That divergence is invisible to `chant build`, which imports a directory
+ * once per process, and highly visible to anything that builds the same
+ * directory twice and compares: whichever build ran first carried the error
+ * and every build after it reported none, so error parity came out of the
+ * ordering rather than out of the tool.
+ *
+ * This map is what makes the answer the same either way. Under Node it never
+ * fires — `import()` throws again before the lookup matters — so it costs
+ * nothing and changes nothing there. Under a runner that forgets, it supplies
+ * the memory the spec requires.
+ */
+const evaluationFailures = new Map();
+/**
+ * Forget every recorded evaluation failure.
+ *
+ * For a harness that deliberately starts a fresh module graph and wants the
+ * failures forgotten with it. Nothing in chant calls this: a real build
+ * imports once, and a second import inside one process is supposed to see what
+ * the first one saw.
+ *
+ * It does not make a module re-evaluate. Node's own registry still holds the
+ * failed record and still re-throws; this only clears chant's memory of it. A
+ * caller wanting genuine re-evaluation needs a fresh process.
+ */
+export function resetImportFailures() {
+    evaluationFailures.clear();
+}
+/**
+ * Dynamically import a module and return its exports.
+ *
+ * @param path - The file path to import
+ * @returns The module exports
+ * @throws {DiscoveryError} with type "import" if the import fails, including
+ *   on every later import of a module whose evaluation has already failed
+ */
+export async function importModule(path) {
+    const failed = evaluationFailures.get(path);
+    if (failed)
+        throw failed;
+    try {
+        ensureTypeScriptLoader();
+        return await import(path);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown import error";
+        const discoveryError = new DiscoveryError(path, message, "import");
+        evaluationFailures.set(path, discoveryError);
+        throw discoveryError;
+    }
+}

package/dist/discovery/index.d.ts

@@ -70,6 +70,15 @@ export interface DiscoveryOptions {
      * at all, rather than a looser fallback.
      */
     lexicons?: readonly string[];
+    /**
+     * chant#3612 — package specifiers to follow a bare import into, verbatim,
+     * alongside whatever {@link lexicons} names. The same allowlist
+     * `FoldProjectOptions.lexiconPackages` gives `foldProject` (chant#2438), so
+     * a build over a host of its own folds the files `foldProject` folds. A
+     * chant project never needs it: its packages are `lexicons`. Only
+     * meaningful when {@link fold} is set. Default: none.
+     */
+    lexiconPackages?: readonly string[];
     /**
      * chant #1045 Phase 2 — opt-in: whatever would otherwise reach the
      * in-process `importModule` step (every file, when {@link fold} isn't set;

package/dist/discovery/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAQ/C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AA8D1D;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IACrB,gGAAgG;IAChG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAE5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,8DAA8D;IAC9D,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACvC,qDAAqD;IACrD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mDAAmD;IACnD,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB;;;OAGG;IACH,aAAa,EAAE,YAAY,EAAE,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CA+SjG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAQ/C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AA8D1D;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IACrB,gGAAgG;IAChG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAE5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7B;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEpC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,8DAA8D;IAC9D,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACvC,qDAAqD;IACrD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mDAAmD;IACnD,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB;;;OAGG;IACH,aAAa,EAAE,YAAY,EAAE,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CA+SjG"}