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

package/dist/tooling/linter/adapters/typescript/query-observation.js

@@ -0,0 +1,171 @@
+import ts from 'typescript';
+import { ambiguous, known, unknown, } from '../../analysis/query/index.js';
+import { location, resolveImportedSymbol, unwrap, visit } from './syntax.js';
+const SDK_MODULES = new Set(['@astrale-os/sdk', '@astrale-os/sdk/query']);
+const QUERY_MODULES = new Set([
+    '@astrale-os/sdk/query',
+    '@astrale-os/kernel-core',
+    '@astrale-os/kernel-core/graph/query',
+]);
+export function observeQueryDefinitions(project) {
+    return Object.freeze(project.files
+        .filter(({ role, layer }) => role === 'production' && layer === 'queries')
+        .flatMap(observeFile));
+}
+function observeFile(file) {
+    const observations = [];
+    visit(file.source, (node) => {
+        if (!ts.isCallExpression(node))
+            return;
+        const origin = resolveImportedSymbol(file, node.expression);
+        if ((origin.kind !== 'resolved' && origin.kind !== 'ambiguous') ||
+            origin.name !== 'defineQuery' ||
+            (origin.kind === 'resolved' && !SDK_MODULES.has(origin.module))) {
+            return;
+        }
+        const subjectId = `${file.path}#${node.getStart(file.source)}`;
+        const sourceLocation = location(file, node);
+        if (origin.kind === 'ambiguous') {
+            const reason = 'definition resolves through a local facade whose ultimate public constructor origin is unknown';
+            observations.push(Object.freeze({
+                subjectId,
+                location: sourceLocation,
+                constructorIdentity: ambiguous(reason),
+                definitionKind: ambiguous(reason),
+                canonicalRequestCount: ambiguous(reason),
+                buildCallbackCount: ambiguous(reason),
+                projectCallbackCount: ambiguous(reason),
+            }));
+            return;
+        }
+        const object = objectArgument(node);
+        if (!object) {
+            const reason = 'definition input is not a static object literal';
+            observations.push(Object.freeze({
+                subjectId,
+                location: sourceLocation,
+                constructorIdentity: known(sdkConstructorIdentity(file, node.expression)),
+                definitionKind: known('single'),
+                canonicalRequestCount: unknown(reason),
+                buildCallbackCount: unknown(reason),
+                projectCallbackCount: unknown(reason),
+            }));
+            return;
+        }
+        const builds = namedProperties(object, 'build');
+        const projects = namedProperties(object, 'project');
+        const build = callback(builds[0]);
+        observations.push(Object.freeze({
+            subjectId,
+            location: sourceLocation,
+            constructorIdentity: known(sdkConstructorIdentity(file, node.expression)),
+            definitionKind: known('single'),
+            canonicalRequestCount: canonicalRequestCount(file, object, builds, build),
+            buildCallbackCount: builds.length === 1 && !build
+                ? unknown('build callback is forwarded through an opaque authored value')
+                : known(builds.length),
+            projectCallbackCount: known(projects.length),
+        }));
+    });
+    return observations;
+}
+function canonicalRequestCount(file, object, builds, build) {
+    if (!build) {
+        if (builds.length > 0)
+            return unknown('build callback origin is not statically visible');
+        const shorthand = object.properties.some((property) => ts.isShorthandPropertyAssignment(property) && property.name.text === 'build');
+        return shorthand
+            ? unknown('build callback is forwarded through an opaque local helper')
+            : known(0);
+    }
+    const returns = returnedExpressions(build);
+    if (returns.length !== 1) {
+        return ambiguous(`build exposes ${returns.length} statically visible return values`);
+    }
+    const roots = canonicalRoots(file, returns[0]);
+    if (roots === 0) {
+        const returned = returns[0];
+        if (ts.isCallExpression(returned) && ts.isIdentifier(unwrap(returned.expression))) {
+            return unknown('build delegates to a helper whose QueryAST origin is not visible');
+        }
+    }
+    return known(roots);
+}
+function sdkConstructorIdentity(file, expression) {
+    const spelling = expression.getText(file.source);
+    return Object.freeze({
+        kind: 'sdk-query',
+        canonicalId: 'astrale.sdk.defineQuery',
+        aliases: Object.freeze(spelling === 'defineQuery' ? [] : [spelling]),
+    });
+}
+function canonicalRoots(file, node) {
+    const roots = [];
+    visit(node, (candidate) => {
+        if (!ts.isCallExpression(candidate))
+            return;
+        const expression = unwrap(candidate.expression);
+        if (!ts.isPropertyAccessExpression(expression) || !ts.isIdentifier(expression.expression)) {
+            return;
+        }
+        const symbol = resolveImportedSymbol(file, expression.expression);
+        if (symbol.kind === 'resolved' && symbol.name === 'Query' && QUERY_MODULES.has(symbol.module)) {
+            roots.push(candidate);
+        }
+    });
+    return roots.filter((root) => !hasCanonicalAncestor(file, root)).length;
+}
+function hasCanonicalAncestor(file, node) {
+    let current = node.parent;
+    while (current && !ts.isFunctionLike(current)) {
+        if (ts.isCallExpression(current) && isCanonicalCall(file, current))
+            return true;
+        current = current.parent;
+    }
+    return false;
+}
+function isCanonicalCall(file, call) {
+    const expression = unwrap(call.expression);
+    if (!ts.isPropertyAccessExpression(expression) || !ts.isIdentifier(expression.expression)) {
+        return false;
+    }
+    const symbol = resolveImportedSymbol(file, expression.expression);
+    return symbol.kind === 'resolved' && symbol.name === 'Query' && QUERY_MODULES.has(symbol.module);
+}
+function objectArgument(call) {
+    const argument = call.arguments[0];
+    const value = argument && unwrap(argument);
+    return value && ts.isObjectLiteralExpression(value) ? value : undefined;
+}
+function namedProperties(object, name) {
+    return object.properties.filter((property) => 'name' in property &&
+        property.name &&
+        (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) &&
+        property.name.text === name);
+}
+function callback(property) {
+    if (!property)
+        return undefined;
+    if (ts.isMethodDeclaration(property))
+        return property;
+    if (!ts.isPropertyAssignment(property))
+        return undefined;
+    const value = unwrap(property.initializer);
+    return ts.isArrowFunction(value) || ts.isFunctionExpression(value) ? value : undefined;
+}
+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;
+}

