@intentius/chant-lexicon-github 0.124.18 → 0.124.19

package/dist/graph-edges.d.ts

@@ -0,0 +1,27 @@
+/**
+ * GitHub Actions dependencies as graph edges (#3910).
+ *
+ * `chant graph` draws an edge for every typed reference it can find, and a
+ * workflow has almost none: a job names the jobs it waits for, the reusable
+ * workflow it calls and the workflows that trigger it as strings. This module
+ * resolves those strings against the declared entities, the way the
+ * serializer would place them, and reports each one through the plugin's
+ * `graphEdges` hook:
+ *
+ *  - `needs`    job -> job in the same workflow
+ *  - `calls`    job -> the workflow a `uses: ./.github/workflows/<file>` names,
+ *               and job -> a composite action a step uses by local path
+ *  - `triggers` workflow -> each workflow its `on.workflow_run.workflows` names
+ *
+ * A string that names nothing declared (another repository's workflow, a
+ * typo'd job, a composite action, which chant does not declare) is reported
+ * as dangling, never matched to a near name.
+ *
+ * Forgejo reuses this module: its entities are github entities, and Forgejo
+ * reads reusable workflows from `.forgejo/workflows/` as well.
+ */
+import type { Declarable } from "@intentius/chant/declarable";
+import type { LexiconGraphEdges } from "@intentius/chant/graph-ir";
+/** The graph edges and pipeline membership a GitHub (or Forgejo) project declares. */
+export declare function githubGraphEdges(entities: ReadonlyMap<string, Declarable>): LexiconGraphEdges | undefined;
+//# sourceMappingURL=graph-edges.d.ts.map

package/dist/graph-edges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-edges.d.ts","sourceRoot":"","sources":["../src/graph-edges.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,iBAAiB,EAAyB,MAAM,2BAA2B,CAAC;AAqG1F,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,iBAAiB,GAAG,SAAS,CA8DzG"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { githubSerializer } from "./serializer.js";
+export { githubGraphEdges } from "./graph-edges.js";
 export { githubPlugin } from "./plugin.js";
 export { Expression, github, runner, secrets, matrix, steps, needs, inputs, vars, env, always, failure, success, cancelled, contains, startsWith, toJSON, fromJSON, format, branch, tag, } from "./expression.js";
 export { GitHub, Runner } from "./variables.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,OAAO,EACL,UAAU,EACV,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAChE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EACnC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAC9C,MAAM,EAAE,GAAG,GACZ,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAI7C,cAAc,mBAAmB,CAAC;AAGlC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAClE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG5E,OAAO,EACL,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EACzC,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAC7C,MAAM,EACN,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EACrD,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,IAAI,EACJ,UAAU,EAAE,gBAAgB,EAC5B,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAC7D,gBAAgB,EAAE,mBAAmB,EAAE,qBAAqB,EAC5D,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,eAAe,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,mBAAmB,EAC7E,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1F,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGzH,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGjD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,OAAO,EACL,UAAU,EACV,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAChE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EACnC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAC9C,MAAM,EAAE,GAAG,GACZ,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAI7C,cAAc,mBAAmB,CAAC;AAGlC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAClE,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG5E,OAAO,EACL,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EACzC,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAC7C,MAAM,EACN,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EACrD,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,IAAI,EACJ,UAAU,EAAE,gBAAgB,EAC5B,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAC7D,gBAAgB,EAAE,mBAAmB,EAAE,qBAAqB,EAC5D,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,eAAe,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,mBAAmB,EAC7E,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1F,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGzH,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "62765f1a817547b9377e08ba5f12be9af77e4d8a62d92f7a456c896c8a0358be",
+    "manifest.json": "70f80920964615564f5d1eaee17b6f74bdac4ff7c52bd4f2016400505dab9af2",
     "meta.json": "c50e0ef3845c370c3ad2210b8bba455980417c0f818aa6ed46e06d4fb8b1b9f9",
     "types/index.d.ts": "0ead95536e947ddfb98a5acf0ddb88547913b5a53a342df67711c59266f84b3e",
     "rules/deprecated-action-version.ts": "a9ba7cc924ff1c7055110416d8989273690415bfb5e8dcc32dc9431b9351f5ca",
@@ -78,5 +78,5 @@
     "skills/chant-github-patterns.md": "bb3abef289a8fdfcf07d6bb2d7289dcb2f38bc0cb0321ea320b78b45a6f548c0",
     "skills/chant-github-security.md": "aab111cb0871cad30281ce48d7da23663689619351029219e2be019a1a61e394"
   },
