agentic-qe 3.8.5 → 3.8.7

package/dist/cli/command-registry.js

@@ -4,7 +4,7 @@
  * Central registry for all CLI command handlers.
  * Provides command routing and management.
  */
-import { createInitHandler, createStatusHandler, createHealthHandler, createTaskHandler, createAgentHandler, createDomainHandler, createProtocolHandler, createBrainHandler, } from './handlers/index.js';
+import { createInitHandler, createStatusHandler, createHealthHandler, createTaskHandler, createAgentHandler, createDomainHandler, createProtocolHandler, createBrainHandler, createHypergraphHandler, } from './handlers/index.js';
 // ============================================================================
 // Command Registry
 // ============================================================================
@@ -80,6 +80,8 @@ export class CommandRegistry {
         this.register(createProtocolHandler(this.cleanupAndExit, this.ensureInitialized));
         // Brain export/import
         this.register(createBrainHandler(this.cleanupAndExit, this.ensureInitialized));
+        // Hypergraph queries
+        this.register(createHypergraphHandler(this.cleanupAndExit, this.ensureInitialized));
     }
     /**
      * Get help for all commands

package/dist/cli/completions/index.d.ts

@@ -115,6 +115,23 @@ export declare const COMMANDS: {
         readonly description: "V2 to V3 migration";
         readonly options: readonly ["--dry-run", "--backup", "--skip-memory", "--skip-patterns", "--skip-config", "--force"];
     };
+    readonly hypergraph: {
+        readonly description: "Query the code knowledge hypergraph";
+        readonly subcommands: {
+            readonly stats: {
+                readonly options: readonly ["--db"];
+            };
+            readonly untested: {
+                readonly options: readonly ["--db", "--limit"];
+            };
+            readonly impacted: {
+                readonly options: readonly ["--db"];
+            };
+            readonly gaps: {
+                readonly options: readonly ["--db", "--max-coverage", "--limit"];
+            };
+        };
+    };
     readonly completions: {
         readonly description: "Generate shell completions";
         readonly subcommands: {

package/dist/cli/completions/index.js

@@ -210,6 +210,16 @@ export const COMMANDS = {
         description: 'V2 to V3 migration',
         options: ['--dry-run', '--backup', '--skip-memory', '--skip-patterns', '--skip-config', '--force'],
     },
+    // Hypergraph queries
+    hypergraph: {
+        description: 'Query the code knowledge hypergraph',
+        subcommands: {
+            stats: { options: ['--db'] },
+            untested: { options: ['--db', '--limit'] },
+            impacted: { options: ['--db'] },
+            gaps: { options: ['--db', '--max-coverage', '--limit'] },
+        },
+    },
     // Completions command (meta)
     completions: {
         description: 'Generate shell completions',
@@ -315,7 +325,7 @@ _aqe_completions() {
     local cur prev words cword
     _init_completion || return
 
-    local commands="init status health task agent domain protocol test coverage quality security code migrate completions"
+    local commands="init status health task agent domain protocol test coverage quality security code migrate hypergraph completions"
     local task_subcmds="submit list cancel status"
     local agent_subcmds="list spawn"
     local domain_subcmds="list health"
@@ -614,6 +624,23 @@ _aqe_completions() {
                     ;;
             esac
             ;;
+        hypergraph)
+            local hg_subcmds="stats untested impacted gaps"
+            case "\${words[2]}" in
+                stats|untested|gaps)
+                    COMPREPLY=( $(compgen -W "--db --limit --max-coverage" -- "$cur") )
+                    return
+                    ;;
+                impacted)
+                    COMPREPLY=( $(compgen -f -- "$cur") )
+                    return
+                    ;;
+                *)
+                    COMPREPLY=( $(compgen -W "$hg_subcmds" -- "$cur") )
+                    return
+                    ;;
+            esac
+            ;;
         migrate)
             COMPREPLY=( $(compgen -W "--dry-run --backup --skip-memory --skip-patterns --skip-config --force" -- "$cur") )
             return
@@ -692,6 +719,7 @@ _aqe() {
         'quality:Quality assessment'
         'security:Security scanning'
         'code:Code intelligence'
+        'hypergraph:Query the code knowledge hypergraph'
         'migrate:V2 to V3 migration'
         'completions:Generate shell completions'
     )
@@ -939,6 +967,20 @@ _aqe() {
                         '--depth[Analysis depth]:depth:(1 2 3 4 5)' \\
                         '--include-tests[Include test files]'
                     ;;
+                hypergraph)
+                    local -a hg_commands
+                    hg_commands=(
+                        'stats:Show hypergraph statistics'
+                        'untested:Find untested functions'
+                        'impacted:Find impacted tests'
+                        'gaps:Find coverage gaps'
+                    )
+                    _arguments -C \\
+                        '1:command:_describe command hg_commands' \\
+                        '--db[Database path]:path:_files' \\
+                        '--limit[Max results]:number:' \\
+                        '--max-coverage[Coverage threshold]:number:'
+                    ;;
                 migrate)
                     _arguments \\
                         '--dry-run[Preview migration without changes]' \\
@@ -1015,6 +1057,11 @@ complete -c aqe -n "__fish_use_subcommand" -a "coverage" -d "Coverage analysis"
 complete -c aqe -n "__fish_use_subcommand" -a "quality" -d "Quality assessment"
 complete -c aqe -n "__fish_use_subcommand" -a "security" -d "Security scanning"
 complete -c aqe -n "__fish_use_subcommand" -a "code" -d "Code intelligence"
+complete -c aqe -n "__fish_use_subcommand" -a "hypergraph" -d "Query the code knowledge hypergraph"
+complete -c aqe -n "__fish_seen_subcommand_from hypergraph; and not __fish_seen_subcommand_from stats untested impacted gaps" -a "stats" -d "Show hypergraph statistics"
+complete -c aqe -n "__fish_seen_subcommand_from hypergraph; and not __fish_seen_subcommand_from stats untested impacted gaps" -a "untested" -d "Find untested functions"
+complete -c aqe -n "__fish_seen_subcommand_from hypergraph; and not __fish_seen_subcommand_from stats untested impacted gaps" -a "impacted" -d "Find impacted tests"
+complete -c aqe -n "__fish_seen_subcommand_from hypergraph; and not __fish_seen_subcommand_from stats untested impacted gaps" -a "gaps" -d "Find coverage gaps"
 complete -c aqe -n "__fish_use_subcommand" -a "migrate" -d "V2 to V3 migration"
 complete -c aqe -n "__fish_use_subcommand" -a "completions" -d "Generate shell completions"
 
@@ -1217,6 +1264,7 @@ $script:AQE_COMMANDS = @{
     'quality' = 'Quality assessment'
     'security' = 'Security scanning'
     'code' = 'Code intelligence'
+    'hypergraph' = 'Query the code knowledge hypergraph'
     'migrate' = 'V2 to V3 migration'
     'completions' = 'Generate shell completions'
 }

package/dist/cli/handlers/hypergraph-handler.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Agentic QE v3 - Hypergraph Command Handler
+ *
+ * Exposes hypergraph queries to users via CLI:
+ *   aqe hypergraph stats       - Show node/edge counts by type
+ *   aqe hypergraph untested    - Find functions with no test coverage
+ *   aqe hypergraph impacted    - Find tests impacted by changed files
+ *   aqe hypergraph gaps        - Find functions with low coverage
+ */
+import { Command } from 'commander';
+import { ICommandHandler, CLIContext } from './interfaces.js';
+export declare class HypergraphHandler implements ICommandHandler {
+    readonly name = "hypergraph";
+    readonly description = "Query the code knowledge hypergraph";
+    private cleanupAndExit;
+    private ensureInitialized;
+    constructor(cleanupAndExit: (code: number) => Promise<never>, ensureInitialized: () => Promise<boolean>);
+    register(program: Command, _context: CLIContext): void;
+    private executeStats;
+    private executeUntested;
+    private executeImpacted;
+    private executeGaps;
+    private openEngine;
+    getHelp(): string;
+}
+export declare function createHypergraphHandler(cleanupAndExit: (code: number) => Promise<never>, ensureInitialized: () => Promise<boolean>): HypergraphHandler;
+//# sourceMappingURL=hypergraph-handler.d.ts.map

