@intentius/chant-lexicon-github 0.46.0 → 0.50.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;
+  },
+};

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

@@ -0,0 +1,144 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha060, findOverScopedTokens } from "./gha060";
+
+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,
+    },
+  };
+}
+
+describe("GHA060: over-scoped generated token", () => {
+  test("flags a minted token whose output is never referenced (unused)", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: \${{ vars.APP_ID }}
+          private-key: \${{ secrets.APP_KEY }}
+          permission-contents: write
+      - run: echo build
+`;
+    const diags = gha060.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA060");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("no other step references its output");
+    expect(diags[0].message).toContain("permission-contents");
+  });
+
+  test("flags a consumed token with no evidence of the granted write scope (no-signal)", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: \${{ vars.APP_ID }}
+          private-key: \${{ secrets.APP_KEY }}
+          permission-contents: write
+      - uses: actions/checkout@v4
+        with:
+          token: \${{ steps.app-token.outputs.token }}
+`;
+    const diags = gha060.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("no consuming step shows evidence");
+    expect(diags[0].message).toContain("permission-contents");
+  });
+
+  test("does not flag when a consuming step evidences the granted scope", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: \${{ vars.APP_ID }}
+          private-key: \${{ secrets.APP_KEY }}
+          permission-contents: write
+      - uses: actions/checkout@v4
+        with:
+          token: \${{ steps.app-token.outputs.token }}
+      - run: |
+          git push origin main
+`;
+    expect(findOverScopedTokens(yaml)).toHaveLength(0);
+  });
+
+  test("does not flag read-only permission scopes", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - id: app-token
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: \${{ vars.APP_ID }}
+          private-key: \${{ secrets.APP_KEY }}
+          permission-contents: read
+      - run: echo build
+`;
+    expect(findOverScopedTokens(yaml)).toHaveLength(0);
+  });
+
+  test("does not flag steps unrelated to a token-minting action", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm test
+`;
+    expect(findOverScopedTokens(yaml)).toHaveLength(0);
+  });
+
+  test("recognizes the alternate app-token action slugs", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - id: app-token
+        uses: tibdex/github-app-token@v2
+        with:
+          app_id: \${{ vars.APP_ID }}
+          permission-issues: write
+      - run: echo build
+`;
+    const found = findOverScopedTokens(yaml);
+    expect(found).toHaveLength(1);
+    expect(found[0].scopes).toEqual(["issues"]);
+    expect(found[0].reason).toBe("unused");
+  });
+});

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