-  "composite": "0a21f2771c147c899dcbc07d4546aaace1d85ff61769bccff37dd42b7ebfa796"
+  "composite": "312cc217df7ecf85abe0e3611828a78fbf581ed38edf0023b787a5b55e1ecca5"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "github",
-  "version": "0.124.18",
+  "version": "0.124.19",
   "chantVersion": ">=0.1.0",
   "namespace": "GitHub",
   "intrinsics": [

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AA8B7F,eAAO,MAAM,YAAY,EAAE,aAgV1B,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AA+B7F,eAAO,MAAM,YAAY,EAAE,aAkV1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.124.18",
+  "version": "0.124.19",
   "description": "GitHub Actions lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -61,6 +61,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.18"
+    "@intentius/chant": "^0.124.19"
   }
 }

package/src/graph-edges.test.ts

@@ -0,0 +1,126 @@
+import { describe, test, expect } from "vitest";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import { applyLexiconGraphEdges, buildGraphIr } from "@intentius/chant/graph-ir";
+import { githubGraphEdges } from "./graph-edges";
+import { githubPlugin } from "./plugin";
+
+function entity(entityType: string, props: Record<string, unknown>, kind: "resource" | "property" = "resource"): Declarable {
+  return { [DECLARABLE_MARKER]: true, lexicon: "github", entityType, kind, props } as unknown as Declarable;
+}
+const workflow = (props: Record<string, unknown> = {}) => entity("GitHub::Actions::Workflow", props);
+const job = (props: Record<string, unknown> = {}) => entity("GitHub::Actions::Job", props);
+const step = (props: Record<string, unknown>) => entity("GitHub::Actions::Step", props, "property");
+
+/** Run the hook and merge it the way `chant graph` does. */
+function graph(entities: Map<string, Declarable>) {
+  const report = githubGraphEdges(entities);
+  return applyLexiconGraphEdges(buildGraphIr(entities), report ? [report] : []);
+}
+
+/** The edges the hook added. A workflow holding an exported Job in `jobs:`
+ * already had a `ref` edge to it from the core walk; that one is not ours. */
+const ciEdges = (ir: ReturnType<typeof graph>) => ir.edges.filter((e) => e.kind !== "ref");
+
+describe("githubGraphEdges (#3910)", () => {
+  test("the plugin exposes the hook", () => {
+    expect(githubPlugin.graphEdges).toBeTypeOf("function");
+  });
+
+  test("needs: job to job within the workflow, by kebab-cased key", () => {
+    const ir = graph(new Map<string, Declarable>([
+      ["ci", workflow({ name: "CI" })],
+      ["build", job({})],
+      ["unitTest", job({ needs: ["build"] })],
+      ["deploy", job({ needs: "unit-test" })],
+    ]));
+    expect(ciEdges(ir)).toEqual([
+      { from: "deploy", to: "unitTest", kind: "needs", viaAttr: "needs" },
+      { from: "unitTest", to: "build", kind: "needs", viaAttr: "needs" },
+    ]);
+    expect(ir.groups.byPipeline).toEqual({ ci: ["build", "ci", "deploy", "unitTest"] });
+    expect(ir.dangling).toBeUndefined();
+  });
+
+  test("needs resolves within the workflow that holds the job, not across workflows", () => {
+    const build = job({});
+    const release = job({ needs: ["build"] });
+    const ir = graph(new Map<string, Declarable>([
+      ["ci", workflow({ name: "CI", jobs: { build } })],
+      ["publish", workflow({ name: "Publish", jobs: { release } })],
+      ["build", build],
+      ["release", release],
+    ]));
+    expect(ciEdges(ir)).toEqual([]);
+    expect(ir.dangling).toEqual([{ from: "release", kind: "needs", path: "needs", value: "build" }]);
+  });
+
+  test("uses: ./.github/workflows/<file> calls the declared workflow written to that file", () => {
+    const callReusable = job({ uses: "./.github/workflows/reusable-ci.yml" });
+    const ir = graph(new Map<string, Declarable>([
+      ["caller", workflow({ name: "Caller", jobs: { callReusable } })],
+      ["reusableCi", workflow({ name: "Reusable", on: { workflow_call: {} }, jobs: { test: job({}) } })],
+      ["callReusable", callReusable],
+    ]));
+    expect(ciEdges(ir)).toEqual([
+      { from: "callReusable", to: "reusableCi", kind: "calls", viaAttr: "uses", crossPipeline: true },
+    ]);
+  });
+
+  test("a .forgejo/workflows path resolves the same way", () => {
+    const call = job({ uses: "./.forgejo/workflows/shared.yaml" });
+    const ir = graph(new Map<string, Declarable>([
+      ["main", workflow({ jobs: { call } })],
+      ["shared", workflow({ jobs: { t: job({}) } })],
+      ["call", call],
+    ]));
+    expect(ciEdges(ir).map((e) => [e.from, e.to, e.kind])).toEqual([["call", "shared", "calls"]]);
+  });
+
+  test("on.workflow_run.workflows: the triggered workflow points at the workflow named", () => {
+    const ir = graph(new Map<string, Declarable>([
+      ["ci", workflow({ name: "CI", jobs: { t: job({}) } })],
+      ["deploy", workflow({ name: "Deploy", on: { workflowRun: { workflows: ["CI"], types: ["completed"] } }, jobs: { d: job({}) } })],
+    ]));
+    expect(ciEdges(ir)).toEqual([
+      { from: "deploy", to: "ci", kind: "triggers", viaAttr: "workflow_run", crossPipeline: true },
+    ]);
+  });
+
+  test("a step using a local composite action is reported, dangling: chant does not declare actions", () => {
+    const ir = graph(new Map<string, Declarable>([
+      ["ci", workflow({})],
+      ["build", job({ steps: [step({ uses: "actions/checkout@v4" }), step({ uses: "./.github/actions/setup" })] })],
+    ]));
+    expect(ciEdges(ir)).toEqual([]);
+    expect(ir.dangling).toEqual([{ from: "build", kind: "calls", path: "steps.uses", value: "./.github/actions/setup" }]);
+  });
+
+  test("dangling: unknown job, another repository's workflow, an undeclared workflow name", () => {
+    const ir = graph(new Map<string, Declarable>([
+      ["ci", workflow({ name: "CI", on: { workflow_run: { workflows: ["Nightly"] } } })],
+      ["build", job({ needs: ["compile"] })],
+      ["shared", job({ uses: "octo-org/infra/.github/workflows/deploy.yml@v1" })],
+      ["local", job({ uses: "./.github/workflows/missing.yml" })],
+    ]));
+    expect(ciEdges(ir)).toEqual([]);
+    expect(ir.dangling).toEqual([
+      { from: "build", kind: "needs", path: "needs", value: "compile" },
+      { from: "ci", kind: "triggers", path: "workflow_run", value: "Nightly", crossPipeline: true },
+      { from: "local", kind: "calls", path: "uses", value: "./.github/workflows/missing.yml", crossPipeline: true },
+      { from: "shared", kind: "calls", path: "uses", value: "octo-org/infra/.github/workflows/deploy.yml@v1", crossPipeline: true },
+    ]);
+  });
+
+  test("standalone jobs follow the serializer: they run in the first workflow only", () => {
+    const ir = graph(new Map<string, Declarable>([
+      ["first", workflow({})],
+      ["second", workflow({})],
+      ["build", job({})],
+    ]));
+    expect(ir.groups.byPipeline).toEqual({ first: ["build", "first"], second: ["second"] });
+  });
+
+  test("a project with no workflows or jobs reports nothing", () => {
+    expect(githubGraphEdges(new Map())).toBeUndefined();
+  });
+});

