@intentius/chant-lexicon-github 0.101.0 → 0.104.0

package/src/composites/node-ci.ts

@@ -1,5 +1,6 @@
 import { Composite, mergeDefaults } from "@intentius/chant";
 import { Job, Step, Workflow } from "../generated/index";
+import { actionRef } from "../action-pins";
 
 export interface NodeCIProps {
   nodeVersion?: string;
@@ -28,12 +29,12 @@ export const NodeCI = Composite((props: NodeCIProps) => {
 
   const checkoutStep = new Step({
     name: "Checkout",
-    uses: "actions/checkout@v4",
+    uses: actionRef("actions/checkout"),
   });
 
   const setupNodeStep = new Step({
     name: "Setup Node.js",
-    uses: "actions/setup-node@v4",
+    uses: actionRef("actions/setup-node"),
     with: {
       "node-version": nodeVersion,
       cache: packageManager === "bun" ? undefined : packageManager,

package/src/composites/node-pipeline.ts

@@ -1,5 +1,6 @@
 import { Composite, withDefaults, mergeDefaults } from "@intentius/chant";
 import { Job, Step, Workflow } from "../generated/index";
+import { actionRef } from "../action-pins";
 
 export interface NodePipelineProps {
   /** Node.js version. Default: "22" */
@@ -32,19 +33,19 @@ const cacheConfig = {
     cache: "npm",
     installCmd: "npm ci",
     runPrefix: "npm run",
-    setupAction: "actions/setup-node@v4",
+    setupAction: actionRef("actions/setup-node"),
   },
   pnpm: {
     cache: "pnpm",
     installCmd: "pnpm install --frozen-lockfile",
     runPrefix: "pnpm run",
-    setupAction: "actions/setup-node@v4",
+    setupAction: actionRef("actions/setup-node"),
   },
   yarn: {
     cache: "yarn",
     installCmd: "yarn install --frozen-lockfile",
     runPrefix: "yarn",
-    setupAction: "actions/setup-node@v4",
+    setupAction: actionRef("actions/setup-node"),
   },
   bun: {
     cache: undefined,
@@ -75,13 +76,13 @@ export const NodePipeline = Composite((props: NodePipelineProps) => {
   const isBun = packageManager === "bun";
 
   // ── Build job steps ────────────────────────────────────────────────
-  const buildCheckout = new Step({ name: "Checkout", uses: "actions/checkout@v4" });
+  const buildCheckout = new Step({ name: "Checkout", uses: actionRef("actions/checkout") });
 
   const buildSetup = isBun
     ? new Step({ name: "Setup Bun", uses: "oven-sh/setup-bun@v2" })
     : new Step({
         name: "Setup Node.js",
-        uses: "actions/setup-node@v4",
+        uses: actionRef("actions/setup-node"),
         with: { "node-version": nodeVersion, cache: pm.cache },
       });
 
@@ -105,13 +106,13 @@ export const NodePipeline = Composite((props: NodePipelineProps) => {
   }, defaults?.buildJob));
 
   // ── Test job steps ─────────────────────────────────────────────────
-  const testCheckout = new Step({ name: "Checkout", uses: "actions/checkout@v4" });
+  const testCheckout = new Step({ name: "Checkout", uses: actionRef("actions/checkout") });
 
   const testSetup = isBun
     ? new Step({ name: "Setup Bun", uses: "oven-sh/setup-bun@v2" })
     : new Step({
         name: "Setup Node.js",
-        uses: "actions/setup-node@v4",
+        uses: actionRef("actions/setup-node"),
         with: { "node-version": nodeVersion, cache: pm.cache },
       });
 

package/src/composites/python-ci.ts

@@ -1,5 +1,6 @@
 import { Composite, mergeDefaults } from "@intentius/chant";
 import { Job, Step, Workflow } from "../generated/index";
+import { actionRef } from "../action-pins";
 
 export interface PythonCIProps {
   /** Python version. Default: "3.12" */
@@ -46,7 +47,7 @@ export const PythonCI = Composite((props: PythonCIProps) => {
   const testJob = new Job(mergeDefaults({
     "runs-on": runsOn,
     steps: [
-      new Step({ name: "Checkout", uses: "actions/checkout@v4" }),
+      new Step({ name: "Checkout", uses: actionRef("actions/checkout") }),
       new Step({
         name: "Setup Python",
         uses: "actions/setup-python@v5",
@@ -63,7 +64,7 @@ export const PythonCI = Composite((props: PythonCIProps) => {
       ? new Job(mergeDefaults({
           "runs-on": runsOn,
           steps: [
-            new Step({ name: "Checkout", uses: "actions/checkout@v4" }),
+            new Step({ name: "Checkout", uses: actionRef("actions/checkout") }),
             new Step({
               name: "Setup Python",
               uses: "actions/setup-python@v5",

package/src/composites/setup-node.ts

@@ -1,11 +1,18 @@
 import { Composite, mergeDefaults } from "@intentius/chant";
 import { Step } from "../generated/index";
+import { actionRef, type ActionPinMode } from "../action-pins";
 
 export interface SetupNodeProps {
   nodeVersion?: string;
   registryUrl?: string;
   cache?: string;
   cacheFilePath?: string;
+  /**
+   * `"tag"` (default) emits the action's major tag. `"sha"` emits the commit
+   * SHA from the lexicon's pin table with the version as a YAML comment, which
+   * passes GHA021, GHA029 and GHA059.
+   */
+  pin?: ActionPinMode;
   defaults?: {
     step?: Partial<ConstructorParameters<typeof Step>[0]>;
   };
@@ -21,7 +28,7 @@ export const SetupNode = Composite((props: SetupNodeProps) => {
 
   const step = new Step(mergeDefaults({
     name: "Setup Node.js",
-    uses: "actions/setup-node@v4",
+    uses: actionRef("actions/setup-node", props.pin),
     ...(Object.keys(withObj).length > 0 ? { with: withObj } : {}),
   }, defaults?.step));
 

package/src/index.ts

@@ -20,6 +20,10 @@ export { GitHub, Runner } from "./variables";
 // After running `chant generate`, this re-exports all entity classes
 export * from "./generated/index";
 
+// Action versions the composites emit, and their pinned commits
+export { ACTION_PINS, actionRef, actionPin } from "./action-pins";
+export type { ActionPin, ActionPinMode, PinnedAction } from "./action-pins";
+
 // Composites
 export {
   Checkout, SetupNode, SetupGo, SetupPython,

package/src/lint/audit-catalog.ts

@@ -66,6 +66,7 @@ export const githubAuditCatalog: Record<string, RuleMeta> = {
   GHA066: auditRule("GHA066", "report-only", "guidance", "Unbounded artifact retention", "Set a retention-days sized to how long the artifact is actually needed.", { category: "efficiency" }),
   GHA067: auditRule("GHA067", "report-only", "guidance", "Unconditional heavy step with no path filter", "Scope the trigger's paths, or add an if: guard to the step.", { category: "efficiency" }),
   GHA068: auditRule("GHA068", "report-only", "guidance", "Pull-request workflow missing a concurrency group", "Add a concurrency group with cancel-in-progress: true.", { category: "efficiency" }),
+  GHA069: auditRule("GHA069", "merge-worthy", "guidance", "Job permissions block drops the workflow's id-token: write", "Add `id-token: write` to the job's `permissions:` block; keep the job block rather than removing it.", { category: "correctness" }),
 };
 
 // Prior art credits live beside the rules in ./audit-lineage.ts (see core audit/prior-art.ts).

package/src/lint/audit-lineage.ts

@@ -4,6 +4,19 @@
  * 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.
+ *
+ * GHA069 (a job-level permissions block drops the workflow's `id-token:
+ * write`, #2273) has no entry here. Checked 2026-10-02: zizmor's 41 audits
+ * (docs.zizmor.sh/audits) cover over-broad scopes (`excessive-permissions`)
+ * and undocumented ones (`undocumented-permissions`), not a scope a job
+ * block silently loses. actionlint's `permissions` check
+ * (github.com/rhysd/actionlint/blob/main/docs/checks.md#permissions)
+ * validates scope names and levels only. poutine's rules (opa/rego/rules)
+ * have `default_permissions_on_risky_events`, the GHA013 condition, and
+ * nothing about a dropped grant. octoscan's `debug-oidc-action` flags OIDC
+ * action use as a debug finding and does not read the permission blocks.
+ * Scorecard's Token-Permissions rewards narrower blocks, the opposite
+ * concern. Ship with no lineage rather than invent a credit.
  */
 import type { Lineage } from "@intentius/chant/audit/catalog";
 

package/src/lint/post-synth/fixtures/GHA069/negative-no-job-block.yml

@@ -0,0 +1,16 @@
+name: Deploy
+on:
+  push:
+    branches: [main]
+permissions:
+  id-token: write
+  contents: read
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::123456789012:role/deploy
+          aws-region: us-east-1

package/src/lint/post-synth/fixtures/GHA069/negative-no-oidc-step.yml

@@ -0,0 +1,22 @@
+name: Deploy
+on:
+  push:
+    branches: [main]
+permissions:
+  id-token: write
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm test
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::123456789012:role/deploy
+          aws-region: us-east-1

package/src/lint/post-synth/fixtures/GHA069/negative.yml

@@ -0,0 +1,21 @@
+name: Deploy
+on:
+  push:
+    branches: [main]
+permissions:
+  id-token: write
+  contents: read
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::123456789012:role/deploy
+          aws-region: us-east-1
+      - run: aws s3 sync ./dist s3://example-bucket

package/src/lint/post-synth/fixtures/GHA069/positive.yml

@@ -0,0 +1,20 @@
+name: Deploy
+on:
+  push:
+    branches: [main]
+permissions:
+  id-token: write
+  contents: read
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::123456789012:role/deploy
+          aws-region: us-east-1
+      - run: aws s3 sync ./dist s3://example-bucket

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

@@ -58,4 +58,20 @@ jobs:
     const diags = gha011.check(makeCtx(yaml));
     expect(diags).toHaveLength(0);
   });
+
+  test("flags a scalar needs: naming a missing job (#3201)", () => {
+    const yaml = `name: CI
+on: push
+jobs:
+  test:
+    needs: biuld
+    runs-on: ubuntu-latest
+    steps:
+      - name: Test
+        run: npm test
+`;
+    const diags = gha011.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain('"biuld"');
+  });
 });

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

@@ -63,4 +63,22 @@ jobs:
     const diags = gha018.check(makeCtx(yaml));
     expect(diags).toHaveLength(0);
   });
+
+  test("flags a checkout step that starts with name: (#3201)", () => {
+    const yaml = `name: CI
+on:
+  pull_request_target:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Label
+        run: echo label
+      - name: Checkout
+        uses: actions/checkout@v7
+`;
+    const diags = gha018.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].entity).toBe("build");
+  });
 });

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

@@ -59,6 +59,48 @@ jobs:
     needs: [test]
     steps:
       - run: echo deploy
+`;
+    const diags = gha019.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("detects a cycle through scalar needs: (#3201)", () => {
+    const yaml = `name: CI
+on: push
+jobs:
+  a:
+    needs: b
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo a
+  b:
+    needs: a
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo b
+`;
+    const diags = gha019.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+  });
+
+  test("no false cycle when a later job id has an underscore (#3201)", () => {
+    // The line-based extractJobs did not split on "extra_thing", so its
+    // needs: landed on shared-alb and read as shared-alb -> shared-alb.
+    // generateGithubPipeline emits this shape for a component named Extra_Thing.
+    const yaml = `name: chant-components
+on:
+  workflow_dispatch: {}
+jobs:
+  shared-alb:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+  extra_thing:
+    runs-on: ubuntu-latest
+    needs:
+      - shared-alb
+    steps:
+      - uses: actions/checkout@v7
 `;
     const diags = gha019.check(makeCtx(yaml));
     expect(diags).toHaveLength(0);

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

@@ -79,4 +79,22 @@ jobs:
     const diags = gha021.check(makeCtx(yaml));
     expect(diags).toHaveLength(0);
   });
+
+  test("flags a checkout step that starts with name: (the composite shape)", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Test
+        run: echo test
+`;
+    const diags = gha021.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain('Checkout({ pin: "sha" })');
+  });
 });

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

@@ -6,7 +6,8 @@
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
-import { getPrimaryOutput, extractJobs } from "./yaml-helpers";
+import { getPrimaryOutput, extractActionRefs, stripUsesComment } from "./yaml-helpers";
+import { pinFixHint } from "../../action-pins";
 
 export const gha021: PostSynthCheck = {
   id: "GHA021",
@@ -17,29 +18,28 @@ export const gha021: PostSynthCheck = {
 
     for (const [, output] of ctx.outputs) {
       const yaml = getPrimaryOutput(output);
-      const jobs = extractJobs(yaml);
-
-      for (const [jobName, job] of jobs) {
-        if (!job.steps) continue;
-
-        for (const step of job.steps) {
-          if (!step.uses) continue;
-
-          const match = step.uses.match(/^actions\/checkout@(.+)$/);
-          if (!match) continue;
-
-          const ref = match[1];
-          // A pinned SHA is 40 hex characters
-          if (/^[0-9a-f]{40}$/.test(ref)) continue;
-
-          diagnostics.push({
-            checkId: "GHA021",
-            severity: "warning",
-            message: `Job "${jobName}" uses actions/checkout@${ref} — pin to a full commit SHA for supply-chain security.`,
-            entity: jobName,
-            lexicon: "github",
-          });
-        }
+      // The structural parser sees every step. The line-based extractJobs
+      // only reads a step's first line, so it missed `uses:` whenever a step
+      // starts with `name:`, which is how every composite emits it.
+      for (const { job: jobName, ref: uses, level } of extractActionRefs(yaml)) {
+        if (level !== "step") continue;
+
+        // A pinned ref carries its version as a trailing comment
+        // (`actions/checkout@<sha> # v7.0.1`); only the ref is judged.
+        const match = stripUsesComment(uses).match(/^actions\/checkout@(.+)$/);
+        if (!match) continue;
+
+        const ref = match[1];
+        // A pinned SHA is 40 hex characters
+        if (/^[0-9a-f]{40}$/.test(ref)) continue;
+
+        diagnostics.push({
+          checkId: "GHA021",
+          severity: "warning",
+          message: `Job "${jobName}" uses actions/checkout@${ref} — pin to a full commit SHA for supply-chain security.${pinFixHint("actions/checkout")}`,
+          entity: jobName,
+          lexicon: "github",
+        });
       }
     }
 

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

@@ -80,4 +80,19 @@ on:
     const diags = gha022.check(makeCtx(yaml));
     expect(diags).toHaveLength(0);
   });
+
+  test("flags a job whose id has capitals or underscores (#3201)", () => {
+    const yaml = `name: CI
+on: push
+jobs:
+  Build_App:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build
+        run: npm run build
+`;
+    const diags = gha022.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].entity).toBe("Build_App");
+  });
 });

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

@@ -49,4 +49,23 @@ jobs:
     const diags = gha023.check(makeCtx(yaml));
     expect(diags).toHaveLength(0);
   });
+
+  test("flags ::set-output in a later name:-first step's block script (#3201)", () => {
+    const yaml = `name: CI
+on: push
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Version
+        run: |
+          v=$(cat VERSION)
+          echo "::set-output name=version::$v"
+`;
+    const diags = gha023.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain('step "Version"');
+  });
 });

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

@@ -14,6 +14,7 @@
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
 import { getPrimaryOutput, extractActionRefs, parseActionUses } from "./yaml-helpers";
 import { TRUSTED_ACTION_OWNERS } from "../rules/data/trusted-action-owners";
+import { pinFixHint } from "../../action-pins";
 
 const SHA_RE = /^[0-9a-f]{40}$/;
 
@@ -52,11 +53,11 @@ export const gha029: PostSynthCheck = {
 
     for (const [, output] of ctx.outputs) {
       const yaml = getPrimaryOutput(output);
-      for (const { job, ref } of findUnpinnedActions(yaml)) {
+      for (const { job, ref, slug } of findUnpinnedActions(yaml)) {
         diagnostics.push({
           checkId: "GHA029",
           severity: "warning",
-          message: `Job "${job}" uses ${ref} pinned to a tag or branch — pin to a full commit SHA for supply-chain security.`,
+          message: `Job "${job}" uses ${ref} pinned to a tag or branch — pin to a full commit SHA for supply-chain security.${pinFixHint(slug)}`,
           entity: job,
           lexicon: "github",
         });

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

@@ -61,4 +61,24 @@ jobs:
     const diags = gha038.check(makeCtx(yaml));
     expect(diags).toHaveLength(0);
   });
+
+  test("flags a checkout step that starts with name: (#3201)", () => {
+    const yaml = `name: After CI
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+jobs:
+  report:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+      - name: Report
+        run: ./report.sh
+`;
+    const diags = gha038.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].entity).toBe("report");
+  });
 });

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

@@ -21,7 +21,7 @@
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
-import { getPrimaryOutput, extractActionRefs, extractUsesComment, parseActionUses } from "./yaml-helpers";
+import { getPrimaryOutput, extractActionRefs, extractUsesComment, parseActionUses, usesLineComments } from "./yaml-helpers";
 
 const SHA_RE = /^[0-9a-f]{40}$/;
 
@@ -49,9 +49,17 @@ export function findStalePinAnnotations(yaml: string): StalePinFinding[] {
   const findings: StalePinFinding[] = [];
 
   // First pass: missing annotations.
+  // The parsed value carries no comment, so match each ref to its `uses:`
+  // line, in document order, to read the label.
+  const lines = usesLineComments(yaml);
+  const commentFor = (ref: string): string | undefined => {
+    const k = lines.findIndex((l) => l.ref === ref);
+    if (k === -1) return extractUsesComment(ref);
+    return lines.splice(k, 1)[0].comment;
+  };
   const withComment: Array<{ job: string; ref: string; slug: string; sha: string; comment: string }> = [];
   for (const { job, ref, parsed } of refs) {
-    const comment = extractUsesComment(ref);
+    const comment = commentFor(ref);
     if (!comment) {
       findings.push({ job, ref, slug: parsed.slug, sha: parsed.gitRef, kind: "missing" });
     } else {