test(trigger-e2e): add deterministic gate/synth-PR trigger-condition E2E suite

Add an ADO-native, non-agentic E2E test framework for the runtime trigger
conditions managed by ado-script (gate.js PR filters and
exec-context-pr-synth.js synthetic-PR promotion), modeled on the executor-e2e
native bundle. A parameterized victim pipeline runs only the two bundles and
reports the decision via REST-observable build tags; an orchestrator harness
creates real PRs and queues the victim many ways, asserting the gate decision.

Test-only bundle: excluded from ado-script.zip exactly like executor-e2e.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: f30758a5-81c8-4024-ab01-52ad22b4f877

Author: jamesadevine

scripts/ado-script/package.json

@@ -25,6 +25,7 @@
     "build:github-app-token": "ncc build src/github-app-token/index.ts -o .ado-build/github-app-token -m -t && node -e \"const fs=require('node:fs'); fs.copyFileSync('.ado-build/github-app-token/index.js','github-app-token.js'); fs.rmSync('.ado-build/github-app-token',{recursive:true,force:true});\"",
     "build:prepare-pr-base": "ncc build src/prepare-pr-base/index.ts -o .ado-build/prepare-pr-base -m -t && node -e \"const fs=require('node:fs'); fs.copyFileSync('.ado-build/prepare-pr-base/index.js','prepare-pr-base.js'); fs.rmSync('.ado-build/prepare-pr-base',{recursive:true,force:true});\"",
     "build:executor-e2e": "ncc build src/executor-e2e/index.ts -o .ado-build/executor-e2e -m -t && node -e \"const fs=require('node:fs'); fs.mkdirSync('test-bin',{recursive:true}); fs.copyFileSync('.ado-build/executor-e2e/index.js','test-bin/executor-e2e.js'); fs.rmSync('.ado-build/executor-e2e',{recursive:true,force:true});\"",
+    "build:trigger-e2e": "ncc build src/trigger-e2e/index.ts -o .ado-build/trigger-e2e -m -t && node -e \"const fs=require('node:fs'); fs.mkdirSync('test-bin',{recursive:true}); fs.copyFileSync('.ado-build/trigger-e2e/index.js','test-bin/trigger-e2e.js'); fs.rmSync('.ado-build/trigger-e2e',{recursive:true,force:true});\"",
     "build:check": "ls -lh gate.js && wc -c gate.js",
     "codegen": "node -e \"require('node:fs').mkdirSync('schema', { recursive: true })\" && cargo run --quiet --manifest-path ../../Cargo.toml -- export-gate-schema --output schema/gate-spec.schema.json && npx json2ts schema/gate-spec.schema.json -o src/shared/types.gen.ts --bannerComment \"// AUTO-GENERATED from Rust IR via cargo run -- export-gate-schema. Do not edit; run npm run codegen.\"",
     "test": "vitest run",

scripts/ado-script/src/__tests__/bundle-coverage.test.ts

@@ -30,8 +30,12 @@ const packageJsonPath = join(here, "..", "..", "package.json");
  * so the release glob (`ado-script/*.js`) never packages it — it is a test
  * harness run only by the executor-e2e pipeline, never downloaded by compiled
  * agentic pipelines at runtime.
+ *
+ * `trigger-e2e` is the analogous deterministic trigger-condition (gate /
+ * synth-PR) E2E harness. Same treatment: its own `build:trigger-e2e` emits to
+ * `test-bin/`, so it is never packaged in `ado-script.zip`.
  */
