@intentius/chant-lexicon-github 0.100.0 → 0.102.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 {

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

@@ -0,0 +1,173 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha069 } from "./gha069";
+
+const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), "fixtures", "GHA069");
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["github", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["github", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+function fixture(name: string): PostSynthContext {
+  return makeCtx(readFileSync(join(FIXTURES, `${name}.yml`), "utf-8"));
+}
+
+/** The issue's fixture with the workflow block, the job block and the step swapped in. */
+function workflow(opts: { wf?: string; job?: string; step: string }): string {
+  const wf = opts.wf ?? "permissions:\n  id-token: write\n  contents: read\n";
+  const job = opts.job === undefined ? "" : `    permissions: ${opts.job}\n`;
+  return `name: Deploy
+on:
+  push:
+${wf}jobs:
+  deploy:
+    runs-on: ubuntu-latest
+${job}    steps:
+${opts.step}`;
+}
+
+const AWS_STEP = `      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::123456789012:role/deploy
+          aws-region: us-east-1
+`;
+
+describe("GHA069: job-level permissions block drops the workflow's id-token: write", () => {
+  test("fires on the issue's fixture and names the scope, the job and the fix", () => {
+    const diags = gha069.check(fixture("positive"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA069");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].entity).toBe("deploy");
+    expect(diags[0].message).toContain("id-token: write");
+    expect(diags[0].message).toContain('Job "deploy"');
+    expect(diags[0].message).toContain("aws-actions/configure-aws-credentials");
+    expect(diags[0].message).toContain("Add `id-token: write` to job \"deploy\"'s permissions block");
+    expect(diags[0].message).toContain("rather than removing it");
+  });
+
+  test("does not fire when the job block carries the scope", () => {
+    expect(gha069.check(fixture("negative"))).toHaveLength(0);
+  });
+
+  test("does not fire when there is no job-level block", () => {
+    expect(gha069.check(fixture("negative-no-job-block"))).toHaveLength(0);
+  });
+
+  test("does not fire on a job block whose job needs no OIDC token", () => {
+    expect(gha069.check(fixture("negative-no-oidc-step"))).toHaveLength(0);
+  });
+
+  test("does not fire when the workflow block never granted id-token", () => {
+    const yaml = workflow({ wf: "permissions:\n  contents: read\n", job: "\n      contents: read\n", step: AWS_STEP });
+    expect(gha069.check(makeCtx(yaml))).toHaveLength(0);
+  });
+
+  test("does not fire when there is no workflow block at all", () => {
+    const yaml = workflow({ wf: "", job: "\n      contents: read\n", step: AWS_STEP });
+    expect(gha069.check(makeCtx(yaml))).toHaveLength(0);
+  });
+
+  test.each([
+    ["azure/login", "azure/login@v2", "client-id: abc"],
+    ["Azure/login, as usually written", "Azure/login@v2", "client-id: abc"],
+    ["google-github-actions/auth", "google-github-actions/auth@v2", "workload_identity_provider: projects/1/locations/global/workloadIdentityPools/p/providers/gh"],
+    [
+      "a full SHA pin with a version comment",
+      "aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502 # v4.0.2",
+      "role-to-assume: arn:aws:iam::123456789012:role/deploy",
+    ],
+    ["a major-only ref", "aws-actions/configure-aws-credentials@v4", "role-to-assume: arn:aws:iam::123456789012:role/deploy"],
+    ["an exact tag", "aws-actions/configure-aws-credentials@v4.0.2", "role-to-assume: arn:aws:iam::123456789012:role/deploy"],
+  ])("matches %s on the action path whatever the ref", (_label, uses, input) => {
+    const step = `      - uses: ${uses}\n        with:\n          ${input}\n`;
+    const diags = gha069.check(makeCtx(workflow({ job: "\n      contents: read\n", step })));
+    expect(diags).toHaveLength(1);
+  });
+
+  test("a job block of {} drops id-token too", () => {
+    const diags = gha069.check(makeCtx(workflow({ job: "{}", step: AWS_STEP })));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("`permissions: {}`");
+  });
+
+  test("a job block of read-all drops id-token too", () => {
+    const diags = gha069.check(makeCtx(workflow({ job: "read-all", step: AWS_STEP })));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("`permissions: read-all`");
+  });
+
+  test("a job block of write-all grants id-token, so it does not fire", () => {
+    expect(gha069.check(makeCtx(workflow({ job: "write-all", step: AWS_STEP })))).toHaveLength(0);
+  });
+
+  test("a workflow block of write-all grants id-token, so a narrower job block drops it", () => {
+    const yaml = workflow({ wf: "permissions: write-all\n", job: "\n      contents: read\n", step: AWS_STEP });
+    expect(gha069.check(makeCtx(yaml))).toHaveLength(1);
+  });
+
+  test("a workflow block of read-all never granted id-token, so it does not fire", () => {
+    const yaml = workflow({ wf: "permissions: read-all\n", job: "\n      contents: read\n", step: AWS_STEP });
+    expect(gha069.check(makeCtx(yaml))).toHaveLength(0);
+  });
+
+  test("a job block setting id-token: none still drops it", () => {
+    const diags = gha069.check(makeCtx(workflow({ job: "\n      id-token: none\n", step: AWS_STEP })));
+    expect(diags).toHaveLength(1);
+  });
+
+  test.each([
+    ["aws-actions/configure-aws-credentials@v4", "aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}"],
+    ["azure/login@v2", "creds: ${{ secrets.AZURE_CREDENTIALS }}"],
+    ["google-github-actions/auth@v2", "credentials_json: ${{ secrets.GCP_SA_KEY }}"],
+  ])("does not fire when %s is given a static credential", (uses, input) => {
+    const step = `      - uses: ${uses}\n        with:\n          ${input}\n`;
+    expect(gha069.check(makeCtx(workflow({ job: "\n      contents: read\n", step })))).toHaveLength(0);
+  });
+
+  test("reports each affected job once, and only those", () => {
+    const yaml = `name: Deploy
+on: push
+permissions:
+  id-token: write
+jobs:
+  staging:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::123456789012:role/staging
+      - uses: google-github-actions/auth@v2
+        with:
+          workload_identity_provider: projects/1/locations/global/workloadIdentityPools/p/providers/gh
+  prod:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: aws-actions/configure-aws-credentials@v4
+        with:
+          role-to-assume: arn:aws:iam::123456789012:role/prod
+`;
+    const diags = gha069.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].entity).toBe("staging");
+    expect(diags[0].message).toContain("aws-actions/configure-aws-credentials, google-github-actions/auth");
+  });
+});

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

@@ -0,0 +1,111 @@
+/**
+ * GHA069: Job-Level Permissions Block Drops the Workflow's `id-token: write`
+ *
+ * A job-level `permissions:` block replaces the workflow-level one; GitHub
+ * does not merge the two. A workflow that grants `id-token: write` at the top
+ * and then gives a job its own block without that scope leaves the job with
+ * no OIDC token, and the job's cloud-credential action fails with an error
+ * that names neither the scope nor the job block (#2273).
+ *
+ * Fires when all three hold:
+ * - the workflow-level block grants `id-token: write` (directly, or through
+ *   `write-all`);
+ * - a job declares its own block that does not (a map without
+ *   `id-token: write`, `{}`, `read-all`, or any other preset but `write-all`);
+ * - that job has a step using a known OIDC credential action, matched on the
+ *   action path whatever the ref (tag, major or full SHA), with no static
+ *   credential input that would make the step skip OIDC.
+ *
+ * Only `id-token` is checked. The reasoning for not generalising to every
+ * scope a job block narrows is recorded on #2273.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import {
+  getPrimaryOutput,
+  extractWorkflowPermissions,
+  extractJobPermissions,
+  extractStepsByJob,
+  parseActionUses,
+  type PermissionsValue,
+} from "./yaml-helpers";
+
+/**
+ * Actions that exchange the job's OIDC token for cloud credentials, keyed by
+ * lowercased `owner/repo`, each with the inputs that select a static
+ * credential instead (when one is set, the step does not need `id-token`).
+ */
+export const OIDC_CREDENTIAL_ACTIONS: ReadonlyMap<string, readonly string[]> = new Map([
+  ["aws-actions/configure-aws-credentials", ["aws-access-key-id", "web-identity-token-file"]],
+  ["azure/login", ["creds"]],
+  ["google-github-actions/auth", ["credentials_json"]],
+]);
+
+/** True when the permissions value grants `id-token: write`. */
+export function grantsIdTokenWrite(perms: PermissionsValue): boolean {
+  if (typeof perms === "string") return perms.trim() === "write-all";
+  return perms["id-token"] === "write";
+}
+
+/** The OIDC credential action a step uses, as written, or undefined. */
+function oidcActionOf(step: Record<string, unknown>): string | undefined {
+  if (typeof step.uses !== "string") return undefined;
+  const parsed = parseActionUses(step.uses);
+  if (!parsed) return undefined;
+  const staticInputs = OIDC_CREDENTIAL_ACTIONS.get(parsed.slug.toLowerCase());
+  if (!staticInputs) return undefined;
+  const withInputs = step.with;
+  if (withInputs && typeof withInputs === "object" && !Array.isArray(withInputs)) {
+    const inputs = withInputs as Record<string, unknown>;
+    if (staticInputs.some((k) => inputs[k] !== undefined && inputs[k] !== null && inputs[k] !== "")) return undefined;
+  }
+  return parsed.slug;
+}
+
+function describeJobBlock(perms: PermissionsValue): string {
+  if (typeof perms === "string") return `\`permissions: ${perms}\``;
+  if (Object.keys(perms).length === 0) return "`permissions: {}`";
+  return "its own `permissions:` block";
+}
+
+export const gha069: PostSynthCheck = {
+  id: "GHA069",
+  description: "Job-level permissions block drops the workflow's id-token: write that an OIDC credential step needs",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+
+      const wf = extractWorkflowPermissions(yaml);
+      if (!wf || !grantsIdTokenWrite(wf)) continue;
+
+      const jobPermissions = extractJobPermissions(yaml);
+      if (jobPermissions.size === 0) continue;
+
+      const stepsByJob = extractStepsByJob(yaml);
+      for (const [job, perms] of jobPermissions) {
+        if (grantsIdTokenWrite(perms)) continue;
+
+        const actions = [
+          ...new Set((stepsByJob.get(job) ?? []).map(oidcActionOf).filter((a): a is string => a !== undefined)),
+        ];
+        if (actions.length === 0) continue;
+
+        diagnostics.push({
+          checkId: "GHA069",
+          severity: "warning",
+          message:
+            `Job "${job}" declares ${describeJobBlock(perms)}, which replaces the workflow-level block instead of merging with it, ` +
+            `so the workflow's \`id-token: write\` does not reach the job and ${actions.join(", ")} cannot request an OIDC token. ` +
+            `Add \`id-token: write\` to job "${job}"'s permissions block; keep the job block rather than removing it.`,
+          entity: job,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -55,6 +55,7 @@ import { gha065 } from "./gha065";
 import { gha066 } from "./gha066";
 import { gha067 } from "./gha067";
 import { gha068 } from "./gha068";
+import { gha069 } from "./gha069";
 
 export const postSynthChecks: PostSynthCheck[] = [
   gha006,
@@ -112,4 +113,5 @@ export const postSynthChecks: PostSynthCheck[] = [
   gha066,
   gha067,
   gha068,
+  gha069,
 ];

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

@@ -0,0 +1,83 @@
+import { describe, test, expect } from "vitest";
+import { extractJobs, buildNeedsGraph } from "./yaml-helpers";
+
+// The shape chant's serializer emits: every step starts with `name:`, and
+// `run:` is often a block scalar. The line-based extractJobs read only the
+// first line of a job's first step, so it saw none of these steps (#3201).
+const NAME_FIRST = `name: CI
+on:
+  pull_request_target:
+    branches:
+      - main
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7 # v7.0.1
+      - name: Setup Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: "22"
+      - name: Test
+        run: |
+          npm ci
+          npm test
+  Publish_Docs:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Publish
+        run: echo publish
+  deploy:
+    needs:
+      - build
+      - Publish_Docs
+    runs-on: ubuntu-latest
+    steps:
+      - id: go
+        name: Deploy
+        run: echo deploy
+`;
+
+describe("extractJobs (#3201)", () => {
+  test("reads every step of a job whose steps start with name:", () => {
+    const build = extractJobs(NAME_FIRST).get("build");
+    expect(build?.steps).toEqual([
+      { name: "Checkout", uses: "actions/checkout@v7", run: undefined },
+      { name: "Setup Node", uses: "actions/setup-node@v7", run: undefined },
+      { name: "Test", uses: undefined, run: "npm ci\nnpm test\n" },
+    ]);
+  });
+
+  test("reads a step whose first key is neither name, uses nor run", () => {
+    expect(extractJobs(NAME_FIRST).get("deploy")?.steps).toEqual([
+      { name: "Deploy", uses: undefined, run: "echo deploy" },
+    ]);
+  });
+
+  test("reads job ids with capitals and underscores", () => {
+    expect([...extractJobs(NAME_FIRST).keys()]).toEqual(["build", "Publish_Docs", "deploy"]);
+  });
+
+  test("reads needs as a scalar, a block list and a flow list", () => {
+    const jobs = extractJobs(NAME_FIRST);
+    expect(jobs.get("build")?.needs).toBeUndefined();
+    expect(jobs.get("Publish_Docs")?.needs).toEqual(["build"]);
+    expect(jobs.get("deploy")?.needs).toEqual(["build", "Publish_Docs"]);
+    expect(extractJobs(`jobs:\n  a:\n    needs: [x, "y"]\n    runs-on: ubuntu-latest\n`).get("a")?.needs).toEqual(["x", "y"]);
+  });
+
+  test("buildNeedsGraph sees scalar needs", () => {
+    expect(buildNeedsGraph(NAME_FIRST).get("Publish_Docs")).toEqual(["build"]);
+  });
+
+  test("a reusable-workflow job has no steps", () => {
+    const jobs = extractJobs(`jobs:\n  call:\n    uses: ./.github/workflows/x.yml\n`);
+    expect(jobs.get("call")).toEqual({ name: "call" });
+  });
+
+  test("unparseable YAML yields no jobs", () => {
+    expect(extractJobs("jobs:\n  a: [\n").size).toBe(0);
+  });
+});