@astrale-os/sdk 0.5.0-beta.2 → 0.5.0-beta.21

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

@@ -0,0 +1,3 @@
+import type { SourceProject } from '../../adapters/typescript/index.js';
+import type { RuleImplementation } from '../../evaluation/index.js';
+export declare const sourceRuleImplementations: readonly RuleImplementation<SourceProject>[];

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

@@ -0,0 +1,3 @@
+import { sourceImplementation } from './verifier.js';
+import { sourceRuleVerifiers } from './verifiers.js';
+export const sourceRuleImplementations = Object.freeze(sourceRuleVerifiers.map(sourceImplementation));

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

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

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

@@ -0,0 +1,40 @@
+import { resolveProjectImport } from '../../adapters/typescript/index.js';
+import { isForeignDomain, production, violation } from './shared.js';
+export const integrationRules = [
+    {
+        id: 'INT-PURE',
+        ruleRevision: '6eddaa070e097a15d194b09ebfeb8d21251c6682879e54a200efb91007742555',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'integrations')) {
+                for (const sourceImport of file.imports) {
+                    const target = resolveProjectImport(project, file, sourceImport.specifier);
+                    const allowedSchemaType = target?.layer === 'schema' && sourceImport.typeOnly;
+                    const allowedSibling = target?.layer === 'integrations';
+                    const allowedKernelType = sourceImport.typeOnly && sourceImport.specifier.startsWith('@astrale-os/kernel-');
+                    const forbiddenBoundary = executionBoundaryImport(sourceImport.specifier) ||
+                        isForeignDomain(sourceImport.specifier) ||
+                        concreteProviderImport(sourceImport.specifier) ||
+                        sourceImport.specifier.startsWith('@astrale-os/adapter-') ||
+                        (sourceImport.specifier.startsWith('@astrale-os/sdk') &&
+                            sourceImport.specifier !== '@astrale-os/sdk/integration') ||
+                        sourceImport.specifier.startsWith('@astrale-os/kernel-client');
+                    const allowedPortableType = sourceImport.typeOnly && !forbiddenBoundary;
+                    if (allowedSchemaType || allowedSibling || allowedKernelType || allowedPortableType) {
+                        continue;
+                    }
+                    if (target || forbiddenBoundary) {
+                        evidence.push(violation(file, sourceImport.node, `Integration imports boundary or concrete dependency ${sourceImport.specifier}.`));
+                    }
+                }
+            }
+            return evidence;
+        },
+    },
+];
+function concreteProviderImport(specifier) {
+    return /^(?:(?:stripe|twilio|openai)(?:$|\/)|@aws-sdk\/|@azure\/|@google-cloud\/)/.test(specifier);
+}
+function executionBoundaryImport(specifier) {
+    return /^(?:node:)?(?:child_process|cluster|dgram|dns(?:\/promises)?|fs(?:\/promises)?|http2?|https|net|process|readline(?:\/promises)?|repl|sqlite|timers(?:\/promises)?|tls|worker_threads)$/.test(specifier);
+}

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

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

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

