@intentius/chant-lexicon-github 0.0.18 → 0.0.22

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "xxhash64",
   "artifacts": {
-    "manifest.json": "199b64fff9617c21",
+    "manifest.json": "10f628cf1d0e9bdc",
     "meta.json": "317499a992c9c274",
     "types/index.d.ts": "93ce391baebf2afb",
     "rules/missing-recommended-inputs.ts": "42f2f3b0b6c7b52c",
@@ -17,15 +17,25 @@
     "rules/suggest-cache.ts": "c45f7659afde2f15",
     "rules/validate-concurrency.ts": "c12a1aa4ee8badb5",
     "rules/use-matrix-builder.ts": "6b1c0ebf43378805",
+    "rules/gha020.ts": "36ef5e141524bab0",
     "rules/gha017.ts": "ff1c08fdedf83afa",
+    "rules/gha027.ts": "6071aedb178c90a8",
     "rules/gha019.ts": "d9184093f36ac167",
+    "rules/gha024.ts": "ed75a2900c8bf12d",
     "rules/gha009.ts": "df140c0cac573bc4",
+    "rules/gha026.ts": "5ace32df6cb850af",
+    "rules/gha028.ts": "9c1ba1eb9a93d8b6",
+    "rules/gha022.ts": "41038ee697a497d1",
     "rules/gha018.ts": "46acbe27d4c0c817",
     "rules/yaml-helpers.ts": "df426df288c175c9",
     "rules/gha011.ts": "105e2d4faeaa9977",
+    "rules/gha025.ts": "d196899f490521ba",
     "rules/gha006.ts": "baca27402ba18d",
-    "skills/chant-github.md": "e38b1aca37ae4ab8",
-    "skills/github-actions-patterns.md": "887ff05cbb3af292"
+    "rules/gha023.ts": "2d00140d63591c9",
+    "rules/gha021.ts": "da7e2491926d1817",
+    "skills/chant-github.md": "620bdfa7c7c6c3bc",
+    "skills/github-actions-patterns.md": "887ff05cbb3af292",
+    "skills/github-actions-security.md": "1804b95909c199ae"
   },
-  "composite": "e2321ecad63df490"
+  "composite": "2bd4a8603c193c0f"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "github",
-  "version": "0.0.18",
+  "version": "0.0.22",
   "chantVersion": ">=0.1.0",
   "namespace": "GitHub",
   "intrinsics": [

package/dist/rules/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/dist/rules/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/dist/rules/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/dist/rules/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/dist/rules/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/dist/rules/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/dist/rules/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;
+  },
+};

package/dist/rules/gha027.ts

