@intentius/chant-lexicon-github 0.57.0 → 0.59.0

package/dist/components/generate-op-pipeline.d.ts

@@ -4,27 +4,50 @@
  * The Op counterpart to `./generate-pipeline.ts` (#891): that module
  * synthesizes a `workflow_dispatch`-triggered pipeline from a deploy-time
  * component graph, this one synthesizes a cron-triggered workflow per
- * stateless Op — the CI-native alternative to a Temporal `TemporalSchedule`
- * for downstream projects that don't run Temporal (`WorkflowAuditOp`,
- * `PipelineAuditOp`, `ReconcileOp`, … all accept an optional `schedule`
- * precisely for this).
+ * stateless Op. An Op's cadence is an `OpSchedule` on the Op itself
+ * (`packages/core/src/op/types.ts`), runtime-neutral data each reader
+ * interprets; this module is the reader that turns it into a cron a GitHub
+ * runner fires (`WorkflowAuditOp`, `PipelineAuditOp`, `ReconcileOp`, … all
+ * accept an optional `schedule` precisely for this).
  *
  * GitHub Actions' `on.schedule` is workflow-scoped, not job-scoped, so unlike
  * the component generator (one combined pipeline for the whole graph) this
  * emits one workflow file per `ScheduledOpSpec`. Each workflow:
