@astrale-os/sdk 0.6.0-beta.37 → 0.6.0-beta.39

package/dist/tooling/linter/implementations/source/shared.js

@@ -215,22 +215,101 @@ export function hasForbiddenGlobalCall(file) {
     visit(file.source, (node) => {
         if (!ts.isCallExpression(node))
             return;
-        const expression = unwrap(node.expression);
-        if (ts.isIdentifier(expression)) {
-            const name = expression.text;
-            if (forbidden.has(name) &&
-                !importedSymbol(file, expression) &&
-                !isLocallyBound(expression, name)) {
-                result.push({ node, name });
+        const name = globalCallName(file, node);
+        if (name !== undefined && forbidden.has(name))
+            result.push({ node, name });
+    });
+    return result;
+}
+/** The global a call reaches, as `name(…)` with no import or local binding, or `globalThis.name(…)`. */
+export function globalCallName(file, node) {
+    const expression = unwrap(node.expression);
+    if (ts.isIdentifier(expression)) {
+        const name = expression.text;
+        return importedSymbol(file, expression) || isLocallyBound(expression, name) ? undefined : name;
+    }
+    const chain = propertyChain(expression);
+    if (chain?.length !== 2 || chain[0] !== 'globalThis')
+        return undefined;
+    let root = expression;
+    while (ts.isPropertyAccessExpression(root))
+        root = unwrap(root.expression);
+    return ts.isIdentifier(root) && isLocallyBound(root, root.text) ? undefined : chain[1];
+}
+/**
+ * Resolve the path of `input` from the first parameter of `run`, or of a durable Step callback in
+ * it, through one immutable local alias, without following arbitrary helpers.
+ */
+export function contextPath(input, run, aliases = 1) {
+    const expression = unwrap(input);
+    if (ts.isPropertyAccessExpression(expression)) {
+        const base = contextPath(expression.expression, run, aliases);
+        return base && [...base, expression.name.text];
+    }
+    if (ts.isElementAccessExpression(expression)) {
+        const base = contextPath(expression.expression, run, aliases);
+        return base && [...base, '[computed]'];
+    }
+    if (!ts.isIdentifier(expression))
+        return undefined;
+    let current = expression.parent;
+    while (current) {
+        if (ts.isFunctionLike(current)) {
+            for (const parameter of current.parameters) {
+                const path = bindingPath(parameter.name, expression.text);
+                if (path)
+                    return parameter === current.parameters[0] &&
+                        (current === run || stepCallback(current, run))
+                        ? path
+                        : undefined;
             }
-            return;
         }
-        const chain = propertyChain(expression);
-        if (chain?.length === 2 && chain[0] === 'globalThis' && forbidden.has(chain[1])) {
-            result.push({ node, name: chain[1] });
+        if (ts.isBlock(current) || ts.isSourceFile(current)) {
+            for (const statement of current.statements) {
+                if (ts.isFunctionDeclaration(statement) && statement.name?.text === expression.text)
+                    return undefined;
+                if (!ts.isVariableStatement(statement))
+                    continue;
+                for (const declaration of statement.declarationList.declarations) {
+                    const path = bindingPath(declaration.name, expression.text);
+                    if (!path)
+                        continue;
+                    if (aliases === 0 ||
+                        !declaration.initializer ||
+                        declaration.end > expression.pos ||
+                        !(statement.declarationList.flags & ts.NodeFlags.Const))
+                        return undefined;
+                    const base = contextPath(declaration.initializer, run, aliases - 1);
+                    return base && [...base, ...path];
+                }
+            }
         }
-    });
-    return result;
+        current = current.parent;
+    }
+    return undefined;
+}
+/** A durable Step callback receives the handler's capabilities under the same names. */
+function stepCallback(callback, run) {
+    const call = callback.parent;
+    if (!ts.isCallExpression(call) || call.arguments[1] !== callback)
+        return false;
+    const callee = contextPath(call.expression, run, 0);
+    return callee?.length === 2 && callee[0] === 'step' && callee[1] === 'run';
+}
+function bindingPath(name, identifier) {
+    if (ts.isIdentifier(name))
+        return name.text === identifier ? [] : undefined;
+    if (!ts.isObjectBindingPattern(name))
+        return undefined;
+    for (const element of name.elements) {
+        if (element.dotDotDotToken)
+            continue;
+        const nested = bindingPath(element.name, identifier);
+        const property = element.propertyName ?? (ts.isIdentifier(element.name) ? element.name : undefined);
+        if (nested && property && (ts.isIdentifier(property) || ts.isStringLiteral(property)))
+            return [property.text, ...nested];
+    }
+    return undefined;
 }
 export function isLocallyBoundIdentifier(node) {
     return isLocallyBound(node, node.text);

package/dist/tooling/linter/implementations/source/workflows.js

@@ -1,8 +1,35 @@
 import ts from 'typescript';
-import { propertyChain, unwrap, visit, visitOwnBody, } from '../../adapters/typescript/index.js';
-import { ambiguity, calls, production, staticId, violation } from './shared.js';
+import { expressionType, propertyChain, unwrap, visit, visitOwnBody, } from '../../adapters/typescript/index.js';
+import { ambiguity, calls, contextPath, globalCallName, production, propertyExpression, staticId, violation, } from './shared.js';
 // `query` and `mutate` are the durable Step sugar over `run`; each is one Step too.
 const STEP_METHODS = new Set(['run', 'query', 'mutate']);
+// Members only a durable Workflow context has: using one proves the Workflow durable.
+const DURABLE_CONTEXT_MEMBERS = new Set([
+    'awaitSignal',
+    'awaitExecution',
+    'cancelled',
+    'exhausted',
+    'retryAfter',
+    'sleep',
+]);
+const AUTHORITIES = new Set(['caller', 'self']);
+// Raw Kernel graph reads a Step's `kernel` offers beside `mutate`.
+const KERNEL_READS = new Set(['query', 'get', 'getOrThrow', 'neighbors']);
+// Array methods that run their callback once per element.
+const ITERATING_METHODS = new Set([
+    'every',
+    'filter',
+    'find',
+    'findIndex',
+    'findLast',
+    'findLastIndex',
+    'flatMap',
+    'forEach',
+    'map',
+    'reduce',
+    'reduceRight',
+    'some',
+]);
 export const workflowRules = [
     {
         id: 'FNC-INT-TYPES',
@@ -51,7 +78,7 @@ export const workflowRules = [
                         const method = stepMethod(node, roots);
                         if (!method)
                             return;
-                        const id = staticId(node.arguments[0]);
+                        const id = stepId(node.arguments[0]);
                         if (!id || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(id)) {
                             evidence.push(violation(file, node.arguments[0] ?? node, `Workflow ${method} step ID is not a non-empty kebab-case literal.`));
                         }
@@ -110,7 +137,403 @@ export const workflowRules = [
             return evidence;
         },
     },
+    {
+        id: 'FNC-STEP-READS',
+        ruleRevision: '16b3a7c85214d5c0c6cfaede5099c16223da1c3fd98dec9781910634bab89343',
+        evaluate(project) {
+            const evidence = [];
+            for (const step of durableSteps(project, evidence)) {
+                const operations = stepOperations(project, step);
+                const effects = operations.filter(({ kind }) => kind === 'effect');
+                const reads = operations.filter((operation) => operation.kind === 'observation' &&
+                    effects.some((effect) => precedes(operation, effect, step.callback)));
+                if (reads.length === 0)
+                    continue;
+                evidence.push(violation(step.file, step.call, `Durable step ${step.label} reads (${names(reads)}) before it writes (${names(effects)}); a retry after its write would read that write. Read in an earlier step.`));
+            }
+            return evidence;
+        },
+    },
+    {
+        id: 'FNC-EFFECT-STEP',
+        ruleRevision: 'edadc22d3dbe2d35a4e8c0c341245808cb2d9f4fb1accf953a05f6162956bea1',
+        evaluate(project) {
+            const evidence = [];
+            for (const step of durableSteps(project, evidence)) {
+                const effects = stepOperations(project, step).filter(({ kind }) => kind === 'effect');
+                // An effect runs again when it sits in a loop or two of its traces can run in one run.
+                const again = (effect) => effect.traces.some((trace) => trace.some((node) => repeated(node, step.callback))) ||
+                    together(effect.traces, effect.traces, step.callback);
+                const involved = effects.filter((effect) => again(effect) ||
+                    effects.some((other) => other !== effect && together(effect.traces, other.traces, step.callback)));
+                if (involved.length === 0)
+                    continue;
+                const listed = involved
+                    .map((effect) => (again(effect) ? `${effect.name} repeatedly` : effect.name))
+                    .join(', ');
+                evidence.push(violation(step.file, step.call, `Durable step ${step.label} performs several effects (${listed}); if one fails after another committed, the Workflow cannot tell. Give each effect its own step.`));
+            }
+            return evidence;
+        },
+    },
+    {
+        id: 'FNC-STEP-RETRY',
+        ruleRevision: 'fefbd4cb783e08b0dfe49788ff036ecff61da9190fd1b64152f92ef3a254a195',
+        evaluate(project) {
+            const evidence = [];
+            for (const step of durableSteps(project, evidence)) {
+                for (const operation of stepOperations(project, step)) {
+                    if (operation.kind !== 'unkeyed')
+                        continue;
+                    evidence.push(violation(step.file, operation.node, `Durable step ${step.label} calls ${operation.name}, which runs again when the step is retried; make it idempotent, declare the callee durable, or move it out of the durable Workflow.`));
+                }
+            }
+            return evidence;
+        },
+    },
 ];
+/**
+ * The `step.run` callbacks of every Workflow its source proves durable: it uses a member only the
+ * durable context has, `step.query` or `step.mutate`, or a Step callback that receives
+ * capabilities. An inline Workflow never retries a step and is not inspected.
+ */
+function durableSteps(project, evidence) {
+    const steps = [];
+    for (const file of production(project, 'functions')) {
+        const helpers = localFunctions(file.source);
+        for (const definition of workflowDefinitions(file)) {
+            if (definition.origin === 'ambiguous') {
+                evidence.push(ambiguity(file, definition.call, 'Workflow definition resolves through a local facade whose ultimate public constructor origin is unknown.'));
+                continue;
+            }
+            const { run } = definition;
+            if (!run)
+                continue;
+            const roots = stepRoots(run);
+            const runs = [];
+            let durable = usesDurableContext(run);
+            visitOwnBody(run, (node) => {
+                if (!ts.isCallExpression(node))
+                    return;
+                const method = stepMethod(node, roots);
+                if (!method)
+                    return;
+                if (method === 'query' || method === 'mutate' || declaredStep(node.arguments[0])) {
+                    durable = true;
+                }
+                if (method !== 'run')
+                    return;
+                const callback = node.arguments[1] && stepRunCallback(node.arguments[1], helpers);
+                if (!callback)
+                    return;
+                if (callback.parameters.length > 0)
+                    durable = true;
+                const id = stepId(node.arguments[0]);
+                runs.push({ file, call: node, label: id ?? 'with a dynamic id', callback });
+            });
+            if (durable)
+                steps.push(...runs);
+        }
+    }
+    return steps;
+}
+/** Only a durable Step takes a declaration, `{ id, retry, timeoutMs }`, in place of its id. */
+function declaredStep(argument) {
+    return argument !== undefined && ts.isObjectLiteralExpression(unwrap(argument));
+}
+/** A Step's literal id: its first argument, or the `id` of the declaration written there. */
+function stepId(argument) {
+    if (argument === undefined)
+        return undefined;
+    const value = unwrap(argument);
+    return ts.isObjectLiteralExpression(value)
+        ? staticId(propertyExpression(value, 'id'))
+        : staticId(value);
+}
+/**
+ * A `step.run` callback written inline or named by one local function. Any other is not inspected;
+ * FNC-NO-NEST reports it as ambiguous.
+ */
+function stepRunCallback(argument, helpers) {
+    const value = unwrap(argument);
+    if (ts.isArrowFunction(value) || ts.isFunctionExpression(value))
+        return value;
+    if (!ts.isIdentifier(value))
+        return undefined;
+    const candidates = helpers.get(value.text) ?? [];
+    return candidates.length === 1 ? candidates[0] : undefined;
+}
+function usesDurableContext(run) {
+    const parameter = run.parameters[0]?.name;
+    if (parameter && ts.isObjectBindingPattern(parameter)) {
+        return parameter.elements.some((element) => {
+            const name = element.propertyName ?? element.name;
+            return ts.isIdentifier(name) && DURABLE_CONTEXT_MEMBERS.has(name.text);
+        });
+    }
+    if (!parameter || !ts.isIdentifier(parameter) || !run.body)
+        return false;
+    let found = false;
+    visit(run.body, (node) => {
+        if (ts.isPropertyAccessExpression(node) &&
+            DURABLE_CONTEXT_MEMBERS.has(node.name.text) &&
+            contextPath(node, run)?.length === 1)
+            found = true;
+    });
+    return found;
+}
+/**
+ * Operations of one step whose kind is provable, with the traces that run them. An operation of
+ * unprovable kind, or in a local helper the step never mentions, is omitted.
+ */
+function stepOperations(project, step) {
+    const operations = [];
+    const body = step.callback.body;
+    if (!body)
+        return operations;
+    visit(body, (node) => {
+        if (!ts.isCallExpression(node))
+            return;
+        const operation = callOperation(project, step, node);
+        if (!operation)
+            return;
+        const traces = runTraces(node, step.callback);
+        if (traces.length > 0)
+            operations.push({ ...operation, traces });
+    });
+    return operations;
+}
+function callOperation(project, step, node) {
+    if (globalCallName(step.file, node) === 'fetch')
+        return { kind: 'unkeyed', node, name: 'fetch' };
+    const path = contextPath(node.expression, step.callback);
+    return path && capabilityOperation(project, step.file, node, path);
+}
+/**
+ * The traces through which the step callback reaches `node`: the node itself, or, inside a local
+ * helper bound to a name, each mention of that name followed by the node.
+ */
+function runTraces(node, callback, active = new Set()) {
+    for (let current = node.parent; current && current !== callback; current = current.parent) {
+        const name = ts.isFunctionLike(current) ? helperName(current) : undefined;
+        if (!name)
+            continue;
+        if (active.has(current))
+            return [];
+        active.add(current);
+        const traces = mentions(name, callback)
+            .filter(invokes)
+            .flatMap((mention) => runTraces(mention, callback, active).map((trace) => [...trace, node]));
+        active.delete(current);
+        return traces;
+    }
+    return [[node]];
+}
+function helperName(fn) {
+    const name = ts.isFunctionDeclaration(fn)
+        ? fn.name
+        : (ts.isArrowFunction(fn) || ts.isFunctionExpression(fn)) &&
+            ts.isVariableDeclaration(fn.parent) &&
+            fn.parent.initializer === fn
+            ? fn.parent.name
+            : undefined;
+    return name && ts.isIdentifier(name) ? name : undefined;
+}
+/**
+ * Whether a mention of a helper runs it: the helper is called, or handed to an iterating Array
+ * method as its callback. A helper only referenced, returned or stored is not known to run.
+ */
+function invokes(mention) {
+    const parent = mention.parent;
+    if (!ts.isCallExpression(parent))
+        return false;
+    return parent.expression === mention || iteratingCallback(mention);
+}
+/** Whether `node` is the callback, the first argument, of an iterating Array method call. */
+function iteratingCallback(node) {
+    const parent = node.parent;
+    return (parent !== undefined &&
+        ts.isCallExpression(parent) &&
+        parent.arguments[0] === node &&
+        ITERATING_METHODS.has(propertyChain(parent.expression)?.at(-1) ?? ''));
+}
+/** The identifiers of `scope` other than `name` itself that refer to its text, not as a member. */
+function mentions(name, scope) {
+    const found = [];
+    visit(scope, (node) => {
+        if (node === name || !ts.isIdentifier(node) || node.text !== name.text)
+            return;
+        const parent = node.parent;
+        if ((ts.isPropertyAccessExpression(parent) || ts.isPropertyAssignment(parent)) &&
+            parent.name === node)
+            return;
+        found.push(node);
+    });
+    return found;
+}
+function capabilityOperation(project, file, node, path) {
+    const name = path.join('.');
+    const method = path.at(-1);
+    const selected = (parts) => parts.length === 0 || (parts.length === 1 && AUTHORITIES.has(parts[0]));
+    if (path.length === 1 && (method === 'query' || method === 'mutate')) {
+        return { kind: method === 'query' ? 'observation' : 'effect', node, name };
+    }
+    if (path[0] === 'graph' && selected(path.slice(1, -1))) {
+        if (method === 'query')
+            return { kind: 'observation', node, name };
+        if (method === 'mutate')
+            return { kind: 'effect', node, name };
+        return undefined;
+    }
+    if (path[0] === 'kernel' && selected(path.slice(1, -1))) {
+        if (KERNEL_READS.has(method))
+            return { kind: 'observation', node, name };
+        if (method === 'mutate')
+            return { kind: 'effect', node, name };
+        if (method !== 'invoke')
+            return undefined;
+        const target = node.arguments[0] && unwrap(node.arguments[0]);
+        if (target &&
+            (ts.isStringLiteralLike(target) ||
+                ts.isTemplateExpression(target) ||
+                stringTyped(project, file, target))) {
+            return { kind: 'unkeyed', node, name: `${name} of an untyped Path` };
+        }
+        return invocation(project, file, node, name);
+    }
+    if (path[0] === 'dependencies' && path.length === 4 && AUTHORITIES.has(path[2])) {
+        return method === 'invoke' ? invocation(project, file, node, name) : undefined;
+    }
+    return undefined;
+}
+/**
+ * A call the types prove durable answers with its Execution and carries the step's key; one they
+ * prove ordinary carries none. Without types, or with an unresolved result, the kind is unprovable.
+ */
+function invocation(project, file, node, name) {
+    const resolved = expressionType(project, file, node);
+    if (resolved === undefined)
+        return undefined;
+    const output = resolved.checker.getAwaitedType(resolved.type) ?? resolved.type;
+    const kinds = new Set((output.isUnion() ? output.types : [output]).map(resultKind));
+    if (kinds.size !== 1)
+        return undefined;
+    const [kind] = kinds;
+    if (kind === 'durable')
+        return { kind: 'effect', node, name };
+    if (kind === 'ordinary') {
+        return { kind: 'unkeyed', node, name: `${name} of a callable that is not durable` };
+    }
+    return undefined;
+}
+/** Whether the types prove `expression` a string, which only an untyped Path is. */
+function stringTyped(project, file, expression) {
+    const resolved = expressionType(project, file, expression);
+    if (resolved === undefined)
+        return false;
+    const types = resolved.type.isUnion() ? resolved.type.types : [resolved.type];
+    return types.every((type) => (type.flags & ts.TypeFlags.StringLike) !== 0);
+}
+function resultKind(type) {
+    if (type.flags &
+        (ts.TypeFlags.Any |
+            ts.TypeFlags.Unknown |
+            ts.TypeFlags.Never |
+            ts.TypeFlags.TypeParameter |
+            ts.TypeFlags.Conditional |
+            ts.TypeFlags.IndexedAccess)) {
+        return 'unprovable';
+    }
+    return (type.aliasSymbol ?? type.getSymbol())?.getName() === 'ExecutionRef'
+        ? 'durable'
+        : 'ordinary';
+}
+/**
+ * Whether some run of the step can reach `read` before `effect` completes. Two traces are ordered
+ * where they part, in source order: a read that ends first precedes the effect or builds its
+ * arguments, unless both sit in the step's own body and take exclusive branches. Inside a helper no
+ * branch is exclusive, since each call may take another. A read after the effect sees the same
+ * committed write on every attempt.
+ */
+function precedes(read, effect, callback) {
+    return read.traces.some((first) => effect.traces.some((second) => before(first, second, callback)));
+}
+/** Whether one run of the step can reach two distinct traces, one from each list. */
+function together(traces, others, callback) {
+    return traces.some((trace) => others.some((other) => other !== trace && (before(trace, other, callback) || before(other, trace, callback))));
+}
+/** Whether a run can reach the end of `first` before `second` completes, by the order above. */
+function before(first, second, callback) {
+    const index = first.findIndex((node, position) => node !== second[position]);
+    const left = first[index];
+    const right = second[index];
+    if (!left || !right)
+        return false;
+    return left.end < right.end && !exclusive(left, right, callback);
+}
+/**
+ * Whether no run of the step reaches `effect` after `read`: both sit directly in the callback, and
+ * they take the two branches of one condition outside any loop, or `read` sits in a branch that
+ * returns or throws without `effect`.
+ */
+function exclusive(read, effect, callback) {
+    if (owner(read) !== callback || owner(effect) !== callback)
+        return false;
+    for (let node = read; node.parent && node !== callback.body; node = node.parent) {
+        const parent = node.parent;
+        if (ts.isIfStatement(parent) && node !== parent.expression) {
+            const other = node === parent.thenStatement ? parent.elseStatement : parent.thenStatement;
+            if (other && within(effect, other) && !repeated(parent, callback))
+                return true;
+            if (exits(node) && !within(effect, node))
+                return true;
+        }
+        if (ts.isConditionalExpression(parent) && node !== parent.condition) {
+            const other = node === parent.whenTrue ? parent.whenFalse : parent.whenTrue;
+            if (within(effect, other) && !repeated(parent, callback))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * A site the step may run more than once: in a loop, or in or as the callback of an iterating
+ * Array method.
+ */
+function repeated(node, callback) {
+    for (let current = node; current && current !== callback; current = current.parent) {
+        if (current !== node && ts.isIterationStatement(current, false))
+            return true;
+        if (iteratingCallback(current))
+            return true;
+    }
+    return false;
+}
+/** A statement whose every run ends in `return` or `throw`. */
+function exits(statement) {
+    if (ts.isReturnStatement(statement) || ts.isThrowStatement(statement))
+        return true;
+    if (ts.isBlock(statement)) {
+        const last = statement.statements.at(-1);
+        return last !== undefined && exits(last);
+    }
+    return (ts.isIfStatement(statement) &&
+        statement.elseStatement !== undefined &&
+        exits(statement.thenStatement) &&
+        exits(statement.elseStatement));
+}
+function owner(node) {
+    let current = node.parent;
+    while (current && !ts.isFunctionLike(current))
+        current = current.parent;
+    return current;
+}
+function within(node, container) {
+    return node.pos >= container.pos && node.end <= container.end;
+}
+function names(operations) {
+    return operations.map(({ name }) => name).join(', ');
+}
 function workflowDefinitions(file) {
     return calls(file, 'defineWorkflow').map(({ call: factory, origin }) => {
         const call = ts.isCallExpression(factory.parent) && factory.parent.expression === factory