@intentius/chant-lexicon-github 0.0.18

package/src/import/generator.ts

@@ -0,0 +1,119 @@
+/**
+ * TypeScript code generator for GitHub Actions import.
+ *
+ * Converts a TemplateIR into TypeScript source code using
+ * the @intentius/chant-lexicon-github constructors.
+ */
+
+import type { TypeScriptGenerator, GeneratedFile } from "@intentius/chant/import/generator";
+import type { TemplateIR } from "@intentius/chant/import/parser";
+
+const TYPE_TO_CLASS: Record<string, string> = {
+  "GitHub::Actions::Workflow": "Workflow",
+  "GitHub::Actions::Job": "Job",
+  "GitHub::Actions::ReusableWorkflowCallJob": "ReusableWorkflowCallJob",
+};
+
+const PROPERTY_CONSTRUCTORS: Record<string, string> = {
+  strategy: "Strategy",
+  concurrency: "Concurrency",
+  container: "Container",
+  environment: "Environment",
+  permissions: "Permissions",
+  defaults: "Defaults",
+};
+
+/**
+ * Generate TypeScript source code from a GitHub Actions IR.
+ */
+export class GitHubActionsGenerator implements TypeScriptGenerator {
+  generate(ir: TemplateIR): GeneratedFile[] {
+    const lines: string[] = [];
+
+    const usedConstructors = new Set<string>();
+    for (const resource of ir.resources) {
+      const cls = TYPE_TO_CLASS[resource.type];
+      if (cls) usedConstructors.add(cls);
+      this.collectNestedConstructors(resource.properties, usedConstructors);
+    }
+
+    const imports = [...usedConstructors].sort().join(", ");
+    lines.push(`import { ${imports} } from "@intentius/chant-lexicon-github";`);
+    lines.push("");
+
+    for (const resource of ir.resources) {
+      const cls = TYPE_TO_CLASS[resource.type];
+      if (!cls) continue;
+
+      const varName = resource.logicalId;
+      const propsStr = this.emitProps(resource.properties, 1);
+      lines.push(`export const ${varName} = new ${cls}(${propsStr});`);
+      lines.push("");
+    }
+
+    return [{ path: "main.ts", content: lines.join("\n") }];
+  }
+
+  private collectNestedConstructors(props: Record<string, unknown>, used: Set<string>): void {
+    for (const [key, value] of Object.entries(props)) {
+      const constructor = PROPERTY_CONSTRUCTORS[key];
+      if (constructor && typeof value === "object" && value !== null && !Array.isArray(value)) {
+        used.add(constructor);
+      }
+    }
+  }
+
+  private emitProps(props: Record<string, unknown>, depth: number): string {
+    const indent = "  ".repeat(depth);
+    const innerIndent = "  ".repeat(depth + 1);
+    const entries: string[] = [];
+
+    for (const [key, value] of Object.entries(props)) {
+      if (value === undefined || value === null) continue;
+      const emitted = this.emitValue(key, value, depth + 1);
+      entries.push(`${innerIndent}${JSON.stringify(key)}: ${emitted},`);
+    }
+
+    if (entries.length === 0) return "{}";
+    return `{\n${entries.join("\n")}\n${indent}}`;
+  }
+
+  private emitValue(key: string, value: unknown, depth: number): string {
+    if (value === null || value === undefined) return "undefined";
+
+    const constructor = PROPERTY_CONSTRUCTORS[key];
+    if (constructor && typeof value === "object" && !Array.isArray(value)) {
+      const propsStr = this.emitProps(value as Record<string, unknown>, depth);
+      return `new ${constructor}(${propsStr})`;
+    }
+
+    return this.emitLiteral(value, depth);
+  }
+
+  private emitLiteral(value: unknown, depth: number): string {
+    if (value === null || value === undefined) return "undefined";
+    if (typeof value === "string") return JSON.stringify(value);
+    if (typeof value === "number" || typeof value === "boolean") return String(value);
+
+    if (Array.isArray(value)) {
+      if (value.length === 0) return "[]";
+      const items = value.map((item) => this.emitLiteral(item, depth + 1));
+      const oneLine = `[${items.join(", ")}]`;
+      if (oneLine.length < 80) return oneLine;
+      const indent = "  ".repeat(depth);
+      const innerIndent = "  ".repeat(depth + 1);
+      return `[\n${items.map((i) => `${innerIndent}${i},`).join("\n")}\n${indent}]`;
+    }
+
+    if (typeof value === "object") {
+      const entries = Object.entries(value as Record<string, unknown>);
+      if (entries.length === 0) return "{}";
+      const indent = "  ".repeat(depth);
+      const innerIndent = "  ".repeat(depth + 1);
+      const items = entries.map(([k, v]) => `${innerIndent}${JSON.stringify(k)}: ${this.emitLiteral(v, depth + 1)},`);
+      return `{\n${items.join("\n")}\n${indent}}`;
+    }
+
+    return String(value);
+  }
+}

