@intentius/chant 0.124.13 → 0.124.15

package/dist/composite.d.ts

@@ -74,8 +74,16 @@ export declare class CompositeRegistry {
  * });
  * export const storage = SecureStorage({ name: "data" });
  * ```
- */
-export declare function Composite<P, M extends CompositeFactoryMembers = CompositeMembers>(factory: (props: P) => M, name?: string): CompositeDefinition<P, M>;
+ *
+ * `D` (chant#3787) lets a lexicon give the definition a more precise call
+ * signature than `(props: P) => M`, such as a generic one whose members' types
+ * depend on the literal props it is called with. It is a type only: the value
+ * is the same definition, and `D` must still be a `CompositeDefinition<P, M>`,
+ * so an intersection with the precise signature first is the usual form. It
+ * is passed as a type argument rather than by casting the result, because the
+ * fold recognizes a composite by its `export const X = Composite(...)` shape.
+ */
+export declare function Composite<P, M extends CompositeFactoryMembers = CompositeMembers, D extends CompositeDefinition<P, M> = CompositeDefinition<P, M>>(factory: (props: P) => M, name?: string): D;
 /**
  * chant#3608 — the composite whose call built `entity`, or `undefined` for an
  * entity no chant composite built.

package/dist/composite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../src/composite.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../src/composite.ts"],"names":[],"mappings":"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"}

package/dist/composite.js

@@ -0,0 +1,313 @@
+import { isDeclarable } from "./declarable.js";
+import { setPathProvenance, setProvenance } from "./provenance.js";
+/**
+ * Marker symbol for Composite type identification.
+ */
+export const COMPOSITE_MARKER = Symbol.for("chant.composite");
+/**
+ * Type guard: is this value a CompositeInstance?
+ */
+export function isCompositeInstance(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        COMPOSITE_MARKER in value &&
+        value[COMPOSITE_MARKER] === true);
+}
+/**
+ * Type guard: is this value a composite definition, what `Composite()` and
+ * `withDefaults()` return? A lexicon's composite catalog test uses it to find
+ * the composites a module exports (#2662).
+ */
+export function isCompositeDefinition(value) {
+    return typeof value === "function" && typeof value.compositeName === "string";
+}
+/**
+ * Global registry of composite definitions.
+ */
+export class CompositeRegistry {
+    static register(definition) {
+        this.definitions.set(definition._id, definition);
+    }
+    static getAll() {
+        return Array.from(this.definitions.values());
+    }
+    static clear() {
+        this.definitions.clear();
+    }
+    static get size() {
+        return this.definitions.size;
+    }
+}
+CompositeRegistry.definitions = new Map();
+/**
+ * Creates a composite definition from a factory closure.
+ *
+ * Usage:
+ * ```ts
+ * const SecureStorage = Composite<{ name: string }>((props) => {
+ *   const bucket = new Bucket({ bucketName: props.name });
+ *   const role = new Role({ policies: [{ resource: bucket.arn }] });
+ *   return { bucket, role };
+ * });
+ * export const storage = SecureStorage({ name: "data" });
+ * ```
+ *
+ * `D` (chant#3787) lets a lexicon give the definition a more precise call
+ * signature than `(props: P) => M`, such as a generic one whose members' types
+ * depend on the literal props it is called with. It is a type only: the value
+ * is the same definition, and `D` must still be a `CompositeDefinition<P, M>`,
+ * so an intersection with the precise signature first is the usual form. It
+ * is passed as a type argument rather than by casting the result, because the
+ * fold recognizes a composite by its `export const X = Composite(...)` shape.
+ */
+export function Composite(factory, name) {
+    const id = Symbol();
+    const compositeName = name ?? "anonymous";
+    const definition = ((props) => {
+        const members = factory(props);
+        for (const [key, value] of Object.entries(members)) {
+            if (!isDeclarable(value) && !isCompositeInstance(value)) {
+                throw new Error(`Composite "${compositeName}" member "${key}" is not a Declarable or CompositeInstance`);
+            }
+        }
+        // chant#3608 — every member records the composite that built it, here,
+        // when the instance is made. A member destructured from the call
+        // (`export const { vpc } = VpcDefault({})`) is never expanded, so this is
+        // the only trace that a composite wrote it; `collectEntities` reads it
+        // through {@link compositeOfMember}. A nested instance recorded its own
+        // members first and the first record is kept, so a member keeps its
+        // innermost composite. Kept off the provenance record so the composite
+        // `expandComposite` records for an instance exported whole is unchanged.
+        markCompositeMembers(members, compositeName);
+        // Define `members` and `_definition` as non-enumerable so spreading a
+        // composite instance (`...someComposite`) only exposes the actual member
+        // resources, not the framework's bookkeeping properties. Without this, a
+        // parent composite that does `...childResult` ends up with a `members` key
+        // pointing at the child's CompositeMembers record — not a Declarable —
+        // which then trips the parent's own member validation.
+        const instance = {};
+        Object.defineProperty(instance, COMPOSITE_MARKER, { value: true, enumerable: false });
+        Object.defineProperty(instance, "members", { value: members, enumerable: false });
+        Object.defineProperty(instance, "_definition", { value: definition, enumerable: false });
+        return Object.assign(instance, members);
+    });
+    Object.defineProperty(definition, "compositeName", { value: compositeName, writable: false });
+    Object.defineProperty(definition, "_id", { value: id, writable: false });
+    CompositeRegistry.register(definition);
+    return definition;
+}
+/** Non-enumerable, symbol-keyed: invisible to serializers, spreads and comparisons, like provenance. */
+const COMPOSITE_MEMBER_OF = Symbol.for("chant.composite.memberOf");
+/** Record `compositeName` on each declarable member, descending into nested instances. First record wins. */
+function markCompositeMembers(members, compositeName) {
+    for (const member of Object.values(members)) {
+        if (isCompositeInstance(member)) {
+            markCompositeMembers(member.members, compositeName);
+        }
+        else if (isDeclarable(member) &&
+            Object.isExtensible(member) &&
+            !Object.prototype.hasOwnProperty.call(member, COMPOSITE_MEMBER_OF)) {
+            Object.defineProperty(member, COMPOSITE_MEMBER_OF, { value: compositeName, enumerable: false, configurable: true });
+        }
+    }
+}
+/**
+ * chant#3608 — the composite whose call built `entity`, or `undefined` for an
+ * entity no chant composite built.
+ */
+export function compositeOfMember(entity) {
+    const name = entity[COMPOSITE_MEMBER_OF];
+    return typeof name === "string" ? name : undefined;
+}
+/**
+ * Expands a CompositeInstance into a flat Map of prefixed entity names to Declarables.
+ * Handles nested composites recursively.
+ *
+ * @param instanceName - The composite INSTANCE every member belongs to (chant
+ *   #1443), which at the top call is the export name and stays that name
+ *   through nesting — `prefix` grows per member and is not an instance
+ *   identity. Defaults to `prefix` so the top call needs no extra argument.
+ */
+export function expandComposite(prefix, instance, instanceName = prefix) {
+    const result = new Map();
+    const shared = instance[SHARED_PROPS];
+    const compositeName = instance._definition?.compositeName;
+    for (const [memberName, member] of Object.entries(instance.members)) {
+        const fullName = `${prefix}${memberName[0].toUpperCase()}${memberName.slice(1)}`;
+        if (isCompositeInstance(member)) {
+            const nested = expandComposite(fullName, member, instanceName);
+            for (const [nestedName, nestedEntity] of nested) {
+                // Inner composite already stamped; `??=` keeps the most-specific one.
+                if (compositeName)
+                    setProvenance(nestedEntity, { composite: compositeName });
+                result.set(nestedName, nestedEntity);
+            }
+        }
+        else {
+            if (compositeName)
+                setProvenance(member, { composite: compositeName });
+            result.set(fullName, member);
+        }
+    }
+    // Whole-entity origin (chant #1443). Recorded after the loop so a nested
+    // member carries its INNER composite here — the recursive call above already
+    // ran and `setPathProvenance` keeps the first writer.
+    if (compositeName) {
+        for (const entity of result.values()) {
+            setPathProvenance(entity, "", { kind: "composite", composite: compositeName, instance: instanceName });
+        }
+    }
+    if (shared) {
+        for (const entity of result.values()) {
+            if ("props" in entity) {
+                // Merge shared props onto each member's ORIGINAL props, not its current
+                // props. Members are module-level singletons, so without stashing the
+                // original a second expansion (e.g. building the same tree twice in one
+                // process) would re-merge shared arrays like tags onto the already-merged
+                // value, duplicating them on every rebuild (#1032). Stashing the original
+                // once makes expansion idempotent: same input -> same output, every time.
+                const store = entity;
+                let existing = store[ORIGINAL_PROPS];
+                if (existing === undefined) {
+                    existing = entity.props;
+                    Object.defineProperty(entity, ORIGINAL_PROPS, {
+                        value: existing, enumerable: false, configurable: true,
+                    });
+                }
+                const merged = {};
+                for (const [k, v] of Object.entries(shared)) {
+                    if (v !== undefined) {
+                        merged[k] = v;
+                    }
+                }
+                for (const [k, v] of Object.entries(existing)) {
+                    if (v !== undefined) {
+                        if (Array.isArray(v) && Array.isArray(merged[k])) {
+                            merged[k] = [...merged[k], ...v];
+                        }
+                        else {
+                            merged[k] = v;
+                        }
+                    }
+                }
+                Object.defineProperty(entity, "props", {
+                    value: merged, enumerable: false, configurable: true,
+                });
+                // A key the member did not set is the propagating instance's alone, so
+                // it is attributable exactly (chant #1443). A key both sides wrote —
+                // an override, or the array concatenation above — is left to the
+                // whole-entity origin rather than credited to one contributor.
+                if (compositeName) {
+                    for (const k of Object.keys(shared)) {
+                        if (shared[k] === undefined || existing[k] !== undefined)
+                            continue;
+                        setPathProvenance(entity, k, {
+                            kind: "composite",
+                            composite: compositeName,
+                            instance: instanceName,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Wraps a CompositeDefinition with pre-applied default values.
+ * Props that have defaults become optional in the returned type.
+ *
+ * ```ts
+ * const SecureApi = withDefaults(LambdaApi, { runtime: "nodejs20.x", timeout: 10 });
+ * const api = SecureApi({ name: "myApi", code: "./dist" }); // runtime and timeout are optional
+ * ```
+ */
+export function withDefaults(definition, defaults) {
+    const wrapped = ((props) => {
+        const resolved = typeof defaults === "function" ? defaults(props) : defaults;
+        return definition({ ...resolved, ...props });
+    });
+    Object.defineProperty(wrapped, "compositeName", {
+        value: definition.compositeName, writable: false,
+    });
+    Object.defineProperty(wrapped, "_id", {
+        value: definition._id, writable: false,
+    });
+    return wrapped;
+}
+/**
+ * Symbol key for shared props attached by propagate().
+ */
+export const SHARED_PROPS = Symbol.for("chant.composite.shared");
+/**
+ * Symbol key stashing a member's original (pre-merge) props, so expandComposite()
+ * is idempotent across repeated expansions of the same singleton instance (#1032).
+ */
+export const ORIGINAL_PROPS = Symbol.for("chant.composite.origProps");
+/**
+ * Attaches shared properties to a composite instance.
+ * During expandComposite(), shared props are merged into every member's props.
+ *
+ * Merge semantics:
+ * - Scalars: member-specific value wins
+ * - Arrays (e.g. tags): concatenate shared + member-specific
+ * - undefined values in shared props are stripped
+ *
+ * ```ts
+ * export const storage = propagate(
+ *   SecureStorage({ name: "data" }),
+ *   { tags: [{ key: "env", value: "prod" }] },
+ * );
+ * ```
+ */
+export function propagate(instance, sharedProps) {
+    Object.defineProperty(instance, SHARED_PROPS, {
+        value: sharedProps,
+        enumerable: false,
+    });
+    return instance;
+}
+/**
+ * Marker function for resource declarations within composites.
+ * At runtime, simply calls `new Type(props)` and returns the result.
+ * Exists so lint tooling can validate composite member construction (EVL005).
+ */
+export function resource(Type, props, attributes) {
+    return new Type(props, attributes);
+}
+/**
+ * Shallow-merges override values into a base props object.
+ *
+ * Merge semantics:
+ * - `undefined` values in overrides are skipped
+ * - Arrays: concatenated (base + overrides), matching `propagate()` semantics
+ * - Scalars / objects: override wins
+ *
+ * No deep merge — too dangerous with IaC props where nested objects
+ * (e.g. policy documents) should be replaced wholesale.
+ *
+ * `overrides` may be any object type, not only `Partial<T>`: a composite
+ * types each member's override against that member's own props, and `T`
+ * here is the shape of the literal the composite builds, which is narrower.
+ */
+export function mergeDefaults(base, overrides) {
+    if (!overrides)
+        return base;
+    const result = { ...base };
+    for (const [key, value] of Object.entries(overrides)) {
+        if (value === undefined)
+            continue;
+        const existing = result[key];
+        if (Array.isArray(existing) && Array.isArray(value)) {
+            result[key] = [...existing, ...value];
+        }
+        else if (existing != null && typeof existing === "object" && !Array.isArray(existing) &&
+            value != null && typeof value === "object" && !Array.isArray(value)) {
+            result[key] = mergeDefaults(existing, value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}

package/dist/config-import.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-import.d.ts","sourceRoot":"","sources":["../src/config-import.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;GAiBG;AAEH,6FAA6F;AAC7F,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5D;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAE3F;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,qBAAqB,CAG1F"}
+{"version":3,"file":"config-import.d.ts","sourceRoot":"","sources":["../src/config-import.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AAEH,6FAA6F;AAC7F,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5D;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAG3F;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,qBAAqB,CAI1F"}

package/dist/config-import.js

@@ -0,0 +1,22 @@
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { ensureTypeScriptLoader } from "./ts-loader.js";
+/**
+ * Import a `chant.config.ts` into THIS process and return its module namespace.
+ * Node's ESM registry caches it, so repeated loads within one CLI invocation
+ * evaluate the file once — the behavior `loadChantConfig` has always had.
+ */
+export async function importConfigModule(configPath) {
+    ensureTypeScriptLoader();
+    return (await import(configPath));
+}
+/**
+ * `require()` a `chant.config.ts` into THIS process from `dir`'s resolution
+ * context — the synchronous path `./lint/config.ts`'s `loadConfig` has used
+ * since before the async loader existed (`chant lint` is a sync pipeline).
+ */
+export function requireConfigModule(configPath, dir) {
+    const req = createRequire(join(dir, "package.json"));
+    ensureTypeScriptLoader();
+    return req(configPath);
+}

package/dist/config-sandbox.js

@@ -0,0 +1,122 @@
+import { dirname } from "node:path";
+import { importConfigModule, requireConfigModule } from "./config-import.js";
+/**
+ * chant #1113 — decides WHERE a project's `chant.config.ts` is evaluated.
+ *
+ * `chant.config.ts` is project-authored code. Every other piece of project
+ * source moved behind the `--sandbox` boundary in chant #1045 (run-fallback
+ * files) and #1093 (composite factories, constructors, intrinsic tags), and
+ * both PRs had to document the config file as a remaining hole: the CLI reads
+ * its configuration by importing it, in-process, before it knows anything else
+ * about the project. This module closes it.
+ *
+ * ## Why an armed process mode rather than a threaded option
+ *
+ * Config is loaded from a dozen call sites (`../cli/main.ts` before command
+ * dispatch, `./cli/plugins.ts`'s `resolveProjectLexicons`,
+ * `./cli/commands/build.ts`, `./lint/policy.ts`, every lifecycle handler …).
+ * Threading a `sandbox` option to each one is fail-OPEN: miss a site and
+ * project code executes in the CLI process with nothing to notice it. Arming
+ * the process once, from the `--sandbox` flag, before any config load happens,
+ * is fail-CLOSED — a call site that nobody remembered still routes through the
+ * child.
+ *
+ * ## The bootstrap limit, stated plainly
+ *
+ * `chant.config.ts`'s own `build.sandbox: true` **cannot** sandbox its own
+ * evaluation. Reading that field requires evaluating the file, so by the time
+ * chant knows the project asked for sandboxing, the project's code has already
+ * run. Only `--sandbox` on the command line — known from `parseArgs`, before
+ * any config is touched — arms this. `chant build` warns when sandboxing was
+ * enabled by config alone, rather than letting the difference stay invisible.
+ * (A `chant.config.json` project has no such limit: JSON is data, parsed and
+ * never executed, so `build.sandbox: true` there is fully honest.)
+ *
+ * ## Memoization
+ *
+ * Armed loads are memoized per config path for the life of the process. That
+ * is not an optimization detail with a semantic cost: the unarmed path is
+ * already memoized by Node's own ESM registry (`await import()` evaluates a
+ * given config file once per process, so `chant build --watch` has never
+ * re-read a config mid-session either). Matching that keeps the two paths
+ * behaviorally identical while keeping a build to one bundle+fork instead of
+ * one per call site.
+ */
+/** Whether this process must evaluate project configs inside the sandbox boundary. */
+let armed = false;
+/** Armed-mode results, keyed by absolute config path. See the module doc on why this matches unarmed behavior rather than diverging from it. */
+const memo = new Map();
+/**
+ * Arm sandboxed config evaluation for the rest of this process. Called from
+ * `../cli/main.ts` immediately after `parseArgs`, when `--sandbox` was passed
+ * — before the first config load. Idempotent; there is deliberately no
+ * disarm, because a security mode that can be turned off partway through a
+ * process is not one.
+ */
+export function armSandboxConfigEvaluation() {
+    armed = true;
+}
+/** Whether {@link armSandboxConfigEvaluation} has been called. */
+export function isSandboxConfigEvaluationArmed() {
+    return armed;
+}
+/**
+ * Test-only reset. Vitest gives each test file its own module registry, so
+ * this exists for suites that arm and disarm within one file.
+ */
+export function resetSandboxConfigEvaluationForTests() {
+    armed = false;
+    memo.clear();
+}
+/**
+ * The export a config module's configuration lives on: an explicit `default`,
+ * a named `config`, else the module namespace itself (a config authored as a
+ * set of top-level named exports). Applied identically on both sides of the
+ * boundary — in the child by `./discovery/sandbox/driver.ts`'s config driver,
+ * here for the in-process path — so `--sandbox` changes only where the file is
+ * evaluated, never how its result is read.
+ */
+export function selectConfigExport(namespace) {
+    return namespace.default ?? namespace.config ?? namespace;
+}
+/**
+ * Evaluate a project's `chant.config.ts` and return its configuration object,
+ * pre-`normalizeConfig`. Sandboxed when armed, in-process otherwise.
+ *
+ * @param configPath - Absolute path to the config file.
+ * @param projectRoot - Directory to grant the sandboxed child read access to;
+ *   defaults to the config file's own directory.
+ */
+export async function evaluateProjectConfig(configPath, projectRoot = dirname(configPath)) {
+    if (!armed) {
+        return selectConfigExport(await importConfigModule(configPath));
+    }
+    if (memo.has(configPath))
+        return memo.get(configPath);
+    // Dynamic, not static, for the same reason `./discovery/index.ts` imports
+    // `./sandbox/run` dynamically: this pulls in `esbuild`, a large CJS package
+    // no unsandboxed build should pay to load.
+    const { evaluateConfigSandboxed } = await import("./discovery/sandbox/config-run.js");
+    const { config } = await evaluateConfigSandboxed(configPath, projectRoot);
+    memo.set(configPath, config);
+    return config;
+}
+/**
+ * Synchronous counterpart for `./lint/config.ts`'s `loadConfig` (`chant lint`
+ * is a sync pipeline and predates the async loader).
+ *
+ * When armed, this cannot spawn a child — so it uses the result of an earlier
+ * armed load of the same file, and refuses if there isn't one. In practice
+ * there always is: `../cli/main.ts` loads the project config before dispatching
+ * to any command. Refusing rather than falling back to an in-process `require`
+ * is the point — a sync call site is exactly where a boundary would otherwise
+ * be lost by accident.
+ */
+export function evaluateProjectConfigSync(configPath, dir) {
+    if (!armed) {
+        return selectConfigExport(requireConfigModule(configPath, dir));
+    }
+    if (memo.has(configPath))
+        return memo.get(configPath);
+    throw new Error(`Cannot read ${configPath} synchronously under --sandbox: it has not yet been evaluated inside the boundary, and evaluating it here would run project code in the chant process. This is a chant bug — the project config should have been loaded before this point.`);
+}