package/dist/cli/handlers/hypergraph-handler.js

@@ -0,0 +1,248 @@
+/**
+ * Agentic QE v3 - Hypergraph Command Handler
+ *
+ * Exposes hypergraph queries to users via CLI:
+ *   aqe hypergraph stats       - Show node/edge counts by type
+ *   aqe hypergraph untested    - Find functions with no test coverage
+ *   aqe hypergraph impacted    - Find tests impacted by changed files
+ *   aqe hypergraph gaps        - Find functions with low coverage
+ */
+import chalk from 'chalk';
+import { join, resolve } from 'path';
+import { existsSync } from 'fs';
+import { findProjectRoot } from '../../kernel/unified-memory.js';
+import { openDatabase } from '../../shared/safe-db.js';
+import { createHypergraphEngine } from '../../integrations/ruvector/hypergraph-engine.js';
+// ============================================================================
+// Hypergraph Handler
+// ============================================================================
+export class HypergraphHandler {
+    name = 'hypergraph';
+    description = 'Query the code knowledge hypergraph';
+    cleanupAndExit;
+    ensureInitialized;
+    constructor(cleanupAndExit, ensureInitialized) {
+        this.cleanupAndExit = cleanupAndExit;
+        this.ensureInitialized = ensureInitialized;
+    }
+    register(program, _context) {
+        const hg = program
+            .command('hypergraph')
+            .alias('hg')
+            .description(this.description);
+        hg
+            .command('stats')
+            .description('Show hypergraph statistics (node/edge counts by type)')
+            .option('--db <path>', 'Database path')
+            .action(async (options) => {
+            await this.executeStats(options);
+        });
+        hg
+            .command('untested')
+            .description('Find functions with no test coverage')
+            .option('--db <path>', 'Database path')
+            .option('--limit <number>', 'Max results', '20')
+            .action(async (options) => {
+            await this.executeUntested(options);
+        });
+        hg
+            .command('impacted <files...>')
+            .description('Find tests impacted by changed files')
+            .option('--db <path>', 'Database path')
+            .action(async (files, options) => {
+            await this.executeImpacted(files, options);
+        });
+        hg
+            .command('gaps')
+            .description('Find functions with low coverage')
+            .option('--db <path>', 'Database path')
+            .option('--max-coverage <number>', 'Coverage threshold (%)', '50')
+            .option('--limit <number>', 'Max results', '20')
+            .action(async (options) => {
+            await this.executeGaps(options);
+        });
+    }
+    // --------------------------------------------------------------------------
+    // Subcommands
+    // --------------------------------------------------------------------------
+    async executeStats(options) {
+        if (!await this.ensureInitialized())
+            return;
+        const { engine, close } = await this.openEngine(options.db);
+        try {
+            const stats = await engine.getStats();
+            console.log(chalk.blue('\n  Hypergraph Statistics\n'));
+            console.log(chalk.white(`  Total nodes: ${stats.totalNodes}`));
+            console.log(chalk.white(`  Total edges: ${stats.totalEdges}`));
+            if (stats.totalNodes > 0) {
+                console.log(chalk.gray('\n  Nodes by type:'));
+                for (const [type, count] of Object.entries(stats.nodesByType)) {
+                    if (count > 0) {
+                        console.log(chalk.gray(`    ${type}: ${count}`));
+                    }
+                }
+                console.log(chalk.gray('\n  Edges by type:'));
+                for (const [type, count] of Object.entries(stats.edgesByType)) {
+                    if (count > 0) {
+                        console.log(chalk.gray(`    ${type}: ${count}`));
+                    }
+                }
+                console.log(chalk.gray(`\n  Avg complexity: ${stats.avgComplexity.toFixed(1)}`));
+                console.log(chalk.gray(`  Avg coverage: ${stats.avgCoverage.toFixed(1)}%`));
+                console.log(chalk.gray(`  Nodes with embeddings: ${stats.nodesWithEmbeddings}`));
+            }
+            else {
+                console.log(chalk.yellow('\n  Hypergraph is empty. Run "aqe init --auto" to populate it.'));
+            }
+            console.log('');
+        }
+        finally {
+            close();
+        }
+        await this.cleanupAndExit(0);
+    }
+    async executeUntested(options) {
+        if (!await this.ensureInitialized())
+            return;
+        const { engine, close } = await this.openEngine(options.db);
+        try {
+            const limit = parseInt(options.limit, 10) || 20;
+            const untested = await engine.findUntestedFunctions();
+            const results = untested.slice(0, limit);
+            console.log(chalk.blue(`\n  Untested Functions (${untested.length} total)\n`));
+            if (results.length === 0) {
+                console.log(chalk.green('  All functions have test coverage!'));
+            }
+            else {
+                for (const fn of results) {
+                    const complexity = fn.complexity ? chalk.yellow(` complexity=${fn.complexity}`) : '';
+                    console.log(chalk.white(`  ${fn.name}`) + chalk.gray(` ${fn.filePath || ''}:${fn.lineStart || '?'}`) + complexity);
+                }
+                if (untested.length > limit) {
+                    console.log(chalk.gray(`\n  ... and ${untested.length - limit} more (use --limit to show more)`));
+                }
+            }
+            console.log('');
+        }
+        finally {
+            close();
+        }
+        await this.cleanupAndExit(0);
+    }
+    async executeImpacted(files, options) {
+        if (!await this.ensureInitialized())
+            return;
+        // Resolve relative paths to absolute so they match hypergraph entries
+        const absoluteFiles = files.map(f => resolve(f));
+        const { engine, close } = await this.openEngine(options.db);
+        try {
+            const tests = await engine.findImpactedTests(absoluteFiles);
+            console.log(chalk.blue(`\n  Impacted Tests for ${files.length} file(s)\n`));
+            if (tests.length === 0) {
+                console.log(chalk.gray('  No impacted tests found. The hypergraph may need rebuilding.'));
+            }
+            else {
+                for (const test of tests) {
+                    console.log(chalk.white(`  ${test.name}`) + chalk.gray(` ${test.filePath || ''}`));
+                }
+            }
+            console.log(chalk.gray(`\n  Total: ${tests.length} test(s)\n`));
+        }
+        finally {
+            close();
+        }
+        await this.cleanupAndExit(0);
+    }
+    async executeGaps(options) {
+        if (!await this.ensureInitialized())
+            return;
+        const { engine, close } = await this.openEngine(options.db);
+        try {
+            const maxCoverage = parseInt(options.maxCoverage, 10) || 50;
+            const limit = parseInt(options.limit, 10) || 20;
+            const gaps = await engine.findCoverageGaps(maxCoverage);
+            const results = gaps.slice(0, limit);
+            console.log(chalk.blue(`\n  Coverage Gaps (<= ${maxCoverage}%) — ${gaps.length} total\n`));
+            if (results.length === 0) {
+                console.log(chalk.green('  No coverage gaps found!'));
+            }
+            else {
+                for (const fn of results) {
+                    const cov = fn.coverage !== undefined ? chalk.red(` ${fn.coverage}%`) : '';
+                    const complexity = fn.complexity ? chalk.yellow(` complexity=${fn.complexity}`) : '';
+                    console.log(chalk.white(`  ${fn.name}`) + cov + chalk.gray(` ${fn.filePath || ''}`) + complexity);
+                }
+                if (gaps.length > limit) {
+                    console.log(chalk.gray(`\n  ... and ${gaps.length - limit} more (use --limit to show more)`));
+                }
+            }
+            console.log('');
+        }
+        finally {
+            close();
+        }
+        await this.cleanupAndExit(0);
+    }
+    // --------------------------------------------------------------------------
+    // Helpers
+    // --------------------------------------------------------------------------
+    async openEngine(dbPathOverride) {
+        const projectRoot = findProjectRoot();
+        const dbPath = dbPathOverride || join(projectRoot, '.agentic-qe', 'memory.db');
+        if (!existsSync(dbPath)) {
+            throw new Error(`Database not found: ${dbPath}\nRun "aqe init --auto" first.`);
+        }
+        const db = openDatabase(dbPath);
+        try {
+            const engine = await createHypergraphEngine({
+                db,
+                maxTraversalDepth: 10,
+                maxQueryResults: 1000,
+                enableVectorSearch: false,
+            });
+            return {
+                engine,
+                close: () => {
+                    try {
+                        db.close();
+                    }
+                    catch { /* ignore */ }
+                },
+            };
+        }
+        catch (error) {
+            // Close db if engine creation fails to prevent connection leak
+            try {
+                db.close();
+            }
+            catch { /* ignore */ }
+            throw error;
+        }
+    }
+    getHelp() {
+        return `
+Query the code knowledge hypergraph for untested functions,
+impacted tests, and coverage gaps.
+
+Usage:
+  aqe hypergraph stats                    Show node/edge counts by type
+  aqe hypergraph untested [--limit N]     Find functions with no test coverage
+  aqe hypergraph impacted <files...>      Find tests impacted by changed files
+  aqe hypergraph gaps [--max-coverage N]  Find functions with low coverage
+
+Options:
+  --db <path>          Override database path (default: .agentic-qe/memory.db)
+  --limit <number>     Max results (default: 20)
+  --max-coverage <n>   Coverage threshold for gaps (default: 50)
+
+Alias: aqe hg stats
+`;
+    }
+}
+// ============================================================================
+// Factory
+// ============================================================================
+export function createHypergraphHandler(cleanupAndExit, ensureInitialized) {
+    return new HypergraphHandler(cleanupAndExit, ensureInitialized);
+}
+//# sourceMappingURL=hypergraph-handler.js.map

