@fairfox/polly 0.1.2 → 0.1.4

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

@@ -1,106 +0,0 @@
-// ═══════════════════════════════════════════════════════════════
-// Verification Primitives (Domain-Agnostic)
-// ═══════════════════════════════════════════════════════════════
-//
-// These are runtime no-ops but extracted during verification.
-// They work with ANY message-passing system, not just web extensions.
-
-/**
- * Assert a precondition that must be true when the handler executes.
- *
- * In production: No-op (compiled away)
- * In verification: Translated to TLA+ assertion
- *
- * @example
- * messageBus.on("USER_LOGIN", (payload) => {
- *   requires(state.user.loggedIn === false, "User must not be logged in")
- *   state.user.loggedIn = true
- * })
- */
-export function requires(condition: boolean, message?: string): void {
-  // Runtime no-op - only used during verification
-  if (!condition && message && process.env["NODE_ENV"] === "development") {
-    console.warn(`Precondition failed: ${message}`);
-  }
-}
-
-/**
- * Assert a postcondition that must be true after the handler completes.
- *
- * In production: No-op (compiled away)
- * In verification: Translated to TLA+ assertion
- *
- * @example
- * messageBus.on("USER_LOGIN", (payload) => {
- *   state.user.loggedIn = true
- *   ensures(state.user.loggedIn === true, "User must be logged in")
- * })
- */
-export function ensures(condition: boolean, message?: string): void {
-  // Runtime no-op - only used during verification
-  if (!condition && message && process.env["NODE_ENV"] === "development") {
-    console.warn(`Postcondition failed: ${message}`);
-  }
-}
-
-/**
- * Define a global invariant that must always hold.
- *
- * In production: No-op (compiled away)
- * In verification: Translated to TLA+ invariant
- *
- * @example
- * invariant("UserIdConsistent", () =>
- *   state.user.loggedIn === false || state.user.id !== null
- * )
- */
-export function invariant(name: string, condition: () => boolean): void {
-  // Runtime no-op - only used during verification
-  if (!condition() && process.env["NODE_ENV"] === "development") {
-    console.warn(`Invariant ${name} violated`);
-  }
-}
-
-/**
- * Assert that a value is within a valid range.
- *
- * @example
- * requires(inRange(todoCount, 0, 100), "Todo count must be 0-100")
- */
-export function inRange(value: number, min: number, max: number): boolean {
-  return value >= min && value <= max;
-}
-
-/**
- * Assert that a value is one of the allowed values.
- *
- * @example
- * requires(oneOf(state.user.role, ["admin", "user"]), "Role must be admin or user")
- */
-export function oneOf<T>(value: T, allowed: T[]): boolean {
-  return allowed.includes(value);
-}
-
-/**
- * Assert that an array has a specific length constraint.
- *
- * @example
- * requires(hasLength(state.todos, { max: 10 }), "Too many todos")
- */
-export function hasLength(array: unknown[], constraint: { min?: number; max?: number }): boolean {
-  if (constraint.min !== undefined && array.length < constraint.min) return false;
-  if (constraint.max !== undefined && array.length > constraint.max) return false;
-  return true;
-}
-
-// Re-export for convenience
-export const verify = {
-  requires,
-  ensures,
-  invariant,
-  inRange,
-  oneOf,
-  hasLength,
-};
-
-export default verify;

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

@@ -1,2 +0,0 @@
-// Re-export from shared analysis package
-export { extractHandlers, HandlerExtractor, type HandlerAnalysis } from "@fairfox/polly-analysis";

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

@@ -1,2 +0,0 @@
-// Re-export from shared analysis package
-export { analyzeCodebase, TypeExtractor } from "@fairfox/polly-analysis";

package/vendor/verify/src/index.ts

