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

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

@@ -14,6 +14,7 @@ export const mutationRules = [
             const targets = [];
             for (const file of production(project, 'mutations')) {
                 const builderScopes = mutationBuilderScopes(file);
+                const handles = handleParameters(file);
                 visit(file.source, (node) => {
                     if (!ts.isCallExpression(node))
                         return;
@@ -25,11 +26,11 @@ export const mutationRules = [
                         return;
                     const input = staticObject(node.arguments[0]);
                     const selectedClass = input && assignedValue(input, 'class');
-                    const target = selectedClass && dependencyClassTarget(selectedClass);
+                    const target = selectedClass && dependencyClassTarget(selectedClass, handles);
                     if (selectedClass !== undefined && target !== undefined) {
                         targets.push({ file, node: selectedClass, ...target, operation: classOperation });
                     }
-                    else if (selectedClass && expressionSelectsDependency(selectedClass)) {
+                    else if (selectedClass && expressionSelectsDependency(selectedClass, handles)) {
                         evidence.push(ambiguity(file, selectedClass, 'Mutation plan selects a foreign Class dynamically, so its Domain requirement cannot be proven.'));
                     }
                 });
@@ -97,6 +98,7 @@ export const mutationRules = [
             const machineProperties = machinePropertiesByClass(project);
             for (const file of production(project, 'mutations')) {
                 const builderScopes = mutationBuilderScopes(file);
+                const handles = handleParameters(file);
                 visit(file.source, (node) => {
                     if (!ts.isCallExpression(node) ||
                         mutationBuilderMember(node, builderScopes) !== 'createNode') {
@@ -109,7 +111,7 @@ export const mutationRules = [
                         }
                         return;
                     }
-                    const selectedClass = propertiesForClass(input, machineProperties);
+                    const selectedClass = propertiesForClass(input, machineProperties, handles);
                     if (selectedClass.kind === 'ambiguous') {
                         evidence.push(ambiguity(file, assignedValue(input, 'class') ?? input, 'Mutation createNode Class has no statically resolvable Schema owner.'));
                         return;
@@ -170,6 +172,7 @@ export const mutationRules = [
             const machineProperties = machinePropertiesByClass(project);
             for (const file of production(project, 'mutations')) {
                 const builderScopes = mutationBuilderScopes(file);
+                const handles = handleParameters(file);
                 visit(file.source, (node) => {
                     if (!ts.isCallExpression(node))
                         return;
@@ -184,7 +187,7 @@ export const mutationRules = [
                             evidence.push(ambiguity(file, node, 'Mutation updateNode input is dynamic and may bypass a StateMachine transition.'));
                             return;
                         }
-                        const selectedClass = propertiesForClass(input, machineProperties);
+                        const selectedClass = propertiesForClass(input, machineProperties, handles);
                         if (selectedClass.kind === 'ambiguous') {
                             evidence.push(ambiguity(file, assignedValue(input, 'class') ?? input, 'Mutation updateNode Class has no statically resolvable Schema owner.'));
                             return;
@@ -265,7 +268,7 @@ export const mutationRules = [
                             evidence.push(violation(file, input, `StateMachine transition has no ${required} intent.`));
                         }
                     }
-                    const selectedClass = propertiesForClass(input, machineProperties);
+                    const selectedClass = propertiesForClass(input, machineProperties, handles);
                     if (selectedClass.kind === 'ambiguous') {
                         evidence.push(ambiguity(file, assignedValue(input, 'class') ?? input, 'StateMachine transition Class has no statically resolvable Schema owner.'));
                     }
@@ -305,8 +308,8 @@ export const mutationRules = [
                         evidence.push(violation(file, object, 'Mutation definition has no build callback.'));
                         continue;
                     }
-                    if (build.parameters.length < 2) {
-                        evidence.push(violation(file, build, 'Mutation build has no callback-scoped builder as its second parameter.'));
+                    if (builderParameter(definition, build) === undefined) {
+                        evidence.push(violation(file, build, `Mutation build has no callback-scoped builder as its ${definition.id === undefined ? 'second' : 'third'} parameter.`));
                     }
                     if (returnedValues(build) > 0) {
                         evidence.push(violation(file, build, 'Mutation build returns a value.'));
@@ -350,7 +353,7 @@ export const mutationRules = [
                     const build = object && callback(object, 'build');
                     if (!build)
                         continue;
-                    const builderName = build.parameters[1]?.name;
+                    const builderName = builderParameter(definition, build)?.name;
                     if (!builderName || !ts.isIdentifier(builderName)) {
                         evidence.push(ambiguity(file, build, 'Mutation build builder parameter is not an identifier.'));
                         continue;
@@ -405,7 +408,7 @@ export const mutationRules = [
                     const build = object && callback(object, 'build');
                     if (!build)
                         continue;
-                    const builderName = build.parameters[1]?.name;
+                    const builderName = builderParameter(definition, build)?.name;
                     visitOwnBody(build, (node) => {
                         if (!ts.isCallExpression(node))
                             return;
@@ -516,7 +519,7 @@ function mutationBuilderScopes(file) {
         if (definition.origin !== 'resolved')
             continue;
         const build = definition.object && callback(definition.object, 'build');
-        const builder = build?.parameters[1]?.name;
+        const builder = build && builderParameter(definition, build)?.name;
         if (build && builder && ts.isIdentifier(builder))
             add(build, builder);
     }
@@ -537,7 +540,7 @@ function mutationBuilderScopes(file) {
             continue;
         }
         for (const [imported, local] of sourceImport.bindings) {
-            if (imported === 'RichMutationBuilder')
+            if (imported === 'RichMutationBuilder' || imported === 'RecipeMutationBuilder')
                 richBuilderTypes.add(local);
         }
     }
@@ -659,7 +662,14 @@ function classOperationForBuilder(operation) {
             return undefined;
     }
 }
-function dependencyClassTarget(expression) {
+function dependencyClassTarget(expression, handles) {
+    // A recipe names a dependency's Class by its handle, `d.<alias>.<Class>`.
+    const path = handlePath(expression, handles);
+    if (path !== undefined) {
+        return path.length === 2 && !OWN_HANDLES.has(path[0])
+            ? { dependency: path[0], className: path[1] }
+            : undefined;
+    }
     const chain = staticPropertyChain(expression);
     if (!chain)
         return undefined;
@@ -670,10 +680,105 @@ function dependencyClassTarget(expression) {
     }
     return { dependency: suffix[dependency + 1], className: suffix[dependency + 3] };
 }
-function expressionSelectsDependency(expression) {
+function expressionSelectsDependency(expression, handles) {
+    const root = firstIdentifier(unwrap(expression));
+    // A handle the source does not name statically, `d[alias]`, may be a dependency's.
+    if (root !== undefined && handlePath(root, handles) !== undefined)
+        return handlePath(expression, handles) === undefined;
     const chain = staticPropertyChain(expression);
     return chain?.includes('dependencies') ?? false;
 }
+/** The handles of `d` that are not dependency aliases (S1). */
+const OWN_HANDLES = new Set(['kernel', 'core', 'origin', 'document']);
+function handleParameters(file) {
+    const parameters = new Set();
+    for (const definition of definitionObjects(file, 'defineMutation')) {
+        if (definition.origin !== 'resolved' || definition.id === undefined)
+            continue;
+        const build = definition.object && callback(definition.object, 'build');
+        const parameter = build?.parameters[1];
+        if (parameter !== undefined)
+            parameters.add(parameter);
+    }
+    const handleTypes = new Set();
+    for (const sourceImport of file.imports) {
+        if (sourceImport.specifier !== '@astrale-os/sdk' &&
+            sourceImport.specifier !== '@astrale-os/sdk/query')
+            continue;
+        for (const [imported, local] of sourceImport.bindings)
+            if (imported === 'Handles')
+                handleTypes.add(local);
+    }
+    if (handleTypes.size > 0)
+        visit(file.source, (node) => {
+            if (ts.isParameter(node) &&
+                node.type !== undefined &&
+                ts.isTypeReferenceNode(node.type) &&
+                ts.isIdentifier(node.type.typeName) &&
+                handleTypes.has(node.type.typeName.text))
+                parameters.add(node);
+        });
+    return parameters;
+}
+/**
+ * The handle a recipe's expression names, as its path from `d`: `d.Item` and a destructured
+ * `{ Item }` are `['Item']`, `d.directory.Person` is `['directory', 'Person']`. Undefined for an
+ * expression that does not start from the handles, or not statically.
+ */
+function handlePath(expression, handles, seen = new Set()) {
+    const value = unwrap(expression);
+    if (handles.size === 0)
+        return undefined;
+    if (ts.isIdentifier(value) && !seen.has(value.text)) {
+        const initializer = visibleConstInitializer(value);
+        if (initializer !== undefined)
+            return handlePath(initializer, handles, new Set([...seen, value.text]));
+    }
+    const chain = propertyChain(value);
+    const root = firstIdentifier(value);
+    const binding = root && identifierDeclaration(root);
+    const prefix = binding && bindingPath(binding, handles, seen);
+    return chain && prefix && [...prefix, ...chain.slice(1)];
+}
+/**
+ * The path of a binding from the handles: `{ directory: { Person } }` binds `Person` at
+ * `['directory', 'Person']`, in a handles parameter or in a constant the handles initialize,
+ * `const { directory } = d`.
+ */
+function bindingPath(binding, handles, seen) {
+    const path = [];
+    let current = binding;
+    while (ts.isBindingElement(current.parent)) {
+        const element = current.parent;
+        const name = element.propertyName ?? element.name;
+        if (!ts.isObjectBindingPattern(element.parent) ||
+            element.dotDotDotToken ||
+            !(ts.isIdentifier(name) || ts.isStringLiteral(name)))
+            return undefined;
+        path.unshift(name.text);
+        current = element.parent;
+    }
+    const declaration = current.parent;
+    if (declaration !== undefined &&
+        ts.isVariableDeclaration(declaration) &&
+        declaration.name === current &&
+        declaration.initializer !== undefined &&
+        (declaration.parent.flags & ts.NodeFlags.Const) !== 0 &&
+        !seen.has(binding.text)) {
+        const prefix = handlePath(declaration.initializer, handles, new Set([...seen, binding.text]));
+        return prefix && [...prefix, ...path];
+    }
+    return declaration !== undefined &&
+        ts.isParameter(declaration) &&
+        declaration.name === current &&
+        handles.has(declaration)
+        ? path
+        : undefined;
+}
+/** The builder a Mutation's `build` receives: second in the closure form, third in a recipe. */
+function builderParameter(definition, build) {
+    return build.parameters[definition.id === undefined ? 1 : 2];
+}
 function kernelProvisionCall(call) {
     const chain = propertyChain(call.expression);
     if (chain?.length === 4 &&
@@ -1180,9 +1285,9 @@ function containingVariableName(node) {
     }
     return undefined;
 }
-function propertiesForClass(input, properties) {
+function propertiesForClass(input, properties, handles) {
     const selectedClass = assignedValue(input, 'class');
-    const selection = selectedClass && selectedClassNames(selectedClass);
+    const selection = selectedClass && selectedClassNames(selectedClass, handles);
     if (selection === undefined || !closedClassSelection(selection, properties)) {
         return { kind: 'ambiguous' };
     }
@@ -1205,13 +1310,17 @@ function propertiesForClass(input, properties) {
     }
     return hasMachineProperty ? { kind: 'resolved', properties: resolved } : { kind: 'absent' };
 }
-function selectedClassNames(expression, seen = new Set()) {
+function selectedClassNames(expression, handles, seen = new Set()) {
     const value = unwrap(expression);
     if (ts.isConditionalExpression(value)) {
-        const whenTrue = selectedClassNames(value.whenTrue, seen);
-        const whenFalse = selectedClassNames(value.whenFalse, seen);
+        const whenTrue = selectedClassNames(value.whenTrue, handles, seen);
+        const whenFalse = selectedClassNames(value.whenFalse, handles, seen);
         return whenTrue && whenFalse ? new Set([...whenTrue, ...whenFalse]) : undefined;
     }
+    // A recipe names its Class by its handle: the last segment of its path from `d`.
+    const path = handlePath(value, handles);
+    if (path !== undefined)
+        return path.length > 0 ? new Set([path.at(-1)]) : undefined;
     if (ts.isIdentifier(value)) {
         if (seen.has(value.text))
             return undefined;
@@ -1219,7 +1328,7 @@ function selectedClassNames(expression, seen = new Set()) {
         if (initializer !== undefined) {
             const next = new Set(seen);
             next.add(value.text);
-            return selectedClassNames(initializer, next);
+            return selectedClassNames(initializer, handles, next);
         }
     }
     const chain = staticPropertyChain(value);

package/dist/tooling/linter/implementations/source/policy-edges.d.ts

@@ -0,0 +1,2 @@
+import type { SourceRuleVerifier } from './verifier.js';
+export declare const policyEdgeRules: readonly SourceRuleVerifier[];

package/dist/tooling/linter/implementations/source/policy-edges.js

@@ -0,0 +1,113 @@
+import ts from 'typescript';
+import { declarationOf, unwrap, visit, } from '../../adapters/typescript/index.js';
+import { production, propertyExpression, violation } from './shared.js';
+export const policyEdgeRules = [
+    {
+        id: 'SCH-EDGE-KEY-ORDER',
+        ruleRevision: '7377f52e7387d618840c7a6d520b317c7eda63348c84b86cfc1e389fe5db10b5',
+        evaluate(project) {
+            return production(project, 'schema').flatMap((file) => edgeOrderEvidence(project, file));
+        },
+    },
+];
+/**
+ * Each Policy `edge(Class, { [role]: term })` whose ends list another role before the source's. A
+ * Class whose source role is not statically visible, or ends that are not plain keys, prove nothing.
+ */
+function edgeOrderEvidence(project, file) {
+    const evidence = [];
+    visit(file.source, (node) => {
+        if (!ts.isCallExpression(node) || !isPolicyEdge(node.expression))
+            return;
+        const [edgeClass, ends] = node.arguments;
+        const object = ends && unwrap(ends);
+        if (!edgeClass || !object || !ts.isObjectLiteralExpression(object))
+            return;
+        const roles = endRoles(object);
+        const source = roles && sourceRole(project, file, edgeClass);
+        if (!roles || source === undefined || roles[0] === source || !roles.includes(source))
+            return;
+        evidence.push(violation(file, object, `Policy edge(${edgeClass.getText(file.source)}, { ... }) lists ${roles[0]} first; write the source role ${source} first.`));
+    });
+    return evidence;
+}
+/** `edge` of a Policy context: destructured from a callback's parameter, or read off it. */
+function isPolicyEdge(expression) {
+    const callee = unwrap(expression);
+    if (ts.isPropertyAccessExpression(callee))
+        return (callee.name.text === 'edge' &&
+            ts.isIdentifier(callee.expression) &&
+            bindingOf(callee.expression) === 'parameter');
+    return ts.isIdentifier(callee) && bindingOf(callee) === 'edge';
+}
+/** How the nearest enclosing callback binds a name: as a parameter, or as its `edge` member. */
+function bindingOf(identifier) {
+    for (let current = identifier.parent; current; current = current.parent) {
+        if (!ts.isFunctionLike(current))
+            continue;
+        for (const { name } of current.parameters) {
+            if (ts.isIdentifier(name) && name.text === identifier.text)
+                return 'parameter';
+            if (!ts.isObjectBindingPattern(name))
+                continue;
+            for (const element of name.elements) {
+                if (!ts.isIdentifier(element.name) || element.name.text !== identifier.text)
+                    continue;
+                const key = element.propertyName ?? element.name;
+                return ts.isIdentifier(key) && key.text === 'edge' ? 'edge' : undefined;
+            }
+        }
+    }
+    return undefined;
+}
+/** The keys of the ends, in the order written; `undefined` when one is not a plain key. */
+function endRoles(object) {
+    const roles = [];
+    for (const property of object.properties) {
+        if (ts.isShorthandPropertyAssignment(property))
+            roles.push(property.name.text);
+        else if (ts.isPropertyAssignment(property) &&
+            (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)))
+            roles.push(property.name.text);
+        else
+            return undefined;
+    }
+    return roles;
+}
+/**
+ * The source role of an Edge Class, read from its declaration: the `as` of a directed Class's
+ * source, or of an undirected Class's first endpoint, which lowers to the source.
+ */
+function sourceRole(project, file, value) {
+    let reference = unwrap(value);
+    if (ts.isArrowFunction(reference) && !ts.isBlock(reference.body))
+        reference = unwrap(reference.body);
+    if (!ts.isIdentifier(reference))
+        return undefined;
+    const declaration = declarationOf(project, file, reference);
+    if (!declaration || !ts.isVariableDeclaration(declaration) || !declaration.initializer)
+        return undefined;
+    const call = unwrap(declaration.initializer);
+    if (!ts.isCallExpression(call))
+        return undefined;
+    const callee = unwrap(call.expression);
+    const input = call.arguments[0] && unwrap(call.arguments[0]);
+    if (!ts.isPropertyAccessExpression(callee) ||
+        !ts.isIdentifier(callee.expression) ||
+        callee.expression.text !== 'edgeClass' ||
+        !input ||
+        !ts.isObjectLiteralExpression(input))
+        return undefined;
+    if (callee.name.text === 'directed')
+        return roleOf(propertyExpression(input, 'source'));
+    if (callee.name.text !== 'undirected')
+        return undefined;
+    const endpoints = propertyExpression(input, 'endpoints');
+    return endpoints && ts.isArrayLiteralExpression(endpoints)
+        ? roleOf(endpoints.elements[0])
+        : undefined;
+}
+function roleOf(end) {
+    const role = end && ts.isObjectLiteralExpression(end) ? propertyExpression(end, 'as') : undefined;
+    return role && ts.isStringLiteralLike(role) ? role.text : undefined;
+}

package/dist/tooling/linter/implementations/source/recipes.d.ts

@@ -0,0 +1,2 @@
+import type { SourceRuleVerifier } from './verifier.js';
+export declare const recipeRules: readonly SourceRuleVerifier[];