@intentius/chant-lexicon-github 0.0.18

package/src/composites/setup-node.ts

@@ -0,0 +1,26 @@
+import { Composite } from "@intentius/chant";
+
+export interface SetupNodeProps {
+  nodeVersion?: string;
+  registryUrl?: string;
+  cache?: string;
+  cacheFilePath?: string;
+}
+
+export const SetupNode = Composite<SetupNodeProps>((props) => {
+  const withObj: Record<string, string> = {};
+  if (props.nodeVersion !== undefined) withObj["node-version"] = props.nodeVersion;
+  if (props.registryUrl !== undefined) withObj["registry-url"] = props.registryUrl;
+  if (props.cache !== undefined) withObj.cache = props.cache;
+  if (props.cacheFilePath !== undefined) withObj["cache-dependency-path"] = props.cacheFilePath;
+
+  const { createProperty } = require("@intentius/chant/runtime");
+  const StepClass = createProperty("GitHub::Actions::Step", "github");
+  const step = new StepClass({
+    name: "Setup Node.js",
+    uses: "actions/setup-node@v4",
+    ...(Object.keys(withObj).length > 0 ? { with: withObj } : {}),
+  });
+
+  return { step };
+}, "SetupNode");

package/src/composites/setup-python.ts

@@ -0,0 +1,24 @@
+import { Composite } from "@intentius/chant";
+
+export interface SetupPythonProps {
+  pythonVersion?: string;
+  cache?: string;
+  architecture?: string;
+}
+
+export const SetupPython = Composite<SetupPythonProps>((props) => {
+  const withObj: Record<string, string> = {};
+  if (props.pythonVersion !== undefined) withObj["python-version"] = props.pythonVersion;
+  if (props.cache !== undefined) withObj.cache = props.cache;
+  if (props.architecture !== undefined) withObj.architecture = props.architecture;
+
+  const { createProperty } = require("@intentius/chant/runtime");
+  const StepClass = createProperty("GitHub::Actions::Step", "github");
+  const step = new StepClass({
+    name: "Setup Python",
+    uses: "actions/setup-python@v5",
+    ...(Object.keys(withObj).length > 0 ? { with: withObj } : {}),
+  });
+
+  return { step };
+}, "SetupPython");

package/src/composites/upload-artifact.ts

@@ -0,0 +1,27 @@
+import { Composite } from "@intentius/chant";
+
+export interface UploadArtifactProps {
+  name: string;
+  path: string;
+  retentionDays?: number;
+  compressionLevel?: number;
+}
+
+export const UploadArtifact = Composite<UploadArtifactProps>((props) => {
+  const withObj: Record<string, string> = {
+    name: props.name,
+    path: props.path,
+  };
+  if (props.retentionDays !== undefined) withObj["retention-days"] = String(props.retentionDays);
+  if (props.compressionLevel !== undefined) withObj["compression-level"] = String(props.compressionLevel);
+
+  const { createProperty } = require("@intentius/chant/runtime");
+  const StepClass = createProperty("GitHub::Actions::Step", "github");
+  const step = new StepClass({
+    name: "Upload Artifact",
+    uses: "actions/upload-artifact@v4",
+    with: withObj,
+  });
+
+  return { step };
+}, "UploadArtifact");

package/src/coverage.ts

@@ -0,0 +1,49 @@
+/**
+ * Coverage analysis for GitHub Actions lexicon.
+ */
+
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import {
+  computeCoverage,
+  overallPct,
+  formatSummary,
+  formatVerbose,
+  checkThresholds,
+  type CoverageReport,
+  type CoverageThresholds,
+} from "@intentius/chant/codegen/coverage";
+
+export type { CoverageReport, CoverageThresholds };
+export { computeCoverage, overallPct, formatSummary, formatVerbose, checkThresholds };
+
+/**
+ * Run coverage analysis for the GitHub Actions lexicon.
+ */
+export async function analyzeGitHubCoverage(opts?: {
+  basePath?: string;
+  verbose?: boolean;
+  minOverall?: number;
+}): Promise<CoverageReport> {
+  const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+  const lexiconPath = join(basePath, "src", "generated", "lexicon-github.json");
+  const content = readFileSync(lexiconPath, "utf-8");
+  const report = computeCoverage(content);
+
+  if (opts?.verbose) {
+    console.error(formatVerbose(report));
+  } else {
+    console.error(formatSummary(report));
+  }
+
+  if (typeof opts?.minOverall === "number") {
+    const result = checkThresholds(report, { minOverallPct: opts.minOverall });
+    if (!result.ok) {
+      for (const v of result.violations) console.error(`  FAIL: ${v}`);
+      throw new Error("Coverage below threshold");
+    }
+  }
+
+  return report;
+}

