@fairfox/polly 0.1.0 → 0.1.2

package/vendor/analysis/src/extract/handlers.ts

@@ -0,0 +1,321 @@
+// Handler extraction from TypeScript code
+// Extracts message handlers and their state mutations
+
+import { Project, type SourceFile, SyntaxKind, Node } from "ts-morph";
+import type { MessageHandler, StateAssignment, VerificationCondition } from "../types";
+
+export interface HandlerAnalysis {
+  handlers: MessageHandler[];
+  messageTypes: Set<string>;
+}
+
+export class HandlerExtractor {
+  private project: Project;
+
+  constructor(tsConfigPath: string) {
+    this.project = new Project({
+      tsConfigFilePath: tsConfigPath,
+    });
+  }
+
+  /**
+   * Extract all message handlers from the codebase
+   */
+  extractHandlers(): HandlerAnalysis {
+    const handlers: MessageHandler[] = [];
+    const messageTypes = new Set<string>();
+
+    // Find all source files
+    const sourceFiles = this.project.getSourceFiles();
+
+    for (const sourceFile of sourceFiles) {
+      const fileHandlers = this.extractFromFile(sourceFile);
+      handlers.push(...fileHandlers);
+
+      for (const handler of fileHandlers) {
+        messageTypes.add(handler.messageType);
+      }
+    }
+
+    return {
+      handlers,
+      messageTypes,
+    };
+  }
+
+  /**
+   * Extract handlers from a single source file
+   */
+  private extractFromFile(sourceFile: SourceFile): MessageHandler[] {
+    const handlers: MessageHandler[] = [];
+    const filePath = sourceFile.getFilePath();
+
+    // Determine context from file path
+    const context = this.inferContext(filePath);
+
+    // Find all .on() call expressions
+    sourceFile.forEachDescendant((node) => {
+      if (Node.isCallExpression(node)) {
+        const expression = node.getExpression();
+
+        // Check if this is a .on() call
+        if (Node.isPropertyAccessExpression(expression)) {
+          const methodName = expression.getName();
+
+          if (methodName === "on") {
+            const handler = this.extractHandler(node, context, filePath);
+            if (handler) {
+              handlers.push(handler);
+            }
+          }
+        }
+      }
+    });
+
+    return handlers;
+  }
+
+  /**
+   * Extract handler details from a .on() call expression
+   */
+  private extractHandler(callExpr: any, context: string, filePath: string): MessageHandler | 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)) {
+      // Handle template literals if needed
+      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.extractAssignments(handlerArg, assignments);
+      this.extractVerificationConditions(handlerArg, preconditions, postconditions);
+    }
+
+    const line = callExpr.getStartLineNumber();
+
+    return {
+      messageType,
+      node: context, // Renamed from 'context' to 'node' for generalization
+      assignments,
+      preconditions,
+      postconditions,
+      location: {
+        file: filePath,
+        line,
+      },
+    };
+  }
+
+  /**
+   * Extract state assignments from a handler function
+   */
+  private extractAssignments(funcNode: any, assignments: StateAssignment[]): void {
+    funcNode.forEachDescendant((node: any) => {
+      // Look for assignment expressions: state.field = value
+      if (Node.isBinaryExpression(node)) {
+        const operator = node.getOperatorToken().getText();
+
+        if (operator === "=") {
+          const left = node.getLeft();
+          const right = node.getRight();
+
+          // Check if left side is a state property access
+          if (Node.isPropertyAccessExpression(left)) {
+            const fieldPath = this.getPropertyPath(left);
+
+            // Check if this is a state access
+            if (fieldPath.startsWith("state.")) {
+              const field = fieldPath.substring(6); // Remove "state." prefix
+              const value = this.extractValue(right);
+
+              if (value !== undefined) {
+                assignments.push({
+                  field,
+                  value,
+                });
+              }
+            }
+          }
+        }
+      }
+    });
+  }
+
+  /**
+   * Extract verification conditions (requires/ensures) from a handler function
+   */
+  private extractVerificationConditions(
+    funcNode: any,
+    preconditions: VerificationCondition[],
+    postconditions: VerificationCondition[]
+  ): void {
+    const body = funcNode.getBody();
+
+    // Get all statements in the function body
+    const statements = Node.isBlock(body) ? body.getStatements() : [body];
+
+    statements.forEach((statement: any, index: number) => {
+      // Look for expression statements that are function calls
+      if (Node.isExpressionStatement(statement)) {
+        const expr = statement.getExpression();
+
+        if (Node.isCallExpression(expr)) {
+          const callee = expr.getExpression();
+
+          if (Node.isIdentifier(callee)) {
+            const functionName = callee.getText();
+
+            if (functionName === "requires") {
+              // Extract precondition
+              const condition = this.extractCondition(expr);
+              if (condition) {
+                preconditions.push(condition);
+              }
+            } else if (functionName === "ensures") {
+              // Extract postcondition
+              const condition = this.extractCondition(expr);
+              if (condition) {
+                postconditions.push(condition);
+              }
+            }
+          }
+        }
+      }
+    });
+  }
+
+  /**
+   * Extract condition from a requires() or ensures() call
+   */
+  private extractCondition(callExpr: any): VerificationCondition | 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.getStartLinePos();
+
+    return {
+      expression,
+      message,
+      location: {
+        line,
+        column,
+      },
+    };
+  }
+
+  /**
+   * Get the full property access path (e.g., "state.user.loggedIn")
+   */
+  private getPropertyPath(node: any): string {
+    const parts: string[] = [];
+
+    let current = 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: any): 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 context (background, content, popup, etc.) from file path
+   */
+  private inferContext(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";
+    }
+
+    return "unknown";
+  }
+}
+
+export function extractHandlers(tsConfigPath: string): HandlerAnalysis {
+  const extractor = new HandlerExtractor(tsConfigPath);
+  return extractor.extractHandlers();
+}

