@intentius/chant-lexicon-gitlab 0.124.18 → 0.124.20

package/dist/graph-edges.d.ts

@@ -0,0 +1,28 @@
+/**
+ * GitLab CI dependencies as graph edges (#3910).
+ *
+ * A GitLab job names everything it depends on as a string: the jobs it
+ * `needs`, the job it `extends`, the pipeline it `trigger`s, and the pipeline
+ * names the files it `include`s. `chant graph` cannot read those, so this
+ * module resolves them against the declared entities and reports each one
+ * through the plugin's `graphEdges` hook:
+ *
+ *  - `needs`    job -> job, from `needs:` (a name, `{ job }`, or the Job
+ *               itself); a job without `needs:` waits for the stages before
+ *               its own, reported as `needs` via `stage`
+ *  - `extends`  job -> the job it inherits from
+ *  - `triggers` job -> the child or multi-project pipeline it starts
+ *  - `includes` pipeline -> each file its `include:` pulls in
+ *
+ * Jobs are named in the YAML by their kebab-cased export name, as
+ * ./serializer.ts writes them. Cross-pipeline references (`trigger:`,
+ * `include:`, `needs: { project }` and `needs: { pipeline }`) name a pipeline
+ * this project does not generate, so they are reported as dangling and
+ * marked `crossPipeline`. So is any job name nothing declares: a hidden
+ * template from an included file, a typo.
+ */
+import type { Declarable } from "@intentius/chant/declarable";
+import type { LexiconGraphEdges } from "@intentius/chant/graph-ir";
+/** The graph edges and pipeline membership a GitLab CI project declares. */
+export declare function gitlabGraphEdges(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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,iBAAiB,EAAyB,MAAM,2BAA2B,CAAC;AA8D1F,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,iBAAiB,GAAG,SAAS,CA6GzG"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { gitlabSerializer } from "./serializer.js";
+export { gitlabGraphEdges } from "./graph-edges.js";
 export { gitlabPlugin } from "./plugin.js";
 export { gitlabPipeline } from "./op/builders.js";
 export { reference, ReferenceIntrinsic } from "./intrinsics.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;AAOxC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAG7D,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAIjC,cAAc,mBAAmB,CAAC;AAGlC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACnI,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGtI,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACrF,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpF,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;AAOxC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAG7D,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAIjC,cAAc,mBAAmB,CAAC;AAGlC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACnI,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGtI,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACrF,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpF,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": "9fc693da7737f59ded275b02bec5d0728953c080cbf890af2a7addff921bad7a",
+    "manifest.json": "76651fdf8d5ef3e97c06ffa43878ca1557abeed81fcd6c831be67ba25435810b",
     "meta.json": "db082fbf90c5941c498b2bee0f106103449c1a4c257716ca2220f0dd490450b2",
     "types/index.d.ts": "a048a66ebe20da0cb5fc889054cac69044d9bf882e2c56b5c5bf113d1f3ba57c",
     "rules/artifact-no-expiry.ts": "0ca5bb972d4a542126e8a0229d43b55658394cb7dd9b9923b2c590bec1c2ad7d",
@@ -55,5 +55,5 @@
     "skills/chant-gitlab-migrate.md": "4853d04980560b379e5b0f7267dcb0a1e5d5879cb9e9931681ce76b2a5fe69d8",
     "skills/chant-gitlab-patterns.md": "6d9a44e9e8de4c3820be9d65381b0d2ede4cb3626aaaf0011e21838a9fbf556e"
   },
-  "composite": "0b5e06ca63b3184e95270d0da0f4cc03e7b0453782f3ae418fd853ffce06f048"
+  "composite": "6ea34b300003999b75345a60087bddcd33cbf1cea8d007dfe71e1add9587b60e"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "gitlab",
-  "version": "0.124.18",
+  "version": "0.124.20",
   "chantVersion": ">=0.1.0",
   "namespace": "GitLab",
   "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;AAqB7F,eAAO,MAAM,YAAY,EAAE,aA0hB1B,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;AAsB7F,eAAO,MAAM,YAAY,EAAE,aA4hB1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gitlab",
-  "version": "0.124.18",
+  "version": "0.124.20",
   "description": "GitLab CI lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -67,8 +67,8 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.18",
