0xray 3.4.1 → 3.4.3

package/dist/processors/implementations/nudge-processor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Nudge Processor - Integrates Nudge Watchdog with processor system
+ *
+ * Post-processor that monitors agent actions and triggers nudges
+ * when stuck patterns are detected.
+ *
+ * @module processors/implementations
+ */
+import { PostProcessor } from "../processor-interfaces.js";
+import { ProcessorContext, ProcessorResult } from "../processor-types.js";
+export declare class NudgeProcessor extends PostProcessor {
+    readonly name = "nudge";
+    readonly priority = 100;
+    private nudgeEnabled;
+    constructor();
+    private loadConfig;
+    protected run(context: ProcessorContext): Promise<unknown>;
+    private detectMostUrgentNudge;
+}
+export declare const nudgeProcessor: NudgeProcessor;
+export declare function executeNudgeProcessor(context: ProcessorContext): Promise<ProcessorResult>;

package/dist/processors/implementations/performance-budget-processor.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Performance Budget Processor
+ *
+ * Enforces codex term #28: Performance Budgets.
+ * Checks code content against configurable size, function-length, nesting-depth,
+ * and parameter-count budgets. Returns structured violation lists.
+ *
+ * @since 2026-03-28
+ */
+import type { PreValidateContext, ProcessorExecutionResult } from "../processor-types.js";
+export type PerformanceViolationType = "fileTooLarge" | "functionTooLong" | "nestingTooDeep" | "tooManyParameters";
+export interface PerformanceViolation {
+    type: PerformanceViolationType;
+    filePath: string;
+    line?: number;
+    message: string;
+    actual: number;
+    limit: number;
+}
+export interface PerformanceBudgetConfig {
+    maxFileSizeBytes: number;
+    maxFunctionLines: number;
+    maxNestingDepth: number;
+    maxParameters: number;
+}
+export declare const DEFAULT_PERFORMANCE_BUDGET: PerformanceBudgetConfig;
+export declare class PerformanceBudgetProcessor {
+    private readonly config;
+    constructor(config?: Partial<PerformanceBudgetConfig>);
+    /**
+     * Check a file against all budget rules.
+     */
+    checkFile(filePath: string, content: string): PerformanceViolation[];
+    /**
+     * Analyse every function body in `content` and check complexity budgets.
+     */
+    checkFunctionComplexity(content: string): PerformanceViolation[];
+    /**
+     * Regex-based extraction of named functions / methods / arrow functions.
+     * Does NOT require a full AST – keeps the processor zero-dependency.
+     */
+    private extractFunctions;
+    /**
+     * Measure the maximum nesting depth by tracking control-flow keywords
+     * (if / for / while / switch / try) inside the function body.
+     */
+    private measureMaxNesting;
+}
+export declare function runPerformanceBudgetCheck(context: PreValidateContext): Promise<ProcessorExecutionResult>;

package/dist/processors/implementations/postprocessor-chain-validator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * PostProcessor Chain Validator
+ *
+ * Validates postprocessor execution chain integrity.
+ * Checks that all registered postprocessors executed without errors,
+ * validates priority ordering, and detects skipped or crashed processors.
+ *
+ * @since 2026-03-28
+ */
+import type { PostValidateContext, ProcessorExecutionResult } from "../processor-types.js";
+export interface ChainValidationResult {
+    valid: boolean;
+    issues: ChainIssue[];
+}
+export interface ChainIssue {
+    severity: "error" | "warning";
+    processorName: string;
+    message: string;
+}
+export interface ChainReport {
+    totalProcessors: number;
+    successful: number;
+    failed: number;
+    skipped: number;
+    issues: ChainIssue[];
+    averageDuration: number;
+    executedInPriorityOrder: boolean;
+}
+export declare class PostProcessorChainValidator {
+    private chainReport;
+    /**
+     * Validate the postprocessor execution chain.
+     */
+    validateChain(results: Array<{
+        name: string;
+        success: boolean;
+        duration: number;
+        priority?: number;
+    }>): ChainValidationResult;
+    /**
+     * Get the chain report from the most recent validation.
+     */
+    getChainReport(): ChainReport;
+}
+export declare function runPostProcessorChainValidation(context: PostValidateContext): Promise<ProcessorExecutionResult>;

package/dist/processors/implementations/pre-validate-processor.d.ts