package/dist/cli/handlers/index.d.ts

@@ -11,4 +11,5 @@ export { AgentHandler, createAgentHandler } from './agent-handler.js';
 export { DomainHandler, createDomainHandler } from './domain-handler.js';
 export { ProtocolHandler, createProtocolHandler } from './protocol-handler.js';
 export { BrainHandler, createBrainHandler } from './brain-handler.js';
+export { HypergraphHandler, createHypergraphHandler } from './hypergraph-handler.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/handlers/index.js

@@ -13,4 +13,5 @@ export { AgentHandler, createAgentHandler } from './agent-handler.js';
 export { DomainHandler, createDomainHandler } from './domain-handler.js';
 export { ProtocolHandler, createProtocolHandler } from './protocol-handler.js';
 export { BrainHandler, createBrainHandler } from './brain-handler.js';
+export { HypergraphHandler, createHypergraphHandler } from './hypergraph-handler.js';
 //# sourceMappingURL=index.js.map

package/dist/coordination/mincut/phase-executor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Agentic QE v3 - Default Phase Executor
+ * ADR-032: Kuramoto CPG oscillators for self-sustaining scheduling
+ *
+ * Default implementation of the PhaseExecutor interface that simulates
+ * test execution. Replace with real test runner integration in production.
+ */
+import type { CPGTestPhase, CPGPhaseResult } from './kuramoto-cpg';
+import type { PhaseExecutor } from './time-crystal-types';
+/**
+ * Default phase executor that simulates test execution
+ * Replace with real test runner integration in production
+ */
+export declare class DefaultPhaseExecutor implements PhaseExecutor {
+    private readonly name;
+    private ready;
+    constructor(name?: string);
+    execute(phase: CPGTestPhase): Promise<CPGPhaseResult>;
+    isReady(): boolean;
+    getName(): string;
+    setReady(ready: boolean): void;
+}
+/**
+ * Create a default phase executor
+ */
+export declare function createDefaultPhaseExecutor(name?: string): DefaultPhaseExecutor;
+//# sourceMappingURL=phase-executor.d.ts.map

