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

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

@@ -0,0 +1,44 @@
+import ts from 'typescript';
+import type { SourceRuleEvidence } from './verifier.js';
+import { type SourceProject, type SourceFile, type SourceImport } from '../../adapters/typescript/index.js';
+export declare const SDK_MODULES: Set<string>;
+export declare const DSL_MODULES: Set<string>;
+export interface DefinitionObject {
+    readonly call: ts.CallExpression;
+    readonly object?: ts.ObjectLiteralExpression;
+    readonly projector?: ts.FunctionLikeDeclaration;
+    readonly origin: 'resolved' | 'ambiguous';
+}
+export declare function production(project: SourceProject, layer?: string): SourceFile[];
+export declare function calls(file: SourceFile, importedName: string, modules?: Set<string>): Array<{
+    readonly call: ts.CallExpression;
+    readonly origin: 'resolved' | 'ambiguous';
+}>;
+export declare function memberCalls(file: SourceFile, importedName: string, member: string, modules?: Set<string>): Array<{
+    readonly call: ts.CallExpression;
+    readonly origin: 'resolved' | 'ambiguous';
+}>;
+export declare function definitionObjects(file: SourceFile, importedName: string, member?: string, modules?: Set<string>, argumentIndex?: number): DefinitionObject[];
+export declare function definitionOriginAmbiguity(file: SourceFile, definition: DefinitionObject, name: string): SourceRuleEvidence | undefined;
+/** Prove the clean curried Domain projector shape for Query and Mutation recipes. */
+export declare function domainProjectorEvidence(file: SourceFile, importedName: 'defineCollectionQuery' | 'defineCompositeQuery' | 'defineMutation' | 'defineQuery', label: string): SourceRuleEvidence[];
+export declare function violation(file: SourceFile, node: ts.Node, evidence: string): SourceRuleEvidence;
+export declare function ambiguity(file: SourceFile, node: ts.Node, evidence: string): SourceRuleEvidence;
+export declare function localTarget(project: SourceProject, file: SourceFile, sourceImport: SourceImport): SourceFile | undefined;
+export declare function importedLayer(project: SourceProject, file: SourceFile, sourceImport: SourceImport): string | undefined;
+export declare function isForeignDomain(specifier: string): boolean;
+export declare function packageRoot(specifier: string): string;
+export declare function isDeepPackageImport(specifier: string): boolean;
+export declare function propertyExpression(object: ts.ObjectLiteralExpression | undefined, name: string): ts.Expression | undefined;
+export declare function callback(object: ts.ObjectLiteralExpression | undefined, name: string): ts.FunctionLikeDeclaration | undefined;
+export declare function returnedExpressions(fn: ts.FunctionLikeDeclaration): ts.Expression[];
+export declare function callChain(expression: ts.Expression): readonly string[] | undefined;
+export declare function staticId(expression: ts.Expression | undefined): string | undefined;
+export declare function hasForbiddenGlobalCall(file: SourceFile): Array<{
+    node: ts.Node;
+    name: string;
+}>;
+export declare function isLocallyBoundIdentifier(node: ts.Identifier): boolean;
+export declare function forbiddenIoImport(specifier: string): boolean;
+export declare function variableName(call: ts.CallExpression): string | undefined;
+export declare function allPropertyNames(object: ts.ObjectLiteralExpression): string[];

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