@@ -0,0 +1,114 @@
+import ts from 'typescript';
+import { importedSymbol, propertyChain, resolveProjectImport, unwrap, visit, } from '../../adapters/typescript/index.js';
+import { ambiguity, definitionOriginAmbiguity, definitionObjects, forbiddenIoImport, production, propertyExpression, violation, } from './shared.js';
+const FORBIDDEN_LAYERS = new Set([
+    'integrations',
+    'actions',
+    'providers',
+    'mutations',
+    'queries',
+    'scripts',
+    'ui',
+    'views',
+    'workflows',
+]);
+export const migrationRules = [
+    {
+        id: 'MIG-EXACT-REVS',
+        ruleRevision: '2353d23e19e0afa948b8c8c15b906a2e1427622cea441001d7e28c6fea81c860',
+        evaluate(project) {
+            const evidence = [];
+            const origins = schemaOrigins(project);
+            for (const file of production(project, 'migrations')) {
+                for (const definition of definitionObjects(file, 'defineMigration')) {
+                    const uncertain = definitionOriginAmbiguity(file, definition, 'Migration definition');
+                    if (uncertain) {
+                        evidence.push(uncertain);
+                        continue;
+                    }
+                    const { call, object } = definition;
+                    if (!object) {
+                        evidence.push(ambiguity(file, call, 'Migration descriptor is not a static object literal.'));
+                        continue;
+                    }
+                    const from = propertyExpression(object, 'from');
+                    const to = propertyExpression(object, 'to');
+                    if (!from || !to) {
+                        evidence.push(violation(file, object, 'Migration must declare exactly one from and one to revision.'));
+                        continue;
+                    }
+                    const fromSchema = revisionSchema(file, from);
+                    const toSchema = revisionSchema(file, to);
+                    if (!fromSchema || !toSchema) {
+                        evidence.push(ambiguity(file, !fromSchema ? from : to, 'Migration revision is not one static schema.revision binding.'));
+                        continue;
+                    }
+                    if (fromSchema === toSchema) {
+                        evidence.push(violation(file, to, `Migration source and target are both ${toSchema}.`));
+                        continue;
+                    }
+                    const fromOrigin = origins.get(fromSchema);
+                    const toOrigin = origins.get(toSchema);
+                    if (!fromOrigin || !toOrigin) {
+                        evidence.push(ambiguity(file, object, `Cannot establish origins for ${fromSchema} and ${toSchema}.`));
+                    }
+                    else if (fromOrigin !== toOrigin) {
+                        evidence.push(violation(file, object, `Migration crosses Domain origins ${fromOrigin} and ${toOrigin}.`));
+                    }
+                }
+            }
+            return evidence;
+        },
+    },
+    {
+        id: 'MIG-DEDICATED-CTX',
+        ruleRevision: 'be6389211e5ac1c0a2805a45dbc394aace48167f462947edc1db47cb4d34bf1e',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'migrations')) {
+                for (const sourceImport of file.imports) {
+                    const target = resolveProjectImport(project, file, sourceImport.specifier);
+                    const layer = target?.layer ?? sourceImport.specifier.match(/^#([^/]+)\//)?.[1];
+                    if ((layer && FORBIDDEN_LAYERS.has(layer)) ||
+                        forbiddenIoImport(sourceImport.specifier) ||
+                        sourceImport.specifier.startsWith('@astrale-os/adapter-')) {
+                        evidence.push(violation(file, sourceImport.node, `Migration imports forbidden boundary ${sourceImport.specifier}.`));
+                    }
+                }
+            }
+            return evidence;
+        },
+    },
+];
+function revisionSchema(file, expression) {
+    const target = unwrap(expression);
+    if (!ts.isCallExpression(target) || target.arguments.length !== 1)
+        return undefined;
+    const chain = propertyChain(target.expression);
+    if (chain?.at(-1) !== 'revision')
+        return undefined;
+    const schema = unwrap(target.arguments[0]);
+    if (!ts.isIdentifier(schema))
+        return undefined;
+    const symbol = importedSymbol(file, schema);
+    return symbol?.name ?? schema.text;
+}
+function schemaOrigins(project) {
+    const result = new Map();
+    for (const file of production(project, 'schema')) {
+        visit(file.source, (node) => {
+            if (!ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name) || !node.initializer)
+                return;
+            const value = unwrap(node.initializer);
+            if (!ts.isCallExpression(value))
+                return;
+            const symbol = importedSymbol(file, value.expression);
+            if (symbol?.name !== 'defineSchema')
+                return;
+            const origin = value.arguments[0];
+            if (origin && ts.isStringLiteral(unwrap(origin)))
+                result.set(node.name.text, unwrap(origin).text);
+        });
+    }
+    return result;
+}

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

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

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

