@intentius/chant-lexicon-github 0.2.0 → 0.3.0

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "9bfb1e2f89ab306d4369dbd5df0a9cb0fc22cc8d282f37a1c6195ce86b812410",
+    "manifest.json": "0fa34c5776ecd073eddf047bf545d4e7eec1b2bef82bda8e8b9a937dafefdbe3",
     "meta.json": "798c5f5f37b0174756d2451299acfdc95c014f11d06d32b9153bbdfa9f3a580c",
     "types/index.d.ts": "39c0791f0e58025bcef82e0f7a92240508f899fc2771d5dd51b2369b4d330f13",
     "rules/deprecated-action-version.ts": "d41e6e532ab7f623af1bee4ac5279fcb2baada7defa1c5d022a5bc71983e8797",
@@ -67,5 +67,5 @@
     "skills/chant-github-patterns.md": "bb3abef289a8fdfcf07d6bb2d7289dcb2f38bc0cb0321ea320b78b45a6f548c0",
     "skills/chant-github-security.md": "aab111cb0871cad30281ce48d7da23663689619351029219e2be019a1a61e394"
   },
-  "composite": "c655b1bc501ac68358351aa669e0eeca83ba58bf483d5503949bb1dad5410586"
+  "composite": "b9406b7d04e47eb1ac9b2562be29fad73787acf1a3d610c2920fd96d874f85f9"
 }

package/dist/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "GitHub Actions lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/codegen/docs.ts

@@ -25,7 +25,7 @@ npm install --save-dev @intentius/chant-lexicon-github
 
 {{file:docs-snippets/src/quickstart.ts}}
 
