@telorun/analyzer 0.68.0 → 0.70.0

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 (82) hide show
  1. package/dist/analysis-registry.d.ts +12 -0
  2. package/dist/analysis-registry.d.ts.map +1 -1
  3. package/dist/analysis-registry.js +26 -0
  4. package/dist/call-graph.d.ts +80 -1
  5. package/dist/call-graph.d.ts.map +1 -1
  6. package/dist/call-graph.js +145 -12
  7. package/dist/canonical-json.d.ts +18 -0
  8. package/dist/canonical-json.d.ts.map +1 -0
  9. package/dist/canonical-json.js +26 -0
  10. package/dist/cel-access-chains.d.ts +14 -0
  11. package/dist/cel-access-chains.d.ts.map +1 -0
  12. package/dist/cel-access-chains.js +45 -0
  13. package/dist/import-resolution-diagnostics.d.ts.map +1 -1
  14. package/dist/import-resolution-diagnostics.js +22 -8
  15. package/dist/index.d.ts +7 -5
  16. package/dist/index.d.ts.map +1 -1
  17. package/dist/index.js +5 -4
  18. package/dist/loaded-types.d.ts +4 -4
  19. package/dist/loaded-types.d.ts.map +1 -1
  20. package/dist/manifest-analysis.d.ts +19 -0
  21. package/dist/manifest-analysis.d.ts.map +1 -1
  22. package/dist/manifest-analysis.js +27 -0
  23. package/dist/manifest-diff.d.ts +111 -0
  24. package/dist/manifest-diff.d.ts.map +1 -0
  25. package/dist/manifest-diff.js +130 -0
  26. package/dist/manifest-loader.d.ts +3 -4
  27. package/dist/manifest-loader.d.ts.map +1 -1
  28. package/dist/manifest-loader.js +4 -5
  29. package/dist/manifest-schemas.d.ts +2 -0
  30. package/dist/manifest-schemas.d.ts.map +1 -1
  31. package/dist/manifest-schemas.js +4 -0
  32. package/dist/module-graph.d.ts +500 -0
  33. package/dist/module-graph.d.ts.map +1 -0
  34. package/dist/module-graph.js +1389 -0
  35. package/dist/reconcile-module-versions.d.ts.map +1 -1
  36. package/dist/reconcile-module-versions.js +10 -11
  37. package/dist/release/release-plan.d.ts +1 -1
  38. package/dist/resolve-zone-containment.d.ts +9 -1
  39. package/dist/resolve-zone-containment.d.ts.map +1 -1
  40. package/dist/resolve-zone-containment.js +34 -6
  41. package/dist/resolve-zone-requirements.d.ts.map +1 -1
  42. package/dist/resolve-zone-requirements.js +4 -2
  43. package/dist/sources/default-sources.d.ts +6 -6
  44. package/dist/sources/default-sources.d.ts.map +1 -1
  45. package/dist/sources/default-sources.js +7 -8
  46. package/dist/sources/integrity.d.ts +3 -2
  47. package/dist/sources/integrity.d.ts.map +1 -1
  48. package/dist/sources/integrity.js +26 -3
  49. package/dist/sources/versioned-ref.d.ts +17 -12
  50. package/dist/sources/versioned-ref.d.ts.map +1 -1
  51. package/dist/sources/versioned-ref.js +22 -24
  52. package/dist/telo-version.d.ts +1 -1
  53. package/dist/telo-version.js +1 -1
  54. package/package.json +2 -2
  55. package/src/analysis-registry.ts +37 -0
  56. package/src/call-graph.ts +207 -14
  57. package/src/canonical-json.ts +24 -0
  58. package/src/cel-access-chains.ts +47 -0
  59. package/src/import-resolution-diagnostics.ts +24 -7
  60. package/src/index.ts +46 -5
  61. package/src/loaded-types.ts +4 -4
  62. package/src/manifest-analysis.ts +39 -0
  63. package/src/manifest-diff.ts +219 -0
  64. package/src/manifest-loader.ts +4 -5
  65. package/src/manifest-schemas.ts +4 -0
  66. package/src/module-graph.ts +1983 -0
  67. package/src/reconcile-module-versions.ts +10 -11
  68. package/src/release/release-plan.ts +1 -1
  69. package/src/resolve-zone-containment.ts +49 -9
  70. package/src/resolve-zone-requirements.ts +7 -2
  71. package/src/sources/default-sources.ts +7 -8
  72. package/src/sources/integrity.ts +28 -3
  73. package/src/sources/versioned-ref.ts +26 -28
  74. package/src/telo-version.ts +1 -1
  75. package/dist/sources/module-ref.d.ts +0 -21
  76. package/dist/sources/module-ref.d.ts.map +0 -1
  77. package/dist/sources/module-ref.js +0 -36
  78. package/dist/sources/registry-source.d.ts +0 -14
  79. package/dist/sources/registry-source.d.ts.map +0 -1
  80. package/dist/sources/registry-source.js +0 -45
  81. package/src/sources/module-ref.ts +0 -49
  82. package/src/sources/registry-source.ts +0 -52
