@intentius/chant-lexicon-github 0.1.23 → 0.3.0

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

@@ -24,15 +24,61 @@ describe("githubPlugin", () => {
 
   test("provides post-synth checks", () => {
     const checks = githubPlugin.postSynthChecks!();
-    expect(checks.length).toBe(15);
+    expect(checks.length).toBe(45);
 
     const checkIds = checks.map((c) => c.id);
     expect(checkIds).toContain("GHA006");
     expect(checkIds).toContain("GHA009");
     expect(checkIds).toContain("GHA011");
+    expect(checkIds).toContain("GHA013");
     expect(checkIds).toContain("GHA017");
     expect(checkIds).toContain("GHA018");
     expect(checkIds).toContain("GHA019");
+    expect(checkIds).toContain("GHA029");
+    expect(checkIds).toContain("GHA030");
+    expect(checkIds).toContain("GHA031");
+    expect(checkIds).toContain("GHA032");
+    expect(checkIds).toContain("GHA033");
+    expect(checkIds).toContain("GHA034");
+    expect(checkIds).toContain("GHA035");
+    expect(checkIds).toContain("GHA036");
+    expect(checkIds).toContain("GHA037");
+    expect(checkIds).toContain("GHA038");
+    expect(checkIds).toContain("GHA039");
+    expect(checkIds).toContain("GHA040");
+    expect(checkIds).toContain("GHA041");
+    expect(checkIds).toContain("GHA042");
+    expect(checkIds).toContain("GHA043");
+    expect(checkIds).toContain("GHA044");
+    expect(checkIds).toContain("GHA045");
+    expect(checkIds).toContain("GHA046");
+    expect(checkIds).toContain("GHA047");
+    expect(checkIds).toContain("GHA048");
+    expect(checkIds).toContain("GHA049");
+    expect(checkIds).toContain("GHA050");
+    expect(checkIds).toContain("GHA051");
+    expect(checkIds).toContain("GHA052");
+    expect(checkIds).toContain("GHA053");
+    expect(checkIds).toContain("GHA054");
+    expect(checkIds).toContain("GHA055");
+    expect(checkIds).toContain("GHA056");
+    expect(checkIds).toContain("GHA057");
+    expect(checkIds).toContain("GHA058");
+  });
+
+  test("lint IDs are unique across rules and post-synth checks", () => {
+    const ruleIds = githubPlugin.lintRules!().map((r) => r.id);
+    const checkIds = githubPlugin.postSynthChecks!().map((c) => c.id);
+    const allIds = [...ruleIds, ...checkIds];
+
+    const seen = new Set<string>();
+    const duplicates = new Set<string>();
+    for (const id of allIds) {
+      if (seen.has(id)) duplicates.add(id);
+      seen.add(id);
+    }
+
+    expect(Array.from(duplicates)).toEqual([]);
   });
 
   test("provides intrinsics", () => {
@@ -79,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() {

package/src/serializer.ts

@@ -233,6 +233,7 @@ export const githubSerializer: Serializer = {
     const workflows: Array<[string, Declarable]> = [];
     const jobs: Array<[string, Declarable]> = [];
     const triggers: Array<[string, Declarable]> = [];
+    const dependabot: Array<[string, Declarable]> = [];
     const others: Array<[string, Declarable]> = [];
 
     for (const [name, entity] of entities) {
@@ -245,21 +246,53 @@ export const githubSerializer: Serializer = {
         jobs.push([name, entity]);
       } else if (isTriggerType(entityType)) {
         triggers.push([name, entity]);
+      } else if (entityType === "GitHub::Dependabot::Config") {
+        dependabot.push([name, entity]);
       } else {
         others.push([name, entity]);
       }
     }
 
-    // If multiple workflows, produce multiple files
-    if (workflows.length > 1) {
-      return serializeMultiWorkflow(workflows, jobs, triggers, entities, entityNames);
+    const workflowOut =
+      workflows.length > 1
+        ? serializeMultiWorkflow(workflows, jobs, triggers, entities, entityNames)
+        : serializeSingleWorkflow(workflows, jobs, triggers, entities, entityNames);
+
+    // A DependabotConfig emits an additional `.github/dependabot.yml` file
+    // alongside (or instead of) any workflow output.
+    if (dependabot.length > 0) {
+      const [, dep] = dependabot[0];
+      const depProps = (dep as unknown as Record<string, unknown>).props as Record<string, unknown>;
+      const dependabotYaml = emitDependabotYaml(depProps);
+      if (typeof workflowOut === "string") {
+        return { primary: workflowOut, files: { "dependabot.yml": dependabotYaml } };
+      }
+      return { ...workflowOut, files: { ...(workflowOut.files ?? {}), "dependabot.yml": dependabotYaml } };
     }
 
-    // Single workflow (or implicit workflow from jobs)
-    return serializeSingleWorkflow(workflows, jobs, triggers, entities, entityNames);
+    return workflowOut;
   },
 };
 
+/** Deep camelCase → kebab-case key conversion for dependabot props. */
+function deepKebabKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(deepKebabKeys);
+  if (value !== null && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[toKebabCase(k)] = deepKebabKeys(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+/** Serialize a DependabotConfig's props into `.github/dependabot.yml`. */
+function emitDependabotYaml(props: Record<string, unknown>): string {
+  const doc = deepKebabKeys(props) as Record<string, unknown>;
+  return emitYAMLDocument(doc);
+}
+
 function serializeSingleWorkflow(
   workflows: Array<[string, Declarable]>,
   jobs: Array<[string, Declarable]>,