@nwire/scan 0.9.2 → 0.10.0

package/dist/scan.d.ts

@@ -1,403 +1,162 @@
 /**
- * `@nwire/scan` — walks `AppDefinition[]` and produces the `.nwire/` cache.
+ * `@nwire/scan` — produces the `.nwire/` cache by inspecting booted apps.
  *
- * The framework's static-reflection layer: every action/event/actor/
- * projection/query/route plus the cross-module event graph emitted as
- * JSON. Studio reads it; the CLI reads it; codegen reads it. Rebuilt
- * from scratch on each invocation (a few ms for hundreds of definitions).
+ * Each input must be a `ForgeApp` (or any object exposing `appName`,
+ * `dispatcher()`, `container`, `runtime`). The scanner walks the
+ * dispatcher metadata maps to collect actions, actors, projections,
+ * queries, workflows, and external calls, and reads `container.list()`
+ * for DI bindings + `runtime.listHooks()` for hooks.
  *
- * See: architecture-sketch.html §05 (Tooling).
- */
-import { zodToJsonSchema } from "./zod-to-json.js";
-import type * as forge from "@nwire/forge";
-/**
- * Source location captured by `captureSourceLocation()` at `defineX` call
- * time. Studio uses it to render `file:line` chips with "open in IDE" links.
+ * Callers are responsible for booting their apps before scanning — the
+ * forge plugin populates the dispatcher during `app.start()`.
  */
 export interface SourceLocationEntry {
     readonly file: string;
-    readonly line: number;
+    readonly line?: number;
     readonly column?: number;
 }
 export interface ActionEntry {
     readonly name: string;
-    readonly description?: string;
-    readonly module: string;
     readonly app: string;
-    readonly schema: object;
-    readonly retry?: object;
-    readonly policy?: string | readonly string[];
-    readonly hasInlineHandler: boolean;
-    readonly emits: readonly string[];
-    /** True when the module's manifest marked this action `.public()`. */
+    readonly module?: string;
     readonly public: boolean;
-    /** Studio-aware metadata (all optional). */
-    readonly persona?: string;
-    readonly journeyStep?: string;
-    readonly capability?: string;
-    readonly slo?: {
-        readonly p95LatencyMs?: number;
-        readonly successRate?: number;
-    };
-    readonly tags?: readonly string[];
+    readonly inputSchema?: unknown;
     readonly source?: SourceLocationEntry;
 }
 export interface ExternalCallEntry {
     readonly name: string;
-    readonly description?: string;
-    readonly module: string;
     readonly app: string;
-    readonly target: {
-        provider: string;
-        endpoint: string;
-        region?: string;
-    };
-    readonly request: object;
-    readonly response?: object;
-    readonly hasIdempotencyKey: boolean;
-    readonly slo?: {
-        p95LatencyMs?: number;
-        successRate?: number;
-    };
-    readonly retry?: {
-        max: number;
-        backoff?: string;
-    };
-    readonly tags?: readonly string[];
+    readonly source?: SourceLocationEntry;
 }
 export interface InboundWebhookEntry {
     readonly name: string;
-    readonly description?: string;
-    readonly module: string;
     readonly app: string;
-    readonly source: string;
-    readonly path: string;
-    readonly hasSignatureVerifier: boolean;
-    readonly dedupe?: {
-        window: string;
-    };
-    readonly discriminator: string;
-    /** Map of discriminator value → action name. */
-    readonly routes: Readonly<Record<string, string>>;
-    readonly tags?: readonly string[];
+    readonly source?: SourceLocationEntry;
 }
 export interface OutboxEntry {
     readonly name: string;
-    readonly description?: string;
-    readonly module: string;
     readonly app: string;
-    readonly publishes: readonly string[];
-    readonly flushIntervalMs: number;
-    readonly maxBatch: number;
-    readonly tags?: readonly string[];
+    readonly source?: SourceLocationEntry;
 }
 export interface InboxEntry {
     readonly name: string;
-    readonly description?: string;
-    readonly module: string;
     readonly app: string;
-    readonly window: string;
-    readonly on: readonly string[];
-    readonly tags?: readonly string[];
+    readonly source?: SourceLocationEntry;
 }
 export interface CronEntry {
     readonly name: string;
-    readonly description?: string;
-    readonly module: string;
     readonly app: string;
     readonly schedule: string;
-    readonly dispatches: string;
-    readonly timezone?: string;
-    readonly tags?: readonly string[];
+    readonly source?: SourceLocationEntry;
 }
