cipher-security 2.1.0 → 2.2.0

package/lib/pipeline/hooks.js

@@ -0,0 +1,288 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+// CIPHER is a trademark of defconxt.
+
+/**
+ * CIPHER Pipeline Hook System
+ *
+ * EventEmitter-based hooks for pipeline stages. Supports before/after
+ * callbacks with context passing, finding transformation, and abort.
+ *
+ * Zero overhead when no hooks are registered.
+ *
+ * @module pipeline/hooks
+ */
+
+import { EventEmitter } from 'node:events';
+
+// ---------------------------------------------------------------------------
+// Hook Events
+// ---------------------------------------------------------------------------
+
+/** @enum {string} */
+export const HookEvent = Object.freeze({
+  PIPELINE_START: 'pipeline:start',
+  PIPELINE_COMPLETE: 'pipeline:complete',
+  PIPELINE_ERROR: 'pipeline:error',
+  BEFORE_CRAWL: 'before:crawl',
+  AFTER_CRAWL: 'after:crawl',
+  BEFORE_SCAN: 'before:scan',
+  AFTER_SCAN: 'after:scan',
+  BEFORE_REVIEW: 'before:review',
+  AFTER_REVIEW: 'after:review',
+  BEFORE_ANALYZE: 'before:analyze',
+  AFTER_ANALYZE: 'after:analyze',
+});
+
+// ---------------------------------------------------------------------------
+// Hook Context
+// ---------------------------------------------------------------------------
+
+/**
+ * Context object passed to hook callbacks.
+ * Mutable — hooks can add metadata or transform findings.
+ */
+export class HookContext {
+  /**
+   * @param {object} opts
+   * @param {string} opts.stage       - Current pipeline stage
+   * @param {string} [opts.target]    - Target being processed
+   * @param {object} [opts.options]   - Stage options
+   * @param {any[]}  [opts.findings]  - Findings accumulated so far
+   * @param {object} [opts.result]    - Stage result (for after hooks)
+   * @param {number} [opts.startTime] - Stage start timestamp
+   * @param {number} [opts.duration]  - Stage duration ms (for after hooks)
+   * @param {object} [opts.meta]      - Arbitrary metadata
+   */
+  constructor(opts = {}) {
+    this.stage = opts.stage ?? '';
+    this.target = opts.target ?? '';
+    this.options = opts.options ?? {};
+    this.findings = opts.findings ?? [];
+    this.result = opts.result ?? null;
+    this.startTime = opts.startTime ?? Date.now();
+    this.duration = opts.duration ?? 0;
+    this.meta = opts.meta ?? {};
+    this._aborted = false;
+    this._abortReason = '';
+  }
+
+  /**
+   * Signal that the pipeline should abort after this hook.
+   * @param {string} [reason]
+   */
+  abort(reason = '') {
+    this._aborted = true;
+    this._abortReason = reason;
+  }
+
+  get aborted() { return this._aborted; }
+  get abortReason() { return this._abortReason; }
+}
+
+// ---------------------------------------------------------------------------
+// PipelineHooks
+// ---------------------------------------------------------------------------
+
+/**
+ * Pipeline hook manager. Wraps EventEmitter with typed hook registration
+ * and context-aware execution.
+ */
+export class PipelineHooks extends EventEmitter {
+  constructor() {
+    super();
+    this.setMaxListeners(50); // Allow many hooks
+  }
+
+  /**
+   * Register a hook callback.
+   * @param {string} event   - HookEvent value
+   * @param {function} fn    - async (ctx: HookContext) => void
+   * @param {object} [opts]
+   * @param {string} [opts.name]     - Hook name for logging
+   * @param {number} [opts.priority] - Lower runs first (default: 100)
+   * @returns {PipelineHooks} this (chainable)
+   */
+  hook(event, fn, opts = {}) {
+    fn._hookName = opts.name ?? fn.name ?? 'anonymous';
+    fn._hookPriority = opts.priority ?? 100;
+    this.on(event, fn);
+    return this;
+  }
+
+  /**
+   * Execute all hooks for an event, in priority order.
+   * Returns the context (possibly mutated by hooks).
+   *
+   * @param {string} event
+   * @param {HookContext} ctx
+   * @returns {Promise<HookContext>}
+   */
+  async run(event, ctx) {
+    const listeners = this.listeners(event);
+    if (listeners.length === 0) return ctx;
+
+    // Sort by priority (stable sort)
+    const sorted = [...listeners].sort(
+      (a, b) => (a._hookPriority ?? 100) - (b._hookPriority ?? 100),
+    );
+
+    for (const fn of sorted) {
+      try {
+        await fn(ctx);
+      } catch (err) {
+        ctx.abort(`Hook "${fn._hookName}" threw: ${err.message}`);
+      }
+      if (ctx.aborted) break;
+    }
+
+    return ctx;
+  }
+
+  /**
+   * Check if any hooks are registered for an event.
+   * @param {string} event
+   * @returns {boolean}
+   */
+  hasHooks(event) {
+    return this.listenerCount(event) > 0;
+  }
+
+  /**
+   * Get all registered hook names grouped by event.
+   * @returns {object}
+   */
+  listHooks() {
+    const result = {};
+    for (const event of Object.values(HookEvent)) {
+      const listeners = this.listeners(event);
+      if (listeners.length > 0) {
+        result[event] = listeners.map((fn) => fn._hookName ?? 'anonymous');
+      }
+    }
+    return result;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HookablePipeline — wraps any stage function with hooks
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a hookable wrapper around a pipeline stage function.
+ *
+ * @param {PipelineHooks} hooks   - Hook manager
+ * @param {string} stageName      - Stage name (e.g. 'crawl', 'scan', 'review')
+ * @param {function} stageFn      - async (target, options) => result
+ * @returns {function}            - async (target, options) => result (with hooks)
+ */
+export function hookableStage(hooks, stageName, stageFn) {
+  const beforeEvent = `before:${stageName}`;
+  const afterEvent = `after:${stageName}`;
+
+  return async function hookedStage(target, options = {}) {
+    // Skip hook overhead if none registered
+    if (!hooks.hasHooks(beforeEvent) && !hooks.hasHooks(afterEvent)) {
+      return stageFn(target, options);
+    }
+
+    const t0 = Date.now();
+
+    // Before hook
+    const beforeCtx = new HookContext({
+      stage: stageName,
+      target,
+      options,
+      startTime: t0,
+    });
+    await hooks.run(beforeEvent, beforeCtx);
+
+    if (beforeCtx.aborted) {
+      throw new Error(`Pipeline aborted before ${stageName}: ${beforeCtx.abortReason}`);
+    }
+
+    // Execute stage
+    const result = await stageFn(target, beforeCtx.options);
+    const duration = Date.now() - t0;
+
+    // After hook
+    const afterCtx = new HookContext({
+      stage: stageName,
+      target,
+      options: beforeCtx.options,
+      result,
+      startTime: t0,
+      duration,
+      meta: beforeCtx.meta, // Pass through metadata from before hook
+    });
+    await hooks.run(afterEvent, afterCtx);
+
+    if (afterCtx.aborted) {
+      throw new Error(`Pipeline aborted after ${stageName}: ${afterCtx.abortReason}`);
+    }
+
+    return afterCtx.result ?? result;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Built-in hooks
+// ---------------------------------------------------------------------------
+
+/**
+ * Timing hook — logs stage duration. Attach to after:* events.
+ * @param {function} logger - (message: string) => void
+ * @returns {function}
+ */
+export function timingHook(logger = console.log) {
+  const fn = async (ctx) => {
+    logger(`[hook:timing] ${ctx.stage} completed in ${ctx.duration}ms`);
+  };
+  fn._hookName = 'timing';
+  fn._hookPriority = 999; // Run last
+  return fn;
+}
+
+/**
+ * Finding filter hook — removes findings below a severity threshold.
+ * Attach to after:review or after:scan events.
+ *
+ * @param {string} minSeverity - Minimum severity to keep
+ * @returns {function}
+ */
+export function severityFilterHook(minSeverity) {
+  const RANK = { critical: 4, high: 3, medium: 2, low: 1, info: 0 };
+  const minRank = RANK[minSeverity] ?? 0;
+
+  const fn = async (ctx) => {
+    if (ctx.result && ctx.result.findings) {
+      ctx.result.findings = ctx.result.findings.filter(
+        (f) => (RANK[f.severity] ?? 0) >= minRank,
+      );
+    }
+  };
+  fn._hookName = `severity-filter:${minSeverity}`;
+  fn._hookPriority = 50;
+  return fn;
+}
+
+/**
+ * Abort hook — aborts pipeline if findings exceed a threshold.
+ * Attach to after:review or after:scan events.
+ *
+ * @param {string} severity - Severity level to count
+ * @param {number} max      - Maximum allowed findings of that severity
+ * @returns {function}
+ */
+export function thresholdAbortHook(severity, max) {
+  const fn = async (ctx) => {
+    if (!ctx.result?.findings) return;
+    const count = ctx.result.findings.filter((f) => f.severity === severity).length;
+    if (count > max) {
+      ctx.abort(`${count} ${severity} findings exceed threshold of ${max}`);
+    }
+  };
+  fn._hookName = `threshold-abort:${severity}>${max}`;
+  fn._hookPriority = 80;
+  return fn;
+}

package/lib/pipeline/index.js

@@ -124,3 +124,14 @@ export {
   TemplateCollection,
   NucleiTemplateManager,
 } from './template-manager.js';
+
+// Pipeline hooks — before/after callbacks for pipeline stages
+export {
+  HookEvent,
+  HookContext,
+  PipelineHooks,
+  hookableStage,
+  timingHook,
+  severityFilterHook,
+  thresholdAbortHook,
+} from './hooks.js';

package/lib/review/budget.js

@@ -0,0 +1,210 @@
+// Copyright (c) 2026 defconxt. All rights reserved.
+// Licensed under AGPL-3.0 — see LICENSE file for details.
+// CIPHER is a trademark of defconxt.
+
+/**
+ * CIPHER Token Budget Manager
+ *
+ * Analyzes input complexity and allocates context tokens across
+ * phases (research, planning, execution, review) based on
+ * file count, LOC, language diversity, and max file size.
+ *
+ * @module review/budget
+ */
+
+import { resolveInput, detectLanguage } from './engine.js';
+
+// ---------------------------------------------------------------------------
+// Complexity levels
+// ---------------------------------------------------------------------------
+
+/** @enum {string} */
+export const Complexity = Object.freeze({
+  SIMPLE: 'simple',
+  MEDIUM: 'medium',
+  COMPLEX: 'complex',
+  EXTREME: 'extreme',
+});
+
+/**
+ * Thresholds for complexity classification.
+ */
+const THRESHOLDS = {
+  simple:  { maxFiles: 3,   maxLoc: 500,   maxLanguages: 1 },
+  medium:  { maxFiles: 15,  maxLoc: 3000,  maxLanguages: 3 },
+  complex: { maxFiles: 50,  maxLoc: 15000, maxLanguages: 5 },
+  // anything above complex is extreme
+};
+
+/**
+ * Default token budgets per complexity level.
+ */
+const DEFAULT_BUDGETS = {
+  simple:  { total: 4000,  weights: { research: 0.15, planning: 0.15, execution: 0.50, review: 0.20 } },
+  medium:  { total: 8000,  weights: { research: 0.20, planning: 0.20, execution: 0.40, review: 0.20 } },
+  complex: { total: 12000, weights: { research: 0.25, planning: 0.20, execution: 0.35, review: 0.20 } },
+  extreme: { total: 16000, weights: { research: 0.25, planning: 0.25, execution: 0.30, review: 0.20 } },
+};
+
+// ---------------------------------------------------------------------------
+// Complexity Analysis
+// ---------------------------------------------------------------------------
+
+/**
+ * Complexity metrics for a set of source files.
+ */
+export class ComplexityMetrics {
+  constructor(opts = {}) {
+    this.fileCount = opts.fileCount ?? 0;
+    this.totalLoc = opts.totalLoc ?? 0;
+    this.languages = opts.languages ?? [];
+    this.languageCount = opts.languageCount ?? 0;
+    this.maxFileSize = opts.maxFileSize ?? 0;
+    this.avgFileSize = opts.avgFileSize ?? 0;
+    this.complexity = opts.complexity ?? Complexity.SIMPLE;
+  }
+}
+
+/**
+ * Analyze complexity of resolved source files.
+ *
+ * @param {import('./engine.js').SourceFile[]} sources
+ * @returns {ComplexityMetrics}
+ */
+export function analyzeComplexity(sources) {
+  if (!sources.length) {
+    return new ComplexityMetrics({ complexity: Complexity.SIMPLE });
+  }
+
+  const langSet = new Set();
+  let totalLoc = 0;
+  let maxFileSize = 0;
+
+  for (const src of sources) {
+    const loc = src.content.split('\n').length;
+    totalLoc += loc;
+    if (loc > maxFileSize) maxFileSize = loc;
+    langSet.add(src.language);
+  }
+
+  const fileCount = sources.length;
+  const languageCount = langSet.size;
+  const avgFileSize = Math.round(totalLoc / fileCount);
+  const languages = [...langSet].sort();
+
+  // Classify complexity
+  let complexity;
+  if (fileCount <= THRESHOLDS.simple.maxFiles &&
+      totalLoc <= THRESHOLDS.simple.maxLoc &&
+      languageCount <= THRESHOLDS.simple.maxLanguages) {
+    complexity = Complexity.SIMPLE;
+  } else if (fileCount <= THRESHOLDS.medium.maxFiles &&
+             totalLoc <= THRESHOLDS.medium.maxLoc &&
+             languageCount <= THRESHOLDS.medium.maxLanguages) {
+    complexity = Complexity.MEDIUM;
+  } else if (fileCount <= THRESHOLDS.complex.maxFiles &&
+             totalLoc <= THRESHOLDS.complex.maxLoc &&
+             languageCount <= THRESHOLDS.complex.maxLanguages) {
+    complexity = Complexity.COMPLEX;
+  } else {
+    complexity = Complexity.EXTREME;
+  }
+
+  return new ComplexityMetrics({
+    fileCount,
+    totalLoc,
+    languages,
+    languageCount,
+    maxFileSize,
+    avgFileSize,
+    complexity,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Token Budget
+// ---------------------------------------------------------------------------
+
+/**
+ * Structured token budget with per-phase allocations.
+ */
+export class TokenBudget {
+  /**
+   * @param {object} opts
+   * @param {number} opts.total
+   * @param {object} opts.phases - { research, planning, execution, review }
+   * @param {ComplexityMetrics} opts.metrics
+   */
+  constructor(opts = {}) {
+    this.total = opts.total ?? 0;
+    this.phases = opts.phases ?? {};
+    this.metrics = opts.metrics ?? new ComplexityMetrics();
+  }
+
+  toReport() {
+    const lines = [
+      `Token Budget (${this.metrics.complexity})`,
+      `  Total: ${this.total} tokens`,
+      `  Research:  ${this.phases.research} tokens`,
+      `  Planning:  ${this.phases.planning} tokens`,
+      `  Execution: ${this.phases.execution} tokens`,
+      `  Review:    ${this.phases.review} tokens`,
+      '',
+      `Complexity: ${this.metrics.complexity}`,
+      `  Files: ${this.metrics.fileCount}`,
+      `  LOC: ${this.metrics.totalLoc}`,
+      `  Languages: ${this.metrics.languages.join(', ')} (${this.metrics.languageCount})`,
+      `  Max file: ${this.metrics.maxFileSize} lines`,
+      `  Avg file: ${this.metrics.avgFileSize} lines`,
+    ];
+    return lines.join('\n');
+  }
+
+  toJSON() {
+    return {
+      total: this.total,
+      phases: this.phases,
+      complexity: this.metrics.complexity,
+      metrics: {
+        fileCount: this.metrics.fileCount,
+        totalLoc: this.metrics.totalLoc,
+        languages: this.metrics.languages,
+        languageCount: this.metrics.languageCount,
+        maxFileSize: this.metrics.maxFileSize,
+        avgFileSize: this.metrics.avgFileSize,
+      },
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a token budget for the given input.
+ *
+ * @param {string} input     - File path, directory, or code string
+ * @param {object} [options]
+ * @param {string} [options.language]  - Override language detection
+ * @param {number} [options.total]     - Override total token budget
+ * @param {object} [options.weights]   - Override phase weights { research, planning, execution, review }
+ * @returns {Promise<TokenBudget>}
+ */
+export async function createTokenBudget(input, options = {}) {
+  const sources = await resolveInput(input, { language: options.language });
+  const metrics = analyzeComplexity(sources);
+
+  const budgetConfig = DEFAULT_BUDGETS[metrics.complexity];
+  const total = options.total ?? budgetConfig.total;
+  const weights = { ...budgetConfig.weights, ...options.weights };
+
+  // Normalize weights
+  const weightSum = Object.values(weights).reduce((a, b) => a + b, 0);
+  const phases = {};
+  for (const [phase, weight] of Object.entries(weights)) {
+    phases[phase] = Math.round((weight / weightSum) * total);
+  }
+
+  return new TokenBudget({ total, phases, metrics });
+}