@nwire/scan 0.12.1 → 0.13.1

package/dist/ast-extract.js

@@ -0,0 +1,1024 @@
+/**
+ * Static AST discovery (Phase 0) — extract `defineEvent` + `defineAction`
+ * declarations from source WITHOUT booting the app. "Scan the graph, not the
+ * runtime." Uses the TypeScript compiler API (already a `@nwire/scan` dep) to
+ * parse each file; reads name, `.public()`, `emits`, literal metadata, and
+ * source location straight off the AST node positions.
+ *
+ * Runs ALONGSIDE the jiti scanner — the equivalence harness diffs the two
+ * manifests. Anything not statically analyzable (computed name, dynamic
+ * `emits`) is recorded in `unanalyzable`, never silently dropped (plan §2,
+ * Law 2). Covers events, actions, actors, projections, queries, and
+ * workflows (including the workflow closure edge-walk and the projection /
+ * workflow event-graph edges).
+ */
+import { readFileSync } from "node:fs";
+import ts from "typescript";
+function parse(files) {
+    return files.map((file) => ({
+        file,
+        // setParentNodes = true so we can walk up to the enclosing declaration
+        // and detect `.public()` chaining.
+        sf: ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.Latest, true),
+    }));
+}
+function sourceOf(node, sf, file) {
+    const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+    return { file, line: line + 1, column: character + 1 };
+}
+/** A `defineX(...)` call whose callee is the bare identifier `name`. */
+function isDefineCall(node, name) {
+    return (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === name);
+}
+/** Walk every node in a source file. */
+function walk(node, visit) {
+    visit(node);
+    node.forEachChild((c) => walk(c, visit));
+}
+/** `export const Foo = defineX(...)` → "Foo" (the binding the call is assigned to). */
+function bindingName(call) {
+    let n = call;
+    while (n && !ts.isVariableDeclaration(n))
+        n = n.parent;
+    if (n && ts.isVariableDeclaration(n) && ts.isIdentifier(n.name))
+        return n.name.text;
+    return undefined;
+}
+/** True when the call is the receiver of a `.public()` call: `defineX(...).public()`. */
+function isPublic(call) {
+    const parent = call.parent;
+    return (!!parent &&
+        ts.isPropertyAccessExpression(parent) &&
+        parent.name.text === "public" &&
+        ts.isCallExpression(parent.parent) &&
+        parent.parent.expression === parent);
+}
+function configObject(call) {
+    for (const arg of call.arguments) {
+        if (ts.isObjectLiteralExpression(arg))
+            return arg;
+    }
+    return undefined;
+}
+function prop(obj, key) {
+    for (const m of obj.properties) {
+        if (ts.isPropertyAssignment(m) && propName(m.name) === key)
+            return m.initializer;
+        if (ts.isShorthandPropertyAssignment(m) && m.name.text === key)
+            return m.name;
+    }
+    return undefined;
+}
+function propName(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name))
+        return name.text;
+    return undefined;
+}
+function stringLiteral(expr) {
+    if (expr && (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr)))
+        return expr.text;
+    return undefined;
+}
+function stringArray(expr) {
+    if (!expr || !ts.isArrayLiteralExpression(expr))
+        return undefined;
+    const out = [];
+    for (const el of expr.elements) {
+        const s = stringLiteral(el);
+        if (s === undefined)
+            return undefined; // non-literal element → not statically resolvable
+        out.push(s);
+    }
+    return out;
+}
+/** The action's `name`: positional `defineAction("name", {...})` or `{ name: "..." }`. */
+function actionName(call, cfg) {
+    const first = call.arguments[0];
+    if (first && (ts.isStringLiteral(first) || ts.isNoSubstitutionTemplateLiteral(first)))
+        return first.text;
+    return cfg ? stringLiteral(prop(cfg, "name")) : undefined;
+}
+/** True if any state spec in a `states` object literal declares `final: true`. */
+function statesHaveFinal(statesExpr) {
+    if (!statesExpr || !ts.isObjectLiteralExpression(statesExpr))
+        return false;
+    for (const m of statesExpr.properties) {
+        if (!ts.isPropertyAssignment(m) || !ts.isObjectLiteralExpression(m.initializer))
+            continue;
+        const fin = prop(m.initializer, "final");
+        if (fin && fin.kind === ts.SyntaxKind.TrueKeyword)
+            return true;
+    }
+    return false;
+}
+/** Enumerate state-name keys from a `states` object literal; report static gaps. */
+function stateKeysOf(statesExpr) {
+    if (!statesExpr)
+        return { keys: [], unanalyzable: false };
+    if (!ts.isObjectLiteralExpression(statesExpr))
+        return { keys: [], unanalyzable: true };
+    const keys = [];
+    let unanalyzable = false;
+    for (const m of statesExpr.properties) {
+        if (ts.isSpreadAssignment(m)) {
+            unanalyzable = true; // `...baseStates` — can't enumerate
+            continue;
+        }
+        const n = ts.isPropertyAssignment(m) || ts.isShorthandPropertyAssignment(m) || ts.isMethodDeclaration(m)
+            ? m.name
+            : undefined;
+        if (n && (ts.isIdentifier(n) || ts.isStringLiteral(n)))
+            keys.push(n.text);
+        else
+            unanalyzable = true; // computed `[Foo.name]:` not statically resolvable
+    }
+    return { keys, unanalyzable };
+}
+/** Is the call a function-valued arg (arrow or function expression)? */
+function isInlineFn(node) {
+    return !!node && (ts.isArrowFunction(node) || ts.isFunctionExpression(node));
+}
+/** Bare-identifier or `ctx.<verb>` callee → the verb name, else undefined. */
+function calleeVerb(call) {
+    const e = call.expression;
+    if (ts.isIdentifier(e))
+        return e.text;
+    if (ts.isPropertyAccessExpression(e))
+        return e.name.text;
+    return undefined;
+}
+/**
+ * Map the closure's `const { active, retrying } = states` binding identifiers to
+ * their state names (renamed-aware: `{ a: renamed }` → renamed → "a").
+ */
+function stateBindings(closure) {
+    const out = new Map();
+    walk(closure, (n) => {
+        if (!ts.isVariableDeclaration(n) || !n.initializer)
+            return;
+        if (!ts.isIdentifier(n.initializer) || n.initializer.text !== "states")
+            return;
+        if (!ts.isObjectBindingPattern(n.name))
+            return;
+        for (const el of n.name.elements) {
+            if (!ts.isIdentifier(el.name))
+                continue;
+            const stateName = el.propertyName && ts.isIdentifier(el.propertyName) ? el.propertyName.text : el.name.text;
+            out.set(el.name.text, stateName);
+        }
+    });
+    return out;
+}
+/** The state a `when` reaction fn transitions to: its returned state-ref. */
+function returnedState(fn, states) {
+    if (!isInlineFn(fn))
+        return undefined;
+    const asState = (e) => e && ts.isIdentifier(e) && states.has(e.text) ? states.get(e.text) : undefined;
+    if (!ts.isBlock(fn.body))
+        return asState(fn.body); // arrow-expression body
+    let result;
+    walk(fn.body, (n) => {
+        if (ts.isReturnStatement(n) && n.expression) {
+            const s = asState(n.expression);
+            if (s)
+                result = s; // last return wins — good enough for the graph
+        }
+    });
+    return result;
+}
+/**
+ * Walk an actor/workflow builder closure for state→state transitions. Each
+ * `when(Event, reaction)` is an edge: `from` is the enclosing `state(() => …)`
+ * scope (or `"*"` at the closure top = always-active), `on` the event, `to` the
+ * state the reaction returns (or `from` when it stays).
+ */
+function extractTransitions(closure, resolveEvent) {
+    const states = stateBindings(closure);
+    const out = [];
+    walk(closure.body ?? closure, (n) => {
+        if (!ts.isCallExpression(n) || calleeVerb(n) !== "when")
+            return;
+        const on = resolveEvent(n.arguments[0]);
+        if (!on)
+            return;
+        const to = returnedState(n.arguments[1], states);
+        let from = "*";
+        let p = n.parent;
+        while (p && p !== closure) {
+            if (ts.isCallExpression(p) &&
+                ts.isIdentifier(p.expression) &&
+                states.has(p.expression.text)) {
+                from = states.get(p.expression.text);
+                break;
+            }
+            p = p.parent;
+        }
+        out.push({ from, on, to: to ?? from });
+    });
+    return out;
+}
+/**
+ * Pull the English failure message out of a predicate. Predicates are written
+ * as `(i) => cond || "message"` (logical-OR form) or as a block returning a
+ * string literal (`{ if (!ok) return "message"; return true }`). We read the
+ * static string operand of the rightmost `||`, or the first returned string
+ * literal. No static string ⇒ undefined (the rule text is still captured).
+ */
+function invariantMessage(pred) {
+    // `cond || "message"` — possibly chained; the message is the RHS string.
+    const fromOr = (e) => {
+        if (ts.isBinaryExpression(e) && e.operatorToken.kind === ts.SyntaxKind.BarBarToken) {
+            const rhs = stringLiteral(e.right);
+            if (rhs !== undefined)
+                return rhs;
+            return fromOr(e.left);
+        }
+        return stringLiteral(e);
+    };
+    if (isInlineFn(pred)) {
+        const body = pred.body;
+        if (ts.isBlock(body)) {
+            // First `return "message"` in the block body.
+            let msg;
+            walk(body, (n) => {
+                if (msg !== undefined)
+                    return;
+                if (ts.isReturnStatement(n) && n.expression) {
+                    const lit = stringLiteral(n.expression);
+                    if (lit !== undefined)
+                        msg = lit;
+                }
+            });
+            return msg;
+        }
+        // Expression-bodied arrow: `(i) => cond || "message"`.
+        return fromOr(body);
+    }
+    // Bare expression predicate (rare) — try the OR form directly.
+    return fromOr(pred);
+}
+/**
+ * Walk a handler/method body for `validate(input, [preds], state?)` calls and
+ * capture each predicate as a business-rule invariant: its source text plus the
+ * English failure message when one is statically present. Predicates with no
+ * static string are still recorded (rule only).
+ */
+function extractInvariants(body) {
+    const out = [];
+    walk(body, (n) => {
+        if (!ts.isCallExpression(n) || calleeVerb(n) !== "validate")
+            return;
+        const predsArg = n.arguments[1];
+        if (!predsArg || !ts.isArrayLiteralExpression(predsArg))
+            return;
+        for (const el of predsArg.elements) {
+            if (ts.isSpreadElement(el))
+                continue;
+            const rule = el.getText();
+            const message = invariantMessage(el);
+            out.push(message !== undefined ? { rule, message } : { rule });
+        }
+    });
+    return out;
+}
+/**
+ * Walk a source file for environment reads and collect the variable names:
+ *   - `process.env.FOO` (member access) and `process.env["FOO"]` (element access)
+ *   - `env.get("FOO")` / `env("FOO")` (config-helper style, when present)
+ * Names that aren't a static identifier/string (computed `process.env[key]`) are
+ * skipped — only statically resolvable variable names are surfaced.
+ */
+function extractEnvReads(sf, into) {
+    walk(sf, (n) => {
+        // process.env.FOO  →  PropertyAccess( PropertyAccess(process, env), FOO )
+        if (ts.isPropertyAccessExpression(n) && isProcessEnv(n.expression)) {
+            into.add(n.name.text);
+            return;
+        }
+        // process.env["FOO"]  →  ElementAccess( PropertyAccess(process, env), "FOO" )
+        if (ts.isElementAccessExpression(n) && isProcessEnv(n.expression)) {
+            const key = stringLiteral(n.argumentExpression);
+            if (key !== undefined)
+                into.add(key);
+            return;
+        }
+        // env.get("FOO")  /  env("FOO")
+        if (ts.isCallExpression(n)) {
+            const callee = n.expression;
+            const isEnvGet = ts.isPropertyAccessExpression(callee) &&
+                ts.isIdentifier(callee.expression) &&
+                callee.expression.text === "env" &&
+                callee.name.text === "get";
+            const isEnvCall = ts.isIdentifier(callee) && callee.text === "env";
+            if (isEnvGet || isEnvCall) {
+                const key = stringLiteral(n.arguments[0]);
+                if (key !== undefined)
+                    into.add(key);
+            }
+        }
+    });
+}
+/** True for the `process.env` member-access node. */
+function isProcessEnv(node) {
+    return (ts.isPropertyAccessExpression(node) &&
+        ts.isIdentifier(node.expression) &&
+        node.expression.text === "process" &&
+        node.name.text === "env");
+}
+/**
+ * Best-effort top-level config field names from a `config/*.ts` module: the keys
+ * of a `export default { … }` object literal, plus any named exports
+ * (`export const X` / `export { X }`). De-duped, declaration order preserved.
+ */
+function extractConfigKeys(sf) {
+    const keys = [];
+    const seen = new Set();
+    const add = (k) => {
+        if (k && !seen.has(k)) {
+            seen.add(k);
+            keys.push(k);
+        }
+    };
+    // Top-level `const x = { … }` declarations, so `export default x` resolves.
+    const objByBinding = new Map();
+    for (const stmt of sf.statements) {
+        if (!ts.isVariableStatement(stmt))
+            continue;
+        for (const d of stmt.declarationList.declarations) {
+            if (ts.isIdentifier(d.name) && d.initializer) {
+                const obj = unwrapObject(d.initializer);
+                if (obj)
+                    objByBinding.set(d.name.text, obj);
+            }
+        }
+    }
+    walk(sf, (n) => {
+        // export default { a, b, c }  /  export default cfg  (cfg = { … })
+        if (ts.isExportAssignment(n) && !n.isExportEquals) {
+            const obj = unwrapObject(n.expression) ??
+                (ts.isIdentifier(n.expression) ? objByBinding.get(n.expression.text) : undefined);
+            if (obj)
+                for (const m of obj.properties)
+                    add(memberKey(m));
+            return;
+        }
+        // export const X = …  /  export function X  /  export class X
+        if ((ts.isVariableStatement(n) || ts.isFunctionDeclaration(n) || ts.isClassDeclaration(n)) &&
+            ts.getModifiers(n)?.some((mod) => mod.kind === ts.SyntaxKind.ExportKeyword)) {
+            if (ts.isVariableStatement(n)) {
+                for (const d of n.declarationList.declarations)
+                    if (ts.isIdentifier(d.name))
+                        add(d.name.text);
+            }
+            else if (n.name && ts.isIdentifier(n.name)) {
+                add(n.name.text);
+            }
+            return;
+        }
+        // export { X, Y as Z }
+        if (ts.isExportDeclaration(n) && n.exportClause && ts.isNamedExports(n.exportClause)) {
+            for (const el of n.exportClause.elements)
+                add(el.name.text);
+        }
+    });
+    return keys;
+}
+/** Unwrap an object literal, looking through `satisfies` / `as` wrappers. */
+function unwrapObject(expr) {
+    let e = expr;
+    while (ts.isAsExpression(e) || ts.isSatisfiesExpression(e))
+        e = e.expression;
+    return ts.isObjectLiteralExpression(e) ? e : undefined;
+}
+/** A property's key name, when it's a plain identifier/string (not computed/spread). */
+function memberKey(m) {
+    if (ts.isSpreadAssignment(m))
+        return undefined;
+    const name = ts.isPropertyAssignment(m) || ts.isShorthandPropertyAssignment(m) || ts.isMethodDeclaration(m)
+        ? m.name
+        : undefined;
+    if (name && (ts.isIdentifier(name) || ts.isStringLiteral(name)))
+        return name.text;
+    return undefined;
+}
+/** Walk a body for `externalCall(X)` / `ctx.externalCall(X)` → external-call names. */
+function extractCalls(body, callNameByBinding) {
+    const out = new Set();
+    walk(body, (n) => {
+        if (!ts.isCallExpression(n) || calleeVerb(n) !== "externalCall")
+            return;
+        const arg = n.arguments[0];
+        if (arg && ts.isIdentifier(arg) && callNameByBinding.has(arg.text))
+            out.add(callNameByBinding.get(arg.text));
+        else {
+            const lit = stringLiteral(arg);
+            if (lit !== undefined)
+                out.add(lit);
+        }
+    });
+    return [...out];
+}
+/**
+ * Extract `defineEvent` + `defineAction` from a set of source files. Two
+ * passes: events first (so `emits` identifiers can resolve to event names),
+ * then actions.
+ */
+export function extractFromFiles(files, app = "") {
+    const parsed = parse(files);
+    const events = [];
+    const actions = [];
+    const actors = [];
+    const projections = [];
+    const queries = [];
+    const workflows = [];
+    const commands = [];
+    const crons = [];
+    const externalCalls = [];
+    const inboundWebhooks = [];
+    const outboxes = [];
+    const inboxes = [];
+    const resources = [];
+    const errors = [];
+    const schemas = [];
+    const unanalyzable = [];
+    const graphEvents = [];
+    const envReads = new Set();
+    // ── Env reads — every `process.env.X` / `env.get("X")` across the source. ──
+    for (const { sf } of parsed)
+        extractEnvReads(sf, envReads);
+    // binding identifier → name, for cross-resolving refs. File-set-global,
+    // keyed by local binding text (mirrors the cross-file behaviour the
+    // examples rely on: events/actions/projections are imported by binding).
+    const eventNameByBinding = new Map();
+    const actionNameByBinding = new Map();
+    const projectionNameByBinding = new Map();
+    const externalCallNameByBinding = new Map();
+    // binding identifier → defineSchema identity, for actor state resolution.
+    const schemaByBinding = new Map();
+    // ── Pass 0: schemas (states + name) for actor resolution + schema entries ──
+    for (const { file, sf } of parsed) {
+        walk(sf, (node) => {
+            if (!isDefineCall(node, "defineSchema"))
+                return;
+            const src = sourceOf(node, sf, file);
+            const cfg = configObject(node);
+            const name = cfg ? stringLiteral(prop(cfg, "name")) : undefined;
+            const statesExpr = cfg ? prop(cfg, "states") : undefined;
+            const { keys, unanalyzable: statesUnanalyzable } = stateKeysOf(statesExpr);
+            const binding = bindingName(node);
+            if (binding)
+                schemaByBinding.set(binding, {
+                    name,
+                    stateNames: keys,
+                    statesUnanalyzable,
+                    hasFinal: statesHaveFinal(statesExpr),
+                });
+            if (name)
+                schemas.push({
+                    name,
+                    app,
+                    key: cfg ? stringLiteral(prop(cfg, "key")) : undefined,
+                    states: keys,
+                    source: src,
+                });
+            else
+                unanalyzable.push({
+                    kind: "schema",
+                    reason: "non-literal or missing schema name",
+                    source: src,
+                });
+        });
+    }
+    // ── Pass 0b: leaf primitives (name + source) — commands / crons /
+    // external calls / inbound webhooks / outboxes / inboxes / resources /
+    // errors. Each is `defineX("name", …)` or `defineX({ name|code|schedule })`.
+    for (const { file, sf } of parsed) {
+        walk(sf, (node) => {
+            if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression))
+                return;
+            const callee = node.expression.text;
+            const src = sourceOf(node, sf, file);
+            const cfg = configObject(node);
+            const push = (
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            list, kind, extra = {}) => {
+                const name = actionName(node, cfg); // first string arg OR cfg.name
+                if (name)
+                    list.push({ name, app, source: src, ...extra });
+                else
+                    unanalyzable.push({ kind, reason: `non-literal or missing ${kind} name`, source: src });
+            };
+            switch (callee) {
+                case "defineCommand":
+                    push(commands, "command");
+                    break;
+                case "defineCron":
+                    push(crons, "cron", { schedule: (cfg && stringLiteral(prop(cfg, "schedule"))) ?? "" });
+                    break;
+                case "defineExternalCall": {
+                    push(externalCalls, "externalCall");
+                    const b = bindingName(node);
+                    const nm = actionName(node, cfg);
+                    if (b && nm)
+                        externalCallNameByBinding.set(b, nm);
+                    break;
+                }
+                case "defineInboundWebhook":
+                    push(inboundWebhooks, "inboundWebhook");
+                    break;
+                case "defineOutbox":
+                    push(outboxes, "outbox");
+                    break;
+                case "defineInbox":
+                    push(inboxes, "inbox");
+                    break;
+                case "defineResource":
+                    push(resources, "resource");
+                    break;
+                case "defineError": {
+                    const code = (cfg && stringLiteral(prop(cfg, "code"))) ?? stringLiteral(node.arguments[0]);
+                    if (code)
+                        errors.push({ code, app, source: src });
+                    else
+                        unanalyzable.push({
+                            kind: "error",
+                            reason: "non-literal or missing error code",
+                            source: src,
+                        });
+                    break;
+                }
+                default:
+                    break;
+            }
+        });
+    }
+    // ── Pass 1: events ──
+    for (const { file, sf } of parsed) {
+        walk(sf, (node) => {
+            if (!isDefineCall(node, "defineEvent"))
+                return;
+            const src = sourceOf(node, sf, file);
+            const cfg = configObject(node);
+            const name = cfg ? stringLiteral(prop(cfg, "name")) : undefined;
+            if (!name) {
+                unanalyzable.push({
+                    kind: "event",
+                    reason: "non-literal or missing event name",
+                    source: src,
+                });
+                return;
+            }
+            const binding = bindingName(node);
+            if (binding)
+                eventNameByBinding.set(binding, name);
+            events.push({
+                name,
+                app,
+                public: isPublic(node),
+                description: cfg ? stringLiteral(prop(cfg, "description")) : undefined,
+                audience: (cfg && stringArray(prop(cfg, "audience"))) || undefined,
+                source: src,
+            });
+        });
+    }
+    // ── Pass 2: actions ──
+    for (const { file, sf } of parsed) {
+        walk(sf, (node) => {
+            if (!isDefineCall(node, "defineAction"))
+                return;
+            const src = sourceOf(node, sf, file);
+            const cfg = configObject(node);
+            const name = actionName(node, cfg);
+            if (!name) {
+                unanalyzable.push({
+                    kind: "action",
+                    reason: "non-literal or missing action name",
+                    source: src,
+                });
+                return;
+            }
+            const actionBinding = bindingName(node);
+            if (actionBinding)
+                actionNameByBinding.set(actionBinding, name);
+            // emits: array of event references → resolve each binding to its name.
+            const emits = [];
+            const emitsExpr = cfg ? prop(cfg, "emits") : undefined;
+            if (emitsExpr) {
+                if (ts.isArrayLiteralExpression(emitsExpr)) {
+                    for (const el of emitsExpr.elements) {
+                        if (ts.isIdentifier(el) && eventNameByBinding.has(el.text)) {
+                            emits.push(eventNameByBinding.get(el.text));
+                        }
+                        else {
+                            const lit = stringLiteral(el);
+                            if (lit !== undefined)
+                                emits.push(lit);
+                            else
+                                unanalyzable.push({
+                                    kind: "action",
+                                    reason: `action "${name}" emits a reference not statically resolvable to an event name`,
+                                    source: src,
+                                });
+                        }
+                    }
+                }
+                else {
+                    unanalyzable.push({
+                        kind: "action",
+                        reason: `action "${name}" has a non-array \`emits\``,
+                        source: src,
+                    });
+                }
+            }
+            const retryExpr = cfg ? prop(cfg, "retry") : undefined;
+            let retry;
+            if (retryExpr && ts.isObjectLiteralExpression(retryExpr)) {
+                const maxExpr = prop(retryExpr, "max");
+                const max = maxExpr && ts.isNumericLiteral(maxExpr) ? Number(maxExpr.text) : undefined;
+                if (max !== undefined)
+                    retry = { max };
+            }
+            const handlerExpr = cfg ? prop(cfg, "handler") : undefined;
+            const calls = handlerExpr ? extractCalls(handlerExpr, externalCallNameByBinding) : [];
+            const invariants = handlerExpr ? extractInvariants(handlerExpr) : [];
+            actions.push({
+                name,
+                app,
+                description: cfg ? stringLiteral(prop(cfg, "description")) : undefined,
+                public: isPublic(node),
+                emits,
+                calls: calls.length ? calls : undefined,
+                invariants: invariants.length ? invariants : undefined,
+                hasInlineHandler: !!handlerExpr,
+                persona: cfg ? stringLiteral(prop(cfg, "persona")) : undefined,
+                journeyStep: cfg ? stringLiteral(prop(cfg, "journeyStep")) : undefined,
+                capability: cfg ? stringLiteral(prop(cfg, "capability")) : undefined,
+                retry,
+                tags: (cfg && stringArray(prop(cfg, "tags"))) || undefined,
+                source: src,
+            });
+        });
+    }
+    // ── Pass 3: projections ──
+    // After events so `listens`/`on` refs resolve. Records the projection
+    // binding so queries (pass 5) can map a projection ref → its name.
+    for (const { file, sf } of parsed) {
+        walk(sf, (node) => {
+            if (!isDefineCall(node, "defineProjection"))
+                return;
+            const src = sourceOf(node, sf, file);
+            const name = stringLiteral(node.arguments[0]);
+            if (!name) {
+                unanalyzable.push({
+                    kind: "projection",
+                    reason: "non-literal or missing projection name",
+                    source: src,
+                });
+                return;
+            }
+            const binding = bindingName(node);
+            if (binding)
+                projectionNameByBinding.set(binding, name);
+            // Builder closure (arg 1) + options object (first object literal at arg ≥ 2).
+            const closure = node.arguments[1];
+            let opts;
+            for (let i = 2; i < node.arguments.length; i++) {
+                const a = node.arguments[i];
+                if (ts.isObjectLiteralExpression(a)) {
+                    opts = a;
+                    break;
+                }
+            }
+            // listens: derived from the `when(Event, reducer)` calls in the closure.
+            const listens = [];
+            if (isInlineFn(closure)) {
+                walk(closure.body ?? closure, (n) => {
+                    if (!ts.isCallExpression(n) || calleeVerb(n) !== "when")
+                        return;
+                    const arg = n.arguments[0];
+                    if (arg && ts.isIdentifier(arg) && eventNameByBinding.has(arg.text)) {
+                        listens.push(eventNameByBinding.get(arg.text));
+                        return;
+                    }
+                    const lit = stringLiteral(arg);
+                    if (lit !== undefined)
+                        listens.push(lit);
+                    else
+                        unanalyzable.push({
+                            kind: "projection",
+                            reason: `projection "${name}" when()s an event reference not statically resolvable to a name`,
+                            source: src,
+                        });
+                });
+            }
+            else {
+                unanalyzable.push({
+                    kind: "projection",
+                    reason: `projection "${name}" builder is not an inline function`,
+                    source: src,
+                });
+            }
+            projections.push({
+                name,
+                app,
+                description: opts ? stringLiteral(prop(opts, "description")) : undefined,
+                listens,
+                source: src,
+            });
+            for (const evName of listens)
+                graphEvents.push({ from: evName, to: name, via: "folds" });
+        });
+    }
+    // ── Pass 4: actors ──
+    // One shape: defineActor("name", (ctx) => {...}, { schema: SchemaRef, ... }).
+    // States come from the referenced schema (+ an injected `deleted` terminal
+    // when the schema declares no `final`, matching the runtime).
+    for (const { file, sf } of parsed) {
+        walk(sf, (node) => {
+            if (!isDefineCall(node, "defineActor"))
+                return;
+            const src = sourceOf(node, sf, file);
+            const [arg0, arg1, arg2] = node.arguments;
+            if (node.arguments.some((a) => ts.isSpreadElement(a))) {
+                unanalyzable.push({
+                    kind: "actor",
+                    reason: "defineActor called with spread or non-literal args",
+                    source: src,
+                });
+                return;
+            }
+            const name = stringLiteral(arg0);
+            if (!name || !isInlineFn(arg1)) {
+                unanalyzable.push({
+                    kind: "actor",
+                    reason: "defineActor: expected (name, closure, { schema }) with a literal name + inline closure",
+                    source: src,
+                });
+                return;
+            }
+            const opts = arg2 && ts.isObjectLiteralExpression(arg2) ? arg2 : undefined;
+            const schemaRef = opts ? prop(opts, "schema") : undefined;
+            const info = schemaRef && ts.isIdentifier(schemaRef) ? schemaByBinding.get(schemaRef.text) : undefined;
+            if (!info) {
+                unanalyzable.push({
+                    kind: "actor",
+                    reason: `actor "${name}" borrows states from an unresolved schema reference`,
+                    source: src,
+                });
+                actors.push({ name, app, states: [], source: src });
+                return;
+            }
+            if (info.statesUnanalyzable) {
+                unanalyzable.push({
+                    kind: "actor",
+                    reason: `actor "${name}" borrows states from a schema whose \`states\` is not statically analyzable`,
+                    source: src,
+                });
+            }
+            // Runtime injects a `deleted` terminal when the schema has no `final`.
+            const states = info.hasFinal ? info.stateNames : [...info.stateNames, "deleted"];
+            const resolveActorEvent = (e) => e && ts.isIdentifier(e) && eventNameByBinding.has(e.text)
+                ? eventNameByBinding.get(e.text)
+                : stringLiteral(e);
+            const transitions = isInlineFn(arg1) ? extractTransitions(arg1, resolveActorEvent) : [];
+            const actorInvariants = isInlineFn(arg1) ? extractInvariants(arg1) : [];
+            actors.push({
+                name,
+                app,
+                states,
+                transitions: transitions.length ? transitions : undefined,
+                invariants: actorInvariants.length ? actorInvariants : undefined,
+                source: src,
+            });
+        });
+    }
+    // ── Pass 5: queries ──
+    // After projections so a projection-form query's first arg resolves.
+    for (const { file, sf } of parsed) {
+        walk(sf, (node) => {
+            if (!isDefineCall(node, "defineQuery"))
+                return;
+            const src = sourceOf(node, sf, file);
+            const cfg = configObject(node);
+            const name = cfg ? stringLiteral(prop(cfg, "name")) : undefined;
+            if (!name) {
+                unanalyzable.push({
+                    kind: "query",
+                    reason: "non-literal or missing query name",
+                    source: src,
+                });
+                return;
+            }
+            const isPublicQ = isPublic(node);
+            // Two args ⇒ projection form; the projection ref is arg[0].
+            let projection;
+            if (node.arguments.length >= 2) {
+                const ref = node.arguments[0];
+                if (ts.isIdentifier(ref) && projectionNameByBinding.has(ref.text)) {
+                    projection = projectionNameByBinding.get(ref.text);
+                }
+                else {
+                    unanalyzable.push({
+                        kind: "query",
+                        reason: `query "${name}" references a projection not statically resolvable to a name`,
+                        source: src,
+                    });
+                }
+            }
+            const entry = projection !== undefined
+                ? { name, app, public: isPublicQ, projection, source: src }
+                : { name, app, public: isPublicQ, source: src };
+            queries.push(entry);
+        });
+    }
+    // ── Pass 6: workflows ──
+    // Closure edge-walk: when/on(Event) → subscribesTo, send/enqueue/execute(Action)
+    // → dispatches. Uses event + action binding maps for ref resolution.
+    for (const { file, sf } of parsed) {
+        walk(sf, (node) => {
+            if (!isDefineCall(node, "defineWorkflow"))
+                return;
+            const src = sourceOf(node, sf, file);
+            const name = stringLiteral(node.arguments[0]);
+            if (!name) {
+                unanalyzable.push({
+                    kind: "workflow",
+                    reason: "non-literal or missing workflow name",
+                    source: src,
+                });
+                return;
+            }
+            const closure = node.arguments[1];
+            if (!isInlineFn(closure)) {
+                unanalyzable.push({
+                    kind: "workflow",
+                    reason: `workflow "${name}" closure is not an inline function`,
+                    source: src,
+                });
+                // Still emit the workflow entry — name + public + description are known.
+            }
+            // Options object: first object literal at arg index ≥ 2 (skip the closure).
+            let opts;
+            for (let i = 2; i < node.arguments.length; i++) {
+                const a = node.arguments[i];
+                if (ts.isObjectLiteralExpression(a)) {
+                    opts = a;
+                    break;
+                }
+            }
+            const description = opts ? stringLiteral(prop(opts, "description")) : undefined;
+            const subscribesTo = new Set();
+            const dispatches = new Set();
+            let transitions = [];
+            let calls = [];
+            if (isInlineFn(closure)) {
+                // Local `const t = timeout("name", ...)` declarations → timer-event names.
+                const timerNameByBinding = new Map();
+                walk(closure.body ?? closure, (n) => {
+                    if (!ts.isVariableDeclaration(n) || !n.initializer)
+                        return;
+                    if (!ts.isCallExpression(n.initializer))
+                        return;
+                    if (calleeVerb(n.initializer) !== "timeout")
+                        return;
+                    if (!ts.isIdentifier(n.name))
+                        return;
+                    const timerName = stringLiteral(n.initializer.arguments[0]);
+                    if (timerName !== undefined)
+                        timerNameByBinding.set(n.name.text, timerName);
+                });
+                const resolveEvent = (arg) => {
+                    if (!arg)
+                        return;
+                    if (ts.isIdentifier(arg)) {
+                        if (eventNameByBinding.has(arg.text)) {
+                            subscribesTo.add(eventNameByBinding.get(arg.text));
+                            return;
+                        }
+                        if (timerNameByBinding.has(arg.text)) {
+                            subscribesTo.add(`__nwire/timer/${name}/${timerNameByBinding.get(arg.text)}`);
+                            return;
+                        }
+                    }
+                    const lit = stringLiteral(arg);
+                    if (lit !== undefined) {
+                        subscribesTo.add(lit);
+                        return;
+                    }
+                    unanalyzable.push({
+                        kind: "workflow",
+                        reason: `workflow "${name}" subscribes to an event reference not statically resolvable to a name`,
+                        source: src,
+                    });
+                };
+                const resolveAction = (arg) => {
+                    if (!arg)
+                        return;
+                    if (ts.isIdentifier(arg) && actionNameByBinding.has(arg.text)) {
+                        dispatches.add(actionNameByBinding.get(arg.text));
+                        return;
+                    }
+                    const lit = stringLiteral(arg);
+                    if (lit !== undefined) {
+                        dispatches.add(lit);
+                        return;
+                    }
+                    unanalyzable.push({
+                        kind: "workflow",
+                        reason: `workflow "${name}" dispatches an action reference not statically resolvable to a name`,
+                        source: src,
+                    });
+                };
+                walk(closure.body ?? closure, (n) => {
+                    if (!ts.isCallExpression(n))
+                        return;
+                    const verb = calleeVerb(n);
+                    if (verb === "when" || verb === "on") {
+                        resolveEvent(n.arguments[0]);
+                        // `opts.dispatches` array on the per-subscription options arg.
+                        const onOpts = n.arguments[2];
+                        if (onOpts && ts.isObjectLiteralExpression(onOpts)) {
+                            const disp = prop(onOpts, "dispatches");
+                            if (disp && ts.isArrayLiteralExpression(disp))
+                                for (const el of disp.elements)
+                                    resolveAction(el);
+                        }
+                    }
+                    else if (verb === "send" || verb === "enqueue" || verb === "execute") {
+                        resolveAction(n.arguments[0]);
+                    }
+                });
+                // State→state transitions (saga state machine) + external calls.
+                const resolveWfEvent = (e) => {
+                    if (e && ts.isIdentifier(e)) {
+                        if (eventNameByBinding.has(e.text))
+                            return eventNameByBinding.get(e.text);
+                        if (timerNameByBinding.has(e.text))
+                            return `__nwire/timer/${name}/${timerNameByBinding.get(e.text)}`;
+                    }
+                    return stringLiteral(e);
+                };
+                transitions = extractTransitions(closure, resolveWfEvent);
+                calls = extractCalls(closure, externalCallNameByBinding);
+            }
+            const entry = {
+                name,
+                app,
+                public: isPublic(node),
+                description,
+                subscribesTo: [...subscribesTo],
+                dispatches: [...dispatches],
+                transitions: transitions.length ? transitions : undefined,
+                calls: calls.length ? calls : undefined,
+                source: src,
+            };
+            workflows.push(entry);
+            for (const evName of subscribesTo)
+                graphEvents.push({ from: evName, to: name, via: "subscribes" });
+            for (const actName of dispatches)
+                graphEvents.push({ from: name, to: actName, via: "dispatches" });
+        });
+    }
+    return {
+        events,
+        actions,
+        actors,
+        projections,
+        queries,
+        workflows,
+        commands,
+        crons,
+        externalCalls,
+        inboundWebhooks,
+        outboxes,
+        inboxes,
+        resources,
+        errors,
+        schemas,
+        env: [...envReads].sort(),
+        config: collectConfigModules(files),
+        unanalyzable,
+        graph: { events: graphEvents },
+    };
+}
+/**
+ * Discover config modules: any parsed file living in a `config/` directory.
+ * Captures each module's top-level config field names (best-effort), sorted by
+ * file so the output is stable.
+ */
+export function collectConfigModules(files) {
+    const out = [];
+    for (const file of files) {
+        if (!isConfigModule(file))
+            continue;
+        const sf = ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.Latest, true);
+        out.push({ file, keys: extractConfigKeys(sf) });
+    }
+    return out.sort((a, b) => a.file.localeCompare(b.file));
+}
+/** True for a `.ts` file inside a `config/` directory (any depth, OS-agnostic). */
+function isConfigModule(file) {
+    const segments = file.split(/[/\\]/);
+    // The file's parent directory (or an ancestor) is named `config`.
+    return segments.slice(0, -1).includes("config");
+}