@@ -0,0 +1,7 @@
+import { PreProcessor } from "../processor-interfaces.js";
+import type { ProcessorContext } from "../processor-types.js";
+export declare class PreValidateProcessor extends PreProcessor {
+    readonly name = "preValidate";
+    readonly priority = 1;
+    protected run(context: ProcessorContext): Promise<Record<string, unknown>>;
+}

package/dist/processors/implementations/publish-preflight-processor.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Publish Preflight Processor
+ *
+ * Post-processor that validates documentation completeness before publishing.
+ * Ensures README.md, AGENTS.md, and reflection documents are up-to-date
+ * before allowing npm publish.
+ *
+ * Configuration is read from .xray/features.json
+ *
+ * @processor_type post
+ * @priority 10 (runs early after post-processing starts)
+ * @blocking true (blocks publish on violations)
+ *
+ * @framework 0xRay 1.15.41
+ */
+import { PostProcessor } from "../processor-interfaces.js";
+import { ProcessorContext, ProcessorResult } from "../processor-types.js";
+export interface PreflightResult {
+    compliant: boolean;
+    checks: PreflightCheck[];
+    summary: string;
+}
+export interface PreflightCheck {
+    name: string;
+    passed: boolean;
+    message: string;
+    required: boolean;
+}
+export declare class PublishPreflightProcessor extends PostProcessor {
+    readonly name = "publishPreflight";
+    readonly priority = 10;
+    private config;
+    constructor();
+    private loadConfig;
+    protected run(context: ProcessorContext): Promise<unknown>;
+    execute(context: ProcessorContext): Promise<ProcessorResult>;
+}

package/dist/processors/implementations/refactoring-logging-processor-wrapper.d.ts

@@ -0,0 +1,7 @@
+import { PreProcessor } from "../processor-interfaces.js";
+import type { ProcessorContext } from "../processor-types.js";
+export declare class RefactoringLoggingProcessorWrapper extends PreProcessor {
+    readonly name = "refactoringLogging";
+    readonly priority = 8;
+    protected run(context: ProcessorContext): Promise<Record<string, unknown>>;
+}

package/dist/processors/implementations/refactoring-logging-processor.d.ts

@@ -0,0 +1,31 @@
+export interface RefactoringContext {
+    agentName: string;
+    task: {
+        id?: string;
+        description?: string;
+        operationType?: string;
+    };
+    startTime: number;
+    complexityScore?: number;
+    changes?: Array<{
+        description?: string;
+        type?: string;
+    }>;
+    files?: string[];
+    metrics?: Record<string, unknown>;
+    operationType?: string;
+}
+export interface RefactoringLogResult {
+    logged: boolean;
+    success: boolean;
+    message: string;
+    error?: string;
+}
+export declare class RefactoringLoggingProcessor {
+    private logPath;
+    constructor();
+    private ensureLogDirectory;
+    execute(context: RefactoringContext): Promise<RefactoringLogResult>;
+    private createLogEntry;
+    private appendToLog;
+}

package/dist/processors/implementations/regression-testing-processor.d.ts

@@ -0,0 +1,20 @@
+import { PostProcessor } from "../processor-interfaces.js";
+import type { ProcessorContext } from "../processor-types.js";
+interface RegressionResult {
+    regressions: number;
+    issues: RegressionIssue[];
+    baseline: string | null;
+    current: string | null;
+}
+interface RegressionIssue {
+    type: "new_failure" | "coverage_drop" | "performance_degradation";
+    description: string;
+    file?: string;
+}
+export declare class RegressionTestingProcessor extends PostProcessor {
+    readonly name = "regressionTesting";
+    readonly priority = 15;
+    protected run(context: ProcessorContext): Promise<RegressionResult>;
+    private getCurrentTestCount;
+}
+export {};

package/dist/processors/implementations/session-capture-processor.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Session Capture Processor
+ *
+ * Extracted from InferenceImprovementProcessor - handles discovery of
+ * session data sources (reflections, logs, reports) for inference workflows.
+ *
+ * @module processors/implementations
+ */
+export declare class SessionCapture {
+    static findReflections(directory: string, reflectionsDir: string): string[];
+    static findLogs(directory: string, logsDir: string): string[];
+    static findReports(directory: string, reportsDir: string): string[];
+}
+export default SessionCapture;

