@ngockhoale/ukit 3.5.2 → 3.5.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +38 -90
- package/README.md +1 -0
- package/manifests/documentation.yaml +12 -1
- package/manifests/platform.full.yaml +12 -0
- package/package.json +34 -1
- package/src/cli/commands/doctor.js +55 -2
- package/src/cli/commands/indexTools.js +10 -4
- package/src/cli/commands/memory.js +107 -8
- package/src/core/memory/episodes.js +106 -7
- package/src/core/memory/memoryCheck.js +241 -0
- package/src/core/memory/memoryCheckRun.js +27 -0
- package/src/core/memory/memoryHit.js +2 -0
- package/src/core/memory/mutateMemory.js +46 -1
- package/src/core/memory/observations.js +192 -0
- package/src/core/memory/projectIdentity.js +9 -2
- package/src/core/memory/recallEngine.js +204 -9
- package/src/core/memory/records.js +23 -0
- package/src/core/memory/registryPrune.js +230 -0
- package/src/core/memory/retrieval.js +12 -3
- package/src/core/memory/writeGate.js +137 -0
- package/src/core/runtimeConfig.js +12 -2
- package/src/index/buildIndex.js +26 -0
- package/src/index/paths.js +3 -1
- package/src/index/queryIndex.js +372 -26
- package/src/index/resolveContext.js +1 -1
- package/template_project/.claude/hooks/edit-hint.mjs +64 -17
- package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
- package/template_project/.claude/hooks/session-episode.sh +9 -4
- package/template_project/.claude/settings.json +2 -2
- package/template_project/.claude/ukit/index/edit-graph.mjs +141 -11
- package/template_project/.claude/ukit/index/lib/index-core.mjs +400 -27
- package/template_project/.claude/ukit/index/query-index.mjs +14 -3
- package/template_project/.claude/ukit/index/resolve-context.mjs +1 -1
- package/template_project/.claude/ukit/index/route-task.mjs +8 -2
- package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
- package/template_project/.claude/ukit/runtime/memory-lanes.mjs +44 -22
- package/template_project/.claude/ukit/runtime/memory-recall.mjs +204 -9
- package/template_project/.claude/ukit/runtime/memory-validity.mjs +259 -0
- package/template_project/.claude/ukit/runtime/reinject-context.mjs +4 -2
- package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
- package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
- package/template_project/ukit/storage/config.json +4 -2
- package/src/core/agentRuntime/completionGate.js +0 -179
- package/src/core/agentRuntime/context.js +0 -571
- package/src/core/agentRuntime/qualityComparison.js +0 -112
- package/src/core/agentRuntime/resourcePolicy.js +0 -78
- package/src/core/agentRuntime/runtimeSupport.js +0 -255
- package/src/core/codeintel/manifest.js +0 -176
- package/src/core/experiments/deliberation.js +0 -327
- package/src/core/experiments/dynamicWorkflow.js +0 -507
- package/src/core/handoffDocValidator.js +0 -154
- package/src/core/memory/deltaOverlays.js +0 -493
- package/src/core/memory/learningCandidates.js +0 -347
- package/src/core/observability/emit/sessionBoot.js +0 -407
- package/src/core/observability/evaluation/experimentPlan.js +0 -95
- package/src/core/observability/evaluation/perturbation.js +0 -273
- package/src/core/observability/evaluation/replay.js +0 -149
- package/src/core/observability/evaluation/scorecard.js +0 -465
- package/src/core/observability/schema/compatibility.js +0 -180
- package/src/core/observability/support/renderer.js +0 -130
- package/src/core/reviewPanelAggregate.js +0 -204
- package/src/core/taskBudgetValidator.js +0 -251
- package/src/core/taskProgressGuard.js +0 -227
- package/src/decision/reviewVerdict.js +0 -339
- package/src/decision/runtimeFilter.js +0 -150
- package/src/decision/runtimeScheduler.js +0 -239
- package/src/diagnostics/classifyHang.js +0 -246
- package/src/diagnostics/ompStallSnapshot.js +0 -199
- package/src/index/contextPack.js +0 -285
- package/src/index/impactContext.js +0 -360
- package/src/index/reviewPolicy.js +0 -368
- package/src/index/sensitivePath.js +0 -21
- package/src/render/instructionRenderer.js +0 -290
- package/src/skill/auditSkill.js +0 -140
- package/template_project/instructions/overlays/repo.md +0 -9
|
@@ -1,199 +0,0 @@
|
|
|
1
|
-
// Development-only incident capture: bounded metadata, no session control or payload persistence.
|
|
2
|
-
import fs from 'node:fs/promises';
|
|
3
|
-
import { constants } from 'node:fs';
|
|
4
|
-
import { spawn } from 'node:child_process';
|
|
5
|
-
|
|
6
|
-
const ID_PATTERN = /^[\w.:/-]{1,120}$/;
|
|
7
|
-
const id = (value) => typeof value === 'string' && ID_PATTERN.test(value) ? value : null;
|
|
8
|
-
const time = (value) => Number.isFinite(Date.parse(value)) ? new Date(value).toISOString() : null;
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
export async function runBoundedProcess(command, args = [], { timeoutMs = 650, maxBuffer = 65536 } = {}) {
|
|
12
|
-
return new Promise((resolve) => {
|
|
13
|
-
let settled = false;
|
|
14
|
-
let timedOut = false;
|
|
15
|
-
let oversized = false;
|
|
16
|
-
let stdoutBytes = 0;
|
|
17
|
-
let stderrBytes = 0;
|
|
18
|
-
const stdout = [];
|
|
19
|
-
const stderr = [];
|
|
20
|
-
let timer;
|
|
21
|
-
const finish = (result) => { if (!settled) { settled = true; clearTimeout(timer); resolve(result); } };
|
|
22
|
-
let child;
|
|
23
|
-
try { child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true }); }
|
|
24
|
-
catch (error) { resolve({ ok: false, errorCode: error.code || 'UNKNOWN', stdout: '', stderr: '' }); return; }
|
|
25
|
-
timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, Math.max(1, timeoutMs));
|
|
26
|
-
const collect = (chunks, field) => (chunk) => {
|
|
27
|
-
const next = field === 'stdout' ? stdoutBytes + chunk.length : stderrBytes + chunk.length;
|
|
28
|
-
if (next + (field === 'stdout' ? stderrBytes : stdoutBytes) > maxBuffer) { oversized = true; child.kill('SIGKILL'); return; }
|
|
29
|
-
chunks.push(chunk);
|
|
30
|
-
if (field === 'stdout') stdoutBytes = next; else stderrBytes = next;
|
|
31
|
-
};
|
|
32
|
-
child.stdout.on('data', collect(stdout, 'stdout'));
|
|
33
|
-
child.stderr.on('data', collect(stderr, 'stderr'));
|
|
34
|
-
child.on('error', (error) => finish({ ok: false, errorCode: error.code || 'UNKNOWN', stdout: '', stderr: '' }));
|
|
35
|
-
child.on('close', (code) => finish({ ok: !timedOut && !oversized && code === 0,
|
|
36
|
-
errorCode: timedOut ? 'ETIMEDOUT' : oversized ? 'MAXBUFFER' : code === 0 ? null : 'EXIT_NONZERO',
|
|
37
|
-
exitCode: code, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') }));
|
|
38
|
-
});
|
|
39
|
-
}
|
|
40
|
-
|
|
41
|
-
export async function readBoundedTail(file, { maxBytes = 262144 } = {}) {
|
|
42
|
-
const cap = Math.max(1, Math.min(1048576, maxBytes));
|
|
43
|
-
const handle = await fs.open(file, constants.O_RDONLY | (constants.O_NONBLOCK || 0) | (constants.O_NOFOLLOW || 0));
|
|
44
|
-
try {
|
|
45
|
-
const stat = await handle.stat();
|
|
46
|
-
if (!stat.isFile()) throw new Error('capture requires a regular file');
|
|
47
|
-
const size = Math.min(cap, stat.size);
|
|
48
|
-
const buffer = Buffer.alloc(size);
|
|
49
|
-
const { bytesRead } = await handle.read(buffer, 0, size, Math.max(0, stat.size - size));
|
|
50
|
-
let text = buffer.subarray(0, bytesRead).toString('utf8');
|
|
51
|
-
const truncated = stat.size > size;
|
|
52
|
-
if (truncated) text = text.includes('\n') ? text.slice(text.indexOf('\n') + 1) : '';
|
|
53
|
-
return { text, bytesRead, truncated, size: stat.size, modifiedAt: stat.mtimeMs };
|
|
54
|
-
} finally { await handle.close(); }
|
|
55
|
-
}
|
|
56
|
-
|
|
57
|
-
const operationKinds = ['model', 'tool', 'hook', 'subagent'];
|
|
58
|
-
const activeStates = new Set(['started', 'running', 'pending', 'waiting']);
|
|
59
|
-
const terminalStates = new Set(['completed', 'finished', 'failed', 'stopped', 'cancelled']);
|
|
60
|
-
export function processInventoryCommand(platform) {
|
|
61
|
-
return platform === 'win32' ? ['tasklist', ['/FO', 'CSV', '/NH']]
|
|
62
|
-
: ['ps', ['-A', '-o', 'pid=,ppid=,stat=,etime=,comm=']];
|
|
63
|
-
}
|
|
64
|
-
|
|
65
|
-
export function parseProcessInventory(platform, text) {
|
|
66
|
-
if (platform === 'win32') return text.split(/\r?\n/).flatMap((line) => {
|
|
67
|
-
const fields = line.match(/"(?:[^"]|"")*"|[^,]+/g) || [];
|
|
68
|
-
const name = fields[0]?.replace(/^"|"$/g, '').replace(/""/g, '"');
|
|
69
|
-
const pid = Number(fields[1]?.replaceAll('"', ''));
|
|
70
|
-
return Number.isSafeInteger(pid) && pid > 0 ? [{ pid, name: (name || '').split(/[\\/]/).at(-1) }] : [];
|
|
71
|
-
});
|
|
72
|
-
return text.split('\n').flatMap((line) => {
|
|
73
|
-
const match = line.match(/^\s*(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+(.+)$/);
|
|
74
|
-
return match ? [{ pid: Number(match[1]), name: match[5].trim().split(/[\\/]/).at(-1) }] : [];
|
|
75
|
-
});
|
|
76
|
-
}
|
|
77
|
-
|
|
78
|
-
export function parseOwnerPids(command, text) {
|
|
79
|
-
const values = command === 'fuser' ? (text.match(/:\s*([^\r\n]+)/g) || []).flatMap((line) => line.slice(line.indexOf(':') + 1).trim().split(/\s+/).map((token) => token.match(/^(\d+)[A-Za-z]*$/)?.[1]).filter(Boolean))
|
|
80
|
-
: (text.match(/\b\d+\b/g) || []);
|
|
81
|
-
return [...new Set(values.map(Number).filter((pid) => Number.isSafeInteger(pid) && pid > 0))];
|
|
82
|
-
}
|
|
83
|
-
|
|
84
|
-
export function classifySessionActivity({ association = 'NOT_OBSERVABLE', summary = null, now = Date.now(), idleMs = 120000 } = {}) {
|
|
85
|
-
if (summary?.operatorBlock === 'OBSERVED_BLOCK') return 'OPERATOR_BLOCK';
|
|
86
|
-
if (summary?.sessionState === 'STOPPED') return 'STOPPED';
|
|
87
|
-
if (association !== 'ACTIVE_OWNER' || !summary) return 'NOT_OBSERVABLE';
|
|
88
|
-
const progressAge = Number.isFinite(summary.lastProgressAt) ? Math.max(0, now - summary.lastProgressAt) : null;
|
|
89
|
-
const outputAge = Number.isFinite(summary.lastOutputAt) ? Math.max(0, now - summary.lastOutputAt) : null;
|
|
90
|
-
const pending = summary.pendingOperations || {};
|
|
91
|
-
if (progressAge === null) return 'NOT_OBSERVABLE';
|
|
92
|
-
if (progressAge >= idleMs) return 'SUSPECTED_STALL';
|
|
93
|
-
if (Object.values(pending).some((items) => Array.isArray(items) && items.length > 0)
|
|
94
|
-
&& Object.entries(pending).some(([kind, items]) => items.length > 0 && summary.operationObservability?.[kind] === 'OBSERVED')) return 'WAITING';
|
|
95
|
-
if (outputAge !== null && outputAge >= idleMs) return 'NO_OUTPUT';
|
|
96
|
-
return 'ACTIVE_PROGRESS';
|
|
97
|
-
}
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
export function summarizeSessionTail(text) {
|
|
101
|
-
const result = { sessionId: null, modelAlias: 'NOT_OBSERVABLE', resolvedRoute: 'NOT_OBSERVABLE', currentTurn: 'NOT_OBSERVABLE', lastCompletedTurn: 'NOT_OBSERVABLE',
|
|
102
|
-
pendingModelRequest: 'NOT_OBSERVABLE', lastChunk: 'NOT_OBSERVABLE', terminalEvent: 'NOT_OBSERVABLE', pendingTools: [], unmatchedToolCallCandidates: [], pendingSubagent: 'NOT_OBSERVABLE',
|
|
103
|
-
pendingOperations: { model: [], tool: [], hook: [], subagent: [] }, operationObservability: { model: 'NOT_OBSERVABLE', tool: 'NOT_OBSERVABLE', hook: 'NOT_OBSERVABLE', subagent: 'NOT_OBSERVABLE' },
|
|
104
|
-
operatorBlock: 'NOT_OBSERVABLE', turnState: 'NOT_OBSERVABLE', sessionState: 'NOT_OBSERVABLE', compaction: 'NOT_OBSERVABLE', stopContinuation: 'NOT_OBSERVABLE',
|
|
105
|
-
lastProgressAt: 'NOT_OBSERVABLE', lastOutputAt: 'NOT_OBSERVABLE', outputState: 'NOT_OBSERVABLE' };
|
|
106
|
-
const operations = Object.fromEntries(operationKinds.map((kind) => [kind, new Map()]));
|
|
107
|
-
const tools = new Map();
|
|
108
|
-
const observedOperations = new Set();
|
|
109
|
-
const operatorBlocks = new Map();
|
|
110
|
-
for (const line of text.split('\n')) {
|
|
111
|
-
let row;
|
|
112
|
-
try { row = JSON.parse(line); } catch { continue; }
|
|
113
|
-
const ts = time(row.timestamp);
|
|
114
|
-
if (ts) result.lastProgressAt = Date.parse(ts);
|
|
115
|
-
if (row.type === 'session' && id(row.id)) { result.sessionId = id(row.id); result.sessionIdentityObserved = true; }
|
|
116
|
-
if (row.type === 'compaction') result.compaction = { timestamp: ts, id: id(row.id), tokensBefore: Number.isFinite(row.tokensBefore) ? row.tokensBefore : null };
|
|
117
|
-
if (row.type === 'session_end' || row.type === 'session_stopped') result.sessionState = 'STOPPED';
|
|
118
|
-
|
|
119
|
-
if (row.type === 'operation' && operationKinds.includes(row.operation) && id(row.id)) {
|
|
120
|
-
observedOperations.add(row.operation);
|
|
121
|
-
const state = typeof row.state === 'string' ? row.state.toLowerCase() : '';
|
|
122
|
-
if (activeStates.has(state)) operations[row.operation].set(row.id, { id: row.id, ...(id(row.name) ? { name: id(row.name) } : {}) });
|
|
123
|
-
if (terminalStates.has(state)) operations[row.operation].delete(row.id);
|
|
124
|
-
}
|
|
125
|
-
const eventState = String(row.state || '').toLowerCase();
|
|
126
|
-
if (row.type === 'operator_block' || row.operation === 'operator') {
|
|
127
|
-
const key = id(row.id) || `block-${operatorBlocks.size}`;
|
|
128
|
-
if (['pending', 'blocked', 'waiting'].includes(eventState)) operatorBlocks.set(key, { id: id(row.id), state: 'BLOCKED' });
|
|
129
|
-
if (terminalStates.has(eventState) || ['unblocked', 'cleared'].includes(eventState)) operatorBlocks.delete(key);
|
|
130
|
-
}
|
|
131
|
-
|
|
132
|
-
const message = row.message;
|
|
133
|
-
if (!message) continue;
|
|
134
|
-
if (message.role === 'toolResult' && id(message.toolCallId)) tools.delete(message.toolCallId);
|
|
135
|
-
if (message.role !== 'assistant') continue;
|
|
136
|
-
result.modelAlias = { provider: id(message.provider), model: id(message.model) };
|
|
137
|
-
if (message.stopReason) {
|
|
138
|
-
const stopReason = ['stop', 'toolUse', 'error', 'aborted', 'length'].includes(message.stopReason) ? message.stopReason : 'other';
|
|
139
|
-
result.lastCompletedTurn = { id: id(row.id), timestamp: ts, stopReason };
|
|
140
|
-
result.terminalEvent = stopReason;
|
|
141
|
-
result.turnState = message.stopReason === 'aborted' ? 'TURN_ABORTED' : message.stopReason === 'error' ? 'TURN_ERROR' : 'TURN_COMPLETED';
|
|
142
|
-
}
|
|
143
|
-
if (Array.isArray(message.content)) {
|
|
144
|
-
for (const part of message.content) {
|
|
145
|
-
if (part.type === 'toolCall' && id(part.id)) tools.set(part.id, { id: id(part.id), name: id(part.name) });
|
|
146
|
-
if (part.type === 'text' && ts) {
|
|
147
|
-
result.lastOutputAt = Date.parse(ts);
|
|
148
|
-
result.outputState = 'OBSERVED_OUTPUT';
|
|
149
|
-
}
|
|
150
|
-
}
|
|
151
|
-
}
|
|
152
|
-
}
|
|
153
|
-
result.unmatchedToolCallCandidates = [...tools.values()].slice(-32);
|
|
154
|
-
result.pendingOperations = Object.fromEntries(operationKinds.map((kind) => [kind, [...operations[kind].values()].slice(-32)]));
|
|
155
|
-
result.pendingTools = result.pendingOperations.tool;
|
|
156
|
-
result.operationObservability = Object.fromEntries(operationKinds.map((kind) => [kind, observedOperations.has(kind) || (kind === 'tool' && tools.size > 0) ? 'OBSERVED' : 'NOT_OBSERVABLE']));
|
|
157
|
-
result.pendingModelRequest = result.operationObservability.model === 'OBSERVED' ? (result.pendingOperations.model.length ? 'OBSERVED_PENDING_EVENT' : 'NO_PENDING_EVENT_OBSERVED') : 'NOT_OBSERVABLE';
|
|
158
|
-
result.pendingSubagent = result.operationObservability.subagent === 'OBSERVED' ? (result.pendingOperations.subagent.length ? 'OBSERVED_PENDING_EVENT' : 'NO_PENDING_EVENT_OBSERVED') : 'NOT_OBSERVABLE';
|
|
159
|
-
result.operatorBlock = operatorBlocks.size ? 'OBSERVED_BLOCK' : 'NOT_OBSERVABLE';
|
|
160
|
-
return result;
|
|
161
|
-
}
|
|
162
|
-
|
|
163
|
-
export function associateSessionEvidence({ sessions = [], ownerLocks = {}, processInventory = { state: 'NOT_OBSERVABLE', processes: [] }, logs = [] } = {}) {
|
|
164
|
-
const sessionCounts = new Map();
|
|
165
|
-
for (const session of sessions) if (id(session.sessionId)) sessionCounts.set(session.sessionId, (sessionCounts.get(session.sessionId) || 0) + 1);
|
|
166
|
-
return sessions.map((session) => {
|
|
167
|
-
const sessionId = id(session.sessionId);
|
|
168
|
-
const lock = sessionId ? ownerLocks[sessionId] : null;
|
|
169
|
-
const lockState = lock?.state || 'NOT_OBSERVABLE';
|
|
170
|
-
const pids = lockState === 'OBSERVED' && Array.isArray(lock.pids) ? [...new Set(lock.pids.filter((pid) => Number.isSafeInteger(pid) && pid > 0))] : [];
|
|
171
|
-
const uniqueOwnerPid = pids.length === 1 ? pids[0] : null;
|
|
172
|
-
const duplicateSession = sessionId !== null && sessionCounts.get(sessionId) > 1;
|
|
173
|
-
const process = uniqueOwnerPid !== null && processInventory.state === 'OBSERVED'
|
|
174
|
-
? processInventory.processes.find((entry) => entry.pid === uniqueOwnerPid && /^omp(?:\.exe)?$/i.test(entry.name)) || null : null;
|
|
175
|
-
const processAssociation = duplicateSession ? 'AMBIGUOUS_TRANSCRIPT' : pids.length > 1 ? 'AMBIGUOUS_OWNER_LOCK'
|
|
176
|
-
: uniqueOwnerPid === null ? (lockState === 'NOT_OBSERVABLE' ? 'NOT_OBSERVABLE' : 'UNHELD')
|
|
177
|
-
: processInventory.state !== 'OBSERVED' ? 'NOT_OBSERVABLE' : process ? 'VERIFIED' : 'PID_NOT_FOUND';
|
|
178
|
-
const ownerPid = duplicateSession ? null : uniqueOwnerPid;
|
|
179
|
-
const identityVerified = session?.sessionIdentityObserved === true || session?.sourceCoverage?.sessionIdentityObserved === true;
|
|
180
|
-
const ompLog = ownerPid === null ? null : logs.find((entry) => entry.pid === ownerPid) || null;
|
|
181
|
-
const logAssociation = ownerPid === null ? 'NOT_OBSERVABLE' : ompLog ? 'VERIFIED' : 'NOT_OBSERVABLE';
|
|
182
|
-
return { sessionId, transcript: typeof session.transcriptPath === 'string' ? session.transcriptPath.split(/[\\/]/).at(-1) : null,
|
|
183
|
-
sessionAssociation: identityVerified && processAssociation === 'VERIFIED' && logAssociation === 'VERIFIED' ? 'ACTIVE_OWNER' : 'NOT_OBSERVABLE',
|
|
184
|
-
ownerLockState: duplicateSession ? 'AMBIGUOUS_TRANSCRIPT' : lockState, ownerPid, processAssociation, logAssociation, identityVerified,
|
|
185
|
-
process: process ? { pid: process.pid, name: id(process.name) } : null, ompLog };
|
|
186
|
-
});
|
|
187
|
-
}
|
|
188
|
-
|
|
189
|
-
export function buildStallSnapshot({ now = Date.now(), lastProgressAt = null, lastOutputAt = null, idleMs = 120000, executionState = 'NOT_OBSERVABLE', ...evidence } = {}) {
|
|
190
|
-
const age = (ts) => Number.isFinite(ts) ? Math.max(0, now - ts) : null;
|
|
191
|
-
const progressAgeMs = age(lastProgressAt);
|
|
192
|
-
const outputAgeMs = age(lastOutputAt);
|
|
193
|
-
const activity = evidence.activity || (executionState === 'NO_EXECUTION' ? 'NO_EXECUTION'
|
|
194
|
-
: executionState !== 'EXECUTING' ? 'NOT_OBSERVABLE'
|
|
195
|
-
: progressAgeMs === null ? 'NOT_OBSERVABLE' : progressAgeMs >= idleMs ? 'NO_OBSERVED_PROGRESS'
|
|
196
|
-
: outputAgeMs !== null && outputAgeMs >= idleMs ? 'NO_OUTPUT' : 'RECENT_PROGRESS');
|
|
197
|
-
return { schemaVersion: 1, capturedAt: new Date(now).toISOString(), verdict: 'INSUFFICIENT_EVIDENCE', activity,
|
|
198
|
-
executionState, progressAgeMs, outputAgeMs, ...evidence };
|
|
199
|
-
}
|
package/src/index/contextPack.js
DELETED
|
@@ -1,285 +0,0 @@
|
|
|
1
|
-
import fs from 'node:fs/promises';
|
|
2
|
-
import path from 'node:path';
|
|
3
|
-
|
|
4
|
-
import { getArtifactPath, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, normalizeRelative } from './paths.js';
|
|
5
|
-
import { getFileOutline, queryCodeIndex } from './queryIndex.js';
|
|
6
|
-
import { inferRelatedTests } from './relatedTests.js';
|
|
7
|
-
import { discoverProjectFiles } from './buildIndex.js';
|
|
8
|
-
import { isSensitivePath } from './sensitivePath.js';
|
|
9
|
-
|
|
10
|
-
// TASK-B2 (PLAN-ENDUR-B §B2): deterministic, bounded context pack built from the
|
|
11
|
-
// existing index artifacts. No LLM, no network, no clock/random — the same
|
|
12
|
-
// inputs + the same index always serialize to byte-identical JSON.
|
|
13
|
-
//
|
|
14
|
-
// Contract notes (recorded in TASK-B2 Discussion):
|
|
15
|
-
// - `overBudget` (global constraint "flags overBudget instead of dropping a
|
|
16
|
-
// required item"): required entries (targets) are always admitted; if the
|
|
17
|
-
// admitted set alone violates maxBytes/maxFiles the pack says so honestly
|
|
18
|
-
// instead of silently dropping a target. `truncated` marks extras
|
|
19
|
-
// (related tests) dropped for budget — the pack then never exceeds the bounds.
|
|
20
|
-
// - `fallback: 'path-only'` is set when the index artifacts are missing/corrupt
|
|
21
|
-
// (whole pack is raw target paths) OR when any individual target could not be
|
|
22
|
-
// resolved through the index (that target is listed as a raw path).
|
|
23
|
-
// - `index` accepts preloaded `{ meta, files }` artifacts to override the disk
|
|
24
|
-
// reads used for targeting/fingerprint; symbol outlines still come from the
|
|
25
|
-
// on-disk symbols artifact via getFileOutline.
|
|
26
|
-
|
|
27
|
-
export const DEFAULT_MAX_BYTES = 12000;
|
|
28
|
-
export const DEFAULT_MAX_FILES = 8;
|
|
29
|
-
|
|
30
|
-
const TARGET_SCORE = 1000;
|
|
31
|
-
const RELATED_TEST_SCORE = 12;
|
|
32
|
-
const SYMBOL_QUERY_LIMIT = 3;
|
|
33
|
-
const RELATED_TEST_LIMIT = 6;
|
|
34
|
-
|
|
35
|
-
const REQUIRED_REASONS = new Set(['target', 'target-symbol', 'unresolved-target', 'path-only']);
|
|
36
|
-
|
|
37
|
-
/**
|
|
38
|
-
* Build a deterministic, bounded context pack from the existing index.
|
|
39
|
-
*
|
|
40
|
-
* @param {object} [options]
|
|
41
|
-
* @param {string} [options.rootDir] Project root (default: cwd).
|
|
42
|
-
* @param {string[]} [options.targets] Target paths or symbol names.
|
|
43
|
-
* @param {number} [options.maxBytes] Byte budget for the files payload (default 12000).
|
|
44
|
-
* @param {number} [options.maxFiles] File-count budget (default 8).
|
|
45
|
-
* @param {{meta?: object, files?: object}} [options.index] Preloaded meta/files artifacts.
|
|
46
|
-
* @returns {Promise<{ok: boolean, files: Array<{path: string, reason: string, outline: Array, bytes: number}>,
|
|
47
|
-
* truncated: boolean, overBudget: boolean, stale: boolean, fallback: 'path-only'|null,
|
|
48
|
-
* bytes: number, fingerprint: {fileCount: number, newestMtimeMs: number, digest: string|null}|null}>}
|
|
49
|
-
* Never throws: every failure mode degrades to `ok: true` with a degraded pack.
|
|
50
|
-
*/
|
|
51
|
-
export async function buildContextPack({
|
|
52
|
-
rootDir = process.cwd(),
|
|
53
|
-
targets = [],
|
|
54
|
-
maxBytes = DEFAULT_MAX_BYTES,
|
|
55
|
-
maxFiles = DEFAULT_MAX_FILES,
|
|
56
|
-
index = null,
|
|
57
|
-
} = {}) {
|
|
58
|
-
const absoluteRoot = path.resolve(rootDir);
|
|
59
|
-
const byteBudget = normalizeBudget(maxBytes, DEFAULT_MAX_BYTES);
|
|
60
|
-
const fileBudget = normalizeBudget(maxFiles, DEFAULT_MAX_FILES);
|
|
61
|
-
const requestedTargets = normalizeTargets(targets);
|
|
62
|
-
|
|
63
|
-
const [filesArtifact, metaArtifact] = await Promise.all([
|
|
64
|
-
index?.files ?? readJsonArtifact(absoluteRoot, INDEX_ARTIFACTS.files),
|
|
65
|
-
index?.meta ?? readJsonArtifact(absoluteRoot, INDEX_ARTIFACTS.meta),
|
|
66
|
-
]);
|
|
67
|
-
|
|
68
|
-
const indexUsable = isValidItemArtifact(filesArtifact) && isValidSchemaArtifact(metaArtifact);
|
|
69
|
-
const recordedFingerprint = normalizeRecordedFingerprint(metaArtifact?.sourceFingerprint);
|
|
70
|
-
|
|
71
|
-
// Staleness: compare meta.sourceFingerprint's file count / newest mtime to a
|
|
72
|
-
// fresh discovery enumeration. No auto refresh, no clock — pure comparison.
|
|
73
|
-
let stale = false;
|
|
74
|
-
if (indexUsable) {
|
|
75
|
-
if (!recordedFingerprint) {
|
|
76
|
-
stale = true;
|
|
77
|
-
} else {
|
|
78
|
-
const discovered = await discoverProjectFiles(absoluteRoot).catch(() => null);
|
|
79
|
-
stale = discovered
|
|
80
|
-
? isFingerprintStale(recordedFingerprint, fingerprintMetaFromEntries(absoluteRoot, discovered))
|
|
81
|
-
: true;
|
|
82
|
-
}
|
|
83
|
-
}
|
|
84
|
-
|
|
85
|
-
const candidates = [];
|
|
86
|
-
let anyUnresolved = false;
|
|
87
|
-
|
|
88
|
-
if (indexUsable) {
|
|
89
|
-
const indexedFileSet = new Set(
|
|
90
|
-
filesArtifact.items
|
|
91
|
-
.filter((item) => item && typeof item === 'object' && typeof item.filePath === 'string')
|
|
92
|
-
.map((item) => item.filePath),
|
|
93
|
-
);
|
|
94
|
-
|
|
95
|
-
let rank = 0;
|
|
96
|
-
const resolvedTargetPaths = [];
|
|
97
|
-
for (const target of requestedTargets) {
|
|
98
|
-
if (isSensitivePath(target)) {
|
|
99
|
-
rank += 1;
|
|
100
|
-
continue;
|
|
101
|
-
}
|
|
102
|
-
const score = Math.max(1, TARGET_SCORE - rank);
|
|
103
|
-
rank += 1;
|
|
104
|
-
|
|
105
|
-
const directPath = normalizeTargetPath(target);
|
|
106
|
-
if (indexedFileSet.has(directPath)) {
|
|
107
|
-
candidates.push({ path: directPath, reason: 'target', score });
|
|
108
|
-
resolvedTargetPaths.push(directPath);
|
|
109
|
-
continue;
|
|
110
|
-
}
|
|
111
|
-
|
|
112
|
-
const queryHits = await queryCodeIndex({ rootDir: absoluteRoot, query: target, limit: SYMBOL_QUERY_LIMIT })
|
|
113
|
-
.catch(() => []);
|
|
114
|
-
const bestHit = queryHits.find((hit) => hit?.filePath && !isSensitivePath(hit.filePath));
|
|
115
|
-
if (bestHit) {
|
|
116
|
-
candidates.push({ path: bestHit.filePath, reason: 'target-symbol', score });
|
|
117
|
-
resolvedTargetPaths.push(bestHit.filePath);
|
|
118
|
-
} else {
|
|
119
|
-
anyUnresolved = true;
|
|
120
|
-
candidates.push({ path: directPath, reason: 'unresolved-target', score });
|
|
121
|
-
}
|
|
122
|
-
}
|
|
123
|
-
|
|
124
|
-
const relatedTests = resolvedTargetPaths.length > 0
|
|
125
|
-
? await inferRelatedTests({ rootDir: absoluteRoot, candidateFiles: resolvedTargetPaths, limit: RELATED_TEST_LIMIT })
|
|
126
|
-
.catch(() => [])
|
|
127
|
-
: [];
|
|
128
|
-
for (const related of relatedTests) {
|
|
129
|
-
if (!related?.filePath || isSensitivePath(related.filePath)) {
|
|
130
|
-
continue;
|
|
131
|
-
}
|
|
132
|
-
candidates.push({ path: related.filePath, reason: 'related-test', score: RELATED_TEST_SCORE });
|
|
133
|
-
}
|
|
134
|
-
} else {
|
|
135
|
-
// Missing/corrupt index: path-only fallback listing the raw target paths.
|
|
136
|
-
anyUnresolved = requestedTargets.length > 0;
|
|
137
|
-
let rank = 0;
|
|
138
|
-
for (const target of requestedTargets) {
|
|
139
|
-
if (isSensitivePath(target)) {
|
|
140
|
-
rank += 1;
|
|
141
|
-
continue;
|
|
142
|
-
}
|
|
143
|
-
candidates.push({
|
|
144
|
-
path: normalizeTargetPath(target),
|
|
145
|
-
reason: 'path-only',
|
|
146
|
-
score: Math.max(1, TARGET_SCORE - rank),
|
|
147
|
-
});
|
|
148
|
-
rank += 1;
|
|
149
|
-
}
|
|
150
|
-
}
|
|
151
|
-
|
|
152
|
-
// Stable order: score desc, then path asc (plan §B2 acceptance).
|
|
153
|
-
candidates.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
|
|
154
|
-
|
|
155
|
-
const seenPaths = new Set();
|
|
156
|
-
const deduped = candidates.filter((candidate) => {
|
|
157
|
-
if (seenPaths.has(candidate.path)) {
|
|
158
|
-
return false;
|
|
159
|
-
}
|
|
160
|
-
seenPaths.add(candidate.path);
|
|
161
|
-
return true;
|
|
162
|
-
});
|
|
163
|
-
|
|
164
|
-
const withOutline = indexUsable;
|
|
165
|
-
const selected = [];
|
|
166
|
-
let usedBytes = 0;
|
|
167
|
-
for (const candidate of deduped.filter((entry) => REQUIRED_REASONS.has(entry.reason))) {
|
|
168
|
-
const entry = await materializeEntry(absoluteRoot, candidate, withOutline);
|
|
169
|
-
selected.push(entry);
|
|
170
|
-
usedBytes += entry.bytes;
|
|
171
|
-
}
|
|
172
|
-
|
|
173
|
-
let truncated = false;
|
|
174
|
-
for (const candidate of deduped.filter((entry) => !REQUIRED_REASONS.has(entry.reason))) {
|
|
175
|
-
const entry = await materializeEntry(absoluteRoot, candidate, withOutline);
|
|
176
|
-
if (selected.length >= fileBudget || usedBytes + entry.bytes > byteBudget) {
|
|
177
|
-
truncated = true;
|
|
178
|
-
continue;
|
|
179
|
-
}
|
|
180
|
-
selected.push(entry);
|
|
181
|
-
usedBytes += entry.bytes;
|
|
182
|
-
}
|
|
183
|
-
|
|
184
|
-
const overBudget = selected.length > fileBudget || usedBytes > byteBudget;
|
|
185
|
-
|
|
186
|
-
return {
|
|
187
|
-
ok: true,
|
|
188
|
-
files: selected,
|
|
189
|
-
truncated,
|
|
190
|
-
overBudget,
|
|
191
|
-
stale,
|
|
192
|
-
fallback: !indexUsable || anyUnresolved ? 'path-only' : null,
|
|
193
|
-
bytes: usedBytes,
|
|
194
|
-
fingerprint: recordedFingerprint,
|
|
195
|
-
};
|
|
196
|
-
}
|
|
197
|
-
|
|
198
|
-
function normalizeBudget(value, defaultValue) {
|
|
199
|
-
const parsed = Number(value);
|
|
200
|
-
return Number.isFinite(parsed) && parsed > 0 ? parsed : defaultValue;
|
|
201
|
-
}
|
|
202
|
-
|
|
203
|
-
function normalizeTargets(targets) {
|
|
204
|
-
const list = Array.isArray(targets) ? targets : [targets];
|
|
205
|
-
const seen = new Set();
|
|
206
|
-
const normalized = [];
|
|
207
|
-
for (const raw of list) {
|
|
208
|
-
const value = String(raw ?? '').trim();
|
|
209
|
-
if (!value || seen.has(value)) {
|
|
210
|
-
continue;
|
|
211
|
-
}
|
|
212
|
-
seen.add(value);
|
|
213
|
-
normalized.push(value);
|
|
214
|
-
}
|
|
215
|
-
return normalized;
|
|
216
|
-
}
|
|
217
|
-
|
|
218
|
-
function normalizeTargetPath(target) {
|
|
219
|
-
return String(target ?? '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
|
|
220
|
-
}
|
|
221
|
-
|
|
222
|
-
async function materializeEntry(absoluteRoot, candidate, withOutline) {
|
|
223
|
-
const outline = withOutline
|
|
224
|
-
? await getFileOutline({ rootDir: absoluteRoot, filePath: candidate.path }).catch(() => [])
|
|
225
|
-
: [];
|
|
226
|
-
const row = { path: candidate.path, reason: candidate.reason, outline, bytes: 0 };
|
|
227
|
-
row.bytes = Buffer.byteLength(JSON.stringify({ path: row.path, reason: row.reason, outline }));
|
|
228
|
-
return row;
|
|
229
|
-
}
|
|
230
|
-
|
|
231
|
-
async function readJsonArtifact(rootDir, artifactName) {
|
|
232
|
-
try {
|
|
233
|
-
const content = await fs.readFile(getArtifactPath(rootDir, artifactName), 'utf8');
|
|
234
|
-
return JSON.parse(content);
|
|
235
|
-
} catch {
|
|
236
|
-
return null;
|
|
237
|
-
}
|
|
238
|
-
}
|
|
239
|
-
|
|
240
|
-
// Same gate queryIndex applies (C92-B-03): artifacts written under a different
|
|
241
|
-
// INDEX_SCHEMA_VERSION are treated as absent. Item artifacts (files.json) must
|
|
242
|
-
// carry an `items` array; meta.json has none, so schema currency is its only gate.
|
|
243
|
-
function isValidItemArtifact(artifact) {
|
|
244
|
-
return Boolean(
|
|
245
|
-
artifact
|
|
246
|
-
&& typeof artifact === 'object'
|
|
247
|
-
&& Array.isArray(artifact.items)
|
|
248
|
-
&& artifact.schemaVersion === INDEX_SCHEMA_VERSION,
|
|
249
|
-
);
|
|
250
|
-
}
|
|
251
|
-
|
|
252
|
-
function isValidSchemaArtifact(artifact) {
|
|
253
|
-
return Boolean(artifact && typeof artifact === 'object' && artifact.schemaVersion === INDEX_SCHEMA_VERSION);
|
|
254
|
-
}
|
|
255
|
-
|
|
256
|
-
function normalizeRecordedFingerprint(raw) {
|
|
257
|
-
if (!raw || typeof raw !== 'object') {
|
|
258
|
-
return null;
|
|
259
|
-
}
|
|
260
|
-
return {
|
|
261
|
-
fileCount: Number(raw.fileCount),
|
|
262
|
-
newestMtimeMs: Number(raw.newestMtimeMs),
|
|
263
|
-
digest: typeof raw.digest === 'string' ? raw.digest : null,
|
|
264
|
-
};
|
|
265
|
-
}
|
|
266
|
-
|
|
267
|
-
function isFingerprintStale(recorded, current) {
|
|
268
|
-
return recorded.fileCount !== current.fileCount || recorded.newestMtimeMs !== current.newestMtimeMs;
|
|
269
|
-
}
|
|
270
|
-
|
|
271
|
-
// Mirrors createSourceFingerprint's normalization (buildIndex.js) for the two
|
|
272
|
-
// fields the plan's staleness contract compares: fileCount and newestMtimeMs.
|
|
273
|
-
function fingerprintMetaFromEntries(rootDir, entries) {
|
|
274
|
-
let fileCount = 0;
|
|
275
|
-
let newestMtimeMs = 0;
|
|
276
|
-
for (const entry of Array.isArray(entries) ? entries : []) {
|
|
277
|
-
const filePath = normalizeRelative(rootDir, entry?.absolutePath ?? '');
|
|
278
|
-
if (!filePath || filePath === '.' || filePath.startsWith('../') || path.isAbsolute(filePath)) {
|
|
279
|
-
continue;
|
|
280
|
-
}
|
|
281
|
-
fileCount += 1;
|
|
282
|
-
newestMtimeMs = Math.max(newestMtimeMs, Number(entry.mtimeMs ?? -1));
|
|
283
|
-
}
|
|
284
|
-
return { fileCount, newestMtimeMs };
|
|
285
|
-
}
|