@devflow-tools/context-engine 0.17.0 → 0.17.2

package/dist/context-engine.js

@@ -9,10 +9,12 @@ import { rankOptionalContextFiles, } from "./ranker.js";
 import { describeLayerEvidence, detectLanguageFromPath, } from "./layer-rules.js";
 import { reachableCodeGraphNodeIds, sanitizeCodeGraphEdges, } from './graph-edge-quality.js';
 import { assembleContextFileRoles } from './context-file-roles.js';
+import { buildArtifactInventory } from './artifact-inventory.js';
 import { buildTaskContextEnvelope } from './task-retrieval-orchestrator.js';
 import { recordTaskEnvelopeLedger } from './retrieval-ledger.js';
 import { selectGraphEvidence } from './graph-evidence-selector.js';
 import { allocateContextFileBudget } from './context-budget-allocator.js';
+import { emitSemanticControlLog } from '@devflow-tools/telemetry';
 const CG = CGModule.default ?? CGModule;
 const SYMBOL_VECTOR_WARNING = "Symbol vector search is not ready; using CodeGraph/BM25 results. Run `devflow doctor` for details.";
 // ── RRF (Reciprocal Rank Fusion) ─────────────────────────────────
@@ -314,11 +316,18 @@ export class ContextEngine {
         const languages = Object.keys(stats.filesByLanguage ?? {});
         return {
             limit,
+            retrievalIntent: 'automatic_context',
             budgetTokens: Math.max(0, Math.floor(totalBudget * 0.25)),
             activeSkill: options.activeSkill,
             relevantFiles: options.relevantFiles,
             action: taskPlan?.action,
             knowledgeNeeds: taskPlan?.knowledgeNeeds,
+            sessionId: options.sessionId,
+            executionId: options.executionId,
+            requestId: options.requestId,
+            turnId: options.turnId,
+            intentArtifactHash: options.intentArtifact?.artifactHash,
+            queryPlanHash: options.queryPlan?.planHash,
             projectSignals: {
                 frameworks,
                 languages,
@@ -624,15 +633,70 @@ export class ContextEngine {
         }
         const intent = parseIntent(query);
         const taskType = intent.intent;
-        const combinedQuery = mergeQueries(query, expandQuery(query), options?.expandedTerms);
-        const targetAnchors = extractTargetAnchors(query);
+        const combinedQuery = options?.queryPlan?.code[0]?.query
+            ?? mergeQueries(query, expandQuery(query), options?.expandedTerms);
+        const explicitTargetAnchors = options?.intentArtifact?.targetAnchors ?? extractTargetAnchors(query);
+        const initialTaskPlan = buildRetrievalTaskPlan({
+            query,
+            parsedIntent: intent,
+            targetAnchors: explicitTargetAnchors,
+            activeSkill: options?.activeSkill,
+            command: options?.command,
+            authoritativeArtifact: options?.intentArtifact,
+        });
+        const projectRoot = this.cg.getProjectRoot?.() ?? process.cwd();
+        const logIdentity = {
+            projectRoot,
+            sessionId: options?.sessionId,
+            turnId: options?.turnId,
+            requestId: options?.requestId,
+            executionId: options?.executionId,
+            intentArtifactHash: options?.intentArtifact?.artifactHash,
+            queryPlanHash: options?.queryPlan?.planHash,
+        };
+        let artifactInventory = this.indexer
+            ? buildArtifactInventory({
+                codegraph: this.cg,
+                indexer: this.indexer,
+                query: combinedQuery,
+                explicitTargetAnchors,
+                action: initialTaskPlan.action,
+                identity: logIdentity,
+            })
+            : { entries: [], operationTargets: [], missingExplicitTargets: [], ambiguous: false };
+        const staleInventoryTargets = artifactInventory.operationTargets
+            .filter(entry => entry.freshness.exists && !entry.freshness.current)
+            .map(entry => entry.path);
+        if (this.indexer && staleInventoryTargets.length > 0) {
+            await this.indexer.ensureFilesCurrent(staleInventoryTargets, { refresh: true, timeoutMs: 5_000 });
+            artifactInventory = buildArtifactInventory({
+                codegraph: this.cg,
+                indexer: this.indexer,
+                query: combinedQuery,
+                explicitTargetAnchors,
+                action: initialTaskPlan.action,
+                identity: logIdentity,
+            });
+        }
+        const targetAnchors = [...new Set([
+                ...explicitTargetAnchors,
+                ...artifactInventory.operationTargets
+                    .filter(entry => entry.freshness.current)
+                    .map(entry => entry.path),
+            ])];
         const retrievalTaskPlan = buildRetrievalTaskPlan({
             query,
             parsedIntent: intent,
             targetAnchors,
             activeSkill: options?.activeSkill,
             command: options?.command,
+            authoritativeArtifact: options?.intentArtifact,
         });
+        if (artifactInventory.missingExplicitTargets.length > 0) {
+            warnings.push(`explicit-target-missing:${artifactInventory.missingExplicitTargets.length}`);
+        }
+        if (artifactInventory.ambiguous)
+            warnings.push('artifact-target-ambiguous');
         const timing = {};
         const t0 = Date.now();
         const [cgResult, knowledgeResult, memoryHits] = await Promise.all([
@@ -647,7 +711,10 @@ export class ContextEngine {
                     }),
                     new Promise((_, reject) => setTimeout(() => reject(new Error("buildContext timeout")), 15000)),
                 ]).catch((err) => {
-                    console.error("[devflow] cg.buildContext failed, falling back:", err.message);
+                    emitSemanticControlLog({
+                        event: 'context.build.degraded', identity: logIdentity, level: 'warn', timestamp: Date.now(),
+                        data: { stage: 'codegraph_context', reason: err.message, fallback: 'manual_pipeline' },
+                    });
                     return null;
                 })
                 : Promise.resolve(null),
@@ -655,7 +722,10 @@ export class ContextEngine {
                 this.searchKnowledgeWithStatus(combinedQuery, this.getKnowledgeSearchOptions(combinedQuery, 5, options, retrievalTaskPlan, maxTokens)),
                 new Promise((_, reject) => setTimeout(() => reject(new Error("knowledge timeout")), 5000)),
             ]).catch((err) => {
-                console.error("[devflow] knowledge.search timeout:", err.message);
+                emitSemanticControlLog({
+                    event: 'knowledge.search.degraded', identity: logIdentity, level: 'warn', timestamp: Date.now(),
+                    data: { reason: err.message, fallback: 'knowledge_empty' },
+                });
                 return { entries: [], warnings: [`knowledge-search-failed: ${err.message}`] };
             }),
             typeof this.memory.search === "function"
@@ -670,18 +740,23 @@ export class ContextEngine {
                     }),
                     new Promise((_, reject) => setTimeout(() => reject(new Error("memory timeout")), 5000)),
                 ]).catch((err) => {
-                    console.error("[devflow] memory.search timeout:", err.message);
+                    emitSemanticControlLog({
+                        event: 'memory.search.completed', identity: logIdentity, level: 'warn', timestamp: Date.now(),
+                        data: { status: 'degraded', reason: err.message, selected: 0, fallback: 'memory_empty' },
+                    });
                     return [];
                 })
                 : Promise.resolve([]),
         ]);
         timing["1_promise_all"] = Date.now() - t0;