package/dist/tooling/linter/adapters/typescript/suppression-directives.d.ts

@@ -0,0 +1,4 @@
+import type { SuppressionDirective } from '../../suppression/index.js';
+import type { SourceProject } from './index.js';
+/** Extracts portable suppression observations from the temporary TypeScript source model. */
+export declare function collectSuppressionDirectives(project: SourceProject): readonly SuppressionDirective[];

package/dist/tooling/linter/adapters/typescript/suppression-directives.js

@@ -0,0 +1,84 @@
+import ts from 'typescript';
+const DIRECTIVE = /^\/\/\s*astrale-disable-next-line\s+([A-Z]+(?:-[A-Z]+)+)\s+--\s+(.+?)\s*$/;
+const DIRECTIVE_NAME = 'astrale-disable-next-line';
+const MAX_REASON_BYTES = 240;
+const MAX_DIRECTIVE_BYTES = 1024;
+/** Extracts portable suppression observations from the temporary TypeScript source model. */
+export function collectSuppressionDirectives(project) {
+    return Object.freeze(project.files.flatMap((file) => scanDirectives(project, file)));
+}
+function scanDirectives(project, file) {
+    const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, file.source.languageVariant, file.text);
+    const directives = [];
+    for (let token = scanner.scan(); token !== ts.SyntaxKind.EndOfFileToken; token = scanner.scan()) {
+        if (token !== ts.SyntaxKind.SingleLineCommentTrivia &&
+            token !== ts.SyntaxKind.MultiLineCommentTrivia)
+            continue;
+        const text = scanner.getTokenText();
+        if (!text.includes(DIRECTIVE_NAME))
+            continue;
+        const offset = scanner.getTokenPos();
+        const position = file.source.getLineAndCharacterOfPosition(offset);
+        const location = Object.freeze({
+            path: file.path,
+            line: position.line + 1,
+            column: position.character + 1,
+            offset,
+            length: Math.max(1, scanner.getTextPos() - offset),
+        });
+        const path = file.path;
+        const line = position.line + 1;
+        const bytes = Buffer.byteLength(text, 'utf8');
+        const lineStart = file.source.getPositionOfLineAndCharacter(position.line, 0);
+        if (file.text.slice(lineStart, offset).trim()) {
+            directives.push(Object.freeze({
+                path,
+                line,
+                location,
+                error: 'Suppression directive must be a standalone comment line.',
+            }));
+            continue;
+        }
+        if (bytes > MAX_DIRECTIVE_BYTES) {
+            directives.push(Object.freeze({
+                path,
+                line,
+                location,
+                error: `Suppression directive is ${bytes} bytes; maximum is ${MAX_DIRECTIVE_BYTES}.`,
+            }));
+            continue;
+        }
+        const match = DIRECTIVE.exec(text);
+        if (!match) {
+            directives.push(Object.freeze({
+                path,
+                line,
+                location,
+                error: 'Suppression must contain exactly one rule ID and use // astrale-disable-next-line ID -- reason.',
+            }));
+            continue;
+        }
+        const [, id, reason] = match;
+        if (!project.policy.catalog.get(id)) {
+            directives.push(Object.freeze({
+                path,
+                line,
+                location,
+                error: `Suppression names unknown rule ${id}.`,
+            }));
+            continue;
+        }
+        const reasonBytes = Buffer.byteLength(reason, 'utf8');
+        if (!reason.trim() || reasonBytes > MAX_REASON_BYTES) {
+            directives.push(Object.freeze({
+                path,
+                line,
+                location,
+                error: `Suppression reason must contain 1-${MAX_REASON_BYTES} bytes.`,
+            }));
+            continue;
+        }
+        directives.push(Object.freeze({ id, reason, path, line, location }));
+    }
+    return directives;
+}

