@intentius/chant-lexicon-github 0.49.0 → 0.51.0

package/src/codegen/docs.ts

@@ -25,7 +25,7 @@ npm install --save-dev @intentius/chant-lexicon-github
 
 {{file:docs-snippets/src/quickstart.ts}}
 
-The lexicon provides **3 resources** (Workflow, Job, Dependabot config), **14 composites** (Checkout, SetupNode, SetupGo, SetupPython, CacheAction, UploadArtifact, DownloadArtifact, NodeCI, NodePipeline, PythonCI, DockerBuild, DeployEnvironment, GoCI, Dependabot) + **3 presets** (BunPipeline, PnpmPipeline, YarnPipeline), a typed **Expression** system with 24 GitHub and 5 Runner context variables, and **13 lint rules** + **45 post-synth checks** (including a CI/CD supply-chain security pass, GHA029–058).
+The lexicon provides **3 resources** (Workflow, Job, Dependabot config), **14 composites** (Checkout, SetupNode, SetupGo, SetupPython, CacheAction, UploadArtifact, DownloadArtifact, NodeCI, NodePipeline, PythonCI, DockerBuild, DeployEnvironment, GoCI, Dependabot) + **3 presets** (BunPipeline, PnpmPipeline, YarnPipeline), a typed **Expression** system with 24 GitHub and 5 Runner context variables, and **13 lint rules** + **49 post-synth checks** (including a CI/CD supply-chain security pass, GHA029–062).
 `;
 
 const outputFormat = `The GitHub Actions lexicon serializes resources into **\`.github/workflows/*.yml\`** YAML files.

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

@@ -0,0 +1,146 @@
+/**
+ * Tests for generate mode's scheduled Op → GitHub Actions workflow YAML
+ * synthesis (#927). Mirrors `./generate-pipeline.test.ts`'s style:
+ *
+ *  1. Each `ScheduledOpSpec` produces its own structurally valid workflow
+ *     (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`.
+ *  3. A cross-cutting generator change (extraScript/beforeScript/runCommand)
+ *     is a single edit reflected in every generated file.
+ */
+
+import { describe, test, expect } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import { generateGithubOpPipeline } from "./generate-op-pipeline";
+import type { ScheduledOpSpec } from "@intentius/chant/lexicon";
+
+interface ParsedStep {
+  name?: string;
+  uses?: string;
+  run?: string;
+  env?: Record<string, string>;
+}
+
+interface ParsedJob {
+  "runs-on"?: string;
+  container?: string;
+  steps: ParsedStep[];
+}
+
+interface ParsedDoc {
+  on?: Record<string, unknown>;
+  concurrency?: Record<string, unknown>;
+  permissions?: Record<string, string>;
+  jobs?: Record<string, ParsedJob>;
+}
+
+function parseFile(yaml: string): ParsedDoc {
+  return parseYAML(yaml) as ParsedDoc;
+}
+
+describe("generateGithubOpPipeline: one file per scheduled Op", () => {
+  test("each spec produces its own workflow with a schedule + workflow_dispatch trigger", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "actions-audit", schedule: "0 6 * * *" },
+      { name: "prod-reconcile", schedule: "0 * * * *", findingMode: "pull-request" },
+    ];
+    const result = generateGithubOpPipeline(specs);
+
+    expect(result.files).toHaveLength(2);
+    expect(result.files.map((f) => f.name)).toEqual(["actions-audit.yml", "prod-reconcile.yml"]);
+
+    const auditDoc = parseFile(result.files[0].yaml);
+    expect(auditDoc.on).toEqual({ schedule: [{ cron: "0 6 * * *" }], workflow_dispatch: {} });
+
+    const reconcileDoc = parseFile(result.files[1].yaml);
+    expect(reconcileDoc.on).toEqual({ schedule: [{ cron: "0 * * * *" }], workflow_dispatch: {} });
+  });
+
+  test("each file's single job runs `chant run <name>` and starts with a checkout step", () => {
+    const result = generateGithubOpPipeline([{ name: "actions-audit", schedule: "0 6 * * *" }]);
+    const doc = parseFile(result.files[0].yaml);
+    const job = doc.jobs!["actions-audit"];
+
+    expect(job["runs-on"]).toBe("ubuntu-latest");
+    expect(job.steps[0].uses).toBe("actions/checkout@v4");
+    const runStep = job.steps.find((s) => typeof s.run === "string")!;
+    expect(runStep.run).toBe("chant run actions-audit");
+  });
+
+  test("an op-name job id is normalized the same way the component generator does", () => {
+    const result = generateGithubOpPipeline([{ name: "cost-observe", schedule: "0 0 * * *" }]);
+    expect(result.jobs[0].jobName).toBe("cost-observe");
+  });
+});
+
+describe("generateGithubOpPipeline: least-privilege permissions per finding-mode", () => {
+  test("report needs no write access", () => {
+    const result = generateGithubOpPipeline([{ name: "actions-audit", schedule: "0 6 * * *", findingMode: "report" }]);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.permissions).toEqual({ contents: "read" });
+
+    const runStep = doc.jobs!["actions-audit"].steps.find((s) => typeof s.run === "string")!;
+    expect(runStep.env).toEqual({ GITHUB_TOKEN: "${{ github.token }}" });
+  });
+
+  test("issue mode adds issues: write and the gh CLI token", () => {
+    const result = generateGithubOpPipeline([{ name: "actions-audit", schedule: "0 6 * * *", findingMode: "issue" }]);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.permissions).toEqual({ contents: "read", issues: "write" });
+
+    const runStep = doc.jobs!["actions-audit"].steps.find((s) => typeof s.run === "string")!;
+    expect(runStep.env).toEqual({ GITHUB_TOKEN: "${{ github.token }}", GH_TOKEN: "${{ github.token }}" });
+  });
+
+  test("pull-request mode grants contents + pull-requests write, not issues", () => {
+    const result = generateGithubOpPipeline([{ name: "prod-reconcile", schedule: "0 * * * *", findingMode: "pull-request" }]);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.permissions).toEqual({ contents: "write", "pull-requests": "write" });
+  });
+
+  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");
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.permissions).toEqual({ contents: "read" });
+  });
+});
+
+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 * * *" }]);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.concurrency).toEqual({ group: "actions-audit", "cancel-in-progress": false });
+  });
+});
+
+describe("generateGithubOpPipeline: a cross-cutting change is one generator edit, not per-file", () => {
+  test("extraScript/beforeScript/runCommand apply uniformly across every generated file", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "actions-audit", schedule: "0 6 * * *" },
+      { name: "prod-reconcile", schedule: "0 * * * *" },
+    ];
+    const result = generateGithubOpPipeline(specs, {
+      runCommand: ["chant", "run", "{name}", "--temporal"],
+      beforeScript: ["npm ci"],
+      extraScript: ["echo done"],
+    });
+
+    for (const file of result.files) {
+      const doc = parseFile(file.yaml);
+      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[2]).toBe("echo done");
+    }
+  });
+
+  test("an empty Op set produces no files", () => {
+    const result = generateGithubOpPipeline([]);
+    expect(result.files).toEqual([]);
+    expect(result.jobs).toEqual([]);
+  });
+});

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

