@telorun/analyzer 0.52.0 → 0.54.0

package/dist/call-graph.d.ts

@@ -0,0 +1,189 @@
+/**
+ * The typed reference graph — one model of "what calls what", replacing the
+ * private walkers each analysis used to build for itself.
+ *
+ * **Two node kinds.** Resource nodes carry their declaration-site identity. Step
+ * nodes carry name, lexical order, enclosing array and nesting parent, and
+ * *optionally* an outgoing edge. Steps are nodes rather than edge decorations
+ * because a pure `value:` step produces `steps.<name>.result` while referencing
+ * nothing — it has no edge to hang on — and because step identity, ordering and
+ * nesting are exactly what `steps.<name>.result` typing, per-step throws
+ * coverage and the editor's step rendering consume.
+ *
+ * **Lexical order and containment, not execution order.** Order is the written
+ * order of the array; which branch actually runs is decided by runtime
+ * predicates and is not statically derivable. That is sufficient by
+ * construction: result typing needs step names, throws coverage needs
+ * `try` / `catch` containment rather than which arm fires, and the editor
+ * renders rows as written.
+ *
+ * **Edges are `(from, slot, to, use)` and the graph is a MULTIGRAPH.** The slot
+ * path is part of an edge's identity, so a kind declaring several ref slots
+ * emits one edge per slot, each with its own `use` — `Cache.View` holds its
+ * `store:` as a `dependency` while its `invoke:` is a `call` — and two slots may
+ * name the same target without collapsing. Array slots emit one edge per
+ * element. This is a requirement, not a detail: the old `dependency-graph.ts`
+ * kept a set-valued adjacency map, which erases parallel edges and would
+ * silently merge a dependency with a call. The init-order consumer projects the
+ * multigraph down to unique pairs itself, since that is the only consumer for
+ * which the distinction genuinely does not matter.
+ *
+ * **Three discovery mechanics, one graph.** Field-map sites (Phase-5 injection
+ * sites — `edge.injected`), schema-driven step slots behind the local `$ref`s
+ * the field map deliberately does not descend, and a value-tree scan for `!ref`
+ * anywhere else — so a ref in a structure no annotation anticipated is still an
+ * edge (with no declared `use`, read conservatively). Inline declarations
+ * inside `x-telo-scope` arrays become nodes of their own and their slots are
+ * walked, so a `with:`-scoped resource's references are part of the one model.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { type RefUse, type RefUseCases } from "./ref-slot.js";
+export interface ResourceGraphNode {
+    type: "resource";
+    id: string;
+    kind: string;
+    name: string;
+    manifest: ResourceManifest;
+    /** Declared inside another resource's `x-telo-scope` array: created when the
+     *  scope opens rather than at boot, so it takes no part in init ordering. Its
+     *  declaration-site identity is the scope site, never the module. */
+    scoped?: boolean;
+    /** Node id of the resource whose scope declares this one (set iff `scoped`). */
+    scopeOwner?: string;
+    /** The scope field's JSON Pointer on the owner (set iff `scoped`). */
+    scopeSite?: string;
+}
+export interface StepGraphNode {
+    type: "step";
+    id: string;
+    /** The step's declared `name:`, when it has one. */
+    name?: string;
+    /** Node id of the resource whose body declares this step. */
+    owner: string;
+    /** Concrete path within the owner (`steps[0].do[1]`). */
+    path: string;
+    /** Concrete path of the enclosing step array (`steps`, `steps[0].do`). */
+    array: string;
+    /** Enclosing step node, when this step nests inside another's branch. */
+    parent?: string;
+    /** Lexical index within its own array. */
+    index: number;
+    /** The step value as written. */
+    step: Record<string, unknown>;
+}
+export type CallGraphNode = ResourceGraphNode | StepGraphNode;
+export interface CallGraphEdge {
+    /** Node id of the resource or step that declares the slot. */
+    from: string;
+    /** The referenced resource's NAME, always present — including when no node
+     *  carries it. A `!ref` to a name that does not exist is a real edge some
+     *  other validator reports; dropping it would make the graph disagree with
+     *  the manifest about what was written. */
+    toName: string;
+    /** Node id of the target, when the name resolves to one. A name declared in
+     *  the source's own scope resolves to the SCOPED node (scope-local first, the
+     *  order `ScopeContext` and `!ref` already agree on), never to a same-named
+     *  module-level resource. */
+    to?: string;
+    /** Field-map path of the slot — part of the edge's identity. */
+    slot: string;
+    /** Concrete path of this site (`routes[2].handler`). */
+    path: string;
+    /**
+     * What the declaring resource does with the target at this site. Resolved
+     * against a case map's selector when the graph could read it; otherwise every
+     * use the slot could take (see {@link CallGraphEdge.unresolved}).
+     */
+    use: RefUse[];
+    /** Set when a case map's selector could not be resolved statically, so `use`
+     *  is the union of the map's cases rather than the one that holds. */
+    unresolved?: RefUseCases;
+    /** Why the selector did not resolve: written in CEL (`dynamic` — a
+     *  diagnostic, see `validate-ref-slots.ts`), absent with no schema default
+     *  (`absent`), or a literal matching no case (`unmatched`). */
+    unresolvedReason?: "dynamic" | "absent" | "unmatched";
+    /** JSON Pointer to the field carrying this call's arguments, when declared. */
+    inputs?: string;
+    /** This site is a Phase-5 injection site — the reference field map reaches
+     *  it, so the kernel puts the live instance into the field before `init()`.
+     *  THE init-order criterion: injection is what forces construct-before-use,
+     *  regardless of whether the slot is declared at resource level or inside an
+     *  inline step array (`Telo.Application.targets`). Step slots behind a local
+     *  `$ref` and value-tree-discovered refs are not injection sites — those
+     *  resolve at dispatch. */
+    injected?: boolean;
+    /** Found by the value-tree scan rather than a declared slot — no schema, no
+     *  declared `use` (read conservatively as control-transferring). */
+    nested?: boolean;
+    /** The target is declared INSIDE the source's own `x-telo-scope`, so it is
+     *  created on demand when the scope opens rather than at boot. Recorded rather
+     *  than dropped: it is a real edge, and only the init-order consumer wants it
+     *  gone. */
+    scoped?: boolean;
+}
+export interface CallGraph {
+    nodes: ReadonlyMap<string, CallGraphNode>;
+    edges: readonly CallGraphEdge[];
+    /** Edges leaving a node, in declaration order. */
+    edgesFrom(id: string): CallGraphEdge[];
+    /** Edges arriving at a resource node. */
+    edgesTo(id: string): CallGraphEdge[];
+    resource(kind: string, name: string): ResourceGraphNode | undefined;
+    resourceByName(name: string): ResourceGraphNode | undefined;
+    /** Step nodes declared by a resource, in lexical order. */
+    steps(resourceId: string): StepGraphNode[];
+    /** Every edge whose `use` includes at least one control transfer, plus every
+     *  edge whose slot declares no `use` at all — see {@link CallGraph.controlEdges}. */
+    controlEdges(): CallGraphEdge[];
+}
+export declare const resourceId: (kind: string, name: string) => string;
+export interface BuildCallGraphOptions {
+    aliases?: AliasResolver;
+    aliasesByModule?: Map<string, AliasResolver>;
+}
+/**
+ * Build the call graph for one manifest set.
+ *
+ * Reference discovery is three-fold. Field-map sites come from `visitManifest`
+ * — the same walk the reference validators use — and are stamped `injected`,
+ * because those and only those are Phase-5 injection sites. Step slots are read
+ * from the step item schema, because they sit behind local `$ref`s the field
+ * map deliberately does not descend. Everything else is caught by the value-
+ * tree scan (`discoverNestedRefs`): a `!ref` is an explicit marker, so a ref in
+ * a structure no annotation anticipated is still an edge — with no declared
+ * `use`, read conservatively — instead of a blind spot. Inline declarations in
+ * `x-telo-scope` arrays become scoped nodes with edges of their own.
+ */
+export declare function buildCallGraph(resources: ResourceManifest[], registry: DefinitionRegistry, options?: BuildCallGraphOptions): CallGraph;
+export interface ProjectToPairsOptions {
+    /** Keep only edges whose use satisfies this. Omit to keep every edge. */
+    keepUse?: (use: RefUse[]) => boolean;
+    /** Also include edges that are NOT injection sites (step slots behind a
+     *  `$ref`, value-tree-discovered refs). Default false — see below. */
+    includeNonInjected?: boolean;
+}
+/**
+ * Unique `(from, to)` pairs, dropping slot identity and `use`. The projection
+ * the init-order consumer needs — the only consumer for which the distinction
+ * between two parallel edges genuinely does not matter.
+ *
+ * **Only injection sites order boot, and that is a property of the SITE, never
+ * of the node kind.** A site the reference field map reaches is a Phase-5
+ * injection site: the kernel puts the live instance into the field before
+ * `init()`, so the target must be constructed first — and that is as true for
+ * `Telo.Application`'s inline `targets[].invoke` (a step-declared slot the
+ * field map reaches) as for a resource-level `connection:`. A step slot behind
+ * a local `$ref` and a value-tree-discovered ref resolve at dispatch instead,
+ * so their targets need only exist by the time the step runs. An earlier
+ * revision keyed this on node kind and silently dropped boot targets' inline
+ * invoke edges from init order — the regression this comment exists to prevent.
+ *
+ * Scoped nodes take no part at all: a `with:`-scoped resource is created when
+ * the scope opens, and an edge into a scope is the owner's runtime business.
+ */
+export declare function projectToPairs(graph: CallGraph, options?: ProjectToPairsOptions): Map<string, Set<string>>;
+//# sourceMappingURL=call-graph.d.ts.map

package/dist/call-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-graph.d.ts","sourceRoot":"","sources":["../src/call-graph.ts"],"names":[],"mappings":"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"}