@intentius/chant 0.1.17 → 0.1.19

package/src/lifecycle/affected.test.ts

@@ -0,0 +1,161 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  changedStacks,
+  dependentStacks,
+  computeAffected,
+  externalInputStacks,
+  affectedStacks,
+} from "./affected";
+import type { StackGraph } from "../build";
+import type { Serializer } from "../serializer";
+import type { Declarable } from "../declarable";
+
+const execFileAsync = promisify(execFile);
+
+// Serializer whose output reflects entity names + types, so a value change moves
+// the bytes but an unrelated edit (comment) does not.
+const fakeSerializer: Serializer = {
+  name: "fake",
+  rulePrefix: "FAKE",
+  serialize: (entities) =>
+    JSON.stringify([...entities.keys()].sort().map((k) => ({ k, t: entities.get(k)!.entityType }))),
+};
+
+function widget(type: string): string {
+  return `export const foo = { lexicon: "fake", entityType: "${type}", [Symbol.for("chant.declarable")]: true };\n`;
+}
+
+// ── Pure model ────────────────────────────────────────────────────────────────
+
+describe("changedStacks", () => {
+  test("flags stacks whose output differs, and added/removed stacks", () => {
+    const base = new Map([["a", "1"], ["b", "2"], ["gone", "x"]]);
+    const head = new Map([["a", "1"], ["b", "CHANGED"], ["new", "y"]]);
+    expect(changedStacks(base, head)).toEqual(["b", "gone", "new"]);
+  });
+  test("identical builds → nothing changed", () => {
+    const m = new Map([["a", "1"], ["b", "2"]]);
+    expect(changedStacks(m, new Map(m))).toEqual([]);
+  });
+});
+
+describe("dependentStacks", () => {
+  // Diamond: top→left, top→right, left→base, right→base (consumer→producer).
+  const graph: StackGraph = {
+    nodes: ["base", "left", "right", "top"],
+    edges: [
+      { from: "left", to: "base" },
+      { from: "right", to: "base" },
+      { from: "top", to: "left" },
+      { from: "top", to: "right" },
+    ],
+    order: ["base", "left", "right", "top"],
+    waves: [["base"], ["left", "right"], ["top"]],
+    cycles: [],
+  };
+  test("a changed producer surfaces all transitive consumers", () => {
+    expect(dependentStacks(["base"], graph)).toEqual(["left", "right", "top"]);
+  });
+  test("a changed mid-stack surfaces only what's above it", () => {
+    expect(dependentStacks(["left"], graph)).toEqual(["top"]);
+  });
+  test("nothing depends on the top", () => {
+    expect(dependentStacks(["top"], graph)).toEqual([]);
+  });
+});
+
+describe("computeAffected", () => {
+  const graph: StackGraph = {
+    nodes: ["aws", "k8s"],
+    edges: [{ from: "k8s", to: "aws" }],
+    order: ["aws", "k8s"],
+    waves: [["aws"], ["k8s"]],
+    cycles: [],
+  };
+  const base = new Map([["aws", "v1"], ["k8s", "same"]]);
+  const head = new Map([["aws", "v2"], ["k8s", "same"]]);
+
+  test("dependents excluded by default", () => {
+    const r = computeAffected(base, head, graph);
+    expect(r.changed).toEqual(["aws"]);
+    expect(r.dependents).toEqual([]);
+  });
+  test("--include-dependents adds the unchanged consumer of a changed producer", () => {
+    const r = computeAffected(base, head, graph, { includeDependents: true });
+    expect(r.changed).toEqual(["aws"]);
+    expect(r.dependents).toEqual(["k8s"]); // k8s bytes unchanged, but consumes aws
+  });
+  test("external-input stacks are reported as indeterminate", () => {
+    const r = computeAffected(base, head, graph, { externalInput: ["k8s"] });
+    expect(r.indeterminate).toEqual(["k8s"]);
+  });
+});
+
+describe("externalInputStacks", () => {
+  test("detects stacks declaring a deploy-time parameter", () => {
+    const entities = new Map<string, Declarable>([
+      ["p", { lexicon: "aws", entityType: "Param", parameterType: "String" } as unknown as Declarable],
+      ["r", { lexicon: "k8s", entityType: "Deployment" } as unknown as Declarable],
+    ]);
+    expect(externalInputStacks(entities)).toEqual(["aws"]);
+  });
+});
+
+// ── Integration: artifact diff over real builds ──────────────────────────────
+
+describe("affectedStacks — baseDir (caller-supplied)", () => {
+  let root: string;
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "chant-affected-it-"));
+  });
+  afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+  const srcDir = (name: string, content: string): string => {
+    const dir = join(root, name);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "infra.ts"), content);
+    return dir;
+  };
+
+  test("a value change makes the stack affected", async () => {
+    const base = srcDir("base", widget("Widget"));
+    const head = srcDir("head", widget("Gadget"));
+    const r = await affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer] });
+    expect(r.changed).toEqual(["fake"]);
+  });
+
+  test("a no-output-change refactor is NOT affected (deterministic build)", async () => {
+    const base = srcDir("base", widget("Widget"));
+    // Same declarable, only a comment added — serialized output is identical.
+    const head = srcDir("head", "// a harmless refactor\n" + widget("Widget"));
+    const r = await affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer] });
+    expect(r.changed).toEqual([]);
+  });
+});
+
+describe("affectedStacks — baseRef (git worktree)", () => {
+  let repo: string;
+  beforeEach(async () => {
+    repo = mkdtempSync(join(tmpdir(), "chant-affected-git-"));
+    const git = (...a: string[]) => execFileAsync("git", a, { cwd: repo });
+    await git("init", "-q");
+    await git("config", "user.email", "t@t.dev");
+    await git("config", "user.name", "t");
+    writeFileSync(join(repo, "infra.ts"), widget("Widget"));
+    await git("add", "-A");
+    await git("commit", "-q", "-m", "base");
+  });
+  afterEach(() => rmSync(repo, { recursive: true, force: true }));
+
+  test("diffs the working tree against a base ref via one worktree", async () => {
+    // Mutate the working tree (uncommitted) — the head build sees this.
+    writeFileSync(join(repo, "infra.ts"), widget("Gadget"));
+    const r = await affectedStacks({ projectPath: repo, baseRef: "HEAD", serializers: [fakeSerializer] });
+    expect(r.changed).toEqual(["fake"]);
+  }, 30_000);
+});