- *  - triggers on `schedule` (the Op's cron) and `workflow_dispatch` (manual
- *    runs stay available for testing/dry-runs);
- *  - declares only the `permissions:` its `findingMode` needs — `report`
- *    stays read-only, `issue`/`pull-request` add the write scope the Op's own
- *    activity uses (`gh issue create` / `gh pr create`, see
- *    `@intentius/chant-lexicon-temporal`'s `reconcilePr` activity) — never a
- *    blanket `write-all`;
+ *  - triggers on its `ScheduledOpSpec`'s trigger (#2084): `cron` (the Op's
+ *    schedule, plus `workflow_dispatch` so manual runs stay available for
+ *    testing/dry-runs), `pull_request` (optionally filtered to `branches`,
+ *    no `workflow_dispatch` — a PR event needs no manual escape hatch), or
+ *    `push` (filtered to `branches`, defaulting to the repository's default
+ *    branch);
+ *  - declares only the `permissions:` its `findingMode` (and, for a
+ *    `pull_request` trigger, whether that mode posts a comment) needs —
+ *    `report` stays read-only, `issue`/`comment`/`pull-request` add the write
+ *    scope the Op's own activity uses (`gh issue create` / a comment on the
+ *    triggering PR / `gh pr create`, see `@intentius/chant/op`'s
+ *    `reconcilePr` activity) — never a blanket `write-all`. `comment` is the
+ *    one mode that constrains the trigger rather than only the scope: it
+ *    needs a pull request to post onto, so this generator refuses it by name
+ *    on any other trigger (#2231);
  *  - runs exactly one invocation, `chant run <name>` by default — never
  *    inlined audit/reconcile logic. The finding-mode itself is already baked
  *    into the Op's own activity args at build time by the composite that
- *    created it; this workflow only supplies the token the mode needs to act.
+ *    created it; this workflow only supplies the token the mode needs to act;
+ *  - on a `push` trigger only, runs that invocation with `--gated-exit 0`
+ *    and adds a follow-up job that says where the approval is pending
+ *    (#2243). See {@link GATED_EXIT_FLAG} and {@link gateNoticeJob}.
+ *
+ * Two per-Op options widen that shape without loosening it (#2242). A spec's
+ * `setup` list emits steps between the checkout and the `beforeScript` lines,
+ * `uses:` steps included, which is the only way a generated job can reach an
+ * action like `aws-actions/configure-aws-credentials`; {@link
+ * assertSetupSteps} refuses an unpinned or default-branch ref at build time.
+ * A spec's `permissions` map is merged over {@link permissionsFor}, adding
+ * scopes the finding-mode never grants (`id-token: write` is the whole
+ * reason) and never touching one it does; {@link mergePermissions} refuses a
+ * blanket grant, an overlap with the mode's own set, an unknown scope name,
+ * and pull-request write on a trigger that has no pull request.
  */
-import type { ComponentPipelineOptions as GenerateGithubOpOptions, OpPipelineJob, OpPipelineResult as GenerateGithubOpResult, ScheduledOpSpec } from "@intentius/chant/lexicon";
+import type { ComponentPipelineOptions as GenerateGithubOpOptions, OpPipelineJob, OpPipelineResult as GenerateGithubOpResult, OpSetupStep, OpTrigger, ScheduledOpSpec } from "@intentius/chant/lexicon";
 export type { GenerateGithubOpOptions, GenerateGithubOpResult };
 /**
  * The structured pipeline document behind one generated file, before YAML
@@ -34,7 +57,11 @@ export type { GenerateGithubOpOptions, GenerateGithubOpResult };
  * `./generate-pipeline.ts`'s `GithubPipelineDoc` split.
  */
 export interface GithubOpPipelineDoc {
-    /** The `on:` trigger mapping (`schedule` + `workflow_dispatch`). */
+    /**
+     * The `on:` trigger mapping, per {@link ScheduledOpSpec}'s trigger kind
+     * (#2084): `{ schedule, workflow_dispatch }` for cron, `{ pull_request }`
+     * for `pull_request`, `{ push }` for `push`.
+     */
     on: Record<string, unknown>;
     /** The `env:` mapping, when `options.variables` is set. */
     env?: Record<string, unknown>;
@@ -48,6 +75,15 @@ export interface GithubOpPipelineDoc {
     permissions: Record<string, unknown>;
     /** The `jobs:` mapping — one entry, this Op's trigger job. */
     jobsDoc: Record<string, unknown>;
+    /**
+     * The gated-apply notice job (#2243), when this Op's trigger is `push`.
+     * Kept out of {@link jobsDoc} so a dialect that cannot run it drops it by
+     * simply not copying it: the job shells to `gh` against the GitHub API and
+     * needs `gh` on the runner, which is the same reason the `comment` finding
+     * mode is refused on forgejo and gitlab (#2231). {@link emitOpPipelineYAML}
+     * merges it into `jobs:` for the forges that can.
+     */
+    gatedNoticeDoc?: Record<string, unknown>;
 }
 /** One generated file: a suggested name plus its pipeline document, pre-emission. */
 export interface GithubOpPipelineFile {
@@ -56,10 +92,48 @@ export interface GithubOpPipelineFile {
     doc: GithubOpPipelineDoc;
 }
 /**
- * Build one `GithubOpPipelineDoc` per scheduled Op: cron trigger,
- * least-privilege `permissions:` for its finding-mode, one job that runs
- * `chant run <name>`. Throws nothing — every `ScheduledOpSpec` is independent,
- * unlike the component generator there is no shared graph to resolve.
+ * Validate a spec's `setup` list (#2242). A `run` entry needs a non-empty
+ * line and nothing else. A `uses` entry has to be a pinned
+ * `owner/repo[/subpath]@ref`: no bare `owner/repo`, since an unpinned action
+ * resolves to its default branch, and no ref in {@link DEFAULT_BRANCH_REFS}
+ * for the same reason spelled out loud. Local (`./path`) and container
+ * (`docker://`) refs are refused too — they are legal GitHub Actions, but the
+ * generator emits a workflow into a repository it has never seen, so it
+ * cannot know a local path resolves there.
+ */
+export declare function assertSetupSteps(name: string, setup: OpSetupStep[]): void;
+/**
+ * Merge a spec's additive `permissions` over the finding-mode's own set
+ * (#2242), refusing by name anything that is not strictly additive:
+ *
+ *  - a blanket `write-all`/`read-all`, in either the key or the value
+ *    position, which is the exact thing {@link permissionsForMode} exists to
+ *    avoid;
+ *  - a scope GitHub does not define ({@link GITHUB_TOKEN_SCOPES}), because
+ *    GitHub ignores the key and the run silently gets nothing;
+ *  - a scope the mode already grants, at any value — additive means additive,
+ *    so this can neither downgrade `contents: write` to read nor restate it.
+ *    A mode whose set is wrong is fixed by changing the mode, where the
+ *    scope and the behavior that spends it stay together;
+ *  - `pull-requests: write` on a trigger with no pull request. Pull-request
+ *    access is what the finding-modes own: `pull-request` grants it together
+ *    with the `contents: write` needed to push the branch first, and
+ *    `comment` grants it on the one trigger that carries a pull request to
+ *    comment on. Adding it beside a mode that posts nothing, on a cron or
+ *    push run, grants write access no step in the generated job can spend.
+ */
+export declare function mergePermissions(name: string, base: Record<string, "read" | "write">, additive: Record<string, "read" | "write">, trigger: OpTrigger): Record<string, "read" | "write">;
+/**
+ * Build one `GithubOpPipelineDoc` per scheduled Op: its trigger, its `setup`
+ * steps, least-privilege `permissions:` for its finding-mode plus whatever
+ * the spec adds, one job that runs `chant run <name>`. Every
+ * `ScheduledOpSpec` is independent — unlike the component generator there is
+ * no shared graph to resolve — so the only thing this refuses is a spec that
+ * contradicts itself: no trigger at all (`resolveOpTrigger`), `findingMode:
+ * "comment"` on a trigger that has no pull request ({@link
+ * assertTriggerSupportsMode}), an unpinned `setup` action ({@link
+ * assertSetupSteps}), or a `permissions` entry that is not additive ({@link
+ * mergePermissions}).
  */
 export declare function buildGithubOpPipelineDocs(ops: ScheduledOpSpec[], options?: GenerateGithubOpOptions): {
     files: GithubOpPipelineFile[];

package/dist/components/generate-op-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EAEnD,aAAa,EACb,gBAAgB,IAAI,sBAAsB,EAC1C,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,qFAAqF;AACrF,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,mBAAmB,CAAC;CAC1B;AA4BD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC;IAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAAC,IAAI,EAAE,aAAa,EAAE,CAAA;CAAE,CA8C1D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAQnE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAMxB"}
+{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAIH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EAEnD,aAAa,EACb,gBAAgB,IAAI,sBAAsB,EAC1C,WAAW,EACX,SAAS,EACT,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,qFAAqF;AACrF,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,mBAAmB,CAAC;CAC1B;AAsQD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,CA8BzE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EACtC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EAC1C,OAAO,EAAE,SAAS,GACjB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAqClC;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC;IAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAAC,IAAI,EAAE,aAAa,EAAE,CAAA;CAAE,CAiF1D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAWnE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAMxB"}

package/dist/composites/pr-plan-report.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pr-plan-report.d.ts","sourceRoot":"","sources":["../../src/composites/pr-plan-report.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAqB,MAAM,oBAAoB,CAAC;AAI5D,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE;QACT,GAAG,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KACrD,CAAC;CACH;AAoBD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,YAAY;;EAkEP,CAAC"}
+{"version":3,"file":"pr-plan-report.d.ts","sourceRoot":"","sources":["../../src/composites/pr-plan-report.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAqB,MAAM,oBAAoB,CAAC;AAI5D,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE;QACT,GAAG,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KACrD,CAAC;CACH;AAyBD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,YAAY;;EAkEP,CAAC"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "6ed02140e5bbb599e6a2c400adf6b320e3ea45a57969e4d9d13969b372eb02b9",
+    "manifest.json": "3015db1776d8467a6769b316b4ffde3bbd225d53df528e97605b4b1645be3f27",
     "meta.json": "dc3977afc2b6ddc4904de906d1b1e448b786b2aced9d82f8eade2ff915203344",
     "types/index.d.ts": "f207946d7ab52f712d0c09995366440a6bba8b39358057b0da38ff9c0acca429",
     "rules/deprecated-action-version.ts": "d41e6e532ab7f623af1bee4ac5279fcb2baada7defa1c5d022a5bc71983e8797",
@@ -77,5 +77,5 @@
     "skills/chant-github-patterns.md": "bb3abef289a8fdfcf07d6bb2d7289dcb2f38bc0cb0321ea320b78b45a6f548c0",
     "skills/chant-github-security.md": "aab111cb0871cad30281ce48d7da23663689619351029219e2be019a1a61e394"
   },
-  "composite": "2eb54e808eb76cc1fc7a94ee7fd6ead00c1d25bb0f776b8a360261224b8ff8e2"
+  "composite": "17318d4ba3cbdc98681abd0d398a4e5ea0c596397464c6622c53e6f2289669e4"
 }

package/dist/lint/audit-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit-catalog.d.ts","sourceRoot":"","sources":["../../src/lint/audit-catalog.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAA4H,KAAK,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAEzL,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CA6DvD,CAAC"}
+{"version":3,"file":"audit-catalog.d.ts","sourceRoot":"","sources":["../../src/lint/audit-catalog.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAA4H,KAAK,QAAQ,EAAgB,MAAM,gCAAgC,CAAC;AAGvM,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CA6DvD,CAAC"}

package/dist/lint/audit-lineage.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Prior art for these audit rules: the open-source tools whose checks cover the
+ * same condition, credited per rule. See packages/core/src/audit/prior-art.ts for
+ * the registry, the relation vocabulary, and why this is credit rather than
+ * authority. Kept by hand; the prior-art sweep (scripts/prior-art-sweep.ts) reports
+ * when a credited tool's index no longer lists a rule cited here.
+ */
+import type { Lineage } from "@intentius/chant/audit/catalog";
+export declare const githubAuditLineage: Record<string, Lineage[]>;
+//# sourceMappingURL=audit-lineage.d.ts.map

package/dist/lint/audit-lineage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-lineage.d.ts","sourceRoot":"","sources":["../../src/lint/audit-lineage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAE9D,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAuKxD,CAAC"}

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "github",
-  "version": "0.57.0",
+  "version": "0.59.0",
   "chantVersion": ">=0.1.0",
   "namespace": "GitHub",
   "intrinsics": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.57.0",
+  "version": "0.59.0",
   "description": "GitHub Actions lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -61,7 +61,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.57.0",
+    "@intentius/chant": "^0.59.0",
     "typescript": "^5.9.3"
   }
 }

package/src/components/generate-op-pipeline.test.ts

@@ -6,7 +6,7 @@
  *     (parses back via `../yaml.ts`'s `parseYAML`) with a `schedule` +
  *     `workflow_dispatch` trigger and one job.
  *  2. `permissions:` is least-privilege per finding-mode — read-only for
- *     `report`, scoped write for `issue`/`pull-request`.
+ *     `report`, scoped write for `issue`/`comment`/`pull-request`.
  *  3. A cross-cutting generator change (extraScript/beforeScript/runCommand)
  *     is a single edit reflected in every generated file.
  */
@@ -18,6 +18,7 @@ import type { ScheduledOpSpec } from "@intentius/chant/lexicon";
 
 interface ParsedStep {
   name?: string;
+  id?: string;
   uses?: string;
   run?: string;
   env?: Record<string, string>;
@@ -26,6 +27,10 @@ interface ParsedStep {
 interface ParsedJob {
   "runs-on"?: string;
   container?: string;
+  needs?: string;
+  if?: string;
+  permissions?: Record<string, string>;
+  outputs?: Record<string, string>;
   steps: ParsedStep[];
 }
 
@@ -100,6 +105,23 @@ describe("generateGithubOpPipeline: least-privilege permissions per finding-mode
     expect(doc.permissions).toEqual({ contents: "write", "pull-requests": "write" });
   });
 
+  test("comment mode is exactly contents: read + pull-requests: write (#2231)", () => {
+    // The least-privilege set a plan-on-PR job wants, and the one no mode
+    // could produce before this one existed: `issue` adds `issues: write`,
+    // `pull-request` widens `contents` to write, `report` gets no forge write
+    // scope at all. `toEqual` is what makes this an exact set rather than a
+    // containment check.
+    const result = generateGithubOpPipeline([
+      { name: "app-plan", trigger: { kind: "pull_request", branches: ["main"] }, findingMode: "comment" },
+    ]);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.permissions).toEqual({ contents: "read", "pull-requests": "write" });
+
+    // The activity shells to `gh`, so the CLI's own token variable rides too.
+    const runStep = doc.jobs!["app-plan"].steps.find((s) => typeof s.run === "string")!;
+    expect(runStep.env).toEqual({ GITHUB_TOKEN: "${{ github.token }}", GH_TOKEN: "${{ github.token }}" });
+  });
+
   test("defaults to report (read-only) when findingMode is omitted", () => {
     const result = generateGithubOpPipeline([{ name: "actions-audit", schedule: "0 6 * * *" }]);
     expect(result.jobs[0].findingMode).toBe("report");
@@ -108,6 +130,102 @@ describe("generateGithubOpPipeline: least-privilege permissions per finding-mode
   });
 });
 
+describe("generateGithubOpPipeline: trigger kinds (#2084)", () => {
+  test("a legacy `{ schedule }` spec with no `trigger` is unchanged", () => {
+    const specs: ScheduledOpSpec[] = [{ name: "actions-audit", schedule: "0 6 * * *", findingMode: "issue" }];
+    const result = generateGithubOpPipeline(specs);
+    const doc = parseFile(result.files[0].yaml);
+
+    expect(doc.on).toEqual({ schedule: [{ cron: "0 6 * * *" }], workflow_dispatch: {} });
+    expect(doc.permissions).toEqual({ contents: "read", issues: "write" });
+    expect(result.jobs[0].trigger).toEqual({ kind: "cron", schedule: "0 6 * * *" });
+  });
+
+  test("pull_request trigger: filters to branches, has no workflow_dispatch", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "tf-plan", trigger: { kind: "pull_request", branches: ["main"] } },
+    ];
+    const result = generateGithubOpPipeline(specs);
+    const doc = parseFile(result.files[0].yaml);
+
+    expect(doc.on).toEqual({ pull_request: { branches: ["main"] } });
+    expect(doc.on).not.toHaveProperty("workflow_dispatch");
+    expect(result.jobs[0].trigger).toEqual({ kind: "pull_request", branches: ["main"] });
+  });
+
+  test("pull_request trigger with no branches filter triggers on every PR", () => {
+    const result = generateGithubOpPipeline([{ name: "tf-plan", trigger: { kind: "pull_request" } }]);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.on).toEqual({ pull_request: {} });
+  });
+
+  test("pull_request trigger with a comment-posting finding mode gets pull-requests: write", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "tf-plan", trigger: { kind: "pull_request" }, findingMode: "issue" },
+    ];
+    const result = generateGithubOpPipeline(specs);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.permissions).toEqual({ contents: "read", issues: "write", "pull-requests": "write" });
+  });
+
+  test("pull_request trigger stays read-only when findingMode is report", () => {
+    const result = generateGithubOpPipeline([{ name: "tf-plan", trigger: { kind: "pull_request" } }]);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.permissions).toEqual({ contents: "read" });
+  });
+
+  test("comment mode is refused by name on a cron trigger (#2231)", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "app-plan", schedule: "0 6 * * *", findingMode: "comment" },
+    ];
+    expect(() => generateGithubOpPipeline(specs)).toThrow(
+      /findingMode "comment".*trigger is "cron".*no pull request/s,
+    );
+  });
+
+  test("comment mode is refused by name on a push trigger (#2231)", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "app-apply", trigger: { kind: "push", branches: ["main"] }, findingMode: "comment" },
+    ];
+    expect(() => generateGithubOpPipeline(specs)).toThrow(
+      /Scheduled Op "app-apply".*findingMode "comment".*trigger is "push"/s,
+    );
+  });
+
+  test("push trigger: filters to branches", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "tf-apply", trigger: { kind: "push", branches: ["release"] } },
+    ];
+    const result = generateGithubOpPipeline(specs);
+    const doc = parseFile(result.files[0].yaml);
+
+    expect(doc.on).toEqual({ push: { branches: ["release"] } });
+    expect(doc.on).not.toHaveProperty("workflow_dispatch");
+    expect(result.jobs[0].trigger).toEqual({ kind: "push", branches: ["release"] });
+  });
+
+  test("push trigger defaults to the repository default branch (main) when branches is omitted", () => {
+    const result = generateGithubOpPipeline([{ name: "tf-apply", trigger: { kind: "push" } }]);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.on).toEqual({ push: { branches: ["main"] } });
+  });
+
+  test("push trigger is read-only by default", () => {
+    const result = generateGithubOpPipeline([{ name: "tf-apply", trigger: { kind: "push" } }]);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.permissions).toEqual({ contents: "read" });
+  });
+
+  test("push trigger honors an elevated findingMode, same as cron", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "tf-apply", trigger: { kind: "push" }, findingMode: "pull-request" },
+    ];
+    const result = generateGithubOpPipeline(specs);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.permissions).toEqual({ contents: "write", "pull-requests": "write" });
+  });
+});
+
 describe("generateGithubOpPipeline: concurrency guards against overlapping runs", () => {
   test("each file's concurrency group is scoped to its own job", () => {
     const result = generateGithubOpPipeline([{ name: "actions-audit", schedule: "0 6 * * *" }]);
@@ -123,7 +241,7 @@ describe("generateGithubOpPipeline: a cross-cutting change is one generator edit
       { name: "prod-reconcile", schedule: "0 * * * *" },
     ];
     const result = generateGithubOpPipeline(specs, {
-      runCommand: ["chant", "run", "{name}", "--temporal"],
+      runCommand: ["chant", "run", "{name}", "--json"],
       beforeScript: ["npm ci"],
       extraScript: ["echo done"],
     });
@@ -133,7 +251,7 @@ describe("generateGithubOpPipeline: a cross-cutting change is one generator edit
       const jobName = Object.keys(doc.jobs!)[0];
       const runLines = doc.jobs![jobName].steps.filter((s) => typeof s.run === "string").map((s) => s.run as string);
       expect(runLines[0]).toBe("npm ci");
-      expect(runLines[1]).toContain("--temporal");
+      expect(runLines[1]).toContain("--json");
       expect(runLines[2]).toBe("echo done");
     }
   });
@@ -144,3 +262,256 @@ describe("generateGithubOpPipeline: a cross-cutting change is one generator edit
     expect(result.jobs).toEqual([]);
   });
 });
