0xray 2.0.0

package/dist/processors/implementations/performance-budget-processor.js

@@ -0,0 +1,217 @@
+/**
+ * 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.
+ *
+ * @version 1.0.0
+ * @since 2026-03-28
+ */
+import { frameworkLogger } from "../../core/framework-logger.js";
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+export const DEFAULT_PERFORMANCE_BUDGET = {
+    maxFileSizeBytes: 10 * 1024, // 10 KB
+    maxFunctionLines: 50,
+    maxNestingDepth: 5,
+    maxParameters: 5,
+};
+// ---------------------------------------------------------------------------
+// Processor
+// ---------------------------------------------------------------------------
+export class PerformanceBudgetProcessor {
+    config;
+    constructor(config) {
+        this.config = { ...DEFAULT_PERFORMANCE_BUDGET, ...config };
+    }
+    /**
+     * Check a file against all budget rules.
+     */
+    checkFile(filePath, content) {
+        const violations = [];
+        // --- file size ---
+        const byteSize = Buffer.byteLength(content, "utf-8");
+        if (byteSize > this.config.maxFileSizeBytes) {
+            violations.push({
+                type: "fileTooLarge",
+                filePath,
+                message: `File size ${byteSize} bytes exceeds budget of ${this.config.maxFileSizeBytes} bytes`,
+                actual: byteSize,
+                limit: this.config.maxFileSizeBytes,
+            });
+        }
+        // --- function-level checks ---
+        const funcViolations = this.checkFunctionComplexity(content);
+        for (const v of funcViolations) {
+            violations.push({ ...v, filePath });
+        }
+        return violations;
+    }
+    /**
+     * Analyse every function body in `content` and check complexity budgets.
+     */
+    checkFunctionComplexity(content) {
+        const violations = [];
+        const functions = this.extractFunctions(content);
+        for (const fn of functions) {
+            // function length
+            if (fn.bodyLineCount > this.config.maxFunctionLines) {
+                violations.push({
+                    type: "functionTooLong",
+                    filePath: "",
+                    line: fn.startLine,
+                    message: `Function "${fn.name}" has ${fn.bodyLineCount} lines (max ${this.config.maxFunctionLines})`,
+                    actual: fn.bodyLineCount,
+                    limit: this.config.maxFunctionLines,
+                });
+            }
+            // nesting depth
+            const depth = this.measureMaxNesting(fn.body);
+            if (depth > this.config.maxNestingDepth) {
+                violations.push({
+                    type: "nestingTooDeep",
+                    filePath: "",
+                    line: fn.startLine,
+                    message: `Function "${fn.name}" has nesting depth ${depth} (max ${this.config.maxNestingDepth})`,
+                    actual: depth,
+                    limit: this.config.maxNestingDepth,
+                });
+            }
+            // parameter count
+            if (fn.paramCount > this.config.maxParameters) {
+                violations.push({
+                    type: "tooManyParameters",
+                    filePath: "",
+                    line: fn.startLine,
+                    message: `Function "${fn.name}" has ${fn.paramCount} parameters (max ${this.config.maxParameters})`,
+                    actual: fn.paramCount,
+                    limit: this.config.maxParameters,
+                });
+            }
+        }
+        return violations;
+    }
+    // -----------------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Regex-based extraction of named functions / methods / arrow functions.
+     * Does NOT require a full AST – keeps the processor zero-dependency.
+     */
+    extractFunctions(content) {
+        const results = [];
+        const lines = content.split("\n");
+        // Alternative 1: function name(params) {  →  groups: [name, params]
+        // Alternative 2: const/let/var name = ... =>  →  groups: [name, empty]
+        // Alternative 3: methodName(params) {  →  groups: [name, params]
+        const funcRegex = /(?:(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?(?:\([^)]*\)|[^=])\s*=>|(?:async\s+)?(\w+)\s*\(([^)]*)\)\s*\{)/g;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (!line)
+                continue;
+            // Skip comments
+            if (line.trimStart().startsWith("//") || line.trimStart().startsWith("*")) {
+                continue;
+            }
+            funcRegex.lastIndex = 0;
+            const match = funcRegex.exec(line);
+            if (!match)
+                continue;
+            const name = match[1] ?? match[3] ?? match[5] ?? "anonymous";
+            const params = match[2] ?? match[6];
+            const paramCount = params
+                ? params.split(",").filter((p) => p.trim().length > 0).length
+                : 0;
+            // Collect body lines until brace depth returns to 0
+            let depth = 0;
+            let started = false;
+            const bodyLines = [];
+            for (let j = i; j < lines.length; j++) {
+                const l = lines[j];
+                if (!l)
+                    continue;
+                for (const ch of l) {
+                    if (ch === "{") {
+                        depth++;
+                        started = true;
+                    }
+                    else if (ch === "}") {
+                        depth--;
+                    }
+                }
+                bodyLines.push(l);
+                if (started && depth <= 0)
+                    break;
+            }
+            const body = bodyLines.join("\n");
+            results.push({
+                name,
+                startLine: i + 1,
+                body,
+                bodyLineCount: bodyLines.length,
+                paramCount,
+            });
+        }
+        return results;
+    }
+    /**
+     * Measure the maximum nesting depth by tracking control-flow keywords
+     * (if / for / while / switch / try) inside the function body.
+     */
+    measureMaxNesting(body) {
+        let maxDepth = 0;
+        let currentDepth = 0;
+        const lines = body.split("\n");
+        for (const line of lines) {
+            const trimmed = line.trim();
+            // Count opening structures that increase nesting
+            const openingMatches = trimmed.match(/\b(if|for|while|switch|try|catch|else)\b/g);
+            if (openingMatches) {
+                // 'else' and 'catch' partially close+reopen, so net +0 for those
+                const netOpen = openingMatches.length -
+                    (trimmed.includes("else") ? 1 : 0) -
+                    (trimmed.includes("catch") ? 1 : 0);
+                currentDepth += Math.max(0, netOpen);
+                maxDepth = Math.max(maxDepth, currentDepth);
+            }
+            // Simple heuristic: decrease depth when line closes braces
+            const closeBraces = (trimmed.match(/}/g) || []).length;
+            currentDepth = Math.max(0, currentDepth - closeBraces);
+        }
+        return maxDepth;
+    }
+}
+// ---------------------------------------------------------------------------
+// Standalone runner for processor-manager integration
+// ---------------------------------------------------------------------------
+export async function runPerformanceBudgetCheck(context) {
+    const start = performance.now();
+    try {
+        const content = context.data ?? "";
+        const filePath = context.filesChanged?.[0] ?? "unknown";
+        const config = context.config ?? {};
+        const processor = new PerformanceBudgetProcessor(config);
+        const violations = processor.checkFile(filePath, content);
+        const hasViolations = violations.length > 0;
+        if (hasViolations) {
+            frameworkLogger.log("performance-budget-processor", "violations_found", "warning", { filePath, violations });
+        }
+        return {
+            success: !hasViolations,
+            processorName: "performance-budget-processor",
+            duration: performance.now() - start,
+            result: { violations },
+        };
+    }
+    catch (error) {
+        frameworkLogger.log("performance-budget-processor", "check_failed", "error", { error: error.message });
+        return {
+            success: false,
+            processorName: "performance-budget-processor",
+            duration: performance.now() - start,
+            error: error.message,
+        };
+    }
+}

