code-search-cli 0.1.0__tar.gz

code_search_cli-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

code_search_cli-0.1.0/NOTICE

@@ -0,0 +1,7 @@
+Code Search
+Copyright 2026 Code Search contributors
+
+This product is licensed under the Apache License, Version 2.0.
+
+Semble and code-review-graph are independent projects referenced only as
+research and evaluation baselines. Their code is not included in this product.

code_search_cli-0.1.0/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: code-search-cli
+Version: 0.1.0
+Summary: Task-aware, evidence-oriented local code retrieval
+Author: Code Search contributors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/quguai/code-search
+Project-URL: Repository, https://github.com/quguai/code-search
+Project-URL: Issues, https://github.com/quguai/code-search/issues
+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>Accurate evidence. Smaller 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://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="Codex skill included" src="https://img.shields.io/badge/Codex-skill_included-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 release is an independently implemented, no-runtime-model MVP. It can read a working tree
+or any Git revision and returns source locations, ranking reasons, structural evidence roles, and
+payload statistics.
+
+> Search less. Hand the agent the evidence it needs to act.
+
+## Quick start
+
+### Install from this checkout
+
+The complete local flow works today:
+
+```bash
+cd /path/to/code-search
+uv tool install .
+code-search install
+```
+
+`code-search install` installs the bundled `code-search` skill into Codex. Restart Codex after the
+command so it can discover the skill. The installer is idempotent and refuses to overwrite a locally
+modified skill unless `--force` is supplied.
+
+After the first PyPI release, the first command becomes:
+
+```bash
+uv tool install code-search-cli
+code-search install
+```
+
+The PyPI distribution name (`code-search-cli`) and CLI entry point (`code-search`) are ready, but this
+repository has not been published to PyPI yet.
+
+### 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; use `code-search clean` to remove the cached source snapshot and derived metadata.
+
+## What you get
+
+- A concise, de-duplicated evidence set instead of an unbounded list of matches.
+- Source locations, scores, inclusion reasons, 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 reuses unchanged source terms and structural boundaries.
+- Java, Python, JavaScript, and TypeScript structural extraction with no runtime model dependency.
+- A bundled Codex skill that teaches the agent when to retrieve, expand, or fall back to exact `rg`.
+
+## CLI
+
+Read a historical revision:
+
+```bash
+code-search retrieve \
+  --repo /path/to/repository \
+  --ref HEAD~1 \
+  --task "Resolve NullPointerException in scheduled dump" \
+  --format json
+```
+
+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 Codex skill:
+
+```bash
+code-search install
+code-search uninstall
+```
+
+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
+```
+
+## Benchmarks
+
+The primary benchmark uses `NDCG@10`, `Recall@10`, `MRR@10`, latency, and Top-10 payload size. The
+local shared subset contains 61 queries over pinned revisions of Gson, Apache Commons Lang, and
+Jackson Databind. Semble's published 1,251-query results are kept in a separate table and are not
+presented as a local rerun.
+
+<!-- benchmark-results:start -->
+#### Local four-axis scorecard
+
+![Local scorecard for ranking, Top-10 recall, latency, and payload](https://raw.githubusercontent.com/quguai/code-search/main/assets/benchmark-quality-speed.png)
+
+### Local shared Java subset
+
+| Method | NDCG@10 | Recall@10 | MRR@10 | Warm p50 | Top-10 payload |
+|---|---:|---:|---:|---:|---:|
+| Semble | **0.8250** | **0.9754** | **0.7852** | 4.25 ms | 1,803 tok |
+| code-review-graph | 0.7634 | 0.8607 | 0.7670 | 103.30 ms | 16,162 tok |
+| Code Search MVP | 0.7217 | 0.8525 | 0.6970 | 38.08 ms | 2,490 tok |
+| BM25 | 0.5686 | 0.7623 | 0.5398 | **0.72 ms** | **1,752 tok** |
+| probe | 0.2044 | 0.4262 | 0.1453 | 1,764.40 ms | 5,537 tok |
+| ripgrep | 0.1977 | 0.2377 | 0.1904 | 30.84 ms | 28,605 tok |
+
+### Published full-suite reference (not a local rerun)
+
+These values are reported by Semble for its 1,251-query, 63-repository, 19-language benchmark.
+
+| Method | NDCG@10 | Cold first result | Model size |
+|---|---:|---:|---:|
+| CodeRankEmbed Hybrid | 0.8617 | 57.29 s | 137M |
+| semble | 0.8544 | 264.09 ms | 16M |
+| CodeRankEmbed | 0.7648 | 57.29 s | 137M |
+| ColGREP | 0.6925 | 5.87 s | 16M |
+| BM25 | 0.6730 | 262.62 ms | no model |
+| grepai | 0.5610 | 35.00 s | 137M |
+| probe | 0.3870 | 207.10 ms | no model |
+| ripgrep | 0.1260 | 12.08 ms | no model |
+<!-- benchmark-results:end -->
+
+Regenerate the scorecard and synchronize the measured JSON values into both READMEs:
+
+```bash
+uv run --no-project --with matplotlib python scripts/publish_shared_benchmark.py
+```
+
+This command does not rerun the benchmark or publish a package. See the
+[shared benchmark methodology](https://github.com/quguai/code-search/blob/main/benchmarks/shared-java/README.md),
+[raw local results](https://github.com/quguai/code-search/blob/main/benchmarks/shared-java/RESULTS.json), and
+[published-reference provenance](https://github.com/quguai/code-search/blob/main/benchmarks/shared-java/PUBLISHED_REFERENCE.json).
+
+The unit test suite creates only temporary synthetic repositories. The shared benchmark uses public,
+pinned Gson, Apache Commons Lang, and Jackson Databind revisions with Semble's public annotations.
+Machine-local and private development tasks are deliberately excluded from the public repository.
+
+## How it differs from Semble and code-review-graph
+
+The projects overlap, but optimize different parts of an agent workflow. This comparison describes
+their public product shape; it is not a claim that one implementation dominates every task.
+
+| | Code Search | Semble | code-review-graph |
+|---|---|---|---|
+| Primary job | Assemble task-relevant, explainable evidence | Find relevant code chunks quickly | Persist code relations for review, impact, and multi-hop exploration |
+| Result shape | Evidence bundle with source, reason, score, and structural role | Compact ranked code snippets | Graph nodes, relations, traversals, and review reports |
+| 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 |
+| 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 |
+| 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 |
+| Best fit today | Explainable task-evidence experiments | Fast general-purpose natural-language code search | Review and durable multi-hop structural questions |
+
+Semble still has the broader onboarding path. Its `install` command can configure MCP, generated
+instructions, or a dedicated sub-agent across several coding agents. `code-search install` currently
+installs one Codex skill. Code Search intentionally uses CLI + skill as its primary interface; an MCP
+server is optional, not a prerequisite.
+
+### Current advantages
+
+- **Task roles, not only similarity.** Lifecycle, registration, publication, ordering, and test
+  evidence are represented separately instead of returning only one cluster of similar chunks.
+- **Missing-behavior evidence.** For callback tasks, structurally similar sibling methods can expose
+  an expected publication step that is absent from the target path, instead of rewarding only code
+  that already contains the queried behavior.
+- **Causal repair sets.** Startup-order tasks can connect a publisher, a lazily initialized static
+  subscriber, and the lifecycle owner whose dependency declaration must change, marking each
+  independently actionable production file.
+- **Auditable evidence.** Each unit includes its location, reason, score, and estimated token cost.
+- **Historical and no-model operation.** It can inspect a Git revision without checkout and has no
+  runtime model dependency.
+- **Smaller output than the current graph adapter.** On the shared subset, Code Search returns a
+  2,490-token Top-10 payload versus 16,162 tokens for code-review-graph.
+
+### Where competitors still lead
+
+Semble leads this MVP on ranking quality, token efficiency, warm latency, and integration breadth.
+code-review-graph provides deeper persistent relations, incremental graph maintenance, and review
+automation. Code Search does not currently claim an overall win over either project.
+
+## 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.
+
+This is currently a transparent lexical/structural baseline. Independently implemented dense retrieval
+and stronger parsers remain future work.
+
+## Documentation
+
+- [Competitive analysis](https://github.com/quguai/code-search/blob/main/docs/competitive-analysis.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)
+- [Open benchmark and adapters](https://github.com/quguai/code-search/blob/main/docs/benchmarking.md)
+- [Shared Java benchmark](https://github.com/quguai/code-search/blob/main/benchmarks/shared-java/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:** add independently implemented optional dense retrieval and stronger
+  AST/symbol parsers.
+- **P1 — onboarding breadth:** add safe CLI/skill installers for more coding agents. Consider MCP only
+  if a resident index or structured tool discovery provides a measured benefit over CLI invocation.
+- **P2 — distribution:** publish to PyPI and ship signed standalone binaries. Until publication,
+  `uv tool install code-search-cli` cannot install this project from the public registry.
+
+## Status and independent implementation
+
+This is a testable experimental MVP, not a production release. It reaches `0.7217 NDCG@10` on the
+61-query shared Java subset versus Semble at `0.8250`; Recall@10 is `0.8525`, and warm query p50 is
+38.08 ms. These public results measure retrieval, not executable patch success, and are not a held-out
+production claim.
+
+The project is inspired by [Semble](https://github.com/MinishLab/semble) and
+[code-review-graph](https://github.com/tirth8205/code-review-graph), which are used as public baselines.
+It does not copy or rewrite their source, tests, prompts, documentation, interfaces, or distinctive
+command vocabulary. The implementation and bundled Codex skill are independently designed around this
+project's task-evidence workflow.
+
+## License
+
+Licensed under the [Apache License 2.0](https://github.com/quguai/code-search/blob/main/LICENSE). Semble and code-review-graph are independent projects;
+their code is not included here.