package/dist/processors/implementations/session-summary-processor.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Session Summary Post-Processor
+ *
+ * Generates emoji-formatted session summaries after tool execution.
+ * Uses features.json -> auto_reporting config for control.
+ *
+ * @since 2026-04-04
+ */
+import { PostProcessor, ProcessorContext } from "../processor-interfaces.js";
+export declare class SessionSummaryProcessor extends PostProcessor {
+    readonly name = "sessionSummary";
+    readonly priority = 15;
+    private config;
+    private sessionStartTime;
+    private agentActivities;
+    private toolCalls;
+    private operations;
+    constructor();
+    private loadConfig;
+    run(context: ProcessorContext): Promise<unknown>;
+    private shouldGenerateSummary;
+    private generateEmojiSummary;
+    private generateRecommendation;
+    private stripEmojis;
+}
+export default SessionSummaryProcessor;

package/dist/processors/implementations/spawn-governance-processor.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Spawn Governance Processor
+ *
+ * Enforces codex terms #52-57:
+ *  - #52 Agent Spawn Governance
+ *  - #53 Subagent Spawning Prevention
+ *  - #54 Concurrent Agent Limits
+ *  - #55 Emergency Memory Cleanup
+ *  - #56 Infinite Spawn Pattern Detection
+ *  - #57 Spawn Rate Limiting
+ *
+ * @since 2026-03-28
+ */
+export interface SpawnGovernanceConfig {
+    maxConcurrent: number;
+    rateLimitWindowMs: number;
+    maxSpawnsPerWindow: number;
+    memoryThreshold: number;
+    infiniteSpawnThreshold: number;
+    infiniteSpawnWindowMs: number;
+}
+export declare class SpawnGovernanceProcessor {
+    static readonly DEFAULT_MAX_CONCURRENT = 5;
+    static readonly DEFAULT_RATE_LIMIT_WINDOW_MS = 10000;
+    static readonly DEFAULT_MAX_SPAWNS_PER_WINDOW = 10;
+    static readonly DEFAULT_MEMORY_THRESHOLD = 0.8;
+    private readonly config;
+    private activeSpawns;
+    private spawnTimestamps;
+    private agentSpawnTimestamps;
+    private blockedCount;
+    private subagentDepth;
+    constructor(config?: Partial<SpawnGovernanceConfig>);
+    checkSpawnAllowed(agentName: string): {
+        allowed: boolean;
+        reason?: string;
+    };
+    recordSpawn(agentName: string): void;
+    recordSpawnComplete(agentName: string): void;
+    getMetrics(): {
+        activeSpawns: number;
+        recentSpawns: number;
+        blockedSpawns: number;
+        memoryUsage: number;
+    };
+    emergencyCleanup(): void;
+    setSubagentDepth(agentName: string, depth: number): void;
+    private purgeOldTimestamps;
+    private getMemoryUsageRatio;
+}
+export declare function resetGovernanceProcessor(): void;
+export declare function runSpawnGovernance(context: any): Promise<{
+    success: boolean;
+    allowed: boolean;
+    reason?: string;
+    metrics: ReturnType<SpawnGovernanceProcessor["getMetrics"]>;
+}>;

package/dist/processors/implementations/state-validation-processor.d.ts

@@ -0,0 +1,11 @@
+import { PostProcessor } from "../processor-interfaces.js";
+import type { ProcessorContext } from "../processor-types.js";
+import type { ProcessorDependency } from "../processor-interfaces.js";
+export declare class StateValidationProcessor extends PostProcessor {
+    readonly name = "stateValidation";
+    readonly priority = 12;
+    static readonly dependencies: ProcessorDependency[];
+    private stateManager;
+    constructor(stateManager?: any);
+    protected run(_context: ProcessorContext): Promise<Record<string, boolean>>;
+}

package/dist/processors/implementations/storytelling-trigger-processor.d.ts

@@ -0,0 +1,40 @@
+import { PostProcessor } from "../processor-interfaces.js";
+import { ProcessorContext } from "../processor-types.js";
+export declare class StorytellingTriggerProcessor extends PostProcessor {
+    readonly name = "storytelling-trigger";
+    readonly priority = 5;
+    private config;
+    private reflectionsDir;
+    private deepReflectionsDir;
+    constructor();
+    protected run(context: ProcessorContext): Promise<unknown>;
+    private runInferenceCycle;
+    private reflectOnCommits;
+    private reflectOnRelease;
+    private synthesizeReflection;
+    private detectPatterns;
+    private detectSemanticPatterns;
+    private extractDecisions;
+    private synthesizeInferences;
+    private getCommitsBetween;
+    private getRecentCommits;
+    private summarizeCommits;
+    private getLastTag;
+    private getFileCommitHash;
+    private getMostRecentReflectionFile;
+    private git;
+    static suggestStoryType(context: {
+        commitCount?: number;
+        fileCount?: number;
+        sessionDuration?: number;
+        isPublishing?: boolean;
+    }): "reflection" | "saga" | "journey" | "narrative";
+    static getStoryTypeMeta(storyType: string): {
+        location: string;
+        minWords: number;
+        idealWords: number;
+        framework: string;
+        template: string;
+    };
+}
+export default StorytellingTriggerProcessor;