-    "@intentius/chant-lexicon-github": "^0.124.18"
+    "@intentius/chant": "^0.124.20",
+    "@intentius/chant-lexicon-github": "^0.124.20"
   },
   "peerDependenciesMeta": {
     "@intentius/chant-lexicon-github": {

package/src/graph-edges.test.ts

@@ -0,0 +1,122 @@
+import { describe, test, expect } from "vitest";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import { applyLexiconGraphEdges, buildGraphIr } from "@intentius/chant/graph-ir";
+import { gitlabGraphEdges } from "./graph-edges";
+import { gitlabPlugin } from "./plugin";
+
+function entity(entityType: string, props: Record<string, unknown>, kind: "resource" | "property" = "resource"): Declarable {
+  return { [DECLARABLE_MARKER]: true, lexicon: "gitlab", entityType, kind, props } as unknown as Declarable;
+}
+const job = (props: Record<string, unknown> = {}) => entity("GitLab::CI::Job", props);
+const pipeline = (props: Record<string, unknown>) => entity("GitLab::CI::Pipeline", props);
+const need = (props: Record<string, unknown>) => entity("GitLab::CI::Need", props, "property");
+const trigger = (props: Record<string, unknown>) => entity("GitLab::CI::Trigger", props, "property");
+const include = (props: Record<string, unknown>) => entity("GitLab::CI::Include", props, "property");
+
+/** Run the hook and merge it the way `chant graph` does. */
+function graph(entities: Map<string, Declarable>) {
+  const report = gitlabGraphEdges(entities);
+  return applyLexiconGraphEdges(buildGraphIr(entities), report ? [report] : []);
+}
+
+describe("gitlabGraphEdges (#3910)", () => {
+  test("the plugin exposes the hook", () => {
+    expect(gitlabPlugin.graphEdges).toBeTypeOf("function");
+  });
+
+  test("needs: a name, { job } and the Job object itself all resolve to the job", () => {
+    const build = job({ stage: "build" });
+    const ir = graph(new Map<string, Declarable>([
+      ["build", build],
+      ["lintCode", job({ stage: "build" })],
+      ["unitTest", job({ stage: "test", needs: ["build", need({ job: "lint-code", artifacts: false })] })],
+      ["deploy", job({ stage: "deploy", needs: [build] })],
+    ]));
+    expect(ir.edges).toEqual([
+      { from: "deploy", to: "build", kind: "needs", viaAttr: "needs" },
+      { from: "unitTest", to: "build", kind: "needs", viaAttr: "needs" },
+      { from: "unitTest", to: "lintCode", kind: "needs", viaAttr: "needs" },
+    ]);
+    expect(ir.groups.byPipeline).toEqual({ ".gitlab-ci.yml": ["build", "deploy", "lintCode", "unitTest"] });
+  });
+
+  test("a job without needs: waits for the stage before its own", () => {
+    const ir = graph(new Map<string, Declarable>([
+      ["build", job({ stage: "build" })],
+      ["test", job({ stage: "test" })],
+      ["deploy", job({ stage: "deploy" })],
+    ]));
+    expect(ir.edges).toEqual([
+      { from: "deploy", to: "test", kind: "needs", viaAttr: "stage" },
+      { from: "test", to: "build", kind: "needs", viaAttr: "stage" },
+    ]);
+  });
+
+  test("stage order looks further back past a job that starts early with needs:", () => {
+    const ir = graph(new Map<string, Declarable>([
+      ["compile", job({ stage: "build" })],
+      ["quick", job({ stage: "test", needs: [] })],
+      ["deploy", job({ stage: "deploy" })],
+    ]));
+    expect(ir.edges).toEqual([
+      { from: "deploy", to: "compile", kind: "needs", viaAttr: "stage" },
+      { from: "deploy", to: "quick", kind: "needs", viaAttr: "stage" },
+    ]);
+  });
+
+  test("a Pipeline's stages: list sets the order, and a job with no stage is in test", () => {
+    const ir = graph(new Map<string, Declarable>([
+      ["pipeline", pipeline({ stages: ["test", "package"] })],
+      ["pack", job({ stage: "package" })],
+      ["check", job({})],
+    ]));
+    expect(ir.edges).toEqual([{ from: "pack", to: "check", kind: "needs", viaAttr: "stage" }]);
+  });
+
+  test("extends: the job it inherits from", () => {
+    const ir = graph(new Map<string, Declarable>([
+      ["baseJob", job({ stage: "build" })],
+      ["build", job({ stage: "build", extends: "base-job" })],
+    ]));
+    expect(ir.edges).toEqual([{ from: "build", to: "baseJob", kind: "extends", viaAttr: "extends" }]);
+  });
+
+  test("trigger: and include: name pipelines this project does not generate, so they dangle", () => {
+    const ir = graph(new Map<string, Declarable>([
+      ["pipeline", pipeline({ include: [include({ local: "ci/templates.yml" }), "https://example.com/ci.yml", include({ project: "group/shared", ref: "main", file: "ci.yml" })] })],
+      ["child", job({ stage: "build", trigger: trigger({ include: "child/.gitlab-ci.yml", strategy: "depend" }) })],
+      ["downstream", job({ stage: "build", trigger: "group/downstream" })],
+      ["multi", job({ stage: "build", trigger: trigger({ project: "group/other", branch: "main" }) })],
+    ]));
+    expect(ir.edges).toEqual([]);
+    expect(ir.dangling).toEqual([
+      { from: "child", kind: "triggers", path: "trigger.include", value: "child/.gitlab-ci.yml", crossPipeline: true },
+      { from: "downstream", kind: "triggers", path: "trigger", value: "group/downstream", crossPipeline: true },
+      { from: "multi", kind: "triggers", path: "trigger.project", value: "group/other@main", crossPipeline: true },
+      { from: "pipeline", kind: "includes", path: "include", value: "ci/templates.yml", crossPipeline: true },
+      { from: "pipeline", kind: "includes", path: "include", value: "group/shared@main:ci.yml", crossPipeline: true },
+      { from: "pipeline", kind: "includes", path: "include", value: "https://example.com/ci.yml", crossPipeline: true },
+    ]);
+  });
+
+  test("dangling: cross-project and parent-pipeline needs, unknown job, hidden template", () => {
+    const ir = graph(new Map<string, Declarable>([
+      ["deploy", job({
+        stage: "deploy",
+        needs: [need({ project: "group/lib", job: "package", ref: "main", artifacts: true }), need({ pipeline: "$PARENT_PIPELINE_ID", job: "gen" }), "compile"],
+        extends: [".deploy-template"],
+      })],
+    ]));
+    expect(ir.edges).toEqual([]);
+    expect(ir.dangling).toEqual([
+      { from: "deploy", kind: "extends", path: "extends", value: ".deploy-template" },
+      { from: "deploy", kind: "needs", path: "needs.pipeline", value: "$PARENT_PIPELINE_ID:gen", crossPipeline: true },
+      { from: "deploy", kind: "needs", path: "needs.project", value: "group/lib@main:package", crossPipeline: true },
+      { from: "deploy", kind: "needs", path: "needs", value: "compile" },
+    ]);
+  });
+
+  test("a project with no jobs or pipeline reports nothing", () => {
+    expect(gitlabGraphEdges(new Map())).toBeUndefined();
+  });
+});

package/src/graph-edges.ts

@@ -0,0 +1,199 @@
+/**
+ * GitLab CI dependencies as graph edges (#3910).
+ *
+ * A GitLab job names everything it depends on as a string: the jobs it
+ * `needs`, the job it `extends`, the pipeline it `trigger`s, and the pipeline
+ * names the files it `include`s. `chant graph` cannot read those, so this
+ * module resolves them against the declared entities and reports each one
+ * through the plugin's `graphEdges` hook:
+ *
+ *  - `needs`    job -> job, from `needs:` (a name, `{ job }`, or the Job
+ *               itself); a job without `needs:` waits for the stages before
+ *               its own, reported as `needs` via `stage`
+ *  - `extends`  job -> the job it inherits from
+ *  - `triggers` job -> the child or multi-project pipeline it starts
+ *  - `includes` pipeline -> each file its `include:` pulls in
+ *
+ * Jobs are named in the YAML by their kebab-cased export name, as
+ * ./serializer.ts writes them. Cross-pipeline references (`trigger:`,
+ * `include:`, `needs: { project }` and `needs: { pipeline }`) name a pipeline
+ * this project does not generate, so they are reported as dangling and
+ * marked `crossPipeline`. So is any job name nothing declares: a hidden
+ * template from an included file, a typo.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { isPropertyDeclarable } from "@intentius/chant/declarable";
+import type { LexiconGraphEdges, LexiconGraphReference } from "@intentius/chant/graph-ir";
+
+const JOB = "GitLab::CI::Job";
+const PIPELINE = "GitLab::CI::Pipeline";
+const PIPELINE_LEVEL = new Set([PIPELINE, "GitLab::CI::Default", "GitLab::CI::Workflow"]);
+
+/** The YAML name ./serializer.ts gives a job. */
+function yamlName(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. */
+function propsOf(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  if (entityType(value) !== undefined) {
+    const props = (value as { props?: unknown }).props;
+    return props && typeof props === "object" ? (props as Record<string, unknown>) : undefined;
+  }
+  return value as Record<string, unknown>;
+}
+
+const asList = (value: unknown): unknown[] => (Array.isArray(value) ? value : value === undefined || value === null ? [] : [value]);
+
+/** GitLab's default stages, used when nothing declares a `stages:` list. */
+const DEFAULT_STAGES = ["build", "test", "deploy"];
+
+/**
+ * The stage order GitLab runs, as ./serializer.ts emits it: a Pipeline's
+ * `stages:` first, then every stage a job names that the list leaves out, in
+ * first use. With neither, GitLab's defaults. `.pre` and `.post` always
+ * bracket the list.
+ */
+function stageOrder(pipelines: Record<string, unknown>[], jobs: Array<{ props: Record<string, unknown> }>): string[] {
+  const stages = new Set<string>();
+  for (const p of pipelines) for (const s of asList(p.stages)) if (typeof s === "string") stages.add(s);
+  for (const j of jobs) if (typeof j.props.stage === "string") stages.add(j.props.stage);
+  const list = stages.size > 0 ? [...stages] : DEFAULT_STAGES;
+  return [".pre", ...list.filter((s) => s !== ".pre" && s !== ".post"), ".post"];
+}
+
+/** A file an `include:` or `trigger: { include }` entry names, as written. */
+function includeTarget(entry: unknown): string | undefined {
+  if (typeof entry === "string") return entry;
+  const p = propsOf(entry);
+  if (!p) return undefined;
+  for (const key of ["local", "remote", "template", "component", "artifact"]) {
+    if (typeof p[key] === "string") return p[key] as string;
+  }
+  if (typeof p.project === "string") {
+    const files = asList(p.file).filter((f): f is string => typeof f === "string");
+    const ref = typeof p.ref === "string" ? `@${p.ref}` : "";
+    return `${p.project}${ref}:${files.join(",")}`;
+  }
+  return undefined;
+}
+
+/** The graph edges and pipeline membership a GitLab CI project declares. */
+export function gitlabGraphEdges(entities: ReadonlyMap<string, Declarable>): LexiconGraphEdges | undefined {
+  const names = new Map<unknown, string>();
+  const jobs: Array<{ node: string; key: string; props: Record<string, unknown> }> = [];
+  const pipelineNodes: string[] = [];
+  const pipelineEntities: Array<{ node: string; props: Record<string, unknown> }> = [];
+  for (const [name, entity] of entities) {
+    names.set(entity, name);
+    if (isPropertyDeclarable(entity)) continue;
+    const type = entityType(entity);
+    if (type === JOB) jobs.push({ node: name, key: yamlName(name), props: propsOf(entity) ?? {} });
+    else if (type && PIPELINE_LEVEL.has(type)) {
+      pipelineNodes.push(name);
+      if (type === PIPELINE) pipelineEntities.push({ node: name, props: propsOf(entity) ?? {} });
+    }
+  }
+  if (jobs.length === 0 && pipelineEntities.length === 0) return undefined;
+
+  const byKey = new Map(jobs.map((j) => [j.key, j.node]));
+  const references: LexiconGraphReference[] = [];
+
+  // A job name as written, or a Job object held directly.
+  const jobKey = (value: unknown): string | undefined => {
+    if (typeof value === "string") return value;
+    const name = names.get(value);
+    return name !== undefined && entityType(value) === JOB ? yamlName(name) : undefined;
+  };
+
+  // Stage order, for the jobs that say nothing about `needs:`.
+  const stages = stageOrder(pipelineEntities.map((p) => p.props), jobs);
+  const stageOf = (j: { props: Record<string, unknown> }): number =>
+    stages.indexOf(typeof j.props.stage === "string" ? j.props.stage : "test");
+  const atStage = new Map<number, typeof jobs>();
+  for (const j of jobs) {
+    const s = stageOf(j);
+    if (s < 0) continue;
+    const arr = atStage.get(s) ?? [];
+    arr.push(j);
+    atStage.set(s, arr);
+  }
+
+  for (const job of jobs) {
+    const from = job.node;
+
+    if (job.props.needs === undefined) {
+      // Stage order: wait for every job in the nearest earlier stage that has
+      // any. Those jobs wait for the stage before them in turn, unless one of
+      // them uses `needs:` and starts early, in which case this job also
+      // waits for the stage before, and so on back.
+      for (let s = stageOf(job) - 1; s >= 0; s--) {
+        const earlier = atStage.get(s);
+        if (!earlier) continue;
+        for (const e of earlier) references.push({ from, to: e.node, kind: "needs", viaAttr: "stage" });
+        if (earlier.every((e) => e.props.needs === undefined)) break;
+      }
+    }
+
+    for (const need of asList(job.props.needs)) {
+      const key = jobKey(need);
+      if (key !== undefined) {
+        const to = byKey.get(key);
+        references.push(to ? { from, to, kind: "needs", viaAttr: "needs" } : { from, to: key, kind: "needs", viaAttr: "needs", dangling: true });
+        continue;
+      }
+      const p = propsOf(need);
+      if (!p || typeof p.job !== "string") continue;
+      if (typeof p.project === "string") {
+        const ref = typeof p.ref === "string" ? `@${p.ref}` : "";
+        references.push({ from, to: `${p.project}${ref}:${p.job}`, kind: "needs", viaAttr: "needs.project", crossPipeline: true, dangling: true });
+      } else if (typeof p.pipeline === "string") {
+        references.push({ from, to: `${p.pipeline}:${p.job}`, kind: "needs", viaAttr: "needs.pipeline", crossPipeline: true, dangling: true });
+      } else {
+        const to = byKey.get(p.job);
+        references.push(to ? { from, to, kind: "needs", viaAttr: "needs" } : { from, to: p.job, kind: "needs", viaAttr: "needs", dangling: true });
+      }
+    }
+
+    for (const parent of asList(job.props.extends)) {
+      const key = jobKey(parent);
+      if (key === undefined) continue;
+      const to = byKey.get(key);
+      references.push(to ? { from, to, kind: "extends", viaAttr: "extends" } : { from, to: key, kind: "extends", viaAttr: "extends", dangling: true });
+    }
+
+    const trigger = job.props.trigger;
+    if (typeof trigger === "string") {
+      references.push({ from, to: trigger, kind: "triggers", viaAttr: "trigger", crossPipeline: true, dangling: true });
+    } else {
+      const t = propsOf(trigger);
+      if (t && typeof t.project === "string") {
+        const branch = typeof t.branch === "string" ? `@${t.branch}` : "";
+        references.push({ from, to: `${t.project}${branch}`, kind: "triggers", viaAttr: "trigger.project", crossPipeline: true, dangling: true });
+      }
+      for (const entry of asList(t?.include)) {
+        const file = includeTarget(entry);
+        if (file) references.push({ from, to: file, kind: "triggers", viaAttr: "trigger.include", crossPipeline: true, dangling: true });
+      }
+    }
+  }
+
+  for (const p of pipelineEntities) {
+    for (const entry of asList(p.props.include)) {
+      const file = includeTarget(entry);
+      if (file) references.push({ from: p.node, to: file, kind: "includes", viaAttr: "include", crossPipeline: true, dangling: true });
+    }
+  }
+
+  // One project, one `.gitlab-ci.yml`: every job and pipeline-level entity is in it.
+  const members = [...pipelineNodes, ...jobs.map((j) => j.node)].sort();
+  return { references, pipelines: { ".gitlab-ci.yml": members } };
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 // Serializer
 export { gitlabSerializer } from "./serializer";
+export { gitlabGraphEdges } from "./graph-edges";
 
 // Plugin
 export { gitlabPlugin } 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 { gitlabSerializer } from "./serializer";
+import { gitlabGraphEdges } from "./graph-edges";
 import { gitlabContextTools } from "./mcp/context-tools";
 import { deprecatedOnlyExceptRule } from "./lint/rules/deprecated-only-except";
 import { missingScriptRule } from "./lint/rules/missing-script";
@@ -46,6 +47,8 @@ export const gitlabPlugin: LexiconPlugin = {
     upstream: { owner: "gitlab-org", repo: "gitlab", kind: "tags", tagSuffix: "-ee" },
   },
   serializer: gitlabSerializer,
+  // `needs`, stage order, `extends`, `trigger:` and `include:` as graph edges (#3910).
+  graphEdges: (entities) => gitlabGraphEdges(entities),
 
   lintRules(): LintRule[] {
     return [deprecatedOnlyExceptRule, missingScriptRule, missingStageRule, artifactNoExpiryRule];