package/src/graph-edges.ts

@@ -0,0 +1,190 @@
+/**
+ * GitHub Actions dependencies as graph edges (#3910).
+ *
+ * `chant graph` draws an edge for every typed reference it can find, and a
+ * workflow has almost none: a job names the jobs it waits for, the reusable
+ * workflow it calls and the workflows that trigger it as strings. This module
+ * resolves those strings against the declared entities, the way the
+ * serializer would place them, and reports each one through the plugin's
+ * `graphEdges` hook:
+ *
+ *  - `needs`    job -> job in the same workflow
+ *  - `calls`    job -> the workflow a `uses: ./.github/workflows/<file>` names,
+ *               and job -> a composite action a step uses by local path
+ *  - `triggers` workflow -> each workflow its `on.workflow_run.workflows` names
+ *
+ * A string that names nothing declared (another repository's workflow, a
+ * typo'd job, a composite action, which chant does not declare) is reported
+ * as dangling, never matched to a near name.
+ *
+ * Forgejo reuses this module: its entities are github entities, and Forgejo
+ * reads reusable workflows from `.forgejo/workflows/` as well.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { isPropertyDeclarable } from "@intentius/chant/declarable";
+import type { LexiconGraphEdges, LexiconGraphReference } from "@intentius/chant/graph-ir";
+
+const WORKFLOW = "GitHub::Actions::Workflow";
+const JOB_TYPES = new Set(["GitHub::Actions::Job", "GitHub::Actions::ReusableWorkflowCallJob"]);
+
+function toKebabCase(name: string): string {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+function entityType(value: unknown): string | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const t = (value as { entityType?: unknown }).entityType;
+  return typeof t === "string" ? t : undefined;
+}
+
+/** A Declarable's props bag, or the plain object itself (JSON-style jobs and steps). */
+function propsOf(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const props = (value as { props?: unknown }).props;
+  if (entityType(value) !== undefined) {
+    return props && typeof props === "object" ? (props as Record<string, unknown>) : undefined;
+  }
+  return value as Record<string, unknown>;
+}
+
+/** One job as the serializer places it: its YAML key and the node it is, if any. */
+interface PlacedJob {
+  key: string;
+  node?: string;
+  props: Record<string, unknown>;
+}
+
+interface PlacedWorkflow {
+  name: string;
+  props: Record<string, unknown>;
+  jobs: PlacedJob[];
+}
+
+/**
+ * Which jobs land in which workflow, mirroring ./serializer.ts: a workflow's
+ * own `jobs:` map when it has one, and otherwise the standalone Job exports,
+ * which go to the first workflow only.
+ */
+function placeJobs(entities: ReadonlyMap<string, Declarable>): { workflows: PlacedWorkflow[]; orphans: PlacedJob[] } {
+  const names = new Map<unknown, string>();
+  const workflows: Array<[string, Declarable]> = [];
+  const standalone: PlacedJob[] = [];
+  for (const [name, entity] of entities) {
+    names.set(entity, name);
+    if (isPropertyDeclarable(entity)) continue;
+    const type = entityType(entity);
+    if (type === WORKFLOW) workflows.push([name, entity]);
+    else if (type && JOB_TYPES.has(type)) standalone.push({ key: toKebabCase(name), node: name, props: propsOf(entity) ?? {} });
+  }
+
+  const placed: PlacedWorkflow[] = workflows.map(([name, wf], i) => {
+    const props = propsOf(wf) ?? {};
+    const inline: PlacedJob[] = [];
+    const jobs = props.jobs;
+    if (jobs && typeof jobs === "object" && !Array.isArray(jobs)) {
+      for (const [key, value] of Object.entries(jobs as Record<string, unknown>)) {
+        const jobProps = propsOf(value);
+        if (!jobProps) continue;
+        inline.push({ key: toKebabCase(key), node: names.get(value), props: jobProps });
+      }
+    }
+    return { name, props, jobs: inline.length > 0 ? inline : i === 0 ? standalone : [] };
+  });
+  return { workflows: placed, orphans: workflows.length === 0 ? standalone : [] };
+}
+
+/** The file a declared workflow is written to. Every workflow after the first
+ * is `<kebab-name>.yml` (./serializer.ts); the first is written to the
+ * `--output` path, which the examples and templates name the same way. */
+function workflowFile(name: string): string {
+  return `${toKebabCase(name)}.yml`;
+}
+
+const stripYamlExt = (file: string): string => file.replace(/\.ya?ml$/, "");
+
+/** `needs:` as a list of job keys. A Job object held directly names itself. */
+function needsKeys(needs: unknown, names: Map<unknown, string>): string[] {
+  const list = Array.isArray(needs) ? needs : needs === undefined ? [] : [needs];
+  const out: string[] = [];
+  for (const item of list) {
+    if (typeof item === "string") out.push(item);
+    else if (names.has(item)) out.push(toKebabCase(names.get(item)!));
+  }
+  return out;
+}
+
+/** `on.workflow_run.workflows`, read from the camelCase or snake_case key. */
+function workflowRunNames(on: unknown): string[] {
+  const triggers = propsOf(on);
+  if (!triggers) return [];
+  const run = propsOf(triggers.workflow_run ?? triggers.workflowRun);
+  const workflows = run?.workflows;
+  if (typeof workflows === "string") return [workflows];
+  return Array.isArray(workflows) ? workflows.filter((w): w is string => typeof w === "string") : [];
+}
+
+/** The graph edges and pipeline membership a GitHub (or Forgejo) project declares. */
+export function githubGraphEdges(entities: ReadonlyMap<string, Declarable>): LexiconGraphEdges | undefined {
+  const { workflows, orphans } = placeJobs(entities);
+  if (workflows.length === 0 && orphans.length === 0) return undefined;
+
+  const names = new Map<unknown, string>();
+  for (const [name, entity] of entities) names.set(entity, name);
+
+  const byFile = new Map<string, string>();
+  const byDisplayName = new Map<string, string>();
+  for (const wf of workflows) {
+    byFile.set(stripYamlExt(workflowFile(wf.name)), wf.name);
+    if (typeof wf.props.name === "string") byDisplayName.set(wf.props.name, wf.name);
+  }
+
+  const references: LexiconGraphReference[] = [];
+  const pipelines: Record<string, string[]> = {};
+
+  const visitJobs = (jobs: PlacedJob[], workflow?: string): void => {
+    const byKey = new Map(jobs.map((j) => [j.key, j]));
+    for (const job of jobs) {
+      const from = job.node ?? workflow;
+      if (!from) continue;
+
+      for (const key of needsKeys(job.props.needs, names)) {
+        const target = byKey.get(key);
+        const to = target ? (target.node ?? workflow) : undefined;
+        if (to) references.push({ from, to, kind: "needs", viaAttr: "needs" });
+        else references.push({ from, to: key, kind: "needs", viaAttr: "needs", dangling: true });
+      }
+
+      const uses = job.props.uses;
+      if (typeof uses === "string") {
+        const local = /^\.\/(?:.*\/)?workflows\/([^/]+\.ya?ml)$/.exec(uses);
+        const called = local ? byFile.get(stripYamlExt(local[1])) : undefined;
+        if (called) references.push({ from, to: called, kind: "calls", viaAttr: "uses", crossPipeline: true });
+        else references.push({ from, to: uses, kind: "calls", viaAttr: "uses", crossPipeline: true, dangling: true });
+      }
+
+      const steps = Array.isArray(job.props.steps) ? job.props.steps : [];
+      for (const step of steps) {
+        const stepUses = propsOf(step)?.uses;
+        // A local composite action. Remote actions (`owner/repo@ref`,
+        // `docker://`) are packages, not part of this project's graph.
+        if (typeof stepUses === "string" && stepUses.startsWith("./")) {
+          references.push({ from, to: stepUses, kind: "calls", viaAttr: "steps.uses", dangling: true });
+        }
+      }
+    }
+  };
+
+  for (const wf of workflows) {
+    visitJobs(wf.jobs, wf.name);
+    pipelines[wf.name] = [wf.name, ...wf.jobs.map((j) => j.node).filter((n): n is string => n !== undefined)];
+    for (const trigger of workflowRunNames(wf.props.on)) {
+      const to = byDisplayName.get(trigger);
+      if (to) references.push({ from: wf.name, to, kind: "triggers", viaAttr: "workflow_run", crossPipeline: true });
+      else references.push({ from: wf.name, to: trigger, kind: "triggers", viaAttr: "workflow_run", crossPipeline: true, dangling: true });
+    }
+  }
+  visitJobs(orphans);
+
+  return { references, ...(Object.keys(pipelines).length > 0 ? { pipelines } : {}) };
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 // Serializer
 export { githubSerializer } from "./serializer";
+export { githubGraphEdges } from "./graph-edges";
 
 // Plugin
 export { githubPlugin } from "./plugin";

package/src/plugin.ts

@@ -14,6 +14,7 @@ import { createSkillsLoader, createDiffTool, createCatalogResource } from "@inte
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { githubSerializer } from "./serializer";
+import { githubGraphEdges } from "./graph-edges";
 import { useTypedActionsRule } from "./lint/rules/use-typed-actions";
 import { useConditionBuildersRule } from "./lint/rules/use-condition-builders";
 import { noHardcodedSecretsRule } from "./lint/rules/no-hardcoded-secrets";
@@ -46,6 +47,8 @@ export const githubPlugin: LexiconPlugin = {
   // Ordered waves of Op runs, each behind one gate (#3679).
   generateOpWavesPipeline: (spec, options) => generateGithubOpWavesPipeline(spec, options),
   serializer: githubSerializer,
+  // `needs`, reusable-workflow `uses:` and `workflow_run` as graph edges (#3910).
+  graphEdges: (entities) => githubGraphEdges(entities),
 
   lintRules(): LintRule[] {
     return [