@codua/codeoutline-win32-x64 0.2.6 → 0.2.9

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 (72) hide show
  1. package/README.md +205 -3
  2. package/README.zh-CN.md +40 -2
  3. package/bin/xnet.exe +0 -0
  4. package/build-info.json +1 -1
  5. package/package.json +1 -1
  6. package/scripts/codeoutline/affected.lua +145 -0
  7. package/scripts/codeoutline/automatic_events.lua +202 -0
  8. package/scripts/codeoutline/cache_repairs.lua +47 -0
  9. package/scripts/codeoutline/callers.lua +56 -16
  10. package/scripts/codeoutline/cargo_toml.lua +125 -0
  11. package/scripts/codeoutline/command.lua +26 -4
  12. package/scripts/codeoutline/common.lua +48 -7
  13. package/scripts/codeoutline/completion.lua +126 -22
  14. package/scripts/codeoutline/coverage.lua +63 -0
  15. package/scripts/codeoutline/cpp_bindings.lua +46 -11
  16. package/scripts/codeoutline/cpp_fragments.lua +143 -0
  17. package/scripts/codeoutline/cpp_implementations.lua +340 -0
  18. package/scripts/codeoutline/cpp_includes.lua +156 -0
  19. package/scripts/codeoutline/cpp_macros.lua +279 -0
  20. package/scripts/codeoutline/cpp_receivers.lua +342 -0
  21. package/scripts/codeoutline/cpp_types.lua +275 -28
  22. package/scripts/codeoutline/definition_candidates.lua +180 -0
  23. package/scripts/codeoutline/dispatch_aliases.lua +10 -5
  24. package/scripts/codeoutline/documents.lua +22 -9
  25. package/scripts/codeoutline/explore.lua +243 -122
  26. package/scripts/codeoutline/external_headers.lua +171 -0
  27. package/scripts/codeoutline/function_values.lua +69 -0
  28. package/scripts/codeoutline/go_methods.lua +931 -0
  29. package/scripts/codeoutline/go_modules.lua +329 -0
  30. package/scripts/codeoutline/graph.lua +322 -67
  31. package/scripts/codeoutline/implementations.lua +403 -0
  32. package/scripts/codeoutline/index.lua +161 -28
  33. package/scripts/codeoutline/index_worker.lua +11 -4
  34. package/scripts/codeoutline/indirect.lua +4 -2
  35. package/scripts/codeoutline/js_evidence.lua +2 -1
  36. package/scripts/codeoutline/js_resolution.lua +40 -12
  37. package/scripts/codeoutline/js_workspace.lua +325 -0
  38. package/scripts/codeoutline/lang/c.lua +15 -2
  39. package/scripts/codeoutline/lang/cpp.lua +7 -4
  40. package/scripts/codeoutline/lang/csharp.lua +1 -1
  41. package/scripts/codeoutline/lang/js.lua +56 -20
  42. package/scripts/codeoutline/lang/rust.lua +9 -1
  43. package/scripts/codeoutline/language_detect.lua +100 -0
  44. package/scripts/codeoutline/lsp.lua +173 -23
  45. package/scripts/codeoutline/lua_bindings.lua +151 -47
  46. package/scripts/codeoutline/lua_callback_loops.lua +210 -0
  47. package/scripts/codeoutline/main.lua +32 -7
  48. package/scripts/codeoutline/mcp.lua +52 -9
  49. package/scripts/codeoutline/navigation.lua +284 -64
  50. package/scripts/codeoutline/on_demand.lua +93 -0
  51. package/scripts/codeoutline/ordinary_bindings.lua +210 -34
  52. package/scripts/codeoutline/parse.lua +18 -2
  53. package/scripts/codeoutline/parse_pool.lua +1 -1
  54. package/scripts/codeoutline/parse_worker.lua +1 -1
  55. package/scripts/codeoutline/python_bindings.lua +2 -2
  56. package/scripts/codeoutline/query_filters.lua +65 -0
  57. package/scripts/codeoutline/query_report.lua +56 -19
  58. package/scripts/codeoutline/resolution.lua +23 -0
  59. package/scripts/codeoutline/rust_packages.lua +203 -0
  60. package/scripts/codeoutline/rust_resolution.lua +301 -0
  61. package/scripts/codeoutline/search_ranking.lua +70 -0
  62. package/scripts/codeoutline/service.lua +47 -7
  63. package/scripts/codeoutline/shared_events.lua +369 -0
  64. package/scripts/codeoutline/static_dispatch.lua +46 -11
  65. package/scripts/codeoutline/text.lua +3 -2
  66. package/scripts/codeoutline/ts_implementations.lua +81 -0
  67. package/scripts/codeoutline/type_bases.lua +61 -0
  68. package/scripts/codeoutline/type_hierarchy.lua +324 -0
  69. package/scripts/codeoutline/type_references.lua +290 -0
  70. package/scripts/codeoutline/type_uses.lua +260 -0
  71. package/scripts/codeoutline/update_sequence.lua +1 -1
  72. package/scripts/codeoutline/version.lua +1 -1
@@ -27,6 +27,7 @@ function M.validate(query, opts)
27
27
  assert(type(query) == 'string' and query:find('%S') and #query <= 4096 and not query:find('%z'),
28
28
  'query must contain 1-4096 bytes of non-empty text without NUL')
