@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.
Files changed (75) hide show
  1. package/CHANGELOG.md +38 -90
  2. package/README.md +1 -0
  3. package/manifests/documentation.yaml +12 -1
  4. package/manifests/platform.full.yaml +12 -0
  5. package/package.json +34 -1
  6. package/src/cli/commands/doctor.js +55 -2
  7. package/src/cli/commands/indexTools.js +10 -4
  8. package/src/cli/commands/memory.js +107 -8
  9. package/src/core/memory/episodes.js +106 -7
  10. package/src/core/memory/memoryCheck.js +241 -0
  11. package/src/core/memory/memoryCheckRun.js +27 -0
  12. package/src/core/memory/memoryHit.js +2 -0
  13. package/src/core/memory/mutateMemory.js +46 -1
  14. package/src/core/memory/observations.js +192 -0
  15. package/src/core/memory/projectIdentity.js +9 -2
  16. package/src/core/memory/recallEngine.js +204 -9
  17. package/src/core/memory/records.js +23 -0
  18. package/src/core/memory/registryPrune.js +230 -0
  19. package/src/core/memory/retrieval.js +12 -3
  20. package/src/core/memory/writeGate.js +137 -0
  21. package/src/core/runtimeConfig.js +12 -2
  22. package/src/index/buildIndex.js +26 -0
  23. package/src/index/paths.js +3 -1
  24. package/src/index/queryIndex.js +372 -26
  25. package/src/index/resolveContext.js +1 -1
  26. package/template_project/.claude/hooks/edit-hint.mjs +64 -17
  27. package/template_project/.claude/hooks/session-episode-start.mjs +35 -0
  28. package/template_project/.claude/hooks/session-episode.sh +9 -4
  29. package/template_project/.claude/settings.json +2 -2
  30. package/template_project/.claude/ukit/index/edit-graph.mjs +141 -11
  31. package/template_project/.claude/ukit/index/lib/index-core.mjs +400 -27
  32. package/template_project/.claude/ukit/index/query-index.mjs +14 -3
  33. package/template_project/.claude/ukit/index/resolve-context.mjs +1 -1
  34. package/template_project/.claude/ukit/index/route-task.mjs +8 -2
  35. package/template_project/.claude/ukit/runtime/memory-check.mjs +241 -0
  36. package/template_project/.claude/ukit/runtime/memory-lanes.mjs +44 -22
  37. package/template_project/.claude/ukit/runtime/memory-recall.mjs +204 -9
  38. package/template_project/.claude/ukit/runtime/memory-validity.mjs +259 -0
  39. package/template_project/.claude/ukit/runtime/reinject-context.mjs +4 -2
  40. package/template_project/.claude/ukit/runtime/self-improve-trigger.mjs +212 -5
  41. package/template_project/.omp/hooks/pre/ukit-bridge.js +2 -1
  42. package/template_project/ukit/storage/config.json +4 -2
  43. package/src/core/agentRuntime/completionGate.js +0 -179
  44. package/src/core/agentRuntime/context.js +0 -571
  45. package/src/core/agentRuntime/qualityComparison.js +0 -112
  46. package/src/core/agentRuntime/resourcePolicy.js +0 -78
  47. package/src/core/agentRuntime/runtimeSupport.js +0 -255
  48. package/src/core/codeintel/manifest.js +0 -176
  49. package/src/core/experiments/deliberation.js +0 -327
  50. package/src/core/experiments/dynamicWorkflow.js +0 -507
  51. package/src/core/handoffDocValidator.js +0 -154
  52. package/src/core/memory/deltaOverlays.js +0 -493
  53. package/src/core/memory/learningCandidates.js +0 -347
  54. package/src/core/observability/emit/sessionBoot.js +0 -407
  55. package/src/core/observability/evaluation/experimentPlan.js +0 -95
  56. package/src/core/observability/evaluation/perturbation.js +0 -273
  57. package/src/core/observability/evaluation/replay.js +0 -149
  58. package/src/core/observability/evaluation/scorecard.js +0 -465
  59. package/src/core/observability/schema/compatibility.js +0 -180
  60. package/src/core/observability/support/renderer.js +0 -130
  61. package/src/core/reviewPanelAggregate.js +0 -204
  62. package/src/core/taskBudgetValidator.js +0 -251
  63. package/src/core/taskProgressGuard.js +0 -227
  64. package/src/decision/reviewVerdict.js +0 -339
  65. package/src/decision/runtimeFilter.js +0 -150
  66. package/src/decision/runtimeScheduler.js +0 -239
  67. package/src/diagnostics/classifyHang.js +0 -246
  68. package/src/diagnostics/ompStallSnapshot.js +0 -199
  69. package/src/index/contextPack.js +0 -285
  70. package/src/index/impactContext.js +0 -360
  71. package/src/index/reviewPolicy.js +0 -368
  72. package/src/index/sensitivePath.js +0 -21
  73. package/src/render/instructionRenderer.js +0 -290
  74. package/src/skill/auditSkill.js +0 -140
  75. package/template_project/instructions/overlays/repo.md +0 -9