@@ -0,0 +1,57 @@
+/**
+ * GHA027: Missing `if: always()` on Cleanup Steps
+ *
+ * Flags steps whose name contains "cleanup", "teardown", or "clean up"
+ * (case-insensitive) that lack an `if:` condition. Cleanup steps should
+ * typically run with `if: always()` so they execute even when prior steps fail.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs } from "./yaml-helpers";
+
+const CLEANUP_PATTERN = /cleanup|teardown|clean\s+up/i;
+
+export const gha027: PostSynthCheck = {
+  id: "GHA027",
+  description: "Missing `if: always()` on cleanup steps",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+
+      // Scan raw YAML for step blocks with cleanup-like names
+      const stepPattern = /-\s+name:\s+(.+)/g;
+      let match: RegExpExecArray | null;
+
+      while ((match = stepPattern.exec(yaml)) !== null) {
+        const stepName = match[1].trim().replace(/^['"]|['"]$/g, "");
+        if (!CLEANUP_PATTERN.test(stepName)) continue;
+
+        // Get the block after this step name line
+        const afterName = yaml.slice(match.index + match[0].length);
+        // Capture lines until the next step entry or job
+        const blockEnd = afterName.search(/\n\s{6}-\s|\n\s{2}[a-z]/);
+        const block = blockEnd === -1 ? afterName : afterName.slice(0, blockEnd);
+
+        if (!/^\s+if:/m.test(block)) {
+          // Find which job this step belongs to
+          const beforeStep = yaml.slice(0, match.index);
+          const jobMatch = [...beforeStep.matchAll(/^\s{2}([a-z][a-z0-9-]*):/gm)];
+          const jobName = jobMatch.length > 0 ? jobMatch[jobMatch.length - 1][1] : "unknown";
+
+          diagnostics.push({
+            checkId: "GHA027",
+            severity: "info",
+            message: `Step "${stepName}" in job "${jobName}" looks like a cleanup step but has no \`if:\` condition. Add \`if: always()\` so it runs even when prior steps fail.`,
+            entity: `${jobName}.${stepName}`,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/gha028.ts

@@ -0,0 +1,37 @@
+/**
+ * GHA028: Workflow With No `on` Triggers
+ *
+ * Flags workflow files that lack a top-level `on:` key, which means
+ * the workflow will never be triggered.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput } from "./yaml-helpers";
+
+export const gha028: PostSynthCheck = {
+  id: "GHA028",
+  description: "Workflow with no `on` triggers",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+
+      const hasOn = /^on:/m.test(yaml);
+
+      if (!hasOn) {
+        diagnostics.push({
+          checkId: "GHA028",
+          severity: "error",
+          message:
+            "Workflow has no `on:` trigger block. Without triggers the workflow will never run. Add an `on:` section with at least one event.",
+          entity: "on",
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/skills/chant-github.md

@@ -8,7 +8,7 @@ user-invocable: true
 
 ## How chant and GitHub Actions relate
 
-chant is a **synthesis-only** tool — it compiles TypeScript source files into `.github/workflows/*.yml` (YAML). chant does NOT call GitHub APIs.
+chant is a **synthesis compiler** — it compiles TypeScript source files into `.github/workflows/*.yml` (YAML). `chant build` does not call GitHub APIs; synthesis is pure and deterministic.
 
 - Use **chant** for: build, lint, diff (local YAML comparison)
 - Use **git + GitHub** for: push, pull requests, workflow monitoring

package/dist/skills/github-actions-security.md

@@ -0,0 +1,87 @@
+---
+skill: github-actions-security
+description: GitHub Actions security best practices — secret scanning, OIDC, permissions hardening, supply chain security
+---
+
+# GitHub Actions Security Playbook
+
+## Permissions Hardening
+
+Always set the minimum required permissions at the workflow level:
+
+```typescript
+new Workflow({
+  name: "CI",
+  on: { push: { branches: ["main"] } },
+  permissions: { contents: "read" },
+});
+```
+
+For deployments that need write access, scope it to the job:
+
+```typescript
+new Job({
+  "runs-on": "ubuntu-latest",
+  permissions: { contents: "read", "id-token": "write" },
+  steps: [...],
+});
+```
+
+## Pin Actions by SHA
+
+Never use mutable tags like `@v4`. Pin to a full commit SHA:
+
+```typescript
+new Step({
+  uses: "actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11", // v4.1.1
+})
+```
+
+## OIDC for Cloud Providers
+
+Use OpenID Connect instead of long-lived secrets:
+
+```typescript
+// AWS
+new Step({
+  uses: "aws-actions/configure-aws-credentials@v4",
+  with: {
+    "role-to-assume": "arn:aws:iam::123456789012:role/deploy",
+    "aws-region": "us-east-1",
+  },
+})
+```
+
+## Secret Scanning
+
+- Never echo secrets in `run:` steps
+- Use `environment` protection rules for production secrets
+- Rotate secrets regularly and audit access logs
+
+## Supply Chain Security
+
+- Use `permissions: {}` (empty) as a baseline, then grant only what each job needs
+- Avoid `pull_request_target` with `actions/checkout` (code injection risk)
+- Use Dependabot or Renovate to keep action versions current
+- Add `concurrency` blocks to prevent parallel deploys
+
+## Concurrency Control
+
+```typescript
+new Concurrency({
+  group: "${{ github.workflow }}-${{ github.ref }}",
+  "cancel-in-progress": true,
+})
+```
+
+## Job Timeouts
+
+Always set timeouts to prevent runaway jobs:
+
+```typescript
+new Job({
+  "runs-on": "ubuntu-latest",
+  "timeout-minutes": 30,
+  steps: [...],
+});
+```

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.0.18",
+  "version": "0.0.22",
+  "description": "GitHub Actions lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
+  "homepage": "https://intentius.io/chant",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/intentius/chant.git",
+    "directory": "lexicons/github"
+  },
+  "bugs": {
+    "url": "https://github.com/intentius/chant/issues"
+  },
+  "keywords": [
+    "infrastructure-as-code",
+    "iac",
+    "typescript",
+    "github",
+    "github-actions",
+    "chant"
+  ],
   "type": "module",
   "files": [
     "src/",
@@ -25,7 +43,7 @@
     "prepack": "bun run generate && bun run bundle && bun run validate"
   },
   "dependencies": {
-    "@intentius/chant": "0.0.18"
+    "@intentius/chant": "0.0.22"
   },
   "devDependencies": {
     "typescript": "^5.9.3"

package/src/codegen/docs.test.ts

@@ -0,0 +1,19 @@
+import { describe, test, expect } from "bun:test";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+
+describe("docs pipeline", () => {
+  test("docs.ts source file exists", () => {
+    expect(existsSync(join(thisDir, "docs.ts"))).toBe(true);
+  });
+
+  test("docs.ts exports generateDocs function", () => {
+    // docs.ts has template literal parse issues in Bun due to ${{ }} expressions
+    // in inline strings. Verify the file exists and contains the export.
+    const content = Bun.file(join(thisDir, "docs.ts")).text();
+    expect(content).resolves.toContain("export async function generateDocs");
+  });
+});

package/src/codegen/generate.test.ts

@@ -0,0 +1,12 @@
+import { describe, test, expect } from "bun:test";
+import { generate, writeGeneratedFiles } from "./generate";
+
+describe("generate pipeline", () => {
+  test("generate function is exported and callable", () => {
+    expect(typeof generate).toBe("function");
+  });
+
+  test("writeGeneratedFiles function is exported", () => {
+    expect(typeof writeGeneratedFiles).toBe("function");
+  });
+});

package/src/codegen/package.test.ts

@@ -0,0 +1,8 @@
+import { describe, test, expect } from "bun:test";
+import { packageLexicon } from "./package";
+
+describe("package pipeline", () => {
+  test("packageLexicon function is exported and callable", () => {
+    expect(typeof packageLexicon).toBe("function");
+  });
+});

package/src/coverage.test.ts

@@ -0,0 +1,23 @@
+import { describe, test, expect } from "bun:test";
+import {
+  analyzeGitHubCoverage,
+  computeCoverage,
+  overallPct,
+  formatSummary,
+  formatVerbose,
+  checkThresholds,
+} from "./coverage";
+
+describe("coverage module", () => {
+  test("analyzeGitHubCoverage is exported and callable", () => {
+    expect(typeof analyzeGitHubCoverage).toBe("function");
+  });
+
+  test("re-exports from core are functions", () => {
+    expect(typeof computeCoverage).toBe("function");
+    expect(typeof overallPct).toBe("function");
+    expect(typeof formatSummary).toBe("function");
+    expect(typeof formatVerbose).toBe("function");
+    expect(typeof checkThresholds).toBe("function");
+  });
+});