@astrale-os/sdk 0.5.0-beta.15 → 0.5.0-beta.151

package/dist/tooling/linter/implementations/source/state-machine.js

@@ -0,0 +1,381 @@
+import ts from 'typescript';
+import { resolveImportedSymbol, resolveProjectImport, staticText, unwrap, visit, } from '../../adapters/typescript/index.js';
+const STATE_MODULES = new Set(['@astrale-os/sdk/state']);
+const SCHEMA_MODULES = new Set([
+    '@astrale-os/sdk',
+    '@astrale-os/sdk/schema',
+    '@astrale-os/kernel-dsl',
+    '@astrale-os/kernel-dsl/v1',
+]);
+const STATE_PROPERTY_MODULES = new Set(['@astrale-os/sdk/schema']);
+/** Resolve a direct or static local alias of the SDK stateMachine constructor. */
+export function stateMachineConstructorOrigin(file, expression, seen = new Set()) {
+    const value = unwrap(expression);
+    const symbol = resolveImportedSymbol(file, value);
+    if (symbol.kind === 'resolved') {
+        return symbol.name === 'stateMachine' && STATE_MODULES.has(symbol.module)
+            ? 'resolved'
+            : 'absent';
+    }
+    if (symbol.kind === 'ambiguous' && symbol.name === 'stateMachine')
+        return 'ambiguous';
+    if (!ts.isIdentifier(value) || seen.has(value.text))
+        return 'absent';
+    const declaration = localVariable(file, value.text);
+    if (declaration === undefined)
+        return 'absent';
+    const next = new Set(seen);
+    next.add(value.text);
+    const origin = stateMachineConstructorOrigin(file, declaration.initializer, next);
+    return declaration.constant || origin === 'absent' ? origin : 'ambiguous';
+}
+/** Resolve one local binding to an exported SDK stateMachine authority. */
+export function stateMachineOrigin(project, file, expression) {
+    return stateMachineIdentity(project, file, expression).kind;
+}
+/** Resolve a consumer expression to the exact exported stateMachine declaration that owns it. */
+export function stateMachineIdentity(project, file, expression, seen = new Set()) {
+    const value = unwrap(expression);
+    if (ts.isIdentifier(value)) {
+        const declaration = localVariable(file, value.text);
+        if (declaration !== undefined) {
+            const identity = `${file.path}\0${value.text}`;
+            if (seen.has(identity))
+                return { kind: 'ambiguous' };
+            const initializer = unwrap(declaration.initializer);
+            if (ts.isCallExpression(initializer)) {
+                const origin = stateMachineConstructorOrigin(file, initializer.expression);
+                if (origin === 'ambiguous')
+                    return { kind: 'ambiguous' };
+                if (origin === 'resolved') {
+                    if (!declaration.constant)
+                        return { kind: 'ambiguous' };
+                    return machineExportStatus(file, initializer) === 'exported'
+                        ? { kind: 'resolved', identity: machineIdentity(file, value.text) }
+                        : { kind: 'absent' };
+                }
+            }
+            const next = new Set(seen);
+            next.add(identity);
+            const resolution = stateMachineIdentity(project, file, declaration.initializer, next);
+            return declaration.constant || resolution.kind === 'absent'
+                ? resolution
+                : { kind: 'ambiguous' };
+        }
+    }
+    const binding = importedBinding(file, value);
+    if (binding === undefined)
+        return { kind: 'absent' };
+    const target = resolveProjectImport(project, file, binding.specifier);
+    if (target === undefined)
+        return { kind: 'ambiguous' };
+    return resolveMachineExport(project, target, binding.imported, new Set());
+}
+/** Resolve a Schema codec expression to the exact machine whose stateSchema it aliases. */
+export function stateSchemaIdentity(project, file, expression, seen = new Set()) {
+    const value = unwrap(expression);
+    const owner = staticMemberReceiver(value, 'stateSchema');
+    if (owner !== undefined) {
+        return stateMachineIdentity(project, file, owner);
+    }
+    if (ts.isCallExpression(value)) {
+        const symbol = resolveImportedSymbol(file, value.expression);
+        if (symbol.kind === 'resolved' &&
+            symbol.name === 'property' &&
+            SCHEMA_MODULES.has(symbol.module)) {
+            const codec = value.arguments[0];
+            return codec === undefined
+                ? { kind: 'absent' }
+                : stateSchemaIdentity(project, file, codec, seen);
+        }
+    }
+    if (ts.isIdentifier(value)) {
+        const declaration = localVariable(file, value.text);
+        if (declaration === undefined)
+            return { kind: 'absent' };
+        if (seen.has(value.text))
+            return { kind: 'ambiguous' };
+        const next = new Set(seen);
+        next.add(value.text);
+        const resolution = stateSchemaIdentity(project, file, declaration.initializer, next);
+        return declaration.constant || resolution.kind === 'absent' ? resolution : { kind: 'ambiguous' };
+    }
+    let candidate = false;
+    visit(value, (node) => {
+        const owner = ts.isExpression(node) ? staticMemberReceiver(node, 'stateSchema') : undefined;
+        if (owner !== undefined && stateMachineIdentity(project, file, owner).kind !== 'absent') {
+            candidate = true;
+        }
+        if (ts.isIdentifier(node) && node !== value) {
+            if (seen.has(node.text)) {
+                return;
+            }
+            const declaration = localVariable(file, node.text);
+            const next = new Set(seen);
+            next.add(node.text);
+            if (declaration !== undefined &&
+                stateSchemaIdentity(project, file, declaration.initializer, next).kind !== 'absent') {
+                candidate = true;
+            }
+        }
+    });
+    return candidate ? { kind: 'ambiguous' } : { kind: 'absent' };
+}
+/** Resolve a persisted Schema stateProperty to its exact StateMachine authority. */
+export function statePropertyIdentity(project, file, expression, seen = new Set()) {
+    const value = unwrap(expression);
+    if (ts.isCallExpression(value)) {
+        const symbol = resolveImportedSymbol(file, value.expression);
+        if (symbol.kind === 'resolved' &&
+            symbol.name === 'stateProperty' &&
+            STATE_PROPERTY_MODULES.has(symbol.module)) {
+            const machine = value.arguments[0];
+            return machine === undefined
+                ? { kind: 'absent' }
+                : stateMachineIdentity(project, file, machine);
+        }
+    }
+    if (ts.isIdentifier(value)) {
+        const declaration = localVariable(file, value.text);
+        if (declaration === undefined)
+            return { kind: 'absent' };
+        if (seen.has(value.text))
+            return { kind: 'ambiguous' };
+        const next = new Set(seen);
+        next.add(value.text);
+        const resolution = statePropertyIdentity(project, file, declaration.initializer, next);
+        return declaration.constant || resolution.kind === 'absent' ? resolution : { kind: 'ambiguous' };
+    }
+    let candidate = false;
+    visit(value, (node) => {
+        if (!ts.isCallExpression(node))
+            return;
+        const symbol = resolveImportedSymbol(file, node.expression);
+        if (symbol.kind !== 'local' &&
+            symbol.name === 'stateProperty' &&
+            (symbol.kind === 'ambiguous' || STATE_PROPERTY_MODULES.has(symbol.module))) {
+            candidate = true;
+        }
+    });
+    return candidate ? { kind: 'ambiguous' } : { kind: 'absent' };
+}
+/** Classify whether an expression is produced by the canonical SDK stateProperty helper. */
+export function statePropertyOrigin(file, expression, seen = new Set()) {
+    const value = unwrap(expression);
+    if (ts.isCallExpression(value)) {
+        const symbol = resolveImportedSymbol(file, value.expression);
+        if (symbol.kind === 'resolved') {
+            return symbol.name === 'stateProperty' && STATE_PROPERTY_MODULES.has(symbol.module)
+                ? 'resolved'
+                : 'absent';
+        }
+        if (symbol.kind === 'ambiguous' && symbol.name === 'stateProperty')
+            return 'ambiguous';
+    }
+    if (!ts.isIdentifier(value) || seen.has(value.text))
+        return 'absent';
+    const declaration = localVariable(file, value.text);
+    if (declaration === undefined)
+        return 'absent';
+    const next = new Set(seen);
+    next.add(value.text);
+    const origin = statePropertyOrigin(file, declaration.initializer, next);
+    return declaration.constant || origin === 'absent' ? origin : 'ambiguous';
+}
+function staticMemberReceiver(expression, member) {
+    const value = unwrap(expression);
+    if (ts.isPropertyAccessExpression(value) && value.name.text === member) {
+        return value.expression;
+    }
+    if (ts.isElementAccessExpression(value) && staticText(value.argumentExpression) === member) {
+        return value.expression;
+    }
+    return undefined;
+}
+function importedBinding(file, expression) {
+    const value = unwrap(expression);
+    if (ts.isIdentifier(value)) {
+        for (const sourceImport of file.imports) {
+            for (const [imported, local] of sourceImport.bindings) {
+                if (local === value.text)
+                    return { specifier: sourceImport.specifier, imported };
+            }
+        }
+        return undefined;
+    }
+    if (ts.isPropertyAccessExpression(value) && ts.isIdentifier(value.expression)) {
+        const namespace = value.expression.text;
+        const sourceImport = file.imports.find((source) => source.namespace === namespace);
+        if (sourceImport !== undefined) {
+            return { specifier: sourceImport.specifier, imported: value.name.text };
+        }
+    }
+    return undefined;
+}
+/** Classify whether a stateMachine call is the value of an exported top-level binding. */
+export function machineExportStatus(file, call) {
+    for (const statement of file.source.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) ||
+                declaration.initializer === undefined ||
+                unwrap(declaration.initializer) !== call) {
+                continue;
+            }
+            const directlyExported = ts
+                .getModifiers(statement)
+                ?.some(({ kind }) => kind === ts.SyntaxKind.ExportKeyword);
+            if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0)
+                return 'mutable';
+            if (directlyExported || locallyExported(file, declaration.name.text))
+                return 'exported';
+            return 'private';
+        }
+    }
+    return 'not-a-declaration';
+}
+function resolveMachineExport(project, file, exported, seen) {
+    const visitIdentity = `${file.path}\0${exported}`;
+    if (seen.has(visitIdentity))
+        return { kind: 'absent' };
+    seen.add(visitIdentity);
+    const identities = new Set();
+    let unresolved = false;
+    for (const statement of file.source.statements) {
+        if (ts.isVariableStatement(statement)) {
+            const directExport = ts
+                .getModifiers(statement)
+                ?.some(({ kind }) => kind === ts.SyntaxKind.ExportKeyword);
+            if (directExport) {
+                const origin = localMachineOrigin(file, exported);
+                if (origin === 'resolved')
+                    identities.add(machineIdentity(file, exported));
+                else if (origin === 'ambiguous')
+                    unresolved = true;
+            }
+            continue;
+        }
+        if (!ts.isExportDeclaration(statement))
+            continue;
+        if (!statement.exportClause) {
+            if (statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)) {
+                const target = resolveProjectImport(project, file, statement.moduleSpecifier.text);
+                if (!target) {
+                    unresolved = true;
+                }
+                else {
+                    mergeResolution(resolveMachineExport(project, target, exported, new Set(seen)), identities, () => {
+                        unresolved = true;
+                    });
+                }
+            }
+            continue;
+        }
+        if (!ts.isNamedExports(statement.exportClause))
+            continue;
+        for (const element of statement.exportClause.elements) {
+            if (element.name.text !== exported)
+                continue;
+            const local = element.propertyName?.text ?? element.name.text;
+            if (statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)) {
+                const target = resolveProjectImport(project, file, statement.moduleSpecifier.text);
+                if (!target) {
+                    unresolved = true;
+                }
+                else {
+                    mergeResolution(resolveMachineExport(project, target, local, new Set(seen)), identities, () => {
+                        unresolved = true;
+                    });
+                }
+            }
+            else {
+                const origin = localMachineOrigin(file, local);
+                if (origin === 'resolved') {
+                    identities.add(machineIdentity(file, local));
+                }
+                else if (origin === 'ambiguous') {
+                    unresolved = true;
+                }
+                else {
+                    const imported = importedLocalBinding(file, local);
+                    if (imported === undefined)
+                        continue;
+                    const target = resolveProjectImport(project, file, imported.specifier);
+                    if (!target) {
+                        unresolved = true;
+                    }
+                    else {
+                        mergeResolution(resolveMachineExport(project, target, imported.imported, new Set(seen)), identities, () => {
+                            unresolved = true;
+                        });
+                    }
+                }
+            }
+        }
+    }
+    if (unresolved || identities.size > 1)
+        return { kind: 'ambiguous' };
+    const [identity] = identities;
+    return identity === undefined ? { kind: 'absent' } : { kind: 'resolved', identity };
+}
+function importedLocalBinding(file, local) {
+    for (const sourceImport of file.imports) {
+        for (const [imported, candidate] of sourceImport.bindings) {
+            if (candidate === local)
+                return { specifier: sourceImport.specifier, imported };
+        }
+    }
+    return undefined;
+}
+function mergeResolution(resolution, identities, ambiguous) {
+    if (resolution.kind === 'resolved')
+        identities.add(resolution.identity);
+    else if (resolution.kind === 'ambiguous')
+        ambiguous();
+}
+function machineIdentity(file, local) {
+    return `${file.path}#${local}`;
+}
+function locallyExported(file, name) {
+    return file.source.statements.some((statement) => ts.isExportDeclaration(statement) &&
+        !statement.moduleSpecifier &&
+        statement.exportClause !== undefined &&
+        ts.isNamedExports(statement.exportClause) &&
+        statement.exportClause.elements.some((element) => (element.propertyName?.text ?? element.name.text) === name));
+}
+function localVariable(file, name) {
+    for (const statement of file.source.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (ts.isIdentifier(declaration.name) &&
+                declaration.name.text === name &&
+                declaration.initializer !== undefined) {
+                return {
+                    initializer: declaration.initializer,
+                    constant: (statement.declarationList.flags & ts.NodeFlags.Const) !== 0,
+                };
+            }
+        }
+    }
+    return undefined;
+}
+function localMachineOrigin(file, name) {
+    for (const statement of file.source.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (ts.isIdentifier(declaration.name) &&
+                declaration.name.text === name &&
+                declaration.initializer !== undefined &&
+                ts.isCallExpression(unwrap(declaration.initializer))) {
+                const call = unwrap(declaration.initializer);
+                const origin = stateMachineConstructorOrigin(file, call.expression);
+                const constant = (statement.declarationList.flags & ts.NodeFlags.Const) !== 0;
+                return constant || origin === 'absent' ? origin : 'ambiguous';
+            }
+        }
+    }
+    return 'absent';
+}

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

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