@@ -143,7 +143,9 @@ const DISCOVERED_EXTENSIONS = new Set([...TRACKED_EXTENSIONS, ...STYLE_EXTENSION
143
143
  // SQL 'column' rows with parent/schema, and calls.json gains per-object SQL
144
144
  // reference records — a v8 cached artifact must not be reused for unchanged
145
145
  // files or the new extractions silently vanish.
146
- export const INDEX_SCHEMA_VERSION = 9;
146
+ // v10: symbols.json gains unexported function/class ('local-function', 'local-class'),
147
+ // function-expression consts, class 'method' rows and TS interface/enum/type ('type') rows.
148
+ export const INDEX_SCHEMA_VERSION = 10;
147
149
  export const DEFAULT_INDEX_CACHE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
148
150
  // Parse-phase read/extract concurrency — deliberately tighter than the
149
151
  // discovery stat pool because parsing holds file content in memory.
@@ -1247,7 +1249,11 @@ function isFunctionLikeSignature(signature) {
1247
1249
  // Reads symbols.json through the existing readArtifact cache (no new file reads, no new
1248
1250
  // cache). Never throws: an absent file, a missing artifact, or a stale schema all resolve
1249
1251
  // to [] so callers can render an outline block unconditionally.
1250
- export async function getFileOutline({ rootDir = process.cwd(), filePath, limit = 12 } = {}) {
1252
+ const OUTLINE_WINDOW = 12; // matches OUTLINE_SYMBOLS_LIMIT in the CLI printers
1253
+
1254
+ // `focus`: symbol names the query matched (see queryMatchedSymbolNames); they are pinned into
1255
+ // the first OUTLINE_WINDOW rows even when unexported, so the printed outline shows the hit.
1256
+ export async function getFileOutline({ rootDir = process.cwd(), filePath, limit = 12, focus = null } = {}) {
1251
1257
  if (!filePath) {
1252
1258
  return Object.freeze([]);
1253
1259
  }
@@ -1273,9 +1279,26 @@ export async function getFileOutline({ rootDir = process.cwd(), filePath, limit
1273
1279
  seenNames.add(item.name);
1274
1280
  deduped.push(item);
1275
1281
  }
1282
+ // The first OUTLINE_WINDOW rows (what the CLI prints) hold exported/top-level symbols
1283
+ // first; unexported functions and class methods only take the remaining slots. Each
1284
+ // part stays in line order, and rows beyond the window follow in line order.
1285
+ const window = Number.isFinite(limit) ? limit : OUTLINE_WINDOW;
1286
+ let kept = deduped;
1287
+ if (deduped.length > window) {
1288
+ const pinned = new Set(focus ?? []);
1289
+ const isPinned = (item) => pinned.has(item.name);
1290
+ const ranked = [
1291
+ ...deduped.filter(isPinned),
1292
+ ...deduped.filter((item) => !isPinned(item) && !isLocalOutlineRow(item)),
1293
+ ...deduped.filter((item) => !isPinned(item) && isLocalOutlineRow(item)),
1294
+ ];
1295
+ const head = ranked.slice(0, window).sort((a, b) => a.line - b.line);
1296
+ const inHead = new Set(head);
1297
+ kept = [...head, ...deduped.filter((item) => !inHead.has(item))];
1298
+ }
1276
1299
 
1277
1300
  return Object.freeze(
1278
- deduped.slice(0, limit).map((item) => Object.freeze({
1301
+ kept.slice(0, limit).map((item) => Object.freeze({
1279
1302
  line: item.line,
1280
1303
  name: item.name,
1281
1304
  type: item.type,
@@ -1284,7 +1307,8 @@ export async function getFileOutline({ rootDir = process.cwd(), filePath, limit
1284
1307
  );
1285
1308
  }
1286
1309
 
1287
- export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5 } = {}) {
1310
+ // contentLane=false skips the error-string content search (context-resolution paths never pay for it).
1311
+ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5, contentLane = true } = {}) {
1288
1312
  const normalizedQuery = String(query ?? '').trim();
1289
1313
  if (!normalizedQuery) return [];
1290
1314
  if (limit <= 0) return Object.freeze([]);
@@ -1296,12 +1320,13 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
1296
1320
  rootDir: absoluteRoot,
1297
1321
  query: normalizedQuery,
1298
1322
  limit,
1323
+ contentLane,
1299
1324
  });
1300
1325
  if (QUERY_RESULT_CACHE.has(queryCacheKey)) {
1301
1326
  return QUERY_RESULT_CACHE.get(queryCacheKey);
1302
1327
  }
1303
1328
  const queryPromise = (async () => {
1304
- const { files, searchDescriptorsByFile } = await loadQuerySearchBundle(absoluteRoot);
1329
+ const { files, searchDescriptorsByFile, tokenWeights } = await loadQuerySearchBundle(absoluteRoot);
1305
1330
  const preferredArchetypes = inferPreferredArchetypes(queryDescriptor.tokens);
1306
1331
  const includeLikelyTestFiles = shouldIncludeLikelyTestFiles(queryDescriptor);
1307
1332
 
@@ -1312,8 +1337,10 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
1312
1337
  const searchDescriptor = searchDescriptorsByFile.get(filePath) ?? createFileSearchDescriptor({ filePath, symbols: [] });
1313
1338
  const { score, reasons } = scoreDirectFileMatch({
1314
1339
  queryDescriptor,
1340
+ rawQuery: normalizedQuery,
1315
1341
  filePath,
1316
1342
  searchDescriptor,
1343
+ tokenWeights,
1317
1344
  });
1318
1345
 
1319
1346
  if (score > 0) {
@@ -1321,7 +1348,50 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
1321
1348
  }
1322
1349
  }
1323
1350
 
1324
- if (directScores.size === 0) return Object.freeze([]);
1351
+ // Content lane: a message-like query with no confident symbol/path hit also searches
1352
+ // file contents through the existing bounded fallback search. It only adds a bounded
1353
+ // bonus, so it can never displace a confident hit (those skip the lane entirely).
1354
+ let bestDirect = 0;
1355
+ let contentLaneRan = false;
1356
+ let contentCutShort = [];
1357
+ for (const entry of directScores.values()) {
1358
+ bestDirect = Math.max(bestDirect, entry.score);
1359
+ }
1360
+ if (contentLane && bestDirect < CONTENT_LANE_CONFIDENT_SCORE && queryDescriptor.tokens.size >= CONTENT_LANE_MIN_TOKENS && looksLikeLiteralMessage(normalizedQuery)) {
1361
+ contentLaneRan = true;
1362
+ // A literal message sits on one source line: every query token must share the matched
1363
+ // line, otherwise this is a scattered token hit, not the message. The scan order and the
1364
+ // count/byte caps are functions of the index and file contents only (never of load or of
1365
+ // ripgrep being installed); wall-clock is a safety cap that reports 'time-budget'.
1366
+ const messageTokens = [...new Set(normalizeIdentifierTokens(queryDescriptor.rawLower))];
1367
+ let lineHits = [];
1368
+ try {
1369
+ const ordered = rankContentLaneFiles({
1370
+ files, searchDescriptorsByFile, tokenWeights, queryTokens: queryDescriptor.tokens, includeLikelyTestFiles,
1371
+ });
1372
+ const scan = await scanContentLane({ absoluteRoot, ordered, tokens: messageTokens, limit: CONTENT_LANE_LIMIT });
1373
+ lineHits = scan.hits;
1374
+ contentCutShort = scan.truncated;
1375
+ } catch {
1376
+ contentCutShort = ['error'];
1377
+ }
1378
+ lineHits.forEach((row, index) => {
1379
+ const existing = directScores.get(row.filePath);
1380
+ const reason = `content_match:${row.filePath}${row.line ? `:${row.line}` : ''}`;
1381
+ if (existing) {
1382
+ existing.score += CONTENT_LANE_BONUS;
1383
+ existing.reasons = dedupe([...(existing.reasons ?? []), reason]);
1384
+ } else {
1385
+ directScores.set(row.filePath, {
1386
+ filePath: row.filePath,
1387
+ score: CONTENT_LANE_ONLY_SCORE - index * 0.1,
1388
+ reasons: [reason],
1389
+ });
1390
+ }
1391
+ });
1392
+ }
1393
+
1394
+ if (directScores.size === 0) return withContentLaneStatus(Object.freeze([]), contentLaneRan, contentCutShort);
1325
1395
 
1326
1396
  const {
1327
1397
  hotspotScores,
@@ -1355,10 +1425,13 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
1355
1425
  importersByTarget,
1356
1426
  testsMapBySource: testsBySource,
1357
1427
  });
1358
- const boosted = applyHotspotBoosts({ scores: relatedScores, hotspotScores });
1359
- return freezeQueryResults(
1360
- [...boosted.values()].sort((a, b) => b.score - a.score || a.filePath.localeCompare(b.filePath)).slice(0, limit),
1361
- );
1428
+ const boosted = capBoostLift({
1429
+ directScores,
1430
+ scores: applyHotspotBoosts({ scores: relatedScores, hotspotScores }),
1431
+ });
1432
+ return withContentLaneStatus(freezeQueryResults(
1433
+ [...boosted.values()].map((entry) => ({ ...entry, score: finalizeScore(entry) })).sort((a, b) => b.score - a.score || a.filePath.localeCompare(b.filePath)).slice(0, limit),
1434
+ ), contentLaneRan, contentCutShort);
1362
1435
  })().catch((error) => {
1363
1436
  QUERY_RESULT_CACHE.delete(queryCacheKey);
1364
1437
  throw error;
@@ -1437,6 +1510,30 @@ export function clearIndexArtifactCache(rootDir = null) {
1437
1510
  RELATED_TEST_LOOKUP_CACHE.delete(absoluteRoot);
1438
1511
  }
1439
1512
 
1513
+ // Names of the symbols a query result matched, parsed from its `symbol_exact:` /
1514
+ // `symbol_token:` reasons; feed to getFileOutline({ focus }).
1515
+ export function queryMatchedSymbolNames(result) {
1516
+ const names = [];
1517
+ for (const reason of result?.reasons ?? []) {
1518
+ const match = /^symbol_(?:exact|compact|contains):([^:]+)$/.exec(reason) ?? /^symbol_token:([^:]+):/.exec(reason);
1519
+ if (match) {
1520
+ names.push(match[1]);
1521
+ }
1522
+ }
1523
+ return names;
1524
+ }
1525
+
1526
+ // Non-enumerable (array equality and JSON stay unchanged), like boundedSourceSearch rows.truncated:
1527
+ // `contentLane` is true when the content search ran; `contentLaneTruncated` lists why it was cut
1528
+ // short ('verify-cap', 'time-budget', 'max-files', ...) so a partial scan never reads as "no match".
1529
+ function withContentLaneStatus(results, ran, truncated) {
1530
+ // results arrive frozen, so copy before attaching the status and freeze again.
1531
+ const out = [...results];
1532
+ Object.defineProperty(out, 'contentLane', { value: ran, enumerable: false });
1533
+ Object.defineProperty(out, 'contentLaneTruncated', { value: Object.freeze([...truncated]), enumerable: false });
1534
+ return Object.freeze(out);
1535
+ }
1536
+
1440
1537
  function freezeQueryResults(results) {
1441
1538
  return Object.freeze(
1442
1539
  results.map((item) => Object.freeze({
@@ -1581,7 +1678,7 @@ export async function resolveContext({
1581
1678
  }
1582
1679
 
1583
1680
  if (queryWasUsed) {
1584
- const queryResults = await queryCodeIndex({ rootDir, query: intent, limit: budget.maxFiles });
1681
+ const queryResults = await queryCodeIndex({ rootDir, query: intent, limit: budget.maxFiles, contentLane: false });
1585
1682
  for (const qr of queryResults) {
1586
1683
  addExplainedFile(result, 'primaryTargets', qr.filePath, buildQueryReason(qr));
1587
1684
  }
@@ -2767,6 +2864,8 @@ function computeSignature(content, lineStartIndex) {
2767
2864
  return `${collapsed.slice(0, 199)}…`;
2768
2865
  }
2769
2866
 
2867
+ const CLASS_METHOD_SKIP = new Set(['if', 'for', 'while', 'switch', 'catch', 'function', 'return', 'with', 'constructor', 'super']);
2868
+
2770
2869
  export function extractSymbols(filePath, content) {
2771
2870
  const out = [];
2772
2871
  const lineStarts = computeLineStarts(content);
@@ -2828,6 +2927,30 @@ export function extractSymbols(filePath, content) {
2828
2927
  addMatches(/defineComponent\(\s*\{[\s\S]*?name\s*:\s*['"]([^'"]+)['"]/g, 'component-name');
2829
2928
  addMatches(/export\s+default\s*\{[\s\S]*?name\s*:\s*['"]([^'"]+)['"]/g, 'component-name');
2830
2929
 
2930
+ // Unexported declarations (3.5.4). Line-anchored, so `export function` / `export class`
2931
+ // (indexed above as exported) never double-count. Local types rank below exported ones.
2932
+ addMatches(/^[ \t]*(?:async\s+)?function\s*\*?\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*[(<]/gm, 'local-function');
2933
+ addMatches(/^[ \t]*(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(?:async\s+)?function\b/gm, 'callable');
2934
+ addMatches(/^[ \t]*(?:abstract\s+)?class\s+([A-Za-z_$][A-Za-z0-9_$]*)/gm, 'local-class');
2935
+ if (/\.(?:ts|tsx|mts|cts|vue)$/.test(filePath)) {
2936
+ addMatches(/^[ \t]*(?:export\s+)?(?:declare\s+)?(?:const\s+)?(?:interface|enum)\s+([A-Za-z_$][A-Za-z0-9_$]*)/gm, 'type');
2937
+ addMatches(/^[ \t]*(?:export\s+)?(?:declare\s+)?type\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*(?:<[^=\n]*>)?\s*=/gm, 'type');
2938
+ }
2939
+ // Class methods: indented `name(args) {` lines inside a balanced class body.
2940
+ for (const classMatch of content.matchAll(/(?:^|[^\w$.])class\s+[A-Za-z_$][A-Za-z0-9_$]*(?:\s+extends\s+[\w$.]+(?:\([^)]*\))?)?\s*\{/g)) {
2941
+ const bodyStart = classMatch.index + classMatch[0].length;
2942
+ const classBody = sliceBalancedBlock(content, bodyStart);
2943
+ if (!classBody) {
2944
+ continue;
2945
+ }
2946
+ for (const methodMatch of classBody.matchAll(/^[ \t]+(?:(?:static|async|get|set)\s+)*\*?\s*(#?[A-Za-z_$][A-Za-z0-9_$]*)\s*\([^()]*\)\s*\{/gm)) {
2947
+ if (CLASS_METHOD_SKIP.has(methodMatch[1])) {
2948
+ continue;
2949
+ }
2950
+ addSymbol(methodMatch[1], 'method', bodyStart + methodMatch.index + methodMatch[0].indexOf(methodMatch[1]));
2951
+ }
2952
+ }
2953
+
2831
2954
  // Global-registered frontend functions: reachable from anywhere without an
2832
2955
  // import edge, so impact analysis must treat them as verified dependencies.
2833
2956
  addMatches(/\b(?:window|globalThis|global)\s*\.\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*=/g, 'global');
@@ -3315,9 +3438,11 @@ async function loadQuerySearchBundle(rootDir) {
3315
3438
  const safeFiles = safeSchemaArtifact(files);
3316
3439
  const safeSymbols = safeSchemaArtifact(symbols);
3317
3440
  const symbolMap = groupBy(safeItems(safeSymbols), (item) => item.filePath);
3441
+ const searchDescriptorsByFile = buildFileSearchDescriptors(safeItems(safeFiles), symbolMap);
3318
3442
  return {
3319
3443
  files: safeFiles,
3320
- searchDescriptorsByFile: buildFileSearchDescriptors(safeItems(safeFiles), symbolMap),
3444
+ searchDescriptorsByFile,
3445
+ tokenWeights: buildTokenWeights(searchDescriptorsByFile),
3321
3446
  };
3322
3447
  })
3323
3448
  .catch((error) => {
@@ -3393,9 +3518,103 @@ function tokenize(query) {
3393
3518
  return tokenizeFoldedText(foldTextForSearch(addCamelBoundaries(query)));
3394
3519
  }
3395
3520
 
3396
- function scoreDirectFileMatch({ queryDescriptor, filePath, searchDescriptor }) {
3521
+ // ── Ranking constants (kept identical in src/index/queryIndex.js) ──
3522
+ const PATH_EXACT_SCORE = 60;
3523
+ const PATH_SUFFIX_SCORE = 48;
3524
+ const PATH_BASENAME_SCORE = 40;
3525
+ const SYMBOL_EXACT_SCORE = 40;
3526
+ const LOCAL_SYMBOL_FACTOR = 0.85; // unexported symbols (local function/class, method, unexported type) rank below an exported symbol of the same name
3527
+ const SYMBOL_DECAY = 0.35; // k-th best symbol of a file adds score * SYMBOL_DECAY^k
3528
+ const SYMBOL_REASON_LIMIT = 3;
3529
+ const MIN_SUBSTRING_TOKEN_LENGTH = 3;
3530
+ const BOOST_LIFT_RATIO = 0.2; // import/hotspot/archetype boosts may add at most this share of a direct score (+1)
3531
+ const CONTENT_LANE_CONFIDENT_SCORE = 30; // a best direct score at/above this (exact symbol or path hit) skips the content lane
3532
+ const CONTENT_LANE_MIN_TOKENS = 3; // shorter queries are names, not messages
3533
+ const CONTENT_LANE_LIMIT = 40; // candidates only share tokens somewhere in the file; the same-line check below keeps the real ones
3534
+ const CONTENT_LANE_CODE_EXT = /\.(?:m?js|cjs|jsx?|tsx?|vue|sql|sh)$/i; // docs/data files quote queries verbatim (baselines, logs); only source carries error strings
3535
+ const CONTENT_LANE_BONUS = 14; // added to a file that already has a direct score
3536
+ const CONTENT_LANE_ONLY_SCORE = 13; // base for a file found only by content; below CONTENT_LANE_CONFIDENT_SCORE by design
3537
+ const CONTENT_LANE_MAX_FILES = 1500; // files read per query, in priority order (primary bound)
3538
+ const CONTENT_LANE_MAX_BYTES = 24 * 1024 * 1024; // characters read per query (primary bound)
3539
+ const CONTENT_LANE_MAX_FILE_BYTES = 512 * 1024; // larger files are generated/data, never scanned
3540
+ const CONTENT_LANE_BATCH = 24;
3541
+ const CONTENT_LANE_SAFETY_MS = 5000; // safety cap only: hitting it reports 'time-budget', normal runs never do
3542
+ const BOOST_ONLY_RATIO = 0.3; // files with no direct match stay below this share of the best direct score
3543
+
3544
+ // Rarity weight per token in (0,1]: a token present in nearly every file is worth
3545
+ // ~ln2/ln(1+N), a token unique to one file is worth 1. Computed once per bundle.
3546
+ function buildTokenWeights(searchDescriptorsByFile) {
3547
+ const docFrequency = new Map();
3548
+ for (const descriptor of searchDescriptorsByFile.values()) {
3549
+ const seen = new Set(descriptor.path.tokens);
3550
+ for (const symbol of descriptor.symbols) {
3551
+ for (const token of symbol.descriptor.tokens) {
3552
+ seen.add(token);
3553
+ }
3554
+ }
3555
+ for (const token of seen) {
3556
+ docFrequency.set(token, (docFrequency.get(token) ?? 0) + 1);
3557
+ }
3558
+ }
3559
+ const total = searchDescriptorsByFile.size;
3560
+ const denominator = Math.log(1 + total) || 1;
3561
+ const weights = new Map();
3562
+ for (const [token, count] of docFrequency) {
3563
+ weights.set(token, Math.max(0.05, Math.log(1 + total / count) / denominator));
3564
+ }
3565
+ return weights;
3566
+ }
3567
+
3568
+ // Prior applied after scoring so an original beats its mirror copy on ties without
3569
+ // hiding the mirror: root installed copies < template_project < everything else.
3570
+ function mirrorPrior(filePath) {
3571
+ if (/^\.(?:claude|codex|omp)\//.test(filePath)) {
3572
+ return 0.8;
3573
+ }
3574
+ if (filePath.startsWith('template_project/')) {
3575
+ return 0.85;
3576
+ }
3577
+ return 1;
3578
+ }
3579
+
3580
+ function normalizePathQuery(rawQuery) {
3581
+ const value = String(rawQuery ?? '').trim().toLowerCase().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
3582
+ return value.length >= 3 && !/\s/.test(value) ? value : '';
3583
+ }
3584
+
3585
+ // Exact path / path-suffix (whole segments) / basename match for single-term queries.
3586
+ function scorePathQuery(pathQuery, filePath) {
3587
+ if (!pathQuery) {
3588
+ return null;
3589
+ }
3590
+ const lower = filePath.toLowerCase();
3591
+ const noExt = lower.replace(/\.[a-z0-9]+$/, '');
3592
+ if (pathQuery === lower) {
3593
+ return { score: PATH_EXACT_SCORE, reason: `path_exact:${filePath}` };
3594
+ }
3595
+ if (pathQuery.includes('/')) {
3596
+ if (noExt === pathQuery || lower.endsWith(`/${pathQuery}`) || noExt.endsWith(`/${pathQuery}`)) {
3597
+ return { score: PATH_SUFFIX_SCORE, reason: `path_suffix:${pathQuery}` };
3598
+ }
3599
+ return null;
3600
+ }
3601
+ const base = lower.slice(lower.lastIndexOf('/') + 1);
3602
+ if (pathQuery === base || pathQuery === base.replace(/\.[a-z0-9]+$/, '')) {
3603
+ return { score: PATH_BASENAME_SCORE, reason: `path_basename:${pathQuery}` };
3604
+ }
3605
+ return null;
3606
+ }
3607
+
3608
+ function scoreDirectFileMatch({ queryDescriptor, rawQuery = '', filePath, searchDescriptor, tokenWeights = null }) {
3397
3609
  let score = 0;
3398
3610
  const reasons = [];
3611
+ const weightOf = (token) => tokenWeights?.get(token) ?? 1;
3612
+
3613
+ const pathHit = scorePathQuery(normalizePathQuery(rawQuery), filePath);
3614
+ if (pathHit) {
3615
+ score += pathHit.score;
3616
+ reasons.push(pathHit.reason);
3617
+ }
3399
3618
 
3400
3619
  if (
3401
3620
  queryDescriptor.compact.length >= 6
@@ -3407,43 +3626,45 @@ function scoreDirectFileMatch({ queryDescriptor, filePath, searchDescriptor }) {
3407
3626
 
3408
3627
  for (const token of queryDescriptor.tokens) {
3409
3628
  if (searchDescriptor.path.tokens.has(token)) {
3410
- score += 3;
3629
+ score += 3 * weightOf(token);
3411
3630
  reasons.push(`path_token:${token}`);
3412
- } else if (searchDescriptor.path.rawLower.includes(token)) {
3413
- score += 1;
3631
+ } else if (token.length >= MIN_SUBSTRING_TOKEN_LENGTH && searchDescriptor.path.rawLower.includes(token)) {
3632
+ score += weightOf(token);
3414
3633
  reasons.push(`path_contains:${token}`);
3415
3634
  }
3416
3635
  }
3417
3636
 
3637
+ const symbolHits = [];
3418
3638
  for (const symbolDescriptor of searchDescriptor.symbols) {
3419
3639
  if (
3420
3640
  queryDescriptor.compact.length >= 4
3421
3641
  && symbolDescriptor.descriptor.compact === queryDescriptor.compact
3422
3642
  ) {
3423
- score += 8;
3424
- reasons.push(`symbol_exact:${symbolDescriptor.name}`);
3643
+ symbolHits.push({ score: SYMBOL_EXACT_SCORE * (symbolDescriptor.local ? LOCAL_SYMBOL_FACTOR : 1), reasons: [`symbol_exact:${symbolDescriptor.name}`] });
3425
3644
  continue;
3426
3645
  }
3427
3646
 
3647
+ let symbolScore = 0;
3648
+ const symbolReasons = [];
3428
3649
  if (
3429
3650
  queryDescriptor.compact.length >= 6
3430
3651
  && symbolDescriptor.descriptor.compact.includes(queryDescriptor.compact)
3431
3652
  ) {
3432
- score += 5;
3433
- reasons.push(`symbol_compact:${symbolDescriptor.name}`);
3653
+ symbolScore += 5;
3654
+ symbolReasons.push(`symbol_compact:${symbolDescriptor.name}`);
3434
3655
  }
3435
3656
 
3436
3657
  let symbolContributed = false;
3437
3658
 
3438
3659
  for (const token of queryDescriptor.tokens) {
3439
3660
  if (symbolDescriptor.descriptor.tokens.has(token)) {
3440
- score += 3;
3661
+ symbolScore += 3 * weightOf(token);
3441
3662
  symbolContributed = true;
3442
- reasons.push(`symbol_token:${symbolDescriptor.name}:${token}`);
3443
- } else if (symbolDescriptor.descriptor.rawLower.includes(token)) {
3444
- score += 1;
3663
+ symbolReasons.push(`symbol_token:${symbolDescriptor.name}:${token}`);
3664
+ } else if (token.length >= MIN_SUBSTRING_TOKEN_LENGTH && symbolDescriptor.descriptor.rawLower.includes(token)) {
3665
+ symbolScore += weightOf(token);
3445
3666
  symbolContributed = true;
3446
- reasons.push(`symbol_contains:${symbolDescriptor.name}`);
3667
+ symbolReasons.push(`symbol_contains:${symbolDescriptor.name}`);
3447
3668
  }
3448
3669
  }
3449
3670
 
@@ -3453,15 +3674,54 @@ function scoreDirectFileMatch({ queryDescriptor, filePath, searchDescriptor }) {
3453
3674
  // from the stronger tiers above.
3454
3675
  if (!symbolContributed && queryDescriptor.compact.length >= 6) {
3455
3676
  if (symbolFuzzyMatches(queryDescriptor.compact, symbolDescriptor.descriptor.compact)) {
3456
- score += 3;
3457
- reasons.push(`symbol_fuzzy:${symbolDescriptor.name}`);
3677
+ symbolScore += 3;
3678
+ symbolReasons.push(`symbol_fuzzy:${symbolDescriptor.name}`);
3458
3679
  }
3459
3680
  }
3681
+
3682
+ if (symbolScore > 0) {
3683
+ symbolHits.push({ score: symbolScore * (symbolDescriptor.local ? LOCAL_SYMBOL_FACTOR : 1), reasons: symbolReasons });
3684
+ }
3460
3685
  }
3461
3686
 
3687
+ // Best symbol dominates; further symbols add with sharp diminishing returns so
3688
+ // file size (symbol count) cannot outvote match quality.
3689
+ symbolHits.sort((a, b) => b.score - a.score);
3690
+ let decay = 1;
3691
+ symbolHits.forEach((hit, index) => {
3692
+ score += hit.score * decay;
3693
+ decay *= SYMBOL_DECAY;
3694
+ if (index < SYMBOL_REASON_LIMIT) {
3695
+ reasons.push(...hit.reasons);
3696
+ }
3697
+ });
3698
+
3462
3699
  return { score, reasons: [...new Set(reasons)], filePath };
3463
3700
  }
3464
3701
 
3702
+ // Import-graph, hotspot and archetype boosts are context, not evidence: they may
3703
+ // reorder near-equal direct matches but never lift a weak match over a strong one,
3704
+ // and files with no direct match stay below the best direct match.
3705
+ function capBoostLift({ directScores, scores }) {
3706
+ let maxDirect = 0;
3707
+ for (const entry of directScores.values()) {
3708
+ maxDirect = Math.max(maxDirect, entry.score);
3709
+ }
3710
+ for (const [filePath, entry] of scores) {
3711
+ const base = directScores.get(filePath)?.score;
3712
+ if (base === undefined) {
3713
+ entry.score = Math.min(entry.score, BOOST_ONLY_RATIO * maxDirect);
3714
+ } else {
3715
+ entry.score = base + Math.min(Math.max(entry.score - base, 0), BOOST_LIFT_RATIO * base + 1);
3716
+ }
3717
+ }
3718
+ return scores;
3719
+ }
3720
+
3721
+ function finalizeScore(entry) {
3722
+ return Number((entry.score * mirrorPrior(entry.filePath)).toFixed(2));
3723
+ }
3724
+
3465
3725
  // Fuzzy predicate shared by scoreDirectFileMatch and resolveSymbolCandidates:
3466
3726
  // ordered containment (either direction, on tokens or compacts) or a bounded
3467
3727
  // Damerau distance. Cheap length gates run first so the common non-fuzzy case
@@ -3939,11 +4199,124 @@ function buildFileSearchDescriptors(files, symbolMap) {
3939
4199
  return descriptors;
3940
4200
  }
3941
4201
 
4202
+ // Rows whose declaration is not exported. 'callable' keeps its pre-3.5.4 weight.
4203
+ // Outline-only: a 'callable' const without `export` is also unexported.
4204
+ function isLocalOutlineRow(item) {
4205
+ return isLocalSymbolRow(item) || (item?.type === 'callable' && !/^\s*export\b/.test(item?.signature ?? ''));
4206
+ }
4207
+
4208
+ function isLocalSymbolRow(symbol) {
4209
+ const type = symbol?.type;
4210
+ if (type === 'local-function' || type === 'local-class' || type === 'method') {
4211
+ return true;
4212
+ }
4213
+ return type === 'type' && !/^\s*export\b/.test(symbol?.signature ?? '');
4214
+ }
4215
+
4216
+ // Single identifiers, questions and non-ASCII (Vietnamese) prose are descriptions of behaviour, not strings
4217
+ // that appear in source, so they never pay for a content search.
4218
+ function looksLikeLiteralMessage(query) {
4219
+ return /^[\x20-\x7e]+$/.test(query)
4220
+ && query.split(/\s+/).length >= CONTENT_LANE_MIN_TOKENS // identifiers and short phrases are symbol queries, never a message
4221
+ && !/^(?:how|where|what|why|which|when|who|does|do|is|are|can|find|show|list)\b/i.test(query);
4222
+ }
4223
+
4224
+ // Stable verify order: index evidence first (rarity-weighted overlap of the query tokens with
4225
+ // each file's path and symbol tokens), originals before mirrors, then path order.
4226
+ function rankContentLaneFiles({ files, searchDescriptorsByFile, tokenWeights, queryTokens, includeLikelyTestFiles }) {
4227
+ const rows = [];
4228
+ for (const file of safeItems(files)) {
4229
+ const filePath = file?.filePath;
4230
+ if (typeof filePath !== 'string' || !CONTENT_LANE_CODE_EXT.test(filePath)) {
4231
+ continue;
4232
+ }
4233
+ if (isLikelyTestFilePath(filePath) && !includeLikelyTestFiles) {
4234
+ continue;
4235
+ }
4236
+ let overlap = 0;
4237
+ const descriptor = searchDescriptorsByFile.get(filePath);
4238
+ if (descriptor) {
4239
+ const seen = new Set(descriptor.path.tokens);
4240
+ for (const symbol of descriptor.symbols) {
4241
+ for (const token of symbol.descriptor.tokens) {
4242
+ seen.add(token);
4243
+ }
4244
+ }
4245
+ for (const token of queryTokens) {
4246
+ if (seen.has(token)) {
4247
+ overlap += tokenWeights?.get(token) ?? 1;
4248
+ }
4249
+ }
4250
+ }
4251
+ rows.push({ filePath, overlap, mirror: mirrorPrior(filePath) < 1 ? 1 : 0, size: Number.isFinite(Number(file.size)) && Number(file.size) >= 0 ? Number(file.size) : null });
4252
+ }
4253
+ rows.sort((a, b) => (b.overlap - a.overlap) || (a.mirror - b.mirror) || (a.filePath < b.filePath ? -1 : a.filePath > b.filePath ? 1 : 0));
4254
+ return rows;
4255
+ }
4256
+
4257
+ // Reads files in priority order (batched for speed, consumed in order) until the hit limit or a
4258
+ // count/byte cap. Caps are checked at batch boundaries on counts and byte totals only, so the
4259
+ // same tree yields the same hits regardless of machine load.
4260
+ async function scanContentLane({ absoluteRoot, ordered, tokens, limit }) {
4261
+ const hits = [];
4262
+ const truncated = new Set();
4263
+ if (tokens.length === 0) {
4264
+ return { hits, truncated: [] };
4265
+ }
4266
+ let scanned = 0;
4267
+ let bytes = 0;
4268
+ const deadline = Date.now() + CONTENT_LANE_SAFETY_MS;
4269
+ for (let start = 0; start < ordered.length && hits.length < limit; start += CONTENT_LANE_BATCH) {
4270
+ if (scanned >= CONTENT_LANE_MAX_FILES) { truncated.add('max-files'); break; }
4271
+ if (bytes >= CONTENT_LANE_MAX_BYTES) { truncated.add('max-bytes'); break; }
4272
+ if (Date.now() > deadline) { truncated.add('time-budget'); break; }
4273
+ const batch = ordered.slice(start, start + Math.min(CONTENT_LANE_BATCH, CONTENT_LANE_MAX_FILES - scanned));
4274
+ // Size comes from the index entry, else a stat; an oversized file is skipped before any read.
4275
+ const texts = await Promise.all(batch.map(async (row) => {
4276
+ try {
4277
+ const absolute = path.join(absoluteRoot, row.filePath);
4278
+ const size = row.size ?? (await fs.stat(absolute)).size;
4279
+ if (size > CONTENT_LANE_MAX_FILE_BYTES) {
4280
+ return { text: '', size: 0 };
4281
+ }
4282
+ const text = await fs.readFile(absolute, 'utf8');
4283
+ return { text, size: Buffer.byteLength(text, 'utf8') };
4284
+ } catch {
4285
+ return { text: '', size: 0 };
4286
+ }
4287
+ }));
4288
+ for (const [index, { text, size }] of texts.entries()) {
4289
+ scanned += 1;
4290
+ bytes += size;
4291
+ if (text.length === 0 || size > CONTENT_LANE_MAX_FILE_BYTES) {
4292
+ continue;
4293
+ }
4294
+ const lower = text.toLowerCase();
4295
+ if (!tokens.every((token) => lower.includes(token))) {
4296
+ continue;
4297
+ }
4298
+ const lines = lower.split('\n');
4299
+ const lineIndex = lines.findIndex((line) => tokens.every((token) => line.includes(token)));
4300
+ if (lineIndex >= 0) {
4301
+ hits.push({ filePath: batch[index].filePath, line: lineIndex + 1 });
4302
+ if (hits.length >= limit) {
4303
+ break;
4304
+ }
4305
+ }
4306
+ }
4307
+ }
4308
+ if (scanned >= CONTENT_LANE_MAX_FILES && scanned < ordered.length && hits.length < limit) {
4309
+ truncated.add('max-files');
4310
+ }
4311
+ return { hits, truncated: [...truncated] };
4312
+ }
4313
+
3942
4314
  function createFileSearchDescriptor({ filePath, symbols }) {
3943
4315
  return {
3944
4316
  path: buildTextSearchDescriptor(filePath),
3945
4317
  symbols: symbols.map((symbol) => ({
3946
4318
  name: symbol.name,
4319
+ local: isLocalSymbolRow(symbol),
3947
4320
  descriptor: buildTextSearchDescriptor(symbol.name),
3948
4321
  })),
3949
4322
  };
@@ -53,12 +53,15 @@ if (!query && !symbolQuery) {
53
53
  query,
54
54
  limit: effectiveLimit,
55
55
  });
56
+ // The status rides on the array as a non-enumerable prop, so the cache stores it explicitly.
57
+ const contentLaneTruncated = cached ? (cached.contentLaneTruncated ?? []) : [...(results.contentLaneTruncated ?? [])];
56
58
 
57
59
  if (!cached) {
58
60
  await writeRecentCacheEntry(cachePath, {
59
61
  requestKey,
60
62
  updatedAt: Date.now(),
61
63
  result: results,
64
+ contentLaneTruncated,
62
65
  }, {
63
66
  maxEntries: DEFAULT_RECENT_CACHE_MAX_ENTRIES,
64
67
  });
@@ -71,6 +74,7 @@ if (!query && !symbolQuery) {
71
74
 
72
75
  if (existingResults.length === 0) {
73
76
  console.log('[ukit:index:query] no matches');
77
+ printContentLaneNotice(contentLaneTruncated);
74
78
  } else {
75
79
  console.log(`[ukit:index:query] top ${existingResults.length} matches for: ${query}`);
76
80
  for (const [idx, item] of existingResults.entries()) {
@@ -82,9 +86,10 @@ if (!query && !symbolQuery) {
82
86
  console.log(` reasons: ${item.reasons.join(', ')}`);
83
87
  }
84
88
  if (showOutline && idx < OUTLINE_TOP_FILES_LIMIT) {
85
- await printOutlineForFile(rootDir, item.filePath);
89
+ await printOutlineForFile(rootDir, item.filePath, indexCore.queryMatchedSymbolNames?.(item) ?? null);
86
90
  }
87
91
  }
92
+ printContentLaneNotice(contentLaneTruncated);
88
93
  }
89
94
  }
90
95
 
@@ -98,6 +103,12 @@ catch (error) {
98
103
  }
99
104
  }
100
105
 
106
+ function printContentLaneNotice(truncated) {
107
+ if (Array.isArray(truncated) && truncated.length > 0) {
108
+ console.log(`content-lane: truncated (${truncated.join(',')}) — results may be incomplete`);
109
+ }
110
+ }
111
+
101
112
  async function runSymbolMode(symbolQuery) {
102
113
  try {
103
114
  await ensureFreshIndex({ rootDir, logPrefix: 'index:query' });
@@ -177,11 +188,11 @@ async function fileExists(absolutePath) {
177
188
  }
178
189
  }
179
190
 
180
- async function printOutlineForFile(root, filePath) {
191
+ async function printOutlineForFile(root, filePath, focus = null) {
181
192
  if (typeof getFileOutline !== 'function') {
182
193
  return;
183
194
  }
184
- const outline = await getFileOutline({ rootDir: root, filePath, limit: Infinity });
195
+ const outline = await getFileOutline({ rootDir: root, filePath, limit: Infinity, focus });
185
196
  if (outline.length === 0) {
186
197
  return;
187
198
  }
@@ -79,7 +79,7 @@ async function printEditHint({ rootDir, targetFile, intent }) {
79
79
  target = path.relative(path.resolve(rootDir), target).split(path.sep).join('/');
80
80
  if (!target || target.startsWith('..') || path.isAbsolute(target)) return; // outside the project: silent
81
81
  }
82
- const hint = await editHintFor({ projectRoot: rootDir, target, query: intent });
82
+ const hint = await editHintFor({ projectRoot: rootDir, target, query: intent, capture: true });
83
83
  if (hint.text) console.log(hint.text);
84
84
  } catch {
85
85
  // Hints are advisory; never fail the helper.