package/dist/processors/implementations/postprocessor-chain-validator.js

@@ -0,0 +1,149 @@
+/**
+ * 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.
+ *
+ * @version 1.0.0
+ * @since 2026-03-28
+ */
+import { frameworkLogger } from "../../core/framework-logger.js";
+// ---------------------------------------------------------------------------
+// Processor
+// ---------------------------------------------------------------------------
+export class PostProcessorChainValidator {
+    chainReport = null;
+    /**
+     * Validate the postprocessor execution chain.
+     */
+    validateChain(results) {
+        const issues = [];
+        if (results.length === 0) {
+            const emptyReport = {
+                totalProcessors: 0,
+                successful: 0,
+                failed: 0,
+                skipped: 0,
+                issues: [],
+                averageDuration: 0,
+                executedInPriorityOrder: true,
+            };
+            this.chainReport = emptyReport;
+            return { valid: true, issues: [] };
+        }
+        // Check for failed processors
+        for (const result of results) {
+            if (!result.success) {
+                issues.push({
+                    severity: "error",
+                    processorName: result.name,
+                    message: `Processor "${result.name}" failed during execution`,
+                });
+            }
+        }
+        // Validate priority ordering if priorities are provided
+        const withPriority = results.filter((r) => r.priority !== undefined);
+        if (withPriority.length > 1) {
+            for (let i = 1; i < withPriority.length; i++) {
+                const prev = withPriority[i - 1];
+                const curr = withPriority[i];
+                if (!prev || !curr)
+                    continue;
+                if (prev.priority !== undefined &&
+                    curr.priority !== undefined &&
+                    prev.priority > curr.priority) {
+                    issues.push({
+                        severity: "warning",
+                        processorName: curr.name,
+                        message: `Processor "${curr.name}" (priority ${curr.priority}) ran after "${prev.name}" (priority ${prev.priority}) — expected ascending priority order`,
+                    });
+                }
+            }
+        }
+        // Detect processors with zero or negative duration (potential skips)
+        for (const result of results) {
+            if (result.success && result.duration <= 0) {
+                issues.push({
+                    severity: "warning",
+                    processorName: result.name,
+                    message: `Processor "${result.name}" reports zero/negative duration (${result.duration}ms) — may have been skipped`,
+                });
+            }
+        }
+        // Build chain report
+        const successful = results.filter((r) => r.success).length;
+        const failed = results.filter((r) => !r.success).length;
+        const skipped = results.filter((r) => r.success && r.duration <= 0).length;
+        const totalDuration = results.reduce((sum, r) => sum + r.duration, 0);
+        const executedInPriorityOrder = !issues.some((issue) => issue.message.includes("expected ascending priority order"));
+        this.chainReport = {
+            totalProcessors: results.length,
+            successful,
+            failed,
+            skipped,
+            issues,
+            averageDuration: results.length > 0 ? totalDuration / results.length : 0,
+            executedInPriorityOrder,
+        };
+        return {
+            valid: issues.filter((i) => i.severity === "error").length === 0,
+            issues,
+        };
+    }
+    /**
+     * Get the chain report from the most recent validation.
+     */
+    getChainReport() {
+        if (!this.chainReport) {
+            return {
+                totalProcessors: 0,
+                successful: 0,
+                failed: 0,
+                skipped: 0,
+                issues: [],
+                averageDuration: 0,
+                executedInPriorityOrder: true,
+            };
+        }
+        return this.chainReport;
+    }
+}
+// ---------------------------------------------------------------------------
+// Standalone runner for processor-manager integration
+// ---------------------------------------------------------------------------
+export async function runPostProcessorChainValidation(context) {
+    const start = performance.now();
+    try {
+        const preResults = context.preResults ?? [];
+        const validator = new PostProcessorChainValidator();
+        const chainEntries = preResults.map((r) => ({
+            name: r.processorName,
+            success: r.success,
+            duration: r.duration,
+        }));
+        const validationResult = validator.validateChain(chainEntries);
+        const report = validator.getChainReport();
+        if (!validationResult.valid) {
+            frameworkLogger.log("postprocessor-chain-validator", "chain_invalid", "warning", { issues: validationResult.issues });
+        }
+        return {
+            success: validationResult.valid,
+            processorName: "postprocessor-chain-validator",
+            duration: performance.now() - start,
+            result: {
+                validation: validationResult,
+                report,
+            },
+        };
+    }
+    catch (error) {
+        frameworkLogger.log("postprocessor-chain-validator", "validation_failed", "error", { error: error.message });
+        return {
+            success: false,
+            processorName: "postprocessor-chain-validator",
+            duration: performance.now() - start,
+            error: error.message,
+        };
+    }
+}

