feat: extract processor switch to polymorphic classes (Part 1)

- Create src/processors/processor-interfaces.ts with:
  - IProcessor interface for all processors
  - BaseProcessor abstract class with error handling
  - PreProcessor and PostProcessor base classes
  - ProcessorRegistry for managing processor instances

- Create src/processors/implementations/ directory with:
  - PreValidateProcessor: Basic pre-validation
  - CodexComplianceProcessor: Validates against codex rules
  - index.ts: Exports all implementations

- Demonstrates the new architecture pattern:
  - Each processor is a class implementing IProcessor
  - Registry pattern instead of switch statement
  - Lazy loading to avoid circular dependencies

Part 2 will migrate ProcessorManager to use the registry.
See docs/reflections/processor-rules-engine-architecture-analysis-2026-03-18.md

Author: htafolla

.opencode/state

@@ -1,9 +1,9 @@
 {
   "memory:baseline": {
-    "heapUsed": 11.31,
-    "heapTotal": 20.81,
-    "external": 1.87,
-    "rss": 58.72,
-    "timestamp": 1773836401737
+    "heapUsed": 11.91,
+    "heapTotal": 20.06,
+    "external": 1.88,
+    "rss": 57.22,
+    "timestamp": 1773840340380
   }
 }

performance-baselines.json

@@ -1,34 +1,34 @@
 {
   "bundle-size-analysis": {
     "testName": "bundle-size-analysis",
-    "averageDuration": 9.873930402777775,
-    "standardDeviation": 0.5583387367407121,
-    "sampleCount": 288,
-    "lastUpdated": 1773836398049,
+    "averageDuration": 9.869833605351168,
+    "standardDeviation": 0.5558387883847822,
+    "sampleCount": 299,
+    "lastUpdated": 1773840313382,
     "tolerance": 10
   },
   "module-import-performance": {
     "testName": "module-import-performance",
-    "averageDuration": 27.368656665226773,
-    "standardDeviation": 3.1741469569897465,
-    "sampleCount": 463,
-    "lastUpdated": 1773836398049,
+    "averageDuration": 27.37792217107942,
+    "standardDeviation": 3.17773022615393,
+    "sampleCount": 491,
+    "lastUpdated": 1773840313382,
     "tolerance": 10
   },
   "memory-usage-check": {
     "testName": "memory-usage-check",
-    "averageDuration": 0.09729197154471665,
-    "standardDeviation": 0.0053422199512606705,
-    "sampleCount": 246,
-    "lastUpdated": 1773836376650,
+    "averageDuration": 0.09729749609375082,
+    "standardDeviation": 0.005329687172289129,
+    "sampleCount": 256,
+    "lastUpdated": 1773840258938,
     "tolerance": 10
   },
   "test-execution-performance": {
     "testName": "test-execution-performance",
-    "averageDuration": 0.10799480595482683,
-    "standardDeviation": 0.02442426405449053,
-    "sampleCount": 974,
-    "lastUpdated": 1773836398049,
+    "averageDuration": 0.10766623720472562,
+    "standardDeviation": 0.023987105568075727,
+    "sampleCount": 1016,
+    "lastUpdated": 1773840336765,
     "tolerance": 10
   }
 }

src/processors/implementations/codex-compliance-processor.ts

@@ -0,0 +1,66 @@
+/**
+ * Codex Compliance Processor
+ *
+ * Validates code against the Universal Development Codex.
+ *
+ * @module processors/implementations
+ * @version 1.0.0
+ */
+
+import { PreProcessor } from "../processor-interfaces.js";
+import { frameworkLogger } from "../../core/framework-logger.js";
+
+export class CodexComplianceProcessor extends PreProcessor {
+  readonly name = "codexCompliance";
+  readonly priority = 20;
+
+  protected async run(context: unknown): Promise<unknown> {
+    const ctx = context as Record<string, unknown>;
+    
+    // Lazy load RuleEnforcer to avoid circular dependencies
+    const { RuleEnforcer } = await import("../../enforcement/rule-enforcer.js");
+    const ruleEnforcer = new RuleEnforcer();
+
+    const operation = (ctx.operation as string) || "modify";
+    const filePath = ctx.filePath as string | undefined;
+    const content = ctx.content as string | undefined;
+
+    await frameworkLogger.log(
+      "codex-compliance-processor",
+      "validating",
+      "info",
+      { operation, filePath: filePath?.slice(0, 100) },
+    );
+
+    // Build validation context
+    const validationContext: import("../../enforcement/types.js").RuleValidationContext = {
+      operation,
+    };
+    
+    if (filePath) {
+      validationContext.files = [filePath];
+    }
+    
+    if (content) {
+      validationContext.newCode = content;
+    }
+
+    // Validate against codex rules
+    const validationResult = await ruleEnforcer.validateOperation(
+      operation,
+      validationContext,
+    );
+
+    if (!validationResult.passed) {
+      const errors = validationResult.errors.join("; ");
+      throw new Error(`Codex compliance failed: ${errors}`);
+    }
+
+    return {
+      passed: true,
+      rulesChecked: validationResult.results.length,
+      errors: validationResult.errors.length,
+      warnings: validationResult.warnings.length,
+    };
+  }
+}

src/processors/implementations/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Processor Implementations Index
+ *
+ * Exports all processor implementations for registration.
+ *
+ * @module processors/implementations
+ * @version 1.0.0
+ */
+
+export { PreValidateProcessor } from "./pre-validate-processor.js";
+export { CodexComplianceProcessor } from "./codex-compliance-processor.js";

