@intentius/chant-lexicon-github 0.0.18

package/src/serializer.ts

@@ -0,0 +1,383 @@
+/**
+ * GitHub Actions YAML serializer.
+ *
+ * Converts Chant declarables to .github/workflows/*.yml YAML output.
+ * Uses kebab-case keys for job properties and snake_case for trigger
+ * event names.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { isPropertyDeclarable } from "@intentius/chant/declarable";
+import type { Serializer, SerializerResult } from "@intentius/chant/serializer";
+import type { LexiconOutput } from "@intentius/chant/lexicon-output";
+import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
+import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+import { emitYAML } from "@intentius/chant/yaml";
+
+// ── Key conversion ────────────────────────────────────────────────
+
+/**
+ * Convert camelCase property names to kebab-case for YAML output.
+ * Examples: timeoutMinutes → timeout-minutes, runsOn → runs-on
+ */
+function toKebabCase(name: string): string {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+/**
+ * Convert camelCase trigger names to snake_case event names.
+ * Examples: pullRequest → pull_request, workflowDispatch → workflow_dispatch
+ */
+function toSnakeCase(name: string): string {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+}
+
+/**
+ * Map entity type names to YAML trigger event names.
+ */
+const TRIGGER_TYPE_TO_EVENT: Record<string, string> = {
+  "GitHub::Actions::PushTrigger": "push",
+  "GitHub::Actions::PullRequestTrigger": "pull_request",
+  "GitHub::Actions::PullRequestTargetTrigger": "pull_request_target",
+  "GitHub::Actions::ScheduleTrigger": "schedule",
+  "GitHub::Actions::WorkflowDispatchTrigger": "workflow_dispatch",
+  "GitHub::Actions::WorkflowCallTrigger": "workflow_call",
+  "GitHub::Actions::WorkflowRunTrigger": "workflow_run",
+  "GitHub::Actions::RepositoryDispatchTrigger": "repository_dispatch",
+};
+
+/** Check if an entity type is a trigger. */
+function isTriggerType(entityType: string): boolean {
+  return entityType in TRIGGER_TYPE_TO_EVENT;
+}
+
+// ── Visitor ───────────────────────────────────────────────────────
+
+function githubVisitor(entityNames: Map<Declarable, string>): SerializerVisitor {
+  return {
+    attrRef: (name, _attr) => name,
+    resourceRef: (name) => toKebabCase(name),
+    propertyDeclarable: (entity, walk) => {
+      if (!("props" in entity) || typeof entity.props !== "object" || entity.props === null) {
+        return undefined;
+      }
+      const props = entity.props as Record<string, unknown>;
+      const result: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(props)) {
+        if (value !== undefined) {
+          result[key] = walk(value);
+        }
+      }
+      return Object.keys(result).length > 0 ? result : undefined;
+    },
+  };
+}
+
+// ── Intrinsic preprocessing ───────────────────────────────────────
+
+function preprocessIntrinsics(value: unknown): unknown {
+  if (value === null || value === undefined) return value;
+
+  if (typeof value === "object" && INTRINSIC_MARKER in value) {
+    if ("toYAML" in value && typeof value.toYAML === "function") {
+      return (value as { toYAML(): unknown }).toYAML();
+    }
+  }
+
+  // Leave Declarables untouched
+  if (typeof value === "object" && value !== null && "entityType" in value) {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(preprocessIntrinsics);
+  }
+
+  if (typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      result[k] = preprocessIntrinsics(v);
+    }
+    return result;
+  }
+
+  return value;
+}
+
+function toYAMLValue(value: unknown, entityNames: Map<Declarable, string>): unknown {
+  const preprocessed = preprocessIntrinsics(value);
+  return walkValue(preprocessed, entityNames, githubVisitor(entityNames));
+}
+
+// ── Key conversion for YAML output ────────────────────────────────
+
+/**
+ * Convert a props object keys from camelCase to kebab-case for job/step properties.
+ */
+function convertKeys(obj: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === undefined || value === null) continue;
+    // Zero and false are valid values, but undefined/null should be omitted
+    const yamlKey = toKebabCase(key);
+    result[yamlKey] = convertValueKeys(value);
+  }
+  return result;
+}
+
+function convertValueKeys(value: unknown): unknown {
+  if (value === null || value === undefined) return value;
+  if (typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(convertValueKeys);
+
+  const obj = value as Record<string, unknown>;
+  const result: Record<string, unknown> = {};
+  for (const [key, v] of Object.entries(obj)) {
+    if (v === undefined || v === null) continue;
+    result[toKebabCase(key)] = convertValueKeys(v);
+  }
+  return result;
+}
+
+// ── Serializer ────────────────────────────────────────────────────
+
+/**
+ * GitHub Actions YAML serializer implementation.
+ */
+export const githubSerializer: Serializer = {
+  name: "github",
+  rulePrefix: "GHA",
+
+  serialize(
+    entities: Map<string, Declarable>,
+    _outputs?: LexiconOutput[],
+  ): string | SerializerResult {
+    const entityNames = new Map<Declarable, string>();
+    for (const [name, entity] of entities) {
+      entityNames.set(entity, name);
+    }
+
+    // Categorize entities
+    const workflows: Array<[string, Declarable]> = [];
+    const jobs: Array<[string, Declarable]> = [];
+    const triggers: Array<[string, Declarable]> = [];
+    const others: Array<[string, Declarable]> = [];
+
+    for (const [name, entity] of entities) {
+      if (isPropertyDeclarable(entity)) continue;
+
+      const entityType = (entity as Record<string, unknown>).entityType as string;
+      if (entityType === "GitHub::Actions::Workflow") {
+        workflows.push([name, entity]);
+      } else if (entityType === "GitHub::Actions::Job" || entityType === "GitHub::Actions::ReusableWorkflowCallJob") {
+        jobs.push([name, entity]);
+      } else if (isTriggerType(entityType)) {
+        triggers.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);
+    }
+
+    // Single workflow (or implicit workflow from jobs)
+    return serializeSingleWorkflow(workflows, jobs, triggers, entities, entityNames);
+  },
+};
+
+function serializeSingleWorkflow(
+  workflows: Array<[string, Declarable]>,
+  jobs: Array<[string, Declarable]>,
+  triggers: Array<[string, Declarable]>,
+  _entities: Map<string, Declarable>,
+  entityNames: Map<Declarable, string>,
+): string {
+  const doc: Record<string, unknown> = {};
+
+  // Workflow-level properties
+  if (workflows.length > 0) {
+    const [, wf] = workflows[0];
+    const props = toYAMLValue((wf as Record<string, unknown>).props, entityNames) as Record<string, unknown> | undefined;
+    if (props) {
+      if (props.name) doc.name = props.name;
+      if (props["run-name"] || props.runName) doc["run-name"] = props["run-name"] ?? props.runName;
+      if (props.permissions) doc.permissions = convertValueKeys(props.permissions);
+      if (props.env) doc.env = props.env;
+      if (props.concurrency) doc.concurrency = convertValueKeys(props.concurrency);
+      if (props.defaults) doc.defaults = convertValueKeys(props.defaults);
+
+      // Handle 'on' from workflow props
+      if (props.on) {
+        doc.on = convertTriggerProps(props.on);
+      }
+    }
+  }
+
+  // If triggers exist as separate entities, merge into 'on'
+  if (triggers.length > 0) {
+    const onSection = (doc.on as Record<string, unknown>) ?? {};
+    for (const [, trigger] of triggers) {
+      const entityType = (trigger as Record<string, unknown>).entityType as string;
+      const eventName = TRIGGER_TYPE_TO_EVENT[entityType];
+      if (!eventName) continue;
+
+      const props = toYAMLValue((trigger as Record<string, unknown>).props, entityNames) as Record<string, unknown> | undefined;
+      if (props && Object.keys(props).length > 0) {
+        onSection[eventName] = convertValueKeys(props);
+      } else {
+        onSection[eventName] = null;
+      }
+    }
+    doc.on = onSection;
+  }
+
+  // Jobs
+  if (jobs.length > 0) {
+    const jobsSection: Record<string, unknown> = {};
+    for (const [name, job] of jobs) {
+      const props = toYAMLValue((job as Record<string, unknown>).props, entityNames) as Record<string, unknown> | undefined;
+      if (props) {
+        const yamlName = toKebabCase(name);
+        jobsSection[yamlName] = convertKeys(props);
+      }
+    }
+    doc.jobs = jobsSection;
+  }
+
+  return emitYAMLDocument(doc);
+}
+
+function serializeMultiWorkflow(
+  workflows: Array<[string, Declarable]>,
+  jobs: Array<[string, Declarable]>,
+  triggers: Array<[string, Declarable]>,
+  _entities: Map<string, Declarable>,
+  entityNames: Map<Declarable, string>,
+): SerializerResult {
+  // For multi-workflow, each workflow gets its own file.
+  // Jobs and triggers need to be associated with workflows somehow.
+  // For now, first workflow gets all unscoped entities.
+  const files: Record<string, string> = {};
+  let primary = "";
+
+  for (let i = 0; i < workflows.length; i++) {
+    const [name, wf] = workflows[i];
+    const doc: Record<string, unknown> = {};
+    const props = toYAMLValue((wf as Record<string, unknown>).props, entityNames) as Record<string, unknown> | undefined;
+
+    if (props) {
+      if (props.name) doc.name = props.name;
+      if (props.on) doc.on = convertTriggerProps(props.on);
+      if (props.permissions) doc.permissions = convertValueKeys(props.permissions);
+      if (props.env) doc.env = props.env;
+      if (props.concurrency) doc.concurrency = convertValueKeys(props.concurrency);
+      if (props.defaults) doc.defaults = convertValueKeys(props.defaults);
+    }
+
+    // Attach all triggers to first workflow for now
+    if (i === 0 && triggers.length > 0) {
+      const onSection = (doc.on as Record<string, unknown>) ?? {};
+      for (const [, trigger] of triggers) {
+        const entityType = (trigger as Record<string, unknown>).entityType as string;
+        const eventName = TRIGGER_TYPE_TO_EVENT[entityType];
+        if (!eventName) continue;
+        const tProps = toYAMLValue((trigger as Record<string, unknown>).props, entityNames) as Record<string, unknown> | undefined;
+        if (tProps && Object.keys(tProps).length > 0) {
+          onSection[eventName] = convertValueKeys(tProps);
+        } else {
+          onSection[eventName] = null;
+        }
+      }
+      doc.on = onSection;
+    }
+
+    // Attach all jobs to first workflow for now
+    if (i === 0 && jobs.length > 0) {
+      const jobsSection: Record<string, unknown> = {};
+      for (const [jName, job] of jobs) {
+        const jProps = toYAMLValue((job as Record<string, unknown>).props, entityNames) as Record<string, unknown> | undefined;
+        if (jProps) {
+          jobsSection[toKebabCase(jName)] = convertKeys(jProps);
+        }
+      }
+      doc.jobs = jobsSection;
+    }
+
+    const content = emitYAMLDocument(doc);
+    const fileName = `${toKebabCase(name)}.yml`;
+    files[fileName] = content;
+
+    if (i === 0) primary = content;
+  }
+
+  return { primary, files };
+}
+
+/**
+ * Convert trigger props to YAML-compatible form.
+ */
+function convertTriggerProps(on: unknown): unknown {
+  if (typeof on !== "object" || on === null) return on;
+  if (Array.isArray(on)) return on;
+
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(on as Record<string, unknown>)) {
+    const eventName = toSnakeCase(key);
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      result[eventName] = convertValueKeys(value as Record<string, unknown>);
+    } else {
+      result[eventName] = value;
+    }
+  }
+  return result;
+}
+
+/**
+ * Emit a complete YAML document from a structured object.
+ */
+function emitYAMLDocument(doc: Record<string, unknown>): string {
+  const sections: string[] = [];
+
+  // Emit in canonical order: name, run-name, on, permissions, env, concurrency, defaults, jobs
+  const order = ["name", "run-name", "on", "permissions", "env", "concurrency", "defaults", "jobs"];
+  const emitted = new Set<string>();
+
+  for (const key of order) {
+    if (key in doc && doc[key] !== undefined) {
+      emitted.add(key);
+      const value = doc[key];
+      if (value === null) {
+        sections.push(`${key}:`);
+      } else if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        sections.push(`${key}: ${yamlScalar(value)}`);
+      } else {
+        sections.push(`${key}:` + emitYAML(value, 1));
+      }
+    }
+  }
+
+  // Remaining keys
+  for (const [key, value] of Object.entries(doc)) {
+    if (emitted.has(key) || value === undefined) continue;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      sections.push(`${key}: ${yamlScalar(value)}`);
+    } else {
+      sections.push(`${key}:` + emitYAML(value, 1));
+    }
+  }
+
+  return sections.join("\n\n") + "\n";
+}
+
+function yamlScalar(value: string | number | boolean): string {
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return String(value);
+  // Quote strings that might be ambiguous
+  if (/^[\d]|[:#\[\]{}|>&*!%@`]|true|false|null|yes|no/i.test(value)) {
+    return `'${value.replace(/'/g, "''")}'`;
+  }
+  return value;
+}

package/src/skills/github-actions-patterns.md

@@ -0,0 +1,93 @@
+---
+skill: github-actions-patterns
+description: GitHub Actions workflow patterns — triggers, jobs, matrix, caching, artifacts, permissions, reusable workflows
+---
+
+# GitHub Actions Patterns
+
+## Workflow Structure
+
+A GitHub Actions workflow is a YAML file in `.github/workflows/`. Key sections:
+
+- `name:` — display name for the workflow
+- `on:` — trigger events (push, pull_request, schedule, etc.)
+- `permissions:` — GITHUB_TOKEN permissions (least-privilege)
+- `jobs:` — named jobs that run on runners
+
+## Trigger Patterns
+
+```typescript
+// Push to main
+new PushTrigger({ branches: ["main"] })
+
+// Pull requests
+new PullRequestTrigger({ branches: ["main"], types: ["opened", "synchronize"] })
+
+// Schedule (cron)
+new ScheduleTrigger({ cron: "0 0 * * *" })
+
+// Manual dispatch with inputs
+new WorkflowDispatchTrigger({ inputs: { environment: { type: "choice", options: ["staging", "production"] } } })
+```
+
+## Matrix Strategy
+
+```typescript
+new Strategy({
+  matrix: {
+    os: ["ubuntu-latest", "windows-latest"],
+    "node-version": ["18", "20", "22"],
+  },
+  "fail-fast": false,
+})
+```
+
+## Caching
+
+Use the `cache` option on setup actions, or explicit Cache action:
+```typescript
+SetupNode({ nodeVersion: "22", cache: "npm" })
+```
+
+## Permissions (Least Privilege)
+
+Always set explicit permissions:
+```typescript
+new Permissions({
+  contents: "read",
+  "pull-requests": "write",
+})
+```
+
+## Reusable Workflows
+
+Call reusable workflows with `ReusableWorkflowCallJob`:
+```typescript
+new ReusableWorkflowCallJob({
+  uses: "./.github/workflows/deploy.yml",
+  with: { environment: "production" },
+  secrets: "inherit",
+})
+```
+
+## Artifacts
+
+```typescript
+UploadArtifact({ name: "build", path: "dist/", retentionDays: 7 })
+DownloadArtifact({ name: "build", path: "dist/" })
+```
+
+## Environment Protection
+
+```typescript
+new Environment({ name: "production", url: "https://example.com" })
+```
+
+## Concurrency
+
+```typescript
+new Concurrency({
+  group: "${{ github.workflow }}-${{ github.ref }}",
+  "cancel-in-progress": true,
+})
+```

package/src/spec/fetch.ts

@@ -0,0 +1,55 @@
+/**
+ * GitHub Actions workflow schema fetching — downloads the JSON Schema
+ * and caches it locally.
+ */
+
+import { join } from "path";
+import { homedir } from "os";
+import { fetchWithCache, clearCacheFile } from "@intentius/chant/codegen/fetch";
+
+/**
+ * Schema URL from SchemaStore.
+ */
+const SCHEMA_URL = "https://json.schemastore.org/github-workflow.json";
+
+/**
+ * Get the cache file path for the workflow schema.
+ */
+export function getCachePath(): string {
+  return join(homedir(), ".chant", "github-workflow-schema.json");
+}
+
+/**
+ * Fetch the GitHub Actions Workflow JSON Schema.
+ * Uses local file caching with 24-hour TTL.
+ */
+export async function fetchWorkflowSchema(force?: boolean): Promise<Buffer> {
+  return fetchWithCache(
+    {
+      url: SCHEMA_URL,
+      cacheFile: getCachePath(),
+    },
+    force,
+  );
+}
+
+/**
+ * Fetch the workflow schema as a Map<typeName, Buffer>
+ * compatible with the generatePipeline fetchSchemas callback.
+ *
+ * Single document keyed by "GitHub::Actions::Workflow" — the parse
+ * step will split it into multiple entities.
+ */
+export async function fetchSchemas(force?: boolean): Promise<Map<string, Buffer>> {
+  const data = await fetchWorkflowSchema(force);
+  const schemas = new Map<string, Buffer>();
+  schemas.set("GitHub::Actions::Workflow", data);
+  return schemas;
+}
+
+/**
+ * Clear the cached schema file.
+ */
+export function clearCache(): void {
+  clearCacheFile(getCachePath());
+}

package/src/validate-cli.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env bun
+/**
+ * Thin entry point for `bun run validate` in lexicon-github.
+ */
+import { validate } from "./validate";
+
+const result = await validate();
+
+for (const check of result.checks) {
+  const status = check.ok ? "OK" : "FAIL";
+  const msg = check.error ? ` — ${check.error}` : "";
+  console.error(`  [${status}] ${check.name}${msg}`);
+}
+
+if (!result.success) {
+  console.error("Validation failed");
+  process.exit(1);
+}
+console.error("All validation checks passed.");

package/src/validate.test.ts

@@ -0,0 +1,12 @@
+import { describe, test, expect } from "bun:test";
+import { validate } from "./validate";
+
+describe("validate", () => {
+  test("exports validate function", () => {
+    expect(typeof validate).toBe("function");
+  });
+
+  // Note: Full validation requires generated artifacts to exist.
+  // This test verifies the validate module loads correctly.
+  // Run `bun run generate` first for full validation tests.
+});

package/src/validate.ts

@@ -0,0 +1,32 @@
+/**
+ * Validate generated lexicon-github artifacts.
+ */
+
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts, type ValidateResult } from "@intentius/chant/codegen/validate";
+
+export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
+
+const REQUIRED_NAMES = [
+  "Workflow", "Job", "ReusableWorkflowCallJob",
+  "Step", "Strategy", "Permissions", "Concurrency",
+  "Container", "Service", "Environment", "Defaults",
+  "PushTrigger", "PullRequestTrigger", "PullRequestTargetTrigger",
+  "ScheduleTrigger", "WorkflowDispatchTrigger", "WorkflowCallTrigger",
+  "WorkflowRunTrigger", "RepositoryDispatchTrigger",
+  "WorkflowInput", "WorkflowOutput", "WorkflowSecret",
+];
+
+/**
+ * Validate the generated lexicon-github artifacts.
+ */
+export async function validate(opts?: { basePath?: string }): Promise<ValidateResult> {
+  const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+
+  return validateLexiconArtifacts({
+    lexiconJsonFilename: "lexicon-github.json",
+    requiredNames: REQUIRED_NAMES,
+    basePath,
+  });
+}

