@intentius/chant 0.124.23 → 0.124.24

package/src/workspace/compose-graph.test.ts

@@ -104,6 +104,61 @@ describe("composeWorkspaceGraph", () => {
   });
 });
 
+describe("CI edges, pipelines and dangling references (#3922)", () => {
+  /** A github member as `chant graph` reports it after #3910. */
+  const ci = (workflow: string, job: string): GraphIR => ({
+    version: 1,
+    nodes: [
+      { id: workflow, kind: "Workflow", lexicon: "github", attrs: {} },
+      { id: job, kind: "Job", lexicon: "github", attrs: {} },
+      { id: "deploy", kind: "Job", lexicon: "github", attrs: {} },
+    ],
+    edges: [
+      { from: "deploy", to: job, kind: "needs", viaAttr: "needs" },
+      { from: job, to: workflow, kind: "calls", viaAttr: "uses", crossPipeline: true },
+    ],
+    groups: { byLexicon: { github: [job, "deploy", workflow] }, byPipeline: { ci: [job, "deploy", workflow] } },
+    dangling: [
+      { from: "deploy", kind: "needs", path: "needs", value: "lint" },
+      { from: job, kind: "calls", path: "uses", value: "other/repo/.github/workflows/x.yml@main", crossPipeline: true },
+    ],
+  });
+  const doc = composeWorkspaceGraph({ name: "acme", root: "." }, [
+    { member: member("svc", "svc"), ir: ci("ciWorkflow", "build") },
+    { member: member("app", "app"), ir: ci("ciWorkflow", "test") },
+    { member: member("db", "db"), ir: db },
+  ]);
+
+  test("edges keep their kind and crossPipeline", () => {
+    expect(doc.edges.filter((e) => e.member === "svc")).toEqual([
+      { from: "svc/build", to: "svc/ciWorkflow", kind: "calls", viaAttr: "uses", crossPipeline: true, member: "svc" },
+      { from: "svc/deploy", to: "svc/build", kind: "needs", viaAttr: "needs", member: "svc" },
+    ]);
+  });
+
+  test("byPipeline keys and ids are prefixed with the member", () => {
+    expect(doc.groups.byPipeline).toEqual({
+      "app/ci": ["app/ciWorkflow", "app/deploy", "app/test"],
+      "svc/ci": ["svc/build", "svc/ciWorkflow", "svc/deploy"],
+    });
+  });
+
+  test("dangling references keep their fields, with from prefixed and the member named, sorted", () => {
+    expect(doc.dangling).toEqual([
+      { from: "app/deploy", kind: "needs", path: "needs", value: "lint", member: "app" },
+      { from: "app/test", kind: "calls", path: "uses", value: "other/repo/.github/workflows/x.yml@main", crossPipeline: true, member: "app" },
+      { from: "svc/build", kind: "calls", path: "uses", value: "other/repo/.github/workflows/x.yml@main", crossPipeline: true, member: "svc" },
+      { from: "svc/deploy", kind: "needs", path: "needs", value: "lint", member: "svc" },
+    ]);
+  });
+
+  test("no dangling section and no byPipeline when no member reports either", () => {
+    const plain = composeWorkspaceGraph({ name: "acme", root: "." }, [{ member: member("db", "db"), ir: db }]);
+    expect("dangling" in plain).toBe(false);
+    expect(plain.groups.byPipeline).toBeUndefined();
+  });
+});
+
 describe("the links section (#2539)", () => {
   test("inferred joins carry their label, and a declared link suppresses the inferred edge it covers", () => {
     const consumer: GraphIR = {

package/src/workspace/compose-graph.ts

@@ -11,8 +11,12 @@
  *   `runtimeOwner` and export and import nodes are rewritten the same way.
  * - `groups.byMember` maps each member to its node ids. `byLexicon` and
  *   `byComposite` keep their keys (a lexicon or composite type is the same
- *   thing in every member) and merge the ids. `byStack`, `byContainer` and
- *   `byWave` name things inside one member, so their keys are prefixed too.
+ *   thing in every member) and merge the ids. `byStack`, `byContainer`,
+ *   `byWave` and `byPipeline` name things inside one member, so their keys
+ *   are prefixed too.
+ * - Edges keep their `kind` and `crossPipeline` (#3910). A member's dangling
+ *   references (`ir.dangling`) land on the top-level `dangling` list with
+ *   `from` prefixed and a `member` field, like edges (#3922).
  * - `links` holds the member links (#2524 D6, #2539): the declared links and
  *   the joins inferred from members' `imports` and `exports` with the core
  *   `joinKey()`, labelled `exact` or `folded` (`./links.ts`). A declared link
@@ -36,7 +40,7 @@ import { graphLinks, type LinkTableRow } from "./links";
 import type { KindLinkRead } from "./kind-link-readers";
 import type { RecordLinkRow } from "./record-assets";
 import type { ReasonCode } from "./reason-codes";
-import { GRAPH_IR_VERSION, type GraphIR, type IRExport, type IRGroups, type IRImport, type IREdge, type IRNode } from "../graph-ir";
+import { GRAPH_IR_VERSION, type GraphIR, type IRExport, type IRDanglingRef, type IRGroups, type IRImport, type IREdge, type IRNode } from "../graph-ir";
 
 /** The version of the composed document `chant workspace graph` writes. */
 export const WORKSPACE_GRAPH_VERSION = 1;
@@ -165,6 +169,8 @@ export const COLLECTOR_META_KEY = "collector";
 /** `nested` names the nested workspace's member a node was read through (#2551); absent for the outer workspace's own nodes. */
 export type ComposedNode = IRNode & { member: string; nested?: string };
 export type ComposedEdge = IREdge & { member: string };
+/** A member's dangling reference (#3910, #3922): `from` is prefixed like a node id. `nested` as on {@link ComposedNode}. */
+export type ComposedDangling = IRDanglingRef & { member: string; nested?: string };
 
 export interface WorkspaceGraph {
   version: number;
@@ -176,6 +182,12 @@ export interface WorkspaceGraph {
   exports: (IRExport & { member: string })[];
   imports: (IRImport & { member: string })[];
   derivedAttrs?: Record<string, string[]>;
+  /**
+   * The members' dangling CI references (#3910, #3922): each `ir.dangling`
+   * entry with `from` prefixed by its member and a `member` field, sorted by
+   * `from`, `path` and `value`. Absent when no member has one.
+   */
+  dangling?: ComposedDangling[];
   /**
    * Member links (#2524 D6, #2539), declared and inferred, then the links of
    * the records read with `--kind` (#2549). Empty when no declaration is given.
@@ -289,6 +301,13 @@ function prefixRefs(value: unknown, member: string): unknown {
   return out;
 }
 
+/** The groups whose keys name something inside one member, so are prefixed with it. */
+export const SCOPED_GROUPS = ["byStack", "byContainer", "byWave", "byPipeline"] as const;
+type ScopedGroup = (typeof SCOPED_GROUPS)[number];
+
+/** The order the composed `dangling` list is sorted in. */
+export const danglingKey = (d: IRDanglingRef): string => `${d.from}\u0000${d.path}\u0000${d.value}`;
+
 function mergeInto(target: Record<string, string[]>, key: string, ids: string[]): void {
   (target[key] ??= []).push(...ids);
 }
@@ -317,7 +336,8 @@ export function composeWorkspaceGraph(
   const imports: WorkspaceGraph["imports"] = [];
   const byMember: Record<string, string[]> = {};
   const shared: Record<"byLexicon" | "byComposite", Record<string, string[]>> = { byLexicon: {}, byComposite: {} };
-  const scoped: Record<"byStack" | "byContainer" | "byWave", Record<string, string[]>> = { byStack: {}, byContainer: {}, byWave: {} };
+  const scoped: Record<ScopedGroup, Record<string, string[]>> = { byStack: {}, byContainer: {}, byWave: {}, byPipeline: {} };
+  const dangling: ComposedDangling[] = [];
   const derivedAttrs: Record<string, Set<string>> = {};
   const collectors: MemberCollector[] = [];
 
@@ -337,9 +357,10 @@ export function composeWorkspaceGraph(
     for (const key of ["byLexicon", "byComposite"] as const) {
       for (const [k, v] of Object.entries(ir.groups[key] ?? {})) mergeInto(shared[key], k, v.map((id) => prefix(m, id)));
     }
-    for (const key of ["byStack", "byContainer", "byWave"] as const) {
+    for (const key of SCOPED_GROUPS) {
       for (const [k, v] of Object.entries(ir.groups[key] ?? {})) mergeInto(scoped[key], prefix(m, k), v.map((id) => prefix(m, id)));
     }
+    for (const d of ir.dangling ?? []) dangling.push({ ...d, from: prefix(m, d.from), member: m });
     for (const e of ir.exports ?? []) exports.push({ ...e, ...(e.node ? { node: prefix(m, e.node) } : {}), member: m });
     for (const i of ir.imports ?? []) imports.push({ ...i, node: prefix(m, i.node), member: m });
     for (const [kind, attrs] of Object.entries(ir.derivedAttrs ?? {})) for (const a of attrs) (derivedAttrs[kind] ??= new Set()).add(a);
@@ -360,7 +381,7 @@ export function composeWorkspaceGraph(
 
   const groups: WorkspaceGraph["groups"] = { byMember };
   for (const key of ["byLexicon", "byComposite"] as const) if (Object.keys(shared[key]).length) groups[key] = sorted(shared[key]);
-  for (const key of ["byStack", "byContainer", "byWave"] as const) if (Object.keys(scoped[key]).length) groups[key] = sorted(scoped[key]);
+  for (const key of SCOPED_GROUPS) if (Object.keys(scoped[key]).length) groups[key] = sorted(scoped[key]);
 
   const doc: WorkspaceGraph = {
     version: WORKSPACE_GRAPH_VERSION,
@@ -377,6 +398,7 @@ export function composeWorkspaceGraph(
     collectors,
     records: [],
   };
+  if (dangling.length) doc.dangling = dangling.sort((a, b) => danglingKey(a).localeCompare(danglingKey(b)));
   if (Object.keys(derivedAttrs).length) {
     doc.derivedAttrs = Object.fromEntries(Object.keys(derivedAttrs).sort().map((k) => [k, [...derivedAttrs[k]].sort()]));
   }

package/src/workspace/graph-contract.test.ts

@@ -15,7 +15,7 @@ import { existsSync, readdirSync, readFileSync, rmSync, utimesSync, writeFileSyn
 import { join } from "node:path";
 import { afterAll, describe, expect, test } from "vitest";
 import { cleanScratch, commitAll, contract, declaration, declaration as declaration_, FAKE_FILE_GRAPH_CHANT, FAKE_GRAPH_CHANT, git, REPO, repo, scratchDir, validSchema } from "./__fixtures__/contract-repo";
-import type { GraphIR } from "../graph-ir";
+import type { GraphIR, IREdgeKind } from "../graph-ir";
 import { composeWorkspaceGraph, MEMBER_RUN_REASON_CODES } from "./compose-graph";
 import { parseDeclaration, WORKSPACE_ERROR_CODES } from "./declaration";
 import type { LinkTableRow } from "./links";
@@ -106,6 +106,31 @@ describe("the links section (#2539)", () => {
   });
 });
 
+describe("CI edges, pipelines and dangling references (#3922)", () => {
+  test("the edge kinds match IREdgeKind, and a composed CI member validates", () => {
+    const kinds: IREdgeKind[] = ["ref", "needs", "calls", "triggers", "includes", "extends"];
+    expect(schema.$defs.edge.properties.kind.enum).toEqual(kinds);
+    const ir: GraphIR = {
+      version: 1,
+      nodes: [
+        { id: "ci", kind: "Workflow", lexicon: "github", attrs: {} },
+        { id: "build", kind: "Job", lexicon: "github", attrs: {} },
+        { id: "deploy", kind: "Job", lexicon: "github", attrs: {} },
+      ],
+      edges: [
+        { from: "deploy", to: "build", kind: "needs", viaAttr: "needs" },
+        { from: "build", to: "ci", kind: "calls", viaAttr: "uses", crossPipeline: true },
+      ],
+      groups: { byPipeline: { ci: ["build", "ci", "deploy"] } },
+      dangling: [{ from: "deploy", kind: "needs", path: "needs", value: "lint" }, { from: "build", kind: "calls", path: "uses", value: "o/r/.github/workflows/x.yml@v1", crossPipeline: true }],
+    };
+    const m = { name: "svc", dir: "svc", kind: "chant", status: "composed" as const, reason: null, chant: "0.124.20", irVersion: 1, live: false };
+    const graph = composeWorkspaceGraph({ name: "acme", root: "." }, [{ member: m, ir }]);
+    expect(graph.dangling).toHaveLength(2);
+    expectValid({ $schema: GRAPH_OUTPUT_SCHEMA_ID, contract: 1, chant: "0.124.20", at: null, ...graph });
+  });
+});
+
 describe("the collectors section (#2559)", () => {
   const topology = {
     pipelines: [{ id: "traces", signal: "traces", receivers: ["otlp"], processors: [], exporters: ["otlphttp"] }],

package/src/workspace/graph.schema.json

@@ -93,6 +93,13 @@
             "$ref": "#/$defs/edge"
           }
         },
+        "dangling": {
+          "description": "Added in contract 1 by #3922. The members' references whose target is no node of their graph (#3910): a job `needs` a job no workflow declares, a `uses:` names another repository's workflow, a GitLab `include:` names a file chant did not generate. Each member's `ir.dangling` entry with `from` prefixed by its member and a `member` field, sorted by `from`, `path` and `value`. Absent when no member has one.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/dangling"
+          }
+        },
         "groups": {
           "type": "object",
           "required": [
@@ -158,6 +165,16 @@
                 }
               },
               "description": "Keys prefixed with the member."
+            },
+            "byPipeline": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "description": "Added in contract 1 by #3922. CI pipeline membership (#3910): a workflow or pipeline the member's CI lexicon reports, with the node ids it runs. Keys prefixed with the member, like byStack. Edges with `crossPipeline` run between these groups."
             }
           }
         },
@@ -523,7 +540,15 @@
           "type": "string"
         },
         "kind": {
-          "type": "string"
+          "enum": [
+            "ref",
+            "needs",
+            "calls",
+            "triggers",
+            "includes",
+            "extends"
+          ],
+          "description": "`ref` for an edge from a typed reference. The CI kinds (#3910): `needs` (a job waits on another), `calls` (a reusable workflow or action is used), `triggers` (a pipeline starts another), `includes` (a file is pulled in), `extends` (a GitLab job inherits another). The list grows within contract 1; a reader ignores a kind it does not know."
         },
         "viaAttr": {
           "type": "string"
@@ -531,11 +556,53 @@
         "toAttr": {
           "type": "string"
         },
+        "crossPipeline": {
+          "type": "boolean",
+          "description": "Added in contract 1 by #3922. True when the edge leaves the pipeline `from` belongs to (#3910): a reusable-workflow call, a `workflow_run` trigger, a GitLab child or multi-project trigger, an include. Absent on every in-pipeline edge."
+        },
         "member": {
           "type": "string"
         }
       }
     },
+    "dangling": {
+      "type": "object",
+      "required": [
+        "from",
+        "kind",
+        "path",
+        "value",
+        "member"
+      ],
+      "properties": {
+        "from": {
+          "type": "string",
+          "description": "The node holding the reference, prefixed with its member."
+        },
+        "kind": {
+          "$ref": "#/$defs/edge/properties/kind"
+        },
+        "path": {
+          "type": "string",
+          "description": "Where on `from` it was written, such as `needs`, `uses` or `trigger.include`."
+        },
+        "value": {
+          "type": "string",
+          "description": "The reference exactly as written."
+        },
+        "crossPipeline": {
+          "type": "boolean",
+          "description": "As on an edge."
+        },
+        "member": {
+          "type": "string"
+        },
+        "nested": {
+          "type": "string",
+          "description": "For a member of kind `workspace`: the nested workspace's member the reference was read through, as on a node."
+        }
+      }
+    },
     "failure": {
       "description": "The declaration could not be read, and nothing was composed. Exit code 1.",
       "type": "object",

package/src/workspace/nested-graph.test.ts

@@ -97,6 +97,20 @@ describe("foldNested", () => {
   });
 });
 
+describe("foldNested with CI pipelines and dangling references (#3922)", () => {
+  test("prefixes byPipeline and dangling with the outer member, and keeps the nested member on each reference", () => {
+    const outer = composeWorkspaceGraph({ name: "outer", root: "." }, [
+      { member: member("platform", { kind: "workspace", status: "skipped", reason: { code: "kind-not-run", message: "nested" }, chant: null, irVersion: null }) },
+    ]);
+    const inner = innerGraph();
+    inner.groups.byPipeline = { "api/ci": ["api/Queue"] };
+    inner.dangling = [{ from: "api/Queue", kind: "needs", path: "needs", value: "lint", member: "api" }];
+    foldNested(outer, outer.members[0], inner);
+    expect(outer.groups.byPipeline).toEqual({ "platform/api/ci": ["platform/api/Queue"] });
+    expect(outer.dangling).toEqual([{ from: "platform/api/Queue", kind: "needs", path: "needs", value: "lint", member: "platform", nested: "api" }]);
+  });
+});
+
 describe("the outer workspace never writes inside a nested one", () => {
   let root: string;
   afterEach(() => rmSync(root, { recursive: true, force: true }));

package/src/workspace/nested-graph.ts

@@ -22,7 +22,7 @@
 
 import { spawn } from "node:child_process";
 import type { ParsedArgs } from "../cli/registry";
-import type { ComposedMember, ComposedNode, WorkspaceGraph } from "./compose-graph";
+import { danglingKey, SCOPED_GROUPS, type ComposedMember, type ComposedNode, type WorkspaceGraph } from "./compose-graph";
 
 export type { NestedWorkspace } from "./compose-graph";
 import { readerToolchain, type Toolchain } from "./member-commands";
@@ -148,12 +148,17 @@ export function foldNested(graph: WorkspaceGraph, member: ComposedMember, inner:
       into[k] = [...(into[k] ?? []), ...v.map((id) => prefixed(outer, id))].sort();
     }
   }
-  for (const key of ["byStack", "byContainer", "byWave"] as const) {
+  for (const key of SCOPED_GROUPS) {
     for (const [k, v] of Object.entries(innerGroups[key] ?? {})) {
       const into = (groups[key] ??= {});
       into[prefixed(outer, k)] = v.map((id) => prefixed(outer, id)).sort();
     }
   }
+  if (inner.dangling?.length) {
+    graph.dangling = [...(graph.dangling ?? []), ...inner.dangling.map((d) => ({ ...d, from: prefixed(outer, d.from), member: outer, nested: d.member }))].sort((a, b) =>
+      danglingKey(a).localeCompare(danglingKey(b)),
+    );
+  }
   for (const c of inner.collectors ?? []) graph.collectors.push({ ...c, member: prefixed(outer, c.member) });
   for (const [kind, attrs] of Object.entries(inner.derivedAttrs ?? {})) {
     const all = new Set([...(graph.derivedAttrs?.[kind] ?? []), ...attrs]);

package/src/workspace/runs.ts

@@ -55,7 +55,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { z } from "zod";
-import { describeLifecyclePush, fetchLifecycleStatus, type LifecyclePushStatus, pushLifecycleStatus, readBlobBySha, RefCASConflictError, writeLedgerFiles } from "../lifecycle/git";
+import { describeLifecyclePush, fetchLifecycleStatus, ledgerRevision, type LifecyclePushStatus, pushLifecycleStatus, readBlobBySha, RefCASConflictError, writeLedgerFiles } from "../lifecycle/git";
 import { resolveMemberLedger } from "../lifecycle/member-ledger";
 import { sortedJsonReplacer } from "../utils";
 import { followSquashes, type SquashFollow } from "./squash";
@@ -509,7 +509,9 @@ async function appendRun(top: string, rootOnDisk: string, id: string, make: (exi
   let written: RunLine[] = [];
   let lastErr: unknown;
   for (let attempt = 1; attempt <= APPEND_RETRY_ATTEMPTS && commit === undefined; attempt++) {
-    const prior = git(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${LEDGER_BRANCH}:${path}`])?.trim() || null;
+    // #3955: in a run that records nothing, the run's own unrecorded tip.
+    const rev = await ledgerRevision(top);
+    const prior = git(top, ["rev-parse", "--verify", "--quiet", `${rev === LEDGER_BRANCH ? `refs/heads/${LEDGER_BRANCH}` : rev}:${path}`])?.trim() || null;
     const text = prior ? ((await readBlobBySha(prior, { cwd: top })) ?? "") : "";
     const existing = parseRunFile(text, id).lines;
     const lines = make(existing);