@intentius/chant-lexicon-github 0.124.31 → 0.124.32

package/dist/action-pins.js

@@ -0,0 +1,53 @@
+/**
+ * The action versions the github lexicon emits, and the commit each release
+ * tag points at.
+ *
+ * Composites emit `<slug>@<major>` by default. With `pin: "sha"` they emit
+ * `<slug>@<sha> # <version>`, the form GHA021 and GHA029 accept and GHA059
+ * reads the version label from. The serializer writes the `# <version>` part
+ * as a YAML comment, so GitHub sees only the SHA.
+ *
+ * Refresh a row by resolving the release tag to its commit:
+ *
+ *   gh api repos/actions/checkout/commits/v7.0.1 --jq .sha
+ *
+ * Keep `major` on a version whose action runs on a Node runtime GitHub still
+ * supports.
+ */
+export const ACTION_PINS = {
+    "actions/checkout": {
+        major: "v7",
+        version: "v7.0.1",
+        sha: "3d3c42e5aac5ba805825da76410c181273ba90b1",
+    },
+    "actions/setup-node": {
+        major: "v7",
+        version: "v7.0.0",
+        sha: "820762786026740c76f36085b0efc47a31fe5020",
+    },
+};
+/** The `uses:` value for a pinned action. */
+export function actionRef(slug, pin = "tag") {
+    const entry = ACTION_PINS[slug];
+    return pin === "sha" ? `${slug}@${entry.sha} # ${entry.version}` : `${slug}@${entry.major}`;
+}
+/** The pin table entry for an action slug, if the lexicon maintains one. */
+export function actionPin(slug) {
+    return Object.prototype.hasOwnProperty.call(ACTION_PINS, slug)
+        ? ACTION_PINS[slug]
+        : undefined;
+}
+const COMPOSITE_FOR = {
+    "actions/checkout": "Checkout",
+    "actions/setup-node": "SetupNode",
+};
+/**
+ * The exact fix a pinning warning names for an action in the pin table, or
+ * an empty string for any other action.
+ */
+export function pinFixHint(slug) {
+    if (!actionPin(slug))
+        return "";
+    const pinned = slug;
+    return ` Use \`uses: ${actionRef(pinned, "sha")}\`, which ${COMPOSITE_FOR[pinned]}({ pin: "sha" }) emits.`;
+}

package/dist/codegen/docs-cli.js

@@ -0,0 +1,2 @@
+import { generateDocs } from "./docs.js";
+await generateDocs({ verbose: true });

package/dist/codegen/docs.js

