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

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

@@ -1,6 +1,7 @@
 import ts from 'typescript';
-import { importedSymbol, propertyChain, staticText, unwrap, visit, } from '../../adapters/typescript/index.js';
-import { ambiguity, DSL_MODULES, forbiddenIoImport, production, violation } from './shared.js';
+import { NEUTRAL_CLASS_ICON_SVG } from '../../../../platform/schema/class-icon.js';
+import { importedSymbol, objectProperty, propertyChain, resolveImportedSymbol, staticText, unwrap, visit, } from '../../adapters/typescript/index.js';
+import { ambiguity, definitionObjects, definitionOriginAmbiguity, DSL_MODULES, forbiddenIoImport, production, propertyExpression, violation, } from './shared.js';
 import { stateMachineConstructorOrigin, stateMachineOrigin, statePropertyIdentity, statePropertyOrigin, stateSchemaIdentity, } from './state-machine.js';
 const FORBIDDEN_LAYERS = new Set([
     'integrations',
@@ -20,7 +21,458 @@ const EXECUTION_NAMES = new Set([
     'mutate',
     'query',
 ]);
+const SCHEMA_KINDS = Object.freeze([
+    'classes',
+    'core',
+    'dependencies',
+    'errors',
+    'functions',
+    'policies',
+    'states',
+    'types',
+    'views',
+]);
+const SCHEMA_KIND_DIRECTORIES = new Set(SCHEMA_KINDS);
+const SCHEMA_ROOT_DIRECTORIES = new Set(['__tests__', 'modules', ...SCHEMA_KINDS]);
+const SCHEMA_KIND_LIST = SCHEMA_KINDS.join(', ');
+const SCHEMA_ROOT_DIRECTORY_LIST = [...SCHEMA_ROOT_DIRECTORIES].join(', ');
+const OWNED_DECLARATION_KINDS = new Set(['classes', 'functions', 'policies', 'states', 'views']);
+const DECLARATION_KIND_CONTRACTS = Object.freeze({
+    classes: {
+        label: 'Class',
+        constructors: [
+            { module: '@astrale-os/sdk/schema', name: 'nodeClass' },
+            { module: '@astrale-os/sdk/schema', name: 'defineClass' },
+            { module: '@astrale-os/sdk/schema', name: 'edgeClass', member: 'directed' },
+            { module: '@astrale-os/sdk/schema', name: 'edgeClass', member: 'undirected' },
+        ],
+    },
+    functions: {
+        label: 'Function or Method',
+        constructors: [
+            { module: '@astrale-os/sdk/schema', name: 'func' },
+            { module: '@astrale-os/sdk/schema', name: 'method' },
+        ],
+    },
+    policies: {
+        label: 'Policy',
+        constructors: [
+            { module: '@astrale-os/sdk/schema', name: 'policy' },
+            { module: '@astrale-os/sdk/schema', name: 'policy', member: 'allOf' },
+            { module: '@astrale-os/sdk/schema', name: 'policy', member: 'anyOf' },
+        ],
+    },
+    states: {
+        label: 'StateMachine',
+        constructors: [{ module: '@astrale-os/sdk/state', name: 'stateMachine' }],
+    },
+    views: {
+        label: 'View',
+        constructors: [{ module: '@astrale-os/sdk/schema', name: 'view' }],
+    },
+});
+function classIconObservation(file, call, object) {
+    if (!object) {
+        if (call.arguments.length === 0 || isUndefinedExpression(call.arguments[0])) {
+            return { state: 'missing', node: call };
+        }
+        return {
+            state: 'presence-ambiguous',
+            node: call,
+            detail: 'Node Class icon is hidden inside an opaque configuration.',
+        };
+    }
+    const property = objectProperty(object, 'icon');
+    if (!property) {
+        if (object.properties.some(mayAssignUnknownProperty)) {
+            return {
+                state: 'presence-ambiguous',
+                node: object,
+                detail: 'Node Class icon may be supplied by an object spread or computed property.',
+            };
+        }
+        return { state: 'missing', node: object };
+    }
+    if (object.properties.some((candidate) => candidate.pos > property.pos && mayAssignUnknownProperty(candidate))) {
+        return {
+            state: 'presence-ambiguous',
+            node: property,
+            detail: 'Node Class icon may be overridden by a later object spread or computed property.',
+        };
+    }
+    if (!ts.isPropertyAssignment(property)) {
+        return {
+            state: 'value-ambiguous',
+            node: property,
+            detail: 'Node Class icon value is not statically visible.',
+        };
+    }
+    if (isUndefinedExpression(property.initializer)) {
+        return { state: 'missing', node: property };
+    }
+    const state = neutralIconState(file, property.initializer);
+    if (state === 'neutral') {
+        return { state, node: property };
+    }
+    if (state === 'value-ambiguous') {
+        return {
+            state,
+            node: property,
+            detail: 'Node Class icon origin is not statically resolvable.',
+        };
+    }
+    return { state: 'meaningful', node: property };
+}
+function neutralIconState(file, expression) {
+    if (staticText(expression) === NEUTRAL_CLASS_ICON_SVG)
+        return 'neutral';
+    const target = unwrap(expression);
+    if (ts.isCallExpression(target)) {
+        const callee = unwrap(target.expression);
+        if (!ts.isPropertyAccessExpression(callee) || callee.name.text !== 'svg') {
+            return 'meaningful';
+        }
+        const resolution = resolveImportedSymbol(file, callee.expression);
+        if (resolution.kind === 'local' || resolution.name !== 'classIcon')
+            return 'meaningful';
+        if (resolution.kind === 'ambiguous')
+            return 'value-ambiguous';
+        if (resolution.module !== '@astrale-os/sdk/schema')
+            return 'meaningful';
+        return staticText(target.arguments[0]) === NEUTRAL_CLASS_ICON_SVG ? 'neutral' : 'meaningful';
+    }
+    if (!ts.isPropertyAccessExpression(target) || target.name.text !== 'neutral') {
+        return 'meaningful';
+    }
+    const resolution = resolveImportedSymbol(file, target.expression);
+    if (resolution.kind === 'local')
+        return 'meaningful';
+    if (resolution.name !== 'classIcon')
+        return 'meaningful';
+    if (resolution.kind === 'resolved') {
+        return resolution.module === '@astrale-os/sdk/schema' ? 'neutral' : 'meaningful';
+    }
+    return resolution.kind === 'ambiguous' ? 'value-ambiguous' : 'meaningful';
+}
+function requiredClassIconEvidence(file, observation) {
+    if (observation.state === 'missing') {
+        return [
+            violation(file, observation.node, 'Node Class must declare icon explicitly; use classIcon.neutral only for an intentional neutral choice.'),
+        ];
+    }
+    if (observation.state === 'presence-ambiguous') {
+        return [ambiguity(file, observation.node, observation.detail ?? 'Node Class icon is opaque.')];
+    }
+    return [];
+}
+function neutralClassIconEvidence(file, observation) {
+    if (observation.state !== 'neutral')
+        return [];
+    return [
+        violation(file, observation.node, 'Node Class uses classIcon.neutral; choose a meaningful Lucide or custom SVG icon.'),
+    ];
+}
+function classIconEvidence(project, mode) {
+    const evidence = [];
+    const report = mode === 'required' ? requiredClassIconEvidence : neutralClassIconEvidence;
+    for (const file of production(project, 'schema')) {
+        for (const definition of definitionObjects(file, 'nodeClass', undefined, DSL_MODULES)) {
+            const uncertain = definitionOriginAmbiguity(file, definition, 'nodeClass declaration');
+            if (uncertain) {
+                if (mode === 'required')
+                    evidence.push(uncertain);
+                continue;
+            }
+            evidence.push(...report(file, classIconObservation(file, definition.call, definition.object)));
+        }
+        for (const definition of definitionObjects(file, 'defineClass', undefined, DSL_MODULES)) {
+            if (!definition.object)
+                continue;
+            if (staticText(propertyExpression(definition.object, 'kind')) !== 'node')
+                continue;
+            const uncertain = definitionOriginAmbiguity(file, definition, 'defineClass declaration');
+            if (uncertain) {
+                if (mode === 'required')
+                    evidence.push(uncertain);
+                continue;
+            }
+            evidence.push(...report(file, classIconObservation(file, definition.call, definition.object)));
+        }
+    }
+    return evidence;
+}
+function isUndefinedExpression(expression) {
+    if (!expression)
+        return false;
+    const target = unwrap(expression);
+    return (ts.isIdentifier(target) && target.text === 'undefined') || ts.isVoidExpression(target);
+}
+function mayAssignUnknownProperty(property) {
+    if (ts.isSpreadAssignment(property))
+        return true;
+    return ('name' in property &&
+        property.name !== undefined &&
+        ts.isComputedPropertyName(property.name) &&
+        staticText(property.name.expression) === undefined);
+}
+function declarationKindFile(project, file) {
+    if (file.role !== 'production' || file.layer !== 'schema')
+        return undefined;
+    const layer = project.policy.layers.find(({ id }) => id === 'schema');
+    if (!layer)
+        return undefined;
+    const segments = file.path.slice(layer.sourcePath.length).split('/');
+    const nestedModule = segments[0] === 'modules';
+    const kind = segments[nestedModule ? 2 : 0];
+    if (!kind || !OWNED_DECLARATION_KINDS.has(kind))
+        return undefined;
+    const index = nestedModule
+        ? segments.length === 4 && segments[3] === 'index.ts'
+        : segments.length === 2 && segments[1] === 'index.ts';
+    return { kind: kind, index };
+}
+function declarationConstructor(file, expression) {
+    const call = unwrap(expression);
+    if (!ts.isCallExpression(call))
+        return undefined;
+    const callee = unwrap(call.expression);
+    const direct = resolveImportedSymbol(file, callee);
+    if (direct.kind === 'resolved') {
+        for (const contract of Object.values(DECLARATION_KIND_CONTRACTS)) {
+            const constructor = contract.constructors.find((candidate) => candidate.module === direct.module &&
+                candidate.name === direct.name &&
+                candidate.member === undefined);
+            if (constructor)
+                return constructor;
+        }
+    }
+    if (!ts.isPropertyAccessExpression(callee))
+        return undefined;
+    const resolution = resolveImportedSymbol(file, callee.expression);
+    if (resolution.kind !== 'resolved')
+        return undefined;
+    for (const contract of Object.values(DECLARATION_KIND_CONTRACTS)) {
+        const constructor = contract.constructors.find((candidate) => candidate.module === resolution.module &&
+            candidate.name === resolution.name &&
+            candidate.member === callee.name.text);
+        if (constructor)
+            return constructor;
+    }
+    return undefined;
+}
+function expectedDeclarationConstructor(file, expression, kind) {
+    if (!expression)
+        return false;
+    const constructor = declarationConstructor(file, expression);
+    return (constructor !== undefined &&
+        DECLARATION_KIND_CONTRACTS[kind].constructors.some((candidate) => candidate.module === constructor.module &&
+            candidate.name === constructor.name &&
+            candidate.member === constructor.member));
+}
+function locallyConstructedDeclarations(file) {
+    const declarations = [];
+    visit(file.source, (node) => {
+        if (ts.isCallExpression(node) && declarationConstructor(file, node))
+            declarations.push(node);
+    });
+    return declarations;
+}
+function runtimeExports(file) {
+    const bindings = new Map();
+    for (const statement of file.source.statements) {
+        if (ts.isVariableStatement(statement)) {
+            for (const declaration of statement.declarationList.declarations) {
+                if (ts.isIdentifier(declaration.name)) {
+                    bindings.set(declaration.name.text, {
+                        node: declaration,
+                        ...(declaration.initializer ? { initializer: declaration.initializer } : {}),
+                    });
+                }
+            }
+            continue;
+        }
+        if ((ts.isFunctionDeclaration(statement) ||
+            ts.isClassDeclaration(statement) ||
+            ts.isEnumDeclaration(statement) ||
+            ts.isModuleDeclaration(statement)) &&
+            statement.name) {
+            bindings.set(statement.name.text, { node: statement });
+        }
+    }
+    const exports = [];
+    for (const statement of file.source.statements) {
+        if (ts.isVariableStatement(statement) && hasModifier(statement, ts.SyntaxKind.ExportKeyword)) {
+            for (const declaration of statement.declarationList.declarations) {
+                exports.push({
+                    node: declaration,
+                    ...(declaration.initializer ? { initializer: declaration.initializer } : {}),
+                });
+            }
+            continue;
+        }
+        if ((ts.isFunctionDeclaration(statement) ||
+            ts.isClassDeclaration(statement) ||
+            ts.isEnumDeclaration(statement) ||
+            ts.isModuleDeclaration(statement)) &&
+            hasModifier(statement, ts.SyntaxKind.ExportKeyword)) {
+            exports.push({ node: statement });
+            continue;
+        }
+        if (ts.isExportAssignment(statement)) {
+            exports.push({
+                node: statement,
+                initializer: localInitializer(statement.expression, bindings),
+            });
+            continue;
+        }
+        if (!ts.isExportDeclaration(statement) || statement.isTypeOnly)
+            continue;
+        if (!statement.exportClause || !ts.isNamedExports(statement.exportClause)) {
+            exports.push({ node: statement });
+            continue;
+        }
+        for (const element of statement.exportClause.elements) {
+            if (element.isTypeOnly)
+                continue;
+            exports.push({
+                node: element,
+                ...(statement.moduleSpecifier
+                    ? {}
+                    : { initializer: localInitializer(element.propertyName ?? element.name, bindings) }),
+            });
+        }
+    }
+    return exports;
+}
+function localInitializer(expression, bindings, seen = new Set()) {
+    const target = unwrap(expression);
+    if (!ts.isIdentifier(target))
+        return target;
+    if (seen.has(target.text))
+        return undefined;
+    seen.add(target.text);
+    const initializer = bindings.get(target.text)?.initializer;
+    return initializer ? localInitializer(initializer, bindings, seen) : undefined;
+}
+function hasModifier(node, kind) {
+    return (ts.canHaveModifiers(node) &&
+        ts.getModifiers(node)?.some((modifier) => modifier.kind === kind) === true);
+}
+function curatedDeclarationIndex(statement) {
+    if (ts.isEmptyStatement(statement))
+        return true;
+    if (ts.isImportDeclaration(statement))
+        return statement.importClause !== undefined;
+    return (ts.isExportDeclaration(statement) &&
+        statement.exportClause !== undefined &&
+        ts.isNamedExports(statement.exportClause));
+}
 export const schemaRules = [
+    {
+        id: 'SCH-SUBMODULE',
+        ruleRevision: '8b226c1ec1f283372e048d40338f010ba97ae81230b4ebae63e48d533c7152c4',
+        evaluate(project) {
+            const layer = project.policy.layers.find(({ id }) => id === 'schema');
+            if (!layer)
+                return [];
+            const evidence = [];
+            const rootFiles = new Set(['index.ts', ...(layer.facade ? [layer.facade] : [])]);
+            const reportedRootDirectories = new Set();
+            const reportedModuleDirectories = new Set();
+            for (const file of project.files) {
+                if (file.layer !== 'schema')
+                    continue;
+                const relative = file.path.slice(layer.sourcePath.length);
+                const segments = relative.split('/');
+                if (segments.length === 1) {
+                    if (!rootFiles.has(relative)) {
+                        evidence.push(violation(file, file.source, `Schema root source ${file.path} is flat; only ${[...rootFiles]
+                            .map((name) => `${layer.sourcePath}${name}`)
+                            .join(' and ')} may be flat.`));
+                    }
+                    continue;
+                }
+                const rootDirectory = segments[0];
+                if (!SCHEMA_ROOT_DIRECTORIES.has(rootDirectory)) {
+                    if (!reportedRootDirectories.has(rootDirectory)) {
+                        reportedRootDirectories.add(rootDirectory);
+                        evidence.push(violation(file, file.source, `Schema source ${file.path} uses unknown root directory ${layer.sourcePath}${rootDirectory}/; expected one of ${SCHEMA_ROOT_DIRECTORY_LIST}.`));
+                    }
+                    continue;
+                }
+                if (rootDirectory !== 'modules')
+                    continue;
+                if (segments.length === 2) {
+                    evidence.push(violation(file, file.source, `Schema modules source ${file.path} is flat; declarations must belong to ${layer.sourcePath}modules/<module>/.`));
+                    continue;
+                }
+                const moduleName = segments[1];
+                if (segments.length === 3) {
+                    if (segments[2] !== 'index.ts') {
+                        evidence.push(violation(file, file.source, `Schema module source ${file.path} is flat; only ${layer.sourcePath}modules/${moduleName}/index.ts may be flat.`));
+                    }
+                    continue;
+                }
+                const kind = segments[2];
+                if (kind === '__tests__' || SCHEMA_KIND_DIRECTORIES.has(kind))
+                    continue;
+                const directory = `${moduleName}/${kind}`;
+                if (reportedModuleDirectories.has(directory))
+                    continue;
+                reportedModuleDirectories.add(directory);
+                evidence.push(violation(file, file.source, `Schema module source ${file.path} uses unknown declaration-kind directory ${kind}/; expected one of ${SCHEMA_KIND_LIST}, __tests__.`));
+            }
+            return evidence;
+        },
+    },
+    {
+        id: 'SCH-ONE-DECL',
+        ruleRevision: '62d059e983429281d3858d3d3e10573668cb5b59762247c3b47c8bb5ed99ee2d',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of project.files) {
+                const owner = declarationKindFile(project, file);
+                if (!owner)
+                    continue;
+                if (owner.index) {
+                    const unsupported = file.source.statements.find((statement) => !curatedDeclarationIndex(statement));
+                    if (unsupported) {
+                        evidence.push(violation(file, unsupported, `Schema declaration-kind index ${file.path} owns a value or uses an uncurated export; keep index.ts limited to imports and named re-exports.`));
+                    }
+                    continue;
+                }
+                const contract = DECLARATION_KIND_CONTRACTS[owner.kind];
+                const exports = runtimeExports(file);
+                if (exports.length !== 1) {
+                    evidence.push(violation(file, exports[0]?.node ?? file.source, `Schema ${owner.kind} leaf ${file.path} exports ${exports.length} runtime values; export exactly one locally authored ${contract.label} declaration.`));
+                    continue;
+                }
+                if (!expectedDeclarationConstructor(file, exports[0]?.initializer, owner.kind)) {
+                    evidence.push(violation(file, exports[0].node, `Schema ${owner.kind} leaf ${file.path} does not export one locally authored ${contract.label} declaration; only index.ts may re-export declarations.`));
+                    continue;
+                }
+                const declarations = locallyConstructedDeclarations(file);
+                if (declarations.length !== 1) {
+                    evidence.push(violation(file, declarations[1] ?? declarations[0] ?? exports[0].node, `Schema ${owner.kind} leaf ${file.path} constructs ${declarations.length} Schema declarations; construct exactly one ${contract.label} declaration.`));
+                }
+            }
+            return evidence;
+        },
+    },
+    {
+        id: 'SCH-ICON-REQUIRED',
+        ruleRevision: 'f4055b93066289f9b7d9cfceb5ef236420f88311a357ea11161b6fda0922ab9f',
+        evaluate(project) {
+            return classIconEvidence(project, 'required');
+        },
+    },
+    {
+        id: 'SCH-ICON-NEUTRAL',
+        ruleRevision: '061939249964440ceba92dcb86f166553d56cc0196dff15785616423963d4d5b',
+        evaluate(project) {
+            return classIconEvidence(project, 'neutral');
+        },
+    },
     {
         id: 'SCH-STATE-SOURCE',
         ruleRevision: '153bb37fbc7ddcf164dea299d6874251b6b2aeffa707e809044c5390f25b3fe6',

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

@@ -1,4 +1,5 @@
 import { actionRules } from './actions.js';
+import { dependencyRules } from './dependencies.js';
 import { globalRules } from './global.js';
 import { integrationRules } from './integrations.js';
 import { migrationRules } from './migrations.js';
@@ -21,6 +22,7 @@ export const sourceRuleVerifiers = Object.freeze([
     ...queryRules,
     ...mutationRules,
     ...workflowRules,
+    ...dependencyRules,
     ...migrationRules,
     ...integrationRules,
     ...actionRules,

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

@@ -1,6 +1,6 @@
 import ts from 'typescript';
-import { importedSymbol, propertyChain, unwrap, visit, } from '../../adapters/typescript/index.js';
-import { ambiguity, calls, isForeignDomain, production, staticId, violation } from './shared.js';
+import { propertyChain, unwrap, visit } from '../../adapters/typescript/index.js';
+import { ambiguity, calls, production, staticId, violation } from './shared.js';
 const STEP_METHODS = new Set(['run']);
 export const workflowRules = [
     {
@@ -65,38 +65,6 @@ export const workflowRules = [
             return evidence;
         },
     },
-    {
-        id: 'FNC-XDOM-INT',
-        ruleRevision: 'ae5a879a6b19e26e33568cc47e0f5c34ba741df0e5dec663590923ceac4de264',
-        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, `Workflow imports foreign Domain ${sourceImport.specifier}; use an Integration.`));
-                    }
-                }
-                for (const definition of workflowDefinitions(file)) {
-                    if (definition.origin === 'ambiguous') {
-                        evidence.push(ambiguity(file, definition.call, 'Workflow definition resolves through a local facade whose ultimate public constructor origin is unknown.'));
-                        continue;
-                    }
-                    const { run } = definition;
-                    if (!run)
-                        continue;
-                    visitOwnBody(run, (node) => {
-                        if (!ts.isCallExpression(node))
-                            return;
-                        const symbol = importedSymbol(file, node.expression);
-                        if (symbol && isForeignDomain(symbol.module)) {
-                            evidence.push(violation(file, node, `Workflow invokes foreign callable ${symbol.name} directly.`));
-                        }
-                    });
-                }
-            }
-            return evidence;
-        },
-    },
     {
         id: 'FNC-NO-NEST',
         ruleRevision: 'f2d818d1da69830c9ccaf183c5eb0310c795ab5da1a67871952aef1c2ef7600c',
@@ -147,7 +115,12 @@ function workflowDefinitions(file) {
         const call = ts.isCallExpression(factory.parent) && factory.parent.expression === factory
             ? factory.parent
             : factory;
-        const run = call.arguments[1] && unwrap(call.arguments[1]);
+        const candidate = call.arguments.length === 2
+            ? call.arguments[1]
+            : call.arguments.length === 3
+                ? call.arguments[2]
+                : undefined;
+        const run = candidate && unwrap(candidate);
         return {
             call,
             origin,