@@ -0,0 +1,319 @@
+import ts from 'typescript';
+import { importedSymbol, location, objectProperty, propertyChain, resolveImportedSymbol, resolveProjectImport, staticText, unwrap, visit, } from '../../adapters/typescript/index.js';
+export const SDK_MODULES = new Set([
+    '@astrale-os/sdk',
+    '@astrale-os/sdk/action',
+    '@astrale-os/sdk/integration',
+    '@astrale-os/sdk/query',
+    '@astrale-os/sdk/mutation',
+    '@astrale-os/sdk/state',
+    '@astrale-os/sdk/workflow',
+]);
+export const DSL_MODULES = new Set([
+    '@astrale-os/sdk/schema',
+    '@astrale-os/kernel-dsl',
+    '@astrale-os/kernel-dsl/v1',
+    '@astrale-os/kernel-core',
+]);
+const DOMAIN_BOUND_DEFINITIONS = new Set([
+    'defineCollectionQuery',
+    'defineCompositeQuery',
+    'defineMutation',
+    'defineQuery',
+]);
+export function production(project, layer) {
+    return project.files.filter((file) => file.role === 'production' && (layer === undefined || file.layer === layer));
+}
+export function calls(file, importedName, modules = SDK_MODULES) {
+    const result = [];
+    visit(file.source, (node) => {
+        if (!ts.isCallExpression(node))
+            return;
+        const symbol = resolveImportedSymbol(file, node.expression);
+        if (symbol.kind === 'resolved' && symbol.name === importedName && modules.has(symbol.module)) {
+            result.push({ call: node, origin: 'resolved' });
+        }
+        else if (symbol.kind === 'ambiguous' && symbol.name === importedName) {
+            result.push({ call: node, origin: 'ambiguous' });
+        }
+    });
+    return result;
+}
+export function memberCalls(file, importedName, member, modules = SDK_MODULES) {
+    const result = [];
+    visit(file.source, (node) => {
+        if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(unwrap(node.expression)))
+            return;
+        const expression = unwrap(node.expression);
+        if (expression.name.text !== member)
+            return;
+        const symbol = resolveImportedSymbol(file, expression.expression);
+        if (symbol.kind === 'resolved' && symbol.name === importedName && modules.has(symbol.module)) {
+            result.push({ call: node, origin: 'resolved' });
+        }
+        else if (symbol.kind === 'ambiguous' && symbol.name === importedName) {
+            result.push({ call: node, origin: 'ambiguous' });
+        }
+    });
+    return result;
+}
+export function definitionObjects(file, importedName, member, modules = SDK_MODULES, argumentIndex = 0) {
+    if (!member && DOMAIN_BOUND_DEFINITIONS.has(importedName)) {
+        return curriedCalls(file, importedName, modules).map(({ call, origin }) => {
+            const projector = callbackArgumentAt(call, argumentIndex);
+            return {
+                call,
+                origin,
+                projector,
+                object: projector && returnedObject(projector),
+            };
+        });
+    }
+    return (member ? memberCalls(file, importedName, member, modules) : calls(file, importedName, modules)).map(({ call, origin }) => ({ call, origin, object: objectArgumentAt(call, argumentIndex) }));
+}
+function curriedCalls(file, importedName, modules) {
+    const result = [];
+    visit(file.source, (node) => {
+        if (!ts.isCallExpression(node))
+            return;
+        const factory = unwrap(node.expression);
+        if (!ts.isCallExpression(factory))
+            return;
+        const symbol = resolveImportedSymbol(file, factory.expression);
+        if (symbol.kind === 'resolved' && symbol.name === importedName && modules.has(symbol.module)) {
+            result.push({ call: node, origin: 'resolved' });
+        }
+        else if (symbol.kind === 'ambiguous' && symbol.name === importedName) {
+            result.push({ call: node, origin: 'ambiguous' });
+        }
+    });
+    return result;
+}
+function callbackArgumentAt(call, index) {
+    const value = call.arguments[index];
+    if (!value)
+        return undefined;
+    const unwrapped = unwrap(value);
+    return ts.isArrowFunction(unwrapped) || ts.isFunctionExpression(unwrapped) ? unwrapped : undefined;
+}
+function returnedObject(projector) {
+    const returned = returnedExpressions(projector);
+    return returned.length === 1 && ts.isObjectLiteralExpression(unwrap(returned[0]))
+        ? unwrap(returned[0])
+        : undefined;
+}
+export function definitionOriginAmbiguity(file, definition, name) {
+    return definition.origin === 'ambiguous'
+        ? ambiguity(file, definition.call, `${name} resolves through a local facade whose ultimate public constructor origin is unknown.`)
+        : undefined;
+}
+/** Prove the clean curried Domain projector shape for Query and Mutation recipes. */
+export function domainProjectorEvidence(file, importedName, label) {
+    const evidence = [];
+    for (const candidate of calls(file, importedName)) {
+        if (candidate.origin === 'ambiguous')
+            continue;
+        const application = candidate.call.parent;
+        if (candidate.call.arguments.length !== 0 ||
+            !ts.isCallExpression(application) ||
+            unwrap(application.expression) !== candidate.call) {
+            evidence.push(violation(file, candidate.call, `${label} must use ${importedName}<typeof Schema>()((Domain) => ({ ... })).`));
+        }
+    }
+    for (const definition of definitionObjects(file, importedName)) {
+        if (definition.origin === 'ambiguous')
+            continue;
+        const projector = definition.projector;
+        if (!projector) {
+            evidence.push(ambiguity(file, definition.call, `${label} Domain projector is not statically visible.`));
+            continue;
+        }
+        if (projector.parameters.length > 1) {
+            evidence.push(violation(file, projector, `${label} Domain projector accepts more than one value.`));
+        }
+        const domain = projector.parameters[0]?.name;
+        if (domain && !ts.isIdentifier(domain)) {
+            evidence.push(ambiguity(file, domain, `${label} Domain projector does not bind one identifiable Domain.`));
+        }
+        if (projector.modifiers?.some(({ kind }) => kind === ts.SyntaxKind.AsyncKeyword)) {
+            evidence.push(violation(file, projector, `${label} Domain projector is async.`));
+        }
+        if ('asteriskToken' in projector && projector.asteriskToken) {
+            evidence.push(violation(file, projector, `${label} Domain projector is a generator.`));
+        }
+    }
+    return evidence;
+}
+function objectArgumentAt(call, index) {
+    const value = call.arguments[index];
+    return value && ts.isObjectLiteralExpression(unwrap(value))
+        ? unwrap(value)
+        : undefined;
+}
+export function violation(file, node, evidence) {
+    return { kind: 'violation', evidence, location: location(file, node) };
+}
+export function ambiguity(file, node, evidence) {
+    return { kind: 'ambiguity', evidence, location: location(file, node) };
+}
+export function localTarget(project, file, sourceImport) {
+    return resolveProjectImport(project, file, sourceImport.specifier);
+}
+export function importedLayer(project, file, sourceImport) {
+    return localTarget(project, file, sourceImport)?.layer;
+}
+export function isForeignDomain(specifier) {
+    if (specifier.startsWith('@astrale-domains/'))
+        return true;
+    const root = packageRoot(specifier);
+    return /(?:^|[-/])domain$/.test(root) || root.endsWith('-domain');
+}
+export function packageRoot(specifier) {
+    if (!specifier.startsWith('@'))
+        return specifier.split('/')[0] ?? specifier;
+    return specifier.split('/').slice(0, 2).join('/');
+}
+export function isDeepPackageImport(specifier) {
+    return specifier !== packageRoot(specifier);
+}
+export function propertyExpression(object, name) {
+    const property = objectProperty(object, name);
+    if (property && ts.isPropertyAssignment(property))
+        return unwrap(property.initializer);
+    return undefined;
+}
+export function callback(object, name) {
+    const property = objectProperty(object, name);
+    if (property && ts.isMethodDeclaration(property))
+        return property;
+    if (property && ts.isPropertyAssignment(property)) {
+        const value = unwrap(property.initializer);
+        if (ts.isArrowFunction(value) || ts.isFunctionExpression(value))
+            return value;
+    }
+    return undefined;
+}
+export function returnedExpressions(fn) {
+    if (!fn.body)
+        return [];
+    if (!ts.isBlock(fn.body))
+        return [unwrap(fn.body)];
+    const expressions = [];
+    const walk = (node) => {
+        if (node !== fn && ts.isFunctionLike(node))
+            return;
+        if (ts.isReturnStatement(node) && node.expression)
+            expressions.push(unwrap(node.expression));
+        node.forEachChild(walk);
+    };
+    fn.body.forEachChild(walk);
+    return expressions;
+}
+export function callChain(expression) {
+    const target = unwrap(expression);
+    if (ts.isCallExpression(target))
+        return propertyChain(target.expression);
+    if (ts.isPropertyAccessExpression(target))
+        return propertyChain(target);
+    return undefined;
+}
+export function staticId(expression) {
+    return staticText(expression);
+}
+export function hasForbiddenGlobalCall(file) {
+    const forbidden = new Set(['fetch', 'setTimeout', 'setInterval', 'queueMicrotask']);
+    const result = [];
+    visit(file.source, (node) => {
+        if (!ts.isCallExpression(node))
+            return;
+        const expression = unwrap(node.expression);
+        if (ts.isIdentifier(expression)) {
+            const name = expression.text;
+            if (forbidden.has(name) &&
+                !importedSymbol(file, expression) &&
+                !isLocallyBound(expression, name)) {
+                result.push({ node, name });
+            }
+            return;
+        }
+        const chain = propertyChain(expression);
+        if (chain?.length === 2 && chain[0] === 'globalThis' && forbidden.has(chain[1])) {
+            result.push({ node, name: chain[1] });
+        }
+    });
+    return result;
+}
+export function isLocallyBoundIdentifier(node) {
+    return isLocallyBound(node, node.text);
+}
+export function forbiddenIoImport(specifier) {
+    return (specifier.startsWith('node:') &&
+        !specifier.startsWith('node:assert') &&
+        !specifier.startsWith('node:util/types'));
+}
+export function variableName(call) {
+    const parent = call.parent;
+    return ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)
+        ? parent.name.text
+        : undefined;
+}
+export function allPropertyNames(object) {
+    return object.properties.flatMap((property) => {
+        if (!('name' in property) || !property.name)
+            return [];
+        const name = ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)
+            ? property.name.text
+            : undefined;
+        return name ? [name] : [];
+    });
+}
+function isLocallyBound(node, name) {
+    let current = node.parent;
+    while (current) {
+        if (ts.isFunctionLike(current)) {
+            if (current.parameters.some((parameter) => bindingContains(parameter.name, name)) ||
+                ('name' in current &&
+                    current.name &&
+                    ts.isIdentifier(current.name) &&
+                    current.name.text === name)) {
+                return true;
+            }
+        }
+        if (ts.isBlock(current) || ts.isSourceFile(current)) {
+            if (current.statements.some((statement) => statementDeclares(statement, name)))
+                return true;
+        }
+        if (ts.isCatchClause(current) && current.variableDeclaration) {
+            if (bindingContains(current.variableDeclaration.name, name))
+                return true;
+        }
+        current = current.parent;
+    }
+    return false;
+}
+function statementDeclares(statement, name) {
+    if (ts.isVariableStatement(statement)) {
+        return statement.declarationList.declarations.some((declaration) => bindingContains(declaration.name, name));
+    }
+    if ((ts.isFunctionDeclaration(statement) ||
+        ts.isClassDeclaration(statement) ||
+        ts.isEnumDeclaration(statement)) &&
+        statement.name?.text === name) {
+        return true;
+    }
+    if (ts.isImportDeclaration(statement) && statement.importClause) {
+        const clause = statement.importClause;
+        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));
+    }
+    return false;
+}
+function bindingContains(binding, name) {
+    if (ts.isIdentifier(binding))
+        return binding.text === name;
+    return binding.elements.some((element) => ts.isOmittedExpression(element) ? false : bindingContains(element.name, name));
+}

