code-search-cli 0.1.0__py3-none-any.whl
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.
- code_retrieval/__init__.py +6 -0
- code_retrieval/__main__.py +3 -0
- code_retrieval/cli.py +144 -0
- code_retrieval/engine.py +722 -0
- code_retrieval/index_store.py +286 -0
- code_retrieval/installer.py +65 -0
- code_retrieval/models.py +90 -0
- code_retrieval/query.py +61 -0
- code_retrieval/repository.py +161 -0
- code_retrieval/resources/code-search/SKILL.md +47 -0
- code_retrieval/resources/code-search/agents/openai.yaml +4 -0
- code_retrieval/structure.py +115 -0
- code_search_cli-0.1.0.dist-info/METADATA +287 -0
- code_search_cli-0.1.0.dist-info/RECORD +19 -0
- code_search_cli-0.1.0.dist-info/WHEEL +5 -0
- code_search_cli-0.1.0.dist-info/entry_points.txt +2 -0
- code_search_cli-0.1.0.dist-info/licenses/LICENSE +202 -0
- code_search_cli-0.1.0.dist-info/licenses/NOTICE +7 -0
- code_search_cli-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: code-search
|
|
3
|
+
description: Task-aware local code retrieval that returns concise, explainable evidence. Use when locating implementation for a bug or feature, tracing lifecycle or structural relationships, gathering relevant code context for an engineering task, or inspecting code at a historical Git revision.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Code Search
|
|
7
|
+
|
|
8
|
+
Use the `code-search` CLI to retrieve a small, auditable evidence bundle before reading broad parts of
|
|
9
|
+
a repository.
|
|
10
|
+
|
|
11
|
+
For a large repository, `code-search index --repo <path>` can prewarm the persistent index. Normal
|
|
12
|
+
`retrieve` calls also refresh it incrementally, so prewarming is optional.
|
|
13
|
+
|
|
14
|
+
## Workflow
|
|
15
|
+
|
|
16
|
+
1. Describe the engineering task, including the failure, component, and expected behavior when known.
|
|
17
|
+
2. Retrieve a ranked evidence set:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
code-search retrieve \
|
|
21
|
+
--repo /absolute/path/to/repository \
|
|
22
|
+
--task "Fix startup events that are published before subscribers register" \
|
|
23
|
+
--format json
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
3. Inspect each result's path, line range, reasons, and token cost. Read the highest-value source spans
|
|
27
|
+
directly before editing. Treat each `required repair site:` reason as a separate actionable
|
|
28
|
+
responsibility; verify every marked production file before deciding the final change set.
|
|
29
|
+
4. Expand a known anchor only when the task needs its enclosing unit, siblings, or references:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
code-search expand \
|
|
33
|
+
--repo /absolute/path/to/repository \
|
|
34
|
+
--path src/main/java/example/Service.java \
|
|
35
|
+
--line 120 \
|
|
36
|
+
--relation references
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
5. Use `rg` instead when the task requires every exact literal occurrence. Treat retrieved evidence as
|
|
40
|
+
a navigation aid, then validate conclusions against source code and tests.
|
|
41
|
+
|
|
42
|
+
## Constraints
|
|
43
|
+
|
|
44
|
+
- Prefer distinct evidence roles over near-duplicate snippets.
|
|
45
|
+
- Do not claim that a missing result proves code is absent.
|
|
46
|
+
- The CLI is read-only and must not be used as evidence that a proposed patch is correct; run relevant
|
|
47
|
+
tests after making changes.
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import re
|
|
4
|
+
|
|
5
|
+
from .models import Section, SourceFile
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
JAVA_METHOD_RE = re.compile(
|
|
9
|
+
r"(?:^|\s)(?:public|protected|private|static|final|synchronized|abstract|native|default|strictfp|\s)+"
|
|
10
|
+
r"(?:<[^{>]+>\s+)?(?:[\w$.<>\[\],?]+\s+)?([A-Za-z_$][\w$]*)\s*\([^;{}]*\)\s*"
|
|
11
|
+
r"(?:throws\s+[^{]+)?\{\s*$"
|
|
12
|
+
)
|
|
13
|
+
PYTHON_DEF_RE = re.compile(r"^\s*(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(")
|
|
14
|
+
JS_FUNCTION_RE = re.compile(
|
|
15
|
+
r"^\s*(?:export\s+)?(?:async\s+)?(?:function\s+([A-Za-z_$][\w$]*)|"
|
|
16
|
+
r"(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=.*=>)"
|
|
17
|
+
)
|
|
18
|
+
CONTROL_NAMES = {"if", "for", "while", "switch", "catch", "try", "do", "synchronized"}
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def sections_for(source: SourceFile) -> list[Section]:
|
|
22
|
+
suffix = source.path.rsplit(".", 1)[-1].lower() if "." in source.path else ""
|
|
23
|
+
if suffix in {"java", "kt", "kts", "scala"}:
|
|
24
|
+
sections = _brace_sections(source, JAVA_METHOD_RE)
|
|
25
|
+
elif suffix == "py":
|
|
26
|
+
sections = _python_sections(source)
|
|
27
|
+
elif suffix in {"js", "jsx", "ts", "tsx"}:
|
|
28
|
+
sections = _brace_sections(source, JS_FUNCTION_RE)
|
|
29
|
+
else:
|
|
30
|
+
sections = []
|
|
31
|
+
return sections or _window_sections(source)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def containing_section(source: SourceFile, line: int, sections: list[Section] | None = None) -> Section:
|
|
35
|
+
sections = sections if sections is not None else sections_for(source)
|
|
36
|
+
matches = [section for section in sections if section.start_line <= line <= section.end_line]
|
|
37
|
+
if matches:
|
|
38
|
+
return min(matches, key=lambda item: item.end_line - item.start_line)
|
|
39
|
+
lines = source.content.splitlines()
|
|
40
|
+
start = max(1, line - 20)
|
|
41
|
+
end = min(len(lines), line + 20)
|
|
42
|
+
return _make_section(source.path, "context", "window", start, end, lines)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _brace_sections(source: SourceFile, pattern: re.Pattern[str]) -> list[Section]:
|
|
46
|
+
lines = source.content.splitlines()
|
|
47
|
+
sections: list[Section] = []
|
|
48
|
+
index = 0
|
|
49
|
+
while index < len(lines):
|
|
50
|
+
header_start = index
|
|
51
|
+
while header_start > 0 and lines[header_start - 1].lstrip().startswith("@"):
|
|
52
|
+
header_start -= 1
|
|
53
|
+
combined = lines[index].strip()
|
|
54
|
+
cursor = index
|
|
55
|
+
while cursor + 1 < len(lines) and "{" not in combined and len(combined) < 1200:
|
|
56
|
+
cursor += 1
|
|
57
|
+
combined += " " + lines[cursor].strip()
|
|
58
|
+
match = pattern.search(combined)
|
|
59
|
+
if not match:
|
|
60
|
+
index += 1
|
|
61
|
+
continue
|
|
62
|
+
name = next((group for group in match.groups() if group), "anonymous")
|
|
63
|
+
if name in CONTROL_NAMES:
|
|
64
|
+
index += 1
|
|
65
|
+
continue
|
|
66
|
+
depth = 0
|
|
67
|
+
seen_open = False
|
|
68
|
+
end = cursor
|
|
69
|
+
for end in range(cursor, len(lines)):
|
|
70
|
+
depth += lines[end].count("{") - lines[end].count("}")
|
|
71
|
+
seen_open = seen_open or "{" in lines[end]
|
|
72
|
+
if seen_open and depth <= 0:
|
|
73
|
+
break
|
|
74
|
+
sections.append(_make_section(source.path, name, "method", header_start + 1, end + 1, lines))
|
|
75
|
+
index = max(index + 1, end + 1)
|
|
76
|
+
return sections
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def _python_sections(source: SourceFile) -> list[Section]:
|
|
80
|
+
lines = source.content.splitlines()
|
|
81
|
+
starts: list[tuple[int, str, int]] = []
|
|
82
|
+
for index, line in enumerate(lines):
|
|
83
|
+
match = PYTHON_DEF_RE.match(line)
|
|
84
|
+
if match:
|
|
85
|
+
starts.append((index, match.group(1), len(line) - len(line.lstrip())))
|
|
86
|
+
sections: list[Section] = []
|
|
87
|
+
for position, (start, name, indent) in enumerate(starts):
|
|
88
|
+
end = len(lines)
|
|
89
|
+
for later, _, later_indent in starts[position + 1 :]:
|
|
90
|
+
if later_indent <= indent:
|
|
91
|
+
end = later
|
|
92
|
+
break
|
|
93
|
+
sections.append(_make_section(source.path, name, "function", start + 1, end, lines))
|
|
94
|
+
return sections
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def _window_sections(source: SourceFile, size: int = 48, overlap: int = 12) -> list[Section]:
|
|
98
|
+
lines = source.content.splitlines()
|
|
99
|
+
if not lines:
|
|
100
|
+
return []
|
|
101
|
+
sections = []
|
|
102
|
+
step = size - overlap
|
|
103
|
+
for start_index in range(0, len(lines), step):
|
|
104
|
+
end_index = min(len(lines), start_index + size)
|
|
105
|
+
sections.append(
|
|
106
|
+
_make_section(source.path, f"lines-{start_index + 1}-{end_index}", "window", start_index + 1, end_index, lines)
|
|
107
|
+
)
|
|
108
|
+
if end_index == len(lines):
|
|
109
|
+
break
|
|
110
|
+
return sections
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def _make_section(path: str, name: str, kind: str, start: int, end: int, lines: list[str]) -> Section:
|
|
114
|
+
content = "\n".join(lines[start - 1 : end])
|
|
115
|
+
return Section(path, name, kind, start, end, content)
|
|
@@ -0,0 +1,287 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: code-search-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Task-aware, evidence-oriented local code retrieval
|
|
5
|
+
Author: Code Search contributors
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://github.com/quguai/code-search
|
|
8
|
+
Project-URL: Repository, https://github.com/quguai/code-search
|
|
9
|
+
Project-URL: Issues, https://github.com/quguai/code-search/issues
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
15
|
+
Classifier: Topic :: Software Development
|
|
16
|
+
Requires-Python: >=3.11
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
License-File: LICENSE
|
|
19
|
+
License-File: NOTICE
|
|
20
|
+
Dynamic: license-file
|
|
21
|
+
|
|
22
|
+
<div align="center">
|
|
23
|
+
<a href="https://github.com/quguai/code-search">
|
|
24
|
+
<picture>
|
|
25
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/quguai/code-search/main/assets/brand-dark.png" />
|
|
26
|
+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/quguai/code-search/main/assets/brand-light.png" />
|
|
27
|
+
<img src="https://raw.githubusercontent.com/quguai/code-search/main/assets/brand-light.png" alt="CodeSearch" width="600" />
|
|
28
|
+
</picture>
|
|
29
|
+
</a>
|
|
30
|
+
<p><strong>Task-aware code search for coding agents</strong></p>
|
|
31
|
+
<p>Accurate evidence. Smaller context. No runtime model.</p>
|
|
32
|
+
</div>
|
|
33
|
+
|
|
34
|
+
<p align="center">
|
|
35
|
+
<a href="https://github.com/quguai/code-search/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/quguai/code-search/ci.yml?branch=main&style=flat-square" /></a>
|
|
36
|
+
<a href="https://github.com/quguai/code-search/blob/main/LICENSE"><img alt="Apache-2.0 license" src="https://img.shields.io/github/license/quguai/code-search?style=flat-square" /></a>
|
|
37
|
+
<img alt="Python 3.11+" src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" />
|
|
38
|
+
<img alt="Codex skill included" src="https://img.shields.io/badge/Codex-skill_included-5B47D6?style=flat-square" />
|
|
39
|
+
<img alt="Experimental status" src="https://img.shields.io/badge/status-experimental-D97706?style=flat-square" />
|
|
40
|
+
</p>
|
|
41
|
+
|
|
42
|
+
<p align="center">
|
|
43
|
+
<strong>English</strong> | <a href="https://github.com/quguai/code-search/blob/main/README.zh-CN.md">简体中文</a> | <a href="https://github.com/quguai/code-search/blob/main/README.ja-JP.md">日本語</a> | <a href="https://github.com/quguai/code-search/blob/main/README.ko-KR.md">한국어</a> | <a href="https://github.com/quguai/code-search/blob/main/README.ru-RU.md">Русский</a>
|
|
44
|
+
</p>
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
Code Search is a task-aware retrieval CLI for coding agents. It returns a concise, verifiable set of
|
|
49
|
+
source evidence for an engineering task—not only a list of similar snippets.
|
|
50
|
+
|
|
51
|
+
The current release is an independently implemented, no-runtime-model MVP. It can read a working tree
|
|
52
|
+
or any Git revision and returns source locations, ranking reasons, structural evidence roles, and
|
|
53
|
+
payload statistics.
|
|
54
|
+
|
|
55
|
+
> Search less. Hand the agent the evidence it needs to act.
|
|
56
|
+
|
|
57
|
+
## Quick start
|
|
58
|
+
|
|
59
|
+
### Install from this checkout
|
|
60
|
+
|
|
61
|
+
The complete local flow works today:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
cd /path/to/code-search
|
|
65
|
+
uv tool install .
|
|
66
|
+
code-search install
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`code-search install` installs the bundled `code-search` skill into Codex. Restart Codex after the
|
|
70
|
+
command so it can discover the skill. The installer is idempotent and refuses to overwrite a locally
|
|
71
|
+
modified skill unless `--force` is supplied.
|
|
72
|
+
|
|
73
|
+
After the first PyPI release, the first command becomes:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
uv tool install code-search-cli
|
|
77
|
+
code-search install
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
The PyPI distribution name (`code-search-cli`) and CLI entry point (`code-search`) are ready, but this
|
|
81
|
+
repository has not been published to PyPI yet.
|
|
82
|
+
|
|
83
|
+
### Retrieve evidence for a task
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
code-search retrieve \
|
|
87
|
+
--repo /path/to/repository \
|
|
88
|
+
--task "Fix dependency injection order so startup events are not missed"
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
The command is read-only. It does not check out revisions, modify the target repository, or create an
|
|
92
|
+
index inside it. It incrementally maintains a per-user SQLite index under the operating-system cache
|
|
93
|
+
directory; use `code-search clean` to remove the cached source snapshot and derived metadata.
|
|
94
|
+
|
|
95
|
+
## What you get
|
|
96
|
+
|
|
97
|
+
- A concise, de-duplicated evidence set instead of an unbounded list of matches.
|
|
98
|
+
- Source locations, scores, inclusion reasons, and estimated token cost for every result.
|
|
99
|
+
- Lightweight structural obligations for lifecycle, event, dependency-ordering, and test evidence.
|
|
100
|
+
- Direct reads from a working tree or historical Git revision without changing the checkout.
|
|
101
|
+
- A persistent incremental index that reuses unchanged source terms and structural boundaries.
|
|
102
|
+
- Java, Python, JavaScript, and TypeScript structural extraction with no runtime model dependency.
|
|
103
|
+
- A bundled Codex skill that teaches the agent when to retrieve, expand, or fall back to exact `rg`.
|
|
104
|
+
|
|
105
|
+
## CLI
|
|
106
|
+
|
|
107
|
+
Read a historical revision:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
code-search retrieve \
|
|
111
|
+
--repo /path/to/repository \
|
|
112
|
+
--ref HEAD~1 \
|
|
113
|
+
--task "Resolve NullPointerException in scheduled dump" \
|
|
114
|
+
--format json
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Expand a known anchor to its enclosing unit, siblings, or references:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
code-search expand \
|
|
121
|
+
--repo /path/to/repository \
|
|
122
|
+
--path src/main/java/example/Service.java \
|
|
123
|
+
--line 120 \
|
|
124
|
+
--relation enclosing
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Manage the Codex skill:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
code-search install
|
|
131
|
+
code-search uninstall
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Prewarm, inspect, or remove the per-repository index:
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
code-search index --repo /path/to/repository
|
|
138
|
+
code-search status --repo /path/to/repository
|
|
139
|
+
code-search clean --repo /path/to/repository
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Benchmarks
|
|
143
|
+
|
|
144
|
+
The primary benchmark uses `NDCG@10`, `Recall@10`, `MRR@10`, latency, and Top-10 payload size. The
|
|
145
|
+
local shared subset contains 61 queries over pinned revisions of Gson, Apache Commons Lang, and
|
|
146
|
+
Jackson Databind. Semble's published 1,251-query results are kept in a separate table and are not
|
|
147
|
+
presented as a local rerun.
|
|
148
|
+
|
|
149
|
+
<!-- benchmark-results:start -->
|
|
150
|
+
#### Local four-axis scorecard
|
|
151
|
+
|
|
152
|
+

