@nwire/scan 0.12.1 → 0.13.0

package/dist/scan.d.ts

@@ -1,20 +1,30 @@
 /**
- * `@nwire/scan` — produces the `.nwire/` cache by inspecting booted apps.
- *
- * Each input is an `App` (or any object exposing `appName`, `container`,
- * `runtime`). When forge is installed, the scanner walks the dispatcher
- * metadata maps to collect actions, actors, projections, queries,
- * workflows, and external calls. It also reads `container.list()` for
- * DI bindings and `runtime.listHooks()` for hooks.
- *
- * Callers are responsible for booting their apps before scanning — the
- * forge plugin populates the dispatcher during `app.start()`.
+ * `@nwire/scan` — the static type surface (the `*Entry` shapes) shared by the
+ * AST extractor + the build-time manifest, plus re-exports of the manifest API
+ * (`buildManifest` / `writeManifest` / `readManifest`, the topology capture, and
+ * the node+edge graph). The old runtime boot-and-walk (`buildCache`) is gone —
+ * `nwire cache` emits `.nwire/manifest.json` via `buildManifest`.
  */
 export interface SourceLocationEntry {
     readonly file: string;
     readonly line?: number;
     readonly column?: number;
 }
+/**
+ * A business-rule invariant captured from a `validate()` predicate: the
+ * predicate's source text (`rule`) and its English failure message (`message`)
+ * when one is statically present.
+ */
+export interface InvariantEntry {
+    readonly rule: string;
+    readonly message?: string;
+}
+/** A state-machine edge: `from --on--> to` (actor/workflow). `from: "*"` = any state. */
+export interface TransitionEdge {
+    readonly from: string;
+    readonly on: string;
+    readonly to: string;
+}
 export interface ActionEntry {
     readonly name: string;
     readonly app: string;
@@ -23,6 +33,10 @@ export interface ActionEntry {
     readonly inputSchema?: unknown;
     /** Event names this action emits, in declaration order. */
     readonly emits: readonly string[];
+    /** External-call names invoked in the handler body (ctx.externalCall). */
+    readonly calls?: readonly string[];
+    /** Business-rule invariants surfaced from `validate()` predicates in the handler. */
+    readonly invariants?: readonly InvariantEntry[];
     /** True when a handler was wired via defineAction({handler}) — false for split definitions. */
     readonly hasInlineHandler: boolean;
     readonly persona?: string;
@@ -82,6 +96,10 @@ export interface WorkflowEntry {
     readonly subscribesTo: readonly string[];
     /** Action names this workflow dispatches inside its body. */
     readonly dispatches: readonly string[];
+    /** State→state transitions (saga state machine), `from: "*"` = always-active `when`. */
+    readonly transitions?: readonly TransitionEdge[];
+    /** External-call names invoked in the body. */
+    readonly calls?: readonly string[];
     readonly source?: SourceLocationEntry;
 }
 export interface EventEntry {
@@ -99,6 +117,10 @@ export interface ActorEntry {
     readonly app: string;
     /** State names declared in the actor's `states` map. */
     readonly states: readonly string[];
+    /** State→state transitions from the closure's `when` reactions, `from: "*"` = always-active. */
+    readonly transitions?: readonly TransitionEdge[];
+    /** Business-rule invariants surfaced from `validate()` predicates in the actor's methods. */
+    readonly invariants?: readonly InvariantEntry[];
     readonly source?: SourceLocationEntry;
 }
 export interface ProjectionEntry {
@@ -117,6 +139,11 @@ export interface QueryEntry {
     readonly projection?: string;
     readonly source?: SourceLocationEntry;
 }
+/** A config module the app exposes: its file path and top-level field names. */
+export interface ConfigModuleEntry {
+    readonly file: string;
+    readonly keys: readonly string[];
+}
 export interface AppEntry {
     readonly name: string;
     readonly description?: string;
@@ -124,6 +151,10 @@ export interface AppEntry {
     readonly plugins: readonly string[];
     readonly tenantModel?: string;
     readonly tenantKey?: string;
+    /** Environment variable names the app's source reads (sorted, de-duped). */
+    readonly env?: readonly string[];
+    /** Config modules discovered under the app's `config/` directory. */
+    readonly config?: readonly ConfigModuleEntry[];
 }
 export interface SinkEntry {
     readonly name: string;
@@ -197,101 +228,8 @@ export interface EventGraphEdge {
     readonly to: string;
     readonly via: string;
 }
-export interface Cache {
-    readonly generatedAt: string;
-    readonly apps: readonly AppEntry[];
-    readonly actions: readonly ActionEntry[];
-    readonly events: readonly EventEntry[];
-    readonly actors: readonly ActorEntry[];
-    readonly projections: readonly ProjectionEntry[];
-    readonly queries: readonly QueryEntry[];
-    readonly resolvers: readonly ResolverEntry[];
-    readonly routes: readonly RouteEntry[];
-    readonly workflows: readonly WorkflowEntry[];
-    readonly externalCalls: readonly ExternalCallEntry[];
-    readonly inboundWebhooks: readonly InboundWebhookEntry[];
-    readonly outboxes: readonly OutboxEntry[];
-    readonly inboxes: readonly InboxEntry[];
-    readonly crons: readonly CronEntry[];
-    readonly commands: readonly CommandEntry[];
-    readonly hooks: readonly HookEntry[];
-    readonly plugins: readonly PluginEntry[];
-    readonly sinks: readonly SinkEntry[];
-    readonly bindings: readonly DIBindingEntry[];
-    readonly resources: readonly ResourceEntry[];
-    readonly errors: readonly ErrorEntry[];
-    readonly middleware: readonly MiddlewareEntry[];
-    readonly graph: {
-        readonly events: readonly EventGraphEdge[];
-    };
-}
-export type ResourceInput = {
-    readonly $kind: "resource";
-} | {
-    readonly definition: {
-        readonly $kind: "resource";
-    } & Record<string, any>;
-    readonly app?: string;
-    readonly module?: string;
-};
-export type ErrorInput = {
-    readonly $kind: "error";
-} | {
-    readonly definition: {
-        readonly $kind: "error";
-    } & Record<string, any>;
-    readonly app?: string;
-    readonly module?: string;
-};
-export type MiddlewareInput = {
-    readonly name: string;
-} | {
-    readonly definition: {
-        readonly name: string;
-    };
-    readonly where?: string;
-};
-export interface BuildCacheOptions {
-    readonly mounts?: readonly ResolverMount[];
-    readonly interfaces?: readonly RouteSource[];
-    readonly resources?: readonly ResourceInput[];
-    readonly errors?: readonly ErrorInput[];
-    readonly middleware?: readonly MiddlewareInput[];
-}
-interface ScannedApp {
-    readonly appName: string;
-    readonly description?: string;
-    dispatcher?: () => any;
-    /** Plugin definitions installed via createApp({plugins}) or .with(). */
-    readonly plugins?: readonly {
-        name: string;
-        $source?: SourceLocationEntry;
-    }[];
-    container: {
-        resolve?: <T = any>(name: string) => T;
-        list?(): readonly {
-            name: string;
-            kind: string;
-            source?: SourceLocationEntry;
-        }[];
-    };
-    runtime?: {
-        listHooks?(): readonly {
-            id: string;
-            name: string;
-            chain: number;
-            listeners: number;
-            source?: SourceLocationEntry;
-        }[];
-        listSinkStages?(): readonly {
-            name: string;
-            kind?: string;
-            position: "early" | "middle" | "terminal";
-            direction?: "outbound";
-        }[];
-        hooks?: Record<string, any>;
-    };
-}
-export declare function buildCache(apps: readonly ScannedApp[], options?: BuildCacheOptions): Cache;
-export declare function writeCache(cache: Cache, dir: string): Promise<void>;
-export {};
+export { buildManifest, writeManifest, readManifest, collectSourceFiles, MANIFEST_VERSION, type Manifest, } from "./manifest.js";
+export { extractFromFiles, collectConfigModules, type AstExtract, type SchemaEntry, type ConfigModuleEntry as AstConfigModuleEntry, } from "./ast-extract.js";
+export { captureTopology, type Topology, type CapabilityInfo, type StageInfo, type PluginInfo, type BindingInfo, type HandlerInfo, type HookInfo, type ContributionInfo, type TriggerInfo, } from "./topology.js";
+export { buildGraph, type ManifestModel, type GraphNode, type GraphEdge, type GraphIntent, type EdgeType, } from "./graph.js";
+export { listTelemetryRuns, readTelemetryRun, type TelemetryRunMeta } from "./telemetry-runs.js";

package/dist/scan.js

@@ -1,383 +1,15 @@
 /**
- * `@nwire/scan` — produces the `.nwire/` cache by inspecting booted apps.
- *
- * Each input is an `App` (or any object exposing `appName`, `container`,
- * `runtime`). When forge is installed, the scanner walks the dispatcher
- * metadata maps to collect actions, actors, projections, queries,
- * workflows, and external calls. It also reads `container.list()` for
- * DI bindings and `runtime.listHooks()` for hooks.
- *
- * Callers are responsible for booting their apps before scanning — the
- * forge plugin populates the dispatcher during `app.start()`.
+ * `@nwire/scan` — the static type surface (the `*Entry` shapes) shared by the
+ * AST extractor + the build-time manifest, plus re-exports of the manifest API
+ * (`buildManifest` / `writeManifest` / `readManifest`, the topology capture, and
+ * the node+edge graph). The old runtime boot-and-walk (`buildCache`) is gone —
+ * `nwire cache` emits `.nwire/manifest.json` via `buildManifest`.
  */
-import { writeFile, mkdir } from "node:fs/promises";
-import { resolve } from "node:path";
-// Pull the ForgeDispatcher off an App in either 0.9 or 0.10 shape. Returns
-// undefined when the App doesn't have forge wired (plain HTTP-only App) —
-// the scanner skips forge-specific collection in that case.
-function resolveDispatcher(app) {
-    if (typeof app.dispatcher === "function") {
-        try {
-            const d = app.dispatcher();
-            if (d)
-                return d;
-        }
-        catch {
-            /* fall through */
-        }
-    }
-    if (typeof app.container?.resolve === "function") {
-        try {
-            const d = app.container.resolve("forge.dispatcher");
-            if (d)
-                return d;
-        }
-        catch {
-            /* not bound — plain app, no forge */
-        }
-    }
-    return undefined;
-}
-function sourceOf(value) {
-    return value?.$source;
-}
-/**
- * Coerce a Zod schema into a JSON-Schema-shaped `{ type, properties,
- * required }` value Studio's form renderer + SchemaTree understand. The
- * scanner doesn't carry a Zod dep, so we walk the runtime shape Zod 4
- * publishes (`def.type`, `def.shape`, `def.innerType`, etc.) and project
- * the bits Studio needs.
- *
- * Falls back to the raw value when the shape is unrecognisable so the
- * SchemaTree's "raw JSON" view still shows something.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function zodToJsonSchema(schema) {
-    if (!schema || typeof schema !== "object")
-        return schema;
-    const s = schema;
-    const def = (s.def ?? s._def ?? {});
-    const type = String(def.type ?? "");
-    switch (type) {
-        case "object": {
-            const shape = (def.shape ?? {});
-            const properties = {};
-            const required = [];
-            for (const [key, raw] of Object.entries(shape)) {
-                const field = raw;
-                const inner = zodToJsonSchema(field);
-                properties[key] = inner;
-                // A field is required when its def isn't `optional`/`nullable`.
-                const innerType = (field.def ?? {}).type;
-                if (innerType !== "optional" && innerType !== "nullable") {
-                    required.push(key);
-                }
-            }
-            return { type: "object", properties, required };
-        }
-        case "string":
-            return { type: "string" };
-        case "number":
-            return { type: "number" };
-        case "boolean":
-            return { type: "boolean" };
-        case "literal":
-            return { type: typeof def.value, enum: [def.value] };
-        case "enum": {
-            const opts = (def.entries ?? def.values ?? []);
-            return { type: "string", enum: opts };
-        }
-        case "array":
-            return { type: "array", items: zodToJsonSchema(def.element) };
-        case "optional":
-        case "nullable":
-        case "default":
-            return zodToJsonSchema(def.innerType);
-        case "union": {
-            const opts = (def.options ?? []);
-            return { anyOf: opts.map((o) => zodToJsonSchema(o)) };
-        }
-        case "record":
-            return { type: "object", additionalProperties: zodToJsonSchema(def.valueType) };
-        default:
-            // Unrecognised — return the raw shape so the SchemaTree at least
-            // shows the JSON, even if the form renderer can't drive it.
-            return schema;
-    }
-}
-function safeMap(map) {
-    return map ?? new Map();
-}
-export function buildCache(apps, options = {}) {
-    const out = {
-        generatedAt: new Date().toISOString(),
-        apps: [],
-        actions: [],
-        events: [],
-        actors: [],
-        projections: [],
-        queries: [],
-        resolvers: [],
-        routes: [],
-        workflows: [],
-        externalCalls: [],
-        inboundWebhooks: [],
-        outboxes: [],
-        inboxes: [],
-        crons: [],
-        commands: [],
-        hooks: [],
-        plugins: [],
-        sinks: [],
-        bindings: [],
-        resources: [],
-        errors: [],
-        middleware: [],
-        graph: { events: [] },
-    };
-    const eventNamesSeen = new Set();
-    for (const app of apps) {
-        const pluginNames = (app.plugins ?? []).map((p) => p.name);
-        out.apps.push({
-            name: app.appName,
-            description: app.description,
-            plugins: pluginNames,
-        });
-        // ── Plugins ─────────────────────────────────────────────────────
-        for (const plugin of app.plugins ?? []) {
-            out.plugins.push({
-                name: plugin.name,
-                kind: "plugin",
-                app: app.appName,
-                source: plugin.$source,
-            });
-        }
-        // ── Sink stages (outbound) ─────────────────────────────────────
-        const sinkStages = app.runtime?.listSinkStages?.() ?? [];
-        for (const stage of sinkStages) {
-            out.sinks.push({
-                name: stage.name,
-                app: app.appName,
-                kind: stage.kind,
-                position: stage.position,
-                direction: stage.direction ?? "outbound",
-            });
-        }
-        const dispatcher = resolveDispatcher(app);
-        if (!dispatcher) {
-            // Plain HTTP App with no forge — the scanner has nothing to
-            // collect from the runtime side. Continue to the next App.
-            continue;
-        }
-        // ── Actions (via handlers) ──────────────────────────────────────
-        const handlers = safeMap(dispatcher.handlers);
-        for (const [name, handler] of handlers) {
-            const action = handler.action ?? {};
-            const emits = (action.emits ?? []);
-            out.actions.push({
-                name,
-                app: app.appName,
-                description: typeof action.description === "string" ? action.description : undefined,
-                public: Boolean(action.$public),
-                inputSchema: zodToJsonSchema(action.schema),
-                emits: emits.map((e) => String(e?.name ?? "")).filter(Boolean),
-                hasInlineHandler: typeof action.handler === "object" && action.handler !== null,
-                persona: typeof action.persona === "string" ? action.persona : undefined,
-                journeyStep: typeof action.journeyStep === "string" ? action.journeyStep : undefined,
-                capability: typeof action.capability === "string" ? action.capability : undefined,
-                slo: action.slo,
-                retry: action.retry,
-                policy: action.policy,
-                tags: action.tags,
-                source: sourceOf(action),
-            });
-            for (const ev of emits) {
-                if (ev?.name && !eventNamesSeen.has(ev.name)) {
-                    eventNamesSeen.add(ev.name);
-                    out.events.push({
-                        name: ev.name,
-                        app: app.appName,
-                        public: Boolean(ev.$public),
-                        description: typeof ev.description === "string" ? ev.description : undefined,
-                        version: typeof ev.version === "number" ? ev.version : undefined,
-                        audience: Array.isArray(ev.audience) ? ev.audience : undefined,
-                        source: sourceOf(ev),
-                    });
-                }
-                if (ev?.name) {
-                    out.graph.events.push({ from: name, to: ev.name, via: "emits" });
-                }
-            }
-        }
-        // ── Actors ──────────────────────────────────────────────────────
-        const actors = safeMap(dispatcher.actors);
-        for (const [name, def] of actors) {
-            const stateNames = def.states && typeof def.states === "object"
-                ? Object.keys(def.states)
-                : [];
-            out.actors.push({
-                name,
-                app: app.appName,
-                states: stateNames,
-                source: sourceOf(def),
-            });
-        }
-        // ── Projections + listened events ──────────────────────────────
-        const projections = safeMap(dispatcher.projections);
-        for (const [name, def] of projections) {
-            const listens = (def.listens ?? []);
-            out.projections.push({
-                name,
-                app: app.appName,
-                description: typeof def.description === "string" ? def.description : undefined,
-                listens: listens.map((e) => String(e?.name ?? "")).filter(Boolean),
-                source: sourceOf(def),
-            });
-            for (const ev of listens) {
-                if (ev?.name && !eventNamesSeen.has(ev.name)) {
-                    eventNamesSeen.add(ev.name);
-                    out.events.push({
-                        name: ev.name,
-                        app: app.appName,
-                        public: Boolean(ev.$public),
-                        description: typeof ev.description === "string" ? ev.description : undefined,
-                        version: typeof ev.version === "number" ? ev.version : undefined,
-                        audience: Array.isArray(ev.audience) ? ev.audience : undefined,
-                        source: sourceOf(ev),
-                    });
-                }
-                if (ev?.name) {
-                    out.graph.events.push({ from: ev.name, to: name, via: "folds" });
-                }
-            }
-        }
-        // ── Queries ─────────────────────────────────────────────────────
-        const queries = safeMap(dispatcher.queries);
-        for (const [name, def] of queries) {
-            const proj = def.projection;
-            out.queries.push({
-                name,
-                app: app.appName,
-                public: Boolean(def.$public),
-                projection: typeof proj?.name === "string" ? proj.name : undefined,
-                source: sourceOf(def),
-            });
-        }
-        // ── Workflows + subscribed/dispatched edges ────────────────────
-        const workflowDefs = dispatcher.listWorkflows?.() ?? [];
-        for (const def of workflowDefs) {
-            const name = String(def.name);
-            const subscribed = (def.subscribedEvents ?? new Set());
-            const dispatched = (def.dispatchedActions ?? new Set());
-            out.workflows.push({
-                name,
-                app: app.appName,
-                public: Boolean(def.$public),
-                description: typeof def.description === "string" ? def.description : undefined,
-                subscribesTo: [...subscribed],
-                dispatches: [...dispatched],
-                source: sourceOf(def),
-            });
-            for (const evName of (def.subscribedEvents ?? new Set())) {
-                out.graph.events.push({ from: evName, to: name, via: "subscribes" });
-            }
-            for (const actName of (def.dispatchedActions ?? new Set())) {
-                out.graph.events.push({ from: name, to: actName, via: "dispatches" });
-            }
-        }
-        // ── External calls ─────────────────────────────────────────────
-        const externalCalls = safeMap(dispatcher.externalCalls);
-        for (const [name, def] of externalCalls) {
-            out.externalCalls.push({ name, app: app.appName, source: sourceOf(def) });
-        }
-        // ── DI bindings ────────────────────────────────────────────────
-        const bindings = app.container.list?.() ?? [];
-        for (const b of bindings) {
-            out.bindings.push({
-                name: b.name,
-                kind: (b.kind === "singleton" || b.kind === "transient" ? b.kind : "singleton"),
-                app: app.appName,
-                source: b.source,
-            });
-        }
-        // ── Hooks ──────────────────────────────────────────────────────
-        // Prefer the structural listHooks helper if the runtime exposes one;
-        // otherwise walk `runtime.hooks` map and read step counts off each
-        // hook. Framework slots that haven't been materialised by a plugin
-        // (`runtime.defineHook(name)`) are absent — that's correct, we don't
-        // want to surface dead slots.
-        const explicit = app.runtime?.listHooks?.();
-        if (explicit) {
-            for (const h of explicit) {
-                out.hooks.push({
-                    id: h.id,
-                    name: h.name,
-                    chain: h.chain,
-                    listeners: h.listeners,
-                    source: h.source,
-                });
-            }
-        }
-        else if (app.runtime?.hooks) {
-            const hookMap = app.runtime.hooks;
-            for (const [slotName, hookValue] of Object.entries(hookMap)) {
-                if (!hookValue || typeof hookValue !== "object")
-                    continue;
-                const h = hookValue;
-                const counts = typeof h.stepCounts === "function" ? h.stepCounts() : { chain: 0, listeners: 0 };
-                out.hooks.push({
-                    id: h.id ?? slotName,
-                    name: slotName,
-                    chain: counts.chain,
-                    listeners: counts.listeners,
-                });
-            }
-        }
-    }
-    // ── Routes (from passed-in interfaces) ────────────────────────────
-    for (const iface of options.interfaces ?? []) {
-        for (const r of iface.listRoutes?.() ?? []) {
-            out.routes.push({ method: r.method, path: r.path, action: r.action });
-        }
-    }
-    // ── Resolver mounts (operator-supplied) ──────────────────────────
-    for (const m of options.mounts ?? []) {
-        out.resolvers.push({ name: m.resolverName, app: "" });
-    }
-    // ── Resources / errors / middleware (operator-supplied) ──────────
-    for (const r of options.resources ?? []) {
-        if ("definition" in r) {
-            const def = r.definition;
-            out.resources.push({
-                name: String(def?.name ?? ""),
-                app: r.app,
-                module: r.module,
-                source: sourceOf(def),
-            });
-        }
-    }
-    for (const e of options.errors ?? []) {
-        if ("definition" in e) {
-            const def = e.definition;
-            out.errors.push({
-                code: String(def?.code ?? ""),
-                app: e.app,
-                module: e.module,
-                source: sourceOf(def),
-            });
-        }
-    }
-    for (const m of options.middleware ?? []) {
-        if ("definition" in m) {
-            out.middleware.push({ name: m.definition.name, where: m.where });
-        }
-        else {
-            out.middleware.push({ name: m.name });
-        }
-    }
-    return out;
-}
-export async function writeCache(cache, dir) {
-    await mkdir(dir, { recursive: true });
-    await writeFile(resolve(dir, "manifest.json"), JSON.stringify(cache, null, 2));
-}
+// ─── Build-time manifest (static AST extract) ──────────────────────────
+// The graph without a boot. The runtime scan above stays for now; the
+// equivalence harness proves they match.
+export { buildManifest, writeManifest, readManifest, collectSourceFiles, MANIFEST_VERSION, } from "./manifest.js";
+export { extractFromFiles, collectConfigModules, } from "./ast-extract.js";
+export { captureTopology, } from "./topology.js";
+export { buildGraph, } from "./graph.js";
+export { listTelemetryRuns, readTelemetryRun } from "./telemetry-runs.js";

package/dist/telemetry-runs.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Disk readers for past telemetry runs — the `.nwire/telemetry/*.jsonl` files
+ * the telemetry reporter writes per run.
+ *
+ * These live in `@nwire/scan` because both Studio (the standalone Vite
+ * middleware) and the `nwire` CLI's one-Vite dev host need to serve telemetry
+ * history off disk, and both already depend on `@nwire/scan`. Keeping the reader
+ * here avoids a UI-package → CLI import edge (the CLI must never depend on
+ * `@nwire/studio`) and avoids duplicating the parse/guard logic in two places.
+ *
+ * All functions are synchronous, side-effect-free beyond filesystem reads, and
+ * take an explicit project `cwd` so callers can target any root without touching
+ * process state.
+ */
+/** One entry from the telemetry run list — id, byte size, and last-modified. */
+export interface TelemetryRunMeta {
+    readonly id: string;
+    readonly size: number;
+    readonly mtime: string;
+}
+/**
+ * List `.nwire/telemetry/*.jsonl` files for a project, newest first.
+ *
+ * Entry ids are the bare filename minus the `.jsonl` extension. Run ids are
+ * ISO-timestamp-prefixed by the telemetry reporter, so lexical descending order
+ * is chronological descending order. Missing dir or unreadable entries degrade
+ * to an empty list rather than throwing.
+ */
+export declare function listTelemetryRuns(cwd: string): TelemetryRunMeta[];
+/**
+ * Read `.nwire/telemetry/<runId>.jsonl` and return each line parsed as JSON.
+ *
+ * Security: `runId` must not contain path separators or `..` — the function
+ * returns an empty array for any id that fails this check. Blank lines and lines
+ * that are not valid JSON are silently skipped.
+ */
+export declare function readTelemetryRun(cwd: string, runId: string): unknown[];