@intentius/chant-lexicon-github 0.46.0 → 0.50.0

package/dist/rules/gha061.ts

@@ -0,0 +1,85 @@
+/**
+ * GHA061: Action Reference Outside the Configured Usage Policy
+ *
+ * An opt-in allow/deny check over third-party `uses:` references, for
+ * environments that constrain which external components may run at all —
+ * distinct from GHA029/031/032, which judge a reference on its own pinning/
+ * naming/health, not against an organizational decision about who is trusted.
+ *
+ * Ships silent: `DEFAULT_ACTION_USAGE_POLICY` (../rules/data/action-usage-
+ * policy.ts) is empty, and {@link evaluateUsagePolicy} returns no findings
+ * for an empty policy — see that module's doc for why (`PostSynthContext`
+ * carries no per-check runtime config channel) and how a project actually
+ * opts in: author a `lint.policies` entry that calls `evaluateUsagePolicy`
+ * with its own policy, wrapped in a `PostSynthCheck`.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractActionRefs, parseActionUses } from "./yaml-helpers";
+import { DEFAULT_ACTION_USAGE_POLICY, type ActionUsagePolicy } from "../rules/data/action-usage-policy";
+
+export type { ActionUsagePolicy } from "../rules/data/action-usage-policy";
+
+function matches(entry: string, owner: string, slug: string): boolean {
+  if (entry === slug) return true;
+  if (entry === owner) return true;
+  if (entry.endsWith("/*") && entry.slice(0, -2) === owner) return true;
+  return false;
+}
+
+function matchesAny(entries: string[] | undefined, owner: string, slug: string): boolean {
+  return (entries ?? []).some((e) => matches(e, owner, slug));
+}
+
+/**
+ * Evaluate a workflow's `uses:` references against a usage policy. Pure: no
+ * fs, no network, no default policy baked in — an empty/unset policy (no
+ * `allow` and no `deny`) always yields no findings, which is what makes this
+ * genuinely opt-in rather than "opt-in by omission of one flag."
+ */
+export function evaluateUsagePolicy(yaml: string, policy: ActionUsagePolicy): PostSynthDiagnostic[] {
+  const { allow, deny } = policy;
+  if ((!allow || allow.length === 0) && (!deny || deny.length === 0)) return [];
+
+  const diagnostics: PostSynthDiagnostic[] = [];
+  for (const { job, ref } of extractActionRefs(yaml)) {
+    const parsed = parseActionUses(ref);
+    if (!parsed) continue; // local or docker:// reference — not a registry policy carries slugs for
+
+    if (matchesAny(deny, parsed.owner, parsed.slug)) {
+      diagnostics.push({
+        checkId: "GHA061",
+        severity: "error",
+        message: `Job "${job}" uses "${parsed.slug}", which is denied by the configured action-usage policy.`,
+        entity: job,
+        lexicon: "github",
+      });
+      continue;
+    }
+
+    if (allow && allow.length > 0 && !matchesAny(allow, parsed.owner, parsed.slug)) {
+      diagnostics.push({
+        checkId: "GHA061",
+        severity: "warning",
+        message: `Job "${job}" uses "${parsed.slug}", which is not in the configured action-usage allowlist.`,
+        entity: job,
+        lexicon: "github",
+      });
+    }
+  }
+  return diagnostics;
+}
+
+export const gha061: PostSynthCheck = {
+  id: "GHA061",
+  description: "Action reference outside the configured usage policy (opt-in)",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      diagnostics.push(...evaluateUsagePolicy(yaml, DEFAULT_ACTION_USAGE_POLICY));
+    }
+    return diagnostics;
+  },
+};

package/dist/rules/gha062.ts

