@nwire/scan 0.12.0 → 0.13.0

package/dist/graph.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The manifest's GRAPH MODEL — the definitive internal model as a typed
+ * node + edge graph: the digital twin of the system. Derived from the static
+ * `AstExtract` (shapes, positions, intent, event-causation edges) joined with
+ * the runtime `Topology` (plugins, capabilities-with-kinds, stages, handlers,
+ * bindings, hooks, triggers).
+ *
+ * Every unit of behaviour is a node carrying its kind, `file:line:column`, and
+ * declared intent (description / policy / slo / persona / journeyStep). Edges
+ * are typed and directional, so traversing them yields the joined
+ * `source → handler → effect → sink` paths a consumer (Studio / docs / the gate)
+ * renders — instead of stitching flat lists by name.
+ */
+import type { InvariantEntry, SourceLocationEntry } from "./scan.js";
+import type { AstExtract } from "./ast-extract.js";
+import type { Topology } from "./topology.js";
+/** Edge relationship types — the wiring vocabulary. */
+export type EdgeType = "triggers" | "emits" | "delivers" | "transitions" | "dispatches" | "reads" | "calls" | "provides" | "contributes" | "mounts";
+export interface GraphIntent {
+    readonly description?: string;
+    readonly policy?: unknown;
+    readonly slo?: unknown;
+    readonly persona?: string;
+    readonly journeyStep?: string;
+    readonly capability?: string;
+    readonly tags?: readonly string[];
+    /** Business-rule invariants surfaced from `validate()` predicates. */
+    readonly invariants?: readonly InvariantEntry[];
+    readonly public?: boolean;
+}
+export interface GraphNode {
+    /** Stable id: `${kind}:${name}` — edges reference these. */
+    readonly id: string;
+    readonly kind: string;
+    readonly name: string;
+    readonly source?: SourceLocationEntry;
+    readonly intent?: GraphIntent;
+    /** Kind-specific extras (states, schedule, emits, ctxKeys, …). */
+    readonly data?: Record<string, unknown>;
+}
+export interface GraphEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly type: EdgeType;
+    /** For `transitions`: the event that drives the state change. */
+    readonly on?: string;
+}
+export interface ManifestModel {
+    readonly nodes: readonly GraphNode[];
+    readonly edges: readonly GraphEdge[];
+}
+/**
+ * Build the node + edge graph from the static extract and (optionally) the
+ * runtime topology. Pure — no IO, no boot; the topology was already captured.
+ */
+export declare function buildGraph(ast: AstExtract, topology?: Topology): ManifestModel;

package/dist/graph.js