-/**
- * Operator-script command (`defineCommand` from `@nwire/please`). Commands
- * live at the app composition layer (not inside modules) — they're imperative
- * scripts the team triggers by hand, not domain intent the system processes.
- * Studio's CLI page consumes this entry to surface "what can ops run?".
- */
 export interface CommandEntry {
     readonly name: string;
-    readonly describe?: string;
     readonly app: string;
-    readonly hasArgsSchema: boolean;
     readonly source?: SourceLocationEntry;
 }
 export interface WorkflowEntry {
-    /** The workflow name (`defineWorkflow("on-wash-complete", …)`). */
     readonly name: string;
-    /** The bounded context (module) that owns this workflow. */
-    readonly module: string;
     readonly app: string;
-    /** Free-form description from `options.description`. */
-    readonly description?: string;
-    /** Every event this workflow declares an `on(...)` for. */
-    readonly subscribesTo: readonly string[];
-    /** Every action this workflow declares it dispatches (via `opts.dispatches`). */
-    readonly dispatches: readonly string[];
-    /** True when the module's manifest marked this workflow `.public()`. */
     readonly public: boolean;
     readonly source?: SourceLocationEntry;
 }
 export interface EventEntry {
     readonly name: string;
-    readonly description?: string;
-    readonly module: string;
     readonly app: string;
-    readonly visibility: "public" | "internal";
-    /**
-     * True when the module's manifest marked this event `.public()`. Distinct
-     * from `visibility` (which the event definition itself may declare for
-     * back-compat) — `public` reflects the canonical module-level decision.
-     */
     readonly public: boolean;
-    readonly schema: object;
-    /** Studio-aware metadata. */
-    readonly outcome?: "success" | "failure" | "milestone" | "warning";
-    readonly businessWeight?: number;
-    readonly audience?: readonly string[];
     readonly source?: SourceLocationEntry;
 }
 export interface ActorEntry {
     readonly name: string;
-    readonly module: string;
     readonly app: string;
-    readonly key: string;
-    readonly initial: string;
-    readonly states: ReadonlyArray<{
-        readonly name: string;
-        readonly final?: boolean;
-        readonly on: ReadonlyArray<{
-            readonly eventName: string;
-            readonly target?: string;
-        }>;
-        readonly after: ReadonlyArray<{
-            readonly timerName: string;
-            readonly action: string;
-            readonly delay: string;
-        }>;
-    }>;
-    readonly methods: readonly string[];
-    readonly schema: object;
-    /** Studio-aware metadata. */
-    readonly stuckThresholds?: Readonly<Record<string, number>>;
-    readonly slas?: Readonly<Record<string, {
-        maxDurationMs: number;
-        escalateTo?: string;
-    }>>;
     readonly source?: SourceLocationEntry;
 }
 export interface ProjectionEntry {
     readonly name: string;
-    readonly module: string;
     readonly app: string;
-    readonly listens: readonly string[];
-    /** Studio-aware metadata. */
-    readonly description?: string;
-    readonly freshness?: {
-        p95MsBehindStream?: number;
-    };
     readonly source?: SourceLocationEntry;
 }
 export interface QueryEntry {
     readonly name: string;
-    readonly description?: string;
-    readonly module: string;
     readonly app: string;
-    /** Backing projection name. Undefined for handler-form queries. */
-    readonly projection?: string;
-    readonly schema: object;
-    /** True when the module's manifest marked this query `.public()`. */
     readonly public: boolean;
-    /** Studio-aware metadata. */
-    readonly slo?: {
-        p95LatencyMs?: number;
-    };
-    readonly cacheable?: boolean;
     readonly source?: SourceLocationEntry;
 }
 export interface ModuleEntry {
     readonly name: string;
     readonly app: string;
-    readonly provides: {
-        readonly events: readonly string[];
-        readonly actions: readonly string[];
-    };
-    readonly needs: {
-        readonly events: readonly string[];
-        readonly externalEvents: readonly string[];
-        readonly actions: readonly string[];
-    };
-    readonly counts: {
-        readonly actions: number;
-        readonly actors: number;
-        readonly projections: number;
-        readonly queries: number;
-        readonly workflows: number;
-        readonly events: number;
-        readonly routes: number;
-    };
-    /** Studio-aware metadata. */
-    readonly description?: string;
-    readonly owners?: readonly string[];
-    readonly journey?: readonly {
-        id: string;
-        label: string;
-        description?: string;
-    }[];
     readonly source?: SourceLocationEntry;
 }
 export interface AppEntry {
     readonly name: string;
     readonly description?: string;
     readonly modules: readonly string[];
-    /** Studio-aware metadata. */
-    readonly tenantModel?: "single" | "per-org" | "per-account" | "per-workspace";
+    readonly tenantModel?: string;
     readonly tenantKey?: string;
 }
 export interface RouteEntry {
     readonly method: string;
     readonly path: string;
-    readonly target?: string;
-    readonly targetKind?: "action" | "query" | "resolver";
-    readonly module?: string;
-    readonly app?: string;
-    /**
-     * Free-form trigger source declared via `RouteBinding.from(source)`.
-     * Studio + observability group routes by it. Undefined when the route
-     * did not declare a source.
-     */
-    readonly source?: string;
+    readonly action?: string;
+    readonly source?: SourceLocationEntry;
 }