package/src/expression.test.ts

@@ -0,0 +1,147 @@
+import { describe, test, expect } from "bun:test";
+import {
+  Expression,
+  github, runner, secrets, matrix, steps, needs, inputs, vars, env,
+  always, failure, success, cancelled,
+  contains, startsWith, toJSON, fromJSON, format,
+  branch, tag,
+} from "./expression";
+
+describe("Expression", () => {
+  test("wraps raw expression in ${{ }}", () => {
+    const expr = new Expression("github.ref");
+    expect(expr.toString()).toBe("${{ github.ref }}");
+  });
+
+  test("raw() returns unwrapped expression", () => {
+    const expr = new Expression("github.sha");
+    expect(expr.raw()).toBe("github.sha");
+  });
+
+  test("toJSON() returns toString()", () => {
+    const expr = new Expression("github.ref");
+    expect(expr.toJSON()).toBe("${{ github.ref }}");
+  });
+
+  test("toYAML() returns toString()", () => {
+    const expr = new Expression("github.ref");
+    expect(expr.toYAML()).toBe("${{ github.ref }}");
+  });
+
+  test("and() combines expressions", () => {
+    const a = new Expression("github.ref == 'refs/heads/main'");
+    const b = new Expression("github.event_name == 'push'");
+    expect(a.and(b).toString()).toBe("${{ github.ref == 'refs/heads/main' && github.event_name == 'push' }}");
+  });
+
+  test("or() combines expressions", () => {
+    const a = new Expression("github.ref == 'refs/heads/main'");
+    const b = new Expression("github.ref == 'refs/heads/develop'");
+    expect(a.or(b).toString()).toBe("${{ github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop' }}");
+  });
+
+  test("not() negates expression", () => {
+    const expr = new Expression("github.event.pull_request.draft");
+    expect(expr.not().toString()).toBe("${{ !(github.event.pull_request.draft) }}");
+  });
+
+  test("eq() creates equality comparison", () => {
+    expect(github.ref.eq("refs/heads/main").toString()).toBe("${{ github.ref == 'refs/heads/main' }}");
+  });
+
+  test("ne() creates inequality comparison", () => {
+    expect(github.ref.ne("refs/heads/main").toString()).toBe("${{ github.ref != 'refs/heads/main' }}");
+  });
+});
+
+describe("Context accessors", () => {
+  test("github context properties", () => {
+    expect(github.ref.toString()).toBe("${{ github.ref }}");
+    expect(github.sha.toString()).toBe("${{ github.sha }}");
+    expect(github.actor.toString()).toBe("${{ github.actor }}");
+    expect(github.repository.toString()).toBe("${{ github.repository }}");
+  });
+
+  test("runner context properties", () => {
+    expect(runner.os.toString()).toBe("${{ runner.os }}");
+    expect(runner.arch.toString()).toBe("${{ runner.arch }}");
+  });
+
+  test("secrets accessor", () => {
+    expect(secrets("DEPLOY_KEY").toString()).toBe("${{ secrets.DEPLOY_KEY }}");
+  });
+
+  test("matrix accessor", () => {
+    expect(matrix("node-version").toString()).toBe("${{ matrix.node-version }}");
+  });
+
+  test("steps accessor", () => {
+    expect(steps("build").outputs("result").toString()).toBe("${{ steps.build.outputs.result }}");
+  });
+
+  test("needs accessor", () => {
+    expect(needs("build").outputs("artifact-path").toString()).toBe("${{ needs.build.outputs.artifact-path }}");
+  });
+
+  test("inputs accessor", () => {
+    expect(inputs("environment").toString()).toBe("${{ inputs.environment }}");
+  });
+
+  test("vars accessor", () => {
+    expect(vars("API_URL").toString()).toBe("${{ vars.API_URL }}");
+  });
+
+  test("env accessor", () => {
+    expect(env("NODE_ENV").toString()).toBe("${{ env.NODE_ENV }}");
+  });
+});
+
+describe("Condition helpers", () => {
+  test("always()", () => {
+    expect(always().toString()).toBe("${{ always() }}");
+  });
+
+  test("failure()", () => {
+    expect(failure().toString()).toBe("${{ failure() }}");
+  });
+
+  test("success()", () => {
+    expect(success().toString()).toBe("${{ success() }}");
+  });
+
+  test("cancelled()", () => {
+    expect(cancelled().toString()).toBe("${{ cancelled() }}");
+  });
+});
+
+describe("Function helpers", () => {
+  test("contains()", () => {
+    expect(contains(github.ref, "main").toString()).toBe("${{ contains(github.ref, 'main') }}");
+  });
+
+  test("startsWith()", () => {
+    expect(startsWith(github.ref, "refs/tags/").toString()).toBe("${{ startsWith(github.ref, 'refs/tags/') }}");
+  });
+
+  test("toJSON()", () => {
+    expect(toJSON(github.event).toString()).toBe("${{ toJSON(github.event) }}");
+  });
+
+  test("fromJSON()", () => {
+    expect(fromJSON(steps("meta").outputs("matrix")).toString()).toBe("${{ fromJSON(steps.meta.outputs.matrix) }}");
+  });
+
+  test("format()", () => {
+    expect(format("{0}-{1}", github.ref, github.sha).toString()).toBe("${{ format('{0}-{1}', github.ref, github.sha) }}");
+  });
+});
+
+describe("Convenience helpers", () => {
+  test("branch()", () => {
+    expect(branch("main").toString()).toBe("${{ github.ref == 'refs/heads/main' }}");
+  });
+
+  test("tag()", () => {
+    expect(tag("v").toString()).toBe("${{ startsWith(github.ref, 'refs/tags/v') }}");
+  });
+});

