@intentius/chant-lexicon-github 0.0.18

package/src/codegen/generate-cli.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env bun
+/**
+ * CLI entry point for GitHub Actions lexicon generation.
+ */
+
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { generate, writeGeneratedFiles } from "./generate";
+
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+
+async function main() {
+  const verbose = process.argv.includes("--verbose") || process.argv.includes("-v");
+  const force = process.argv.includes("--force") || process.argv.includes("-f");
+
+  console.error("Generating GitHub Actions lexicon...");
+
+  const result = await generate({ verbose, force });
+  writeGeneratedFiles(result, pkgDir);
+
+  console.error(
+    `Generated ${result.resources} entities, ${result.properties} property types, ${result.enums} enums`,
+  );
+
+  if (result.warnings.length > 0) {
+    console.error(`${result.warnings.length} warnings:`);
+    for (const w of result.warnings) {
+      console.error(`  ${w.file}: ${w.error}`);
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error("Generation failed:", err);
+  process.exit(1);
+});

package/src/codegen/generate-lexicon.ts

@@ -0,0 +1,58 @@
+/**
+ * Lexicon JSON generator — produces lexicon-github.json with metadata
+ * for all GitHub Actions entities.
+ */
+
+import type { PropertyConstraints } from "@intentius/chant/codegen/json-schema";
+import type { GitHubParseResult } from "./parse";
+import { githubShortName } from "./parse";
+import type { NamingStrategy } from "./naming";
+import {
+  buildRegistry,
+  serializeRegistry,
+  type RegistryResource,
+} from "@intentius/chant/codegen/generate-registry";
+
+export interface LexiconEntry {
+  resourceType: string;
+  kind: "resource" | "property";
+  lexicon: "github";
+  deprecatedProperties?: string[];
+  constraints?: Record<string, PropertyConstraints>;
+}
+
+/**
+ * Generate the lexicon-github.json content.
+ */
+export function generateLexiconJSON(
+  results: GitHubParseResult[],
+  naming: NamingStrategy,
+): string {
+  const registryResources: RegistryResource[] = results.map((r) => ({
+    typeName: r.resource.typeName,
+    attributes: r.resource.attributes,
+    properties: r.resource.properties,
+    propertyTypes: r.propertyTypes.map((pt) => ({ name: pt.name, specType: pt.defType })),
+  }));
+
+  const entries = buildRegistry<LexiconEntry>(registryResources, naming, {
+    shortName: githubShortName,
+    buildEntry: (resource, _tsName, _attrs, propConstraints) => {
+      const r = results.find((res) => res.resource.typeName === resource.typeName);
+      return {
+        resourceType: resource.typeName,
+        kind: (r?.isProperty ? "property" : "resource") as "resource" | "property",
+        lexicon: "github" as const,
+        ...(r?.resource.deprecatedProperties?.length && { deprecatedProperties: r.resource.deprecatedProperties }),
+        ...(propConstraints && Object.keys(propConstraints).length > 0 && { constraints: propConstraints }),
+      };
+    },
+    buildPropertyEntry: (resourceType, propertyType) => ({
+      resourceType: `${resourceType}.${propertyType}`,
+      kind: "property" as const,
+      lexicon: "github" as const,
+    }),
+  });
+
+  return serializeRegistry(entries);
+}

package/src/codegen/generate-typescript.ts

@@ -0,0 +1,149 @@
+/**
+ * TypeScript declaration file generator — produces index.d.ts with all
+ * GitHub Actions entity classes.
+ */
+
+import type { GitHubParseResult } from "./parse";
+import { githubShortName } from "./parse";
+import type { NamingStrategy } from "./naming";
+import { propertyTypeName, extractDefName } from "./naming";
+import {
+  writeResourceClass,
+  writePropertyClass,
+  writeEnumType,
+  type DtsProperty,
+  type DtsAttribute,
+} from "@intentius/chant/codegen/generate-typescript";
+
+interface ResourceEntry {
+  tsName: string;
+  properties: DtsProperty[];
+  attributes: DtsAttribute[];
+  remap: Map<string, string>;
+}
+
+interface EnumEntry {
+  tsName: string;
+  values: string[];
+}
+
+/**
+ * Generate the complete .d.ts file content.
+ */
+export function generateTypeScriptDeclarations(
+  results: GitHubParseResult[],
+  naming: NamingStrategy,
+): string {
+  const lines: string[] = [];
+  lines.push("// Code generated by chant github generate. DO NOT EDIT.");
+
+  const resources: ResourceEntry[] = [];
+  const enums: EnumEntry[] = [];
+
+  for (const r of results) {
+    const typeName = r.resource.typeName;
+    const tsName = naming.resolve(typeName);
+    if (!tsName) continue;
+
+    const shortName = githubShortName(typeName);
+    const remap = new Map<string, string>();
+    for (const pt of r.propertyTypes) {
+      const defName = extractDefName(pt.name, shortName);
+      remap.set(pt.name, propertyTypeName(tsName, defName));
+    }
+    for (const e of r.enums) {
+      const defName = extractDefName(e.name, shortName);
+      remap.set(e.name, propertyTypeName(tsName, defName));
+    }
+
+    const dtsProps: DtsProperty[] = r.resource.properties.map((p) => ({
+      name: p.name,
+      type: p.tsType,
+      required: p.required,
+      description: p.description,
+    }));
+    const dtsAttrs: DtsAttribute[] = r.resource.attributes.map((a) => ({
+      name: a.name,
+      type: a.tsType,
+    }));
+
+    resources.push({ tsName, properties: dtsProps, attributes: dtsAttrs, remap });
+
+    for (const alias of naming.aliases(typeName)) {
+      resources.push({ tsName: alias, properties: dtsProps, attributes: dtsAttrs, remap });
+    }
+
+    for (const e of r.enums) {
+      const defName = extractDefName(e.name, shortName);
+      const eName = propertyTypeName(tsName, defName);
+      enums.push({ tsName: eName, values: e.values });
+    }
+  }
+
+  resources.sort((a, b) => a.tsName.localeCompare(b.tsName));
+  enums.sort((a, b) => a.tsName.localeCompare(b.tsName));
+
+  lines.push("");
+  lines.push("// --- GitHub Actions Entity classes ---");
+  for (const re of resources) {
+    writeResourceClass(lines, re.tsName, re.properties, re.attributes, re.remap);
+  }
+
+  if (enums.length > 0) {
+    lines.push("");
+    lines.push("// --- Enum types ---");
+    for (const ee of enums) {
+      writeEnumType(lines, ee.tsName, ee.values);
+    }
+  }
+
+  lines.push("");
+  lines.push(staticTypeScript());
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function staticTypeScript(): string {
+  const lines: string[] = [];
+
+  // Inline Expression interface so dist/types/index.d.ts is self-contained
+  lines.push("// --- Expression type (inlined for portability) ---");
+  lines.push("");
+  lines.push("export declare class Expression {");
+  lines.push("  constructor(raw: string);");
+  lines.push("  toString(): string;");
+  lines.push("  valueOf(): string;");
+  lines.push("  eq(value: string | Expression): Expression;");
+  lines.push("  ne(value: string | Expression): Expression;");
+  lines.push("  and(other: Expression): Expression;");
+  lines.push("  or(other: Expression): Expression;");
+  lines.push("  not(): Expression;");
+  lines.push("}");
+
+  lines.push("");
+  lines.push("// --- GitHub Context Variables ---");
+  lines.push("");
+  lines.push("export declare const GitHub: {");
+  const ghVars = [
+    "Ref", "RefName", "RefType", "Sha", "Actor", "TriggeringActor",
+    "Repository", "RepositoryOwner", "EventName", "Event",
+    "RunId", "RunNumber", "RunAttempt", "Workflow", "WorkflowRef",
+    "Workspace", "Token", "Job", "HeadRef", "BaseRef",
+    "ServerUrl", "ApiUrl", "GraphqlUrl", "Action", "ActionPath",
+  ];
+  for (const v of ghVars) {
+    lines.push(`  readonly ${v}: Expression;`);
+  }
+  lines.push("};");
+
+  lines.push("");
+  lines.push("export declare const Runner: {");
+  const runnerVars = ["Os", "Arch", "Name", "Temp", "ToolCache"];
+  for (const v of runnerVars) {
+    lines.push(`  readonly ${v}: Expression;`);
+  }
+  lines.push("};");
+
+  return lines.join("\n");
+}

package/src/codegen/generate.ts

@@ -0,0 +1,141 @@
+/**
+ * GitHub Actions generation pipeline — uses core generatePipeline
+ * with GitHub-specific fetch, parse, naming, and generation callbacks.
+ */
+
+import {
+  generatePipeline,
+  writeGeneratedArtifacts,
+  type GenerateOptions,
+  type GenerateResult,
+  type GeneratePipelineConfig,
+} from "@intentius/chant/codegen/generate";
+import { fetchSchemas } from "../spec/fetch";
+import { parseWorkflowSchema, type GitHubParseResult } from "./parse";
+import { NamingStrategy, propertyTypeName, extractDefName } from "./naming";
+import { githubShortName } from "./parse";
+import { generateLexiconJSON } from "./generate-lexicon";
+import { generateTypeScriptDeclarations } from "./generate-typescript";
+import {
+  generateRuntimeIndex as coreGenerateRuntimeIndex,
+  type RuntimeIndexEntry,
+  type RuntimeIndexPropertyEntry,
+} from "@intentius/chant/codegen/generate-runtime-index";
+
+export type { GenerateResult };
+
+/**
+ * Run the full GitHub Actions generation pipeline.
+ */
+export async function generate(opts: GenerateOptions = {}): Promise<GenerateResult> {
+  let pendingResults: GitHubParseResult[] = [];
+
+  const config: GeneratePipelineConfig<GitHubParseResult> = {
+    fetchSchemas: async (fetchOpts) => {
+      return fetchSchemas(fetchOpts.force);
+    },
+
+    parseSchema: (_typeName, data) => {
+      const results = parseWorkflowSchema(data);
+      if (results.length === 0) return null;
+      pendingResults = results.slice(1);
+      return results[0];
+    },
+
+    createNaming: (results) => new NamingStrategy(results),
+
+    augmentResults: (results, _opts, log) => {
+      if (pendingResults.length > 0) {
+        results.push(...pendingResults);
+        log(`Added ${pendingResults.length} additional entities from single schema`);
+        pendingResults = [];
+      }
+      log(`Total: ${results.length} GitHub Actions entity schemas`);
+      return { results };
+    },
+
+    generateRegistry: (results, naming) => {
+      return generateLexiconJSON(results, naming as NamingStrategy);
+    },
+
+    generateTypes: (results, naming) => {
+      return generateTypeScriptDeclarations(results, naming as NamingStrategy);
+    },
+
+    generateRuntimeIndex: (results, naming) => {
+      return generateRuntimeIndex(results, naming as NamingStrategy);
+    },
+  };
+
+  return generatePipeline(config, opts);
+}
+
+/**
+ * Write generated artifacts to disk.
+ */
+export function writeGeneratedFiles(result: GenerateResult, baseDir: string): void {
+  writeGeneratedArtifacts({
+    baseDir,
+    files: {
+      "lexicon-github.json": result.lexiconJSON,
+      "index.d.ts": result.typesDTS,
+      "index.ts": result.indexTS,
+      "runtime.ts": `/**\n * Runtime factory constructors — re-exported from core.\n */\nexport { createResource, createProperty } from "@intentius/chant/runtime";\n`,
+    },
+  });
+}
+
+/**
+ * Generate the runtime index.ts with factory constructor exports.
+ */
+function generateRuntimeIndex(
+  results: GitHubParseResult[],
+  naming: NamingStrategy,
+): string {
+  const resourceEntries: RuntimeIndexEntry[] = [];
+  const propertyEntries: RuntimeIndexPropertyEntry[] = [];
+
+  for (const r of results) {
+    const typeName = r.resource.typeName;
+    const tsName = naming.resolve(typeName);
+    if (!tsName) continue;
+
+    const attrs: Record<string, string> = {};
+
+    if (r.isProperty) {
+      propertyEntries.push({ tsName, resourceType: typeName });
+      for (const alias of naming.aliases(typeName)) {
+        propertyEntries.push({ tsName: alias, resourceType: typeName });
+      }
+    } else {
+      resourceEntries.push({ tsName, resourceType: typeName, attrs });
+      for (const alias of naming.aliases(typeName)) {
+        resourceEntries.push({ tsName: alias, resourceType: typeName, attrs });
+      }
+    }
+
+    const shortName = githubShortName(typeName);
+    const ptAliases = naming.propertyTypeAliases(typeName);
+    for (const pt of r.propertyTypes) {
+      const defName = extractDefName(pt.name, shortName);
+      const ptName = propertyTypeName(tsName, defName);
+      const ptType = `${typeName}.${pt.defType}`;
+      propertyEntries.push({ tsName: ptName, resourceType: ptType });
+
+      if (ptAliases) {
+        const aliasName = ptAliases.get(defName);
+        if (aliasName) {
+          propertyEntries.push({ tsName: aliasName, resourceType: ptType });
+        }
+      }
+    }
+  }
+
+  return coreGenerateRuntimeIndex(resourceEntries, propertyEntries, {
+    lexiconName: "github",
+    pseudoReExports: {
+      names: ["GitHub", "Runner"],
+      from: "../variables",
+    },
+  });
+}

package/src/codegen/naming.ts

@@ -0,0 +1,57 @@
+/**
+ * GitHub Actions naming strategy — flat namespace with few collisions.
+ */
+
+import {
+  NamingStrategy as CoreNamingStrategy,
+  type NamingConfig,
+  type NamingInput,
+} from "@intentius/chant/codegen/naming";
+import { githubShortName, githubServiceName, type GitHubParseResult } from "./parse";
+
+export { propertyTypeName, extractDefName } from "@intentius/chant/codegen/naming";
+
+const githubNamingConfig: NamingConfig = {
+  priorityNames: {
+    "GitHub::Actions::Workflow": "Workflow",
+    "GitHub::Actions::Job": "Job",
+    "GitHub::Actions::ReusableWorkflowCallJob": "ReusableWorkflowCallJob",
+    "GitHub::Actions::Step": "Step",
+    "GitHub::Actions::Strategy": "Strategy",
+    "GitHub::Actions::Permissions": "Permissions",
+    "GitHub::Actions::Concurrency": "Concurrency",
+    "GitHub::Actions::Container": "Container",
+    "GitHub::Actions::Service": "Service",
+    "GitHub::Actions::Environment": "Environment",
+    "GitHub::Actions::Defaults": "Defaults",
+    "GitHub::Actions::PushTrigger": "PushTrigger",
+    "GitHub::Actions::PullRequestTrigger": "PullRequestTrigger",
+    "GitHub::Actions::PullRequestTargetTrigger": "PullRequestTargetTrigger",
+    "GitHub::Actions::ScheduleTrigger": "ScheduleTrigger",
+    "GitHub::Actions::WorkflowDispatchTrigger": "WorkflowDispatchTrigger",
+    "GitHub::Actions::WorkflowCallTrigger": "WorkflowCallTrigger",
+    "GitHub::Actions::WorkflowRunTrigger": "WorkflowRunTrigger",
+    "GitHub::Actions::RepositoryDispatchTrigger": "RepositoryDispatchTrigger",
+    "GitHub::Actions::WorkflowInput": "WorkflowInput",
+    "GitHub::Actions::WorkflowOutput": "WorkflowOutput",
+    "GitHub::Actions::WorkflowSecret": "WorkflowSecret",
+  },
+  priorityAliases: {},
+  priorityPropertyAliases: {},
+  serviceAbbreviations: {},
+  shortName: githubShortName,
+  serviceName: githubServiceName,
+};
+
+/**
+ * GitHub Actions naming strategy.
+ */
+export class NamingStrategy extends CoreNamingStrategy {
+  constructor(results: GitHubParseResult[]) {
+    const inputs: NamingInput[] = results.map((r) => ({
+      typeName: r.resource.typeName,
+      propertyTypes: r.propertyTypes,
+    }));
+    super(inputs, githubNamingConfig);
+  }
+}

package/src/codegen/package.ts

@@ -0,0 +1,65 @@
+/**
+ * GitHub Actions lexicon packaging — delegates to core packagePipeline.
+ */
+
+import { createRequire } from "module";
+import { readFileSync } from "fs";
+const require = createRequire(import.meta.url);
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import type { IntrinsicDef } from "@intentius/chant/lexicon";
+import {
+  packagePipeline,
+  collectSkills,
+  type PackageOptions,
+  type PackageResult,
+} from "@intentius/chant/codegen/package";
+import { generate } from "./generate";
+
+export type { PackageOptions, PackageResult };
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/**
+ * Package the GitHub Actions lexicon into a distributable BundleSpec.
+ */
+export async function packageLexicon(opts: PackageOptions = {}): Promise<PackageResult> {
+  const pkgJson = JSON.parse(readFileSync(join(pkgDir, "..", "package.json"), "utf-8"));
+
+  return packagePipeline(
+    {
+      generate: (genOpts) => generate({ verbose: genOpts.verbose, force: genOpts.force }),
+
+      buildManifest: (_genResult) => {
+        const intrinsics: IntrinsicDef[] = [
+          {
+            name: "expression",
+            description: "${{ }} expression wrapper for GitHub Actions contexts",
+            outputKey: "expression",
+            isTag: false,
+          },
+        ];
+
+        return {
+          name: "github",
+          version: pkgJson.version ?? "0.0.0",
+          chantVersion: ">=0.1.0",
+          namespace: "GitHub",
+          intrinsics,
+          pseudoParameters: {},
+        };
+      },
+
+      srcDir: pkgDir,
+
+      collectSkills: () => {
+        const { githubPlugin } = require("../plugin");
+        const skillDefs = githubPlugin.skills?.() ?? [];
+        return collectSkills(skillDefs);
+      },
+
+      version: pkgJson.version ?? "0.0.0",
+    },
+    opts,
+  );
+}