-/**
- * Minimal duck-typed shape the scanner reads from `@nwire/http`'s
- * `httpInterface().listRoutes()` (and any compatible transport that
- * exposes the same surface). Kept structural so the scanner doesn't
- * take a hard dep on the http package.
- */
 export interface RouteSource {
-    listRoutes(): ReadonlyArray<{
-        readonly verb: string;
-        readonly path: string;
-        readonly source?: string;
-    }>;
+    listRoutes?(): readonly {
+        method: string;
+        path: string;
+        action?: string;
+    }[];
 }
-/**
- * Interface-layer operation. Each resolver is a typed, transport-agnostic
- * surface — Studio's canonical "what does this app expose?" answer.
- */
 export interface ResolverEntry {
-    readonly operation: string;
-    readonly version: number;
-    readonly status: "draft" | "active" | "deprecated" | "sunset";
-    readonly summary?: string;
-    readonly description?: string;
-    readonly tags?: readonly string[];
+    readonly name: string;
     readonly app: string;
-    /** Transport bindings — verb/path table from httpInterface().wire() + friends. */
-    readonly bindings: ReadonlyArray<{
-        readonly transport: "rest" | "graphql" | "cli";
-        readonly method?: string;
-        readonly path?: string;
-    }>;
-    /** Zod schemas converted to JSON schema. */
-    readonly params?: object;
-    readonly query?: object;
-    readonly body?: object;
-    readonly returns: ReadonlyArray<{
-        readonly status: number;
-        readonly kind: "single" | "list" | "empty";
-    }>;
-    readonly errors: ReadonlyArray<{
-        readonly code: string;
-        readonly status: number;
-    }>;
-    readonly successor?: {
-        readonly operation: string;
-        readonly version: number;
-    };
-    readonly sunsetDate?: string;
+    readonly source?: SourceLocationEntry;
 }
-/**
- * Optional mount table for resolvers. The scanner can't reach into
- * `@nwire/http`'s rest registry (transport-layer dep), so callers pass
- * the mount tuples in. Passing nothing is fine — resolvers will be
- * emitted without verb/path bindings.
- */
 export interface ResolverMount {
-    readonly resolver: any;
-    readonly transport: "rest" | "graphql" | "cli";
-    readonly method?: string;
-    readonly path?: string;
+    readonly verb: string;
+    readonly path: string;
+    readonly resolverName: string;
 }