package/dist/coordination/mincut/phase-executor.js

@@ -0,0 +1,70 @@
+/**
+ * Agentic QE v3 - Default Phase Executor
+ * ADR-032: Kuramoto CPG oscillators for self-sustaining scheduling
+ *
+ * Default implementation of the PhaseExecutor interface that simulates
+ * test execution. Replace with real test runner integration in production.
+ */
+import { secureRandom, secureRandomInt, secureRandomFloat } from '../../shared/utils/crypto-random.js';
+/**
+ * Default phase executor that simulates test execution
+ * Replace with real test runner integration in production
+ */
+export class DefaultPhaseExecutor {
+    name;
+    ready = true;
+    constructor(name = 'default-executor') {
+        this.name = name;
+    }
+    async execute(phase) {
+        const startTime = Date.now();
+        // Simulate test execution with some variance
+        const basePassRate = phase.qualityThresholds.minPassRate;
+        const variance = (secureRandom() - 0.5) * 0.1; // ±5% variance
+        const actualPassRate = Math.min(1, Math.max(0, basePassRate + variance));
+        const testsRun = secureRandomInt(50, 150);
+        const testsPassed = Math.floor(testsRun * actualPassRate);
+        const testsFailed = testsRun - testsPassed;
+        // Simulate execution time with variance
+        const expectedDuration = phase.expectedDuration;
+        const durationVariance = (secureRandom() - 0.5) * 0.3; // ±15% variance
+        const actualDuration = Math.floor(expectedDuration * (1 + durationVariance));
+        // Simulate wait (scaled down for testing - use 1% of expected duration)
+        const simulatedWait = Math.min(100, actualDuration * 0.01);
+        await new Promise((resolve) => setTimeout(resolve, simulatedWait));
+        const flakyRatio = secureRandom() * phase.qualityThresholds.maxFlakyRatio;
+        const coverage = secureRandomFloat(phase.qualityThresholds.minCoverage, phase.qualityThresholds.minCoverage + 0.1);
+        const qualityMet = actualPassRate >= phase.qualityThresholds.minPassRate &&
+            flakyRatio <= phase.qualityThresholds.maxFlakyRatio &&
+            coverage >= phase.qualityThresholds.minCoverage;
+        return {
+            phaseId: phase.id,
+            phaseName: phase.name,
+            passRate: actualPassRate,
+            flakyRatio,
+            coverage: Math.min(1, coverage),
+            duration: Date.now() - startTime,
+            testsRun,
+            testsPassed,
+            testsFailed,
+            testsSkipped: 0,
+            qualityMet,
+        };
+    }
+    isReady() {
+        return this.ready;
+    }
+    getName() {
+        return this.name;
+    }
+    setReady(ready) {
+        this.ready = ready;
+    }
+}
+/**
+ * Create a default phase executor
+ */
+export function createDefaultPhaseExecutor(name) {
+    return new DefaultPhaseExecutor(name);
+}
+//# sourceMappingURL=phase-executor.js.map

