diff --git a/README.md b/README.md index 8ad2cdc3..594ee07a 100644 --- a/README.md +++ b/README.md @@ -54,11 +54,11 @@ curl -fsSL https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/install.ps1 | iex ``` -**Index a project and query it:** +**Index a project and search it:** ```bash codegraph init /path/to/project # create .codegraph/ and run the first index -codegraph query "" -p /path/to/project # full-text search +codegraph search "" -p /path/to/project # full-text symbol search (`query` is a legacy alias) codegraph serve --mcp --path /path/to/project # MCP server (--path optional, defaults to cwd) ``` @@ -454,14 +454,15 @@ Claude prompt-hook: [`docs/mcp.md`](docs/mcp.md) and ## CLI Subcommands -Core commands: `init`, `index`, `sync`, `query`, `files`, `status`, `serve`, +Core commands: `init`, `index`, `sync`, `search`, `files`, `status`, `serve`, `callers`, `callees`, `impact`, `affected`, `check`, `export`, `unlock`. Agent / install commands: `install`, `uninstall`, `skill`, `self-update`, `completions` (`--install` sets up tab completion for bash/zsh/fish/powershell/elvish). Path convention: most traversal commands accept the project path as a positional -argument or `-p/--path`; `query`/`files`/`serve` use `-p/--path`. +argument or `-p/--path`; `search`/`files`/`serve` use `-p/--path`. +`query` remains a backward-compatible alias for `search`. > **Full reference with all flags:** [`docs/cli.md`](docs/cli.md) diff --git a/crates/codegraph-cli/src/main.rs b/crates/codegraph-cli/src/main.rs index 97fd62b9..815cf38e 100644 --- a/crates/codegraph-cli/src/main.rs +++ b/crates/codegraph-cli/src/main.rs @@ -239,8 +239,11 @@ enum Command { #[arg(short = 'j', long = "json")] json: bool, }, - // Upstream flags/output shape: upstream bin/codegraph.ts:831-837, 849-887. - Query { + // Upstream `query` flags/output shape: upstream bin/codegraph.ts:831-837, + // 849-887. `search` is the canonical CLI name; `query` stays compatible. + /// Search indexed symbols by name. + #[command(visible_alias = "query")] + Search { search: String, #[arg(short, long)] path: Option, @@ -637,14 +640,14 @@ fn run(cli: Cli) -> Result<()> { } => cmd_index(path, force, quiet, verbose), Command::Sync { path, quiet } => cmd_sync(path, quiet), Command::Status { path, json } => cmd_status(path, json), - Command::Query { + Command::Search { search, path, limit, kind, json, strict, - } => cmd_query(search, path, limit, kind, json, strict), + } => cmd_search(search, path, limit, kind, json, strict), Command::Files { path, filter, @@ -1947,7 +1950,7 @@ fn status_extraction_detail( } } -fn cmd_query( +fn cmd_search( search: String, path: Option, limit: i64, @@ -1991,7 +1994,7 @@ fn cmd_query( } else { println!("\nSearch Results for \"{search}\":\n"); for result in results { - println!("{}", format_query_result_line(&result)); + println!("{}", format_search_result_line(&result)); println!(" {}:{}", result.node.file_path, result.node.start_line); if let Some(signature) = &result.node.signature { println!(" {signature}"); @@ -2000,7 +2003,7 @@ fn cmd_query( } } if strict && is_empty { - bail!("codegraph query: no results found for \"{search}\""); + bail!("codegraph search: no results found for \"{search}\""); } Ok(()) } @@ -2009,7 +2012,7 @@ fn cmd_query( /// best-match-first, so the raw FTS `score` (not a 0..1 fraction) is NOT shown — /// rendering `score * 100` produced nonsensical values like `12042%` (upstream /// #1045). The score stays in the `--json` output for sorting/thresholding. -fn format_query_result_line(result: &SearchResult) -> String { +fn format_search_result_line(result: &SearchResult) -> String { format!("{:<12}{}", result.node.kind, result.node.name) } @@ -5538,7 +5541,7 @@ fn describe_symbol(symbol: &str, file: Option<&str>) -> String { fn lookup_symbol_not_found_message(symbol: &str) -> String { format!( - "Symbol \"{symbol}\" not found. Run `codegraph query {symbol}` to search for fuzzy matches." + "Symbol \"{symbol}\" not found. Run `codegraph search {symbol}` to search for fuzzy matches." ) } @@ -7042,7 +7045,7 @@ mod formatter_and_env_tests { } #[test] - fn query_human_result_line_has_no_percentage() { + fn search_human_result_line_has_no_percentage() { // #1045: the raw FTS score is not a percentage; multiplying by 100 emits // nonsensical values like "12042%". Results are already best-match-first, // so the human-readable line must NOT print any percentage at all. @@ -7051,7 +7054,7 @@ mod formatter_and_env_tests { node: n, score: 120.42, }; - let line = format_query_result_line(&sr); + let line = format_search_result_line(&sr); assert!( !line.contains('%'), "human query output must not contain a percentage: {line:?}" diff --git a/crates/codegraph-cli/tests/cli_text_and_errors.rs b/crates/codegraph-cli/tests/cli_text_and_errors.rs index 257837da..a0ee5b12 100644 --- a/crates/codegraph-cli/tests/cli_text_and_errors.rs +++ b/crates/codegraph-cli/tests/cli_text_and_errors.rs @@ -116,6 +116,43 @@ fn query_text_with_results_prints_header_and_signature() { ); } +#[test] +fn search_is_listed_with_query_alias_in_help() { + let dir = TestDir::new("search-help"); + let run = run_in(dir.path(), &["--help"]); + assert!(run.ok, "top-level help must succeed: {}", run.stderr); + assert!( + run.stdout + .lines() + .any(|line| line.contains("search") && line.contains("query")), + "help must expose canonical `search` with the `query` alias: {}", + run.stdout + ); +} + +#[test] +fn search_and_query_alias_are_byte_identical() { + let dir = TestDir::new("search-query-alias"); + let project = indexed_project(&dir); + let p = project.to_str().unwrap(); + let search = run_in(dir.path(), &["search", "add", "-p", p, "--json"]); + let query = run_in(dir.path(), &["query", "add", "-p", p, "--json"]); + assert!(search.ok, "search must succeed: {}", search.stderr); + assert!( + query.ok, + "query compatibility alias must succeed: {}", + query.stderr + ); + assert_eq!( + query.stdout, search.stdout, + "alias stdout must be identical" + ); + assert_eq!( + query.stderr, search.stderr, + "alias stderr must be identical" + ); +} + #[test] fn query_text_with_kind_filter_and_limit() { let dir = TestDir::new("query-kind"); @@ -189,7 +226,7 @@ fn lookup_commands_refuse_fuzzy_only_symbol_matches() { run.stdout ); assert!( - run.stderr.contains("not found") && run.stderr.contains("codegraph query ad"), + run.stderr.contains("not found") && run.stderr.contains("codegraph search ad"), "{command} must provide actionable fuzzy-search guidance: {}", run.stderr ); @@ -218,7 +255,7 @@ fn impact_text_output_and_not_found_branch() { ); assert!( miss.stderr.contains("not found") - && miss.stderr.contains("codegraph query no_such_symbol_zzz"), + && miss.stderr.contains("codegraph search no_such_symbol_zzz"), "missing symbol must print actionable guidance: {}", miss.stderr ); diff --git a/crates/codegraph-cli/tests/godot_qualified_lookup.rs b/crates/codegraph-cli/tests/godot_qualified_lookup.rs index 25ca434f..240c4b37 100644 --- a/crates/codegraph-cli/tests/godot_qualified_lookup.rs +++ b/crates/codegraph-cli/tests/godot_qualified_lookup.rs @@ -249,7 +249,7 @@ fn dotted_nonexistent_member_is_rejected() { "a nonexistent member must be rejected: stdout={stdout} stderr={err}" ); assert!( - err.contains("not found") && err.contains("codegraph query DamageCalculator.nonexistent"), + err.contains("not found") && err.contains("codegraph search DamageCalculator.nonexistent"), "the rejection must be actionable: {err}" ); } @@ -269,7 +269,7 @@ fn dotted_non_class_receiver_is_rejected() { "a non-class receiver must be rejected: stdout={stdout} stderr={err}" ); assert!( - err.contains("not found") && err.contains("codegraph query notaclass.calc_skill_damage"), + err.contains("not found") && err.contains("codegraph search notaclass.calc_skill_damage"), "the rejection must be actionable: {err}" ); } diff --git a/docs/cli.md b/docs/cli.md index d88cccb8..71116853 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -6,7 +6,7 @@ - **Positional or `-p/--path`:** `init`, `uninit`, `index`, `sync`, `status`, `callers`, `callees`, `impact`, `affected`, `unlock`, `check`, `export`. -- **`-p/--path` only:** `query`, `files`, `serve`, `audit`. +- **`-p/--path` only:** `search`, `files`, `serve`, `audit`. - **No project path:** `install`, `uninstall`, `skill`, `version`, `self-update`, `completions`. @@ -28,7 +28,7 @@ | `index` | (Re-)index in full | `[path]`, `-f/--force`, `-q/--quiet`, `-v/--verbose` | | `sync` | Incremental sync: re-index only changed files, drop deleted ones, re-resolve | `[path]`, `-q/--quiet` | | `status` | Print index stats (files/nodes/edges/DB size/journal) | `[path]`, `-j/--json` | -| `query` | FTS5 + multi-signal scored search | ``, `-p`, `-l/--limit`, `-k/--kind`, `-j/--json`, `--strict` | +| `search` | FTS5 + multi-signal scored symbol search | ``, `-p`, `-l/--limit`, `-k/--kind`, `-j/--json`, `--strict` | | `files` | List indexed files (tree/flat/grouped) | `-p`, `--filter `, `--language `, `--pattern`, `--format`, `--max-depth`, `-j` | | `serve` | Start the server; `--mcp` enters MCP stdio mode | `-p`, `--mcp`, `--no-watch` | | `unlock` | Clear a stale daemon lock (keeps live pids) | `[path]` | @@ -43,6 +43,9 @@ | `self-update` | Update the binary in place from the latest GitHub release | `--check`, `--force`, `--tag ` | | `completions` | Print or install shell completions | `` (bash, zsh, fish, powershell, elvish), `--install` | +`query` remains a visible backward-compatible alias for `search`; new scripts, +documentation, and diagnostics should use `search`. + > **Note:** `serve --no-watch` and `CODEGRAPH_NO_WATCH=1` are fully equivalent — > both disable the live file watcher. See > [Daemon, watch & environment variables](#daemon-watch--environment-variables) @@ -288,7 +291,7 @@ codegraph files -p . --filter src --language go # combine: Go files under src/ **Symbol count semantics.** The per-file "symbols" count shown by `files` is the **live count of graph nodes for that file** (`COUNT(*)` over the `nodes` table), -so it stays consistent with what `query`/`callers`/`callees` see. This matters +so it stays consistent with what `search`/`callers`/`callees` see. This matters for Godot `.tscn`/`.tres` files: their scene/resource marker nodes are added by the framework resolver after the initial extractor, so the stored `files.node_count` column (which records only the initial extractor's count) can @@ -386,7 +389,7 @@ is out of scope (that is Godot MCP Pro's job). ## Symbol lookup failures and `--strict` `callers`, `callees`, and `impact` require an exact symbol match. If the name -does not exist, they exit non-zero and suggest `codegraph query ` for +does not exist, they exit non-zero and suggest `codegraph search ` for fuzzy search instead of silently substituting the highest-ranked result. `--strict` retains its separate contract: after an exact match, an empty result also exits non-zero. diff --git a/docs/readme/README.zh-CN.md b/docs/readme/README.zh-CN.md index d0ef1252..27afcc16 100644 --- a/docs/readme/README.zh-CN.md +++ b/docs/readme/README.zh-CN.md @@ -53,7 +53,7 @@ irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/instal ```bash codegraph init /path/to/project # 创建 .codegraph/ 并执行首次索引 -codegraph query "" -p /path/to/project # 全文检索 +codegraph search "" -p /path/to/project # 全文符号检索(`query` 为兼容别名) codegraph serve --mcp --path /path/to/project # 为 AI 代理启动 MCP 服务器(--path 可选,默认 cwd) ``` @@ -415,13 +415,13 @@ codegraph http list / stop # 管理运行中的 HTTP 服务 ## CLI 子命令 -核心命令:`init`、`index`、`sync`、`query`、`files`、`status`、`serve`、 +核心命令:`init`、`index`、`sync`、`search`、`files`、`status`、`serve`、 `callers`、`callees`、`impact`、`affected`、`check`、`export`、`unlock`。 代理 / 安装命令:`install`、`uninstall`、`skill`、`self-update`、`completions`。 -路径约定:大多数遍历命令把项目路径作位置参数或 `-p/--path`;`query`/`files`/ -`serve` 用 `-p/--path`。 +路径约定:大多数遍历命令把项目路径作位置参数或 `-p/--path`;`search`/`files`/ +`serve` 用 `-p/--path`。`query` 继续作为 `search` 的向后兼容别名。 > **完整参考(含所有标志):** [`../cli.md`](../cli.md) diff --git a/skills/codegraph/SKILL.md b/skills/codegraph/SKILL.md index c8487823..25a81822 100644 --- a/skills/codegraph/SKILL.md +++ b/skills/codegraph/SKILL.md @@ -103,6 +103,11 @@ Pick your entry point based on what you're trying to answer: | "What files are under path P?" | `codegraph_files` | | "Is the index up to date?" | `codegraph_status` | +These are MCP tool names. When MCP is unavailable and you are invoking the +binary directly, use `codegraph search "" -p /path/to/project` for +symbol lookup. `codegraph query` remains a compatibility alias; prefer +`codegraph search` in new commands and guidance. + ### `codegraph_explore` — start here For a whole-project overview ("analyze the project", "explain the architecture", @@ -127,6 +132,12 @@ across multiple signals (name, kind, path). This is the closest thing to "semantic" lookup available, but it is **fully deterministic full-text scoring** — there are no embeddings, no vector index, no neural model of any kind. +CLI equivalent: + +```bash +codegraph search "" -p /path/to/project +``` + ### `codegraph_node` — read source + graph trail Pass a symbol ID (from a `search` result) or a file path. A symbol ID returns