@intentius/chant 0.100.0 → 0.102.0

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

@@ -14,7 +14,7 @@
 import { existsSync, readdirSync, readFileSync, rmSync, utimesSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { afterAll, describe, expect, test } from "vitest";
-import { cleanScratch, commitAll, contract, declaration, declaration as declaration_, FAKE_GRAPH_CHANT, git, REPO, repo, scratchDir, validSchema } from "./__fixtures__/contract-repo";
+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 { composeWorkspaceGraph, MEMBER_RUN_REASON_CODES } from "./compose-graph";
 import { parseDeclaration, WORKSPACE_ERROR_CODES } from "./declaration";
@@ -106,12 +106,97 @@ describe("the links section (#2539)", () => {
   });
 });
 
+describe("the collectors section (#2559)", () => {
+  const topology = {
+    pipelines: [{ id: "traces", signal: "traces", receivers: ["otlp"], processors: [], exporters: ["otlphttp"] }],
+    components: [{ id: "otlphttp", kind: "exporter", type: "otlphttp", endpoints: ["https://collector.example:4318"], pipelines: ["traces"] }],
+    exporters: [{ id: "otlphttp", type: "otlphttp", endpoints: ["https://collector.example:4318"], pipelines: ["traces"], signals: ["traces"] }],
+  };
+  /** A member whose chant answers from ir.json, as one whose project declares a collector does. */
+  const collectorWorkspace = () =>
+    repo({
+      "chant.workspace.json": declaration([{ name: "ops", dir: "ops", kind: "chant" }, { name: "web", dir: "web", kind: "chant" }]),
+      "ops/chant.config.ts": "export default {};\n",
+      "ops/ir.json": JSON.stringify({ version: 1, nodes: [], edges: [], groups: {}, meta: { collector: topology } }),
+      "web/chant.config.ts": "export default {};\n",
+      "web/ir.json": JSON.stringify({ version: 1, nodes: [], edges: [], groups: {} }),
+      ".gitignore": "node_modules\n",
+      "node_modules/.bin/chant": { text: FAKE_FILE_GRAPH_CHANT, mode: 0o755 },
+    });
+
+  test("the schema requires collectors and describes each entry", () => {
+    const required = (schema.$defs.result as { required: string[] }).required;
+    expect(required).toContain("collectors");
+    expect((schema.$defs.collector as { required: string[] }).required).toEqual(["member", "pipelines", "components", "exporters"]);
+  });
+
+  test("a workspace whose member declares a collector lists its pipelines and exporters, and validates", async () => {
+    const { doc } = await workspaceGraph({ cwd: collectorWorkspace() });
+    const g = result(doc);
+    expectValid(g);
+    expect(g.collectors.map((c) => c.member)).toEqual(["ops"]);
+    expect(g.collectors[0]!.pipelines.map((p) => p.id)).toEqual(["traces"]);
+    expect(g.collectors[0]!.exporters).toEqual(topology.exporters);
+    expect(g.members.find((m) => m.name === "ops")!.meta).toBeUndefined();
+  });
+
+  test("telemetry links resolve against the collectors and validate (#2558)", async () => {
+    const withProtocols = {
+      pipelines: topology.pipelines,
+      components: [
+        { id: "otlp", kind: "receiver", type: "otlp", endpoints: ["0.0.0.0:4318"], protocols: ["http/protobuf", "http/json"], pipelines: ["traces"] },
+        { id: "otlphttp", kind: "exporter", type: "otlphttp", endpoints: ["https://collector.example:4318"], protocols: ["http/protobuf"], pipelines: ["traces"] },
+      ],
+      exporters: topology.exporters,
+    };
+    const cwd = repo({
+      "chant.workspace.json": declaration([
+        { name: "ops", dir: "ops", kind: "chant" },
+        {
+          name: "web",
+          dir: "web",
+          kind: "chant",
+          links: [
+            { member: "ops", output: "traces", kind: "telemetry", protocol: "http/protobuf" },
+            { member: "ops", output: "traces", kind: "telemetry", protocol: "grpc" },
+            { member: "ops", output: "logs", kind: "telemetry" },
+          ],
+        },
+      ]),
+      "ops/chant.config.ts": "export default {};\n",
+      "ops/ir.json": JSON.stringify({ version: 1, nodes: [], edges: [], groups: {}, meta: { collector: withProtocols } }),
+      "web/chant.config.ts": "export default {};\n",
+      "web/ir.json": JSON.stringify({ version: 1, nodes: [], edges: [], groups: {} }),
+      ".gitignore": "node_modules\n",
+      "node_modules/.bin/chant": { text: FAKE_FILE_GRAPH_CHANT, mode: 0o755 },
+    });
+    const { doc } = await workspaceGraph({ cwd });
+    const g = result(doc);
+    expectValid(g);
+    const rows = (g.links as LinkTableRow[]).filter((r) => r.kind === "telemetry").map((r) => (r.status === "ambiguous" ? "" : `${r.output} ${r.protocol ?? "-"} ${r.status} ${r.target ?? "-"}`));
+    expect(rows).toEqual(["traces http/protobuf resolved pipeline", "traces grpc invalid pipeline", "logs - missing -"]);
+  });
+
+  test("a workspace with no collector prints an empty list", async () => {
+    const { doc } = await workspaceGraph({ cwd: fakeWorkspace() });
+    const g = result(doc);
+    expectValid(g);
+    expect(g.collectors).toEqual([]);
+  });
+
+  test("a collector with no exporters list does not validate", () => {
+    const bad = { member: "ops", pipelines: [], components: [] };
+    expect(() => expectValid({ $schema: GRAPH_OUTPUT_SCHEMA_ID, contract: 1, chant: "0.81.0", at: null, ...composeWorkspaceGraph({ name: "x", root: "." }, []), collectors: [bad] })).toThrow();
+  });
+});
+
 describe("chant workspace graph on the chant repo (#2557)", () => {
   // The one terraform member runs through the terraform lexicon (#2874), a
-  // real chant per read; kind-readers.e2e.test.ts covers that. Here it is
-  // left out, so nothing runs.
+  // real chant per read; kind-readers.e2e.test.ts covers that. The nested
+  // reference workspace runs its own chant workspace graph (#2551);
+  // read-contract.test.ts covers that. Here both are left out, so nothing runs.
   const notRun = (JSON.parse(readFileSync(join(REPO, "chant.workspace.json"), "utf-8")) as { members: { name: string; kind: string }[] }).members
-    .filter((m) => m.kind !== "terraform" && m.kind !== "choudoufu")
+    .filter((m) => m.kind !== "terraform" && m.kind !== "choudoufu" && m.kind !== "workspace")
     .map((m) => m.name);
 
   test("validates, and lists every member but the terraform one as skipped: none is kind chant", async () => {

package/src/workspace/graph.schema.json

@@ -29,6 +29,7 @@
         "exports",
         "imports",
         "links",
+        "collectors",
         "records"
       ],
       "properties": {
@@ -223,12 +224,23 @@
             "$ref": "#/$defs/link"
           }
         },
+        "collectors": {
+          "type": "array",
+          "description": "The collector pipelines and exporters of each member that declares a collector, in declaration order (#2559). A member reports them from its own IR (`meta.collector`), which the lexicon that types the collector config writes, so chant itself reads no collector config. Empty when no member declares one. A reader joins a telemetry endpoint to the pipeline or exporter it names through `exporters[].endpoints` and `pipelines[].id`.",
+          "items": {
+            "$ref": "#/$defs/collector"
+          }
+        },
         "records": {
           "type": "array",
           "description": "The records read with --kind (#2524 D4, #2549), sorted by path; empty without it. A record link in `links` names its record by id.",
           "items": {
             "$ref": "#/$defs/record"
           }
+        },
+        "plantable": {
+          "description": "Added in contract 1 by #3146. Whether a host such as a studio's planter can plant the workspace as one box: exactly one member's box block declares services, read from the declaration at the revision read. Not a check: a records-only or infra workspace is valid and simply not plantable.",
+          "$ref": "#/$defs/plantable"
         }
       }
     },
