@intentius/chant-lexicon-github 0.0.18

package/src/lint/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/src/lint/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/src/lint/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/src/lint/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/src/lint/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/src/lsp/completions.test.ts

@@ -0,0 +1,9 @@
+import { describe, test, expect } from "bun:test";
+
+describe("github completions", () => {
+  test("completions module exports githubCompletions", async () => {
+    const mod = await import("./completions");
+    expect(mod.githubCompletions).toBeDefined();
+    expect(typeof mod.githubCompletions).toBe("function");
+  });
+});

package/src/lsp/completions.ts

@@ -0,0 +1,20 @@
+import { createRequire } from "module";
+import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconCompletions, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(import.meta.url);
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-github.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Provide GitHub Actions completions based on context.
+ */
+export function githubCompletions(ctx: CompletionContext): CompletionItem[] {
+  return lexiconCompletions(ctx, getIndex(), "GitHub Actions entity");
+}

package/src/lsp/hover.test.ts

@@ -0,0 +1,9 @@
+import { describe, test, expect } from "bun:test";
+
+describe("github hover", () => {
+  test("hover module exports githubHover", async () => {
+    const mod = await import("./hover");
+    expect(mod.githubHover).toBeDefined();
+    expect(typeof mod.githubHover).toBe("function");
+  });
+});

package/src/lsp/hover.ts

@@ -0,0 +1,38 @@
+import { createRequire } from "module";
+import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconHover, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(import.meta.url);
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-github.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Provide hover information for GitHub Actions entity types.
+ */
+export function githubHover(ctx: HoverContext): HoverInfo | undefined {
+  return lexiconHover(ctx, getIndex(), resourceHover);
+}
+
+function resourceHover(className: string, entry: LexiconEntry): HoverInfo | undefined {
+  const lines: string[] = [];
+
+  lines.push(`**${className}**`);
+  lines.push("");
+  lines.push(`GitHub Actions type: \`${entry.resourceType}\``);
+
+  if (entry.kind === "resource") {
+    lines.push("");
+    lines.push("*Resource entity — serialized as a top-level workflow/job entry*");
+  } else {
+    lines.push("");
+    lines.push("*Property entity — used as a nested value in resources*");
+  }
+
+  return { contents: lines.join("\n") };
+}