-        console.error("[devflow:timing] Promise.all:", timing["1_promise_all"], "ms");
         const knowledgeHits = knowledgeResult.entries;
         if (knowledgeResult.warnings.length > 0)
             warnings.push(...knowledgeResult.warnings);
         if (!cgResult) {
-            console.error("[devflow] buildContext failed, falling back to manual pipeline");
+            emitSemanticControlLog({
+                event: 'context.build.degraded', identity: logIdentity, level: 'warn', timestamp: Date.now(),
+                data: { stage: 'codegraph_context', reason: 'context_unavailable', fallback: 'manual_pipeline' },
+            });
             const result = await this.buildTaskContextLegacy(query, options);
             result._devflow = { fallback: "buildContext-unavailable" };
             return result;
@@ -693,7 +768,10 @@ export class ContextEngine {
                 ctx = JSON.parse(cgResult);
             }
             catch {
-                console.error("[devflow] buildContext returned unparseable string, falling back");
+                emitSemanticControlLog({
+                    event: 'context.build.degraded', identity: logIdentity, level: 'warn', timestamp: Date.now(),
+                    data: { stage: 'codegraph_parse', reason: 'unparseable_context', fallback: 'manual_pipeline' },
+                });
                 return this.buildTaskContextLegacy(query, options);
             }
         }
