@soundscript/soundscript 0.1.12 → 0.1.15

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

@@ -0,0 +1,23 @@
+import ts from 'typescript';
+export function isAnnotationTargetNode(node) {
+    return ts.isStatement(node) ||
+        ts.isBindingElement(node) ||
+        ts.isClassDeclaration(node) ||
+        ts.isClassElement(node) ||
+        ts.isEnumDeclaration(node) ||
+        ts.isEnumMember(node) ||
+        ts.isFunctionDeclaration(node) ||
+        ts.isImportClause(node) ||
+        ts.isImportDeclaration(node) ||
+        ts.isInterfaceDeclaration(node) ||
+        ts.isModuleDeclaration(node) ||
+        ts.isParameter(node) ||
+        ts.isPropertyAssignment(node) ||
+        ts.isShorthandPropertyAssignment(node) ||
+        ts.isTypeElement(node) ||
+        ts.isTypeAliasDeclaration(node);
+}
+export function getNodeStartLine(node) {
+    const sourceFile = node.getSourceFile();
+    return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+}

package/project-transform/src/checker/rules/directives.ts

@@ -0,0 +1,25 @@
+import ts from 'typescript';
+
+export function isAnnotationTargetNode(node: ts.Node): boolean {
+  return ts.isStatement(node) ||
+    ts.isBindingElement(node) ||
+    ts.isClassDeclaration(node) ||
+    ts.isClassElement(node) ||
+    ts.isEnumDeclaration(node) ||
+    ts.isEnumMember(node) ||
+    ts.isFunctionDeclaration(node) ||
+    ts.isImportClause(node) ||
+    ts.isImportDeclaration(node) ||
+    ts.isInterfaceDeclaration(node) ||
+    ts.isModuleDeclaration(node) ||
+    ts.isParameter(node) ||
+    ts.isPropertyAssignment(node) ||
+    ts.isShorthandPropertyAssignment(node) ||
+    ts.isTypeElement(node) ||
+    ts.isTypeAliasDeclaration(node);
+}
+
+export function getNodeStartLine(node: ts.Node): number {
+  const sourceFile = node.getSourceFile();
+  return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+}

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