@@ -0,0 +1,325 @@
+/**
+ * The manifest's GRAPH MODEL — the definitive internal model as a typed
+ * node + edge graph: the digital twin of the system. Derived from the static
+ * `AstExtract` (shapes, positions, intent, event-causation edges) joined with
+ * the runtime `Topology` (plugins, capabilities-with-kinds, stages, handlers,
+ * bindings, hooks, triggers).
+ *
+ * Every unit of behaviour is a node carrying its kind, `file:line:column`, and
+ * declared intent (description / policy / slo / persona / journeyStep). Edges
+ * are typed and directional, so traversing them yields the joined
+ * `source → handler → effect → sink` paths a consumer (Studio / docs / the gate)
+ * renders — instead of stitching flat lists by name.
+ */
+const nid = (kind, name) => `${kind}:${name}`;
+const hasIntent = (i) => i.description !== undefined ||
+    i.policy !== undefined ||
+    i.slo !== undefined ||
+    i.persona !== undefined ||
+    i.journeyStep !== undefined ||
+    i.capability !== undefined ||
+    (i.tags?.length ?? 0) > 0 ||
+    (i.invariants?.length ?? 0) > 0 ||
+    i.public !== undefined;
+/**
+ * Build the node + edge graph from the static extract and (optionally) the
+ * runtime topology. Pure — no IO, no boot; the topology was already captured.
+ */
+export function buildGraph(ast, topology) {
+    const nodes = [];
+    const edges = [];
+    const seen = new Set();
+    const add = (n) => {
+        if (seen.has(n.id))
+            return;
+        seen.add(n.id);
+        const intent = n.intent && hasIntent(n.intent) ? n.intent : undefined;
+        nodes.push(intent ? { ...n, intent } : { ...n, intent: undefined });
+    };
+    const seenEdge = new Set();
+    const edge = (from, to, type, on) => {
+        const key = `${from}|${to}|${type}|${on ?? ""}`;
+        if (seenEdge.has(key))
+            return;
+        seenEdge.add(key);
+        edges.push(on ? { from, to, type, on } : { from, to, type });
+    };
+    // ── Domain nodes (static AST) ──────────────────────────────────────
+    for (const e of ast.events)
+        add({
+            id: nid("event", e.name),
+            kind: "event",
+            name: e.name,
+            source: e.source,
+            intent: { description: e.description, public: e.public },
+            data: { version: e.version, audience: e.audience },
+        });
+    for (const a of ast.actions)
+        add({
+            id: nid("action", a.name),
+            kind: "action",
+            name: a.name,
+            source: a.source,
+            intent: {
+                description: a.description,
+                policy: a.policy,
+                slo: a.slo,
+                persona: a.persona,
+                journeyStep: a.journeyStep,
+                capability: a.capability,
+                tags: a.tags,
+                invariants: a.invariants,
+                public: a.public,
+            },
+            data: { emits: a.emits, retry: a.retry, hasInlineHandler: a.hasInlineHandler },
+        });
+    for (const q of ast.queries)
+        add({
+            id: nid("query", q.name),
+            kind: "query",
+            name: q.name,
+            source: q.source,
+            intent: { public: q.public },
+            data: { projection: q.projection },
+        });
+    // Shared state-machine emit: state nodes + `transitions` edges (on event).
+    // `from: "*"` (always-active) is rooted at the machine node itself.
+    const emitStates = (machineKind, machineName, declaredStates, transitions) => {
+        const stateKind = `${machineKind}State`;
+        const stateId = (s) => nid(stateKind, `${machineName}/${s}`);
+        const machineId = nid(machineKind, machineName);
+        const names = new Set(declaredStates);
+        for (const t of transitions ?? []) {
+            if (t.from !== "*")
+                names.add(t.from);
+            names.add(t.to);
+        }
+        for (const s of names)
+            add({ id: stateId(s), kind: stateKind, name: s, data: { [machineKind]: machineName } });
+        for (const t of transitions ?? [])
+            edge(t.from === "*" ? machineId : stateId(t.from), stateId(t.to), "transitions", t.on);
+    };
+    for (const ac of ast.actors) {
+        add({
+            id: nid("actor", ac.name),
+            kind: "actor",
+            name: ac.name,
+            source: ac.source,
+            intent: { invariants: ac.invariants },
+            data: { states: ac.states },
+        });
+        emitStates("actor", ac.name, ac.states, ac.transitions);
+    }
+    for (const w of ast.workflows) {
+        add({
+            id: nid("workflow", w.name),
+            kind: "workflow",
+            name: w.name,
+            source: w.source,
+            intent: { description: w.description, public: w.public },
+            data: { subscribesTo: w.subscribesTo, dispatches: w.dispatches },
+        });
+        emitStates("workflow", w.name, [], w.transitions);
+        for (const c of w.calls ?? [])
+            edge(nid("workflow", w.name), nid("externalCall", c), "calls");
+    }
+    for (const p of ast.projections)
+        add({
+            id: nid("projection", p.name),
+            kind: "projection",
+            name: p.name,
+            source: p.source,
+            intent: { description: p.description },
+            data: { listens: p.listens },
+        });
+    // Extra static kinds — present once their extractors land; guarded so the
+    // graph picks them up automatically without coupling to extractor order.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const x = ast;
+    for (const c of x.commands ?? [])
+        add({ id: nid("command", c.name), kind: "command", name: c.name, source: c.source });
+    for (const c of x.crons ?? [])
+        add({
+            id: nid("cron", c.name),
+            kind: "cron",
+            name: c.name,
+            source: c.source,
+            data: { schedule: c.schedule },
+        });
+    for (const c of x.externalCalls ?? [])
+        add({ id: nid("externalCall", c.name), kind: "externalCall", name: c.name, source: c.source });
+    for (const c of x.inboundWebhooks ?? [])
+        add({
+            id: nid("inboundWebhook", c.name),
+            kind: "inboundWebhook",
+            name: c.name,
+            source: c.source,
+        });
+    for (const c of x.outboxes ?? [])
+        add({ id: nid("outbox", c.name), kind: "outbox", name: c.name, source: c.source });
+    for (const c of x.inboxes ?? [])
+        add({ id: nid("inbox", c.name), kind: "inbox", name: c.name, source: c.source });
+    for (const c of x.resources ?? [])
+        add({ id: nid("resource", c.name), kind: "resource", name: c.name, source: c.source });
+    for (const c of x.errors ?? [])
+        add({ id: nid("error", c.code), kind: "error", name: c.code, source: c.source });
+    for (const c of x.schemas ?? [])
+        add({
+            id: nid("schema", c.name),
+            kind: "schema",
+            name: c.name,
+            source: c.source,
+            data: { states: c.states, key: c.key },
+        });
+    // ── Domain edges ───────────────────────────────────────────────────
+    // `emits` from each action's declared events (the static graph carries
+    // folds/subscribes/dispatches, but the emit list lives on the action entry).
+    for (const a of ast.actions) {
+        for (const ev of a.emits)
+            edge(nid("action", a.name), nid("event", ev), "emits");
+        for (const c of a.calls ?? [])
+            edge(nid("action", a.name), nid("externalCall", c), "calls");
+    }
+    for (const ed of ast.graph.events) {
+        switch (ed.via) {
+            case "emits":
+                edge(nid("action", ed.from), nid("event", ed.to), "emits");
+                break;
+            case "folds":
+                edge(nid("event", ed.from), nid("projection", ed.to), "delivers");
+                break;
+            case "subscribes":
+                edge(nid("event", ed.from), nid("workflow", ed.to), "delivers");
+                break;
+            case "dispatches":
+                edge(nid("workflow", ed.from), nid("action", ed.to), "dispatches");
+                break;
+            default:
+                break;
+        }
+    }
+    for (const q of ast.queries)
+        if (q.projection)
+            edge(nid("query", q.name), nid("projection", q.projection), "reads");
+    // ── Topology layer (runtime wiring) ────────────────────────────────
+    if (topology) {
+        for (const pl of topology.plugins)
+            add({ id: nid("plugin", pl.name), kind: "plugin", name: pl.name });
+        for (const cap of topology.capabilities)
+            add({
+                id: nid("capability", cap.name),
+                kind: "capability",
+                name: cap.name,
+                data: { kinds: cap.kinds, ctxKeys: cap.ctxKeys },
+            });
+        for (const s of topology.sourceStages)
+            add({
+                id: nid("sourceStage", s.name),
+                kind: "sourceStage",
+                name: s.name,
+                data: { position: s.position, stageKind: s.kind },
+            });
+        for (const s of topology.sinkStages)
+            add({
+                id: nid("sinkStage", s.name),
+                kind: "sinkStage",
+                name: s.name,
+                data: { position: s.position, stageKind: s.kind },
+            });
+        for (const b of topology.bindings)
+            add({ id: nid("binding", b.name), kind: "binding", name: b.name, data: { diKind: b.kind } });
+        for (const h of topology.hooks)
+            add({
+                id: nid("hook", h.name),
+                kind: "hook",
+                name: h.name,
+                source: h.source,
+                data: { chain: h.chain, listeners: h.listeners },
+            });
+        // Registered handlers — plain handlers / listeners that aren't already a
+        // domain node (action/query ids merge with the domain nodes above).
+        for (const h of topology.handlers)
+            add({ id: nid(h.kind, h.name), kind: h.kind, name: h.name });
+        // kind pseudo-nodes + capability→kind `provides` edges (the ctx-per-kind map).
+        const allKinds = new Set(Object.keys(topology.ctxByKind));
+        for (const k of allKinds)
+            add({ id: nid("kind", k), kind: "kind", name: k, data: { ctxKeys: topology.ctxByKind[k] } });
+        for (const cap of topology.capabilities) {
+            const applies = cap.kinds ?? [...allKinds]; // undefined = universal
+            for (const k of applies)
+                edge(nid("capability", cap.name), nid("kind", k), "provides");
+        }
+        // app nodes (the BC) + richer route nodes; `mounts` app → route.
+        // env/config are scanned statically from the app's source tree (project-
+        // scoped, one app per manifest) and surfaced on the app node's data.
+        for (const ap of topology.apps)
+            add({
+                id: nid("app", ap.name),
+                kind: "app",
+                name: ap.name,
+                intent: { description: ap.description },
+                data: {
+                    plugins: ap.plugins,
+                    ...(ast.env.length ? { env: ast.env } : {}),
+                    ...(ast.config.length ? { config: ast.config } : {}),
+                },
+            });
+        for (const r of topology.routes) {
+            const label = `${r.method} ${r.path}`;
+            add({
+                id: nid("route", label),
+                kind: "route",
+                name: label,
+                data: { method: r.method, path: r.path },
+            });
+            for (const ap of topology.apps)
+                edge(nid("app", ap.name), nid("route", label), "mounts");
+        }
+        // triggers: source (route/binding) → the handler it dispatches. The route id
+        // matches the richer route nodes above (same `"METHOD /path"` label).
+        for (const t of topology.triggers) {
+            const routeId = nid("route", t.binding);
+            add({ id: routeId, kind: "route", name: t.binding });
+            if (t.handler) {
+                const hk = topology.handlers.find((h) => h.name === t.handler)?.kind ?? "handler";
+                edge(routeId, nid(hk, t.handler), "triggers");
+            }
+        }
+        // `contributes`: plugin → the binding/capability/stage/handler/hook it
+        // added, attributed at boot by the app lifecycle (diffing the runtime +
+        // hook registry around each plugin's phase). Each contributed name maps to
+        // its already-added graph node by kind; edges to a node we didn't add are
+        // skipped (the node may be a static-only kind the topology doesn't carry).
+        for (const c of topology.contributions ?? []) {
+            const pluginId = nid("plugin", c.plugin);
+            const contribute = (kind, name) => {
+                const targetId = nid(kind, name);
+                if (seen.has(targetId))
+                    edge(pluginId, targetId, "contributes");
+            };
+            for (const b of c.bindings)
+                contribute("binding", b);
+            for (const cap of c.capabilities)
+                contribute("capability", cap);
+            for (const s of c.sourceStages)
+                contribute("sourceStage", s);
+            for (const s of c.sinkStages)
+                contribute("sinkStage", s);
+            for (const h of c.handlers) {
+                // A handler node id uses its registered kind, not "handler".
+                const hk = topology.handlers.find((x) => x.name === h)?.kind ?? "handler";
+                contribute(hk, h);
+            }
+            for (const h of c.hooks)
+                contribute("hook", h);
+        }
+        // The →sink leg: a public event drains to the terminal outbound stage(s),
+        // completing the joined source → handler → effect → sink path.
+        const terminalSinks = topology.sinkStages.filter((s) => s.position === "terminal");
+        for (const e of ast.events)
+            if (e.public)
+                for (const s of terminalSinks)
+                    edge(nid("event", e.name), nid("sinkStage", s.name), "delivers");
+    }
+    return { nodes, edges };
+}