@@ -0,0 +1,68 @@
+/**
+ * GHA062: Pinned Reference Matches a Known-Vulnerability Advisory
+ *
+ * Cross-references every pinned `uses:` (commit SHA or tag/branch) against a
+ * caller-supplied advisory feed and flags a match. Unlike GHA031/032's
+ * vendored, committed reference lists, a vulnerability feed is meant to be
+ * refreshed continuously — so this rule takes it as data, not code: the pure
+ * core never fetches (epic #350's design spine), and an absent/empty feed
+ * degrades to "no findings," never an error or a thrown exception. That is
+ * what "unreachable" means for a rule that makes no network call of its own:
+ * whatever couldn't reach the feed already failed upstream of this function,
+ * and this function's job is to not compound that with a crash.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractActionRefs, parseActionUses } from "./yaml-helpers";
+import { DEFAULT_ADVISORY_FEED, type AdvisoryFeed, type AdvisoryEntry } from "../rules/data/advisory-feed";
+
+export type { AdvisoryFeed, AdvisoryEntry } from "../rules/data/advisory-feed";
+
+function matchesEntry(entry: AdvisoryEntry, slug: string, gitRef: string): boolean {
+  if (entry.slug !== slug) return false;
+  if (entry.shas?.includes(gitRef)) return true;
+  if (entry.refs?.includes(gitRef)) return true;
+  return false;
+}
+
+/**
+ * Check a workflow's pinned action references against an advisory feed. Pure
+ * and total: a missing/empty feed (`entries.length === 0`, including the
+ * `undefined` default) always yields `[]`, never a throw.
+ */
+export function checkAdvisories(yaml: string, feed: AdvisoryFeed | undefined = DEFAULT_ADVISORY_FEED): PostSynthDiagnostic[] {
+  if (!feed || !feed.entries || feed.entries.length === 0) return [];
+
+  const diagnostics: PostSynthDiagnostic[] = [];
+  for (const { job, ref } of extractActionRefs(yaml)) {
+    const parsed = parseActionUses(ref);
+    if (!parsed) continue;
+    for (const entry of feed.entries) {
+      if (!matchesEntry(entry, parsed.slug, parsed.gitRef)) continue;
+      const patch = entry.patchedRef ? ` A patched ref is available: ${entry.patchedRef}.` : "";
+      const link = entry.url ? ` (${entry.url})` : "";
+      diagnostics.push({
+        checkId: "GHA062",
+        severity: "error",
+        message: `Job "${job}" uses "${parsed.slug}@${parsed.gitRef}", which matches disclosed advisory ${entry.id}${link}: ${entry.summary}.${patch}`,
+        entity: job,
+        lexicon: "github",
+      });
+    }
+  }
+  return diagnostics;
+}
+
+export const gha062: PostSynthCheck = {
+  id: "GHA062",
+  description: "Pinned action reference matches a known-vulnerability advisory (feed-driven)",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      diagnostics.push(...checkAdvisories(yaml, DEFAULT_ADVISORY_FEED));
+    }
+    return diagnostics;
+  },
+};

package/dist/rules/gha063.ts

