@intentius/chant-lexicon-github 0.49.0 → 0.50.0

package/src/lint/post-synth/gha067.ts

@@ -0,0 +1,76 @@
+/**
+ * GHA067: Unconditional Heavy Step With No Path Filter
+ *
+ * Flags a `docker build`/`docker buildx build` step that has no `if:` guard,
+ * in a workflow that triggers on `push`/`pull_request` with no `paths:` or
+ * `paths-ignore:` filter. A docs-only or unrelated change still pays for a
+ * full image build because nothing scopes the trigger or guards the step.
+ * Efficiency (#444), not a correctness or security issue.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseDoc, jobEntries } from "./yaml-helpers";
+
+const DOCKER_BUILD_RE = /\bdocker(\s+buildx)?\s+build\b/i;
+
+function triggerObject(on: unknown, key: string): Record<string, unknown> | undefined {
+  if (!on || typeof on !== "object" || Array.isArray(on)) return undefined;
+  const trig = (on as Record<string, unknown>)[key];
+  return trig && typeof trig === "object" && !Array.isArray(trig) ? (trig as Record<string, unknown>) : undefined;
+}
+
+function hasPushOrPRTrigger(on: unknown): boolean {
+  if (typeof on === "string") return on === "push" || on === "pull_request";
+  if (Array.isArray(on)) return on.includes("push") || on.includes("pull_request");
+  if (on && typeof on === "object") {
+    const keys = Object.keys(on as Record<string, unknown>);
+    return keys.includes("push") || keys.includes("pull_request");
+  }
+  return false;
+}
+
+function hasPathFilter(on: unknown): boolean {
+  for (const key of ["push", "pull_request"]) {
+    const trig = triggerObject(on, key);
+    if (!trig) continue;
+    if (Array.isArray(trig.paths) && trig.paths.length > 0) return true;
+    if (Array.isArray(trig["paths-ignore"]) && trig["paths-ignore"].length > 0) return true;
+  }
+  return false;
+}
+
+export const gha067: PostSynthCheck = {
+  id: "GHA067",
+  description: "Unconditional docker build with no path filter or guard",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const doc = parseDoc(yaml);
+      if (!doc) continue;
+      if (!hasPushOrPRTrigger(doc.on)) continue;
+      if (hasPathFilter(doc.on)) continue;
+
+      for (const [jobName, jobObj] of jobEntries(yaml)) {
+        const steps = Array.isArray(jobObj.steps) ? (jobObj.steps as Array<Record<string, unknown>>) : [];
+        for (const step of steps) {
+          const run = typeof step.run === "string" ? step.run : undefined;
+          if (!run || !DOCKER_BUILD_RE.test(run)) continue;
+          if (step.if !== undefined) continue; // already guarded
+
+          diagnostics.push({
+            checkId: "GHA067",
+            severity: "info",
+            message: `Job "${jobName}" runs a Docker build on every push/pull_request with no \`paths:\`/\`paths-ignore:\` filter and no \`if:\` guard — unrelated changes (docs, etc.) still pay for a full image build. Scope the trigger's paths or add a guard.`,
+            entity: jobName,
+            lexicon: "github",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/gha068.test.ts

@@ -0,0 +1,71 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { gha068 } from "./gha068";
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["github", yaml]]),
+    entities: new Map(),
+    buildResult: { outputs: new Map([["github", yaml]]), entities: new Map(), warnings: [], errors: [], sourceFileCount: 1 },
+  };
+}
+
+describe("GHA068: pull-request workflow missing a concurrency group", () => {
+  test("flags a pull_request workflow with no concurrency block", () => {
+    const yaml = `name: CI
+on:
+  pull_request: {}
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm test
+`;
+    const diags = gha068.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("GHA068");
+    expect(diags[0].message).toContain("CI");
+  });
+
+  test("does not flag when a concurrency block is present", () => {
+    const yaml = `name: CI
+on:
+  pull_request: {}
+concurrency:
+  group: \${{ github.workflow }}-\${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm test
+`;
+    expect(gha068.check(makeCtx(yaml))).toHaveLength(0);
+  });
+
+  test("does not flag a deploy workflow (covered by GHA024)", () => {
+    const yaml = `name: Deploy
+on:
+  pull_request: {}
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - run: ./deploy.sh
+`;
+    expect(gha068.check(makeCtx(yaml))).toHaveLength(0);
+  });
+
+  test("does not flag a workflow with no pull_request trigger", () => {
+    const yaml = `name: CI
+on:
+  push: {}
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm test
+`;
+    expect(gha068.check(makeCtx(yaml))).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/gha068.ts

@@ -0,0 +1,51 @@
+/**
+ * GHA068: Pull-Request Workflow Missing a Concurrency Group
+ *
+ * Flags a workflow triggered on `pull_request` with no top-level
+ * `concurrency:` block. Without one, a superseded push keeps its old run
+ * going instead of cancelling it, so every commit on a PR pays for the full
+ * pipeline instead of just the latest. Deploy workflows are left to GHA024,
+ * which already covers them (overlapping-deployment risk, not capacity).
+ * Efficiency (#444), not a correctness or security issue.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseDoc, extractJobs, extractWorkflowName } from "./yaml-helpers";
+
+function hasPullRequestTrigger(on: unknown): boolean {
+  if (typeof on === "string") return on === "pull_request";
+  if (Array.isArray(on)) return on.includes("pull_request");
+  if (on && typeof on === "object") return "pull_request" in (on as Record<string, unknown>);
+  return false;
+}
+
+export const gha068: PostSynthCheck = {
+  id: "GHA068",
+  description: "Pull-request workflow missing a concurrency group",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const doc = parseDoc(yaml);
+      if (!doc || !hasPullRequestTrigger(doc.on)) continue;
+
+      const workflowName = extractWorkflowName(yaml) ?? "";
+      const jobNames = [...extractJobs(yaml).keys()];
+      const isDeployWorkflow = /deploy/i.test(workflowName) || jobNames.some((n) => /deploy/i.test(n));
+      if (isDeployWorkflow) continue; // GHA024 already covers deploy workflows
+
+      if (!/^\s*concurrency:/m.test(yaml)) {
+        diagnostics.push({
+          checkId: "GHA068",
+          severity: "info",
+          message: `Workflow${workflowName ? ` "${workflowName}"` : ""} triggers on pull_request with no \`concurrency:\` group — a new push doesn't cancel the superseded run, so every commit on the PR consumes a full run's worth of runner capacity. Add a \`concurrency:\` group with \`cancel-in-progress: true\`.`,
+          lexicon: "github",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/index.ts

@@ -45,6 +45,16 @@ import { gha055 } from "./gha055";
 import { gha056 } from "./gha056";
 import { gha057 } from "./gha057";
 import { gha058 } from "./gha058";
+import { gha059 } from "./gha059";
+import { gha060 } from "./gha060";
+import { gha061 } from "./gha061";
+import { gha062 } from "./gha062";
+import { gha063 } from "./gha063";
+import { gha064 } from "./gha064";
+import { gha065 } from "./gha065";
+import { gha066 } from "./gha066";
+import { gha067 } from "./gha067";
+import { gha068 } from "./gha068";
 
 export const postSynthChecks: PostSynthCheck[] = [
   gha006,
@@ -92,4 +102,14 @@ export const postSynthChecks: PostSynthCheck[] = [
   gha056,
   gha057,
   gha058,
+  gha059,
+  gha060,
+  gha061,
+  gha062,
+  gha063,
+  gha064,
+  gha065,
+  gha066,
+  gha067,
+  gha068,
 ];

package/src/lint/post-synth/yaml-helpers.ts

@@ -172,7 +172,8 @@ export interface ImageRef {
   source: "container" | "service" | "step";
 }
 
-function parseDoc(yaml: string): Record<string, unknown> | undefined {
+/** Parse a workflow YAML into a structured document, tolerant of parse errors. */
+export function parseDoc(yaml: string): Record<string, unknown> | undefined {
   try {
     return parseYAML(yaml);
   } catch {
@@ -180,7 +181,8 @@ function parseDoc(yaml: string): Record<string, unknown> | undefined {
   }
 }
 
-function jobEntries(yaml: string): Array<[string, Record<string, unknown>]> {
+/** Every job in the workflow as `[name, rawJobObject]`, via the structural parser. */
+export function jobEntries(yaml: string): Array<[string, Record<string, unknown>]> {
   const doc = parseDoc(yaml);
   const jobs = doc?.jobs;
   if (!jobs || typeof jobs !== "object") return [];
@@ -193,6 +195,26 @@ function jobEntries(yaml: string): Array<[string, Record<string, unknown>]> {
   return out;
 }
 
+/**
+ * Every step object (raw, as parsed from YAML — `uses`, `with`, `id`, `run`,
+ * `env`, etc.) grouped by owning job. Unlike {@link extractJobs} (which only
+ * lifts `uses`/`run`/`name`), this hands back each step's full object so a
+ * check can read arbitrary keys (`with:` inputs, `id:`) without growing a new
+ * bespoke regex extractor per key. See GHA060.
+ */
+export function extractStepsByJob(yaml: string): Map<string, Array<Record<string, unknown>>> {
+  const out = new Map<string, Array<Record<string, unknown>>>();
+  for (const [job, jobObj] of jobEntries(yaml)) {
+    const steps = jobObj.steps;
+    if (!Array.isArray(steps)) continue;
+    out.set(
+      job,
+      steps.filter((s): s is Record<string, unknown> => !!s && typeof s === "object" && !Array.isArray(s)),
+    );
+  }
+  return out;
+}
+
 /**
  * Extract every `uses:` reference from the workflow — both step-level actions
  * and job-level reusable-workflow calls. Uses the structural YAML parser so
@@ -462,6 +484,19 @@ export function stripUsesComment(uses: string): string {
   return uses.replace(/\s+#.*$/, "").trim();
 }
 
+/**
+ * Extract a `uses:` value's trailing inline comment, if any — the
+ * human-readable version label reviewers rely on when a ref is pinned to an
+ * opaque commit SHA (e.g. `actions/setup-node@1a2b…9a0b # v4.0.2` → `v4.0.2`).
+ * Returns undefined for no comment or an empty (`# ` with nothing after it)
+ * one, since both mean "no annotation" to a reviewer. See GHA059.
+ */
+export function extractUsesComment(rawUses: string): string | undefined {
+  const m = rawUses.match(/\s+#\s*(.*)$/);
+  const comment = m?.[1]?.trim();
+  return comment ? comment : undefined;
+}
+
 export function parseActionUses(rawUses: string): { owner: string; repo: string; slug: string; gitRef: string } | undefined {
   const uses = stripUsesComment(rawUses);
   if (uses.startsWith("./") || uses.startsWith("../") || uses.startsWith("docker://")) return undefined;

package/src/lint/rules/data/action-usage-policy.ts

@@ -0,0 +1,31 @@
+/**
+ * Default action-usage policy for GHA061 — opt-in, so it ships with an empty
+ * allow/deny list: with nothing configured, GHA061 reports nothing (#445
+ * acceptance criteria: "silent when unconfigured").
+ *
+ * `PostSynthContext` carries no per-check runtime config channel today (see
+ * `trusted-action-owners.ts`'s doc for the same constraint), so — like that
+ * file — this is a vendored, code-level default. A project that wants a real
+ * policy doesn't edit this file: it authors a `lint.policies` entry
+ * (`chant.config.ts`'s `lint.policies`, see `packages/core/src/lint/config.ts`)
+ * that imports `evaluateUsagePolicy` from `../../post-synth/gha061` and calls
+ * it with its own `ActionUsagePolicy`, wrapped in a `PostSynthCheck`. That is
+ * the supported opt-in path; this default only documents the "nothing
+ * configured" shape and is what the shipped GHA061 check itself passes.
+ */
+
+/**
+ * An opt-in allow/deny policy over third-party action references.
+ * Entries match an exact `owner/repo` slug, a bare `owner` (every repo under
+ * that owner), or an `owner/*` wildcard (equivalent to a bare owner, offered
+ * for readability). `deny` always wins over `allow` for an entry that somehow
+ * appears in both.
+ */
+export interface ActionUsagePolicy {
+  /** If set, any reference whose owner/slug isn't matched here is flagged. Unset = no allowlist restriction. */
+  allow?: string[];
+  /** Always flagged, regardless of `allow`. */
+  deny?: string[];
+}
+
+export const DEFAULT_ACTION_USAGE_POLICY: ActionUsagePolicy = {};

package/src/lint/rules/data/advisory-feed.ts

@@ -0,0 +1,38 @@
+/**
+ * Default advisory feed for GHA062 — ships empty, so the check degrades to
+ * "no findings" rather than erroring when nothing is supplied (#445
+ * acceptance criteria: "degrades gracefully when the feed is unreachable").
+ *
+ * Per epic #350's design spine, the pure core never fetches: a live feed is
+ * the CALLER's concern (a `chant audit` CLI flag reading a local JSON file,
+ * a pre-fetched structure a hosted service passes in) — never a `fetch()`
+ * inside a rule. This module documents the "nothing supplied" shape and is
+ * what the shipped GHA062 check itself passes; a caller with a real feed
+ * calls `checkAdvisories` (`../../post-synth/gha062`) directly with its own
+ * `AdvisoryFeed`, the same way a `lint.policies` entry supplies GHA061 its
+ * own `ActionUsagePolicy` (see `action-usage-policy.ts`).
+ */
+
+/** One disclosed advisory affecting a pinned action reference. */
+export interface AdvisoryEntry {
+  /** `owner/repo` slug the advisory applies to. */
+  slug: string;
+  /** Affected commit SHA(s) — for SHA-pinned refs. */
+  shas?: string[];
+  /** Affected tag/branch ref(s) — for refs still pinned to a mutable tag. */
+  refs?: string[];
+  /** Advisory identifier (e.g. a GHSA id). */
+  id: string;
+  /** Human-readable summary of the issue. */
+  summary: string;
+  /** A ref/SHA known to be patched, if the feed carries one. */
+  patchedRef?: string;
+  /** Link to the advisory. */
+  url?: string;
+}
+
+export interface AdvisoryFeed {
+  entries: AdvisoryEntry[];
+}
+
+export const DEFAULT_ADVISORY_FEED: AdvisoryFeed = { entries: [] };

package/src/plugin.test.ts

@@ -24,7 +24,7 @@ describe("githubPlugin", () => {
 
   test("provides post-synth checks", () => {
     const checks = githubPlugin.postSynthChecks!();
-    expect(checks.length).toBe(45);
+    expect(checks.length).toBe(55);
 
     const checkIds = checks.map((c) => c.id);
     expect(checkIds).toContain("GHA006");
@@ -85,8 +85,29 @@ describe("githubPlugin", () => {
     // chant #1069 — registered as the `Expression` class (capitalized), the
     // real export of src/index.ts; "expression" (lowercase) was never exported.
     const intrinsics = githubPlugin.intrinsics!();
-    expect(intrinsics.length).toBe(1);
-    expect(intrinsics[0].name).toBe("Expression");
+    expect(intrinsics.find((i) => i.name === "Expression")).toEqual({
+      name: "Expression",
+      description: expect.any(String),
+      outputKey: "expression",
+      isTag: false,
+    });
+
+    // chant #1966 — src/expression.ts's pure context-accessor and condition
+    // helpers, registered `foldsEagerly` rather than `foldsAsCall` (see
+    // ../../../packages/core/src/lexicon.ts's IntrinsicDef.foldsEagerly).
+    const eagerNames = [
+      "secrets", "matrix", "steps", "needs", "inputs", "vars", "env",
+      "always", "failure", "success", "cancelled",
+      "contains", "startsWith", "toJSON", "fromJSON", "format",
+      "branch", "tag",
+    ];
+    for (const name of eagerNames) {
+      const def = intrinsics.find((i) => i.name === name);
+      expect(def, `missing intrinsic registration for "${name}"`).toBeDefined();
+      expect(def!.isTag).toBe(false);
+      expect(def!.foldsEagerly).toBe(true);
+    }
+    expect(intrinsics.length).toBe(1 + eagerNames.length);
   });
 
   test("provides init templates", () => {

package/src/plugin.ts

@@ -32,12 +32,15 @@ import { GitHubActionsParser } from "./import/parser";
 import { GitHubActionsGenerator } from "./import/generator";
 import { githubContextTools } from "./mcp/context-tools";
 import { generateGithubPipeline } from "./components/generate-pipeline";
+import { generateGithubOpPipeline } from "./components/generate-op-pipeline";
 
 export const githubPlugin: LexiconPlugin = {
   name: "github",
   auditCatalog: () => githubAuditCatalog,
   // Generate mode (#891): synthesize a GitHub Actions workflow from the component graph.
   generateComponentPipeline: (components, options) => generateGithubPipeline(components, options),
+  // Generate mode, Op counterpart (#927): synthesize one cron-triggered workflow per scheduled Op.
+  generateOpPipeline: (ops, options) => generateGithubOpPipeline(ops, options),
   serializer: githubSerializer,
 
   lintRules(): LintRule[] {
@@ -70,6 +73,31 @@ export const githubPlugin: LexiconPlugin = {
         outputKey: "expression",
         isTag: false,
       },
+      // chant #1966 — src/expression.ts's context-accessor and condition
+      // helpers, each a pure function of its arguments building an
+      // `Expression` (or, for `steps`/`needs`, a plain object of one).
+      // `foldsEagerly: true` (not `foldsAsCall`) because their usual use is
+      // embedded directly in a template literal (`` `${matrix("os")}` ``),
+      // which needs the real, already-live `Expression` at fold time to
+      // stringify correctly — see IntrinsicDef.foldsEagerly's doc.
+      { name: "secrets", description: "Access a secret by name.", isTag: false, foldsEagerly: true },
+      { name: "matrix", description: "Access a matrix value by key.", isTag: false, foldsEagerly: true },
+      { name: "steps", description: "Access a step output.", isTag: false, foldsEagerly: true },
+      { name: "needs", description: "Access a job output from a needed job.", isTag: false, foldsEagerly: true },
+      { name: "inputs", description: "Access a workflow input.", isTag: false, foldsEagerly: true },
+      { name: "vars", description: "Access a configuration variable.", isTag: false, foldsEagerly: true },
+      { name: "env", description: "Access an environment variable.", isTag: false, foldsEagerly: true },
+      { name: "always", description: "Always run, regardless of status.", isTag: false, foldsEagerly: true },
+      { name: "failure", description: "Run only if a previous step has failed.", isTag: false, foldsEagerly: true },
+      { name: "success", description: "Run only if all previous steps succeeded.", isTag: false, foldsEagerly: true },
+      { name: "cancelled", description: "Run only if the workflow was cancelled.", isTag: false, foldsEagerly: true },
+      { name: "contains", description: "Check if a string contains a substring.", isTag: false, foldsEagerly: true },
+      { name: "startsWith", description: "Check if a string starts with a prefix.", isTag: false, foldsEagerly: true },
+      { name: "toJSON", description: "Convert a value to JSON.", isTag: false, foldsEagerly: true },
+      { name: "fromJSON", description: "Parse a JSON string.", isTag: false, foldsEagerly: true },
+      { name: "format", description: "Format a string with placeholders.", isTag: false, foldsEagerly: true },
+      { name: "branch", description: "Check if the ref matches a branch name.", isTag: false, foldsEagerly: true },
+      { name: "tag", description: "Check if the ref matches a tag prefix.", isTag: false, foldsEagerly: true },
     ];
   },