agentic-qe 3.11.1 → 3.11.3

package/dist/domains/code-intelligence/services/product-factors-bridge.js

@@ -18,8 +18,10 @@ import * as fs from 'fs/promises';
 import { ok, err } from '../../../shared/types';
 import { CodeIntelligenceEvents, createEvent, } from '../../../shared/events/domain-events';
 import { toError } from '../../../shared/error-utils.js';
-import { isCacheValid, sanitizeId, inferComponentType, } from '../../../shared/c4-model';
+import { isCacheValid, sanitizeId, inferComponentType, assessC4Confidence, } from '../../../shared/c4-model';
 import { safeJsonParse } from '../../../shared/safe-json.js';
+import { C4ModelService } from './c4-model';
+import { toContextRequest, toContainerRequest, toComponentRequest, } from './c4-model/from-detected';
 const DEFAULT_CONFIG = {
     cacheTtlMs: 3600000, // 1 hour
     publishEvents: true,
@@ -96,11 +98,26 @@ export class ProductFactorsBridgeService {
     config;
     initialized = false;
     eventSubscriptions = [];
+    /** ADR-112: the consolidated render+analyze+store engine (lazily built). */
+    c4Service;
     constructor(eventBus, memory, config = {}) {
         this.eventBus = eventBus;
         this.memory = memory;
         this.config = { ...DEFAULT_CONFIG, ...config };
     }
+    /**
+     * ADR-112: lazily construct the shared C4ModelService.
+     * Embeddings are OFF on this internal product-factors path (keeps it offline +
+     * fast); the CLI/MCP surfaces opt embeddings in when semantic search is wanted.
+     */
+    getC4Service() {
+        if (!this.c4Service) {
+            this.c4Service = new C4ModelService(this.memory, {
+                enableEmbeddings: this.config.enableC4Embeddings ?? false,
+            });
+        }
+        return this.c4Service;
+    }
     // ==========================================================================
     // Lifecycle
     // ==========================================================================
@@ -130,7 +147,7 @@ export class ProductFactorsBridgeService {
         const sub2 = this.eventBus.subscribe(CodeIntelligenceEvents.ImpactAnalysisCompleted, this.handleImpactAnalysisCompleted.bind(this));
         this.eventSubscriptions.push(sub2);
     }
-    async handleKnowledgeGraphUpdated(event) {
+    async handleKnowledgeGraphUpdated(_event) {
         // Invalidate relevant caches when knowledge graph is updated
         logger.info('[ProductFactorsBridge] Knowledge graph updated, considering cache invalidation');
         // Note: We don't have project path in this event, so we rely on hash-based invalidation
@@ -198,30 +215,40 @@ export class ProductFactorsBridgeService {
             if (request.analyzeCoupling && components.length > 1) {
                 couplingAnalysis = this.analyzeCoupling(components, relationships);
             }
-            // Generate diagrams
+            // Generate diagrams. ADR-112: the three C4 levels render through the
+            // consolidated C4ModelService (richer + stored + searchable); the bridge
+            // keeps only detection. Inline generators remain as a safety fallback.
             const diagrams = {};
             if (request.includeContext !== false) {
-                diagrams.context = this.generateContextDiagram(projectInfo, externalSystems);
+                diagrams.context = await this.renderContext(projectInfo, externalSystems);
             }
             if (request.includeContainer !== false) {
-                diagrams.container = this.generateContainerDiagram(projectInfo, externalSystems);
+                diagrams.container = await this.renderContainer(projectInfo, externalSystems);
             }
             if (request.includeComponent !== false && components.length > 0) {
-                diagrams.component = this.generateComponentDiagram(projectInfo.name, components, relationships);
+                diagrams.component = await this.renderComponent(projectInfo, components, relationships);
             }
             if (request.includeDependency && components.length > 0) {
                 diagrams.dependency = this.generateDependencyGraph(components, relationships);
             }
+            const filesAnalyzed = components.reduce((sum, c) => sum + c.files.length, 0);
             const metadata = {
                 projectName: projectInfo.name,
                 projectDescription: projectInfo.description,
                 generatedAt: new Date(),
                 source: 'codebase-analysis',
                 analysisMetadata: {
-                    filesAnalyzed: components.reduce((sum, c) => sum + c.files.length, 0),
+                    filesAnalyzed,
                     componentsDetected: components.length,
                     externalSystemsDetected: externalSystems.length,
                     analysisTimeMs: Date.now() - startTime,
+                    // ADR-112: deterministic confidence gate — never present a wrong diagram as truth.
+                    confidence: assessC4Confidence({
+                        componentsDetected: components.length,
+                        relationshipsDetected: relationships.length,
+                        externalSystemsDetected: externalSystems.length,
+                        filesAnalyzed,
+                    }),
                 },
             };
             return ok({
@@ -239,70 +266,37 @@ export class ProductFactorsBridgeService {
         }
     }
     // ==========================================================================
-    // IC4DiagramGenerator Implementation
+    // ADR-112: render via the consolidated C4ModelService (the single engine).
+    // On failure we FAIL LOUD — propagate the error so the caller surfaces it —
+    // rather than silently degrading to a weaker inline diagram. A masked render
+    // failure is worse than a surfaced one (ADR-050: no silent degradation).
     // ==========================================================================
-    generateContextDiagram(project, externalSystems) {
-        let mermaid = `C4Context
-  title System Context diagram for ${project.name}
-
-  Person(user, "User", "A user of the system")
-  System(system, "${project.name}", "${project.description}")
-`;
-        for (const sys of externalSystems) {
-            mermaid += `  System_Ext(${sys.id}, "${sys.name}", "${sys.type}")
-`;
-        }
-        mermaid += `
-  Rel(user, system, "Uses")
-`;
-        for (const sys of externalSystems) {
-            mermaid += `  Rel(system, ${sys.id}, "${sys.relationship}")
-`;
+    async renderContext(projectInfo, externalSystems) {
+        const res = await this.getC4Service().buildContext(toContextRequest(projectInfo, externalSystems));
+        if (!res.success) {
+            logger.error('[ProductFactorsBridge] C4 context render failed', res.error);
+            throw res.error;
         }
-        return mermaid;
+        return res.value.mermaid;
     }
-    generateContainerDiagram(project, externalSystems) {
-        let mermaid = `C4Container
-  title Container diagram for ${project.name}
-
-  Person(user, "User", "A user of the system")
-
-  Container_Boundary(c1, "${project.name}") {
-    Container(app, "Application", "TypeScript", "Main application")
-  }
-`;
-        for (const sys of externalSystems) {
-            mermaid += `  System_Ext(${sys.id}, "${sys.name}", "${sys.type}")
-`;
-        }
-        mermaid += `
-  Rel(user, app, "Uses")
-`;
-        for (const sys of externalSystems) {
-            mermaid += `  Rel(app, ${sys.id}, "${sys.relationship}")
-`;
+    async renderContainer(projectInfo, externalSystems) {
+        const res = await this.getC4Service().buildContainer(toContainerRequest(projectInfo, externalSystems));
+        if (!res.success) {
+            logger.error('[ProductFactorsBridge] C4 container render failed', res.error);
+            throw res.error;
         }
-        return mermaid;
+        return res.value.mermaid;
     }
-    generateComponentDiagram(projectName, components, relationships) {
-        let mermaid = `C4Component
-  title Component diagram for ${projectName}
-
-  Container_Boundary(app, "Application") {
-`;
-        for (const comp of components) {
-            const responsibility = comp.responsibilities?.[0] || '';
-            mermaid += `    Component(${comp.id}, "${comp.name}", "${comp.technology || 'TypeScript'}", "${responsibility}")
-`;
-        }
-        mermaid += `  }
-`;
-        for (const rel of relationships) {
-            mermaid += `  Rel(${rel.sourceId}, ${rel.targetId}, "${rel.type}")
-`;
+    async renderComponent(projectInfo, components, relationships) {
+        const res = await this.getC4Service().buildComponent(toComponentRequest(components, relationships));
+        if (!res.success) {
+            logger.error('[ProductFactorsBridge] C4 component render failed', res.error);
+            throw res.error;
         }
-        return mermaid;
+        return res.value.mermaid;
     }
+    // The dependency graph is NOT a C4 level and C4ModelService does not render
+    // it, so this stays as the bridge's own renderer.
     generateDependencyGraph(components, relationships) {
         let mermaid = `graph TD
 `;
@@ -439,6 +433,19 @@ export class ProductFactorsBridgeService {
         catch (error) {
             logger.error('Component analysis failed:', error instanceof Error ? error : undefined);
         }
+        // ADR-112 C2: prefer REAL KG-derived edges (AST import/call graph) over the
+        // naming heuristic. The resolver returns null on any miss → heuristic stands.
+        if (this.config.relationshipResolver && components.length > 0) {
+            try {
+                const resolved = await this.config.relationshipResolver(components, projectPath);
+                if (resolved && resolved.length > 0) {
+                    return { components, relationships: resolved };
+                }
+            }
+            catch (error) {
+                logger.debug(`KG relationship resolver failed; using heuristic: ${toError(error).message}`);
+            }
+        }
         return { components, relationships };
     }
     shouldExclude(name) {
@@ -473,7 +480,7 @@ export class ProductFactorsBridgeService {
                     }
                 }
             }
-            catch (error) {
+            catch {
                 // Non-critical: permission errors when scanning directories
                 logger.debug('Directory scan error:');
             }

package/dist/feedback/regenerability-gate.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Regenerability Gate (ADR-113)
+ *
+ * Answers the Deletion Test per module: "if I deleted this module and
+ * regenerated it, how confident am I that a wrong rebuild would be caught?"
+ * Confidence comes from the oracle tier backing the module (durable > live >
+ * ephemeral > none) scaled by its mutation kill rate. The gate is warn-by-default
+ * and opt-in blocking so it never breaks an existing pipeline on adoption.
+ *
+ * Pure functions only — no I/O. Inputs (tier presence + mutation score) are
+ * produced upstream by the oracle eval runner and test-tier tagging.
+ */
+/** Which durability tier of test backs a module (see qe-test-generation SKILL.md). */
+export type RegenerabilityTier = 'durable' | 'live' | 'ephemeral' | 'none';
+export interface ModuleTestProfile {
+    module: string;
+    /** Mutation kill rate of the module's tests, 0..1. */
+    mutationScore: number;
+    /** Has >=1 durable test (invariant / contract / property at the boundary). */
+    hasDurable: boolean;
+    /** Has live checks (monitoring / drift / cost assertions). */
+    hasLive?: boolean;
+    /** Has ephemeral tests (example-based / mock-call). */
+    hasEphemeral?: boolean;
+}
+export interface RegenerabilityResult {
+    module: string;
+    tier: RegenerabilityTier;
+    /** 0..1 confidence that deleting + regenerating this module is safe. */
+    score: number;
+    reason: string;
+}
+export interface RegenerabilityGateConfig {
+    /** Minimum mutation kill rate per module. */
+    mutationScoreMin: number;
+    /** Minimum regenerability score per module. */
+    regenerabilityMin: number;
+    /** 'warn' reports but never fails CI; 'block' fails CI when thresholds are unmet. */
+    mode: 'warn' | 'block';
+}
+/** Non-blocking by default — adoption must not break existing pipelines. */
+export declare const DEFAULT_REGENERABILITY_GATE: RegenerabilityGateConfig;
+export interface RegenerabilityGateVerdict {
+    /** True when every module meets both thresholds. */
+    passed: boolean;
+    /** True only when the gate should fail CI: mode === 'block' AND not passed. */
+    blocking: boolean;
+    mode: 'warn' | 'block';
+    results: RegenerabilityResult[];
+    failures: Array<{
+        module: string;
+        reasons: string[];
+    }>;
+    summary: string;
+}
+/** Highest tier of test present on the module. Durable wins because it survives a rewrite. */
+export declare function classifyTier(profile: ModuleTestProfile): RegenerabilityTier;
+/**
+ * Regenerability = fault-detection (mutation score) discounted by how well the
+ * backing tests survive a reimplementation. Ephemeral tests are coupled to the
+ * current code, so even a high mutation score earns limited regeneration
+ * confidence; durable tests earn full confidence for their kill rate.
+ */
+export declare function regenerabilityScore(profile: ModuleTestProfile): RegenerabilityResult;
+/**
+ * Evaluate the regenerability gate over a set of modules.
+ * `passed` reflects thresholds; `blocking` reflects whether CI should fail.
+ */
+export declare function evaluateRegenerabilityGate(profiles: ModuleTestProfile[], config?: RegenerabilityGateConfig): RegenerabilityGateVerdict;
+//# sourceMappingURL=regenerability-gate.d.ts.map

package/dist/feedback/regenerability-gate.js

@@ -0,0 +1,91 @@
+/**
+ * Regenerability Gate (ADR-113)
+ *
+ * Answers the Deletion Test per module: "if I deleted this module and
+ * regenerated it, how confident am I that a wrong rebuild would be caught?"
+ * Confidence comes from the oracle tier backing the module (durable > live >
+ * ephemeral > none) scaled by its mutation kill rate. The gate is warn-by-default
+ * and opt-in blocking so it never breaks an existing pipeline on adoption.
+ *
+ * Pure functions only — no I/O. Inputs (tier presence + mutation score) are
+ * produced upstream by the oracle eval runner and test-tier tagging.
+ */
+/** Non-blocking by default — adoption must not break existing pipelines. */
+export const DEFAULT_REGENERABILITY_GATE = {
+    mutationScoreMin: 0.6,
+    regenerabilityMin: 0.5,
+    mode: 'warn',
+};
+const round = (n) => Math.round(n * 10000) / 10000;
+const clamp01 = (n) => Math.max(0, Math.min(1, n));
+/** Highest tier of test present on the module. Durable wins because it survives a rewrite. */
+export function classifyTier(profile) {
+    if (profile.hasDurable)
+        return 'durable';
+    if (profile.hasLive)
+        return 'live';
+    if (profile.hasEphemeral)
+        return 'ephemeral';
+    return 'none';
+}
+/**
+ * Regenerability = fault-detection (mutation score) discounted by how well the
+ * backing tests survive a reimplementation. Ephemeral tests are coupled to the
+ * current code, so even a high mutation score earns limited regeneration
+ * confidence; durable tests earn full confidence for their kill rate.
+ */
+export function regenerabilityScore(profile) {
+    const tier = classifyTier(profile);
+    const mutation = clamp01(profile.mutationScore);
+    let score;
+    let reason;
+    switch (tier) {
+        case 'durable':
+            score = mutation;
+            reason = `durable tests kill ${(mutation * 100).toFixed(0)}% of mutants and survive a reimplementation`;
+            break;
+        case 'live':
+            score = mutation * 0.7;
+            reason = `live checks only; ${(mutation * 100).toFixed(0)}% mutation — add durable boundary tests for full confidence`;
+            break;
+        case 'ephemeral':
+            score = mutation * 0.4;
+            reason = `only ephemeral (example/mock) tests — coupled to the current implementation, would not survive a rewrite`;
+            break;
+        case 'none':
+        default:
+            score = 0;
+            reason = `no tests — deleting this module is unrecoverable (fails the Deletion Test)`;
+            break;
+    }
+    return { module: profile.module, tier, score: round(score), reason };
+}
+/**
+ * Evaluate the regenerability gate over a set of modules.
+ * `passed` reflects thresholds; `blocking` reflects whether CI should fail.
+ */
+export function evaluateRegenerabilityGate(profiles, config = DEFAULT_REGENERABILITY_GATE) {
+    const results = profiles.map(regenerabilityScore);
+    const failures = [];
+    for (let i = 0; i < profiles.length; i++) {
+        const p = profiles[i];
+        const r = results[i];
+        const reasons = [];
+        if (clamp01(p.mutationScore) < config.mutationScoreMin) {
+            reasons.push(`mutation score ${(clamp01(p.mutationScore) * 100).toFixed(0)}% < ${(config.mutationScoreMin * 100).toFixed(0)}%`);
+        }
+        if (r.score < config.regenerabilityMin) {
+            reasons.push(`regenerability ${(r.score * 100).toFixed(0)}% < ${(config.regenerabilityMin * 100).toFixed(0)}% (${r.tier})`);
+        }
+        if (reasons.length > 0)
+            failures.push({ module: p.module, reasons });
+    }
+    const passed = failures.length === 0;
+    const blocking = config.mode === 'block' && !passed;
+    const verb = passed ? 'PASS' : config.mode === 'block' ? 'FAIL (blocking)' : 'WARN (non-blocking)';
+    const summary = profiles.length === 0
+        ? 'regenerability gate: no modules evaluated'
+        : `regenerability gate: ${verb} — ${profiles.length - failures.length}/${profiles.length} modules meet thresholds`;
+    return { passed, blocking, mode: config.mode, results, failures, summary };
+}
+//# sourceMappingURL=regenerability-gate.js.map