@codua/codeoutline-win32-x64 0.3.8 → 0.5.0

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 (32) hide show
  1. package/README.md +49 -0
  2. package/README.zh-CN.md +37 -0
  3. package/bin/xnet.exe +0 -0
  4. package/build-info.json +1 -1
  5. package/editors/codeoutline.vsix +0 -0
  6. package/editors/zed/extension.wasm +0 -0
  7. package/keys/update-ca.crt +18 -18
  8. package/package.json +1 -1
  9. package/scripts/codeoutline/analysis/graph.lua +7 -16
  10. package/scripts/codeoutline/analysis/indirect.lua +18 -12
  11. package/scripts/codeoutline/analysis/lua/lua_bindings.lua +28 -0
  12. package/scripts/codeoutline/bm25/automatic.lua +100 -0
  13. package/scripts/codeoutline/bm25/collect.lua +148 -0
  14. package/scripts/codeoutline/bm25/index.lua +548 -0
  15. package/scripts/codeoutline/bm25/snapshot.lua +45 -0
  16. package/scripts/codeoutline/command.lua +3 -3
  17. package/scripts/codeoutline/indexing/parse_pool.lua +12 -6
  18. package/scripts/codeoutline/main.lua +5 -1
  19. package/scripts/codeoutline/protocol/lsp.lua +3 -1
  20. package/scripts/codeoutline/protocol/mcp.lua +5 -2
  21. package/scripts/codeoutline/query/coverage.lua +2 -0
  22. package/scripts/codeoutline/query/definition_candidates.lua +36 -12
  23. package/scripts/codeoutline/query/explore.lua +110 -18
  24. package/scripts/codeoutline/query/navigation.lua +213 -26
  25. package/scripts/codeoutline/query/query_filters.lua +5 -1
  26. package/scripts/codeoutline/runtime/bm25_worker.lua +86 -0
  27. package/scripts/codeoutline/runtime/index_worker.lua +18 -5
  28. package/scripts/codeoutline/runtime/parse_worker.lua +10 -3
  29. package/scripts/codeoutline/service.lua +6 -0
  30. package/scripts/codeoutline/shared/rules.lua +9 -1
  31. package/scripts/codeoutline/update_sequence.lua +1 -1
  32. package/scripts/codeoutline/version.lua +1 -1
