@astrale-os/sdk 0.5.0-beta.99 → 0.6.0-beta.0

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

@@ -0,0 +1,219 @@
+import ts from 'typescript';
+import { propertyChain, resolveImportedSymbol, unwrap, visit, } from '../../adapters/typescript/index.js';
+import { applicationFunctionRequirements, callableReference, callableSelector, declaredDomainDependencies, remoteCallableKey, } from './callable-requirements.js';
+import { ambiguity, calls, isForeignDomain, production, violation } from './shared.js';
+export const dependencyRules = [
+    {
+        id: 'FNC-XDOM-DECLARED',
+        ruleRevision: '269e22202a0fbec5ec4afc3579ca504eed457f44046b99e64a38d08634294909',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'functions')) {
+                for (const sourceImport of file.imports) {
+                    if (isForeignDomain(sourceImport.specifier))
+                        evidence.push(violation(file, sourceImport.node, `Handler imports foreign Domain ${sourceImport.specifier}; use declared dependencies or an Integration.`));
+                }
+            }
+            return [...evidence, ...observeInvocations(project).evidence];
+        },
+    },
+    {
+        id: 'FNC-XDOM-REQ',
+        ruleRevision: 'a646c9931bb8b5a011a2cf7431f362fcb0e63be49dfc4c1bc0eba77a8aca8fdb',
+        evaluate(project) {
+            const { targets, evidence } = observeInvocations(project);
+            const declared = applicationFunctionRequirements(project);
+            const results = evidence.filter(({ kind }) => kind === 'ambiguity');
+            for (const target of targets) {
+                if (declared.keys.has(remoteCallableKey(target)))
+                    continue;
+                results.push((declared.indeterminate ? ambiguity : violation)(target.file, target.node, `Remote Domain callable ${target.module} ${target.selector.join('.')} lacks one provable exact Application Function requirement.`));
+            }
+            return results;
+        },
+    },
+];
+function observeInvocations(project) {
+    const dependencies = declaredDomainDependencies(project);
+    const targets = [];
+    const evidence = [];
+    for (const file of production(project, 'functions')) {
+        for (const definition of [...calls(file, 'defineAction'), ...calls(file, 'defineWorkflow')]) {
+            if (definition.origin === 'ambiguous') {
+                evidence.push(ambiguity(file, definition.call, 'Handler definition resolves through a local facade whose ultimate public constructor origin is unknown.'));
+                continue;
+            }
+            const call = ts.isCallExpression(definition.call.parent) &&
+                definition.call.parent.expression === definition.call
+                ? definition.call.parent
+                : definition.call;
+            const candidate = call.arguments.length === 2
+                ? call.arguments[1]
+                : call.arguments.length === 3
+                    ? call.arguments[2]
+                    : undefined;
+            const run = candidate && unwrap(candidate);
+            if (!run || (!ts.isArrowFunction(run) && !ts.isFunctionExpression(run))) {
+                evidence.push(ambiguity(file, call, 'Handler run is not a static function.'));
+                continue;
+            }
+            visit(run.body, (node) => {
+                if (!ts.isCallExpression(node))
+                    return;
+                const path = contextPath(node.expression, run);
+                if (!path || path.at(-1) !== 'invoke')
+                    return;
+                if (path.includes('[computed]')) {
+                    evidence.push(ambiguity(file, node, 'Computed dependency invocation cannot be proven statically.'));
+                    return;
+                }
+                let alias;
+                let selector;
+                if (path[0] === 'dependencies') {
+                    if (path.length !== 4 || !['caller', 'self', 'union'].includes(path[2])) {
+                        evidence.push(violation(file, node, 'Dependency invocation requires one direct alias and one explicit caller, self, or union authority.'));
+                        return;
+                    }
+                    alias = path[1];
+                    selector = selectedCallable(node.arguments[0]);
+                }
+                else if (path[0] === 'kernel' &&
+                    (path.length === 2 ||
+                        (path.length === 3 && ['caller', 'self', 'union'].includes(path[1])))) {
+                    const argument = node.arguments[0];
+                    if (!argument) {
+                        evidence.push(violation(file, node, 'Kernel invocation requires one canonical typed reference.'));
+                        return;
+                    }
+                    const admitted = callableReference(unwrap(argument));
+                    let reference = admitted.expression;
+                    if (ts.isCallExpression(reference) && ts.isCallExpression(reference.expression))
+                        reference = reference.expression;
+                    if (!admitted.resolved) {
+                        evidence.push(ambiguity(file, node, 'Kernel invocation reference is opaque.'));
+                        return;
+                    }
+                    const symbol = ts.isCallExpression(reference)
+                        ? resolveImportedSymbol(file, reference.expression)
+                        : undefined;
+                    if (symbol?.kind !== 'resolved' ||
+                        symbol.module !== '@astrale-os/sdk/client/session' ||
+                        symbol.name !== 'reference' ||
+                        !ts.isCallExpression(reference)) {
+                        evidence.push(violation(file, node, 'Kernel invocation requires one canonical typed reference.'));
+                        return;
+                    }
+                    const domain = reference.arguments[0] && contextPath(reference.arguments[0], run);
+                    const callable = reference.arguments[1] && contextPath(reference.arguments[1], run);
+                    // Local typed Kernel invocations are outside cross-Domain requirement policy.
+                    if (domain?.length === 1 && domain[0] === 'domain')
+                        return;
+                    if (domain?.length === 3 &&
+                        domain[0] === 'domain' &&
+                        domain[1] === 'dependencies' &&
+                        callable &&
+                        domain.every((part, index) => part === callable[index])) {
+                        alias = domain[2];
+                        selector = callable.slice(3);
+                    }
+                }
+                else
+                    return;
+                if (!alias || !selector || !callableSelector(selector)) {
+                    evidence.push(ambiguity(file, node, 'Remote callable selector cannot be proven from one static selector or typed reference.'));
+                    return;
+                }
+                const module = dependencies.aliases.get(alias);
+                if (!module) {
+                    evidence.push((dependencies.indeterminate ? ambiguity : violation)(file, node, `Dependency alias ${alias} is not one declared public Domain dependency.`));
+                    return;
+                }
+                targets.push({ file, node, module, selector });
+            });
+        }
+    }
+    return { targets, evidence };
+}
+function selectedCallable(input) {
+    if (!input)
+        return undefined;
+    const admitted = callableReference(unwrap(input));
+    const selector = admitted.expression;
+    if (!admitted.resolved ||
+        (!ts.isArrowFunction(selector) && !ts.isFunctionExpression(selector)) ||
+        selector.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword))
+        return undefined;
+    const parameter = selector.parameters[0]?.name;
+    if (!parameter || !ts.isIdentifier(parameter))
+        return undefined;
+    let expression;
+    if (ts.isBlock(selector.body)) {
+        if (selector.body.statements.length === 1 && ts.isReturnStatement(selector.body.statements[0]))
+            expression = selector.body.statements[0].expression;
+    }
+    else
+        expression = selector.body;
+    const chain = expression && propertyChain(expression);
+    return chain && chain[0] === parameter.text ? chain.slice(1) : undefined;
+}
+/** Resolve handler context bindings and one immutable local alias without following arbitrary helpers. */
+function contextPath(input, run, aliases = 1) {
+    const expression = unwrap(input);
+    if (ts.isPropertyAccessExpression(expression)) {
+        const base = contextPath(expression.expression, run, aliases);
+        return base && [...base, expression.name.text];
+    }
+    if (ts.isElementAccessExpression(expression)) {
+        const base = contextPath(expression.expression, run, aliases);
+        return base && [...base, '[computed]'];
+    }
+    if (!ts.isIdentifier(expression))
+        return undefined;
+    let current = expression.parent;
+    while (current) {
+        if (ts.isFunctionLike(current)) {
+            for (const parameter of current.parameters) {
+                const path = bindingPath(parameter.name, expression.text);
+                if (path)
+                    return current === run && parameter === run.parameters[0] ? path : undefined;
+            }
+        }
+        if (ts.isBlock(current) || ts.isSourceFile(current)) {
+            for (const statement of current.statements) {
+                if (ts.isFunctionDeclaration(statement) && statement.name?.text === expression.text)
+                    return undefined;
+                if (!ts.isVariableStatement(statement))
+                    continue;
+                for (const declaration of statement.declarationList.declarations) {
+                    const path = bindingPath(declaration.name, expression.text);
+                    if (!path)
+                        continue;
+                    if (aliases === 0 ||
+                        !declaration.initializer ||
+                        declaration.end > expression.pos ||
+                        !(statement.declarationList.flags & ts.NodeFlags.Const))
+                        return undefined;
+                    const base = contextPath(declaration.initializer, run, aliases - 1);
+                    return base && [...base, ...path];
+                }
+            }
+        }
+        current = current.parent;
+    }
+    return undefined;
+}
+function bindingPath(name, identifier) {
+    if (ts.isIdentifier(name))
+        return name.text === identifier ? [] : undefined;
+    if (!ts.isObjectBindingPattern(name))
+        return undefined;
+    for (const element of name.elements) {
+        if (element.dotDotDotToken)
+            continue;
+        const nested = bindingPath(element.name, identifier);
+        const property = element.propertyName ?? (ts.isIdentifier(element.name) ? element.name : undefined);
+        if (nested && property && (ts.isIdentifier(property) || ts.isStringLiteral(property)))
+            return [property.text, ...nested];
+    }
+    return undefined;
+}

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

