@fairfox/polly 0.1.1 → 0.1.3

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

@@ -0,0 +1,53 @@
+// Architecture Decision Record types
+
+/**
+ * Architecture Decision Record
+ * Based on Michael Nygard's ADR format
+ */
+export type ADR = {
+  /** ADR number/ID */
+  id: string;
+
+  /** Decision title */
+  title: string;
+
+  /** Status: proposed, accepted, deprecated, superseded */
+  status: ADRStatus;
+
+  /** Date of decision */
+  date: string;
+
+  /** Context - what is the issue motivating this decision */
+  context: string;
+
+  /** Decision - what is the change we're proposing */
+  decision: string;
+
+  /** Consequences - what becomes easier or more difficult */
+  consequences: string;
+
+  /** Optional: Alternatives considered */
+  alternatives?: string[];
+
+  /** Optional: Links to superseding/superseded ADRs */
+  links?: ADRLink[];
+
+  /** Source file path */
+  source: string;
+};
+
+export type ADRStatus = "proposed" | "accepted" | "deprecated" | "superseded";
+
+export type ADRLink = {
+  type: "supersedes" | "superseded-by" | "related-to";
+  adrId: string;
+  title?: string;
+};
+
+/**
+ * Collection of ADRs
+ */
+export type ADRCollection = {
+  adrs: ADR[];
+  directory: string;
+};

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

@@ -0,0 +1,245 @@
+// Types for architecture analysis (used by visualize)
+
+import type { MessageHandler } from "./core";
+
+// ─────────────────────────────────────────────────────────────────
+// Context Information
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Information about an execution context (background, content, popup, etc.)
+ */
+export type ContextInfo = {
+  /** Type of context */
+  type: string;
+
+  /** Entry point file path */
+  entryPoint: string;
+
+  /** Message handlers defined in this context */
+  handlers: MessageHandler[];
+
+  /** Chrome APIs used in this context */
+  chromeAPIs: string[];
+
+  /** External APIs called from this context */
+  externalAPIs: ExternalAPICall[];
+
+  /** UI components rendered (for popup/options/devtools) */
+  components?: ComponentInfo[];
+
+  /** Dependencies/imports */
+  dependencies: string[];
+
+  /** JSDoc description if available */
+  description?: string;
+};
+
+/**
+ * Component information (for UI contexts)
+ */
+export type ComponentInfo = {
+  name: string;
+  type: "function" | "class";
+  filePath: string;
+  line: number;
+  props?: string[];
+  description?: string;
+};
+
+// ─────────────────────────────────────────────────────────────────
+// Message Flow Analysis
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Represents a message flow between contexts
+ */
+export type MessageFlow = {
+  /** Message type identifier */
+  messageType: string;
+
+  /** Source context */
+  from: string;
+
+  /** Destination context(s) */
+  to: string[];
+
+  /** What triggers this flow (user action, event, etc.) */
+  trigger?: string;
+
+  /** Sequence of steps in this flow */
+  sequence: MessageStep[];
+
+  /** Flow name (from @flow annotation or inferred) */
+  flowName?: string;
+
+  /** Description (from JSDoc) */
+  description?: string;
+};
+
+/**
+ * A step in a message flow sequence
+ */
+export type MessageStep = {
+  /** Step number in sequence */
+  step: number;
+
+  /** Action description */
+  action: string;
+
+  /** Context where this step occurs */
+  context: string;
+
+  /** Source location */
+  location?: {
+    file: string;
+    line: number;
+  };
+};
+
+// ─────────────────────────────────────────────────────────────────
+// External Integrations
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * External system integration
+ */
+export type ExternalIntegration = {
+  /** Type of integration */
+  type: "api" | "storage" | "browser-api" | "external-script" | "websocket";
+
+  /** Name/identifier */
+  name: string;
+
+  /** Technology/protocol */
+  technology?: string;
+
+  /** Base URL or endpoint */
+  url?: string;
+
+  /** Where it's used (file paths) */
+  usedIn: string[];
+
+  /** Description (from JSDoc or inferred) */
+  description?: string;
+
+  /** Specific API calls made */
+  calls?: ExternalAPICall[];
+};
+
+/**
+ * A specific API call
+ */
+export type ExternalAPICall = {
+  /** HTTP method or API method name */
+  method: string;
+
+  /** Endpoint or resource */
+  endpoint: string;
+
+  /** Where this call is made */
+  location: {
+    file: string;
+    line: number;
+  };
+
+  /** Description */
+  description?: string;
+};
+
+// ─────────────────────────────────────────────────────────────────
+// Manifest Analysis
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Parsed manifest.json information
+ */
+export type ManifestInfo = {
+  /** Extension name */
+  name: string;
+
+  /** Version */
+  version: string;
+
+  /** Description */
+  description?: string;
+
+  /** Manifest version (2 or 3) */
+  manifestVersion: number;
+
+  /** Background script/service worker */
+  background?: {
+    type: "script" | "service_worker";
+    files: string[];
+  };
+
+  /** Content scripts */
+  contentScripts?: Array<{
+    matches: string[];
+    js: string[];
+    css?: string[];
+  }>;
+
+  /** Popup */
+  popup?: {
+    html: string;
+    default?: boolean;
+  };
+
+  /** Options page */
+  options?: {
+    page: string;
+    openInTab?: boolean;
+  };
+
+  /** DevTools page */
+  devtools?: {
+    page: string;
+  };
+
+  /** Permissions */
+  permissions?: string[];
+
+  /** Host permissions */
+  hostPermissions?: string[];
+};
+
+// ─────────────────────────────────────────────────────────────────
+// Complete Architecture Analysis
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Complete architecture analysis result
+ */
+export type ArchitectureAnalysis = {
+  /** Basic system information */
+  system: {
+    name: string;
+    version: string;
+    description?: string;
+  };
+
+  /** Manifest information */
+  manifest?: ManifestInfo;
+
+  /** All contexts found in the system */
+  contexts: Record<string, ContextInfo>;
+
+  /** Message flows between contexts */
+  messageFlows: MessageFlow[];
+
+  /** External integrations */
+  integrations: ExternalIntegration[];
+
+  /** Architecture Decision Records */
+  adrs?: ADRCollection;
+
+  /** Repository information */
+  repository?: {
+    url: string;
+    type: string;
+  };
+};
+
+// Import ADR types
+import type { ADRCollection } from "./adr";

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