@@ -0,0 +1,45 @@
1
+ -- Internal source identity shared by readers and the background builder.
2
+ local indexing = require('codeoutline.indexing.index')
3
+ local paths = require('codeoutline.shared.path')
4
+ local control = require('codeoutline.shared.control')
5
+ local M = {magic = 'CODEOUTLINE-BM25\n', version = 3}
6
+
7
+ function M.prefix(version)
8
+ return M.magic .. version .. '\n'
9
+ end
10
+ local cache = setmetatable({}, {__mode = 'k'})
11
+
12
+ function M.stamp(index)
13
+ local cached = cache[index]
14
+ if cached and cached.generation == index.generation then return cached.stamp, cached.files end
15
+ local files, records = {}, {}
16
+ for path in pairs(index.files) do files[#files + 1] = path end
17
+ table.sort(files)
18
+ for i, path in ipairs(files) do
19
+ if i % 128 == 0 then control.check() end
20
+ local file = index.files[path]
21
+ records[i] = {path, file.size, file.crc, file.language, file.cpp_fragment or false}
22
+ end
23
+ local stamp = xutils.sha256_hex(cmsgpack.pack({indexing.VERSION, paths.key(index.root), records}))
24
+ cache[index] = {generation = index.generation, stamp = stamp, files = files}
25
+ return stamp, files
26
+ end
27
+
28
+ function M.current(path, stamp)
29
+ local file = io.open(path, 'rb')
30
+ if not file then return false end
31
+ local expected = M.prefix(M.version) .. stamp
32
+ local prefix = file:read(#expected)
33
+ file:close()
34
+ return prefix == expected
35
+ end
36
+
37
+ -- The background reader validates the disk snapshot against the foreground
38
+ -- index's identity without loading a second copy of its base records.
39
+ function M.reader(root, stamp)
40
+ local index = {root = root}
41
+ cache[index] = {stamp = stamp}
42
+ return index
43
+ end
44
+
45
+ return M
@@ -97,9 +97,9 @@ install starts the background service and registers it at login. uninstall
97
97
  stops it, removes its login entry, user-level MCP registrations and editor clients.
98
98
  --project also removes MCP entries from that project; --service-only keeps integrations.
99
99
  --purge additionally removes ~/.codeoutline data after cleanup succeeds.
100
- Run uninstall before npm uninstall -g codeoutline; npm has no uninstall hooks.
101
- For npm global installations, remove performs full cleanup with --purge, then
102
- removes the npm package after the runtime exits. Cleanup failures keep the package.
100
+ To fully uninstall a global npm installation, run codeoutline remove.
101
+ It deletes default user data and removes the npm package after cleanup succeeds.
102
+ To keep user data, run codeoutline uninstall, then npm uninstall -g codeoutline.
103
103
  daemon is the service itself.
104
104
  editors detects VS Code, Cursor and Zed and offers optional LSP client installation.
105
105
  Use --editors or CODEOUTLINE_EDITORS to select clients without a prompt.
@@ -22,7 +22,7 @@ M.CHUNK_FILES = 32
22
22
  M.CHUNK_BYTES = 1048576
23
23
  M.IDLE_MS = 60000
24
24
 
25
- local threads, owner, shared = {}, nil, nil
25
+ local threads, owner, shared, abort_key = {}, nil, nil, nil
26
26
  local job, waiting, token = nil, false, 0
27
27
  local script_path, thread_count
28
28
  local outstanding, running, idle_since = {}, false, nil
@@ -36,9 +36,15 @@ function M.configure(script, count)
36
36
  script_path, thread_count = script, count or M.THREADS
37
37
  end
38
38
 
39
+ function M.configured_threads()
40
+ local count = tonumber(os.getenv('CODEOUTLINE_INDEX_THREADS') or '') or M.THREADS
41
+ return math.max(0, math.floor(count))
42
+ end
43
+
39
44
  local function start_threads()
40
45
  shared = assert(xshared.dict('codeoutline_control'))
41
46
  owner = xthread.current_id()
47
+ abort_key = 'parse_abort:' .. owner
42
48
  for i = 1, thread_count do
43
49
  local id = M.FIRST_ID + i - 1
44
50
  local ok, err = xthread.create_thread(id, 'PARSE' .. i, script_path)
@@ -51,7 +57,7 @@ end
51
57
 
52
58
  local function stop_threads(reason)
53
59
  local started, count, stopped = xtimer.now_ms(), #threads, 0
54
- if shared then shared:set('parse_abort', token) end
60
+ if shared then shared:set(abort_key, token) end
55
61
  for _, id in ipairs(threads) do
56
62
  local ok, err = xthread.shutdown_thread(id)
57
63
  if ok then stopped = stopped + 1
@@ -129,7 +135,7 @@ M.partition = partition
129
135
 
130
136
  -- jobs: { rel, abs, weight, size?, crc? }; on_result(rel, load_file result)
131
137
  -- runs in this thread, in arrival order. Must be called from the bound job.
132
- function M.run(jobs, max_bytes, on_result)
138
+ function M.run(jobs, max_bytes, on_result, operation)
133
139
  assert(M.ready(), 'parse pool is not available here')
134
140
  token = token + 1
135
141
  local current, pending = token, 0
@@ -142,14 +148,14 @@ function M.run(jobs, max_bytes, on_result)
142
148
  local chunk, bytes = {}, 0
143
149
  local function flush()
144
150
  if #chunk == 0 then return end
145
- local posted, why = xthread.post(threads[i], 'parse', owner, current, max_bytes, chunk)
151
+ local posted, why = xthread.post(threads[i], operation or 'parse', owner, current, max_bytes, chunk)
146
152
  assert(posted, 'cannot post to parse thread: ' .. tostring(why))
147
153
  pending = pending + 1
148
154
  outstanding[current] = (outstanding[current] or 0) + 1
149
155
  chunk, bytes = {}, 0
150
156
  end
151
157
  for _, j in ipairs(bucket) do
152
- chunk[#chunk + 1] = { j.rel, j.abs, j.size or false, j.crc or false, j.language or false }
158
+ chunk[#chunk + 1] = { j.rel, j.abs, j.size or false, j.crc or false, j.language or false, j.documents }
153
159
  bytes = bytes + j.weight
154
160
  if #chunk >= M.CHUNK_FILES or bytes >= M.CHUNK_BYTES then flush() end
155
161
  end
@@ -181,7 +187,7 @@ function M.run(jobs, max_bytes, on_result)
181
187
  xtimer.now_ms() - started)
182
188
  if not ok then
183
189
  -- Workers skip the rest of this pass; late results carry a stale token.
184
- shared:set('parse_abort', current)
190
+ shared:set(abort_key, current)
185
191
  error(err, 0)
186
192
  end
187
193
  end
@@ -50,7 +50,7 @@ if #config.roots == 0 then
50
50
  end
51
51
  local shared = assert(xshared.create('codeoutline_control', 65536, 256))
52
52
  local jobs, next_id, job_count, worker_ready = {}, 0, 0, false
53
- local stopping, indexing = false, false
53
+ local stopping, indexing, building_bm25 = false, false, false
54
54
  local endpoint, stdio, input = nil, nil, ''
55
55
  local updating = false
56
56
  local startup = xtimer.now_ms()
@@ -129,6 +129,9 @@ return {
129
129
  end
130
130
  os.remove(daemon.stop_file(config.port))
131
131
  end
132
+ local bm25 = require('codeoutline.bm25.automatic')
133
+ building_bm25 = xthread.create_thread(bm25.worker_id, 'BM25', scripts .. '/codeoutline/runtime/bm25_worker.lua')
134
+ shared:set('bm25_worker', building_bm25 and true or false)
132
135
  assert(xthread.create_thread(2, 'INDEX', scripts .. '/codeoutline/runtime/index_worker.lua'))
133
136
  indexing = true
134
137
  -- Launchers enable this for serve; the background service updates unless
@@ -264,6 +267,7 @@ return {
264
267
  shared:set('shutdown', true)
265
268
  if stdio then stdio:close() end
266
269
  if endpoint then endpoint.close() end
270
+ if building_bm25 then xthread.shutdown_thread(require('codeoutline.bm25.automatic').worker_id) end
267
271
  if indexing then xthread.shutdown_thread(2) end
268
272
  if updating then xthread.shutdown_thread(3) end
269
273
  xnet.uninit()
@@ -601,7 +601,9 @@ function M.new(config, emit, submit, cancel, stop, await_worker)
601
601
  if value.incomplete then
602
602
  if trace then trace:record('limit', { id = id, method = req.method, uri = req.uri,
603
603
  position = req.position, epoch = navigation_epoch }) end
604
- local message = req.method == 'lsp_definition'
604
+ local message = value.bm25_building
605
+ and 'CodeOutline: building the BM25 definition index in the background; retry shortly'
606
+ or req.method == 'lsp_definition'
605
607
  and 'CodeOutline: definition lookup reached a candidate, source or visibility limit; some definitions may be omitted'
606
608
  or req.method == 'lsp_references'
607
609
  and 'CodeOutline: results were truncated; too many matching references'
@@ -45,6 +45,8 @@ M.tools = array({
45
45
  { name = 'codeoutline_explore', description = 'Query symbols, line-numbered source, call paths and neighbors. Explicit unknown-suffix project file paths are parsed on demand using supported syntax or a lang: hint. Unresolved calls and string commands may include explicitly unconfirmed candidates; these are not call edges and require source inspection. Long bodies preserve relevant call-site windows within the output budget. Optional lang:/kind:/path:/name: filters select starting symbols only; dependencies may cross languages and files. Refreshes automatically.',
46
46
  inputSchema = { type = 'object', properties = { projectPath = project,
47
47
  query = { type = 'string', minLength = 1, maxLength = 4096 },
48
+ bm25Match = {type = 'string', enum = array({'any', 'all'}), default = 'any',
49
+ description = 'When the normal lookup misses, require any or all tokenized query terms in the BM25 fallback.'},
48
50
  budget = { type = 'integer', minimum = 256, maximum = 262144, default = 16000 } },
49
51
  required = array({ 'query' }), additionalProperties = false } },
50
52
  { name = 'codeoutline_status', description = 'Refresh and report project index, cache, scanner and parser statistics.',
@@ -185,7 +187,7 @@ function M.new(config, submit, cancel)
185
187
  codeoutline_type_hierarchy = type_hierarchy, codeoutline_type_references = type_references, codeoutline_affected = affected })[tool.name]
186
188
  if engine then
187
189
  local ok, err = pcall(engine.validate, tool.name == 'codeoutline_affected' and args.files or args.query, { budget = args.budget, depth = args.depth,
188
- max_nodes = args.max_nodes, direction = args.direction })
190
+ max_nodes = args.max_nodes, direction = args.direction, bm25_match = args.bm25Match })
189
191
  if not ok then error_result(-32602, tostring(err)); return end
190
192
  end
191
193
  local token = object(params._meta) and params._meta.progressToken or nil
@@ -205,7 +207,7 @@ function M.new(config, submit, cancel)
205
207
  end
206
208
  local job, submit_error = submit({ method = tool.name:sub(#'codeoutline_' + 1), projectPath = root,
207
209
  allowedRoots = config.roots, query = args.query, files = args.files, budget = args.budget, depth = args.depth,
208
- max_nodes = args.max_nodes, direction = args.direction }, function(ok, value)
210
+ max_nodes = args.max_nodes, direction = args.direction, bm25_match = args.bm25Match }, function(ok, value)
209
211
  if self.pending[id] ~= p then return end
210
212
  self.pending[id] = nil
211
213
  local output = ok and (engine and value.text or xutils.json_pack(value)) or tostring(value)
@@ -218,6 +220,7 @@ function M.new(config, submit, cancel)
218
220
  metadata.state = metadata.coverage.partial and 'partial' or 'ok'
219
221
  metadata.generation = value.generation
220
222
  metadata.resolution = value.resolution
223
+ metadata.bm25 = value.bm25
221
224
  else metadata.error = coverage.error(output) end
222
225
  end
223
226
  result({ content = array({ { type = 'text', text = text.valid(output) } }), isError = not ok,
@@ -32,6 +32,8 @@ function M.summarize(info)
32
32
  if info.unresolved_files and #info.unresolved_files > 0 then add('unresolved_files') end
33
33
  if info.files_without_symbols and #info.files_without_symbols > 0 then add('files_without_symbols') end
34
34
  if info.on_demand_rejected and #info.on_demand_rejected > 0 then add('on_demand_rejected') end
35
+ if info.bm25 and info.bm25.state == 'building' then add('bm25_building') end
36
+ if info.bm25 and info.bm25.state == 'unavailable' then add('bm25_unavailable') end
35
37
  if info.unresolved and #info.unresolved > 0 then add('unresolved_types') end
36
38
  if (info.unresolved_sites or 0) > 0 then add('unresolved_type_sites') end
37
39
  if (info.ambiguous_sites or 0) > 0 then add('ambiguous_type_sites') end
@@ -8,6 +8,16 @@ local types = { class = true, struct = true, union = true, interface = true, rec
8
8
  local values = { variable = true, constant = true, field = true, enum_member = true }
9
9
  local function normalized(name) return (name:gsub('::', '.'):gsub(':', '.'):gsub('^%.', '')) end
10
10
 
11
+ local function lua_receiver_score(receiver, qualified, path)
12
+ local owner = graph.owner(normalized(qualified))
13
+ if owner and owner:match('[^.]+$') == receiver then return 350 end
14
+ path, receiver = path:lower(), receiver:lower()
15
+ local filename = path:match('[^/]+$')
16
+ if filename and (filename:gsub('%.lua$', '')) == receiver then return 300 end
17
+ if ('/' .. path):find('/' .. receiver .. '/', 1, true) then return 200 end
18
+ return 0
19
+ end
20
+
11
21
  -- An empty answer leaves the editor and the agent nothing to inspect, so a
12
22
  -- failed binding still gets name-based suggestions. They remain unconfirmed
13
23
  -- candidates: never call edges, references or index data.
@@ -22,30 +32,32 @@ function M.allowed(site)
22
32
  or site.kind == 'member_call' or site.kind == 'member_symbol'
23
33
  end
24
34
 
25
- function M.find(G, f, site, ctx, lua_self, lua_initializers)
35
+ function M.find(G, f, site, ctx, lua_self, lua_initializers, candidates)
26
36
  local info = { truncated = site and site.macro_state == 'limited' or false,
27
37
  scanned = 0, reason = 'exact name; binding unconfirmed' }
28
38
  if not lua_self and not M.allowed(site) then return {}, info end
29
39
  local language = G.files[f].language
30
40
  -- These languages have package/project visibility that a name-only search
31
41
  -- cannot establish. Their existing resolvers retain authority.
32
- if language == 'go' or language == 'rust' or language == 'csharp' then return {}, info end
42
+ local unresolved_receiver = site.reason == 'receiver binding unresolved'
43
+ if not unresolved_receiver and (language == 'go' or language == 'rust' or language == 'csharp') then return {}, info end
44
+ if unresolved_receiver then info.reason = 'matching member name; receiver binding unconfirmed' end
33
45
  local configured = (language == 'c' or language == 'cpp')
34
46
  and require('codeoutline.analysis.cpp.cpp_includes').policy(G, f, ctx).configured
35
47
  local qualified
36
- if site.evidence and site.evidence ~= '' then qualified = site.evidence:match('^cpp:name:(.-)%z') end
48
+ if type(site.evidence) == 'string' then qualified = site.evidence:match('^cpp:name:(.-)%z%d+$') end
37
49
  qualified = qualified and normalized(qualified)
38
50
  if qualified and not qualified:find('.', 1, true) then qualified = nil end
39
51
  if not lua_self then
40
52
  if site.recv then
41
53
  if site.recv == 'self' or site.recv == 'this' or site.recv == 'cls' then return {}, info end
42
54
  qualified = qualified or normalized(site.recv .. '.' .. site.name)
43
- elseif site.kind == 'member_call' or site.kind == 'member_symbol' then return {}, info end
55
+ elseif not unresolved_receiver and (site.kind == 'member_call' or site.kind == 'member_symbol') then return {}, info end
44
56
  end
45
- local list = G.by_name[site.name] or {}
57
+ local list = candidates or G.by_name[site.name] or {}
46
58
  -- A Lua member alias is only reachable through its dotted name; its bare
47
59
  -- key stays unpublished unless the owner is a configured export table.
48
- local dotted = language == 'lua' and qualified and G.by_name[qualified]
60
+ local dotted = not candidates and language == 'lua' and qualified and G.by_name[qualified]
49
61
  if dotted and dotted ~= list then
50
62
  local merged, seen = {}, {}
51
63
  for _, id in ipairs(list) do merged[#merged + 1], seen[id] = id, true end
@@ -55,6 +67,10 @@ function M.find(G, f, site, ctx, lua_self, lua_initializers)
55
67
  list = merged
56
68
  end
57
69
  local source_dir = G.files[f].path:match('^(.*)/') or ''
70
+ local receiver = language == 'lua' and not lua_self and site.recv
71
+ -- These are hints for unconfirmed candidates. The source can import a
72
+ -- module conditionally even when the resolver cannot bind its receiver.
73
+ local imported = receiver and graph.visible_dependencies(G, f, ctx)
58
74
  -- `bare` drops the receiver qualifier: the member name alone still names a
59
75
  -- definition worth offering, including top-level method definitions.
60
76
  local function scan(qualifier, bare)
@@ -82,9 +98,9 @@ function M.find(G, f, site, ctx, lua_self, lua_initializers)
82
98
  if not bare then name_matches = name_matches and (normalized(node.qualified) == site.name or published) end
83
99
  local aliased = language == 'lua' and require('codeoutline.analysis.lua.lua_bindings').member_alias(node, qualifier)
84
100
  if qualifier then name_matches = normalized(node.qualified) == qualifier or aliased end
85
- -- No call sites, private locals, nested functions or unrelated class
86
- -- methods. A class-nested member stays excluded even in the bare
87
- -- pass, so an unbound C++ receiver cannot reach another class.
101
+ if bare and unresolved_receiver then name_matches = name_matches and graph.owner(node.qualified) ~= nil end
102
+ -- Restrict receiver candidates to members and exclude nested
103
+ -- functions unless they are recognized Lua initializer members.
88
104
  -- A lexical self can inherit through runtime metatables. The editor
89
105
  -- can offer method definition tags even without a receiver binding.
90
106
  local lua_method = lua_self and rec.language == 'lua' and node.name == site.name and not parent
@@ -94,12 +110,18 @@ function M.find(G, f, site, ctx, lua_self, lua_initializers)
94
110
  and graph.owner(parent.qualified) == site.recv and normalized(node.qualified) == qualifier
95
111
  if lua_method or not lua_self and kind and name_matches and graph.family(rec.language) == graph.family(language)
96
112
  and (not node['local'] or published or aliased) and not (node.static and g ~= f)
97
- and (not parent or parent.kind == 'namespace' or qualifier and types[parent.kind] or initialized_member)
113
+ and (not parent or parent.kind == 'namespace'
114
+ or (qualifier or unresolved_receiver) and (types[parent.kind] or parent.kind == 'impl')
115
+ or initialized_member)
98
116
  and (qualifier or bare or node.kind ~= 'method' and node.kind ~= 'constructor') then
99
117
  local score = g == f and 100 or (rec.path:match('^(.*)/') or '') == source_dir and 20 or 0
118
+ if receiver then
119
+ score = score + lua_receiver_score(receiver, node.qualified, rec.path)
120
+ if imported[g] then score = score + 150 end
121
+ end
100
122
  if node.kind ~= 'prototype' and not node.decl then score = score + 1 end
101
123
  local bucket = node.kind == 'macro' and macro_hits or hits
102
- bucket[#bucket + 1] = { id = id, score = score }
124
+ bucket[#bucket + 1] = { id = id, score = score, order = i }
103
125
  end
104
126
  end
105
127
  return hits, macro_hits, scanned
@@ -107,7 +129,7 @@ function M.find(G, f, site, ctx, lua_self, lua_initializers)
107
129
  local hits, macro_hits, scanned = scan(qualified, false)
108
130
  -- An unbound receiver still names a member. Offer the bare name instead of
109
131
  -- an empty answer, keeping the qualified match authoritative when it hits.
110
- if #hits == 0 and #macro_hits == 0 and qualified and not lua_self then
132
+ if #hits == 0 and #macro_hits == 0 and (qualified or unresolved_receiver) and not lua_self then
111
133
  hits, macro_hits, scanned = scan(nil, true)
112
134
  end
113
135
  info.scanned = scanned
@@ -130,6 +152,8 @@ function M.find(G, f, site, ctx, lua_self, lua_initializers)
130
152
  hits = kept
131
153
  table.sort(hits, function(a, b)
132
154
  if a.score ~= b.score then return a.score > b.score end
155
+ -- Keep the lexical shortlist's order when semantic hints tie.
156
+ if candidates and site.recv then return a.order < b.order end
133
157
  return graph.before(G, a.id, b.id)
134
158
  end)
135
159
  local ids = {}
@@ -29,6 +29,8 @@ function M.validate(query, opts)
29
29
  assert(text.valid(query) == query, 'query must be valid UTF-8')
30
30
  require('codeoutline.query.query_filters').parse(query)
31
31
  assert(opts == nil or type(opts) == 'table', 'options must be a table')
32
+ local match = opts and opts.bm25_match
33
+ assert(match == nil or match == 'any' or match == 'all', 'bm25Match must be any or all')
32
34
  local budget = M.DEFAULT_BUDGET
33
35
  if opts and opts.budget ~= nil then budget = opts.budget end
34
36
  assert(type(budget) == 'number' and budget >= M.MIN_BUDGET and budget <= M.MAX_BUDGET and budget % 1 == 0,
@@ -431,6 +433,34 @@ end
431
433
 
432
434
  -- Run a query over symbol tables (graph.build). Returns the text and a table
433
435
  -- with what was selected; relationships resolve per query.
436
+ local function bm25_seeds(G, idx, filters, lookup, match)
437
+ local predicate = require('codeoutline.query.query_filters')
438
+ local accept
439
+ if filters.count > 0 then
440
+ accept = function(path, name, kind)
441
+ local record = idx.files[path]
442
+ return record and predicate.node_fields(filters, record, kind, name)
443
+ end
444
+ end
445
+ local hits, state = lookup(filters.text, accept, match)
446
+ local ranked, seen = {}, {}
447
+ for _, hit in ipairs(hits or {}) do
448
+ local file = G.file_index[hit.path]
449
+ for i, id in ipairs(file and G.id_of[file] or {}) do
450
+ if i % 128 == 0 then control.check() end
451
+ local node = G.nodes[id]
452
+ if not seen[id] and node.line == hit.start_line and node.kind == hit.kind
453
+ and (node.end_line or node.line) == hit.end_line and text.valid(node.qualified) == hit.symbol
454
+ and predicate.id(filters, G, id) then
455
+ ranked[#ranked + 1] = {id = id, s = hit.score}
456
+ seen[id] = true
457
+ break
458
+ end
459
+ end
460
+ end
461
+ return ranked, {state = state, matches = #ranked, match = match}
462
+ end
463
+
434
464
  local function run(G, idx, query, opts)
435
465
  control.check()
436
466
  opts = opts or {}
@@ -444,6 +474,10 @@ local function run(G, idx, query, opts)
444
474
  file_cache, source_cache = {}, {}
445
475
  local filters = require('codeoutline.query.query_filters').parse(query)
446
476
  local ranked, named_files = find_seeds(G, filters.text, filters, ranking)
477
+ local bm25
478
+ if #ranked == 0 and #named_files == 0 and filters.text ~= '' and opts.bm25_fallback then
479
+ ranked, bm25 = bm25_seeds(G, idx, filters, opts.bm25_fallback, opts.bm25_match)
480
+ end
447
481
 
448
482
  -- Seeds: top-ranked, but at most 3 definitions per name so one generic
449
483
  -- name can't crowd out the others the query mentions.
@@ -527,17 +561,28 @@ local function run(G, idx, query, opts)
527
561
  local shown, files_shown, file_order = {}, {}, {}
528
562
 
529
563
  if #seeds == 0 and #named_files == 0 then
530
- return 'No symbols matched. Name functions, classes, or files (e.g. "xtimer_poll", "Session.save", "xpoll.c").', { seeds = {} }
564
+ local notice = ''
565
+ if bm25 and bm25.state == 'building' then
566
+ notice = ' The BM25 index is being built; retry this query shortly.'
567
+ elseif bm25 and bm25.state == 'unavailable' then
568
+ notice = ' The BM25 fallback is temporarily unavailable.'
569
+ end
570
+ local message, truncated = text.limit('No symbols matched. Name functions, classes, or files (e.g. "xtimer_poll", "Session.save", "xpoll.c").'
571
+ .. notice, budget)
572
+ return message, {seeds = {}, bm25 = bm25, truncated = truncated}
531
573
  end
532
574
 
533
575
  -- Section 1: summary + flows.
534
576
  local nfiles = {}
535
577
  for _, id in ipairs(seeds) do nfiles[G.node_file[id]] = true end
536
578
  for _, id in ipairs(spine) do nfiles[G.node_file[id]] = true end
579
+ for _, f in ipairs(named_files) do nfiles[f] = true end
537
580
  local nf = 0
538
581
  for _ in pairs(nfiles) do nf = nf + 1 end
539
- 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.',
582
+ emit(string.format('Matched %d symbols in %d files, %d more on %s between them; short ones bring %s. Source blocks are verbatim with line numbers; treat them as already Read. Outlines are generated declaration summaries, not source bodies.',
540
583
  #seeds, nf, #spine, non_call_paths and 'relationship paths' or 'call paths', non_call_paths and 'related functions' or 'their callees'))
584
+ if bm25 then emit('No symbols matched the original lookup. BM25 fallback matched functions by keywords.') end
585
+ if #named_files > 0 then emit(string.format('Explicitly named files: %d (top-level outlines).', #named_files)) end
541
586
  if #flows > 0 then
542
587
  emit(non_call_paths and '\n## Relationship paths' or '\n## Call paths')
543
588
  if non_call_paths then emit('ref retains a function value; implementation, event and callback hops are static possibilities, not proof of execution.') end
@@ -626,31 +671,78 @@ local function run(G, idx, query, opts)
626
671
  focus[hop.source][#focus[hop.source] + 1] = hop.line
627
672
  end
628
673
  end
629
- local reserve = math.floor(budget * 0.15) -- keep room for sections 3-4
674
+ local reserve = #order > 0 and math.floor(budget * 0.15) or 128
675
+ -- Share outline space a row at a time, so a large first file cannot hide
676
+ -- the others. Mixed queries also keep space for the requested source bodies.
677
+ local outline_budget = math.max(0, budget - reserve - used)
678
+ if #order > 0 then outline_budget = math.floor(outline_budget / 2) end
679
+ local outlines, outline_order, outline_bytes = {}, {}, 0
680
+ local outline_hint = 'Outline entries omitted; refine path:/name: filters to inspect specific declarations.'
681
+ local function outline_status(count, total)
682
+ return string.format('Shown %d/%d top-level declarations.', count, total)
683
+ end
684
+ for _, f in ipairs(file_order) do
685
+ if by_file[f].outline then
686
+ local rec, nodes = G.files[f], {}
687
+ for _, node in ipairs(rec.nodes) do
688
+ if not node.parent and node.kind ~= 'macro' and require('codeoutline.query.query_filters').node(filters, rec, node) then
689
+ nodes[#nodes + 1] = node
690
+ end
691
+ end
692
+ local header = '\n## ' .. rec.path .. ' (outline)\n'
693
+ local overhead = #header + #outline_status(#nodes, #nodes) + #outline_hint + 3
694
+ if overhead <= outline_budget then
695
+ checked_source(idx, rec.path)
696
+ outlines[f] = { nodes = nodes, rows = {}, header = header }
697
+ outline_order[#outline_order + 1] = f
698
+ outline_budget = outline_budget - overhead
699
+ else omitted = true end
700
+ end
701
+ end
702
+ local progress = true
703
+ while progress do
704
+ progress = false
705
+ for _, f in ipairs(outline_order) do
706
+ local outline = outlines[f]
707
+ local node = outline.nodes[#outline.rows + 1]
708
+ if node and not outline.full then
709
+ control.check()
710
+ local row = text.valid(string.format('%d\t%s %s', node.line, node.kind,
711
+ require('codeoutline.query.navigation').detail(G, f, node).sig or node.name))
712
+ if #outline.rows < 1024 and #row + 1 <= outline_budget then
713
+ outline.rows[#outline.rows + 1] = row
714
+ outline_budget = outline_budget - #row - 1
715
+ progress = true
716
+ else outline.full = true end
717
+ end
718
+ end
719
+ end
720
+ for _, f in ipairs(outline_order) do
721
+ local outline = outlines[f]
722
+ local cut = #outline.rows < #outline.nodes
723
+ outline.block = outline.header .. outline_status(#outline.rows, #outline.nodes)
724
+ .. (#outline.rows > 0 and '\n' .. table.concat(outline.rows, '\n') or '')
725
+ .. (cut and '\n' .. outline_hint or '')
726
+ omitted = omitted or cut
727
+ outline_bytes = outline_bytes + #outline.block + 1
728
+ end
630
729
  for _, f in ipairs(file_order) do
631
730
  local rec = G.files[f]
632
731
  local header = '\n## ' .. rec.path
633
732
  local items = by_file[f]
634
733
  table.sort(items, function(a, b) return G.nodes[a.id].line < G.nodes[b.id].line end)
635
734
  local wrote_header = false
636
- if items.outline and used + #header + 16 < budget - reserve then
637
- checked_source(idx, rec.path)
638
- local ol = {}
639
- for _, node in ipairs(rec.nodes) do
640
- if not node.parent and node.kind ~= 'macro' and require('codeoutline.query.query_filters').node(filters, rec, node) then
641
- ol[#ol + 1] = string.format('%d\t%s %s', node.line, node.kind, require('codeoutline.query.navigation').detail(G, f, node).sig or node.name)
642
- end
643
- if #ol >= 60 then ol[#ol + 1] = '\t...'; break end
644
- end
645
- local block = header .. ' (outline)\n' .. table.concat(ol, '\n')
646
- if used + #block < budget - reserve then emit(block, location_refs({ f })); wrote_header = true else omitted = true end
647
- elseif items.outline then omitted = true end
735
+ if outlines[f] then
736
+ local block = outlines[f].block
737
+ outline_bytes = outline_bytes - #block - 1
738
+ emit(block, location_refs({ f })); wrote_header = true
739
+ end
648
740
  for _, item in ipairs(items) do
649
- if not shown[item.id] and used + #header + 16 < budget - reserve then
741
+ if not shown[item.id] and used + #header + 16 < budget - reserve - outline_bytes then
650
742
  local block, source_cut = node_block(G, idx, item.id, item.full, focus[item.id])
651
743
  omitted = omitted or source_cut
652
744
  local need = #block + (wrote_header and 0 or #header + 1) + 1
653
- if used + need < budget - reserve then
745
+ if used + need < budget - reserve - outline_bytes then
654
746
  if not wrote_header then emit(header, location_refs({ f })); wrote_header = true end
655
747
  emit(block, location_refs({ f }))
656
748
  shown[item.id] = true
@@ -760,7 +852,7 @@ local function run(G, idx, query, opts)
760
852
  evidence = G.report.entries, evidence_truncated = evidence_cut or G.report.truncated,
761
853
  unresolved_candidates = candidates.entries, unresolved_candidates_truncated = candidate_cut or false,
762
854
  path_search_limited = path_limited, evidence_scope = G.report.scope,
763
- path_breakpoints = breakpoints.entries, path_breakpoints_truncated = breakpoint_cut }
855
+ path_breakpoints = breakpoints.entries, path_breakpoints_truncated = breakpoint_cut, bm25 = bm25 }
764
856
  end
765
857
 
766
858
  function M.run(...)