@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
|
@@ -39,6 +39,7 @@ import {
|
|
|
39
39
|
import { resolveRecordFreshness } from '../runtime/memory-freshness.mjs';
|
|
40
40
|
import { resolveMemoryStage } from '../runtime/memory-flags.mjs';
|
|
41
41
|
import { recallForHook, renderMarkdownDoc } from '../runtime/memory-recall.mjs';
|
|
42
|
+
import { withValidity, staleSuffix } from '../runtime/memory-validity.mjs';
|
|
42
43
|
import {
|
|
43
44
|
ROUTE_VERSION,
|
|
44
45
|
ROUTE_CONTRACT_VERSION,
|
|
@@ -1736,8 +1737,11 @@ async function main() {
|
|
|
1736
1737
|
// with UKIT_SELF_IMPROVE=0 (tests/CI) or learning.selfImprove.enabled:false.
|
|
1737
1738
|
if (process.env.UKIT_SELF_IMPROVE !== '0') {
|
|
1738
1739
|
try {
|
|
1739
|
-
const { triggerSelfImprove } = await import('../runtime/self-improve-trigger.mjs');
|
|
1740
|
+
const { triggerSelfImprove, triggerEpisodeStart } = await import('../runtime/self-improve-trigger.mjs');
|
|
1740
1741
|
triggerSelfImprove({ projectRoot: rootDir });
|
|
1742
|
+
// Codex has no SessionStart/SessionEnd: the routed prompt is its only lifecycle point.
|
|
1743
|
+
// Same 10 min marker as the other engines, so later prompts pay one async read.
|
|
1744
|
+
await triggerEpisodeStart({ projectRoot: rootDir });
|
|
1741
1745
|
} catch {
|
|
1742
1746
|
// background work only — a missing/broken trigger never affects routing
|
|
1743
1747
|
}
|
|
@@ -7272,7 +7276,9 @@ async function buildPreviousContextSnapshot({ rootDir = process.cwd(), routingCo
|
|
|
7272
7276
|
});
|
|
7273
7277
|
const recalled = await recallForHook({
|
|
7274
7278
|
projectRoot: rootDir, query: taskQuery, docs, config: memoryConfig, limit: 2,
|
|
7279
|
+
annotate: (pool) => withValidity(rootDir, pool),
|
|
7275
7280
|
});
|
|
7281
|
+
const validityById = new Map(recalled.ranked.map((entry) => [entry.doc.id, entry.doc]));
|
|
7276
7282
|
const rankedItems = recalled.ranked.map((entry) => (entry.doc.type === 'markdown'
|
|
7277
7283
|
? { id: entry.doc.id, type: 'markdown', doc: entry.doc }
|
|
7278
7284
|
: itemById.get(entry.doc.id))).filter(Boolean);
|
|
@@ -7294,7 +7300,7 @@ async function buildPreviousContextSnapshot({ rootDir = process.cwd(), routingCo
|
|
|
7294
7300
|
return {
|
|
7295
7301
|
line: rankedItems.map((item) => (item.type === 'markdown'
|
|
7296
7302
|
? renderMarkdownDoc(item.doc, 120)
|
|
7297
|
-
: buildPreviousContextSnippet(item, freshnessById.get(item.id)))).join(' | '),
|
|
7303
|
+
: `${buildPreviousContextSnippet(item, freshnessById.get(item.id))}${staleSuffix(validityById.get(item.id))}`)).join(' | '),
|
|
7298
7304
|
selectedIds: rankedItems.map((item) => item.id),
|
|
7299
7305
|
fingerprint: buildCompactMachineKey('route-memory-v2', {
|
|
7300
7306
|
taskQuery: normalize(taskQuery),
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
// memoryCheck.js — memory rules + deterministic checker for memory source files
|
|
2
|
+
// (3.5.4). ONE file, node: builtins only, shipped byte-identical as
|
|
3
|
+
// template_project/.claude/ukit/runtime/memory-check.mjs (the PostToolUse advisory
|
|
4
|
+
// and Codex-less hosts use the mirror; `ukit memory check` and the record write
|
|
5
|
+
// gate use this copy). The recall engine and the secret scanner are injected, so
|
|
6
|
+
// there is exactly one tokenizer and one scanner. Async fs only; never throws.
|
|
7
|
+
//
|
|
8
|
+
// violation (exit 1) warning (exit 0)
|
|
9
|
+
// core-over-lines / core-over-bytes no-evidence (bullet names no existing
|
|
10
|
+
// line-too-long (core) / bullet-too-long file path or commit)
|
|
11
|
+
// secret-detected / near-duplicate
|
|
12
|
+
// unknown-supersedes / duplicate-id
|
|
13
|
+
//
|
|
14
|
+
// no-evidence is only a warning for markdown: pre-3.5.4 notes without a path are
|
|
15
|
+
// not rejected retroactively. Record writes (writeGate.js) enforce it.
|
|
16
|
+
import fsp from 'node:fs/promises';
|
|
17
|
+
import path from 'node:path';
|
|
18
|
+
|
|
19
|
+
// Caps. Measured on the live corpus before the split: longest hand-written
|
|
20
|
+
// bullet 1315 chars, longest record text 114, episodes sliced to 900.
|
|
21
|
+
export const RECORD_TEXT_MAX = 1200;
|
|
22
|
+
export const CORE_MAX_LINES = 150;
|
|
23
|
+
export const CORE_MAX_BYTES = 12000; // "12 KB" core cap, decimal so 12,000 is a hard number
|
|
24
|
+
export const CORE_LINE_MAX = 400; // one line per item in the core
|
|
25
|
+
export const DETAIL_BULLET_MAX = 1500; // verbatim detail bullets in docs/memory/*
|
|
26
|
+
export const CORE_FILE = 'docs/MEMORY.md';
|
|
27
|
+
|
|
28
|
+
// Lexical near-duplicate: Jaccard over the BM25 tokens. Measured (3.5.4) on
|
|
29
|
+
// docs/MEMORY.md (68 notes) + live records: the highest similarity between two
|
|
30
|
+
// distinct hand-written notes is 0.250 (markdown/markdown), 0.080 (markdown/
|
|
31
|
+
// record); 0.80 flags only near-restatements. Generated "Verification pattern
|
|
32
|
+
// ... failed N x" records reach 0.917 with each other, so generated writers are
|
|
33
|
+
// exempt in writeGate.js (GENERATED_CREATORS) and never rejected.
|
|
34
|
+
export const NEAR_DUP_JACCARD = 0.8;
|
|
35
|
+
export const NEAR_DUP_MIN_TOKENS = 6;
|
|
36
|
+
|
|
37
|
+
// Machine-generated writers: templated text, expected to resemble each other.
|
|
38
|
+
export const GENERATED_CREATORS = Object.freeze(new Set([
|
|
39
|
+
'episode-hook', 'propose', 'learning-observe', 'learning-candidate',
|
|
40
|
+
'delta-overlay', 'migration', 'system', 'observe',
|
|
41
|
+
]));
|
|
42
|
+
|
|
43
|
+
export function jaccard(aSet, bSet) {
|
|
44
|
+
if (aSet.size === 0 || bSet.size === 0) return 0;
|
|
45
|
+
let inter = 0;
|
|
46
|
+
for (const t of aSet) if (bSet.has(t)) inter += 1;
|
|
47
|
+
return inter / (aSet.size + bSet.size - inter);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* findNearDuplicate(text, candidates, tokenize, threshold) -> { id, similarity } | null
|
|
52
|
+
* candidates: [{ id, text }]. Notes under NEAR_DUP_MIN_TOKENS tokens are skipped
|
|
53
|
+
* (a short note shares most of its tokens by chance).
|
|
54
|
+
*/
|
|
55
|
+
export function findNearDuplicate(text, candidates, tokenize, threshold = NEAR_DUP_JACCARD) {
|
|
56
|
+
const a = new Set(tokenize(String(text ?? '')));
|
|
57
|
+
if (a.size < NEAR_DUP_MIN_TOKENS) return null;
|
|
58
|
+
let best = null;
|
|
59
|
+
for (const c of candidates) {
|
|
60
|
+
const b = new Set(tokenize(String(c?.text ?? '')));
|
|
61
|
+
if (b.size < NEAR_DUP_MIN_TOKENS) continue;
|
|
62
|
+
const similarity = jaccard(a, b);
|
|
63
|
+
if (similarity >= threshold && (!best || similarity > best.similarity)) best = { id: c.id, similarity };
|
|
64
|
+
}
|
|
65
|
+
return best;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
// Markdown supersession convention (honoured by recallEngine.parseMarkdownBullets):
|
|
69
|
+
// [id: slug] names a bullet (slug = [a-z0-9][a-z0-9._-]*)
|
|
70
|
+
// [supersedes: slug] the bullet replaces the bullet(s) so named
|
|
71
|
+
const MD_ID_RE = /\[id:\s*([a-z0-9][a-z0-9._-]*)\s*\]/gi;
|
|
72
|
+
// dir/file paths, or a bare file name with a known extension
|
|
73
|
+
const PATH_WORD_RE = /(?<![\w./@-])(?:[\w@.-]+\/)+[\w@.-]+(?::\d+)?|(?<![\w./@-])[\w-]+\.(?:m?js|cjs|json|md|sh|ya?ml|ts|py)\b/g;
|
|
74
|
+
const SHA_RE = /\b[0-9a-f]{7,40}\b/;
|
|
75
|
+
|
|
76
|
+
async function exists(root, rel) {
|
|
77
|
+
const clean = rel.replace(/[:#].*$/, '').replace(/^\.\//, '');
|
|
78
|
+
if (!clean || clean.startsWith('/') || clean.split('/').includes('..')) return false;
|
|
79
|
+
try {
|
|
80
|
+
await fsp.stat(path.join(root, clean));
|
|
81
|
+
return true;
|
|
82
|
+
} catch {
|
|
83
|
+
return false;
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
// A note is "about code" when it names a code token (camelCase, snake_case, call(),
|
|
88
|
+
// --flag, dotted config key). Owner preferences, process rules and release history
|
|
89
|
+
// name none, cannot point at a file, and never warn. The heading skip covers prose
|
|
90
|
+
// sections whose notes happen to mention a flag.
|
|
91
|
+
const CODE_TOKEN_RE = /\b[a-z]+[A-Z]\w*\b|\b[a-z0-9]+_[a-z0-9_]+\b|\b\w+\(\)|(?<![\w-])--[a-z][\w-]+|\b[a-z]+\.[a-z]+\.[a-z]\w*\b|\b[\w-]+\.(?:m?js|cjs|json|sh|ya?ml|ts)\b/;
|
|
92
|
+
const PROSE_HEADING_RE = /protocol|release history|preference|process|owner/i;
|
|
93
|
+
export function isCodeNote(doc) {
|
|
94
|
+
return !PROSE_HEADING_RE.test(doc?.heading ?? '') && CODE_TOKEN_RE.test(doc?.text ?? '');
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/** A bullet is evidenced when it names an existing project path (backticked) or a commit. */
|
|
98
|
+
export async function bulletNamesExistingFile(root, text) {
|
|
99
|
+
// Parsed bullet text has its backticks stripped, so match path-shaped words.
|
|
100
|
+
let tried = 0;
|
|
101
|
+
for (const m of text.matchAll(PATH_WORD_RE)) {
|
|
102
|
+
if (tried >= 12) break;
|
|
103
|
+
tried += 1;
|
|
104
|
+
if (await exists(root, m[0])) return true;
|
|
105
|
+
}
|
|
106
|
+
return SHA_RE.test(text) && /\b(commit|sha)\b/i.test(text);
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
const DETAIL_RE = /Detail:\s+(\S+\.md)/g;
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* missingDetailPointers(root, text) -> [{ line, rel, why }]: core lines whose
|
|
113
|
+
* `Detail: <file>.md` pointer escapes the project root or names a missing file.
|
|
114
|
+
*/
|
|
115
|
+
export async function missingDetailPointers(root, text) {
|
|
116
|
+
const out = [];
|
|
117
|
+
const base = path.resolve(root);
|
|
118
|
+
const lines = String(text).split('\n');
|
|
119
|
+
for (let i = 0; i < lines.length; i += 1) {
|
|
120
|
+
for (const m of lines[i].replace(/`/g, '').matchAll(DETAIL_RE)) {
|
|
121
|
+
const abs = path.resolve(base, m[1]);
|
|
122
|
+
if (abs !== base && !abs.startsWith(base + path.sep)) { out.push({ line: i + 1, rel: m[1], why: 'escapes the project root' }); continue; }
|
|
123
|
+
try { await fsp.stat(abs); } catch { out.push({ line: i + 1, rel: m[1], why: 'does not exist' }); }
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
return out;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* checkMemorySources(projectRoot, { sources, engine, scan, files }) ->
|
|
131
|
+
* { ok, violations: [{file,line,code,message}], warnings, stats }
|
|
132
|
+
* sources: relative .md paths (normalizeMemorySources). engine: { tokenize,
|
|
133
|
+
* parseMarkdownBullets }. scan: (text) -> { labels: string[] } (optional).
|
|
134
|
+
* files: limit the report to these paths (every source is still read, so
|
|
135
|
+
* cross-file duplicates and supersession slugs resolve).
|
|
136
|
+
*/
|
|
137
|
+
export async function checkMemorySources(projectRoot, { sources, engine, scan = null, files = null } = {}) {
|
|
138
|
+
const root = path.resolve(projectRoot);
|
|
139
|
+
const violations = [];
|
|
140
|
+
const warnings = [];
|
|
141
|
+
const stats = { files: 0, bullets: 0, coreLines: 0, coreBytes: 0 };
|
|
142
|
+
const all = [];
|
|
143
|
+
const raw = new Map();
|
|
144
|
+
for (const rel of sources ?? []) {
|
|
145
|
+
let text;
|
|
146
|
+
try { text = await fsp.readFile(path.join(root, rel), 'utf8'); } catch { continue; }
|
|
147
|
+
stats.files += 1;
|
|
148
|
+
raw.set(rel, text);
|
|
149
|
+
for (const doc of engine.parseMarkdownBullets(text, rel)) all.push({ ...doc, rel });
|
|
150
|
+
}
|
|
151
|
+
const focus = (rel) => !files || files.includes(rel);
|
|
152
|
+
const add = (list, rel, line, code, message) => { if (focus(rel)) list.push({ file: rel, line, code, message }); };
|
|
153
|
+
|
|
154
|
+
const core = raw.get(CORE_FILE);
|
|
155
|
+
if (core !== undefined) {
|
|
156
|
+
const lines = core.split('\n');
|
|
157
|
+
const lineCount = core.endsWith('\n') ? lines.length - 1 : lines.length;
|
|
158
|
+
const bytes = Buffer.byteLength(core, 'utf8');
|
|
159
|
+
stats.coreLines = lineCount;
|
|
160
|
+
stats.coreBytes = bytes;
|
|
161
|
+
if (lineCount > CORE_MAX_LINES) {
|
|
162
|
+
add(violations, CORE_FILE, lineCount, 'core-over-lines',
|
|
163
|
+
`core has ${lineCount} lines (max ${CORE_MAX_LINES}); merge items or move detail to docs/memory/`);
|
|
164
|
+
}
|
|
165
|
+
if (bytes > CORE_MAX_BYTES) {
|
|
166
|
+
add(violations, CORE_FILE, 1, 'core-over-bytes',
|
|
167
|
+
`core is ${bytes} bytes (max ${CORE_MAX_BYTES}); merge items or move detail to docs/memory/`);
|
|
168
|
+
}
|
|
169
|
+
for (const p of await missingDetailPointers(root, core)) {
|
|
170
|
+
add(violations, CORE_FILE, p.line, 'missing-detail', `Detail pointer ${p.rel} ${p.why}; point at an existing file under docs/memory/`);
|
|
171
|
+
}
|
|
172
|
+
lines.forEach((line, i) => {
|
|
173
|
+
if (/^[-*]\s/.test(line) && line.length > CORE_LINE_MAX) {
|
|
174
|
+
add(violations, CORE_FILE, i + 1, 'line-too-long',
|
|
175
|
+
`core item is ${line.length} chars (max ${CORE_LINE_MAX}); keep one line, move detail to docs/memory/`);
|
|
176
|
+
}
|
|
177
|
+
});
|
|
178
|
+
}
|
|
179
|
+
for (const [rel, text] of raw) {
|
|
180
|
+
if (rel === CORE_FILE) continue;
|
|
181
|
+
text.split('\n').forEach((line, i) => {
|
|
182
|
+
if (/^[-*]\s/.test(line) && line.length > DETAIL_BULLET_MAX) {
|
|
183
|
+
add(violations, rel, i + 1, 'bullet-too-long', `bullet is ${line.length} chars (max ${DETAIL_BULLET_MAX}); split it`);
|
|
184
|
+
}
|
|
185
|
+
});
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
stats.bullets = all.length;
|
|
189
|
+
const slugs = new Map();
|
|
190
|
+
for (const [rel, text] of raw) {
|
|
191
|
+
text.split('\n').forEach((line, i) => {
|
|
192
|
+
for (const m of line.matchAll(MD_ID_RE)) {
|
|
193
|
+
const slug = m[1].toLowerCase();
|
|
194
|
+
if (slugs.has(slug)) add(violations, rel, i + 1, 'duplicate-id', `id "${slug}" already used at ${slugs.get(slug)}`);
|
|
195
|
+
else slugs.set(slug, `${rel}:${i + 1}`);
|
|
196
|
+
}
|
|
197
|
+
});
|
|
198
|
+
}
|
|
199
|
+
for (const doc of all) {
|
|
200
|
+
for (const slug of doc.supersedesSlugs ?? []) {
|
|
201
|
+
if (!slugs.has(slug)) add(violations, doc.rel, doc.line, 'unknown-supersedes', `supersedes "${slug}" but no bullet has [id: ${slug}]`);
|
|
202
|
+
}
|
|
203
|
+
if (scan && focus(doc.rel)) {
|
|
204
|
+
let labels = [];
|
|
205
|
+
try { labels = scan(doc.text)?.labels ?? []; } catch { labels = []; }
|
|
206
|
+
if (labels.length > 0) add(violations, doc.rel, doc.line, 'secret-detected', `secret-like value (${labels.join(', ')}); remove it`);
|
|
207
|
+
}
|
|
208
|
+
if (focus(doc.rel) && isCodeNote(doc) && !(await bulletNamesExistingFile(root, doc.text))) {
|
|
209
|
+
add(warnings, doc.rel, doc.line, 'no-evidence', 'names no existing file path or commit; add the path this note is about');
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
// A superseded bullet may legitimately resemble its replacement.
|
|
213
|
+
const replaced = new Set();
|
|
214
|
+
for (const doc of all) for (const s of doc.supersedesSlugs ?? []) { const t = slugs.get(s); if (t) replaced.add(t); }
|
|
215
|
+
const live = all.filter((d) => !replaced.has(`${d.rel}:${d.line}`));
|
|
216
|
+
const seen = new Set();
|
|
217
|
+
const tokenCache = new Map();
|
|
218
|
+
const memoTokenize = (t) => {
|
|
219
|
+
let v = tokenCache.get(t);
|
|
220
|
+
if (!v) { v = engine.tokenize(t); tokenCache.set(t, v); }
|
|
221
|
+
return v;
|
|
222
|
+
};
|
|
223
|
+
for (let i = 0; i < live.length; i += 1) {
|
|
224
|
+
if (!focus(live[i].rel)) continue;
|
|
225
|
+
const dup = findNearDuplicate(live[i].text, live.slice(0, i).map((d) => ({ id: `${d.rel}:${d.line}`, text: d.text })), memoTokenize);
|
|
226
|
+
if (dup && !seen.has(dup.id)) {
|
|
227
|
+
seen.add(dup.id);
|
|
228
|
+
add(violations, live[i].rel, live[i].line, 'near-duplicate',
|
|
229
|
+
`${Math.round(dup.similarity * 100)}% lexical overlap with ${dup.id}; merge them or tag one [supersedes: <slug>]`);
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
return { ok: violations.length === 0, violations, warnings, stats };
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/** One advisory line for the first violation, '' when clean. */
|
|
236
|
+
export function formatCheckLine(res) {
|
|
237
|
+
const v = res?.violations?.[0];
|
|
238
|
+
if (!v) return '';
|
|
239
|
+
const more = res.violations.length > 1 ? ` (+${res.violations.length - 1} more)` : '';
|
|
240
|
+
return `[UKit memory] ${v.file}:${v.line} ${v.code}: ${v.message}${more}. Run \`ukit memory check\`.`;
|
|
241
|
+
}
|
|
@@ -2,7 +2,10 @@
|
|
|
2
2
|
// Standalone ESM; deterministic, no LLM, async fs only, never throws to callers.
|
|
3
3
|
import fsp from 'node:fs/promises';
|
|
4
4
|
import path from 'node:path';
|
|
5
|
-
import {
|
|
5
|
+
import {
|
|
6
|
+
demoteByValidity, dropSuperseded, fuseRanked, loadMarkdownDocs, normalizeMemorySources, rankDocs, STALE_MARKER,
|
|
7
|
+
} from './memory-recall.mjs';
|
|
8
|
+
import { withValidity } from './memory-validity.mjs';
|
|
6
9
|
import { eligible, resolveProjectIdentityMirror } from './memory-policy.mjs';
|
|
7
10
|
import { resolveMemoryStage } from './memory-flags.mjs';
|
|
8
11
|
|
|
@@ -49,17 +52,9 @@ export function extractAnchors(doc) {
|
|
|
49
52
|
|
|
50
53
|
const byId = (a, b) => String(a.id ?? '').localeCompare(String(b.id ?? ''));
|
|
51
54
|
|
|
55
|
+
// Reciprocal rank fusion (3.5.3); same signature as the 3.5.2 priority merge.
|
|
52
56
|
export function fuseLanes(lanes, { limit = Infinity } = {}) {
|
|
53
|
-
|
|
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);
|
|
57
|
+
return fuseRanked(lanes).map((e) => e.id).slice(0, limit);
|
|
63
58
|
}
|
|
64
59
|
|
|
65
60
|
function docEligible(doc, now) {
|
|
@@ -76,7 +71,7 @@ export function recallForTarget({ target, neighbours, docs, query = '', limit =
|
|
|
76
71
|
const empty = { ranked: [], abstained: true };
|
|
77
72
|
try {
|
|
78
73
|
const now = Date.now();
|
|
79
|
-
const pool = (Array.isArray(docs) ? docs : []).filter((d) => docEligible(d, now));
|
|
74
|
+
const pool = dropSuperseded((Array.isArray(docs) ? docs : []).filter((d) => docEligible(d, now)));
|
|
80
75
|
if (pool.length === 0 || !target) return empty;
|
|
81
76
|
const n = neighbours ?? {};
|
|
82
77
|
const mirrors = new Set(paths(n.mirrors));
|
|
@@ -106,7 +101,9 @@ export function recallForTarget({ target, neighbours, docs, query = '', limit =
|
|
|
106
101
|
if (!info.has(e.doc.id)) { info.set(e.doc.id, { doc: e.doc, tier: 4, via: 'query' }); }
|
|
107
102
|
fill.push(e.doc.id);
|
|
108
103
|
}
|
|
109
|
-
|
|
104
|
+
// Lanes: file/graph proximity (tier order kept inside the lane) and BM25 text.
|
|
105
|
+
// Source validity then demotes changed/missing-source notes below valid ones.
|
|
106
|
+
const ranked = demoteByValidity(fuseLanes([lanes.flat(), fill]).map((id) => info.get(id)), (e) => e.doc).slice(0, limit);
|
|
110
107
|
return { ranked, abstained: ranked.length === 0 };
|
|
111
108
|
} catch {
|
|
112
109
|
return empty;
|
|
@@ -125,15 +122,23 @@ export function renderEditHint({ target, neighbours, memory = [], maxChars = 600
|
|
|
125
122
|
for (const m of mirrors) lines.push(`mirror (${KIND_LABEL[m.kind] ?? 'declared'}): ${flat(m.path)}`);
|
|
126
123
|
const tests = [...new Set(paths(n.tests))].sort().slice(0, 3);
|
|
127
124
|
if (tests.length) lines.push(`tests: ${tests.map(flat).join(', ')}`);
|
|
125
|
+
// Opt-in (memory.editHints.coChange === true): the caller passes `together` only then.
|
|
126
|
+
const shown = new Set([...mirrors.map((m) => m.path), ...tests]);
|
|
127
|
+
const together = [...(Array.isArray(n.together) ? n.together : [])]
|
|
128
|
+
.map((t) => (typeof t === 'string' ? { path: t, count: 0 } : t)).filter((t) => t?.path && !shown.has(t.path))
|
|
129
|
+
.sort((a, b) => (b.count ?? 0) - (a.count ?? 0) || String(a.path).localeCompare(String(b.path)))
|
|
130
|
+
.slice(0, 3).map((t) => flat(t.path));
|
|
131
|
+
if (together.length) lines.push(`often changed together: ${together.join(', ')}`);
|
|
128
132
|
const mem = [];
|
|
129
133
|
for (const entry of (Array.isArray(memory) ? memory : []).slice(0, 2)) {
|
|
130
134
|
const doc = entry?.doc ?? entry;
|
|
131
135
|
if (!doc) continue;
|
|
132
136
|
const label = doc.type === 'markdown' ? (doc.provenance ?? doc.id) : (doc.id ?? doc.provenance);
|
|
133
137
|
const head = `- [${flat(label)} | ${flat(entry.via ?? 'query')}] `;
|
|
138
|
+
const tag = doc.validity ? ` ${STALE_MARKER}` : '';
|
|
134
139
|
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));
|
|
140
|
+
const room = Math.max(0, LINE_CHARS - head.length - tag.length);
|
|
141
|
+
mem.push(head + (body.length > room ? `${body.slice(0, Math.max(0, room - 3))}...` : body) + tag);
|
|
137
142
|
}
|
|
138
143
|
if (lines.length === 0 && mem.length === 0) return '';
|
|
139
144
|
const build = (m) => [`[UKit edit-graph] ${flat(target)}`, ...lines,
|
|
@@ -170,14 +175,14 @@ async function loadRecordDocs(projectRoot, config) {
|
|
|
170
175
|
return records.filter((r) => r && typeof r === 'object' && !r.superseded_by && eligible(r, ctx).ok)
|
|
171
176
|
.map((r) => ({
|
|
172
177
|
id: `record:${r.id}`, type: r.type, provenance: r.provenance, text: String(r.text ?? ''),
|
|
173
|
-
evidence: r.evidence, created_at: r.created_at ?? 0,
|
|
178
|
+
evidence: r.evidence, created_at: r.created_at ?? 0, supersedes: r.supersedes,
|
|
174
179
|
}));
|
|
175
180
|
}
|
|
176
181
|
|
|
177
182
|
const EMPTY = { text: '', neighbours: null, memoryIds: [] };
|
|
178
183
|
|
|
179
184
|
export async function editHintFor({
|
|
180
|
-
projectRoot, target, config = null, query = '', exclude = {}, signal, deps = {}, memoryBudgetMs,
|
|
185
|
+
projectRoot, target, config = null, query = '', exclude = {}, signal, deps = {}, memoryBudgetMs, capture = false,
|
|
181
186
|
} = {}) {
|
|
182
187
|
try {
|
|
183
188
|
if (process.env.UKIT_EDIT_HINTS === '0' || !projectRoot || !target) return EMPTY;
|
|
@@ -201,23 +206,40 @@ export async function editHintFor({
|
|
|
201
206
|
let neighbours = {
|
|
202
207
|
mirrors: sorted(raw?.mirrors), tests: sorted(raw?.tests),
|
|
203
208
|
importers: sorted(raw?.importers), imports: sorted(raw?.imports),
|
|
209
|
+
together: cfg?.memory?.editHints?.coChange === true
|
|
210
|
+
? (Array.isArray(raw?.together) ? raw.together : []).filter(keep)
|
|
211
|
+
.sort((a, b) => (b.count ?? 0) - (a.count ?? 0) || String(a.path).localeCompare(String(b.path)))
|
|
212
|
+
: [],
|
|
204
213
|
};
|
|
205
|
-
const
|
|
206
|
-
|
|
207
|
-
const
|
|
214
|
+
const shownPaths = new Set([...neighbours.mirrors.map((m) => m.path), ...neighbours.tests.map((t) => t?.path ?? t)]);
|
|
215
|
+
neighbours.together = neighbours.together.filter((t) => !shownPaths.has(t.path)).slice(0, 3);
|
|
216
|
+
const probe = [
|
|
217
|
+
...neighbours.mirrors.slice(0, 4).map((m) => m.path),
|
|
218
|
+
...neighbours.tests.slice(0, MAX_STAT - Math.min(4, neighbours.mirrors.length)),
|
|
219
|
+
].slice(0, MAX_STAT);
|
|
220
|
+
const togetherProbe = neighbours.together.map((t) => t.path);
|
|
221
|
+
const toProbe = [...new Set([...probe, ...togetherProbe])];
|
|
222
|
+
const alive = new Set((await Promise.all(toProbe.map(async (p) => ((await exists(projectRoot, p)) ? p : null)))).filter(Boolean));
|
|
223
|
+
const probed = new Set(toProbe);
|
|
208
224
|
const live = (p) => !probed.has(p) || alive.has(p);
|
|
209
225
|
neighbours = {
|
|
210
226
|
...neighbours,
|
|
211
227
|
mirrors: neighbours.mirrors.filter((m) => live(m.path)),
|
|
212
228
|
tests: neighbours.tests.filter(live),
|
|
229
|
+
together: neighbours.together.filter((t) => live(t.path)),
|
|
213
230
|
};
|
|
214
231
|
if (signal?.aborted) return EMPTY;
|
|
215
232
|
// Graph part is ready; memory gets its own sub-budget and never delays it.
|
|
216
233
|
let timer;
|
|
217
|
-
|
|
234
|
+
// Source validity rides inside the same budget; `capture` (passed only by
|
|
235
|
+
// `resolve-context --target`) also anchors never-seen items; a hook never writes.
|
|
236
|
+
const lookup = (deps.loadMemory ? deps.loadMemory() : Promise.all([
|
|
218
237
|
loadRecordDocs(projectRoot, cfg),
|
|
219
238
|
loadMarkdownDocs(projectRoot, normalizeMemorySources(cfg)),
|
|
220
|
-
])
|
|
239
|
+
])).then(async ([recs, mds]) => {
|
|
240
|
+
const all = await withValidity(projectRoot, [...recs, ...mds], { capture });
|
|
241
|
+
return [all.slice(0, recs.length), all.slice(recs.length)];
|
|
242
|
+
});
|
|
221
243
|
lookup.catch(() => {});
|
|
222
244
|
const loaded = Number.isFinite(memoryBudgetMs)
|
|
223
245
|
? await Promise.race([lookup, new Promise((resolve) => { timer = setTimeout(() => resolve(null), Math.max(1, memoryBudgetMs)); })])
|