@@ -0,0 +1,142 @@
+/**
+ * Documentation generation for GitHub Actions lexicon.
+ */
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+function serviceFromType(resourceType) {
+    const parts = resourceType.split("::");
+    return parts.length >= 2 ? parts[1] : "Actions";
+}
+const overview = `The **GitHub Actions** lexicon provides typed constructors for GitHub Actions
+workflow configuration. It covers workflows, jobs, steps, triggers, strategy,
+permissions, concurrency, and more.
+
+Install it with:
+
+\`\`\`bash
+npm install --save-dev @intentius/chant-lexicon-github
+\`\`\`
+
+## Quick Start
+
+{{file:docs-snippets/src/quickstart.ts}}
+
+The lexicon provides **3 resources** (Workflow, Job, Dependabot config), **15 composites** (Checkout, SetupNode, SetupGo, SetupPython, CacheAction, UploadArtifact, DownloadArtifact, NodeCI, NodePipeline, PythonCI, DockerBuild, DeployEnvironment, GoCI, Dependabot, PrPlanReport) + **3 presets** (BunPipeline, PnpmPipeline, YarnPipeline), a typed **Expression** system with 24 GitHub and 5 Runner context variables, and **13 lint rules** + **49 post-synth checks** (including a CI/CD supply-chain security pass, GHA029–062).
+`;
+const outputFormat = `The GitHub Actions lexicon serializes resources into **\`.github/workflows/*.yml\`** YAML files.
+Keys use kebab-case for job properties and snake_case for trigger event names.
+
+## Building
+
+Run \`chant build\` to produce workflow YAML from your declarations:
+
+\`\`\`bash
+chant build src/ --output .github/workflows/ci.yml
+# Or build all workflow files
+chant build
+\`\`\`
+
+The generated file includes:
+
+- \`name:\` — workflow display name
+- \`on:\` — trigger events (push, pull_request, schedule, workflow_dispatch, etc.)
+- \`permissions:\` — workflow-level GITHUB_TOKEN permissions
+- \`jobs:\` — job definitions with kebab-case keys
+
+## Key conversions
+
+| Chant (TypeScript) | YAML output | Rule |
+|--------------------|-------------|------|
+| \`export const buildApp = new Job({...})\` | \`jobs: build-app:\` | Export name → kebab-case job key |
+| \`"runs-on": "ubuntu-latest"\` | \`runs-on: ubuntu-latest\` | Property names match GitHub spec |
+| \`timeoutMinutes: 15\` | \`timeout-minutes: 15\` | camelCase → kebab-case for job properties |
+| \`new Step({ uses: "actions/checkout@v7" })\` | \`- uses: actions/checkout@v7\` | Steps serialize as sequence entries |
+
+## Comments
+
+\`Workflow\`, \`Job\` and \`Step\` take a \`comment\`. It is not a workflow key: the serializer writes it as \`#\` lines, one per line of the string, so the reasons a hand-written workflow keeps as YAML comments stay in the file a reader opens on GitHub. A workflow's comment is the file's header, above \`name:\`; a job's goes above its key and a step's above its \`- \`. The Forgejo lexicon renders the same declarations, so its files carry them too.
+
+\`\`\`typescript
+export const publish = new Workflow({
+  comment: "Publishes on a version tag.\\nKeep the file name: npm's trusted publisher names it.",
+  name: "Publish",
+  on: { push: { tags: ["v*"] } },
+  jobs: {
+    publish: new Job({
+      "runs-on": "ubuntu-latest",
+      steps: [new Step({ comment: "The registry times out now and then; retry once.", run: "npm publish || npm publish" })],
+    }),
+  },
+});
+\`\`\`
+
+\`\`\`yaml
+# Publishes on a version tag.
+# Keep the file name: npm's trusted publisher names it.
+
+name: Publish
+
+on:
+  push:
+    tags:
+      - v*
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      # The registry times out now and then; retry once.
+      - run: npm publish || npm publish
+\`\`\`
+
+## Validating locally
+
+The output is standard GitHub Actions YAML. Validate locally with \`act\` or push to GitHub:
+
+\`\`\`bash
+# Using act for local testing
+act -W .github/workflows/ci.yml
+
+# Using GitHub's workflow validation (requires push)
+git add .github/workflows/ci.yml
+git push
+\`\`\`
+
+## Compatibility
+
+The output is compatible with:
+- GitHub Actions (any GitHub.com or GitHub Enterprise Server)
+- \`act\` local runner
+- VS Code GitHub Actions extension
+- Any tool that processes \`.github/workflows/*.yml\` files`;
+/**
+ * Generate documentation for the GitHub Actions lexicon.
+ */
+export async function generateDocs(opts) {
+    const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const config = {
+        name: "github",
+        displayName: "GitHub Actions",
+        description: "Typed constructors for GitHub Actions workflow configuration",
+        distDir: join(pkgDir, "dist"),
+        outDir: join(pkgDir, "docs"),
+        overview,
+        outputFormat,
+        serviceFromType,
+        suppressPages: ["intrinsics"],
+        examplesDir: join(pkgDir, "examples"),
+        extraSections: [
+            {
+                title: "Migrating to GitLab CI/CD?",
+                content: `The GitLab lexicon ships a typed-compiler migration tool that translates \`.github/workflows/*.yml\` into \`.gitlab-ci.yml\` (or chant TypeScript) with provenance, 33 curated marketplace-action mappings, and optional composite recognition. See [GitLab → Migration from GitHub Actions](/chant/lexicons/gitlab/migration/) or the [\`chant migrate\` CLI reference](/chant/cli/migrate/).`,
+            },
+        ],
+        basePath: "/chant/lexicons/github/",
+    };
+    const result = await docsPipeline(config);
+    writeDocsSite(config, result);
+    if (opts?.verbose) {
+        console.error(`Generated docs: ${result.stats.resources} resources, ${result.stats.properties} properties, ${result.stats.services} services, ${result.stats.rules} rules`);
+    }
+}

package/dist/codegen/generate-cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env tsx
+/**
+ * CLI entry point for GitHub Actions lexicon generation.
+ */
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { generate, writeGeneratedFiles } from "./generate.js";
+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/dist/codegen/generate-lexicon.js

@@ -0,0 +1,36 @@
+/**
+ * Lexicon JSON generator — produces lexicon-github.json with metadata
+ * for all GitHub Actions entities.
+ */
+import { githubShortName } from "./parse.js";
+import { buildRegistry, serializeRegistry, } from "@intentius/chant/codegen/generate-registry";
+/**
+ * Generate the lexicon-github.json content.
+ */
+export function generateLexiconJSON(results, naming) {
+    const registryResources = 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(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"),
+                lexicon: "github",
+                ...(r?.resource.deprecatedProperties?.length && { deprecatedProperties: r.resource.deprecatedProperties }),
+                ...(propConstraints && Object.keys(propConstraints).length > 0 && { constraints: propConstraints }),
+            };
+        },
+        buildPropertyEntry: (resourceType, propertyType) => ({
+            resourceType: `${resourceType}.${propertyType}`,
+            kind: "property",
+            lexicon: "github",
+        }),
+    });
+    return serializeRegistry(entries);
+}

package/dist/codegen/generate-typescript.js

