@fairfox/polly 0.1.1 → 0.1.3

package/vendor/verify/src/adapters/web-extension/index.ts

@@ -0,0 +1,508 @@
+// ═══════════════════════════════════════════════════════════════
+// Web Extension Adapter
+// ═══════════════════════════════════════════════════════════════
+//
+// Extracts verification model from Chrome extension codebases.
+// Recognizes:
+// - Extension contexts (background, content, popup, etc.)
+// - MessageBus.on() pattern for message handling
+// - State mutations via state.field = value
+// - Verification primitives (requires, ensures)
+
+import { Project, type SourceFile, SyntaxKind, Node } from "ts-morph";
+import type {
+  CoreVerificationModel,
+  MessageHandler,
+  StateAssignment,
+  VerificationCondition,
+  NodeDefinition,
+  MessageType,
+  RoutingRule,
+} from "../../core/model";
+import type { AdapterConfig, RoutingAdapter } from "../base";
+
+// ─────────────────────────────────────────────────────────────────
+// Configuration
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Extension contexts that can send/receive messages
+ */
+export type ExtensionContext =
+  | "background"
+  | "content"
+  | "popup"
+  | "devtools"
+  | "options"
+  | "offscreen"
+  | "sidepanel";
+
+export interface WebExtensionAdapterConfig extends AdapterConfig {
+  /** Which contexts to analyze (default: all) */
+  contexts?: ExtensionContext[];
+
+  /** Whether to detect tab-based message routing */
+  detectTabBased?: boolean;
+
+  /** Maximum number of tabs to model (default: 1) */
+  maxTabs?: number;
+
+  /** Maximum messages in flight (default: 3) */
+  maxInFlight?: number;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Web Extension Adapter Implementation
+// ─────────────────────────────────────────────────────────────────
+
+export class WebExtensionAdapter implements RoutingAdapter<WebExtensionAdapterConfig> {
+  readonly name = "web-extension";
+  readonly config: WebExtensionAdapterConfig;
+  private project: Project;
+
+  constructor(config: WebExtensionAdapterConfig) {
+    this.config = {
+      contexts: ["background", "content", "popup", "devtools", "options", "offscreen", "sidepanel"],
+      detectTabBased: true,
+      maxTabs: 1,
+      maxInFlight: 3,
+      ...config,
+    };
+
+    this.project = new Project({
+      tsConfigFilePath: config.tsConfigPath,
+    });
+  }
+
+  /**
+   * Extract the complete verification model from the extension codebase
+   */
+  extractModel(): CoreVerificationModel {
+    const sourceFiles = this.project.getSourceFiles();
+
+    // Extract all handlers
+    const handlers: MessageHandler[] = [];
+    const messageTypeNames = new Set<string>();
+
+    for (const sourceFile of sourceFiles) {
+      const fileHandlers = this.extractHandlersFromFile(sourceFile);
+      handlers.push(...fileHandlers);
+
+      for (const handler of fileHandlers) {
+        messageTypeNames.add(handler.messageType);
+      }
+    }
+
+    // Define nodes (extension contexts)
+    const nodes: NodeDefinition[] = [];
+    for (const context of this.config.contexts!) {
+      nodes.push({
+        id: context,
+        type: "extension-context",
+        canSendTo: ["*"], // Extensions can send to any context
+        canReceiveFrom: ["*"], // Extensions can receive from any context
+        metadata: {
+          isServiceWorker: context === "background",
+          isContentScript: context === "content",
+        },
+      });
+    }
+
+    // Define message types
+    const messageTypes: MessageType[] = Array.from(messageTypeNames).map((name) => ({
+      name,
+      payload: {
+        name: "unknown",
+        kind: "unknown",
+        nullable: false,
+      },
+      routing: {
+        from: ["*"],
+        to: ["*"],
+      },
+    }));
+
+    // Define routing rules (extension uses request-reply pattern)
+    const routingRules: RoutingRule[] = [
+      {
+        pattern: "request-reply",
+        messageTypes: Array.from(messageTypeNames),
+        description: "Chrome extension message passing with chrome.runtime.sendMessage",
+      },
+    ];
+
+    return {
+      nodes,
+      messageTypes,
+      routingRules,
+      state: {}, // Populated by user configuration
+      handlers,
+      bounds: {
+        maxConcurrentMessages: this.config.maxInFlight!,
+        maxNodes: nodes.length,
+        custom: {
+          maxTabs: this.config.maxTabs!,
+        },
+      },
+    };
+  }
+
+  /**
+   * Recognize message handler registration: bus.on("TYPE", handler)
+   */
+  recognizeMessageHandler(node: Node): MessageHandler | null {
+    if (!Node.isCallExpression(node)) {
+      return null;
+    }
+
+    const expression = node.getExpression();
+
+    // Check if this is a .on() call
+    if (!Node.isPropertyAccessExpression(expression)) {
+      return null;
+    }
+
+    const methodName = expression.getName();
+    if (methodName !== "on") {
+      return null;
+    }
+
+    return this.extractHandlerFromOnCall(node);
+  }
+
+  /**
+   * Recognize state mutation: state.field = value
+   */
+  recognizeStateUpdate(node: Node): StateAssignment | null {
+    if (!Node.isBinaryExpression(node)) {
+      return null;
+    }
+
+    const operator = node.getOperatorToken().getText();
+    if (operator !== "=") {
+      return null;
+    }
+
+    const left = node.getLeft();
+    const right = node.getRight();
+
+    // Check if left side is a state property access
+    if (!Node.isPropertyAccessExpression(left)) {
+      return null;
+    }
+
+    const fieldPath = this.getPropertyPath(left);
+
+    // Check if this is a state access
+    if (!fieldPath.startsWith("state.")) {
+      return null;
+    }
+
+    const field = fieldPath.substring(6); // Remove "state." prefix
+    const value = this.extractValue(right);
+
+    if (value === undefined) {
+      return null;
+    }
+
+    return {
+      field,
+      value,
+    };
+  }
+
+  /**
+   * Recognize verification condition: requires() or ensures()
+   */
+  recognizeVerificationCondition(
+    node: Node,
+    type: "precondition" | "postcondition"
+  ): VerificationCondition | null {
+    if (!Node.isCallExpression(node)) {
+      return null;
+    }
+
+    const callee = node.getExpression();
+    if (!Node.isIdentifier(callee)) {
+      return null;
+    }
+
+    const functionName = callee.getText();
+    const expectedName = type === "precondition" ? "requires" : "ensures";
+
+    if (functionName !== expectedName) {
+      return null;
+    }
+
+    return this.extractCondition(node);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Private Helper Methods
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Extract all handlers from a source file
+   */
+  private extractHandlersFromFile(sourceFile: SourceFile): MessageHandler[] {
+    const handlers: MessageHandler[] = [];
+    const filePath = sourceFile.getFilePath();
+    const context = this.inferContextFromPath(filePath);
+
+    sourceFile.forEachDescendant((node) => {
+      const handler = this.recognizeMessageHandler(node);
+      if (handler) {
+        // Override context with inferred value
+        handlers.push({
+          ...handler,
+          node: context,
+        });
+      }
+    });
+
+    return handlers;
+  }
+
+  /**
+   * Extract handler details from a .on() call expression
+   */
+  private extractHandlerFromOnCall(callExpr: Node): MessageHandler | null {
+    if (!Node.isCallExpression(callExpr)) {
+      return null;
+    }
+
+    const args = callExpr.getArguments();
+
+    if (args.length < 2) {
+      return null;
+    }
+
+    // First argument should be the message type (string literal)
+    const messageTypeArg = args[0];
+    let messageType: string | null = null;
+
+    if (Node.isStringLiteral(messageTypeArg)) {
+      messageType = messageTypeArg.getLiteralValue();
+    } else if (Node.isTemplateExpression(messageTypeArg)) {
+      messageType = messageTypeArg.getText().replace(/[`'"]/g, "");
+    }
+
+    if (!messageType) {
+      return null;
+    }
+
+    // Second argument is the handler function
+    const handlerArg = args[1];
+    const assignments: StateAssignment[] = [];
+    const preconditions: VerificationCondition[] = [];
+    const postconditions: VerificationCondition[] = [];
+
+    // Parse the handler function for state assignments and verification conditions
+    if (Node.isArrowFunction(handlerArg) || Node.isFunctionExpression(handlerArg)) {
+      this.extractAssignmentsFromFunction(handlerArg, assignments);
+      this.extractVerificationConditionsFromFunction(handlerArg, preconditions, postconditions);
+    }
+
+    const sourceFile = callExpr.getSourceFile();
+    const line = callExpr.getStartLineNumber();
+
+    return {
+      messageType,
+      node: "unknown", // Will be overridden by extractHandlersFromFile
+      assignments,
+      preconditions,
+      postconditions,
+      location: {
+        file: sourceFile.getFilePath(),
+        line,
+      },
+    };
+  }
+
+  /**
+   * Extract state assignments from a handler function
+   */
+  private extractAssignmentsFromFunction(funcNode: Node, assignments: StateAssignment[]): void {
+    funcNode.forEachDescendant((node) => {
+      const assignment = this.recognizeStateUpdate(node);
+      if (assignment) {
+        assignments.push(assignment);
+      }
+    });
+  }
+
+  /**
+   * Extract verification conditions from a handler function
+   */
+  private extractVerificationConditionsFromFunction(
+    funcNode: Node,
+    preconditions: VerificationCondition[],
+    postconditions: VerificationCondition[]
+  ): void {
+    const body =
+      Node.isArrowFunction(funcNode) || Node.isFunctionExpression(funcNode)
+        ? funcNode.getBody()
+        : funcNode;
+
+    if (!body) {
+      return;
+    }
+
+    // Get all statements in the function body
+    const statements = Node.isBlock(body) ? body.getStatements() : [body];
+
+    for (const statement of statements) {
+      // Look for expression statements that are function calls
+      if (Node.isExpressionStatement(statement)) {
+        const expr = statement.getExpression();
+
+        const precond = this.recognizeVerificationCondition(expr, "precondition");
+        if (precond) {
+          preconditions.push(precond);
+        }
+
+        const postcond = this.recognizeVerificationCondition(expr, "postcondition");
+        if (postcond) {
+          postconditions.push(postcond);
+        }
+      }
+    }
+  }
+
+  /**
+   * Extract condition from a requires() or ensures() call
+   */
+  private extractCondition(callExpr: Node): VerificationCondition | null {
+    if (!Node.isCallExpression(callExpr)) {
+      return null;
+    }
+
+    const args = callExpr.getArguments();
+
+    if (args.length === 0) {
+      return null;
+    }
+
+    // First argument is the condition expression
+    const conditionArg = args[0];
+    const expression = conditionArg.getText();
+
+    // Second argument (optional) is the message
+    let message: string | undefined;
+    if (args.length >= 2 && Node.isStringLiteral(args[1])) {
+      message = args[1].getLiteralValue();
+    }
+
+    const line = callExpr.getStartLineNumber();
+    const column = callExpr.getStart();
+
+    return {
+      expression,
+      message,
+      location: {
+        line,
+        column,
+      },
+    };
+  }
+
+  /**
+   * Get the full property access path (e.g., "state.user.loggedIn")
+   */
+  private getPropertyPath(node: Node): string {
+    const parts: string[] = [];
+
+    let current: Node = node;
+    while (Node.isPropertyAccessExpression(current)) {
+      parts.unshift(current.getName());
+      current = current.getExpression();
+    }
+
+    // Add the base identifier
+    if (Node.isIdentifier(current)) {
+      parts.unshift(current.getText());
+    }
+
+    return parts.join(".");
+  }
+
+  /**
+   * Extract a literal value from an expression
+   */
+  private extractValue(node: Node): string | boolean | number | null | undefined {
+    if (Node.isStringLiteral(node)) {
+      return node.getLiteralValue();
+    }
+
+    if (Node.isNumericLiteral(node)) {
+      return node.getLiteralValue();
+    }
+
+    if (node.getKind() === SyntaxKind.TrueKeyword) {
+      return true;
+    }
+
+    if (node.getKind() === SyntaxKind.FalseKeyword) {
+      return false;
+    }
+
+    if (node.getKind() === SyntaxKind.NullKeyword) {
+      return null;
+    }
+
+    // For complex expressions, return undefined (can't extract)
+    return undefined;
+  }
+
+  /**
+   * Infer the extension context from file path
+   *
+   * @example
+   * "/src/background/index.ts" => "background"
+   * "/src/popup/popup.tsx" => "popup"
+   */
+  private inferContextFromPath(filePath: string): string {
+    const path = filePath.toLowerCase();
+
+    if (path.includes("/background/") || path.includes("\\background\\")) {
+      return "background";
+    }
+    if (path.includes("/content/") || path.includes("\\content\\")) {
+      return "content";
+    }
+    if (path.includes("/popup/") || path.includes("\\popup\\")) {
+      return "popup";
+    }
+    if (path.includes("/devtools/") || path.includes("\\devtools\\")) {
+      return "devtools";
+    }
+    if (path.includes("/options/") || path.includes("\\options\\")) {
+      return "options";
+    }
+    if (path.includes("/offscreen/") || path.includes("\\offscreen\\")) {
+      return "offscreen";
+    }
+    if (path.includes("/sidepanel/") || path.includes("\\sidepanel\\")) {
+      return "sidepanel";
+    }
+
+    return "unknown";
+  }
+
+  /**
+   * Custom invariants specific to web extensions
+   */
+  customInvariants(): Array<[name: string, tlaExpression: string]> {
+    return [
+      [
+        "BackgroundAlwaysConnected",
+        'ports["background"] = "connected"  \\* Background context should always be available',
+      ],
+      [
+        "ContentScriptTabBound",
+        "\\A msg \\in Range(messages) : " +
+          '(msg.source = "content" \\/ "content" \\in msg.targets) => msg.tabId >= 0',
+      ],
+    ];
+  }
+}