@fairfox/polly 0.1.0 → 0.1.2

package/vendor/verify/src/config/parser.ts

@@ -0,0 +1,303 @@
+// Configuration validator - detects incomplete configuration
+
+import type { ValidationResult, ConfigIssue, VerificationConfig } from "../types";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export class ConfigValidator {
+  private issues: ConfigIssue[] = [];
+
+  validate(configPath: string): ValidationResult {
+    this.issues = [];
+
+    if (!fs.existsSync(configPath)) {
+      this.issues.push({
+        type: "incomplete",
+        severity: "error",
+        message: "Configuration file does not exist",
+        suggestion: "Run 'bun verify --setup' to generate configuration",
+      });
+
+      return {
+        valid: false,
+        issues: this.issues,
+      };
+    }
+
+    // Read the source file
+    const configSource = fs.readFileSync(configPath, "utf-8");
+
+    // Check for CONFIGURE markers
+    this.checkConfigureMarkers(configSource);
+
+    // Check for REVIEW markers (warnings only)
+    this.checkReviewMarkers(configSource);
+
+    // Load and validate the actual config
+    try {
+      const config = this.loadConfig(configPath);
+      this.validateConfig(config);
+    } catch (error) {
+      this.issues.push({
+        type: "invalid_value",
+        severity: "error",
+        message: `Failed to load configuration: ${error instanceof Error ? error.message : String(error)}`,
+        suggestion: "Check for syntax errors in the configuration file",
+      });
+    }
+
+    const hasErrors = this.issues.some((i) => i.severity === "error");
+
+    return {
+      valid: !hasErrors,
+      issues: this.issues,
+    };
+  }
+
+  private checkConfigureMarkers(source: string): void {
+    const configureRegex = /\/\*\s*CONFIGURE\s*\*\//g;
+    const matches = [...source.matchAll(configureRegex)];
+
+    if (matches.length > 0) {
+      // Find line numbers for each match
+      const lines = source.split("\n");
+      const locations: Array<{ line: number; column: number; context: string }> = [];
+
+      for (const match of matches) {
+        const position = match.index!;
+        const lineNumber = source.substring(0, position).split("\n").length;
+        const line = lines[lineNumber - 1];
+
+        // Extract field name from context
+        const fieldMatch = line.match(/"([^"]+)":\s*{/);
+        const fieldName = fieldMatch ? fieldMatch[1] : "unknown";
+
+        locations.push({
+          line: lineNumber,
+          column: match.index! - source.lastIndexOf("\n", position),
+          context: fieldName,
+        });
+      }
+
+      this.issues.push({
+        type: "incomplete",
+        severity: "error",
+        message: `Found ${matches.length} incomplete configuration marker(s)`,
+        suggestion: "Replace all /* CONFIGURE */ markers with actual values",
+      });
+
+      // Add individual issues for each marker
+      for (const loc of locations) {
+        this.issues.push({
+          type: "incomplete",
+          severity: "error",
+          field: loc.context,
+          location: { line: loc.line, column: loc.column },
+          message: `Incomplete configuration at line ${loc.line}`,
+          suggestion: `Fill in value for "${loc.context}"`,
+        });
+      }
+    }
+  }
+
+  private checkReviewMarkers(source: string): void {
+    const reviewRegex = /\/\*\s*REVIEW\s*\*\//g;
+    const matches = [...source.matchAll(reviewRegex)];
+
+    if (matches.length > 0) {
+      this.issues.push({
+        type: "incomplete",
+        severity: "warning",
+        message: `Found ${matches.length} value(s) that should be reviewed`,
+        suggestion: "Review auto-generated values marked with /* REVIEW */",
+      });
+    }
+  }
+
+  private loadConfig(configPath: string): VerificationConfig {
+    // Dynamic import of the config file
+    // Note: In production, this would use proper module loading
+    delete require.cache[require.resolve(path.resolve(configPath))];
+    const module = require(path.resolve(configPath));
+    return module.default || module;
+  }
+
+  private validateConfig(config: VerificationConfig): void {
+    // Check for null values
+    this.findNullPlaceholders(config.state, "state");
+    this.findNullPlaceholders(config.messages, "messages");
+
+    // Validate bounds
+    this.validateBounds(config);
+  }
+
+  private findNullPlaceholders(obj: any, path: string): void {
+    if (obj === null || obj === undefined) {
+      this.issues.push({
+        type: "null_placeholder",
+        severity: "error",
+        field: path,
+        message: `Configuration incomplete: ${path}`,
+        suggestion: "Replace null with a concrete value",
+      });
+      return;
+    }
+
+    if (typeof obj !== "object") {
+      return;
+    }
+
+    for (const [key, value] of Object.entries(obj)) {
+      const fullPath = `${path}.${key}`;
+
+      if (value === null) {
+        this.issues.push({
+          type: "null_placeholder",
+          severity: "error",
+          field: fullPath,
+          message: `Configuration incomplete: ${fullPath}`,
+          suggestion: "Replace null with a concrete value",
+        });
+      } else if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        this.findNullPlaceholders(value, fullPath);
+      }
+    }
+  }
+
+  private validateBounds(config: VerificationConfig): void {
+    // Check messages config
+    if (config.messages.maxInFlight !== null) {
+      if (config.messages.maxInFlight < 1) {
+        this.issues.push({
+          type: "invalid_value",
+          severity: "error",
+          field: "messages.maxInFlight",
+          message: "maxInFlight must be at least 1",
+          suggestion: "Use a value between 4-10 for most cases",
+        });
+      }
+
+      if (config.messages.maxInFlight > 20) {
+        this.issues.push({
+          type: "unrealistic_bound",
+          severity: "warning",
+          field: "messages.maxInFlight",
+          message: "Very high maxInFlight (>20) will slow verification significantly",
+          suggestion: "Use 4-10 for development, up to 20 for thorough verification",
+        });
+      }
+    }
+
+    if (config.messages.maxTabs !== null) {
+      if (config.messages.maxTabs < 1) {
+        this.issues.push({
+          type: "invalid_value",
+          severity: "error",
+          field: "messages.maxTabs",
+          message: "maxTabs must be at least 1",
+          suggestion: "Use 2-3 for most cases",
+        });
+      }
+
+      if (config.messages.maxTabs > 10) {
+        this.issues.push({
+          type: "unrealistic_bound",
+          severity: "warning",
+          field: "messages.maxTabs",
+          message: "Very high maxTabs (>10) will slow verification significantly",
+          suggestion: "Use 2-3 for most cases",
+        });
+      }
+    }
+
+    // Check state field bounds
+    for (const [fieldName, fieldConfig] of Object.entries(config.state)) {
+      if (typeof fieldConfig !== "object" || fieldConfig === null) {
+        continue;
+      }
+
+      // Array bounds
+      if ("maxLength" in fieldConfig) {
+        const maxLength = (fieldConfig as any).maxLength;
+        if (maxLength !== null) {
+          if (maxLength < 0) {
+            this.issues.push({
+              type: "invalid_value",
+              severity: "error",
+              field: `state.${fieldName}.maxLength`,
+              message: "maxLength cannot be negative",
+              suggestion: "Use a positive number",
+            });
+          }
+
+          if (maxLength > 50) {
+            this.issues.push({
+              type: "unrealistic_bound",
+              severity: "warning",
+              field: `state.${fieldName}.maxLength`,
+              message: `Very large maxLength (${maxLength}) will slow verification`,
+              suggestion: "Use 10-20 for most cases",
+            });
+          }
+        }
+      }
+
+      // Number bounds
+      if ("min" in fieldConfig && "max" in fieldConfig) {
+        const min = (fieldConfig as any).min;
+        const max = (fieldConfig as any).max;
+
+        if (min !== null && max !== null && min > max) {
+          this.issues.push({
+            type: "invalid_value",
+            severity: "error",
+            field: `state.${fieldName}`,
+            message: `Invalid range: min (${min}) > max (${max})`,
+            suggestion: "Ensure min is less than or equal to max",
+          });
+        }
+
+        if (min !== null && max !== null && max - min > 1000) {
+          this.issues.push({
+            type: "unrealistic_bound",
+            severity: "warning",
+            field: `state.${fieldName}`,
+            message: `Very large number range (${max - min}) will slow verification`,
+            suggestion: "Use smaller ranges when possible",
+          });
+        }
+      }
+
+      // Map/Set bounds
+      if ("maxSize" in fieldConfig) {
+        const maxSize = (fieldConfig as any).maxSize;
+        if (maxSize !== null) {
+          if (maxSize < 0) {
+            this.issues.push({
+              type: "invalid_value",
+              severity: "error",
+              field: `state.${fieldName}.maxSize`,
+              message: "maxSize cannot be negative",
+              suggestion: "Use a positive number",
+            });
+          }
+
+          if (maxSize > 20) {
+            this.issues.push({
+              type: "unrealistic_bound",
+              severity: "warning",
+              field: `state.${fieldName}.maxSize`,
+              message: `Very large maxSize (${maxSize}) will slow verification`,
+              suggestion: "Use 3-5 for most cases",
+            });
+          }
+        }
+      }
+    }
+  }
+}
+
+export function validateConfig(configPath: string): ValidationResult {
+  const validator = new ConfigValidator();
+  return validator.validate(configPath);
+}

