code-search-cli 0.1.0__tar.gz → 0.3.0__tar.gz

code_search_cli-0.3.0/.gitignore

@@ -0,0 +1,37 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.DS_Store
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.playwright-cli/
+.venv/
+.idea/
+build/
+dist/
+*.log
+*.sqlite
+*.sqlite3
+
+# Machine-local configuration and benchmark artifacts
+.local/
+benchmarks/private/
+.env
+.env.*
+!.env.example
+.netrc
+.npmrc
+.pypirc
+credentials*.json
+secrets*.json
+*.key
+*.pem
+*.p12
+*.pfx
+
+# wrangler files
+.wrangler
+.dev.vars*
+!.dev.vars.example

code_search_cli-0.3.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include .gitignore
+include uv.lock
+recursive-include scripts *.py
+recursive-include benchmarks *.java *.json *.md *.py *.ts

code_search_cli-0.3.0/NOTICE

@@ -0,0 +1,4 @@
+Code Search
+Copyright 2026 Code Search contributors
+
+This product is licensed under the Apache License, Version 2.0.

code_search_cli-0.3.0/PKG-INFO

@@ -0,0 +1,392 @@
+Metadata-Version: 2.4
+Name: code-search-cli
+Version: 0.3.0
+Summary: Task-aware code search with compact, auditable evidence for coding agents
+Author: Code Search contributors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://code-search.quguai.cc/
+Project-URL: Documentation, https://code-search.quguai.cc/
+Project-URL: Repository, https://github.com/quguai/code-search
+Project-URL: Issues, https://github.com/quguai/code-search/issues
+Project-URL: Changelog, https://github.com/quguai/code-search/releases
+Keywords: code-search,code-retrieval,coding-agents,agent-skills,cli,codex
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+<div align="center">
+  <a href="https://github.com/quguai/code-search">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/quguai/code-search/main/assets/brand-dark.png" />
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/quguai/code-search/main/assets/brand-light.png" />
+      <img src="https://raw.githubusercontent.com/quguai/code-search/main/assets/brand-light.png" alt="CodeSearch" width="600" />
+    </picture>
+  </a>
+  <p><strong>Task-aware code search for coding agents</strong></p>
+  <p>Explainable evidence. Scoped context. No runtime model.</p>
+</div>
+
+<p align="center">
+  <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&amp;style=flat-square" /></a>
+  <a href="https://pypi.org/project/code-search-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/code-search-cli?style=flat-square" /></a>
+  <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>
+  <img alt="Python 3.11+" src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&amp;logo=python&amp;logoColor=white" />
+  <img alt="Agent Skill installers for seven agents" src="https://img.shields.io/badge/Agent_Skills-7_targets-5B47D6?style=flat-square" />
+  <img alt="Experimental status" src="https://img.shields.io/badge/status-experimental-D97706?style=flat-square" />
+</p>
+
+<p align="center">
+  <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>
+</p>
+
+---
+
+Code Search is a task-aware retrieval CLI for coding agents. It returns a concise, verifiable set of
+source evidence for an engineering task, not only a list of similar snippets.
+
+The current version is an independently implemented, fully model-free MVP: no embeddings, no GPU, no
+server, and no network calls. It can read a working tree or any Git revision and returns source
+locations, ranking reasons, structural evidence roles, provenance, categorical confidence, and
+payload statistics.
+
+> Search less. Hand the agent the evidence it needs to act.
+
+## Quick start
+
+### Install from PyPI
+
+```bash
+uv tool install code-search-cli
+code-search --version
+```
+
+The distribution is named `code-search-cli`; the installed command remains `code-search`.
+
+### Install from this checkout
+
+```bash
+cd /path/to/code-search
+uv tool install .
+code-search --version
+```
+
+### Retrieve evidence for a task
+
+```bash
+code-search retrieve \
+  --repo /path/to/repository \
+  --task "Fix dependency injection order so startup events are not missed"
+```
+
+The command is read-only. It does not check out revisions, modify the target repository, or create an
+index inside it. It incrementally maintains a per-user SQLite index under the operating-system cache
+directory, honors Git ignore rules for working trees, and uses `code-search clean` to remove the
+cached source snapshot and derived metadata.
+
+### Optional agent integration
+
+```bash
+code-search install                  # Codex remains the default
+code-search install --target cursor  # Or select one target explicitly
+```
+
+The bundled `code-search` Agent Skill can be installed for Codex, Claude Code, Cursor, Gemini CLI,
+OpenCode, GitHub Copilot, or Kiro. Installation is user-level and idempotent. It tracks hashes of
+the files it installed, so an untouched older release can upgrade safely while a locally modified
+skill is still protected unless `--force` is supplied. Add `--dry-run` to preview the operation.
+The CLI remains the primary interface; installing the skill adds neither an MCP server nor a runtime
+model.
+
+### Why there is no model underneath
+
+Retrieval is deterministic, auditable, and runs entirely on lexical and structural signals: stemmed
+term matching, file-name coverage, structural expansion, and task-role inference. The same query on
+the same tree returns the same evidence, every result explains why it was included, and nothing is
+downloaded at runtime. Model-backed products appear in the public benchmark only as separately
+versioned comparison methods; they are not Code Search runtime dependencies.
+
+## What you get
+
+- A concise, de-duplicated evidence set instead of an unbounded list of matches.
+- Source locations, scores, inclusion reasons, evidence roles, provenance, categorical confidence,
+  and estimated token cost for every result.
+- Lightweight structural obligations for lifecycle, event, dependency-ordering, and test evidence.
+- Direct reads from a working tree or historical Git revision without changing the checkout.
+- A persistent incremental index that verifies content hashes and reuses unchanged source terms and
+  structural boundaries.
+- Optional `code`, `tests`, or `config` scope filters when a task does not need the whole repository.
+- Source indexing across C/C++, C#, Elixir, Go, Haskell, Java, JavaScript/TypeScript, Kotlin, Lua,
+  PHP, Python, Ruby, Rust, Scala, shell/Bats, Swift, Zig, and common configuration formats.
+- Model-free structural extraction for Java/Kotlin/Scala, Python, and JavaScript/TypeScript on the
+  default path.
+- Compact exact-symbol windows across all indexed source formats when the whole task is an
+  identifier or qualified name.
+- A bundled Agent Skill, with user-level filesystem installers for Codex, Claude Code, Cursor,
+  Gemini CLI, OpenCode, GitHub Copilot, and Kiro, that teaches the agent when to retrieve, expand,
+  or fall back to exact `rg`. Their paths, dry-run behavior, idempotence, safe upgrades, and
+  file-protection behavior have automated coverage.
+
+## Task evidence beyond ranked matches
+
+A flat result list may return both a target function and a similar working function. For the
+callback patterns it currently supports, Code Search compares them and can label the behavior that
+is present in one path but absent from the other. For supported lifecycle patterns, it can also keep
+separate repair responsibilities in one evidence bundle.
+
+| Synthetic case | Code Search task-evidence schema | Neutral flat-result schema |
+|---|---|---|
+| Python callback using `emit` | `missing-behavior` + `comparison` with reasons, provenance, and confidence | source spans + score |
+| TypeScript callback using `dispatchEvent` | `missing-behavior` + `comparison` with reasons, provenance, and confidence | source spans + score |
+| Java/Spring-style startup lifecycle | two explicit `required repair site` responsibilities + subscriber `registration` | source spans + score |
+
+From a source checkout, run the synthetic fixtures:
+
+```bash
+uv run python scripts/showcase_evidence.py
+```
+
+The [task-evidence contract](https://github.com/quguai/code-search/blob/main/benchmarks/evidence-showcase/README.md)
+documents the fixture and its
+[generated output](https://github.com/quguai/code-search/blob/main/benchmarks/evidence-showcase/RESULTS.md).
+This is a regression check, not a held-out quality benchmark or a patch-success claim.
+
+## CLI
+
+Read a historical revision:
+
+```bash
+code-search retrieve \
+  --repo /path/to/repository \
+  --ref HEAD~1 \
+  --task "Resolve NullPointerException in scheduled dump" \
+  --format json
+```
+
+Limit a focused query to conventional test paths and filenames:
+
+```bash
+code-search retrieve \
+  --repo /path/to/repository \
+  --task "Find regression tests for field naming" \
+  --scope tests
+```
+
+`--scope` accepts `all` (the default), `code`, `tests`, or `config`. It filters files before ranking;
+leave it at `all` when a task crosses production code, configuration, and tests.
+
+Expand a known anchor to its enclosing unit, siblings, or references:
+
+```bash
+code-search expand \
+  --repo /path/to/repository \
+  --path src/main/java/example/Service.java \
+  --line 120 \
+  --relation enclosing
+```
+
+Manage the optional Agent Skill:
+
+```bash
+code-search install                                  # Codex
+code-search install --target claude-code
+code-search install --target cursor
+code-search install --target gemini
+code-search install --target opencode
+code-search install --target github-copilot
+code-search install --target kiro
+code-search install --target detected                # Best-effort convenience selector
+code-search install --target detected --dry-run      # Preview without writing
+code-search uninstall --target cursor
+code-search uninstall --target detected
+```
+
+The installer writes only managed Skill files and its hash manifest inside the selected agent's
+user configuration:
+
+| `--target` | User-level destination |
+|---|---|
+| `codex` | `$CODEX_HOME/skills/code-search/` when set; otherwise `~/.agents/skills/code-search/` |
+| `claude-code` | `$CLAUDE_CONFIG_DIR/skills/code-search/` when set; otherwise `~/.claude/skills/code-search/` |
+| `cursor` | `~/.cursor/skills/code-search/` |
+| `gemini` | `$GEMINI_CLI_HOME/.gemini/skills/code-search/` when set; otherwise `~/.gemini/skills/code-search/` |
+| `opencode` | `$OPENCODE_CONFIG_DIR/skills/code-search/` when set; otherwise `${XDG_CONFIG_HOME:-~/.config}/opencode/skills/code-search/` |
+| `github-copilot` | `$COPILOT_HOME/skills/code-search/` when set; otherwise `~/.copilot/skills/code-search/` |
+| `kiro` | `~/.kiro/skills/code-search/` |
+
+Agent-specific environment overrides must be absolute paths; a relative `XDG_CONFIG_HOME` is ignored
+as required by the XDG base-directory specification. An existing legacy Codex installation under
+`~/.codex/skills/code-search/` is updated and removed in place instead of being silently migrated.
+
+`detected` is a best-effort convenience selector based on known commands, configuration directories,
+environment overrides, and an already-installed target. It does not launch a client or verify that
+the client can load the skill. Cursor detection deliberately relies on `~/.cursor` rather than the
+ambiguous `agent` executable name. Because some clients also scan another client's compatibility
+directories, prefer an explicit target and use one if the same skill appears more than once.
+
+Every selected destination is preflighted before writing or removing files. A small hidden manifest
+records hashes of the managed files; it is installer metadata, not another instruction loaded by the
+agent. This lets an untouched older installation upgrade without treating it as a user edit.
+Uninstall removes only managed files whose content is still recognized and leaves extra user files
+in place. Use `--force` only when you intentionally want to replace or remove a modified managed
+file. `--dry-run` performs the same checks and reports the planned action without changing files.
+
+Prewarm, inspect, or remove the per-repository index:
+
+```bash
+code-search index --repo /path/to/repository
+code-search status --repo /path/to/repository
+code-search clean --repo /path/to/repository
+```
+
+## Benchmark
+
+The repository publishes two recorded development comparisons. Both measure
+[Code Search](https://github.com/quguai/code-search),
+[Semble](https://github.com/MinishLab/semble),
+[code-review-graph](https://github.com/tirth8205/code-review-graph), BM25,
+[Probe](https://github.com/probelabs/probe), and
+[ripgrep](https://github.com/BurntSushi/ripgrep). They use different datasets and adapters, so their
+scores must not be merged into one leaderboard. The shared Java runner reproduces all six methods;
+the multilingual public runner currently reproduces BM25, Probe, and ripgrep, while the other three
+rows retain their recorded implementation identities and per-task output. The Code Search rows
+describe the source revisions recorded by each benchmark, not a new measurement of the current release.
+
+### Shared Java comparison
+
+The primary comparison uses the same 61 public queries and relevance annotations over pinned Gson,
+Apache Commons Lang, and Jackson Databind revisions.
+
+![Six retrieval methods compared across quality, coverage, latency, and payload](https://raw.githubusercontent.com/quguai/code-search/main/assets/benchmark-quality-speed.png)
+
+| Method | NDCG@10 | Recall@10 | MRR@10 | Setup | Query p50 / p95 | Top-10 payload |
+|---|---:|---:|---:|---:|---:|---:|
+| Code Search | **0.8638** | 0.9672 | **0.8463** | 1.809 s | 15.69 / 50.11 ms | 3,058 tok |
+| Semble | 0.8250 | **0.9754** | 0.7852 | 1.550 s | 5.83 / 22.41 ms | 1,803 tok |
+| code-review-graph | 0.7634 | 0.8607 | 0.7670 | 23.744 s | 103.55 / 230.24 ms | 16,161 tok |
+| BM25 | 0.5686 | 0.7623 | 0.5398 | 1.449 s | **1.47 / 3.16 ms** | **1,752 tok** |
+| Probe | 0.2271 | 0.4754 | 0.1649 | — | 586.82 / 952.48 ms | 4,295 tok |
+| ripgrep | 0.1977 | 0.2377 | 0.1904 | — | 32.52 / 61.40 ms | 28,605 tok |
+
+No row wins every dimension. On these 61 queries, Code Search has the highest NDCG and MRR; Semble
+has slightly higher Recall, lower query latency, and a smaller payload; BM25 has the lowest query
+latency and payload.
+
+NDCG@10 also changes by query type:
+
+| Query type | Tasks | Code Search | Semble | code-review-graph | BM25 | Probe | ripgrep |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| Conceptual | 33 | **0.8550** | 0.7869 | 0.7607 | 0.4855 | 0.1794 | 0.0000 |
+| Architecture | 12 | **0.7204** | 0.7068 | 0.4877 | 0.5819 | 0.3044 | 0.0000 |
+| Symbol | 16 | 0.9895 | **0.9923** | 0.9758 | 0.7301 | 0.2678 | 0.7539 |
+
+The [shared Java methodology and machine-readable results](https://github.com/quguai/code-search/tree/main/benchmarks/shared-java)
+record exact tool commits, model revisions, repository revisions, adapter definitions, p95 values,
+per-query rows, and reproduction commands.
+
+### Multilingual diagnostic
+
+The second comparison uses 30 fixed pre-fix tasks from eight public repositories and eight
+languages. Each language has only three or four tasks, so the heatmap locates weaknesses in this
+sample; it does not establish broad language support.
+
+![NDCG, Recall, and MRR by language for six retrieval methods](https://raw.githubusercontent.com/quguai/code-search/main/assets/benchmark-multilingual.png)
+
+| Method | NDCG@10 | Recall@10 | MRR@10 | Warm p50 | Payload p50 |
+|---|---:|---:|---:|---:|---:|
+| Code Search | 0.5026 | 0.7311 | 0.4520 | 18.5 ms | 4,816 tok |
+| Semble | **0.5620** | 0.6700 | **0.5609** | 13.5 ms | 1,750 tok |
+| code-review-graph | 0.3603 | 0.3800 | 0.3944 | 69.7 ms | **734 tok** |
+| BM25 | 0.4973 | **0.7644** | 0.4663 | **0.9 ms** | 70,558 tok |
+| Probe | 0.3084 | 0.6133 | 0.2380 | 1,262.0 ms | 6,982 tok |
+| ripgrep | 0.3954 | 0.7200 | 0.3009 | 473.0 ms | 100,974 tok |
+
+BM25 and ripgrep return whole files in this diagnostic, which explains their large payloads. Probe
+returns AST blocks; its file order was identical across five repeated queries on 25 of 30 tasks.
+See the [multilingual methodology and per-language results](https://github.com/quguai/code-search/tree/main/benchmarks/multilingual-30)
+for the adapter definitions and complete records.
+
+Both datasets are retrieval-only **development data** that have already been inspected. They do not
+generate patches, run project tests, or run agents. Native result units also differ—evidence spans,
+chunks, graph nodes, AST blocks, and whole files—so setup and payload describe the recorded
+adapters, not every capability of each product. Held-out product claims still require untouched
+tasks, executable patch tests, and repeated agent runs.
+
+## How Code Search fits
+
+No retrieval approach is best for every query. The first four rows below generate candidates or
+index source relationships. Code Search builds on lexical candidates, applies lightweight structural
+inference, and organizes selected source as task evidence. It is an evidence layer, not a same-level
+replacement for every retrieval method.
+
+| Approach | Typical question | Typical output | Main trade-off |
+|---|---|---|---|
+| Exact text or regex search | Where does this identifier, error string, or literal occur? | Matching lines or small windows | Fast and deterministic, but depends on exact wording and does not infer missing behavior on its own |
+| Lexical or full-text retrieval | Which files share this vocabulary or path context? | Ranked files or spans with lexical scores | Explainable and model-free, but weaker on paraphrases and cross-file relationships |
+| Embedding or hybrid chunk retrieval | Which code expresses this natural-language concept? | Semantically ranked code chunks | Designed to recover conceptual matches, but adds model and index cost; chunk boundaries may omit surrounding evidence |
+| Structural graph or symbol index | Where is this symbol defined, referenced, or related? | Definitions, references, relations, or traversals | Strong for explicit relations, but depends on parser coverage, edge accuracy, and a correct starting anchor |
+| Code Search task-evidence bundle | Which evidence belongs in this bug, change, or review? | De-duplicated source spans with task roles, reasons, provenance, confidence, and payload | Task-role inference is lightweight and rule-based, and the result is not a compiler-grade program graph |
+
+These approaches complement each other. Exact search remains the right first tool for a known
+literal. Semantic retrieval helps with conceptual discovery, while a structural index is better for
+deep relation queries. Code Search focuses on deciding which implementation, test, configuration,
+registration, comparison, or repair site belongs in the evidence set for the task.
+
+## How it works
+
+The engine incrementally caches source terms and structural boundaries, splits identifiers, expands
+engineering aliases, scores paths and content, identifies task-specific structural obligations,
+contrasts related sibling methods when a callback path is missing expected behavior, detects missing
+subscriber-initialization and dependency edges, focuses long methods into query-aware windows, expands
+selected anchors, and packs non-duplicate evidence into a ranked result set. The differentiating thesis is:
+
+> Return not only similar code, but the evidence subgraph required to answer the engineering task.
+
+The retrieval path is a transparent lexical/structural engine. For an exact symbol-only query, a
+compact window is promoted only when the literal symbol appears directly after a common declaration
+keyword. The result remains a medium-confidence exact-text anchor, not a parser-verified definition.
+Task roles and structural conclusions are rule-based. Stronger parsers and independent held-out
+validation remain future work.
+
+## Documentation
+
+- [Retrieval approaches](https://github.com/quguai/code-search/blob/main/docs/retrieval-approaches.md)
+- [Product thesis and proposed architecture](https://github.com/quguai/code-search/blob/main/docs/product-thesis.md)
+- [MVP implementation](https://github.com/quguai/code-search/blob/main/docs/implementation.md)
+- [Evaluation plan](https://github.com/quguai/code-search/blob/main/docs/evaluation-plan.md)
+- [Evaluation harness](https://github.com/quguai/code-search/blob/main/docs/benchmarking.md)
+- [Reproducible benchmark entry points](https://github.com/quguai/code-search/tree/main/benchmarks)
+- [Public release E2E smoke test](https://github.com/quguai/code-search/blob/main/scripts/e2e_smoke.py)
+- [Shared Java retrieval comparison](https://github.com/quguai/code-search/tree/main/benchmarks/shared-java)
+- [Multilingual development benchmark](https://github.com/quguai/code-search/tree/main/benchmarks/multilingual-30)
+- [Task-evidence fixture](https://github.com/quguai/code-search/blob/main/benchmarks/evidence-showcase/README.md)
+- [PyPI release process](https://github.com/quguai/code-search/blob/main/docs/releasing.md)
+
+## Current gaps
+
+- **P0, public held-out validation:** publish at least 30 untouched, license-compatible tasks with
+  executable patch tests and repeated model runs.
+- **P1, retrieval quality:** close the long-query ranking gaps surfaced by the multilingual
+  diagnostic, and add stronger AST/symbol parsers.
+- **P1, onboarding validation:** expand beyond the seven current user-level Agent Skill destinations
+  only when another integration has a real discovery path and automated coverage. Consider MCP only
+  if a resident index or structured tool discovery provides a measured benefit over CLI invocation.
+- **P2, distribution:** ship signed standalone binaries.
+
+## Status and independent implementation
+
+This is a testable experimental MVP, not a production release. The public development benchmark
+measures retrieval, while the deterministic fixtures and tests cover output behavior and package
+quality. None of them proves held-out retrieval superiority or executable patch success. The
+implementation and bundled Agent Skill are independently designed around the task-evidence workflow.
+
+## License
+
+Licensed under the [Apache License 2.0](https://github.com/quguai/code-search/blob/main/LICENSE).