@fairfox/polly 0.15.0 → 0.15.4

package/dist/tools/analysis/src/extract/handlers.d.ts

@@ -1,10 +1,17 @@
 import { type SourceFile } from "ts-morph";
 import type { MessageHandler, StateConstraint, VerifiedStateInfo } from "../types";
+export interface ExtractionWarning {
+    type: "unsupported_pattern";
+    pattern: string;
+    location: string;
+    suggestion: string;
+}
 export interface HandlerAnalysis {
     handlers: MessageHandler[];
     messageTypes: Set<string>;
     stateConstraints: StateConstraint[];
     verifiedStates: VerifiedStateInfo[];
+    warnings: ExtractionWarning[];
 }
 export declare class HandlerExtractor {
     private project;
@@ -12,7 +19,16 @@ export declare class HandlerExtractor {
     private relationshipExtractor;
     private analyzedFiles;
     private packageRoot;
+    private warnings;
     constructor(tsConfigPath: string);
+    /**
+     * Emit a warning for an unsupported pattern
+     */
+    private warnUnsupportedPattern;
+    /**
+     * Get a location string for a node
+     */
+    private getNodeLocation;
     /**
      * Find the nearest package.json directory from tsconfig location
      * This defines the package boundary - we only analyze files within this package
@@ -97,11 +113,67 @@ export declare class HandlerExtractor {
      * Extract property access assignment (state.field = value or someState.value.field = value)
      */
     private extractPropertyAccessAssignment;
+    /** Pattern 1: state.field = value */
+    private tryExtractStateFieldPattern;
+    /** Pattern 2: someState.value.field = value (signal pattern with nested field) */
+    private tryExtractSignalNestedFieldPattern;
+    /** Pattern 3: someState.value = { object literal } (signal replacement or spread update) */
+    private tryExtractSignalObjectPattern;
+    /** Check if object literal is a spread update pattern: { ...existing, field: value } */
+    private isSpreadUpdatePattern;
+    /** Pattern 4: someState.value = [...someState.value, item] (array spread) */
+    private tryExtractSignalArrayPattern;
+    /** Pattern 5: someState.value = someState.value.filter(...) or .map(...) (array methods) */
+    private tryExtractSignalMethodPattern;
+    /** Check for mutating Set/Map methods and emit warnings */
+    private checkForMutatingCollectionMethods;
+    /** Heuristic check if an expression might be a Set or Map */
+    private looksLikeSetOrMap;
+    /** Pattern 6: someState.value = new Set([...someState.value, item]) (Set operations) */
+    private tryExtractSetConstructorPattern;
+    /** Pattern 7: someState.value = new Map([...someState.value, [key, val]]) (Map operations) */
+    private tryExtractMapConstructorPattern;
+    /** Extract Set operations from new Set(...) constructor */
+    private extractSetOperation;
+    /** Extract Set operation from array literal: new Set([...set.value, item]) */
+    private extractSetArrayOperation;
+    /** Extract Set operation from method chain: new Set([...set.value].filter(...)) */
+    private extractSetMethodChainOperation;
+    /** Extract Map operations from new Map(...) constructor */
+    private extractMapOperation;
+    /** Extract Map operation from array literal: new Map([...map.value, [key, val]]) */
+    private extractMapArrayOperation;
+    /** Extract Map operation from method chain: new Map([...map.value].filter(...)) */
+    private extractMapMethodChainOperation;
+    /**
+     * Extract array method operations: arr.filter(...), arr.map(...)
+     */
+    private extractArrayMethodOperation;
+    /** Warn about unsupported array methods */
+    private warnUnsupportedArrayMethod;
+    /**
+     * Extract assignments from spread update pattern: { ...existing, field: value }
+     * Only extracts the explicitly set properties, not the spread
+     */
+    private extractSpreadUpdateAssignments;
+    /**
+     * Extract array spread operations: [...arr, item] or [item, ...arr]
+     */
+    private extractArraySpreadOperation;
+    /** Extract append operation: [...arr, item] or [...arr, item1, item2] */
+    private tryExtractAppendOperation;
+    /** Extract prepend operation: [item, ...arr] or [item1, item2, ...arr] */
+    private tryExtractPrependOperation;
     /**
      * Extract assignments from object literal properties
      * Used for: someState.value = { field1: value1, field2: value2 }
+     * @param signalName - Optional signal name prefix (e.g., "user" for user.value = {...})
      */
     private extractObjectLiteralAssignments;
+    /**
+     * Extract a single property assignment from an object literal property
+     */
+    private extractPropertyAssignment;
     /**
      * Extract element access assignment (state.items[index] = value)
      */

package/dist/tools/teach/src/cli.js

@@ -5471,6 +5471,7 @@ class HandlerExtractor {
   relationshipExtractor;
   analyzedFiles;
   packageRoot;
+  warnings;
   constructor(tsConfigPath) {
     this.project = new Project3({
       tsConfigFilePath: tsConfigPath
@@ -5478,8 +5479,27 @@ class HandlerExtractor {
     this.typeGuardCache = new WeakMap;
     this.relationshipExtractor = new RelationshipExtractor;
     this.analyzedFiles = new Set;
+    this.warnings = [];
     this.packageRoot = this.findPackageRoot(tsConfigPath);
   }
+  warnUnsupportedPattern(pattern, location, suggestion) {
+    const exists = this.warnings.some((w) => w.pattern === pattern && w.location === location);
+    if (!exists) {
+      this.warnings.push({
+        type: "unsupported_pattern",
+        pattern,
+        location,
+        suggestion
+      });
+    }
+  }
+  getNodeLocation(node) {
+    const sourceFile = node.getSourceFile();
+    const lineAndCol = sourceFile.getLineAndColumnAtPos(node.getStart());
+    const filePath = sourceFile.getFilePath();
+    const relativePath = filePath.startsWith(this.packageRoot) ? filePath.substring(this.packageRoot.length + 1) : filePath;
+    return `${relativePath}:${lineAndCol.line}`;
+  }
   findPackageRoot(tsConfigPath) {
     let dir = tsConfigPath.substring(0, tsConfigPath.lastIndexOf("/"));
     while (dir.length > 1) {
@@ -5503,6 +5523,7 @@ class HandlerExtractor {
     const invalidMessageTypes = new Set;
     const stateConstraints = [];
     const verifiedStates = [];
+    this.warnings = [];
     const allSourceFiles = this.project.getSourceFiles();
     const entryPoints = allSourceFiles.filter((f) => this.isWithinPackage(f.getFilePath()));
     this.debugLogSourceFiles(allSourceFiles, entryPoints);
@@ -5537,7 +5558,8 @@ class HandlerExtractor {
       handlers,
       messageTypes,
       stateConstraints,
-      verifiedStates
+      verifiedStates,
+      warnings: this.warnings
     };
   }
   analyzeFileAndImports(sourceFile, handlers, messageTypes, invalidMessageTypes, stateConstraints, verifiedStates) {
@@ -5767,46 +5789,364 @@ class HandlerExtractor {
     if (!Node4.isPropertyAccessExpression(left))
       return;
     const fieldPath = this.getPropertyPath(left);
-    if (fieldPath.startsWith("state.")) {
-      const field = fieldPath.substring(6);
-      const value = this.extractValue(right);
-      if (value !== undefined) {
-        assignments.push({ field, value });
-      }
+    if (this.tryExtractStateFieldPattern(fieldPath, right, assignments))
       return;
-    }
-    const valueMatch = fieldPath.match(/\.value\.(.+)$/);
-    if (valueMatch?.[1]) {
-      const field = valueMatch[1];
-      const value = this.extractValue(right);
-      if (value !== undefined) {
-        assignments.push({ field, value });
-      }
+    if (this.tryExtractSignalNestedFieldPattern(fieldPath, right, assignments))
+      return;
+    if (this.tryExtractSignalObjectPattern(fieldPath, right, assignments))
+      return;
+    if (this.tryExtractSignalArrayPattern(fieldPath, right, assignments))
+      return;
+    if (this.tryExtractSignalMethodPattern(fieldPath, right, assignments))
+      return;
+    if (this.tryExtractSetConstructorPattern(fieldPath, right, assignments))
       return;
+    this.tryExtractMapConstructorPattern(fieldPath, right, assignments);
+  }
+  tryExtractStateFieldPattern(fieldPath, right, assignments) {
+    if (!fieldPath.startsWith("state."))
+      return false;
+    const field = fieldPath.substring(6);
+    const value = this.extractValue(right);
+    if (value !== undefined) {
+      assignments.push({ field, value });
     }
-    if (fieldPath.endsWith(".value") && Node4.isObjectLiteralExpression(right)) {
-      this.extractObjectLiteralAssignments(right, assignments);
+    return true;
+  }
+  tryExtractSignalNestedFieldPattern(fieldPath, right, assignments) {
+    const valueFieldMatch = fieldPath.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\.value\.(.+)$/);
+    if (!valueFieldMatch?.[1] || !valueFieldMatch?.[2])
+      return false;
+    const signalName = valueFieldMatch[1];
+    const fieldName = valueFieldMatch[2];
+    const value = this.extractValue(right);
+    if (value !== undefined) {
+      assignments.push({ field: `${signalName}_${fieldName}`, value });
     }
+    return true;
   }
-  extractObjectLiteralAssignments(objectLiteral, assignments) {
-    if (!Node4.isObjectLiteralExpression(objectLiteral))
+  tryExtractSignalObjectPattern(fieldPath, right, assignments) {
+    if (!fieldPath.endsWith(".value") || !Node4.isObjectLiteralExpression(right))
+      return false;
+    const signalName = fieldPath.slice(0, -6);
+    if (this.isSpreadUpdatePattern(right, fieldPath)) {
+      this.extractSpreadUpdateAssignments(right, assignments, signalName);
+    } else {
+      this.extractObjectLiteralAssignments(right, assignments, signalName);
+    }
+    return true;
+  }
+  isSpreadUpdatePattern(objectLiteral, fieldPath) {
+    const properties = objectLiteral.getProperties();
+    if (properties.length === 0)
+      return false;
+    const firstProp = properties[0];
+    if (!firstProp || !Node4.isSpreadAssignment(firstProp))
+      return false;
+    const spreadExpr = firstProp.getExpression();
+    if (!spreadExpr)
+      return false;
+    return this.getPropertyPath(spreadExpr) === fieldPath;
+  }
+  tryExtractSignalArrayPattern(fieldPath, right, assignments) {
+    if (!fieldPath.endsWith(".value") || !Node4.isArrayLiteralExpression(right))
+      return false;
+    const signalName = fieldPath.slice(0, -6);
+    const arrayAssignment = this.extractArraySpreadOperation(right, fieldPath, signalName);
+    if (arrayAssignment) {
+      assignments.push(arrayAssignment);
+    }
+    return true;
+  }
+  tryExtractSignalMethodPattern(fieldPath, right, assignments) {
+    if (!fieldPath.endsWith(".value") || !Node4.isCallExpression(right))
+      return false;
+    const signalName = fieldPath.slice(0, -6);
+    this.checkForMutatingCollectionMethods(right);
+    const methodAssignment = this.extractArrayMethodOperation(right, fieldPath, signalName);
+    if (methodAssignment) {
+      assignments.push(methodAssignment);
+    }
+    return true;
+  }
+  checkForMutatingCollectionMethods(callExpr) {
+    const expression = callExpr.getExpression();
+    if (!Node4.isPropertyAccessExpression(expression))
       return;
-    for (const prop of objectLiteral.getProperties()) {
-      if (Node4.isPropertyAssignment(prop)) {
-        const name = prop.getName();
-        const initializer = prop.getInitializer();
-        if (!name || !initializer)
-          continue;
-        const value = this.extractValue(initializer);
-        if (value !== undefined) {
-          assignments.push({ field: name, value });
+    const methodName = expression.getName();
+    const sourceExpr = expression.getExpression();
+    const setMethods = ["add", "delete", "clear"];
+    if (setMethods.includes(methodName)) {
+      const sourceText = sourceExpr.getText();
+      if (sourceText.includes("Set") || this.looksLikeSetOrMap(sourceExpr, "Set")) {
+        this.warnUnsupportedPattern(`set.${methodName}()`, this.getNodeLocation(callExpr), `Set.${methodName}() mutates in place. Use: new Set([...set, item]) for add, new Set([...set].filter(...)) for delete.`);
+      }
+    }
+    const mapMethods = ["set", "delete", "clear"];
+    if (mapMethods.includes(methodName)) {
+      const sourceText = sourceExpr.getText();
+      if (sourceText.includes("Map") || this.looksLikeSetOrMap(sourceExpr, "Map")) {
+        this.warnUnsupportedPattern(`map.${methodName}()`, this.getNodeLocation(callExpr), `Map.${methodName}() mutates in place. Use: new Map([...map, [key, value]]) for set, new Map([...map].filter(...)) for delete.`);
+      }
+    }
+  }
+  looksLikeSetOrMap(expr, collectionType) {
+    const text = expr.getText().toLowerCase();
+    return text.includes(collectionType.toLowerCase());
+  }
+  tryExtractSetConstructorPattern(fieldPath, right, assignments) {
+    if (!fieldPath.endsWith(".value") || !Node4.isNewExpression(right))
+      return false;
+    const constructorExpr = right.getExpression();
+    if (!Node4.isIdentifier(constructorExpr) || constructorExpr.getText() !== "Set")
+      return false;
+    const signalName = fieldPath.slice(0, -6);
+    const setAssignment = this.extractSetOperation(right, fieldPath, signalName);
+    if (setAssignment) {
+      assignments.push(setAssignment);
+    }
+    return true;
+  }
+  tryExtractMapConstructorPattern(fieldPath, right, assignments) {
+    if (!fieldPath.endsWith(".value") || !Node4.isNewExpression(right))
+      return false;
+    const constructorExpr = right.getExpression();
+    if (!Node4.isIdentifier(constructorExpr) || constructorExpr.getText() !== "Map")
+      return false;
+    const signalName = fieldPath.slice(0, -6);
+    const mapAssignment = this.extractMapOperation(right, fieldPath, signalName);
+    if (mapAssignment) {
+      assignments.push(mapAssignment);
+    }
+    return true;
+  }
+  extractSetOperation(newExpr, fieldPath, signalName) {
+    const args = newExpr.getArguments();
+    if (args.length === 0) {
+      return { field: signalName, value: "{}" };
+    }
+    const firstArg = args[0];
+    if (!firstArg)
+      return null;
+    if (Node4.isArrayLiteralExpression(firstArg)) {
+      return this.extractSetArrayOperation(firstArg, fieldPath, signalName);
+    }
+    if (Node4.isCallExpression(firstArg)) {
+      return this.extractSetMethodChainOperation(firstArg, fieldPath, signalName);
+    }
+    return null;
+  }
+  extractSetArrayOperation(arrayLiteral, fieldPath, signalName) {
+    const elements = arrayLiteral.getElements();
+    if (elements.length < 1)
+      return null;
+    const firstElement = elements[0];
+    const lastElement = elements[elements.length - 1];
+    if (firstElement && Node4.isSpreadElement(firstElement)) {
+      const spreadExpr = firstElement.getExpression();
+      if (spreadExpr && this.getPropertyPath(spreadExpr) === fieldPath) {
+        return { field: signalName, value: "@ \\union {payload}" };
+      }
+    }
+    if (lastElement && Node4.isSpreadElement(lastElement)) {
+      const spreadExpr = lastElement.getExpression();
+      if (spreadExpr && this.getPropertyPath(spreadExpr) === fieldPath) {
+        return { field: signalName, value: "{payload} \\union @" };
+      }
+    }
+    return null;
+  }
+  extractSetMethodChainOperation(callExpr, fieldPath, signalName) {
+    const expression = callExpr.getExpression();
+    if (!Node4.isPropertyAccessExpression(expression))
+      return null;
+    const methodName = expression.getName();
+    const sourceExpr = expression.getExpression();
+    if (methodName === "filter" && Node4.isArrayLiteralExpression(sourceExpr)) {
+      const elements = sourceExpr.getElements();
+      if (elements.length === 1) {
+        const spreadEl = elements[0];
+        if (spreadEl && Node4.isSpreadElement(spreadEl)) {
+          const spreadExpr = spreadEl.getExpression();
+          if (spreadExpr && this.getPropertyPath(spreadExpr) === fieldPath) {
+            return { field: signalName, value: "@ \\ {payload}" };
+          }
         }
       }
-      if (Node4.isShorthandPropertyAssignment(prop)) {
-        const name = prop.getName();
-        assignments.push({ field: name, value: "@" });
+    }
+    return null;
+  }
+  extractMapOperation(newExpr, fieldPath, signalName) {
+    const args = newExpr.getArguments();
+    if (args.length === 0) {
+      return { field: signalName, value: "<<>>" };
+    }
+    const firstArg = args[0];
+    if (!firstArg)
+      return null;
+    if (Node4.isArrayLiteralExpression(firstArg)) {
+      return this.extractMapArrayOperation(firstArg, fieldPath, signalName);
+    }
+    if (Node4.isCallExpression(firstArg)) {
+      return this.extractMapMethodChainOperation(firstArg, fieldPath, signalName);
+    }
+    return null;
+  }
+  extractMapArrayOperation(arrayLiteral, fieldPath, signalName) {
+    const elements = arrayLiteral.getElements();
+    if (elements.length < 1)
+      return null;
+    const firstElement = elements[0];
+    if (firstElement && Node4.isSpreadElement(firstElement)) {
+      const spreadExpr = firstElement.getExpression();
+      if (spreadExpr && this.getPropertyPath(spreadExpr) === fieldPath) {
+        return { field: signalName, value: "[@ EXCEPT ![payload.key] = payload.value]" };
+      }
+    }
+    return null;
+  }
+  extractMapMethodChainOperation(callExpr, fieldPath, signalName) {
+    const expression = callExpr.getExpression();
+    if (!Node4.isPropertyAccessExpression(expression))
+      return null;
+    const methodName = expression.getName();
+    const sourceExpr = expression.getExpression();
+    if (methodName === "filter" && Node4.isArrayLiteralExpression(sourceExpr)) {
+      const elements = sourceExpr.getElements();
+      if (elements.length === 1) {
+        const spreadEl = elements[0];
+        if (spreadEl && Node4.isSpreadElement(spreadEl)) {
+          const spreadExpr = spreadEl.getExpression();
+          if (spreadExpr && this.getPropertyPath(spreadExpr) === fieldPath) {
+            return { field: signalName, value: "[k \\in DOMAIN @ \\ {payload.key} |-> @[k]]" };
+          }
+        }
       }
     }
+    return null;
+  }
+  extractArrayMethodOperation(callExpr, fieldPath, signalName) {
+    const expression = callExpr.getExpression();
+    if (!Node4.isPropertyAccessExpression(expression))
+      return null;
+    const methodName = expression.getName();
+    const sourceExpr = expression.getExpression();
+    const sourcePath = this.getPropertyPath(sourceExpr);
+    if (sourcePath !== fieldPath)
+      return null;
+    switch (methodName) {
+      case "filter":
+        return { field: signalName, value: "SelectSeq(@, LAMBDA t: TRUE)" };
+      case "map":
+        return { field: signalName, value: "[i \\in DOMAIN @ |-> @[i]]" };
+      case "slice":
+        return { field: signalName, value: "SubSeq(@, 1, Len(@))" };
+      case "concat":
+        return { field: signalName, value: "@ \\o <<payload>>" };
+      case "reverse":
+        return { field: signalName, value: "[i \\in DOMAIN @ |-> @[Len(@) - i + 1]]" };
+      default:
+        this.warnUnsupportedArrayMethod(methodName, callExpr);
+        return null;
+    }
+  }
+  warnUnsupportedArrayMethod(methodName, node) {
+    const mutatingMethods = [
+      "push",
+      "pop",
+      "shift",
+      "unshift",
+      "splice",
+      "sort",
+      "fill",
+      "copyWithin"
+    ];
+    const queryMethods = [
+      "find",
+      "findIndex",
+      "reduce",
+      "reduceRight",
+      "some",
+      "every",
+      "includes",
+      "indexOf",
+      "lastIndexOf"
+    ];
+    const otherMethods = ["flat", "flatMap", "join", "toString", "toLocaleString"];
+    if (mutatingMethods.includes(methodName)) {
+      this.warnUnsupportedPattern(`array.${methodName}()`, this.getNodeLocation(node), `'${methodName}' mutates in place. Use spread syntax: [...arr, item] for append, arr.filter() for removal.`);
+    } else if (queryMethods.includes(methodName)) {
+      this.warnUnsupportedPattern(`array.${methodName}()`, this.getNodeLocation(node), `'${methodName}' returns a single value, not a new array. State assignment won't be extracted.`);
+    } else if (otherMethods.includes(methodName)) {
+      this.warnUnsupportedPattern(`array.${methodName}()`, this.getNodeLocation(node), `'${methodName}' is not supported for state extraction. Consider using map/filter instead.`);
+    }
+  }
+  extractSpreadUpdateAssignments(objectLiteral, assignments, signalName) {
+    for (const prop of objectLiteral.getProperties()) {
+      if (Node4.isSpreadAssignment(prop))
+        continue;
+      this.extractPropertyAssignment(prop, assignments, signalName);
+    }
+  }
+  extractArraySpreadOperation(arrayLiteral, fieldPath, signalName) {
+    const elements = arrayLiteral.getElements();
+    if (elements.length < 1)
+      return null;
+    return this.tryExtractAppendOperation(elements, fieldPath, signalName) ?? this.tryExtractPrependOperation(elements, fieldPath, signalName);
+  }
+  tryExtractAppendOperation(elements, fieldPath, signalName) {
+    const firstElement = elements[0];
+    if (!firstElement || !Node4.isSpreadElement(firstElement))
+      return null;
+    const spreadExpr = firstElement.getExpression();
+    if (!spreadExpr || this.getPropertyPath(spreadExpr) !== fieldPath)
+      return null;
+    if (elements.length === 2) {
+      return { field: signalName, value: "Append(@, payload)" };
+    }
+    const placeholders = Array(elements.length - 1).fill("payload").join(", ");
+    return { field: signalName, value: `@ \\o <<${placeholders}>>` };
+  }
+  tryExtractPrependOperation(elements, fieldPath, signalName) {
+    if (elements.length < 2)
+      return null;
+    const lastElement = elements[elements.length - 1];
+    if (!lastElement || !Node4.isSpreadElement(lastElement))
+      return null;
+    const spreadExpr = lastElement.getExpression();
+    if (!spreadExpr || this.getPropertyPath(spreadExpr) !== fieldPath)
+      return null;
+    if (elements.length === 2) {
+      return { field: signalName, value: "<<payload>> \\o @" };
+    }
+    const placeholders = Array(elements.length - 1).fill("payload").join(", ");
+    return { field: signalName, value: `<<${placeholders}>> \\o @` };
+  }
+  extractObjectLiteralAssignments(objectLiteral, assignments, signalName) {
+    if (!Node4.isObjectLiteralExpression(objectLiteral))
+      return;
+    for (const prop of objectLiteral.getProperties()) {
+      this.extractPropertyAssignment(prop, assignments, signalName);
+    }
+  }
+  extractPropertyAssignment(prop, assignments, signalName) {
+    if (Node4.isPropertyAssignment(prop)) {
+      const name = prop.getName();
+      const initializer = prop.getInitializer();
+      if (!name || !initializer)
+        return;
+      const value = this.extractValue(initializer);
+      if (value === undefined)
+        return;
+      const field = signalName ? `${signalName}_${name}` : name;
+      assignments.push({ field, value });
+      return;
+    }
+    if (Node4.isShorthandPropertyAssignment(prop)) {
+      const name = prop.getName();
+      const field = signalName ? `${signalName}_${name}` : name;
+      assignments.push({ field, value: "@" });
+    }
   }
   extractElementAccessAssignment(left, right, assignments) {
     if (!Node4.isElementAccessExpression(left))
@@ -6819,15 +7159,15 @@ class HandlerExtractor {
         if (path3 === `${varName}.value`) {
           const right = node.getRight();
           if (Node4.isObjectLiteralExpression(right)) {
-            this.extractObjectLiteralAssignments(right, mutations);
+            this.extractObjectLiteralAssignments(right, mutations, varName);
           }
           break;
         }
         const fieldPrefix = `${varName}.value.`;
         if (path3.startsWith(fieldPrefix)) {
-          const field = path3.substring(fieldPrefix.length);
+          const fieldName = path3.substring(fieldPrefix.length);
           const value = this.extractValue(node.getRight());
-          mutations.push({ field, value: value ?? "@" });
+          mutations.push({ field: `${varName}_${fieldName}`, value: value ?? "@" });
           break;
         }
       }
@@ -10294,4 +10634,4 @@ Goodbye!`);
 }
 main();
 
-//# debugId=4FDE5BCEB24CA52B64756E2164756E21
+//# debugId=1AD3AF419335104764756E2164756E21