@fairfox/polly 0.1.0 → 0.1.2

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

@@ -0,0 +1,298 @@
+// Manifest.json parser for Chrome extensions
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ManifestInfo, ContextInfo } from "../types/architecture";
+
+/**
+ * Parse manifest.json and extract context information
+ */
+export class ManifestParser {
+  private manifestPath: string;
+  private manifestData: any;
+  private baseDir: string;
+
+  constructor(projectRoot: string) {
+    this.baseDir = projectRoot;
+    this.manifestPath = path.join(projectRoot, "manifest.json");
+
+    if (!fs.existsSync(this.manifestPath)) {
+      throw new Error(`manifest.json not found at ${this.manifestPath}`);
+    }
+
+    try {
+      const content = fs.readFileSync(this.manifestPath, "utf-8");
+      this.manifestData = JSON.parse(content);
+    } catch (error) {
+      throw new Error(`Failed to parse manifest.json: ${error}`);
+    }
+  }
+
+  /**
+   * Parse manifest and extract all information
+   */
+  parse(): ManifestInfo {
+    const manifest = this.manifestData;
+
+    return {
+      name: manifest.name || "Unknown Extension",
+      version: manifest.version || "0.0.0",
+      description: manifest.description,
+      manifestVersion: manifest.manifest_version || 2,
+      background: this.parseBackground(),
+      contentScripts: this.parseContentScripts(),
+      popup: this.parsePopup(),
+      options: this.parseOptions(),
+      devtools: this.parseDevtools(),
+      permissions: manifest.permissions || [],
+      hostPermissions: manifest.host_permissions || [],
+    };
+  }
+
+  /**
+   * Get context entry points from manifest
+   */
+  getContextEntryPoints(): Record<string, string> {
+    const entryPoints: Record<string, string> = {};
+
+    // Background
+    const background = this.parseBackground();
+    if (background) {
+      // Take first file as entry point
+      const entryFile = background.files[0];
+      if (entryFile) {
+        entryPoints.background = this.findSourceFile(entryFile);
+      }
+    }
+
+    // Content scripts
+    const contentScripts = this.parseContentScripts();
+    if (contentScripts && contentScripts.length > 0) {
+      const firstScript = contentScripts[0].js[0];
+      if (firstScript) {
+        entryPoints.content = this.findSourceFile(firstScript);
+      }
+    }
+
+    // Popup
+    const popup = this.parsePopup();
+    if (popup) {
+      // For HTML, we need to find the associated JS/TS file
+      const htmlPath = path.join(this.baseDir, popup.html);
+      const jsPath = this.findAssociatedJS(htmlPath);
+      if (jsPath) {
+        entryPoints.popup = jsPath;
+      }
+    }
+
+    // Options
+    const options = this.parseOptions();
+    if (options) {
+      const htmlPath = path.join(this.baseDir, options.page);
+      const jsPath = this.findAssociatedJS(htmlPath);
+      if (jsPath) {
+        entryPoints.options = jsPath;
+      }
+    }
+
+    // DevTools
+    const devtools = this.parseDevtools();
+    if (devtools) {
+      const htmlPath = path.join(this.baseDir, devtools.page);
+      const jsPath = this.findAssociatedJS(htmlPath);
+      if (jsPath) {
+        entryPoints.devtools = jsPath;
+      }
+    }
+
+    return entryPoints;
+  }
+
+  /**
+   * Parse background configuration
+   */
+  private parseBackground(): ManifestInfo["background"] {
+    const bg = this.manifestData.background;
+    if (!bg) return undefined;
+
+    // Manifest V3 - service worker
+    if (bg.service_worker) {
+      return {
+        type: "service_worker",
+        files: [bg.service_worker],
+      };
+    }
+
+    // Manifest V2 - scripts
+    if (bg.scripts) {
+      return {
+        type: "script",
+        files: bg.scripts,
+      };
+    }
+
+    // Manifest V2 - page
+    if (bg.page) {
+      return {
+        type: "script",
+        files: [bg.page],
+      };
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Parse content scripts configuration
+   */
+  private parseContentScripts(): ManifestInfo["contentScripts"] {
+    const cs = this.manifestData.content_scripts;
+    if (!cs || !Array.isArray(cs)) return undefined;
+
+    return cs.map((script) => ({
+      matches: script.matches || [],
+      js: script.js || [],
+      css: script.css,
+    }));
+  }
+
+  /**
+   * Parse popup configuration
+   */
+  private parsePopup(): ManifestInfo["popup"] {
+    const action = this.manifestData.action || this.manifestData.browser_action;
+    if (!action) return undefined;
+
+    if (action.default_popup) {
+      return {
+        html: action.default_popup,
+        default: true,
+      };
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Parse options configuration
+   */
+  private parseOptions(): ManifestInfo["options"] {
+    const options = this.manifestData.options_ui || this.manifestData.options_page;
+    if (!options) return undefined;
+
+    if (typeof options === "string") {
+      return {
+        page: options,
+        openInTab: false,
+      };
+    }
+
+    return {
+      page: options.page,
+      openInTab: options.open_in_tab,
+    };
+  }
+
+  /**
+   * Parse devtools configuration
+   */
+  private parseDevtools(): ManifestInfo["devtools"] {
+    const devtools = this.manifestData.devtools_page;
+    if (!devtools) return undefined;
+
+    return {
+      page: devtools,
+    };
+  }
+
+  /**
+   * Find source file from manifest reference
+   * Tries multiple locations: exact path, src/ directory, .ts extension
+   */
+  private findSourceFile(manifestPath: string): string {
+    const candidates = [
+      // Exact path from manifest
+      path.join(this.baseDir, manifestPath),
+      // Same path with .ts extension
+      path.join(this.baseDir, manifestPath.replace(/\.js$/, ".ts")),
+      // In src/ directory
+      path.join(this.baseDir, "src", manifestPath),
+      path.join(this.baseDir, "src", manifestPath.replace(/\.js$/, ".ts")),
+      // In src/ with .tsx extension
+      path.join(this.baseDir, "src", manifestPath.replace(/\.js$/, ".tsx")),
+    ];
+
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) {
+        return candidate;
+      }
+    }
+
+    // Fallback to manifest path (will error later if not found)
+    return path.join(this.baseDir, manifestPath);
+  }
+
+  /**
+   * Find associated JavaScript/TypeScript file for an HTML file
+   */
+  private findAssociatedJS(htmlPath: string): string | null {
+    if (!fs.existsSync(htmlPath)) {
+      return null;
+    }
+
+    // Read HTML and look for script tags
+    const html = fs.readFileSync(htmlPath, "utf-8");
+    const scriptMatch = html.match(/<script[^>]+src=["']([^"']+)["']/i);
+
+    if (scriptMatch && scriptMatch[1]) {
+      const scriptPath = scriptMatch[1];
+      const fullPath = path.resolve(path.dirname(htmlPath), scriptPath);
+
+      // Try with and without .js/.ts extension
+      if (fs.existsSync(fullPath)) return fullPath;
+      if (fs.existsSync(fullPath.replace(/\.js$/, ".ts"))) {
+        return fullPath.replace(/\.js$/, ".ts");
+      }
+      if (fs.existsSync(fullPath.replace(/\.js$/, ".tsx"))) {
+        return fullPath.replace(/\.js$/, ".tsx");
+      }
+    }
+
+    // Fallback: look for convention-based files
+    const baseName = path.basename(htmlPath, ".html");
+    const dir = path.dirname(htmlPath);
+
+    const candidates = [
+      path.join(dir, `${baseName}.ts`),
+      path.join(dir, `${baseName}.tsx`),
+      path.join(dir, `${baseName}.js`),
+      path.join(dir, "index.ts"),
+      path.join(dir, "index.tsx"),
+      path.join(dir, "index.js"),
+    ];
+
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) {
+        return candidate;
+      }
+    }
+
+    return null;
+  }
+}
+
+/**
+ * Parse manifest.json and extract information
+ */
+export function parseManifest(projectRoot: string): ManifestInfo {
+  const parser = new ManifestParser(projectRoot);
+  return parser.parse();
+}
+
+/**
+ * Get context entry points from manifest.json
+ */
+export function getContextEntryPoints(projectRoot: string): Record<string, string> {
+  const parser = new ManifestParser(projectRoot);
+  return parser.getContextEntryPoints();
+}

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