package/src/lifecycle/affected.ts

@@ -0,0 +1,202 @@
+/**
+ * Selective change-set scoping — which stacks does a change affect?
+ *
+ * "Affected" is two distinct things, because chant serializes cross-stack
+ * references symbolically:
+ *   1. **Directly changed** — the stack's built artifact differs between base
+ *      and head. Caught by artifact diff over deterministic builds, so it
+ *      ignores comment-only / refactor-with-no-output-change edits.
+ *   2. **Operationally affected (dependents)** — a stack whose own artifact is
+ *      unchanged but which consumes an upstream export whose value changed. Its
+ *      bytes don't move, yet it may need re-apply. Caught by walking the
+ *      cross-stack graph (#200) from the directly-changed set; opt-in.
+ *
+ * A stack whose inputs come from outside synthesis (deploy-time params) cannot
+ * be judged from a source diff — reported as **indeterminate**, not silently
+ * included or excluded.
+ *
+ * This returns the set; it does not act. Fanning `lifecycle plan` / `ApplyOp`
+ * over it is an Op the user composes.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdtempSync, rmSync, existsSync, symlinkSync, realpathSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { build, type StackGraph } from "../build";
+import { getPrimaryOutput } from "../lint/post-synth";
+import type { Serializer } from "../serializer";
+import type { Declarable } from "../declarable";
+
+const execFileAsync = promisify(execFile);
+
+export interface AffectedResult {
+  /** Stacks whose built artifact differs between base and head. */
+  changed: string[];
+  /** Downstream consumers of changed stacks (only when `includeDependents`). */
+  dependents: string[];
+  /** Stacks with deploy-time inputs — cannot be confirmed from a source diff. */
+  indeterminate: string[];
+}
+
+// ── Pure model ──────────────────────────────────────────────────────────────
+
+/** Stacks whose serialized output differs between the two builds (added/removed count). */
+export function changedStacks(
+  base: Map<string, string>,
+  head: Map<string, string>,
+): string[] {
+  const names = new Set([...base.keys(), ...head.keys()]);
+  const changed: string[] = [];
+  for (const name of names) {
+    if (base.get(name) !== head.get(name)) changed.push(name);
+  }
+  return changed.sort();
+}
+
+/**
+ * Walk the cross-stack graph backwards from `changed` to find every stack that
+ * (transitively) consumes a changed stack. Edge `from → to` means `from`
+ * depends on `to`, so a changed `to` makes `from` a dependent.
+ */
+export function dependentStacks(changed: string[], graph: StackGraph): string[] {
+  const consumersOf = new Map<string, string[]>();
+  for (const { from, to } of graph.edges) {
+    (consumersOf.get(to) ?? consumersOf.set(to, []).get(to)!).push(from);
+  }
+  const seen = new Set(changed);
+  const queue = [...changed];
+  const dependents = new Set<string>();
+  while (queue.length > 0) {
+    const node = queue.shift()!;
+    for (const consumer of consumersOf.get(node) ?? []) {
+      if (seen.has(consumer)) continue;
+      seen.add(consumer);
+      dependents.add(consumer);
+      queue.push(consumer);
+    }
+  }
+  return [...dependents].sort();
+}
+
+/**
+ * Compute the affected set from two per-stack artifact maps and the cross-stack
+ * graph. Pure — no builds, no git — so the model is independently testable.
+ */
+export function computeAffected(
+  base: Map<string, string>,
+  head: Map<string, string>,
+  graph: StackGraph,
+  opts: { includeDependents?: boolean; externalInput?: string[] } = {},
+): AffectedResult {
+  const changed = changedStacks(base, head);
+  const dependents = opts.includeDependents ? dependentStacks(changed, graph) : [];
+  const indeterminate = [...(opts.externalInput ?? [])].sort();
+  return { changed, dependents, indeterminate };
+}
+
+// ── Build + git plumbing ──────────────────────────────────────────────────────
+
+/** A built BuildResult's per-stack (lexicon) primary output, keyed by stack. */
+export function artifactMap(outputs: Map<string, string | { primary: string }>): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const [stack, output] of outputs) map.set(stack, getPrimaryOutput(output as string));
+  return map;
+}
+
+/** Stacks (lexicons) that declare a deploy-time parameter — external input. */
+export function externalInputStacks(entities: Map<string, Declarable>): string[] {
+  const stacks = new Set<string>();
+  for (const [, entity] of entities) {
+    if ("parameterType" in entity && typeof (entity as { parameterType?: unknown }).parameterType === "string") {
+      stacks.add(entity.lexicon);
+    }
+  }
+  return [...stacks].sort();
+}
+
+async function gitTopLevel(cwd: string): Promise<string> {
+  const { stdout } = await execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd });
+  return stdout.trim();
+}
+
+/**
+ * Check out `ref` into a throwaway worktree, symlink the repo's node_modules so
+ * lexicon imports resolve, run `fn`, then remove the worktree. At most one
+ * worktree exists at a time.
+ */
+async function withWorktree<T>(repoRoot: string, ref: string, fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = mkdtempSync(join(tmpdir(), "chant-affected-"));
+  await execFileAsync("git", ["worktree", "add", "--detach", dir, ref], { cwd: repoRoot });
+  try {
+    const nm = join(repoRoot, "node_modules");
+    const linked = join(dir, "node_modules");
+    if (existsSync(nm) && !existsSync(linked)) symlinkSync(nm, linked, "dir");
+    return await fn(dir);
+  } finally {
+    await execFileAsync("git", ["worktree", "remove", "--force", dir], { cwd: repoRoot }).catch(() => {
+      rmSync(dir, { recursive: true, force: true });
+    });
+  }
+}
+
+export interface AffectedStacksOptions {
+  /** Project source directory to scope (the head/working-tree build root). */
+  projectPath: string;
+  serializers: Serializer[];
+  /** Base git ref to diff against (built in a throwaway worktree). */
+  baseRef?: string;
+  /** Head git ref. Defaults to the working tree (built in place — no worktree). */
+  headRef?: string;
+  /**
+   * Caller-supplied base source directory (already on disk). Takes precedence
+   * over `baseRef` — no worktree is created. Use for a build cache or two dist
+   * trees you already have.
+   */
+  baseDir?: string;
+  includeDependents?: boolean;
+}
+
+/**
+ * Compute the affected stacks for a change. Head is built in place (the working
+ * tree); base is built from `baseDir` if supplied, else from `baseRef` via a
+ * single throwaway worktree. Builds are deterministic, so a cached/supplied base
+ * is as trustworthy as a rebuild.
+ */
+export async function affectedStacks(opts: AffectedStacksOptions): Promise<AffectedResult> {
+  const projectPath = resolve(opts.projectPath);
+  const needsWorktree = Boolean(opts.headRef) || Boolean(opts.baseRef && !opts.baseDir);
+  const repoRoot = needsWorktree ? await gitTopLevel(projectPath) : projectPath;
+  // Canonicalize via realpath so the worktree-relative path is correct even when
+  // the temp dir is a symlink (macOS /var → /private/var) and `git
+  // rev-parse --show-toplevel` reports the real path.
+  const relProject = needsWorktree ? relative(repoRoot, realpathSync(projectPath)) : "";
+
+  // Head: the in-place build of the working tree, unless an explicit headRef is
+  // given (then a throwaway worktree — removed before the base worktree, so at
+  // most one exists at a time).
+  const head = opts.headRef
+    ? await withWorktree(repoRoot, opts.headRef, (dir) => build(join(dir, relProject), opts.serializers))
+    : await build(projectPath, opts.serializers);
+  const headMap = artifactMap(head.outputs);
+  const externalInput = externalInputStacks(head.entities);
+
+  // Base: caller-supplied dir (cheapest), else a single worktree at baseRef.
+  let baseMap: Map<string, string>;
+  if (opts.baseDir) {
+    const baseBuild = await build(resolve(opts.baseDir), opts.serializers);
+    baseMap = artifactMap(baseBuild.outputs);
+  } else if (opts.baseRef) {
+    baseMap = await withWorktree(repoRoot, opts.baseRef, async (dir) => {
+      const baseBuild = await build(join(dir, relProject), opts.serializers);
+      return artifactMap(baseBuild.outputs);
+    });
+  } else {
+    throw new Error("affectedStacks requires either baseDir or baseRef");
+  }
+
+  return computeAffected(baseMap, headMap, head.manifest.stackGraph, {
+    includeDependents: opts.includeDependents,
+    externalInput,
+  });
+}