package/dist/tooling/linter/adapters/typescript/syntax.d.ts

@@ -0,0 +1,38 @@
+import ts from 'typescript';
+import type { DiagnosticLocation } from '../../diagnostics/index.js';
+import type { SourceFile } from './index.js';
+export declare function visit(node: ts.Node, callback: (node: ts.Node) => void): void;
+export declare function location(file: SourceFile, node: ts.Node): DiagnosticLocation;
+export declare function importedSymbol(file: SourceFile, expression: ts.Expression): Readonly<{
+    module: string;
+    name: string;
+}> | undefined;
+export type ImportedSymbolResolution = Readonly<{
+    kind: 'resolved';
+    module: string;
+    name: string;
+}> | Readonly<{
+    kind: 'local';
+}> | Readonly<{
+    kind: 'ambiguous';
+    module: string;
+    name: string;
+    reason: 'reexport-origin';
+}>;
+/**
+ * Resolve only directly imported bindings. Local facade and relative imports
+ * preserve their visible module but expose that their ultimate re-export
+ * origin is unresolved, allowing a verifier to report ambiguity when origin
+ * is material to its verdict.
+ */
+export declare function resolveImportedSymbol(file: SourceFile, expression: ts.Expression): ImportedSymbolResolution;
+export declare function isLocallyDeclared(identifier: ts.Identifier): boolean;
+export declare function unwrap(expression: ts.Expression): ts.Expression;
+export declare function staticText(expression: ts.Expression | undefined): string | undefined;
+export declare function objectProperty(object: ts.ObjectLiteralExpression | undefined, name: string): ts.ObjectLiteralElementLike | undefined;
+export declare function propertyName(name: ts.PropertyName): string | undefined;
+export declare function callbackOf(property: ts.ObjectLiteralElementLike | undefined): ts.FunctionLikeDeclaration | undefined;
+export declare function objectArgument(call: ts.CallExpression): ts.ObjectLiteralExpression | undefined;
+export declare function isImportedCall(file: SourceFile, node: ts.Node, modules: ReadonlySet<string>, name: string): node is ts.CallExpression;
+export declare function propertyChain(expression: ts.Expression): readonly string[] | undefined;
+export declare function containingFunction(node: ts.Node): ts.FunctionLikeDeclaration | undefined;

package/dist/tooling/linter/adapters/typescript/syntax.js