@@ -0,0 +1,60 @@
+/**
+ * GHA063: Dependency Setup Without Caching
+ *
+ * Flags a `actions/setup-{node,python,java,ruby,dotnet}` step that leaves its
+ * built-in `cache:` option unset, with no adjacent `actions/cache` step to
+ * cover the gap. Every run re-downloads the same dependencies from the
+ * registry from a cold cache — pure wasted time and bandwidth, not a
+ * correctness or security issue (efficiency, #444).
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, jobEntries, parseActionUses } from "./yaml-helpers";
+
+/** Setup actions whose `with.cache` option enables built-in dependency caching. */
+const CACHEABLE_SETUP_ACTIONS = new Set(["actions/setup-node", "actions/setup-python", "actions/setup-java", "actions/setup-ruby", "actions/setup-dotnet"]);
+
+function cacheEnabled(withBlock: unknown): boolean {
+  if (!withBlock || typeof withBlock !== "object") return false;
+  const cache = (withBlock as Record<string, unknown>).cache;
+  if (typeof cache === "boolean") return cache;
+  if (typeof cache === "string") return cache.trim().length > 0 && cache.trim() !== "false";
+  return false;
+}
+
+export const gha063: PostSynthCheck = {
+  id: "GHA063",
+  description: "Dependency setup action without caching enabled",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+
+      for (const [jobName, jobObj] of jobEntries(yaml)) {
+        const steps = Array.isArray(jobObj.steps) ? (jobObj.steps as Array<Record<string, unknown>>) : [];
+        const hasGenericCacheStep = steps.some((s) => parseActionUses(String(s.uses ?? ""))?.slug === "actions/cache");
+        if (hasGenericCacheStep) continue;
+
+        for (const step of steps) {
+          const uses = typeof step.uses === "string" ? step.uses : undefined;
+          if (!uses) continue;
+          const parsed = parseActionUses(uses);
+          if (!parsed || !CACHEABLE_SETUP_ACTIONS.has(parsed.slug)) continue;
+          if (cacheEnabled(step.with)) continue;
+
+          diagnostics.push({
+            checkId: "GHA063",
+            severity: "info",
+            message: `Job "${jobName}" uses ${parsed.slug} without enabling its \`cache:\` option, and no separate actions/cache step covers it — dependencies are re-fetched from a cold cache on every run. Set \`with.cache\` (e.g. \`cache: npm\`) or add an actions/cache step.`,
+            entity: jobName,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/gha064.ts

@@ -0,0 +1,55 @@
+/**
+ * GHA064: Expensive Runner Without Justification
+ *
+ * Flags a job hardcoded onto a pricier macOS/Windows runner (billed at a
+ * multiple of Linux minutes) when none of its `run:` steps show any sign the
+ * job actually needs that OS. A matrix-driven `runs-on: ${{ matrix.os }}`
+ * (intentional cross-platform testing) is never flagged — only a literal,
+ * hardcoded label. Efficiency (#444), not a correctness/security issue.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractRunsOnByJob, extractRunBlocks } from "./yaml-helpers";
+
+const OS_JUSTIFICATION: Array<{ prefix: string; label: string; keywords: RegExp }> = [
+  { prefix: "macos-", label: "macOS", keywords: /xcodebuild|xcode-select|\.xcodeproj|\.xcworkspace|carthage|fastlane|cocoapods|pod install|swiftpm|codesign|notarize/i },
+  { prefix: "windows-", label: "Windows", keywords: /msbuild|\.sln\b|\.ps1\b|vcvarsall|nuget\s|choco\s|Set-ItemProperty|Get-ChildItem/i },
+];
+
+export const gha064: PostSynthCheck = {
+  id: "GHA064",
+  description: "Job hardcoded onto an expensive runner with no sign it needs that OS",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const runsOnByJob = extractRunsOnByJob(yaml);
+      const runBlocks = extractRunBlocks(yaml);
+
+      for (const [jobName, labels] of runsOnByJob) {
+        if (labels.some((l) => l.includes("${{"))) continue; // matrix/expression-driven — intentional
+
+        for (const { prefix, label, keywords } of OS_JUSTIFICATION) {
+          const matched = labels.find((l) => l.toLowerCase().startsWith(prefix));
+          if (!matched) continue;
+
+          const justified = runBlocks.some((r) => r.job === jobName && keywords.test(r.run));
+          if (justified) break;
+
+          diagnostics.push({
+            checkId: "GHA064",
+            severity: "info",
+            message: `Job "${jobName}" runs on "${matched}" (a pricier ${label} runner) but no step looks ${label}-specific. Confirm it needs ${label}, or move it to a Linux runner.`,
+            entity: jobName,
+            lexicon: "github",
+          });
+          break;
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/gha065.ts

@@ -0,0 +1,129 @@
+/**
+ * GHA065: Unbounded Matrix Fan-Out
+ *
+ * Flags a `strategy.matrix` that combines two or more dimensions into more
+ * jobs than a `max-parallel:` cap bounds. Two orthogonal axes each with a
+ * handful of values multiply, not add — `os` x `node` x `arch` can produce
+ * dozens of jobs from a config that reads like a short list. Unbounded, that
+ * is capacity spent on a combination nobody asked for, not a correctness or
+ * security issue (efficiency, #444).
+ *
+ * Parses the `matrix:` block by indentation, not the structural YAML parser
+ * — a flow list of bare words (`os: [ubuntu-latest, macos-latest]`, the
+ * overwhelmingly common hand-written form) is not one it round-trips, only
+ * a flow list of numbers. Mirrors GHA009's regex-based matrix handling for
+ * the same reason.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs } from "./yaml-helpers";
+
+/** Above this many combinations, an uncapped matrix is flagged. */
+const FANOUT_THRESHOLD = 12;
+
+/** The raw text of one job's block within `jobs:`, or undefined if not found. */
+function jobSection(yaml: string, jobName: string): string | undefined {
+  const jobsIdx = yaml.search(/^jobs:\s*$/m);
+  if (jobsIdx === -1) return undefined;
+  const afterJobs = yaml.slice(jobsIdx + yaml.slice(jobsIdx).indexOf("\n") + 1);
+  const header = `  ${jobName}:\n`;
+  const start = afterJobs.indexOf(header);
+  if (start === -1) return undefined;
+  const rest = afterJobs.slice(start + header.length);
+  const nextJobMatch = rest.search(/\n {2}\S/);
+  return nextJobMatch === -1 ? rest : rest.slice(0, nextJobMatch);
+}
+
+interface MatrixInfo {
+  dims: Array<{ key: string; size: number }>;
+  maxParallel: boolean;
+}
+
+/** Parse a job section's `strategy.matrix` dimensions and whether max-parallel caps it. */
+function parseMatrix(section: string): MatrixInfo | undefined {
+  const lines = section.split("\n");
+  const matrixLineIdx = lines.findIndex((l) => /^\s*matrix:\s*$/.test(l));
+  if (matrixLineIdx === -1) return undefined;
+  const matrixIndent = lines[matrixLineIdx].search(/\S/);
+
+  const maxParallel = lines.some((l) => {
+    const m = l.match(/^(\s*)max-parallel:/);
+    return !!m && m[1].length === matrixIndent;
+  });
+
+  const dims: Array<{ key: string; size: number }> = [];
+  let i = matrixLineIdx + 1;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.trim() === "") { i++; continue; }
+    const indent = line.search(/\S/);
+    if (indent <= matrixIndent) break; // dedented out of the matrix: block
+
+    const kv = line.match(/^\s*([a-zA-Z0-9_-]+):\s*(.*)$/);
+    if (!kv) { i++; continue; }
+    const [, key, rest] = kv;
+    const value = rest.trim();
+
+    if (value.startsWith("[")) {
+      const inner = value.replace(/^\[|\]\s*$/g, "").trim();
+      dims.push({ key, size: inner === "" ? 0 : inner.split(",").length });
+      i++;
+      continue;
+    }
+    if (value !== "") {
+      dims.push({ key, size: 1 }); // a bare scalar dimension
+      i++;
+      continue;
+    }
+    // Block-list value on subsequent, deeper-indented lines.
+    let size = 0;
+    i++;
+    while (i < lines.length) {
+      const l2 = lines[i];
+      if (l2.trim() === "") { i++; continue; }
+      const ind2 = l2.search(/\S/);
+      if (ind2 <= indent) break;
+      if (/^\s*-\s/.test(l2)) size++;
+      i++;
+    }
+    dims.push({ key, size });
+  }
+
+  return { dims, maxParallel };
+}
+
+export const gha065: PostSynthCheck = {
+  id: "GHA065",
+  description: "Matrix combines dimensions into an uncapped, large fan-out",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+
+      for (const [jobName] of extractJobs(yaml)) {
+        const section = jobSection(yaml, jobName);
+        if (!section) continue;
+        const matrix = parseMatrix(section);
+        if (!matrix) continue;
+
+        const dims = matrix.dims.filter((d) => d.key !== "include" && d.key !== "exclude" && d.size > 0);
+        if (dims.length < 2) continue; // a single axis isn't "combined" fan-out
+
+        const combos = dims.reduce((a, d) => a * d.size, 1);
+        if (combos <= FANOUT_THRESHOLD || matrix.maxParallel) continue;
+
+        diagnostics.push({
+          checkId: "GHA065",
+          severity: "info",
+          message: `Job "${jobName}"'s matrix combines ${dims.length} dimensions (${dims.map((d) => d.key).join(" x ")}) into ${combos} jobs with no \`max-parallel:\` cap. Confirm the full cross-product is intended, trim it with \`include\`/\`exclude\`, or add \`max-parallel:\`.`,
+          entity: jobName,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/gha066.ts

@@ -0,0 +1,47 @@
+/**
+ * GHA066: Unbounded Artifact Retention
+ *
+ * Flags an `actions/upload-artifact` step with no `retention-days`, which
+ * falls back to the repository's default (up to 90 days). Build logs, test
+ * output, and intermediate artifacts rarely need to outlive the PR they came
+ * from; an unset retention silently accumulates storage. Efficiency (#444),
+ * not a correctness or security issue.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, jobEntries, parseActionUses } from "./yaml-helpers";
+
+export const gha066: PostSynthCheck = {
+  id: "GHA066",
+  description: "Uploaded artifact has no explicit retention-days",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+
+      for (const [jobName, jobObj] of jobEntries(yaml)) {
+        const steps = Array.isArray(jobObj.steps) ? (jobObj.steps as Array<Record<string, unknown>>) : [];
+        for (const step of steps) {
+          const uses = typeof step.uses === "string" ? step.uses : undefined;
+          if (!uses || parseActionUses(uses)?.slug !== "actions/upload-artifact") continue;
+
+          const withBlock = step.with as Record<string, unknown> | undefined;
+          if (withBlock && withBlock["retention-days"] !== undefined) continue;
+
+          const name = typeof withBlock?.name === "string" ? withBlock.name : undefined;
+          diagnostics.push({
+            checkId: "GHA066",
+            severity: "info",
+            message: `Job "${jobName}" uploads${name ? ` artifact "${name}"` : " an artifact"} with no \`retention-days\` — it falls back to the repository's default (up to 90 days). Set a \`retention-days\` sized to how long the artifact is actually needed.`,
+            entity: jobName,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/gha067.ts

@@ -0,0 +1,76 @@
+/**
+ * GHA067: Unconditional Heavy Step With No Path Filter
+ *
+ * Flags a `docker build`/`docker buildx build` step that has no `if:` guard,
+ * in a workflow that triggers on `push`/`pull_request` with no `paths:` or
+ * `paths-ignore:` filter. A docs-only or unrelated change still pays for a
+ * full image build because nothing scopes the trigger or guards the step.
+ * Efficiency (#444), not a correctness or security issue.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseDoc, jobEntries } from "./yaml-helpers";
+
+const DOCKER_BUILD_RE = /\bdocker(\s+buildx)?\s+build\b/i;
+
+function triggerObject(on: unknown, key: string): Record<string, unknown> | undefined {
+  if (!on || typeof on !== "object" || Array.isArray(on)) return undefined;
+  const trig = (on as Record<string, unknown>)[key];
+  return trig && typeof trig === "object" && !Array.isArray(trig) ? (trig as Record<string, unknown>) : undefined;
+}
+
+function hasPushOrPRTrigger(on: unknown): boolean {
+  if (typeof on === "string") return on === "push" || on === "pull_request";
+  if (Array.isArray(on)) return on.includes("push") || on.includes("pull_request");
+  if (on && typeof on === "object") {
+    const keys = Object.keys(on as Record<string, unknown>);
+    return keys.includes("push") || keys.includes("pull_request");
+  }
+  return false;
+}
+
+function hasPathFilter(on: unknown): boolean {
+  for (const key of ["push", "pull_request"]) {
+    const trig = triggerObject(on, key);
+    if (!trig) continue;
+    if (Array.isArray(trig.paths) && trig.paths.length > 0) return true;
+    if (Array.isArray(trig["paths-ignore"]) && trig["paths-ignore"].length > 0) return true;
+  }
+  return false;
+}
+
+export const gha067: PostSynthCheck = {
+  id: "GHA067",
+  description: "Unconditional docker build with no path filter or guard",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const doc = parseDoc(yaml);
+      if (!doc) continue;
+      if (!hasPushOrPRTrigger(doc.on)) continue;
+      if (hasPathFilter(doc.on)) continue;
+
+      for (const [jobName, jobObj] of jobEntries(yaml)) {
+        const steps = Array.isArray(jobObj.steps) ? (jobObj.steps as Array<Record<string, unknown>>) : [];
+        for (const step of steps) {
+          const run = typeof step.run === "string" ? step.run : undefined;
+          if (!run || !DOCKER_BUILD_RE.test(run)) continue;
+          if (step.if !== undefined) continue; // already guarded
+
+          diagnostics.push({
+            checkId: "GHA067",
+            severity: "info",
+            message: `Job "${jobName}" runs a Docker build on every push/pull_request with no \`paths:\`/\`paths-ignore:\` filter and no \`if:\` guard — unrelated changes (docs, etc.) still pay for a full image build. Scope the trigger's paths or add a guard.`,
+            entity: jobName,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/gha068.ts

@@ -0,0 +1,51 @@
+/**
+ * GHA068: Pull-Request Workflow Missing a Concurrency Group
+ *
+ * Flags a workflow triggered on `pull_request` with no top-level
+ * `concurrency:` block. Without one, a superseded push keeps its old run
+ * going instead of cancelling it, so every commit on a PR pays for the full
+ * pipeline instead of just the latest. Deploy workflows are left to GHA024,
+ * which already covers them (overlapping-deployment risk, not capacity).
+ * Efficiency (#444), not a correctness or security issue.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseDoc, extractJobs, extractWorkflowName } from "./yaml-helpers";
+
+function hasPullRequestTrigger(on: unknown): boolean {
+  if (typeof on === "string") return on === "pull_request";
+  if (Array.isArray(on)) return on.includes("pull_request");
+  if (on && typeof on === "object") return "pull_request" in (on as Record<string, unknown>);
+  return false;
+}
+
+export const gha068: PostSynthCheck = {
+  id: "GHA068",
+  description: "Pull-request workflow missing a concurrency group",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const doc = parseDoc(yaml);
+      if (!doc || !hasPullRequestTrigger(doc.on)) continue;
+
+      const workflowName = extractWorkflowName(yaml) ?? "";
+      const jobNames = [...extractJobs(yaml).keys()];
+      const isDeployWorkflow = /deploy/i.test(workflowName) || jobNames.some((n) => /deploy/i.test(n));
+      if (isDeployWorkflow) continue; // GHA024 already covers deploy workflows
+
+      if (!/^\s*concurrency:/m.test(yaml)) {
+        diagnostics.push({
+          checkId: "GHA068",
+          severity: "info",
+          message: `Workflow${workflowName ? ` "${workflowName}"` : ""} triggers on pull_request with no \`concurrency:\` group — a new push doesn't cancel the superseded run, so every commit on the PR consumes a full run's worth of runner capacity. Add a \`concurrency:\` group with \`cancel-in-progress: true\`.`,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/yaml-helpers.ts

@@ -172,7 +172,8 @@ export interface ImageRef {
   source: "container" | "service" | "step";
 }
 
-function parseDoc(yaml: string): Record<string, unknown> | undefined {
+/** Parse a workflow YAML into a structured document, tolerant of parse errors. */
+export function parseDoc(yaml: string): Record<string, unknown> | undefined {
   try {
     return parseYAML(yaml);
   } catch {
@@ -180,7 +181,8 @@ function parseDoc(yaml: string): Record<string, unknown> | undefined {
   }
 }
 
-function jobEntries(yaml: string): Array<[string, Record<string, unknown>]> {
+/** Every job in the workflow as `[name, rawJobObject]`, via the structural parser. */
+export function jobEntries(yaml: string): Array<[string, Record<string, unknown>]> {
   const doc = parseDoc(yaml);
   const jobs = doc?.jobs;
   if (!jobs || typeof jobs !== "object") return [];
@@ -193,6 +195,26 @@ function jobEntries(yaml: string): Array<[string, Record<string, unknown>]> {
   return out;
 }
 
+/**
+ * Every step object (raw, as parsed from YAML — `uses`, `with`, `id`, `run`,
+ * `env`, etc.) grouped by owning job. Unlike {@link extractJobs} (which only
+ * lifts `uses`/`run`/`name`), this hands back each step's full object so a
+ * check can read arbitrary keys (`with:` inputs, `id:`) without growing a new
+ * bespoke regex extractor per key. See GHA060.
+ */
+export function extractStepsByJob(yaml: string): Map<string, Array<Record<string, unknown>>> {
+  const out = new Map<string, Array<Record<string, unknown>>>();
+  for (const [job, jobObj] of jobEntries(yaml)) {
+    const steps = jobObj.steps;
+    if (!Array.isArray(steps)) continue;
+    out.set(
+      job,
+      steps.filter((s): s is Record<string, unknown> => !!s && typeof s === "object" && !Array.isArray(s)),
+    );
+  }
+  return out;
+}
+
 /**
  * Extract every `uses:` reference from the workflow — both step-level actions
  * and job-level reusable-workflow calls. Uses the structural YAML parser so
@@ -462,6 +484,19 @@ export function stripUsesComment(uses: string): string {
   return uses.replace(/\s+#.*$/, "").trim();
 }
 
+/**
+ * Extract a `uses:` value's trailing inline comment, if any — the
+ * human-readable version label reviewers rely on when a ref is pinned to an
+ * opaque commit SHA (e.g. `actions/setup-node@1a2b…9a0b # v4.0.2` → `v4.0.2`).
+ * Returns undefined for no comment or an empty (`# ` with nothing after it)
+ * one, since both mean "no annotation" to a reviewer. See GHA059.
+ */
+export function extractUsesComment(rawUses: string): string | undefined {
+  const m = rawUses.match(/\s+#\s*(.*)$/);
+  const comment = m?.[1]?.trim();
+  return comment ? comment : undefined;
+}
+
 export function parseActionUses(rawUses: string): { owner: string; repo: string; slug: string; gitRef: string } | undefined {
   const uses = stripUsesComment(rawUses);
   if (uses.startsWith("./") || uses.startsWith("../") || uses.startsWith("docker://")) return undefined;

package/dist/types/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.46.0",
+  "version": "0.50.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.46.0",
+    "@intentius/chant": "^0.50.0",
     "typescript": "^5.9.3"
   }
 }