-/**
- * Resource definition entry — emitted to `.nwire/models.json`. Captures the
- * external-contract data shape (the "M" in MVC; what the API client sees)
- * produced by `defineResource(name, { schema, public, examples, … })`. The
- * scanner collects these from `BuildCacheOptions.resources` because
- * resources are imported by handlers/resolvers and not attached to module
- * manifests — the caller passes them in alongside the apps.
- */
 export interface ResourceEntry {
     readonly name: string;
-    readonly summary?: string;
-    readonly description?: string;
-    /** App attribution (when the caller provided it). */
     readonly app?: string;
-    /** Module attribution (when the caller provided it). */
     readonly module?: string;
-    /** Field paths exposed by the public projection (from `defineResource.public`). */
-    readonly public: readonly string[];
-    /** JSON-Schema of the resource's zod shape. */
-    readonly schema: object;
-    /** Variant names declared via `defineResource.examples`. */
-    readonly exampleVariants: readonly string[];
-    readonly audience?: readonly string[];
     readonly source?: SourceLocationEntry;
 }
-/**
- * Error definition entry — emitted to `.nwire/errors.json`. One row per
- * `defineError({ code, status, summary, … })`. Studio's Errors page lists
- * the full error catalogue; transport adapters cross-reference the codes
- * for OpenAPI / GraphQL error extensions.
- */
 export interface ErrorEntry {
     readonly code: string;
-    readonly status: number;
-    readonly summary: string;
-    readonly description?: string;
     readonly app?: string;
     readonly module?: string;
-    readonly tags?: readonly string[];
     readonly source?: SourceLocationEntry;
 }
-/**
- * Middleware definition entry — emitted to `.nwire/middleware.json`. One
- * row per `defineMiddleware(...)` value the caller passes in. `where`
- * is a free-form label declared by the caller — typically the route
- * group, resolver layer, or interface the middleware applies to (for
- * example `"stations:guard"` or `"auth:authenticate"`). The scanner
- * does not infer it; it round-trips whatever the caller supplies.
- */
 export interface MiddlewareEntry {
     readonly name: string;
-    readonly app?: string;
-    readonly module?: string;
-    /** Caller-supplied label for "where it runs" — see interface docstring. */
     readonly where?: string;
     readonly source?: SourceLocationEntry;
 }
+export interface HookEntry {
+    readonly id: string;
+    readonly name: string;
+    readonly chain: number;
+    readonly listeners: number;
+    readonly source?: SourceLocationEntry;
+}
+export interface PluginEntry {
+    readonly name: string;
+    readonly kind: "plugin" | "module";
+    readonly app: string;
+    readonly source?: SourceLocationEntry;
+}
+export interface DIBindingEntry {
+    readonly name: string;
+    readonly kind: "singleton" | "transient";
+    readonly app: string;
+    readonly source?: SourceLocationEntry;
+}
 export interface EventGraphEdge {
-    readonly event: string;
-    readonly producer: {
-        app: string;
-        module: string;
-    };
-    readonly consumers: ReadonlyArray<{
-        readonly app: string;
-        readonly module: string;
-        readonly via: "workflow" | "projection" | "actor" | "external";
-    }>;
+    readonly from: string;
+    readonly to: string;
+    readonly via: string;
 }
 export interface Cache {
     readonly generatedAt: string;
@@ -427,95 +186,6 @@ export interface Cache {
         readonly events: readonly EventGraphEdge[];
     };
 }