@@ -330,6 +342,77 @@
         },
         "pipeline": {
           "description": "The member IR's pipeline projection, when it has one."
+        },
+        "nested": {
+          "type": "object",
+          "description": "For a member of kind workspace (#2551): the nested workspace, read read-only through its own chant workspace graph. Its nodes, edges, exports and imports are in the outer sections with `<member>/<nested member>/<id>` ids, and each node names its nested member in `nested`. The outer workspace never writes inside it.",
+          "required": [
+            "name",
+            "contract",
+            "members",
+            "links"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "The nested declaration's name."
+            },
+            "contract": {
+              "type": "integer",
+              "description": "The contract version of the nested read's document."
+            },
+            "members": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/member"
+              },
+              "description": "The nested workspace's members as its own graph lists them, with their own names and directories (relative to the nested root)."
+            },
+            "links": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/link"
+              },
+              "description": "The nested workspace's links, naming its members as the nested side does."
+            }
+          }
+        },
+        "box": {
+          "description": "Added in contract 1 by #3146. The factory and listing the member's box block declares (ws-077), read from the declaration at the revision read, so --at gives them as they were. null when the box declares neither, or the member has no box block; the rest of the box block is in chant workspace status --json.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "factory",
+                "listing"
+              ],
+              "properties": {
+                "factory": {
+                  "oneOf": [
+                    {
+                      "type": "null"
+                    },
+                    {
+                      "$ref": "#/$defs/factory"
+                    }
+                  ]
+                },
+                "listing": {
+                  "oneOf": [
+                    {
+                      "type": "null"
+                    },
+                    {
+                      "$ref": "#/$defs/listing"
+                    }
+                  ]
+                }
+              }
+            }
+          ]
         }
       },
       "if": {
@@ -396,6 +479,10 @@
         "runtimeOwner": {
           "type": "string"
         },
+        "nested": {
+          "type": "string",
+          "description": "For a node read through a nested workspace (#2551): the nested workspace's member it belongs to. `member` is then the outer member, and the id is `<member>/<nested>/<id>`."
+        },
         "sourceLoc": {
           "type": "object",
           "required": [
@@ -544,7 +631,7 @@
             },
             "kind": {
               "type": "string",
-              "description": "What the link joins, such as output."
+              "description": "What the link joins: `output`, or `telemetry` (#2558), where the consumer sends its telemetry to a pipeline or exporter of the producer's collector and `output` names it."
             },
             "origin": {
               "enum": [
@@ -599,6 +686,21 @@
             "pointer": {
               "type": "string",
               "description": "The declared link's JSON Pointer in the declaration; left out of the graph for a declared link."
+            },
+            "protocol": {
+              "enum": [
+                "grpc",
+                "http/protobuf",
+                "http/json"
+              ],
+              "description": "A telemetry link: the OTLP protocol it states."
+            },
+            "target": {
+              "enum": [
+                "pipeline",
+                "exporter"
+              ],
+              "description": "A telemetry link that found its target: whether `output` named a pipeline or an exporter in the producer's `collectors` entry."
             }
           }
         },
@@ -764,6 +866,150 @@
         }
       ]
     },
