@soundscript/soundscript 0.1.13 → 0.1.15

package/project-transform/src/checker/proof_escape_hatch_diagnostics.ts

@@ -0,0 +1,173 @@
+import ts from 'typescript';
+
+import { SOUND_DIAGNOSTIC_CODES, SOUND_DIAGNOSTIC_MESSAGES } from './engine/diagnostic_codes.ts';
+import type { AnalysisContext } from './engine/types.ts';
+import { getNodeDiagnosticRange, type SoundDiagnostic } from './diagnostics.ts';
+
+const ANY_TYPE_EXAMPLE =
+  'Replace `any` with `unknown`, then narrow or validate before use, or spell the precise type you expect.';
+const TYPE_ASSERTION_EXAMPLE =
+  'Replace the assertion with a real runtime check, a validated interop boundary, or a helper that already returns the target type honestly.';
+const NON_NULL_ASSERTION_EXAMPLE =
+  'Check the value first, or normalize it with a real fallback before using it as present.';
+const DEFINITE_ASSIGNMENT_ASSERTION_EXAMPLE =
+  'Initialize the declaration directly, widen it to include `undefined`, or move the unchecked assumption to a local `// #[unsafe] let x!: T` site that the backend can still represent honestly.';
+
+function createDiagnostic(
+  node: ts.Node,
+  code:
+    | typeof SOUND_DIAGNOSTIC_CODES.anyType
+    | typeof SOUND_DIAGNOSTIC_CODES.definiteAssignmentAssertion
+    | typeof SOUND_DIAGNOSTIC_CODES.nonNullAssertion
+    | typeof SOUND_DIAGNOSTIC_CODES.typeAssertion,
+  message: string,
+  options?: {
+    hint?: string;
+    metadata?: SoundDiagnostic['metadata'];
+    notes?: string[];
+  },
+): SoundDiagnostic {
+  return {
+    source: 'sound',
+    code,
+    category: 'error',
+    message,
+    metadata: options?.metadata,
+    notes: options?.notes,
+    hint: options?.hint,
+    ...getNodeDiagnosticRange(node),
+  };
+}
+
+export function createAnyTypeDiagnostic(node: ts.Node): SoundDiagnostic {
+  return createDiagnostic(
+    node,
+    SOUND_DIAGNOSTIC_CODES.anyType,
+    SOUND_DIAGNOSTIC_MESSAGES.anyType,
+    {
+      metadata: {
+        rule: 'any_type',
+        fixability: 'local_rewrite',
+        invariant:
+          'Checked soundscript code must preserve honest type information instead of erasing it to `any`.',
+        replacementFamily: 'unknown_plus_validation',
+        counterexample:
+          'Using `any` lets unchecked assumptions flow outward and disables the proof obligations soundscript relies on.',
+        example: ANY_TYPE_EXAMPLE,
+      },
+      notes: [
+        '`any` erases the type information that checked soundscript code relies on.',
+        `Example: ${ANY_TYPE_EXAMPLE}`,
+      ],
+      hint:
+        'Replace `any` with `unknown` plus validation, or write the precise type directly.',
+    },
+  );
+}
+
+export function createTypeAssertionDiagnostic(
+  context: AnalysisContext,
+  node: ts.TypeAssertion | ts.AsExpression,
+): SoundDiagnostic {
+  const expressionType = context.checker.typeToString(context.checker.getTypeAtLocation(node.expression));
+  const assertedType = context.checker.typeToString(context.checker.getTypeFromTypeNode(node.type));
+
+  return createDiagnostic(
+    node,
+    SOUND_DIAGNOSTIC_CODES.typeAssertion,
+    SOUND_DIAGNOSTIC_MESSAGES.typeAssertion,
+    {
+      metadata: {
+        rule: 'unchecked_type_assertion',
+        fixability: 'local_rewrite',
+        invariant:
+          'Checked soundscript code must prove the target type instead of asserting it without evidence.',
+        replacementFamily: 'control_flow_narrowing_or_boundary_validation',
+        evidence: [
+          { label: 'expressionType', value: expressionType },
+          { label: 'assertedType', value: assertedType },
+        ],
+        counterexample:
+          'A type assertion can claim a value has structure or variants that the checker never proved.',
+        example: TYPE_ASSERTION_EXAMPLE,
+      },
+      notes: [
+        `This assertion changes the type from '${expressionType}' to '${assertedType}' without a checked proof.`,
+        `Example: ${TYPE_ASSERTION_EXAMPLE}`,
+      ],
+      hint:
+        'Use narrowing, validation, or an interop boundary instead of asserting the target type.',
+    },
+  );
+}
+
+export function createNonNullAssertionDiagnostic(
+  context: AnalysisContext,
+  node: ts.NonNullExpression,
+): SoundDiagnostic {
+  const expressionType = context.checker.typeToString(context.checker.getTypeAtLocation(node.expression));
+
+  return createDiagnostic(
+    node,
+    SOUND_DIAGNOSTIC_CODES.nonNullAssertion,
+    SOUND_DIAGNOSTIC_MESSAGES.nonNullAssertion,
+    {
+      metadata: {
+        rule: 'unchecked_non_null_assertion',
+        fixability: 'local_rewrite',
+        invariant:
+          'Checked soundscript code must prove that maybe-null values are present before using them as non-null.',
+        replacementFamily: 'explicit_null_check',
+        evidence: [{ label: 'expressionType', value: expressionType }],
+        counterexample:
+          'A non-null assertion can pretend a maybe-null value is present even though another path still allows `null` or `undefined`.',
+        example: NON_NULL_ASSERTION_EXAMPLE,
+      },
+      notes: [
+        `This expression has type '${expressionType}', but \`!\` skips the proof that it is present.`,
+        `Example: ${NON_NULL_ASSERTION_EXAMPLE}`,
+      ],
+      hint:
+        'Re-check the value or provide an explicit fallback before using it as non-null.',
+    },
+  );
+}
+
+export function createDefiniteAssignmentAssertionDiagnostic(
+  context: AnalysisContext,
+  node: ts.VariableDeclaration | ts.PropertyDeclaration,
+): SoundDiagnostic {
+  const typeText = node.type
+    ? context.checker.typeToString(context.checker.getTypeFromTypeNode(node.type))
+    : context.checker.typeToString(context.checker.getTypeAtLocation(node.name));
+  const targetText = ts.isIdentifier(node.name) ? node.name.text : node.name.getText();
+  const diagnosticNode = node.exclamationToken ?? node.name;
+
+  return createDiagnostic(
+    diagnosticNode,
+    SOUND_DIAGNOSTIC_CODES.definiteAssignmentAssertion,
+    SOUND_DIAGNOSTIC_MESSAGES.definiteAssignmentAssertion,
+    {
+      metadata: {
+        rule: 'unchecked_definite_assignment_assertion',
+        fixability: 'local_rewrite',
+        invariant:
+          'Checked soundscript code must not claim that storage is initialized before the checker can prove that write happened.',
+        replacementFamily: 'initializer_or_explicit_optional_state',
+        evidence: [
+          { label: 'target', value: targetText },
+          { label: 'assertedType', value: typeText },
+        ],
+        counterexample:
+          'A definite-assignment assertion can let code read an uninitialized local or field as if the promised value already existed.',
+        example: DEFINITE_ASSIGNMENT_ASSERTION_EXAMPLE,
+      },
+      notes: [
+        `This declaration claims '${targetText}' is definitely assigned as '${typeText}' without a checked proof.`,
+        `Example: ${DEFINITE_ASSIGNMENT_ASSERTION_EXAMPLE}`,
+      ],
+      hint:
+        'Add an initializer, widen the type to include absence, or move the unchecked claim to a supported local unsafe site.',
+    },
+  );
+}

