@astrale-os/sdk 0.6.0-beta.4 → 0.6.0-beta.41

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

@@ -1,7 +1,42 @@
 import ts from 'typescript';
-import { propertyChain, unwrap, visit } from '../../adapters/typescript/index.js';
-import { ambiguity, calls, production, staticId, violation } from './shared.js';
-const STEP_METHODS = new Set(['run']);
+import { expressionType, propertyChain, unwrap, visit, visitOwnBody, } from '../../adapters/typescript/index.js';
+import { ambiguity, calls, contextPath, globalCallName, globalPath, 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',
+    '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']);
+// Global reads a replay answers anew: the clock and randomness.
+const REPLAY_VALUES = new Set([
+    'Date.now',
+    'Math.random',
+    'crypto.randomUUID',
+    'crypto.getRandomValues',
+    'performance.now',
+]);
+// 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',
@@ -50,7 +85,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.`));
                         }
@@ -67,7 +102,7 @@ export const workflowRules = [
     },
     {
         id: 'FNC-NO-NEST',
-        ruleRevision: 'f2d818d1da69830c9ccaf183c5eb0310c795ab5da1a67871952aef1c2ef7600c',
+        ruleRevision: '28e764f96932bbee59a2ae6399569789a1cd2bda8e2a14ce9da5afbd348e3a63',
         evaluate(project) {
             const evidence = [];
             for (const file of production(project, 'functions')) {
@@ -109,7 +144,465 @@ 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;
+        },
+    },
+    {
+        id: 'FNC-REPLAY-VALUES',
+        ruleRevision: 'ddadc9e08be8faa36c38fd47d82d6c7815f68ffcac8806af958b13df3872b995',
+        evaluate(project) {
+            const evidence = [];
+            for (const workflow of durableWorkflows(project, evidence)) {
+                for (const { node, name } of replayValues(workflow.file, workflow.run)) {
+                    evidence.push(violation(workflow.file, node, `Durable Workflow reads ${name} outside its steps; a replay reads another value and can take another path. Read it in a step.`));
+                }
+            }
+            return evidence;
+        },
+    },
 ];
+/** The `step.run` callbacks of every Workflow its source proves durable. */
+function durableSteps(project, evidence) {
+    return durableWorkflows(project, evidence).flatMap(({ steps }) => steps);
+}
+/**
+ * Every Workflow its source proves durable, with its `step.run` callbacks: 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 replays nor retries a step and is not inspected.
+ */
+function durableWorkflows(project, evidence) {
+    const workflows = [];
+    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)
+                workflows.push({ file, run, steps: runs });
+        }
+    }
+    return workflows;
+}
+/**
+ * Reads of the clock and randomness in the code a replay runs again: the run's own body, and the
+ * functions it invokes there at once, immediately invoked or as an iterating Array callback. Step
+ * callbacks and every other nested function run at a time the source does not prove, and are
+ * skipped.
+ */
+function replayValues(file, run) {
+    const found = [];
+    const walk = (node) => {
+        if (ts.isFunctionLike(node) && !invokedAtOnce(node))
+            return;
+        const name = replayValue(file, node);
+        if (name)
+            found.push({ node, name });
+        node.forEachChild(walk);
+    };
+    if (run.body)
+        walk(run.body);
+    return found;
+}
+/** The clock or random value `node` reads from a global, as the rule names it. */
+function replayValue(file, node) {
+    if (ts.isNewExpression(node)) {
+        const path = globalPath(file, node.expression);
+        return path?.join('.') === 'Date' && (node.arguments?.length ?? 0) === 0
+            ? 'new Date()'
+            : undefined;
+    }
+    if (!ts.isCallExpression(node))
+        return undefined;
+    const name = globalPath(file, node.expression)?.join('.');
+    // `Date` called as a function answers the current time, whatever it receives.
+    if (name === 'Date')
+        return 'Date()';
+    return name !== undefined && REPLAY_VALUES.has(name) ? `${name}()` : undefined;
+}
+/** A function the code around it runs at once: immediately invoked, or an iterating Array callback. */
+function invokedAtOnce(fn) {
+    if (!ts.isArrowFunction(fn) && !ts.isFunctionExpression(fn))
+        return false;
+    let site = fn;
+    while (ts.isParenthesizedExpression(site.parent))
+        site = site.parent;
+    return ((ts.isCallExpression(site.parent) && site.parent.expression === site) || iteratingCallback(fn));
+}
+/** 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
@@ -154,17 +647,6 @@ function stepMethod(call, roots) {
         ? chain.at(-1)
         : undefined;
 }
-function visitOwnBody(fn, callback) {
-    if (!fn.body)
-        return;
-    const walk = (node) => {
-        callback(node);
-        if (node !== fn.body && ts.isFunctionLike(node))
-            return;
-        node.forEachChild(walk);
-    };
-    walk(fn.body);
-}
 function localFunctions(source) {
     const result = new Map();
     const add = (name, fn) => {
@@ -192,7 +674,7 @@ function traceNestedSteps(file, fn, workflowRun, roots, helpers, evidence, activ
             return;
         if (ts.isCallExpression(node)) {
             const nested = stepMethod(node, roots);
-            if (nested === 'run') {
+            if (nested !== undefined) {
                 evidence.push(violation(file, node, `step.run callback reaches nested step.${nested}.`));
                 return;
             }