@intentius/chant 0.124.96 → 0.124.98

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (237) hide show
  1. package/dist/audit/core.d.ts +29 -0
  2. package/dist/audit/core.d.ts.map +1 -1
  3. package/dist/audit/core.js +48 -11
  4. package/dist/audit/identity.d.ts +27 -0
  5. package/dist/audit/identity.d.ts.map +1 -0
  6. package/dist/audit/identity.js +36 -0
  7. package/dist/audit/report-html.d.ts +3 -1
  8. package/dist/audit/report-html.d.ts.map +1 -1
  9. package/dist/audit/report-html.js +1 -1
  10. package/dist/audit/report-model.d.ts +16 -0
  11. package/dist/audit/report-model.d.ts.map +1 -1
  12. package/dist/audit/report-model.js +5 -1
  13. package/dist/change-set-graph.d.ts +3 -1
  14. package/dist/change-set-graph.d.ts.map +1 -1
  15. package/dist/change-set-graph.js +7 -1
  16. package/dist/change-set.d.ts +5 -2
  17. package/dist/change-set.d.ts.map +1 -1
  18. package/dist/change-set.js +6 -3
  19. package/dist/ci-agent.d.ts +17 -0
  20. package/dist/ci-agent.d.ts.map +1 -1
  21. package/dist/ci-agent.js +32 -0
  22. package/dist/ci-comment-allow.d.ts +88 -0
  23. package/dist/ci-comment-allow.d.ts.map +1 -0
  24. package/dist/ci-comment-allow.js +178 -0
  25. package/dist/ci-comment-commands.d.ts +12 -0
  26. package/dist/ci-comment-commands.d.ts.map +1 -1
  27. package/dist/ci-comment-commands.js +22 -0
  28. package/dist/ci-control.d.ts +6 -1
  29. package/dist/ci-control.d.ts.map +1 -1
  30. package/dist/ci-control.js +6 -1
  31. package/dist/ci-product.d.ts +3 -0
  32. package/dist/ci-product.d.ts.map +1 -1
  33. package/dist/ci-product.js +3 -0
  34. package/dist/cli/commands/audit.d.ts +3 -1
  35. package/dist/cli/commands/audit.d.ts.map +1 -1
  36. package/dist/cli/commands/audit.js +23 -6
  37. package/dist/cli/commands/import.d.ts +8 -1
  38. package/dist/cli/commands/import.d.ts.map +1 -1
  39. package/dist/cli/commands/import.js +31 -6
  40. package/dist/cli/handlers/agent.d.ts.map +1 -1
  41. package/dist/cli/handlers/agent.js +12 -2
  42. package/dist/cli/handlers/pr-comment.d.ts +6 -0
  43. package/dist/cli/handlers/pr-comment.d.ts.map +1 -1
  44. package/dist/cli/handlers/pr-comment.js +12 -0
  45. package/dist/cli/handlers/promote.d.ts.map +1 -1
  46. package/dist/cli/handlers/promote.js +53 -6
  47. package/dist/cli/main.d.ts.map +1 -1
  48. package/dist/cli/main.js +29 -6
  49. package/dist/cli/parse-args.d.ts.map +1 -1
  50. package/dist/cli/parse-args.js +23 -0
  51. package/dist/cli/registry.d.ts +8 -0
  52. package/dist/cli/registry.d.ts.map +1 -1
  53. package/dist/cloud-lister/mask.d.ts +30 -1
  54. package/dist/cloud-lister/mask.d.ts.map +1 -1
  55. package/dist/cloud-lister/mask.js +66 -3
  56. package/dist/components/driver.d.ts +8 -1
  57. package/dist/components/driver.d.ts.map +1 -1
  58. package/dist/components/driver.js +1 -0
  59. package/dist/components/product-pipeline.d.ts +23 -1
  60. package/dist/components/product-pipeline.d.ts.map +1 -1
  61. package/dist/components/product-pipeline.js +40 -7
  62. package/dist/components/product-plan.d.ts +20 -0
  63. package/dist/components/product-plan.d.ts.map +1 -1
  64. package/dist/components/product-plan.js +11 -1
  65. package/dist/control/applied.d.ts +8 -1
  66. package/dist/control/applied.d.ts.map +1 -1
  67. package/dist/control/applied.js +18 -2
  68. package/dist/control/dispatch.d.ts +52 -0
  69. package/dist/control/dispatch.d.ts.map +1 -1
  70. package/dist/control/dispatch.js +140 -4
  71. package/dist/control/train.d.ts +198 -0
  72. package/dist/control/train.d.ts.map +1 -0
  73. package/dist/control/train.js +294 -0
  74. package/dist/deep-observation.js +2 -2
  75. package/dist/floor-table.data.d.ts.map +1 -1
  76. package/dist/floor-table.data.js +7 -1
  77. package/dist/graph-detail.d.ts +9 -0
  78. package/dist/graph-detail.d.ts.map +1 -1
  79. package/dist/graph-detail.js +38 -13
  80. package/dist/graph-refs.d.ts +233 -3
  81. package/dist/graph-refs.d.ts.map +1 -1
  82. package/dist/graph-refs.js +106 -15
  83. package/dist/lint/post-synth.d.ts +22 -0
  84. package/dist/lint/post-synth.d.ts.map +1 -1
  85. package/dist/lint/rules/declarable-naming-convention.d.ts +12 -0
  86. package/dist/lint/rules/declarable-naming-convention.d.ts.map +1 -1
  87. package/dist/lint/rules/declarable-naming-convention.js +38 -8
  88. package/dist/lint/rules/imported-source.d.ts +20 -0
  89. package/dist/lint/rules/imported-source.d.ts.map +1 -0
  90. package/dist/lint/rules/imported-source.js +27 -0
  91. package/dist/lint/rules/no-unused-declarable.d.ts.map +1 -1
  92. package/dist/lint/rules/no-unused-declarable.js +3 -0
  93. package/dist/op/gate.d.ts +2 -0
  94. package/dist/op/gate.d.ts.map +1 -1
  95. package/dist/op/gate.js +8 -1
  96. package/dist/pr-forge-reads.d.ts +17 -0
  97. package/dist/pr-forge-reads.d.ts.map +1 -1
  98. package/dist/pr-forge-reads.js +55 -0
  99. package/dist/reconcile.d.ts +9 -0
  100. package/dist/reconcile.d.ts.map +1 -1
  101. package/dist/release-floors.d.ts +9 -1
  102. package/dist/release-floors.d.ts.map +1 -1
  103. package/dist/release-floors.js +10 -2
  104. package/dist/repo-path.d.ts +29 -0
  105. package/dist/repo-path.d.ts.map +1 -0
  106. package/dist/repo-path.js +81 -0
  107. package/dist/sensitive-key.d.ts +23 -0
  108. package/dist/sensitive-key.d.ts.map +1 -1
  109. package/dist/sensitive-key.js +37 -0
  110. package/dist/terraform/hcl2json.d.ts +7 -0
  111. package/dist/terraform/hcl2json.d.ts.map +1 -1
  112. package/dist/terraform/hcl2json.js +7 -0
  113. package/dist/wave-runtime.mjs +352 -345
  114. package/dist/workspace/catalog-edges.d.ts +147 -0
  115. package/dist/workspace/catalog-edges.d.ts.map +1 -0
  116. package/dist/workspace/catalog-edges.js +461 -0
  117. package/dist/workspace/compose-graph.d.ts +73 -3
  118. package/dist/workspace/compose-graph.d.ts.map +1 -1
  119. package/dist/workspace/declaration.d.ts +2 -0
  120. package/dist/workspace/declaration.d.ts.map +1 -1
  121. package/dist/workspace/declaration.js +1 -0
  122. package/dist/workspace/declaration.schema.json +6 -0
  123. package/dist/workspace/discover.d.ts +134 -0
  124. package/dist/workspace/discover.d.ts.map +1 -0
  125. package/dist/workspace/discover.js +372 -0
  126. package/dist/workspace/graph-cli.d.ts +20 -0
  127. package/dist/workspace/graph-cli.d.ts.map +1 -1
  128. package/dist/workspace/graph-cli.js +178 -20
  129. package/dist/workspace/graph.schema.json +195 -2
  130. package/dist/workspace/release-train.d.ts +214 -3
  131. package/dist/workspace/release-train.d.ts.map +1 -1
  132. package/dist/workspace/release-train.js +552 -16
  133. package/dist/workspace/repo-ref.d.ts +14 -0
  134. package/dist/workspace/repo-ref.d.ts.map +1 -1
  135. package/dist/workspace/repo-ref.js +26 -1
  136. package/dist/workspace/workspace-gates.d.ts +24 -0
  137. package/dist/workspace/workspace-gates.d.ts.map +1 -1
  138. package/dist/workspace/workspace-gates.js +29 -5
  139. package/dist/workspace/workspace-ledger.d.ts +31 -5
  140. package/dist/workspace/workspace-ledger.d.ts.map +1 -1
  141. package/dist/workspace/workspace-ledger.js +2 -1
  142. package/dist/workspace/workspace-run.d.ts +14 -0
  143. package/dist/workspace/workspace-run.d.ts.map +1 -1
  144. package/dist/workspace/workspace-run.js +2 -2
  145. package/dist/yaml.d.ts.map +1 -1
  146. package/dist/yaml.js +33 -8
  147. package/package.json +1 -1
  148. package/src/audit/core.test.ts +64 -1
  149. package/src/audit/core.ts +75 -10
  150. package/src/audit/identity.test.ts +31 -0
  151. package/src/audit/identity.ts +43 -0
  152. package/src/audit/report-html.ts +4 -2
  153. package/src/audit/report-model.ts +21 -1
  154. package/src/change-set-graph.test.ts +33 -1
  155. package/src/change-set-graph.ts +7 -1
  156. package/src/change-set.ts +6 -3
  157. package/src/ci-agent.test.ts +32 -0
  158. package/src/ci-agent.ts +42 -0
  159. package/src/ci-comment-allow.test.ts +380 -0
  160. package/src/ci-comment-allow.ts +184 -0
  161. package/src/ci-comment-commands.ts +25 -0
  162. package/src/ci-control.ts +42 -0
  163. package/src/ci-product.ts +3 -0
  164. package/src/cli/commands/audit-parser-notice.test.ts +74 -0
  165. package/src/cli/commands/audit.test.ts +12 -0
  166. package/src/cli/commands/audit.ts +25 -7
  167. package/src/cli/commands/import-layout.test.ts +2 -1
  168. package/src/cli/commands/import.ts +29 -6
  169. package/src/cli/handlers/agent.ts +13 -2
  170. package/src/cli/handlers/pr-before-merge.test.ts +18 -0
  171. package/src/cli/handlers/pr-comment.ts +12 -0
  172. package/src/cli/handlers/promote.test.ts +68 -0
  173. package/src/cli/handlers/promote.ts +52 -6
  174. package/src/cli/main.test.ts +5 -0
  175. package/src/cli/main.ts +29 -6
  176. package/src/cli/parse-args.ts +18 -0
  177. package/src/cli/registry.ts +8 -0
  178. package/src/cloud-lister/kubernetes.k3d.e2e.test.ts +104 -0
  179. package/src/cloud-lister/mask-references.test.ts +132 -0
  180. package/src/cloud-lister/mask.ts +68 -3
  181. package/src/components/driver.ts +9 -1
  182. package/src/components/product-pipeline.ts +57 -7
  183. package/src/components/product-plan.ts +27 -2
  184. package/src/control/applied.ts +33 -3
  185. package/src/control/dispatch.ts +156 -5
  186. package/src/control/train.test.ts +215 -0
  187. package/src/control/train.ts +413 -0
  188. package/src/deep-observation.ts +2 -2
  189. package/src/floor-table.data.ts +7 -1
  190. package/src/graph-detail.ts +37 -12
  191. package/src/graph-refs.test.ts +45 -1
  192. package/src/graph-refs.ts +321 -14
  193. package/src/lint/post-synth.ts +20 -0
  194. package/src/lint/rules/declarable-naming-convention.test.ts +35 -1
  195. package/src/lint/rules/declarable-naming-convention.ts +35 -8
  196. package/src/lint/rules/imported-source.test.ts +22 -0
  197. package/src/lint/rules/imported-source.ts +31 -0
  198. package/src/lint/rules/no-unused-declarable.test.ts +16 -0
  199. package/src/lint/rules/no-unused-declarable.ts +7 -0
  200. package/src/op/gate.ts +10 -2
  201. package/src/pr-forge-reads.ts +62 -0
  202. package/src/reconcile.ts +9 -0
  203. package/src/release-floors.ts +14 -2
  204. package/src/repo-path.test.ts +72 -0
  205. package/src/repo-path.ts +103 -0
  206. package/src/sensitive-key.ts +38 -0
  207. package/src/terraform/hcl2json.ts +8 -0
  208. package/src/workspace/application-set.e2e.test.ts +405 -0
  209. package/src/workspace/catalog-edges.ts +507 -0
  210. package/src/workspace/ci-green-workflow.test.ts +2 -2
  211. package/src/workspace/cluster-join.e2e.test.ts +150 -0
  212. package/src/workspace/compose-graph.ts +74 -5
  213. package/src/workspace/declaration.schema.json +6 -0
  214. package/src/workspace/declaration.ts +3 -0
  215. package/src/workspace/discover.e2e.test.ts +122 -0
  216. package/src/workspace/discover.test.ts +225 -0
  217. package/src/workspace/discover.ts +406 -0
  218. package/src/workspace/drift-reader.test.ts +3 -3
  219. package/src/workspace/external-secret-catalog.e2e.test.ts +98 -0
  220. package/src/workspace/external-secret-catalog.test.ts +142 -0
  221. package/src/workspace/graph-cli.ts +207 -21
  222. package/src/workspace/graph-contract.test.ts +92 -0
  223. package/src/workspace/graph.schema.json +195 -2
  224. package/src/workspace/helm-references.e2e.test.ts +135 -0
  225. package/src/workspace/identity-annotation-catalog.e2e.test.ts +91 -0
  226. package/src/workspace/identity-annotation-catalog.test.ts +139 -0
  227. package/src/workspace/release-train-repos.test.ts +304 -0
  228. package/src/workspace/release-train.test.ts +296 -0
  229. package/src/workspace/release-train.ts +631 -16
  230. package/src/workspace/repo-ref.ts +26 -1
  231. package/src/workspace/runs-on.test.ts +45 -0
  232. package/src/workspace/workspace-gates.ts +48 -5
  233. package/src/workspace/workspace-ledger.ts +28 -5
  234. package/src/workspace/workspace-run.test.ts +1 -1
  235. package/src/workspace/workspace-run.ts +2 -2
  236. package/src/yaml.test.ts +96 -8
  237. package/src/yaml.ts +36 -8