package/dist/processors/implementations/test-auto-creation-processor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Test Auto-Creation Processor
+ *
+ * Automatically generates test files when new source files are created.
+ * Supports multiple languages: TypeScript, JavaScript, Python, Go, Rust, Java, C#
+ * Uses direct skill calls (no MCP overhead) for instant test generation.
+ *
+ * @since 2026-02-15
+ */
+export declare const testAutoCreationProcessor: {
+    name: string;
+    priority: number;
+    enabled: boolean;
+    execute(context: any): Promise<any>;
+};
+export default testAutoCreationProcessor;

package/dist/processors/implementations/test-execution-processor.d.ts

@@ -0,0 +1,11 @@
+import { PreProcessor } from "../processor-interfaces.js";
+import type { ProcessorContext } from "../processor-types.js";
+export declare class TestExecutionProcessor extends PreProcessor {
+    readonly name = "testExecution";
+    readonly priority = 10;
+    protected run(context: ProcessorContext): Promise<Record<string, unknown>>;
+    private executeTypeScriptTests;
+    private executeGenericTests;
+    private runTestCommand;
+    private parseTestOutput;
+}

package/dist/processors/implementations/typescript-compilation-processor.d.ts

@@ -0,0 +1,37 @@
+/**
+ * TypeScript Compilation Processor
+ *
+ * Runs `tsc --noEmit` to catch type errors before writes land.
+ * Parses TypeScript error lines from stderr and returns structured results.
+ * Gracefully skips when no tsconfig.json exists.
+ *
+ * @since 2026-03-28
+ */
+export interface TypeScriptCompilationResult {
+    success: boolean;
+    errors: string[];
+    duration: number;
+    fileCount: number;
+    errorCount?: number;
+    skipped?: boolean;
+    reason?: string;
+}
+/**
+ * Parse TypeScript error lines from stderr output.
+ * Filters for lines containing "error TS" which is the standard TypeScript error format.
+ */
+export declare function parseTypeScriptErrors(stderr: string): string[];
+/**
+ * Run TypeScript compilation check (tsc --noEmit).
+ *
+ * @param cwd - Working directory for the command (defaults to process.cwd())
+ * @param timeout - Maximum execution time in milliseconds (default 30000)
+ * @returns Structured result with success status, errors, and timing
+ */
+export declare function runTypeScriptCompilation(cwd?: string, timeout?: number): TypeScriptCompilationResult;
+export declare const typescriptCompilationProcessor: {
+    name: string;
+    priority: number;
+    enabled: boolean;
+    execute(context: Record<string, unknown>): Promise<TypeScriptCompilationResult>;
+};

package/dist/processors/implementations/version-compliance-processor.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Version Compliance Processor
+ *
+ * Pre-processor that enforces version compliance rules before allowing
+ * commits or publishes. Integrates with 0xRay's processor pipeline.
+ *
+ * Rules Enforced:
+ * 1. Universal Version Manager MUST be 1 ahead of NPM published version
+ * 2. package.json SHOULD match UVM (warning if not)
+ * 3. Source files MUST be synchronized to UVM version
+ * 4. README SHOULD reference current version
+ *
+ * @processor_type pre
+ * @priority 25 (high - runs early, after preValidate, before errorBoundary)
+ * @blocking true (blocks on violations)
+ *
+ * @framework 0xRay 1.3.5
+ */
+export interface VersionComplianceResult {
+    compliant: boolean;
+    npmVersion: string;
+    uvmVersion: string;
+    pkgVersion: string;
+    errors: string[];
+    warnings: string[];
+    fixes?: VersionFix[];
+}
+export interface VersionFix {
+    type: "update-uvm" | "sync-source" | "update-readme";
+    description: string;
+    command: string;
+    autoFixable: boolean;
+}
+export interface VersionInfo {
+    major: number;
+    minor: number;
+    patch: number;
+    raw: string;
+}
+export declare class VersionComplianceProcessor {
+    private projectRoot;
+    private errors;
+    private warnings;
+    private fixes;
+    constructor(projectRoot?: string);
+    /**
+     * Main execution method - called by ProcessorManager
+     */
+    execute(context: {
+        tool: string;
+        args?: {
+            filePath?: string;
+            content?: string;
+        };
+        operation: string;
+    }): Promise<{
+        success: boolean;
+        blocked: boolean;
+        message: string;
+        result?: VersionComplianceResult;
+    }>;
+    /**
+     * Validate all version compliance rules
+     */
+    validateVersionCompliance(): Promise<VersionComplianceResult>;
+    /**
+     * Get NPM published version
+     */
+    private getNpmVersion;
+    /**
+     * Get Universal Version Manager version
+     */
+    private getUvmVersion;
+    /**
+     * Get package.json version
+     */
+    private getPackageVersion;
+    /**
+     * Get version from source files
+     */
+    private getSourceVersion;
+    /**
+     * Get version from README
+     */
+    private getReadmeVersion;
+    /**
+     * Parse version string into components
+     */
+    private parseVersion;
+    /**
+     * Format version components back to string
+     */
+    private formatVersion;
+    /**
+     * Increment patch version
+     */
+    private incrementPatch;
+    /**
+     * Auto-fix version compliance issues
+     */
+    autoFix(): Promise<{
+        success: boolean;
+        fixed: string[];
+        failed: string[];
+    }>;
+    /**
+     * Generate compliance report
+     */
+    generateReport(result: VersionComplianceResult): string;
+}
+export declare const versionComplianceProcessor: VersionComplianceProcessor;