package/dist/processors/implementations/pre-validate-processor.js

@@ -0,0 +1,18 @@
+import { PreProcessor } from "../processor-interfaces.js";
+export class PreValidateProcessor extends PreProcessor {
+    name = "preValidate";
+    priority = 1;
+    async run(context) {
+        const { data, filePath } = context;
+        if (!data && !filePath) {
+            return { validated: true, syntaxCheck: "skipped", reason: "no data provided" };
+        }
+        if (!data) {
+            return { validated: true, syntaxCheck: "skipped", reason: "no data in context" };
+        }
+        if (typeof data === "string" && data.includes("undefined")) {
+            throw new Error("Potential undefined usage detected");
+        }
+        return { validated: true, syntaxCheck: "passed" };
+    }
+}

package/dist/processors/implementations/publish-preflight-processor.js

@@ -0,0 +1,249 @@
+/**
+ * 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 .strray/features.json
+ *
+ * @processor_type post
+ * @priority 10 (runs early after post-processing starts)
+ * @blocking true (blocks publish on violations)
+ *
+ * @version 1.0.0
+ * @framework 0xRay 1.15.41
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { PostProcessor } from "../processor-interfaces.js";
+import { frameworkLogger } from "../../core/framework-logger.js";
+export class PublishPreflightProcessor extends PostProcessor {
+    name = "publishPreflight";
+    priority = 10;
+    config = {
+        enabled: true,
+        require_documentation: {
+            enabled: true,
+            required_files: ["README.md", "AGENTS.md", "CHANGELOG.md"],
+            readme_version_sync: true,
+        },
+        require_reflection: {
+            enabled: true,
+            max_age_days: 7,
+            auto_create_on_publish: true,
+        },
+        require_pipeline_tests: {
+            enabled: true,
+            min_pipeline_tests: 3,
+        },
+    };
+    constructor() {
+        super();
+        this.loadConfig();
+    }
+    loadConfig() {
+        try {
+            const configPaths = [
+                path.join(process.cwd(), ".strray", "features.json"),
+                path.join(process.cwd(), ".opencode", "strray", "features.json"),
+            ];
+            for (const configPath of configPaths) {
+                if (fs.existsSync(configPath)) {
+                    const configData = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+                    if (configData.publish) {
+                        this.config = { ...this.config, ...configData.publish };
+                    }
+                    break;
+                }
+            }
+        }
+        catch (e) {
+            frameworkLogger.log("publish-preflight-processor", "config-load-failed", "warning", { error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    async run(context) {
+        const projectRoot = process.cwd();
+        await frameworkLogger.log("publish-preflight-processor", "starting", "info", { operation: context.operation });
+        const checks = [];
+        const pubConfig = this.config;
+        const docConfig = pubConfig?.require_documentation ?? {
+            enabled: true,
+            required_files: ["README.md", "AGENTS.md", "CHANGELOG.md"],
+            readme_version_sync: true,
+        };
+        const reflectionConfig = pubConfig?.require_reflection ?? {
+            enabled: true,
+            max_age_days: 7,
+            auto_create_on_publish: true,
+        };
+        const pipelineConfig = pubConfig?.require_pipeline_tests ?? {
+            enabled: true,
+            min_pipeline_tests: 3,
+        };
+        // Check 1: Required documentation files exist
+        if (docConfig.enabled) {
+            for (const docFile of docConfig.required_files) {
+                const docPath = path.join(projectRoot, docFile);
+                const exists = fs.existsSync(docPath);
+                checks.push({
+                    name: `${docFile} exists`,
+                    passed: exists,
+                    message: exists
+                        ? `${docFile} found`
+                        : `${docFile} is missing - required for publish`,
+                    required: true,
+                });
+            }
+        }
+        // Check 2: Required directories exist
+        const reflectionsDir = path.join(projectRoot, "docs/reflections");
+        const pipelineTestDir = path.join(projectRoot, "src/__tests__/pipeline");
+        const reflectionsExists = fs.existsSync(reflectionsDir);
+        const pipelineTestsExist = fs.existsSync(pipelineTestDir);
+        checks.push({
+            name: "docs/reflections exists",
+            passed: reflectionsExists,
+            message: reflectionsExists
+                ? "docs/reflections directory found"
+                : "docs/reflections directory is missing",
+            required: reflectionConfig.enabled,
+        });
+        checks.push({
+            name: "Pipeline tests directory exists",
+            passed: pipelineTestsExist,
+            message: pipelineTestsExist
+                ? "src/__tests__/pipeline directory found"
+                : "src/__tests__/pipeline directory is missing",
+            required: pipelineConfig.enabled,
+        });
+        // Check 3: README version matches package.json
+        if (docConfig.readme_version_sync) {
+            const pkgPath = path.join(projectRoot, "package.json");
+            const readmePath = path.join(projectRoot, "README.md");
+            if (fs.existsSync(pkgPath) && fs.existsSync(readmePath)) {
+                try {
+                    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+                    const readme = fs.readFileSync(readmePath, "utf-8");
+                    const pkgVersion = pkg.version;
+                    const readmeHasVersion = readme.includes(pkgVersion);
+                    checks.push({
+                        name: "README version sync",
+                        passed: readmeHasVersion,
+                        message: readmeHasVersion
+                            ? `README references version ${pkgVersion}`
+                            : `README does not reference current version ${pkgVersion}`,
+                        required: false,
+                    });
+                }
+                catch (e) {
+                    checks.push({
+                        name: "README version sync",
+                        passed: false,
+                        message: "Could not verify README version sync",
+                        required: false,
+                    });
+                }
+            }
+        }
+        // Check 4: Latest reflection exists (within configured days)
+        if (reflectionConfig.enabled && reflectionsExists) {
+            const reflectionFiles = fs.readdirSync(reflectionsDir)
+                .filter(f => f.endsWith(".md"))
+                .map(f => ({
+                name: f,
+                path: path.join(reflectionsDir, f),
+                mtime: fs.statSync(path.join(reflectionsDir, f)).mtime.getTime(),
+            }))
+                .sort((a, b) => b.mtime - a.mtime);
+            const maxAgeMs = reflectionConfig.max_age_days * 24 * 60 * 60 * 1000;
+            const latestReflection = reflectionFiles[0];
+            const hasRecentReflection = latestReflection !== undefined &&
+                latestReflection.mtime > (Date.now() - maxAgeMs);
+            checks.push({
+                name: "Recent reflection",
+                passed: hasRecentReflection,
+                message: hasRecentReflection
+                    ? `Latest reflection: ${latestReflection.name}`
+                    : `No reflection documents from last ${reflectionConfig.max_age_days} days - reflection required before publish`,
+                required: true,
+            });
+        }
+        // Check 5: Pipeline tests exist - must match all discoverable pipelines
+        const pipelineInventoryPath = path.join(projectRoot, "docs/architecture/PIPELINE_INVENTORY.md");
+        let requiredPipelineTests = pipelineConfig.min_pipeline_tests;
+        if (fs.existsSync(pipelineInventoryPath)) {
+            try {
+                const inventory = fs.readFileSync(pipelineInventoryPath, "utf-8");
+                const mainPipelineMatches = inventory.match(/### Main Pipelines \((\d+)\)/);
+                const subPipelineSectionMatch = inventory.match(/### Sub-Pipelines[\s\S]*?(?=### |\n## |\n$)/);
+                let subCount = 0;
+                if (subPipelineSectionMatch) {
+                    const subLines = subPipelineSectionMatch[0].split('\n').filter(l => l.match(/^\|.*\*\*.*\|/));
+                    subCount = subLines.length;
+                }
+                if (mainPipelineMatches || subCount > 0) {
+                    const mainPipelineCount = mainPipelineMatches?.[1] ?? "0";
+                    const mainCount = parseInt(mainPipelineCount, 10);
+                    requiredPipelineTests = mainCount + subCount;
+                }
+            }
+            catch (e) {
+                frameworkLogger.log("publish-preflight-processor", "inventory-parse-failed", "warning", { error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        if (pipelineConfig.enabled && pipelineTestsExist) {
+            const testFiles = fs.readdirSync(pipelineTestDir)
+                .filter(f => f.endsWith(".mjs") || f.endsWith(".test.mjs"));
+            const hasEnoughTests = testFiles.length >= requiredPipelineTests;
+            const requiredStr = requiredPipelineTests.toString();
+            checks.push({
+                name: "Pipeline tests",
+                passed: hasEnoughTests,
+                message: hasEnoughTests
+                    ? `Found ${testFiles.length} pipeline test files (required: ${requiredStr})`
+                    : `Only ${testFiles.length} pipeline test files - ${requiredStr} required (from PIPELINE_INVENTORY.md)`,
+                required: true,
+            });
+        }
+        // Determine overall compliance
+        const failedRequired = checks.filter(c => c.required && !c.passed);
+        const compliant = failedRequired.length === 0;
+        const summary = compliant
+            ? "✅ All preflight checks passed"
+            : `❌ ${failedRequired.length} required check(s) failed: ${failedRequired.map(c => c.name).join(", ")}`;
+        if (!compliant) {
+            await frameworkLogger.log("publish-preflight-processor", "failed", "error", { failedChecks: failedRequired.map(c => c.name) });
+        }
+        return {
+            compliant,
+            checks,
+            summary,
+            checkedAt: new Date().toISOString(),
+        };
+    }
+    async execute(context) {
+        const startTime = Date.now();
+        const result = await this.run(context);
+        const duration = Date.now() - startTime;
+        if (!result.compliant) {
+            const failedChecks = result.checks
+                .filter(c => c.required && !c.passed)
+                .map(c => c.message)
+                .join("; ");
+            return {
+                success: false,
+                error: `Publish preflight failed: ${failedChecks}`,
+                data: result,
+                duration,
+                processorName: this.name,
+            };
+        }
+        return {
+            success: true,
+            data: result,
+            duration,
+            processorName: this.name,
+        };
+    }
+}

package/dist/processors/implementations/refactoring-logging-processor-wrapper.js

@@ -0,0 +1,33 @@
+import { PreProcessor } from "../processor-interfaces.js";
+import { frameworkLogger } from "../../core/framework-logger.js";
+export class RefactoringLoggingProcessorWrapper extends PreProcessor {
+    name = "refactoringLogging";
+    priority = 8;
+    async run(context) {
+        try {
+            const { RefactoringLoggingProcessor } = await import("./refactoring-logging-processor.js");
+            const processor = new RefactoringLoggingProcessor();
+            if (context.agentName &&
+                context.task &&
+                typeof context.startTime === "number") {
+                const result = await processor.execute(context);
+                return {
+                    logged: result.logged || false,
+                    success: true,
+                    message: result.logged ? "Agent completion logged" : "No logging needed",
+                };
+            }
+            return { logged: false, success: true, message: "Not an agent task completion context" };
+        }
+        catch (error) {
+            frameworkLogger.log("refactoring-logging-processor", "failed", "error", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return {
+                logged: false,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+}