-const NON_BUNDLE_DIRS = new Set(["shared", "__tests__", "executor-e2e"]);
+const NON_BUNDLE_DIRS = new Set(["shared", "__tests__", "executor-e2e", "trigger-e2e"]);
 
 function listBundleDirs(): string[] {
   return readdirSync(srcDir)

scripts/ado-script/src/executor-e2e/ado-rest.ts

@@ -264,18 +264,21 @@ export class AdoRest {
     targetRef: string,
     title: string,
     description: string,
+    isDraft?: boolean,
   ): Promise<{ pullRequestId: number }> {
     const path = this.projPath(
       `_apis/git/repositories/${AdoRest.seg(repo)}/pullrequests?api-version=7.1`,
     );
+    const body: Record<string, unknown> = {
+      sourceRefName: sourceRef.startsWith("refs/") ? sourceRef : `refs/heads/${sourceRef}`,
+      targetRefName: targetRef.startsWith("refs/") ? targetRef : `refs/heads/${targetRef}`,
+      title,
+      description,
+    };
+    if (isDraft !== undefined) body.isDraft = isDraft;
     const res = await this.request<{ pullRequestId: number }>(path, {
       method: "POST",
-      body: {
-        sourceRefName: sourceRef.startsWith("refs/") ? sourceRef : `refs/heads/${sourceRef}`,
-        targetRefName: targetRef.startsWith("refs/") ? targetRef : `refs/heads/${targetRef}`,
-        title,
-        description,
-      },
+      body,
     });
     if (!res) throw new Error("createPullRequest returned no body");
     return res;
@@ -365,6 +368,20 @@ export class AdoRest {
     await this.request(path, { method: "PATCH", body: { status: "abandoned" }, allow404: true });
   }
 
+  /**
+   * Attach one or more labels (tags) to a PR. ADO's label endpoint takes a
+   * single `{ name }` per POST, so this loops. Used by the trigger E2E harness
+   * to exercise the gate's `label_set_match` predicate against real PR labels.
+   */
+  async setPullRequestLabels(repo: string, prId: number, labels: string[]): Promise<void> {
+    for (const name of labels) {
+      const path = this.projPath(
+        `_apis/git/repositories/${AdoRest.seg(repo)}/pullRequests/${prId}/labels?api-version=7.1`,
+      );
+      await this.request(path, { method: "POST", body: { name } });
+    }
+  }
+
   // ---- Wiki -------------------------------------------------------------
 
   async listWikis(): Promise<{ name: string; id: string; type?: string }[]> {
@@ -451,4 +468,62 @@ export class AdoRest {
     const path = this.projPath(`_apis/build/builds/${buildId}?api-version=7.1`);
     await this.request(path, { method: "PATCH", body: { status: "cancelling" }, allow404: true });
   }
+
+  /**
+   * Queue a new build of a registered definition. `sourceBranch` selects the
+   * branch to build (used by the trigger E2E harness to point a queued build
+   * at a PR's source branch so `exec-context-pr-synth` can discover the open
+   * PR). `templateParameters` supplies the victim pipeline's runtime
+   * parameters (e.g. the base64 GATE_SPEC / PR_SYNTH_SPEC under test).
+   *
+   * Returns the new build id. Note: a build queued via this REST call has
+   * `Build.Reason = Manual`; the victim relies on the synthetic-PR flag (set
+   * by `exec-context-pr-synth` from a real open PR) — not the build reason —
+   * to drive full PR-gate evaluation.
+   */
+  async queueBuild(
+    definitionId: number,
+    opts: { sourceBranch?: string; templateParameters?: Record<string, string> } = {},
+  ): Promise<{ id: number }> {
+    const path = this.projPath(`_apis/build/builds?api-version=7.1`);
+    const body: Record<string, unknown> = { definition: { id: definitionId } };
+    if (opts.sourceBranch) {
+      body.sourceBranch = opts.sourceBranch.startsWith("refs/")
+        ? opts.sourceBranch
+        : `refs/heads/${opts.sourceBranch}`;
+    }
+    if (opts.templateParameters && Object.keys(opts.templateParameters).length > 0) {
+      body.templateParameters = opts.templateParameters;
+    }
+    const res = await this.request<{ id: number }>(path, { method: "POST", body });
+    if (!res) throw new Error(`queueBuild(${definitionId}) returned no body`);
+    return res;
+  }
+
+  /**
+   * Poll a build until it reaches `status === "completed"` (or the timeout
+   * elapses). Returns the terminal `{ status, result }`. `result` is one of
+   * `succeeded` | `partiallySucceeded` | `failed` | `canceled`.
+   */
+  async waitForBuild(
+    buildId: number,
+    opts: { timeoutMs?: number; pollMs?: number } = {},
+  ): Promise<{ status: string; result?: string }> {
+    const timeoutMs =
+      opts.timeoutMs ?? (Number(process.env.TRIGGER_E2E_BUILD_TIMEOUT_MS) || 900_000);
+    const pollMs = opts.pollMs ?? (Number(process.env.TRIGGER_E2E_BUILD_POLL_MS) || 10_000);
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      const build = await this.getBuild(buildId);
+      if (build.status === "completed") {
+        return { status: build.status, result: build.result };
+      }
+      if (Date.now() >= deadline) {
+        throw new Error(
+          `waitForBuild(${buildId}) timed out after ${timeoutMs}ms (last status='${build.status ?? "?"}')`,
+        );
+      }
+      await new Promise((r) => setTimeout(r, pollMs));
+    }
+  }
 }

scripts/ado-script/src/trigger-e2e/__tests__/gate-spec.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  buildGateSpec,
+  changeCountCheck,
+  changedFilesCheck,
+  draftCheck,
+  encodeGateSpec,
+  encodePrSynthSpec,
+  labelsCheck,
+  targetBranchCheck,
+  titleCheck,
+} from "../gate-spec.js";
+
+const factKinds = (checks: Parameters<typeof buildGateSpec>[1]) =>
+  buildGateSpec("pull-request", checks).facts.map((f) => f.kind);
+
+describe("buildGateSpec fact derivation", () => {
+  it("emits no facts and no checks for an empty gate", () => {
+    const spec = buildGateSpec("pull-request", []);
+    expect(spec.facts).toEqual([]);
+    expect(spec.checks).toEqual([]);
+    expect(spec.context.tag_prefix).toBe("pr-gate");
+    expect(spec.context.build_reason).toBe("PullRequest");
+    expect(spec.context.bypass_label).toBe("PR");
+  });
+
+  it("derives pr_metadata (skip_dependents) before pr_labels (fail_open) for a labels check", () => {
+    const spec = buildGateSpec("pull-request", [labelsCheck({ anyOf: ["run-agent"] })]);
+    const kinds = spec.facts.map((f) => f.kind);
+    expect(kinds).toEqual(["pr_metadata", "pr_labels"]);
+    const meta = Object.fromEntries(spec.facts.map((f) => [f.kind, f]));
+    expect(meta.pr_metadata!.failure_policy).toBe("skip_dependents");
+    expect(meta.pr_metadata!.dependencies).toEqual([]);
+    expect(meta.pr_labels!.failure_policy).toBe("fail_open");
+    expect(meta.pr_labels!.dependencies).toEqual(["pr_metadata"]);
+  });
+
+  it("derives pr_metadata before pr_is_draft (fail_closed) for a draft check", () => {
+    expect(factKinds([draftCheck(true)])).toEqual(["pr_metadata", "pr_is_draft"]);
+  });
+
+  it("derives changed_files before changed_file_count for a change-count check", () => {
+    expect(factKinds([changeCountCheck({ min: 5 })])).toEqual([
+      "changed_files",
+      "changed_file_count",
+    ]);
+  });
+
+  it("derives only changed_files for a changed-files check", () => {
+    expect(factKinds([changedFilesCheck({ include: ["src/**"] })])).toEqual(["changed_files"]);
+  });
+
+  it("derives a single fail_closed pipeline-var fact for a title check", () => {
+    const spec = buildGateSpec("pull-request", [titleCheck("release *")]);
+    expect(spec.facts).toEqual([
+      { kind: "pr_title", failure_policy: "fail_closed", dependencies: [] },
+    ]);
+  });
+
+  it("dedupes facts shared across multiple checks", () => {
+    const kinds = factKinds([draftCheck(true), labelsCheck({ anyOf: ["x"] })]);
+    // pr_metadata appears once, before both dependents, in enum order.
+    expect(kinds).toEqual(["pr_metadata", "pr_is_draft", "pr_labels"]);
+  });
+});
+
+describe("check tag suffixes match the Rust FilterCheck::build_tag_suffix", () => {
+  it("emits the expected suffixes", () => {
+    const cases: [Parameters<typeof buildGateSpec>[1][number], string][] = [
+      [titleCheck("x"), "title-mismatch"],
+      [labelsCheck({ anyOf: ["x"] }), "labels-mismatch"],
+      [changedFilesCheck({ include: ["src/**"] }), "changed-files-mismatch"],
+      [draftCheck(true), "draft-mismatch"],
+      [targetBranchCheck("main"), "target-branch-mismatch"],
+      [changeCountCheck({ min: 1 }), "changes-mismatch"],
+    ];
+    for (const [check, suffix] of cases) {
+      const spec = buildGateSpec("pull-request", [check]);
+      expect(spec.checks[0]!.tag_suffix).toBe(suffix);
+    }
+  });
+});
+
+describe("encoding", () => {
+  it("round-trips a gate spec through base64", () => {
+    const spec = buildGateSpec("pull-request", [labelsCheck({ anyOf: ["run-agent"] })]);
+    const decoded = JSON.parse(Buffer.from(encodeGateSpec(spec), "base64").toString("utf8"));
+    expect(decoded).toEqual(spec);
+  });
+
+  it("produces the canonical empty PR_SYNTH_SPEC base64", () => {
+    expect(encodePrSynthSpec()).toBe(
+      "eyJicmFuY2hlcyI6eyJpbmNsdWRlIjpbXSwiZXhjbHVkZSI6W119LCJwYXRocyI6eyJpbmNsdWRlIjpbXSwiZXhjbHVkZSI6W119fQ==",
+    );
+  });
+
+  it("encodes provided branch/path filters", () => {
+    const decoded = JSON.parse(
+      Buffer.from(
+        encodePrSynthSpec({ branches: { include: ["main"] }, paths: { exclude: ["docs/**"] } }),
+        "base64",
+      ).toString("utf8"),
+    );
+    expect(decoded).toEqual({
+      branches: { include: ["main"], exclude: [] },
+      paths: { include: [], exclude: ["docs/**"] },
+    });
+  });
+});