+
+describe("generateGithubOpPipeline: the Op's own schedule (#2120)", () => {
+  test("an Op that declares its cadence needs no cron on the spec — opSchedule supplies it", () => {
+    const specs: ScheduledOpSpec[] = [{ name: "prod-watch", opSchedule: { cron: "*/10 * * * *", overlap: "skip" } }];
+    const result = generateGithubOpPipeline(specs);
+    const doc = parseFile(result.files[0].yaml);
+
+    expect(doc.on).toEqual({ schedule: [{ cron: "*/10 * * * *" }], workflow_dispatch: {} });
+    expect(result.jobs[0].trigger).toEqual({ kind: "cron", schedule: "*/10 * * * *" });
+  });
+
+  test("an explicit spec `schedule` still wins over the Op's own", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "prod-watch", schedule: "0 6 * * *", opSchedule: { cron: "*/10 * * * *" } },
+    ];
+    const doc = parseFile(generateGithubOpPipeline(specs).files[0].yaml);
+    expect(doc.on).toEqual({ schedule: [{ cron: "0 6 * * *" }], workflow_dispatch: {} });
+  });
+
+  test("an explicit `trigger` overrides the Op's own cadence entirely", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "tf-plan", trigger: { kind: "pull_request" }, opSchedule: { cron: "*/10 * * * *" } },
+    ];
+    const result = generateGithubOpPipeline(specs);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.on).toEqual({ pull_request: {} });
+    expect(result.jobs[0].trigger).toEqual({ kind: "pull_request" });
+  });
+
+  test("an Op with no cadence anywhere is still an error naming the Op", () => {
+    expect(() => generateGithubOpPipeline([{ name: "no-cadence" }])).toThrow(
+      /Scheduled Op "no-cadence" has neither/,
+    );
+  });
+});
+
+/**
+ * The two per-Op options from #2242: `setup` steps between the checkout and
+ * the `beforeScript` lines, and `permissions` merged additively over the
+ * finding-mode's own set. Together they are what makes an OIDC job
+ * expressible — `aws-actions/configure-aws-credentials` is a `uses:` step,
+ * and no finding-mode grants `id-token: write`.
+ */
+describe("generateGithubOpPipeline: setup steps and additive permissions (#2242)", () => {
+  const OIDC_SPEC: ScheduledOpSpec = {
+    name: "app-apply",
+    trigger: { kind: "push", branches: ["main"] },
+    setup: [
+      {
+        uses: "aws-actions/configure-aws-credentials@v6",
+        with: { "role-to-assume": "${{ vars.AWS_ROLE_ARN }}", "aws-region": "eu-west-1" },
+      },
+    ],
+    permissions: { "id-token": "write" },
+  };
+
+  test("emits the action between the checkout and the beforeScript install", () => {
+    const result = generateGithubOpPipeline([OIDC_SPEC], { beforeScript: ["install terraform"] });
+    const doc = parseFile(result.files[0].yaml);
+    const steps = doc.jobs!["app-apply"].steps;
+
+    expect(steps.slice(0, 3).map((s) => s.uses ?? s.run)).toEqual([
+      "actions/checkout@v4",
+      "aws-actions/configure-aws-credentials@v6",
+      "install terraform",
+    ]);
+    // The last step is the invocation. This spec's trigger is `push`, so it
+    // is the gated-apply script rather than a bare line (#2243); what this
+    // test owns is that the setup action lands between the checkout and the
+    // `beforeScript` install, whatever shape the invocation takes.
+    expect(steps).toHaveLength(4);
+    expect(steps[3].run).toContain("chant run app-apply");
+    expect((steps[1] as { with?: Record<string, string> }).with).toEqual({
+      "role-to-assume": "${{ vars.AWS_ROLE_ARN }}",
+      "aws-region": "eu-west-1",
+    });
+  });
+
+  test("adds id-token: write to the mode's own set without replacing it", () => {
+    const doc = parseFile(generateGithubOpPipeline([OIDC_SPEC]).files[0].yaml);
+    expect(doc.permissions).toEqual({ contents: "read", "id-token": "write" });
+  });
+
+  test("carries a setup step's own `env` and emits a `run` entry as a plain step", () => {
+    const specs: ScheduledOpSpec[] = [
+      {
+        name: "app-apply",
+        schedule: "0 6 * * *",
+        setup: [{ run: "aws sts get-caller-identity", env: { AWS_REGION: "eu-west-1" } }],
+      },
+    ];
+    const steps = parseFile(generateGithubOpPipeline(specs).files[0].yaml).jobs!["app-apply"].steps;
+    expect(steps[1]).toEqual({ run: "aws sts get-caller-identity", env: { AWS_REGION: "eu-west-1" } });
+  });
+
+  test("refuses an action pinned to its own default branch", () => {
+    expect(() =>
+      generateGithubOpPipeline([{ ...OIDC_SPEC, setup: [{ uses: "aws-actions/configure-aws-credentials@main" }] }]),
+    ).toThrow(/setup step 1 pins .* to "main", the action repository's own default branch/s);
+  });
+
+  test("refuses an action with no ref at all", () => {
+    expect(() =>
+      generateGithubOpPipeline([{ ...OIDC_SPEC, setup: [{ uses: "aws-actions/configure-aws-credentials" }] }]),
+    ).toThrow(/is not a pinned action reference/);
+  });
+
+  test("accepts a subpath ref and a commit sha", () => {
+    const specs: ScheduledOpSpec[] = [
+      {
+        name: "app-apply",
+        schedule: "0 6 * * *",
+        setup: [
+          { uses: "github/codeql-action/upload-sarif@v4" },
+          { uses: "aws-actions/configure-aws-credentials@0e613a0980cbf65ed5b322eb7a1e075d28913a83" },
+        ],
+      },
+    ];
+    const steps = parseFile(generateGithubOpPipeline(specs).files[0].yaml).jobs!["app-apply"].steps;
+    expect(steps.map((s) => s.uses).filter(Boolean)).toEqual([
+      "actions/checkout@v4",
+      "github/codeql-action/upload-sarif@v4",
+      "aws-actions/configure-aws-credentials@0e613a0980cbf65ed5b322eb7a1e075d28913a83",
+    ]);
+  });
+
+  test("refuses a blanket write-all", () => {
+    expect(() =>
+      generateGithubOpPipeline([{ ...OIDC_SPEC, permissions: { "write-all": "write" } }]),
+    ).toThrow(/a blanket grant/);
+  });
+
+  test("refuses widening a scope the finding-mode already grants", () => {
+    expect(() =>
+      generateGithubOpPipeline([
+        { name: "prod-reconcile", schedule: "0 * * * *", findingMode: "issue", permissions: { issues: "write" } },
+      ]),
+    ).toThrow(/its finding-mode already grants "issues: write"/);
+  });
+
+  test("refuses downgrading a scope the finding-mode already grants", () => {
+    expect(() =>
+      generateGithubOpPipeline([
+        {
+          name: "prod-reconcile",
+          schedule: "0 * * * *",
+          findingMode: "pull-request",
+          permissions: { contents: "read" },
+        },
+      ]),
+    ).toThrow(/its finding-mode already grants "contents: write"/);
+  });
+
+  test("refuses a scope name GitHub does not define, which it would silently ignore", () => {
+    expect(() => generateGithubOpPipeline([{ ...OIDC_SPEC, permissions: { id_token: "write" } }])).toThrow(
+      /not a GITHUB_TOKEN permission scope/,
+    );
+  });
+
+  test("refuses pull-requests: write on a trigger that has no pull request", () => {
+    expect(() =>
+      generateGithubOpPipeline([{ ...OIDC_SPEC, permissions: { "pull-requests": "write" } }]),
+    ).toThrow(/trigger is "push", which carries no pull request/);
+  });
+
+  test("allows id-token: write beside the comment mode's own pull-request scope", () => {
+    const doc = parseFile(
+      generateGithubOpPipeline([
+        {
+          name: "app-plan",
+          trigger: { kind: "pull_request", branches: ["main"] },
+          findingMode: "comment",
+          permissions: { "id-token": "write" },
+        },
+      ]).files[0].yaml,
+    );
+    expect(doc.permissions).toEqual({
+      contents: "read",
+      "pull-requests": "write",
+      "id-token": "write",
+    });
+  });
+});
+
+/**
+ * chant #2243 — a `push` job whose Op gates would otherwise be a red workflow
+ * run on every merge until someone approves. The mapping is `chant run`'s own
+ * (`--gated-exit 0`); what the generator adds is asking for it on the one
+ * trigger that needs it, and a job that says where the approval is pending.
+ */
+describe("generateGithubOpPipeline: the gated apply on push (#2243)", () => {
+  const pushSpec: ScheduledOpSpec = { name: "app-apply", trigger: { kind: "push", branches: ["main"] } };
+
+  function pushDoc(): ParsedDoc {
+    return parseFile(generateGithubOpPipeline([pushSpec]).files[0].yaml);
+  }
+
+  test("a push job runs with --gated-exit 0 and publishes what it stopped on", () => {
+    const doc = pushDoc();
+    const job = doc.jobs!["app-apply"];
+    const step = job.steps.find((s) => s.id === "chant-run");
+    expect(step?.run).toContain("chant run app-apply --gated-exit 0 --json");
+    expect(job.outputs).toEqual({
+      gated: "${{ steps.chant-run.outputs.gated }}",
+      op: "${{ steps.chant-run.outputs.op }}",
+      gate: "${{ steps.chant-run.outputs.gate }}",
+      approve: "${{ steps.chant-run.outputs.approve }}",
+    });
+  });
+
+  test("a cron watch and a pull_request plan keep the plain one-line invocation", () => {
+    for (const spec of [
+      { name: "app-watch", schedule: "0 6 * * *" },
+      { name: "app-plan", trigger: { kind: "pull_request" as const } },
+    ] satisfies ScheduledOpSpec[]) {
+      const doc = parseFile(generateGithubOpPipeline([spec]).files[0].yaml);
+      const job = doc.jobs![spec.name];
+      expect(job.steps.some((s) => s.run?.includes("--gated-exit"))).toBe(false);
+      expect(job.outputs).toBeUndefined();
+      expect(doc.jobs![`${spec.name}-gate-notice`]).toBeUndefined();
+    }
+  });
+
+  test("the notice job needs the apply, runs only on gated, and posts outside the log", () => {
+    const notice = pushDoc().jobs!["app-apply-gate-notice"];
+    expect(notice.needs).toBe("app-apply");
+    expect(notice.if).toBe("needs.app-apply.outputs.gated == 'true'");
+    // It shells to `gh`, which a hosted runner carries and the Op's own
+    // container image does not.
+    expect(notice.container).toBeUndefined();
+    const script = notice.steps[0].run ?? "";
+    expect(script).toContain('gh api "repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/pulls"');
+    expect(script).toContain('marker="<!-- chant-gate:$CHANT_OP -->"');
+    expect(script).toContain("gh issue create");
+  });
+
+  test("the notice job's permissions are its two posting paths and the lookup", () => {
+    const notice = pushDoc().jobs!["app-apply-gate-notice"];
+    expect(notice.permissions).toEqual({
+      contents: "read",
+      issues: "write",
+      "pull-requests": "write",
+    });
+    // Job-level, so the apply beside it keeps the workflow's own read-only set.
+    expect(pushDoc().permissions).toEqual({ contents: "read" });
+    expect(pushDoc().jobs!["app-apply"].permissions).toBeUndefined();
+  });
+
+  test("a failing run stays a failing job: the pipe cannot swallow its exit code", () => {
+    const step = pushDoc().jobs!["app-apply"].steps.find((s) => s.id === "chant-run");
+    expect(step?.run).toContain("set -o pipefail");
+  });
+});