@@ -0,0 +1,210 @@
+// ═══════════════════════════════════════════════════════════════
+// Core Analysis Model (Domain-Agnostic)
+// ═══════════════════════════════════════════════════════════════
+//
+// This module defines abstract types for analyzing message-passing systems.
+// These types are independent of the specific domain (web extensions,
+// actors, event buses, etc.).
+
+// ─────────────────────────────────────────────────────────────────
+// Type System (Universal)
+// ─────────────────────────────────────────────────────────────────
+
+export type TypeKind =
+  | "boolean"
+  | "string"
+  | "number"
+  | "enum"
+  | "array"
+  | "object"
+  | "map"
+  | "set"
+  | "union"
+  | "null"
+  | "unknown";
+
+export type TypeInfo = {
+  name: string;
+  kind: TypeKind;
+  nullable: boolean;
+  elementType?: TypeInfo; // For arrays, sets
+  valueType?: TypeInfo; // For maps
+  properties?: Record<string, TypeInfo>; // For objects
+  enumValues?: string[]; // For enums
+  unionTypes?: TypeInfo[]; // For unions
+};
+
+// ─────────────────────────────────────────────────────────────────
+// Node System (Abstract)
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * A node represents an entity in the system that can send/receive messages.
+ *
+ * Examples:
+ * - Web extension: "background", "content", "popup"
+ * - Actor system: Individual actor instances
+ * - Event bus: Emitters/listeners
+ * - Worker threads: Main thread + worker instances
+ */
+export type NodeDefinition = {
+  /** Unique identifier for this node */
+  id: string;
+
+  /** Type of node (adapter-specific) */
+  type: string;
+
+  /** Which nodes can this send messages to? */
+  canSendTo: string[];
+
+  /** Which nodes can send messages to this? */
+  canReceiveFrom: string[];
+
+  /** Optional: Additional metadata */
+  metadata?: Record<string, unknown>;
+};
+
+// ─────────────────────────────────────────────────────────────────
+// Message Types (Abstract)
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Defines a type of message that flows through the system
+ */
+export type MessageTypeDefinition = {
+  /** Name/identifier of the message type */
+  name: string;
+
+  /** Schema of the message payload */
+  payload: TypeInfo;
+
+  /** Routing constraints */
+  routing: {
+    /** Which node types can send this message? */
+    from: string[];
+
+    /** Which node types can receive this message? */
+    to: string[];
+  };
+
+  /** Optional: Expected response type */
+  response?: TypeInfo;
+};
+
+// ─────────────────────────────────────────────────────────────────
+// State Schema (Abstract)
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Configuration for a state field
+ */
+export type FieldConfig =
+  | { maxLength: number | null }
+  | { min: number | null; max: number | null }
+  | { type: "enum"; values: string[] }
+  | { values: string[] | null; abstract?: boolean }
+  | { maxSize: number | null; valueType?: unknown }
+  | { abstract: boolean };
+
+export type StateSchema = Record<string, FieldConfig>;
+
+// ─────────────────────────────────────────────────────────────────
+// State Mutations (Abstract)
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Represents an assignment to a state field
+ */
+export type StateAssignment = {
+  /** Field path (e.g., "user.loggedIn") */
+  field: string;
+
+  /** The assigned value */
+  value: string | boolean | number | null;
+
+  /** Optional condition guard */
+  conditional?: string;
+};
+
+// ─────────────────────────────────────────────────────────────────
+// Verification Conditions (Abstract)
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * A verification condition (precondition or postcondition)
+ */
+export type VerificationCondition = {
+  /** The condition expression as a string */
+  expression: string;
+
+  /** Optional error message */
+  message?: string;
+
+  /** Source location */
+  location: {
+    line: number;
+    column: number;
+  };
+};
+
+// ─────────────────────────────────────────────────────────────────
+// Message Handler (Abstract)
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Represents a message handler extracted from code
+ */
+export type MessageHandler = {
+  /** Which message type does this handle? */
+  messageType: string;
+
+  /** Which node handles this message? */
+  node: string;
+
+  /** State assignments made by this handler */
+  assignments: StateAssignment[];
+
+  /** Preconditions (requires() calls) */
+  preconditions: VerificationCondition[];
+
+  /** Postconditions (ensures() calls) */
+  postconditions: VerificationCondition[];
+
+  /** Source location */
+  location: {
+    file: string;
+    line: number;
+  };
+};
+
+// ─────────────────────────────────────────────────────────────────
+// Confidence Levels (Universal)
+// ─────────────────────────────────────────────────────────────────
+
+export type Confidence = "high" | "medium" | "low";
+
+export type FieldAnalysis = {
+  path: string;
+  type: TypeInfo;
+  confidence: Confidence;
+  evidence: string[];
+  suggestions: string[];
+  bounds?: {
+    min?: number;
+    max?: number;
+    maxLength?: number;
+    maxSize?: number;
+    values?: string[];
+  };
+};
+
+// ─────────────────────────────────────────────────────────────────
+// Codebase Analysis Result
+// ─────────────────────────────────────────────────────────────────
+
+export type CodebaseAnalysis = {
+  stateType: TypeInfo | null;
+  messageTypes: string[];
+  fields: FieldAnalysis[];
+  handlers: MessageHandler[];
+};

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