package/src/import/parser.test.ts

@@ -0,0 +1,98 @@
+import { describe, test, expect } from "bun:test";
+import { GitHubActionsParser } from "./parser";
+
+const parser = new GitHubActionsParser();
+
+describe("GitHubActionsParser", () => {
+  test("parses workflow-level properties", () => {
+    const yaml = `name: CI
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+`;
+    const ir = parser.parse(yaml);
+    const wf = ir.resources.find((r) => r.type === "GitHub::Actions::Workflow");
+    expect(wf).toBeDefined();
+    expect(wf!.properties.name).toBe("CI");
+    expect(wf!.properties.permissions).toBeDefined();
+  });
+
+  test("parses jobs as Job resources", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo build
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo test
+`;
+    const ir = parser.parse(yaml);
+    const jobs = ir.resources.filter((r) => r.type === "GitHub::Actions::Job");
+    expect(jobs).toHaveLength(2);
+    expect(jobs[0].logicalId).toBe("build");
+    expect(jobs[1].logicalId).toBe("test");
+  });
+
+  test("converts kebab-case job IDs to camelCase logical IDs", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo test
+`;
+    const ir = parser.parse(yaml);
+    const job = ir.resources.find((r) => r.type === "GitHub::Actions::Job");
+    expect(job!.logicalId).toBe("buildAndTest");
+    expect(job!.metadata?.originalName).toBe("build-and-test");
+  });
+
+  test("detects reusable workflow call jobs", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  call-other:
+    uses: owner/repo/.github/workflows/reusable.yml@main
+`;
+    const ir = parser.parse(yaml);
+    const job = ir.resources.find((r) => r.type === "GitHub::Actions::ReusableWorkflowCallJob");
+    expect(job).toBeDefined();
+    expect(job!.logicalId).toBe("callOther");
+  });
+
+  test("returns empty resources for non-workflow YAML", () => {
+    const yaml = `key: value\nother: stuff`;
+    const ir = parser.parse(yaml);
+    // May have a workflow resource with key/value, but no jobs
+    const jobs = ir.resources.filter((r) => r.type === "GitHub::Actions::Job");
+    expect(jobs).toHaveLength(0);
+  });
+
+  test("preserves job properties", () => {
+    const yaml = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm test
+`;
+    const ir = parser.parse(yaml);
+    const job = ir.resources.find((r) => r.type === "GitHub::Actions::Job");
+    expect(job!.properties["runs-on"]).toBe("ubuntu-latest");
+    expect(job!.properties["timeout-minutes"]).toBe(30);
+  });
+});

package/src/import/parser.ts