@@ -0,0 +1,182 @@
+import ts from 'typescript';
+export function visit(node, callback) {
+    callback(node);
+    node.forEachChild((child) => visit(child, callback));
+}
+export function location(file, node) {
+    const offset = node.getStart(file.source);
+    const position = file.source.getLineAndCharacterOfPosition(offset);
+    return {
+        path: file.path,
+        line: position.line + 1,
+        column: position.character + 1,
+        offset,
+        length: Math.max(1, node.getEnd() - offset),
+    };
+}
+export function importedSymbol(file, expression) {
+    const resolution = resolveImportedSymbol(file, expression);
+    return resolution.kind === 'resolved' || resolution.kind === 'ambiguous'
+        ? { module: resolution.module, name: resolution.name }
+        : undefined;
+}
+/**
+ * Resolve only directly imported bindings. Local facade and relative imports
+ * preserve their visible module but expose that their ultimate re-export
+ * origin is unresolved, allowing a verifier to report ambiguity when origin
+ * is material to its verdict.
+ */
+export function resolveImportedSymbol(file, expression) {
+    const target = unwrap(expression);
+    if (ts.isIdentifier(target)) {
+        if (isLocallyDeclared(target))
+            return { kind: 'local' };
+        for (const sourceImport of file.imports) {
+            for (const [imported, local] of sourceImport.bindings) {
+                if (local === target.text)
+                    return resolution(sourceImport.specifier, imported);
+            }
+        }
+        return { kind: 'local' };
+    }
+    if (ts.isPropertyAccessExpression(target) && ts.isIdentifier(target.expression)) {
+        const rootName = target.expression.text;
+        if (isLocallyDeclared(target.expression))
+            return { kind: 'local' };
+        const sourceImport = file.imports.find(({ namespace }) => namespace === rootName);
+        if (sourceImport)
+            return resolution(sourceImport.specifier, target.name.text);
+    }
+    return { kind: 'local' };
+}
+function resolution(module, name) {
+    return module.startsWith('.') || module.startsWith('#')
+        ? { kind: 'ambiguous', module, name, reason: 'reexport-origin' }
+        : { kind: 'resolved', module, name };
+}
+export function isLocallyDeclared(identifier) {
+    let current = identifier.parent;
+    while (current) {
+        if (ts.isFunctionLike(current)) {
+            if (current.parameters.some(({ name }) => bindingContains(name, identifier.text)))
+                return true;
+            if ('name' in current &&
+                current.name &&
+                ts.isIdentifier(current.name) &&
+                current.name.text === identifier.text &&
+                ts.isFunctionExpression(current)) {
+                return true;
+            }
+        }
+        if (ts.isCatchClause(current) &&
+            current.variableDeclaration &&
+            bindingContains(current.variableDeclaration.name, identifier.text)) {
+            return true;
+        }
+        if (ts.isBlock(current) || ts.isSourceFile(current) || ts.isModuleBlock(current)) {
+            if (current.statements.some((statement) => statementDeclares(statement, identifier.text))) {
+                return true;
+            }
+        }
+        if ((ts.isForStatement(current) ||
+            ts.isForInStatement(current) ||
+            ts.isForOfStatement(current)) &&
+            current.initializer &&
+            ts.isVariableDeclarationList(current.initializer) &&
+            current.initializer.declarations.some(({ name }) => bindingContains(name, identifier.text))) {
+            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) ||
+        ts.isModuleDeclaration(statement)) &&
+        statement.name) {
+        return statement.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) && bindingContains(element.name, name));
+}
+export function unwrap(expression) {
+    let current = expression;
+    while (ts.isParenthesizedExpression(current) ||
+        ts.isAsExpression(current) ||
+        ts.isSatisfiesExpression(current) ||
+        ts.isNonNullExpression(current)) {
+        current = current.expression;
+    }
+    return current;
+}
+export function staticText(expression) {
+    if (!expression)
+        return undefined;
+    const target = unwrap(expression);
+    return ts.isStringLiteral(target) || ts.isNoSubstitutionTemplateLiteral(target)
+        ? target.text
+        : undefined;
+}
+export function objectProperty(object, name) {
+    return object?.properties.find((property) => {
+        if (!('name' in property) || !property.name)
+            return false;
+        return propertyName(property.name) === name;
+    });
+}
+export function propertyName(name) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name))
+        return name.text;
+    return ts.isComputedPropertyName(name) ? staticText(name.expression) : undefined;
+}
+export function callbackOf(property) {
+    if (!property)
+        return undefined;
+    if (ts.isMethodDeclaration(property))
+        return property;
+    if (ts.isPropertyAssignment(property)) {
+        const value = unwrap(property.initializer);
+        if (ts.isArrowFunction(value) || ts.isFunctionExpression(value))
+            return value;
+    }
+    return undefined;
+}
+export function objectArgument(call) {
+    const value = call.arguments[0];
+    return value && ts.isObjectLiteralExpression(unwrap(value))
+        ? unwrap(value)
+        : undefined;
+}
+export function isImportedCall(file, node, modules, name) {
+    if (!ts.isCallExpression(node))
+        return false;
+    const symbol = importedSymbol(file, node.expression);
+    return symbol?.name === name && modules.has(symbol.module);
+}
+export function propertyChain(expression) {
+    const target = unwrap(expression);
+    if (ts.isIdentifier(target))
+        return [target.text];
+    if (!ts.isPropertyAccessExpression(target))
+        return undefined;
+    const root = propertyChain(target.expression);
+    return root ? [...root, target.name.text] : undefined;
+}
+export function containingFunction(node) {
+    let current = node.parent;
+    while (current) {
+        if (ts.isFunctionLike(current) && 'body' in current)
+            return current;
+        current = current.parent;
+    }
+    return undefined;
+}

package/dist/tooling/linter/adapters/typescript/type-universe.d.ts

@@ -0,0 +1 @@
+export declare function assertSingleTypeUniverse(root: string, signal?: AbortSignal): Promise<void>;