@@ -0,0 +1,202 @@
+import ts from 'typescript';
+import { SOUND_DIAGNOSTIC_CODES, SOUND_DIAGNOSTIC_MESSAGES } from '../engine/diagnostic_codes.js';
+import { getNodeDiagnosticRange, } from '../diagnostics.js';
+import { getFlowChildRegionStructure, getFlowRegionStructure, materializeConditionStructures, } from './flow_facts.js';
+import { cloneState, FLOW_FACT_ENVIRONMENT, isFunctionLikeWithBody, prepareChildRegionState, recordExecutedExpressionAliases, recordVariableAliases, statementAffectsNarrow, } from './flow_invalidation.js';
+import { isInsideSyntheticErrorNormalizationHelper } from './generated_helpers.js';
+function boundaryKindLabel(kind) {
+    switch (kind) {
+        case 'alias_or_escape':
+            return 'alias or escape';
+        case 'call':
+            return 'call';
+        case 'callback':
+            return 'callback';
+        case 'mutation':
+            return 'mutation';
+        case 'suspension':
+            return 'suspension';
+    }
+}
+function classifyBoundaryKind(node) {
+    if (ts.isAwaitExpression(node) || ts.isYieldExpression(node)) {
+        return 'suspension';
+    }
+    if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+        return 'call';
+    }
+    if (ts.isDeleteExpression(node) ||
+        ts.isPrefixUnaryExpression(node) ||
+        ts.isPostfixUnaryExpression(node) ||
+        (ts.isBinaryExpression(node) &&
+            node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+            node.operatorToken.kind <= ts.SyntaxKind.LastAssignment)) {
+        return 'mutation';
+    }
+    return 'alias_or_escape';
+}
+function formatPathSegment(segment) {
+    if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(segment)) {
+        return `.${segment}`;
+    }
+    if (/^\d+$/.test(segment)) {
+        return `[${segment}]`;
+    }
+    return `[${JSON.stringify(segment)}]`;
+}
+function formatNormalizedPath(context, path) {
+    return `${context.checker.symbolToString(path.baseSymbol)}${path.segments.map(formatPathSegment).join('')}`;
+}
+function formatNodeText(node) {
+    return node.getText(node.getSourceFile()).trim();
+}
+function createRelatedInformation(node, message) {
+    return {
+        message,
+        ...getNodeDiagnosticRange(node),
+    };
+}
+function createDiagnostic(context, invalidation) {
+    const example = 'Re-check after the boundary: `mutate(box); if (box.value !== null) { use(box.value); }`.';
+    const boundaryKind = boundaryKindLabel(invalidation.boundaryKind);
+    const narrowedValue = invalidation.fact
+        ? formatNormalizedPath(context, invalidation.fact.path)
+        : undefined;
+    const invalidatingBoundary = formatNodeText(invalidation.node);
+    const earlierProof = invalidation.fact
+        ? formatNodeText(invalidation.fact.sourceNode)
+        : undefined;
+    return {
+        source: 'sound',
+        code: SOUND_DIAGNOSTIC_CODES.unsoundFlowNarrowing,
+        category: 'error',
+        message: SOUND_DIAGNOSTIC_MESSAGES.unsoundFlowNarrowing,
+        metadata: {
+            rule: 'flow_narrowing_invalidation',
+            primarySymbol: narrowedValue,
+            secondarySymbol: invalidation.boundaryKind,
+            fixability: 'local_rewrite',
+            invariant: 'Narrowing facts cannot cross aliasing, mutation, callback escape, or suspension boundaries that may change the value before use.',
+            replacementFamily: 'recheck_after_boundary',
+            evidence: [
+                ...(narrowedValue ? [{ label: 'narrowedValue', value: narrowedValue }] : []),
+                { label: 'boundaryKind', value: invalidation.boundaryKind },
+                { label: 'invalidatingBoundary', value: invalidatingBoundary },
+                ...(earlierProof ? [{ label: 'earlierProof', value: earlierProof }] : []),
+            ],
+            counterexample: 'A boundary between the check and later use could change the value before the narrowed use runs.',
+            example,
+        },
+        notes: [
+            narrowedValue
+                ? `The earlier check for \`${narrowedValue}\` was invalidated by this ${boundaryKind} boundary.`
+                : 'A call, mutation, callback, alias, or suspension point can change the value after the earlier check.',
+            ...(earlierProof ? [`Earlier proof: \`${earlierProof}\`.`] : []),
+            `Example: ${example}`,
+        ],
+        hint: 'Re-check the value after the invalidating boundary instead of carrying the earlier narrowing forward.',
+        relatedInformation: invalidation.fact
+            ? [createRelatedInformation(invalidation.fact.sourceNode, 'Earlier narrowing established here.')]
+            : undefined,
+        ...getNodeDiagnosticRange(invalidation.node),
+    };
+}
+function findInvalidation(context, statement, activeFacts, state) {
+    for (const fact of activeFacts) {
+        const invalidatingNode = statementAffectsNarrow(context, statement, fact.path, state);
+        if (invalidatingNode) {
+            return {
+                node: invalidatingNode,
+                fact,
+                boundaryKind: classifyBoundaryKind(invalidatingNode),
+            };
+        }
+    }
+    return undefined;
+}
+function analyzeStatements(context, regionNode, statements, state, diagnostics, inheritedFacts = [], options = {}) {
+    const region = regionNode ? getFlowRegionStructure(context, regionNode, statements, options) : {
+        entries: statements.map((statement) => ({
+            statement,
+            sequentialConditions: [],
+        })),
+    };
+    for (const entry of region.entries) {
+        const statement = entry.statement;
+        if (context.isGeneratedNode(statement)) {
+            continue;
+        }
+        const sequentialAnalysis = materializeConditionStructures(context, entry.sequentialConditions, state, FLOW_FACT_ENVIRONMENT);
+        if (sequentialAnalysis.invalidatingNode) {
+            diagnostics.push(createDiagnostic(context, {
+                node: sequentialAnalysis.invalidatingNode,
+                fact: sequentialAnalysis.invalidatedFact,
+                boundaryKind: classifyBoundaryKind(sequentialAnalysis.invalidatingNode),
+            }));
+        }
+        const activeSequentialFacts = [...inheritedFacts, ...sequentialAnalysis.facts];
+        const invalidatingNode = findInvalidation(context, statement, activeSequentialFacts, state);
+        if (invalidatingNode) {
+            diagnostics.push(createDiagnostic(context, invalidatingNode));
+        }
+        if (ts.isVariableStatement(statement)) {
+            for (const declaration of statement.declarationList.declarations) {
+                recordVariableAliases(context, declaration, state);
+            }
+        }
+        else if (ts.isExpressionStatement(statement)) {
+            recordExecutedExpressionAliases(context, statement.expression, state);
+        }
+        const branchState = prepareChildRegionState(context, statement, state);
+        const childRegions = getFlowChildRegionStructure(context, statement).entries;
+        for (const childRegion of childRegions) {
+            const conditionAnalysis = materializeConditionStructures(context, childRegion.entryConditions, branchState, FLOW_FACT_ENVIRONMENT);
+            if (conditionAnalysis.invalidatingNode) {
+                diagnostics.push(createDiagnostic(context, {
+                    node: conditionAnalysis.invalidatingNode,
+                    fact: conditionAnalysis.invalidatedFact,
+                    boundaryKind: classifyBoundaryKind(conditionAnalysis.invalidatingNode),
+                }));
+            }
+            analyzeStatements(context, childRegion.regionNode, childRegion.statements, cloneState(branchState), diagnostics, [...activeSequentialFacts, ...conditionAnalysis.facts], {
+                treatBreakAsExit: childRegion.treatBreakAsExit || options.treatBreakAsExit,
+                treatContinueAsExit: childRegion.treatContinueAsExit || options.treatContinueAsExit,
+            });
+        }
+    }
+}
+function getRootStatements(body) {
+    if (ts.isBlock(body)) {
+        return body.statements;
+    }
+    return [ts.factory.createExpressionStatement(body)];
+}
+function createInitialState() {
+    return {
+        aliases: new Map(),
+        arrayRestAliases: new Map(),
+        boundValues: new Map(),
+        extractedBindings: new Map(),
+        objectRestAliases: new Map(),
+        spreadAliases: new Map(),
+    };
+}
+function analyzeRootRegion(context, regionNode, statements, diagnostics) {
+    analyzeStatements(context, regionNode, statements, createInitialState(), diagnostics);
+}
+export function runFlowRules(context) {
+    const diagnostics = [];
+    context.forEachSourceFile((sourceFile) => {
+        analyzeRootRegion(context, sourceFile, sourceFile.statements.filter((statement) => !context.isGeneratedNode(statement)), diagnostics);
+        context.traverse(sourceFile, (node) => {
+            if (!isFunctionLikeWithBody(node)) {
+                return;
+            }
+            if (isInsideSyntheticErrorNormalizationHelper(node)) {
+                return;
+            }
+            analyzeRootRegion(context, ts.isBlock(node.body) ? node.body : undefined, getRootStatements(node.body).filter((statement) => !context.isGeneratedNode(statement)), diagnostics);
+        });
+    });
+    return diagnostics;
+}

