name: explore description: Explore codebase structure via iterative SQL queries against yomu's indexed SQLite DB. Do NOT use for concept/semantic search (use use-cli-yomu) or literal string search (use Grep). when_to_use: どこで使われてる, どのファイルが依存してる, 呼び出し元, 参照してるファイル, import元, 循環依存, 依存チェーン, who calls, what depends on, which files use, callers, callees, dependency chain, files importing a symbol allowed-tools: Bash(sqlite3:) Bash(git:) Bash(yomu:*) argument-hint: "[natural language question about codebase structure]"

explore

Prerequisite

Run yomu status first and read the counts.

DB path: <project_root>/.yomu/index.db (git rev-parse --show-toplevel). If not a git repo, ask user for the DB path.

Schema

Run queries via sqlite3 -readonly <db_path> "<query>".

chunks (
  id INTEGER PRIMARY KEY,
  file_path TEXT NOT NULL,
  chunk_type TEXT NOT NULL,   -- e.g. rust_fn, rust_struct, rust_impl, rust_trait, rust_enum, md_section, other. Language-dependent.
  name TEXT,                  -- nullable
  content TEXT NOT NULL,
  start_line INTEGER NOT NULL,
  end_line INTEGER NOT NULL,
  file_hash TEXT NOT NULL,
  parent_chunk_id INTEGER REFERENCES chunks(id)
)

file_references (
  id INTEGER PRIMARY KEY,
  source_file TEXT NOT NULL,  -- symbol を使う側
  target_file TEXT NOT NULL,  -- symbol を定義する側
  symbol_name TEXT,           -- nullable
  ref_kind TEXT NOT NULL      -- e.g. named
)

file_context (file_path TEXT PRIMARY KEY, imports_text TEXT)

-- FTS5 external content. rowid = chunks.id で JOIN
fts_chunks (name, content, file_path)

Do not query vec_chunks (requires sqlite-vec extension; semantic search belongs to yomu search).

When to Use

Query Archetypes

Start from an archetype → refine based on previous results. Do not hardcode today's only enum value (e.g. ref_kind='named' will expand).

1. Caller lookup (who uses this symbol)

SELECT source_file, ref_kind, COUNT(*) AS uses
FROM file_references
WHERE symbol_name = 'TargetSymbol'
GROUP BY source_file, ref_kind
ORDER BY uses DESC;

2. Import chain (what a file imports)

SELECT file_path, imports_text
FROM file_context
WHERE imports_text LIKE '%target_module%';

3. Keyword FTS (where keyword appears in code content)

SELECT c.file_path, c.start_line, c.name, c.chunk_type
FROM fts_chunks f
JOIN chunks c ON f.rowid = c.id
WHERE fts_chunks MATCH 'keyword'
LIMIT 20;

Output

• Lead with the direct answer (file list, count, chain)
• Cite file_path:line for every claim
• State the basis for each claim: direct row from query result for facts, "inferred by JOIN / aggregation / naming" for inferences

Example:

TargetSymbol を使うファイルは 3 件 (direct query result)
  src/handlers/user.rs:42
  src/handlers/admin.rs:18
  src/tests/integration.rs:205

ref_kind は 'named' のみ (inferred from aggregation): import vs call の区別は不明