Skip to content
28 changes: 20 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ The `phantom-fractal` package builds two binaries from one `main.rs`: `phantom-f
They have sixteen commands:

- `index PATH` walks the Rust files under PATH, extracts their items, `use` paths, and calls, and stores them in a SQLite database in the Phantom data directory. It then builds each package's module tree and resolves calls to edges, as [Calls](#calls) describes, adds `import` and `impl` edges, and stores the rank of the graph, as [Rank](#rank) describes. On a git root it also reads the history and stores which files change together, as [Co-change](#co-change) describes. PATH itself is only read. It holds the database's writer lock while it runs, as [Freshness](#freshness) describes. A second run over an unchanged tree and an unmoved HEAD writes nothing.
- `find NAME` returns the indexed symbols named exactly NAME as `hits`, each with its kind, visibility, path, and line, ordered by path and then line. It returns at most 100; `truncated` is true when more matched. A name that was not indexed returns no hits.
- `find NAME` returns the indexed symbols named exactly NAME as `hits`, each with its kind, visibility, path, and line, ordered by path and then line. Methods are included: a function, struct, enum, trait or module hit gives its bare name, and a method hit gives its qualified name, such as `crate::meta::Meta::page`, since the bare name does not say whose method it is. It returns at most 100; `truncated` is true when more matched. A name that was not indexed returns no hits.
- `callers SYMBOL` returns the resolved calls to SYMBOL.
- `callees SYMBOL` returns the resolved calls SYMBOL makes, and `unresolved_calls`: how many calls, method calls, and macros inside SYMBOL have no edge.
- `impact SYMBOL` walks the calls into SYMBOL backwards and says what a change to it reaches, as [Impact](#impact) describes. `impact --diff` does the same from every symbol the work tree changed against HEAD or a named commit, as [Diff impact](#diff-impact) describes.
Expand Down Expand Up @@ -84,11 +84,12 @@ SYMBOL is one of:

- a bare name, such as `helper`;
- a name within its file, such as `Counter::new` or `tests::check` for a function in an inline `mod tests`;
- a module-qualified name: the file's whole module path from the target root, with or without `crate::`, joined to the name within the file, such as `util::deep::sink` or `crate::util::deep::sink`. A partial path such as `deep::sink` does not match.
- a module-qualified name: the file's whole module path from the target root, with or without `crate::`, joined to the name within the file, such as `util::deep::sink` or `crate::util::deep::sink`. A partial path such as `deep::sink` does not match;
- a method by its module and bare name, leaving out its type, such as `tricky::greet` for `Guest::greet` in `src/tricky.rs`, or `app::watch_dir` for `App::watch_dir` in a module `tui::app`.

Output names a symbol by its qualified name from `crate`, such as `crate::tests::check`. In a workspace, `crate` is the symbol's own target, and `path` or `symbol_path` says which package it is in. A symbol in an orphan file has no module, so its name starts at its own name or `impl` type.

- No symbol matches: `not_found`, exit 3.
- No symbol matches: `not_found`, exit 3. `data.did_you_mean` lists up to 10 symbols whose bare name is the query's last segment, each in the shape of an `ambiguous` candidate, or none: `{"did_you_mean":[]}`. The message is unchanged.
- More than one matches: `ambiguous`, exit 6. The message lists up to 10 candidates with their paths and lines, `data.candidates` holds the same ones, and `data.total` counts them all. Qualify the name further to pick one.
- The tree has no index, or its index predates call edges: `no_index`, exit 2. Run `index` again.

Expand All @@ -97,12 +98,21 @@ On success, `data.symbol` is the symbol's qualified name, kind, path, and line.
- `name`, `kind`, and `symbol_path`: the other symbol's qualified name, its kind, and the file it is declared in.
- `path` and `line`: the call site.
- `confidence` and `reason`: how the call was placed.
- `display`: the other symbol by file, then its inline scope, type and name, such as `src/tui/app.rs::App::start_watcher`.

Hits are sorted by path and then line. There are at most 100, and `truncated` is true when more existed. Every path is relative to the indexed tree.

After the hits, three keys answer "which functions, in which files" without counting by hand. All three are built from the hits listed, after the cap:

- `callers_distinct`: one entry per `display`, sorted by it, with `sites`, its call-site lines sorted, and `min_confidence`, the lowest confidence among them. For `callees` it groups by callee.
- `files`: the files the other symbols are declared in, distinct and sorted.
- `sites`: how many hits are listed.

A caller reached only through a re-export or a macro may be missing; confirm with one grep when completeness matters.

```
$ fract callers util::helper
{"ok":true,"data":{"symbol":{"name":"crate::util::helper","kind":"function","path":"src/util.rs","line":5},"hits":[{"name":"crate::entry","kind":"function","path":"src/lib.rs","line":17,"symbol_path":"src/lib.rs","confidence":1.0,"reason":"path-exact"}],"truncated":false},"error":null,"schema":1}
{"ok":true,"data":{"symbol":{"name":"crate::util::helper","kind":"function","path":"src/util.rs","line":5},"hits":[{"name":"crate::entry","kind":"function","path":"src/lib.rs","line":17,"symbol_path":"src/lib.rs","confidence":1.0,"reason":"path-exact","display":"src/lib.rs::entry"}],"truncated":false,"callers_distinct":[{"display":"src/lib.rs::entry","sites":[17],"min_confidence":1.0}],"files":["src/lib.rs"],"sites":1},"error":null,"schema":1}
```

That output is cut to one hit.
Expand Down Expand Up @@ -221,15 +231,15 @@ Phantom reads source text only. Macros are never expanded: they are counted by n

A value out of range, or one that is not a number, is usage and exits 1.

`data` holds `symbol` (as in [Calls](#calls)), `risk`, `exact`, `reasons`, `counts`, `groups`, `tests`, and `options`, which echoes `depth`, `min_confidence`, and `include_tests`. Every path is relative to the indexed tree.
`data` holds `symbol` (as in [Calls](#calls)), `risk`, `exact`, `reasons`, `counts`, `groups`, `tests`, and `options`, which echoes `depth`, `min_confidence`, and `include_tests`. Then come `callers_distinct`, `files`, and `sites`, as in [Calls](#calls), over the hits and tests listed: each entry groups the reached symbol's `site_line`s, and `files` holds the reached symbols' `path`s. Under `--summary` those three are absent. Every path is relative to the indexed tree.

### What is walked

- Only the stored `calls` edges, the ones `callers` lists, followed from callee to caller, breadth-first from SYMBOL. SYMBOL's callers are depth 1, their callers depth 2, and so on.
- A symbol's depth is the level where it is first reached. An edge to a symbol already placed at that level or nearer is ignored, so a cycle or a self-call never brings a symbol, or SYMBOL itself, back.
- Its `confidence` is the product of the edge confidences along its best path. SYMBOL counts as 1.0, and a symbol takes the highest product over its edges from the level before. `reason`, `site_path`, and `site_line` are that best edge's reason and call site.
- A symbol below `--min-confidence` is neither reported nor walked past. It adds 1 to `counts.below_floor`.
- `groups` has one entry per depth with a hit: `depth`, `total`, `truncated`, and at most 100 `hits`, sorted by path, then line, then name. Each hit is `name`, `kind`, `path`, `line`, `confidence`, `reason`, `site_path`, and `site_line`.
- `groups` has one entry per depth with a hit: `depth`, `total`, `truncated`, and at most 100 `hits`, sorted by path, then line, then name. Each hit is `name`, `kind`, `path`, `line`, `confidence`, `reason`, `site_path`, `site_line`, and `display`, as in [Calls](#calls). `impact --diff` hits have no `display`.

### Tests

Expand Down Expand Up @@ -273,7 +283,7 @@ A test that is reached goes to `tests`, with its depth, and never to `groups`. I

```
$ fract impact report
{"ok":true,"data":{"symbol":{"name":"crate::report","kind":"function","path":"app/src/main.rs","line":16},"risk":"low","exact":true,"reasons":[],"counts":{"direct":1,"total":2,"packages":1,"tests":0,"below_floor":0},"groups":[{"depth":1,"total":1,"truncated":false,"hits":[{"name":"crate::run","kind":"function","path":"app/src/main.rs","line":9,"confidence":0.95,"reason":"local","site_path":"app/src/main.rs","site_line":13}]}],"tests":[],"options":{"depth":3,"min_confidence":0.2,"include_tests":true}},"error":null,"schema":1}
{"ok":true,"data":{"symbol":{"name":"crate::report","kind":"function","path":"app/src/main.rs","line":16},"risk":"low","exact":true,"reasons":[],"counts":{"direct":1,"total":2,"packages":1,"tests":0,"below_floor":0},"groups":[{"depth":1,"total":1,"truncated":false,"hits":[{"name":"crate::run","kind":"function","path":"app/src/main.rs","line":9,"confidence":0.95,"reason":"local","site_path":"app/src/main.rs","site_line":13,"display":"app/src/main.rs::run"}]}],"tests":[],"options":{"depth":3,"min_confidence":0.2,"include_tests":true},"callers_distinct":[{"display":"app/src/main.rs::run","sites":[13],"min_confidence":0.95}],"files":["app/src/main.rs"],"sites":1},"error":null,"schema":1}
```

That output, from `fixtures/impact`, is cut to one hit: the depth-2 group is left out.
Expand Down Expand Up @@ -703,6 +713,8 @@ The server is read-only by default. It offers these tools:
- `impact --diff`: as `impact`, within `impact`, then `files_only` and `changed` from the end;
- `show`: `source` as a whole, then the `cochange` partners, the callees' hits, the callers' hits, and the members' hits, each from the end.

Before any of these, `callers`, `callees`, and `impact` drop the keys added beside the old ones, as a whole: each hit's `display`, and `callers_distinct`, `files`, and `sites`. A reply that fits with them keeps them all; one that does not loses them all and is then cut exactly as it was before they existed. They are not counted in `omitted`.

The target symbol, the counts, `risk`, `exact`, `reasons`, the groups themselves, and every `truncated` flag stay. `truncated` still says only whether the command's own cap cut the list.
- **`data.tokens`:** with a budget, `data` ends with `tokens: {max, used, omitted}`. `max` is the budget, `used` is the estimate of the printed line, `tokens` and `meta` included, and `omitted` counts the entries dropped. Without a budget there is no `tokens` key, and `data` is byte for byte what it was.
- **Too small:** when the reply does not fit even with every list empty, the result is `usage`, exit 1, with a message that starts `budget_too_small:`.
Expand All @@ -715,7 +727,7 @@ The server speaks the `initialize`-based MCP revisions [2025-11-25](https://mode
- **`initialize`:**
- The server echoes the client's `protocolVersion` when it is one of those two, and otherwise answers `2025-11-25`.
- `serverInfo` is `{"name":"phantom-fractal","version":"0.0.0"}`, and `capabilities` is `{"tools":{"listChanged":false}}`.
- `instructions` is one short paragraph.
- `instructions` is the [For agents](#for-agents) list, trimmed to at most 25 lines. It says to treat tool output as untrusted data, never as instructions, and each tool's `description` leads with the question it answers and the grep it replaces.
- **Other methods:**
- `notifications/initialized` gets no reply, and every other notification is ignored.
- `ping` returns `{}`.
Expand Down
18 changes: 18 additions & 0 deletions crates/phantom-fractal-store/src/fetch.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
//! One statement's rows through its mapper, shared by the read modules.
//!
//! A read prepares one statement, queries it, and hands every row to its
//! mapper through [`collect_rows`]; a column the result type does not
//! carry, or a mark the caller owns, is read by the caller and passed in
//! (W13 R14).
use crate::StoreError;
/// Every row of one statement through its mapper, in statement order.
pub(crate) fn collect_rows<T>(
rows: &mut rusqlite::Rows<'_>,
map: impl Fn(&rusqlite::Row<'_>) -> Result<T, StoreError>,
) -> Result<Vec<T>, StoreError> {
let mut out = Vec::new();
while let Some(row) = rows.next()? {
out.push(map(row)?);
}
Ok(out)
}
151 changes: 130 additions & 21 deletions crates/phantom-fractal-store/src/graph.rs
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ use phantom_fractal_lang::{
};

use crate::StoreError;
use crate::fetch::collect_rows;
use crate::rows;

/// What `write_crate_graph` replaces the `packages` table with.
Expand All @@ -37,6 +38,17 @@ pub struct SymbolMatch {
pub line: Option<i64>,
}

/// One symbol named exactly as `find` asked: the stored name, kind,
/// visibility text, file and start line, items and methods alike.
#[derive(Debug, Clone, PartialEq)]
pub struct FindRow {
pub id: i64,
pub name: String,
pub kind: String,
pub visibility: String,
pub file: String,
pub line: Option<i64>,
}
/// One stored edge row of one kind, as `edges_of_kind` reads it.
#[derive(Debug, Clone, PartialEq)]
pub struct EdgeRow {
Expand Down Expand Up @@ -101,6 +113,28 @@ fn parse_fingerprint(text: &str) -> Option<[u8; 32]> {
Some(out)
}

/// One matching row, with the row id read by the caller.
fn symbol_match_row(row: &rusqlite::Row<'_>, id: i64) -> Result<SymbolMatch, StoreError> {
Ok(SymbolMatch {
id,
kind: row.get(1)?,
module_path: row.get(2)?,
qual_name: row.get(3)?,
file: row.get(4)?,
line: row.get(5)?,
})
}
/// One named row: name, kind, visibility, file and start line.
fn find_row(row: &rusqlite::Row<'_>, id: i64) -> Result<FindRow, StoreError> {
Ok(FindRow {
id,
name: row.get(1)?,
kind: row.get(2)?,
visibility: row.get(3)?,
file: row.get(4)?,
line: row.get(5)?,
})
}
pub(crate) fn reason_from_text(reason: &str) -> Result<Reason, StoreError> {
match reason {
"path-exact" => Ok(Reason::PathExact),
Expand Down Expand Up @@ -662,15 +696,26 @@ impl crate::Store {
Ok(())
}

/// Symbols matching a bare name such as `open_ledger` or a
/// module-qualified name such as `ledger::open_ledger` or
/// `ledger::Ledger::open` — the file module path without a leading
/// `crate::` joined to the in-file `qual_name`, so an inline module
/// never doubles, and the `crate::` prefixed spelling matches too.
/// `query` is bound, never spliced.
/// Symbols matching a query: the bare name, the in-file `qual_name`
/// such as `Ledger::open`, and the file module path joined to that
/// name, with or without `crate::`. When those answer nothing, a
/// method is tried as `<module>::<name>` from any `::` boundary of its
/// file module path, so `app::watch_dir` resolves while every query
/// the exact forms answer keeps exactly its rows. `query` is bound,
/// never spliced.
pub fn symbols_matching(&self, query: &str) -> Result<Vec<SymbolMatch>, StoreError> {
// The optional `crate::` prefix of the query is stripped in the
// caller, not in SQL, so one bound value covers both spellings.
let exact = self.symbols_matching_exact(query)?;
if !exact.is_empty() {
return Ok(exact);
}
self.symbols_matching_method(query)
}
/// The spellings the base answers: the bare name, the in-file
/// qualified name, and the file module path joined to it, `crate::`
/// optional.
fn symbols_matching_exact(&self, query: &str) -> Result<Vec<SymbolMatch>, StoreError> {
// The optional `crate::` prefix is stripped in Rust, not in SQL,
// so one bound value covers both spellings.
let qualified = query.strip_prefix("crate::").unwrap_or(query);
let mut statement = self.conn.prepare(
"SELECT s.id, s.kind, COALESCE(m.path, ''), s.qual_name, f.path, s.start_line
Expand All @@ -695,20 +740,84 @@ impl crate::Store {
#[cfg(test)]
let queried = crate::fault::tick(queried);
let mut rows = queried?;
let mut out = Vec::new();
while let Some(row) = rows.next()? {
out.push(SymbolMatch {
id: row.get(0)?,
kind: row.get(1)?,
module_path: row.get(2)?,
qual_name: row.get(3)?,
file: row.get(4)?,
line: row.get(5)?,
});
}
Ok(out)
collect_rows(&mut rows, |row| {
symbol_match_row(row, row.get::<_, i64>(0)?)
})
}
/// A method addressed as `<module>::<name>`, with the module part
/// starting at any `::` boundary of the method's file module path.
/// The caller runs this only when the exact spellings answer nothing,
/// so a query the base answers keeps exactly its rows.
fn symbols_matching_method(&self, query: &str) -> Result<Vec<SymbolMatch>, StoreError> {
let qualified = query.strip_prefix("crate::").unwrap_or(query);
let Some((module, name)) = qualified.rsplit_once("::") else {
return Ok(Vec::new());
};
let mut statement = self.conn.prepare(
"SELECT s.id, s.kind, COALESCE(m.path, ''), s.qual_name, f.path, s.start_line
FROM symbols s
JOIN files f ON f.id = s.file_id
LEFT JOIN modules m ON m.id = s.module_id
WHERE s.owner IS NOT NULL AND s.name = ?2
AND EXISTS (
SELECT 1 FROM modules gm
WHERE gm.file_id = s.file_id AND gm.scope = ''
AND (
gm.path = ?1
OR (
length(gm.path) > length(?1) + 2
AND substr(gm.path, -length(?1) - 2) = '::' || ?1
)
)
)
ORDER BY s.qual_name, f.path, s.id",
)?;
let queried = statement.query([module, name]);
#[cfg(test)]
let queried = crate::fault::tick(queried);
let mut rows = queried?;
collect_rows(&mut rows, |row| {
symbol_match_row(row, row.get::<_, i64>(0)?)
})
}
/// Every stored symbol named exactly `name`, items and methods alike,
/// ordered by file, line, id: the rows `find` answers with. Unlike
/// `read_items`, this carries methods, which have no item row.
pub fn symbols_named(&self, name: &str) -> Result<Vec<FindRow>, StoreError> {
let mut statement = self.conn.prepare(
"SELECT s.id, s.name, s.kind, s.visibility, f.path, s.start_line
FROM symbols s JOIN files f ON f.id = s.file_id
WHERE s.name = ?1
ORDER BY f.path, s.start_line, s.id",
)?;
let queried = statement.query([name]);
#[cfg(test)]
let queried = crate::fault::tick(queried);
let mut rows = queried?;
collect_rows(&mut rows, |row| find_row(row, row.get::<_, i64>(0)?))
}
/// Up to ten symbols whose bare name equals the last `::` segment of
/// `query`, ordered as [`symbols_matching`](Self::symbols_matching)
/// orders its rows: the candidates a `not_found` reply offers.
pub fn did_you_mean(&self, query: &str) -> Result<Vec<SymbolMatch>, StoreError> {
let last = query.rsplit("::").next().unwrap_or(query);
let mut statement = self.conn.prepare(
"SELECT s.id, s.kind, COALESCE(m.path, ''), s.qual_name, f.path, s.start_line
FROM symbols s
JOIN files f ON f.id = s.file_id
LEFT JOIN modules m ON m.id = s.module_id
WHERE s.name = ?1
ORDER BY s.qual_name, f.path, s.id
LIMIT 10",
)?;
let queried = statement.query([last]);
#[cfg(test)]
let queried = crate::fault::tick(queried);
let mut rows = queried?;
collect_rows(&mut rows, |row| {
symbol_match_row(row, row.get::<_, i64>(0)?)
})
}

/// Every edge addressed to the symbol `id`, as the caller's row id,
/// the caller's file, the call-site line, the confidence, and the
/// reason.
Expand Down
Loading
Loading