package/project-transform/src/checker/rules/flow.ts

@@ -0,0 +1,333 @@
+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 DiagnosticRelatedInformation,
+  type SoundDiagnostic,
+} from '../diagnostics.ts';
+import {
+  type FlowFact,
+  getFlowChildRegionStructure,
+  getFlowRegionStructure,
+  materializeConditionStructures,
+  type StatementAnalysisOptions,
+} from './flow_facts.ts';
+import {
+  type AnalysisState,
+  cloneState,
+  FLOW_FACT_ENVIRONMENT,
+  isFunctionLikeWithBody,
+  type NormalizedPath,
+  prepareChildRegionState,
+  recordExecutedExpressionAliases,
+  recordVariableAliases,
+  statementAffectsNarrow,
+} from './flow_invalidation.ts';
+import { isInsideSyntheticErrorNormalizationHelper } from './generated_helpers.ts';
+
+type InvalidationBoundaryKind =
+  | 'alias_or_escape'
+  | 'call'
+  | 'callback'
+  | 'mutation'
+  | 'suspension';
+
+interface InvalidationDiagnosticContext {
+  boundaryKind: InvalidationBoundaryKind;
+  fact?: FlowFact<NormalizedPath>;
+  node: ts.Node;
+}
+
+function boundaryKindLabel(kind: InvalidationBoundaryKind): string {
+  switch (kind) {
+    case 'alias_or_escape':
+      return 'alias or escape';
+    case 'call':
+      return 'call';
+    case 'callback':
+      return 'callback';
+    case 'mutation':
+      return 'mutation';
+    case 'suspension':
+      return 'suspension';
+  }
+}
+
+function classifyBoundaryKind(node: ts.Node): InvalidationBoundaryKind {
+  if (ts.isAwaitExpression(node) || ts.isYieldExpression(node)) {
+    return 'suspension';
+  }
+  if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+    return 'call';
+  }
+  if (
+    ts.isDeleteExpression(node) ||
+    ts.isPrefixUnaryExpression(node) ||
+    ts.isPostfixUnaryExpression(node) ||
+    (
+      ts.isBinaryExpression(node) &&
+      node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+      node.operatorToken.kind <= ts.SyntaxKind.LastAssignment
+    )
+  ) {
+    return 'mutation';
+  }
+  return 'alias_or_escape';
+}
+
+function formatPathSegment(segment: string): string {
+  if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(segment)) {
+    return `.${segment}`;
+  }
+  if (/^\d+$/.test(segment)) {
+    return `[${segment}]`;
+  }
+  return `[${JSON.stringify(segment)}]`;
+}
+
+function formatNormalizedPath(
+  context: AnalysisContext,
+  path: NormalizedPath,
+): string {
+  return `${context.checker.symbolToString(path.baseSymbol)}${path.segments.map(formatPathSegment).join('')}`;
+}
+
+function formatNodeText(node: ts.Node): string {
+  return node.getText(node.getSourceFile()).trim();
+}
+
+function createRelatedInformation(
+  node: ts.Node,
+  message: string,
+): DiagnosticRelatedInformation {
+  return {
+    message,
+    ...getNodeDiagnosticRange(node),
+  };
+}
+
+function createDiagnostic(
+  context: AnalysisContext,
+  invalidation: InvalidationDiagnosticContext,
+): SoundDiagnostic {
+  const example =
+    'Re-check after the boundary: `mutate(box); if (box.value !== null) { use(box.value); }`.';
+  const boundaryKind = boundaryKindLabel(invalidation.boundaryKind);
+  const narrowedValue = invalidation.fact
+    ? formatNormalizedPath(context, invalidation.fact.path)
+    : undefined;
+  const invalidatingBoundary = formatNodeText(invalidation.node);
+  const earlierProof = invalidation.fact
+    ? formatNodeText(invalidation.fact.sourceNode)
+    : undefined;
+  return {
+    source: 'sound',
+    code: SOUND_DIAGNOSTIC_CODES.unsoundFlowNarrowing,
+    category: 'error',
+    message: SOUND_DIAGNOSTIC_MESSAGES.unsoundFlowNarrowing,
+    metadata: {
+      rule: 'flow_narrowing_invalidation',
+      primarySymbol: narrowedValue,
+      secondarySymbol: invalidation.boundaryKind,
+      fixability: 'local_rewrite',
+      invariant:
+        'Narrowing facts cannot cross aliasing, mutation, callback escape, or suspension boundaries that may change the value before use.',
+      replacementFamily: 'recheck_after_boundary',
+      evidence: [
+        ...(narrowedValue ? [{ label: 'narrowedValue', value: narrowedValue }] : []),
+        { label: 'boundaryKind', value: invalidation.boundaryKind },
+        { label: 'invalidatingBoundary', value: invalidatingBoundary },
+        ...(earlierProof ? [{ label: 'earlierProof', value: earlierProof }] : []),
+      ],
+      counterexample:
+        'A boundary between the check and later use could change the value before the narrowed use runs.',
+      example,
+    },
+    notes: [
+      narrowedValue
+        ? `The earlier check for \`${narrowedValue}\` was invalidated by this ${boundaryKind} boundary.`
+        : 'A call, mutation, callback, alias, or suspension point can change the value after the earlier check.',
+      ...(earlierProof ? [`Earlier proof: \`${earlierProof}\`.`] : []),
+      `Example: ${example}`,
+    ],
+    hint:
+      'Re-check the value after the invalidating boundary instead of carrying the earlier narrowing forward.',
+    relatedInformation: invalidation.fact
+      ? [createRelatedInformation(invalidation.fact.sourceNode, 'Earlier narrowing established here.')]
+      : undefined,
+    ...getNodeDiagnosticRange(invalidation.node),
+  };
+}
+
+function findInvalidation(
+  context: AnalysisContext,
+  statement: ts.Statement,
+  activeFacts: readonly FlowFact<NormalizedPath>[],
+  state: AnalysisState,
+): InvalidationDiagnosticContext | undefined {
+  for (const fact of activeFacts) {
+    const invalidatingNode = statementAffectsNarrow(context, statement, fact.path, state);
+    if (invalidatingNode) {
+      return {
+        node: invalidatingNode,
+        fact,
+        boundaryKind: classifyBoundaryKind(invalidatingNode),
+      };
+    }
+  }
+
+  return undefined;
+}
+
+function analyzeStatements(
+  context: AnalysisContext,
+  regionNode: ts.Node | undefined,
+  statements: readonly ts.Statement[],
+  state: AnalysisState,
+  diagnostics: SoundDiagnostic[],
+  inheritedFacts: readonly FlowFact<NormalizedPath>[] = [],
+  options: StatementAnalysisOptions = {},
+): void {
+  const region = regionNode ? getFlowRegionStructure(context, regionNode, statements, options) : {
+    entries: statements.map((statement) => ({
+      statement,
+      sequentialConditions: [],
+    })),
+  };
+
+  for (const entry of region.entries) {
+    const statement = entry.statement;
+    if (context.isGeneratedNode(statement)) {
+      continue;
+    }
+
+    const sequentialAnalysis = materializeConditionStructures(
+      context,
+      entry.sequentialConditions,
+      state,
+      FLOW_FACT_ENVIRONMENT,
+    );
+    if (sequentialAnalysis.invalidatingNode) {
+      diagnostics.push(
+        createDiagnostic(context, {
+          node: sequentialAnalysis.invalidatingNode,
+          fact: sequentialAnalysis.invalidatedFact,
+          boundaryKind: classifyBoundaryKind(sequentialAnalysis.invalidatingNode),
+        }),
+      );
+    }
+    const activeSequentialFacts = [...inheritedFacts, ...sequentialAnalysis.facts];
+    const invalidatingNode = findInvalidation(context, statement, activeSequentialFacts, state);
+    if (invalidatingNode) {
+      diagnostics.push(createDiagnostic(context, invalidatingNode));
+    }
+
+    if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        recordVariableAliases(context, declaration, state);
+      }
+    } else if (ts.isExpressionStatement(statement)) {
+      recordExecutedExpressionAliases(context, statement.expression, state);
+    }
+
+    const branchState = prepareChildRegionState(context, statement, state);
+    const childRegions = getFlowChildRegionStructure(context, statement).entries;
+    for (const childRegion of childRegions) {
+      const conditionAnalysis = materializeConditionStructures(
+        context,
+        childRegion.entryConditions,
+        branchState,
+        FLOW_FACT_ENVIRONMENT,
+      );
+      if (conditionAnalysis.invalidatingNode) {
+        diagnostics.push(
+          createDiagnostic(context, {
+            node: conditionAnalysis.invalidatingNode,
+            fact: conditionAnalysis.invalidatedFact,
+            boundaryKind: classifyBoundaryKind(conditionAnalysis.invalidatingNode),
+          }),
+        );
+      }
+
+      analyzeStatements(
+        context,
+        childRegion.regionNode,
+        childRegion.statements,
+        cloneState(branchState),
+        diagnostics,
+        [...activeSequentialFacts, ...conditionAnalysis.facts],
+        {
+          treatBreakAsExit: childRegion.treatBreakAsExit || options.treatBreakAsExit,
+          treatContinueAsExit: childRegion.treatContinueAsExit || options.treatContinueAsExit,
+        },
+      );
+    }
+  }
+}
+
+function getRootStatements(body: ts.FunctionBody | ts.ConciseBody): readonly ts.Statement[] {
+  if (ts.isBlock(body)) {
+    return body.statements;
+  }
+
+  return [ts.factory.createExpressionStatement(body)];
+}
+
+function createInitialState(): AnalysisState {
+  return {
+    aliases: new Map(),
+    arrayRestAliases: new Map(),
+    boundValues: new Map(),
+    extractedBindings: new Map(),
+    objectRestAliases: new Map(),
+    spreadAliases: new Map(),
+  };
+}
+
+function analyzeRootRegion(
+  context: AnalysisContext,
+  regionNode: ts.Node | undefined,
+  statements: readonly ts.Statement[],
+  diagnostics: SoundDiagnostic[],
+): void {
+  analyzeStatements(
+    context,
+    regionNode,
+    statements,
+    createInitialState(),
+    diagnostics,
+  );
+}
+
+export function runFlowRules(context: AnalysisContext): SoundDiagnostic[] {
+  const diagnostics: SoundDiagnostic[] = [];
+
+  context.forEachSourceFile((sourceFile) => {
+    analyzeRootRegion(
+      context,
+      sourceFile,
+      sourceFile.statements.filter((statement) => !context.isGeneratedNode(statement)),
+      diagnostics,
+    );
+
+    context.traverse(sourceFile, (node) => {
+      if (!isFunctionLikeWithBody(node)) {
+        return;
+      }
+      if (isInsideSyntheticErrorNormalizationHelper(node)) {
+        return;
+      }
+
+      analyzeRootRegion(
+        context,
+        ts.isBlock(node.body) ? node.body : undefined,
+        getRootStatements(node.body).filter((statement) => !context.isGeneratedNode(statement)),
+        diagnostics,
+      );
+    });
+  });
+
+  return diagnostics;
+}