package/src/variables.ts

@@ -0,0 +1,44 @@
+/**
+ * GitHub Actions predefined context variable references.
+ *
+ * These provide type-safe access to GitHub and Runner context values
+ * that expand to `${{ context.property }}` expressions in YAML.
+ */
+
+import { Expression } from "./expression";
+
+export const GitHub = {
+  Ref: new Expression("github.ref"),
+  RefName: new Expression("github.ref_name"),
+  RefType: new Expression("github.ref_type"),
+  Sha: new Expression("github.sha"),
+  Actor: new Expression("github.actor"),
+  TriggeringActor: new Expression("github.triggering_actor"),
+  Repository: new Expression("github.repository"),
+  RepositoryOwner: new Expression("github.repository_owner"),
+  EventName: new Expression("github.event_name"),
+  Event: new Expression("github.event"),
+  RunId: new Expression("github.run_id"),
+  RunNumber: new Expression("github.run_number"),
+  RunAttempt: new Expression("github.run_attempt"),
+  Workflow: new Expression("github.workflow"),
+  WorkflowRef: new Expression("github.workflow_ref"),
+  Workspace: new Expression("github.workspace"),
+  Token: new Expression("github.token"),
+  Job: new Expression("github.job"),
+  HeadRef: new Expression("github.head_ref"),
+  BaseRef: new Expression("github.base_ref"),
+  ServerUrl: new Expression("github.server_url"),
+  ApiUrl: new Expression("github.api_url"),
+  GraphqlUrl: new Expression("github.graphql_url"),
+  Action: new Expression("github.action"),
+  ActionPath: new Expression("github.action_path"),
+} as const;
+
+export const Runner = {
+  Os: new Expression("runner.os"),
+  Arch: new Expression("runner.arch"),
+  Name: new Expression("runner.name"),
+  Temp: new Expression("runner.temp"),
+  ToolCache: new Expression("runner.tool_cache"),
+} as const;