@@ -0,0 +1,500 @@
1
+ /**
2
+ * The module graph — what a module IS, as boxes, rows and classed edges.
3
+ *
4
+ * One fold over the call graph, the reference field map and each kind's own
5
+ * schema, producing the three primitives an editor draws:
6
+ *
7
+ * - **Box** — a declaration and what it owns. Every resource is a node whatever
8
+ * declaration form it arrived in (named, inline, `with:`-scoped, imported,
9
+ * injected), plus the module root, which is not a resource but owns `targets`.
10
+ * - **Row** — one ORDERED entry inside a box: a step, an entry-list item (a
11
+ * route, a mount), a boot target. Order is manifest data, so it is carried
12
+ * rather than re-derived; a row is where reordering is expressible at all.
13
+ * - **Edge** — a reference leaving a PORT, classed by what the slot's `use`
14
+ * says happens at it.
15
+ *
16
+ * **Ports are declared, not discovered.** A port exists because the kind's
17
+ * schema declares a ref slot, so an EMPTY slot is a port with an empty
18
+ * occupancy — the fact that `notFoundHandler` is unset is as much a property of
19
+ * the application as the fact that `mounts` has two entries, and it is the only
20
+ * thing an editor can offer to fill.
21
+ *
22
+ * **Three edge classes, not six uses.** What a reader must distinguish is
23
+ * whether control transfers, not which of four ways it does:
24
+ * `call` / `detached` / `trigger.inbound` / `trigger.consumer` are **flow**,
25
+ * `dependency` is **holds**, `schema` is **shape** — a type annotation rather
26
+ * than a runtime relation. The six-value `use` stays on the edge for consumers
27
+ * that need the distinction; the class is what a view draws.
28
+ *
29
+ * **Identity is anchored on names, never on indices.** A row addressed by array
30
+ * index shifts when a sibling is inserted above it, so selection and sticky
31
+ * expansion would detach precisely while the user is editing — the primary use
32
+ * case. Where the grammar offers a name (a step's `name:`, a resource's
33
+ * `metadata.name`) the name is the identity; where it does not (an unnamed
34
+ * route, an unnamed step) the identity is the nearest named ancestor plus a
35
+ * content-derived key. The same reason the migration driver refuses indexed
36
+ * matches into a resized array: a stale key resolves to nothing, a stale index
37
+ * silently names a different element.
38
+ *
39
+ * **What is deliberately NOT here: view policy.** Bands, labels, layout and
40
+ * expansion are the editor's, so nothing in this file reads a schema `title` or
41
+ * decides where a node is drawn. What it emits is the fact each of those
42
+ * decisions is taken from — capability, ownership, edge class, `boot` — so two
43
+ * hosts drawing the same module cannot disagree about what it contains.
44
+ *
45
+ * Browser-safe: no Node built-ins.
46
+ */
47
+ import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
48
+ import { type CallGraph } from "./call-graph.js";
49
+ import { type RefUse } from "./ref-slot.js";
50
+ /** How a node's declaration reached the module, which is what decides where a
51
+ * view may draw it — an inline child exists nowhere but its parent's YAML, so
52
+ * it is never a peer of the resource holding it. */
53
+ export type NodeOwnership = "root" | "named" | "inline" | "scoped" | "imported" | "injected";
54
+ /**
55
+ * What happens at a site, reduced to what a view draws.
56
+ *
57
+ * The first three classify a REFERENCE by its `use`; `data` is not a reference
58
+ * at all — it is one resource reading another's published state in CEL
59
+ * (`resources.<name>.status.<field>`), which is a real dependency the reference
60
+ * graph does not carry and which no slot declares.
61
+ */
62
+ export type EdgeClass = "flow" | "holds" | "shape" | "data";
63
+ /**
64
+ * What a line of a body is.
65
+ *
66
+ * The first three are ORDERED entries of an array — a step, an entry-list item,
67
+ * a boot target — and reordering one is the point of drawing them. The last two
68
+ * are not positions at all: a slot may hold a DECLARATION rather than a name
69
+ * (`invoke: { kind: …, …config }`), and that declaration exists nowhere but the
70
+ * site, so it has no array to sit in and no sibling to be moved past. It is a
71
+ * line of the body because it is a thing the author wrote and has to be able to
72
+ * reach; see {@link isOrderedRow}.
73
+ */
74
+ export type RowKind = "step" | "entry" | "target" | "inline" | "reference";
75
+ /**
76
+ * Rows that are ordered entries of their array.
77
+ *
78
+ * A consumer offering reorder, removal or an index must ask — a declaration
79
+ * written at a dispatch site carries an `index` of 0 and an `array` it shares
80
+ * with its host, both of which are borrowed so it groups into the right branch,
81
+ * and neither of which means what it means on a step.
82
+ */
83
+ export declare function isOrderedRow(row: GraphRow): boolean;
84
+ /** One occupancy of a port: the concrete site, and the name it holds. */
85
+ export interface PortSlot {
86
+ /** Concrete path of this site (`mounts[1].mount`), the write target. */
87
+ path: string;
88
+ /** Referenced resource name, absent for an empty slot. */
89
+ target?: string;
90
+ /** Node id the name resolves to, absent when it resolves to nothing. */
91
+ targetNode?: string;
92
+ /** The site holds an inline declaration rather than a reference; `targetNode`
93
+ * is the extracted child. */
94
+ inline?: boolean;
95
+ }
96
+ /** A reference slot the kind declares, filled or not. */
97
+ export interface GraphPort {
98
+ /** Field-map path with `[]` / `{}` markers — the port's identity on its node. */
99
+ slot: string;
100
+ /** Accepted `x-telo-ref` constraints, canonicalized. */
101
+ refs: string[];
102
+ /** Capabilities a target may satisfy — what validates a wire. */
103
+ capabilities: string[];
104
+ /** The slot traverses at least one array, so it takes many targets. */
105
+ array: boolean;
106
+ class: EdgeClass;
107
+ slots: PortSlot[];
108
+ /** Concrete path a new array item would be written at. Array ports only. */
109
+ addPath?: string;
110
+ /** This slot's occupancy is drawn as ROWS rather than as port slots — the
111
+ * slot sits inside a step body or an entry list, where order is semantic and
112
+ * the row is the thing a reader manipulates. */
113
+ rowOwned?: boolean;
114
+ }
115
+ /** One ordered entry inside a box. */
116
+ export interface GraphRow {
117
+ /** Name-anchored identity, stable across insertion of a sibling. */
118
+ id: string;
119
+ kind: RowKind;
120
+ /** What the manifest calls this line: a step's `name:`, or — for a
121
+ * `reference` row — the field holding it. Absent where the grammar offers
122
+ * neither (an unnamed route, an `inline` row, which is named by its kind). */
123
+ name?: string;
124
+ /** Concrete path of the row (`steps[0].do[1]`, `routes[2]`) — the write
125
+ * target, and what a position index is keyed by. */
126
+ path: string;
127
+ /** Concrete path of the array holding it, the reorder domain. */
128
+ array: string;
129
+ /** Lexical index within that array. */
130
+ index: number;
131
+ /** Nesting depth: 0 at the body's top level, +1 inside each branch. */
132
+ depth: number;
133
+ /** Row id of the enclosing row, when this one nests inside a branch. */
134
+ parent?: string;
135
+ /** Referenced name this row dispatches to, when it dispatches. */
136
+ target?: string;
137
+ /** Node id of that target, when it resolves. */
138
+ targetNode?: string;
139
+ /** JSON Pointer to this call's argument map, when the slot declares one. */
140
+ inputs?: string;
141
+ /** The values a matcher-role field holds (`{path: "/orders", method: "POST"}`)
142
+ * — what identifies an entry to a reader, and what its content key is
143
+ * derived from. Entry rows only. */
144
+ match?: Record<string, unknown>;
145
+ /**
146
+ * What this row IS, in the grammar's own words — `invoke`, `if/then/else`,
147
+ * `while/do`, `switch/cases/default`, `try/catch/finally`, `throw`, `value`.
148
+ *
149
+ * Without it every statement in a body reads alike: a loop and a dispatch are
150
+ * both a name and an arrow, so a reader has to open the source to find out
151
+ * which is which. Read off the branch the step matches, so a kind declaring a
152
+ * body of its own is described in the words its author chose.
153
+ */
154
+ variant?: string;
155
+ /** The branch's title as its author wrote it — a label to render, never to
156
+ * parse. See `StepGraphNode.variantLabel`. */
157
+ variantLabel?: string;
158
+ /**
159
+ * The expression deciding whether or how this row runs, as written — an
160
+ * `if:`, a `while:`, a `switch:`, or a dispatch's `when:` guard.
161
+ *
162
+ * A step drawn without it says it is conditional and not on what, which for a
163
+ * loop is the whole behaviour.
164
+ */
165
+ predicate?: string;
166
+ /** This row declares an error branch — a field the kind annotated
167
+ * `x-telo-error-context`, which is where a raised code is discharged. Found
168
+ * by the annotation, so a third-party composer's `catches:` is seen too. */
169
+ catches?: boolean;
170
+ /**
171
+ * Where this row's call is WRITTEN, and what may fill it.
172
+ *
173
+ * A row is the dispatch site a reader manipulates — a step's `invoke:`, a
174
+ * route's `handler:`, a boot target — and until now the site was recoverable
175
+ * only from an edge, so a row dispatching to nothing yet had no address at
176
+ * all. That is exactly the row an editor has something to offer at: it is
177
+ * where a reference is written, and where a new resource would be wired in.
178
+ *
179
+ * Absent for a row that dispatches nothing by grammar (a pure `value:` step)
180
+ * and for a declaration row, which IS the thing dispatched to.
181
+ */
182
+ dispatch?: {
183
+ path: string;
184
+ refs: string[];
185
+ /** The slot holds a DECLARATION written at the site rather than a reference
186
+ * to one elsewhere. A consumer offers different things at the two: nothing
187
+ * can be wired into an occupied declaration without destroying it, and a
188
+ * declaration is the one thing that can be given a name of its own. */
189
+ inline?: boolean;
190
+ /**
191
+ * The row's OTHER sites — the same call, written a different way, under a
192
+ * different constraint.
193
+ *
194
+ * A boot target is the case that forced it: the entry takes a bare
195
+ * `!ref` to a `Telo.Runnable | Telo.Service`, and it takes an invoke step
196
+ * whose `invoke:` takes any `Telo.Executable`. Reporting only the first made
197
+ * every `Telo.Invocable` in the application unbootable from the editor —
198
+ * legal in the manifest, and offered nowhere, since a slot with nothing to
199
+ * put in it reads as an empty module rather than as a missing site.
200
+ *
201
+ * Primary first, and a site is listed once per CONSTRAINT: a boot target's
202
+ * `ref:` accepts exactly what its bare form does, so the two are one site
203
+ * and the bare spelling wins. Which spelling to write is a choice a reader
204
+ * should not have to make, and the constraint is the only thing that
205
+ * changes what may be written at all.
206
+ */
207
+ alternatives?: {
208
+ path: string;
209
+ refs: string[];
210
+ }[];
211
+ };
212
+ /** `inline` rows: the kind the declaration written at this site names. A
213
+ * declaration is not a reference — there is nothing elsewhere to point at,
214
+ * which is the whole reason the row has to carry its own identity. */
215
+ declares?: string;
216
+ /** That kind resolved to no definition. */
217
+ unknownKind?: boolean;
218
+ }
219
+ /** A resource, the module root, or a declaration owned by either. */
220
+ export interface GraphNode {
221
+ /** `<kind>\0<name>` for a module-level resource — the call graph's own id, so
222
+ * a consumer holding one can address the other. */
223
+ id: string;
224
+ kind: string;
225
+ name: string;
226
+ /** Declared capability, absent when the kind does not resolve — an unresolved
227
+ * import, a kind with no definition. A view must render it as unknown rather
228
+ * than guessing a placement it would have to take back. */
229
+ capability?: string;
230
+ /**
231
+ * `<module>.<Kind>` — what `kind` NAMES, resolved.
232
+ *
233
+ * `kind` is the string the author wrote, and it is written in the DECLARING
234
+ * module's alias scope: a library declares its own instances as
235
+ * `kind: Self.WriteLine`, and `Self` means that library. Carried into a
236
+ * flattened application the spelling survives and resolves to nothing there,
237
+ * so every consumer joining on a kind — does this slot accept it, which
238
+ * instances does this kind have, what schema does the form use — silently
239
+ * missed a whole imported library.
240
+ *
241
+ * Absent when the kind is already canonical, and when it resolves to nothing
242
+ * (which `unknownKind` says).
243
+ */
244
+ canonicalKind?: string;
245
+ /** The kind resolved to no definition at all. */
246
+ unknownKind?: boolean;
247
+ ownership: NodeOwnership;
248
+ /** Node that owns this declaration — set for `inline` and `scoped`. */
249
+ owner?: string;
250
+ /** Site on the owner that declares it (`/with`, `mounts[0].mount`). */
251
+ ownerSite?: string;
252
+ /** Module that declared it, when stamped. */
253
+ module?: string;
254
+ /** True when the declaring module is not the entry module — an instance
255
+ * reached across an import boundary. */
256
+ external?: boolean;
257
+ /** Import alias the entry module reaches it under, when it is external and
258
+ * one alias points at its module. What a boundary box is labelled by, and
259
+ * what a reference to it is written with. */
260
+ alias?: string;
261
+ ports: GraphPort[];
262
+ rows: GraphRow[];
263
+ /**
264
+ * The ordered arrays this kind can hold rows in, whether or not any exist.
265
+ *
266
+ * Declared rather than observed, for the same reason a port is: a server with
267
+ * no mounts still HAS mounts, and a canvas that lists only what is there
268
+ * offers no way to add the first one. Each is a field name plus what its rows
269
+ * would be.
270
+ */
271
+ rowArrays: {
272
+ field: string;
273
+ kind: RowKind;
274
+ }[];
275
+ /** What invoking this can raise, resolved along its own call graph — the
276
+ * error contract a caller has to render or let escape. `unbounded` means the
277
+ * union could not be closed statically, so a catch-all is required. */
278
+ throws?: {
279
+ codes: string[];
280
+ unbounded: boolean;
281
+ };
282
+ /** The module root, which owns `targets` and the module's own config. */
283
+ root?: boolean;
284
+ }
285
+ /** A reference site, classed. */
286
+ export interface GraphEdge {
287
+ /** Stable within the graph: source, slot and site. */
288
+ id: string;
289
+ /** Node id of the declaring resource — never a step, since a step is a ROW of
290
+ * its owner here rather than a node. `row` says which row declared it. */
291
+ from: string;
292
+ /** Node id of the target, absent when the name resolves to nothing. */
293
+ to?: string;
294
+ /** The referenced name as written, always present — a `!ref` to a name that
295
+ * does not exist is a real edge some other pass reports, and dropping it
296
+ * would make the graph disagree with the manifest about what was written. */
297
+ toName: string;
298
+ class: EdgeClass;
299
+ /** The declared uses at this site, unreduced. */
300
+ use: RefUse[];
301
+ /** Field-map path of the slot — part of the edge's identity, so two slots
302
+ * naming one target are two edges. */
303
+ slot: string;
304
+ /** Concrete path of the site. */
305
+ path: string;
306
+ /** Row this edge leaves from, when a row declares it. */
307
+ row?: string;
308
+ /** JSON Pointer to this call's argument map, when declared. */
309
+ inputs?: string;
310
+ /** The edge is a boot target of the module root: ordered, and the reason the
311
+ * target runs at all. */
312
+ boot?: boolean;
313
+ /** The target is declared inside the source's own scope. */
314
+ scoped?: boolean;
315
+ /** Data edges only: the access chain as written (`resources.db.status.port`),
316
+ * so a reader is told WHAT is read rather than only that something is. */
317
+ read?: string;
318
+ }
319
+ /**
320
+ * A genuine containment: a set of nodes something else encloses.
321
+ *
322
+ * Reference reachability is NOT containment — that mistake is what drew a mount
323
+ * as a child of its server while the slot said `dependency`. The three that ARE:
324
+ * an **inline** declaration and a **scope**'s resources exist nowhere but their
325
+ * owner's YAML, and a **zone** is a region of execution every dispatch inside it
326
+ * runs within.
327
+ */
328
+ export interface GraphRegion {
329
+ id: string;
330
+ kind: "inline" | "scope" | "zone";
331
+ /** Node whose declaration encloses the members. */
332
+ owner: string;
333
+ /** Site on the owner (`/with`, `invoke`, `steps`). */
334
+ site: string;
335
+ /** Node ids inside. */
336
+ members: string[];
337
+ /** Zone regions only: what the region GUARANTEES about its contents, as the
338
+ * declaring kind wrote it — the attribute name mapped to the author's
339
+ * reason, which a consumer quotes rather than paraphrases. */
340
+ attributes?: Readonly<Record<string, string>>;
341
+ /** Zone regions only: dispatches inside the region the zone does NOT extend
342
+ * through — a detached call, an inbound trigger. Recorded because the site is
343
+ * inside the region even though its target is not. */
344
+ boundaries?: {
345
+ from: string;
346
+ toName: string;
347
+ escaping: string[];
348
+ }[];
349
+ }
350
+ /**
351
+ * A kind declaration — the second plane.
352
+ *
353
+ * Kept apart from the instance nodes rather than mixed in: a `Telo.Definition`
354
+ * is a TYPE, and drawing it among the instances would put things that exist at
355
+ * runtime and things that do not on one surface with nothing separating them.
356
+ * A module that declares only kinds has this plane and no other, which is why
357
+ * it is a first-class list rather than a flag on a node.
358
+ */
359
+ export interface GraphKind {
360
+ /** Canonical `<module>.<Name>` — what a `kind:` resolves to. */
361
+ id: string;
362
+ name: string;
363
+ module?: string;
364
+ /** Non-instantiable: the contract has no default implementation. */
365
+ abstract: boolean;
366
+ capability?: string;
367
+ /** Canonical id of the kind this one specializes, when it resolves. */
368
+ extendsId?: string;
369
+ /** The `extends` target as WRITTEN, kept when it resolves to nothing — an
370
+ * unresolved parent is a fact about the manifest, not a reason to draw the
371
+ * kind as having none. */
372
+ extendsName?: string;
373
+ /** Ids of the instance nodes declared of this kind — the join between the
374
+ * two planes. */
375
+ instances: string[];
376
+ /** Declares a body of its own (`resources:` / `invoke:` / `run:` / `provide:`)
377
+ * rather than naming a controller — the kind's interior. */
378
+ template: boolean;
379
+ /** Declared by the entry module rather than reached through an import. */
380
+ own: boolean;
381
+ /** Listed in the entry module's `exports.kinds`, so an importer may construct
382
+ * one. Undefined for a kind this module did not declare, whose gate is its
383
+ * own library's to state. */
384
+ exported?: boolean;
385
+ }
386
+ export interface ModuleGraph {
387
+ /** The module root, when one was supplied. */
388
+ root?: GraphNode;
389
+ nodes: GraphNode[];
390
+ edges: GraphEdge[];
391
+ regions: GraphRegion[];
392
+ /** The kind plane — every kind declaration in scope. */
393
+ kinds: GraphKind[];
394
+ nodeById(id: string): GraphNode | undefined;
395
+ edgesFrom(id: string): GraphEdge[];
396
+ edgesTo(id: string): GraphEdge[];
397
+ }
398
+ /**
399
+ * A hold whose target is ambient infrastructure — the collapse candidate.
400
+ *
401
+ * Stated here rather than in the view because it is the rule the plan fixes,
402
+ * and two hosts applying it differently would disagree about which edges exist:
403
+ * a hold into a shared connection or store is fan-in that swamps a layout and
404
+ * carries no structure, while a hold BETWEEN working resources is the
405
+ * application's spine — a server holding its mounts — and demoting the second
406
+ * with the first is exactly the mistake this replaces.
407
+ */
408
+ /**
409
+ * Is anything reaching this declaration at all?
410
+ *
411
+ * "Declared, referenced by nothing, in no `targets`" — the resource a reader
412
+ * cannot otherwise tell apart from a wired one, since a manifest states no
413
+ * difference between the two. Every incoming edge counts, not only flow: a
414
+ * connection is HELD rather than called, and reading it as unwired would mark
415
+ * every provider in the module. An owned declaration is reached by its owner,
416
+ * and the root is what reaches everything else.
417
+ *
418
+ * A declaration this module did not write is NEVER unwired, however little it
419
+ * is used here. An imported library exports what it exports, and the flatten
420
+ * forwards all of it; "nothing references this" would be a true sentence about
421
+ * an unused export and a useless one, since the reader cannot act on it — the
422
+ * declaration is not theirs to remove.
423
+ */
424
+ export declare function isUnwired(node: GraphNode, graph: ModuleGraph): boolean;
425
+ export declare function isAmbientHold(edge: GraphEdge, graph: ModuleGraph): boolean;
426
+ /**
427
+ * Capabilities whose resources are AMBIENT: held and read, never run, and never
428
+ * drawn as the target of a line.
429
+ *
430
+ * Exported because the view partitions on the same fact — which boxes go off
431
+ * the canvas into the drawer — and two spellings of it is how a host ends up
432
+ * collapsing a hold the other still draws an edge for.
433
+ */
434
+ export declare const AMBIENT_CAPABILITIES: ReadonlySet<string>;
435
+ /** Is this an ambient declaration — held and read rather than run? */
436
+ export declare function isAmbientCapability(capability: string | undefined): boolean;
437
+ /**
438
+ * The class a site is drawn as.
439
+ *
440
+ * A slot declaring NO use reads as flow, the same conservative direction the
441
+ * call graph takes: the cost of a false "control reaches here" is an edge drawn
442
+ * more prominently than it deserved, while the cost of a false "it never does"
443
+ * is a call the picture denies exists.
444
+ */
445
+ export declare function edgeClassOf(use: readonly RefUse[]): EdgeClass;
446
+ /** What the projection needs from a registry, as a structural contract — so it
447
+ * folds over stubs in tests and over the real registry in a host, and so this
448
+ * module imports no registry class. */
449
+ export interface ModuleGraphDeps {
450
+ /** Every reference slot a resource's kind declares, filled or not. */
451
+ refFields(resource: ResourceManifest): {
452
+ path: string;
453
+ isArray: boolean;
454
+ refs: string[];
455
+ capabilities: string[];
456
+ }[];
457
+ /** The resource's definition, resolved in its declaring module's scope. */
458
+ definition(kind: string, module?: string): ResourceDefinition | undefined;
459
+ /** What invoking this resource can raise. Optional: a host without the
460
+ * resolver gets nodes with no error contract rather than a wrong one. */
461
+ throwsOf?(manifest: ResourceManifest): {
462
+ codes: string[];
463
+ unbounded: boolean;
464
+ } | undefined;
465
+ /** Import aliases pointing at a module, so a reference written across the
466
+ * boundary as `!ref <Alias>.<name>` resolves to the instance it names. The
467
+ * call graph resolves bare names only — correct for a name declared here,
468
+ * and the reason every cross-module reference otherwise reads as dangling. */
469
+ aliasesForModule(module: string): string[];
470
+ }
471
+ export interface BuildModuleGraphOptions {
472
+ /** The module doc (`Telo.Application` / `Telo.Library`), which is not a
473
+ * resource but owns `targets` and is the boot root. */
474
+ root?: ResourceManifest;
475
+ /** Module name of the entry module, so an instance declared elsewhere is
476
+ * marked external rather than being told apart by a heuristic. */
477
+ entryModule?: string;
478
+ }
479
+ /**
480
+ * A short, stable key over a value's shape.
481
+ *
482
+ * FNV-1a over canonical JSON: what is wanted is that the same written entry
483
+ * keeps the same identity when a sibling is inserted above it, which a hash of
484
+ * the entry's own content gives and an index cannot. Collisions are resolved by
485
+ * declaration order at the call site, so two byte-identical rows stay
486
+ * distinguishable without either one's identity depending on the other's
487
+ * position.
488
+ */
489
+ export declare function contentKey(value: unknown): string;
490
+ /**
491
+ * Fold a manifest set into the module graph.
492
+ *
493
+ * The call graph supplies what calls what — including the scoped nodes and step
494
+ * bodies it already discovers — and this pass adds what a picture needs and a
495
+ * call graph has no reason to carry: declared-but-empty ports, ownership,
496
+ * ordered rows, region membership, and the reduction of six uses to three
497
+ * classes.
498
+ */
499
+ export declare function buildModuleGraph(resources: ResourceManifest[], callGraph: CallGraph, deps: ModuleGraphDeps, options?: BuildModuleGraphOptions): ModuleGraph;
500
+ //# sourceMappingURL=module-graph.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"module-graph.d.ts","sourceRoot":"","sources":["../src/module-graph.ts"],"names":[],"mappings":"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"}