@@ -702,6 +780,20 @@ export class ContextEngine {
         }
         ctx.nodes = Array.isArray(ctx.nodes) ? ctx.nodes : [];
         ctx.entryPoints = Array.isArray(ctx.entryPoints) ? ctx.entryPoints : [];
+        const inventoryNodeIds = new Set(ctx.nodes.map((node) => String(node.id ?? '')));
+        for (const target of artifactInventory.operationTargets.filter(entry => entry.freshness.current)) {
+            const nodes = this.cg.getNodesInFile(target.path)
+                .filter(node => node.kind !== 'file' && node.kind !== 'import');
+            for (const node of nodes) {
+                if (!inventoryNodeIds.has(node.id)) {
+                    ctx.nodes.push(node);
+                    inventoryNodeIds.add(node.id);
+                }
+            }
+            const root = nodes.find(node => target.symbols.includes(node.name)) ?? nodes[0];
+            if (root && !ctx.entryPoints.some((entry) => entry.id === root.id))
+                ctx.entryPoints.unshift(root);
+        }
         await this.applyTaskSymbolVectorRecall(ctx, combinedQuery, warnings);
         this.clearRecoveredSymbolWarning(warnings);
         // Fallback: direct searchNodes for query terms that buildContext may have missed
@@ -734,7 +826,6 @@ export class ContextEngine {
                 }
             }
         }
