@intentius/chant-lexicon-github 0.0.18

package/dist/rules/job-timeout.ts

@@ -0,0 +1,59 @@
+/**
+ * GHA014: Job Timeout
+ *
+ * Flags `new Job({...})` without `timeoutMinutes` property.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+export const jobTimeoutRule: LintRule = {
+  id: "GHA014",
+  severity: "warning",
+  category: "correctness",
+  description: "Job should specify a timeout-minutes value",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      if (ts.isNewExpression(node)) {
+        let isJob = false;
+        if (ts.isIdentifier(node.expression) && node.expression.text === "Job") isJob = true;
+        if (ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "Job") isJob = true;
+
+        if (isJob && node.arguments?.length) {
+          const arg = node.arguments[0];
+          if (ts.isObjectLiteralExpression(arg)) {
+            const hasTimeout = arg.properties.some((prop) => {
+              if (ts.isPropertyAssignment(prop)) {
+                const name = ts.isIdentifier(prop.name) ? prop.name.text
+                  : ts.isStringLiteral(prop.name) ? prop.name.text
+                  : "";
+                return name === "timeoutMinutes" || name === "timeout-minutes";
+              }
+              return false;
+            });
+
+            if (!hasTimeout) {
+              const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+              diagnostics.push({
+                file: sourceFile.fileName,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "GHA014",
+                severity: "warning",
+                message: "Job should specify timeoutMinutes. Default is 360 (6 hours), which may be excessive.",
+              });
+            }
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/rules/missing-recommended-inputs.ts

@@ -0,0 +1,61 @@
+/**
+ * GHA010: Missing Recommended Inputs
+ *
+ * Flags setup action composites without version-related inputs.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+import { recommendedInputs } from "./data/recommended-inputs";
+
+const SETUP_ACTIONS = new Set(Object.keys(recommendedInputs));
+
+export const missingRecommendedInputsRule: LintRule = {
+  id: "GHA010",
+  severity: "warning",
+  category: "correctness",
+  description: "Setup action composite should specify a version input",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      // Match: SetupNode({...}), SetupGo({...}), SetupPython({...})
+      if (ts.isCallExpression(node)) {
+        let actionName: string | null = null;
+
+        if (ts.isIdentifier(node.expression) && SETUP_ACTIONS.has(node.expression.text)) {
+          actionName = node.expression.text;
+        }
+
+        if (actionName && node.arguments.length > 0) {
+          const arg = node.arguments[0];
+          if (ts.isObjectLiteralExpression(arg)) {
+            const required = recommendedInputs[actionName] ?? [];
+            const propNames = arg.properties
+              .filter(ts.isPropertyAssignment)
+              .map((p) => (ts.isIdentifier(p.name) ? p.name.text : ""));
+
+            const hasAny = required.some((r) => propNames.includes(r));
+            if (!hasAny) {
+              const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+              diagnostics.push({
+                file: sourceFile.fileName,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "GHA010",
+                severity: "warning",
+                message: `${actionName}() should specify a version input (${required.join(" or ")}).`,
+              });
+            }
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/rules/no-hardcoded-secrets.ts

@@ -0,0 +1,46 @@
+/**
+ * GHA003: No Hardcoded Secrets
+ *
+ * Flags string literals matching GitHub token prefixes.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+const TOKEN_PREFIXES = ["ghp_", "ghs_", "ghu_", "ghr_", "gho_", "github_pat_"];
+
+export const noHardcodedSecretsRule: LintRule = {
+  id: "GHA003",
+  severity: "error",
+  category: "security",
+  description: "No hardcoded GitHub tokens in source code",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+        const text = node.text;
+        for (const prefix of TOKEN_PREFIXES) {
+          if (text.includes(prefix)) {
+            const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+            diagnostics.push({
+              file: sourceFile.fileName,
+              line: line + 1,
+              column: character + 1,
+              ruleId: "GHA003",
+              severity: "error",
+              message: `Hardcoded GitHub token detected (prefix: ${prefix}). Use secrets() instead.`,
+            });
+            break;
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/rules/no-raw-expressions.ts

@@ -0,0 +1,51 @@
+/**
+ * GHA008: No Raw Expressions
+ *
+ * Flags `${{` strings outside valid context paths.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+const VALID_CONTEXTS = ["github.", "secrets.", "matrix.", "steps.", "needs.", "inputs.", "env.", "vars.", "runner.", "always()", "failure()", "success()", "cancelled()", "contains(", "startsWith(", "endsWith(", "format(", "join(", "toJSON(", "fromJSON(", "hashFiles("];
+
+export const noRawExpressionsRule: LintRule = {
+  id: "GHA008",
+  severity: "info",
+  category: "style",
+  description: "Avoid raw ${{ }} expression strings — use typed Expression helpers",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+        const text = node.text;
+        if (text.includes("${{")) {
+          // Extract the expression content
+          const match = text.match(/\$\{\{\s*(.+?)\s*\}\}/);
+          if (match) {
+            const expr = match[1];
+            const isValid = VALID_CONTEXTS.some((ctx) => expr.startsWith(ctx));
+            if (!isValid) {
+              const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+              diagnostics.push({
+                file: sourceFile.fileName,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "GHA008",
+                severity: "info",
+                message: `Raw expression "$\{{ ${expr} }}" doesn't match a known context. Use typed Expression helpers.`,
+              });
+            }
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/rules/suggest-cache.ts

@@ -0,0 +1,71 @@
+/**
+ * GHA015: Suggest Cache
+ *
+ * Flags setup action composites in steps without a corresponding Cache composite.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+const setupActionsNeedingCache = new Set(["SetupNode", "SetupGo", "SetupPython"]);
+
+export const suggestCacheRule: LintRule = {
+  id: "GHA015",
+  severity: "warning",
+  category: "performance",
+  description: "Setup action should be paired with a Cache composite for faster builds",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      // Look for steps array with setup actions but no Cache
+      if (
+        ts.isPropertyAssignment(node) &&
+        ts.isIdentifier(node.name) &&
+        node.name.text === "steps" &&
+        ts.isArrayLiteralExpression(node.initializer)
+      ) {
+        const elements = node.initializer.elements;
+        let hasSetup = false;
+        let setupName = "";
+        let hasCache = false;
+
+        for (const el of elements) {
+          if (ts.isCallExpression(el)) {
+            const name = ts.isIdentifier(el.expression) ? el.expression.text : "";
+            if (setupActionsNeedingCache.has(name)) {
+              hasSetup = true;
+              setupName = name;
+              // Check if the setup action already has cache in its props
+              if (el.arguments.length > 0 && ts.isObjectLiteralExpression(el.arguments[0])) {
+                const hasCacheProp = el.arguments[0].properties.some(
+                  (p) => ts.isPropertyAssignment(p) && ts.isIdentifier(p.name) && p.name.text === "cache",
+                );
+                if (hasCacheProp) hasCache = true;
+              }
+            }
+            if (name === "Cache") hasCache = true;
+          }
+        }
+
+        if (hasSetup && !hasCache) {
+          const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+          diagnostics.push({
+            file: sourceFile.fileName,
+            line: line + 1,
+            column: character + 1,
+            ruleId: "GHA015",
+            severity: "warning",
+            message: `${setupName}() found without Cache. Add a Cache() step or use the built-in cache option for faster builds.`,
+          });
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/rules/use-condition-builders.ts

@@ -0,0 +1,45 @@
+/**
+ * GHA002: Use Condition Builders
+ *
+ * Flags string literals containing `${{` in `if` property assignments
+ * inside Job/Step constructors. Suggests using Expression helpers.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+export const useConditionBuildersRule: LintRule = {
+  id: "GHA002",
+  severity: "warning",
+  category: "style",
+  description: "Use Expression helpers instead of raw ${{ }} strings in if conditions",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      if (
+        ts.isPropertyAssignment(node) &&
+        ts.isIdentifier(node.name) &&
+        node.name.text === "if" &&
+        ts.isStringLiteral(node.initializer) &&
+        node.initializer.text.includes("${{")
+      ) {
+        const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+        diagnostics.push({
+          file: sourceFile.fileName,
+          line: line + 1,
+          column: character + 1,
+          ruleId: "GHA002",
+          severity: "warning",
+          message: "Use typed Expression helpers (e.g., github.ref.eq('refs/heads/main')) instead of raw ${{ }} strings.",
+        });
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/rules/use-matrix-builder.ts

@@ -0,0 +1,44 @@
+/**
+ * GHA004: Use Matrix Builder
+ *
+ * Flags inline object literals in `matrix` property. Suggests extracting
+ * to a named const for reusability and clarity.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+export const useMatrixBuilderRule: LintRule = {
+  id: "GHA004",
+  severity: "info",
+  category: "style",
+  description: "Extract inline matrix objects to named constants",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      if (
+        ts.isPropertyAssignment(node) &&
+        ts.isIdentifier(node.name) &&
+        node.name.text === "matrix" &&
+        ts.isObjectLiteralExpression(node.initializer)
+      ) {
+        const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+        diagnostics.push({
+          file: sourceFile.fileName,
+          line: line + 1,
+          column: character + 1,
+          ruleId: "GHA004",
+          severity: "info",
+          message: "Consider extracting inline matrix to a named constant for clarity.",
+        });
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/rules/use-typed-actions.ts

@@ -0,0 +1,47 @@
+/**
+ * GHA001: Use Typed Action Composites
+ *
+ * Flags raw `uses:` string literals when a matching typed composite exists.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+import { knownActions } from "./data/known-actions";
+
+export const useTypedActionsRule: LintRule = {
+  id: "GHA001",
+  severity: "warning",
+  category: "style",
+  description: "Use typed action composite instead of raw uses: string",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && node.name.text === "uses") {
+        if (ts.isStringLiteral(node.initializer)) {
+          const value = node.initializer.text;
+          // Extract action name without version: "actions/checkout@v4" → "actions/checkout"
+          const actionName = value.split("@")[0];
+          const match = knownActions[actionName];
+          if (match) {
+            const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+            diagnostics.push({
+              file: sourceFile.fileName,
+              line: line + 1,
+              column: character + 1,
+              ruleId: "GHA001",
+              severity: "warning",
+              message: `Use the typed ${match.composite}() composite instead of raw "${value}" string.`,
+            });
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/rules/validate-concurrency.ts

@@ -0,0 +1,66 @@
+/**
+ * GHA016: Validate Concurrency
+ *
+ * Flags `new Concurrency({cancelInProgress: true})` without `group`.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+export const validateConcurrencyRule: LintRule = {
+  id: "GHA016",
+  severity: "warning",
+  category: "correctness",
+  description: "Concurrency with cancel-in-progress should specify a group",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      if (ts.isNewExpression(node)) {
+        let isConcurrency = false;
+        if (ts.isIdentifier(node.expression) && node.expression.text === "Concurrency") isConcurrency = true;
+        if (ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "Concurrency") isConcurrency = true;
+
+        if (isConcurrency && node.arguments?.length) {
+          const arg = node.arguments[0];
+          if (ts.isObjectLiteralExpression(arg)) {
+            let hasCancelInProgress = false;
+            let hasGroup = false;
+
+            for (const prop of arg.properties) {
+              if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+                if (prop.name.text === "cancelInProgress" || prop.name.text === "cancel-in-progress") {
+                  // Check if it's set to true
+                  if (prop.initializer.kind === ts.SyntaxKind.TrueKeyword) {
+                    hasCancelInProgress = true;
+                  }
+                }
+                if (prop.name.text === "group") {
+                  hasGroup = true;
+                }
+              }
+            }
+
+            if (hasCancelInProgress && !hasGroup) {
+              const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+              diagnostics.push({
+                file: sourceFile.fileName,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "GHA016",
+                severity: "warning",
+                message: "Concurrency with cancel-in-progress should specify a group to avoid cancelling unrelated runs.",
+              });
+            }
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/rules/yaml-helpers.ts

@@ -0,0 +1,129 @@
+/**
+ * Helpers for parsing serialized GitHub Actions YAML in post-synth checks.
+ */
+
+export { getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+
+export interface ParsedJob {
+  name: string;
+  needs?: string[];
+  steps?: Array<{ uses?: string; run?: string; name?: string }>;
+  permissions?: Record<string, string>;
+}
+
+/**
+ * Extract jobs from a serialized GitHub Actions workflow YAML.
+ */
+export function extractJobs(yaml: string): Map<string, ParsedJob> {
+  const jobs = new Map<string, ParsedJob>();
+
+  // Find the jobs: section — take everything after `jobs:\n`
+  const jobsIdx = yaml.search(/^jobs:\s*$/m);
+  if (jobsIdx === -1) return jobs;
+
+  // Content after the `jobs:` line. Stop at the next top-level key (non-indented) or EOF.
+  const afterJobs = yaml.slice(jobsIdx + yaml.slice(jobsIdx).indexOf("\n") + 1);
+  const endMatch = afterJobs.search(/^[a-z]/m);
+  const jobsContent = endMatch === -1 ? afterJobs : afterJobs.slice(0, endMatch);
+
+  // Split into individual jobs by finding lines with exactly 2 spaces of indent followed by a key
+  const jobSections = jobsContent.split(/\n(?=  [a-z][a-z0-9-]*:)/);
+
+  for (const section of jobSections) {
+    const nameMatch = section.match(/^\s{2}([a-z][a-z0-9-]*):/);
+    if (!nameMatch) continue;
+
+    const name = nameMatch[1];
+    const job: ParsedJob = { name };
+
+    // Extract needs
+    const needsInline = section.match(/^\s{4}needs:\s+\[(.+)\]$/m);
+    if (needsInline) {
+      job.needs = needsInline[1].split(",").map((s) => s.trim().replace(/^'|'$/g, "").replace(/^"|"$/g, ""));
+    } else {
+      const needsList = section.match(/^\s{4}needs:\n((?:\s{6}- .+\n?)+)/m);
+      if (needsList) {
+        job.needs = [];
+        for (const line of needsList[1].split("\n")) {
+          const item = line.match(/^\s{6}- (.+)$/);
+          if (item) job.needs.push(item[1].trim().replace(/^'|'$/g, "").replace(/^"|"$/g, ""));
+        }
+      }
+    }
+
+    // Extract steps with uses:
+    const stepsMatch = section.match(/^\s{4}steps:\n([\s\S]*?)(?=\n\s{4}[a-z]|\n\s{2}[a-z]|$)/m);
+    if (stepsMatch) {
+      job.steps = [];
+      const stepEntries = stepsMatch[1].split(/\n(?=\s{6}- )/);
+      for (const stepEntry of stepEntries) {
+        const usesMatch = stepEntry.match(/uses:\s+(.+)$/m);
+        const runMatch = stepEntry.match(/run:\s+(.+)$/m);
+        const stepNameMatch = stepEntry.match(/name:\s+(.+)$/m);
+        if (usesMatch || runMatch) {
+          job.steps.push({
+            uses: usesMatch?.[1]?.trim().replace(/^'|'$/g, ""),
+            run: runMatch?.[1]?.trim(),
+            name: stepNameMatch?.[1]?.trim().replace(/^'|'$/g, ""),
+          });
+        }
+      }
+    }
+
+    jobs.set(name, job);
+  }
+
+  return jobs;
+}
+
+/**
+ * Extract trigger events from the YAML.
+ */
+export function extractTriggers(yaml: string): Record<string, unknown> {
+  const onMatch = yaml.match(/^on:\n([\s\S]*?)(?=\n[a-z]|$)/m);
+  if (!onMatch) return {};
+
+  const triggers: Record<string, unknown> = {};
+  const lines = onMatch[1].split("\n");
+  for (const line of lines) {
+    const triggerMatch = line.match(/^\s{2}([a-z_]+):/);
+    if (triggerMatch) {
+      triggers[triggerMatch[1]] = true;
+    }
+  }
+  return triggers;
+}
+
+/**
+ * Check if any step in the list uses a checkout action.
+ */
+export function hasCheckoutAction(steps: Array<{ uses?: string }>): boolean {
+  return steps.some((s) => s.uses?.startsWith("actions/checkout"));
+}
+
+/**
+ * Build a needs dependency graph from the YAML.
+ */
+export function buildNeedsGraph(yaml: string): Map<string, string[]> {
+  const jobs = extractJobs(yaml);
+  const graph = new Map<string, string[]>();
+  for (const [name, job] of jobs) {
+    graph.set(name, job.needs ?? []);
+  }
+  return graph;
+}
+
+/**
+ * Extract the workflow name from the YAML.
+ */
+export function extractWorkflowName(yaml: string): string | undefined {
+  const match = yaml.match(/^name:\s+(.+)$/m);
+  return match?.[1]?.trim().replace(/^'|'$/g, "");
+}
+
+/**
+ * Check if the YAML has an explicit permissions block.
+ */
+export function hasPermissions(yaml: string): boolean {
+  return /^permissions:/m.test(yaml);
+}

package/dist/skills/chant-github.md

@@ -0,0 +1,29 @@
+---
+skill: chant-github
+description: Build, validate, and deploy GitHub Actions workflows from a chant project
+user-invocable: true
+---
+
+# GitHub Actions Operational Playbook
+
+## How chant and GitHub Actions relate
+
+chant is a **synthesis-only** tool — it compiles TypeScript source files into `.github/workflows/*.yml` (YAML). chant does NOT call GitHub APIs.
+
+- Use **chant** for: build, lint, diff (local YAML comparison)
+- Use **git + GitHub** for: push, pull requests, workflow monitoring
+
+## Build and validate
+
+```bash
+chant build src/ --output .github/workflows/ci.yml
+chant lint src/
+```
+
+## Deploy
+
+```bash
+git add .github/workflows/ci.yml
+git commit -m "Update workflow"
+git push
+```