package/src/lifecycle/index.ts

@@ -4,3 +4,4 @@ export * from "./digest";
 export * from "./snapshot";
 export * from "./live-diff";
 export * from "./change-set";
+export * from "./affected";

package/src/lint/config.ts

@@ -29,6 +29,7 @@ export const LintConfigSchema = z.object({
     rules: z.record(z.string(), RuleConfigSchema),
   })).optional(),
   plugins: z.array(z.string()).optional(),
+  policies: z.array(z.string()).optional(),
 });
 
 /**
@@ -149,6 +150,14 @@ export interface LintConfig {
   overrides?: LintOverride[];
   /** Array of plugin file paths to load custom rules from (project-local, not inherited) */
   plugins?: string[];
+  /**
+   * Array of file paths to load project-authored organizational policy checks
+   * from — each exporting one or more {@link PostSynthCheck} objects. They run
+   * during `chant build` over the resolved resources, with the current `env` in
+   * context. Distinct from `plugins` (declarative lint rules) by authorship and
+   * phase; same engine.
+   */
+  policies?: string[];
 }
 
 /**

package/src/lint/policy.ts

@@ -0,0 +1,81 @@
+/**
+ * Project-authored organizational policy: loading the policy pack and evaluating
+ * it against a freshly built project. `chant build` runs policies inline; the
+ * `policyGate` Op step runs this to gate an apply on the same checks.
+ */
+import { resolve, dirname } from "node:path";
+import { loadChantConfig } from "../config";
+import { resolveProjectLexicons, loadPlugins } from "../cli/plugins";
+import { build } from "../build";
+import { runPostSynthChecks, isPostSynthCheck } from "./post-synth";
+import type { PostSynthCheck, PostSynthDiagnostic } from "./post-synth";
+
+/** Load project policy checks (one or more `PostSynthCheck` exports) from files. */
+export async function loadPolicyChecks(paths: string[], configDir: string): Promise<PostSynthCheck[]> {
+  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>;
+    } catch (err) {
+      throw new Error(
+        `Failed to load policy "${p}": ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    for (const value of Object.values(mod)) {
+      if (isPostSynthCheck(value)) checks.push(value);
+    }
+  }
+  return checks;
+}
+
+export interface PolicyEvaluation {
+  /** All policy diagnostics (errors + warnings). */
+  diagnostics: PostSynthDiagnostic[];
+  /** The error-severity subset — these are policy *violations* that gate. */
+  violations: PostSynthDiagnostic[];
+  /** The environment policies were evaluated against (if any). */
+  env?: string;
+}
+
+/**
+ * Build a project and run its `lint.policies` over the resolved resources,
+ * standalone — used by the `policyGate` Op step to gate an apply on the same
+ * organizational policy `chant build` enforces. Loads the project's lexicons,
+ * builds, then runs the policy pack with `env` (explicit, else `ownership.env`).
+ */
+export async function evaluateProjectPolicies(opts: {
+  path: string;
+  env?: string;
+}): Promise<PolicyEvaluation> {
+  const buildPath = resolve(opts.path);
+
+  const lexiconNames = await resolveProjectLexicons(buildPath);
+  const plugins = await loadPlugins(lexiconNames);
+  const serializers = plugins.map((p) => p.serializer);
+
+  // Config can live in the build dir or its parent (the project root).
+  const loaded = await loadChantConfig(buildPath).then((r) =>
+    r.configPath ? r : loadChantConfig(dirname(buildPath)),
+  );
+  const config = loaded.config;
+  const configDir = loaded.configPath ? dirname(loaded.configPath) : buildPath;
+  const env = opts.env ?? config.ownership?.env;
+
+  const result = await build(buildPath, serializers);
+  if (result.errors.length > 0) {
+    throw new Error("Build failed — cannot evaluate policy on a broken build");
+  }
+
+  const checks = config.lint?.policies?.length
+    ? await loadPolicyChecks(config.lint.policies, configDir)
+    : [];
+  if (checks.length === 0) {
+    return { diagnostics: [], violations: [], env };
+  }
+
+  const diagnostics = runPostSynthChecks(checks, result, env);
+  const violations = diagnostics.filter((d) => d.severity === "error");
+  return { diagnostics, violations, env };
+}

package/src/lint/post-synth.test.ts

@@ -111,3 +111,33 @@ describe("post-synth checks", () => {
     expect(diags).toHaveLength(0);
   });
 });
+
+describe("environment-aware checks (#201)", () => {
+  // A policy that only fires in prod — the new env-branching primitive.
+  const prodOnly: PostSynthCheck = {
+    id: "ENV-PROD",
+    description: "fires only in prod",
+    check(ctx) {
+      return ctx.env === "prod"
+        ? [{ checkId: "ENV-PROD", severity: "error", message: "blocked in prod" }]
+        : [];
+    },
+  };
+
+  test("env is threaded into the context", () => {
+    expect(runPostSynthChecks([prodOnly], createBuildResult(), "prod")).toHaveLength(1);
+    expect(runPostSynthChecks([prodOnly], createBuildResult(), "dev")).toHaveLength(0);
+    expect(runPostSynthChecks([prodOnly], createBuildResult())).toHaveLength(0); // env undefined
+  });
+});
+
+describe("isPostSynthCheck", () => {
+  test("accepts a well-formed check and rejects others", async () => {
+    const { isPostSynthCheck } = await import("./post-synth");
+    expect(isPostSynthCheck({ id: "X", description: "d", check: () => [] })).toBe(true);
+    expect(isPostSynthCheck({ id: "X", description: "d" })).toBe(false); // no check fn
+    expect(isPostSynthCheck({ check: () => [] })).toBe(false); // no id/description
+    expect(isPostSynthCheck(null)).toBe(false);
+    expect(isPostSynthCheck("nope")).toBe(false);
+  });
+});

package/src/lint/post-synth.ts

@@ -10,6 +10,12 @@ export interface PostSynthContext {
   outputs: Map<string, string | SerializerResult>;
   /** Map of entity name to Declarable entity */
   entities: Map<string, Declarable>;
+  /**
+   * The environment/stack being built, if known (from `--env` or the project's
+   * `ownership.env`). Lets an organizational policy branch on environment —
+   * e.g. "no public buckets in prod". Undefined when no environment is set.
+   */
+  env?: string;
   /** Raw build result object */
   buildResult: {
     outputs: Map<string, string | SerializerResult>;
@@ -44,7 +50,9 @@ export interface PostSynthDiagnostic {
 }
 
 /**
- * A post-synthesis check that validates build output.
+ * A post-synthesis check that validates build output. Lexicons ship these as
+ * domain rules; projects author them as organizational policy (see the
+ * `lint.policies` config and the Organizational Policy guide).
  */
 export interface PostSynthCheck {
   /** Unique identifier for this check */
@@ -55,16 +63,30 @@ export interface PostSynthCheck {
   check(ctx: PostSynthContext): PostSynthDiagnostic[];
 }
 
+/** Structural type guard — used to collect project-authored policy checks. */
+export function isPostSynthCheck(value: unknown): value is PostSynthCheck {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as PostSynthCheck).id === "string" &&
+    typeof (value as PostSynthCheck).description === "string" &&
+    typeof (value as PostSynthCheck).check === "function"
+  );
+}
+
 /**
- * Run a set of post-synthesis checks against a build result.
+ * Run a set of post-synthesis checks against a build result. `env` is threaded
+ * into the context so a check can branch on the current environment/stack.
  */
 export function runPostSynthChecks(
   checks: PostSynthCheck[],
   buildResult: PostSynthContext["buildResult"],
+  env?: string,
 ): PostSynthDiagnostic[] {
   const ctx: PostSynthContext = {
     outputs: buildResult.outputs,
     entities: buildResult.entities,
+    env,
     buildResult,
   };
 

package/src/op/builders.ts

@@ -130,3 +130,17 @@ export const shell = (
 /** Run `chant teardown` in the given project directory. Uses `longInfra` profile. */
 export const teardown = (path: string): ActivityStep =>
   activity("chantTeardown", { path }, "longInfra");
+
+/**
+ * Gate an apply on organizational policy: build the project and run its
+ * `lint.policies` over the resolved resources, blocking the workflow on any
+ * violation. Place it before the apply phase. `env` (or `ownership.env`) lets a
+ * policy branch on environment. Single-attempt (`policyCheck` profile) — a
+ * deterministic violation is not retried.
+ */
+export const policyGate = (opts?: { env?: string; path?: string }): ActivityStep =>
+  activity(
+    "policyGate",
+    { path: opts?.path ?? ".", ...(opts?.env ? { env: opts.env } : {}) },
+    "policyCheck",
+  );

package/src/op/index.ts

@@ -1,5 +1,5 @@
 export { Op, phase, activity, gate, build, kubectlApply, helmInstall, waitForStack,
-         gitlabPipeline, lifecycleSnapshot, shell, teardown } from "./builders";
+         gitlabPipeline, lifecycleSnapshot, shell, teardown, policyGate } from "./builders";
 export { OpResource } from "./resource";
 export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep } from "./types";
 export { discoverOps } from "./discover";

package/src/op/op.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, expect, it } from "vitest";
 import { Op, phase, activity, gate, build, kubectlApply, helmInstall,
-         waitForStack, gitlabPipeline, lifecycleSnapshot, shell, teardown } from "./builders";
+         waitForStack, gitlabPipeline, lifecycleSnapshot, shell, teardown, policyGate } from "./builders";
 import { DECLARABLE_MARKER, type Declarable } from "../declarable";
 
 // ── Op() ──────────────────────────────────────────────────────────────────────
@@ -196,6 +196,20 @@ describe("pre-built shortcuts", () => {
     expect(a.args?.path).toBe("./project");
     expect(a.profile).toBe("longInfra");
   });
+
+  it("policyGate() produces a policyGate activity with the single-attempt policyCheck profile", () => {
+    const a = policyGate({ env: "prod" });
+    expect(a.fn).toBe("policyGate");
+    expect(a.args?.path).toBe("."); // defaults to the project dir
+    expect(a.args?.env).toBe("prod");
+    expect(a.profile).toBe("policyCheck");
+  });
+
+  it("policyGate() with no opts defaults path to '.' and omits env", () => {
+    const a = policyGate();
+    expect(a.args?.path).toBe(".");
+    expect("env" in (a.args ?? {})).toBe(false);
+  });
 });
 
 describe("profile routing (opts.profile sets the step profile, never leaks into args)", () => {

package/src/op/types.ts

@@ -45,7 +45,7 @@ export interface ActivityStep {
    * Key from TEMPORAL_ACTIVITY_PROFILES controlling timeout + retry.
    * Default: "fastIdempotent"
    */
-  profile?: "fastIdempotent" | "longInfra" | "k8sWait" | "humanGate" | "argoSync";
+  profile?: "fastIdempotent" | "longInfra" | "k8sWait" | "humanGate" | "argoSync" | "policyCheck";
   /**
    * Surface this activity's return value as a workflow search attribute.
    *