package/project-transform/src/checker/rules/async_surface.js

@@ -0,0 +1,231 @@
+import ts from 'typescript';
+import { SOUND_DIAGNOSTIC_CODES, SOUND_DIAGNOSTIC_MESSAGES } from '../engine/diagnostic_codes.js';
+import { getNodeDiagnosticRange } from '../diagnostics.js';
+import { isForeignSourceFile } from '../../soundscript_packages.js';
+import { matchesResolvedBuiltinCallableValue, matchesResolvedBuiltinSignature, } from './resolved_builtins.js';
+function describeSurfaceKind(surfaceKind) {
+    switch (surfaceKind) {
+        case 'thenable surface':
+            return 'structural thenable';
+        case 'awaited thenable':
+            return 'thenable awaited through `await`';
+        case 'promise resolve thenable':
+            return 'thenable normalized through `Promise.resolve`';
+        case 'promise subclass':
+            return 'Promise subclass';
+    }
+}
+function createDiagnostic(info) {
+    return {
+        source: 'sound',
+        code: SOUND_DIAGNOSTIC_CODES.unsupportedAsyncSurface,
+        category: 'error',
+        message: SOUND_DIAGNOSTIC_MESSAGES.unsupportedAsyncSurface,
+        metadata: {
+            rule: 'unsupported_async_surface',
+            primarySymbol: info.primarySymbol,
+            fixability: 'api_redesign',
+            invariant: 'soundscript only models compiler-owned Promise semantics, not structural thenables or Promise subclass behavior.',
+            replacementFamily: 'builtin_promise_surface',
+            evidence: [
+                { label: 'surfaceKind', value: info.surfaceKind },
+                { label: 'surfaceText', value: info.surfaceText },
+            ],
+            counterexample: 'Structural thenables can run arbitrary fulfillment behavior outside the compiler-owned Promise semantics soundscript models.',
+            example: `Replace \`${info.surfaceText}\` with \`Promise<number>\`, or normalize the foreign thenable at a boundary before it reaches checked soundscript code.`,
+        },
+        notes: [
+            `This async surface uses \`${info.surfaceText}\`, which is a ${describeSurfaceKind(info.surfaceKind)} rather than a builtin \`Promise<T>\` surface.`,
+            `Example: Replace \`${info.surfaceText}\` with \`Promise<number>\`, or normalize the foreign thenable at a boundary before it reaches checked soundscript code.`,
+        ],
+        hint: 'Use plain `Promise<T>` surfaces in soundscript, and normalize foreign thenables at the boundary.',
+        ...getNodeDiagnosticRange(info.node),
+    };
+}
+function resolveAliasedSymbol(checker, symbol) {
+    let current = symbol;
+    while ((current.flags & ts.SymbolFlags.Alias) !== 0) {
+        const aliased = checker.getAliasedSymbol(current);
+        if (aliased === current) {
+            break;
+        }
+        current = aliased;
+    }
+    return current;
+}
+function isDeclarationBackedBuiltinSymbolNamed(checker, symbol, name) {
+    if (!symbol) {
+        return false;
+    }
+    const resolved = resolveAliasedSymbol(checker, symbol);
+    if (resolved.getName() !== name) {
+        return false;
+    }
+    const declarations = resolved.declarations ?? [];
+    return declarations.length > 0 &&
+        declarations.every((declaration) => declaration.getSourceFile().isDeclarationFile);
+}
+function getPromisedType(checker, type) {
+    return checker.getPromisedTypeOfPromise(type);
+}
+function getSurfaceText(context, node) {
+    if (ts.isTypeReferenceNode(node) ||
+        ts.isImportTypeNode(node) ||
+        ts.isTypeLiteralNode(node)) {
+        return node.getText();
+    }
+    if ((ts.isInterfaceDeclaration(node) || ts.isClassDeclaration(node) || ts.isClassExpression(node)) && node.name) {
+        const declaredType = getSurfaceType(context, node);
+        if (declaredType) {
+            return context.checker.typeToString(declaredType);
+        }
+        return node.name.text;
+    }
+    return context.checker.typeToString(context.checker.getTypeAtLocation(node));
+}
+function getSurfacePrimarySymbol(node) {
+    if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName)) {
+        return node.typeName.text;
+    }
+    if ((ts.isInterfaceDeclaration(node) || ts.isClassDeclaration(node) || ts.isClassExpression(node)) && node.name) {
+        return node.name.text;
+    }
+    return undefined;
+}
+function isBuiltinPromiseType(checker, type) {
+    return isDeclarationBackedBuiltinSymbolNamed(checker, type.aliasSymbol, 'Promise') ||
+        isDeclarationBackedBuiltinSymbolNamed(checker, type.getSymbol(), 'Promise');
+}
+function hasUnsupportedThenableBranch(context, type, seen) {
+    if (seen.has(type)) {
+        return false;
+    }
+    seen.add(type);
+    if (type.isUnionOrIntersection()) {
+        return type.types.some((part) => hasUnsupportedThenableBranch(context, part, seen));
+    }
+    const promisedType = getPromisedType(context.checker, type);
+    if (!promisedType) {
+        return false;
+    }
+    return !isBuiltinPromiseType(context.checker, type);
+}
+function isUnsupportedThenableType(context, type) {
+    return hasUnsupportedThenableBranch(context, type, new Set());
+}
+function getSurfaceType(context, node) {
+    if ((ts.isClassDeclaration(node) || ts.isClassExpression(node) || ts.isInterfaceDeclaration(node)) &&
+        node.name) {
+        const symbol = context.checker.getSymbolAtLocation(node.name);
+        return symbol ? context.checker.getDeclaredTypeOfSymbol(symbol) : undefined;
+    }
+    return context.checker.getTypeAtLocation(node);
+}
+function getPromiseSubclassDiagnosticInfo(context, node) {
+    if (!ts.isClassDeclaration(node) && !ts.isClassExpression(node)) {
+        return undefined;
+    }
+    for (const heritageClause of node.heritageClauses ?? []) {
+        if (heritageClause.token !== ts.SyntaxKind.ExtendsKeyword) {
+            continue;
+        }
+        for (const heritageType of heritageClause.types) {
+            const heritageSymbol = context.checker.getSymbolAtLocation(heritageType.expression);
+            const heritageValueType = context.checker.getTypeAtLocation(heritageType.expression);
+            if (isDeclarationBackedBuiltinSymbolNamed(context.checker, heritageSymbol, 'Promise') ||
+                isDeclarationBackedBuiltinSymbolNamed(context.checker, heritageValueType.aliasSymbol, 'PromiseConstructor') ||
+                isDeclarationBackedBuiltinSymbolNamed(context.checker, heritageValueType.getSymbol(), 'PromiseConstructor')) {
+                return {
+                    node: heritageType.expression,
+                    primarySymbol: node.name?.text ?? 'Promise',
+                    surfaceKind: 'promise subclass',
+                    surfaceText: node.name?.text ?? heritageType.getText(),
+                };
+            }
+        }
+    }
+    return undefined;
+}
+function getThenableSurfaceDiagnosticInfo(context, node) {
+    if (!ts.isTypeReferenceNode(node) &&
+        !ts.isImportTypeNode(node) &&
+        !ts.isTypeLiteralNode(node) &&
+        !ts.isInterfaceDeclaration(node) &&
+        !ts.isClassDeclaration(node) &&
+        !ts.isClassExpression(node) &&
+        !ts.isObjectLiteralExpression(node)) {
+        return undefined;
+    }
+    const type = getSurfaceType(context, node);
+    return type && isUnsupportedThenableType(context, type)
+        ? {
+            node,
+            primarySymbol: getSurfacePrimarySymbol(node),
+            surfaceKind: 'thenable surface',
+            surfaceText: getSurfaceText(context, node),
+        }
+        : undefined;
+}
+function getAwaitDiagnosticInfo(context, node) {
+    if (!ts.isAwaitExpression(node)) {
+        return undefined;
+    }
+    return isUnsupportedThenableType(context, context.checker.getTypeAtLocation(node.expression))
+        ? {
+            node: node.expression,
+            primarySymbol: getSurfacePrimarySymbol(node.expression),
+            surfaceKind: 'awaited thenable',
+            surfaceText: getSurfaceText(context, node.expression),
+        }
+        : undefined;
+}
+function getPromiseResolveDiagnosticInfo(context, node) {
+    if (!ts.isCallExpression(node) ||
+        node.arguments.length === 0 ||
+        !(matchesResolvedBuiltinSignature(context, node, {
+            ownerNames: ['PromiseConstructor'],
+            memberNames: ['resolve'],
+        }) ||
+            matchesResolvedBuiltinCallableValue(context, node.expression, {
+                ownerNames: ['PromiseConstructor'],
+                memberNames: ['resolve'],
+            }))) {
+        return undefined;
+    }
+    return isUnsupportedThenableType(context, context.checker.getTypeAtLocation(node.arguments[0]))
+        ? {
+            node: node.arguments[0],
+            primarySymbol: getSurfacePrimarySymbol(node.arguments[0]),
+            surfaceKind: 'promise resolve thenable',
+            surfaceText: getSurfaceText(context, node.arguments[0]),
+        }
+        : undefined;
+}
+export function runAsyncSurfaceRules(context) {
+    const diagnostics = [];
+    const seen = new Set();
+    function pushDiagnostic(info) {
+        if (!info) {
+            return;
+        }
+        const range = getNodeDiagnosticRange(info.node);
+        const key = `${range.filePath}:${range.line}:${range.column}:${range.endLine}:${range.endColumn}`;
+        if (seen.has(key)) {
+            return;
+        }
+        seen.add(key);
+        diagnostics.push(createDiagnostic(info));
+    }
+    context.forEachSourceFile((sourceFile) => {
+        if (isForeignSourceFile(sourceFile.fileName, ts.sys)) {
+            return;
+        }
+        context.traverse(sourceFile, (node) => {
+            pushDiagnostic(getPromiseSubclassDiagnosticInfo(context, node));
+            pushDiagnostic(getThenableSurfaceDiagnosticInfo(context, node));
+            pushDiagnostic(getAwaitDiagnosticInfo(context, node));
+            pushDiagnostic(getPromiseResolveDiagnosticInfo(context, node));
+        });
+    });
+    return diagnostics;
+}