@@ -0,0 +1,183 @@
+/**
+ * Generate mode — scheduled Op → GitHub Actions workflow YAML (#927).
+ *
+ * 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).
+ *
+ * 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`;
+ *  - 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.
+ */
+
+import { emitYAML } from "@intentius/chant/yaml";
+import type {
+  ComponentPipelineOptions as GenerateGithubOpOptions,
+  OpFindingMode,
+  OpPipelineJob,
+  OpPipelineResult as GenerateGithubOpResult,
+  ScheduledOpSpec,
+} from "@intentius/chant/lexicon";
+
+export type { GenerateGithubOpOptions, GenerateGithubOpResult };
+
+/**
+ * The structured pipeline document behind one generated file, before YAML
+ * emission — exposed so a GitHub-Actions dialect (the forgejo lexicon, #969)
+ * can reuse the exact trigger/concurrency/job structure and only apply its
+ * dialect transform + emit, rather than re-deriving it. Mirrors
+ * `./generate-pipeline.ts`'s `GithubPipelineDoc` split.
+ */
+export interface GithubOpPipelineDoc {
+  /** The `on:` trigger mapping (`schedule` + `workflow_dispatch`). */
+  on: Record<string, unknown>;
+  /** The `env:` mapping, when `options.variables` is set. */
+  env?: Record<string, unknown>;
+  /** The `concurrency:` mapping — one run at a time per Op. */
+  concurrency: Record<string, unknown>;
+  /**
+   * The `permissions:` mapping for this Op's finding-mode. GitHub-only:
+   * Forgejo Actions ignores `permissions:` entirely, so the forgejo dialect
+   * drops this section rather than translating it (see ../../forgejo/src/dialect.ts).
+   */
+  permissions: Record<string, unknown>;
+  /** The `jobs:` mapping — one entry, this Op's trigger job. */
+  jobsDoc: Record<string, unknown>;
+}
+
+/** One generated file: a suggested name plus its pipeline document, pre-emission. */
+export interface GithubOpPipelineFile {
+  /** Suggested file name (`<op-name>.yml`), relative to the provider's workflow directory. */
+  name: string;
+  doc: GithubOpPipelineDoc;
+}
+
+/** GitHub Actions job ids must match `[a-zA-Z_][a-zA-Z0-9_-]*`; Op names are already kebab-case in every fixture, but normalize defensively (mirrors `./generate-pipeline.ts`'s `toJobName`). */
+function toJobName(opName: string): string {
+  return opName.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+const DEFAULT_IMAGE = "node:22-slim";
+
+/**
+ * Least-privilege `permissions:` for a scheduled Op's finding-mode. `report`
+ * needs no write access; `issue` needs only `issues: write`; `pull-request`
+ * (and `merge-request`, generated the same way when a GitLab-authored spec is
+ * targeted at github) needs `contents: write` to push the reconcile branch
+ * plus `pull-requests: write` to open the PR.
+ */
+function permissionsFor(mode: OpFindingMode): Record<string, "read" | "write"> {
+  switch (mode) {
+    case "issue":
+      return { contents: "read", issues: "write" };
+    case "pull-request":
+    case "merge-request":
+      return { contents: "write", "pull-requests": "write" };
+    case "report":
+      return { contents: "read" };
+  }
+}
+
+/**
+ * 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.
+ */
+export function buildGithubOpPipelineDocs(
+  ops: ScheduledOpSpec[],
+  options: GenerateGithubOpOptions = {},
+): { files: GithubOpPipelineFile[]; jobs: OpPipelineJob[] } {
+  const image = options.image ?? DEFAULT_IMAGE;
+  const runCommand = options.runCommand ?? ["chant", "run", "{name}"];
+  const beforeScript = options.beforeScript ?? [];
+  const extraScript = options.extraScript ?? [];
+
+  const files: GithubOpPipelineFile[] = [];
+  const jobs: OpPipelineJob[] = [];
+
+  for (const spec of ops) {
+    const findingMode = spec.findingMode ?? "report";
+    const jobName = toJobName(spec.name);
+    jobs.push({ jobName, op: spec.name, schedule: spec.schedule, findingMode });
+
+    const runParts = runCommand.map((part) => part.replace("{name}", spec.name));
+
+    // A live-resolution read (rate limits) always benefits from a token;
+    // creating an issue/PR additionally needs `gh` CLI's own token variable.
+    const stepEnv: Record<string, string> = { GITHUB_TOKEN: "${{ github.token }}" };
+    if (findingMode !== "report") stepEnv.GH_TOKEN = "${{ github.token }}";
+
+    const steps: Array<Record<string, unknown>> = [{ uses: "actions/checkout@v4" }];
+    for (const line of beforeScript) steps.push({ run: line });
+    steps.push({ run: runParts.join(" "), env: stepEnv });
+    for (const line of extraScript) steps.push({ run: line });
+
+    const doc: GithubOpPipelineDoc = {
+      on: { schedule: [{ cron: spec.schedule }], workflow_dispatch: {} },
+      ...(options.variables && Object.keys(options.variables).length > 0 ? { env: options.variables } : {}),
+      // One run at a time per Op — a slow audit must not overlap its own next
+      // scheduled trigger.
+      concurrency: { group: jobName, "cancel-in-progress": false },
+      permissions: permissionsFor(findingMode),
+      jobsDoc: {
+        [jobName]: {
+          "runs-on": "ubuntu-latest",
+          container: image,
+          steps,
+        },
+      },
+    };
+
+    files.push({ name: `${spec.name}.yml`, doc });
+  }
+
+  return { files, jobs };
+}
+
+/**
+ * Emit a `GithubOpPipelineDoc`'s `on`/`env`/`concurrency`/`permissions`/`jobs`
+ * mappings as workflow YAML. Shared with the forgejo dialect (#969), which
+ * transforms the doc first (and drops `permissions`, which it ignores).
+ */
+export function emitOpPipelineYAML(doc: GithubOpPipelineDoc): string {
+  const sections: string[] = [];
+  sections.push("on:" + emitYAML(doc.on, 1));
+  if (doc.env && Object.keys(doc.env).length > 0) sections.push("env:" + emitYAML(doc.env, 1));
+  sections.push("concurrency:" + emitYAML(doc.concurrency, 1));
+  if (Object.keys(doc.permissions).length > 0) sections.push("permissions:" + emitYAML(doc.permissions, 1));
+  sections.push("jobs:" + emitYAML(doc.jobsDoc, 1));
+  return sections.join("\n\n") + "\n";
+}
+
+/**
+ * Synthesize one `.github/workflows/*.yml` per scheduled Op. Thin wrapper
+ * over {@link buildGithubOpPipelineDocs} + {@link emitOpPipelineYAML}. Wired
+ * into core's Op generate mode via the github lexicon plugin's
+ * `generateOpPipeline` (../plugin.ts).
+ */
+export function generateGithubOpPipeline(
+  ops: ScheduledOpSpec[],
+  options: GenerateGithubOpOptions = {},
+): GenerateGithubOpResult {
+  const { files, jobs } = buildGithubOpPipelineDocs(ops, options);
+  return {
+    files: files.map((f) => ({ name: f.name, yaml: emitOpPipelineYAML(f.doc) })),
+    jobs,
+  };
+}

package/src/generated/index.d.ts

@@ -100,6 +100,7 @@ export declare class Permissions {
     checks?: "read" | "write" | "none";
     "code-quality"?: "read" | "write" | "none";
     contents?: "read" | "write" | "none";
+    "copilot-requests"?: "write";
     deployments?: "read" | "write" | "none";
     discussions?: "read" | "write" | "none";
     "id-token"?: "read" | "write" | "none";

package/src/generated/lexicon-github.json

@@ -53,6 +53,11 @@
           "read",
           "none"
         ]
+      },
+      "copilot-requests": {
+        "enum": [
+          "write"
+        ]
       }
     }
   },