package/vendor/verify/src/config/types.ts

@@ -0,0 +1,113 @@
+// ═══════════════════════════════════════════════════════════════
+// Configuration Types for Adapter-Based Verification
+// ═══════════════════════════════════════════════════════════════
+
+import type { RoutingAdapter } from "../adapters/base";
+import type { StateSchema } from "../core/model";
+
+// ─────────────────────────────────────────────────────────────────
+// New Adapter-Based Configuration
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Adapter-based verification configuration (new format)
+ */
+export interface AdapterVerificationConfig {
+  /** The routing adapter to use */
+  adapter: RoutingAdapter;
+
+  /** State bounds (domain-agnostic) */
+  state: StateSchema;
+
+  /** Concurrency bounds */
+  bounds?: {
+    maxInFlight?: number;
+    [key: string]: unknown;
+  };
+
+  /** Verification behavior on build */
+  onBuild?: "warn" | "error" | "off";
+
+  /** Verification behavior on release */
+  onRelease?: "warn" | "error" | "off";
+
+  /** Optional: Custom invariants */
+  invariants?: Array<{
+    name: string;
+    expression: string;
+    description?: string;
+  }>;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Legacy Configuration (Backward Compatibility)
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Legacy verification configuration (backward compatible)
+ */
+export interface LegacyVerificationConfig {
+  /** State configuration (old format) */
+  state: Record<string, any>;
+
+  /** Message configuration (old format) */
+  messages: {
+    maxInFlight: number | null;
+    maxTabs: number | null;
+  };
+
+  /** Verification behavior on build */
+  onBuild: "warn" | "error" | "off";
+
+  /** Verification behavior on release */
+  onRelease: "warn" | "error" | "off";
+
+  /** Optional preset */
+  preset?: "quick" | "balanced" | "thorough";
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Unified Configuration Type
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * Union of new and legacy configuration formats
+ */
+export type UnifiedVerificationConfig = AdapterVerificationConfig | LegacyVerificationConfig;
+
+/**
+ * Type guard to check if config is adapter-based (new format)
+ */
+export function isAdapterConfig(
+  config: UnifiedVerificationConfig
+): config is AdapterVerificationConfig {
+  return "adapter" in config;
+}
+
+/**
+ * Type guard to check if config is legacy format
+ */
+export function isLegacyConfig(
+  config: UnifiedVerificationConfig
+): config is LegacyVerificationConfig {
+  return "messages" in config && !("adapter" in config);
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Configuration Validation
+// ─────────────────────────────────────────────────────────────────
+
+export interface ConfigIssue {
+  type: "incomplete" | "null_placeholder" | "unrealistic_bound" | "invalid_value";
+  severity: "error" | "warning";
+  field?: string;
+  location?: { line: number; column: number };
+  message: string;
+  suggestion: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  issues: ConfigIssue[];
+  configType?: "adapter" | "legacy";
+}

package/vendor/verify/src/core/model.ts

@@ -0,0 +1,267 @@
+// ═══════════════════════════════════════════════════════════════
+// Core Verification Model (Domain-Agnostic)
+// ═══════════════════════════════════════════════════════════════
+//
+// This module defines abstract types for any message-passing system.
+// These types are independent of the specific domain (web extensions,
+// actors, event buses, etc.).
+//
+// Adapters translate domain-specific code into this universal model.
+
+// ─────────────────────────────────────────────────────────────────
+// 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 MessageType = {
+  /** 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;
+};
+
+// ─────────────────────────────────────────────────────────────────
+// Routing Rules (Abstract)
+// ─────────────────────────────────────────────────────────────────
+
+export type RoutingPattern =
+  | "direct" // Point-to-point (actor.send)
+  | "broadcast" // One-to-many (event bus)
+  | "request-reply" // Request-response (extension messaging)
+  | "publish-subscribe" // Pub/sub pattern
+  | "custom"; // Adapter-defined
+
+export type RoutingRule = {
+  /** Type of routing pattern */
+  pattern: RoutingPattern;
+
+  /** Which message types use this routing? */
+  messageTypes: string[];
+
+  /** Optional: Custom routing logic description */
+  description?: string;
+};
+
+// ─────────────────────────────────────────────────────────────────
+// 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;
+  };
+};
+
+// ─────────────────────────────────────────────────────────────────
+// Complete Verification Model (Abstract)
+// ─────────────────────────────────────────────────────────────────
+
+/**
+ * The complete abstract model that the core verification engine operates on.
+ * This is what adapters produce from domain-specific code.
+ */
+export type CoreVerificationModel = {
+  /** All nodes in the system */
+  nodes: NodeDefinition[];
+
+  /** All message types that flow between nodes */
+  messageTypes: MessageType[];
+
+  /** Routing rules that govern message delivery */
+  routingRules: RoutingRule[];
+
+  /** State schema with bounds */
+  state: StateSchema;
+
+  /** All message handlers extracted from code */
+  handlers: MessageHandler[];
+
+  /** Concurrency bounds for model checking */
+  bounds: {
+    /** Maximum concurrent messages in flight */
+    maxConcurrentMessages: number;
+
+    /** Maximum number of nodes (for bounded model checking) */
+    maxNodes: number;
+
+    /** Optional: Adapter-specific bounds */
+    custom?: Record<string, 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[];
+  };
+};
+
+export type CodebaseAnalysis = {
+  stateType: TypeInfo | null;
+  messageTypes: string[];
+  fields: FieldAnalysis[];
+  handlers: MessageHandler[];
+};