@@ -321,7 +321,7 @@ export const globalRules = [
                         (edge.kind === kind ||
                             (kind === 'type-only' &&
                                 (edge.kind === 'runtime' || edge.kind === 'composition'))))) {
-                        evidence.push(violation(file, sourceImport.node, `Import ${sourceImport.specifier} creates absent ${file.layer} -> ${target.layer} (${kind}) edge.`));
+                        evidence.push(violation(file, sourceImport.node, `Import ${sourceImport.specifier} creates absent ${file.layer} -> ${target.layer} (${kind}) edge. ${admittedDependencies(project, file.layer, target.layer)}`));
                     }
                 }
             }
@@ -626,7 +626,7 @@ export const globalRules = [
                             evidence.push(ambiguity(file, property, 'Schema dependency is not one statically aliased Domain facade.'));
                             continue;
                         }
-                        const symbol = importedSymbol(file, unwrap(element));
+                        const symbol = dependencySchemaSymbol(file, element);
                         if (symbol?.module === '@astrale-os/sdk/schema' && symbol.name === 'KernelSchema') {
                             continue;
                         }
@@ -678,6 +678,23 @@ export const globalRules = [
     },
 ];
 const STABLE_DEFINITION_ID = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+/**
+ * Name the admitted neighborhood of a rejected dependency edge. Rejection alone
+ * states that the import is wrong; the allowlist states which decomposition is
+ * expected, and the authored condition states why.
+ */
+function admittedDependencies(project, source, target) {
+    const admitted = project.policy.dependencies.filter((edge) => edge.source === source);
+    const admittedTarget = admitted.filter((edge) => edge.target === target);
+    if (admittedTarget.length > 0) {
+        const kinds = admittedTarget.map((edge) => `${edge.kind} (${edge.condition})`).join(', ');
+        return `Admitted ${source} -> ${target} kinds: ${kinds}.`;
+    }
+    if (admitted.length === 0)
+        return `No ${source} dependency is admitted.`;
+    const targets = admitted.map((edge) => `${edge.target} (${edge.kind})`).join(', ');
+    return `Admitted ${source} targets: ${targets}.`;
+}
 function rootEvidence(file, evidence) {
     return file ? violation(file, file.source, evidence) : { kind: 'violation', evidence };
 }
