docs(site): update filter-ir page to reflect Node/TypeScript gate evaluator (#634)

Author: github-actions[bot]

site/src/content/docs/reference/filter-ir.mdx

@@ -235,8 +235,9 @@ require heuristic analysis and could produce false positives.
 ### `compile_gate_step(ctx: GateContext, checks: &[FilterCheck]) -> String`
 
 Produces a complete ADO pipeline step (`- bash: |`) with a **data-driven
-architecture**: bash is a thin ADO-macro shim, all filter logic lives in a
-generic Python evaluator that reads a JSON gate spec.
+architecture**: bash is a thin ADO-macro shim, all filter logic lives in
+the bundled Node.js gate evaluator (`scripts/ado-script/dist/gate/index.js`) that reads a JSON
+gate spec.
 
 #### Generated Step Structure
 
@@ -256,10 +257,8 @@ generic Python evaluator that reads a JSON gate spec.
     # 3. Access token passthrough
     export ADO_SYSTEM_ACCESS_TOKEN="$SYSTEM_ACCESSTOKEN"
 
-    # 4. Embedded Python evaluator (heredoc -- never modified)
-    python3 << 'GATE_EVAL_EOF'
-    ...evaluator source...
-    GATE_EVAL_EOF
+    # 4. Run the bundled Node evaluator (downloaded by the Setup job)
+    node '/tmp/ado-aw-scripts/ado-script/dist/gate/index.js'
   name: prGate
   displayName: "Evaluate PR filters"
   env:
@@ -268,7 +267,7 @@ generic Python evaluator that reads a JSON gate spec.
 
 #### Gate Spec Format (JSON)
 
-The spec is base64-encoded to prevent ADO macro expansion and heredoc
+The spec is base64-encoded to prevent ADO macro expansion and shell
 quoting issues. Decoded, it contains:
 
 ```json
@@ -300,21 +299,22 @@ quoting issues. Decoded, it contains:
 ```
 
 The spec is declarative -- it uses fact *kinds* (e.g., `"pr_title"`,
-`"pr_metadata"`) not raw REST endpoints. The Python evaluator owns
+`"pr_metadata"`) not raw REST endpoints. The Node evaluator owns
 acquisition logic.
 
-#### Python Gate Evaluator (`scripts/gate-eval.py`)
+#### Bundled Gate Evaluator (`scripts/ado-script/src/gate/`)
 
-The evaluator is a self-contained Python script embedded via
-`include_str!()`. It handles:
+The evaluator is a TypeScript program ncc-bundled to a single
+self-contained `scripts/ado-script/dist/gate/index.js` (~1.1 MB) that ships as part of the
+`ado-script.zip` release asset. It handles:
 
 1. **Bypass logic** -- reads `ADO_BUILD_REASON` and exits early for non-matching
    trigger types
 2. **Fact acquisition** -- maps fact kinds to acquisition methods:
-   - Pipeline variables -> `os.environ.get("ADO_*")`
-   - PR metadata -> `urllib` call to ADO REST API
+   - Pipeline variables -> `process.env["ADO_*"]`
+   - PR metadata -> `azure-devops-node-api` REST call to ADO
    - Changed files -> iteration API calls
-   - UTC time -> `datetime.now(timezone.utc)`
+   - UTC time -> `Date.now()`
 3. **Failure policies** -- `fail_closed`, `fail_open`, `skip_dependents`
 4. **Predicate evaluation** -- recursive evaluator supporting all predicate types
 5. **Result reporting** -- `##vso[...]` logging commands, build tags, self-cancel
@@ -343,7 +343,7 @@ The bash shim exports only the ADO macros needed by the spec's facts:
 | `numeric_range` | `fact`, `min?`, `max?` | Integer range check |
 | `time_window` | `start`, `end` | UTC HH:MM window (overnight-aware) |
 | `label_set_match` | `fact`, `any_of?`, `all_of?`, `none_of?` | Label set predicates |
-| `file_glob_match` | `fact`, `include?`, `exclude?` | Python `fnmatch` globs |
+| `file_glob_match` | `fact`, `include?`, `exclude?` | Glob match against changed file paths |
 | `and` | `operands` | All must pass |
 | `or` | `operands` | At least one must pass |
 | `not` | `operand` | Inner must fail |
@@ -352,34 +352,30 @@ The bash shim exports only the ADO macros needed by the spec's facts:
 
 ### TriggerFiltersExtension
 