-        console.error("[devflow:timing] Fallback searchNodes loop:", Date.now() - tFallback, "ms");
         timing["2_fallback_loop"] = Date.now() - tFallback;
         const fileFreshnessByPath = new Map();
         if (this.indexer?.ensureFilesCurrent) {
@@ -765,6 +856,22 @@ export class ContextEngine {
         ctx.edges = edgeQuality.accepted;
         if (edgeQuality.rejected.length > 0) {
             warnings.push(`codegraph-relations-rejected:${edgeQuality.rejected.length}`);
+            emitSemanticControlLog({
+                event: 'codegraph.edge.rejected',
+                identity: logIdentity,
+                level: 'warn',
+                timestamp: Date.now(),
+                data: {
+                    rejectedCount: edgeQuality.rejected.length,
+                    reasons: countValues(edgeQuality.rejected.map(edge => edge.reason)),
+                    examples: edgeQuality.rejected.slice(0, 8).map(edge => ({
+                        kind: edge.kind,
+                        sourceFile: edge.sourceFile,
+                        targetFile: edge.targetFile,
+                        reason: edge.reason,
+                    })),
+                },
+            });
         }
         const tSnippet = Date.now();
         let allNodes = ctx.nodes ?? [];
@@ -813,6 +920,10 @@ export class ContextEngine {
         const optionalCandidates = new Map();
         const graphOptionalPaths = new Set();
         const queryTerms = combinedQuery.split(/\s+/).map(term => term.toLowerCase()).filter(term => term.length >= 3);
+        for (const target of artifactInventory.operationTargets) {
+            if (target.freshness.current)
+                requiredFileSet.add(target.path);
+        }
         for (const node of allNodes) {
             // Skip file wrappers and import edges — they're not actionable symbols
             if (node.kind === "file" || node.kind === "import")
@@ -867,6 +978,16 @@ export class ContextEngine {
             }
         }
         const fileRoleByPath = new Map();
+        for (const artifact of artifactInventory.entries.filter(entry => entry.freshness.current)) {
+            fileRoleByPath.set(artifact.path, {
+                path: artifact.path,
+                role: artifact.artifactRole === 'operation_target' ? 'target' : 'dependency',
+                artifactRole: artifact.artifactRole,
+                score: artifact.score,
+                evidence: artifact.evidence,
+            });
+            fileFreshnessByPath.set(artifact.path, artifact.freshness);
+        }
         const roleCandidates = this.indexer
             ? assembleContextFileRoles({
                 codegraph: this.cg,
@@ -879,7 +1000,10 @@ export class ContextEngine {
             if (this.indexer?.getFileFreshness) {
                 fileFreshnessByPath.set(candidate.path, this.indexer.getFileFreshness(candidate.path));
             }
-            fileRoleByPath.set(candidate.path, candidate);
+            const inventoryRole = fileRoleByPath.get(candidate.path);
+            fileRoleByPath.set(candidate.path, inventoryRole && inventoryRole.score >= candidate.score
+                ? inventoryRole
+                : candidate);
             if (candidate.role === 'target') {
                 requiredFileSet.add(candidate.path);
                 continue;
@@ -979,7 +1103,6 @@ export class ContextEngine {
         const compressed = compressToTokenLimit(allFileSnippets, Math.floor(maxTokens * 0.45));
         if (compressed.overBudget)
             warnings.push("context-compressor-budget-exceeded");
-        console.error("[devflow:timing] Snippet building + compress:", Date.now() - tSnippet, "ms");
         timing["3_snippet_compress"] = Date.now() - tSnippet;
         const riskHints = generateRiskHints(allNodes.filter(node => node.kind !== "file" && node.kind !== "import"), graphEvidence);
         const nextActions = generateNextActions(taskType, keySymbols.slice(0, 5));
@@ -1108,6 +1231,9 @@ export class ContextEngine {
             requestId: options?.requestId,
             host: options?.host,
             command: options?.command,
+            turnId: options?.turnId,
+            intentArtifact: options?.intentArtifact,
+            queryPlan: options?.queryPlan,
             tokenBudget: maxTokens,
             targetAnchors,
             taskPlan: retrievalTaskPlan,
@@ -1152,7 +1278,23 @@ export class ContextEngine {
             this.queryCache.set(cacheKey, result);
         }
         timing["0_total"] = Date.now() - t0;
-        console.error("[devflow:timing] buildTaskContext TOTAL:", timing["0_total"], "ms");
+        emitSemanticControlLog({
+            event: 'codegraph.selection.completed',
+            identity: {
+                ...logIdentity,
+                contextReceipt: result.taskEnvelope?.receipt.contextHash,
+            },
+            level: warnings.length > 0 ? 'warn' : 'info',
+            timestamp: Date.now(),
+            data: {
+                selectedFiles: result.taskEnvelope?.code.files.length ?? 0,
+                selectedSymbols: result.taskEnvelope?.code.symbols.length ?? 0,
+                rejectedRelations: result.taskEnvelope?.quality.code.rejected ?? 0,
+                ambiguityCount: result.taskEnvelope?.code.ambiguities?.length ?? 0,
+                timing,
+                warnings: warnings.map(value => value.split(':')[0]),
+            },
+        });
         result._timing = timing;
         return result;
     }
@@ -1487,6 +1629,9 @@ export class ContextEngine {
             requestId: options?.requestId,
             host: options?.host,
             command: options?.command,
+            turnId: options?.turnId,
+            intentArtifact: options?.intentArtifact,
+            queryPlan: options?.queryPlan,
             tokenBudget: maxTokens,
             targetAnchors,
             fileRoles: fileRoleByPath,
@@ -1586,4 +1731,10 @@ function getGroupFilePaths(group) {
         return group;
     return group?.files ?? [];
 }
+function countValues(values) {
+    const counts = {};
+    for (const value of values)
+        counts[value] = (counts[value] ?? 0) + 1;
+    return counts;
+}
 //# sourceMappingURL=context-engine.js.map