package/src/package-cli.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env bun
+/**
+ * Thin entry point for `bun run bundle` in lexicon-github.
+ */
+import { generate, writeGeneratedFiles } from "./codegen/generate";
+import { packageLexicon } from "./codegen/package";
+import { writeFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+// 1. Generate src/generated/ files
+const genResult = await generate({ verbose: true });
+writeGeneratedFiles(genResult, pkgDir);
+console.error(`Generated ${genResult.resources} entities, ${genResult.properties} property types, ${genResult.enums} enums`);
+
+// 2. Run package pipeline and write dist/
+const { spec, stats } = await packageLexicon({ verbose: true });
+
+const distDir = join(pkgDir, "dist");
+mkdirSync(join(distDir, "types"), { recursive: true });
+mkdirSync(join(distDir, "rules"), { recursive: true });
+mkdirSync(join(distDir, "skills"), { recursive: true });
+
+writeFileSync(join(distDir, "manifest.json"), JSON.stringify(spec.manifest, null, 2));
+writeFileSync(join(distDir, "meta.json"), spec.registry);
+writeFileSync(join(distDir, "types", "index.d.ts"), spec.typesDTS);
+
+for (const [name, content] of spec.rules) {
+  writeFileSync(join(distDir, "rules", name), content);
+}
+for (const [name, content] of spec.skills) {
+  writeFileSync(join(distDir, "skills", name), content);
+}
+
+if (spec.integrity) {
+  writeFileSync(join(distDir, "integrity.json"), JSON.stringify(spec.integrity, null, 2));
+}
+
+console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+console.error(`dist/ written to ${distDir}`);

package/src/plugin.test.ts

@@ -0,0 +1,128 @@
+import { describe, test, expect } from "bun:test";
+import { githubPlugin } from "./plugin";
+
+describe("githubPlugin", () => {
+  test("has correct name", () => {
+    expect(githubPlugin.name).toBe("github");
+  });
+
+  test("has serializer", () => {
+    expect(githubPlugin.serializer).toBeDefined();
+    expect(githubPlugin.serializer.name).toBe("github");
+  });
+
+  test("provides lint rules", () => {
+    const rules = githubPlugin.lintRules!();
+    expect(rules.length).toBe(13);
+
+    const ruleIds = rules.map((r) => r.id);
+    expect(ruleIds).toContain("GHA001");
+    expect(ruleIds).toContain("GHA003");
+    expect(ruleIds).toContain("GHA014");
+    expect(ruleIds).toContain("GHA020");
+  });
+
+  test("provides post-synth checks", () => {
+    const checks = githubPlugin.postSynthChecks!();
+    expect(checks.length).toBe(6);
+
+    const checkIds = checks.map((c) => c.id);
+    expect(checkIds).toContain("GHA006");
+    expect(checkIds).toContain("GHA009");
+    expect(checkIds).toContain("GHA011");
+    expect(checkIds).toContain("GHA017");
+    expect(checkIds).toContain("GHA018");
+    expect(checkIds).toContain("GHA019");
+  });
+
+  test("provides intrinsics", () => {
+    const intrinsics = githubPlugin.intrinsics!();
+    expect(intrinsics.length).toBe(1);
+    expect(intrinsics[0].name).toBe("expression");
+  });
+
+  test("provides init templates", () => {
+    const defaultTemplate = githubPlugin.initTemplates!();
+    expect(defaultTemplate.src).toBeDefined();
+    expect(defaultTemplate.src["pipeline.ts"]).toContain("Workflow");
+  });
+
+  test("provides node-ci template", () => {
+    const template = githubPlugin.initTemplates!("node-ci");
+    expect(template.src["pipeline.ts"]).toContain("NodeCI");
+  });
+
+  test("provides docker-build template", () => {
+    const template = githubPlugin.initTemplates!("docker-build");
+    expect(template.src["pipeline.ts"]).toContain("docker");
+  });
+
+  test("detects GitHub Actions template", () => {
+    expect(githubPlugin.detectTemplate!({ on: {}, jobs: {} })).toBe(true);
+  });
+
+  test("detects job-like entries", () => {
+    expect(githubPlugin.detectTemplate!({
+      build: { "runs-on": "ubuntu-latest", steps: [] },
+    })).toBe(true);
+  });
+
+  test("rejects non-GitHub Actions data", () => {
+    expect(githubPlugin.detectTemplate!({ stages: [], image: "node:20" })).toBe(false);
+  });
+
+  test("provides skills", () => {
+    const skills = githubPlugin.skills!();
+    expect(skills.length).toBeGreaterThanOrEqual(1);
+    expect(skills[0].name).toBe("chant-github");
+  });
+
+  test("provides MCP tools", () => {
+    const tools = githubPlugin.mcpTools!();
+    expect(tools.length).toBe(1);
+    expect(tools[0].name).toBe("diff");
+  });
+
+  test("provides MCP resources", () => {
+    const resources = githubPlugin.mcpResources!();
+    expect(resources.length).toBe(2);
+    expect(resources[0].uri).toBe("resource-catalog");
+    expect(resources[1].uri).toBe("examples/basic-ci");
+  });
+
+  test("has completionProvider", () => {
+    expect(githubPlugin.completionProvider).toBeDefined();
+  });
+
+  test("has hoverProvider", () => {
+    expect(githubPlugin.hoverProvider).toBeDefined();
+  });
+
+  test("has templateParser", () => {
+    expect(githubPlugin.templateParser).toBeDefined();
+  });
+
+  test("has templateGenerator", () => {
+    expect(githubPlugin.templateGenerator).toBeDefined();
+  });
+
+  test("has generate method", () => {
+    expect(githubPlugin.generate).toBeDefined();
+  });
+
+  test("has validate method", () => {
+    expect(githubPlugin.validate).toBeDefined();
+  });
+
+  test("has coverage method", () => {
+    expect(githubPlugin.coverage).toBeDefined();
+  });
+
+  test("has package method", () => {
+    expect(githubPlugin.package).toBeDefined();
+  });
+
+  test("has docs method", () => {
+    expect(githubPlugin.docs).toBeDefined();
+  });
+});