asrch 0.1.0

# asrch

`asrch` is an agent-safe, bounded code search CLI for coding agents. It uses
`ripgrep` as the backend, but it does not dump unbounded matches into the
agent context.

The tool is designed for exploratory search in unfamiliar repositories: compare
candidate terms, identify promising paths, sample representative nearby matches,
and only then show focused snippets.

日本語版は [README.md#日本語](#日本語) を参照してください。

## Requirements

- Rust 1.85 or later
- `rg` (`ripgrep`) available in `PATH`

## Installation

From a local checkout:

```sh
cargo install --path .
```

After publication to crates.io:

```sh
cargo install asrch
```

## Basic Workflow

When you have multiple candidate terms, do not combine them into a broad OR
regular expression. Start with `survey`; it compares terms and paths without
printing match bodies.

```sh
asrch survey \
  --term cam_coef \
  --term hyb_cam \
  --term erfc \
  --term erf \
  crates/rschem crates/libxc docs \
  --identifier
```

Then choose one useful term and path, and narrow step by step.

```sh
# Summarize match counts and path distribution.
asrch scout cam_coef crates/rschem --identifier

# Sample representative nearby match clusters.
asrch sample cam_coef crates/rschem/src --identifier

# Show focused snippets only after selecting an explicit file.
asrch show cam_coef crates/rschem/src/functional.rs --identifier --context 2
```

`survey` and `scout` use a compact TOON-style output:

```text
survey:
  terms: 3
  paths: 2
  mode: identifier
overall[term,matches,files,dominant_path]:
  cam_coef,20,5,crates/rschem
  hyb_cam,6,2,crates/rschem
by_path:
  crates/rschem[term,matches,files,top_directory]:
    cam_coef,18,4,crates/rschem/src
    hyb_cam,6,2,crates/rschem/src
next: choose one useful term and path, then run asrch scout
```

## Commands

| Command | Purpose |
| --- | --- |
| `survey --term ... [path ...]` | Compare up to 12 terms across up to 8 paths without printing matches. |
| `scout <query> [path]` | Summarize match counts, top directories, and top files. |
| `sample <query> [path]` | Show deterministic representative nearby match clusters. |
| `show <query> <file>` | Show small snippets from one explicit file. |

## Search Modes

Queries are fixed strings by default. Regex search is enabled only with
`--regex`.

| Option | Meaning |
| --- | --- |
| none | Fixed-string substring search |
| `--identifier` | ASCII identifier-boundary search |
| `--word` | Word-boundary fixed-string search |
| `--regex` | Regex search for single-query commands |

`scout`, `sample`, and `show` reject unescaped OR regexes. Use `survey --term`
for multi-term comparison.

## Safety Rules

- Output is hard-capped at 40 lines and 8,000 bytes.
- `show` accepts only an explicit file path.
- `show` refuses broad matches before printing snippets.
- `sample` does not accept `--context`; use `show` after narrowing.
- Empty queries are rejected.
- Short partial-match terms are warned about in `survey`.
- `.git`, `target`, `node_modules`, logs, JSONL/XML files, generated files, and
  scratch directories are excluded by default.
- The CLI is read-only and never modifies searched repositories.

## Documentation

- CLI behavior: [Japanese](docs/cli_behavior.md) / [English](docs/cli_behavior.en.md)
- Goals and constraints: [Japanese](docs/goals_and_condition.md) / [English](docs/goals_and_condition.en.md)
- Agent skill: [skills/asrch-search/SKILL.md](skills/asrch-search/SKILL.md)

## Development

```sh
cargo fmt --all -- --check
cargo test
cargo clippy --all-targets -- -D warnings
```

---

# 日本語

`asrch` は、コーディングエージェント向けの安全な検索 CLI です。バックエンドには
`ripgrep` を使いますが、一致結果を無制限にエージェントのコンテキストへ流し込みません。

未知のリポジトリで探索するときに、候補語を比較し、有望なパスを絞り、代表的な近接一致だけを見てから、最後に小さな snippet を読むための道具です。

## 要件

- Rust 1.85 以降
- `rg` (`ripgrep`) が `PATH` に存在すること

## インストール

ローカル checkout から:

```sh
cargo install --path .
```

crates.io 公開後:

```sh
cargo install asrch
```

## 基本ワークフロー

複数の候補語がある場合は、広い OR 正規表現へ結合しないでください。まず `survey` で、本文を表示せずに候補語と候補パスを比較します。

```sh
asrch survey \
  --term cam_coef \
  --term hyb_cam \
  --term erfc \
  --term erf \
  crates/rschem crates/libxc docs \
  --identifier
```

有効な語とパスを選び、段階的に狭めます。

```sh
# 一致件数とパス分布を確認する
asrch scout cam_coef crates/rschem --identifier

# 代表的な近接一致クラスタを少量見る
asrch sample cam_coef crates/rschem/src --identifier

# 明示したファイルだけ、短い文脈付きで見る
asrch show cam_coef crates/rschem/src/functional.rs --identifier --context 2
```

`survey` と `scout` は、トークン消費を抑えるため TOON に寄せた compact な形式で出力します。

## コマンド

| コマンド | 目的 |
| --- | --- |
| `survey --term ... [path ...]` | 最大 12 語を最大 8 パスで比較し、一致本文は表示しない |
| `scout <query> [path]` | 一致件数、上位ディレクトリ、上位ファイルを要約する |
| `sample <query> [path]` | 決定的に選んだ代表的な近接一致クラスタを表示する |
| `show <query> <file>` | 明示した 1 ファイルから小さな snippet を表示する |

## 検索モード

検索語は既定で固定文字列として扱います。正規表現は `--regex` を明示した場合だけ使います。

| オプション | 意味 |
| --- | --- |
| なし | 固定文字列の部分一致 |
| `--identifier` | ASCII 識別子境界付き検索 |
| `--word` | 単語境界付き固定文字列検索 |
| `--regex` | 単一クエリ系コマンドの正規表現検索 |

`scout`、`sample`、`show` はエスケープされていない OR 正規表現を拒否します。複数語の比較には `survey --term` を使ってください。

## 安全性

- 出力は最大 40 行、8,000 バイトです。
- `show` は明示したファイルだけを受け付けます。
- `show` は一致が広すぎる場合、snippet を表示しません。
- `sample` は `--context` を受け付けません。文脈量を増やす場合は、絞り込み後に `show` を使います。
- 空の検索語は拒否します。
- 短い部分一致語は `survey` で警告します。
- `.git`、`target`、`node_modules`、ログ、JSONL/XML、生成物、scratch 領域などを既定で除外します。
- CLI は読み取り専用であり、検索対象を変更しません。

## ドキュメント

- CLI の挙動: [日本語](docs/cli_behavior.md) / [English](docs/cli_behavior.en.md)
- 目的と制約: [日本語](docs/goals_and_condition.md) / [English](docs/goals_and_condition.en.md)
- Agent Skill: [skills/asrch-search/SKILL.md](skills/asrch-search/SKILL.md)