package/dist/manifest.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The build-time manifest — the static graph, written without booting an app.
+ *
+ * "Scan the graph, not the runtime." `buildManifest(root)` walks the source
+ * tree with the AST extractor (`extractFromFiles`) and produces a `Manifest`:
+ * every event / action / query / actor / workflow / projection with its
+ * `file:line:column`, the event-graph edges, and an `unanalyzable` list for
+ * anything not statically resolvable (never silently dropped). `writeManifest`
+ * serializes it to `.nwire/manifest.json`; `readManifest` loads it back — so
+ * Studio / please / trust / doc-gen can read the graph without a running app.
+ *
+ * equivalence harness proves this static extract matches it. Later units retire
+ * the runtime path and point consumers here.
+ */
+import { type AstExtract } from "./ast-extract.js";
+import { type Topology } from "./topology.js";
+import { type ManifestModel } from "./graph.js";
+/** Bumped when the manifest shape changes, so readers can detect a stale file. */
+export declare const MANIFEST_VERSION: 3;
+/**
+ * The project manifest — the static AST graph (events/actions/queries/actors/
+ * workflows/projections + positions + event-causation edges) plus, when built
+ * with a booted app, the runtime `topology` (plugins, capabilities-with-kinds,
+ * source/sink stages, ctx-per-kind, handlers, bindings, hooks, triggers). Static
+ * shapes + runtime wiring — enough to render exactly how the app works and why.
+ */
+export interface Manifest extends AstExtract {
+    readonly version: typeof MANIFEST_VERSION;
+    /** Runtime topology layer — present only when `buildManifest` got a booted app. */
+    readonly topology?: Topology;
+    /**
+     * The definitive internal model — a typed node + edge graph joining the static
+     * shapes with the runtime topology. The digital twin: traverse the edges to
+     * get `source → handler → effect → sink` paths. Always present.
+     */
+    readonly model: ManifestModel;
+}
+/**
+ * Recursively collect non-test `.ts` source files under `root` — the input to
+ * the AST extractor. Skips build output, deps, and test/declaration files so
+ * the manifest reflects authored source only.
+ */
+export declare function collectSourceFiles(root: string): string[];
+/**
+ * Read the topology a running app self-emitted to `<root>/.nwire/topology.json`.
+ * Returns `undefined` when the file is absent or unreadable (graceful — the
+ * static path then produces a manifest with no topology layer).
+ */
+export declare function readEmittedTopology(root: string): Topology | undefined;
+/**
+ * Build the manifest by extracting the static graph from the source tree at
+ * `root`. The topology layer (plugins/capabilities/stages/ctx-per-kind/…) needs
+ * a running app; it is resolved in priority order:
+ *
+ *   1. a booted `instance` passed in — `captureTopology(instance)` (legacy path);
+ *   2. else `<root>/.nwire/topology.json`, the file a running app self-emits.
+ *
+ * When neither is present the manifest carries no topology layer (graceful).
+ */
+export declare function buildManifest(root: string, app?: string, instance?: any): Manifest;
+/** Write the manifest to `<outDir>/manifest.json` (default `.nwire`). */
+export declare function writeManifest(manifest: Manifest, outDir?: string): Promise<void>;
+/**
+ * Load `<dir>/manifest.json` (default `.nwire`). Returns `undefined` when the
+ * file is absent — callers decide whether that's "build first" or an error.
+ */
+export declare function readManifest(dir?: string): Manifest | undefined;