@@ -0,0 +1,178 @@
+import ts from 'typescript';
+import { importedSymbol, propertyChain, unwrap, visit } from '../../adapters/typescript/index.js';
+import { ambiguity, callback, definitionOriginAmbiguity, definitionObjects, forbiddenIoImport, hasForbiddenGlobalCall, production, returnedExpressions, violation, } from './shared.js';
+const FORBIDDEN_LAYERS = new Set(['integrations', 'actions', 'providers', 'queries', 'workflows']);
+const FORBIDDEN_CALLS = new Set(['invoke', 'query', 'retry', 'run', 'submit']);
+export const mutationRules = [
+    {
+        id: 'MUT-CANON',
+        ruleRevision: '02de3e2ece6aed702fd85bd16214f967cf74a516600247c4e6b1393139814c7a',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'mutations')) {
+                for (const definition of definitionObjects(file, 'defineMutation')) {
+                    const uncertain = definitionOriginAmbiguity(file, definition, 'Mutation definition');
+                    if (uncertain) {
+                        evidence.push(uncertain);
+                        continue;
+                    }
+                    const { call, object } = definition;
+                    if (!object) {
+                        evidence.push(ambiguity(file, call, 'Mutation definition is not a static object literal.'));
+                        continue;
+                    }
+                    const build = callback(object, 'build');
+                    if (!build) {
+                        evidence.push(violation(file, object, 'Mutation definition has no build callback.'));
+                        continue;
+                    }
+                    const returns = returnedExpressions(build);
+                    if (returns.length !== 1) {
+                        evidence.push(violation(file, build, `Mutation build exposes ${returns.length} author callbacks; expected one.`));
+                        continue;
+                    }
+                    const author = returns[0];
+                    if (!ts.isArrowFunction(author) && !ts.isFunctionExpression(author)) {
+                        evidence.push(ts.isIdentifier(author)
+                            ? ambiguity(file, author, 'MutationAuthor helper cannot be proven from the local callback body.')
+                            : violation(file, author, 'Mutation build does not return an inline MutationAuthor callback.'));
+                        continue;
+                    }
+                    if (author.modifiers?.some(({ kind }) => kind === ts.SyntaxKind.AsyncKeyword)) {
+                        evidence.push(violation(file, author, 'MutationAuthor callback is async.'));
+                    }
+                    let nestedBuilds = 0;
+                    visit(author.body, (node) => {
+                        if (!ts.isCallExpression(node))
+                            return;
+                        const symbol = importedSymbol(file, node.expression);
+                        const chain = propertyChain(node.expression);
+                        if (symbol?.name === 'MutationAST' ||
+                            (chain?.includes('MutationAST') && chain.at(-1) === 'build')) {
+                            nestedBuilds += 1;
+                        }
+                    });
+                    if (nestedBuilds > 0) {
+                        evidence.push(violation(file, author, 'Mutation definition constructs a nested MutationAST.'));
+                    }
+                }
+            }
+            return evidence;
+        },
+    },
+    {
+        id: 'MUT-FRAGMENTS',
+        ruleRevision: '6102ea4dbe2e461ef38b98afcfbe28639f4f472ee6a83e44ce6aad7de3c3c7ef',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'mutations')) {
+                for (const definition of definitionObjects(file, 'defineMutation')) {
+                    const uncertain = definitionOriginAmbiguity(file, definition, 'Mutation definition');
+                    if (uncertain) {
+                        evidence.push(uncertain);
+                        continue;
+                    }
+                    const { object } = definition;
+                    const build = object && callback(object, 'build');
+                    const authorExpression = build && returnedExpressions(build)[0];
+                    if (!authorExpression ||
+                        (!ts.isArrowFunction(authorExpression) && !ts.isFunctionExpression(authorExpression)))
+                        continue;
+                    const builderName = authorExpression.parameters[0]?.name;
+                    if (!builderName || !ts.isIdentifier(builderName)) {
+                        evidence.push(ambiguity(file, authorExpression, 'MutationAuthor builder parameter is not an identifier.'));
+                        continue;
+                    }
+                    visitOwnBody(authorExpression, (node) => {
+                        if (ts.isReturnStatement(node) && node.expression) {
+                            evidence.push(violation(file, node, 'Mutation fragment author callback returns a value or escaped builder.'));
+                        }
+                        if (!ts.isCallExpression(node))
+                            return;
+                        const chain = propertyChain(node.expression);
+                        if (chain?.[0] === builderName.text)
+                            return;
+                        if (!referencesIdentifier(node.arguments, builderName.text))
+                            return;
+                        const first = node.arguments[0];
+                        if (!first ||
+                            !ts.isIdentifier(unwrap(first)) ||
+                            unwrap(first).text !== builderName.text) {
+                            evidence.push(violation(file, node, `Mutation fragment must receive ${builderName.text} as its first argument.`));
+                        }
+                    });
+                }
+            }
+            return evidence;
+        },
+    },
+    {
+        id: 'MUT-PURE',
+        ruleRevision: '0101d7edd7d34e69338aaec7129a14df40d3395b6a58b40265ccb5448e739170',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'mutations')) {
+                for (const sourceImport of file.imports) {
+                    const targetLayer = sourceImport.specifier.match(/^#([^/]+)\//)?.[1];
+                    if ((targetLayer && FORBIDDEN_LAYERS.has(targetLayer)) ||
+                        forbiddenIoImport(sourceImport.specifier) ||
+                        sourceImport.specifier.startsWith('@astrale-os/adapter-')) {
+                        evidence.push(violation(file, sourceImport.node, `Mutation imports effect boundary ${sourceImport.specifier}.`));
+                    }
+                }
+                for (const { node, name } of hasForbiddenGlobalCall(file)) {
+                    evidence.push(violation(file, node, `Mutation definition calls effectful global ${name}.`));
+                }
+                for (const definition of definitionObjects(file, 'defineMutation')) {
+                    const uncertain = definitionOriginAmbiguity(file, definition, 'Mutation definition');
+                    if (uncertain) {
+                        evidence.push(uncertain);
+                        continue;
+                    }
+                    const { object } = definition;
+                    const build = object && callback(object, 'build');
+                    if (!build)
+                        continue;
+                    visitOwnBody(build, (node) => {
+                        if (!ts.isCallExpression(node))
+                            return;
+                        const symbol = importedSymbol(file, node.expression);
+                        const chain = propertyChain(node.expression);
+                        const name = symbol?.name;
+                        if (name && FORBIDDEN_CALLS.has(name)) {
+                            evidence.push(violation(file, node, `Mutation definition invokes ${name}.`));
+                        }
+                        else if (!symbol &&
+                            chain &&
+                            chain.length > 1 &&
+                            FORBIDDEN_CALLS.has(chain.at(-1) ?? '')) {
+                            evidence.push(ambiguity(file, node, `Mutation call ${chain.join('.')} resembles an excluded operation but its receiver is opaque.`));
+                        }
+                    });
+                }
+            }
+            return evidence;
+        },
+    },
+];
+function referencesIdentifier(arguments_, name) {
+    let found = false;
+    for (const argument of arguments_) {
+        visit(argument, (node) => {
+            if (ts.isIdentifier(node) && node.text === name)
+                found = true;
+        });
+    }
+    return found;
+}
+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);
+}

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

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

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