@@ -27,17 +27,20 @@
27
27
  import { execFileSync } from "node:child_process";
28
28
  import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync } from "node:fs";
29
29
  import { tmpdir } from "node:os";
30
- import { dirname, join, resolve } from "node:path";
30
+ import { dirname, isAbsolute, join, resolve } from "node:path";
31
31
  import { formatError } from "../cli/format";
32
32
  import { INSTANCE_ROLLUP_CODES } from "../instance-nodes";
33
33
  import type { ReasonCode } from "./reason-codes";
34
34
  import type { CommandContext, ParsedArgs } from "../cli/registry";
35
35
  import { graphBox, plantability, type Plantable } from "./box-factory";
36
36
  import { composedId, composeWorkspaceGraph, readMemberIr, type ComposedMember, type ComposeInput, type WorkspaceGraph } from "./compose-graph";
37
+ import { placeCatalogPass, runCatalogPass, runsOnEdges, type LookPath, type ReadFile } from "./catalog-edges";
38
+ import { detailIdMap, type DetailLevel } from "../graph-detail";
39
+ import type { NamedCatalog } from "../graph-refs";
37
40
  import { isViewDocument, prefixView } from "../capabilities/view";
38
41
  import { refusedCapabilityView } from "./nested-graph";
39
42
  import { openGraphCache, planStamps, splitCached, storeReads, withoutUnits } from "./graph-cache";
