@astrale-os/sdk 0.5.0-beta.13 → 0.5.0-beta.131

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

@@ -0,0 +1,1176 @@
+import ts from 'typescript';
+import { importedSymbol, observeQueryDefinitions, propertyChain, queryCollectionKind, unwrap, visit, } from '../../adapters/typescript/index.js';
+import { decideCanonicalQuery, decideSingleQuery } from '../../analysis/query/index.js';
+import { ambiguity, callback, definitionOriginAmbiguity, definitionObjects, domainProjectorEvidence, propertyExpression, production, returnedExpressions, staticId, violation, } from './shared.js';
+import { sourceEvidence } from './verifier.js';
+const FORBIDDEN_COMPOSE_NAMES = new Set(['fetch', 'invoke', 'mutate', 'run', 'step', 'then']);
+export const queryRules = [
+    {
+        id: 'QRY-CANON',
+        ruleRevision: '17dc62dc0413f93c9d9cfd4787ee729caf187eeffe83e38f8036c1cece1b3639',
+        evaluate(project) {
+            return [
+                ...sourceEvidence(decideCanonicalQuery(observeQueryDefinitions(project))),
+                ...production(project, 'queries').flatMap((file) => [
+                    ...domainProjectorEvidence(file, 'defineCollectionQuery', 'Collection Query'),
+                    ...domainProjectorEvidence(file, 'defineQuery', 'Query'),
+                    ...domainProjectorEvidence(file, 'defineCompositeQuery', 'Composite Query'),
+                ]),
+            ];
+        },
+    },
+    {
+        id: 'QRY-SINGLE',
+        ruleRevision: 'a0b90940e0e980f1536b8bfd4288ba3b07689ddf4bf0e72a0ad4f39a83d01f84',
+        evaluate(project) {
+            return sourceEvidence(decideSingleQuery(observeQueryDefinitions(project)));
+        },
+    },
+    {
+        id: 'QRY-COMPOSE-TYPED',
+        ruleRevision: '4ab1566f88e42f6105ef99038f78fb03e2f95c6836458425aecfdecfc6ff3720',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'queries')) {
+                for (const definition of definitionObjects(file, 'defineCompositeQuery')) {
+                    const uncertain = definitionOriginAmbiguity(file, definition, 'Composite Query definition');
+                    if (uncertain) {
+                        evidence.push(uncertain);
+                        continue;
+                    }
+                    const { call, object } = definition;
+                    if (!object) {
+                        evidence.push(ambiguity(file, call, 'Composite Query definition is not a static object literal.'));
+                        continue;
+                    }
+                    const compose = callback(object, 'compose');
+                    if (!compose) {
+                        evidence.push(violation(file, object, 'Composite Query has no compose callback.'));
+                        continue;
+                    }
+                    if (compose.modifiers?.some(({ kind }) => kind === ts.SyntaxKind.AsyncKeyword)) {
+                        evidence.push(violation(file, compose, 'Composite Query compose callback is async.'));
+                    }
+                    if ('asteriskToken' in compose && compose.asteriskToken) {
+                        evidence.push(violation(file, compose, 'Composite Query compose callback is a generator.'));
+                    }
+                    const builder = composeBuilder(compose);
+                    if (!builder) {
+                        evidence.push(ambiguity(file, compose, 'Composite Query builder bindings are not statically identifiable.'));
+                        continue;
+                    }
+                    evidence.push(...composeReturnEvidence(file, compose, builder));
+                    evidence.push(...composePlanReachabilityEvidence(file, compose, builder));
+                    const reportedWriteTargets = [];
+                    visitOwnBody(compose, (node) => {
+                        if (writesComposeBuilder(node, builder)) {
+                            const target = composeWriteTarget(node) ?? node;
+                            if (containsReportedWriteTarget(reportedWriteTargets, target))
+                                return;
+                            reportedWriteTargets.push(target);
+                            evidence.push(violation(file, node, 'Composite Query builder binding is reassigned or mutated.'));
+                            return;
+                        }
+                        if (isComposeEffectWrite(node)) {
+                            const target = composeWriteTarget(node) ?? node;
+                            if (containsReportedWriteTarget(reportedWriteTargets, target))
+                                return;
+                            reportedWriteTargets.push(target);
+                            evidence.push(violation(file, node, 'Composite Query compose performs a state write outside plan construction.'));
+                            return;
+                        }
+                        if (ts.isNewExpression(node)) {
+                            const imported = importedSymbol(file, node.expression);
+                            evidence.push(imported
+                                ? violation(file, node, `Composite Query compose invokes imported constructor ${imported.name} outside the closed plan builder.`)
+                                : ambiguity(file, node, `Composite Query compose constructor ${propertyChain(node.expression)?.join('.') ?? '<expression>'} has an unresolved origin.`));
+                            return;
+                        }
+                        if (ts.isTaggedTemplateExpression(node)) {
+                            const imported = importedSymbol(file, node.tag);
+                            evidence.push(imported
+                                ? violation(file, node, `Composite Query compose invokes imported tag ${imported.name} outside the closed plan builder.`)
+                                : ambiguity(file, node, `Composite Query compose tag ${propertyChain(node.tag)?.join('.') ?? '<expression>'} has an unresolved origin.`));
+                            return;
+                        }
+                        if (!ts.isCallExpression(node))
+                            return;
+                        const chain = propertyChain(node.expression);
+                        const builderMethod = composeBuilderMethod(node.expression, builder);
+                        if (builderMethod) {
+                            if (builderMethod === 'query' && isCompositeLeaf(node.arguments[1], file)) {
+                                evidence.push(violation(file, node.arguments[1], 'Composite Query leaf is itself composite.'));
+                            }
+                            if (builderMethod === 'combine') {
+                                const result = resultTimeCallbacks(node, compose, builder);
+                                for (const callback of result.callbacks) {
+                                    evidence.push(violation(file, callback, 'Composite Query result embeds a result-time callback.'));
+                                }
+                                if (result.incomplete) {
+                                    evidence.push(ambiguity(file, node, 'Composite Query result callback analysis reached its cycle or node limit.'));
+                                }
+                            }
+                            return;
+                        }
+                        const imported = importedSymbol(file, node.expression);
+                        const name = imported?.name ?? chain?.at(-1);
+                        if (name && FORBIDDEN_COMPOSE_NAMES.has(name)) {
+                            evidence.push(violation(file, node, `Composite Query compose invokes forbidden ${name}.`));
+                        }
+                        else if (imported) {
+                            evidence.push(violation(file, node, `Composite Query compose invokes imported ${imported.name} outside the closed plan builder.`));
+                        }
+                        else {
+                            evidence.push(ambiguity(file, node, `Composite Query compose call ${chain?.join('.') ?? '<expression>'} has an unresolved origin.`));
+                        }
+                    });
+                }
+            }
+            return evidence;
+        },
+    },
+    {
+        id: 'QRY-COMPOSE-STABLE',
+        ruleRevision: '7e028a5408a958e7e5bd6ccf04a9262c33be1152c2248896ef3cf038c125ff1e',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'queries')) {
+                for (const definition of definitionObjects(file, 'defineCompositeQuery')) {
+                    const uncertain = definitionOriginAmbiguity(file, definition, 'Composite Query definition');
+                    if (uncertain) {
+                        evidence.push(uncertain);
+                        continue;
+                    }
+                    const { object } = definition;
+                    const compose = object && callback(object, 'compose');
+                    if (!compose)
+                        continue;
+                    const builder = composeBuilder(compose);
+                    if (!builder) {
+                        evidence.push(ambiguity(file, compose, 'Composite Query builder bindings are not statically identifiable.'));
+                        continue;
+                    }
+                    const ids = new Set();
+                    visitOwnBody(compose, (node) => {
+                        if (ts.isCallExpression(node)) {
+                            if (composeBuilderMethod(node.expression, builder) !== 'query')
+                                return;
+                            const id = staticId(node.arguments[0]);
+                            if (!id || !/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/.test(id)) {
+                                evidence.push(violation(file, node.arguments[0] ?? node, 'Composite Query leaf ID is not a stable semantic literal.'));
+                            }
+                            else if (ids.has(id)) {
+                                evidence.push(violation(file, node.arguments[0], `Composite Query duplicates leaf ID ${id}.`));
+                            }
+                            else
+                                ids.add(id);
+                        }
+                    });
+                }
+            }
+            return evidence;
+        },
+    },
+    {
+        id: 'QRY-COLL-FANOUT',
+        ruleRevision: '50279cef3618d44cc1c3212a0d72213eca26a78c540f7a2998df244c38fc54ca',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'queries')) {
+                for (const definition of definitionObjects(file, 'defineCompositeQuery')) {
+                    if (definition.origin !== 'resolved' || !definition.object)
+                        continue;
+                    const compose = callback(definition.object, 'compose');
+                    if (!compose)
+                        continue;
+                    const builder = composeBuilder(compose);
+                    if (!builder)
+                        continue;
+                    const groups = {
+                        node: [],
+                        edge: [],
+                    };
+                    let logicalQueries = 0;
+                    let physicalQueries = 0;
+                    const returns = returnedExpressions(compose);
+                    if (returns.length !== 1)
+                        continue;
+                    visit(returns[0], (node) => {
+                        if (!ts.isCallExpression(node))
+                            return;
+                        const method = composeBuilderMethod(node.expression, builder);
+                        if (method === 'query') {
+                            logicalQueries += 1;
+                            physicalQueries += 1;
+                            if (!isVoidCollectionLeaf(node))
+                                return;
+                            const selected = node.arguments[1];
+                            if (selected === undefined)
+                                return;
+                            const kind = queryCollectionKind(project, file, selected);
+                            const member = kind && collectionMember(file, selected, node);
+                            if (kind && member)
+                                groups[kind].push(member);
+                            return;
+                        }
+                        if (method !== 'union')
+                            return;
+                        const members = staticRecordMembers(node.arguments[0]);
+                        if (members === undefined)
+                            return;
+                        logicalQueries += members;
+                        physicalQueries += 1;
+                    });
+                    const candidates = ['node', 'edge'].filter((kind) => {
+                        const members = groups[kind];
+                        return (members.length >= 3 &&
+                            new Set(members.map(({ id }) => id)).size === members.length &&
+                            new Set(members.map(({ classKey }) => classKey)).size === members.length);
+                    });
+                    if (candidates.length === 0)
+                        continue;
+                    const optimizedPhysical = physicalQueries -
+                        candidates.reduce((total, kind) => total + groups[kind].length, 0) +
+                        candidates.length;
+                    const scaffold = candidates
+                        .map((kind) => {
+                        const outer = kind === 'node' ? 'nodes' : 'relations';
+                        const members = groups[kind]
+                            .map(({ name, value }) => (name === value ? name : `${name}: ${value}`))
+                            .join(', ');
+                        return `${outer}: query.union({ ${members} })`;
+                    })
+                        .join('\n');
+                    evidence.push(violation(file, compose, `Compatible collection fan-out has a direct replacement:\n${scaffold}\nPlan estimate: ${logicalQueries} logical → ${optimizedPhysical} physical cursor chains (currently ${physicalQueries} physical).`));
+                }
+            }
+            return evidence;
+        },
+    },
+];
+function isVoidCollectionLeaf(call) {
+    const input = call.arguments[2];
+    if (input === undefined)
+        return true;
+    const value = unwrap(input);
+    return ((ts.isIdentifier(value) && value.text === 'undefined') ||
+        (ts.isVoidExpression(value) && ts.isNumericLiteral(unwrap(value.expression))));
+}
+function collectionMember(file, expression, call) {
+    const value = unwrap(expression);
+    if (!ts.isIdentifier(value))
+        return undefined;
+    const outputName = directOutputName(call);
+    const semantics = collectionDefinitionSemantics(file, value.text);
+    if (outputName === undefined || semantics === undefined)
+        return undefined;
+    return { name: outputName, value: value.text, ...semantics };
+}
+function directOutputName(call) {
+    const property = call.parent;
+    if (!ts.isPropertyAssignment(property) || unwrap(property.initializer) !== call)
+        return undefined;
+    const name = property.name;
+    return ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : undefined;
+}
+function collectionDefinitionSemantics(file, name) {
+    const declarations = [];
+    visit(file.source, (node) => {
+        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.name.text === name) {
+            declarations.push(node);
+        }
+    });
+    if (declarations.length !== 1)
+        return undefined;
+    const application = declarations[0].initializer && unwrap(declarations[0].initializer);
+    if (!application || !ts.isCallExpression(application))
+        return undefined;
+    const factory = unwrap(application.expression);
+    if (!ts.isCallExpression(factory))
+        return undefined;
+    const origin = importedSymbol(file, factory.expression);
+    if (origin?.name !== 'defineCollectionQuery' ||
+        (origin.module !== '@astrale-os/sdk' && origin.module !== '@astrale-os/sdk/query')) {
+        return undefined;
+    }
+    const projected = application.arguments[0] && unwrap(application.arguments[0]);
+    if (!projected || (!ts.isArrowFunction(projected) && !ts.isFunctionExpression(projected))) {
+        return undefined;
+    }
+    const domain = projected.parameters[0]?.name;
+    if (!domain || !ts.isIdentifier(domain))
+        return undefined;
+    const returns = returnedExpressions(projected);
+    if (returns.length !== 1)
+        return undefined;
+    const object = unwrap(returns[0]);
+    if (!ts.isObjectLiteralExpression(object))
+        return undefined;
+    const id = staticId(propertyExpression(object, 'id'));
+    const selected = propertyExpression(object, 'class');
+    const chain = selected && propertyChain(selected);
+    if (!id || chain?.length !== 3 || chain[0] !== domain.text || chain[1] !== 'classes') {
+        return undefined;
+    }
+    return { id, classKey: chain.slice(1).join('.') };
+}
+function staticRecordMembers(expression) {
+    if (!expression)
+        return undefined;
+    const value = unwrap(expression);
+    if (!ts.isObjectLiteralExpression(value))
+        return undefined;
+    if (value.properties.some((property) => ts.isSpreadAssignment(property) ||
+        ('name' in property && property.name && ts.isComputedPropertyName(property.name)))) {
+        return undefined;
+    }
+    return value.properties.length;
+}
+function composeBuilder(compose) {
+    const name = compose.parameters[0]?.name;
+    if (!name)
+        return undefined;
+    if (ts.isIdentifier(name))
+        return { owner: compose, root: name };
+    if (!ts.isObjectBindingPattern(name))
+        return undefined;
+    const bindings = {};
+    for (const element of name.elements) {
+        if (element.dotDotDotToken || !ts.isIdentifier(element.name))
+            return undefined;
+        const source = element.propertyName
+            ? ts.isIdentifier(element.propertyName) || ts.isStringLiteral(element.propertyName)
+                ? element.propertyName.text
+                : undefined
+            : element.name.text;
+        if (source !== 'query' && source !== 'union' && source !== 'combine')
+            continue;
+        if (bindings[source])
+            return undefined;
+        bindings[source] = element.name;
+    }
+    return bindings.query || bindings.union || bindings.combine
+        ? { owner: compose, ...bindings }
+        : undefined;
+}
+function composeBuilderMethod(expression, builder) {
+    const target = unwrap(expression);
+    if (builder.root && ts.isPropertyAccessExpression(target)) {
+        const root = unwrap(target.expression);
+        if (ts.isIdentifier(root) &&
+            (target.name.text === 'query' ||
+                target.name.text === 'union' ||
+                target.name.text === 'combine') &&
+            referencesComposeBinding(root, builder.root, builder.owner)) {
+            return target.name.text;
+        }
+    }
+    if (!ts.isIdentifier(target))
+        return undefined;
+    if (builder.query && referencesComposeBinding(target, builder.query, builder.owner))
+        return 'query';
+    if (builder.union && referencesComposeBinding(target, builder.union, builder.owner))
+        return 'union';
+    if (builder.combine && referencesComposeBinding(target, builder.combine, builder.owner)) {
+        return 'combine';
+    }
+    return undefined;
+}
+function referencesComposeBinding(reference, binding, owner) {
+    if (reference.text !== binding.text)
+        return false;
+    let current = reference.parent;
+    while (current && current !== owner) {
+        if ((ts.isClassExpression(current) || ts.isClassDeclaration(current)) &&
+            current.name?.text === reference.text) {
+            return false;
+        }
+        if (ts.isFunctionLike(current) &&
+            current.parameters.some(({ name }) => bindingContains(name, reference.text))) {
+            return false;
+        }
+        if (ts.isCatchClause(current) &&
+            current.variableDeclaration &&
+            bindingContains(current.variableDeclaration.name, reference.text)) {
+            return false;
+        }
+        if (ts.isBlock(current) || ts.isModuleBlock(current) || ts.isCaseBlock(current)) {
+            const scope = current;
+            const statements = ts.isCaseBlock(scope)
+                ? scope.clauses.flatMap((clause) => [...clause.statements])
+                : [...scope.statements];
+            if (statements.some((statement) => statementShadowsComposeBinding(statement, reference.text, scope, owner))) {
+                return false;
+            }
+        }
+        if ((ts.isForStatement(current) ||
+            ts.isForInStatement(current) ||
+            ts.isForOfStatement(current)) &&
+            current.initializer &&
+            ts.isVariableDeclarationList(current.initializer) &&
+            declarationListShadowsComposeBinding(current.initializer, reference.text, current, owner)) {
+            return false;
+        }
+        current = current.parent;
+    }
+    return current === owner;
+}
+function writesComposeBuilder(node, builder) {
+    if (ts.isBinaryExpression(node) && isAssignmentOperator(node.operatorToken.kind)) {
+        return writeTargetReferencesBuilder(node.left, builder);
+    }
+    if (ts.isDeleteExpression(node)) {
+        return writeTargetReferencesBuilder(node.expression, builder);
+    }
+    if (ts.isVariableDeclaration(node) &&
+        node.initializer &&
+        ts.isVariableDeclarationList(node.parent) &&
+        isOwnerFunctionVar(node.parent, builder.owner)) {
+        return writeTargetReferencesBuilder(node.name, builder);
+    }
+    if (ts.isFunctionDeclaration(node) && node.name && node.parent === builder.owner.body) {
+        return isComposeBuilderReference(node.name, builder);
+    }
+    if ((ts.isForInStatement(node) || ts.isForOfStatement(node)) &&
+        ts.isVariableDeclarationList(node.initializer)) {
+        return (isOwnerFunctionVar(node.initializer, builder.owner) &&
+            node.initializer.declarations.some(({ name }) => writeTargetReferencesBuilder(name, builder)));
+    }
+    if ((ts.isForInStatement(node) || ts.isForOfStatement(node)) &&
+        !ts.isVariableDeclarationList(node.initializer)) {
+        return writeTargetReferencesBuilder(node.initializer, builder);
+    }
+    if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+        (node.operator === ts.SyntaxKind.PlusPlusToken ||
+            node.operator === ts.SyntaxKind.MinusMinusToken)) {
+        return writeTargetReferencesBuilder(node.operand, builder);
+    }
+    return false;
+}
+function isAssignmentOperator(kind) {
+    return kind >= ts.SyntaxKind.FirstAssignment && kind <= ts.SyntaxKind.LastAssignment;
+}
+function isComposeEffectWrite(node) {
+    return ((ts.isBinaryExpression(node) && isAssignmentOperator(node.operatorToken.kind)) ||
+        ts.isDeleteExpression(node) ||
+        ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+            (node.operator === ts.SyntaxKind.PlusPlusToken ||
+                node.operator === ts.SyntaxKind.MinusMinusToken)) ||
+        ts.isForInStatement(node) ||
+        ts.isForOfStatement(node));
+}
+function composeWriteTarget(node) {
+    if (ts.isBinaryExpression(node) && isAssignmentOperator(node.operatorToken.kind))
+        return node.left;
+    if (ts.isDeleteExpression(node))
+        return node.expression;
+    if (ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node))
+        return node.operand;
+    if (ts.isForInStatement(node) || ts.isForOfStatement(node))
+        return node.initializer;
+    if (ts.isVariableDeclaration(node))
+        return node.name;
+    if (ts.isFunctionDeclaration(node))
+        return node.name;
+    return undefined;
+}
+function containsReportedWriteTarget(reported, target) {
+    return reported.some((owner) => owner.pos <= target.pos && owner.end >= target.end);
+}
+function composeReturnEvidence(file, compose, builder) {
+    if (!compose.body)
+        return [];
+    if (!ts.isBlock(compose.body)) {
+        return isBuilderClosedPlanCall(compose.body, builder)
+            ? []
+            : [
+                violation(file, compose.body, 'Composite Query compose does not return the closed plan from combine or union.'),
+            ];
+    }
+    const evidence = [];
+    let returns = 0;
+    visitOwnBody(compose, (node) => {
+        if (ts.isReturnStatement(node)) {
+            returns += 1;
+            if (!node.expression || !isBuilderClosedPlanCall(node.expression, builder)) {
+                evidence.push(violation(file, node, 'Composite Query compose return does not produce the closed plan from combine or union.'));
+            }
+        }
+        else if (ts.isThrowStatement(node)) {
+            evidence.push(violation(file, node, 'Composite Query compose throws instead of constructing its plan.'));
+        }
+    });
+    if (returns === 0) {
+        evidence.push(violation(file, compose, 'Composite Query compose has no returned closed QueryPlan.'));
+    }
+    return evidence;
+}
+function isBuilderClosedPlanCall(expression, builder) {
+    const value = unwrap(expression);
+    if (!ts.isCallExpression(value))
+        return false;
+    const method = composeBuilderMethod(value.expression, builder);
+    return method === 'combine' || method === 'union';
+}
+function composePlanReachabilityEvidence(file, compose, builder) {
+    const authored = new Set();
+    visitOwnBody(compose, (node) => {
+        if (ts.isCallExpression(node) && composeBuilderMethod(node.expression, builder) !== undefined) {
+            authored.add(node);
+        }
+    });
+    if (authored.size === 0 || !compose.body)
+        return [];
+    const roots = [];
+    if (!ts.isBlock(compose.body)) {
+        const root = unwrap(compose.body);
+        if (ts.isCallExpression(root) && isBuilderClosedPlanCall(root, builder)) {
+            roots.push(root);
+        }
+    }
+    else {
+        visitOwnBody(compose, (node) => {
+            if (!ts.isReturnStatement(node) || !node.expression)
+                return;
+            const root = unwrap(node.expression);
+            if (ts.isCallExpression(root) && isBuilderClosedPlanCall(root, builder)) {
+                roots.push(root);
+            }
+        });
+    }
+    if (roots.length === 0)
+        return [];
+    const reachable = new Set();
+    const activeAliases = new Set();
+    const completedAliases = new Set();
+    let remaining = 256;
+    let incomplete = false;
+    const traceSymbolicRoot = (node, seen = new Set()) => {
+        if (seen.has(node)) {
+            incomplete = true;
+            return false;
+        }
+        seen.add(node);
+        if (!ts.isExpression(node))
+            return false;
+        const value = unwrap(node);
+        if (ts.isPropertyAccessExpression(value) || ts.isElementAccessExpression(value)) {
+            const base = resolveComposeValueNode(value.expression, compose, builder, new Set());
+            if (base.kind === 'value' &&
+                ts.isCallExpression(base.node) &&
+                composeBuilderMethod(base.node.expression, builder) !== undefined &&
+                staticMemberName(value) === 'value') {
+                trace(base.node);
+                return true;
+            }
+            return traceSymbolicRoot(value.expression, seen);
+        }
+        if (ts.isCallExpression(value)) {
+            if (composeBuilderMethod(value.expression, builder) === undefined)
+                return false;
+            trace(value);
+            return true;
+        }
+        if (!ts.isIdentifier(value))
+            return false;
+        const binding = resolveComposeValueBinding(value, compose);
+        if (binding.kind === 'ambiguous')
+            incomplete = true;
+        return binding.kind === 'value' ? traceSymbolicRoot(binding.node, seen) : false;
+    };
+    const trace = (node) => {
+        if (remaining-- <= 0) {
+            incomplete = true;
+            return;
+        }
+        if (isResultCallback(node))
+            return;
+        if (ts.isCallExpression(node)) {
+            const method = composeBuilderMethod(node.expression, builder);
+            if (!method) {
+                incomplete = true;
+                return;
+            }
+            if (reachable.has(node))
+                return;
+            reachable.add(node);
+            if (method === 'combine') {
+                for (const argument of node.arguments) {
+                    trace(ts.isSpreadElement(argument) ? argument.expression : argument);
+                }
+            }
+            else if (node.arguments[2]) {
+                trace(node.arguments[2]);
+            }
+            return;
+        }
+        if (ts.isIdentifier(node)) {
+            const binding = resolveComposeValueBinding(node, compose);
+            if (binding.kind === 'ambiguous') {
+                incomplete = true;
+                return;
+            }
+            if (binding.kind !== 'value')
+                return;
+            if (activeAliases.has(binding.node)) {
+                incomplete = true;
+                return;
+            }
+            if (completedAliases.has(binding.node))
+                return;
+            activeAliases.add(binding.node);
+            trace(binding.node);
+            activeAliases.delete(binding.node);
+            completedAliases.add(binding.node);
+            return;
+        }
+        if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+            const projection = resolveStaticComposeProjection(node, compose, builder);
+            if (projection.kind === 'value') {
+                trace(projection.node);
+            }
+            else if (!traceSymbolicRoot(node) && projection.kind === 'ambiguous') {
+                incomplete = true;
+            }
+            return;
+        }
+        if (ts.isObjectLiteralExpression(node)) {
+            for (const property of node.properties) {
+                if (ts.isPropertyAssignment(property))
+                    trace(property.initializer);
+                else if (ts.isShorthandPropertyAssignment(property))
+                    trace(property.name);
+                else if (ts.isSpreadAssignment(property))
+                    trace(property.expression);
+            }
+            return;
+        }
+        if (ts.isArrayLiteralExpression(node)) {
+            for (const element of node.elements) {
+                trace(ts.isSpreadElement(element) ? element.expression : element);
+            }
+            return;
+        }
+        if (ts.isConditionalExpression(node)) {
+            trace(node.whenTrue);
+            trace(node.whenFalse);
+            return;
+        }
+        if (ts.isBinaryExpression(node)) {
+            if (node.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken ||
+                node.operatorToken.kind === ts.SyntaxKind.BarBarToken ||
+                node.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken) {
+                trace(node.left);
+                trace(node.right);
+            }
+            else if (node.operatorToken.kind === ts.SyntaxKind.CommaToken) {
+                trace(node.right);
+            }
+            return;
+        }
+        if (ts.isExpression(node)) {
+            const value = unwrap(node);
+            if (value !== node)
+                trace(value);
+        }
+    };
+    for (const root of roots)
+        trace(root);
+    if (incomplete) {
+        return [
+            ambiguity(file, compose, 'Composite Query plan reachability reached an unresolved edge, cycle, or node limit.'),
+        ];
+    }
+    return [...authored]
+        .filter((node) => !reachable.has(node))
+        .map((node) => violation(file, node, 'Composite Query builder node is unreachable from its returned plan.'));
+}
+function staticMemberName(member) {
+    return ts.isPropertyAccessExpression(member)
+        ? member.name.text
+        : staticMemberKey(member.argumentExpression);
+}
+function isBuilderSymbolicMember(member, compose, builder) {
+    let current = member;
+    while (ts.isPropertyAccessExpression(current) || ts.isElementAccessExpression(current)) {
+        if (staticMemberName(current) === 'value') {
+            const base = resolveComposeValueNode(current.expression, compose, builder, new Set());
+            if (base.kind === 'value' &&
+                ts.isCallExpression(base.node) &&
+                composeBuilderMethod(base.node.expression, builder) !== undefined) {
+                return true;
+            }
+        }
+        current = unwrap(current.expression);
+    }
+    return false;
+}
+function resultTimeCallbacks(combine, compose, builder) {
+    const callbacks = new Set();
+    const completedAliases = new Set();
+    const activeAliases = new Set();
+    let remaining = 256;
+    let incomplete = false;
+    const inspect = (node) => {
+        if (remaining-- <= 0) {
+            incomplete = true;
+            return;
+        }
+        if (isResultCallback(node)) {
+            callbacks.add(node);
+            return;
+        }
+        if (ts.isIdentifier(node)) {
+            const resolution = resolveComposeValueBinding(node, compose);
+            if (resolution.kind === 'ambiguous') {
+                incomplete = true;
+                return;
+            }
+            if (resolution.kind !== 'value')
+                return;
+            const alias = resolution.node;
+            if (activeAliases.has(alias)) {
+                incomplete = true;
+                return;
+            }
+            if (completedAliases.has(alias))
+                return;
+            activeAliases.add(alias);
+            inspect(alias);
+            activeAliases.delete(alias);
+            completedAliases.add(alias);
+            return;
+        }
+        if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+            if (isBuilderSymbolicMember(node, compose, builder))
+                return;
+            const projection = resolveStaticComposeProjection(node, compose, builder);
+            if (projection.kind === 'ambiguous')
+                incomplete = true;
+            if (projection.kind === 'value')
+                inspect(projection.node);
+            return;
+        }
+        if (ts.isObjectLiteralExpression(node)) {
+            for (const property of node.properties) {
+                if (ts.isMethodDeclaration(property) ||
+                    ts.isGetAccessorDeclaration(property) ||
+                    ts.isSetAccessorDeclaration(property)) {
+                    callbacks.add(property);
+                }
+                else if (ts.isPropertyAssignment(property)) {
+                    inspect(property.initializer);
+                }
+                else if (ts.isShorthandPropertyAssignment(property)) {
+                    inspect(property.name);
+                }
+                else if (ts.isSpreadAssignment(property)) {
+                    inspect(property.expression);
+                }
+            }
+            return;
+        }
+        if (ts.isArrayLiteralExpression(node)) {
+            for (const element of node.elements) {
+                inspect(ts.isSpreadElement(element) ? element.expression : element);
+            }
+            return;
+        }
+        if (ts.isConditionalExpression(node)) {
+            inspect(node.whenTrue);
+            inspect(node.whenFalse);
+            return;
+        }
+        if (ts.isBinaryExpression(node)) {
+            if (node.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken ||
+                node.operatorToken.kind === ts.SyntaxKind.BarBarToken ||
+                node.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken) {
+                inspect(node.left);
+                inspect(node.right);
+            }
+            else if (node.operatorToken.kind === ts.SyntaxKind.CommaToken) {
+                inspect(node.right);
+            }
+            return;
+        }
+        if (ts.isExpression(node)) {
+            const value = unwrap(node);
+            if (value !== node)
+                inspect(value);
+        }
+    };
+    for (const argument of combine.arguments) {
+        inspect(ts.isSpreadElement(argument) ? argument.expression : argument);
+    }
+    return { callbacks: [...callbacks], incomplete };
+}
+function isResultCallback(node) {
+    return (ts.isArrowFunction(node) ||
+        ts.isFunctionExpression(node) ||
+        ts.isFunctionDeclaration(node) ||
+        ts.isMethodDeclaration(node) ||
+        ts.isGetAccessorDeclaration(node) ||
+        ts.isSetAccessorDeclaration(node));
+}
+function resolveStaticComposeProjection(member, compose, builder) {
+    const key = ts.isPropertyAccessExpression(member)
+        ? member.name.text
+        : staticMemberKey(member.argumentExpression);
+    const base = resolveComposeValueNode(member.expression, compose, builder, new Set());
+    if (base.kind !== 'value')
+        return base;
+    if (key === undefined)
+        return { kind: 'ambiguous' };
+    return projectStaticMember(base.node, key, compose, builder, new Set());
+}
+function resolveComposeValueNode(node, compose, builder, seen) {
+    if (seen.has(node) || seen.size >= 64)
+        return { kind: 'ambiguous' };
+    seen.add(node);
+    if (ts.isExpression(node)) {
+        const value = unwrap(node);
+        if (value !== node)
+            return resolveComposeValueNode(value, compose, builder, seen);
+    }
+    if (ts.isIdentifier(node)) {
+        const binding = resolveComposeValueBinding(node, compose);
+        return binding.kind === 'value'
+            ? resolveComposeValueNode(binding.node, compose, builder, seen)
+            : binding;
+    }
+    if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+        const key = ts.isPropertyAccessExpression(node)
+            ? node.name.text
+            : staticMemberKey(node.argumentExpression);
+        const base = resolveComposeValueNode(node.expression, compose, builder, seen);
+        if (base.kind !== 'value')
+            return base;
+        if (key === undefined)
+            return { kind: 'ambiguous' };
+        const projected = projectStaticMember(base.node, key, compose, builder, seen);
+        return projected.kind === 'value'
+            ? resolveComposeValueNode(projected.node, compose, builder, seen)
+            : projected;
+    }
+    return { kind: 'value', node };
+}
+function projectStaticMember(node, key, compose, builder, seen) {
+    const value = ts.isExpression(node) ? unwrap(node) : node;
+    if (ts.isObjectLiteralExpression(value)) {
+        let candidate;
+        let uncertain = false;
+        for (const property of value.properties) {
+            if (ts.isSpreadAssignment(property)) {
+                const spread = resolveComposeValueNode(property.expression, compose, builder, seen);
+                if (spread.kind === 'value') {
+                    const projected = projectStaticMember(spread.node, key, compose, builder, seen);
+                    if (projected.kind === 'value') {
+                        candidate = projected.node;
+                        uncertain = false;
+                    }
+                    else if (projected.kind === 'ambiguous' || projected.kind === 'opaque') {
+                        uncertain = true;
+                    }
+                }
+                else {
+                    uncertain = true;
+                }
+                continue;
+            }
+            const propertyKey = 'name' in property ? staticPropertyKey(property.name) : undefined;
+            if (propertyKey === undefined) {
+                if ('name' in property && property.name && ts.isComputedPropertyName(property.name)) {
+                    uncertain = true;
+                }
+                continue;
+            }
+            if (propertyKey !== key)
+                continue;
+            if (ts.isPropertyAssignment(property))
+                candidate = property.initializer;
+            else if (ts.isShorthandPropertyAssignment(property))
+                candidate = property.name;
+            else if (ts.isMethodDeclaration(property) ||
+                ts.isGetAccessorDeclaration(property) ||
+                ts.isSetAccessorDeclaration(property)) {
+                candidate = property;
+            }
+            uncertain = false;
+        }
+        if (uncertain)
+            return { kind: 'ambiguous' };
+        return candidate ? { kind: 'value', node: candidate } : { kind: 'none' };
+    }
+    if (ts.isArrayLiteralExpression(value)) {
+        const index = Number(key);
+        if (!Number.isInteger(index) || index < 0)
+            return { kind: 'opaque' };
+        let offset = 0;
+        for (const element of value.elements) {
+            if (ts.isSpreadElement(element))
+                return { kind: 'ambiguous' };
+            if (offset === index) {
+                return ts.isOmittedExpression(element) ? { kind: 'none' } : { kind: 'value', node: element };
+            }
+            offset += 1;
+        }
+        return { kind: 'none' };
+    }
+    return { kind: 'ambiguous' };
+}
+function staticMemberKey(expression) {
+    if (!expression)
+        return undefined;
+    const value = unwrap(expression);
+    return ts.isStringLiteral(value) ||
+        ts.isNoSubstitutionTemplateLiteral(value) ||
+        ts.isNumericLiteral(value)
+        ? value.text
+        : undefined;
+}
+function staticPropertyKey(name) {
+    if (!name)
+        return undefined;
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) {
+        return name.text;
+    }
+    return ts.isComputedPropertyName(name) ? staticMemberKey(name.expression) : undefined;
+}
+function resolveComposeValueBinding(reference, compose) {
+    let current = reference.parent;
+    while (current && current !== compose) {
+        if ((ts.isClassExpression(current) || ts.isClassDeclaration(current)) &&
+            current.name?.text === reference.text) {
+            return { kind: 'opaque' };
+        }
+        if (ts.isFunctionLike(current) && current !== compose) {
+            if (current.parameters.some(({ name }) => bindingContains(name, reference.text))) {
+                return { kind: 'opaque' };
+            }
+            if ('name' in current &&
+                current.name &&
+                ts.isIdentifier(current.name) &&
+                current.name.text === reference.text) {
+                return { kind: 'opaque' };
+            }
+        }
+        if (ts.isCatchClause(current) &&
+            current.variableDeclaration &&
+            bindingContains(current.variableDeclaration.name, reference.text)) {
+            return { kind: 'opaque' };
+        }
+        if ((ts.isForStatement(current) ||
+            ts.isForInStatement(current) ||
+            ts.isForOfStatement(current)) &&
+            current.initializer &&
+            ts.isVariableDeclarationList(current.initializer) &&
+            current.initializer.flags & ts.NodeFlags.BlockScoped) {
+            const resolution = bindingFromDeclarations(current.initializer.declarations, reference);
+            if (resolution.kind !== 'none')
+                return resolution;
+        }
+        if (ts.isBlock(current) || ts.isModuleBlock(current) || ts.isCaseBlock(current)) {
+            const statements = ts.isCaseBlock(current)
+                ? current.clauses.flatMap((clause) => [...clause.statements])
+                : [...current.statements];
+            const declarations = declarationsInScope(statements, current === compose.body, reference.text);
+            const resolution = bindingFromNodes(declarations, reference);
+            if (resolution.kind !== 'none')
+                return resolution;
+        }
+        current = current.parent;
+    }
+    const ownerBindings = [];
+    visitOwnBody(compose, (node) => {
+        if (ts.isVariableDeclaration(node) &&
+            ts.isVariableDeclarationList(node.parent) &&
+            !(node.parent.flags & ts.NodeFlags.BlockScoped) &&
+            bindingContains(node.name, reference.text)) {
+            ownerBindings.push(node);
+        }
+    });
+    if (compose.body && ts.isBlock(compose.body)) {
+        for (const statement of compose.body.statements) {
+            if (ts.isFunctionDeclaration(statement) && statement.name?.text === reference.text) {
+                ownerBindings.push(statement);
+            }
+        }
+    }
+    const ownerBinding = bindingFromNodes(ownerBindings, reference);
+    if (ownerBinding.kind !== 'none')
+        return ownerBinding;
+    if (compose.parameters.some(({ name }) => bindingContains(name, reference.text))) {
+        return { kind: 'opaque' };
+    }
+    return { kind: 'none' };
+}
+function declarationsInScope(statements, includeVar, name) {
+    const declarations = [];
+    for (const statement of statements) {
+        if (ts.isVariableStatement(statement)) {
+            if (statement.declarationList.flags & ts.NodeFlags.BlockScoped) {
+                for (const declaration of statement.declarationList.declarations) {
+                    if (bindingContains(declaration.name, name))
+                        declarations.push(declaration);
+                }
+            }
+        }
+        else if (((!includeVar && ts.isFunctionDeclaration(statement)) ||
+            ts.isClassDeclaration(statement) ||
+            ts.isEnumDeclaration(statement) ||
+            ts.isModuleDeclaration(statement)) &&
+            statement.name?.text === name) {
+            declarations.push(statement);
+        }
+    }
+    return declarations;
+}
+function bindingFromDeclarations(declarations, reference) {
+    return bindingFromNodes(declarations.filter(({ name }) => bindingContains(name, reference.text)), reference);
+}
+function bindingFromNodes(declarations, reference) {
+    if (declarations.length === 0)
+        return { kind: 'none' };
+    const values = [];
+    let opaque = false;
+    for (const declaration of declarations) {
+        if (ts.isFunctionDeclaration(declaration)) {
+            values.push(declaration);
+        }
+        else if (ts.isVariableDeclaration(declaration)) {
+            if (!ts.isIdentifier(declaration.name))
+                return { kind: 'ambiguous' };
+            if (!declaration.initializer) {
+                opaque = true;
+            }
+            else if (declaration.pos > reference.pos) {
+                return { kind: 'ambiguous' };
+            }
+            else {
+                values.push(declaration.initializer);
+            }
+        }
+        else {
+            opaque = true;
+        }
+    }
+    if (values.length > 1)
+        return { kind: 'ambiguous' };
+    if (values.length === 1)
+        return { kind: 'value', node: values[0] };
+    return { kind: opaque ? 'opaque' : 'none' };
+}
+function writeTargetReferencesBuilder(node, builder) {
+    const target = ts.isExpression(node) ? unwrap(node) : node;
+    if (ts.isIdentifier(target))
+        return isComposeBuilderReference(target, builder);
+    if (ts.isBindingElement(target)) {
+        return writeTargetReferencesBuilder(target.name, builder);
+    }
+    if (ts.isArrayBindingPattern(target) || ts.isObjectBindingPattern(target)) {
+        return target.elements.some((element) => writeTargetReferencesBuilder(element, builder));
+    }
+    if (ts.isBinaryExpression(target) && isAssignmentOperator(target.operatorToken.kind)) {
+        return writeTargetReferencesBuilder(target.left, builder);
+    }
+    if (ts.isPropertyAccessExpression(target) || ts.isElementAccessExpression(target)) {
+        return writeTargetReferencesBuilder(target.expression, builder);
+    }
+    if (ts.isArrayLiteralExpression(target)) {
+        return target.elements.some((element) => ts.isSpreadElement(element)
+            ? writeTargetReferencesBuilder(element.expression, builder)
+            : writeTargetReferencesBuilder(element, builder));
+    }
+    if (ts.isObjectLiteralExpression(target)) {
+        return target.properties.some((property) => {
+            if (ts.isShorthandPropertyAssignment(property)) {
+                return isComposeBuilderReference(property.name, builder);
+            }
+            if (ts.isPropertyAssignment(property)) {
+                return writeTargetReferencesBuilder(property.initializer, builder);
+            }
+            if (ts.isSpreadAssignment(property)) {
+                return writeTargetReferencesBuilder(property.expression, builder);
+            }
+            return false;
+        });
+    }
+    return false;
+}
+function isComposeBuilderReference(reference, builder) {
+    return Boolean((builder.root && referencesComposeBinding(reference, builder.root, builder.owner)) ||
+        (builder.query && referencesComposeBinding(reference, builder.query, builder.owner)) ||
+        (builder.union && referencesComposeBinding(reference, builder.union, builder.owner)) ||
+        (builder.combine && referencesComposeBinding(reference, builder.combine, builder.owner)));
+}
+function statementShadowsComposeBinding(statement, name, scope, owner) {
+    if (ts.isVariableStatement(statement)) {
+        return declarationListShadowsComposeBinding(statement.declarationList, name, scope, owner);
+    }
+    if (ts.isFunctionDeclaration(statement)) {
+        return scope !== owner.body && statement.name?.text === name;
+    }
+    return Boolean((ts.isClassDeclaration(statement) ||
+        ts.isEnumDeclaration(statement) ||
+        ts.isModuleDeclaration(statement)) &&
+        statement.name?.text === name);
+}
+function declarationListShadowsComposeBinding(declarations, name, scope, owner) {
+    if (!declarations.declarations.some((declaration) => bindingContains(declaration.name, name))) {
+        return false;
+    }
+    return (Boolean(declarations.flags & ts.NodeFlags.BlockScoped) || enclosingFunction(scope) !== owner);
+}
+function isOwnerFunctionVar(declarations, owner) {
+    return (!(declarations.flags & ts.NodeFlags.BlockScoped) && enclosingFunction(declarations) === owner);
+}
+function enclosingFunction(node) {
+    let current = node.parent;
+    while (current && !ts.isFunctionLike(current))
+        current = current.parent;
+    return current;
+}
+function bindingContains(binding, name) {
+    if (ts.isIdentifier(binding))
+        return binding.text === name;
+    return binding.elements.some((element) => !ts.isOmittedExpression(element) && bindingContains(element.name, name));
+}
+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 isCompositeLeaf(expression, file) {
+    if (!expression || !ts.isIdentifier(unwrap(expression)))
+        return false;
+    const name = unwrap(expression).text;
+    let composite = false;
+    visit(file.source, (node) => {
+        if (!ts.isVariableDeclaration(node) ||
+            !ts.isIdentifier(node.name) ||
+            node.name.text !== name ||
+            !node.initializer)
+            return;
+        const value = unwrap(node.initializer);
+        if (!ts.isCallExpression(value))
+            return;
+        const factory = unwrap(value.expression);
+        if (ts.isCallExpression(factory)) {
+            composite = importedSymbol(file, factory.expression)?.name === 'defineCompositeQuery';
+            return;
+        }
+        if (!ts.isPropertyAccessExpression(factory))
+            return;
+        const member = factory;
+        composite =
+            member.name.text === 'composite' &&
+                importedSymbol(file, member.expression)?.name === 'defineQuery';
+    });
+    return composite;
+}