Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 "<symbol>" -p /path/to/project # full-text search
codegraph search "<symbol>" -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)
```

Expand Down Expand Up @@ -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)

Expand Down
25 changes: 14 additions & 11 deletions crates/codegraph-cli/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<PathBuf>,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -1947,7 +1950,7 @@ fn status_extraction_detail(
}
}

fn cmd_query(
fn cmd_search(
search: String,
path: Option<PathBuf>,
limit: i64,
Expand Down Expand Up @@ -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}");
Expand All @@ -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(())
}
Expand All @@ -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)
}

Expand Down Expand Up @@ -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."
)
}

Expand Down Expand Up @@ -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.
Expand 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:?}"
Expand Down
41 changes: 39 additions & 2 deletions crates/codegraph-cli/tests/cli_text_and_errors.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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");
Expand Down Expand Up @@ -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
);
Expand Down Expand Up @@ -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
);
Expand Down
4 changes: 2 additions & 2 deletions crates/codegraph-cli/tests/godot_qualified_lookup.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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}"
);
}
Expand All @@ -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}"
);
}
Expand Down
11 changes: 7 additions & 4 deletions docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand All @@ -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 | `<search>`, `-p`, `-l/--limit`, `-k/--kind`, `-j/--json`, `--strict` |
| `search` | FTS5 + multi-signal scored symbol search | `<search>`, `-p`, `-l/--limit`, `-k/--kind`, `-j/--json`, `--strict` |
| `files` | List indexed files (tree/flat/grouped) | `-p`, `--filter <DIR>`, `--language <LANG>`, `--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]` |
Expand All @@ -43,6 +43,9 @@
| `self-update` | Update the binary in place from the latest GitHub release | `--check`, `--force`, `--tag <vX.Y.Z>` |
| `completions` | Print or install shell completions | `<shell>` (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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 <name>` for
does not exist, they exit non-zero and suggest `codegraph search <name>` 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.
Expand Down
8 changes: 4 additions & 4 deletions docs/readme/README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/instal

```bash
codegraph init /path/to/project # 创建 .codegraph/ 并执行首次索引
codegraph query "<symbol>" -p /path/to/project # 全文检索
codegraph search "<symbol>" -p /path/to/project # 全文符号检索(`query` 为兼容别名)
codegraph serve --mcp --path /path/to/project # 为 AI 代理启动 MCP 服务器(--path 可选,默认 cwd)
```

Expand Down Expand Up @@ -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)

Expand Down
11 changes: 11 additions & 0 deletions skills/codegraph/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 "<symbol>" -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",
Expand All @@ -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 "<symbol>" -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
Expand Down
Loading