package/dist/processors/processor-interfaces.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Processor Interface and Base Classes
+ *
+ * Defines the contract for all processors in the 0xRay framework.
+ * Replaces the switch statement anti-pattern in ProcessorManager with
+ * polymorphic processor classes.
+ *
+ * @module processors/interfaces
+ */
+import { ProcessorContext, ProcessorResult, LogProtectionProcessorResult, TestExecutionResult, CodexComplianceProcessorResult, VersionComplianceProcessorResult, TestAutoCreationResult, CoverageAnalysisResult } from "./processor-types.js";
+/**
+ * Union of all known processor result types for type safety
+ */
+export type ProcessorResultData = LogProtectionProcessorResult | TestExecutionResult | CodexComplianceProcessorResult | VersionComplianceProcessorResult | TestAutoCreationResult | CoverageAnalysisResult;
+/**
+ * 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 type ProcessorDependency = "stateManager" | "config" | "logger";
+export interface ProcessorDependencies {
+    stateManager?: unknown;
+    config?: unknown;
+    logger?: unknown;
+}
+export declare abstract class BaseProcessor implements IProcessor {
+    abstract readonly name: string;
+    abstract readonly type: "pre" | "post";
+    abstract readonly priority: number;
+    enabled: boolean;
+    static readonly dependencies?: ProcessorDependency[];
+    /**
+     * Execute the processor with error handling and metrics
+     * @param context Processor execution context
+     * @returns Processor result
+     */
+    execute(context: ProcessorContext): Promise<ProcessorResult>;
+    /**
+     * 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;
+    /**
+     * Safely extract content from context
+     */
+    protected getContent(context: ProcessorContext): string | undefined;
+}
+/**
+ * Pre-processor base class
+ */
+export declare abstract class PreProcessor extends BaseProcessor {
+    readonly type: "pre";
+}
+/**
+ * Post-processor base class
+ */
+export declare abstract class PostProcessor extends BaseProcessor {
+    readonly type: "post";
+}
+/**
+ * Processor registry for managing processor instances
+ */
+export declare class ProcessorRegistry {
+    private processors;
+    /**
+     * Register a processor
+     * @param processor Processor instance
+     */
+    register(processor: IProcessor): void;
+    /**
+     * Unregister a processor
+     * @param name Processor name
+     */
+    unregister(name: string): void;
+    /**
+     * Get a processor by name
+     * @param name Processor name
+     * @returns Processor instance or undefined
+     */
+    get(name: string): IProcessor | undefined;
+    /**
+     * Get all registered processors
+     * @returns Array of processors
+     */
+    getAll(): IProcessor[];
+    /**
+     * Get processors by type
+     * @param type Processor type
+     * @returns Array of processors
+     */
+    getByType(type: "pre" | "post"): IProcessor[];
+    /**
+     * Check if processor exists
+     * @param name Processor name
+     * @returns True if processor exists
+     */
+    has(name: string): boolean;
+    /**
+     * Clear all processors
+     */
+    clear(): void;
+}
+export type { ProcessorContext, ProcessorResult } from "./processor-types.js";
+export declare const processorRegistry: ProcessorRegistry;