package/src/lint/audit-catalog.ts

@@ -2,7 +2,7 @@
  * The github lexicon's chant audit catalog — metadata for its post-synth rules
  * (GHA GitHub Actions rules). Contributed via githubPlugin.auditCatalog() (#687).
  */
-import { auditRule, GH_INJECTION, GH_PWN, GH_SECRETS, GH_THIRD_PARTY, GH_TOKEN, SCORECARD_PINNED, SCORECARD_TOKEN, type RuleMeta } from "@intentius/chant/audit/catalog";
+import { auditRule, GH_INJECTION, GH_PWN, GH_SECRETS, GH_THIRD_PARTY, GH_TOKEN, SCORECARD_PINNED, SCORECARD_TOKEN, SCORECARD_VULN, type RuleMeta } from "@intentius/chant/audit/catalog";
 
 export const githubAuditCatalog: Record<string, RuleMeta> = {
   GHA006: auditRule("GHA006", "report-only", "guidance", "Duplicate workflow name", "Give each workflow a unique `name:`.", { category: "correctness" }),
@@ -50,4 +50,19 @@ export const githubAuditCatalog: Record<string, RuleMeta> = {
   GHA056: auditRule("GHA056", "report-only", "guidance", "Workflow without a name", "Add a `name:` to the workflow.", { category: "best-practice" }),
   GHA057: auditRule("GHA057", "merge-worthy", "guidance", "Dependency update can execute untrusted code", "Disable the option that lets dependency updates run external code.", { authority: [GH_PWN] }),
   GHA058: auditRule("GHA058", "report-only", "guidance", "Dependency update has no cooldown window", "Add a cooldown so new releases aren't merged instantly.", { category: "best-practice" }),
+
+  // Supply-chain and token-scoping expansion (#445).
+  GHA059: auditRule("GHA059", "merge-worthy", "guidance", "Stale or missing pin annotation", "Add or correct the trailing version comment on the SHA-pinned reference so it matches the digest.", { authority: [SCORECARD_PINNED, GH_THIRD_PARTY] }),
+  GHA060: auditRule("GHA060", "merge-worthy", "guidance", "Over-scoped generated token", "Narrow the GitHub App token's permission-* inputs to the scopes its consuming steps actually use, or remove the unused ones.", { authority: [SCORECARD_TOKEN, GH_TOKEN] }),
+  GHA061: auditRule("GHA061", "merge-worthy", "guidance", "Action reference outside the configured usage policy", "Replace the reference with one from the approved allowlist, or get it added if it should be trusted.", { category: "security" }),
+  GHA062: auditRule("GHA062", "merge-worthy", "guidance", "Pinned reference matches a known-vulnerability advisory", "Bump the reference to a patched ref/commit named by the advisory.", { authority: [SCORECARD_VULN] }),
+
+  // Efficiency (#444) — waste, not a safety/correctness issue. Always
+  // report-only: none of these warrant a merge on their own.
+  GHA063: auditRule("GHA063", "report-only", "guidance", "Dependency setup action without caching enabled", "Enable the setup action's `cache:` option or add an actions/cache step.", { category: "efficiency" }),
+  GHA064: auditRule("GHA064", "report-only", "guidance", "Expensive runner without justification", "Confirm the job needs that OS, or move it to a Linux runner.", { category: "efficiency" }),
+  GHA065: auditRule("GHA065", "report-only", "guidance", "Unbounded matrix fan-out", "Trim the matrix with include/exclude, or cap it with max-parallel.", { category: "efficiency" }),
+  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" }),
 };

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

@@ -0,0 +1,147 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha059, findStalePinAnnotations } from "./gha059";
+
+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,
+    },
+  };
+}
+
+const SHA_A = "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b";
+const SHA_B = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+
+describe("GHA059: stale or missing pin annotation", () => {
+  test("flags a SHA-pinned ref with no trailing comment", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@${SHA_A}
+`;
+    const diags = gha059.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA059");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("no trailing version comment");
+  });
+
+  test("does not flag a SHA-pinned ref with a comment", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@${SHA_A} # v4.0.2
+`;
+    expect(gha059.check(makeCtx(yaml))).toHaveLength(0);
+  });
+
+  test("treats a bare '# ' with nothing after it as missing", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@${SHA_A} #
+`;
+    const diags = gha059.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("no trailing version comment");
+  });
+
+  test("flags the same commit annotated with two different labels (mismatch)", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@${SHA_A} # v4.0.2
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@${SHA_A} # v4.0.3
+`;
+    const diags = gha059.check(makeCtx(yaml));
+    expect(diags).toHaveLength(2);
+    expect(diags.every((d) => d.severity === "warning")).toBe(true);
+    expect(diags.every((d) => d.message.includes("internally inconsistent"))).toBe(true);
+  });
+
+  test("flags the same label attached to two different commits (mismatch)", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@${SHA_A} # v4.0.2
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@${SHA_B} # v4.0.2
+`;
+    const diags = gha059.check(makeCtx(yaml));
+    expect(diags).toHaveLength(2);
+    expect(diags.every((d) => d.message.includes("internally inconsistent"))).toBe(true);
+  });
+
+  test("does not flag two different actions annotated independently", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@${SHA_A} # v4.0.2
+      - uses: actions/setup-go@${SHA_B} # v5.0.0
+`;
+    expect(findStalePinAnnotations(yaml)).toHaveLength(0);
+  });
+
+  test("does not flag a tag/branch-pinned ref (owned by GHA029)", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@v4
+`;
+    expect(findStalePinAnnotations(yaml)).toHaveLength(0);
+  });
+
+  test("does not flag local or docker references", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: ./.github/actions/local
+      - uses: docker://alpine@sha256:abc
+`;
+    expect(findStalePinAnnotations(yaml)).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,132 @@
+/**
+ * GHA059: Stale or Missing Pin Annotation
+ *
+ * A ref pinned to a commit SHA is only as trustworthy as the label a reviewer
+ * reads next to it — `uses: actions/setup-node@1a2b…9a0b # v4.0.2` lets a
+ * reviewer sanity-check the digest without resolving it themselves. This check
+ * flags two ways that label goes stale:
+ *
+ *  1. Missing — a SHA-pinned ref with no trailing version comment at all.
+ *  2. Mismatched — inferred without any network call, from internal
+ *     inconsistency in the workflow itself: the same action is pinned to the
+ *     same commit SHA in one place and a *different* label in another, or the
+ *     same label is attached to two *different* commit SHAs. Either shape
+ *     proves at least one of the labels is wrong — a real digest has exactly
+ *     one correct human-readable name.
+ *
+ * Cross-referencing a label against the actual git history (to catch a lone,
+ * internally-consistent but still-wrong annotation) needs a network call and
+ * is out of scope here — see GHA062 for the feed-based advisory check, which
+ * takes the same "no network in the rule itself" stance via an injected feed.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractActionRefs, extractUsesComment, parseActionUses } from "./yaml-helpers";
+
+const SHA_RE = /^[0-9a-f]{40}$/;
+
+export interface StalePinFinding {
+  job: string;
+  ref: string;
+  slug: string;
+  sha: string;
+  kind: "missing" | "mismatched";
+  /** For "mismatched": the other label/SHA this one conflicts with. */
+  conflict?: string;
+}
+
+/**
+ * Find every SHA-pinned `uses:` with a missing or internally-inconsistent
+ * version annotation. Scoped to one workflow document — cross-file
+ * consistency isn't attempted since two independent workflows pinning the
+ * same action differently isn't evidence of drift.
+ */
+export function findStalePinAnnotations(yaml: string): StalePinFinding[] {
+  const refs = extractActionRefs(yaml)
+    .map(({ job, ref }) => ({ job, ref, parsed: parseActionUses(ref) }))
+    .filter((r): r is { job: string; ref: string; parsed: NonNullable<ReturnType<typeof parseActionUses>> } => !!r.parsed && SHA_RE.test(r.parsed.gitRef));
+
+  const findings: StalePinFinding[] = [];
+
+  // First pass: missing annotations.
+  const withComment: Array<{ job: string; ref: string; slug: string; sha: string; comment: string }> = [];
+  for (const { job, ref, parsed } of refs) {
+    const comment = extractUsesComment(ref);
+    if (!comment) {
+      findings.push({ job, ref, slug: parsed.slug, sha: parsed.gitRef, kind: "missing" });
+    } else {
+      withComment.push({ job, ref, slug: parsed.slug, sha: parsed.gitRef, comment });
+    }
+  }
+
+  // Second pass: internal mismatch. Group by slug — the same action's
+  // commit-SHA↔label mapping must be one-to-one across the whole file.
+  const bySlug = new Map<string, Array<{ job: string; ref: string; slug: string; sha: string; comment: string }>>();
+  for (const entry of withComment) {
+    const list = bySlug.get(entry.slug) ?? [];
+    list.push(entry);
+    bySlug.set(entry.slug, list);
+  }
+
+  for (const [, entries] of bySlug) {
+    const shaToComments = new Map<string, Set<string>>();
+    const commentToShas = new Map<string, Set<string>>();
+    for (const e of entries) {
+      (shaToComments.get(e.sha) ?? shaToComments.set(e.sha, new Set()).get(e.sha)!).add(e.comment);
+      (commentToShas.get(e.comment) ?? commentToShas.set(e.comment, new Set()).get(e.comment)!).add(e.sha);
+    }
+    for (const e of entries) {
+      const otherComments = [...(shaToComments.get(e.sha) ?? [])].filter((c) => c !== e.comment);
+      const otherShas = [...(commentToShas.get(e.comment) ?? [])].filter((s) => s !== e.sha);
+      if (otherComments.length > 0) {
+        findings.push({
+          job: e.job,
+          ref: e.ref,
+          slug: e.slug,
+          sha: e.sha,
+          kind: "mismatched",
+          conflict: `commit ${e.sha} is also annotated "# ${otherComments[0]}" elsewhere`,
+        });
+      } else if (otherShas.length > 0) {
+        findings.push({
+          job: e.job,
+          ref: e.ref,
+          slug: e.slug,
+          sha: e.sha,
+          kind: "mismatched",
+          conflict: `label "# ${e.comment}" is also attached to commit ${otherShas[0]} elsewhere`,
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+export const gha059: PostSynthCheck = {
+  id: "GHA059",
+  description: "SHA-pinned action reference has a missing or internally-inconsistent version annotation",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const finding of findStalePinAnnotations(yaml)) {
+        const message =
+          finding.kind === "missing"
+            ? `Job "${finding.job}" pins ${finding.ref} to a commit SHA with no trailing version comment (e.g. "# v4.0.2") — add one so reviewers can sanity-check the digest.`
+            : `Job "${finding.job}" pins ${finding.ref} whose annotation is internally inconsistent (${finding.conflict}) — one of these labels no longer matches the digest it's attached to.`;
+        diagnostics.push({
+          checkId: "GHA059",
+          severity: "warning",
+          message,
+          entity: finding.job,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};