+    "collector": {
+      "type": "object",
+      "required": [
+        "member",
+        "pipelines",
+        "components",
+        "exporters"
+      ],
+      "properties": {
+        "member": {
+          "type": "string",
+          "description": "The member whose source declares the collector."
+        },
+        "pipelines": {
+          "type": "array",
+          "description": "Each pipeline under `service.pipelines`.",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "signal",
+              "receivers",
+              "processors",
+              "exporters"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "The pipeline id, such as `traces` or `traces/backend`."
+              },
+              "signal": {
+                "type": "string",
+                "description": "`traces`, `metrics` or `logs`."
+              },
+              "receivers": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "processors": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "exporters": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "components": {
+          "type": "array",
+          "description": "Every receiver, processor, exporter, connector and extension, with the addresses its config states.",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "kind",
+              "type",
+              "endpoints",
+              "protocols",
+              "pipelines"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "The collector id, `type` or `type/name`."
+              },
+              "kind": {
+                "type": "string",
+                "description": "`receiver`, `processor`, `exporter`, `connector` or `extension`."
+              },
+              "type": {
+                "type": "string"
+              },
+              "endpoints": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "protocols": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "The wire protocols the component speaks, as OTLP SDKs name them: `grpc`, `http/protobuf` or `http/json`. Empty when its definition states none, which a telemetry link's protocol check reads as unknown."
+              },
+              "pipelines": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "exporters": {
+          "type": "array",
+          "description": "The exporters again, with the signals that reach each: where the member's telemetry is sent.",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "type",
+              "endpoints",
+              "pipelines",
+              "signals"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string"
+              },
+              "endpoints": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "pipelines": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "signals": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "record": {
       "type": "object",
       "required": [
@@ -814,6 +1060,212 @@
           }
         }
       }