scripts/ado-script/src/trigger-e2e/__tests__/runner.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { AdoRest } from "../../executor-e2e/ado-rest.js";
+import { runScenario } from "../runner.js";
+import { SkipError } from "../scenario.js";
+import type { TriggerContext, TriggerScenario } from "../scenario.js";
+
+interface FakeBuild {
+  result?: string;
+  tags?: string[];
+}
+
+function makeCtx(build: FakeBuild): TriggerContext {
+  const rest = {
+    queueBuild: vi.fn().mockResolvedValue({ id: 42 }),
+    waitForBuild: vi.fn().mockResolvedValue({ status: "completed", result: build.result }),
+    getBuildTags: vi.fn().mockResolvedValue(build.tags ?? []),
+  } as unknown as AdoRest;
+  return {
+    orgUrl: "https://dev.azure.com/org/",
+    project: "proj",
+    adoRepo: "repo",
+    buildId: "1",
+    token: "t",
+    victimDefinitionId: 7,
+    rest,
+    log: () => {},
+    prefix: (id) => `ado-aw-trig-1-${id}`,
+  };
+}
+
+function scenario(overrides: Partial<TriggerScenario<string>>): TriggerScenario<string> {
+  return {
+    id: "s",
+    description: "test scenario",
+    setup: async () => "state",
+    queue: () => ({ templateParameters: { gateSpec: "x" } }),
+    expected: () => ({ result: "succeeded" }),
+    cleanup: async () => {},
+    ...overrides,
+  };
+}
+
+describe("runScenario", () => {
+  it("passes when result and tags match", async () => {
+    const ctx = makeCtx({ result: "succeeded", tags: ["trig.should-run.true"] });
+    const res = await runScenario(
+      ctx,
+      scenario({ expected: () => ({ result: "succeeded", tags: ["trig.should-run.true"] }) }),
+    );
+    expect(res.ok).toBe(true);
+  });
+
+  it("fails (assert) when a required tag is missing", async () => {
+    const ctx = makeCtx({ result: "succeeded", tags: [] });
+    const res = await runScenario(ctx, scenario({ expected: () => ({ tags: ["pr-gate.skipped"] }) }));
+    expect(res.ok).toBe(false);
+    expect(res.phase).toBe("assert");
+    expect(res.message).toContain("pr-gate.skipped");
+  });
+
+  it("fails (assert) on the wrong build result", async () => {
+    const ctx = makeCtx({ result: "canceled" });
+    const res = await runScenario(ctx, scenario({ expected: () => ({ result: "succeeded" }) }));
+    expect(res.ok).toBe(false);
+    expect(res.phase).toBe("assert");
+  });
+
+  it("fails (assert) when a forbidden tag is present", async () => {
+    const ctx = makeCtx({ result: "succeeded", tags: ["pr-gate.skipped"] });
+    const res = await runScenario(
+      ctx,
+      scenario({ expected: () => ({ absentTags: ["pr-gate.skipped"] }) }),
+    );
+    expect(res.ok).toBe(false);
+    expect(res.phase).toBe("assert");
+  });
+
+  it("records a SkipError from setup as skipped and does NOT run cleanup", async () => {
+    const ctx = makeCtx({ result: "succeeded" });
+    const cleanup = vi.fn().mockResolvedValue(undefined);
+    const res = await runScenario(
+      ctx,
+      scenario({
+        setup: async () => {
+          throw new SkipError("no repo");
+        },
+        cleanup,
+      }),
+    );
+    expect(res.skipped).toBe(true);
+    expect(res.ok).toBe(true);
+    expect(cleanup).not.toHaveBeenCalled();
+  });
+
+  it("runs cleanup after a successful setup even when assertion fails", async () => {
+    const ctx = makeCtx({ result: "failed" });
+    const cleanup = vi.fn().mockResolvedValue(undefined);
+    const res = await runScenario(ctx, scenario({ cleanup }));
+    expect(res.ok).toBe(false);
+    expect(cleanup).toHaveBeenCalledOnce();
+  });
+
+  it("honours a custom assert hook", async () => {
+    const ctx = makeCtx({ result: "succeeded" });
+    const res = await runScenario(
+      ctx,
+      scenario({
+        assert: async () => {
+          throw new Error("custom boom");
+        },
+      }),
+    );
+    expect(res.ok).toBe(false);
+    expect(res.message).toContain("custom boom");
+  });
+});