package/vendor/analysis/src/extract/index.ts

@@ -0,0 +1,9 @@
+// Export all extraction utilities
+export * from "./types";
+export * from "./handlers";
+export * from "./manifest";
+export * from "./contexts";
+export * from "./flows";
+export * from "./integrations";
+export * from "./adr";
+export * from "./architecture";

package/vendor/analysis/src/extract/integrations.ts

@@ -0,0 +1,329 @@
+// External integration detection - find external APIs, services, etc.
+
+import { Project, Node } from "ts-morph";
+import type { ExternalIntegration, ExternalAPICall } from "../types/architecture";
+
+export class IntegrationAnalyzer {
+  private project: Project;
+
+  constructor(tsConfigPath: string) {
+    this.project = new Project({
+      tsConfigFilePath: tsConfigPath,
+    });
+  }
+
+  /**
+   * Analyze external integrations in the codebase
+   */
+  analyzeIntegrations(): ExternalIntegration[] {
+    const integrations = new Map<string, ExternalIntegration>();
+
+    // Find all fetch() calls
+    const fetchCalls = this.findFetchCalls();
+    for (const call of fetchCalls) {
+      this.addOrMergeIntegration(integrations, this.createAPIIntegration(call));
+    }
+
+    // Find WebSocket connections
+    const websockets = this.findWebSockets();
+    for (const ws of websockets) {
+      this.addOrMergeIntegration(integrations, this.createWebSocketIntegration(ws));
+    }
+
+    // Find external script imports
+    const externalScripts = this.findExternalScripts();
+    for (const script of externalScripts) {
+      this.addOrMergeIntegration(integrations, script);
+    }
+
+    return Array.from(integrations.values());
+  }
+
+  /**
+   * Find all fetch() API calls
+   */
+  private findFetchCalls(): Array<{
+    url: string;
+    method: string;
+    file: string;
+    line: number;
+    description?: string;
+  }> {
+    const calls: Array<{
+      url: string;
+      method: string;
+      file: string;
+      line: number;
+      description?: string;
+    }> = [];
+
+    for (const sourceFile of this.project.getSourceFiles()) {
+      sourceFile.forEachDescendant((node) => {
+        if (Node.isCallExpression(node)) {
+          const expression = node.getExpression();
+
+          // Check for fetch() calls
+          if (Node.isIdentifier(expression) && expression.getText() === "fetch") {
+            const args = node.getArguments();
+            if (args.length > 0) {
+              // Extract URL
+              const urlArg = args[0];
+              let url: string | null = null;
+
+              if (Node.isStringLiteral(urlArg)) {
+                url = urlArg.getLiteralValue();
+              } else if (Node.isTemplateExpression(urlArg)) {
+                // Try to extract base URL from template
+                url = this.extractBaseURL(urlArg.getText());
+              }
+
+              if (url) {
+                // Extract method
+                let method = "GET"; // Default
+                if (args.length > 1 && Node.isObjectLiteralExpression(args[1])) {
+                  const options = args[1];
+                  const methodProp = options.getProperty("method");
+                  if (methodProp && Node.isPropertyAssignment(methodProp)) {
+                    const initializer = methodProp.getInitializer();
+                    if (initializer && Node.isStringLiteral(initializer)) {
+                      method = initializer.getLiteralValue().toUpperCase();
+                    }
+                  }
+                }
+
+                // Extract description from JSDoc
+                const description = this.extractJSDocDescription(node);
+
+                calls.push({
+                  url,
+                  method,
+                  file: sourceFile.getFilePath(),
+                  line: node.getStartLineNumber(),
+                  description,
+                });
+              }
+            }
+          }
+        }
+      });
+    }
+
+    return calls;
+  }
+
+  /**
+   * Find WebSocket connections
+   */
+  private findWebSockets(): Array<{
+    url: string;
+    file: string;
+    line: number;
+    description?: string;
+  }> {
+    const websockets: Array<{
+      url: string;
+      file: string;
+      line: number;
+      description?: string;
+    }> = [];
+
+    for (const sourceFile of this.project.getSourceFiles()) {
+      sourceFile.forEachDescendant((node) => {
+        if (Node.isNewExpression(node)) {
+          const expression = node.getExpression();
+
+          // Check for new WebSocket()
+          if (Node.isIdentifier(expression) && expression.getText() === "WebSocket") {
+            const args = node.getArguments();
+            if (args.length > 0 && Node.isStringLiteral(args[0])) {
+              const url = args[0].getLiteralValue();
+              const description = this.extractJSDocDescription(node);
+
+              websockets.push({
+                url,
+                file: sourceFile.getFilePath(),
+                line: node.getStartLineNumber(),
+                description,
+              });
+            }
+          }
+        }
+      });
+    }
+
+    return websockets;
+  }
+
+  /**
+   * Find external script dependencies (from imports)
+   */
+  private findExternalScripts(): ExternalIntegration[] {
+    const scripts: ExternalIntegration[] = [];
+    const seen = new Set<string>();
+
+    for (const sourceFile of this.project.getSourceFiles()) {
+      for (const importDecl of sourceFile.getImportDeclarations()) {
+        const moduleSpecifier = importDecl.getModuleSpecifierValue();
+
+        // Only consider external packages (not relative imports)
+        if (!moduleSpecifier.startsWith(".") && !moduleSpecifier.startsWith("/")) {
+          // Extract package name (handle scoped packages)
+          const packageName = moduleSpecifier.startsWith("@")
+            ? moduleSpecifier.split("/").slice(0, 2).join("/")
+            : moduleSpecifier.split("/")[0];
+
+          if (!seen.has(packageName)) {
+            seen.add(packageName);
+
+            scripts.push({
+              type: "external-script",
+              name: packageName,
+              technology: "npm package",
+              usedIn: [sourceFile.getFilePath()],
+              description: `External dependency: ${packageName}`,
+            });
+          }
+        }
+      }
+    }
+
+    return scripts;
+  }
+
+  /**
+   * Create API integration from fetch call
+   */
+  private createAPIIntegration(call: {
+    url: string;
+    method: string;
+    file: string;
+    line: number;
+    description?: string;
+  }): ExternalIntegration {
+    // Extract base URL
+    const baseURL = this.extractBaseURL(call.url);
+
+    // Infer name from URL
+    const name = this.inferAPIName(baseURL);
+
+    return {
+      type: "api",
+      name,
+      technology: "REST API",
+      url: baseURL,
+      usedIn: [call.file],
+      description: call.description || `External API: ${name}`,
+      calls: [
+        {
+          method: call.method,
+          endpoint: call.url,
+          location: {
+            file: call.file,
+            line: call.line,
+          },
+          description: call.description,
+        },
+      ],
+    };
+  }
+
+  /**
+   * Create WebSocket integration
+   */
+  private createWebSocketIntegration(ws: {
+    url: string;
+    file: string;
+    line: number;
+    description?: string;
+  }): ExternalIntegration {
+    const name = this.inferAPIName(ws.url);
+
+    return {
+      type: "websocket",
+      name,
+      technology: "WebSocket",
+      url: ws.url,
+      usedIn: [ws.file],
+      description: ws.description || `WebSocket connection: ${name}`,
+    };
+  }
+
+  /**
+   * Extract base URL from full URL or template
+   */
+  private extractBaseURL(url: string): string {
+    // Remove template parts
+    url = url.replace(/\$\{[^}]+\}/g, "");
+    url = url.replace(/`/g, "");
+
+    try {
+      const parsed = new URL(url);
+      return `${parsed.protocol}//${parsed.host}`;
+    } catch {
+      // If parsing fails, try to extract domain
+      const match = url.match(/https?:\/\/([^/]+)/);
+      return match ? match[0] : url;
+    }
+  }
+
+  /**
+   * Infer API name from URL
+   */
+  private inferAPIName(url: string): string {
+    try {
+      const parsed = new URL(url);
+      const hostname = parsed.hostname;
+
+      // Remove www. prefix
+      const cleanHost = hostname.replace(/^www\./, "");
+
+      // Take first part of domain
+      const parts = cleanHost.split(".");
+      if (parts.length > 0) {
+        // Capitalize first letter
+        return parts[0].charAt(0).toUpperCase() + parts[0].slice(1) + " API";
+      }
+    } catch {
+      // Fallback
+    }
+
+    return "External API";
+  }
+
+  /**
+   * Add or merge integration into map
+   */
+  private addOrMergeIntegration(
+    map: Map<string, ExternalIntegration>,
+    integration: ExternalIntegration
+  ): void {
+    const key = `${integration.type}:${integration.name}`;
+
+    if (map.has(key)) {
+      const existing = map.get(key)!;
+
+      // Merge usedIn
+      existing.usedIn = [...new Set([...existing.usedIn, ...integration.usedIn])];
+
+      // Merge calls
+      if (integration.calls && existing.calls) {
+        existing.calls.push(...integration.calls);
+      } else if (integration.calls) {
+        existing.calls = integration.calls;
+      }
+    } else {
+      map.set(key, integration);
+    }
+  }
+
+  /**
+   * Extract JSDoc description from node
+   */
+  private extractJSDocDescription(node: any): string | undefined {
+    const jsDocs = node.getJsDocs?.() || [];
+    if (jsDocs.length === 0) return undefined;
+
+    const comment = jsDocs[0].getDescription().trim();
+    return comment || undefined;
+  }
+}