@@ -1,150 +0,0 @@
-// ═══════════════════════════════════════════════════════════════
-// Public API for @fairfox/polly-verify
-// ═══════════════════════════════════════════════════════════════
-
-// ─────────────────────────────────────────────────────────────────
-// Core Types (Domain-Agnostic)
-// ─────────────────────────────────────────────────────────────────
-export type {
-  CoreVerificationModel,
-  NodeDefinition,
-  MessageType,
-  RoutingPattern,
-  RoutingRule,
-  StateSchema,
-  FieldConfig,
-  StateAssignment,
-  VerificationCondition,
-  MessageHandler,
-  TypeKind,
-  TypeInfo,
-  Confidence,
-  FieldAnalysis,
-  CodebaseAnalysis,
-} from "./core/model";
-
-// ─────────────────────────────────────────────────────────────────
-// Verification Primitives (Domain-Agnostic)
-// ─────────────────────────────────────────────────────────────────
-export {
-  requires,
-  ensures,
-  invariant,
-  inRange,
-  oneOf,
-  hasLength,
-  verify,
-} from "./core/primitives";
-
-// Also re-export from old location for backward compatibility
-export * from "./primitives/index";
-
-// ─────────────────────────────────────────────────────────────────
-// Adapters
-// ─────────────────────────────────────────────────────────────────
-export type { RoutingAdapter, AdapterConfig } from "./adapters/base";
-export { BaseRoutingAdapter } from "./adapters/base";
-export {
-  WebExtensionAdapter,
-  type WebExtensionAdapterConfig,
-  type ExtensionContext,
-} from "./adapters/web-extension";
-export {
-  EventBusAdapter,
-  type EventBusAdapterConfig,
-} from "./adapters/event-bus";
-export {
-  WebSocketAdapter,
-  type WebSocketAdapterConfig,
-} from "./adapters/websocket";
-
-// Adapter Detection
-export {
-  AdapterDetector,
-  detectAdapter,
-  type AdapterDetectionResult,
-} from "./adapters/detection";
-
-// ─────────────────────────────────────────────────────────────────
-// Configuration
-// ─────────────────────────────────────────────────────────────────
-export type {
-  AdapterVerificationConfig,
-  LegacyVerificationConfig,
-  UnifiedVerificationConfig,
-  ConfigIssue,
-  ValidationResult as ConfigValidationResult,
-} from "./config/types";
-export { isAdapterConfig, isLegacyConfig } from "./config/types";
-
-import type { UnifiedVerificationConfig } from "./config/types";
-
-/**
- * Define verification configuration with type checking
- *
- * Supports both new adapter-based and legacy configurations.
- *
- * @example New adapter-based format:
- * ```typescript
- * import { WebExtensionAdapter, defineVerification } from '@fairfox/polly-verify'
- *
- * export default defineVerification({
- *   adapter: new WebExtensionAdapter({
- *     tsConfigPath: "./tsconfig.json",
- *     maxInFlight: 6,
- *   }),
- *   state: {
- *     "user.role": { type: "enum", values: ["admin", "user", "guest"] },
- *   },
- * })
- * ```
- *
- * @example Legacy format (backward compatible):
- * ```typescript
- * export default defineVerification({
- *   state: {
- *     "user.role": { type: "enum", values: ["admin", "user", "guest"] },
- *   },
- *   messages: {
- *     maxInFlight: 6,
- *     maxTabs: 2,
- *   },
- * })
- * ```
- */
-export function defineVerification<T extends UnifiedVerificationConfig>(config: T): T {
-  // Validate configuration structure
-  if ("adapter" in config) {
-    // New adapter-based format
-    if (!config.adapter) {
-      throw new Error("Configuration must include an adapter");
-    }
-    if (!config.state) {
-      throw new Error("Configuration must include state bounds");
-    }
-  } else if ("messages" in config) {
-    // Legacy format
-    if (!config.state) {
-      throw new Error("Configuration must include state bounds");
-    }
-    if (!config.messages) {
-      throw new Error("Legacy configuration must include messages bounds");
-    }
-  } else {
-    throw new Error(
-      "Invalid configuration format. Must include either 'adapter' (new format) or 'messages' (legacy format)"
-    );
-  }
-
-  return config;
-}
-
-// ─────────────────────────────────────────────────────────────────
-// Legacy API (Backward Compatibility)
-// ─────────────────────────────────────────────────────────────────
-export type { VerificationConfig, ValidationResult } from "./types";
-export { HandlerExtractor, extractHandlers } from "./extract/handlers";
-export { analyzeCodebase } from "./extract/types";
-export { TLAGenerator, generateTLA } from "./codegen/tla";
-export { generateConfig } from "./codegen/config";
-export { validateConfig } from "./config/parser";