@@ -0,0 +1,108 @@
+/**
+ * TypeScript declaration file generator — produces index.d.ts with all
+ * GitHub Actions entity classes.
+ */
+import { githubShortName } from "./parse.js";
+import { propertyTypeName, extractDefName } from "./naming.js";
+import { writeResourceClass, writeEnumType, } from "@intentius/chant/codegen/generate-typescript";
+/**
+ * Generate the complete .d.ts file content.
+ */
+export function generateTypeScriptDeclarations(results, naming) {
+    const lines = [];
+    lines.push("// Code generated by chant github generate. DO NOT EDIT.");
+    const resources = [];
+    const enums = [];
+    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();
+        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 = r.resource.properties.map((p) => ({
+            name: p.name,
+            type: p.tsType,
+            required: p.required,
+            description: p.description,
+        }));
+        const dtsAttrs = 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() {
+    const lines = [];
+    // 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/dist/codegen/generate.js

@@ -0,0 +1,111 @@
+/**
+ * GitHub Actions generation pipeline — uses core generatePipeline
+ * with GitHub-specific fetch, parse, naming, and generation callbacks.
+ */
+import { generatePipeline, writeGeneratedArtifacts, } from "@intentius/chant/codegen/generate";
+import { fetchSchemas } from "../spec/fetch.js";
+import { parseWorkflowSchema } from "./parse.js";
+import { NamingStrategy, propertyTypeName, extractDefName } from "./naming.js";
+import { githubShortName } from "./parse.js";
+import { generateLexiconJSON } from "./generate-lexicon.js";
+import { generateTypeScriptDeclarations } from "./generate-typescript.js";
+import { generateRuntimeIndex as coreGenerateRuntimeIndex, } from "@intentius/chant/codegen/generate-runtime-index";
+/**
+ * Run the full GitHub Actions generation pipeline.
+ */
+export async function generate(opts = {}) {
+    let pendingResults = [];
+    const config = {
+        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);
+        },
+        generateTypes: (results, naming) => {
+            return generateTypeScriptDeclarations(results, naming);
+        },
+        generateRuntimeIndex: (results, naming) => {
+            return generateRuntimeIndex(results, naming);
+        },
+    };
+    return generatePipeline(config, opts);
+}
+/**
+ * Write generated artifacts to disk.
+ */
+export function writeGeneratedFiles(result, baseDir) {
+    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, naming) {
+    const resourceEntries = [];
+    const propertyEntries = [];
+    for (const r of results) {
+        const typeName = r.resource.typeName;
+        const tsName = naming.resolve(typeName);
+        if (!tsName)
+            continue;
+        const attrs = {};
+        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/dist/codegen/naming.js

@@ -0,0 +1,49 @@
+/**
+ * GitHub Actions naming strategy — flat namespace with few collisions.
+ */
+import { NamingStrategy as CoreNamingStrategy, } from "@intentius/chant/codegen/naming";
+import { githubShortName, githubServiceName } from "./parse.js";
+export { propertyTypeName, extractDefName } from "@intentius/chant/codegen/naming";
+const githubNamingConfig = {
+    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) {
+        const inputs = results.map((r) => ({
+            typeName: r.resource.typeName,
+            propertyTypes: r.propertyTypes,
+        }));
+        super(inputs, githubNamingConfig);
+    }
+}

package/dist/codegen/package.js

@@ -0,0 +1,40 @@
+/**
+ * GitHub Actions lexicon packaging — delegates to core packagePipeline.
+ */
+import { readFileSync } from "fs";
+import { githubPlugin } from "../plugin.js";
+import { join, dirname } from "path";
+import { moduleSourceDir } from "@intentius/chant/module-source";
+import { packagePipeline, collectSkills, } from "@intentius/chant/codegen/package";
+import { generate } from "./generate.js";
+const pkgDir = dirname(moduleSourceDir(import.meta.url));
+/**
+ * Package the GitHub Actions lexicon into a distributable BundleSpec.
+ */
+export async function packageLexicon(opts = {}) {
+    const pkgJson = JSON.parse(readFileSync(join(pkgDir, "..", "package.json"), "utf-8"));
+    return packagePipeline({
+        generate: (genOpts) => generate({ verbose: genOpts.verbose, force: genOpts.force }),
+        buildManifest: (_genResult) => {
+            // Derived from the plugin's own registration (chant #1067) — this
+            // used to be a hand-maintained array independent of ../plugin.ts,
+            // free to drift from the real registration without anything
+            // noticing.
+            const intrinsics = githubPlugin.intrinsics?.() ?? [];
+            return {
+                name: "github",
+                version: pkgJson.version ?? "0.0.0",
+                chantVersion: ">=0.1.0",
+                namespace: "GitHub",
+                intrinsics,
+                pseudoParameters: {},
+            };
+        },
+        srcDir: pkgDir,
+        collectSkills: () => {
+            const skillDefs = githubPlugin.skills?.() ?? [];
+            return collectSkills(skillDefs);
+        },
+        version: pkgJson.version ?? "0.0.0",
+    }, opts);
+}