@@ -0,0 +1,18 @@
+// Export all core types
+export * from "./core";
+
+// Export architecture types
+export * from "./architecture";
+
+// Export ADR types
+export * from "./adr";
+
+// Extension-specific context types
+export type Context =
+  | "background"
+  | "content"
+  | "popup"
+  | "devtools"
+  | "options"
+  | "offscreen"
+  | "sidepanel";

package/vendor/verify/src/adapters/base.ts

@@ -0,0 +1,164 @@
+// ═══════════════════════════════════════════════════════════════
+// Routing Adapter Interface
+// ═══════════════════════════════════════════════════════════════
+//
+// Adapters translate domain-specific code into the core verification model.
+// Each adapter implements pattern matching and extraction logic for a
+// specific messaging paradigm.
+
+import type { Node } from "ts-morph";
+import type {
+  CoreVerificationModel,
+  MessageHandler,
+  StateAssignment,
+  VerificationCondition,
+  CodebaseAnalysis,
+} from "../core/model";
+
+// ─────────────────────────────────────────────────────────────────
+// Adapter Configuration
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Base configuration for all adapters
+ */
+export type AdapterConfig = {
+  /** Root directory to analyze */
+  rootDir?: string;
+
+  /** TypeScript config path */
+  tsConfigPath: string;
+
+  /** Adapter-specific options */
+  [key: string]: unknown;
+};
+
+// ─────────────────────────────────────────────────────────────────
+// Adapter Interface
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Base interface that all routing adapters must implement.
+ *
+ * Adapters are responsible for:
+ * 1. Extracting the abstract model from domain-specific code
+ * 2. Recognizing domain-specific patterns (how messages are sent/received)
+ * 3. Mapping domain concepts to abstract model concepts
+ */
+export interface RoutingAdapter<TConfig extends AdapterConfig = AdapterConfig> {
+  /** Unique name for this adapter */
+  readonly name: string;
+
+  /** Configuration */
+  readonly config: TConfig;
+
+  /**
+   * Extract the complete abstract model from a codebase
+   *
+   * This is the main entry point for the adapter. It should:
+   * 1. Discover nodes in the system
+   * 2. Extract message types
+   * 3. Infer routing rules
+   * 4. Extract message handlers and state mutations
+   * 5. Return a complete CoreVerificationModel
+   */
+  extractModel(): CoreVerificationModel;
+
+  /**
+   * Recognize if an AST node is a message handler registration
+   *
+   * @param node - TypeScript AST node to analyze
+   * @returns MessageHandler if recognized, null otherwise
+   *
+   * @example
+   * // Web extension adapter recognizes:
+   * bus.on("USER_LOGIN", (payload) => { ... })
+   *
+   * // Actor adapter recognizes:
+   * actor.receive((msg) => { if (msg.type === "USER_LOGIN") { ... } })
+   */
+  recognizeMessageHandler(node: Node): MessageHandler | null;
+
+  /**
+   * Recognize if an AST node is a state mutation
+   *
+   * @param node - TypeScript AST node to analyze
+   * @returns StateAssignment if recognized, null otherwise
+   *
+   * @example
+   * // Most adapters recognize:
+   * state.user.loggedIn = true
+   */
+  recognizeStateUpdate(node: Node): StateAssignment | null;
+
+  /**
+   * Recognize if an AST node is a verification condition
+   *
+   * @param node - TypeScript AST node to analyze
+   * @param type - "precondition" or "postcondition"
+   * @returns VerificationCondition if recognized, null otherwise
+   *
+   * @example
+   * // All adapters should recognize:
+   * requires(state.user.loggedIn === false, "Must not be logged in")
+   * ensures(state.user.loggedIn === true, "Must be logged in")
+   */
+  recognizeVerificationCondition(
+    node: Node,
+    type: "precondition" | "postcondition"
+  ): VerificationCondition | null;
+
+  /**
+   * Optional: Provide custom TLA+ invariants specific to this domain
+   *
+   * @example
+   * // Actor adapter might add:
+   * ["ActorMailboxBounded", "\\A actor \\in Actors : Len(mailbox[actor]) <= MaxMailboxSize"]
+   */
+  customInvariants?(): Array<[name: string, tlaExpression: string]>;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Helper: Base Adapter Class
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Base class providing common extraction logic that adapters can extend.
+ * This reduces boilerplate in adapter implementations.
+ */
+export abstract class BaseRoutingAdapter<TConfig extends AdapterConfig = AdapterConfig>
+  implements RoutingAdapter<TConfig>
+{
+  abstract readonly name: string;
+  abstract readonly config: TConfig;
+
+  abstract extractModel(): CoreVerificationModel;
+  abstract recognizeMessageHandler(node: Node): MessageHandler | null;
+  abstract recognizeStateUpdate(node: Node): StateAssignment | null;
+  abstract recognizeVerificationCondition(
+    node: Node,
+    type: "precondition" | "postcondition"
+  ): VerificationCondition | null;
+
+  /**
+   * Common pattern: Extract verification conditions from requires()/ensures() calls
+   *
+   * Subclasses can use this helper to avoid duplicating condition extraction logic.
+   */
+  protected extractConditionFromCall(
+    callNode: Node,
+    expectedFunctionName: string
+  ): VerificationCondition | null {
+    // Shared implementation for requires()/ensures() extraction
+    // This will be implemented when we refactor the existing handler extraction
+    return null;
+  }
+
+  /**
+   * Common pattern: Extract state assignments from binary expressions
+   */
+  protected extractAssignmentFromBinaryExpr(binaryNode: Node): StateAssignment | null {
+    // Shared implementation for state.field = value extraction
+    return null;
+  }
+}