40
- import { readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, type Declaration, type ErrorLocation, type RepoRef } from "./declaration";
43
+ import { DECLARATION_FILES, readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, type Declaration, type ErrorLocation, type RepoRef } from "./declaration";
41
44
  import { describePlan, emitDocument, executePlan, memberStatus, planJson, planMembers, type MemberArgv, type MemberPlan, type Toolchain, type UnitResult } from "./member-commands";
42
45
  import { loadKindRegistry, REPO_KIND, type KindRegistry } from "./kinds";
43
46
  import { repoIdentity } from "./repo-ref";
@@ -45,7 +48,8 @@ import { readKindLinks } from "./kind-link-readers";
45
48
  import { prepareKindReaders, type PreparedReaders } from "./kind-readers";
46
49
  import { recordLinkRows } from "./record-assets";
47
50
  import { RecordReadError } from "./records";
48
- import { workingTree } from "./tree";
51
+ import { workingTree, type WorkspaceTree } from "./tree";
52
+ import { declares, discover, discoveredTree, discoveredWorkspaceName, discoveryKinds, locateDiscovered, type DiscoveredEntry } from "./discover";
49
53
  import { handToRootChant, locateWorkspace, type LocatedWorkspace } from "./which-chant";
50
54
 
51
55
  /** The version of the `graph` document this chant writes. */