package/src/expression.ts

@@ -0,0 +1,214 @@
+/**
+ * GitHub Actions expression system.
+ *
+ * Provides a typed Expression class and context accessors for building
+ * ${{ }} expressions in GitHub Actions workflows.
+ */
+
+import { INTRINSIC_MARKER, type Intrinsic } from "@intentius/chant/intrinsic";
+
+/**
+ * A GitHub Actions expression that serializes to `${{ raw }}`.
+ */
+export class Expression implements Intrinsic {
+  readonly [INTRINSIC_MARKER] = true as const;
+  private readonly _raw: string;
+
+  constructor(raw: string) {
+    this._raw = raw;
+  }
+
+  /** The raw expression string without ${{ }} wrapper. */
+  raw(): string {
+    return this._raw;
+  }
+
+  /** Returns the expression wrapped in ${{ }}. */
+  toString(): string {
+    return `\${{ ${this._raw} }}`;
+  }
+
+  toJSON(): string {
+    return this.toString();
+  }
+
+  /** YAML serialization — plain string with ${{ }}. */
+  toYAML(): string {
+    return this.toString();
+  }
+
+  /** Logical AND with another expression. */
+  and(other: Expression): Expression {
+    return new Expression(`${this._raw} && ${other._raw}`);
+  }
+
+  /** Logical OR with another expression. */
+  or(other: Expression): Expression {
+    return new Expression(`${this._raw} || ${other._raw}`);
+  }
+
+  /** Logical NOT of this expression. */
+  not(): Expression {
+    return new Expression(`!(${this._raw})`);
+  }
+
+  /** Equality comparison. */
+  eq(value: string | Expression): Expression {
+    const rhs = value instanceof Expression ? value._raw : `'${value}'`;
+    return new Expression(`${this._raw} == ${rhs}`);
+  }
+
+  /** Inequality comparison. */
+  ne(value: string | Expression): Expression {
+    const rhs = value instanceof Expression ? value._raw : `'${value}'`;
+    return new Expression(`${this._raw} != ${rhs}`);
+  }
+}
+
+// ── Context accessors ─────────────────────────────────────────────
+
+/** GitHub context — github.* properties. */
+export const github = {
+  get ref() { return new Expression("github.ref"); },
+  get sha() { return new Expression("github.sha"); },
+  get actor() { return new Expression("github.actor"); },
+  get repository() { return new Expression("github.repository"); },
+  get repositoryOwner() { return new Expression("github.repository_owner"); },
+  get event() { return new Expression("github.event"); },
+  get eventName() { return new Expression("github.event_name"); },
+  get runId() { return new Expression("github.run_id"); },
+  get runNumber() { return new Expression("github.run_number"); },
+  get workflow() { return new Expression("github.workflow"); },
+  get workspace() { return new Expression("github.workspace"); },
+  get token() { return new Expression("github.token"); },
+  get job() { return new Expression("github.job"); },
+  get refName() { return new Expression("github.ref_name"); },
+  get refType() { return new Expression("github.ref_type"); },
+  get headRef() { return new Expression("github.head_ref"); },
+  get baseRef() { return new Expression("github.base_ref"); },
+  get serverUrl() { return new Expression("github.server_url"); },
+  get apiUrl() { return new Expression("github.api_url"); },
+  get graphqlUrl() { return new Expression("github.graphql_url"); },
+  get action() { return new Expression("github.action"); },
+  get actionPath() { return new Expression("github.action_path"); },
+  get triggeringActor() { return new Expression("github.triggering_actor"); },
+} as const;
+
+/** Runner context — runner.* properties. */
+export const runner = {
+  get os() { return new Expression("runner.os"); },
+  get arch() { return new Expression("runner.arch"); },
+  get temp() { return new Expression("runner.temp"); },
+  get toolCache() { return new Expression("runner.tool_cache"); },
+  get name() { return new Expression("runner.name"); },
+} as const;
+
+/** Access a secret by name. */
+export function secrets(name: string): Expression {
+  return new Expression(`secrets.${name}`);
+}
+
+/** Access a matrix value by key. */
+export function matrix(key: string): Expression {
+  return new Expression(`matrix.${key}`);
+}
+
+/** Access a step output. */
+export function steps(id: string): { outputs(name: string): Expression } {
+  return {
+    outputs(name: string): Expression {
+      return new Expression(`steps.${id}.outputs.${name}`);
+    },
+  };
+}
+
+/** Access a job output from a needed job. */
+export function needs(job: string): { outputs(name: string): Expression } {
+  return {
+    outputs(name: string): Expression {
+      return new Expression(`needs.${job}.outputs.${name}`);
+    },
+  };
+}
+
+/** Access a workflow input. */
+export function inputs(name: string): Expression {
+  return new Expression(`inputs.${name}`);
+}
+
+/** Access a configuration variable. */
+export function vars(name: string): Expression {
+  return new Expression(`vars.${name}`);
+}
+
+/** Access an environment variable. */
+export function env(name: string): Expression {
+  return new Expression(`env.${name}`);
+}
+
+// ── Condition helpers ─────────────────────────────────────────────
+
+/** Always run, regardless of status. */
+export function always(): Expression {
+  return new Expression("always()");
+}
+
+/** Run only if a previous step has failed. */
+export function failure(): Expression {
+  return new Expression("failure()");
+}
+
+/** Run only if all previous steps succeeded (default). */
+export function success(): Expression {
+  return new Expression("success()");
+}
+
+/** Run only if the workflow was cancelled. */
+export function cancelled(): Expression {
+  return new Expression("cancelled()");
+}
+
+// ── Function helpers ──────────────────────────────────────────────
+
+/** Check if a string contains a substring. */
+export function contains(haystack: Expression | string, needle: Expression | string): Expression {
+  const h = haystack instanceof Expression ? haystack.raw() : `'${haystack}'`;
+  const n = needle instanceof Expression ? needle.raw() : `'${needle}'`;
+  return new Expression(`contains(${h}, ${n})`);
+}
+
+/** Check if a string starts with a prefix. */
+export function startsWith(value: Expression | string, prefix: Expression | string): Expression {
+  const v = value instanceof Expression ? value.raw() : `'${value}'`;
+  const p = prefix instanceof Expression ? prefix.raw() : `'${prefix}'`;
+  return new Expression(`startsWith(${v}, ${p})`);
+}
+
+/** Convert a value to JSON. */
+export function toJSON(value: Expression): Expression {
+  return new Expression(`toJSON(${value.raw()})`);
+}
+
+/** Parse a JSON string. */
+export function fromJSON(json: Expression | string): Expression {
+  const j = json instanceof Expression ? json.raw() : `'${json}'`;
+  return new Expression(`fromJSON(${j})`);
+}
+
+/** Format a string with placeholders. */
+export function format(template: string, ...args: Expression[]): Expression {
+  const argStrs = args.map((a) => a.raw()).join(", ");
+  return new Expression(`format('${template}', ${argStrs})`);
+}
+
+// ── Convenience helpers ───────────────────────────────────────────
+
+/** Check if the ref matches a branch name. */
+export function branch(name: string): Expression {
+  return github.ref.eq(`refs/heads/${name}`);
+}
+
+/** Check if the ref matches a tag prefix. */
+export function tag(name: string): Expression {
+  return startsWith(github.ref, `refs/tags/${name}`);
+}