@@ -0,0 +1,73 @@
+/**
+ * GitHub Actions YAML parser for `chant import`.
+ *
+ * Parses existing .github/workflows/*.yml files into TemplateIR.
+ */
+
+import type { TemplateParser, TemplateIR, ResourceIR } from "@intentius/chant/import/parser";
+import { parseYAML } from "@intentius/chant/yaml";
+
+function kebabToCamelCase(name: string): string {
+  return name.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+function snakeToCamelCase(name: string): string {
+  return name.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+/**
+ * GitHub Actions YAML parser implementation.
+ */
+export class GitHubActionsParser implements TemplateParser {
+  parse(content: string): TemplateIR {
+    const doc = parseYAML(content);
+    const resources: ResourceIR[] = [];
+
+    // Extract workflow-level properties
+    const workflowProps: Record<string, unknown> = {};
+    if (doc.name) workflowProps.name = doc.name;
+    if (doc["run-name"]) workflowProps["run-name"] = doc["run-name"];
+    if (doc.on) workflowProps.on = doc.on;
+    if (doc.permissions) workflowProps.permissions = doc.permissions;
+    if (doc.env) workflowProps.env = doc.env;
+    if (doc.concurrency) workflowProps.concurrency = doc.concurrency;
+    if (doc.defaults) workflowProps.defaults = doc.defaults;
+
+    if (Object.keys(workflowProps).length > 0) {
+      resources.push({
+        logicalId: "workflow",
+        type: "GitHub::Actions::Workflow",
+        properties: workflowProps,
+      });
+    }
+
+    // Extract jobs
+    if (doc.jobs && typeof doc.jobs === "object") {
+      for (const [jobId, jobDef] of Object.entries(doc.jobs as Record<string, unknown>)) {
+        if (typeof jobDef !== "object" || jobDef === null) continue;
+
+        const jobObj = jobDef as Record<string, unknown>;
+        const logicalId = kebabToCamelCase(jobId);
+
+        // Determine if it's a reusable workflow call job
+        const type = jobObj.uses
+          ? "GitHub::Actions::ReusableWorkflowCallJob"
+          : "GitHub::Actions::Job";
+
+        resources.push({
+          logicalId,
+          type,
+          properties: jobObj,
+          metadata: {
+            originalName: jobId,
+          },
+        });
+      }
+    }
+
+    return {
+      resources,
+      parameters: [],
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+// Serializer
+export { githubSerializer } from "./serializer";
+
+// Plugin
+export { githubPlugin } from "./plugin";
+
+// Expression system
+export {
+  Expression,
+  github, runner, secrets, matrix, steps, needs, inputs, vars, env,
+  always, failure, success, cancelled,
+  contains, startsWith, toJSON, fromJSON, format,
+  branch, tag,
+} from "./expression";
+
+// Context Variables
+export { GitHub, Runner } from "./variables";
+
+// Generated entities — export everything from generated index
+// After running `chant generate`, this re-exports all entity classes
+export * from "./generated/index";
+
+// Composites
+export {
+  Checkout, SetupNode, SetupGo, SetupPython,
+  CacheAction, UploadArtifact, DownloadArtifact,
+  NodeCI,
+  NodePipeline, BunPipeline, PnpmPipeline, YarnPipeline,
+  PythonCI,
+  DockerBuild,
+  DeployEnvironment,
+  GoCI,
+} from "./composites/index";
+export type {
+  CheckoutProps, SetupNodeProps, SetupGoProps, SetupPythonProps,
+  CacheActionProps, UploadArtifactProps, DownloadArtifactProps,
+  NodeCIProps,
+  NodePipelineProps,
+  PythonCIProps,
+  DockerBuildProps,
+  DeployEnvironmentProps,
+  GoCIProps,
+} from "./composites/index";
+
+// Spec utilities (for tooling)
+export { fetchWorkflowSchema, fetchSchemas } from "./spec/fetch";
+export { parseWorkflowSchema, githubShortName, githubServiceName } from "./codegen/parse";
+export type { GitHubParseResult, ParsedResource, ParsedProperty, ParsedPropertyType, ParsedEnum } from "./codegen/parse";
+
+// Code generation pipeline
+export { generate, writeGeneratedFiles } from "./codegen/generate";
+export { packageLexicon } from "./codegen/package";
+export type { PackageOptions, PackageResult } from "./codegen/package";

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

@@ -0,0 +1,58 @@
+/**
+ * GHA006: Duplicate Workflow Name
+ *
+ * Detects multiple workflows sharing the same `name:` value.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { extractWorkflowName } from "./yaml-helpers";
+import type { SerializerResult } from "@intentius/chant/serializer";
+
+export const gha006: PostSynthCheck = {
+  id: "GHA006",
+  description: "Multiple workflows share the same name",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const nameMap = new Map<string, string[]>();
+
+    for (const [outputName, output] of ctx.outputs) {
+      const yaml = typeof output === "string" ? output : (output as SerializerResult).primary;
+
+      // Check if this is a multi-file output
+      if (typeof output === "object" && "files" in output) {
+        const result = output as SerializerResult;
+        if (result.files) {
+          for (const [fileName, fileContent] of Object.entries(result.files)) {
+            const name = extractWorkflowName(fileContent);
+            if (name) {
+              const existing = nameMap.get(name) ?? [];
+              existing.push(fileName);
+              nameMap.set(name, existing);
+            }
+          }
+        }
+      } else {
+        const name = extractWorkflowName(yaml);
+        if (name) {
+          const existing = nameMap.get(name) ?? [];
+          existing.push(outputName);
+          nameMap.set(name, existing);
+        }
+      }
+    }
+
+    for (const [name, files] of nameMap) {
+      if (files.length > 1) {
+        diagnostics.push({
+          checkId: "GHA006",
+          severity: "error",
+          message: `Duplicate workflow name "${name}" found in: ${files.join(", ")}`,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,42 @@
+/**
+ * GHA009: Empty Matrix Dimension
+ *
+ * Detects matrix dimensions with empty values arrays.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput } from "./yaml-helpers";
+
+export const gha009: PostSynthCheck = {
+  id: "GHA009",
+  description: "Matrix dimension has empty values array",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+
+      // Find matrix sections and check for empty arrays
+      const matrixMatch = yaml.match(/matrix:\n([\s\S]*?)(?=\n\s{4}[a-z]|\n\s{2}[a-z]|\n[a-z]|$)/gm);
+      if (!matrixMatch) continue;
+
+      for (const section of matrixMatch) {
+        const lines = section.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+          const keyMatch = lines[i].match(/^\s+([a-z][a-z0-9_-]*):\s*\[\s*\]\s*$/);
+          if (keyMatch) {
+            diagnostics.push({
+              checkId: "GHA009",
+              severity: "error",
+              message: `Matrix dimension "${keyMatch[1]}" has an empty values array.`,
+              lexicon: "github",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,40 @@
+/**
+ * GHA011: Invalid Needs Reference
+ *
+ * Detects `needs:` references to non-existent job IDs.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs } from "./yaml-helpers";
+
+export const gha011: PostSynthCheck = {
+  id: "GHA011",
+  description: "Job needs: references non-existent job",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const jobs = extractJobs(yaml);
+      const jobNames = new Set(jobs.keys());
+
+      for (const [jobName, job] of jobs) {
+        if (!job.needs) continue;
+        for (const need of job.needs) {
+          if (!jobNames.has(need)) {
+            diagnostics.push({
+              checkId: "GHA011",
+              severity: "error",
+              message: `Job "${jobName}" needs "${need}", but no such job exists.`,
+              entity: jobName,
+              lexicon: "github",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,32 @@
+/**
+ * GHA017: Missing Permissions
+ *
+ * Flags workflows without an explicit `permissions:` block.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, hasPermissions } from "./yaml-helpers";
+
+export const gha017: PostSynthCheck = {
+  id: "GHA017",
+  description: "Workflow without explicit permissions block",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+
+      if (!hasPermissions(yaml)) {
+        diagnostics.push({
+          checkId: "GHA017",
+          severity: "info",
+          message: "Workflow does not specify permissions. Consider adding explicit permissions for least-privilege security.",
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,40 @@
+/**
+ * GHA018: Pull Request Target + Checkout Security Risk
+ *
+ * Flags workflows using `pull_request_target` trigger with a checkout action
+ * in steps — this is a known security anti-pattern.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs, extractTriggers, hasCheckoutAction } from "./yaml-helpers";
+
+export const gha018: PostSynthCheck = {
+  id: "GHA018",
+  description: "pull_request_target with checkout action is a security risk",
+
+  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;
+
+      const jobs = extractJobs(yaml);
+      for (const [jobName, job] of jobs) {
+        if (job.steps && hasCheckoutAction(job.steps)) {
+          diagnostics.push({
+            checkId: "GHA018",
+            severity: "warning",
+            message: `Job "${jobName}" uses checkout with pull_request_target trigger. This runs untrusted PR code with write permissions — a security risk.`,
+            entity: jobName,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,72 @@
+/**
+ * GHA019: Circular Needs Chain
+ *
+ * DFS-based cycle detection on the job `needs:` dependency graph.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, buildNeedsGraph } from "./yaml-helpers";
+
+export function checkCircularNeeds(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [, output] of ctx.outputs) {
+    const yaml = getPrimaryOutput(output);
+    const graph = buildNeedsGraph(yaml);
+
+    const visited = new Set<string>();
+    const inStack = new Set<string>();
+    const reportedInCycle = new Set<string>();
+
+    function dfs(node: string, path: string[]): void {
+      if (inStack.has(node)) {
+        const cycleStart = path.indexOf(node);
+        const cycle = path.slice(cycleStart);
+        cycle.push(node);
+
+        const cycleKey = [...cycle].sort().join(",");
+        if (!reportedInCycle.has(cycleKey)) {
+          reportedInCycle.add(cycleKey);
+          diagnostics.push({
+            checkId: "GHA019",
+            severity: "error",
+            message: `Circular needs: chain detected: ${cycle.join(" → ")}`,
+            entity: node,
+            lexicon: "github",
+          });
+        }
+        return;
+      }
+
+      if (visited.has(node)) return;
+
+      visited.add(node);
+      inStack.add(node);
+
+      for (const neighbor of graph.get(node) ?? []) {
+        if (graph.has(neighbor)) {
+          dfs(neighbor, [...path, node]);
+        }
+      }
+
+      inStack.delete(node);
+    }
+
+    for (const jobName of graph.keys()) {
+      if (!visited.has(jobName)) {
+        dfs(jobName, []);
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const gha019: PostSynthCheck = {
+  id: "GHA019",
+  description: "Circular needs: chain — cycle in job dependency graph",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkCircularNeeds(ctx);
+  },
+};