-The lexicon provides **2 resources** (Workflow, Job), **13 composites** (Checkout, SetupNode, SetupGo, SetupPython, CacheAction, UploadArtifact, DownloadArtifact, NodeCI, NodePipeline, PythonCI, DockerBuild, DeployEnvironment, GoCI) + **3 presets** (BunPipeline, PnpmPipeline, YarnPipeline), a typed **Expression** system with 24 GitHub and 5 Runner context variables, and **13 lint rules** + **6 post-synth checks**.
+The lexicon provides **3 resources** (Workflow, Job, Dependabot config), **14 composites** (Checkout, SetupNode, SetupGo, SetupPython, CacheAction, UploadArtifact, DownloadArtifact, NodeCI, NodePipeline, PythonCI, DockerBuild, DeployEnvironment, GoCI, Dependabot) + **3 presets** (BunPipeline, PnpmPipeline, YarnPipeline), a typed **Expression** system with 24 GitHub and 5 Runner context variables, and **13 lint rules** + **45 post-synth checks** (including a CI/CD supply-chain security pass, GHA029–058).
 `;
 
 const outputFormat = `The GitHub Actions lexicon serializes resources into **\`.github/workflows/*.yml\`** YAML files.
@@ -184,7 +184,7 @@ GitHub automatically picks up any \`.github/workflows/*.yml\` files and runs the
 - [Workflow Concepts](/chant/lexicons/github/workflow-concepts/) — resource types, triggers, permissions
 - [Expressions](/chant/lexicons/github/expressions/) — typed expression system and condition helpers
 - [Composites](/chant/lexicons/github/composites/) — pre-built action wrappers (Checkout, SetupNode, etc.)
-- [Lint Rules](/chant/lexicons/github/lint-rules/) — 13 lint rules and 6 post-synth checks`,
+- [Lint Rules](/chant/lexicons/github/lint-rules/) — 13 lint rules and 45 post-synth checks`,
       },
       {
         slug: "workflow-concepts",
@@ -838,7 +838,27 @@ const { workflow, buildJob, testJob, lintJob } = GoCI({
 const noLint = GoCI({ lintCommand: null });
 \`\`\`
 
-**Props:** \`goVersion?\`, \`testCommand?\`, \`buildCommand?\`, \`lintCommand?\` (null to omit), \`runsOn?\``,
+**Props:** \`goVersion?\`, \`testCommand?\`, \`buildCommand?\`, \`lintCommand?\` (null to omit), \`runsOn?\`
+
+## Dependabot
+
+Models the repository's dependency-update configuration (\`.github/dependabot.yml\`) as a chant resource, so it is emitted and lintable like a workflow. The composite ships **safe defaults**: a cooldown window on every ecosystem (so a version published moments ago — including a compromised one — is not adopted before anyone can react) and external code execution explicitly denied.
+
+\`\`\`typescript
+import { Dependabot } from "@intentius/chant-lexicon-github";
+
+export const dependabot = Dependabot({
+  ecosystems: [
+    { packageEcosystem: "npm", directory: "/" },
+    { packageEcosystem: "github-actions", directory: "/" },
+  ],
+  // cooldownDays defaults to 7, openPullRequestsLimit to 5
+});
+\`\`\`
+
+**Props:** \`ecosystems\` (required — each \`{ packageEcosystem, directory?, interval? }\`), \`cooldownDays?\` (default 7), \`openPullRequestsLimit?\` (default 5)
+
+For full control, construct the \`DependabotConfig\` resource directly with raw \`updates:\` entries. Two post-synth checks validate the emitted config: **GHA057** (\`insecure-external-code-execution: allow\`) and **GHA058** (no cooldown). See [Lint Rules](/chant/lexicons/github/lint-rules/).`,
       },
       {
         slug: "lint-rules",
@@ -976,6 +996,60 @@ Flags workflows triggered by \`pull_request_target\` that include \`actions/chec
 
 Detects cycles in the \`needs:\` dependency graph. If job A needs B and B needs A (directly or transitively), GitHub rejects the workflow. Reports the full cycle chain in the diagnostic message.
 
+### GHA021 — Checkout action not pinned to a SHA
+
+**Severity:** warning
+
+Flags \`actions/checkout\` referenced by a tag (e.g. \`@v4\`) instead of a pinned commit SHA. The narrower precursor to GHA029, kept because checkout is the most common unpinned action.
+
+### GHA022 — Job without timeout-minutes
+
+**Severity:** info
+
+Flags jobs that omit \`timeout-minutes\`. A hung step otherwise runs to the runner's default cap, burning minutes — set an explicit ceiling.
+
+### GHA023 — Deprecated set-output command
+
+**Severity:** warning
+
+Flags \`::set-output\` in \`run:\` steps. The workflow command is deprecated and disabled on current runners — write to \`$GITHUB_OUTPUT\` instead.
+
+### GHA024 — Missing concurrency for deploy workflows
+
+**Severity:** info
+
+Flags deploy workflows without a \`concurrency:\` block. Without one, two pushes can deploy concurrently and race — add a concurrency group to serialize them.
+
+### GHA025 — pull_request_target without restrictions
+
+**Severity:** warning
+
+Flags \`pull_request_target\` used without a \`types:\` filter. The trigger runs with repository secrets in the base-branch context, so it should be scoped to the specific PR events that need it.
+
+### GHA026 — Secret used without environment protection
+
+**Severity:** info
+
+Flags workflows that reference \`secrets.\` in steps but declare no \`environment:\` on any job, so the secret skips the approval and scoping rules an environment gate provides.
+
+### GHA027 — Cleanup step missing if: always()
+
+**Severity:** info
+
+Flags steps named "cleanup" / "teardown" / "clean up" that lack an \`if:\` condition. Cleanup should run even when a prior step fails — add \`if: always()\`.
+
+### GHA028 — Workflow with no on: triggers
+
+**Severity:** error
+
+Flags a workflow file with no top-level \`on:\` key. Without a trigger the workflow can never run.
+
+## Supply-chain security pass (GHA029–058)
+
+GHA029 onward are a CI/CD supply-chain security pass: pin & vet external references, enforce least-privilege token scopes, guard trust boundaries against untrusted input, contain secrets, reject unsound expressions, and keep artifacts/caches honest. They run statically on the emitted YAML — everything answerable without leaving the build.
+
+The checks that need a *moving external truth* — whether a pinned SHA still maps to a real upstream tag, whether a ref still exists, whether a new advisory now covers an action in use — can't be deterministic, so they live in the operational layer instead. Schedule the [\`WorkflowAuditOp\`](/chant/guide/ops/#audit-supply-chain-drift) (temporal lexicon) for that live, always-fresh half; it reads the same emitted workflow references and reports drift via \`report | issue | pull-request\`.
+
 ### GHA029 — Action or reusable workflow not pinned to a commit SHA
 
 **Severity:** warning
@@ -1287,7 +1361,7 @@ The inline \`chant-github\` skill covers the full workflow lifecycle:
 - **Validate** — \`chant lint src/\`
 - **Deploy** — commit and push the generated YAML
 - **Status** — GitHub Actions UI or \`gh run list\`
-- **Troubleshooting** — lint rule codes (GHA001–GHA020), post-synth checks (GHA006–GHA019)
+- **Troubleshooting** — lint rule codes (GHA001–GHA020), post-synth checks (GHA006–GHA058)
 
 The skill is invocable as a slash command: \`/chant-github\`
 
@@ -1311,6 +1385,13 @@ The lexicon provides MCP (Model Context Protocol) tools and resources that AI ag
 | MCP tool | Description |
 |----------|-------------|
 | \`diff\` | Compare current build output against previous output |
+| \`github:checks\` | Build the workflow and return its security findings (the GHA checks) |
+| \`github:workflow\` | Triggers and jobs as written — name, run order, step count |
+| \`github:references\` | Actions and images pulled in, and whether each is pinned to a commit SHA |
+| \`github:affected\` | Given a job, the jobs that would re-run because they depend on it |
+| \`github:workflow-yaml\` | The generated workflow YAML |
+
+The \`github:*\` tools are **read-only context tools** (#327): each builds from your source and returns what chant already computes — before the workflow runs or merges. None touch the live GitHub instance, run history, or write anything.
 
 | MCP resource | Description |
 |--------------|-------------|

package/src/mcp/context-tools.test.ts

@@ -0,0 +1,108 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { githubContextTools, downstreamJobs, actionPinned } from "./context-tools";
+
+const tools = Object.fromEntries(githubContextTools().map((t) => [t.name, t]));
+
+async function call(name: string, params: Record<string, unknown>): Promise<unknown> {
+  return tools[name].handler(params);
+}
+
+describe("downstreamJobs / actionPinned (#327)", () => {
+  test("downstreamJobs follows the needs chain transitively", () => {
+    const yaml = `jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo build
+  test:
+    runs-on: ubuntu-latest
+    needs: [build]
+    steps:
+      - run: echo test
+  deploy:
+    runs-on: ubuntu-latest
+    needs: [test]
+    steps:
+      - run: echo deploy
+`;
+    expect(downstreamJobs(yaml, "build").sort()).toEqual(["deploy", "test"]);
+    expect(downstreamJobs(yaml, "test")).toEqual(["deploy"]);
+    expect(downstreamJobs(yaml, "deploy")).toEqual([]);
+  });
+
+  test("actionPinned only accepts a full commit SHA", () => {
+    expect(actionPinned("actions/checkout@" + "a".repeat(40))).toBe(true);
+    expect(actionPinned("actions/checkout@v4")).toBe(false);
+    expect(actionPinned("actions/checkout@main")).toBe(false);
+  });
+});
+
+describe("github context tools — end to end (#327)", () => {
+  let dir: string;
+  beforeEach(async () => {
+    dir = join(tmpdir(), `chant-mcp-gh-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      join(dir, "workflow.github.ts"),
+      `const M = Symbol.for("chant.declarable");
+export const ci = { [M]: true, lexicon: "github", entityType: "GitHub::Actions::Workflow", kind: "resource",
+  props: {
+    name: "CI",
+    on: { push: { branches: ["main"] } },
+    permissions: { contents: "read" },
+    jobs: {
+      build: { runsOn: "ubuntu-latest", steps: [ { uses: "peter-evans/create-pull-request@v6" }, { run: "npm ci" } ] },
+      test: { runsOn: "ubuntu-latest", needs: ["build"], steps: [ { run: "npm test" } ] },
+    },
+  } };
+`,
+    );
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("github:workflow returns triggers and jobs", async () => {
+    const out = (await call("github:workflow", { path: dir })) as {
+      workflow: string | null;
+      triggers: string[];
+      jobs: Array<{ name: string; runsAfter: string[]; steps: number }>;
+    };
+    expect(out.workflow).toBe("CI");
+    expect(out.triggers).toContain("push");
+    const names = out.jobs.map((j) => j.name);
+    expect(names).toEqual(expect.arrayContaining(["build", "test"]));
+    expect(out.jobs.find((j) => j.name === "test")?.runsAfter).toContain("build");
+  });
+
+  test("github:references reports the unpinned third-party action", async () => {
+    const out = (await call("github:references", { path: dir })) as Array<{ kind: string; source: string; pinned: boolean }>;
+    const action = out.find((r) => r.kind === "action" && r.source === "peter-evans/create-pull-request@v6");
+    expect(action).toBeDefined();
+    expect(action?.pinned).toBe(false);
+  });
+
+  test("github:checks returns the GHA findings (unpinned action trips GHA029)", async () => {
+    const out = (await call("github:checks", { path: dir })) as { findings: Array<{ id: string; severity: string; job: string | null; message: string }> };
+    expect(Array.isArray(out.findings)).toBe(true);
+    expect(out.findings.some((f) => f.id === "GHA029")).toBe(true);
+    for (const f of out.findings) {
+      expect(typeof f.id).toBe("string");
+      expect(typeof f.message).toBe("string");
+    }
+  });
+
+  test("github:affected lists downstream jobs", async () => {
+    const out = (await call("github:affected", { path: dir, job: "build" })) as { job: string; wouldRerun: string[] };
+    expect(out.wouldRerun).toContain("test");
+  });
+
+  test("github:workflow-yaml returns the generated YAML for a path", async () => {
+    const out = (await call("github:workflow-yaml", { path: dir })) as { yaml: string };
+    expect(typeof out.yaml).toBe("string");
+    expect(out.yaml).toContain("jobs:");
+  });
+});