|
|
153
|
+
|
|
154
|
+
### Local shared Java subset
|
|
155
|
+
|
|
156
|
+
| Method | NDCG@10 | Recall@10 | MRR@10 | Warm p50 | Top-10 payload |
|
|
157
|
+
|---|---:|---:|---:|---:|---:|
|
|
158
|
+
| Semble | **0.8250** | **0.9754** | **0.7852** | 4.25 ms | 1,803 tok |
|
|
159
|
+
| code-review-graph | 0.7634 | 0.8607 | 0.7670 | 103.30 ms | 16,162 tok |
|
|
160
|
+
| Code Search MVP | 0.7217 | 0.8525 | 0.6970 | 38.08 ms | 2,490 tok |
|
|
161
|
+
| BM25 | 0.5686 | 0.7623 | 0.5398 | **0.72 ms** | **1,752 tok** |
|
|
162
|
+
| probe | 0.2044 | 0.4262 | 0.1453 | 1,764.40 ms | 5,537 tok |
|
|
163
|
+
| ripgrep | 0.1977 | 0.2377 | 0.1904 | 30.84 ms | 28,605 tok |
|
|
164
|
+
|
|
165
|
+
### Published full-suite reference (not a local rerun)
|
|
166
|
+
|
|
167
|
+
These values are reported by Semble for its 1,251-query, 63-repository, 19-language benchmark.
|
|
168
|
+
|
|
169
|
+
| Method | NDCG@10 | Cold first result | Model size |
|
|
170
|
+
|---|---:|---:|---:|
|
|
171
|
+
| CodeRankEmbed Hybrid | 0.8617 | 57.29 s | 137M |
|
|
172
|
+
| semble | 0.8544 | 264.09 ms | 16M |
|
|
173
|
+
| CodeRankEmbed | 0.7648 | 57.29 s | 137M |
|
|
174
|
+
| ColGREP | 0.6925 | 5.87 s | 16M |
|
|
175
|
+
| BM25 | 0.6730 | 262.62 ms | no model |
|
|
176
|
+
| grepai | 0.5610 | 35.00 s | 137M |
|
|
177
|
+
| probe | 0.3870 | 207.10 ms | no model |
|
|
178
|
+
| ripgrep | 0.1260 | 12.08 ms | no model |
|
|
179
|
+
<!-- benchmark-results:end -->
|
|
180
|
+
|
|
181
|
+
Regenerate the scorecard and synchronize the measured JSON values into both READMEs:
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
uv run --no-project --with matplotlib python scripts/publish_shared_benchmark.py
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
This command does not rerun the benchmark or publish a package. See the
|
|
188
|
+
[shared benchmark methodology](https://github.com/quguai/code-search/blob/main/benchmarks/shared-java/README.md),
|
|
189
|
+
[raw local results](https://github.com/quguai/code-search/blob/main/benchmarks/shared-java/RESULTS.json), and
|
|
190
|
+
[published-reference provenance](https://github.com/quguai/code-search/blob/main/benchmarks/shared-java/PUBLISHED_REFERENCE.json).
|
|
191
|
+
|
|
192
|
+
The unit test suite creates only temporary synthetic repositories. The shared benchmark uses public,
|
|
193
|
+
pinned Gson, Apache Commons Lang, and Jackson Databind revisions with Semble's public annotations.
|
|
194
|
+
Machine-local and private development tasks are deliberately excluded from the public repository.
|
|
195
|
+
|
|
196
|
+
## How it differs from Semble and code-review-graph
|
|
197
|
+
|
|
198
|
+
The projects overlap, but optimize different parts of an agent workflow. This comparison describes
|
|
199
|
+
their public product shape; it is not a claim that one implementation dominates every task.
|
|
200
|
+
|
|
201
|
+
| | Code Search | Semble | code-review-graph |
|
|
202
|
+
|---|---|---|---|
|
|
203
|
+
| Primary job | Assemble task-relevant, explainable evidence | Find relevant code chunks quickly | Persist code relations for review, impact, and multi-hop exploration |
|
|
204
|
+
| Result shape | Evidence bundle with source, reason, score, and structural role | Compact ranked code snippets | Graph nodes, relations, traversals, and review reports |
|
|
205
|
+
| Retrieval | Lexical and task-aware structural retrieval; no runtime model today | Code-aware chunks, semantic retrieval, BM25, fusion, and reranking | Structural graph plus full-text/vector hybrid search |
|
|
206
|
+
| Structure/history | Persistent incremental local index, lightweight expansion, and direct reads from any Git revision | Similar-chunk retrieval and cached working-tree indexes | Persistent incremental graph, callers, flows, communities, and impact analysis |
|
|
207
|
+
| Onboarding | CLI plus a bundled Codex skill installer | CLI installer for MCP, instructions, and search sub-agents across multiple agents | CLI, MCP, daemon, GitHub Action, and review workflows |
|
|
208
|
+
| Best fit today | Explainable task-evidence experiments | Fast general-purpose natural-language code search | Review and durable multi-hop structural questions |
|
|
209
|
+
|
|
210
|
+
Semble still has the broader onboarding path. Its `install` command can configure MCP, generated
|
|
211
|
+
instructions, or a dedicated sub-agent across several coding agents. `code-search install` currently
|
|
212
|
+
installs one Codex skill. Code Search intentionally uses CLI + skill as its primary interface; an MCP
|
|
213
|
+
server is optional, not a prerequisite.
|
|
214
|
+
|
|
215
|
+
### Current advantages
|
|
216
|
+
|
|
217
|
+
- **Task roles, not only similarity.** Lifecycle, registration, publication, ordering, and test
|
|
218
|
+
evidence are represented separately instead of returning only one cluster of similar chunks.
|
|
219
|
+
- **Missing-behavior evidence.** For callback tasks, structurally similar sibling methods can expose
|
|
220
|
+
an expected publication step that is absent from the target path, instead of rewarding only code
|
|
221
|
+
that already contains the queried behavior.
|
|
222
|
+
- **Causal repair sets.** Startup-order tasks can connect a publisher, a lazily initialized static
|
|
223
|
+
subscriber, and the lifecycle owner whose dependency declaration must change, marking each
|
|
224
|
+
independently actionable production file.
|
|
225
|
+
- **Auditable evidence.** Each unit includes its location, reason, score, and estimated token cost.
|
|
226
|
+
- **Historical and no-model operation.** It can inspect a Git revision without checkout and has no
|
|
227
|
+
runtime model dependency.
|
|
228
|
+
- **Smaller output than the current graph adapter.** On the shared subset, Code Search returns a
|
|
229
|
+
2,490-token Top-10 payload versus 16,162 tokens for code-review-graph.
|
|
230
|
+
|
|
231
|
+
### Where competitors still lead
|
|
232
|
+
|
|
233
|
+
Semble leads this MVP on ranking quality, token efficiency, warm latency, and integration breadth.
|
|
234
|
+
code-review-graph provides deeper persistent relations, incremental graph maintenance, and review
|
|
235
|
+
automation. Code Search does not currently claim an overall win over either project.
|
|
236
|
+
|
|
237
|
+
## How it works
|
|
238
|
+
|
|
239
|
+
The engine incrementally caches source terms and structural boundaries, splits identifiers, expands
|
|
240
|
+
engineering aliases, scores paths and content, identifies task-specific structural obligations,
|
|
241
|
+
contrasts related sibling methods when a callback path is missing expected behavior, detects missing
|
|
242
|
+
subscriber-initialization and dependency edges, focuses long methods into query-aware windows, expands
|
|
243
|
+
selected anchors, and packs non-duplicate evidence into a ranked result set. The differentiating thesis is:
|
|
244
|
+
|
|
245
|
+
> Return not only similar code, but the evidence subgraph required to answer the engineering task.
|
|
246
|
+
|
|
247
|
+
This is currently a transparent lexical/structural baseline. Independently implemented dense retrieval
|
|
248
|
+
and stronger parsers remain future work.
|
|
249
|
+
|
|
250
|
+
## Documentation
|
|
251
|
+
|
|
252
|
+
- [Competitive analysis](https://github.com/quguai/code-search/blob/main/docs/competitive-analysis.md)
|
|
253
|
+
- [Product thesis and proposed architecture](https://github.com/quguai/code-search/blob/main/docs/product-thesis.md)
|
|
254
|
+
- [MVP implementation](https://github.com/quguai/code-search/blob/main/docs/implementation.md)
|
|
255
|
+
- [Evaluation plan](https://github.com/quguai/code-search/blob/main/docs/evaluation-plan.md)
|
|
256
|
+
- [Open benchmark and adapters](https://github.com/quguai/code-search/blob/main/docs/benchmarking.md)
|
|
257
|
+
- [Shared Java benchmark](https://github.com/quguai/code-search/blob/main/benchmarks/shared-java/README.md)
|
|
258
|
+
- [PyPI release process](https://github.com/quguai/code-search/blob/main/docs/releasing.md)
|
|
259
|
+
|
|
260
|
+
## Current gaps
|
|
261
|
+
|
|
262
|
+
- **P0 — public held-out validation:** publish at least 30 untouched, license-compatible tasks with
|
|
263
|
+
executable patch tests and repeated model runs.
|
|
264
|
+
- **P1 — retrieval quality:** add independently implemented optional dense retrieval and stronger
|
|
265
|
+
AST/symbol parsers.
|
|
266
|
+
- **P1 — onboarding breadth:** add safe CLI/skill installers for more coding agents. Consider MCP only
|
|
267
|
+
if a resident index or structured tool discovery provides a measured benefit over CLI invocation.
|
|
268
|
+
- **P2 — distribution:** publish to PyPI and ship signed standalone binaries. Until publication,
|
|
269
|
+
`uv tool install code-search-cli` cannot install this project from the public registry.
|
|
270
|
+
|
|
271
|
+
## Status and independent implementation
|
|
272
|
+
|
|
273
|
+
This is a testable experimental MVP, not a production release. It reaches `0.7217 NDCG@10` on the
|
|
274
|
+
61-query shared Java subset versus Semble at `0.8250`; Recall@10 is `0.8525`, and warm query p50 is
|
|
275
|
+
38.08 ms. These public results measure retrieval, not executable patch success, and are not a held-out
|
|
276
|
+
production claim.
|
|
277
|
+
|
|
278
|
+
The project is inspired by [Semble](https://github.com/MinishLab/semble) and
|
|
279
|
+
[code-review-graph](https://github.com/tirth8205/code-review-graph), which are used as public baselines.
|
|
280
|
+
It does not copy or rewrite their source, tests, prompts, documentation, interfaces, or distinctive
|
|
281
|
+
command vocabulary. The implementation and bundled Codex skill are independently designed around this
|
|
282
|
+
project's task-evidence workflow.
|
|
283
|
+
|
|
284
|
+
## License
|
|
285
|
+
|
|
286
|
+
Licensed under the [Apache License 2.0](https://github.com/quguai/code-search/blob/main/LICENSE). Semble and code-review-graph are independent projects;
|
|
287
|
+
their code is not included here.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
code_retrieval/__init__.py,sha256=zNqqZe91zhRnR4onrqkRk9iW7xxG60wiZeQmTgZ8awQ,220
|
|
2
|
+
code_retrieval/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
|
|
3
|
+
code_retrieval/cli.py,sha256=_ArAExiKa05vHow7PRUNItnF4Hzt9t372mYfkSNOWao,5921
|
|
4
|
+
code_retrieval/engine.py,sha256=xmiEVGp0rLhAbI0VzBfhe4uBtkrr_47aiOI9nkjiFg0,31539
|
|
5
|
+
code_retrieval/index_store.py,sha256=pXAeliFO3kwuyGogXlQF7uNHWGqoyyztsrUIBmQvwT4,10903
|
|
6
|
+
code_retrieval/installer.py,sha256=l4wdDk3jSe2EQT4vGZhZvY8oCIEJofprUyoy6XIOi9s,2415
|
|
7
|
+
code_retrieval/models.py,sha256=kLQ_Md8fBWOnDkQa4CGUF886wBbv_8vp1b7SVJMJsGw,2341
|
|
8
|
+
code_retrieval/query.py,sha256=xjcBTEdjz51RyoIj0wtYR-WMI9_2nXIJ8P7Xzu_D2jo,2455
|
|
9
|
+
code_retrieval/repository.py,sha256=Og3gzluSB3CS4_6OhyQF-hHU75v855Fa0xN4U62pH78,5749
|
|
10
|
+
code_retrieval/structure.py,sha256=6Fwo1h-oaIxY9gSowu0LKhD6UL4WIkZpVkPr1euQHCY,4497
|
|
11
|
+
code_retrieval/resources/code-search/SKILL.md,sha256=VZiSxZZAhr62hEaTFHm99gWF7KGYsquHGsgeJHq5sfs,1955
|
|
12
|
+
code_retrieval/resources/code-search/agents/openai.yaml,sha256=Qz6AxMi9Wg0ZxqO-xwsv2En-SDQ6LBQ4twi8pp_0vBs,212
|
|
13
|
+
code_search_cli-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
|
|
14
|
+
code_search_cli-0.1.0.dist-info/licenses/NOTICE,sha256=b1SkI7tJw19Je1SNLP7eNDWpwxD7A-TsI6QiYat9HVE,270
|
|
15
|
+
code_search_cli-0.1.0.dist-info/METADATA,sha256=TaexvHUtUL8c0VJoubGSncTxl_YrXIZiUX6Zal4cTIM,14660
|
|
16
|
+
code_search_cli-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
|
|
17
|
+
code_search_cli-0.1.0.dist-info/entry_points.txt,sha256=Y4u1GuLbinsDr-jdhyQZF9XFEdnsco_byL8NTrDYp7w,56
|
|
18
|
+
code_search_cli-0.1.0.dist-info/top_level.txt,sha256=G2fxsJkpCt-QxmOlHVKR-XtsH9IZnM1lAhfurXOqsDw,15
|
|
19
|
+
code_search_cli-0.1.0.dist-info/RECORD,,
|