@@ -68,7 +72,7 @@ export const GRAPH_INSTANCE_ROLLUP_CODES = INSTANCE_ROLLUP_CODES satisfies reado
68
72
  const LIVE_AT_REVISION = "--live reads the account as it stands now, and --at reads the source at a revision; chant workspace graph takes one of them";
69
73
 
70
74
  const USAGE =
71
- "chant workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--live [--overlay] [--traffic <level>]] [--no-cache] [--dry-run] | chant workspace graph --composites [--at <rev>] [--member <name>] [-o <file>] | chant workspace graph --intent <path[:start-end]|path#symbol|member/node|sha> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
75
+ "chant workspace graph [dir] [--discover [--runs-on <member>=<member>/<address>]...] [--at <rev>] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--live [--overlay] [--traffic <level>]] [--no-cache] [--dry-run] | chant workspace graph --composites [--at <rev>] [--member <name>] [-o <file>] | chant workspace graph --intent <path[:start-end]|path#symbol|member/node|sha> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
72
76
 
73
77
  interface Head {
74
78
  $schema: string;
@@ -77,7 +81,7 @@ interface Head {
77
81
  }
78
82
 
79
83
  export type GraphDocument =
80
- | (Head & { at: string | null; plantable: Plantable } & WorkspaceGraph)
84
+ | (Head & { at: string | null; plantable: Plantable; discovered?: DiscoveredEntry[] } & WorkspaceGraph)
81
85
  | (Head & { error: { code: GraphErrorCode; message: string; location: ErrorLocation | null } });
82
86
 
83
87
  export interface GraphQuery {
@@ -113,6 +117,20 @@ export interface GraphQuery {
113
117
  inTree?: (root: string, members: readonly { name: string; dir: string; kind: string }[]) => Promise<void>;
114
118
  /** Read every member, leaving the per-member cache unread and unwritten (`--no-cache`, #2876). */
115
119
  noCache?: boolean;
120
+ /**
121
+ * Read `cwd` with no declaration (#5095): the kinds' probes find the
122
+ * members, as `discover.ts` describes, and nothing is written inside it.
123
+ * When `cwd` holds a declaration itself, that declaration is read instead.
124
+ */
125
+ discover?: boolean;
126
+ /** With `discover`: the cluster resource a discovered member runs on, by member name (#5101), as a declaration's `runsOn`. */
127
+ runsOn?: Record<string, string>;
128
+ /**
129
+ * Run the lexicons' reference catalogs over the composed graph (#5097,
130
+ * `./catalog-edges.ts`). A source read only: with `--live` each member's
131
+ * own chant has run its catalog already. `chant workspace graph` sets it.
132
+ */
133
+ catalog?: boolean;
116
134
  }
117
135
 
118
136
  export interface GraphResult {
@@ -223,12 +241,52 @@ function compose(
223
241
  return { inputs, failed };
224
242
  }
225
243
 
226
- /** Plan a graph read without running anything, for `--dry-run`. Throws a {@link WorkspaceReadError}. */
227
- export function planGraph(query: GraphQuery): MemberPlan {
244
+ /** Where a read's members come from: a declaration, or a discovery (#5095). */
245
+ interface ReadSource {
246
+ located: LocatedWorkspace;
247
+ declaration: Declaration;
248
+ kinds: KindRegistry;
249
+ kindProblems: string[];
250
+ /** The tree to plan from in a directory the revision was exported to (`--at`). */
251
+ treeAt(dir: string): WorkspaceTree;
252
+ /** For a discovered read, every directory a kind claims. */
253
+ discovered?: DiscoveredEntry[];
254
+ }
255
+
256
+ /**
257
+ * The declaration a read covers and the kinds it reads with. With
258
+ * `discover`, and no declaration in `cwd` itself, the members are found by
259
+ * probe and the declaration is held in memory. Throws a {@link WorkspaceReadError}.
260
+ */
261
+ function readSource(query: GraphQuery): ReadSource {
262
+ if (query.discover) {
263
+ const where = locateDiscovered(query.cwd, query.at);
264
+ if (!declares(where.base)) {
265
+ const kinds = discoveryKinds();
266
+ const found = discover(where.base, kinds, discoveredWorkspaceName(where.rootOnDisk), query.runsOn);
267
+ const tree = discoveredTree(where.base, found.declaration);
268
+ const declaration = readDeclaration(tree, "", { rootChant: true });
269
+ return {
270
+ located: { ...where, tree },
271
+ declaration,
272
+ kinds: kinds.registry,
273
+ kindProblems: kinds.problems,
274
+ treeAt: (dir) => discoveredTree(workingTree(dir), found.declaration),
275
+ discovered: found.entries,
276
+ };
277
+ }
278
+ }
228
279
  const located = locateWorkspace(query.cwd, query.at);
229
280
  const declaration = readDeclaration(located.tree, "", { rootChant: true });
281
+ // Kinds are read before planning: a package kind with a graph block runs (#2874).
230
282
  const { registry: kinds, problems } = loadKindRegistry(declaration.pins, located.rootOnDisk);
231
- return planMembers("graph", located.rootOnDisk, { only: query.members, reader: query.reader, tree: located.tree, kinds, kindProblems: problems.map((p) => p.message) });
283
+ return { located, declaration, kinds, kindProblems: problems.map((p) => p.message), treeAt: workingTree };
284
+ }
285
+
286
+ /** Plan a graph read without running anything, for `--dry-run`. Throws a {@link WorkspaceReadError}. */
287
+ export function planGraph(query: GraphQuery): MemberPlan {
288
+ const { located, kinds, kindProblems } = readSource(query);
289
+ return planMembers("graph", located.rootOnDisk, { only: query.members, reader: query.reader, tree: located.tree, kinds, kindProblems });
232
290
  }
233
291
 
234
292
  /** The members of a workspace read, each read under its own toolchain: what graph and search compose (#4374). */
@@ -246,6 +304,8 @@ export interface MemberReads {
246
304
  stamps: ReadonlyMap<string, string>;
247
305
  /** With {@link GraphQuery.components}: each member's component graph run. */
248
306
  components?: UnitResult[];
307
+ /** For a discovered read (#5095), every directory a kind claims. */
308
+ discovered?: DiscoveredEntry[];
249
309
  }
250
310
 
251
311
  export interface MemberReadOptions {
@@ -272,11 +332,7 @@ export async function readMembers(query: GraphQuery, options: MemberReadOptions)
272
332
  let exported: string | undefined;
273
333
  let readers: PreparedReaders | undefined;
274
334
  try {
275
- const located = locateWorkspace(query.cwd, query.at);
276
- const declaration = readDeclaration(located.tree, "", { rootChant: true });
277
- // Kinds are read before planning: a package kind with a graph block runs (#2874).
278
- const { registry: kinds, problems } = loadKindRegistry(declaration.pins, located.rootOnDisk);
279
- const kindProblems = problems.map((p) => p.message);
335
+ const { located, declaration, kinds, kindProblems, treeAt, discovered } = readSource(query);
280
336
  let plan = planMembers("graph", located.rootOnDisk, { only: query.members, reader: query.reader, tree: located.tree, kinds, kindProblems });
281
337
  const args = (query.args ?? {}) as ParsedArgs;
282
338
  // Members whose last source read still stands are answered from the cache (#2876).
@@ -287,7 +343,7 @@ export async function readMembers(query: GraphQuery, options: MemberReadOptions)
287
343
  const served = new Set(split?.hits.map((h) => h.id));
288
344
  if (located.at !== null && withoutUnits(plan, served).groups.length > 0) {
289
345
  exported = exportRevision(located, withoutUnits(plan, served).groups.flatMap((g) => g.units.map((u) => u.dir)));
290
- plan = planMembers("graph", exported, { only: query.members, reader: query.reader, tree: workingTree(exported), kinds, kindProblems });
346
+ plan = planMembers("graph", exported, { only: query.members, reader: query.reader, tree: treeAt(exported), kinds, kindProblems });
291
347
  }
292
348
  // Only the members that run get a reader project; a served member needs none.
293
349
  const toRun = withoutUnits(plan, served);
@@ -302,7 +358,7 @@ export async function readMembers(query: GraphQuery, options: MemberReadOptions)
302
358
  if (query.inTree) await query.inTree(exported ?? located.rootOnDisk, declaration.members.filter((m) => !query.members?.length || query.members.includes(m.name)));
303
359
  for (const r of components ?? []) if (r.stderr.trim() && query.onStderr) query.onStderr(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
304
360
  for (const r of results) if (r.stderr.trim() && query.onStderr) query.onStderr(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
305
- return { located, declaration, kinds, plan, results, served, stamps, ...(components ? { components } : {}) };
361
+ return { located, declaration, kinds, plan, results, served, stamps, ...(components ? { components } : {}), ...(discovered ? { discovered } : {}) };
306
362
  } finally {
307
363
  readers?.cleanup();
308
364
  if (exported) rmSync(dirname(exported), { recursive: true, force: true });
@@ -331,7 +387,7 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
331
387
  return { doc: { ...head, error: { code: "live-at-revision", message: LIVE_AT_REVISION, location: null } }, failed: true };
332
388
  }
333
389
  try {
334
- const { located, declaration, kinds, plan, results, served, stamps, components } = await readMembers(query, { cache: true });
390
+ const { located, declaration, kinds, plan, results, served, stamps, components, discovered } = await readMembers(query, { cache: true });
335
391
  const args = (query.args ?? {}) as ParsedArgs;
336
392
  const { inputs, failed } = compose(plan, results, query.members, declaration.members, !!args.live, !!args.capabilityView);
337
393
  for (const { member } of inputs) {
@@ -342,6 +398,8 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
342
398
  // Links (#2539) resolve against the declaration that was read, the revision's for --at, and the kinds installed now.
343
399
  // A kind's link reader (#3932) reads the member's files in the tree read, as check does.
344
400
  const graph = composeWorkspaceGraph({ name: declaration.name, root: located.root, repo: repoIdentity(located.rootOnDisk) }, inputs, { declaration, kinds, read: readKindLinks(declaration, located.tree, kinds) });
401
+ // The reference catalogs over the composed graph (#5097), on full attributes whatever --detail asks for.
402
+ if (query.catalog && !args.live) await addCatalogEdges(graph, query, args, { workspace: graph.workspace, inputs, located, runsOn: runsOnOf(declaration.members) });
345
403
  // The box's factory and listing (#3146), from the declaration read, so --at gives them at that revision.
346
404
  for (const member of graph.members) member.box = graphBox(declaration.members.find((m) => m.name === member.name)?.box ?? null, located.tree, declaration.members);
347
405
  // Nested workspaces (#2551, ws-071): read-only, through their own chant workspace graph.
@@ -363,13 +421,126 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
363
421
  query.onStderr?.(`${formatError({ message: `--kind ${query.kind}: ${err.code}: ${err.message}`, hint: USAGE })}\n`);
364
422
  }
365
423
  }
366
- return { doc: { ...head, at: located.at, plantable: plantability(declaration), ...graph }, failed: failed || recordsFailed || nestedFailed, ...(components ? { components } : {}) };
424
+ // A discovered read lists every directory a kind claims (#5095), the ones that are not members included.
425
+ return {
426
+ doc: { ...head, at: located.at, plantable: plantability(declaration), ...graph, ...(discovered ? { discovered } : {}) },
427
+ failed: failed || recordsFailed || nestedFailed,
428
+ ...(components ? { components } : {}),
429
+ };
367
430
  } catch (err) {
368
431
  if (!(err instanceof WorkspaceReadError)) throw err;
369
432
  return { doc: { ...head, error: { code: err.code, message: err.message, location: err.location ?? null } }, failed: true };
370
433
  }
371
434
  }
372
435
 
436
+ /** The reference catalog of each lexicon that has one, best effort: a lexicon that does not load has none. */
437
+ async function loadCatalogs(lexicons: readonly string[]): Promise<NamedCatalog[]> {
438
+ const { loadPlugin } = await import("../cli/plugins");
439
+ const out: NamedCatalog[] = [];
440
+ for (const lexicon of lexicons) {
441
+ try {
442
+ const catalog = (await loadPlugin(lexicon)).referenceCatalog;
443
+ if (catalog) out.push({ lexicon, catalog });
444
+ } catch {
445
+ // Not installed where this chant can load it: its nodes get no derived edges.
446
+ }
447
+ }
448
+ return out;
449
+ }
450
+
451
+ /**
452
+ * The catalog pass (#5097): load the catalogs of the lexicons the graph
453
+ * holds, read the members again at `--detail 3` when the document is printed
454
+ * at another tier, since the rules read nested attributes (`spec`,
455
+ * `metadata`) that the lower tiers leave out, run the pass over those nodes
456
+ * and place what it finds on the document's nodes.
457
+ */
458
+ async function addCatalogEdges(
459
+ graph: WorkspaceGraph,
460
+ query: GraphQuery,
461
+ args: ParsedArgs,
462
+ read: { workspace: WorkspaceGraph["workspace"]; inputs: ComposeInput[]; located: LocatedWorkspace; runsOn: ReadonlyMap<string, string> },
463
+ ): Promise<void> {
464
+ const lexicons = [...new Set(graph.nodes.map((n) => n.lexicon))].sort();
465
+ const catalogs = await loadCatalogs(lexicons);
466
+ const level = (args.detail ?? 2) as DetailLevel;
467
+ let full = read.inputs;
468
+ if (catalogs.length > 0 && level !== 3) {
469
+ // With no stderr and no capability view: the document's own read has
470
+ // passed on what the members said already.
471
+ const again = await readMembers({ ...query, args: { ...args, detail: 3, capabilityView: false }, onStderr: undefined, inTree: undefined, components: false }, { cache: true });
472
+ full = compose(again.plan, again.results, query.members, again.declaration.members).inputs;
473
+ }
474
+ const printed = new Set(read.inputs.filter((i) => i.ir).map((i) => i.member.name));
475
+ const readable = full.filter((i) => i.ir && printed.has(i.member.name)).map((i) => ({ member: { ...i.member }, ir: i.ir }));
476
+ const nodes = catalogs.length > 0 ? composeWorkspaceGraph(read.workspace, readable).nodes : [];
477
+ const placed = new Map<string, string>();
478
+ for (const { member, ir } of readable) {
479
+ for (const [id, at] of detailIdMap(ir!, level)) placed.set(composedId(member.name, id), composedId(member.name, at));
480
+ }
481
+ const pass = runCatalogPass(nodes, catalogs, catalogs.length > 0 ? readable.map((i) => i.member.name) : [], repoPathLookup(read.located, read.workspace.repo ?? null), treeFileReader(read.located));
482
+ // The declared cluster each member runs on (#5101): its edges are drawn first, so a Secret they join is not also derived or left dangling.
483
+ const declared = runsOnEdges(nodes, read.runsOn, catalogs);
484
+ for (const problem of declared.problems) query.onStderr?.(`warning: ${problem}\n`);
485
+ pass.dangling = pass.dangling.filter((d) => !(declared.joined.has(d.from) && pass.rules[d.rule!]?.relation === "reference"));
486
+ graph.edges = [...graph.edges, ...declared.edges.map((e) => ({ ...e, from: placed.get(e.from) ?? e.from, to: placed.get(e.to) ?? e.to })).filter((e) => e.from !== e.to)];
487
+ placeCatalogPass(graph, pass, placed, level);
488
+ }
489
+
490
+ /** A repository URL with its scheme, credentials, `.git` and case taken off, so two spellings of one repository compare equal. */
491
+ export function repoKey(url: string): string {
492
+ let u = url.trim().toLowerCase();
493
+ u = u.replace(/^[a-z][a-z0-9+.-]*:\/\//, "").replace(/^[^@/]+@/, "");
494
+ // scp-like `host:owner/repo` is `host/owner/repo`.
495
+ u = u.replace(/^([^/:]+):(?!\d+\/)/, "$1/").replace(/^([^/:]+):\d+\//, "$1/");
496
+ return u.replace(/\/+$/, "").replace(/\.git$/, "");
497
+ }
498
+
499
+ /**
500
+ * Where a path rule's path is (#5102): read in the tree the workspace was
501
+ * read from, when the path's repository is the workspace's own (its origin)
502
+ * and the path is under the workspace root. A path in any other repository,
503
+ * or with no origin to compare with, is not read.
504
+ */
505
+ function repoPathLookup(located: LocatedWorkspace, repo: string | null): LookPath | undefined {
506
+ if (repo === null) return undefined;
507
+ const own = repoKey(repo);
508
+ const root = located.root;
509
+ if (isAbsolute(root)) return undefined;
510
+ return (ref) => {
511
+ if (repoKey(ref.repo) !== own) return undefined;
512
+ let path = ref.value;
513
+ if (root !== "." && root !== "") {
514
+ if (path !== root && !path.startsWith(`${root}/`)) return undefined;
515
+ path = path.slice(root.length + 1);
516
+ }
517
+ if (path === "") return "dir";
518
+ return located.tree.stat(path) ?? "missing";
519
+ };
520
+ }
521
+
522
+ /**
523
+ * A workspace-relative file's text from the tree the workspace is read from,
524
+ * for the files a generated node names (#5094), or undefined when it is not
525
+ * a file there or cannot be read.
526
+ */
527
+ function treeFileReader(located: LocatedWorkspace): ReadFile {
528
+ return (path) => {
529
+ if (path === "" || path.startsWith("/") || path.split("/").includes("..")) return undefined;
530
+ if (located.tree.stat(path) !== "file") return undefined;
531
+ try {
532
+ return located.tree.read(path);
533
+ } catch {
534
+ return undefined;
535
+ }
536
+ };
537
+ }
538
+
539
+ /** The `runsOn` each declared member sets, by member name (#5101). */
540
+ function runsOnOf(members: readonly { name: string; runsOn: string | null }[]): Map<string, string> {
541
+ return new Map(members.filter((m) => m.runsOn !== null).map((m) => [m.name, m.runsOn!]));
542
+ }
543
+
373
544
  /**
374
545
  * Expand every member of kind `workspace` the query covers, read-only (#2551,
375
546
  * ws-071), and every member of kind `repo` the same way, at its pinned
@@ -434,9 +605,21 @@ export async function runWorkspaceGraph(ctx: CommandContext): Promise<number> {
434
605
  console.error(formatError({ message: `${cwd} does not exist`, hint: USAGE }));
435
606
  return 1;
436
607
  }
437
- // The root's chant reads the declaration (ws-021).
438
- const handed = await handToRootChant(cwd, args.at);
439
- if (handed !== undefined) return handed;
608
+ if (args.runsOn && !args.discover) {
609
+ console.error(formatError({ message: "--runs-on sets a discovered member's cluster; with a declaration, set runsOn on the member's entry", hint: USAGE }));
610
+ return 2;
611
+ }
612
+ // --discover (#5095) reads one directory with no declaration, as the composed graph only.
613
+ if (args.discover && (args.composites || args.intent !== undefined || args.kind !== undefined)) {
614
+ console.error(formatError({ message: "--discover reads the composed graph, and takes none of --composites, --intent and --kind", hint: USAGE }));
615
+ return 1;
616
+ }
617
+ // The root's chant reads the declaration (ws-021). A discovered read has
618
+ // none to hand over, unless <dir> holds one itself, which is then read.
619
+ if (!args.discover || DECLARATION_FILES.some((f) => existsSync(join(cwd, f)))) {
620
+ const handed = await handToRootChant(cwd, args.at);
621
+ if (handed !== undefined) return handed;
622
+ }
440
623
 
441
624
  // Composite instances joined to components (#2662) are their own document.
442
625
  if (args.composites) {
@@ -472,7 +655,7 @@ export async function runWorkspaceGraph(ctx: CommandContext): Promise<number> {
472
655
  if (args.dryRun) {
473
656
  let plan: MemberPlan;
474
657
  try {
475
- plan = planGraph({ cwd, at: args.at, members: args.members });
658
+ plan = planGraph({ cwd, at: args.at, members: args.members, ...(args.discover ? { discover: true } : {}) });
476
659
  } catch (err) {
477
660
  if (!(err instanceof WorkspaceReadError)) throw err;
478
661
  console.error(formatError({ message: `${err.code}: ${err.describe()}`, hint: USAGE }));
@@ -488,8 +671,11 @@ export async function runWorkspaceGraph(ctx: CommandContext): Promise<number> {
488
671
  members: args.members,
489
672
  args,
490
673
  ...(args.noCache ? { noCache: true } : {}),
674
+ ...(args.discover ? { discover: true } : {}),
675
+ ...(args.runsOn ? { runsOn: args.runsOn } : {}),
491
676
  ...(args.kind !== undefined ? { kind: resolve(args.kind) } : {}),
492
677
  onStderr: (text) => process.stderr.write(text),
678
+ catalog: true,
493
679
  });
494
680
  emitDocument(doc, args.output);
495
681
  if ("error" in doc) {
@@ -439,3 +439,95 @@ describe("the live read (#2875)", () => {
439
439
  expect(existsSync(join(root, "argv.txt"))).toBe(false);
440
440
  });
441
441
  });
442
+
443
+ /** A chant that prints full.json for `--detail 3`, stacks.json for `--detail 0` and ir.json otherwise. */
444
+ const FAKE_DETAIL_CHANT = `#!/bin/sh
445
+ [ "$1" = graph ] || { echo "Error: Unknown command: $1" >&2; exit 1; }
446
+ case " $* " in
447
+ *" --detail 3 "*) cat full.json ;;
448
+ *" --detail 0 "*) cat stacks.json ;;
449
+ *) cat ir.json ;;
450
+ esac
451
+ `;
452
+
453
+ describe("the reference catalog across members (#5097)", () => {
454
+ const RULE = "k8s:K8s::Apps::Deployment:spec.template.spec.serviceAccountName";
455
+ const ir = (nodes: GraphIR["nodes"]): string => JSON.stringify({ version: 1, nodes, edges: [], groups: {} });
456
+ /** A k8s member: its full read, its T2 read (no nested trees) and its T0 read. */
457
+ const k8sMember = (dir: string, nodes: GraphIR["nodes"]) => ({
458
+ [`${dir}/chant.config.ts`]: "export default {};\n",
459
+ [`${dir}/full.json`]: ir(nodes),
460
+ [`${dir}/ir.json`]: ir(nodes.map((n) => ({ ...n, attrs: {} }))),
461
+ [`${dir}/stacks.json`]: ir([{ id: "k8s", kind: "stack", lexicon: "k8s", attrs: {} }]),
462
+ });
463
+ const deployment = (sa: string) => ({
464
+ id: "web",
465
+ kind: "K8s::Apps::Deployment",
466
+ lexicon: "k8s",
467
+ attrs: { metadata: { name: "web", namespace: "shop" }, spec: { template: { spec: { serviceAccountName: sa } } } },
468
+ });
469
+ const account = { id: "runner", kind: "K8s::Core::ServiceAccount", lexicon: "k8s", attrs: { metadata: { name: "runner", namespace: "shop" } } };
470
+ const namespace = { id: "shop", kind: "K8s::Core::Namespace", lexicon: "k8s", attrs: { metadata: { name: "shop" } } };
471
+ const workspace = (sa: string, extra: Record<string, string> = {}, members: unknown[] = []) =>
472
+ repo({
473
+ "chant.workspace.json": declaration([
474
+ { name: "app", dir: "app", kind: "chant" },
475
+ { name: "rbac", dir: "rbac", kind: "chant" },
476
+ ...members,
477
+ ]),
478
+ ...k8sMember("app", [deployment(sa), namespace]),
479
+ ...k8sMember("rbac", [account]),
480
+ ...extra,
481
+ ".gitignore": "node_modules\n",
482
+ "node_modules/.bin/chant": { text: FAKE_DETAIL_CHANT, mode: 0o755 },
483
+ });
484
+
485
+ test("draws the edge from one member's Deployment to another's ServiceAccount, with its rule", async () => {
486
+ const g = result((await workspaceGraph({ cwd: workspace("runner"), catalog: true })).doc);
487
+ expectValid(g);
488
+ expect(g.edges.filter((e) => e.origin === "derived").map((e) => [e.from, e.to, e.rule, e.member])).toEqual([
489
+ ["app/web", "app/shop", "k8s:K8s::Apps::Deployment:metadata.namespace", "app"],
490
+ ["app/web", "rbac/runner", RULE, "app"],
491
+ ["rbac/runner", "app/shop", "k8s:K8s::Core::ServiceAccount:metadata.namespace", "rbac"],
492
+ ]);
493
+ expect(g.catalog).toMatchObject({ lexicons: ["k8s"], members: ["app", "rbac"], rules: { [RULE]: { label: "runs as", targetKinds: ["K8s::Core::ServiceAccount"] } } });
494
+ expect(g.groups.byContainer).toEqual({ "app/shop": ["app/web", "rbac/runner"] });
495
+ // The document is still printed at T2: the nested trees the rules read are not on its nodes.
496
+ expect(g.nodes.find((n) => n.id === "app/web")?.attrs).toEqual({});
497
+ });
498
+
499
+ test("lists a reference to no node in dangling with its rule", async () => {
500
+ const g = result((await workspaceGraph({ cwd: workspace("missing"), catalog: true })).doc);
501
+ expectValid(g);
502
+ expect(g.edges.filter((e) => e.rule === RULE)).toEqual([]);
503
+ expect(g.dangling).toEqual([
504
+ { from: "app/web", kind: "ref", path: "spec.template.spec.serviceAccountName", value: "missing", member: "app", rule: RULE, targetKind: "K8s::Core::ServiceAccount" },
505
+ ]);
506
+ });
507
+
508
+ test("draws no edge when two members hold the name, and records both candidates", async () => {
509
+ const root = workspace("runner", k8sMember("rbac2", [account]), [{ name: "rbac2", dir: "rbac2", kind: "chant" }]);
510
+ const g = result((await workspaceGraph({ cwd: root, catalog: true })).doc);
511
+ expectValid(g);
512
+ expect(g.edges.filter((e) => e.rule === RULE)).toEqual([]);
513
+ expect(g.ambiguous).toEqual([
514
+ { from: "app/web", member: "app", rule: RULE, path: "spec.template.spec.serviceAccountName", value: "runner", candidates: ["rbac/runner", "rbac2/runner"] },
515
+ ]);
516
+ });
517
+
518
+ test("keeps the derived edges at --detail 0, on the members' stack nodes", async () => {
519
+ const g = result((await workspaceGraph({ cwd: workspace("runner"), args: { detail: 0 }, catalog: true })).doc);
520
+ expectValid(g);
521
+ expect(g.nodes.map((n) => n.id)).toEqual(["app/k8s", "rbac/k8s"]);
522
+ expect(g.edges.map((e) => [e.from, e.to, e.origin, e.rule])).toEqual([
523
+ ["app/k8s", "rbac/k8s", "derived", RULE],
524
+ ["rbac/k8s", "app/k8s", "derived", "k8s:K8s::Core::ServiceAccount:metadata.namespace"],
525
+ ]);
526
+ });
527
+
528
+ test("leaves the document as it was when not asked for", async () => {
529
+ const g = result((await workspaceGraph({ cwd: workspace("runner") })).doc);
530
+ expect(g.edges).toEqual([]);
531
+ expect(g.catalog).toBeUndefined();
532
+ });
533
+ });