@fairfox/polly 0.1.1 → 0.1.3

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

@@ -0,0 +1,298 @@
+// Context analysis - analyze individual execution contexts
+
+import { Project, Node, SyntaxKind } from "ts-morph";
+import type { ContextInfo, ComponentInfo } from "../types/architecture";
+import type { MessageHandler } from "../types/core";
+
+export class ContextAnalyzer {
+  private project: Project;
+
+  constructor(tsConfigPath: string) {
+    this.project = new Project({
+      tsConfigFilePath: tsConfigPath,
+    });
+  }
+
+  /**
+   * Analyze a specific context given its entry point
+   */
+  analyzeContext(contextType: string, entryPoint: string, handlers: MessageHandler[]): ContextInfo {
+    const sourceFile = this.project.getSourceFile(entryPoint);
+
+    if (!sourceFile) {
+      throw new Error(`Could not find source file: ${entryPoint}`);
+    }
+
+    // Extract Chrome API usage
+    const chromeAPIs = this.extractChromeAPIs(sourceFile);
+
+    // Extract dependencies
+    const dependencies = this.extractDependencies(sourceFile);
+
+    // Extract JSDoc description
+    const description = this.extractDescription(sourceFile);
+
+    // Extract components (for UI contexts)
+    const components = this.isUIContext(contextType)
+      ? this.extractComponents(sourceFile)
+      : undefined;
+
+    // Filter handlers for this context
+    const contextHandlers = handlers.filter((h) => h.node === contextType);
+
+    return {
+      type: contextType,
+      entryPoint,
+      handlers: contextHandlers,
+      chromeAPIs,
+      externalAPIs: [], // Will be filled by integration analyzer
+      components,
+      dependencies,
+      description,
+    };
+  }
+
+  /**
+   * Extract Chrome API usage from source file
+   */
+  private extractChromeAPIs(sourceFile: any): string[] {
+    const apis = new Set<string>();
+
+    sourceFile.forEachDescendant((node: any) => {
+      if (Node.isPropertyAccessExpression(node)) {
+        const text = node.getText();
+
+        // Match chrome.* API calls
+        if (text.startsWith("chrome.")) {
+          // Extract API namespace (e.g., "chrome.tabs", "chrome.storage.local")
+          const match = text.match(/^chrome\.([^.(]+(?:\.[^.(]+)?)/);
+          if (match) {
+            apis.add(match[1]);
+          }
+        }
+
+        // Also match browser.* for Firefox compatibility
+        if (text.startsWith("browser.")) {
+          const match = text.match(/^browser\.([^.(]+(?:\.[^.(]+)?)/);
+          if (match) {
+            apis.add(match[1]);
+          }
+        }
+
+        // Match bus.adapters.* pattern (framework abstraction over Chrome APIs)
+        // e.g., bus.adapters.storage.get() -> storage
+        //       bus.adapters.tabs.query() -> tabs
+        if (text.includes("bus.adapters.")) {
+          const match = text.match(/bus\.adapters\.([^.(]+)/);
+          if (match) {
+            apis.add(match[1]);
+          }
+        }
+      }
+    });
+
+    return Array.from(apis).sort();
+  }
+
+  /**
+   * Extract import dependencies
+   */
+  private extractDependencies(sourceFile: any): string[] {
+    const deps: string[] = [];
+
+    for (const importDecl of sourceFile.getImportDeclarations()) {
+      const moduleSpecifier = importDecl.getModuleSpecifierValue();
+      deps.push(moduleSpecifier);
+    }
+
+    return deps;
+  }
+
+  /**
+   * Extract JSDoc description from file
+   */
+  private extractDescription(sourceFile: any): string | undefined {
+    // Look for file-level JSDoc comment
+    const firstStatement = sourceFile.getStatements()[0];
+    if (!firstStatement) return undefined;
+
+    const leadingComments = firstStatement.getLeadingCommentRanges();
+    if (leadingComments.length === 0) return undefined;
+
+    const comment = leadingComments[0].getText();
+
+    // Extract description from JSDoc
+    const descMatch = comment.match(/@description\s+(.+?)(?:\n|$)/s);
+    if (descMatch) {
+      return descMatch[1].trim();
+    }
+
+    // Or just take the first line of the comment
+    const lines = comment
+      .split("\n")
+      .map((l: string) => l.replace(/^[\s*]+/, "").trim())
+      .filter((l: string) => l && !l.startsWith("@"));
+
+    return lines[0] || undefined;
+  }
+
+  /**
+   * Extract React/Preact components from source file
+   */
+  private extractComponents(sourceFile: any): ComponentInfo[] {
+    const components: ComponentInfo[] = [];
+
+    sourceFile.forEachDescendant((node: any) => {
+      // Function components
+      if (Node.isFunctionDeclaration(node)) {
+        const name = node.getName();
+        if (name && this.looksLikeComponent(name, node)) {
+          components.push({
+            name,
+            type: "function",
+            filePath: sourceFile.getFilePath(),
+            line: node.getStartLineNumber(),
+            props: this.extractProps(node),
+            description: this.extractJSDocDescription(node),
+          });
+        }
+      }
+
+      // Arrow function components (const Foo = () => ...)
+      if (Node.isVariableDeclaration(node)) {
+        const name = node.getName();
+        const initializer = node.getInitializer();
+
+        if (
+          name &&
+          initializer &&
+          (Node.isArrowFunction(initializer) || Node.isFunctionExpression(initializer))
+        ) {
+          if (this.looksLikeComponent(name, initializer)) {
+            components.push({
+              name,
+              type: "function",
+              filePath: sourceFile.getFilePath(),
+              line: node.getStartLineNumber(),
+              props: this.extractProps(initializer),
+              description: this.extractJSDocDescription(node),
+            });
+          }
+        }
+      }
+
+      // Class components
+      if (Node.isClassDeclaration(node)) {
+        const name = node.getName();
+        if (name && this.looksLikeClassComponent(node)) {
+          components.push({
+            name,
+            type: "class",
+            filePath: sourceFile.getFilePath(),
+            line: node.getStartLineNumber(),
+            props: this.extractPropsFromClass(node),
+            description: this.extractJSDocDescription(node),
+          });
+        }
+      }
+    });
+
+    return components;
+  }
+
+  /**
+   * Check if a function looks like a React/Preact component
+   */
+  private looksLikeComponent(name: string, node: any): boolean {
+    // Component names should start with uppercase
+    if (!/^[A-Z]/.test(name)) return false;
+
+    // Check if it returns JSX
+    const body = node.getBody();
+    if (!body) return false;
+
+    let hasJSX = false;
+
+    if (Node.isBlock(body)) {
+      body.forEachDescendant((child: any) => {
+        if (Node.isJsxElement(child) || Node.isJsxSelfClosingElement(child)) {
+          hasJSX = true;
+        }
+      });
+    } else {
+      // Arrow function with implicit return
+      if (Node.isJsxElement(body) || Node.isJsxSelfClosingElement(body)) {
+        hasJSX = true;
+      }
+    }
+
+    return hasJSX;
+  }
+
+  /**
+   * Check if a class looks like a React component
+   */
+  private looksLikeClassComponent(node: any): boolean {
+    const extendedTypes = node.getExtends();
+    if (!extendedTypes) return false;
+
+    const extendsText = extendedTypes.getText();
+    return /Component|PureComponent/.test(extendsText);
+  }
+
+  /**
+   * Extract props from function component
+   */
+  private extractProps(node: any): string[] {
+    const params = node.getParameters();
+    if (params.length === 0) return [];
+
+    const propsParam = params[0];
+    const type = propsParam.getType();
+
+    const props: string[] = [];
+    for (const prop of type.getProperties()) {
+      props.push(prop.getName());
+    }
+
+    return props;
+  }
+
+  /**
+   * Extract props from class component
+   */
+  private extractPropsFromClass(node: any): string[] {
+    const extendedTypes = node.getExtends();
+    if (!extendedTypes) return [];
+
+    const typeArgs = extendedTypes.getType().getTypeArguments();
+    if (typeArgs.length === 0) return [];
+
+    const propsType = typeArgs[0];
+    const props: string[] = [];
+
+    for (const prop of propsType.getProperties()) {
+      props.push(prop.getName());
+    }
+
+    return props;
+  }
+
+  /**
+   * Extract JSDoc description from node
+   */
+  private extractJSDocDescription(node: any): string | undefined {
+    const jsDocs = node.getJsDocs();
+    if (jsDocs.length === 0) return undefined;
+
+    const description = jsDocs[0].getDescription().trim();
+    return description || undefined;
+  }
+
+  /**
+   * Check if context is a UI context
+   */
+  private isUIContext(contextType: string): boolean {
+    return ["popup", "options", "devtools"].includes(contextType);
+  }
+}

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

@@ -0,0 +1,309 @@
+// Message flow analysis - trace messages between contexts
+
+import { Project, Node } from "ts-morph";
+import type { MessageFlow, MessageStep } from "../types/architecture";
+import type { MessageHandler } from "../types/core";
+
+export class FlowAnalyzer {
+  private project: Project;
+  private handlers: MessageHandler[];
+
+  constructor(tsConfigPath: string, handlers: MessageHandler[]) {
+    this.project = new Project({
+      tsConfigFilePath: tsConfigPath,
+    });
+    this.handlers = handlers;
+  }
+
+  /**
+   * Analyze message flows between contexts
+   */
+  analyzeFlows(): MessageFlow[] {
+    const flows: MessageFlow[] = [];
+
+    // Group handlers by message type
+    const handlersByType = new Map<string, MessageHandler[]>();
+    for (const handler of this.handlers) {
+      if (!handlersByType.has(handler.messageType)) {
+        handlersByType.set(handler.messageType, []);
+      }
+      handlersByType.get(handler.messageType)!.push(handler);
+    }
+
+    // For each message type, trace the flow
+    for (const [messageType, handlers] of handlersByType) {
+      // Find senders
+      const senders = this.findMessageSenders(messageType);
+
+      // For each sender, create a flow
+      for (const sender of senders) {
+        const recipients = handlers.map((h) => h.node);
+
+        // Build sequence of steps
+        const sequence = this.buildSequence(messageType, sender, handlers);
+
+        // Extract flow metadata
+        const flowMetadata = this.extractFlowMetadata(sender.file, sender.line);
+
+        flows.push({
+          messageType,
+          from: sender.context,
+          to: recipients,
+          trigger: flowMetadata.trigger,
+          flowName: flowMetadata.flowName,
+          description: flowMetadata.description,
+          sequence,
+        });
+      }
+    }
+
+    return flows;
+  }
+
+  /**
+   * Find all places where a message is sent
+   */
+  private findMessageSenders(messageType: string): Array<{
+    context: string;
+    file: string;
+    line: number;
+  }> {
+    const senders: Array<{ context: string; file: string; line: number }> = [];
+
+    for (const sourceFile of this.project.getSourceFiles()) {
+      const filePath = sourceFile.getFilePath();
+      const context = this.inferContext(filePath);
+
+      sourceFile.forEachDescendant((node) => {
+        if (Node.isCallExpression(node)) {
+          const expression = node.getExpression();
+
+          // Check for .send() or .emit() calls
+          if (Node.isPropertyAccessExpression(expression)) {
+            const methodName = expression.getName();
+
+            if (methodName === "send" || methodName === "emit") {
+              const args = node.getArguments();
+              if (args.length > 0) {
+                const firstArg = args[0];
+
+                let msgType: string | undefined;
+
+                // Check if first argument is a string literal: send("MESSAGE")
+                if (Node.isStringLiteral(firstArg)) {
+                  msgType = firstArg.getLiteralValue();
+                }
+                // Check if first argument is an object literal: send({ type: "MESSAGE" })
+                else if (Node.isObjectLiteralExpression(firstArg)) {
+                  const typeProperty = firstArg.getProperty("type");
+                  if (typeProperty && Node.isPropertyAssignment(typeProperty)) {
+                    const initializer = typeProperty.getInitializer();
+                    if (initializer && Node.isStringLiteral(initializer)) {
+                      msgType = initializer.getLiteralValue();
+                    }
+                  }
+                }
+
+                if (msgType === messageType) {
+                  senders.push({
+                    context,
+                    file: filePath,
+                    line: node.getStartLineNumber(),
+                  });
+                }
+              }
+            }
+          }
+        }
+      });
+    }
+
+    return senders;
+  }
+
+  /**
+   * Build sequence of steps for a message flow
+   */
+  private buildSequence(
+    messageType: string,
+    sender: { context: string; file: string; line: number },
+    handlers: MessageHandler[]
+  ): MessageStep[] {
+    const steps: MessageStep[] = [];
+    let stepNumber = 1;
+
+    // Step 1: Send message
+    steps.push({
+      step: stepNumber++,
+      action: `${sender.context}.send(${messageType})`,
+      context: sender.context,
+      location: {
+        file: sender.file,
+        line: sender.line,
+      },
+    });
+
+    // Step 2+: Handle in each recipient context
+    for (const handler of handlers) {
+      steps.push({
+        step: stepNumber++,
+        action: `${handler.node}.handle(${messageType})`,
+        context: handler.node,
+        location: handler.location,
+      });
+
+      // Add substeps for any messages sent by this handler
+      const subsends = this.findMessagesInHandler(handler);
+      for (const subsend of subsends) {
+        steps.push({
+          step: stepNumber++,
+          action: `${handler.node}.send(${subsend.messageType})`,
+          context: handler.node,
+          location: subsend.location,
+        });
+      }
+    }
+
+    return steps;
+  }
+
+  /**
+   * Find messages sent within a handler
+   */
+  private findMessagesInHandler(handler: MessageHandler): Array<{
+    messageType: string;
+    location: { file: string; line: number };
+  }> {
+    const sends: Array<{ messageType: string; location: { file: string; line: number } }> = [];
+
+    const sourceFile = this.project.getSourceFile(handler.location.file);
+    if (!sourceFile) return sends;
+
+    // Find the handler function at the given line
+    const targetLine = handler.location.line;
+
+    sourceFile.forEachDescendant((node) => {
+      if (Node.isCallExpression(node)) {
+        const line = node.getStartLineNumber();
+
+        // Rough heuristic: if it's near the handler line, it's probably in the handler
+        if (Math.abs(line - targetLine) < 20) {
+          const expression = node.getExpression();
+
+          if (Node.isPropertyAccessExpression(expression)) {
+            const methodName = expression.getName();
+
+            if (methodName === "send" || methodName === "emit") {
+              const args = node.getArguments();
+              if (args.length > 0) {
+                const firstArg = args[0];
+                let messageType: string | undefined;
+
+                // Check if first argument is a string literal: send("MESSAGE")
+                if (Node.isStringLiteral(firstArg)) {
+                  messageType = firstArg.getLiteralValue();
+                }
+                // Check if first argument is an object literal: send({ type: "MESSAGE" })
+                else if (Node.isObjectLiteralExpression(firstArg)) {
+                  const typeProperty = firstArg.getProperty("type");
+                  if (typeProperty && Node.isPropertyAssignment(typeProperty)) {
+                    const initializer = typeProperty.getInitializer();
+                    if (initializer && Node.isStringLiteral(initializer)) {
+                      messageType = initializer.getLiteralValue();
+                    }
+                  }
+                }
+
+                if (messageType) {
+                  sends.push({
+                    messageType,
+                    location: {
+                      file: handler.location.file,
+                      line,
+                    },
+                  });
+                }
+              }
+            }
+          }
+        }
+      }
+    });
+
+    return sends;
+  }
+
+  /**
+   * Extract flow metadata from JSDoc annotations
+   */
+  private extractFlowMetadata(
+    filePath: string,
+    lineNumber: number
+  ): {
+    trigger?: string;
+    flowName?: string;
+    description?: string;
+  } {
+    const sourceFile = this.project.getSourceFile(filePath);
+    if (!sourceFile) return {};
+
+    // Find the node at this line
+    let targetNode: any = null;
+
+    sourceFile.forEachDescendant((node) => {
+      if (node.getStartLineNumber() === lineNumber) {
+        targetNode = node;
+      }
+    });
+
+    if (!targetNode) return {};
+
+    // Look for JSDoc comments
+    const jsDocs = targetNode.getJsDocs?.() || [];
+    if (jsDocs.length === 0) return {};
+
+    const comment = jsDocs[0].getText();
+
+    // Extract @flow annotation
+    const flowMatch = comment.match(/@flow\s+([^\s]+)/);
+    const flowName = flowMatch ? flowMatch[1] : undefined;
+
+    // Extract @trigger annotation
+    const triggerMatch = comment.match(/@trigger\s+(.+?)(?:\n|$)/);
+    const trigger = triggerMatch ? triggerMatch[1].trim() : undefined;
+
+    // Extract @description
+    const descMatch = comment.match(/@description\s+(.+?)(?:\n|$)/s);
+    const description = descMatch ? descMatch[1].trim() : undefined;
+
+    return { trigger, flowName, description };
+  }
+
+  /**
+   * Infer context 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";
+  }
+}