package/dist/manifest.js

@@ -0,0 +1,103 @@
+/**
+ * The build-time manifest — the static graph, written without booting an app.
+ *
+ * "Scan the graph, not the runtime." `buildManifest(root)` walks the source
+ * tree with the AST extractor (`extractFromFiles`) and produces a `Manifest`:
+ * every event / action / query / actor / workflow / projection with its
+ * `file:line:column`, the event-graph edges, and an `unanalyzable` list for
+ * anything not statically resolvable (never silently dropped). `writeManifest`
+ * serializes it to `.nwire/manifest.json`; `readManifest` loads it back — so
+ * Studio / please / trust / doc-gen can read the graph without a running app.
+ *
+ * equivalence harness proves this static extract matches it. Later units retire
+ * the runtime path and point consumers here.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { extractFromFiles } from "./ast-extract.js";
+import { captureTopology } from "./topology.js";
+import { buildGraph } from "./graph.js";
+/** Bumped when the manifest shape changes, so readers can detect a stale file. */
+export const MANIFEST_VERSION = 3;
+const SKIP_DIRS = new Set(["node_modules", "dist", ".nwire", ".git", ".vitepress", "__tests__"]);
+/**
+ * Recursively collect non-test `.ts` source files under `root` — the input to
+ * the AST extractor. Skips build output, deps, and test/declaration files so
+ * the manifest reflects authored source only.
+ */
+export function collectSourceFiles(root) {
+    const out = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir)) {
+            const p = join(dir, entry);
+            const st = statSync(p);
+            if (st.isDirectory()) {
+                if (!SKIP_DIRS.has(entry))
+                    walk(p);
+                continue;
+            }
+            if (entry.endsWith(".ts") &&
+                !entry.endsWith(".test.ts") &&
+                !entry.endsWith(".spec.ts") &&
+                !entry.endsWith(".steps.ts") &&
+                !entry.endsWith(".d.ts")) {
+                out.push(p);
+            }
+        }
+    };
+    if (existsSync(root))
+        walk(root);
+    return out;
+}
+/**
+ * Read the topology a running app self-emitted to `<root>/.nwire/topology.json`.
+ * Returns `undefined` when the file is absent or unreadable (graceful — the
+ * static path then produces a manifest with no topology layer).
+ */
+export function readEmittedTopology(root) {
+    const p = resolve(root, ".nwire", "topology.json");
+    if (!existsSync(p))
+        return undefined;
+    try {
+        const file = JSON.parse(readFileSync(p, "utf8"));
+        return file.topology;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build the manifest by extracting the static graph from the source tree at
+ * `root`. The topology layer (plugins/capabilities/stages/ctx-per-kind/…) needs
+ * a running app; it is resolved in priority order:
+ *
+ *   1. a booted `instance` passed in — `captureTopology(instance)` (legacy path);
+ *   2. else `<root>/.nwire/topology.json`, the file a running app self-emits.
+ *
+ * When neither is present the manifest carries no topology layer (graceful).
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function buildManifest(root, app = "", instance) {
+    const ast = extractFromFiles(collectSourceFiles(root), app);
+    const topology = instance ? captureTopology(instance) : readEmittedTopology(root);
+    const model = buildGraph(ast, topology);
+    return topology
+        ? { version: MANIFEST_VERSION, ...ast, topology, model }
+        : { version: MANIFEST_VERSION, ...ast, model };
+}
+/** Write the manifest to `<outDir>/manifest.json` (default `.nwire`). */
+export async function writeManifest(manifest, outDir = ".nwire") {
+    await mkdir(outDir, { recursive: true });
+    await writeFile(resolve(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+}
+/**
+ * Load `<dir>/manifest.json` (default `.nwire`). Returns `undefined` when the
+ * file is absent — callers decide whether that's "build first" or an error.
+ */
+export function readManifest(dir = ".nwire") {
+    const p = resolve(dir, "manifest.json");
+    if (!existsSync(p))
+        return undefined;
+    return JSON.parse(readFileSync(p, "utf8"));
+}