package/dist/tooling/linter/implementations/source/state-machine.d.ts

@@ -0,0 +1,24 @@
+import ts from 'typescript';
+import type { SourceFile, SourceProject } from '../../adapters/typescript/index.js';
+export type StateMachineOrigin = 'resolved' | 'ambiguous' | 'absent';
+export type StateMachineResolution = Readonly<{
+    kind: 'resolved';
+    identity: string;
+}> | Readonly<{
+    kind: 'ambiguous' | 'absent';
+}>;
+export type MachineExportStatus = 'exported' | 'private' | 'mutable' | 'not-a-declaration';
+/** Resolve a direct or static local alias of the SDK stateMachine constructor. */
+export declare function stateMachineConstructorOrigin(file: SourceFile, expression: ts.Expression, seen?: ReadonlySet<string>): StateMachineOrigin;
+/** Resolve one local binding to an exported SDK stateMachine authority. */
+export declare function stateMachineOrigin(project: SourceProject, file: SourceFile, expression: ts.Expression): StateMachineOrigin;
+/** Resolve a consumer expression to the exact exported stateMachine declaration that owns it. */
+export declare function stateMachineIdentity(project: SourceProject, file: SourceFile, expression: ts.Expression, seen?: ReadonlySet<string>): StateMachineResolution;
+/** Resolve a Schema codec expression to the exact machine whose stateSchema it aliases. */
+export declare function stateSchemaIdentity(project: SourceProject, file: SourceFile, expression: ts.Expression, seen?: ReadonlySet<string>): StateMachineResolution;
+/** Resolve a persisted Schema stateProperty to its exact StateMachine authority. */
+export declare function statePropertyIdentity(project: SourceProject, file: SourceFile, expression: ts.Expression, seen?: ReadonlySet<string>): StateMachineResolution;
+/** Classify whether an expression is produced by the canonical SDK stateProperty helper. */
+export declare function statePropertyOrigin(file: SourceFile, expression: ts.Expression, seen?: ReadonlySet<string>): StateMachineOrigin;
+/** Classify whether a stateMachine call is the value of an exported top-level binding. */
+export declare function machineExportStatus(file: SourceFile, call: ts.CallExpression): MachineExportStatus;