@intentius/chant 0.24.0 → 0.26.0

package/src/lint/policy-import.ts

@@ -0,0 +1,70 @@
+/**
+ * The single place chant imports a project's `lint.policies` module **in the
+ * CLI's own process** — and the flag that says it may not.
+ *
+ * The third member of the same family as `../discovery/import.ts`'s
+ * `importModule` (project source) and `../config-import.ts`'s
+ * `importConfigModule` (`chant.config.ts`): one narrow module whose only job is
+ * "execute project-authored code here", so that "did any project code run in
+ * this process?" has one place to look and one place to instrument — see
+ * `examples/sandbox-execution-boundary.test.ts`, which spies on all three.
+ *
+ * Before chant #1131 `./policy.ts` called `await import(resolved)` inline,
+ * which is why the corpus boundary gate could not see it even after #1113 put
+ * the config behind the boundary: there was nothing named to wrap.
+ *
+ * The armed flag lives here rather than in `./policy-sandbox.ts` (which owns
+ * the *decision* and documents the reasoning, and re-exports these three
+ * functions as its public surface) for one structural reason: `./policy.ts`
+ * needs to consult it, `./policy-sandbox.ts` needs to call `./policy.ts`, and a
+ * flag on a leaf module with no imports of its own breaks what would otherwise
+ * be an import cycle. It also puts the check on the narrowest possible thing —
+ * the function that actually executes project code — rather than on a caller
+ * that might forget to ask.
+ */
+
+/** Whether this process must run project policy modules inside the sandbox boundary instead of here. */
+let armed = false;
+
+/**
+ * Arm sandboxed policy execution for the rest of this process. See
+ * `./policy-sandbox.ts` for what arms it and why it is a process mode rather
+ * than a threaded option. Idempotent; there is deliberately no disarm.
+ */
+export function armSandboxPolicyExecution(): void {
+  armed = true;
+}
+
+/** Whether {@link armSandboxPolicyExecution} has been called. */
+export function isSandboxPolicyExecutionArmed(): boolean {
+  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 resetSandboxPolicyExecutionForTests(): void {
+  armed = false;
+}
+
+/** The shape a policy module evaluates to — chant reads its exported values and keeps the `PostSynthCheck`-shaped ones. */
+export type PolicyModuleNamespace = Record<string, unknown>;
+
+/**
+ * Import a policy module 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.
+ *
+ * Refuses while armed. Under `--sandbox` the policy modules are imported inside
+ * a child process (`../discovery/sandbox/policy-run.ts`); arriving here anyway
+ * means something is about to execute project-authored code in the CLI's own
+ * process, which is exactly what the flag promises does not happen. Falling
+ * through would make `--sandbox` mean less than it says with nothing visible to
+ * notice, so this throws instead.
+ */
+export async function importPolicyModule(policyPath: string): Promise<PolicyModuleNamespace> {
+  if (armed) {
+    throw new Error(
+      `Refusing to import the policy module ${policyPath} into the chant process under --sandbox: it is project-authored code and must be imported inside the sandbox boundary (packages/core/src/lint/policy-sandbox.ts's runProjectPolicies).`,
+    );
+  }
+  return (await import(policyPath)) as PolicyModuleNamespace;
+}

package/src/lint/policy-sandbox.ts

@@ -0,0 +1,123 @@
+import { resolve } from "node:path";
+import {
+  runPostSynthChecks,
+  type PostSynthCheck,
+  type PostSynthContext,
+  type PostSynthDiagnostic,
+} from "./post-synth";
+import { loadPolicyChecks } from "./policy";
+import {
+  armSandboxPolicyExecution,
+  isSandboxPolicyExecutionArmed,
+  resetSandboxPolicyExecutionForTests,
+} from "./policy-import";
+import type { EncodablePolicyBuildResult } from "../discovery/sandbox/policy-wire";
+
+/**
+ * chant #1131 — decides WHERE a project's `lint.policies` checks run.
+ *
+ * A policy is project-authored code. Every other piece of project code moved
+ * behind the `--sandbox` boundary in chant #1045 (run-fallback source), #1093
+ * (composite factories, constructors, intrinsic tags) and #1113
+ * (`chant.config.ts`), and all three had to leave this one out: the config
+ * declares its policies as *paths*, so putting the config behind the boundary
+ * did not put them there with it. `chant build` imported each policy module and
+ * called its `check` function in the CLI's own process, after discovery was
+ * over, with the CLI's filesystem, network, environment and process-spawn
+ * access. This module closes it.
+ *
+ * ## Why an armed process mode rather than a threaded option
+ *
+ * The same reason `../config-sandbox.ts` gives. `./policy.ts`'s
+ * `loadPolicyChecks` is exported from chant-core's public surface and called
+ * from more than one place (`../cli/commands/build.ts` for a build, and
+ * `evaluateProjectPolicies` for the `policyGate` Op step). Threading a
+ * `sandbox` flag to each is fail-OPEN: miss one and project code executes in
+ * the CLI process with nothing to notice. Arming the process once, before any
+ * policy is loaded, is fail-CLOSED — `loadPolicyChecks` REFUSES while armed, so
+ * a call site nobody remembered gets a loud error rather than a silent
+ * execution.
+ *
+ * ## What arms it
+ *
+ * Both ways of turning sandboxing on, unlike `../config-sandbox.ts`. That
+ * asymmetry is not an oversight: the config has a bootstrap limit (reading
+ * `build.sandbox` out of `chant.config.ts` means running it, so only the CLI
+ * flag, known before any config is touched, can cover the config's own
+ * evaluation). Policies have no such limit — they are loaded long after the
+ * config is known — so `build.sandbox: true` in a project's config sandboxes
+ * them just as `--sandbox` does, and `../cli/commands/build.ts` arms this from
+ * the RESOLVED value.
+ *
+ * There is deliberately no disarm: a security mode that can be turned off
+ * partway through a process is not one.
+ */
+
+/**
+ * The mode itself lives on `./policy-import.ts` — the leaf module that actually
+ * performs an in-process policy import, so the refusal sits on the narrowest
+ * possible thing and `./policy.ts` can consult it without importing this file
+ * (which imports `./policy.ts`). Re-exported here because this is where the
+ * decision is documented and where callers look.
+ *
+ * `armSandboxPolicyExecution` is called from `../cli/commands/build.ts` once
+ * `build.sandbox`/`--sandbox` has resolved, and from `../cli/main.ts` off the
+ * parsed flag.
+ */
+export { armSandboxPolicyExecution, isSandboxPolicyExecutionArmed, resetSandboxPolicyExecutionForTests };
+
+export interface ProjectPolicyRun {
+  /** `lint.policies` as declared in the config — relative paths, resolved against {@link configDir}. */
+  policies: readonly string[];
+  /** The `chant.config.*` directory (`lint.policies` paths are relative to it), also the child's read allowance. */
+  configDir: string;
+  /** The merged, serialized build result the checks run over. */
+  buildResult: EncodablePolicyBuildResult & PostSynthContext["buildResult"];
+  /** `--env`, else `ownership.env`. Becomes `ctx.env`. */
+  env?: string;
+  /**
+   * Checks the caller already loaded into THIS process, before the build ran.
+   *
+   * `chant build` has always loaded `lint.policies` up front rather than at the
+   * point of use, so a policy path that doesn't resolve fails the command
+   * immediately — including when the build itself goes on to fail, which is
+   * exactly when a typo'd path would otherwise go unnoticed. Preserving that
+   * for the unsandboxed path is the whole reason this field exists.
+   *
+   * Ignored when armed: under `--sandbox` there is nothing loaded here to pass,
+   * and `loadPolicyChecks` refuses outright.
+   */
+  preloaded?: PostSynthCheck[];
+}
+
+/**
+ * Run a project's organizational policy checks over a finished build and return
+ * their diagnostics. Sandboxed in a post-merge child when armed, in-process
+ * otherwise.
+ *
+ * The unarmed path is byte-for-byte what `chant build` has always done: load
+ * the modules, hand every check one `PostSynthContext`, concatenate what they
+ * return. The armed path does the same thing on the other side of a process
+ * boundary — see `../discovery/sandbox/policy-run.ts`.
+ */
+export async function runProjectPolicies(run: ProjectPolicyRun): Promise<PostSynthDiagnostic[]> {
+  if (run.policies.length === 0) return [];
+
+  if (!isSandboxPolicyExecutionArmed()) {
+    const checks = run.preloaded ?? (await loadPolicyChecks([...run.policies], run.configDir));
+    if (checks.length === 0) return [];
+    return runPostSynthChecks(checks, run.buildResult, run.env);
+  }
+
+  // Dynamic, not static, for the same reason `../config-sandbox.ts` imports
+  // `../discovery/sandbox/config-run` dynamically: this pulls in `esbuild`, a
+  // large CJS package no unsandboxed build should pay to load.
+  const { runPoliciesSandboxed } = await import("../discovery/sandbox/policy-run");
+  const { diagnostics } = await runPoliciesSandboxed({
+    policyPaths: run.policies.map((p) => resolve(run.configDir, p)),
+    buildResult: run.buildResult,
+    env: run.env,
+    projectRoot: run.configDir,
+  });
+  return diagnostics;
+}

package/src/lint/policy.ts

@@ -9,15 +9,33 @@ import { resolveProjectLexicons, loadPlugins } from "../cli/plugins";
 import { build } from "../build";
 import { runPostSynthChecks, isPostSynthCheck } from "./post-synth";
 import type { PostSynthCheck, PostSynthDiagnostic } from "./post-synth";
+import { importPolicyModule, isSandboxPolicyExecutionArmed } from "./policy-import";
 
-/** Load project policy checks (one or more `PostSynthCheck` exports) from files. */
+/**
+ * Load project policy checks (one or more `PostSynthCheck` exports) from files,
+ * **into this process**.
+ *
+ * chant #1131 — refuses while `./policy-sandbox.ts` is armed. Under `--sandbox`
+ * the policy modules are imported and their checks run inside a child process
+ * (`runProjectPolicies`); reaching this function anyway means a call site is
+ * about to execute project-authored code in the CLI's own process, which is
+ * precisely the thing the flag promises does not happen. Failing loudly is the
+ * only honest option — falling through would make `--sandbox` mean less than it
+ * says without anything visible to notice.
+ */
 export async function loadPolicyChecks(paths: string[], configDir: string): Promise<PostSynthCheck[]> {
+  if (isSandboxPolicyExecutionArmed()) {
+    throw new Error(
+      `Cannot load lint.policies (${paths.join(", ")}) in the chant process under --sandbox: a policy module is project-authored code, and it must be imported inside the sandbox boundary. This is a chant bug — the caller should route through runProjectPolicies() (packages/core/src/lint/policy-sandbox.ts).`,
+    );
+  }
+
   const checks: PostSynthCheck[] = [];
   for (const p of paths) {
     const resolved = resolve(configDir, p);
     let mod: Record<string, unknown>;
     try {
-      mod = (await import(resolved)) as Record<string, unknown>;
+      mod = await importPolicyModule(resolved);
     } catch (err) {
       throw new Error(
         `Failed to load policy "${p}": ${err instanceof Error ? err.message : String(err)}`,

package/src/stack-output.test.ts

@@ -0,0 +1,118 @@
+import { describe, test, expect, vi } from "vitest";
+import { stackOutput, isStackOutput, STACK_OUTPUT_MARKER } from "./stack-output";
+import { AttrRef } from "./attrref";
+import { INTRINSIC_MARKER } from "./intrinsic";
+import { DECLARABLE_MARKER, type Declarable } from "./declarable";
+
+const vpc: Declarable = {
+  lexicon: "aws",
+  entityType: "AWS::EC2::VPC",
+  [DECLARABLE_MARKER]: true,
+};
+
+describe("stackOutput", () => {
+  test("wraps a bare AttrRef and derives lexicon from its parent", () => {
+    const ref = new AttrRef(vpc, "VpcId");
+    const out = stackOutput(ref);
+
+    expect(out[STACK_OUTPUT_MARKER]).toBe(true);
+    expect(out[DECLARABLE_MARKER]).toBe(true);
+    expect(out.lexicon).toBe("aws");
+    expect(out.kind).toBe("output");
+    expect(out.sourceRef).toBe(ref);
+  });
+
+  test("wraps an intrinsic nesting an AttrRef and borrows the AttrRef's lexicon", () => {
+    const ref = new AttrRef(vpc, "VpcId");
+    const join = {
+      [INTRINSIC_MARKER]: true as const,
+      values: [ref, "-suffix"],
+      toJSON: () => ({ "Fn::Join": ["", ["VpcId", "-suffix"]] }),
+    };
+
+    const out = stackOutput(join);
+    expect(out.lexicon).toBe("aws");
+    expect(out.sourceRef).toBe(join);
+  });
+
+  test("records an optional description", () => {
+    const ref = new AttrRef(vpc, "VpcId");
+    const out = stackOutput(ref, { description: "Primary VPC id" });
+    expect(out.description).toBe("Primary VPC id");
+  });
+
+  test("throws for a value that is neither AttrRef-like nor an Intrinsic", () => {
+    expect(() => stackOutput("not-a-ref" as unknown as AttrRef)).toThrow(
+      "stackOutput(ref): ref must be an attribute reference or an intrinsic wrapping one",
+    );
+  });
+
+  test("falls back to lexicon 'unknown' when the anchor's parent has no lexicon field", () => {
+    const ref = new AttrRef({}, "attr");
+    const out = stackOutput(ref);
+    expect(out.lexicon).toBe("unknown");
+  });
+
+  // chant #1137 — `stackOutput()` used to check `ref instanceof AttrRef` (in
+  // both its input validation and its lexicon-deriving anchor selection),
+  // which returns false for an AttrRef built by a SEPARATELY-LOADED copy of
+  // `./attrref` (the same dual-npm-copy hazard #1122 fixed for
+  // `LexiconOutput`). `firstAttrRef` had the same raw `instanceof` check, so
+  // even the "wrapped in an intrinsic" fallback path missed a foreign
+  // AttrRef too. Before the fix, a foreign-copy AttrRef silently anchored on
+  // nothing and the output's `lexicon` field became `"unknown"` instead of
+  // the real producing lexicon — no error, just a wrong value.
+  // `vi.resetModules()` + a fresh dynamic import reproduces the split module
+  // graph exactly.
+  test("derives lexicon from a bare AttrRef built by a second, separately-loaded copy", async () => {
+    vi.resetModules();
+    const secondCopy = await import("./attrref");
+    expect(secondCopy.AttrRef).not.toBe(AttrRef);
+
+    const foreignRef = new secondCopy.AttrRef(vpc, "VpcId");
+
+    // The historic bug: instanceof fails across separately-loaded copies of
+    // chant-core, even though the two classes are structurally identical.
+    expect(foreignRef instanceof AttrRef).toBe(false);
+
+    const out = stackOutput(foreignRef);
+    expect(out.lexicon).toBe("aws");
+    expect(out.sourceRef).toBe(foreignRef);
+    vi.resetModules();
+  });
+
+  test("derives lexicon from a foreign-copy AttrRef nested inside an intrinsic", async () => {
+    vi.resetModules();
+    const secondCopy = await import("./attrref");
+    const foreignRef = new secondCopy.AttrRef(vpc, "VpcId");
+    expect(foreignRef instanceof AttrRef).toBe(false);
+
+    const join = {
+      [INTRINSIC_MARKER]: true as const,
+      values: [foreignRef, "-suffix"],
+      toJSON: () => ({ "Fn::Join": ["", ["VpcId", "-suffix"]] }),
+    };
+
+    const out = stackOutput(join);
+    expect(out.lexicon).toBe("aws");
+    vi.resetModules();
+  });
+});
+
+describe("isStackOutput", () => {
+  test("returns true for a StackOutput", () => {
+    const ref = new AttrRef(vpc, "VpcId");
+    expect(isStackOutput(stackOutput(ref))).toBe(true);
+  });
+
+  test("returns false for a plain AttrRef", () => {
+    const ref = new AttrRef(vpc, "VpcId");
+    expect(isStackOutput(ref)).toBe(false);
+  });
+
+  test("returns false for null/primitives", () => {
+    expect(isStackOutput(null)).toBe(false);
+    expect(isStackOutput("x")).toBe(false);
+    expect(isStackOutput(42)).toBe(false);
+  });
+});

package/src/stack-output.ts

@@ -9,6 +9,7 @@
 import { DECLARABLE_MARKER, type Declarable } from "./declarable";
 import { AttrRef } from "./attrref";
 import { isIntrinsic, type Intrinsic } from "./intrinsic";
+import { isAttrRefLike } from "./utils";
 
 /**
  * Marker symbol for stack output identification.
@@ -32,10 +33,15 @@ export interface StackOutput extends Declarable {
 }
 
 /** Find the first AttrRef anywhere inside a value (walking intrinsics/objects/
- * arrays), so a wrapping intrinsic can still borrow its parent's lexicon. */
+ * arrays), so a wrapping intrinsic can still borrow its parent's lexicon.
+ * 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 — missing one would
+ * make the walk recurse into the AttrRef's own (unhelpful) fields instead
+ * of stopping on it, silently failing to find the anchor. */
 function firstAttrRef(value: unknown, seen = new Set<unknown>()): AttrRef | undefined {
   if (value === null || typeof value !== "object" || seen.has(value)) return undefined;
-  if (value instanceof AttrRef) return value;
+  if (isAttrRefLike(value)) return value;
   seen.add(value);
   const children = Array.isArray(value) ? value : Object.values(value as Record<string, unknown>);
   for (const child of children) {
@@ -79,12 +85,22 @@ export function stackOutput(
   ref: AttrRef | Intrinsic,
   options?: { description?: string },
 ): StackOutput {
-  if (!(ref instanceof AttrRef) && !isIntrinsic(ref)) {
+  // Duck-type, not `instanceof` (chant #1137): AttrRef also implements
+  // Intrinsic (a global-symbol marker), so `isIntrinsic(ref)` alone already
+  // happens to accept a foreign-copy AttrRef here — this check would not
+  // misfire even with the raw `instanceof` left in. It is converted anyway
+  // so the guard's own logic states the invariant explicitly ("ref must be
+  // AttrRef-like or Intrinsic") rather than relying on that coincidence,
+  // matching the anchor selection right below it, which does misbehave.
+  if (!isAttrRefLike(ref) && !isIntrinsic(ref)) {
     throw new Error("stackOutput(ref): ref must be an attribute reference or an intrinsic wrapping one");
   }
   // Derive lexicon from the referenced entity — for a bare AttrRef, its parent;
-  // for an intrinsic (Join etc.), the first AttrRef nested inside it.
-  const anchor = ref instanceof AttrRef ? ref : firstAttrRef(ref);
+  // for an intrinsic (Join etc.), the first AttrRef nested inside it. A
+  // foreign-copy AttrRef failing raw `instanceof` here would fall to
+  // `firstAttrRef`, which (before its own #1137 fix) would also miss it —
+  // silently anchoring on nothing and recording `lexicon: "unknown"`.
+  const anchor = isAttrRefLike(ref) ? ref : firstAttrRef(ref);
   const parent = anchor?.parent.deref();
   const lexicon = parent && typeof (parent as Record<string, unknown>).lexicon === "string"
     ? (parent as Record<string, unknown>).lexicon as string