src/processors/implementations/pre-validate-processor.ts

@@ -0,0 +1,21 @@
+/**
+ * Pre-Validation Processor
+ *
+ * Validates input before processing begins.
+ *
+ * @module processors/implementations
+ * @version 1.0.0
+ */
+
+import { PreProcessor } from "../processor-interfaces.js";
+
+export class PreValidateProcessor extends PreProcessor {
+  readonly name = "preValidate";
+  readonly priority = 10;
+
+  protected async run(context: unknown): Promise<unknown> {
+    // Basic pre-validation logic
+    // This is intentionally lightweight - just validation setup
+    return { validated: true, timestamp: Date.now() };
+  }
+}

src/processors/processor-interfaces.ts

@@ -0,0 +1,204 @@
+/**
+ * Processor Interface and Base Classes
+ *
+ * Defines the contract for all processors in the StringRay framework.
+ * Replaces the switch statement anti-pattern in ProcessorManager with
+ * polymorphic processor classes.
+ *
+ * @module processors/interfaces
+ * @version 1.0.0
+ */
+
+import { ProcessorResult } from "./processor-manager.js";
+
+/**
+ * Processor execution context
+ */
+export interface ProcessorContext {
+  /** Tool input (for pre-processors) */
+  toolInput?: {
+    tool?: string;
+    args?: {
+      filePath?: string;
+      content?: string;
+      [key: string]: unknown;
+    };
+  };
+  /** File path being processed */
+  filePath?: string;
+  /** Operation being performed */
+  operation?: string;
+  /** Content being processed */
+  content?: string;
+  /** Additional context */
+  [key: string]: unknown;
+}
+
+/**
+ * Processor interface - all processors must implement this
+ */
+export interface IProcessor {
+  /** Unique processor identifier */
+  readonly name: string;
+
+  /** Processor type: pre or post */
+  readonly type: "pre" | "post";
+
+  /** Execution priority (lower = earlier) */
+  readonly priority: number;
+
+  /** Whether processor is enabled */
+  enabled: boolean;
+
+  /**
+   * Execute the processor
+   * @param context Processor execution context
+   * @returns Processor result
+   */
+  execute(context: ProcessorContext): Promise<ProcessorResult>;
+}
+
+/**
+ * Base processor class with common functionality
+ */
+export abstract class BaseProcessor implements IProcessor {
+  abstract readonly name: string;
+  abstract readonly type: "pre" | "post";
+  abstract readonly priority: number;
+  enabled = true;
+
+  /**
+   * Execute the processor with error handling and metrics
+   * @param context Processor execution context
+   * @returns Processor result
+   */
+  async execute(context: ProcessorContext): Promise<ProcessorResult> {
+    const startTime = Date.now();
+
+    try {
+      const data = await this.run(context);
+      const duration = Date.now() - startTime;
+
+      return {
+        success: true,
+        data,
+        duration,
+        processorName: this.name,
+      };
+    } catch (error) {
+      const duration = Date.now() - startTime;
+
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+        duration,
+        processorName: this.name,
+      };
+    }
+  }
+
+  /**
+   * Override this method in subclasses to implement processor logic
+   * @param context Processor execution context
+   * @returns Processor data
+   */
+  protected abstract run(context: ProcessorContext): Promise<unknown>;
+
+  /**
+   * Safely extract file path from context
+   */
+  protected getFilePath(context: ProcessorContext): string | undefined {
+    return context.toolInput?.args?.filePath || context.filePath;
+  }
+
+  /**
+   * Safely extract content from context
+   */
+  protected getContent(context: ProcessorContext): string | undefined {
+    return context.toolInput?.args?.content;
+  }
+}
+
+/**
+ * Pre-processor base class
+ */
+export abstract class PreProcessor extends BaseProcessor {
+  readonly type = "pre" as const;
+}
+
+/**
+ * Post-processor base class
+ */
+export abstract class PostProcessor extends BaseProcessor {
+  readonly type = "post" as const;
+}
+
+/**
+ * Processor registry for managing processor instances
+ */
+export class ProcessorRegistry {
+  private processors = new Map<string, IProcessor>();
+
+  /**
+   * Register a processor
+   * @param processor Processor instance
+   */
+  register(processor: IProcessor): void {
+    this.processors.set(processor.name, processor);
+  }
+
+  /**
+   * Unregister a processor
+   * @param name Processor name
+   */
+  unregister(name: string): void {
+    this.processors.delete(name);
+  }
+
+  /**
+   * Get a processor by name
+   * @param name Processor name
+   * @returns Processor instance or undefined
+   */
+  get(name: string): IProcessor | undefined {
+    return this.processors.get(name);
+  }
+
+  /**
+   * Get all registered processors
+   * @returns Array of processors
+   */
+  getAll(): IProcessor[] {
+    return Array.from(this.processors.values());
+  }
+
+  /**
+   * Get processors by type
+   * @param type Processor type
+   * @returns Array of processors
+   */
+  getByType(type: "pre" | "post"): IProcessor[] {
+    return this.getAll()
+      .filter((p) => p.type === type)
+      .sort((a, b) => a.priority - b.priority);
+  }
+
+  /**
+   * Check if processor exists
+   * @param name Processor name
+   * @returns True if processor exists
+   */
+  has(name: string): boolean {
+    return this.processors.has(name);
+  }
+
+  /**
+   * Clear all processors
+   */
+  clear(): void {
+    this.processors.clear();
+  }
+}
+
+// Singleton registry instance
+export const processorRegistry = new ProcessorRegistry();