@@ -0,0 +1,389 @@
+// Type extraction from TypeScript using ts-morph
+
+import { Project, SourceFile, Type, TypeFormatFlags } from "ts-morph";
+import type { TypeInfo, TypeKind, FieldAnalysis, Confidence, CodebaseAnalysis } from "../types";
+import { HandlerExtractor } from "./handlers";
+
+export class TypeExtractor {
+  private project: Project;
+
+  constructor(tsConfigPath: string) {
+    this.project = new Project({
+      tsConfigFilePath: tsConfigPath,
+    });
+  }
+
+  /**
+   * Analyze the codebase and extract state types and message types
+   */
+  async analyzeCodebase(stateFilePath?: string): Promise<CodebaseAnalysis> {
+    // Find state type
+    const stateType = stateFilePath ? this.extractStateType(stateFilePath) : this.findStateType();
+
+    // Find message types
+    const messageTypes = this.findMessageTypes();
+
+    // Analyze fields
+    const fields = stateType ? this.analyzeFields(stateType) : [];
+
+    // Extract message handlers
+    const configFilePath = this.project.getCompilerOptions().configFilePath;
+    const tsConfigPath = typeof configFilePath === "string" ? configFilePath : "tsconfig.json";
+    const handlerExtractor = new HandlerExtractor(tsConfigPath);
+    const handlerAnalysis = handlerExtractor.extractHandlers();
+
+    return {
+      stateType,
+      messageTypes: Array.from(new Set([...messageTypes, ...handlerAnalysis.messageTypes])),
+      fields,
+      handlers: handlerAnalysis.handlers,
+    };
+  }
+
+  /**
+   * Extract state type from a specific file
+   */
+  private extractStateType(filePath: string): TypeInfo | null {
+    const sourceFile = this.project.getSourceFile(filePath);
+    if (!sourceFile) {
+      return null;
+    }
+
+    // Look for type alias named "AppState" or similar
+    const typeAlias =
+      sourceFile.getTypeAlias("AppState") ||
+      sourceFile.getTypeAlias("State") ||
+      sourceFile.getTypeAliases()[0];
+
+    if (!typeAlias) {
+      return null;
+    }
+
+    const type = typeAlias.getType();
+    return this.convertType(type, typeAlias.getName());
+  }
+
+  /**
+   * Find state type by searching common patterns
+   */
+  private findStateType(): TypeInfo | null {
+    // Search for files with "state" in the name
+    const stateFiles = this.project.getSourceFiles("**/state*.ts");
+
+    for (const file of stateFiles) {
+      const typeAlias = file.getTypeAlias("AppState") || file.getTypeAlias("State");
+
+      if (typeAlias) {
+        const type = typeAlias.getType();
+        return this.convertType(type, typeAlias.getName());
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Find message types by searching for type unions
+   */
+  private findMessageTypes(): string[] {
+    const messageTypes: string[] = [];
+
+    // Search for files with "message" in the name
+    const messageFiles = this.project.getSourceFiles("**/message*.ts");
+
+    for (const file of messageFiles) {
+      // Look for type aliases that are unions
+      for (const typeAlias of file.getTypeAliases()) {
+        const type = typeAlias.getType();
+        if (type.isUnion()) {
+          // Extract message type literals
+          for (const unionType of type.getUnionTypes()) {
+            if (unionType.isObject()) {
+              const typeProperty = unionType.getProperty("type");
+              if (typeProperty) {
+                const typeType = typeProperty.getTypeAtLocation(file);
+                if (typeType.isStringLiteral()) {
+                  messageTypes.push(typeType.getLiteralValue() as string);
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+
+    return [...new Set(messageTypes)]; // Dedupe
+  }
+
+  /**
+   * Convert ts-morph Type to our TypeInfo
+   */
+  private convertType(type: Type, name: string): TypeInfo {
+    // Check for null/undefined
+    const nullable = type.isNullable();
+
+    // Boolean
+    if (type.isBoolean() || type.isBooleanLiteral()) {
+      return { name, kind: "boolean", nullable };
+    }
+
+    // Union types
+    if (type.isUnion()) {
+      const unionTypes = type.getUnionTypes();
+
+      // Check for string literal union (enum)
+      const allStringLiterals = unionTypes.every((t) => t.isStringLiteral());
+      if (allStringLiterals) {
+        const enumValues = unionTypes.map((t) => t.getLiteralValue() as string);
+        return {
+          name,
+          kind: "enum",
+          nullable,
+          enumValues,
+        };
+      }
+
+      // Check for nullable type (T | null | undefined)
+      const nonNullTypes = unionTypes.filter((t) => !t.isNull() && !t.isUndefined());
+
+      if (nonNullTypes.length === 1) {
+        // This is a nullable type: T | null or T | undefined
+        const baseType = this.convertType(nonNullTypes[0], name);
+        return {
+          ...baseType,
+          nullable: true,
+        };
+      }
+
+      // Generic union - keep as-is
+      return {
+        name,
+        kind: "union",
+        nullable,
+        unionTypes: unionTypes.map((t, i) => this.convertType(t, `${name}_${i}`)),
+      };
+    }
+
+    // String
+    if (type.isString() || type.isStringLiteral()) {
+      return { name, kind: "string", nullable };
+    }
+
+    // Number
+    if (type.isNumber() || type.isNumberLiteral()) {
+      return { name, kind: "number", nullable };
+    }
+
+    // Array
+    if (type.isArray()) {
+      const elementType = type.getArrayElementType();
+      return {
+        name,
+        kind: "array",
+        nullable,
+        elementType: elementType
+          ? this.convertType(elementType, `${name}_element`)
+          : { name: "unknown", kind: "unknown", nullable: false },
+      };
+    }
+
+    // Map/Set detection - must come before generic object handling
+    const symbol = type.getSymbol();
+    if (symbol) {
+      const symbolName = symbol.getName();
+
+      // Map<K, V>
+      if (symbolName === "Map") {
+        const typeArgs = type.getTypeArguments();
+        return {
+          name,
+          kind: "map",
+          nullable,
+          // Extract value type from Map<K, V>
+          valueType:
+            typeArgs && typeArgs[1] ? this.convertType(typeArgs[1], `${name}_value`) : undefined,
+        };
+      }
+
+      // Set<T>
+      if (symbolName === "Set") {
+        const typeArgs = type.getTypeArguments();
+        return {
+          name,
+          kind: "set",
+          nullable,
+          elementType:
+            typeArgs && typeArgs[0] ? this.convertType(typeArgs[0], `${name}_element`) : undefined,
+        };
+      }
+    }
+
+    // Object
+    if (type.isObject()) {
+      const properties: Record<string, TypeInfo> = {};
+
+      for (const prop of type.getProperties()) {
+        const propName = prop.getName();
+        const propType = prop.getTypeAtLocation(this.project.getSourceFiles()[0]);
+        properties[propName] = this.convertType(propType, propName);
+      }
+
+      return {
+        name,
+        kind: "object",
+        nullable,
+        properties,
+      };
+    }
+
+    // Null
+    if (type.isNull()) {
+      return { name, kind: "null", nullable: true };
+    }
+
+    // Unknown/Any
+    return { name, kind: "unknown", nullable };
+  }
+
+  /**
+   * Analyze fields and determine confidence/bounds
+   */
+  private analyzeFields(stateType: TypeInfo, prefix = ""): FieldAnalysis[] {
+    const fields: FieldAnalysis[] = [];
+
+    if (stateType.kind === "object" && stateType.properties) {
+      for (const [key, propType] of Object.entries(stateType.properties)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+
+        // Recursively analyze nested objects (but not Map/Set - they're leaf nodes)
+        if (propType.kind === "object") {
+          // Don't add intermediate objects as fields, just recurse into them
+          fields.push(...this.analyzeFields(propType, path));
+        } else {
+          // This is a leaf field (or Map/Set), add it for configuration
+          const analysis = this.analyzeField(path, propType);
+          fields.push(analysis);
+        }
+      }
+    }
+
+    return fields;
+  }
+
+  /**
+   * Analyze a single field and determine configuration needs
+   */
+  private analyzeField(path: string, type: TypeInfo): FieldAnalysis {
+    const analysis: FieldAnalysis = {
+      path,
+      type,
+      confidence: "low",
+      evidence: [],
+      suggestions: [],
+      bounds: {},
+    };
+
+    // Boolean - high confidence, no config needed
+    if (type.kind === "boolean") {
+      analysis.confidence = "high";
+      analysis.evidence.push("Boolean type - auto-configured");
+      return analysis;
+    }
+
+    // Enum - high confidence
+    if (type.kind === "enum" && type.enumValues) {
+      analysis.confidence = "high";
+      analysis.evidence.push(`Enum with ${type.enumValues.length} values`);
+      analysis.bounds!.values = type.enumValues;
+      return analysis;
+    }
+
+    // Array - needs manual configuration
+    if (type.kind === "array") {
+      analysis.confidence = "low";
+      analysis.suggestions.push("Choose maxLength: 5 (fast), 10 (balanced), or 20 (thorough)");
+      analysis.bounds!.maxLength = undefined;
+
+      // Try to find bounds in code
+      const foundBound = this.findArrayBound(path);
+      if (foundBound) {
+        analysis.confidence = "medium";
+        analysis.evidence.push(`Found array check: ${foundBound.evidence}`);
+        analysis.bounds!.maxLength = foundBound.value;
+      }
+
+      return analysis;
+    }
+
+    // Number - needs manual configuration
+    if (type.kind === "number") {
+      analysis.confidence = "low";
+      analysis.suggestions.push("Provide min and max values based on your application logic");
+      analysis.bounds!.min = undefined;
+      analysis.bounds!.max = undefined;
+
+      // Try to find bounds in code
+      const foundBound = this.findNumberBound(path);
+      if (foundBound) {
+        analysis.confidence = "high";
+        analysis.evidence.push(`Found comparison: ${foundBound.evidence}`);
+        analysis.bounds = { ...analysis.bounds!, ...foundBound.bounds };
+      }
+
+      return analysis;
+    }
+
+    // String - needs manual configuration
+    if (type.kind === "string") {
+      analysis.confidence = "low";
+      analysis.suggestions.push(
+        'Provide 2-3 example values: ["value1", "value2", "value3"]',
+        "Or use { abstract: true } for symbolic verification"
+      );
+      analysis.bounds!.values = undefined;
+      return analysis;
+    }
+
+    // Map/Set - needs manual configuration
+    if (type.kind === "map" || type.kind === "set") {
+      analysis.confidence = "low";
+      analysis.suggestions.push("Provide maxSize (recommended: 3-5)");
+      analysis.bounds!.maxSize = undefined;
+      return analysis;
+    }
+
+    return analysis;
+  }
+
+  /**
+   * Try to find array bounds by searching for length checks
+   */
+  private findArrayBound(path: string): { value: number; evidence: string } | null {
+    // TODO: Search source code for patterns like:
+    // - if (array.length < N)
+    // - array.slice(0, N)
+    // This would require analyzing the actual usage in code
+    return null;
+  }
+
+  /**
+   * Try to find number bounds by searching for comparisons
+   */
+  private findNumberBound(
+    path: string
+  ): { bounds: { min?: number; max?: number }; evidence: string } | null {
+    // TODO: Search source code for patterns like:
+    // - if (counter < 100)
+    // - if (value >= 0 && value <= 100)
+    // This would require analyzing the actual usage in code
+    return null;
+  }
+}
+
+export async function analyzeCodebase(options: {
+  tsConfigPath: string;
+  stateFilePath?: string;
+}): Promise<CodebaseAnalysis> {
+  const extractor = new TypeExtractor(options.tsConfigPath);
+  return extractor.analyzeCodebase(options.stateFilePath);
+}

package/vendor/analysis/src/index.ts

@@ -0,0 +1,7 @@
+// Main entry point for @fairfox/polly-analysis
+
+// Export types
+export * from "./types";
+
+// Export extractors
+export * from "./extract";