@@ -0,0 +1,146 @@
+/**
+ * GHA060: Over-Scoped Generated Token
+ *
+ * Flags a GitHub App installation token minted with a `permission-<scope>:
+ * write`/`admin` input broader than what the job's consuming steps evidence.
+ * Targets the well-known GitHub App token actions (`actions/create-github-app-
+ * token`, `tibdex/github-app-token`, `getsentry/action-github-app-token`),
+ * which take `permission-<resource>: read|write|admin` inputs and hand back
+ * the minted token as a step output.
+ *
+ * Two ways a generated token is over-scoped:
+ *  1. Unused — the token's output (`steps.<id>.outputs.token`) is never
+ *     referenced by any other step in the job, so every write/admin scope
+ *     granted is pure waste.
+ *  2. No signal — the token IS consumed, but no other step in the job shows
+ *     any evidence (a `gh`/`git` invocation, an API path, a keyword) of
+ *     exercising a scope granted `write`/`admin`.
+ *
+ * "No signal" is a heuristic, not a proof — a step could exercise a scope
+ * through machinery this doesn't recognize (a custom script calling `octokit`
+ * directly, say). It reports `guidance`, not a `deterministic` fix, for
+ * exactly that reason: a human confirms before narrowing the grant.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractStepsByJob, parseActionUses } from "./yaml-helpers";
+
+const APP_TOKEN_SLUGS = new Set([
+  "actions/create-github-app-token",
+  "tibdex/github-app-token",
+  "getsentry/action-github-app-token",
+]);
+
+const WRITE_LEVELS = new Set(["write", "admin"]);
+
+/** Textual evidence that a step exercises a given permission scope. Not exhaustive — a fallback covers unlisted scopes. */
+const SCOPE_SIGNALS: Record<string, RegExp> = {
+  contents: /git\s+push|gh\s+release|\/(?:git\/)?contents\b/i,
+  issues: /gh\s+issue|\/issues\b/i,
+  "pull-requests": /gh\s+pr\b|\/pulls\b/i,
+  packages: /npm\s+publish|docker\s+push|\/packages\b/i,
+  administration: /\/admin\b|administration/i,
+  actions: /\/actions\/runs|gh\s+run\b/i,
+  checks: /check-runs|\bchecks\b/i,
+  deployments: /\/deployments\b/i,
+  statuses: /\/statuses\b/i,
+  workflows: /\.github\/workflows/i,
+  environments: /\/environments\b/i,
+};
+
+function scopeSignalMatches(scope: string, text: string): boolean {
+  const signal = SCOPE_SIGNALS[scope];
+  if (signal) return signal.test(text);
+  return new RegExp(scope.replace(/-/g, "[-_ ]?"), "i").test(text);
+}
+
+function stepText(step: Record<string, unknown>): string {
+  const parts: string[] = [];
+  if (typeof step.run === "string") parts.push(step.run);
+  if (step.with && typeof step.with === "object") parts.push(JSON.stringify(step.with));
+  if (step.env && typeof step.env === "object") parts.push(JSON.stringify(step.env));
+  if (typeof step.uses === "string") parts.push(step.uses);
+  return parts.join("\n");
+}
+
+export interface OverScopedTokenFinding {
+  job: string;
+  stepId: string;
+  scopes: string[];
+  reason: "unused" | "no-signal";
+}
+
+/** Find every generated GitHub App token whose granted write/admin scopes exceed what the job's other steps evidence. */
+export function findOverScopedTokens(yaml: string): OverScopedTokenFinding[] {
+  const findings: OverScopedTokenFinding[] = [];
+
+  for (const [job, steps] of extractStepsByJob(yaml)) {
+    steps.forEach((step, idx) => {
+      const uses = typeof step.uses === "string" ? step.uses : undefined;
+      if (!uses) return;
+      const parsed = parseActionUses(uses);
+      if (!parsed || !APP_TOKEN_SLUGS.has(parsed.slug)) return;
+
+      const withBlock = step.with && typeof step.with === "object" ? (step.with as Record<string, unknown>) : {};
+      const stepId = typeof step.id === "string" ? step.id : `#${idx}`;
+
+      const writeScopes: string[] = [];
+      for (const [key, value] of Object.entries(withBlock)) {
+        const m = /^permission-([a-z-]+)$/i.exec(key);
+        if (!m) continue;
+        if (WRITE_LEVELS.has(String(value).toLowerCase())) writeScopes.push(m[1]);
+      }
+      if (writeScopes.length === 0) return;
+
+      // Evidence comes only from OTHER steps — the minting step's own `with:`
+      // block names the scopes being granted, so it can't also count as
+      // evidence they're used.
+      const otherStepsText = steps
+        .filter((_, i) => i !== idx)
+        .map(stepText)
+        .join("\n");
+
+      const outputRef = `steps.${stepId}.outputs.token`;
+      if (!otherStepsText.includes(outputRef)) {
+        findings.push({ job, stepId, scopes: writeScopes, reason: "unused" });
+        return;
+      }
+
+      const unsignaled = writeScopes.filter((scope) => !scopeSignalMatches(scope, otherStepsText));
+      if (unsignaled.length > 0) {
+        findings.push({ job, stepId, scopes: unsignaled, reason: "no-signal" });
+      }
+    });
+  }
+
+  return findings;
+}
+
+export const gha060: PostSynthCheck = {
+  id: "GHA060",
+  description: "Generated GitHub App token granted broader scope than its consuming steps evidence",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const finding of findOverScopedTokens(yaml)) {
+        const scopeList = finding.scopes.map((s) => `permission-${s}`).join(", ");
+        const message =
+          finding.reason === "unused"
+            ? `Job "${finding.job}" step "${finding.stepId}" mints a GitHub App token with ${scopeList} but no other step references its output — remove the unused scope(s) or the token step entirely.`
+            : `Job "${finding.job}" step "${finding.stepId}" mints a GitHub App token with ${scopeList}, but no consuming step shows evidence of exercising that scope — narrow the token to the scopes actually used.`;
+        diagnostics.push({
+          checkId: "GHA060",
+          severity: "warning",
+          message,
+          entity: finding.job,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,85 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha061, evaluateUsagePolicy } from "./gha061";
+
+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 YAML = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: some-rando/sketchy-action@v1
+`;
+
+describe("GHA061: usage policy enforcement (opt-in)", () => {
+  test("is silent when the wrapped check runs with no policy configured", () => {
+    expect(gha061.check(makeCtx(YAML))).toHaveLength(0);
+  });
+
+  test("evaluateUsagePolicy returns nothing for an empty/unset policy", () => {
+    expect(evaluateUsagePolicy(YAML, {})).toHaveLength(0);
+  });
+
+  test("flags a denied slug", () => {
+    const diags = evaluateUsagePolicy(YAML, { deny: ["some-rando/sketchy-action"] });
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA061");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain("some-rando/sketchy-action");
+    expect(diags[0].message).toContain("denied");
+  });
+
+  test("flags a denied owner (bare owner entry)", () => {
+    const diags = evaluateUsagePolicy(YAML, { deny: ["some-rando"] });
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("some-rando/sketchy-action");
+  });
+
+  test("flags a slug outside the allowlist", () => {
+    const diags = evaluateUsagePolicy(YAML, { allow: ["actions/*"] });
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("not in the configured action-usage allowlist");
+  });
+
+  test("does not flag a slug inside the allowlist", () => {
+    const diags = evaluateUsagePolicy(YAML, { allow: ["actions/*", "some-rando/*"] });
+    expect(diags).toHaveLength(0);
+  });
+
+  test("deny wins over allow for the same entry", () => {
+    const diags = evaluateUsagePolicy(YAML, { allow: ["actions/*", "some-rando/*"], deny: ["some-rando/sketchy-action"] });
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe("error");
+  });
+
+  test("skips local and docker references regardless of policy", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: ./.github/actions/local
+      - uses: docker://alpine@sha256:abc
+`;
+    expect(evaluateUsagePolicy(yaml, { allow: ["actions/*"] })).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/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/src/lint/post-synth/gha062.test.ts

@@ -0,0 +1,88 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha062, checkAdvisories } from "./gha062";
+
+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 = "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b";
+
+const YAML = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@${SHA}
+      - uses: actions/checkout@v4
+`;
+
+describe("GHA062: advisory cross-reference (feed-driven, graceful degrade)", () => {
+  test("is silent when the wrapped check runs with no feed present", () => {
+    expect(gha062.check(makeCtx(YAML))).toHaveLength(0);
+  });
+
+  test("checkAdvisories degrades to no findings when the feed argument is omitted", () => {
+    expect(checkAdvisories(YAML)).toHaveLength(0);
+  });
+
+  test("checkAdvisories degrades to no findings for an explicitly empty feed", () => {
+    expect(checkAdvisories(YAML, { entries: [] })).toHaveLength(0);
+  });
+
+  test("does not throw for an undefined feed", () => {
+    expect(() => checkAdvisories(YAML, undefined)).not.toThrow();
+  });
+
+  test("flags a SHA-pinned ref matching a feed entry", () => {
+    const diags = checkAdvisories(YAML, {
+      entries: [{ slug: "actions/setup-node", shas: [SHA], id: "GHSA-xxxx-yyyy-zzzz", summary: "Arbitrary code execution", url: "https://example.com/advisory" }],
+    });
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA062");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain("GHSA-xxxx-yyyy-zzzz");
+    expect(diags[0].message).toContain("actions/setup-node");
+  });
+
+  test("flags a tag-pinned ref matching a feed entry by ref", () => {
+    const diags = checkAdvisories(YAML, {
+      entries: [{ slug: "actions/checkout", refs: ["v4"], id: "GHSA-aaaa-bbbb-cccc", summary: "Path traversal" }],
+    });
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("actions/checkout@v4");
+  });
+
+  test("includes the patched-ref hint when the feed carries one", () => {
+    const diags = checkAdvisories(YAML, {
+      entries: [{ slug: "actions/setup-node", shas: [SHA], id: "GHSA-xxxx", summary: "Issue", patchedRef: "v4.1.0" }],
+    });
+    expect(diags[0].message).toContain("v4.1.0");
+  });
+
+  test("does not flag a reference the feed doesn't mention", () => {
+    const diags = checkAdvisories(YAML, {
+      entries: [{ slug: "some/other-action", shas: [SHA], id: "GHSA-xxxx", summary: "Unrelated" }],
+    });
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag when the SHA doesn't match the entry's affected list", () => {
+    const diags = checkAdvisories(YAML, {
+      entries: [{ slug: "actions/setup-node", shas: ["bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"], id: "GHSA-xxxx", summary: "Issue" }],
+    });
+    expect(diags).toHaveLength(0);
+  });
+});