@@ -710,6 +727,39 @@ function isExternalPackage(specifier) {
         !specifier.startsWith('@astrale-os/kernel-core') &&
         !specifier.startsWith('@astrale-os/kernel-dsl'));
 }
+function dependencySchemaSymbol(file, expression) {
+    const target = unwrap(expression);
+    const direct = importedSymbol(file, target);
+    if (direct || !ts.isIdentifier(target))
+        return direct;
+    const declarations = file.source.statements.flatMap((statement) => {
+        if (!ts.isVariableStatement(statement) ||
+            !(statement.declarationList.flags & ts.NodeFlags.Const)) {
+            return [];
+        }
+        return statement.declarationList.declarations.filter((declaration) => ts.isIdentifier(declaration.name) && declaration.name.text === target.text);
+    });
+    if (declarations.length !== 1)
+        return undefined;
+    const initializer = declarations[0].initializer;
+    const accepted = initializer && unwrap(initializer);
+    if (!accepted ||
+        !ts.isCallExpression(accepted) ||
+        !ts.isPropertyAccessExpression(unwrap(accepted.expression))) {
+        return undefined;
+    }
+    const callee = unwrap(accepted.expression);
+    if (callee.name.text !== 'accept')
+        return undefined;
+    const owner = resolveImportedSymbol(file, callee.expression);
+    if (owner.kind !== 'resolved' ||
+        owner.name !== 'schema' ||
+        !schemaAuthoringModule(owner.module)) {
+        return undefined;
+    }
+    const admitted = accepted.arguments[0];
+    return admitted ? importedSymbol(file, unwrap(admitted)) : undefined;
+}
 function directKernelAuthoringImport(specifier) {
     return (specifier === '@astrale-os/kernel-core' ||
         specifier.startsWith('@astrale-os/kernel-core/') ||