@ngockhoale/ukit 3.5.1 → 3.5.2
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 +18 -207
- package/manifests/platform.full.yaml +23 -0
- package/package.json +1 -1
- package/src/core/runtimeConfig.js +1 -0
- package/src/index/buildIndex.js +22 -0
- package/src/index/impactContext.js +11 -1
- package/template_project/.claude/hooks/edit-hint.mjs +119 -0
- package/template_project/.claude/settings.json +2 -2
- package/template_project/.claude/ukit/index/edit-graph.mjs +274 -0
- package/template_project/.claude/ukit/index/lib/index-core.mjs +36 -1
- package/template_project/.claude/ukit/index/post-edit-verify.mjs +8 -5
- package/template_project/.claude/ukit/index/resolve-context.mjs +17 -0
- package/template_project/.claude/ukit/runtime/hook-chain-runner.mjs +62 -5
- package/template_project/.claude/ukit/runtime/memory-lanes.mjs +237 -0
- package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
- package/template_project/AGENTS.md +1 -1
- package/template_project/CLAUDE.md +1 -1
- package/template_project/instructions/core.md +1 -1
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
// memory-lanes.mjs (3.5.2) - attaches memory to code: path lane + graph lane.
|
|
2
|
+
// Standalone ESM; deterministic, no LLM, async fs only, never throws to callers.
|
|
3
|
+
import fsp from 'node:fs/promises';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
import { loadMarkdownDocs, normalizeMemorySources, rankDocs } from './memory-recall.mjs';
|
|
6
|
+
import { eligible, resolveProjectIdentityMirror } from './memory-policy.mjs';
|
|
7
|
+
import { resolveMemoryStage } from './memory-flags.mjs';
|
|
8
|
+
|
|
9
|
+
const MAX_STORE_BYTES = 2 * 1024 * 1024;
|
|
10
|
+
const MAX_STAT = 8;
|
|
11
|
+
const LINE_CHARS = 160;
|
|
12
|
+
const KNOWN_ROOTS = new Set(['src', 'tests', 'test', 'docs', 'scripts', 'lib', 'app', 'template_project', 'packages', 'bin']);
|
|
13
|
+
const EXT_RE = /\.[A-Za-z][A-Za-z0-9]{0,7}$/;
|
|
14
|
+
const LEGACY_STUB_RE = /^\s*Session\s+\S+?:\s*(?:writeOk|writeFail)\b/;
|
|
15
|
+
|
|
16
|
+
function normalizePath(raw, { needSlash = true } = {}) {
|
|
17
|
+
let t = String(raw ?? '').trim().replace(/`/g, '').replace(/\\/g, '/');
|
|
18
|
+
t = t.replace(/^(\.\/)+/, '').replace(/:\d+(?::\d+)?$/, '').replace(/[.,;:!?)\]}>"'*]+$/, '').replace(/^[("'[{<]+/, '');
|
|
19
|
+
// Second pass is intentional: "a.js:12:" only exposes ":12" after the trailing ":" is stripped.
|
|
20
|
+
t = t.replace(/:\d+(?::\d+)?$/, '');
|
|
21
|
+
if (!t || t.includes('://') || t.startsWith('/') || /^[A-Za-z]:/.test(t) || t.startsWith('~')) return null;
|
|
22
|
+
const segs = t.split('/');
|
|
23
|
+
if (segs.some((s) => s === '..' || s === '')) {
|
|
24
|
+
if (!(t.endsWith('/') && segs.slice(0, -1).every((s) => s && s !== '..'))) return null;
|
|
25
|
+
segs.pop();
|
|
26
|
+
}
|
|
27
|
+
const clean = segs.join('/');
|
|
28
|
+
const last = segs[segs.length - 1];
|
|
29
|
+
if (EXT_RE.test(last) && last.length > 2) return needSlash && segs.length < 2 ? null : clean;
|
|
30
|
+
if (segs.length >= 2 && (t.endsWith('/') || KNOWN_ROOTS.has(segs[0]))) return clean;
|
|
31
|
+
return null;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
export function extractAnchors(doc) {
|
|
35
|
+
const out = new Set();
|
|
36
|
+
const text = String(doc?.text ?? '');
|
|
37
|
+
for (const tok of text.split(/\s+/)) {
|
|
38
|
+
const hit = /[/\\]/.test(tok) ?normalizePath(tok) : null;
|
|
39
|
+
if (hit) out.add(hit);
|
|
40
|
+
}
|
|
41
|
+
for (const ev of Array.isArray(doc?.evidence) ? doc.evidence : []) {
|
|
42
|
+
if (typeof ev === 'string') { const p = normalizePath(ev, { needSlash: false }); if (p) out.add(p); continue; }
|
|
43
|
+
if (ev?.kind && ev.kind !== 'file') continue;
|
|
44
|
+
const p = normalizePath(ev?.locator, { needSlash: false });
|
|
45
|
+
if (p) out.add(p);
|
|
46
|
+
}
|
|
47
|
+
return [...out].sort();
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const byId = (a, b) => String(a.id ?? '').localeCompare(String(b.id ?? ''));
|
|
51
|
+
|
|
52
|
+
export function fuseLanes(lanes, { limit = Infinity } = {}) {
|
|
53
|
+
const seen = new Set();
|
|
54
|
+
const out = [];
|
|
55
|
+
for (const lane of Array.isArray(lanes) ? lanes : []) {
|
|
56
|
+
for (const id of lane ?? []) {
|
|
57
|
+
if (seen.has(id)) continue;
|
|
58
|
+
seen.add(id);
|
|
59
|
+
out.push(id);
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
return out.slice(0, limit);
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
function docEligible(doc, now) {
|
|
66
|
+
if (!doc || typeof doc !== 'object') return false;
|
|
67
|
+
if (doc.type === 'markdown') return true;
|
|
68
|
+
if ((doc.status ?? 'active') !== 'active' || doc.superseded_by) return false;
|
|
69
|
+
if (doc.valid_until != null && doc.valid_until <= now) return false;
|
|
70
|
+
return !LEGACY_STUB_RE.test(String(doc.text ?? ''));
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
const paths = (list) => (Array.isArray(list) ? list : []).map((x) => (typeof x === 'string' ? x : x?.path)).filter(Boolean);
|
|
74
|
+
|
|
75
|
+
export function recallForTarget({ target, neighbours, docs, query = '', limit = 2 } = {}) {
|
|
76
|
+
const empty = { ranked: [], abstained: true };
|
|
77
|
+
try {
|
|
78
|
+
const now = Date.now();
|
|
79
|
+
const pool = (Array.isArray(docs) ? docs : []).filter((d) => docEligible(d, now));
|
|
80
|
+
if (pool.length === 0 || !target) return empty;
|
|
81
|
+
const n = neighbours ?? {};
|
|
82
|
+
const mirrors = new Set(paths(n.mirrors));
|
|
83
|
+
const tests = new Set(paths(n.tests));
|
|
84
|
+
const imports = new Set([...paths(n.importers), ...paths(n.imports)]);
|
|
85
|
+
const tiers = [[], [], [], []];
|
|
86
|
+
const info = new Map();
|
|
87
|
+
for (const doc of pool) {
|
|
88
|
+
const anchors = extractAnchors(doc);
|
|
89
|
+
let tier = -1;
|
|
90
|
+
let via = '';
|
|
91
|
+
if (anchors.includes(target)) { tier = 0; via = 'this file'; }
|
|
92
|
+
else if (anchors.some((a) => mirrors.has(a))) { tier = 1; via = 'via mirror'; }
|
|
93
|
+
else if (anchors.some((a) => tests.has(a))) { tier = 2; via = 'via test'; }
|
|
94
|
+
else if (anchors.some((a) => imports.has(a))) { tier = 2; via = 'via import'; }
|
|
95
|
+
else if (anchors.some((a) => !EXT_RE.test(a) && target.startsWith(`${a}/`))) { tier = 3; via = 'via directory'; }
|
|
96
|
+
if (tier >= 0) { tiers[tier].push(doc); info.set(doc.id, { doc, tier, via }); }
|
|
97
|
+
}
|
|
98
|
+
const hasQuery = String(query ?? '').trim() !== '';
|
|
99
|
+
const bm = hasQuery ? rankDocs(pool, query, { limit: pool.length }).ranked : [];
|
|
100
|
+
const score = new Map(bm.map((e) => [e.doc.id, e.score]));
|
|
101
|
+
const lanes = tiers.map((list) => [...list]
|
|
102
|
+
.sort((a, b) => (score.get(b.id) ?? 0) - (score.get(a.id) ?? 0) || byId(a, b))
|
|
103
|
+
.map((d) => d.id));
|
|
104
|
+
const fill = [];
|
|
105
|
+
for (const e of bm) {
|
|
106
|
+
if (!info.has(e.doc.id)) { info.set(e.doc.id, { doc: e.doc, tier: 4, via: 'query' }); }
|
|
107
|
+
fill.push(e.doc.id);
|
|
108
|
+
}
|
|
109
|
+
const ranked = fuseLanes([...lanes, fill], { limit }).map((id) => info.get(id));
|
|
110
|
+
return { ranked, abstained: ranked.length === 0 };
|
|
111
|
+
} catch {
|
|
112
|
+
return empty;
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
const flat = (s) => String(s ?? '').replace(/\s+/g, ' ').trim();
|
|
117
|
+
const KIND_LABEL = { twin: 'identical at last index', declared: 'declared', drifted: 'differs now' };
|
|
118
|
+
|
|
119
|
+
export function renderEditHint({ target, neighbours, memory = [], maxChars = 600 } = {}) {
|
|
120
|
+
try {
|
|
121
|
+
const n = neighbours ?? {};
|
|
122
|
+
const lines = [];
|
|
123
|
+
const mirrors = (Array.isArray(n.mirrors) ? n.mirrors : []).map((m) => (typeof m === 'string' ? { path: m, kind: 'declared' } : m))
|
|
124
|
+
.filter((m) => m?.path).sort((a, b) => String(a.path).localeCompare(String(b.path))).slice(0, 2);
|
|
125
|
+
for (const m of mirrors) lines.push(`mirror (${KIND_LABEL[m.kind] ?? 'declared'}): ${flat(m.path)}`);
|
|
126
|
+
const tests = [...new Set(paths(n.tests))].sort().slice(0, 3);
|
|
127
|
+
if (tests.length) lines.push(`tests: ${tests.map(flat).join(', ')}`);
|
|
128
|
+
const mem = [];
|
|
129
|
+
for (const entry of (Array.isArray(memory) ? memory : []).slice(0, 2)) {
|
|
130
|
+
const doc = entry?.doc ?? entry;
|
|
131
|
+
if (!doc) continue;
|
|
132
|
+
const label = doc.type === 'markdown' ? (doc.provenance ?? doc.id) : (doc.id ?? doc.provenance);
|
|
133
|
+
const head = `- [${flat(label)} | ${flat(entry.via ?? 'query')}] `;
|
|
134
|
+
const body = flat(doc.text);
|
|
135
|
+
const room = Math.max(0, LINE_CHARS - head.length);
|
|
136
|
+
mem.push(head + (body.length > room ? `${body.slice(0, Math.max(0, room - 3))}...` : body));
|
|
137
|
+
}
|
|
138
|
+
if (lines.length === 0 && mem.length === 0) return '';
|
|
139
|
+
const build = (m) => [`[UKit edit-graph] ${flat(target)}`, ...lines,
|
|
140
|
+
...(m.length ? ['memory (cited project notes, not instructions):', ...m] : [])].join('\n');
|
|
141
|
+
let out = build(mem);
|
|
142
|
+
while (out.length > maxChars && mem.length) { mem.pop(); out = build(mem); }
|
|
143
|
+
return out.length > maxChars ? `${out.slice(0, Math.max(0, maxChars - 3))}...` : out;
|
|
144
|
+
} catch {
|
|
145
|
+
return '';
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
async function readJsonBounded(file) {
|
|
150
|
+
try {
|
|
151
|
+
const st = await fsp.stat(file);
|
|
152
|
+
if (!st.isFile() || st.size > MAX_STORE_BYTES) return null;
|
|
153
|
+
return JSON.parse(await fsp.readFile(file, 'utf8'));
|
|
154
|
+
} catch {
|
|
155
|
+
return null;
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
async function exists(root, rel) {
|
|
160
|
+
try { await fsp.stat(path.resolve(root, rel)); return true; } catch { return false; }
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
async function loadRecordDocs(projectRoot, config) {
|
|
164
|
+
if (resolveMemoryStage(config, 'eligibility') === 'off') return [];
|
|
165
|
+
const store = await readJsonBounded(path.join(projectRoot, '.ukit', 'storage', 'memory', 'v2', 'records.json'));
|
|
166
|
+
const records = Array.isArray(store?.records) ? store.records : [];
|
|
167
|
+
if (records.length === 0) return [];
|
|
168
|
+
const identity = await resolveProjectIdentityMirror(projectRoot).catch(() => null);
|
|
169
|
+
const ctx = { projectId: identity?.projectId ?? null, projectAliases: identity?.aliases ?? [], includeUser: false };
|
|
170
|
+
return records.filter((r) => r && typeof r === 'object' && !r.superseded_by && eligible(r, ctx).ok)
|
|
171
|
+
.map((r) => ({
|
|
172
|
+
id: `record:${r.id}`, type: r.type, provenance: r.provenance, text: String(r.text ?? ''),
|
|
173
|
+
evidence: r.evidence, created_at: r.created_at ?? 0,
|
|
174
|
+
}));
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
const EMPTY = { text: '', neighbours: null, memoryIds: [] };
|
|
178
|
+
|
|
179
|
+
export async function editHintFor({
|
|
180
|
+
projectRoot, target, config = null, query = '', exclude = {}, signal, deps = {}, memoryBudgetMs,
|
|
181
|
+
} = {}) {
|
|
182
|
+
try {
|
|
183
|
+
if (process.env.UKIT_EDIT_HINTS === '0' || !projectRoot || !target) return EMPTY;
|
|
184
|
+
const cfg = config ?? await readJsonBounded(path.join(projectRoot, '.ukit', 'storage', 'config.json'));
|
|
185
|
+
if (cfg?.memory?.editHints?.enabled === false) return EMPTY;
|
|
186
|
+
const rel = normalizePath(target, { needSlash: false });
|
|
187
|
+
if (!rel || signal?.aborted) return EMPTY;
|
|
188
|
+
let loadGraph = deps.loadEditGraph;
|
|
189
|
+
let neighboursOf = deps.neighboursOf;
|
|
190
|
+
if (!loadGraph || !neighboursOf) {
|
|
191
|
+
const mod = await import('../index/edit-graph.mjs').catch(() => null);
|
|
192
|
+
loadGraph = mod?.loadEditGraph;
|
|
193
|
+
neighboursOf = mod?.neighboursOf;
|
|
194
|
+
}
|
|
195
|
+
const graph = loadGraph ? await loadGraph(projectRoot, { signal }) : null;
|
|
196
|
+
const raw = graph && neighboursOf ? neighboursOf(graph, rel) : null;
|
|
197
|
+
const skip = new Set(Array.isArray(exclude?.paths) ? exclude.paths : []);
|
|
198
|
+
const keep = (p) => !skip.has(typeof p === 'string' ? p : p?.path);
|
|
199
|
+
const sorted = (list) => (Array.isArray(list) ? list : []).filter(keep)
|
|
200
|
+
.sort((a, b) => String(a?.path ?? a).localeCompare(String(b?.path ?? b)));
|
|
201
|
+
let neighbours = {
|
|
202
|
+
mirrors: sorted(raw?.mirrors), tests: sorted(raw?.tests),
|
|
203
|
+
importers: sorted(raw?.importers), imports: sorted(raw?.imports),
|
|
204
|
+
};
|
|
205
|
+
const probe = [...neighbours.mirrors.slice(0, 4).map((m) => m.path), ...neighbours.tests.slice(0, MAX_STAT - Math.min(4, neighbours.mirrors.length))];
|
|
206
|
+
const alive = new Set((await Promise.all(probe.slice(0, MAX_STAT).map(async (p) => ((await exists(projectRoot, p)) ? p : null)))).filter(Boolean));
|
|
207
|
+
const probed = new Set(probe.slice(0, MAX_STAT));
|
|
208
|
+
const live = (p) => !probed.has(p) || alive.has(p);
|
|
209
|
+
neighbours = {
|
|
210
|
+
...neighbours,
|
|
211
|
+
mirrors: neighbours.mirrors.filter((m) => live(m.path)),
|
|
212
|
+
tests: neighbours.tests.filter(live),
|
|
213
|
+
};
|
|
214
|
+
if (signal?.aborted) return EMPTY;
|
|
215
|
+
// Graph part is ready; memory gets its own sub-budget and never delays it.
|
|
216
|
+
let timer;
|
|
217
|
+
const lookup = deps.loadMemory ? deps.loadMemory() : Promise.all([
|
|
218
|
+
loadRecordDocs(projectRoot, cfg),
|
|
219
|
+
loadMarkdownDocs(projectRoot, normalizeMemorySources(cfg)),
|
|
220
|
+
]);
|
|
221
|
+
lookup.catch(() => {});
|
|
222
|
+
const loaded = Number.isFinite(memoryBudgetMs)
|
|
223
|
+
? await Promise.race([lookup, new Promise((resolve) => { timer = setTimeout(() => resolve(null), Math.max(1, memoryBudgetMs)); })])
|
|
224
|
+
: await lookup;
|
|
225
|
+
clearTimeout(timer);
|
|
226
|
+
const memoryMissed = loaded === null;
|
|
227
|
+
const [records, markdown] = loaded ?? [[], []];
|
|
228
|
+
const drop = new Set(Array.isArray(exclude?.memoryIds) ? exclude.memoryIds : []);
|
|
229
|
+
const docs = [...records, ...markdown].filter((d) => !drop.has(d.id));
|
|
230
|
+
const { ranked } = recallForTarget({ target: rel, neighbours, docs, query });
|
|
231
|
+
const text = renderEditHint({ target: rel, neighbours, memory: ranked });
|
|
232
|
+
if (!text) return { text: '', neighbours, memoryIds: [], memoryMissed };
|
|
233
|
+
return { text, neighbours, memoryIds: ranked.slice(0, 2).map((e) => e.doc.id), memoryMissed };
|
|
234
|
+
} catch {
|
|
235
|
+
return EMPTY;
|
|
236
|
+
}
|
|
237
|
+
}
|
|
@@ -74,7 +74,7 @@ export const HOOK_EVENT_MAP = {
|
|
|
74
74
|
},
|
|
75
75
|
tool_result: {
|
|
76
76
|
'Read|Grep|Glob': ['record-execution.mjs'],
|
|
77
|
-
'Edit|Write': ['post-edit-verify.sh', 'record-execution.mjs', 'task-watchdog.sh'],
|
|
77
|
+
'Edit|Write': ['post-edit-verify.sh', 'record-execution.mjs', 'task-watchdog.sh', 'edit-hint.mjs'],
|
|
78
78
|
Bash: ['compress-output.sh', 'record-execution.mjs'],
|
|
79
79
|
// Delegation result: releases the per-task execution claim taken by the pre-call guard.
|
|
80
80
|
'MultiEdit|NotebookEdit|Agent|Task': ['record-execution.mjs'],
|
|
@@ -167,6 +167,7 @@ export const ADVISORY_SCRIPTS = new Set([
|
|
|
167
167
|
'record-execution.sh',
|
|
168
168
|
// TASK-005: record-execution now runs as an .mjs module step (advisory).
|
|
169
169
|
'record-execution.mjs',
|
|
170
|
+
'edit-hint.mjs',
|
|
170
171
|
'auto-allow-bash.sh',
|
|
171
172
|
'pre-edit-backup.sh',
|
|
172
173
|
'vision-router.sh',
|
|
@@ -45,7 +45,7 @@
|
|
|
45
45
|
<!-- RULE: IDX-02 -->
|
|
46
46
|
2. Open only the **top 1-3 suspect files first**, then widen — `outline:` jumps to `Read(file, offset=<line>)`.
|
|
47
47
|
<!-- RULE: IDX-03 -->
|
|
48
|
-
The outline locates code, not behaviour — **code you are about to change must still be read**. Analog/reuse → `resolve-context`; non-code lanes skip.
|
|
48
|
+
The outline locates code, not behaviour — **code you are about to change must still be read**. Analog/reuse → `resolve-context`; non-code lanes skip. No edit hooks (Codex)? `resolve-context --target <file>` before editing lists its mirror, tests, attached memory.
|
|
49
49
|
|
|
50
50
|
## Automatic Skill Activation (mandatory)
|
|
51
51
|
<!-- RULE: SKILL-01 -->
|
|
@@ -45,7 +45,7 @@
|
|
|
45
45
|
<!-- RULE: IDX-02 -->
|
|
46
46
|
2. Open only the **top 1-3 suspect files first**, then widen — `outline:` jumps to `Read(file, offset=<line>)`.
|
|
47
47
|
<!-- RULE: IDX-03 -->
|
|
48
|
-
The outline locates code, not behaviour — **code you are about to change must still be read**. Analog/reuse → `resolve-context`; non-code lanes skip.
|
|
48
|
+
The outline locates code, not behaviour — **code you are about to change must still be read**. Analog/reuse → `resolve-context`; non-code lanes skip. No edit hooks (Codex)? `resolve-context --target <file>` before editing lists its mirror, tests, attached memory.
|
|
49
49
|
|
|
50
50
|
## Automatic Skill Activation (mandatory)
|
|
51
51
|
<!-- RULE: SKILL-01 -->
|
|
@@ -42,7 +42,7 @@
|
|
|
42
42
|
<!-- RULE: IDX-02 -->
|
|
43
43
|
2. Open only the **top 1-3 suspect files first**, then widen — `outline:` jumps to `Read(file, offset=<line>)`.
|
|
44
44
|
<!-- RULE: IDX-03 -->
|
|
45
|
-
The outline locates code, not behaviour — **code you are about to change must still be read**. Analog/reuse → `resolve-context`; non-code lanes skip.
|
|
45
|
+
The outline locates code, not behaviour — **code you are about to change must still be read**. Analog/reuse → `resolve-context`; non-code lanes skip. No edit hooks (Codex)? `resolve-context --target <file>` before editing lists its mirror, tests, attached memory.
|
|
46
46
|
|
|
47
47
|
## Automatic Skill Activation (mandatory)
|
|
48
48
|
<!-- RULE: SKILL-01 -->
|