-/**
- * One entry per `hook()` instantiated in this process at scan time. The
- * scanner snapshots `listHooks()` after the consumer's apps have loaded —
- * runtime construction, plugin registration, and module wiring all create
- * hooks during import, so the snapshot covers the full extension surface
- * the running app exposes.
- *
- * Studio's Hooks page consumes this directly; OTel + structured-logging
- * adapters use it to know the name space they're observing.
- */
-export interface HookEntry {
-    readonly id: string;
-    readonly name: string;
-    readonly chain: number;
-    readonly listeners: number;
-    readonly source?: SourceLocationEntry;
-}
-/**
- * One entry per registered plugin OR module. Modules participate in the
- * same lifecycle event surface as plugins (see `App.plugins` docs); the
- * `kind` field distinguishes them so Studio can render each with the
- * right affordances + link.
- */
-export interface PluginEntry {
-    readonly name: string;
-    readonly kind: "plugin" | "module";
-    readonly app: string;
-    readonly source?: SourceLocationEntry;
-}
-/**
- * One row per DI registration visible on the app's container at scan time.
- * Studio's future DI page will render this as a "who registered what?"
- * table — capability factories registered by `createApp` (`execute`,
- * `send`, `useProjection`), plus everything plugins contributed via
- * `provide()`.
- *
- * Captured by walking `app.container.list()` (defensive — older apps may
- * predate the introspection contract; we skip them silently rather than
- * crash the cache build).
- */
-export interface DIBindingEntry {
-    readonly name: string;
-    readonly kind: "singleton" | "transient";
-    readonly app: string;
-    readonly source?: SourceLocationEntry;
-}
-export interface BuildCacheOptions {
-    /**
-     * Resolver mount tuples — pass in from the runtime side (typically
-     * `rest.listMounts()` from `@nwire/http`) so resolvers carry their
-     * verb/path bindings in the cache.
-     */
-    readonly mounts?: readonly ResolverMount[];
-    /**
-     * HTTP interfaces (or anything implementing `RouteSource`) whose
-     * wired routes should be emitted to `.nwire/routes.json`. The
-     * scanner reads `listRoutes()` and stamps each entry with the
-     * optional `.from(source)` label. Pass the same `httpInterface`
-     * the wire boots with.
-     */
-    readonly interfaces?: readonly RouteSource[];
-    /**
-     * Resource definitions (`defineResource(...)`) to emit to
-     * `.nwire/models.json`. Resources live at the interface layer
-     * (imported by handlers + transports), not on module manifests, so
-     * the caller passes them in. Each input is either the bare
-     * definition or a tuple carrying `{ definition, app?, module? }`
-     * attribution for Studio's grouping.
-     */
-    readonly resources?: readonly ResourceInput[];
-    /**
-     * Error definitions (`defineError(...)`) to emit to `.nwire/errors.json`.
-     * Same attribution model as `resources`.
-     */
-    readonly errors?: readonly ErrorInput[];
-    /**
-     * Middleware definitions (`defineMiddleware(...)`) to emit to
-     * `.nwire/middleware.json`. The optional `where` field is a free-form
-     * caller-supplied label (e.g. `"stations:guard"`) describing where the
-     * middleware runs — the scanner round-trips it, doesn't infer it.
-     */
-    readonly middleware?: readonly MiddlewareInput[];
-}
-/**
- * Resource input — accepts the bare definition OR a tagged object that
- * carries app/module attribution. The bare form is the common case
- * (caller imports the resource and drops it in the array); the tagged
- * form is for callers building cache for multiple apps at once.
- */
 export type ResourceInput = {
     readonly $kind: "resource";
 } | {
@@ -535,16 +205,41 @@ export type ErrorInput = {
     readonly module?: string;
 };
 export type MiddlewareInput = {
-    readonly $kind: "middleware";
+    readonly name: string;
 } | {
     readonly definition: {
-        readonly $kind: "middleware";
-    } & Record<string, any>;
-    readonly app?: string;
-    readonly module?: string;
+        readonly name: string;
+    };
     readonly where?: string;
 };
-export declare function buildCache(apps: readonly forge.AppDefinition[], options?: BuildCacheOptions): Cache;
+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;
+    dispatcher?: () => any;
+    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;
+        }[];
+    };
+}
+export declare function buildCache(apps: readonly ScannedApp[], options?: BuildCacheOptions): Cache;
 export declare function writeCache(cache: Cache, dir: string): Promise<void>;
-export { zodToJsonSchema };
-//# sourceMappingURL=scan.d.ts.map
+export {};