@loomwork/compiler 0.0.0-stage → 0.1.0

package/dist/runnerReach.d.ts

@@ -0,0 +1,136 @@
+import ts from "typescript";
+/** A `ctx.run` target resolved to a concrete tool. */
+export interface RunnerStepRef {
+    /** The step's declared id, when the binding carried one. */
+    stepId?: string;
+    toolId: string;
+    /**
+     * The target was reached through `scope.invokeTransient(…)` inside a `ctx.decide`
+     * decider (L31), not through `ctx.run`. Such a call is transient: it is refused at
+     * runtime for a `journaled` effect, which the verifier can only check if it knows
+     * the call came from a scope.
+     */
+    viaDecider?: true;
+}
+/** A `ctx.run`/`ctx.suspend` whose target could not be resolved statically. */
+export interface UnresolvedReach {
+    /** Source text of the unresolved expression, e.g. `mcpInvoke$(…)` or `steps[i]`. */
+    expr: string;
+    /** What was being resolved — a step target or a suspend condition. */
+    kind: "step" | "suspend";
+    location?: string;
+}
+/** A suspend point read from a `ctx.suspend({ … })` object literal. */
+export interface RunnerSuspend {
+    /** The `on` event type, used to name the finding. */
+    id?: string;
+    correlationKey?: string;
+    /** A `timeout` was declared — the wake depends on a timer. */
+    timed?: boolean;
+    /** A `wakeAt` was declared explicitly in the condition. */
+    wakeAt?: boolean;
+}
+/**
+ * L32 — the flow's `ctx` (or its `ctx.decide`) is handed to code outside this region. The
+ * compiler cannot see that code, so it records WHERE it went; `@loomwork/verify`'s adapter
+ * resolves `callee`/`root` against the app's declared reach (`verify.reach`) and either
+ * counts the declared tools or reports the escape unresolved.
+ */
+export interface ReachEscape {
+    /** Source text of the callee the value was handed to, e.g. `planner.compose`. */
+    callee: string;
+    /** The leftmost identifier of `callee` (`planner`), absent for `this.x` / call results. */
+    root?: string;
+    /** What was handed over: the whole `ctx`, or just `ctx.decide`. */
+    via: "ctx" | "decide";
+    /** When `via` is "ctx": the ctx METHOD handed over (`run` for `lib(ctx.run)`), absent for the whole ctx. */
+    member?: string;
+    /**
+     * L34 - the arguments of the hand-off that RESOLVE to a step, by position, for a callee whose
+     * declaration says it runs a step it is handed (`fanout$(ctx, step, items)`: argument 1). A
+     * position absent here did not resolve; the verifier reports that only if the declaration names
+     * the position. Absent for `via: "decide"`, a ctx method, and a pass-through
+     * (`setTimeout(lib, …)`), whose arguments are not the callee's.
+     */
+    args?: ReachEscapeArg[];
+    location?: string;
+}
+/** One argument of a ctx hand-off, see {@link ReachEscape.args}. */
+export interface ReachEscapeArg {
+    index: number;
+    step: RunnerStepRef;
+}
+/**
+ * Resolution services the analysis cannot do on a single parsed module. Optional: without it
+ * the analysis is same-module only.
+ */
+export interface AnalyzeReachOptions {
+    /**
+     * L37 - resolve a name this module IMPORTS to what its declaration shows: a string constant
+     * (`export const LLM_X = "llm.x"`) or a step-factory shape (`export function llmStep$(id, toolId)`).
+     */
+    importResolver?: (localName: string) => ImportedBinding | undefined;
+}
+/** What an imported name resolves to. */
+export interface ImportedBinding {
+    value?: string;
+    factory?: StepFactoryShape;
+}
+/**
+ * L37 - how a step factory yields its effect id: a fixed one (`mcpInvoke$` always dispatches
+ * `mcp.invoke`; the step ID is minted but the EFFECT is what verify checks) or the value of one of
+ * its parameters (`llmStep$(id, toolId)`).
+ */
+export type StepFactoryShape = {
+    fixed: string;
+}
+/** The effect id is argument `argIndex`; when that argument is absent, `default` (a parameter default). */
+ | {
+    argIndex: number;
+    default?: string;
+};
+/**
+ * First-party factories whose effect id is fixed and whose source is in a package (never followed
+ * through an import). `mcp.invoke` is `MCP_INVOKE_TOOL_ID` in `@loomwork/plugin-mcp` and `sandbox.eval` is
+ * `SANDBOX_TOOL_ID` in `@loomwork/sandbox` (re-exported by `@loomwork/plugin-sandbox`, ADR 0144); a test pins each to its package.
+ */
+export declare const KNOWN_STEP_FACTORIES: Readonly<Record<string, StepFactoryShape>>;
+export interface RunnerReach {
+    steps: RunnerStepRef[];
+    unresolved: UnresolvedReach[];
+    suspends: RunnerSuspend[];
+    /** L32 — `ctx` handed to out-of-region callees. Absent when there are none. */
+    escapes?: ReachEscape[];
+}
+/** The string a literal-ish expression denotes (`"x"`, an expression-free template, `"x" as const`). */
+export declare function stringLiteralValue(e: ts.Expression): string | undefined;
+/**
+ * L37 - infer how a function yields a step's effect id, by SHAPE (like {@link collectBindings}):
+ * its single returned expression is a call whose first argument is an object literal with a
+ * `toolId` that is a constant (per `str`) or one of the function's plain parameters. Anything else
+ * (several returns, a spread, a computed toolId) is `undefined`, never a guess.
+ */
+export declare function inferStepFactory(fn: ts.Node, rawStr: (e: ts.Expression) => string | undefined): StepFactoryShape | undefined;
+/** Analyze a parsed node (a flow runner body) for reachable steps and suspend points. */
+export declare function analyzeReachNode(root: ts.Node, location?: string, options?: AnalyzeReachOptions): RunnerReach;
+/**
+ * {@link analyzeReachNode} plus how many runner functions the region declares and the analysis
+ * followed, and how many of them are BOUND to a `flow$` definition: declared in the same object
+ * literal / class as a `flow$(...)` (or a const holding one), or passed to `registerFlow(def, …)`
+ * whose `def` is a `flow$` call or names one. An EMPTY reach is ambiguous on its own: "the runner
+ * reaches nothing" and "no runner of THIS flow is here" (an unrelated runner elsewhere in the
+ * module, or one registered from another module) look the same. A runner that is NOT followable is
+ * never silent (`unresolved`), so an empty reach with `boundRunners > 0` means the flow's own
+ * runner was read and reaches no step, suspend or ctx hand-off: a pure runner, analysed.
+ */
+export declare function analyzeReachRegion(root: ts.Node, location?: string, options?: AnalyzeReachOptions): {
+    reach: RunnerReach;
+    runners: number;
+    boundRunners: number;
+};
+/**
+ * Analyze a source string (a flow runner / orchestration body). Feed the result
+ * to `@loomwork/verify` via `resolveVerifyInput({ runnerReachByFlow })`.
+ */
+export declare function analyzeRunnerReach(source: string, location?: string): RunnerReach;
+//# sourceMappingURL=runnerReach.d.ts.map

package/dist/runnerReach.d.ts.map

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