package/vendor/verify/src/primitives/index.ts

@@ -1,102 +0,0 @@
-// Verification primitives for formal verification
-// These are runtime no-ops but extracted during verification
-
-/**
- * Assert a precondition that must be true when the handler executes.
- *
- * In production: No-op (compiled away)
- * In verification: Translated to TLA+ assertion
- *
- * @example
- * messageBus.on("USER_LOGIN", (payload) => {
- *   requires(state.user.loggedIn === false, "User must not be logged in")
- *   state.user.loggedIn = true
- * })
- */
-export function requires(condition: boolean, message?: string): void {
-  // Runtime no-op - only used during verification
-  if (!condition && message && process.env.NODE_ENV === "development") {
-    console.warn(`Precondition failed: ${message}`);
-  }
-}
-
-/**
- * Assert a postcondition that must be true after the handler completes.
- *
- * In production: No-op (compiled away)
- * In verification: Translated to TLA+ assertion
- *
- * @example
- * messageBus.on("USER_LOGIN", (payload) => {
- *   state.user.loggedIn = true
- *   ensures(state.user.loggedIn === true, "User must be logged in")
- * })
- */
-export function ensures(condition: boolean, message?: string): void {
-  // Runtime no-op - only used during verification
-  if (!condition && message && process.env.NODE_ENV === "development") {
-    console.warn(`Postcondition failed: ${message}`);
-  }
-}
-
-/**
- * Define a global invariant that must always hold.
- *
- * In production: No-op (compiled away)
- * In verification: Translated to TLA+ invariant
- *
- * @example
- * invariant("UserIdConsistent", () =>
- *   state.user.loggedIn === false || state.user.id !== null
- * )
- */
-export function invariant(name: string, condition: () => boolean): void {
-  // Runtime no-op - only used during verification
-  if (!condition() && process.env.NODE_ENV === "development") {
-    console.warn(`Invariant ${name} violated`);
-  }
-}
-
-/**
- * Assert that a value is within a valid range.
- *
- * @example
- * requires(inRange(todoCount, 0, 100), "Todo count must be 0-100")
- */
-export function inRange(value: number, min: number, max: number): boolean {
-  return value >= min && value <= max;
-}
-
-/**
- * Assert that a value is one of the allowed values.
- *
- * @example
- * requires(oneOf(state.user.role, ["admin", "user"]), "Role must be admin or user")
- */
-export function oneOf<T>(value: T, allowed: T[]): boolean {
-  return allowed.includes(value);
-}
-
-/**
- * Assert that an array has a specific length constraint.
- *
- * @example
- * requires(hasLength(state.todos, { max: 10 }), "Too many todos")
- */
-export function hasLength(array: unknown[], constraint: { min?: number; max?: number }): boolean {
-  if (constraint.min !== undefined && array.length < constraint.min) return false;
-  if (constraint.max !== undefined && array.length > constraint.max) return false;
-  return true;
-}
-
-// Re-export for convenience
-export const verify = {
-  requires,
-  ensures,
-  invariant,
-  inRange,
-  oneOf,
-  hasLength,
-};
-
-export default verify;

package/vendor/verify/src/runner/docker.ts