package/src/mcp/context-tools.ts

@@ -0,0 +1,172 @@
+/**
+ * Read-only MCP tools that expose what `chant build` already computes about a
+ * GitHub Actions workflow — its jobs and run order, what it pulls in from
+ * outside (actions, images), and its security findings — so an agent can ask
+ * about a change *before it runs or merges* (#327).
+ *
+ * The GitHub counterpart to the GitLab context tools. Every tool builds from
+ * source and returns data. None of them touch the live GitHub instance, read
+ * run history, or write anything — that boundary is what keeps chant a context
+ * producer and not a copy of the live tooling.
+ */
+
+import { build, type BuildResult } from "@intentius/chant/build";
+import { runPostSynthChecks, getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+import { discoverPostSynthChecks } from "@intentius/chant/lint/discover";
+import type { McpToolContribution } from "@intentius/chant/mcp/types";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { githubSerializer } from "../serializer";
+import {
+  extractJobs,
+  extractActionRefs,
+  extractImageRefs,
+  extractTriggers,
+  extractWorkflowName,
+} from "../lint/post-synth/yaml-helpers";
+
+/** Build the project and return the emitted GitHub workflow YAML plus the raw result. */
+async function buildGithub(path: string): Promise<{ yaml: string; result: BuildResult }> {
+  const result = await build(path, [githubSerializer]);
+  const out = result.outputs.get("github");
+  return { yaml: out ? getPrimaryOutput(out) : "", result };
+}
+
+/** Discover the lexicon's post-synth checks without depending on the plugin. */
+function githubPostSynthChecks() {
+  const dir = join(dirname(fileURLToPath(import.meta.url)), "..", "lint", "post-synth");
+  return discoverPostSynthChecks(dir, import.meta.url);
+}
+
+/** Is a `uses:` ref pinned to a full commit SHA (the only immutable form)? */
+export function actionPinned(ref: string): boolean {
+  const at = ref.lastIndexOf("@");
+  return at !== -1 && /^[0-9a-f]{40}$/.test(ref.slice(at + 1));
+}
+
+/** Jobs that would re-run because they depend (transitively) on `job`. */
+export function downstreamJobs(yaml: string, job: string): string[] {
+  const jobs = extractJobs(yaml);
+  // edge: upstream -> downstream (J depends on each of its needs)
+  const downstreamOf = new Map<string, string[]>();
+  for (const [name, j] of jobs) {
+    for (const dep of j.needs ?? []) {
+      const arr = downstreamOf.get(dep) ?? [];
+      arr.push(name);
+      downstreamOf.set(dep, arr);
+    }
+  }
+  const out = new Set<string>();
+  const queue = [job];
+  while (queue.length) {
+    const cur = queue.shift()!;
+    for (const next of downstreamOf.get(cur) ?? []) {
+      if (!out.has(next)) {
+        out.add(next);
+        queue.push(next);
+      }
+    }
+  }
+  return [...out];
+}
+
+const PATH_INPUT = {
+  type: "object" as const,
+  properties: {
+    path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+  },
+};
+
+/** The read-only context tools for the GitHub lexicon. */
+export function githubContextTools(): McpToolContribution[] {
+  return [
+    {
+      name: "github:checks",
+      description:
+        "Build the workflow and return its security and correctness findings (the GHA checks) as JSON. Read-only — does not touch the live GitHub instance.",
+      inputSchema: PATH_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { yaml, result } = await buildGithub((params.path as string) ?? ".");
+        if (!yaml) return { findings: [], note: "no GitHub workflow produced from this project" };
+        const scoped = { ...result, outputs: new Map([["github", result.outputs.get("github")!]]) };
+        const diags = runPostSynthChecks(githubPostSynthChecks(), scoped);
+        return {
+          findings: diags.map((d) => ({
+            id: d.checkId,
+            severity: d.severity,
+            job: d.entity ?? null,
+            message: d.message,
+          })),
+        };
+      },
+    },
+    {
+      name: "github:workflow",
+      description:
+        "Build the workflow and return its triggers and jobs as written (name, what each job runs after, step count) — before anything runs. Read-only.",
+      inputSchema: PATH_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { yaml } = await buildGithub((params.path as string) ?? ".");
+        const jobs = [...extractJobs(yaml).values()].map((j) => ({
+          name: j.name,
+          runsAfter: j.needs ?? [],
+          steps: j.steps?.length ?? 0,
+        }));
+        return {
+          workflow: extractWorkflowName(yaml) ?? null,
+          triggers: Object.keys(extractTriggers(yaml)),
+          jobs,
+        };
+      },
+    },
+    {
+      name: "github:references",
+      description:
+        "Build the workflow and list everything it pulls in from outside (actions via uses:, container/service images) and whether each is pinned to an immutable commit SHA. Read-only.",
+      inputSchema: PATH_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { yaml } = await buildGithub((params.path as string) ?? ".");
+        const actions = extractActionRefs(yaml).map((a) => ({
+          kind: a.level === "job" ? ("reusable-workflow" as const) : ("action" as const),
+          job: a.job,
+          source: a.ref,
+          pinned: actionPinned(a.ref),
+        }));
+        const images = extractImageRefs(yaml).map((i) => ({
+          kind: "image" as const,
+          job: i.job,
+          source: i.image,
+          pinned: i.image.includes("@sha256:"),
+        }));
+        return [...actions, ...images];
+      },
+    },
+    {
+      name: "github:affected",
+      description:
+        "Build the workflow and, given a job name, list the jobs that would re-run because they depend on it (the needs chain). Read-only.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+          job: { type: "string", description: "Job name to trace downstream from" },
+        },
+        required: ["job"],
+      },
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { yaml } = await buildGithub((params.path as string) ?? ".");
+        const job = params.job as string;
+        return { job, wouldRerun: downstreamJobs(yaml, job) };
+      },
+    },
+    {
+      name: "github:workflow-yaml",
+      description: "Build the project and return the generated GitHub Actions workflow YAML as a string. Read-only.",
+      inputSchema: PATH_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { yaml } = await buildGithub((params.path as string) ?? ".");
+        return { yaml };
+      },
+    },
+  ];
+}