+    },
+    "plantable": {
+      "type": "object",
+      "required": [
+        "plantable",
+        "box",
+        "reason"
+      ],
+      "properties": {
+        "plantable": {
+          "type": "boolean"
+        },
+        "box": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The member whose box block declares services, or null when the workspace isn't plantable."
+        },
+        "reason": {
+          "description": "Why the workspace isn't plantable, or null when it is.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "code",
+                "message"
+              ],
+              "properties": {
+                "code": {
+                  "enum": [
+                    "box-none",
+                    "box-several"
+                  ]
+                },
+                "message": {
+                  "type": "string"
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "factory": {
+      "type": "object",
+      "required": [
+        "builds",
+        "check",
+        "checks",
+        "builders",
+        "publish"
+      ],
+      "properties": {
+        "builds": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          },
+          "description": "The members the factory builds, in declaration order. A work item a person asks for constrains member:<the first>."
+        },
+        "check": {
+          "description": "The verdict command, run from the workspace root, and what it is; null when none is declared.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "run",
+                "kind"
+              ],
+              "properties": {
+                "run": {
+                  "type": "string"
+                },
+                "kind": {
+                  "enum": [
+                    "test",
+                    "build",
+                    "lint",
+                    "plan",
+                    "conformance"
+                  ]
+                }
+              }
+            }
+          ]
+        },
+        "checks": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Where a work item's builder writes its check, from the workspace root, or null for the orchestrator's choice."
+        },
+        "builders": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The member that declares the builder agents, or null."
+        },
+        "publish": {
+          "description": "Where a finished build is published, or null when the factory doesn't publish past the box.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "forge",
+                "repo",
+                "base",
+                "branchPrefix",
+                "head"
+              ],
+              "properties": {
+                "forge": {
+                  "const": "github"
+                },
+                "repo": {
+                  "type": "string",
+                  "description": "owner/name: where the pull request is opened."
+                },
+                "base": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The branch the pull request targets, or null for the repository's default branch."
+                },
+                "branchPrefix": {
+                  "type": "string",
+                  "description": "What the published branch's name starts with, before the work item's id. chant/work/ unless declared."
+                },
+                "head": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "owner/name of the fork the branch is pushed to, or null to push to repo."
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "listing": {
+      "type": "object",
+      "required": [
+        "published",
+        "title",
+        "line",
+        "cover"
+      ],
+      "properties": {
+        "published": {
+          "type": "boolean",
+          "description": "Whether the box is listed; true unless declared otherwise."
+        },
+        "title": {
+          "type": "string",
+          "description": "Empty when not declared: a reader shows a name of its own."
+        },
+        "line": {
+          "type": "string",
+          "description": "Empty when not declared."
+        },
+        "cover": {
+          "description": "The cover image, or null when none is declared.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "path",
+                "sha256"
+              ],
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "description": "From the workspace root."
+                },
+                "sha256": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "pattern": "^[0-9a-f]{64}$",
+                  "description": "The sha256 of the file's bytes at the revision read, or null when it can't be read."
+                }
+              }
+            }
+          ]
+        }
+      }
     }
   }
 }