-When Tier 2/3 filters are configured, the `TriggerFiltersExtension`
+When any `filters:` configuration is present, the `TriggerFiltersExtension`
 (`src/compile/extensions/trigger_filters.rs`) activates via
 `collect_extensions()`. It implements `CompilerExtension` and controls:
 
-1. **Download step** -- downloads `scripts.zip` from the ado-aw release
+1. **Node install step** -- emits a `NodeTool@0` step pinned to Node 20.x
+   LTS so the gate evaluator has a runtime
+2. **Download step** -- fetches `ado-script.zip` from the ado-aw release
    artifacts, verifies its SHA256 checksum via `checksums.txt`, then
-   extracts `gate-eval.py` to `/tmp/ado-aw-scripts/gate-eval.py`
-2. **Gate step** -- calls `compile_gate_step_external()` to generate a step
-   that references the downloaded script (no inline heredoc)
-3. **Validation** -- runs `validate_pr_filters()` / `validate_pipeline_filters()`
+   extracts `gate.js` to `/tmp/ado-aw-scripts/ado-script/dist/gate/index.js`
+3. **Gate step** -- calls `compile_gate_step_external()` to generate a step
+   that runs `node /tmp/ado-aw-scripts/ado-script/dist/gate/index.js` (no inline heredoc)
+4. **Validation** -- runs `validate_pr_filters()` / `validate_pipeline_filters()`
    during compilation via the `validate()` trait method
 
 The extension uses the `setup_steps()` trait method (not `prepare_steps()`)
-because the gate must run in the **Setup job** (before the SafeOutputs job).
-
-### Tier 1 Inline Path
-
-When only Tier 1 filters are configured (pipeline variables -- title, author,
-branch, commit-message, build-reason), the extension is NOT activated.
-`generate_pr_gate_step()` generates an inline bash gate step directly, with
-no Python evaluator and no download step.
+because the gate must run in the **Setup job** (before the Agent job). All
+filter types are evaluated by the Node evaluator — there is no inline bash
+codegen path.
 
 ### Gate Step Injection
 
 Gate steps are injected into the Setup job by `generate_setup_job()` in
-`common.rs`. When the `TriggerFiltersExtension` is active, its
-`setup_steps()` are collected and injected first (download + gate). When
-only Tier 1 filters are present, the inline gate step is injected directly.
+`common.rs`. The `TriggerFiltersExtension`'s `setup_steps()` are collected
+and injected first (Node install + download + gate steps).
 
 User setup steps are conditioned on the gate output:
 `condition: eq(variables['{stepName}.SHOULD_RUN'], 'true')`
@@ -406,13 +402,15 @@ The `expression` escape hatch is also ANDed if present.
 
 ### Scripts Distribution
 
-`gate-eval.py` lives at `scripts/gate-eval.py` in the repository and is
-shipped inside a `scripts.zip` archive alongside the ado-aw binary. The
-download URL is deterministic based on the ado-aw version:
-`https://github.com/githubnext/ado-aw/releases/download/v{VERSION}/scripts.zip`
+The `gate.js` bundle is built from the TypeScript workspace at
+`scripts/ado-script/` and emitted to `scripts/ado-script/dist/gate/index.js`
+by the release workflow's build step. It ships inside the `ado-script.zip`
+release asset alongside any future bundled helpers. The download URL is
+deterministic based on the ado-aw version:
+`https://github.com/githubnext/ado-aw/releases/download/v{VERSION}/ado-script.zip`
 
 A `checksums.txt` file is also published at the same URL base and used to
-verify the SHA256 integrity of `scripts.zip` before extraction.
+verify the SHA256 integrity of `ado-script.zip` before extraction.
 
 ## Adding New Filter Types
 
@@ -423,8 +421,9 @@ step-by-step guide. In summary:
    `ado_exports()`, `dependencies()`, `failure_policy()`)
 2. Add a `Predicate` variant if a new test shape is needed
 3. Add a `PredicateSpec` variant for serialization
-4. Add an evaluator handler in `scripts/gate-eval.py` for the new predicate
-   type
+4. Add an evaluator handler in `scripts/ado-script/src/gate/predicates.ts`
+   for the new predicate type, and add corresponding tests in
+   `scripts/ado-script/src/gate/__tests__/`
 5. Extend the lowering function (`lower_pr_filters` or
    `lower_pipeline_filters`)
 6. Add validation rules if the new filter can conflict with existing ones