@@ -1,283 +0,0 @@
-// Docker container management for TLA+ verification
-
-import { spawn, type ChildProcess } from "node:child_process";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import * as os from "node:os";
-
-export type DockerRunResult = {
-  exitCode: number;
-  stdout: string;
-  stderr: string;
-};
-
-export class DockerRunner {
-  private containerName = "web-ext-tla-verify";
-
-  /**
-   * Check if Docker is available
-   */
-  async isDockerAvailable(): Promise<boolean> {
-    try {
-      const result = await this.runCommand("docker", ["--version"]);
-      return result.exitCode === 0;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Check if TLA+ image exists
-   */
-  async hasImage(): Promise<boolean> {
-    try {
-      const result = await this.runCommand("docker", ["images", "-q", "talex5/tla"]);
-      return result.stdout.trim().length > 0;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Pull TLA+ image
-   */
-  async pullImage(onProgress?: (line: string) => void): Promise<void> {
-    await this.runCommandStreaming("docker", ["pull", "talex5/tla:latest"], onProgress);
-  }
-
-  /**
-   * Run TLC model checker on a spec
-   */
-  async runTLC(
-    specPath: string,
-    options?: {
-      workers?: number;
-      timeout?: number;
-    }
-  ): Promise<TLCResult> {
-    // Ensure spec file exists
-    if (!fs.existsSync(specPath)) {
-      throw new Error(`Spec file not found: ${specPath}`);
-    }
-
-    const specDir = path.dirname(specPath);
-    const specName = path.basename(specPath, ".tla");
-    const cfgPath = path.join(specDir, `${specName}.cfg`);
-
-    // Ensure cfg file exists
-    if (!fs.existsSync(cfgPath)) {
-      throw new Error(`Config file not found: ${cfgPath}`);
-    }
-
-    // Run TLC in Docker
-    // Use sh -c to cd into /specs directory so TLC can find imported modules
-    const args = [
-      "run",
-      "--rm",
-      "-v",
-      `${specDir}:/specs`,
-      "talex5/tla",
-      "sh",
-      "-c",
-      `cd /specs && tlc -workers ${options?.workers || 1} ${specName}.tla`,
-    ];
-
-    const result = await this.runCommand("docker", args, {
-      timeout: options?.timeout || 60000,
-    });
-
-    return this.parseTLCOutput(result);
-  }
-
-  /**
-   * Parse TLC output
-   */
-  private parseTLCOutput(result: DockerRunResult): TLCResult {
-    const output = result.stdout + result.stderr;
-
-    // Check for violations
-    const violationMatch = output.match(/Error: Invariant (.*?) is violated/);
-    if (violationMatch) {
-      return {
-        success: false,
-        violation: {
-          type: "invariant",
-          name: violationMatch[1],
-          trace: this.extractTrace(output),
-        },
-        output,
-      };
-    }
-
-    // Check for errors
-    if (result.exitCode !== 0 || output.includes("Error:")) {
-      return {
-        success: false,
-        error: this.extractError(output),
-        output,
-      };
-    }
-
-    // Success
-    const statesMatch = output.match(/(\d+) states generated/);
-    const distinctMatch = output.match(/(\d+) distinct states/);
-
-    return {
-      success: true,
-      stats: {
-        statesGenerated: statesMatch ? Number.parseInt(statesMatch[1]) : 0,
-        distinctStates: distinctMatch ? Number.parseInt(distinctMatch[1]) : 0,
-      },
-      output,
-    };
-  }
-
-  /**
-   * Extract error trace from TLC output
-   */
-  private extractTrace(output: string): string[] {
-    const lines = output.split("\n");
-    const trace: string[] = [];
-    let inTrace = false;
-
-    for (const line of lines) {
-      if (line.includes("State ") && line.includes(":")) {
-        inTrace = true;
-        trace.push(line);
-      } else if (inTrace) {
-        if (line.trim() === "" || line.startsWith("Error:")) {
-          break;
-        }
-        trace.push(line);
-      }
-    }
-
-    return trace;
-  }
-
-  /**
-   * Extract error message from TLC output
-   */
-  private extractError(output: string): string {
-    const errorMatch = output.match(/Error: (.*?)(?:\n|$)/);
-    if (errorMatch) {
-      return errorMatch[1];
-    }
-
-    // Look for common error patterns
-    if (output.includes("Parse Error")) {
-      return "TLA+ syntax error in specification";
-    }
-    if (output.includes("Semantic Error")) {
-      return "Semantic error in specification";
-    }
-
-    return "Unknown error occurred during model checking";
-  }
-
-  /**
-   * Run a command and return output
-   */
-  private runCommand(
-    command: string,
-    args: string[],
-    options?: { timeout?: number }
-  ): Promise<DockerRunResult> {
-    return new Promise((resolve, reject) => {
-      const proc = spawn(command, args);
-
-      let stdout = "";
-      let stderr = "";
-
-      proc.stdout.on("data", (data) => {
-        stdout += data.toString();
-      });
-
-      proc.stderr.on("data", (data) => {
-        stderr += data.toString();
-      });
-
-      const timeout = options?.timeout
-        ? setTimeout(() => {
-            proc.kill();
-            reject(new Error(`Command timed out after ${options.timeout}ms`));
-          }, options.timeout)
-        : null;
-
-      proc.on("close", (exitCode) => {
-        if (timeout) clearTimeout(timeout);
-
-        resolve({
-          exitCode: exitCode || 0,
-          stdout,
-          stderr,
-        });
-      });
-
-      proc.on("error", (error) => {
-        if (timeout) clearTimeout(timeout);
-        reject(error);
-      });
-    });
-  }
-
-  /**
-   * Run a command with streaming output
-   */
-  private runCommandStreaming(
-    command: string,
-    args: string[],
-    onOutput?: (line: string) => void
-  ): Promise<void> {
-    return new Promise((resolve, reject) => {
-      const proc = spawn(command, args);
-
-      proc.stdout.on("data", (data) => {
-        if (onOutput) {
-          const lines = data.toString().split("\n");
-          for (const line of lines) {
-            if (line.trim()) {
-              onOutput(line.trim());
-            }
-          }
-        }
-      });
-
-      proc.stderr.on("data", (data) => {
-        if (onOutput) {
-          const lines = data.toString().split("\n");
-          for (const line of lines) {
-            if (line.trim()) {
-              onOutput(line.trim());
-            }
-          }
-        }
-      });
-
-      proc.on("close", (exitCode) => {
-        if (exitCode === 0) {
-          resolve();
-        } else {
-          reject(new Error(`Command failed with exit code ${exitCode}`));
-        }
-      });
-
-      proc.on("error", reject);
-    });
-  }
-}
-
-export type TLCResult = {
-  success: boolean;
-  violation?: {
-    type: "invariant" | "property" | "deadlock";
-    name?: string;
-    trace: string[];
-  };
-  error?: string;
-  stats?: {
-    statesGenerated: number;
-    distinctStates: number;
-  };
-  output: string;
-};

package/vendor/verify/src/types.ts

@@ -1,51 +0,0 @@
-// Core types for verification system
-
-// Re-export shared types from analysis package
-export type {
-  Context,
-  TypeKind,
-  TypeInfo,
-  FieldAnalysis,
-  Confidence,
-  MessageHandler,
-  StateAssignment,
-  VerificationCondition,
-  CodebaseAnalysis,
-} from "@fairfox/polly-analysis";
-
-export type VerificationConfig = {
-  preset?: "quick" | "balanced" | "thorough";
-  state: StateConfig;
-  messages: MessageConfig;
-  onBuild: "warn" | "error" | "off";
-  onRelease: "warn" | "error" | "off";
-};
-
-export type StateConfig = Record<string, FieldConfig>;
-
-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?: any }
-  | { abstract: boolean };
-
-export type MessageConfig = {
-  maxInFlight: number | null;
-  maxTabs: number | null;
-};
-
-export type ConfigIssue = {
-  type: "incomplete" | "null_placeholder" | "unrealistic_bound" | "invalid_value";
-  severity: "error" | "warning";
-  field?: string;
-  location?: { line: number; column: number };
-  message: string;
-  suggestion: string;
-};
-
-export type ValidationResult = {
-  valid: boolean;
-  issues: ConfigIssue[];
-};