@@ -0,0 +1,185 @@
+import ts from 'typescript';
+import { importedSymbol, propertyChain, resolveImportedSymbol, resolveProjectImport, unwrap, visit, } from '../../adapters/typescript/index.js';
+import { ambiguity, production, violation } from './shared.js';
+const LOCAL_DOMAIN_LAYERS = new Set([
+    'actions',
+    'mutations',
+    'queries',
+    'rules',
+    'schema',
+    'states',
+    'ui',
+    'views',
+    'workflows',
+]);
+const GRAPH_OPERATIONS = new Set(['mutate', 'query', 'invoke', 'defineAction', 'defineWorkflow']);
+export const providerRules = [
+    {
+        id: 'PRV-XDOM-TYPED',
+        ruleRevision: 'eed3bdf8393bdc61563adf18f0dba443c13ad1cd5ae88303676ed484dad74c41',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'providers')) {
+                visit(file.source, (node) => {
+                    if (ts.isCallExpression(node)) {
+                        const symbol = resolveImportedSymbol(file, node.expression);
+                        if (symbol.kind === 'resolved' &&
+                            symbol.name === 'bindDomain' &&
+                            isKernelClientModule(symbol.module) &&
+                            node.arguments.length < 2) {
+                            evidence.push(violation(file, node, 'Remote Domain binding omits the exact public Domain schema.'));
+                        }
+                    }
+                    if (ts.isAsExpression(node) &&
+                        node.type.kind === ts.SyntaxKind.NeverKeyword &&
+                        enclosingInvoke(node)) {
+                        evidence.push(violation(file, node, 'Remote Domain invocation fabricates a never cast instead of using the typed public facade.'));
+                    }
+                });
+            }
+            return evidence;
+        },
+    },
+    {
+        id: 'PRV-NO-DOMAIN',
+        ruleRevision: '5905f9e8fdd2130de52b41e2bbd920ada1ad9c04a71a04e79c98b1333c318e1b',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'providers')) {
+                for (const sourceImport of file.imports) {
+                    const target = resolveProjectImport(project, file, sourceImport.specifier);
+                    if (target?.layer && LOCAL_DOMAIN_LAYERS.has(target.layer)) {
+                        evidence.push(violation(file, sourceImport.node, `Provider imports local Domain layer ${target.layer}.`));
+                    }
+                }
+                visit(file.source, (node) => {
+                    if (!ts.isCallExpression(node))
+                        return;
+                    const chain = propertyChain(node.expression);
+                    const name = chain?.at(-1);
+                    if (name && GRAPH_OPERATIONS.has(name) && !remoteDomainInvoke(file, node)) {
+                        evidence.push(ambiguity(file, node, `Provider call ${chain?.join('.')} resembles a local Domain operation but its receiver is opaque.`));
+                    }
+                });
+            }
+            return evidence;
+        },
+    },
+];
+function remoteDomainInvoke(file, call) {
+    const expression = unwrap(call.expression);
+    if (!ts.isPropertyAccessExpression(expression) ||
+        expression.name.text !== 'invoke' ||
+        !ts.isIdentifier(unwrap(expression.expression))) {
+        return false;
+    }
+    const receiver = unwrap(expression.expression);
+    const binding = lexicalBinding(receiver);
+    return Boolean(binding.found && binding.type && isDomainBindingType(file, binding.type));
+}
+function lexicalBinding(identifier) {
+    let current = identifier.parent;
+    while (current) {
+        if (ts.isFunctionLike(current)) {
+            for (const parameter of current.parameters) {
+                if (ts.isIdentifier(parameter.name) && parameter.name.text === identifier.text) {
+                    return { found: true, ...(parameter.type ? { type: parameter.type } : {}) };
+                }
+                if (bindingContains(parameter.name, identifier.text))
+                    return { found: true };
+            }
+        }
+        if (ts.isCatchClause(current) &&
+            current.variableDeclaration &&
+            bindingContains(current.variableDeclaration.name, identifier.text)) {
+            return { found: true };
+        }
+        if (ts.isBlock(current) || ts.isSourceFile(current) || ts.isModuleBlock(current)) {
+            for (const statement of current.statements) {
+                const binding = statementBinding(statement, identifier.text);
+                if (binding.found)
+                    return binding;
+            }
+        }
+        if ((ts.isForStatement(current) ||
+            ts.isForInStatement(current) ||
+            ts.isForOfStatement(current)) &&
+            current.initializer &&
+            ts.isVariableDeclarationList(current.initializer)) {
+            for (const declaration of current.initializer.declarations) {
+                if (bindingContains(declaration.name, identifier.text)) {
+                    return { found: true, ...(declaration.type ? { type: declaration.type } : {}) };
+                }
+            }
+        }
+        current = current.parent;
+    }
+    return { found: false };
+}
+function statementBinding(statement, name) {
+    if (ts.isVariableStatement(statement)) {
+        for (const declaration of statement.declarationList.declarations) {
+            if (bindingContains(declaration.name, name)) {
+                return { found: true, ...(declaration.type ? { type: declaration.type } : {}) };
+            }
+        }
+    }
+    if (((ts.isFunctionDeclaration(statement) ||
+        ts.isClassDeclaration(statement) ||
+        ts.isEnumDeclaration(statement) ||
+        ts.isModuleDeclaration(statement)) &&
+        statement.name?.text === name) ||
+        (ts.isImportDeclaration(statement) && importDeclares(statement, name))) {
+        return { found: true };
+    }
+    return { found: false };
+}
+function importDeclares(statement, name) {
+    const clause = statement.importClause;
+    if (!clause)
+        return false;
+    if (clause.name?.text === name)
+        return true;
+    const bindings = clause.namedBindings;
+    if (bindings && ts.isNamespaceImport(bindings))
+        return bindings.name.text === name;
+    return Boolean(bindings && bindings.elements.some((element) => element.name.text === name));
+}
+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 isDomainBindingType(file, type) {
+    if (!ts.isTypeReferenceNode(type))
+        return false;
+    let module;
+    let name;
+    if (ts.isIdentifier(type.typeName)) {
+        const symbol = importedSymbol(file, type.typeName);
+        module = symbol?.module;
+        name = symbol?.name;
+    }
+    else if (ts.isQualifiedName(type.typeName) && ts.isIdentifier(type.typeName.left)) {
+        const namespaceName = type.typeName.left.text;
+        const sourceImport = file.imports.find(({ namespace }) => namespace === namespaceName);
+        module = sourceImport?.specifier;
+        name = type.typeName.right.text;
+    }
+    return Boolean(name === 'DomainBinding' && module && isKernelClientModule(module));
+}
+function isKernelClientModule(module) {
+    return module === '@astrale-os/shell';
+}
+function enclosingInvoke(node) {
+    let current = node.parent;
+    while (current && !ts.isStatement(current)) {
+        if (ts.isCallExpression(current)) {
+            const expression = unwrap(current.expression);
+            if (ts.isPropertyAccessExpression(expression) && expression.name.text === 'invoke')
+                return true;
+        }
+        current = current.parent;
+    }
+    return false;
+}

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

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