29
29
  assert(text.valid(query) == query, 'query must be valid UTF-8')
30
+ require('codeoutline.query_filters').parse(query)
30
31
  assert(opts == nil or type(opts) == 'table', 'options must be a table')
31
32
  local budget = M.DEFAULT_BUDGET
32
33
  if opts and opts.budget ~= nil then budget = opts.budget end
@@ -59,16 +60,6 @@ for w in ([[the a an and or of to in on for with from by is are was be how what
59
60
  STOP[w] = true
60
61
  end
61
62
 
62
- local VENDORED = { '/3rd/', '^3rd/', '/third_party/', '^third_party/', '/thirdparty/',
63
- '/vendor/', '^vendor/', '/node_modules/', '/external/', '^external/', '/deps/', '^deps/' }
64
-
65
- local function vendored(path)
66
- for _, p in ipairs(VENDORED) do
67
- if path:find(p) then return true end
68
- end
69
- return false
70
- end
71
-
72
63
  -- Split camelCase / snake_case into lowercase segments.
73
64
  local function segments(name)
74
65
  local out = {}
@@ -101,7 +92,7 @@ local function terms(query)
101
92
  for _, p in ipairs(parts) do seen['name:' .. p] = true; seen['word:' .. p] = true end
102
93
  end
103
94
  end
104
- for path in query:gmatch('[%w_%-%./]+%.%a%a?%a?%a?') do
95
+ for path in query:gmatch('[%w_%-%./]+%.[%a][%w_]*') do
105
96
  local ext = path:match('%.(%a+)$')
106
97
  if path:find('/') or (ext and SOURCE_EXT[ext:lower()]) then add('file', path) end
107
98
  end
@@ -116,21 +107,21 @@ local function terms(query)
116
107
  return out
117
108
  end
118
109
 
119
- -- Rank one candidate node for a query term.
120
- local function seed_score(G, id, exact)
121
- local s = (KIND_WEIGHT[G.nodes[id].kind] or 1) + (exact and 20 or 0)
122
- if vendored(G.files[G.node_file[id]].path) then s = s - 6 end
123
- return s
124
- end
125
-
126
- local function find_seeds(G, query)
110
+ local function find_seeds(G, query, filters, ranking)
111
+ local predicate = require('codeoutline.query_filters')
112
+ local function seed_score(id, exact, explicit)
113
+ local s = (KIND_WEIGHT[G.nodes[id].kind] or 1) + (exact and 20 or 0)
114
+ return s - ranking.penalty(G.files[G.node_file[id]].path, explicit)
115
+ end
127
116
  local cands = {} -- id -> score
128
117
  local files = {} -- file indices named in the query
129
118
  local considered = 0
130
119
  local function consider(id, s)
131
120
  considered = considered + 1
132
121
  if considered % 128 == 0 then control.check() end
122
+ if not predicate.id(filters, G, id) then return end
133
123
  if not cands[id] or cands[id] < s then cands[id] = s end
124
+ return true
134
125
  end
135
126
  local list_terms = terms(query)
136
127
  local has_code = false
@@ -144,14 +135,18 @@ local function find_seeds(G, query)
144
135
  -- matching, which is where English words pick up noise), and rank
145
136
  -- below code-like terms when the query has any.
146
137
  for _, id in ipairs(G.by_name[t.text] or {}) do
147
- consider(id, seed_score(G, id, true) - (has_code and 12 or 8))
138
+ consider(id, seed_score(id, true) - (has_code and 12 or 8))
148
139
  end
149
140
  elseif t.kind == 'file' then
150
141
  local want = t.text:gsub('\\', '/')
151
142
  for i, f in ipairs(G.file_order) do
152
143
  if i % 128 == 0 then control.check() end
153
144
  local rec = G.files[f]
154
- if rec.path == want or rec.path:sub(-(#want + 1)) == '/' .. want then files[#files + 1] = f end
145
+ if (rec.path == want or rec.path:sub(-(#want + 1)) == '/' .. want) and predicate.file(filters, rec) then
146
+ for _, node in ipairs(rec.nodes) do
147
+ if predicate.node(filters, rec, node) then files[#files + 1] = f; break end
148
+ end
149
+ end
155
150
  end
156
151
  elseif t.kind == 'qualified' then
157
152
  local last = t.text:match('([%w_]+)$')
@@ -160,43 +155,74 @@ local function find_seeds(G, query)
160
155
  if i % 128 == 0 then control.check() end
161
156
  local q = G.nodes[id].qualified:gsub('[:]+', '.')
162
157
  if q == t.text or q:sub(-(#t.text + 1)) == '.' .. t.text then
163
- consider(id, seed_score(G, id, true) + 10)
158
+ consider(id, seed_score(id, true, true) + 10)
164
159
  elseif select(2, t.text:gsub('%.', '')) == 1
165
160
  and G.files[G.node_file[id]].path:match('([^/]+)%.[^./]+$') == first then
166
161
  -- module.func where the module is the file: Lua's `local M`
167
162
  -- tables and Python modules are named by their file
168
- consider(id, seed_score(G, id, true) + 8)
163
+ consider(id, seed_score(id, true, true) + 8)
169
164
  end
170
165
  end
171
166
  else
172
167
  local exact = G.by_name[t.text]
173
168
  if exact then
174
169
  -- a name defined in many places is generic; keep its best few
175
- for _, id in ipairs(exact) do consider(id, seed_score(G, id, true) - math.min(#exact, 20) * 0.2) end
170
+ for _, id in ipairs(exact) do consider(id, seed_score(id, true) - math.min(#exact, 20) * 0.2) end
176
171
  else
177
172
  local ci = G.by_lname[t.text:lower()]
178
173
  if ci then
179
- for _, id in ipairs(ci) do consider(id, seed_score(G, id, true) - 2) end
174
+ for _, id in ipairs(ci) do consider(id, seed_score(id, true) - 2) end
180
175
  elseif #t.text >= 4 then
181
176
  -- fuzzy: every query segment appears in the name's segments
182
177
  local want = segments(t.text)
183
178
  local hits, visited = 0, 0
184
- for name, ids in pairs(G.by_name) do
185
- visited = visited + 1
186
- if visited % 128 == 0 then control.check() end
187
- local lname = name:lower()
188
- local ok = true
189
- for _, w in ipairs(want) do
190
- if not lname:find(w, 1, true) then ok = false; break end
179
+ for _, names in ipairs(G.query_base_names and { G.by_name, G.query_base_names } or { G.by_name }) do
180
+ for name, ids in pairs(names) do
181
+ if names ~= G.query_base_names or rawget(G.by_name, name) == nil then
182
+ visited = visited + 1
183
+ if visited % 128 == 0 then control.check() end
184
+ local lname = name:lower()
185
+ local ok = true
186
+ for _, w in ipairs(want) do
187
+ if not lname:find(w, 1, true) then ok = false; break end
188
+ end
189
+ if ok then
190
+ local accepted = false
191
+ for _, id in ipairs(ids) do
192
+ if consider(id, seed_score(id, false) - #name * 0.05) then accepted = true end
193
+ end
194
+ if accepted then hits = hits + 1 end
195
+ if hits > 200 then break end
196
+ end
197
+ end
191
198
  end
192
- if ok then
193
- for _, id in ipairs(ids) do consider(id, seed_score(G, id, false) - #name * 0.05) end
194
- hits = hits + 1
195
- if hits > 200 then break end
199
+ if hits > 200 then break end
200
+ end
201
+ end
202
+ end
203
+ end
204
+ end
205
+ if query == '' then
206
+ local count = 0
207
+ -- With a configured policy, select the candidate window from preferred
208
+ -- files first so an early generated directory cannot fill all 512 slots.
209
+ for pass = 1, ranking.configured and 2 or 1 do
210
+ for _, f in ipairs(G.file_order) do
211
+ control.check()
212
+ local rec = G.files[f]
213
+ if predicate.file(filters, rec) and (not ranking.configured
214
+ or (ranking.penalty(rec.path) > 0) == (pass == 2)) then
215
+ for i, id in ipairs(G.id_of[f]) do
216
+ if i % 256 == 0 then control.check() end
217
+ if predicate.id(filters, G, id) then
218
+ if count >= 512 then filters.seed_limit_reached = true; break end
219
+ consider(id, seed_score(id, false)); count = count + 1
196
220
  end
197
221
  end
198
222
  end
223
+ if filters.seed_limit_reached then break end
199
224
  end
225
+ if filters.seed_limit_reached then break end
200
226
  end
201
227
  end
202
228
  local list = {}
@@ -211,9 +237,9 @@ local function find_seeds(G, query)
211
237
  return list, files
212
238
  end
213
239
 
214
- -- Shortest call path a -> b (out edges), up to depth; returns id list.
240
+ -- Shortest dependency path a -> b, retaining edge kinds for presentation.
215
241
  local function path_between(G, a, b, depth)
216
- local prev, frontier = { [a] = a }, { a }
242
+ local prev, frontier, via = { [a] = a }, { a }, {}
217
243
  local expansion_limited = false
218
244
  for _ = 1, depth do
219
245
  local next_frontier = {}
@@ -227,29 +253,40 @@ local function path_between(G, a, b, depth)
227
253
  local dst = out[i]
228
254
  if not prev[dst] then
229
255
  prev[dst] = x
256
+ via[dst] = { source = x, target = dst, kind = out[i + 2], line = out[i + 1] }
230
257
  if dst == b then
231
258
  local path, y = { b }, b
232
259
  while y ~= a do y = prev[y]; table.insert(path, 1, y) end
233
- return path
260
+ local hops = {}; for n = 2, #path do hops[#hops + 1] = via[path[n]] end
261
+ return path, false, prev, expansion_limited, hops
234
262
  end
235
263
  next_frontier[#next_frontier + 1] = dst
236
264
  end
237
265
  end
238
266
  end
239
267
  frontier = next_frontier
240
- if #frontier == 0 then return nil, false, prev, expansion_limited end
241
- if #frontier > 20000 then return nil, true, prev, expansion_limited end
268
+ if #frontier == 0 then return nil, false, prev, expansion_limited, nil, via end
269
+ if #frontier > 20000 then return nil, true, prev, expansion_limited, nil, via end
242
270
  end
243
- return nil, #frontier > 0, prev, expansion_limited
271
+ return nil, #frontier > 0, prev, expansion_limited, nil, via
244
272
  end
245
273
 
246
- local file_cache = {}
274
+ local file_cache, source_cache = {}, {}
275
+ local encoding_retry = {}
276
+ local function checked_source(idx, rel)
277
+ local key = idx.root .. '/' .. rel
278
+ if source_cache[key] then return source_cache[key] end
279
+ local source, repaired = idx:query_source(rel)
280
+ assert(source, 'cannot read source: ' .. rel)
281
+ if repaired then error(encoding_retry, 0) end
282
+ source_cache[key] = source; return source
283
+ end
247
284
  local function file_lines(idx, rel)
248
285
  local key = idx.root .. '/' .. rel
249
286
  local lines = file_cache[key]
250
287
  if lines then return lines end
251
288
  lines = {}
252
- local src = assert(idx:query_source(rel), 'cannot read source: ' .. rel)
289
+ local src = checked_source(idx, rel)
253
290
  if src then
254
291
  for line in (src .. '\n'):gmatch('([^\n]*)\n') do lines[#lines + 1] = (line:gsub('\r$', '')) end
255
292
  end
@@ -305,18 +342,55 @@ local function label(G, id)
305
342
  return string.format('%s %s (%s)', node.kind, node.qualified, graph.where(G, id))
306
343
  end
307
344
 
345
+ local edge_label = require('codeoutline.query_report').edge_label
346
+
347
+ local function candidate_text(G, idx, report, in_order)
348
+ if #report.entries == 0 then return nil end
349
+ local lines, references, used = {}, {}, 0
350
+ local function append(line, files)
351
+ line = text.valid(line)
352
+ if files then references[#references + 1] = { at = used, files = files } end
353
+ lines[#lines + 1] = line; used = used + #line + 1
354
+ end
355
+ append('\n## Unconfirmed definition candidates')
356
+ append('Suggestions for unresolved calls only, not call edges or verified bindings. Inspect the source before using them.')
357
+ local shown = {}
358
+ for _, group in ipairs(report.entries) do
359
+ append(string.format('- Unresolved %s at %s:%d: %s', group.call, group.path, group.line, group.resolution_reason),
360
+ { G.node_file[group.source] })
361
+ for _, candidate in ipairs(group.candidates) do
362
+ local id = candidate.id
363
+ append(' Unconfirmed candidate: ' .. label(G, id) .. '; ' .. candidate.reason, { G.node_file[id] })
364
+ if not in_order[id] and not shown[id] then
365
+ local node = G.nodes[id]
366
+ local source = file_lines(idx, candidate.path)
367
+ for line = node.line, math.min(#source, node.end_line, node.line + 7) do
368
+ append(string.format('%d\t%s', line, source[line]), { G.node_file[id] })
369
+ end
370
+ if node.end_line > node.line + 7 then append('\t... (candidate snippet only; explore its file and name for more)') end
371
+ shown[id] = true
372
+ end
373
+ end
374
+ end
375
+ if report.truncated then append('Candidate lookup reached a site, source, evidence or result limit; more candidates may exist.') end
376
+ return table.concat(lines, '\n'), references
377
+ end
378
+
308
379
  -- Run a query over symbol tables (graph.build). Returns the text and a table
309
380
  -- with what was selected; relationships resolve per query.
310
- function M.run(G, idx, query, opts)
381
+ local function run(G, idx, query, opts)
311
382
  control.check()
312
383
  opts = opts or {}
313
384
  local budget = M.validate(query, opts)
314
385
  local query_opts = {}
315
386
  for key, value in pairs(opts) do query_opts[key] = value end
316
387
  query_opts.explain = true
388
+ local ranking = require('codeoutline.search_ranking').policy(G.root or idx.root)
317
389
  G = graph.query(G, query_opts)
318
- file_cache = {}
319
- local ranked, named_files = find_seeds(G, query)
390
+ G.stats.ranking = ranking.stats
391
+ file_cache, source_cache = {}, {}
392
+ local filters = require('codeoutline.query_filters').parse(query)
393
+ local ranked, named_files = find_seeds(G, filters.text, filters, ranking)
320
394
 
321
395
  -- Seeds: top-ranked, but at most 3 definitions per name so one generic
322
396
  -- name can't crowd out the others the query mentions.
@@ -327,44 +401,51 @@ function M.run(G, idx, query, opts)
327
401
  local node = G.nodes[c.id]
328
402
  if node.kind ~= 'prototype' and not node.decl then defined[node.name] = true end
329
403
  end
330
- local seeds, per_name = {}, {}
404
+ local seeds, per_name, seed_selection_limited = {}, {}, false
331
405
  for _, c in ipairs(ranked) do
332
406
  local node = G.nodes[c.id]
333
407
  local name = node.name
334
408
  if not ((node.kind == 'prototype' or node.decl) and defined[name]) then
335
409
  per_name[name] = (per_name[name] or 0) + 1
336
- if per_name[name] <= 3 and #seeds < M.MAX_SEEDS then seeds[#seeds + 1] = c.id end
410
+ if per_name[name] <= 3 and #seeds < M.MAX_SEEDS then seeds[#seeds + 1] = c.id
411
+ else seed_selection_limited = true end
337
412
  end
338
413
  end
339
414
  local is_seed = {}
340
415
  for _, id in ipairs(seeds) do is_seed[id] = true end
341
416
 
342
417
  -- Spine: nodes on call paths between seeds.
343
- local flows, spine, on_spine = {}, {}, {}
418
+ local flows, spine, on_spine, flow_edges, flow_files, non_call_paths = {}, {}, {}, {}, {}, false
344
419
  local reports = require('codeoutline.query_report')
345
420
  local searches, missed, connected = {}, {}, {}
346
421
  local path_limited = false
347
422
  for _, a in ipairs(seeds) do
348
423
  for _, b in ipairs(seeds) do
349
424
  if a ~= b then
350
- local p, limited, prev, expansion_limited = path_between(G, a, b, M.PATH_DEPTH)
425
+ local p, limited, prev, expansion_limited, hops, via = path_between(G, a, b, M.PATH_DEPTH)
351
426
  path_limited = path_limited or limited or false
352
427
  if p then
353
428
  connected[a] = connected[a] or {}
354
429
  connected[a][b] = true
355
- local names = {}
356
- for _, id in ipairs(p) do
357
- names[#names + 1] = G.nodes[id].name
430
+ local names, files = {}, {}
431
+ for n, id in ipairs(p) do
432
+ if n > 1 then
433
+ local kind = edge_label(hops[n - 1].kind)
434
+ names[#names + 1] = kind and (' -[' .. kind .. ']-> ') or ' -> '
435
+ non_call_paths = non_call_paths or kind ~= nil
436
+ end
437
+ names[#names + 1] = G.nodes[id].name; files[#files + 1] = G.node_file[id]
358
438
  if not is_seed[id] and not on_spine[id] then
359
439
  on_spine[id] = true
360
440
  spine[#spine + 1] = id
361
441
  end
362
442
  end
363
- flows[#flows + 1] = table.concat(names, ' -> ')
443
+ flows[#flows + 1] = table.concat(names)
444
+ flow_edges[#flows], flow_files[#flows] = hops, files
364
445
  else
365
446
  if not missed[a] then
366
447
  missed[a] = { root = a, targets = {}, limited = limited, incomplete = expansion_limited,
367
- sites = reports.capture_paths(G.report, prev, a) }
448
+ sites = reports.capture_paths(G.report, prev, a, via) }
368
449
  searches[#searches + 1] = missed[a]
369
450
  end
370
451
  missed[a].targets[#missed[a].targets + 1] = b
@@ -373,11 +454,23 @@ function M.run(G, idx, query, opts)
373
454
  end
374
455
  end
375
456
 
376
- local parts, used, omitted = {}, 0, false
377
- local function emit(s)
457
+ local parts, dependencies, used, omitted = {}, {}, 0, false
458
+ local function emit(s, refs)
459
+ s = text.valid(s)
378
460
  parts[#parts + 1] = s
461
+ dependencies[#parts] = refs or {}
379
462
  used = used + #s + 1
380
463
  end
464
+ local function prepend(s)
465
+ table.insert(parts, 1, s); table.insert(dependencies, 1, {})
466
+ end
467
+ local function location_refs(files) return { { at = 0, files = files } } end
468
+ local function emit_limited(s, limit, cut, refs)
469
+ local block, _, kept = text.limit(s, limit, cut)
470
+ local visible = {}
471
+ for _, ref in ipairs(refs or {}) do if ref.at < kept then visible[#visible + 1] = ref end end
472
+ emit(block, visible)
473
+ end
381
474
  local shown, files_shown, file_order = {}, {}, {}
382
475
 
383
476
  if #seeds == 0 and #named_files == 0 then
@@ -390,11 +483,12 @@ function M.run(G, idx, query, opts)
390
483
  for _, id in ipairs(spine) do nfiles[G.node_file[id]] = true end
391
484
  local nf = 0
392
485
  for _ in pairs(nfiles) do nf = nf + 1 end
393
- emit(string.format('Matched %d symbols in %d files, %d more on call paths between them; short ones bring their callees. Source below is verbatim with line numbers; treat it as already Read.',
394
- #seeds, nf, #spine))
486
+ emit(string.format('Matched %d symbols in %d files, %d more on %s between them; short ones bring %s. Source below is verbatim with line numbers; treat it as already Read.',
487
+ #seeds, nf, #spine, non_call_paths and 'relationship paths' or 'call paths', non_call_paths and 'related functions' or 'their callees'))
395
488
  if #flows > 0 then
396
- emit('\n## Call paths')
397
- for i = 1, math.min(#flows, M.LIST_CAP) do emit(' ' .. flows[i]) end
489
+ emit(non_call_paths and '\n## Relationship paths' or '\n## Call paths')
490
+ if non_call_paths then emit('ref retains a function value; implementation, event and callback hops are static possibilities, not proof of execution.') end
491
+ for i = 1, math.min(#flows, M.LIST_CAP) do emit(' ' .. flows[i], location_refs(flow_files[i])) end
398
492
  end
399
493
 
400
494
  -- Section 2: source, grouped by file in first-appearance order.
@@ -436,50 +530,42 @@ function M.run(G, idx, query, opts)
436
530
  end
437
531
 
438
532
  if G.load_incoming then G:load_incoming(seeds) end
533
+ -- Neighbors below already require these scans. Run them before diagnostics,
534
+ -- including for long seeds that did not take the short-wrapper context path.
535
+ for _, id in ipairs(seeds) do local _ = G.out[id] end
439
536
  if #seeds == 1 then
440
537
  searches[1] = { root = seeds[1], targets = {}, single = true,
441
538
  sites = reports.capture_paths(G.report, { [seeds[1]] = seeds[1] }, seeds[1]) }
442
539
  end
443
540
  local breakpoints = reports.path_breakpoints(G.report, G, searches, connected)
541
+ local candidates = G:definition_candidates()
542
+ G.stats.definition_candidates = candidates.stats
444
543
 
445
- -- Confirm every file whose source or symbol labels this query can emit.
446
- -- GBK reparsing invalidates node IDs, so rebuild and select again before
447
- -- producing any output. Unrelated project files remain speculative.
448
- local selected, changed = {}, false
449
- for _, f in ipairs(file_order) do selected[f] = true end
450
- for _, c in ipairs(ranked) do selected[G.node_file[c.id]] = true end
451
- for _, id in ipairs(seeds) do
452
- for _, edges in ipairs({ G.inn[id] or {}, G.out[id] or {} }) do
453
- for i = 1, #edges, graph.EDGE do selected[G.node_file[edges[i]]] = true end
454
- end
455
- end
456
- for _, entry in ipairs(breakpoints.entries) do
457
- for _, id in ipairs(entry.path) do selected[G.node_file[id]] = true end
458
- if entry.goal then selected[G.node_file[entry.goal]] = true end
459
- end
460
- for f in pairs(selected) do
461
- local path = G.files[f].path -- a decoding repair replaces this file ID
462
- local source, repaired = idx:query_source(path)
463
- assert(source, 'cannot read source: ' .. path)
464
- changed = repaired or changed
465
- end
466
- if changed then return nil, { encoding_retry = true } end
467
-
468
- local evidence_text = reports.render(G.report, G)
544
+ -- Build output as a transaction. Check rendered locations before returning;
545
+ -- an encoding repair aborts immediately and retries with fresh node IDs.
546
+ local evidence_text, evidence_refs = reports.render(G.report, G)
469
547
  local evidence_budget = math.min(4096, math.floor(budget / 4))
470
- local breakpoint_text = reports.render_breakpoints(breakpoints, G)
548
+ local breakpoint_text, breakpoint_refs = reports.render_breakpoints(breakpoints, G)
471
549
  local breakpoint_budget = breakpoint_text and math.floor(evidence_budget / 2) or 0
472
550
  evidence_budget = evidence_budget - breakpoint_budget
473
551
  local breakpoint_cut = breakpoint_text and (#breakpoint_text > breakpoint_budget or breakpoints.truncated) or false
474
- if breakpoint_budget >= 256 then emit(text.limit(breakpoint_text, breakpoint_budget, breakpoints.truncated))
552
+ if breakpoint_budget >= 256 then emit_limited(breakpoint_text, breakpoint_budget, breakpoints.truncated, breakpoint_refs)
475
553
  elseif breakpoint_text then breakpoint_cut = true end
476
554
  omitted = omitted or breakpoint_cut
477
555
  local evidence_cut = #evidence_text > evidence_budget
478
556
  if evidence_budget >= 256 then
479
- emit(text.limit(evidence_text, evidence_budget, G.report.truncated))
557
+ emit_limited(evidence_text, evidence_budget, G.report.truncated, evidence_refs)
480
558
  else evidence_cut = #G.report.entries > 0 end
481
559
  omitted = omitted or evidence_cut or G.report.truncated or #flows > M.LIST_CAP
482
560
 
561
+ local candidate_budget = math.min(3072, math.floor(budget / 5))
562
+ local candidate_block, candidate_refs
563
+ if candidate_budget >= 256 then candidate_block, candidate_refs = candidate_text(G, idx, candidates, in_order) end
564
+ local candidate_cut = candidate_block and (#candidate_block > candidate_budget or candidates.truncated) or candidates.truncated
565
+ if candidate_block then emit_limited(candidate_block, candidate_budget, candidates.truncated, candidate_refs)
566
+ elseif #candidates.entries > 0 then candidate_cut = true end
567
+ omitted = omitted or candidate_cut
568
+
483
569
  local reserve = math.floor(budget * 0.15) -- keep room for sections 3-4
484
570
  for _, f in ipairs(file_order) do
485
571
  local rec = G.files[f]
@@ -487,30 +573,32 @@ function M.run(G, idx, query, opts)
487
573
  local items = by_file[f]
488
574
  table.sort(items, function(a, b) return G.nodes[a.id].line < G.nodes[b.id].line end)
489
575
  local wrote_header = false
490
- if items.outline then
576
+ if items.outline and used + #header + 16 < budget - reserve then
577
+ checked_source(idx, rec.path)
491
578
  local ol = {}
492
579
  for _, node in ipairs(rec.nodes) do
493
- if not node.parent and node.kind ~= 'macro' then
580
+ if not node.parent and node.kind ~= 'macro' and require('codeoutline.query_filters').node(filters, rec, node) then
494
581
  ol[#ol + 1] = string.format('%d\t%s %s', node.line, node.kind, require('codeoutline.navigation').detail(G, f, node).sig or node.name)
495
582
  end
496
583
  if #ol >= 60 then ol[#ol + 1] = '\t...'; break end
497
584
  end
498
585
  local block = header .. ' (outline)\n' .. table.concat(ol, '\n')
499
- if used + #block < budget - reserve then emit(block); wrote_header = true else omitted = true end
500
- end
586
+ if used + #block < budget - reserve then emit(block, location_refs({ f })); wrote_header = true else omitted = true end
587
+ elseif items.outline then omitted = true end
501
588
  for _, item in ipairs(items) do
502
- if not shown[item.id] then
589
+ if not shown[item.id] and used + #header + 16 < budget - reserve then
503
590
  local block, source_cut = node_block(G, idx, item.id, item.full)
504
591
  omitted = omitted or source_cut
505
592
  local need = #block + (wrote_header and 0 or #header + 1) + 1
506
593
  if used + need < budget - reserve then
507
- if not wrote_header then emit(header); wrote_header = true end
508
- emit(block)
594
+ if not wrote_header then emit(header, location_refs({ f })); wrote_header = true end
595
+ emit(block, location_refs({ f }))
509
596
  shown[item.id] = true
510
597
  files_shown[f] = true
511
598
  else
512
599
  pointers[#pointers + 1] = item.id
513
600
  end
601
+ elseif not shown[item.id] then pointers[#pointers + 1] = item.id
514
602
  end
515
603
  end
516
604
  end
@@ -520,73 +608,106 @@ function M.run(G, idx, query, opts)
520
608
  for _, id in ipairs(seeds) do
521
609
  local callers, callees = {}, {}
522
610
  local seen_in, seen_out = {}, {}
611
+ local caller_files, callee_files, incoming_special, outgoing_special = {}, {}, false, false
523
612
  local inn, out = G.inn[id] or {}, G.out[id] or {}
524
613
  for i = 1, #inn, graph.EDGE do
525
614
  local src = inn[i]
526
- if not seen_in[src] and #callers < M.LIST_CAP then
527
- seen_in[src] = true
615
+ local tag, key = edge_label(inn[i + 2]), src .. ':' .. inn[i + 2]
616
+ if not seen_in[key] and #callers < M.LIST_CAP then
617
+ seen_in[key] = true; caller_files[#caller_files + 1] = G.node_file[src]
618
+ incoming_special = incoming_special or tag ~= nil
528
619
  callers[#callers + 1] = string.format('%s (%s:%d)', G.nodes[src].name, G.files[G.node_file[src]].path, inn[i + 1])
529
- .. (inn[i + 2]:match('^indirect:') and (' [' .. inn[i + 2] .. ']') or '')
530
- elseif not seen_in[src] then omitted = true
620
+ .. (tag and (' [' .. tag .. ']') or '')
621
+ elseif not seen_in[key] then omitted = true
531
622
  end
532
623
  end
533
624
  for i = 1, #out, graph.EDGE do
534
625
  local dst = out[i]
535
- if not seen_out[dst] and #callees < M.LIST_CAP then
536
- seen_out[dst] = true
626
+ local tag, key = edge_label(out[i + 2]), dst .. ':' .. out[i + 2]
627
+ if not seen_out[key] and #callees < M.LIST_CAP then
628
+ seen_out[key] = true; callee_files[#callee_files + 1] = G.node_file[dst]
629
+ outgoing_special = outgoing_special or tag ~= nil
537
630
  callees[#callees + 1] = G.nodes[dst].name .. ' (' .. graph.where(G, dst) .. ')'
538
- .. (out[i + 2]:match('^indirect:') and (' [' .. out[i + 2] .. ']') or '')
539
- elseif not seen_out[dst] then omitted = true
631
+ .. (tag and (' [' .. tag .. ']') or '')
632
+ elseif not seen_out[key] then omitted = true
540
633
  end
541
634
  end
542
635
  if #callers > 0 or #callees > 0 then
543
636
  local nsites = math.floor(#inn / graph.EDGE)
544
- rel[#rel + 1] = string.format('%s:\n called by%s: %s\n calls: %s', G.nodes[id].qualified,
545
- nsites > #callers and string.format(' (%d call sites)', nsites) or '',
546
- #callers > 0 and table.concat(callers, ', ') or '-',
547
- #callees > 0 and table.concat(callees, ', ') or '-')
637
+ rel[#rel + 1] = { line = G.nodes[id].qualified .. ':', files = { G.node_file[id] } }
638
+ rel[#rel + 1] = { line = string.format(' %s%s: %s', incoming_special and 'incoming relationships' or 'called by',
639
+ nsites > #callers and string.format(incoming_special and ' (%d sites)' or ' (%d call sites)', nsites) or '',
640
+ #callers > 0 and table.concat(callers, ', ') or '-'), files = caller_files }
641
+ rel[#rel + 1] = { line = ' ' .. (outgoing_special and 'outgoing relationships' or 'calls') .. ': '
642
+ .. (#callees > 0 and table.concat(callees, ', ') or '-'), files = callee_files }
548
643
  end
549
644
  end
550
645
  if #rel > 0 then
551
- local block = '\n## Callers / callees\n' .. table.concat(rel, '\n')
552
- emit(block)
646
+ emit('\n## Callers / callees')
647
+ for _, entry in ipairs(rel) do emit(entry.line, location_refs(entry.files)) end
553
648
  end
554
649
 
555
650
  -- Section 4: pointers for everything that matched but was not shown.
556
651
  local more = {}
557
- for _, id in ipairs(pointers) do more[#more + 1] = ' ' .. label(G, id) end
652
+ for _, id in ipairs(pointers) do if #more < 15 then more[#more + 1] = id end end
558
653
  local extra = 0
559
654
  for _, c in ipairs(ranked) do
560
655
  if not shown[c.id] and not is_seed[c.id] then
561
656
  extra = extra + 1
562
- if #more < 15 then more[#more + 1] = ' ' .. label(G, c.id) end
657
+ if #more < 15 then more[#more + 1] = c.id end
563
658
  end
564
659
  end
565
660
  if #more > 0 then
566
- local block = '\n## Not shown (explore these by name for their source)\n' .. table.concat(more, '\n')
567
- if extra + #pointers > #more then block = block .. string.format('\n ... %d more', extra + #pointers - #more) end
568
- if used + #block <= budget + 400 then emit(block) else omitted = true end
661
+ emit('\n## Not shown (explore these by name for their source)')
662
+ for _, id in ipairs(more) do emit(' ' .. label(G, id), location_refs({ G.node_file[id] })) end
663
+ if extra + #pointers > #more then emit(string.format(' ... %d more', extra + #pointers - #more)) end
569
664
  end
570
665
 
571
666
  if G.incomplete then
572
- table.insert(parts, 1, 'Call-path expansion limit reached; relationships are incomplete.')
573
- omitted = true
667
+ local reasons = require('codeoutline.coverage').relations({ relationships_incomplete = true, query_stats = G.stats })
668
+ prepend('Relationships incomplete: ' .. table.concat(reasons, ', ') .. '.')
574
669
  end
575
670
  if path_limited then
576
- table.insert(parts, 1, 'Call-path search reached its depth/frontier limit; no path found is not proof of no runtime connection.')
671
+ prepend('Call-path search reached its depth/frontier limit; no path found is not proof of no runtime connection.')
577
672
  end
578
673
  if evidence_cut or G.report.truncated then
579
- table.insert(parts, 1, 'Relationship explanations omitted due to evidence/output limits.')
674
+ prepend('Relationship explanations omitted due to evidence/output limits.')
580
675
  end
581
676
  if breakpoint_cut then
582
- table.insert(parts, 1, 'Call-path breakpoint explanations omitted due to site/evidence/output limits.')
677
+ prepend('Call-path breakpoint explanations omitted due to site/evidence/output limits.')
678
+ end
679
+ if filters.seed_limit_reached then prepend('Seed selection stopped after 512 matching candidates; narrow the query filters.') end
680
+ if seed_selection_limited then prepend('Starting-symbol selection limited to eight symbols and three definitions per name; refine name/path filters for other matches.') end
681
+ if candidate_cut then prepend('Unconfirmed definition candidates were limited or omitted; they are not call edges.') end
682
+ local result, truncated, kept = text.limit(table.concat(parts, '\n'), budget, omitted or #pointers > 0)
683
+ -- Validate locations retained by section budgets and the final byte cut.
684
+ -- Encoding repair aborts this transaction before any text is returned.
685
+ local selected, offset = {}, 0
686
+ for i, part in ipairs(parts) do
687
+ if offset >= kept then break end
688
+ for _, ref in ipairs(dependencies[i]) do
689
+ if offset + ref.at < kept then for _, f in ipairs(ref.files) do selected[f] = true end end
690
+ end
691
+ offset = offset + #part + 1
583
692
  end
584
- local result, truncated = text.limit(table.concat(parts, '\n'), budget, omitted or #pointers > 0)
585
- return result, { seeds = seeds, spine = spine, shown = shown, flows = flows, truncated = truncated,
693
+ for f in pairs(selected) do checked_source(idx, G.files[f].path) end
694
+ local source_files = 0; for _ in pairs(source_cache) do source_files = source_files + 1 end
695
+ G.stats.sources = { files = source_files }
696
+ return result, { seeds = seeds, spine = spine, shown = shown, flows = flows, flow_edges = flow_edges, truncated = truncated,
586
697
  relationships_incomplete = G.incomplete or false, query_stats = G.stats,
698
+ seed_limit_reached = filters.seed_limit_reached or false,
699
+ seed_selection_limited = seed_selection_limited,
587
700
  evidence = G.report.entries, evidence_truncated = evidence_cut or G.report.truncated,
701
+ unresolved_candidates = candidates.entries, unresolved_candidates_truncated = candidate_cut or false,
588
702
  path_search_limited = path_limited, evidence_scope = G.report.scope,
589
703
  path_breakpoints = breakpoints.entries, path_breakpoints_truncated = breakpoint_cut }
590
704
  end
591
705
 
706
+ function M.run(...)
707
+ local ok, output, info = pcall(run, ...)
708
+ if not ok and output == encoding_retry then return nil, { encoding_retry = true } end
709
+ if not ok then error(output, 0) end
710
+ return output, info
711
+ end
712
+
592
713
  return M