package/src/plugin.test.ts

@@ -125,8 +125,17 @@ describe("githubPlugin", () => {
 
   test("provides MCP tools", () => {
     const tools = githubPlugin.mcpTools!();
-    expect(tools.length).toBe(1);
-    expect(tools[0].name).toBe("github:diff");
+    const names = tools.map((t) => t.name);
+    expect(names).toContain("github:diff");
+    // Read-only context tools (#327)
+    expect(names).toContain("github:checks");
+    expect(names).toContain("github:workflow");
+    expect(names).toContain("github:references");
+    expect(names).toContain("github:affected");
+    expect(names).toContain("github:workflow-yaml");
+    for (const t of tools) {
+      expect(typeof t.handler).toBe("function");
+    }
   });
 
   test("provides MCP resources", () => {

package/src/plugin.ts

@@ -29,6 +29,7 @@ import { githubCompletions } from "./lsp/completions";
 import { githubHover } from "./lsp/hover";
 import { GitHubActionsParser } from "./import/parser";
 import { GitHubActionsGenerator } from "./import/generator";
+import { githubContextTools } from "./mcp/context-tools";
 
 export const githubPlugin: LexiconPlugin = {
   name: "github",
@@ -224,7 +225,10 @@ export const build = new Job({
   },
 
   mcpTools() {
-    return [createDiffTool(githubSerializer, "Compare current build output against previous output for GitHub Actions", "github")];
+    return [
+      createDiffTool(githubSerializer, "Compare current build output against previous output for GitHub Actions", "github"),
+      ...githubContextTools(),
+    ];
   },
 
   mcpResources() {