@intentius/chant-lexicon-github 0.0.18 → 0.0.24

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

@@ -0,0 +1,40 @@
+/**
+ * GHA020: Missing Job-Level Permissions for Sensitive Triggers
+ *
+ * Flags jobs without explicit `permissions:` when the workflow uses
+ * `pull_request_target` or `workflow_dispatch` triggers.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs, extractTriggers } from "./yaml-helpers";
+
+export const gha020: PostSynthCheck = {
+  id: "GHA020",
+  description: "Missing job-level permissions for sensitive triggers",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const triggers = extractTriggers(yaml);
+
+      if (!triggers["pull_request_target"] && !triggers["workflow_dispatch"]) continue;
+
+      const jobs = extractJobs(yaml);
+      for (const [jobName, job] of jobs) {
+        if (!job.permissions) {
+          diagnostics.push({
+            checkId: "GHA020",
+            severity: "warning",
+            message: `Job "${jobName}" lacks explicit permissions but workflow uses a sensitive trigger. Add job-level permissions for least-privilege security.`,
+            entity: jobName,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,67 @@
+import { describe, test, expect } from "bun:test";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha021 } from "./gha021";
+
+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("GHA021: checkout without pinned SHA", () => {
+  test("flags checkout with tag ref", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: echo test
+`;
+    const diags = gha021.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA021");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("v4");
+  });
+
+  test("does not flag checkout with pinned SHA", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+      - run: echo test
+`;
+    const diags = gha021.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag non-checkout actions", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@v4
+      - run: echo test
+`;
+    const diags = gha021.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,48 @@
+/**
+ * GHA021: Checkout Action Without Pinned SHA
+ *
+ * Flags `actions/checkout` usage that references a tag (e.g. v4) instead of
+ * a pinned commit SHA.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs } from "./yaml-helpers";
+
+export const gha021: PostSynthCheck = {
+  id: "GHA021",
+  description: "actions/checkout used without pinned SHA",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    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",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,45 @@
+import { describe, test, expect } from "bun:test";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha022 } from "./gha022";
+
+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("GHA022: job without timeout-minutes", () => {
+  test("flags job missing timeout-minutes", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo test
+`;
+    const diags = gha022.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA022");
+    expect(diags[0].severity).toBe("info");
+    expect(diags[0].message).toContain("build");
+  });
+
+  test("does not flag workflow without jobs", () => {
+    const yaml = `name: CI
+on:
+  push:
+`;
+    const diags = gha022.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,50 @@
+/**
+ * GHA022: Job Without timeout-minutes
+ *
+ * Flags jobs that do not specify `timeout-minutes`, which can lead to
+ * hung workflows consuming runner minutes.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs } from "./yaml-helpers";
+
+export const gha022: PostSynthCheck = {
+  id: "GHA022",
+  description: "Job without timeout-minutes",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const jobs = extractJobs(yaml);
+
+      // Find job sections in the raw YAML to check for timeout-minutes
+      const jobsIdx = yaml.search(/^jobs:\s*$/m);
+      if (jobsIdx === -1) continue;
+
+      const afterJobs = yaml.slice(jobsIdx + yaml.slice(jobsIdx).indexOf("\n") + 1);
+      const endMatch = afterJobs.search(/^[a-z]/m);
+      const jobsContent = endMatch === -1 ? afterJobs : afterJobs.slice(0, endMatch);
+
+      for (const [jobName] of jobs) {
+        // Find this job's section in the raw YAML
+        const jobPattern = new RegExp(`^  ${jobName}:\\n([\\s\\S]*?)(?=\\n  [a-z]|$)`, "m");
+        const jobSection = jobsContent.match(jobPattern);
+        const section = jobSection ? jobSection[0] : "";
+
+        if (!/timeout-minutes:/m.test(section)) {
+          diagnostics.push({
+            checkId: "GHA022",
+            severity: "info",
+            message: `Job "${jobName}" does not specify timeout-minutes. Consider adding a timeout to prevent hung workflows.`,
+            entity: jobName,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,52 @@
+import { describe, test, expect } from "bun:test";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha023 } from "./gha023";
+
+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("GHA023: deprecated ::set-output command", () => {
+  test("flags step using ::set-output", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "::set-output name=version::1.0.0"
+      - run: echo done
+`;
+    const diags = gha023.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA023");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("set-output");
+  });
+
+  test("does not flag step using GITHUB_OUTPUT", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "version=1.0.0" >> $GITHUB_OUTPUT
+      - run: echo done
+`;
+    const diags = gha023.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,44 @@
+/**
+ * GHA023: Deprecated set-output Command
+ *
+ * Flags usage of `::set-output` in run steps, which has been deprecated
+ * in favor of `$GITHUB_OUTPUT`.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs } from "./yaml-helpers";
+
+export const gha023: PostSynthCheck = {
+  id: "GHA023",
+  description: "Deprecated ::set-output command usage",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    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.run) continue;
+
+          if (step.run.includes("::set-output")) {
+            const stepLabel = step.name ?? "unnamed step";
+            diagnostics.push({
+              checkId: "GHA023",
+              severity: "warning",
+              message: `Job "${jobName}" step "${stepLabel}" uses deprecated ::set-output. Use $GITHUB_OUTPUT instead.`,
+              entity: jobName,
+              lexicon: "github",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,67 @@
+import { describe, test, expect } from "bun:test";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha024 } from "./gha024";
+
+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("GHA024: missing concurrency for deploy workflow", () => {
+  test("flags deploy workflow without concurrency", () => {
+    const yaml = `name: Deploy
+on:
+  push:
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo deploy
+`;
+    const diags = gha024.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA024");
+    expect(diags[0].severity).toBe("info");
+    expect(diags[0].message).toContain("concurrency");
+  });
+
+  test("does not flag deploy workflow with concurrency", () => {
+    const yaml = `name: Deploy
+on:
+  push:
+concurrency:
+  group: deploy
+  cancel-in-progress: true
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo deploy
+`;
+    const diags = gha024.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag non-deploy workflow without concurrency", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo build
+`;
+    const diags = gha024.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,42 @@
+/**
+ * GHA024: Missing Concurrency for Deploy Workflows
+ *
+ * Flags deploy workflows that lack a `concurrency:` block, which risks
+ * overlapping deployments.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs, extractWorkflowName } from "./yaml-helpers";
+
+export const gha024: PostSynthCheck = {
+  id: "GHA024",
+  description: "Missing concurrency block for deploy workflow",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+
+      const workflowName = extractWorkflowName(yaml) ?? "";
+      const jobs = extractJobs(yaml);
+      const jobNames = [...jobs.keys()];
+
+      const isDeployWorkflow =
+        /deploy/i.test(workflowName) || jobNames.some((name) => /deploy/i.test(name));
+
+      if (!isDeployWorkflow) continue;
+
+      if (!/^concurrency:/m.test(yaml)) {
+        diagnostics.push({
+          checkId: "GHA024",
+          severity: "info",
+          message: "Deploy workflow does not specify concurrency. Add a concurrency block to prevent overlapping deployments.",
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,65 @@
+import { describe, test, expect } from "bun:test";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha025 } from "./gha025";
+
+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("GHA025: pull_request_target without restrictions", () => {
+  test("flags pull_request_target without types filter", () => {
+    const yaml = `name: CI
+on:
+  pull_request_target:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo test
+`;
+    const diags = gha025.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA025");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("types");
+  });
+
+  test("does not flag pull_request_target with types filter", () => {
+    const yaml = `name: CI
+on:
+  pull_request_target:
+    types: [labeled, opened]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo test
+`;
+    const diags = gha025.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag workflow without pull_request_target", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo test
+`;
+    const diags = gha025.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,42 @@
+/**
+ * GHA025: Using `pull_request_target` Without Restrictions
+ *
+ * Flags workflows that use `pull_request_target` without a `types:` filter,
+ * which can expose secrets to untrusted fork PRs.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractTriggers } from "./yaml-helpers";
+
+export const gha025: PostSynthCheck = {
+  id: "GHA025",
+  description: "Using pull_request_target without restrictions",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const triggers = extractTriggers(yaml);
+
+      if (!triggers["pull_request_target"]) continue;
+
+      // Check if pull_request_target section has a types: filter
+      const prtSection = yaml.match(/^\s{2}pull_request_target:\s*\n((?:\s{4,}.+\n)*)/m);
+      const hasTypes = prtSection?.[1]?.match(/^\s+types:/m);
+
+      if (!hasTypes) {
+        diagnostics.push({
+          checkId: "GHA025",
+          severity: "warning",
+          message:
+            "Workflow uses `pull_request_target` without a `types:` filter. This exposes secrets to all fork PRs. Add a `types:` restriction (e.g., [labeled, opened]) to limit exposure.",
+          entity: "pull_request_target",
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,65 @@
+import { describe, test, expect } from "bun:test";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha026 } from "./gha026";
+
+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("GHA026: secret without environment protection", () => {
+  test("flags secrets usage without environment", () => {
+    const yaml = `name: Deploy
+on:
+  push:
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo secrets.DEPLOY_KEY
+`;
+    const diags = gha026.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA026");
+    expect(diags[0].severity).toBe("info");
+    expect(diags[0].message).toContain("secrets");
+  });
+
+  test("does not flag secrets with environment", () => {
+    const yaml = `name: Deploy
+on:
+  push:
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - run: echo secrets.DEPLOY_KEY
+`;
+    const diags = gha026.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag workflow without secrets", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo test
+`;
+    const diags = gha026.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,40 @@
+/**
+ * GHA026: Secret Passed to Action Without `environment` Protection
+ *
+ * Flags workflows that reference `secrets.` in steps but have no
+ * `environment:` key in any job, meaning secrets lack deployment
+ * protection rules.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput } from "./yaml-helpers";
+
+export const gha026: PostSynthCheck = {
+  id: "GHA026",
+  description: "Secret passed to action without environment protection",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+
+      const usesSecrets = /secrets\./m.test(yaml);
+      if (!usesSecrets) continue;
+
+      const hasEnvironment = /^\s+environment:/m.test(yaml);
+      if (hasEnvironment) continue;
+
+      diagnostics.push({
+        checkId: "GHA026",
+        severity: "info",
+        message:
+          "Workflow references secrets but no job defines an `environment:`. Consider using environment protection rules to gate secret access with required reviewers or wait timers.",
+        entity: "secrets",
+        lexicon: "github",
+      });
+    }
+
+    return diagnostics;
+  },
+};