package/dist/coordination/mincut/time-crystal-analysis.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Agentic QE v3 - Time Crystal Analysis & Observation
+ * ADR-047: MinCut Self-Organizing QE Integration - Phase 4
+ *
+ * Pure functions for metrics collection, attractor detection,
+ * anomaly detection, phase prediction, and stabilization decisions.
+ */
+import type { ExecutionMetrics, TimeCrystalPhase, CrystalAnomaly, CrystalObservation, TemporalAttractor, StabilizationAction, TimeCrystalConfig } from './time-crystal-types';
+import type { StrangeLoopController } from './strange-loop';
+import type { MinCutHealthMonitor } from './mincut-health-monitor';
+import type { TestFailureCausalGraph } from './causal-discovery';
+/**
+ * Collect current execution metrics from available monitors
+ */
+export declare function collectMetrics(observations: CrystalObservation[], config: TimeCrystalConfig, healthMonitor?: MinCutHealthMonitor, strangeLoop?: StrangeLoopController): ExecutionMetrics;
+/**
+ * Detect the current attractor state from metrics
+ */
+export declare function detectAttractor(metrics: ExecutionMetrics, config: TimeCrystalConfig, healthMonitor?: MinCutHealthMonitor): TemporalAttractor;
+/**
+ * Detect anomalies in the metrics
+ */
+export declare function detectAnomalies(metrics: ExecutionMetrics, metricsHistory: ExecutionMetrics[], phases: Map<string, TimeCrystalPhase>, config: TimeCrystalConfig, causalGraph?: TestFailureCausalGraph): CrystalAnomaly[];
+/**
+ * Predict the next phase based on observation history
+ */
+export declare function predictPhase(observations: CrystalObservation[], minObservationsForPattern: number): {
+    phase: string | undefined;
+    confidence: number;
+};
+/**
+ * Determine the stabilization action to move toward stable attractor
+ */
+export declare function determineStabilization(observations: CrystalObservation[], causalGraph?: TestFailureCausalGraph): StabilizationAction;
+//# sourceMappingURL=time-crystal-analysis.d.ts.map