use parking_lot::RwLock;
/// MCP tool handler methods and their input parameter structs.
///
/// Each handler follows the pattern:
/// 1. Acquire read lock (or write lock for `index_folder`)
/// 2. Check loading guard (except `health` which always responds)
/// 3. Extract needed data into owned values
/// 4. Drop lock
/// 5. Call `format::` function
/// 6. Return `String`
///
/// Anti-patterns avoided (per RESEARCH.md):
/// - Never return JSON — always plain text String (AD-6)
/// - Never use MCP error codes for not-found — return helpful text via format functions
/// - Never hold RwLockReadGuard across await points — extract into owned values first
use std::collections::{HashMap, HashSet};
use std::io::Read;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::sync::atomic::Ordering;
use std::time::{Duration, Instant};
use axum::http::StatusCode;
use rmcp::handler::server::wrapper::Parameters;
use rmcp::{tool, tool_router};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use crate::capability::{
CapabilityCost, CapabilityEvidence, CapabilityFreshness, CapabilityName, CapabilitySafety,
CapabilityStatus, CouplingPreparePolicy, FrecencyCollectionPolicy, RankingDiagnosticsPolicy,
WorktreeRoutingPolicy,
};
use crate::protocol::result_status::{OutcomeClass, ResultStatus};
#[cfg(test)]
use super::edit_tools::{EditError, prepare_batch_paths_for_edit, prepare_exact_path_for_edit};
#[cfg(test)]
pub(crate) use super::read_tools::lenient_option_vec;
pub use super::read_tools::{
FindDependentsInput, GetFileContentInput, GetFileContextInput, GetRepoMapInput,
GetSymbolContextInput, GetSymbolInput, InspectMatchInput, SymbolTarget, SymforgeRetrieveInput,
TraceSymbolInput,
};
pub(crate) use super::read_tools::{
ValidateFileSyntaxInput, encode_include_tests_marker, file_content_options_from_input,
include_tests_from_sections, lenient_bool, lenient_bool_required, lenient_i64, lenient_u32,
lenient_u64, lenient_vec_required, normalize_file_content_aliases, visible_sections,
};
#[cfg(test)]
pub(crate) use super::search_tools::normalize_search_text_glob;
pub use super::search_tools::{
CurateKnowledgeInput, FindReferencesInput, ReviewKnowledgeInput, SearchFilesInput,
SearchKnowledgeInput, SearchSymbolsInput, SearchTextInput,
};
pub(crate) use super::search_tools::{
fix_common_double_escapes, normalize_path_prefix, parse_language_filter,
search_symbols_options_from_input, search_text_options_from_input,
};
const INDEX_FOLDER_RESET_ENV: &str = "SYMFORGE_INDEX_FOLDER_RESET";
pub(crate) fn index_folder_reset_requested() -> bool {
std::env::var(INDEX_FOLDER_RESET_ENV).as_deref() == Ok("1")
}
fn statused_tool_result(
text: String,
outcome_class: OutcomeClass,
) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
Ok(ResultStatus::new(outcome_class).into_call_tool_result(text))
}
/// Lexically normalize a path, resolving `.`/`..` segments WITHOUT touching the
/// filesystem (so a not-yet-existing within-project filter path can still be
/// checked for `..` escapes). Absolute prefixes and the path root are preserved.
fn normalize_lexically(path: &Path) -> PathBuf {
use std::path::Component;
let mut out = PathBuf::new();
for component in path.components() {
match component {
Component::ParentDir => {
// Pop a normal segment if there is one; never pop past the root
// or a prefix (drive/UNC) component.
if matches!(out.components().next_back(), Some(Component::Normal(_))) {
out.pop();
} else {
out.push("..");
}
}
Component::CurDir => {}
other => out.push(other.as_os_str()),
}
}
out
}
/// Whether `path` (a `symforge` `path:` filter) resolves WITHIN the bound
/// project `root` (012 D6 / contracts §3c). `path:` is a within-project filter,
/// never a project selector, so a path that escapes the bound root is a caller
/// error.
///
/// Resolution: a relative `path` is joined onto `root`; an absolute `path` is
/// used as-is. Both the resolved target and the root are canonicalized when they
/// exist on disk (resolving symlinks/`..`); when the target does not exist yet,
/// we fall back to a lexical normalization so a `../../escape` filter is still
/// rejected. Containment is the canonical/normalized-root being a prefix of the
/// canonical/normalized target (equal counts as within).
fn path_is_within_bound_project(path: &str, root: &Path) -> bool {
let canonical_root = root.canonicalize().unwrap_or_else(|_| root.to_path_buf());
let raw = Path::new(path);
let resolved = if raw.is_absolute() {
raw.to_path_buf()
} else {
canonical_root.join(raw)
};
let resolved = resolved
.canonicalize()
.unwrap_or_else(|_| normalize_lexically(&resolved));
// Compare with the Windows verbatim (`\\?\`) prefix stripped from BOTH sides
// so a canonicalized root (which gains `\\?\`) and a lexically-normalized
// not-yet-existing target (which does not) still compare correctly.
let resolved_cmp = strip_verbatim_prefix(&resolved);
let root_cmp = strip_verbatim_prefix(&canonical_root);
resolved_cmp.starts_with(&root_cmp)
}
/// Strip the Windows verbatim/UNC `\\?\` prefix from a path for comparison,
/// returning a plain comparable `PathBuf`. On a path without the prefix (or on
/// non-Windows) this is an allocation-light passthrough.
///
/// We rebuild the path from its components: a `Prefix` component that is verbatim
/// (`\\?\C:`, `\\?\UNC\...`) is replaced by its plain disk/UNC form so it lines
/// up with a non-canonicalized (lexically normalized) sibling path.
fn strip_verbatim_prefix(path: &Path) -> PathBuf {
use std::path::{Component, Prefix};
let mut out = PathBuf::new();
for component in path.components() {
match component {
Component::Prefix(prefix) => match prefix.kind() {
Prefix::VerbatimDisk(disk) => {
out.push(format!("{}:\\", disk as char));
}
Prefix::VerbatimUNC(server, share) => {
let mut unc = std::ffi::OsString::from(r"\\");
unc.push(server);
unc.push(r"\");
unc.push(share);
out.push(unc);
}
_ => out.push(component.as_os_str()),
},
Component::RootDir => {
// Disk prefixes above already include the root separator; only
// push a bare root when there is no preceding prefix.
if out.as_os_str().is_empty() {
out.push(component.as_os_str());
}
}
other => out.push(other.as_os_str()),
}
}
out
}
pub(super) fn is_index_unavailable_output(text: &str) -> bool {
text.starts_with("Index not loaded.")
|| text.starts_with("Index is loading")
|| text.starts_with("Index degraded:")
}
/// The ONE error-shape predicate for the whole protocol surface, read/write
/// alike. `edit_tools.rs` used to keep a private copy of this function, which
/// diverged the moment the project-refusal shapes were added here — so the seven
/// structural edit tools reported a REFUSED edit as `success`/`found`. Shared
/// (`pub(super)`) so a new shape can only ever be taught once.
pub(super) fn is_error_output(text: &str) -> bool {
text.starts_with("Error:")
|| text.starts_with("Error in ")
|| is_admission_refusal(text)
|| is_foreign_project_refusal(text)
|| is_local_cross_project_refusal(text)
}
/// An admission-gate refusal is an honest REFUSAL, not a successful read. Taught
/// HERE rather than per-arm: `validate_file_syntax` has no classifier arm of its
/// own, so its refusal fell through `classify_compact_tool_output`'s catch-all
/// and reported a withheld file as a successful validation. Anchored at position
/// 0 (not `contains`) so a body that merely QUOTES the phrase stays `Found`.
/// Both refusal variants share this opening clause, so one anchor classifies
/// both.
fn is_admission_refusal(text: &str) -> bool {
text.starts_with("Content withheld by admission policy:")
}
/// The single-project refusal [`SymForgeServer::foreign_project_refusal`] emits
/// carries no `Error:` prefix, so without this a refusal that came back through
/// DISPATCH rather than an early return classified as a SUCCESSFUL answer
/// (`found`) — notably in `classify_symforge_edit_outcome` and in every
/// `classify_edit_output` caller. Deliberately narrow: BOTH anchors must match,
/// so no unrelated body is reclassified.
fn is_foreign_project_refusal(text: &str) -> bool {
text.starts_with("project '") && text.contains("is not available on this connection")
}
/// Sibling shape emitted by [`SymForgeServer::local_cross_project_refusal`] for
/// a genuinely cross-project (`projects`, `*`, or foreign `project`) read on a
/// transport with no daemon working set. Same defect as above and same fix: an
/// honest refusal must not be reported as a successful answer. Narrow by
/// anchoring the FULL opening clause at position 0: a rendered search hit or doc
/// line that quotes the message is prefixed (`7: // ...`) and stays `Found`.
fn is_local_cross_project_refusal(text: &str) -> bool {
text.starts_with("Cross-project queries (project/projects) require the daemon")
}
fn classify_get_symbol_output(text: &str) -> OutcomeClass {
if is_index_unavailable_output(text) {
OutcomeClass::InternalFailure
} else if is_error_output(text) {
OutcomeClass::InvalidRequest
} else if text.starts_with("Ambiguous:") {
OutcomeClass::Ambiguous
} else if text.starts_with("File not found:") || text.starts_with("No symbol ") {
OutcomeClass::NotFound
} else {
OutcomeClass::Found
}
}
fn classify_get_symbol_context_output(text: &str) -> OutcomeClass {
if is_index_unavailable_output(text) {
OutcomeClass::InternalFailure
} else if is_error_output(text) {
OutcomeClass::InvalidRequest
} else if text.starts_with("Ambiguous symbol selector") || text.starts_with("Ambiguous:") {
OutcomeClass::Ambiguous
} else if text.starts_with("Symbol \"") || text.starts_with("Symbol '") {
OutcomeClass::NotFound
} else {
OutcomeClass::Found
}
}
/// Strip an optional leading `── mode: <name> (explicit) ──\n` annotation so
/// output classification can match the renderer's message at the start of the
/// remaining body. Returns `text` unchanged when no annotation is present.
fn strip_mode_annotation(text: &str) -> &str {
text.strip_prefix("── mode: ")
.and_then(|rest| rest.split_once(" ──\n"))
.map(|(_, body)| body)
.unwrap_or(text)
}
fn classify_get_file_content_output(text: &str) -> OutcomeClass {
// Strip an optional `── mode: <name> (explicit) ──` prefix so the renderer's
// status message is matched at the start of `body` even when an explicit-mode
// annotation precedes it. Anchoring on `body` (not a bare `contains`) keeps a
// successful read whose CONTENT merely mentions these phrases classified Found.
let body = strip_mode_annotation(text);
if is_index_unavailable_output(text) {
OutcomeClass::InternalFailure
} else if is_error_output(text)
|| text.starts_with("Invalid get_file_content request:")
|| text.starts_with("mode=")
|| text.contains("[error:")
|| (body.starts_with("Chunk ") && body.contains(" out of range for "))
{
// A request for a non-existent chunk index is an invalid request, not a
// successful read: the path exists but the requested page does not.
OutcomeClass::InvalidRequest
} else if text.starts_with("Ambiguous symbol selector") {
OutcomeClass::Ambiguous
} else if text.starts_with("File not found:")
|| text.starts_with("No symbol ")
|| text.starts_with("Symbol not found in ")
|| body.starts_with("No matches for '")
|| body.starts_with("Match occurrence ")
{
// around_match / match-occurrence misses: the needle was not found in the
// file. These must report NotFound, not a successful read.
OutcomeClass::NotFound
} else {
OutcomeClass::Found
}
}
fn classify_search_symbols_output(text: &str) -> OutcomeClass {
if is_index_unavailable_output(text) {
OutcomeClass::InternalFailure
} else if is_error_output(text) || text.starts_with("search_symbols requires") {
OutcomeClass::InvalidRequest
} else if text.starts_with("No symbols matching") {
OutcomeClass::EmptyResult
} else {
OutcomeClass::Found
}
}
fn classify_search_text_output(text: &str) -> OutcomeClass {
if is_index_unavailable_output(text) {
OutcomeClass::InternalFailure
} else if is_error_output(text)
|| text.starts_with("Regex search requires")
|| text.starts_with("Search requires")
|| text.starts_with("Invalid regex")
|| text.starts_with("Invalid glob")
|| text.starts_with("whole_word is not supported")
{
OutcomeClass::InvalidRequest
} else if text.starts_with("No matches") || text.starts_with("No AST matches") {
OutcomeClass::EmptyResult
} else {
OutcomeClass::Found
}
}
fn classify_search_knowledge_output(text: &str) -> OutcomeClass {
if text.starts_with("Error:") {
OutcomeClass::InvalidRequest
} else if text.contains("\nNo match:") {
OutcomeClass::EmptyResult
} else if text.starts_with("Readiness:") {
OutcomeClass::InternalFailure
} else {
OutcomeClass::Found
}
}
fn classify_search_files_output(text: &str) -> OutcomeClass {
if is_index_unavailable_output(text) {
OutcomeClass::InternalFailure
} else if is_error_output(text)
|| text.starts_with("Path search requires")
|| text.starts_with("Path hint must not be empty")
|| text.starts_with("search_files")
{
OutcomeClass::InvalidRequest
} else if text.contains("Ambiguous path hint") {
OutcomeClass::Ambiguous
} else if text.starts_with("No indexed source files matching")
|| text.starts_with("No indexed source path matched")
|| text.starts_with("No git history found")
|| text.starts_with("'") && text.contains("not found in git history")
{
OutcomeClass::NotFound
} else if text.starts_with("No high-confidence co-change data") {
OutcomeClass::EmptyResult
} else {
OutcomeClass::Found
}
}
fn classify_find_references_output(text: &str) -> OutcomeClass {
if is_index_unavailable_output(text) {
OutcomeClass::InternalFailure
} else if is_error_output(text) {
OutcomeClass::InvalidRequest
} else if text.starts_with("Ambiguous symbol selector") {
OutcomeClass::Ambiguous
} else if text.starts_with("File not found:")
|| text.starts_with("Symbol not found")
|| text.contains("this symbol is not defined in the indexed project")
{
OutcomeClass::NotFound
} else if text.starts_with("No references found")
|| text.starts_with("No implementations found")
{
OutcomeClass::EmptyResult
} else {
OutcomeClass::Found
}
}
fn classify_get_file_context_output(text: &str) -> OutcomeClass {
if is_index_unavailable_output(text) {
OutcomeClass::InternalFailure
} else if is_error_output(text) || text.starts_with("Invalid get_file_context") {
OutcomeClass::InvalidRequest
} else if text.starts_with("File not found:")
|| text.starts_with("File not found on disk:")
|| text.starts_with("No symbol ")
{
OutcomeClass::NotFound
} else if text.starts_with("Ambiguous") {
OutcomeClass::Ambiguous
} else {
OutcomeClass::Found
}
}
/// Classify compact-surface legacy tool output for STEL chain admission and replay validation.
pub(crate) fn classify_compact_tool_output(tool: &str, text: &str) -> OutcomeClass {
match tool {
"get_symbol" => classify_get_symbol_output(text),
"get_symbol_context" => classify_get_symbol_context_output(text),
"get_file_content" => classify_get_file_content_output(text),
"get_file_context" => classify_get_file_context_output(text),
"search_symbols" => classify_search_symbols_output(text),
"search_text" => classify_search_text_output(text),
"search_knowledge" => classify_search_knowledge_output(text),
"search_files" => classify_search_files_output(text),
"find_references" => classify_find_references_output(text),
_ => {
if is_index_unavailable_output(text) {
OutcomeClass::InternalFailure
} else if is_error_output(text) || text.starts_with("Invalid") {
OutcomeClass::InvalidRequest
} else {
OutcomeClass::Found
}
}
}
}
/// Whether a legacy tool body represents successful serve output for STEL chain continuation.
pub(crate) fn compact_tool_output_is_success(tool: &str, text: &str) -> bool {
classify_compact_tool_output(tool, text) == OutcomeClass::Found
}
/// Deserialize a required `u32` from either a JSON number or a stringified number.
use crate::domain::index::{AdmissionTier, BINARY_SNIFF_BYTES, SkipReason};
use crate::domain::{FileClassification, LanguageId, ReferenceKind};
use crate::live_index::qualified_usages::{self, QualifiedUsage};
use crate::live_index::{
FindReferencesView, IndexedFile, ReferenceContextLineView, ReferenceFileView, ReferenceHitView,
SearchFilesCouplingEvidence, SearchFilesCouplingNeighbors, SearchFilesHit,
SearchFilesResolveView, SearchFilesTier, SearchFilesView, search,
store::{IndexState, LiveIndex},
};
use crate::protocol::edit;
use crate::protocol::format;
use crate::protocol::read_gate;
use crate::protocol::search_format;
use crate::sidecar::handlers::{
ImpactParams, OutlineParams, SymbolContextParams, impact_tool_text,
outline_tool_text_for_generation, repo_map_text_for_generation,
symbol_context_tool_text_for_generation,
};
use crate::sidecar::{SidecarState, TokenStats};
use crate::watcher;
use super::SymForgeServer;
// ─── Input parameter structs ────────────────────────────────────────────────
/// Input for `index_folder`.
#[derive(Deserialize, Serialize, JsonSchema)]
pub struct IndexFolderInput {
/// Absolute or relative path to the directory to index.
pub path: String,
/// Optional key used to replay an identical `index_folder` request safely.
#[serde(default)]
pub idempotency_key: Option<String>,
/// Feature 012 (Phase 2): when true, OPEN this folder ADDITIVELY in the
/// current session's working set instead of retargeting. The session keeps
/// its existing active project AND gains this one, enabling cross-project
/// reads (`project`/`projects` on `search_symbols`/`search_text`/
/// `find_references`). Default/omitted = the existing retarget behavior
/// (FR-006, byte-identical). Multi-project requires the daemon; on stdio/embed
/// (no daemon) an `add:true` call honestly refuses (Principle VII).
#[serde(default, deserialize_with = "lenient_bool")]
pub add: Option<bool>,
/// Direct, per-request authority to index the exact protected root in
/// read/index-only mode. Never inherited by automatic root discovery.
#[serde(default, deserialize_with = "lenient_bool")]
pub allow_protected_root: Option<bool>,
}
/// Input for `checkpoint_now`.
#[derive(Default, Deserialize, Serialize, JsonSchema)]
pub struct CheckpointNowInput {
/// When true, deserialize the snapshot after writing and fail the command if it cannot be read back.
#[serde(default, deserialize_with = "lenient_bool")]
pub verify_after_write: Option<bool>,
/// When true, additionally export the Best-tier team artifact
/// (`.symforge/index.bin.zst` + `artifact.json`, plus a `.gitattributes`
/// `*.zst merge=ours` hint) alongside the plain snapshot. See
/// contracts/team-artifact.md § Tiers.
#[serde(default, deserialize_with = "lenient_bool")]
pub export_artifact: Option<bool>,
}
/// Input for `health`.
///
/// SF-STRESS-010: the parse/span quarantine registry was hard-capped at 10
/// entries with no retrieval surface, so the full list of partial/failed files
/// was unreachable without thousands of per-file calls. These optional paging
/// parameters page the ranked registry; entries are ranked real-source-first so
/// genuine repo-owned losses surface before vendored/fixture noise. Omitting
/// both preserves the historical default (offset 0, limit 10).
#[derive(Default, Deserialize, Serialize, JsonSchema)]
pub struct HealthInput {
/// Maximum quarantine registry entries to render (default 10, capped at
/// 1000). Raise to retrieve more of the full partial/failed file list.
#[serde(default, deserialize_with = "lenient_u32")]
pub quarantine_limit: Option<u32>,
/// Offset into the ranked quarantine registry for paging (default 0).
#[serde(default, deserialize_with = "lenient_u32")]
pub quarantine_offset: Option<u32>,
}
impl HealthInput {
fn quarantine_limit(&self) -> Option<usize> {
self.quarantine_limit.map(|n| n as usize)
}
fn quarantine_offset(&self) -> Option<usize> {
self.quarantine_offset.map(|n| n as usize)
}
}
/// Input for `what_changed`.
#[derive(Deserialize, Serialize, JsonSchema)]
pub struct WhatChangedInput {
/// Optional explicit project selector (daemon sessions with multiple open
/// projects): an open project ID or unique project name. Omit for the
/// session's home project. Local/embedded servers are bound to one project
/// and refuse a non-matching selector.
#[serde(default)]
pub project: Option<String>,
/// Optional Unix timestamp (seconds since epoch). Files newer than this are returned.
#[serde(default, deserialize_with = "lenient_i64")]
pub since: Option<i64>,
/// Optional git ref to diff against, for example `HEAD~5` or `branch:main`.
pub git_ref: Option<String>,
/// When true, report uncommitted git changes. Defaults to true when no other mode is specified and a repo root exists.
#[serde(default, deserialize_with = "lenient_bool")]
pub uncommitted: Option<bool>,
/// Optional relative path prefix scope, for example `src/` or `src/protocol`.
pub path_prefix: Option<String>,
/// Optional canonical language name such as `Rust`, `TypeScript`, `C#`, or `C++`.
pub language: Option<String>,
/// When true, exclude non-source files (docs, configs, images, lock files).
/// Only files with a recognized programming language extension are included.
#[serde(default, deserialize_with = "lenient_bool")]
pub code_only: Option<bool>,
/// When true, also include a symbol-level diff alongside the file list.
/// Only applies in git_ref and uncommitted modes (not timestamp mode).
/// In git_ref mode, diffs the given ref against HEAD.
/// In uncommitted mode, diffs HEAD against the working tree.
#[serde(default, deserialize_with = "lenient_bool")]
pub include_symbol_diff: Option<bool>,
/// When true, return an approximate token cost estimate instead of actual content.
#[serde(default, deserialize_with = "lenient_bool")]
pub estimate: Option<bool>,
/// Optional maximum token budget for the response.
#[serde(default, deserialize_with = "lenient_u64")]
pub max_tokens: Option<u64>,
}
/// Blast-radius granularity for `detect_impact`
/// (contracts/detect-impact.md, frozen 2026-06-30).
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Deserialize, Serialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum ImpactScope {
Files,
#[default]
Symbols,
}
/// `depth` defaults to 2 via this function — **not** `u8::default()` (0),
/// since depth 0 yields an empty blast radius (a silent no-op impact query).
/// contracts/detect-impact.md § Input.
fn default_impact_depth() -> u8 {
2
}
fn default_include_untracked() -> bool {
true
}
/// Maximum depth accepted before `detect_impact` clamps + warns
/// (contracts/detect-impact.md § Risk tiers / error catalog: "depth capped").
const DETECT_IMPACT_MAX_DEPTH: u8 = 5;
/// ponytail: fixed safety cap on EACH list (`changed_files`, `changed_symbols`,
/// `blast_radius`) returned per call — the bound that stops the 54 MB / 291K-symbol
/// dump seen on a large repo. The frozen contract's `pagination` envelope has no
/// `offset`/`limit` input field to page past it — add one if a real need for
/// deeper paging shows up. `risk_summary` is always counted over the full set.
const DETECT_IMPACT_MAX_RETURNED: usize = 200;
/// Input for `detect_impact` (contracts/detect-impact.md, frozen 2026-06-30).
#[derive(Deserialize, Serialize, JsonSchema)]
pub struct DetectImpactInput {
/// Base branch/ref to diff against HEAD when `since` is not set. Defaults
/// to `main` when neither `base_branch` nor `since` is set
/// (contracts/detect-impact.md § Input); on a repo whose default branch is
/// not `main`, pass this (or `since`) explicitly — an absent `main` surfaces
/// an "Invalid git ref" error. Uncommitted working-tree changes are always
/// merged in per `include_untracked`.
pub base_branch: Option<String>,
/// Git ref to diff against HEAD; overrides `base_branch` when set. Pass
/// the literal value `WORKTREE` to diff tracked working-tree changes
/// (staged + unstaged) against HEAD instead of another ref.
pub since: Option<String>,
/// Blast-radius hop depth (default 2). Values above 5 are clamped to 5
/// with a warning footer.
#[serde(default = "default_impact_depth")]
pub depth: u8,
/// Blast-radius granularity: `files` or `symbols` (default `symbols`).
#[serde(default)]
pub scope: ImpactScope,
/// Merge uncommitted (staged + unstaged + untracked) changes into the
/// changed-file set (default true).
#[serde(
default = "default_include_untracked",
deserialize_with = "lenient_bool_required"
)]
pub include_untracked: bool,
/// Include non-source data files (e.g. JSON/YAML/TOML) in the changed-set
/// that seeds the blast radius. Default false (018 US1 / FR-001): the
/// impact walk is source-focused so untracked data files and their
/// key-symbols don't dominate. Set true to restore full inclusion.
#[serde(default, deserialize_with = "lenient_bool")]
pub include_data: Option<bool>,
}
/// Input for `analyze_file_impact`.
#[derive(Deserialize, Serialize, JsonSchema)]
pub struct AnalyzeFileImpactInput {
/// Optional explicit project selector (daemon sessions with multiple open
/// projects): an open project ID or unique project name. Omit for the
/// session's home project. Local/embedded servers are bound to one project
/// and refuse a non-matching selector.
#[serde(default)]
pub project: Option<String>,
/// Relative path to the file to re-read from disk.
pub path: String,
/// When true, treat the file as newly created and index it.
#[serde(default, deserialize_with = "lenient_bool")]
pub new_file: Option<bool>,
/// When true, also include git temporal co-change data (files that historically change together with this file).
#[serde(default, deserialize_with = "lenient_bool")]
pub include_co_changes: Option<bool>,
/// Maximum co-changing files to return (default 10). Only used when include_co_changes=true.
#[serde(default, deserialize_with = "lenient_u32")]
pub co_changes_limit: Option<u32>,
/// When true, return an approximate token cost estimate instead of actual content.
#[serde(default, deserialize_with = "lenient_bool")]
pub estimate: Option<bool>,
}
/// Input for `explore`.
#[derive(Deserialize, Serialize, JsonSchema, Default)]
pub struct ExploreInput {
/// Optional explicit project selector (daemon sessions with multiple open
/// projects): an open project ID or unique project name. Omit for the
/// session's home project. Local/embedded servers are bound to one project
/// and refuse a non-matching selector.
#[serde(default)]
pub project: Option<String>,
/// Natural-language concept or topic to explore (e.g., "error handling", "concurrency", "database").
pub query: String,
/// Maximum number of results per category (default 10).
#[serde(default, deserialize_with = "lenient_u32")]
pub limit: Option<u32>,
/// Exploration depth: 1 (default) = symbol names + text patterns + files.
/// 2 = adds signatures and one hop of dependents for top symbols.
/// 3 = adds call chains and type dependency edges for top symbols.
#[serde(default, deserialize_with = "lenient_u32")]
pub depth: Option<u32>,
/// When true, include results from vendor, generated, and gitignored files.
/// By default these are hidden to reduce noise (default false).
#[serde(default, deserialize_with = "lenient_bool")]
pub include_noise: Option<bool>,
/// When true, surface vendored/third-party paths (additive with `include_noise`).
/// Default false.
#[serde(default, deserialize_with = "lenient_bool")]
pub include_vendor: Option<bool>,
/// When true, surface personal tooling paths (.claude/gsd-*; additive with `include_noise`).
/// Default false.
#[serde(default, deserialize_with = "lenient_bool")]
pub include_personal_tooling: Option<bool>,
/// Optional canonical language name filter (e.g., "Rust", "TypeScript", "C#").
pub language: Option<String>,
/// Optional relative path prefix scope (e.g., "src/", "backend/").
pub path_prefix: Option<String>,
/// When true, return an approximate token cost estimate instead of actual content.
#[serde(default, deserialize_with = "lenient_bool")]
pub estimate: Option<bool>,
/// Optional maximum token budget for the response.
#[serde(default, deserialize_with = "lenient_u64")]
pub max_tokens: Option<u64>,
}
#[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
pub struct SmartQueryInput {
/// Optional explicit project selector (daemon sessions with multiple open
/// projects): an open project ID or unique project name. Omit for the
/// session's home project. Local/embedded servers are bound to one project
/// and refuse a non-matching selector.
#[serde(default)]
pub project: Option<String>,
/// Natural language question about the codebase. Examples:
/// "who calls optimize_deterministic", "where is LiveIndex defined",
/// "how does the parser work", "what changed", "find file tools.rs"
pub query: String,
/// Optional maximum token budget for the response.
#[serde(default, deserialize_with = "lenient_u64")]
pub max_tokens: Option<u64>,
}
#[derive(Debug, serde::Deserialize, serde::Serialize, schemars::JsonSchema)]
pub struct EditPlanInput {
/// Optional explicit project selector (daemon sessions with multiple open
/// projects): an open project ID or unique project name. Omit for the
/// session's home project. Local/embedded servers are bound to one project
/// and refuse a non-matching selector.
#[serde(default)]
pub project: Option<String>,
/// The symbol name or file path you want to edit.
pub target: String,
}
#[derive(Debug, serde::Deserialize, serde::Serialize, schemars::JsonSchema)]
pub struct InvestigationInput {
/// Optional explicit project selector (daemon sessions with multiple open
/// projects): an open project ID or unique project name. Omit for the
/// session's home project. Local/embedded servers are bound to one project
/// and refuse a non-matching selector.
#[serde(default)]
pub project: Option<String>,
/// Optional focus area to filter suggestions.
pub focus: Option<String>,
}
/// Input for `diff_symbols`.
#[derive(Deserialize, Serialize, JsonSchema)]
pub struct DiffSymbolsInput {
/// Optional explicit project selector (daemon sessions with multiple open
/// projects): an open project ID or unique project name. Omit for the
/// session's home project. Local/embedded servers are bound to one project
/// and refuse a non-matching selector.
#[serde(default)]
pub project: Option<String>,
/// Base git ref to compare from (default: "main").
pub base: Option<String>,
/// Target git ref to compare to (default: "HEAD").
pub target: Option<String>,
/// Optional path filter — only show diffs for files matching this prefix.
pub path_prefix: Option<String>,
/// Optional canonical language name such as `Rust`, `TypeScript`, `C#`, or `C++`.
pub language: Option<String>,
/// When true, exclude non-source files (docs, configs, images, lock files).
/// Only files with a recognized programming language extension are included.
#[serde(default, deserialize_with = "lenient_bool")]
pub code_only: Option<bool>,
/// When true, show only per-file summary counts (+N added, -N removed, ~N modified)
/// without listing individual symbols. Like `git diff --stat` vs `git diff`.
#[serde(default, deserialize_with = "lenient_bool")]
pub compact: Option<bool>,
/// When true, emit only the aggregate summary line (total added/removed/modified
/// counts) without any per-file detail. Useful for quick change-scope assessment.
#[serde(default, deserialize_with = "lenient_bool")]
pub summary_only: Option<bool>,
/// When true, return an approximate token cost estimate instead of actual content.
#[serde(default, deserialize_with = "lenient_bool")]
pub estimate: Option<bool>,
/// Optional maximum token budget for the response.
#[serde(default, deserialize_with = "lenient_u64")]
pub max_tokens: Option<u64>,
}
enum WhatChangedMode {
Timestamp(i64),
GitRef(String),
Uncommitted,
}
#[derive(Default)]
struct ExploreMatchScore {
raw_count: usize,
matched_terms: HashSet<String>,
}
#[derive(Default)]
struct ExploreFileSignal {
raw_score: u64,
matched_terms: HashSet<String>,
}
struct DerivedExploreCluster {
seed_terms: Vec<String>,
promoted_symbols: Vec<String>,
seed_files: Vec<String>,
}
fn determine_what_changed_mode(
input: &WhatChangedInput,
has_repo_root: bool,
) -> Result<WhatChangedMode, String> {
if let Some(git_ref) = input
.git_ref
.as_deref()
.map(str::trim)
.filter(|git_ref| !git_ref.is_empty())
{
return if has_repo_root {
Ok(WhatChangedMode::GitRef(
git_ref
.strip_prefix("branch:")
.unwrap_or(git_ref)
.to_string(),
))
} else {
Err("Git change detection unavailable; pass `since` for timestamp mode.".to_string())
};
}
if input.uncommitted.unwrap_or(false) || (input.since.is_none() && has_repo_root) {
return if has_repo_root {
Ok(WhatChangedMode::Uncommitted)
} else {
Err("Git change detection unavailable; pass `since` for timestamp mode.".to_string())
};
}
if let Some(since) = input.since {
Ok(WhatChangedMode::Timestamp(since))
} else {
Err(
"what_changed requires either `since`, `git_ref`, or an available repo root."
.to_string(),
)
}
}
fn filter_paths_by_prefix_and_language(
paths: Vec<String>,
path_prefix: Option<&str>,
language: Option<&str>,
code_only: bool,
) -> Result<Vec<String>, String> {
let lang_filter = parse_language_filter(language)?;
let prefix = path_prefix
.map(str::trim)
.filter(|p| !p.is_empty())
.map(|p| {
p.replace('\\', "/")
.trim_start_matches("./")
.trim_start_matches('/')
.trim_end_matches('/')
.to_string()
});
Ok(paths
.into_iter()
.filter(|path| {
if let Some(ref pfx) = prefix
&& !path.starts_with(pfx.as_str())
{
return false;
}
if let Some(ref lang) = lang_filter {
let ext = path.rsplit('.').next().unwrap_or("");
if crate::domain::index::LanguageId::from_extension(ext).as_ref() != Some(lang) {
return false;
}
}
if code_only && lang_filter.is_none() {
let ext = path.rsplit('.').next().unwrap_or("");
match crate::domain::index::LanguageId::from_extension(ext) {
// Recovered finding #3: an unknown extension is not proof of
// "data" — SQL, shell, PowerShell, Proto, Terraform,
// Dockerfile, Makefile are legitimate source SymForge just
// cannot parse. Keep them under code_only.
None => return is_unparsed_source_path(path),
Some(lang) => {
if crate::parsing::config_extractors::is_config_language(&lang) {
return false;
}
}
}
}
true
})
.collect())
}
/// Source formats with no `LanguageId` parser that are nonetheless
/// unambiguously source, not data — they must survive `code_only` filtering
/// (recovered finding #3). Deliberately small allowlist; extend as real
/// misclassifications surface.
fn is_unparsed_source_path(path: &str) -> bool {
let file_name = path.rsplit('/').next().unwrap_or(path);
let lower = file_name.to_ascii_lowercase();
if matches!(
lower.as_str(),
"dockerfile" | "makefile" | "gnumakefile" | "justfile"
) {
return true;
}
let Some((_, ext)) = lower.rsplit_once('.') else {
return false;
};
matches!(
ext,
"sql"
| "sh"
| "bash"
| "zsh"
| "ps1"
| "psm1"
| "psd1"
| "bat"
| "cmd"
| "proto"
| "tf"
| "tfvars"
| "cmake"
| "gradle"
| "dockerfile"
)
}
fn normalize_exact_path(input: &str) -> String {
let normalized = input
.trim()
.replace('\\', "/")
.trim_start_matches("./")
.trim_start_matches('/')
.trim_end_matches('/')
.to_string();
if normalized.is_empty() {
input.trim().to_string()
} else {
normalized
}
}
/// Find up to 5 similar file paths for "file not found" suggestions.
/// Extracts the basename from the failed path and searches the index.
fn suggest_similar_files(index: &crate::live_index::LiveIndex, path: &str) -> Vec<String> {
let basename = std::path::Path::new(path)
.file_name()
.and_then(|f| f.to_str())
.unwrap_or(path);
// Try basename match first
let mut suggestions: Vec<String> = index
.find_files_by_basename(basename)
.into_iter()
.take(5)
.map(|s| s.to_string())
.collect();
// If no basename match, try the stem (without extension)
if suggestions.is_empty() {
let stem = std::path::Path::new(path)
.file_stem()
.and_then(|f| f.to_str())
.unwrap_or(basename);
if stem.len() >= 3 {
let stem_lower = stem.to_ascii_lowercase();
suggestions = index
.all_files()
.map(|(p, _)| p.as_str())
.filter(|p| {
let file_stem = std::path::Path::new(p)
.file_stem()
.and_then(|s| s.to_str())
.unwrap_or("");
file_stem.to_ascii_lowercase().contains(&stem_lower)
})
.take(5)
.map(|s| s.to_string())
.collect();
}
}
suggestions
}
fn enrich_with_callers(
index: &crate::live_index::LiveIndex,
result: &mut search::TextSearchResult,
file_limit: usize,
) {
use std::collections::HashSet;
for file_matches in result.files.iter_mut().take(file_limit) {
// Collect unique enclosing symbol names from this file's matches
let mut symbol_names: HashSet<String> = HashSet::new();
for m in &file_matches.matches {
if let Some(ref enc) = m.enclosing_symbol {
symbol_names.insert(enc.name.clone());
}
}
if symbol_names.is_empty() {
continue;
}
let mut callers: Vec<search::CallerEntry> = Vec::new();
let mut seen: HashSet<(String, String)> = HashSet::new(); // (file, symbol) dedup
for sym_name in &symbol_names {
let refs = index.find_references_for_name(sym_name, None, false);
for (ref_file, ref_record) in refs {
// Get enclosing symbol of the reference
let enclosing_name = ref_record
.enclosing_symbol_index
.and_then(|idx| {
index
.get_file(ref_file)
.and_then(|f| f.symbols.get(idx as usize))
.map(|s| s.name.clone())
})
.unwrap_or_else(|| "(top-level)".to_string());
// Skip self-references only when the caller IS one of the matched
// symbols (same-file callers from different symbols are useful context)
if ref_file == file_matches.path && symbol_names.contains(&enclosing_name) {
continue;
}
let key = (ref_file.to_string(), enclosing_name.clone());
if seen.insert(key) {
callers.push(search::CallerEntry {
file: ref_file.to_string(),
symbol: enclosing_name,
line: ref_record.line_range.0 + 1, // 0-based to 1-based
});
}
}
}
// Cap at 10 callers to avoid noise
callers.truncate(10);
// Always set callers when follow_refs was requested — distinguishes
// "not requested" (None) from "ran but found nothing" (Some([]))
file_matches.callers = Some(callers);
}
}
fn freshen_exact_path_for_targeted_retrieval(
server: &SymForgeServer,
path_scope: &search::PathScope,
) -> bool {
let search::PathScope::Exact(relative_path) = path_scope else {
return false;
};
let expected_gen = server.index.current_project_generation();
let Some(repo_root) = server.capture_repo_root() else {
return false;
};
let Ok(abs_path) = safe_repo_path_for_freshen(&repo_root, relative_path) else {
return false;
};
match watcher::freshen_file_if_stale(relative_path, &abs_path, &server.index, expected_gen) {
watcher::FreshenResult::Fresh => false,
watcher::FreshenResult::StaleReindexed => true,
watcher::FreshenResult::StaleRemoved => true,
watcher::FreshenResult::GenerationMismatch => false,
}
}
pub(super) fn safe_repo_path_for_freshen(
repo_root: &std::path::Path,
relative_path: &str,
) -> Result<PathBuf, String> {
let relative = std::path::Path::new(relative_path);
if relative.is_absolute()
|| relative
.components()
.any(|component| matches!(component, std::path::Component::ParentDir))
{
return Err(format!("path '{relative_path}' is outside the repository"));
}
match edit::safe_repo_path(repo_root, relative_path) {
Ok(path) => Ok(path),
Err(_) => {
let canon_root = repo_root
.canonicalize()
.map_err(|e| format!("cannot resolve repo root: {e}"))?;
Ok(canon_root.join(relative))
}
}
}
fn search_scope_summary(
path_scope: &search::PathScope,
language_filter: Option<&LanguageId>,
noise_policy: &search::NoisePolicy,
include_personal_tooling: bool,
glob: Option<&str>,
exclude_glob: Option<&str>,
ranked: bool,
) -> String {
let mut parts = Vec::new();
match path_scope {
search::PathScope::Any => parts.push("repo-wide".to_string()),
search::PathScope::Exact(path) => parts.push(format!("path `{path}`")),
search::PathScope::Prefix(prefix) => parts.push(format!("path prefix `{prefix}`")),
}
if let Some(language) = language_filter {
parts.push(format!("language `{language}`"));
}
// SF-STRESS-011 honesty fix: these are HEURISTIC path-based filters, not a
// guaranteed outcome. Detection keys on path segments (vendor/, deps/,
// dist/, test_data/, ...) and basename patterns, so a vendored/generated
// file with an unconventional path can still appear in results. The header
// says "filter active (heuristic)" rather than asserting the file class was
// actually removed, which the previous "vendor filtered" wording overstated.
parts.push(if noise_policy.include_tests {
"tests included".to_string()
} else {
"tests filter active (heuristic)".to_string()
});
parts.push(if noise_policy.include_generated {
"generated included".to_string()
} else {
"generated filter active (heuristic)".to_string()
});
parts.push(if noise_policy.include_vendor {
"vendor included".to_string()
} else {
"vendor filter active (heuristic)".to_string()
});
parts.push(if include_personal_tooling {
"personal tooling included".to_string()
} else {
"personal tooling filtered".to_string()
});
if let Some(glob) = glob {
parts.push(format!("glob `{glob}`"));
}
if let Some(exclude_glob) = exclude_glob {
parts.push(format!("exclude `{exclude_glob}`"));
}
if ranked {
parts.push("ranked ordering enabled".to_string());
}
parts.join("; ")
}
fn search_parse_state_for_paths<'a, I>(index: &LiveIndex, paths: I) -> &'static str
where
I: IntoIterator<Item = &'a str>,
{
if paths
.into_iter()
.filter_map(|path| index.get_file(path))
.any(|file| file.parse_diagnostic.is_some())
{
"partial"
} else {
"parsed"
}
}
fn parse_state_for_file(file: &IndexedFile) -> &'static str {
match &file.parse_status {
crate::live_index::store::ParseStatus::Parsed => "parsed",
crate::live_index::store::ParseStatus::PartialParse { .. } => {
// SF-003: a partial parse caused only by the tree-sitter-typescript
// 0.23.2 import-type-array grammar limitation is valid TypeScript;
// report it as parsed rather than partial.
if crate::parsing::is_expected_typescript_import_type_array_limitation(
&file.language,
&file.content,
crate::domain::LanguageId::is_tsx_path(&file.relative_path),
) {
"parsed"
} else {
"partial"
}
}
crate::live_index::store::ParseStatus::Failed { .. } => "degraded",
}
}
fn context_source_authority_label(refreshed: bool) -> &'static str {
if refreshed {
"disk-refreshed"
} else {
"current index"
}
}
/// The source-authority axis of a result envelope, MEASURED from the index's own
/// freshness rather than asserted.
///
/// `format_search_envelope` collapses to the compact one-line `Trust:` banner
/// exactly when authority is `"current index"`, and its own doc says any
/// deviation must keep the loud six-line form so "degraded/stale/truncated
/// results stay loud". That contract was unreachable on the code-navigation
/// lane: every call site passed the literal `"current index"`, so a result could
/// never be anything but confident — including one served from an index whose
/// reconciliation against disk had failed or never run.
///
/// The rest of the envelope already works this way. The parse-state axis
/// deliberately degrades (`"metadata-only (not parsed)"`, "instead of the
/// misleading 'parsed'"), and the knowledge lane already gates its envelope on
/// `FreshnessStatus`. This applies the same discipline to code navigation, which
/// is the lane whose anchors an agent actually navigates by — a wrong line
/// number in the right file is worse than a miss, because it is actionable.
fn index_source_authority_label(freshness: &crate::domain::FreshnessStatus) -> &'static str {
match freshness {
crate::domain::FreshnessStatus::Current => "current index",
crate::domain::FreshnessStatus::Verifying => "index (verifying against disk)",
crate::domain::FreshnessStatus::Degraded { .. } => "index (UNVERIFIED against disk)",
}
}
fn context_bundle_completeness_label(
view: &crate::live_index::ContextBundleFoundView,
rendered: &str,
) -> String {
let section_overflow =
view.callers.overflow_count + view.callees.overflow_count + view.type_usages.overflow_count;
let mut parts = Vec::new();
if rendered.contains("Truncated at ~") {
parts.push("budget-limited".to_string());
}
if section_overflow > 0 {
parts.push(format!(
"section-capped ({} additional reference entries not shown)",
section_overflow
));
}
if parts.is_empty() {
"full".to_string()
} else {
parts.join("; ")
}
}
fn search_completeness_label(overflow_count: usize, suppressed_by_noise: usize) -> String {
// Honesty (trust): the index is built by a discovery walk with the `ignore`
// crate default `.hidden(true)`, so hidden / dotdir paths (`.github/`,
// `.gitlab-ci.yml`, …) are NOT indexed and never appear in results. A bare
// "full" claim would mislead an agent into trusting the file count as
// exhaustive (the dogfood report: `search_text` silently omitted
// `.github/workflows/release-please.yml` that ripgrep found). Qualify the
// claim so the agent knows to use a raw grep for hidden paths.
let mut parts = vec![if overflow_count > 0 {
format!("truncated by result cap ({overflow_count} more omitted)")
} else {
"full for indexed scope (hidden/dotdir paths not indexed — grep those)".to_string()
}];
if suppressed_by_noise > 0 {
if suppressed_by_noise > search::SUPPRESSED_TEXT_MATCH_DISPLAY_CAP {
parts.push(format!(
"{}+ noise-filtered match(es) suppressed",
search::SUPPRESSED_TEXT_MATCH_DISPLAY_CAP
));
} else {
parts.push(format!(
"{suppressed_by_noise} noise-filtered match(es) suppressed"
));
}
}
parts.join("; ")
}
fn search_text_match_type_label(
structural: bool,
is_regex: bool,
terms: Option<&[String]>,
auto_detected_regex: bool,
auto_corrected_regex: bool,
ranked: bool,
) -> String {
if structural {
"structural (ast-grep)".to_string()
} else if auto_corrected_regex {
"heuristic (auto-corrected regex)".to_string()
} else if is_regex && auto_detected_regex {
"heuristic (auto-detected regex)".to_string()
} else if is_regex {
"heuristic (regex)".to_string()
} else if ranked {
match terms {
Some(terms) if !terms.is_empty() => "heuristic (ranked OR-literal terms)".to_string(),
_ => "heuristic (ranked literal)".to_string(),
}
} else if matches!(terms, Some(terms) if !terms.is_empty()) {
"constrained (OR-literal terms)".to_string()
} else {
"constrained (literal)".to_string()
}
}
fn search_symbols_match_type_label(
result: &search::SymbolSearchResult,
is_browse: bool,
) -> &'static str {
if is_browse {
"constrained (scoped browse)"
} else {
match result.hits.first().map(|hit| hit.tier) {
Some(search::SymbolMatchTier::Exact) => "exact",
Some(search::SymbolMatchTier::Prefix) => "constrained (prefix tier)",
Some(search::SymbolMatchTier::Substring) => "heuristic (substring tier)",
None => "constrained",
}
}
}
fn search_files_match_type_label(view: &SearchFilesView) -> &'static str {
match view {
SearchFilesView::Found { hits, .. } => match hits.first().map(|hit| hit.tier) {
Some(SearchFilesTier::CoChange) => "heuristic (git-temporal coupling)",
Some(SearchFilesTier::StrongPath) | Some(SearchFilesTier::Basename) => {
"constrained (tiered path relevance)"
}
Some(SearchFilesTier::LoosePath) => "heuristic (loose path relevance)",
Some(SearchFilesTier::MetadataOnly) => "heuristic (Tier-2 metadata-only path)",
None => "constrained",
},
_ => "constrained",
}
}
const MAX_CO_CHANGE_PARTNERS_PER_ANCHOR: u32 = 20;
struct SearchFilesCoChangeResolution {
neighbors: Option<SearchFilesCouplingNeighbors>,
evidence: CapabilityEvidence,
}
fn cochange_ranking_evidence(
status: CapabilityStatus,
freshness: CapabilityFreshness,
cost: CapabilityCost,
detail: impl Into<String>,
) -> CapabilityEvidence {
CapabilityEvidence::new(CapabilityName::CoChangeRanking, status)
.with_freshness(freshness)
.with_cost(cost)
.with_safety(CapabilitySafety::ReadOnly)
.with_detail(detail)
}
/// Build the precise `FallbackUsed` co-change detail for the case where the
/// coupling store loaded usable partner rows for the anchor, yet no returned
/// candidate landed in the co-change tier. The four distinguishable reasons:
///
/// 1. chore-anchor excluded (`is_chore_anchor_path` fires before the gate),
/// 2. anchor reached only prefix-tier path confidence (below the basename
/// floor), with a `query="<basename>"` hint to clear it,
/// 3. neighbors exist but none of them appear among the returned candidates
/// (the genuine path-mismatch case),
/// 4. neighbors appear among candidates but were filtered out by a later gate.
///
/// The anchor-confidence reason (1 and 2) is computed once at anchor level via
/// [`classify_anchor_cochange_rejection`], not per candidate.
fn cochange_fallback_detail(
query: &str,
anchor_path: &str,
neighbors: &SearchFilesCouplingNeighbors,
candidate_paths: &[&str],
) -> String {
let partner_count = neighbors.len();
let anchor_score = crate::live_index::query::anchor_path_match_score(query, anchor_path);
match crate::live_index::rank_signals::classify_anchor_cochange_rejection(
anchor_path,
anchor_score,
) {
Some(crate::live_index::rank_signals::AnchorCoChangeRejection::ChoreAnchor) => {
format!(
"anchor_path={anchor_path} loaded {partner_count} usable coupling partner(s), but it is a chore anchor (lockfile/changelog/workflow) excluded from co-change promotion; path ranking returned"
)
}
Some(crate::live_index::rank_signals::AnchorCoChangeRejection::BelowConfidenceFloor) => {
let anchor_basename = std::path::Path::new(anchor_path)
.file_name()
.and_then(|name| name.to_str())
.unwrap_or(anchor_path);
format!(
"anchor_path={anchor_path} loaded {partner_count} usable coupling partner(s), but the query reached only prefix-tier path confidence for the anchor (below the basename-tier floor); pass query=\"{anchor_basename}\" to clear it; path ranking returned"
)
}
None => {
let any_partner_in_candidates = candidate_paths
.iter()
.any(|path| neighbors.contains_key(*path));
if any_partner_in_candidates {
format!(
"anchor_path={anchor_path} loaded {partner_count} usable coupling partner(s) present among returned candidates, but a later rank gate filtered them; path ranking returned"
)
} else {
format!(
"anchor_path={anchor_path} loaded {partner_count} usable coupling partner(s), but none appear among the returned candidates; path ranking returned"
)
}
}
}
}
fn cochange_lazy_prepare_evidence(
root: &Path,
project_state: Option<&crate::domain::ProjectStateDir>,
reason: &str,
fallback_detail: &str,
) -> CapabilityEvidence {
let Some(project_state) = project_state else {
return cochange_ranking_evidence(
CapabilityStatus::Unavailable,
CapabilityFreshness::Unknown,
CapabilityCost::Free,
format!("{reason}; no project-state owner is available; {fallback_detail}"),
);
};
match crate::live_index::coupling::start_lazy_prepare(root, project_state) {
Ok(crate::live_index::coupling::LazyPrepareOutcome::Started) => cochange_ranking_evidence(
CapabilityStatus::Preparing,
CapabilityFreshness::Unknown,
CapabilityCost::Bounded,
format!("{reason}; bounded background preparation started; {fallback_detail}"),
),
Ok(crate::live_index::coupling::LazyPrepareOutcome::AlreadyRunning) => {
cochange_ranking_evidence(
CapabilityStatus::Preparing,
CapabilityFreshness::Unknown,
CapabilityCost::Bounded,
format!(
"{reason}; bounded background preparation already in progress; {fallback_detail}"
),
)
}
Err(error) => cochange_ranking_evidence(
CapabilityStatus::Unavailable,
CapabilityFreshness::Unknown,
CapabilityCost::Bounded,
format!("{reason}; unable to start bounded preparation: {error}; {fallback_detail}"),
),
}
}
fn cochange_stale_prepare_evidence(
root: &Path,
project_state: Option<&crate::domain::ProjectStateDir>,
) -> CapabilityEvidence {
let Some(project_state) = project_state else {
return cochange_ranking_evidence(
CapabilityStatus::Unavailable,
CapabilityFreshness::Stale,
CapabilityCost::Free,
"coupling store is stale but no project-state owner is available; path ranking returned",
);
};
match crate::live_index::coupling::start_lazy_prepare(root, project_state) {
Ok(crate::live_index::coupling::LazyPrepareOutcome::Started) => cochange_ranking_evidence(
CapabilityStatus::Stale,
CapabilityFreshness::Stale,
CapabilityCost::Bounded,
"coupling store is stale for the current HEAD; bounded background refresh started; path ranking returned",
),
Ok(crate::live_index::coupling::LazyPrepareOutcome::AlreadyRunning) => {
cochange_ranking_evidence(
CapabilityStatus::Stale,
CapabilityFreshness::Stale,
CapabilityCost::Bounded,
"coupling store is stale for the current HEAD; bounded background refresh already in progress; path ranking returned",
)
}
Err(error) => cochange_ranking_evidence(
CapabilityStatus::Unavailable,
CapabilityFreshness::Stale,
CapabilityCost::Bounded,
format!(
"coupling store is stale for the current HEAD; unable to start bounded refresh: {error}; path ranking returned"
),
),
}
}
fn search_files_coupling_neighbors(
index: &LiveIndex,
repo_root: Option<&Path>,
project_state: Option<&crate::domain::ProjectStateDir>,
anchor_path: &str,
) -> SearchFilesCoChangeResolution {
let anchor_path = normalize_exact_path(anchor_path);
if !index.files.contains_key(&anchor_path) {
return SearchFilesCoChangeResolution {
neighbors: None,
evidence: cochange_ranking_evidence(
CapabilityStatus::FallbackUsed,
CapabilityFreshness::Unknown,
CapabilityCost::Free,
format!("anchor_path={anchor_path} is not indexed; path ranking returned"),
),
};
}
match crate::live_index::coupling::coupling_prepare_policy_from_env() {
CouplingPreparePolicy::Disabled => {
return SearchFilesCoChangeResolution {
neighbors: None,
evidence: cochange_ranking_evidence(
CapabilityStatus::DisabledByPolicy,
CapabilityFreshness::Unknown,
CapabilityCost::Free,
"operator policy disabled co-change preparation and ranking; path ranking returned",
),
};
}
CouplingPreparePolicy::LazyOnRequest | CouplingPreparePolicy::WarmOnStart => {}
}
let store = if let Some(store) = index.coupling_store() {
Some(store.clone())
} else if let (Some(root), Some(project_state)) = (repo_root, project_state) {
match crate::live_index::coupling::open_existing_coupling_store(project_state) {
Ok(Some(store)) => Some((*store).clone()),
Ok(None) => {
return SearchFilesCoChangeResolution {
neighbors: None,
evidence: cochange_lazy_prepare_evidence(
root,
Some(project_state),
"no coupling store exists for this workspace",
"path ranking returned",
),
};
}
Err(error) => {
return SearchFilesCoChangeResolution {
neighbors: None,
evidence: cochange_ranking_evidence(
CapabilityStatus::Unavailable,
CapabilityFreshness::Unknown,
CapabilityCost::Low,
format!("unable to open coupling store: {error}; path ranking returned"),
),
};
}
}
} else {
return SearchFilesCoChangeResolution {
neighbors: None,
evidence: cochange_ranking_evidence(
CapabilityStatus::Unavailable,
CapabilityFreshness::Unknown,
CapabilityCost::Free,
"no repository root is bound; path ranking returned",
),
};
};
let Some(store) = store else {
return SearchFilesCoChangeResolution {
neighbors: None,
evidence: cochange_ranking_evidence(
CapabilityStatus::Unavailable,
CapabilityFreshness::Unknown,
CapabilityCost::Free,
"no coupling store is available; path ranking returned",
),
};
};
if let Some(root) = repo_root {
match store.cold_built_at() {
Ok(Some(_)) => {}
Ok(None) => {
return SearchFilesCoChangeResolution {
neighbors: None,
evidence: cochange_lazy_prepare_evidence(
root,
project_state,
"coupling store exists but has not completed a cold build",
"path ranking returned",
),
};
}
Err(error) => {
return SearchFilesCoChangeResolution {
neighbors: None,
evidence: cochange_ranking_evidence(
CapabilityStatus::Unavailable,
CapabilityFreshness::Unknown,
CapabilityCost::Low,
format!(
"unable to inspect coupling store build state: {error}; path ranking returned"
),
),
};
}
}
let stored_head = match store.last_head() {
Ok(head) => head,
Err(error) => {
return SearchFilesCoChangeResolution {
neighbors: None,
evidence: cochange_ranking_evidence(
CapabilityStatus::Unavailable,
CapabilityFreshness::Unknown,
CapabilityCost::Low,
format!(
"unable to inspect coupling store HEAD state: {error}; path ranking returned"
),
),
};
}
};
let current_head = crate::git::head_sha(root).ok();
if stored_head != current_head {
return SearchFilesCoChangeResolution {
neighbors: None,
evidence: cochange_stale_prepare_evidence(root, project_state),
};
}
}
let rows = store
.query_with_floor(
&crate::live_index::coupling::AnchorKey::file(&anchor_path),
MAX_CO_CHANGE_PARTNERS_PER_ANCHOR,
crate::live_index::rank_signals::FILE_LEVEL_CO_CHANGE_FLOOR,
)
.map_err(|error| error.to_string());
let rows = match rows {
Ok(rows) => rows,
Err(error) => {
return SearchFilesCoChangeResolution {
neighbors: None,
evidence: cochange_ranking_evidence(
CapabilityStatus::Unavailable,
CapabilityFreshness::Unknown,
CapabilityCost::Low,
format!("unable to query coupling store: {error}; path ranking returned"),
),
};
}
};
let mut neighbors = HashMap::new();
for row in rows {
let Some(partner_path) = row.partner.as_str().strip_prefix("file:") else {
continue;
};
let weighted_score = row.weighted_score as f32;
if !weighted_score.is_finite() || weighted_score <= 0.0 {
continue;
}
neighbors.insert(
partner_path.to_string(),
SearchFilesCouplingEvidence {
shared_commits: row.shared_commits,
weighted_score,
},
);
}
if neighbors.is_empty() {
SearchFilesCoChangeResolution {
neighbors: None,
evidence: cochange_ranking_evidence(
CapabilityStatus::FallbackUsed,
CapabilityFreshness::Empty,
CapabilityCost::Low,
format!(
"ready coupling store has no usable partner rows for anchor_path={anchor_path}; path ranking returned"
),
),
}
} else {
SearchFilesCoChangeResolution {
neighbors: Some(neighbors),
evidence: cochange_ranking_evidence(
CapabilityStatus::Ready,
CapabilityFreshness::Current,
CapabilityCost::Low,
format!(
"ready coupling store loaded usable partner rows for anchor_path={anchor_path}"
),
),
}
}
}
fn frecency_ranking_evidence(
status: CapabilityStatus,
detail: impl Into<String>,
) -> CapabilityEvidence {
CapabilityEvidence::new(CapabilityName::FrecencyRanking, status)
.with_freshness(CapabilityFreshness::Current)
.with_safety(CapabilitySafety::ReadOnly)
.with_detail(detail)
}
const RANKING_DIAGNOSTICS_ENV: &str = "SYMFORGE_DEBUG_RANKING";
fn ranking_diagnostics_policy_from_env() -> RankingDiagnosticsPolicy {
match std::env::var(RANKING_DIAGNOSTICS_ENV) {
Ok(value) => match value.trim().to_ascii_lowercase().as_str() {
"" => RankingDiagnosticsPolicy::CallTimeExplain,
"1" | "true" | "on" | "yes" | "default-on" => RankingDiagnosticsPolicy::DefaultOn,
"0" | "false" | "no" | "off" | "disabled" | "disable" => {
RankingDiagnosticsPolicy::Disabled
}
_ => RankingDiagnosticsPolicy::Disabled,
},
Err(std::env::VarError::NotPresent) => RankingDiagnosticsPolicy::CallTimeExplain,
Err(std::env::VarError::NotUnicode(_)) => RankingDiagnosticsPolicy::Disabled,
}
}
struct SearchFilesRankingDiagnosticsDecision {
explain: bool,
evidence: Option<CapabilityEvidence>,
}
fn ranking_diagnostics_evidence(
status: CapabilityStatus,
detail: impl Into<String>,
) -> CapabilityEvidence {
CapabilityEvidence::new(CapabilityName::RankingDiagnostics, status)
.with_freshness(CapabilityFreshness::Current)
.with_safety(CapabilitySafety::ReadOnly)
.with_detail(detail)
}
fn search_files_debug_ranking_requested(
input: &SearchFilesInput,
) -> SearchFilesRankingDiagnosticsDecision {
match ranking_diagnostics_policy_from_env() {
RankingDiagnosticsPolicy::CallTimeExplain => SearchFilesRankingDiagnosticsDecision {
explain: input.debug_ranking.unwrap_or(false),
evidence: None,
},
RankingDiagnosticsPolicy::DefaultOn => SearchFilesRankingDiagnosticsDecision {
explain: true,
evidence: None,
},
RankingDiagnosticsPolicy::Disabled if input.debug_ranking.unwrap_or(false) => {
SearchFilesRankingDiagnosticsDecision {
explain: false,
evidence: Some(ranking_diagnostics_evidence(
CapabilityStatus::DisabledByPolicy,
"operator policy disabled ranking diagnostics; ranking explanation omitted",
)),
}
}
RankingDiagnosticsPolicy::Disabled => SearchFilesRankingDiagnosticsDecision {
explain: false,
evidence: None,
},
}
}
fn search_files_rank_mode_label(rank_by: Option<&str>) -> &'static str {
match rank_by {
Some("frecency") => "frecency",
Some("path+cochange") => "path+cochange",
_ => "default path",
}
}
fn search_files_tier_summary(view: &SearchFilesView) -> String {
let SearchFilesView::Found { hits, .. } = view else {
return "no returned files".to_string();
};
let mut cochange = 0usize;
let mut strong = 0usize;
let mut basename = 0usize;
let mut loose = 0usize;
let mut metadata = 0usize;
for hit in hits {
match hit.tier {
SearchFilesTier::CoChange => cochange += 1,
SearchFilesTier::StrongPath => strong += 1,
SearchFilesTier::Basename => basename += 1,
SearchFilesTier::LoosePath => loose += 1,
SearchFilesTier::MetadataOnly => metadata += 1,
}
}
let mut parts = Vec::new();
if cochange > 0 {
parts.push(format!("co-change={cochange}"));
}
if strong > 0 {
parts.push(format!("strong path={strong}"));
}
if basename > 0 {
parts.push(format!("basename={basename}"));
}
if loose > 0 {
parts.push(format!("loose path={loose}"));
}
if metadata > 0 {
parts.push(format!("metadata-only={metadata}"));
}
if parts.is_empty() {
"no returned files".to_string()
} else {
parts.join(", ")
}
}
fn search_files_signal_explanation(
signal: &str,
evidence: Option<&CapabilityEvidence>,
not_requested: bool,
) -> String {
if not_requested {
return format!("{signal} signal: not requested");
}
match evidence {
Some(evidence) => {
let mut line = format!("{signal} signal: {}", evidence.status);
if let Some(detail) = evidence.detail.as_deref().map(str::trim)
&& !detail.is_empty()
{
line.push_str(" - ");
line.push_str(detail.trim_end_matches('.'));
}
line
}
None => format!("{signal} signal: unavailable - no capability evidence was recorded"),
}
}
fn search_files_final_ordering_note(
rank_by: Option<&str>,
cochange_evidence: Option<&CapabilityEvidence>,
frecency_evidence: Option<&CapabilityEvidence>,
) -> String {
match rank_by {
Some("frecency") => match frecency_evidence.map(|evidence| evidence.status) {
Some(CapabilityStatus::Applied) => {
"frecency fusion applied after path ranking; ties remain deterministic by path"
.to_string()
}
Some(status) => format!(
"frecency requested but {status}; path-ranked ordering was returned"
),
None => "frecency requested but no evidence was available; path-ranked ordering was returned"
.to_string(),
},
Some("path+cochange") => match cochange_evidence.map(|evidence| evidence.status) {
Some(CapabilityStatus::Applied) | Some(CapabilityStatus::Ready) => {
"co-change partners that passed gates were fused with path ranking; remaining files keep path tie-breakers"
.to_string()
}
Some(status) => format!(
"path+cochange requested but {status}; path-ranked ordering was returned"
),
None => "path+cochange requested but no evidence was available; path-ranked ordering was returned"
.to_string(),
},
_ => "tiered path relevance ordered the results with deterministic path tie-breakers"
.to_string(),
}
}
fn search_files_ranking_explanation(
view: &SearchFilesView,
rank_by: Option<&str>,
cochange_evidence: Option<&CapabilityEvidence>,
frecency_evidence: Option<&CapabilityEvidence>,
) -> String {
let rank_mode = search_files_rank_mode_label(rank_by);
let frecency_not_requested = rank_by != Some("frecency");
let cochange_not_requested = rank_by != Some("path+cochange");
[
"Ranking explanation:".to_string(),
format!("requested rank mode: {rank_mode}"),
format!(
"path signal: applied - returned tier family: {}",
search_files_tier_summary(view)
),
search_files_signal_explanation("frecency", frecency_evidence, frecency_not_requested),
search_files_signal_explanation("co-change", cochange_evidence, cochange_not_requested),
format!(
"final ordering: {}",
search_files_final_ordering_note(rank_by, cochange_evidence, frecency_evidence)
),
]
.join("\n")
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct CapabilityStatusReport {
frecency: String,
co_change: String,
worktree_routing: String,
ranking_diagnostics: String,
}
impl CapabilityStatusReport {
fn full_text(&self) -> String {
format!(
"Capabilities:\n frecency: {}\n co-change: {}\n worktree routing: {}\n ranking diagnostics: {}",
self.frecency, self.co_change, self.worktree_routing, self.ranking_diagnostics
)
}
fn compact_text(&self) -> String {
format!(
"Capabilities: frecency={}; co-change={}; worktree={}; ranking={}",
self.frecency, self.co_change, self.worktree_routing, self.ranking_diagnostics
)
}
}
fn frecency_health_status(
repo_root: Option<&Path>,
project_state: Option<&crate::domain::ProjectStateDir>,
) -> String {
if repo_root.is_none() {
return "unavailable/no-repository-root".to_string();
}
let has_persistent_history = project_state
.map(crate::live_index::frecency::frecency_db_path)
.is_some_and(|path| path.is_file());
match crate::live_index::frecency::collection_policy_from_env() {
FrecencyCollectionPolicy::Disabled => "disabled by policy".to_string(),
FrecencyCollectionPolicy::Session => {
if has_persistent_history {
"ready/session+persistent".to_string()
} else {
"ready/session/no-history fallback-used-on-empty".to_string()
}
}
FrecencyCollectionPolicy::Persistent => {
if project_state.is_none() {
return "unavailable/no-project-state-owner".to_string();
}
if has_persistent_history {
"ready/persistent".to_string()
} else {
"ready/persistent/no-history fallback-used-on-empty".to_string()
}
}
}
}
fn cochange_store_health_status(
store: &crate::live_index::coupling::CouplingStore,
repo_root: &Path,
) -> String {
match store.cold_built_at() {
Ok(Some(_)) => {}
Ok(None) => return "preparing/cold-build-pending fallback-used-on-request".to_string(),
Err(error) => return format!("unavailable/store-build-state-error ({error})"),
}
let stored_head = match store.last_head() {
Ok(Some(head)) => head,
Ok(None) => return "preparing/no-head-recorded fallback-used-on-request".to_string(),
Err(error) => return format!("unavailable/store-head-state-error ({error})"),
};
let current_head = match crate::git::head_sha(repo_root) {
Ok(head) => head,
Err(error) => return format!("unavailable/head-read-failed ({error})"),
};
if stored_head != current_head {
"stale/head-mismatch fallback-used-on-request".to_string()
} else {
"ready/current".to_string()
}
}
fn cochange_health_status(
index: &LiveIndex,
repo_root: Option<&Path>,
project_state: Option<&crate::domain::ProjectStateDir>,
) -> String {
let policy = crate::live_index::coupling::coupling_prepare_policy_from_env();
if matches!(policy, CouplingPreparePolicy::Disabled) {
return "disabled by policy".to_string();
}
let Some(repo_root) = repo_root else {
return "unavailable/no-repository-root".to_string();
};
if git2::Repository::discover(repo_root).is_err() {
return "unavailable/not-a-git-repo".to_string();
}
if let Some(store) = index.coupling_store() {
return cochange_store_health_status(store, repo_root);
}
let Some(project_state) = project_state else {
return "unavailable/no-project-state-owner".to_string();
};
match crate::live_index::coupling::open_existing_coupling_store(project_state) {
Ok(Some(store)) => cochange_store_health_status(store.as_ref(), repo_root),
Ok(None) => match policy {
CouplingPreparePolicy::LazyOnRequest => {
"preparing/lazy-on-request fallback-used-on-request".to_string()
}
CouplingPreparePolicy::WarmOnStart => {
"preparing/warm-on-start fallback-used-on-request".to_string()
}
CouplingPreparePolicy::Disabled => "disabled by policy".to_string(),
},
Err(error) => format!("unavailable/store-open-failed ({error})"),
}
}
fn worktree_routing_health_status() -> String {
match crate::worktree::routing_policy_from_env() {
WorktreeRoutingPolicy::ExplicitCallTime => "explicit-call enabled".to_string(),
WorktreeRoutingPolicy::Disabled => "disabled by policy".to_string(),
}
}
fn ranking_diagnostics_health_status() -> String {
match ranking_diagnostics_policy_from_env() {
RankingDiagnosticsPolicy::CallTimeExplain => {
"call-time explain available/default-off".to_string()
}
RankingDiagnosticsPolicy::DefaultOn => "call-time explain available/default-on".to_string(),
RankingDiagnosticsPolicy::Disabled => "disabled by policy".to_string(),
}
}
fn capability_status_report(
index: &LiveIndex,
repo_root: Option<&Path>,
project_state: Option<&crate::domain::ProjectStateDir>,
) -> CapabilityStatusReport {
CapabilityStatusReport {
frecency: frecency_health_status(repo_root, project_state),
co_change: cochange_health_status(index, repo_root, project_state),
worktree_routing: worktree_routing_health_status(),
ranking_diagnostics: ranking_diagnostics_health_status(),
}
}
const CHANGED_WITH_DEPRECATION_WARNING: &str = "Deprecation warning: `search_files changed_with=` is deprecated since v7.x and scheduled for removal in v8.x; prefer `rank_by=\"path+cochange\"` with `anchor_path=<path>`.";
fn append_changed_with_deprecation_warning(mut result: String) -> String {
result.push_str("\n\n");
result.push_str(CHANGED_WITH_DEPRECATION_WARNING);
result
}
fn search_files_total_matches(view: &SearchFilesView) -> usize {
match view {
SearchFilesView::Found { total_matches, .. } => *total_matches,
_ => 0,
}
}
fn search_symbols_total_matches(result: &search::SymbolSearchResult) -> usize {
result.hits.len().saturating_add(result.overflow_count)
}
fn hidden_search_symbols_noise_count(
index: &LiveIndex,
query: &str,
kind: Option<&str>,
options: &search::SymbolSearchOptions,
visible: &search::SymbolSearchResult,
) -> usize {
if options.noise_policy.include_vendor && options.include_personal_tooling {
return 0;
}
let mut unfiltered_options = options.clone();
unfiltered_options.noise_policy.include_vendor = true;
unfiltered_options.include_personal_tooling = true;
let unfiltered = search::search_symbols_with_options(index, query, kind, &unfiltered_options);
search_symbols_total_matches(&unfiltered).saturating_sub(search_symbols_total_matches(visible))
}
fn search_files_resolve_candidate_count(view: &SearchFilesResolveView) -> usize {
match view {
SearchFilesResolveView::Resolved { .. }
| SearchFilesResolveView::ResolvedMetadataOnly { .. } => 1,
SearchFilesResolveView::Ambiguous {
matches,
overflow_count,
..
} => matches.len().saturating_add(*overflow_count),
_ => 0,
}
}
fn search_files_hidden_noise_note(
hidden_count: usize,
include_vendor: bool,
include_personal_tooling: bool,
) -> Option<String> {
if hidden_count == 0 || (include_vendor && include_personal_tooling) {
return None;
}
let mut flags = Vec::new();
if !include_vendor {
flags.push("include_vendor=true");
}
if !include_personal_tooling {
flags.push("include_personal_tooling=true");
}
let noun = if hidden_count == 1 {
"path candidate"
} else {
"path candidates"
};
Some(format!(
"{hidden_count} vendor/personal-tooling {noun} hidden by default; pass {} to include suppressed noise.",
flags.join(" or ")
))
}
fn search_files_filter_summary(include_vendor: bool, include_personal_tooling: bool) -> String {
// SF-STRESS-011 honesty fix: vendor detection is a heuristic path filter, so
// the header says "filter active (heuristic)" rather than asserting the file
// class was actually removed. Personal-tooling paths are an exact prefix
// match, so that claim stays definite.
let vendor = if include_vendor {
"vendor included"
} else {
"vendor filter active (heuristic)"
};
let personal = if include_personal_tooling {
"personal tooling included"
} else {
"personal tooling filtered"
};
format!("filters: {vendor}; {personal}")
}
fn search_files_scope_summary(
base_scope: impl Into<String>,
include_vendor: bool,
include_personal_tooling: bool,
) -> String {
format!(
"{}; {}",
base_scope.into(),
search_files_filter_summary(include_vendor, include_personal_tooling)
)
}
fn append_search_files_filter_summary(
result: &mut String,
include_vendor: bool,
include_personal_tooling: bool,
) {
result.push_str("\n\n");
result.push_str(&search_files_filter_summary(
include_vendor,
include_personal_tooling,
));
}
fn search_files_resolve_match_type_label(view: &SearchFilesResolveView) -> &'static str {
match view {
SearchFilesResolveView::Resolved { .. } => "exact (resolve)",
SearchFilesResolveView::ResolvedMetadataOnly { .. } => {
"exact (resolve, Tier-2 metadata-only)"
}
SearchFilesResolveView::Ambiguous { .. } => "constrained (resolve candidates)",
_ => "constrained",
}
}
fn anchored_search_evidence(anchors: Vec<String>, noun: &str) -> String {
if anchors.is_empty() {
format!("no {noun} available")
} else {
let rendered = anchors
.into_iter()
.map(|anchor| format!("`{anchor}`"))
.collect::<Vec<_>>()
.join(", ");
format!("{noun} {rendered}")
}
}
fn search_text_evidence(result: &search::TextSearchResult) -> String {
let anchors = result
.files
.iter()
.flat_map(|file| {
file.matches
.iter()
.take(2)
.map(move |line_match| format!("{}:{}", file.path, line_match.line_number))
})
.take(3)
.collect();
anchored_search_evidence(anchors, "line anchors")
}
fn search_symbols_evidence(result: &search::SymbolSearchResult) -> String {
let anchors = result
.hits
.iter()
.take(3)
.map(|hit| format!("{}:{}", hit.path, hit.line))
.collect();
anchored_search_evidence(anchors, "symbol anchors")
}
fn search_paths_evidence<'a, I>(paths: I) -> String
where
I: IntoIterator<Item = &'a str>,
{
let anchors = paths
.into_iter()
.take(3)
.map(std::borrow::ToOwned::to_owned)
.collect();
anchored_search_evidence(anchors, "paths")
}
fn normalize_untracked_search_path(raw: &str) -> String {
let mut normalized = raw.trim().replace('\\', "/");
while normalized.starts_with("./") {
normalized = normalized[2..].to_string();
}
normalized.trim_matches('/').to_string()
}
fn untracked_path_has_component(path: &str, component: &str) -> bool {
path.split('/')
.any(|part| part.eq_ignore_ascii_case(component))
}
fn language_for_path(path: &str) -> Option<LanguageId> {
Path::new(path)
.extension()
.and_then(|extension| extension.to_str())
.map(str::to_ascii_lowercase)
.and_then(|extension| LanguageId::from_extension(&extension))
}
fn untracked_common_path_filters_allow(
path: &str,
include_vendor: bool,
include_personal_tooling: bool,
) -> bool {
(include_vendor || !crate::live_index::query::is_vendor_path(path))
&& (include_personal_tooling || !crate::live_index::query::is_personal_tooling_path(path))
}
fn untracked_paths_not_in_index(server: &SymForgeServer) -> Vec<String> {
let Some(repo_root) = server.effective_repo_root_for_git_tools() else {
return Vec::new();
};
let Ok(repo) = crate::git::GitRepo::open(&repo_root) else {
return Vec::new();
};
let Ok(mut paths) = repo.untracked_paths() else {
return Vec::new();
};
{
let guard = server.index.read();
paths.retain(|path| guard.get_file(path).is_none());
}
paths.sort();
paths.dedup();
paths
}
fn untracked_file_diagnostic(paths: &[String]) -> Option<String> {
let first = paths.first()?;
Some(format!(
"untracked file may match: {} untracked path(s) are not indexed. To index the first match, call analyze_file_impact(\"{}\", new_file=true).",
paths.len(),
first
))
}
fn append_untracked_file_diagnostic(output: &mut String, paths: &[String]) {
if let Some(diagnostic) = untracked_file_diagnostic(paths) {
output.push_str("\n\n");
output.push_str(&diagnostic);
}
}
fn untracked_path_matches_search_files_query(path: &str, query: &str) -> bool {
let normalized_query = normalize_untracked_search_path(query);
if normalized_query.is_empty() {
return false;
}
let is_glob = normalized_query.contains('*')
|| normalized_query.contains('?')
|| normalized_query.contains('[');
if is_glob
&& let Ok(glob) = globset::GlobBuilder::new(&normalized_query)
.literal_separator(false)
.build()
{
return glob.compile_matcher().is_match(path);
}
let path_lower = path.to_ascii_lowercase();
let normalized_query_lower = normalized_query.to_ascii_lowercase();
let has_path_context = normalized_query.contains('/');
if path_lower == normalized_query_lower
|| (has_path_context && path_lower.ends_with(&normalized_query_lower))
{
return true;
}
let tokens: Vec<String> = normalized_query
.split(|ch: char| ch == '/' || ch.is_whitespace())
.filter(|part| !part.is_empty())
.map(str::to_ascii_lowercase)
.collect();
let Some(basename_token) = tokens.last() else {
return false;
};
let component_tokens = if tokens.len() > 1 {
&tokens[..tokens.len() - 1]
} else {
&[][..]
};
let file_name = Path::new(path)
.file_name()
.and_then(|name| name.to_str())
.unwrap_or("");
if file_name.eq_ignore_ascii_case(basename_token)
&& component_tokens
.iter()
.all(|component| untracked_path_has_component(path, component))
{
return true;
}
if basename_token.len() >= 3 {
let file_stem = Path::new(path)
.file_stem()
.and_then(|stem| stem.to_str())
.unwrap_or("");
if file_stem.to_ascii_lowercase().starts_with(basename_token) {
return true;
}
}
tokens.iter().all(|token| path_lower.contains(token))
}
fn matching_untracked_paths_for_search_files(
server: &SymForgeServer,
query: &str,
include_vendor: bool,
include_personal_tooling: bool,
) -> Vec<String> {
untracked_paths_not_in_index(server)
.into_iter()
.filter(|path| {
untracked_common_path_filters_allow(path, include_vendor, include_personal_tooling)
&& untracked_path_matches_search_files_query(path, query)
})
.collect()
}
fn untracked_text_path_allowed(path: &str, options: &search::TextSearchOptions) -> bool {
let classification = FileClassification::for_code_path(path);
options.path_scope.matches(path)
&& options.search_scope.allows(&classification)
&& options.noise_policy.allows(&classification)
&& (options.noise_policy.include_vendor || !crate::live_index::query::is_vendor_path(path))
&& (options.include_personal_tooling
|| !crate::live_index::query::is_personal_tooling_path(path))
&& options
.language_filter
.as_ref()
.is_none_or(|language| language_for_path(path).as_ref() == Some(language))
&& untracked_text_globs_allow(path, options)
}
fn untracked_text_globs_allow(path: &str, options: &search::TextSearchOptions) -> bool {
let include_matches = match options.glob.as_deref() {
Some(pattern) => globset::GlobBuilder::new(pattern)
.literal_separator(false)
.build()
.map(|glob| glob.compile_matcher().is_match(path))
.unwrap_or(false),
None => true,
};
let exclude_matches = match options.exclude_glob.as_deref() {
Some(pattern) => globset::GlobBuilder::new(pattern)
.literal_separator(false)
.build()
.map(|glob| glob.compile_matcher().is_match(path))
.unwrap_or(false),
None => false,
};
include_matches && !exclude_matches
}
fn whole_word_contains(haystack: &str, needle: &str) -> bool {
haystack.match_indices(needle).any(|(idx, matched)| {
let before_is_word = haystack[..idx]
.chars()
.next_back()
.is_some_and(|ch| ch == '_' || ch.is_alphanumeric());
let after_idx = idx + matched.len();
let after_is_word = haystack[after_idx..]
.chars()
.next()
.is_some_and(|ch| ch == '_' || ch.is_alphanumeric());
!before_is_word && !after_is_word
})
}
fn untracked_text_matches(
content: &str,
query: Option<&str>,
terms: Option<&[String]>,
is_regex: bool,
options: &search::TextSearchOptions,
) -> bool {
let case_sensitive = options.case_sensitive.unwrap_or(is_regex);
if is_regex {
let Some(pattern) = query.map(str::trim).filter(|pattern| !pattern.is_empty()) else {
return false;
};
return regex::RegexBuilder::new(pattern)
.case_insensitive(!case_sensitive)
.build()
.map(|regex| regex.is_match(content))
.unwrap_or(false);
}
let normalized_terms: Vec<&str> = match terms {
Some(raw_terms) if !raw_terms.is_empty() => raw_terms
.iter()
.map(|term| term.trim())
.filter(|term| !term.is_empty())
.collect(),
_ => query
.map(str::trim)
.filter(|text| !text.is_empty())
.map(|text| vec![text])
.unwrap_or_default(),
};
if normalized_terms.is_empty() {
return false;
}
if case_sensitive {
if options.whole_word {
normalized_terms
.iter()
.any(|term| whole_word_contains(content, term))
} else {
normalized_terms.iter().any(|term| content.contains(term))
}
} else {
let lowered = content.to_lowercase();
normalized_terms.iter().any(|term| {
let lowered_term = term.to_lowercase();
if options.whole_word {
whole_word_contains(&lowered, &lowered_term)
} else {
lowered.contains(&lowered_term)
}
})
}
}
fn matching_untracked_paths_for_search_text(
server: &SymForgeServer,
query: Option<&str>,
terms: Option<&[String]>,
structural: bool,
is_regex: bool,
options: &search::TextSearchOptions,
) -> Vec<String> {
if structural {
return Vec::new();
}
let Some(repo_root) = server.effective_repo_root_for_git_tools() else {
return Vec::new();
};
let Ok(repo) = crate::git::GitRepo::open(&repo_root) else {
return Vec::new();
};
// The caller's own regex is evaluated against this content, so an anchored
// pattern recovers a refused file character by character from nothing but
// which paths come back. The gate runs BEFORE any matching: a refusal drops
// the path from the sweep entirely, disclosing neither content nor
// existence-by-match.
let live = server.index.read();
untracked_paths_not_in_index(server)
.into_iter()
.filter(|path| untracked_text_path_allowed(path, options))
.filter(|path| {
crate::protocol::read_gate::admit_worktree_text(&live, &repo, path)
.ok()
.flatten()
.is_some_and(|content| {
untracked_text_matches(&content, query, terms, is_regex, options)
})
})
.collect()
}
struct AdmissionDegradationView {
tier: AdmissionTier,
path: String,
size: Option<u64>,
extension: Option<String>,
language: Option<LanguageId>,
reason: Option<SkipReason>,
}
fn normalize_admission_degradation_path(raw: &str) -> String {
let mut normalized = raw.trim().replace('\\', "/");
while normalized.starts_with("./") {
normalized = normalized[2..].to_string();
}
normalized.trim_matches('/').to_string()
}
fn admission_degradation_view_from_lookup(
view: crate::live_index::query::AdmissionTierLookupView,
) -> AdmissionDegradationView {
AdmissionDegradationView {
tier: view.tier,
path: view.path,
size: view.size,
extension: view.extension,
language: view.language,
reason: view.reason,
}
}
fn admission_degradation_view_from_disk(
repo_root: &Path,
path: &str,
) -> Option<AdmissionDegradationView> {
let canonical_root = std::fs::canonicalize(repo_root).ok()?;
let raw_path = Path::new(path);
let candidate = if raw_path.is_absolute() {
raw_path.to_path_buf()
} else {
canonical_root.join(raw_path)
};
let canonical_candidate = std::fs::canonicalize(candidate).ok()?;
if !canonical_candidate.starts_with(&canonical_root) {
return None;
}
let metadata = std::fs::metadata(&canonical_candidate).ok()?;
if !metadata.is_file() {
return None;
}
let size = metadata.len();
let initial_decision = crate::discovery::classify_admission(&canonical_candidate, size, None);
let decision = if initial_decision.tier == AdmissionTier::Normal {
let mut sample = Vec::new();
let mut file = std::fs::File::open(&canonical_candidate).ok()?;
file.by_ref()
.take(BINARY_SNIFF_BYTES as u64)
.read_to_end(&mut sample)
.ok()?;
crate::discovery::classify_admission(&canonical_candidate, size, Some(&sample))
} else {
initial_decision
};
let extension = canonical_candidate
.extension()
.and_then(|extension| extension.to_str())
.map(str::to_string);
let language = extension.as_deref().and_then(LanguageId::from_extension);
// SF-004: a small, non-binary, non-denylisted file whose extension maps to
// no supported grammar comes back `Normal` from `classify_admission` (which
// never inspects language). On disk it EXISTS but cannot be parsed, so it
// must report the honest Tier-2/UnsupportedLanguage degradation rather than
// falling through to a false "File not found". Mirror the bulk-walk demotion
// (store.rs Phase-2) via the same shared predicate. A recognized-language
// file that is genuinely Tier-1 keeps its `Normal` decision and returns
// `None` below so the caller's normal handling proceeds.
let decision = if decision.tier == AdmissionTier::Normal && language.is_none() {
crate::discovery::unsupported_language_decision(decision)
} else {
decision
};
if decision.tier == AdmissionTier::Normal {
return None;
}
let relative_path = canonical_candidate
.strip_prefix(&canonical_root)
.ok()
.map(|relative| relative.to_string_lossy().replace('\\', "/"))
.filter(|relative| !relative.is_empty())
.unwrap_or_else(|| normalize_admission_degradation_path(path));
Some(AdmissionDegradationView {
tier: decision.tier,
path: relative_path,
size: Some(size),
extension,
language,
reason: decision.reason,
})
}
fn admission_tier_degradation_for_path(
index: &LiveIndex,
repo_root: Option<&Path>,
tool_name: &str,
path: &str,
symbol_name: &str,
) -> Option<String> {
let view = index
.capture_admission_tier_lookup_view(path)
.map(admission_degradation_view_from_lookup)
.or_else(|| repo_root.and_then(|root| admission_degradation_view_from_disk(root, path)))?;
match view.tier {
AdmissionTier::Normal => None,
AdmissionTier::MetadataOnly => Some(format!(
"degraded result (Tier 2 metadata-only): `{tool_name}` cannot return symbol or \
reference data for `{}` because SymForge admits this path as metadata-only instead \
of parsing it.\n\n\
Warning: metadata-only files are not parsed, so no symbol or reference data exists \
for this file.\n\
Path: {}\n\
Size: {}\n\
Extension: {}\n\
Language: {}\n\
Reason: {}\n\
Requested symbol: `{symbol_name}`\n\n\
No symbol or reference data is available for this file.",
view.path,
view.path,
view.size
.map(|size| format!("{size} bytes"))
.unwrap_or_else(|| "unknown".to_string()),
view.extension.as_deref().unwrap_or("unavailable"),
view.language
.as_ref()
.map(std::string::ToString::to_string)
.unwrap_or_else(|| "unavailable".to_string()),
view.reason
.map(|reason| reason.to_string())
.unwrap_or_else(|| "unknown".to_string()),
)),
AdmissionTier::HardSkip => Some(format!(
"Not available (Tier 3 hard-skipped): `{tool_name}` cannot inspect `{}` because \
the file was hard-skipped during admission.\n\n\
Path: {}\n\
Size: {}\n\
Extension: {}\n\
Reason: {}\n\
Requested symbol: `{symbol_name}`\n\n\
No symbol or reference data is available for this file.",
view.path,
view.path,
view.size
.map(|size| format!("{size} bytes"))
.unwrap_or_else(|| "unknown".to_string()),
view.extension.as_deref().unwrap_or("unavailable"),
view.reason
.map(|reason| reason.to_string())
.unwrap_or_else(|| "unknown".to_string()),
)),
}
}
/// File-level (non-symbol) variant of admission-tier degradation. Returns an
/// honest "not indexed" message for a path that EXISTS but was admitted as
/// Tier-2 metadata-only or Tier-3 hard-skipped, instead of a misleading
/// "File not found". Resolution reuses the same index-lookup + disk-fallback
/// path as `admission_tier_degradation_for_path`, so the containment guard in
/// `admission_degradation_view_from_disk` (path must stay within the repo root)
/// is preserved. `None` means the path is either Tier-1 (indexed) or genuinely
/// absent — the caller should fall through to its normal not-found handling.
fn admission_tier_file_degradation_for_path(
index: &LiveIndex,
repo_root: Option<&Path>,
path: &str,
) -> Option<String> {
let view = index
.capture_admission_tier_lookup_view(path)
.map(admission_degradation_view_from_lookup)
.or_else(|| repo_root.and_then(|root| admission_degradation_view_from_disk(root, path)))?;
if view.tier == AdmissionTier::Normal {
return None;
}
Some(format::not_indexed_skipped_file(
&view.path,
view.tier,
view.reason,
view.size,
!crate::protocol::read_gate::disk_read_would_refuse(index, &view.path, view.size),
))
}
fn find_references_match_type_label(input: &FindReferencesInput, mode: &str) -> &'static str {
if mode == "implementations" {
return "constrained (implementations mode)";
}
if input.path.is_some() && input.symbol_line.is_some() {
"exact"
} else if input.path.is_some() {
"constrained (path-scoped symbol)"
} else if input.symbol_kind.is_some() || input.kind.as_deref().is_some_and(|kind| kind != "all")
{
"constrained (repo-wide filtered symbol)"
} else {
"constrained (repo-wide name match)"
}
}
fn find_references_scope_summary(input: &FindReferencesInput, mode: &str) -> String {
let mut parts = Vec::new();
if mode == "implementations" {
parts.push(format!(
"repo-wide implementations for symbol token `{}`",
input.name
));
parts.push(format!(
"direction `{}`",
input.direction.as_deref().unwrap_or("auto")
));
return parts.join("; ");
}
match input.path.as_deref() {
Some(path) => parts.push(format!("path `{path}`")),
None => parts.push(format!("repo-wide symbol token `{}`", input.name)),
}
if let Some(line) = input.symbol_line {
parts.push(format!("exact selector line {line}"));
}
if let Some(symbol_kind) = input.symbol_kind.as_deref() {
parts.push(format!("symbol kind `{symbol_kind}`"));
}
if let Some(reference_kind) = input.kind.as_deref().filter(|kind| *kind != "all") {
parts.push(format!("reference kind `{reference_kind}`"));
}
parts.join("; ")
}
/// True when the `references`-mode `kind` filter sweeps in type/value usages,
/// whose recall is genuinely best-effort: the xref extractor resolves them
/// syntactically and misses dynamic dispatch, macro-generated, reflective, and
/// cross-language usages. Direct `call`/`import`/`macro_use` references are
/// extracted reliably, so they earn no caveat (and `implementations` mode never
/// reaches this label — it has its own branch). `None`/`"all"` default includes
/// type/value usages, so it is best-effort too.
fn find_references_kind_is_best_effort(kind: Option<&str>) -> bool {
// Mirror `find_references_kind_filter` rather than duplicating a string
// whitelist, so the caveat can never drift from the kinds actually returned.
// A filter result of `None` means "no kind filter" -> all kinds returned,
// INCLUDING best-effort type/value usages; that covers `all`/`None` AND any
// UNRECOGNIZED kind (the filter's `_ => None` arm), so a typo'd `kind` still
// gets the caveat instead of silently shipping a best-effort trace unmarked.
matches!(
find_references_kind_filter(kind),
None | Some(ReferenceKind::TypeUsage) | Some(ReferenceKind::ValueUse)
)
}
fn find_references_completeness_label(
view: &crate::live_index::FindReferencesView,
limits: &format::OutputLimits,
kind: Option<&str>,
) -> String {
let shown_files = view.files.len().min(limits.max_files);
let mut shown_refs = 0usize;
for file in view.files.iter().take(limits.max_files) {
if shown_refs >= limits.total_hits {
break;
}
let remaining_budget = limits.total_hits.saturating_sub(shown_refs);
shown_refs += file
.hits
.len()
.min(limits.max_per_file)
.min(remaining_budget);
}
let omitted_refs = view.total_refs.saturating_sub(shown_refs);
let omitted_files = view.total_files.saturating_sub(shown_files);
// Recall-confidence caveat, targeted (not blanket): only type/value-usage
// traces are best-effort, so only they carry it. Riding the existing
// completeness label keeps it one site, one envelope, no ResultStatus bump.
let recall_caveat = if find_references_kind_is_best_effort(kind) {
" — usage-trace recall is best-effort; dynamic dispatch, macro-generated, \
reflective, and cross-language usages may be missed"
} else {
""
};
if omitted_refs == 0 && omitted_files == 0 {
return format!("full for current scope{recall_caveat}");
}
let mut parts = vec!["truncated by result cap".to_string()];
if omitted_refs > 0 {
parts.push(format!("{omitted_refs} reference(s) omitted"));
}
if omitted_files > 0 {
parts.push(format!("{omitted_files} file(s) omitted"));
}
format!("{}{recall_caveat}", parts.join("; "))
}
/// Tier-2 honesty sweep (dogfood finding #1, 2026-07-06): the reference scan
/// covers Tier-1 files only, but first-party source demoted to Tier-2 for size
/// (`SkipReason::SizeThreshold`: 1MB data / 4MB code) can still contain the queried name —
/// the field failure was a compile-breaking construction site inside a 1.2 MB
/// file while the envelope claimed "full for current scope". Sweep those files
/// textually (bounded) and return a disclosure so the envelope never claims a
/// completeness it does not have. Returns `None` when there is nothing to
/// disclose (no size-demoted files, or none contain the name).
///
/// Candidate eligibility is decided by the caller from the typed manifest
/// disposition (`LiveIndex::oversized_metadata_only_files`), NOT from the lossy
/// `SkipReason` projection this used to filter on: that projection collapses
/// security demotions into the reason-free `SkipReason::PolicyWithheld` (it
/// collapsed them into `SkipReason::UnsupportedLanguage` before the admission
/// honesty fix), so excluding them was an accident of mislabelling rather than
/// a decision. Only size-demoted
/// files are reference-relevant anyway — binary, lockfile, and artifact
/// demotions cannot hold code references to the queried symbol.
fn tier2_reference_disclosure(
candidates: &[(String, u64)],
live: &crate::live_index::LiveIndex,
repo_root: Option<&std::path::Path>,
name: &str,
) -> Option<String> {
if candidates.is_empty() || name.trim().is_empty() {
return None;
}
// ponytail: bounded whole-file reads + str::contains; the OS page cache
// makes repeated sweeps cheap. Budgets keep the pathological repo honest
// (reported as unswept) instead of slow.
const MAX_SWEEP_FILES: usize = 8;
const MAX_SWEEP_BYTES: u64 = 32 * 1024 * 1024;
let preview = |paths: &[&str]| -> String {
let shown: Vec<&str> = paths.iter().take(3).copied().collect();
let suffix = if paths.len() > shown.len() {
format!(", … (+{} more)", paths.len() - shown.len())
} else {
String::new()
};
format!("{}{}", shown.join(", "), suffix)
};
let Some(root) = repo_root else {
// No resolvable root: cannot sweep, but silence would be the lie.
let paths: Vec<&str> = candidates.iter().map(|(path, _)| path.as_str()).collect();
return Some(format!(
"Tier-2 exclusion: {} first-party file(s) over the size threshold (1MB data / 4MB code) were NOT reference-scanned \
(metadata-only) and could not be swept for \"{name}\" (no repo root): {}",
candidates.len(),
preview(&paths),
));
};
let mut matched: Vec<&str> = Vec::new();
let mut unswept: Vec<&str> = Vec::new();
let mut bytes_budget = MAX_SWEEP_BYTES;
for (i, (path, size)) in candidates.iter().enumerate() {
if i >= MAX_SWEEP_FILES || bytes_budget < *size {
unswept.push(path.as_str());
continue;
}
// The gate owns the read and re-classifies the current bytes, so a file
// the manifest still records as merely oversized cannot have a textual
// match disclosed once its bytes turn sensitive. The refusal itself is
// discarded: only the path reaches the response, via `unswept`.
match read_gate::admit_disk_read(live, path, &root.join(path)) {
Ok(bytes) => {
bytes_budget = bytes_budget.saturating_sub(bytes.len() as u64);
if String::from_utf8_lossy(&bytes).contains(name) {
matched.push(path.as_str());
}
}
Err(_) => unswept.push(path.as_str()),
}
}
if matched.is_empty() && unswept.is_empty() {
return None;
}
let mut parts: Vec<String> = Vec::new();
if !matched.is_empty() {
parts.push(format!(
"\"{name}\" appears textually in {} size-demoted Tier-2 file(s) that were NOT \
reference-scanned (metadata-only): {} — grep or get_file_content to inspect",
matched.len(),
preview(&matched),
));
}
if !unswept.is_empty() {
parts.push(format!(
"{} size-demoted Tier-2 file(s) not reference-scanned and not swept (budget or policy): {}",
unswept.len(),
preview(&unswept),
));
}
Some(format!("Tier-2 exclusion: {}", parts.join("; ")))
}
fn find_references_evidence(view: &crate::live_index::FindReferencesView) -> String {
let anchors = view
.files
.iter()
.flat_map(|file| {
let file_path = file.file_path.clone();
file.hits.iter().flat_map(move |hit| {
hit.context_lines
.iter()
.filter(|line| line.is_reference_line)
.map({
let file_path = file_path.clone();
move |line| format!("{file_path}:{}", line.line_number)
})
})
})
.take(3)
.collect();
anchored_search_evidence(anchors, "reference anchors")
}
fn find_references_kind_filter(kind_filter: Option<&str>) -> Option<ReferenceKind> {
match kind_filter {
Some("call") => Some(ReferenceKind::Call),
Some("import") => Some(ReferenceKind::Import),
Some("type_usage") => Some(ReferenceKind::TypeUsage),
Some("macro_use") => Some(ReferenceKind::MacroUse),
Some("value_use") => Some(ReferenceKind::ValueUse),
Some("all") | None => None,
_ => None,
}
}
fn should_collect_qualified_usages(input: &FindReferencesInput) -> bool {
input.path.is_none()
&& !input.name.is_empty()
&& matches!(
input.kind.as_deref(),
None | Some("all") | Some("type_usage")
)
}
fn qualified_usage_hit_view(usage: &QualifiedUsage) -> ReferenceHitView {
let confidence = if usage.confident {
"confident"
} else {
"uncertain"
};
let annotation = format!("[qualified-path scan: {confidence}]");
ReferenceHitView {
context_lines: vec![ReferenceContextLineView {
line_number: usage.line,
text: usage.line_text.clone(),
is_reference_line: true,
enclosing_annotation: Some(annotation),
}],
}
}
fn merge_qualified_usages_into_view(
view: &mut FindReferencesView,
mut usages: Vec<QualifiedUsage>,
mut seen_ranges: HashSet<(String, (u32, u32))>,
) {
let mut known_files: HashSet<String> = seen_ranges
.iter()
.map(|(file_path, _)| file_path.clone())
.collect();
known_files.extend(view.files.iter().map(|file| file.file_path.clone()));
usages.sort_by(|a, b| {
a.file_path
.cmp(&b.file_path)
.then(a.line.cmp(&b.line))
.then(a.byte_range.0.cmp(&b.byte_range.0))
});
let mut added = 0usize;
for usage in usages {
let range_key = (usage.file_path.clone(), usage.byte_range);
if !seen_ranges.insert(range_key) {
continue;
}
let hit = qualified_usage_hit_view(&usage);
if let Some(file_view) = view
.files
.iter_mut()
.find(|file| file.file_path == usage.file_path)
{
file_view.hits.push(hit);
} else {
view.files.push(ReferenceFileView {
file_path: usage.file_path.clone(),
hits: vec![hit],
});
}
known_files.insert(usage.file_path);
added += 1;
}
if added > 0 {
view.total_refs += added;
view.total_files = known_files.len();
view.files.sort_by(|a, b| a.file_path.cmp(&b.file_path));
}
}
fn implementations_parse_state_for_paths(
index: &LiveIndex,
view: &crate::live_index::ImplementationsView,
) -> &'static str {
search_parse_state_for_paths(
index,
view.entries.iter().map(|entry| entry.file_path.as_str()),
)
}
fn implementations_completeness_label(
view: &crate::live_index::ImplementationsView,
limits: &format::OutputLimits,
) -> String {
let shown = view
.entries
.len()
.min(limits.max_files * limits.max_per_file);
let omitted = view.entries.len().saturating_sub(shown);
if omitted == 0 {
"full for current scope".to_string()
} else {
format!("truncated by result cap ({omitted} implementation entry(s) omitted)")
}
}
fn implementations_evidence(view: &crate::live_index::ImplementationsView) -> String {
let anchors = view
.entries
.iter()
.take(3)
.map(|entry| format!("{}:{}", entry.file_path, entry.line + 1))
.collect();
anchored_search_evidence(anchors, "implementation anchors")
}
fn explore_is_test_like_path(
path: &str,
classification: Option<&crate::domain::index::FileClassification>,
) -> bool {
let path_lower = path.replace('\\', "/").to_ascii_lowercase();
classification.is_some_and(|c| c.is_test)
|| path_lower.contains("/tests/")
|| path_lower.contains("/test/")
|| path_lower.contains("/__tests__/")
|| path_lower.ends_with("/tests.rs")
|| path_lower.ends_with("/test.rs")
|| path_lower.ends_with("_test.rs")
|| path_lower.ends_with("_spec.rs")
}
fn explore_should_skip_path_boost(
path: &str,
classification: &crate::domain::index::FileClassification,
include_noise: bool,
include_vendor: bool,
include_personal_tooling: bool,
) -> bool {
let suppress_vendor = !(include_noise || include_vendor);
let suppress_personal = !(include_noise || include_personal_tooling);
let suppress_other = !include_noise;
if !suppress_vendor && !suppress_personal && !suppress_other {
return false;
}
if suppress_other && explore_is_test_like_path(path, Some(classification)) {
return true;
}
if suppress_personal && crate::live_index::query::is_personal_tooling_path(path) {
return true;
}
if suppress_vendor && classification.is_vendor {
return true;
}
if suppress_other && (classification.is_generated || classification.is_config) {
return true;
}
false
}
/// Whether a concept `text_query` legitimately matches `line` at a word
/// boundary, rather than as a coincidental substring inside a larger
/// identifier.
///
/// SF-STRESS-013: concept text queries are matched by plain case-insensitive
/// substring, so `"try {"` substring-matches `public string Country { ... }`
/// (`coun-TRY-{`) and floods DTO-property results into "Error Handling". When a
/// query begins with an identifier token, we require the character immediately
/// before the match to be a non-word character (or the line start), so the
/// token sits on a real word boundary. Queries that begin with punctuation
/// (e.g. `.expect(`, `#[derive(Serialize`) are already specific and pass
/// through unchanged. This only *rejects* false positives in explore; it never
/// invents new matches.
fn concept_text_query_matches_on_boundary(line: &str, query: &str) -> bool {
let line_lower = line.to_ascii_lowercase();
let query_lower = query.to_ascii_lowercase();
// Anchor token = the leading run of word characters in the query.
let anchor: String = query_lower
.chars()
.take_while(|c| c.is_ascii_alphanumeric() || *c == '_')
.collect();
if anchor.is_empty() {
// Punctuation-led query (e.g. `.expect(`); substring containment is the
// intended semantics and already specific.
return line_lower.contains(&query_lower);
}
// Require at least one occurrence of the full query whose anchor token sits
// on a left word boundary.
let anchor_bytes = anchor.as_bytes();
let mut start = 0usize;
while let Some(rel) = line_lower[start..].find(&query_lower) {
let pos = start + rel;
let left_ok = pos == 0
|| !line_lower.as_bytes()[pos - 1].is_ascii_alphanumeric()
&& line_lower.as_bytes()[pos - 1] != b'_';
if left_ok {
// Anchor is a prefix of the query, so the right boundary of the
// anchor is the char at pos + anchor.len(); for code idioms the
// query already includes the trailing delimiter (e.g. `unwrap()`),
// so a left boundary is sufficient to reject identifier-internal
// hits like `coun|try {`.
debug_assert!(query_lower.as_bytes().starts_with(anchor_bytes));
return true;
}
// Advance past this occurrence to keep scanning.
start = pos + 1;
if start >= line_lower.len() {
break;
}
}
false
}
fn explore_path_penalty(
path: &str,
classification: Option<&crate::domain::index::FileClassification>,
) -> u64 {
let path_lower = path.replace('\\', "/").to_ascii_lowercase();
if explore_is_test_like_path(path, classification) {
return 2;
}
if classification.is_some_and(|c| c.is_config)
|| path_lower.ends_with(".md")
|| path_lower.ends_with(".html")
|| path_lower.ends_with(".htm")
|| path_lower.contains("/docs/")
|| path_lower.contains("/doc/")
|| path_lower.contains("/plans/")
|| path_lower.contains("/manual/")
|| path_lower.contains("changelog")
|| path_lower.contains(".planning/")
|| path_lower.contains(".auto-claude")
{
return 2;
}
if path_lower.contains("/examples/")
|| path_lower.contains("/fixtures/")
|| path_lower.contains("/bench/")
|| path_lower.contains("/benches/")
|| path_lower.contains("/sample/")
|| path_lower.contains("/samples/")
{
return 3;
}
8
}
// Explore scorer tuning (US2). The score blends a saturating NAME signal with an
// additive concept-PROXIMITY term instead of multiplying correlated name-overlap
// factors. Caps keep both signals bounded so no single symbol can run away and
// pin the max-normalized top to 1.00 while the rest crater. W_NAME >= W_PROX
// guarantees an exact-name query still ranks its target at/near the top.
const EXPLORE_RAW_CAP: u64 = 8;
const EXPLORE_COVERAGE_CAP: u64 = 8;
const EXPLORE_PROX_CAP: u64 = 12;
const EXPLORE_W_NAME: u64 = 3;
const EXPLORE_W_PROX: u64 = 2;
fn explore_fallback_alignment_multiplier(
query_term_count: usize,
matched_term_count: usize,
) -> u64 {
if query_term_count <= 1 {
return 8;
}
match (query_term_count, matched_term_count) {
(_, 0) => 1,
(2, 1) => 3,
(2, _) => 8,
(3, 1) => 2,
(3, 2) => 6,
(3, _) => 8,
(_, 1) => 1,
(_, 2) => 4,
_ => 8,
}
}
fn changed_paths_completeness_label(before_filter: usize, after_filter: usize) -> String {
if before_filter == after_filter {
"full for current scope".to_string()
} else {
format!("full for filtered scope ({after_filter} of {before_filter} path(s) shown)")
}
}
fn what_changed_scope_summary(input: &WhatChangedInput, mode: &WhatChangedMode) -> String {
let mut parts = Vec::new();
match mode {
WhatChangedMode::Timestamp(since_ts) => parts.push(format!("timestamp since `{since_ts}`")),
WhatChangedMode::Uncommitted => parts.push("uncommitted working tree".to_string()),
WhatChangedMode::GitRef(git_ref) => {
parts.push(format!("git diff from `{git_ref}` to `HEAD`"))
}
}
if let Some(path_prefix) = input
.path_prefix
.as_deref()
.filter(|prefix| !prefix.trim().is_empty())
{
parts.push(format!(
"path prefix `{}`",
normalize_exact_path(path_prefix)
));
}
if let Some(language) = input.language.as_deref() {
parts.push(format!("language `{language}`"));
}
// US1 (018) III trust: disclose the code-only filter whenever it is
// actually applied. Uncommitted mode now defaults it on (FR-001), so the
// effective default is mode-scoped and must match the handler's sites.
let code_only_default = matches!(mode, WhatChangedMode::Uncommitted);
if input.code_only.unwrap_or(code_only_default) {
parts.push("code-only filter".to_string());
}
if input.include_symbol_diff.unwrap_or(false) {
parts.push("symbol diff appended".to_string());
}
parts.join("; ")
}
fn what_changed_source_authority_label(mode: &WhatChangedMode) -> &'static str {
match mode {
WhatChangedMode::Timestamp(_) => "current index",
WhatChangedMode::Uncommitted => "git working tree",
WhatChangedMode::GitRef(_) => "git ref diff",
}
}
fn what_changed_parse_state_label(
mode: &WhatChangedMode,
include_symbol_diff: bool,
) -> &'static str {
match mode {
WhatChangedMode::Timestamp(_) => "parsed",
_ if include_symbol_diff => {
"degraded (git path diff + lexical symbol diff — regex extraction may miss nested symbols)"
}
_ => "not-applicable (git path diff)",
}
}
#[allow(clippy::too_many_arguments)]
fn render_diff_symbols_output(
base: &str,
target: &str,
all_changed_files: usize,
changed_files: &[&str],
repo: &crate::git::GitRepo,
live: &crate::live_index::LiveIndex,
compact: bool,
summary_only: bool,
path_prefix: Option<&str>,
language: Option<&str>,
code_only: bool,
) -> String {
let mut scope_parts = vec![format!("git diff `{base}`...`{target}`")];
if let Some(path_prefix) = path_prefix.filter(|prefix| !prefix.trim().is_empty()) {
scope_parts.push(format!(
"path prefix `{}`",
normalize_exact_path(path_prefix)
));
}
if let Some(language) = language {
scope_parts.push(format!("language `{language}`"));
}
if code_only {
scope_parts.push("code-only filter".to_string());
}
if compact {
scope_parts.push("compact output".to_string());
}
if summary_only {
scope_parts.push("summary-only output".to_string());
}
let completeness = if changed_files.len() == all_changed_files {
"full for filtered git delta".to_string()
} else {
format!(
"full for filtered git delta ({} of {} changed file(s) shown)",
changed_files.len(),
all_changed_files
)
};
let envelope = search_format::format_search_envelope(
"exact (git ref diff)",
"git ref diff",
"high (tree-sitter AST extraction for supported languages, regex fallback for others)",
&completeness,
&scope_parts.join("; "),
&search_paths_evidence(changed_files.iter().copied()),
);
let output = format::diff_symbols_result_view(
base,
target,
changed_files,
repo,
live,
compact,
summary_only,
);
format!("{envelope}\n\n{output}")
}
/// Strip vendor / personal-tooling paths from a `TextSearchResult` per the
/// caller's `include_vendor` / `include_personal_tooling` flags. Suppressed
/// match counts feed `suppressed_by_noise`, which renders into the existing
/// "N noise-filtered match(es) suppressed" envelope footer.
fn apply_path_predicate_filter(
result: &mut Result<search::TextSearchResult, search::TextSearchError>,
include_vendor: bool,
include_personal_tooling: bool,
) {
if include_vendor && include_personal_tooling {
return;
}
if let Ok(r) = result {
let mut filtered: usize = 0;
r.files.retain(|file| {
if !include_vendor && crate::live_index::query::is_vendor_path(&file.path) {
filtered += file.matches.len();
return false;
}
if !include_personal_tooling
&& crate::live_index::query::is_personal_tooling_path(&file.path)
{
filtered += file.matches.len();
return false;
}
true
});
r.suppressed_by_noise = r.suppressed_by_noise.saturating_add(filtered);
}
}
#[allow(clippy::too_many_arguments)]
fn render_search_text_output(
server: &SymForgeServer,
result: Result<search::TextSearchResult, search::TextSearchError>,
query: Option<&str>,
structural: bool,
group_by: Option<&str>,
terms: Option<&[String]>,
options: &search::TextSearchOptions,
is_regex: bool,
auto_detected_regex: bool,
auto_corrected_regex: bool,
) -> String {
let envelope = match &result {
Ok(result) if !result.files.is_empty() => {
let guard = server.index.read();
Some(search_format::format_search_envelope(
&search_text_match_type_label(
structural,
is_regex,
terms,
auto_detected_regex,
auto_corrected_regex,
options.ranked,
),
index_source_authority_label(&server.index.freshness_status()),
search_parse_state_for_paths(
&guard,
result.files.iter().map(|file| file.path.as_str()),
),
&search_completeness_label(result.overflow_count, result.suppressed_by_noise),
&search_scope_summary(
&options.path_scope,
options.language_filter.as_ref(),
&options.noise_policy,
options.include_personal_tooling,
options.glob.as_deref(),
options.exclude_glob.as_deref(),
options.ranked,
),
&search_text_evidence(result),
))
}
_ => None,
};
let matching_untracked_paths = match &result {
Ok(result) if result.files.is_empty() && result.suppressed_by_noise == 0 => {
matching_untracked_paths_for_search_text(
server, query, terms, structural, is_regex, options,
)
}
_ => Vec::new(),
};
let confidence = if auto_corrected_regex {
0.75f32
} else if is_regex && auto_detected_regex {
0.80
} else if is_regex {
0.85
} else if options.ranked {
0.80
} else {
0.95
};
let output = format::search_text_result_view(
result,
group_by,
terms,
Some(confidence),
format::SearchSuggestionContext {
regex: is_regex,
include_tests: options.noise_policy.include_tests,
multi_word_literal: !is_regex
&& query.is_some_and(|q| q.trim().contains(char::is_whitespace)),
},
);
let mut rendered = match envelope {
Some(envelope) => format!("{envelope}\n\n{output}"),
None => output,
};
append_untracked_file_diagnostic(&mut rendered, &matching_untracked_paths);
rendered
}
fn search_text_compaction_query(query: Option<&str>, terms: Option<&[String]>) -> String {
if let Some(q) = query.filter(|s| !s.trim().is_empty()) {
return q.to_string();
}
terms
.map(|items| {
items
.iter()
.map(String::as_str)
.collect::<Vec<_>>()
.join(" ")
})
.unwrap_or_default()
}
fn maybe_compact_text_search_result(
result: &mut Result<search::TextSearchResult, search::TextSearchError>,
query: &str,
) {
if query.trim().is_empty() {
return;
}
if let Ok(text) = result {
crate::protocol::ccr::compact_text_search_result(text, query);
}
}
fn resolve_text_search_enclosing_symbols(
index: &LiveIndex,
result: &mut Result<search::TextSearchResult, search::TextSearchError>,
) {
let Ok(result) = result else {
return;
};
for file_matches in &mut result.files {
let Some(file) = index.get_file(&file_matches.path) else {
continue;
};
for line_match in &mut file_matches.matches {
let zero_based_line = line_match.line_number.saturating_sub(1) as u32;
line_match.enclosing_symbol =
crate::domain::find_enclosing_symbol(&file.symbols, zero_based_line)
.and_then(|idx| file.symbols.get(idx as usize))
.map(|symbol| search::EnclosingMatchSymbol {
name: symbol.name.clone(),
kind: symbol.kind.to_string(),
line_range: symbol.line_range,
});
}
}
}
fn sidecar_state_for_server(server: &SymForgeServer) -> SidecarState {
SidecarState {
index: Arc::clone(&server.index),
token_stats: server.token_stats.clone().unwrap_or_else(TokenStats::new),
repo_root: server.capture_repo_root(),
symbol_cache: Arc::new(RwLock::new(HashMap::new())),
}
}
fn sidecar_status_for_server(server: &SymForgeServer) -> crate::sidecar::port_file::SidecarStatus {
let bind_host =
std::env::var("SYMFORGE_SIDECAR_BIND").unwrap_or_else(|_| "127.0.0.1".to_string());
let Some(control_state_dir) = server.capture_control_state_dir() else {
return crate::sidecar::port_file::SidecarStatus::no_sidecar();
};
let repo_root = server.capture_repo_root();
crate::sidecar::port_file::read_sidecar_status(
&control_state_dir,
&bind_host,
repo_root.as_deref(),
)
}
/// Best-effort PATH-shadow report for the binary serving this runtime.
///
/// Uses `std::env::current_exe()` as "our binary" and asks `path_shadow` whether
/// a bare `symforge` on `$PATH` would run a different install. Returns `None`
/// when we win, when there is no shadow, or when `current_exe()` is unresolvable.
fn current_exe_shadow_report() -> Option<crate::path_shadow::ShadowReport> {
let our_binary = std::env::current_exe().ok()?;
let mut report = crate::path_shadow::detect_shadow(&our_binary)?;
// `detect_shadow` probes our_version via a bounded `<binary> --version`
// subprocess, which can flake/time out under load — that produced
// "(version unknown)" on one health surface while another showed the real
// version in the same session. We ARE the running binary, so source our
// version from the compile-time package version instead of a subprocess.
// (Leave the shadow's version probed, since that is genuinely a foreign
// binary we cannot introspect statically.)
report.our_version = Some(env!("CARGO_PKG_VERSION").to_string());
Some(report)
}
/// Read-only `.gitignore` hygiene status for the health `gitignore_hygiene=`
/// field (source-binding-and-state.md Health contract). `None` when unbound.
/// Explicit-protected roots are not applicable (hygiene never touches a
/// protected root); every other bound root is observed without mutation via
/// `ObserveOnly` — the same code path bind/init use, never a second checker.
fn gitignore_hygiene_status(
repo_root: Option<&Path>,
placement: Option<&crate::domain::StatePlacement>,
) -> Option<&'static str> {
let root = repo_root?;
if matches!(
crate::protocol::format::placement_authorization(placement),
Some(crate::domain::SourceAccessMode::ExplicitProtected)
) {
return Some("not_applicable_explicit_protected");
}
Some(
crate::gitignore_hygiene::reconcile_project_gitignore(
root,
crate::gitignore_hygiene::GitignoreHygieneAuthority::ObserveOnly,
)
.status_label(),
)
}
/// Extract the `version=<token>` value emitted on the runtime-status line of a
/// `health` / `health_compact` report (see `format::format_runtime_status`).
///
/// The runtime line is ` | `-delimited, e.g.
/// `Runtime: mode=... | version=7.18.1 | project_root=...`, and round-2 guarantees
/// a `version=` token is present in EVERY mode (regression:
/// `test_runtime_status_includes_binary_version_in_every_mode`). Returns the raw
/// token (e.g. `"7.18.1"`) or `None` when no such token is present.
///
/// The `status` body (TR-01 proxy path) does NOT carry `version=`; it emits the
/// daemon binary version as `symforge_version: X` (status.rs). Accept that token
/// form too, so the staleness guard fires when `status` is proxied to a stale
/// daemon — not only when `health` is. Health is unaffected: its body always
/// carries `version=` (the regression above), so it takes the first branch.
fn extract_runtime_version(health_output: &str) -> Option<&str> {
let after = health_output
.split("version=")
.nth(1)
.or_else(|| health_output.split("symforge_version: ").nth(1))?;
// The version token runs until the next field separator, whitespace, or EOL.
let token = after
.split(['|', ' ', '\n', '\r', '\t'])
.next()
.map(str::trim)
.filter(|s| !s.is_empty())?;
Some(token)
}
/// LOUD operations guard (SF-001 / SF-009 root-cause class): when the MCP
/// front-end is proxying to a daemon, the daemon's reported binary version can be
/// OLDER than the front-end's own build — a stale/shadowed daemon serving
/// pre-fix behavior, which is exactly what masked the SF-001 fix during the audit.
///
/// Compares the daemon version parsed out of the proxied health report against the
/// front-end's `frontend_version` (its `env!("CARGO_PKG_VERSION")`). Returns a
/// warning string ONLY when the daemon version is strictly OLDER than the
/// front-end. Fail-safe by construction: a missing/unparseable token or an
/// equal/newer daemon yields `None` (no warning).
///
/// Product decision: WARN, do NOT auto-restart. Auto-restarting risks killing a
/// daemon mid-session for other clients; a loud, idempotent health warning is the
/// safe, sufficient remedy and tells the operator to reconnect/restart.
fn daemon_staleness_warning(proxied_health: &str, frontend_version: &str) -> Option<String> {
let daemon_version = extract_runtime_version(proxied_health)?;
// `is_newer_version(latest, current)` is true iff `latest` > `current`. The
// daemon is stale exactly when the front-end is newer than the daemon.
if !crate::cli::version::is_newer_version(frontend_version, daemon_version) {
return None;
}
Some(format!(
"\n── \u{26a0} Daemon serving stale code ──\n\
The MCP daemon answering this session reports version {daemon_version}, but this\n\
front-end is version {frontend_version} (newer). The daemon is serving an OLDER\n\
binary, so tool behavior may be stale (this is the operational root cause behind\n\
masked fixes such as SF-001). Reconnect your MCP client (e.g. /mcp) or restart the\n\
daemon so it picks up the newer binary; this is a WARNING only — no automatic\n\
restart is performed."
))
}
/// Append `daemon_staleness_warning` to a proxied health report when the daemon is
/// older than the front-end; otherwise return the report unchanged.
fn append_daemon_staleness_warning(mut proxied_health: String, frontend_version: &str) -> String {
if let Some(warning) = daemon_staleness_warning(&proxied_health, frontend_version) {
proxied_health.push_str(&warning);
}
proxied_health
}
/// Overlay ALL of the proxy's OWN ledger/store-derived lines onto a `status`
/// body proxied from the daemon worker (D2-ROOT — proxy-owned state invisible to
/// worker-rendered responses).
///
/// In the daemon-backed stdio default, `status` is proxied to the daemon WORKER,
/// which owns the populated INDEX but has an EMPTY session ledger and NO durable
/// store wired — so its body renders `ledger_events: 0`, `last_ledger_*: none`,
/// `durable_ledger: unavailable`, and `calibration: deferred`. But the PROXY
/// owns `stel_ledger` + `stel_ledger_store` (attached in `main.rs`), and
/// economics events accumulate THERE. The operator's one observability window
/// must show the proxy's truth, not the worker's blind spot.
///
/// This rewrites every proxy-owned line/block with the proxy's own rendering
/// (`proxy`, built once from `self.stel_ledger` + `self.stel_ledger_store` via
/// [`SymForgeServer::proxy_owned_status_lines`], so the overlaid text is
/// byte-identical to what the worker WOULD render if it had the proxy's state):
/// - `ledger_events:` (present in compact AND full bodies),
/// - `last_ledger_decision:` / `last_ledger_route:` (full only),
/// - `durable_ledger:` (full only),
/// - the whole `── calibration (observational) ──` … `──` block (full only).
///
/// The INDEX lines (`index_ready`/`index_files`/`index_symbols`/`project`) stay
/// the WORKER's — it owns the warm index (TR-01) — and are NEVER overlaid.
///
/// Honesty: if the proxy's ledger is empty / its store is `Unavailable`/
/// `Disabled`, the overlaid values reflect THAT truthfully (`ledger_events: 0`,
/// `last_ledger_*: none`, `durable_ledger: unavailable`, `calibration: deferred`)
/// — the overlay makes status reflect the PROXY's real state, whatever it is,
/// not the worker's blind zero, and never invents accumulation.
///
/// Each rewrite is guarded on the line/block actually being present: a
/// `detail:compact` worker body (only `ledger_events:`, no full-only lines or
/// calibration section) or an older worker missing a line is a no-op for the
/// absent parts — exactly like the original single-line durable overlay.
fn overlay_proxy_status_lines(
worker_body: String,
proxy: &crate::stel::ProxyOwnedStatusLines,
) -> String {
let trailing_newline = worker_body.ends_with('\n');
let lines: Vec<&str> = worker_body.lines().collect();
let mut out_lines: Vec<String> = Vec::with_capacity(lines.len());
let mut i = 0;
while i < lines.len() {
let line = lines[i];
if line.starts_with("ledger_events:") {
// Present in BOTH compact and full bodies — proxy's session length.
out_lines.push(proxy.ledger_events.clone());
} else if line.starts_with("last_ledger_decision:") {
out_lines.push(proxy.last_ledger_decision.clone());
} else if line.starts_with("last_ledger_route:") {
out_lines.push(proxy.last_ledger_route.clone());
} else if line.starts_with("durable_ledger:") {
out_lines.push(proxy.durable_ledger.clone());
} else if line == "── calibration (observational) ──" {
// Replace the WHOLE worker calibration block (header through its
// closing `──`) with the proxy's rendering, then skip past it. The
// block is the proxy-rendered section verbatim, so its line count may
// differ — we consume the worker block by structure, not by count.
for replacement_line in proxy.calibration_section.lines() {
out_lines.push(replacement_line.to_string());
}
// Advance the worker cursor past its calibration header...
i += 1;
// ...and past its body up to and including the section's closing
// `──` banner (the first standalone `──` after the header).
while i < lines.len() && lines[i] != "──" {
i += 1;
}
if i < lines.len() {
// Skip the closing `──` (already included by the replacement).
i += 1;
}
continue;
} else {
// Everything else — the static labels and the WORKER-owned index/
// project lines — is preserved verbatim.
out_lines.push(line.to_string());
}
i += 1;
}
let mut out = out_lines.join("\n");
// Preserve a trailing newline if the original body had one (joining lines
// drops it), so the overlay is byte-faithful apart from the swapped lines.
if trailing_newline {
out.push('\n');
}
out
}
fn symbol_candidate_paths(index: &crate::live_index::store::LiveIndex, name: &str) -> Vec<String> {
let mut candidates: Vec<String> = index
.all_files()
.filter_map(|(path, file)| {
if file.symbols.iter().any(|s| s.name == name) {
Some(path.to_string())
} else {
None
}
})
.collect();
candidates.sort();
candidates.dedup();
candidates
}
fn format_ambiguous_symbol_context(name: &str, candidates: &[String]) -> String {
let mut output = format!(
"Ambiguous symbol selector: {} symbols named \"{}\" found.\nPass `path` or `file` to disambiguate.\nCandidate paths:",
candidates.len(),
name
);
for path in candidates {
output.push_str(&format!("\n- {path}"));
}
output
}
fn render_symbol_context_header(
file: &IndexedFile,
name: &str,
symbol_kind: Option<&str>,
symbol_line: Option<u32>,
verbosity: &str,
max_tokens: Option<u64>,
) -> Option<String> {
use crate::live_index::query::{SymbolSelectorMatch, resolve_symbol_selector};
match resolve_symbol_selector(file, name, symbol_kind, symbol_line) {
SymbolSelectorMatch::Selected(_, sym) => {
let body = std::str::from_utf8(
&file.content[sym.byte_range.0 as usize..sym.byte_range.1 as usize],
)
.ok()?;
let (rendered, actual_level) = format::resolve_verbosity(
body,
Some(verbosity),
max_tokens,
0.7, // standalone symbol — allocate 70% of budget to body
);
let mut output = format!(
"{}\n[{}, {}:{}-{}]",
rendered,
sym.kind,
file.relative_path,
sym.line_range.0 + 1,
sym.line_range.1 + 1
);
if actual_level != "full" && actual_level != verbosity {
output.push_str(&format!(
"\n[adaptive verbosity: {} — fits within {} token budget]",
actual_level,
max_tokens.unwrap_or(0)
));
}
Some(output)
}
SymbolSelectorMatch::NotFound | SymbolSelectorMatch::Ambiguous(_) => None,
}
}
fn capture_trace_symbol_view_for_generation(
published: &crate::live_index::PublishedGeneration,
params: &TraceSymbolInput,
sections: Option<&[String]>,
) -> crate::live_index::TraceSymbolView {
let mut trace_view = published.live.capture_trace_symbol_view(
¶ms.path,
¶ms.name,
params.kind.as_deref(),
params.symbol_line,
sections,
include_tests_from_sections(params.sections.as_ref()),
);
if let crate::live_index::TraceSymbolView::Found(ref mut found) = trace_view {
let wants_git = sections
.map(|values| values.iter().any(|value| value.eq_ignore_ascii_case("git")))
.unwrap_or(true);
if wants_git {
let temporal = &published.code_signals.temporal;
if temporal.state == crate::live_index::git_temporal::GitTemporalState::Ready
&& let Some(history) = temporal.files.get(¶ms.path)
{
use crate::live_index::git_temporal::{churn_bar, churn_label, relative_time};
found.git_activity = Some(crate::live_index::GitActivityView {
churn_score: history.churn_score,
churn_bar: churn_bar(history.churn_score),
churn_label: churn_label(history.churn_score).to_string(),
commit_count: history.commit_count,
last_relative: relative_time(history.last_commit.days_ago),
last_hash: history.last_commit.hash.clone(),
last_message: history.last_commit.message_head.clone(),
last_author: history.last_commit.author.clone(),
last_timestamp: history.last_commit.timestamp.clone(),
owners: history
.contributors
.iter()
.map(|contributor| {
format!("{} {:.0}%", contributor.author, contributor.percentage)
})
.collect(),
co_changes: history
.co_changes
.iter()
.map(|entry| {
(
entry.path.clone(),
entry.coupling_score,
entry.shared_commits,
)
})
.collect(),
});
}
}
}
trace_view
}
enum CapturedGetSymbolsEntry {
SymbolLookup {
file: Arc<IndexedFile>,
name: String,
kind: Option<String>,
symbol_line: Option<u32>,
},
CodeSlice {
file: Arc<IndexedFile>,
start_byte: usize,
end_byte: Option<usize>,
},
FileNotFound {
path: String,
},
}
// ─── Tool handlers ───────────────────────────────────────────────────────────
/// Loading guard helper — returns `Some(message)` when index is NOT ready.
///
/// Call at the top of every handler except `health`. If `Some` is returned,
/// return that string immediately. Otherwise continue with the handler body.
macro_rules! loading_guard {
($guard:expr) => {
match $guard.index_state() {
IndexState::Ready => {}
IndexState::Empty => return format::empty_guard_message(),
IndexState::Loading => return format::loading_guard_message(),
IndexState::CircuitBreakerTripped { summary } => {
return format!("Index degraded: {summary}");
}
}
};
}
fn loading_guard_message_from_published(
published: &crate::live_index::PublishedIndexState,
) -> Option<String> {
match published.status {
crate::live_index::PublishedIndexStatus::Ready => None,
crate::live_index::PublishedIndexStatus::Empty => Some(format::empty_guard_message()),
crate::live_index::PublishedIndexStatus::Loading => Some(format::loading_guard_message()),
crate::live_index::PublishedIndexStatus::Degraded => Some(format!(
"Index degraded: {}",
published
.degraded_summary
.as_deref()
.unwrap_or("circuit breaker tripped")
)),
}
}
/// Outcome of a name-only `get_symbol` lookup (Wave 1 Fix 2).
enum SymbolNameLookup {
/// Exactly one match — path and canonical indexed symbol name.
Unique { path: String, symbol_name: String },
/// More than one exact-name match — a ready-to-return disambiguation listing.
Ambiguous(String),
/// No exact-name match — a ready-to-return loud not-found (D18 style).
NotFound(String),
}
/// Render the disambiguation listing for a name-only `get_symbol` hit that
/// matched multiple symbols. Shows path + start line + kind per candidate,
/// capped at 20 with a count disclosure, and names how to disambiguate.
fn render_symbol_name_ambiguity(
name: &str,
hits: &[crate::live_index::search::SymbolSearchHit],
overflowed: bool,
) -> String {
const MAX_CANDIDATES: usize = 20;
// Under the 500-hit search cap the exact count can under-report; when the
// search overflowed, disclose the total as a lower bound (Wave 1 Fix 4).
let total = if overflowed {
format!("more than {}", hits.len())
} else {
hits.len().to_string()
};
let mut output = format!(
"Ambiguous symbol selector: {total} symbols named \"{name}\" found across the index.\n\
Pass `path` (and `symbol_line` if a file has several) to disambiguate.\n\
Candidates:",
);
for hit in hits.iter().take(MAX_CANDIDATES) {
output.push_str(&format!(
"\n- {} (line {}, {})",
hit.path, hit.line, hit.kind
));
}
if hits.len() > MAX_CANDIDATES {
output.push_str(&format!(
"\n... and {} more (use search_symbols to list them all)",
hits.len() - MAX_CANDIDATES
));
}
output
}
#[tool_router(router = core_tool_router, vis = "pub(crate)")]
impl SymForgeServer {
/// Resolve a bare symbol `name` (no path) to a file path by an EXACT
/// name search across the index, honoring the `kind` filter and the
/// `symbol_line` disambiguator (Wave 1 Fix 2). Reuses the same search
/// machinery `search_symbols` uses so name resolution is consistent with it.
fn resolve_symbol_path_by_name(
&self,
name: &str,
kind: Option<&str>,
symbol_line: Option<u32>,
) -> SymbolNameLookup {
use crate::live_index::search::{
ResultLimit, SymbolMatchTier, SymbolSearchOptions, search_symbols_with_options,
};
let guard = self.index.read();
// Permissive noise policy (the default) so a symbol defined only in a
// test/vendor/generated file is still resolvable by exact name — an
// explicit path already reaches those files. A generous limit keeps the
// ambiguity count honest without changing the O(symbols) scan cost.
let options = SymbolSearchOptions {
result_limit: ResultLimit::new(500),
..Default::default()
};
let result = search_symbols_with_options(&guard, name, kind, &options);
// Under the 500-hit search cap, `overflow_count > 0` means more matches
// exist than were returned, so the ambiguity total must be a lower bound,
// never an exact under-report (Wave 1 Fix 4).
let overflowed = result.overflow_count > 0;
let hits = result.hits;
// Exact tier + exact (case-sensitive) name only — a name selector must
// not silently resolve to a prefix/substring neighbor.
let mut exact: Vec<crate::live_index::search::SymbolSearchHit> = hits
.iter()
.filter(|hit| hit.tier == SymbolMatchTier::Exact && hit.name == name)
.cloned()
.collect();
// `symbol_line` narrows to matches at that 1-based start line when it
// resolves at least one candidate (e.g. two files, one line each).
if let Some(line) = symbol_line {
let narrowed: Vec<_> = exact
.iter()
.filter(|hit| hit.line == line)
.cloned()
.collect();
if !narrowed.is_empty() {
exact = narrowed;
}
}
match exact.len() {
0 => {
// Kind-mismatch guard (Wave 1 Fix 1): before claiming the name is
// absent, re-check WITHOUT the kind filter. If it exists under other
// kinds, "No symbol named X" is factually false — name the kinds it
// DOES have so the caller can drop or correct the filter.
if let Some(requested_kind) = kind {
let unfiltered = search_symbols_with_options(&guard, name, None, &options);
let mut kinds: Vec<String> = unfiltered
.hits
.into_iter()
.filter(|hit| hit.tier == SymbolMatchTier::Exact && hit.name == name)
.map(|hit| hit.kind)
.collect();
kinds.sort();
kinds.dedup();
if !kinds.is_empty() {
return SymbolNameLookup::NotFound(format!(
"`{name}` exists in the index, but not as kind={requested_kind} \
(found: {}). Drop the kind filter or pass the correct kind.",
kinds.join(", ")
));
}
}
// Unique snake_case prefix (`reconcile` → `reconcile_orders`) when the
// query names a single indexed symbol unambiguously.
if kind.is_none() {
let prefix: Vec<_> = hits
.iter()
.filter(|hit| {
hit.tier == SymbolMatchTier::Prefix
&& hit.name.starts_with(name)
&& hit.name.as_bytes().get(name.len()) == Some(&b'_')
})
.cloned()
.collect();
if prefix.len() == 1 {
return SymbolNameLookup::Unique {
path: prefix[0].path.clone(),
symbol_name: prefix[0].name.clone(),
};
}
}
SymbolNameLookup::NotFound(format!(
"No symbol named `{name}` in the index. \
Use search_symbols(query=\"{name}\") for a fuzzy lookup, \
or pass an explicit `path` if the file is not indexed."
))
}
1 => SymbolNameLookup::Unique {
path: exact[0].path.clone(),
symbol_name: exact[0].name.clone(),
},
_ => {
SymbolNameLookup::Ambiguous(render_symbol_name_ambiguity(name, &exact, overflowed))
}
}
}
/// Look up symbol(s) by file path and name. Single mode: provide path + name for one symbol.
/// Batch mode: provide targets[] array for multiple symbols or code slices in one call.
/// When multiple symbols share the same name (e.g. `handle` in different impl blocks),
/// pass symbol_line (1-based) to disambiguate; omitting it auto-selects by kind tier or
/// returns an Ambiguous error listing candidate lines.
/// NOT for finding symbols by name (use search_symbols first).
/// NOT for understanding who calls it (use find_references or get_symbol_context).
/// NOT for edit preparation (use get_symbol_context with bundle=true).
#[tool(
name = "get_symbol",
description = "Prefer this over reading an entire file when you already know the symbol or have narrowed to one file. Retrieves the complete source code of a specific symbol with doc comments. Single mode: provide path + name. Batch mode: provide targets[] array for 2+ symbols or code slices in one call (each target is file path + symbol name or byte range). When multiple symbols share the same name, pass symbol_line (1-based) to disambiguate; auto-selects by kind tier when possible. Use search_symbols first if you only know part of the name. NOT for understanding callers (use find_references or get_symbol_context). NOT for edit preparation (use get_symbol_context with bundle=true).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn get_symbol_tool(
&self,
params: Parameters<GetSymbolInput>,
) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
let started = Instant::now();
let output = self.get_symbol(params).await;
let outcome_class = classify_get_symbol_output(&output);
self.record_tool_completion("get_symbol", &output, started.elapsed(), outcome_class);
statused_tool_result(output, outcome_class)
}
pub(crate) async fn get_symbol(&self, params: Parameters<GetSymbolInput>) -> String {
if let Some(result) = self.proxy_tool_call("get_symbol", ¶ms.0).await {
return result;
}
if let Some(refusal) = self.foreign_project_refusal(params.0.project.as_deref()) {
return refusal;
}
// Batch mode: targets[] provided
if let Some(ref targets) = params.0.targets {
if targets.is_empty() {
return "Error: targets array is empty.".to_string();
}
let captured = {
let guard = self.index.read();
loading_guard!(guard);
targets
.iter()
.map(|target| match target.name.as_deref() {
Some(name) => match guard.capture_shared_file(&target.path) {
Some(file) => CapturedGetSymbolsEntry::SymbolLookup {
file,
name: name.to_string(),
kind: target.kind.clone(),
symbol_line: target.symbol_line,
},
None => CapturedGetSymbolsEntry::FileNotFound {
path: target.path.clone(),
},
},
None => match guard.capture_shared_file(&target.path) {
None => CapturedGetSymbolsEntry::FileNotFound {
path: target.path.clone(),
},
Some(file) => CapturedGetSymbolsEntry::CodeSlice {
file,
start_byte: target.start_byte.unwrap_or(0) as usize,
end_byte: target.end_byte.map(|e| e as usize),
},
},
})
.collect::<Vec<_>>()
};
// Frecency bump — batch commitment path. Collect the file path
// for every resolved entry (skip FileNotFound since we did not
// actually touch them), dedup, and emit one bump call at the end
// per Implementation Notes §"Bump dedup per tool invocation".
// Collection policy is resolved inside bump_frecency.
let bump_paths: Vec<PathBuf> = captured
.iter()
.filter_map(|entry| match entry {
CapturedGetSymbolsEntry::SymbolLookup { file, .. }
| CapturedGetSymbolsEntry::CodeSlice { file, .. } => {
Some(PathBuf::from(&file.relative_path))
}
CapturedGetSymbolsEntry::FileNotFound { .. } => None,
})
.collect::<std::collections::HashSet<_>>()
.into_iter()
.collect();
let batch_baseline_chars: usize = captured
.iter()
.filter_map(|entry| match entry {
CapturedGetSymbolsEntry::SymbolLookup { file, .. }
| CapturedGetSymbolsEntry::CodeSlice { file, .. } => Some(
format::competent_manual_baseline_chars(file.as_ref().content.len()),
),
CapturedGetSymbolsEntry::FileNotFound { .. } => None,
})
.sum();
let output = captured
.into_iter()
.map(|entry| match entry {
CapturedGetSymbolsEntry::SymbolLookup {
file,
name,
kind,
symbol_line,
} => format::symbol_detail_from_indexed_file(
file.as_ref(),
&name,
kind.as_deref(),
symbol_line,
),
CapturedGetSymbolsEntry::CodeSlice {
file,
start_byte,
end_byte,
} => format::code_slice_from_indexed_file(file.as_ref(), start_byte, end_byte),
CapturedGetSymbolsEntry::FileNotFound { path } => format::not_found_file(&path),
})
.collect::<Vec<_>>()
.join("\n---\n");
// No next-step tip: always-on tips measured as saturation, not
// steering (2026-07-03 spike gate, B5) — tips stay rare + contextual.
self.record_tool_savings_named(
"get_symbol",
format::estimate_tokens_from_chars(batch_baseline_chars),
(output.len() / 4) as u64,
);
self.bump_frecency(&bump_paths);
return output;
}
// Single mode: path + name
let mut params = params;
// Name-only lookup (Wave 1 Fix 2): `path` is OPTIONAL. When the caller
// supplies a `name` but no `path`, resolve the path by an EXACT name
// search across the index (the same machinery `search_symbols` uses),
// honoring `kind` and the `symbol_line` disambiguator. This also powers
// the compact `read` intent, which routes here via the STEL planner —
// one fix, two surfaces. Both empty (and no `targets`) is a clean
// invalid-request, never `File not found: .`.
let mut resolved_from_bare_name: Option<String> = None;
if params.0.path.trim().is_empty() {
if params.0.name.trim().is_empty() {
return "Invalid request: get_symbol needs a `name` (optionally with `path`), \
or a `targets` array. Add `path`/`symbol_line` to disambiguate a common \
name, or use search_symbols for a fuzzy lookup."
.to_string();
}
match self.resolve_symbol_path_by_name(
params.0.name.trim(),
params.0.kind.as_deref(),
params.0.symbol_line,
) {
SymbolNameLookup::Unique { path, symbol_name } => {
// Dogfood #2 (2026-07-06): a bare-name pick must SAY which
// file it resolved to — the caller cannot tell a TypeScript
// alias from a Rust struct by the body alone.
resolved_from_bare_name = Some(path.clone());
params.0.path = path;
params.0.name = symbol_name;
}
SymbolNameLookup::Ambiguous(message) | SymbolNameLookup::NotFound(message) => {
return message;
}
}
}
let force_refresh = params.0.force_refresh == Some(true);
let params_hash = crate::protocol::session::hash_symbol_params(
params.0.kind.as_deref(),
params.0.symbol_line,
params.0.max_tokens,
);
if let Some(meta) = self.session_context.try_symbol_cache_hit(
¶ms.0.path,
¶ms.0.name,
params_hash,
force_refresh,
) {
return self.format_read_cache_hit(&meta, "session_repeat_read");
}
let file = {
// The single-project overlay READ was REMOVED: it was redundant (the
// shared live index already holds the edit via reindex_after_write) and
// carried a narrow staleness shadow risk (overlay-first with no freshness
// gate could shadow a base advanced by a watcher event). The base read is
// always at-least-as-fresh. See
// docs/reviews/overlay-redundancy-decision.md.
let guard = self.index.read();
loading_guard!(guard);
guard.capture_shared_file(¶ms.0.path)
};
// Honest Tier-2/Tier-3 response before any miss handling: a path like
// package-lock.json EXISTS but is admitted metadata-only, so it has no
// symbols to return. Name the tier and point at get_file_content for raw
// reads instead of "File not found". Only runs when the file is not in
// the index (Tier-1 files resolve above).
if file.is_none() {
let repo_root = self.capture_repo_root();
let degraded = {
let guard = self.index.read();
loading_guard!(guard);
admission_tier_file_degradation_for_path(
&guard,
repo_root.as_deref(),
¶ms.0.path,
)
};
if let Some(result) = degraded {
return result;
}
}
// Estimate mode: return token cost without full content
if params.0.estimate == Some(true) {
if let Some(ref file) = file {
let file_tokens = file.content.len() / 4;
let sym_tokens = file
.symbols
.iter()
.find(|s| s.name == params.0.name)
.map(|s| (s.byte_range.1 - s.byte_range.0) as usize / 4)
.unwrap_or(0);
return format!(
"Estimate for get_symbol(path=\"{}\", name=\"{}\"):\n Symbol body: ~{} tokens\n Raw file: ~{} tokens",
params.0.path, params.0.name, sym_tokens, file_tokens
);
} else {
return format::not_found_file(¶ms.0.path);
}
}
match file {
Some(file) => {
let raw_chars = file.content.len();
let body = format::symbol_detail_from_indexed_file(
file.as_ref(),
¶ms.0.name,
params.0.kind.as_deref(),
params.0.symbol_line,
);
let output = match &resolved_from_bare_name {
Some(path) => format!(
"Resolved bare name to {path} — pass `path` (and `symbol_line`) \
to pin a different same-named symbol.\n{body}"
),
None => body,
};
let max_tokens = format::resolve_read_max_tokens(params.0.max_tokens, raw_chars);
self.record_tool_savings_named(
"get_symbol",
format::estimate_tokens_from_chars(format::competent_manual_baseline_chars(
raw_chars,
)),
(output.len() / 4) as u64,
);
let tokens = (output.len() / 4) as u32;
let prior_dedup = if force_refresh {
self.session_context.prior_fetch_for_dedup(
crate::protocol::session::FetchKind::Symbol,
¶ms.0.path,
¶ms.0.name,
params_hash,
)
} else {
None
};
self.session_context.record_symbol_fetch(
¶ms.0.path,
¶ms.0.name,
params_hash,
tokens,
);
// Frecency bump — commitment tool, single-symbol happy path.
// Collection policy is resolved inside bump_frecency. See wiki
// `[[SymForge Frecency-Weighted File Ranking]]` §"Bump hooks".
self.bump_frecency(&[PathBuf::from(¶ms.0.path)]);
let mut final_output = format::enforce_token_budget(output, Some(max_tokens));
if force_refresh && let Some(prior) = prior_dedup {
final_output = format::append_dedup_hint_footer(
final_output,
"symbol",
prior.fetched_at.elapsed().as_secs(),
prior.approx_tokens,
);
}
final_output
}
None => {
let suggestions = {
let guard = self.index.read();
suggest_similar_files(&guard, ¶ms.0.path)
};
format::not_found_file_with_suggestions(¶ms.0.path, &suggestions)
}
}
}
/// Start here. Project overview with adjustable detail level. Modes: (1) default/compact: ~500 token
/// overview with file count, languages, and directory tree. (2) detail='full': complete symbol outline
/// of every file — warning: large output. (3) detail='tree': browsable file tree with per-file symbol
/// counts and language tags — supports path and depth params for subtree browsing.
/// NOT for file details (use get_file_context) or finding symbols (use search_symbols).
#[tool(
description = "Start here for project orientation and the first code-reading pass before any broad raw file read. Returns a structural overview of the repository. Modes: (1) default/compact: ~500 token overview with file count, languages, and directory tree. (2) detail='full': complete symbol outline of every file — warning: large output; may CCR-compress with symforge_retrieve hash when over max_tokens. (3) detail='tree': browsable file tree with per-file symbol counts and language tags — supports path and depth params for subtree browsing. NOT for file details (use get_file_context) or finding symbols (use search_symbols).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn get_repo_map(&self, params: Parameters<GetRepoMapInput>) -> String {
if let Some(result) = self.proxy_tool_call("get_repo_map", ¶ms.0).await {
return result;
}
if let Some(refusal) = self.foreign_project_refusal(params.0.project.as_deref()) {
return refusal;
}
// Single loading guard covering EVERY local path (estimate, compact, and
// the `full`/`tree` outline branches), consistent with how
// `search_symbols`/`search_text` guard at the top. Without this, an
// outline-only call on an empty/unloaded index could fall through to a
// bare empty map instead of the "index still loading / run index_folder"
// guidance. The per-branch guards below remain as harmless redundancy.
{
let guard = self.index.read();
loading_guard!(guard);
}
let published = self.index.published_generation();
if params.0.estimate == Some(true) {
let file_count = published.live.file_count();
let detail = params.0.detail.as_deref().unwrap_or("compact");
let est = match detail {
"full" => {
let max = params.0.max_files.unwrap_or(200) as usize;
max.min(file_count) * 30
}
"tree" => file_count * 10,
_ => 500,
};
return format!(
"Estimate for get_repo_map: ~{} tokens (detail={}, files={})",
est, detail, file_count
);
}
let detail = if let Some(ref d) = params.0.detail {
d.as_str()
} else if let Some(max_tokens) = params.0.max_tokens {
// Adaptive detail: auto-select "full" when the estimated output fits
// within the token budget, otherwise fall back to "compact".
let file_count = published.live.file_count();
let max_files = params.0.max_files.unwrap_or(200) as usize;
let full_estimate = max_files.min(file_count) * 30;
if (full_estimate as u64) <= max_tokens {
"full"
} else {
"compact"
}
} else {
"compact"
};
let mut output = match detail {
"full" => {
if let Some(message) = loading_guard_message_from_published(&published.health) {
return message;
}
let view = Arc::clone(&published.outline);
if let Some(ref path) = params.0.path {
// Filter outline to files under the given path prefix
let filtered_files: Vec<_> = view
.files
.iter()
.filter(|fo| fo.relative_path.starts_with(path.as_str()))
.cloned()
.collect();
let filtered_symbols: usize =
filtered_files.iter().map(|f| f.symbol_count).sum();
let filtered_view = crate::live_index::query::RepoOutlineView {
total_files: filtered_files.len(),
total_symbols: filtered_symbols,
files: filtered_files,
};
let max_files = params.0.max_files.unwrap_or(200) as usize;
if filtered_view.files.len() > max_files {
let remaining = filtered_view.files.len() - max_files;
let truncated_files: Vec<_> = filtered_view
.files
.iter()
.take(max_files)
.cloned()
.collect();
let truncated_view = crate::live_index::query::RepoOutlineView {
total_files: filtered_view.total_files,
total_symbols: filtered_view.total_symbols,
files: truncated_files,
};
let mut output =
format::repo_outline_view(&truncated_view, &self.project_name);
output.push_str(&format!(
"\n\n... and {} more files (increase max_files= to see more)",
remaining
));
output
} else {
format::repo_outline_view(&filtered_view, &self.project_name)
}
} else {
let max_files = params.0.max_files.unwrap_or(200) as usize;
if view.files.len() > max_files {
let truncated_files: Vec<_> =
view.files.iter().take(max_files).cloned().collect();
let remaining = view.files.len() - max_files;
let truncated_view = crate::live_index::query::RepoOutlineView {
total_files: view.total_files,
total_symbols: view.total_symbols,
files: truncated_files,
};
let mut output =
format::repo_outline_view(&truncated_view, &self.project_name);
output.push_str(&format!(
"\n\n... and {} more files (use path= to scope or increase max_files=)",
remaining
));
output
} else {
format::repo_outline_view(&view, &self.project_name)
}
}
}
"tree" => {
if let Some(message) = loading_guard_message_from_published(&published.health) {
return message;
}
let path = params.0.path.as_deref().unwrap_or("");
let depth = params.0.depth.unwrap_or(2).min(5);
let view = Arc::clone(&published.outline);
let skipped = published.live.compatibility_skipped_files();
format::file_tree_view_with_skipped(&view.files, &skipped, path, depth)
}
_ => match repo_map_text_for_generation(&published) {
Ok(result) => {
let doctrine = "\nDoctrine: the map orients; the tools prove. \
Completeness: ranked and truncated by result cap - absence \
from the map is not absence from the repo; confirm with \
search_symbols / search_text before concluding something is missing.";
format!("{result}{doctrine}")
}
Err(StatusCode::NOT_FOUND) => "Repository map unavailable.".to_string(),
Err(StatusCode::INTERNAL_SERVER_ERROR) => {
"Repository map failed: internal error.".to_string()
}
Err(other) => format!("Repository map failed: HTTP {}", other.as_u16()),
},
};
let knowledge_map =
crate::protocol::knowledge_model::render_repository_knowledge_map(&published);
output.push_str("\n\n");
output.push_str(&knowledge_map);
self.session_context.record_summary_output(
"get_repo_map",
(output.len() / 4).min(u32::MAX as usize) as u32,
);
let budget_summary = format!(
"Repository orientation budget summary\noutput_coverage=degraded\n{knowledge_map}\n\nCode topology omitted from the bounded summary; retrieve the full map through the CCR handle."
);
self.apply_ccr_budget_with_summary(
"get_repo_map",
output,
budget_summary,
params.0.max_tokens,
)
}
/// Rich file summary: symbol outline, imports, consumers, references, and git activity.
/// Use sections=['outline'] for a compact symbol outline only.
/// Use sections=['outline','imports'] to limit output. Best tool for understanding a file before editing.
/// Much smaller than reading the raw file.
/// NOT for reading actual source code (use get_file_content or get_symbol).
#[tool(
description = "Prefer this over raw file reads for code understanding — it usually saves 70-95% of tokens by returning the file's symbol outline and structure first. Rich file summary: symbol outline, imports, consumers, references, git activity, and exact repository-knowledge backlinks. Use sections=['outline'] for a fast first pass, sections=['knowledge'] for the trust header plus knowledge backlinks only, or omit/pass [] for all sections. Best tool for understanding a file before editing or before deciding whether you need exact raw text. NOT for reading actual source code (use get_file_content or get_symbol).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn get_file_context(&self, params: Parameters<GetFileContextInput>) -> String {
if let Some(result) = self.proxy_tool_call("get_file_context", ¶ms.0).await {
return result;
}
if let Some(refusal) = self.foreign_project_refusal(params.0.project.as_deref()) {
return refusal;
}
let force_refresh = params.0.force_refresh == Some(true);
freshen_exact_path_for_targeted_retrieval(self, &search::PathScope::exact(¶ms.0.path));
let published = self.index.published_generation();
if let Some(message) = loading_guard_message_from_published(&published.health) {
return message;
}
let params_hash = crate::protocol::session::hash_file_context_params(
params.0.max_tokens,
params.0.sections.as_deref(),
&self.project_name,
published
.source
.as_deref()
.map(|source| source.source_id.as_str()),
published.publication_generation,
published.content_generation,
);
if let Some(meta) = self.session_context.try_file_context_cache_hit(
¶ms.0.path,
params_hash,
force_refresh,
) {
return self.format_read_cache_hit(&meta, "session_repeat_read");
}
// Honest Tier-2/Tier-3 response: the path may EXIST on disk but be
// deliberately admitted as metadata-only (e.g. package-lock.json) or
// hard-skipped. Return an actionable "not indexed" message pointing at
// get_file_content for raw reads, instead of a misleading
// "File not found". Resolution reuses the index lookup + repo-root-bound
// disk fallback shared with the symbol-level degradation path.
{
let repo_root = self.capture_repo_root();
let degraded = admission_tier_file_degradation_for_path(
published.live.as_ref(),
repo_root.as_deref(),
¶ms.0.path,
);
if let Some(result) = degraded {
return result;
}
}
if params.0.estimate == Some(true) {
if let Some(file) = published.live.capture_shared_file(¶ms.0.path) {
let file_tokens = file.content.len() / 4;
let outline_tokens = file.content.len() / 50; // ~5-10% of raw
return format!(
"Estimate for get_file_context(path=\"{}\"):\n Outline: ~{} tokens\n Raw file: ~{} tokens\n Savings: ~{}%",
params.0.path,
outline_tokens,
file_tokens,
(outline_tokens * 100)
.checked_div(file_tokens)
.map(|pct| 100usize.saturating_sub(pct))
.unwrap_or(0)
);
} else {
return format::not_found_file(¶ms.0.path);
}
}
const LARGE_FILE_CONTEXT_DEFAULT_TOKENS: u64 = 1000;
let (file_exists, raw_chars, line_count, symbol_count, reference_count) = {
published
.live
.capture_shared_file(¶ms.0.path)
.map(|f| {
(
true,
f.content.len(),
format::indexed_file_line_count(&f.content),
f.symbols.len(),
f.references.len(),
)
})
.unwrap_or((false, 0, 0, 0, 0))
};
let is_small_file = format::is_small_indexed_file(raw_chars, line_count);
let large_default_summary = !is_small_file
&& params.0.sections.is_none()
&& (raw_chars > 200_000 || symbol_count > 250 || reference_count > 800);
let state = sidecar_state_for_server(self);
let include_tests = include_tests_from_sections(params.0.sections.as_ref());
let requested_sections = visible_sections(¶ms.0.sections);
let knowledge_requested = requested_sections.as_ref().is_none_or(|sections| {
sections.is_empty() || sections.iter().any(|section| section == "knowledge")
});
let knowledge_only = requested_sections
.as_ref()
.is_some_and(|sections| sections.len() == 1 && sections[0] == "knowledge");
let requested_code_sections = requested_sections.as_ref().map(|sections| {
sections
.iter()
.filter(|section| section.as_str() != "knowledge")
.cloned()
.collect::<Vec<_>>()
});
let sections = if is_small_file {
Some(vec!["outline".to_string()])
} else if large_default_summary {
Some(vec!["outline".to_string(), "imports".to_string()])
} else {
requested_code_sections
};
let context_max_tokens = Some(format::resolve_read_max_tokens(
params
.0
.max_tokens
.or_else(|| knowledge_requested.then_some(1000))
.or_else(|| large_default_summary.then_some(LARGE_FILE_CONTEXT_DEFAULT_TOKENS)),
raw_chars,
));
let knowledge_section = knowledge_requested
.then(|| {
crate::protocol::knowledge_model::render_code_knowledge_context(
&published,
&crate::live_index::knowledge_bridge::CodeAnchorId::File {
path: params.0.path.clone(),
},
true,
)
})
.flatten();
if knowledge_only {
if !file_exists {
return format::not_found_file(¶ms.0.path);
}
let output = crate::protocol::knowledge_model::render_budgeted_code_knowledge_only(
&published,
knowledge_section.as_deref(),
context_max_tokens,
);
let tokens = (output.len() / 4) as u32;
self.session_context
.record_file_context_fetch(¶ms.0.path, params_hash, tokens);
self.session_context
.record_listed_file(¶ms.0.path, tokens);
self.bump_frecency(&[PathBuf::from(¶ms.0.path)]);
return output;
}
let outline = OutlineParams {
path: params.0.path.clone(),
max_tokens: context_max_tokens,
sections: sections.clone(),
};
match outline_tool_text_for_generation(&state, &published, &outline) {
Ok(result) => {
let mut result =
format::collapse_large_test_modules(result, include_tests, sections.as_deref());
if large_default_summary {
let note = format!(
"Large file summary: outline+imports only ({} symbols, {} references); omitted consumers/references/git; request sections=[\"consumers\"], sections=[\"references\"], sections=[\"git\"] or higher max_tokens.",
symbol_count, reference_count
);
result = if let Some((envelope, rest)) = result.split_once("\n\n") {
format!("{envelope}\n\n{note}\n\n{rest}")
} else {
format!("{note}\n\n{result}")
};
}
let mut body = result;
if let Some(knowledge) = &knowledge_section {
body.push_str("\n\n");
body.push_str(knowledge);
}
let footer = format::compact_savings_footer(body.len(), raw_chars);
let (mut output, truncated_after_assembly) =
crate::protocol::knowledge_model::enforce_budgeted_code_context_with_knowledge(
&published,
format!("{body}{footer}"),
knowledge_section.as_deref(),
context_max_tokens,
);
if truncated_after_assembly {
// The sidecar stamped the trust envelope (possibly
// `Completeness: full`) BEFORE this post-assembly cut —
// downgrade the claim so the envelope stays honest
// (dogfood 2026-07-11).
output = format::downgrade_full_completeness_after_truncation(&output);
}
let tokens = (output.len() / 4) as u32;
let prior_dedup = if force_refresh {
self.session_context.prior_fetch_for_dedup(
crate::protocol::session::FetchKind::FileContext,
¶ms.0.path,
"",
params_hash,
)
} else {
None
};
self.session_context
.record_file_context_fetch(¶ms.0.path, params_hash, tokens);
self.session_context
.record_listed_file(¶ms.0.path, tokens);
if let Some(prior) = prior_dedup {
output = format::append_dedup_hint_footer(
output,
"file context",
prior.fetched_at.elapsed().as_secs(),
prior.approx_tokens,
);
}
// Frecency bump — commitment tool. Reached only on the happy
// path after a successful outline fetch; collection policy is
// resolved inside bump_frecency. See wiki `[[SymForge Frecency-Weighted
// File Ranking]]` §"Bump hooks".
self.bump_frecency(&[PathBuf::from(¶ms.0.path)]);
output
}
Err(StatusCode::NOT_FOUND) => format::not_found_file(¶ms.0.path),
Err(StatusCode::INTERNAL_SERVER_ERROR) => {
"File context failed: internal error.".to_string()
}
Err(other) => format!("File context failed: HTTP {}", other.as_u16()),
}
}
/// Symbol usage analysis with three modes. (1) Default: definition + callers grouped by file + callees + type usages.
/// (2) bundle=true: symbol body + full definitions of all referenced custom types, resolved recursively — best
/// for edit preparation (requires path). (3) sections=[...]: comprehensive trace analysis — definition, callers,
/// callees, implementations, type dependencies, git activity. Valid sections: 'dependents', 'siblings',
/// 'implementations', 'git', 'knowledge' (empty array = all). Set verbosity='signature' for ~80% smaller output.
/// NOT for just the symbol body (use get_symbol).
#[tool(
name = "get_symbol_context",
description = "Symbol usage analysis with three modes. (1) Default: definition + callers grouped by file + callees + type usages; exact knowledge backlinks are appended only when evidence exists. (2) bundle=true: symbol body + full definitions of all referenced custom types, resolved recursively; bundles never inject knowledge. (3) sections=[...]: comprehensive trace analysis or sections=['knowledge'] for the trust header plus knowledge backlinks only. Valid sections: 'dependents', 'siblings', 'implementations', 'git', 'knowledge' (empty array = all). Set verbosity='signature' for ~80% smaller output. NOT for just the symbol body (use get_symbol).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn get_symbol_context_tool(
&self,
params: Parameters<GetSymbolContextInput>,
) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
let started = Instant::now();
let output = self.get_symbol_context(params).await;
let outcome_class = classify_get_symbol_context_output(&output);
self.record_tool_completion(
"get_symbol_context",
&output,
started.elapsed(),
outcome_class,
);
statused_tool_result(output, outcome_class)
}
pub(crate) async fn get_symbol_context(
&self,
params: Parameters<GetSymbolContextInput>,
) -> String {
if let Some(result) = self.proxy_tool_call("get_symbol_context", ¶ms.0).await {
return result;
}
if let Some(refusal) = self.foreign_project_refusal(params.0.project.as_deref()) {
return refusal;
}
let refreshed = params
.0
.path
.as_deref()
.or(params.0.file.as_deref())
.is_some_and(|path| {
freshen_exact_path_for_targeted_retrieval(self, &search::PathScope::exact(path))
});
let published = self.index.published_generation();
if let Some(message) = loading_guard_message_from_published(&published.health) {
return message;
}
if let Some(path) = params.0.path.as_deref().or(params.0.file.as_deref()) {
let repo_root = self.capture_repo_root();
let degraded = admission_tier_degradation_for_path(
published.live.as_ref(),
repo_root.as_deref(),
"get_symbol_context",
path,
¶ms.0.name,
);
if let Some(result) = degraded {
return result;
}
}
if params.0.estimate == Some(true) {
let path = params.0.path.as_deref().unwrap_or("");
if let Some(file) = published.live.capture_shared_file(path) {
let sym_tokens = file
.symbols
.iter()
.find(|s| s.name == params.0.name)
.map(|s| (s.byte_range.1 - s.byte_range.0) as usize / 4)
.unwrap_or(0);
let ref_count = file
.references
.iter()
.filter(|r| r.name == params.0.name)
.count();
let bundle_est = sym_tokens * 3; // rough: body + deps
return format!(
"Estimate for get_symbol_context(name=\"{}\"):\n Symbol body: ~{} tokens\n Callers: ~{} tokens\n Bundle: ~{} tokens",
params.0.name,
sym_tokens,
ref_count * 15 + 50,
bundle_est
);
} else {
return format!("Symbol '{}' not found in '{}'", params.0.name, path);
}
}
if params.0.bundle.unwrap_or(false) {
let path = match params.0.path.as_deref() {
Some(p) => p.to_string(),
None => return "Error: bundle=true requires the 'path' parameter.".to_string(),
};
let (view, raw_chars, parse_state) = {
let raw = published
.live
.capture_shared_file(&path)
.map(|f| f.content.len())
.unwrap_or(0);
let parse_state = published
.live
.capture_shared_file(&path)
.map(|f| parse_state_for_file(f.as_ref()))
.unwrap_or("parsed");
let view = published.live.capture_context_bundle_view(
&path,
¶ms.0.name,
params.0.symbol_kind.as_deref(),
params.0.symbol_line,
);
(view, raw, parse_state)
};
let verbosity = params.0.verbosity.as_deref().unwrap_or("full");
let result = format::context_bundle_result_view_with_max_tokens(
&view,
verbosity,
params.0.max_tokens,
);
let result = if let crate::live_index::ContextBundleView::Found(found) = &view {
let scope = match params.0.max_tokens {
Some(max_tokens) => format!(
"path `{}`; bundle mode; max_tokens={max_tokens}",
found.file_path
),
None => format!("path `{}`; bundle mode", found.file_path),
};
let envelope = search_format::format_search_envelope(
if params.0.symbol_line.is_some() {
"exact"
} else {
"constrained"
},
context_source_authority_label(refreshed),
parse_state,
&context_bundle_completeness_label(found.as_ref(), &result),
&scope,
&format!(
"symbol anchor `{}:{}`",
found.file_path,
found.line_range.0.saturating_add(1)
),
);
format!("{envelope}\n\n{result}")
} else {
result
};
let footer = format::compact_savings_footer(result.len(), raw_chars);
self.record_read_savings(format::saved_tokens_vs_competent_manual(
result.len(),
raw_chars,
));
let output = format!("{result}{footer}");
self.session_context
.record_symbol(&path, ¶ms.0.name, (output.len() / 4) as u32);
// Frecency bump — commitment tool, bundle-mode happy path.
// Collection policy is resolved inside bump_frecency.
self.bump_frecency(&[PathBuf::from(&path)]);
return output;
}
// Trace mode: comprehensive symbol analysis (absorbed from trace_symbol)
if params.0.sections.is_some() {
let path = match params.0.path.as_deref() {
Some(p) => p.to_string(),
None => return "Error: sections requires the 'path' parameter.".to_string(),
};
// Convert sections: Some(empty vec) = all sections (like trace_symbol's None)
let include_tests = include_tests_from_sections(params.0.sections.as_ref());
let requested_sections = visible_sections(¶ms.0.sections).unwrap_or_default();
let knowledge_requested = requested_sections.is_empty()
|| requested_sections
.iter()
.any(|section| section == "knowledge");
let knowledge_only = requested_sections.len() == 1
&& requested_sections
.first()
.is_some_and(|section| section == "knowledge");
let sections_param = requested_sections
.iter()
.filter(|section| section.as_str() != "knowledge")
.cloned()
.collect::<Vec<_>>();
let sections_param = if sections_param.is_empty() {
None
} else {
Some(sections_param)
};
let sections_param = encode_include_tests_marker(sections_param, include_tests);
let target = crate::protocol::knowledge_model::resolve_symbol_code_anchor(
&published,
&path,
¶ms.0.name,
params.0.symbol_kind.as_deref(),
params.0.symbol_line,
);
let knowledge = target.as_ref().and_then(|target| {
crate::protocol::knowledge_model::render_code_knowledge_context(
&published, target, true,
)
});
if knowledge_only {
let output = crate::protocol::knowledge_model::render_budgeted_code_knowledge_only(
&published,
knowledge.as_deref(),
params.0.max_tokens.or(Some(1000)),
);
self.session_context.record_symbol(
&path,
¶ms.0.name,
(output.len() / 4) as u32,
);
self.bump_frecency(&[PathBuf::from(&path)]);
return output;
}
let trace_input = TraceSymbolInput {
path: path.clone(),
name: params.0.name.clone(),
kind: params.0.symbol_kind.clone(),
symbol_line: params.0.symbol_line,
sections: sections_param,
verbosity: params.0.verbosity.clone(),
max_tokens: params.0.max_tokens,
estimate: None,
};
let trace_sections = visible_sections(&trace_input.sections);
let trace_view = capture_trace_symbol_view_for_generation(
&published,
&trace_input,
trace_sections.as_deref(),
);
let trace_verbosity = trace_input.verbosity.as_deref().unwrap_or("full");
let mut trace_result = format::trace_symbol_result_view(
&trace_view,
&trace_input.name,
trace_verbosity,
trace_input.max_tokens,
);
if knowledge_requested && let Some(knowledge) = &knowledge {
trace_result.push_str("\n\n");
trace_result.push_str(knowledge);
}
let (trace_result, _) =
crate::protocol::knowledge_model::enforce_budgeted_code_context_with_knowledge(
&published,
trace_result,
knowledge.as_deref(),
params
.0
.max_tokens
.or_else(|| knowledge_requested.then_some(1000)),
);
self.session_context.record_symbol(
&path,
¶ms.0.name,
(trace_result.len() / 4) as u32,
);
// Frecency bump — commitment tool, trace-mode happy path.
// Collection policy is resolved inside bump_frecency.
self.bump_frecency(&[PathBuf::from(&path)]);
return trace_result;
}
// Default: symbol context mode
let file_path_hint = params.0.path.as_deref().or(params.0.file.as_deref());
// Auto-resolve path from index when not provided
let resolved_path: Option<String>;
let file_path_hint = if file_path_hint.is_some() {
resolved_path = None;
file_path_hint
} else {
let candidates = symbol_candidate_paths(published.live.as_ref(), ¶ms.0.name);
if candidates.len() == 1 {
resolved_path = Some(candidates.into_iter().next().unwrap());
resolved_path.as_deref()
} else if candidates.len() > 1 {
return format_ambiguous_symbol_context(¶ms.0.name, &candidates);
} else {
resolved_path = None;
None
}
};
let verbosity = params.0.verbosity.as_deref().unwrap_or("full");
let max_tokens = params.0.max_tokens;
let knowledge_section = file_path_hint
.and_then(|path| {
crate::protocol::knowledge_model::resolve_symbol_code_anchor(
&published,
path,
¶ms.0.name,
params.0.symbol_kind.as_deref(),
params.0.symbol_line,
)
})
.and_then(|target| {
crate::protocol::knowledge_model::render_code_knowledge_context(
&published, &target, false,
)
});
// Capture the symbol definition from the index so we can prepend it
// (the sidecar only returns reference locations, not the definition itself).
let (symbol_header, impl_block_tip, callees_text, raw_chars) = {
let file = file_path_hint.and_then(|path| published.live.capture_shared_file(path));
let raw = file.as_ref().map(|f| f.content.len()).unwrap_or(0);
let header = file.and_then(|f| {
render_symbol_context_header(
f.as_ref(),
¶ms.0.name,
params.0.symbol_kind.as_deref(),
params.0.symbol_line,
verbosity,
max_tokens,
)
});
let (impl_block_tip, callees_text) = file_path_hint
.map(|path| {
let view = published.live.capture_context_bundle_view(
path,
¶ms.0.name,
params.0.symbol_kind.as_deref(),
params.0.symbol_line,
);
let tip = format::context_bundle_impl_suggestion_tip(&view);
let callees = format::context_bundle_callees_text(&view);
(tip, callees)
})
.unwrap_or_default();
(header, impl_block_tip, callees_text, raw)
};
let state = sidecar_state_for_server(self);
let symbol_context = SymbolContextParams {
name: params.0.name.clone(),
file: params.0.file.clone(),
path: params.0.path.clone(),
symbol_kind: params.0.symbol_kind.clone(),
symbol_line: params.0.symbol_line,
};
match symbol_context_tool_text_for_generation(&state, &published, &symbol_context) {
Ok(refs_text) => {
let mut output = String::new();
if let Some(header) = &symbol_header {
output.push_str(header);
output.push_str("\n\n");
}
output.push_str(&refs_text);
if !callees_text.is_empty() {
output.push('\n');
output.push_str(&callees_text);
}
if !impl_block_tip.is_empty() {
output.push_str(impl_block_tip.trim_start_matches('\n'));
}
if let Some(knowledge) = &knowledge_section {
output.push_str("\n\n");
output.push_str(knowledge);
}
let footer = format::compact_savings_footer(output.len(), raw_chars);
// Frecency bump — commitment tool, default-mode happy path.
// Resolve the bump path the same way the output did:
// explicit params first, auto-resolved path as fallback.
// Collection policy is resolved inside bump_frecency.
if let Some(bump_path) = params
.0
.path
.as_deref()
.or(params.0.file.as_deref())
.map(PathBuf::from)
.or_else(|| resolved_path.as_deref().map(PathBuf::from))
{
self.bump_frecency(&[bump_path]);
}
crate::protocol::knowledge_model::enforce_budgeted_code_context_with_knowledge(
&published,
format!("{output}{footer}"),
knowledge_section.as_deref(),
max_tokens,
)
.0
}
Err(_) => {
// Sidecar unavailable — fall back to the index definition so callers
// always get at least the symbol body instead of an opaque error.
if let Some(header) = symbol_header {
let mut body = format!(
"{header}\n\n(Reference data unavailable — showing definition only)"
);
if !impl_block_tip.is_empty() {
body.push('\n');
body.push_str(impl_block_tip.trim_start_matches('\n'));
}
if let Some(knowledge) = &knowledge_section {
body.push_str("\n\n");
body.push_str(knowledge);
}
let footer = format::compact_savings_footer(body.len(), raw_chars);
self.record_read_savings(format::saved_tokens_vs_competent_manual(
body.len(),
raw_chars,
));
let output = format!("{body}{footer}");
if let Some(ref p) = resolved_path {
self.session_context.record_symbol(
p,
¶ms.0.name,
(output.len() / 4) as u32,
);
} else if let Some(ref p) = params.0.path {
self.session_context.record_symbol(
p,
¶ms.0.name,
(output.len() / 4) as u32,
);
}
// Frecency bump — commitment tool, fallback-definition
// branch (sidecar unavailable but we still returned a
// useful symbol body to the caller). Collection policy is
// resolved inside bump_frecency.
if let Some(bump_path) = params
.0
.path
.as_deref()
.or(params.0.file.as_deref())
.map(PathBuf::from)
.or_else(|| resolved_path.as_deref().map(PathBuf::from))
{
self.bump_frecency(&[bump_path]);
}
crate::protocol::knowledge_model::enforce_budgeted_code_context_with_knowledge(
&published,
output,
knowledge_section.as_deref(),
max_tokens,
)
.0
} else {
format!("Symbol \"{}\" not found in index.", params.0.name)
}
}
}
}
/// Call AFTER editing a file. Re-reads from disk, updates the index, reports added/removed/modified
/// symbols and affected dependents. Set include_co_changes=true to also see git temporal coupling data
/// (files that historically change together with this file). Always call this after making edits.
#[tool(
description = "Call AFTER editing a file. Re-reads from disk, updates the index, reports added/removed/modified symbols and affected dependents. Set include_co_changes=true to also see git temporal coupling data (files that historically change together). Always call this after making edits to keep the index current. NOT for listing changed files across the repo (use what_changed). NOT for a symbol-level diff between git refs (use diff_symbols).",
annotations(
read_only_hint = false,
destructive_hint = false,
idempotent_hint = true,
open_world_hint = false
)
)]
pub(crate) async fn analyze_file_impact(
&self,
params: Parameters<AnalyzeFileImpactInput>,
) -> String {
if let Some(result) = self.proxy_tool_call("analyze_file_impact", ¶ms.0).await {
return result;
}
if let Some(refusal) = self.foreign_project_refusal(params.0.project.as_deref()) {
return refusal;
}
if params.0.estimate == Some(true) {
let with_co = params.0.include_co_changes.unwrap_or(false);
let co_limit = params.0.co_changes_limit.unwrap_or(10) as usize;
let est = 200 + if with_co { co_limit * 13 } else { 0 };
return format!(
"Estimate for analyze_file_impact: ~{} tokens (include_co_changes={})",
est, with_co
);
}
{
let guard = self.index.read();
loading_guard!(guard);
}
let state = sidecar_state_for_server(self);
let impact = ImpactParams {
path: params.0.path.clone(),
new_file: params.0.new_file,
};
let mut result = match impact_tool_text(state, &impact).await {
Ok(result) => result,
Err(StatusCode::NOT_FOUND) => {
return format!("File not found on disk: {}", params.0.path);
}
Err(StatusCode::INTERNAL_SERVER_ERROR) => {
return "Impact analysis failed: internal error.".to_string();
}
Err(other) => return format!("Impact analysis failed: HTTP {}", other.as_u16()),
};
// Append co-changes if requested
if params.0.include_co_changes.unwrap_or(false) {
let temporal = self.index.git_temporal();
match temporal.state {
crate::live_index::git_temporal::GitTemporalState::Ready => {
let limit = params.0.co_changes_limit.unwrap_or(10) as usize;
let path = params.0.path.as_str();
match temporal.files.get(path) {
Some(history) => {
result.push_str("\n\n");
result.push_str(&format::co_changes_result_view(path, history, limit));
}
None => {
result.push_str("\n\nNo git co-change data found for this file.");
}
}
}
crate::live_index::git_temporal::GitTemporalState::Pending
| crate::live_index::git_temporal::GitTemporalState::Computing => {
result.push_str(
"\n\nGit temporal data is still loading. Co-changes unavailable.",
);
}
crate::live_index::git_temporal::GitTemporalState::Unavailable(ref reason) => {
result.push_str(&format!("\n\nGit temporal data unavailable: {reason}"));
}
}
}
self.session_context.record_summary_output(
"analyze_file_impact",
(result.len() / 4).min(u32::MAX as usize) as u32,
);
result
}
/// Find symbols by name substring across the project — returns name, kind, file, line range.
/// Use when you know part of a symbol name but not the file. Supports kind filter, language filter,
/// and path prefix scope. Query is optional: omit it to browse by kind or path_prefix (at least
/// one of query, kind, or path_prefix is required).
/// NOT for text content search (use search_text). NOT for file path search (use search_files).
#[tool(
name = "search_symbols",
description = "Prefer this before grep when you are looking for a function, class, type, or other symbol by name. Finds symbols across the repository in milliseconds and returns name, kind, file, and line range. Use when you know part of a symbol name but not the file. Supports kind filter, language filter, and path prefix scope. Query is optional — omit it to browse all symbols matching kind/path_prefix (browse mode defaults to limit=20, ranks by reference count/kind/path/line, and returns one representative per exact name+kind). At least one of query, kind, or path_prefix is required. Large result sets may CCR-compress; use symforge_retrieve with the footer hash for the full ranked list. NOT for text content search (use search_text). NOT for file path search (use search_files).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn search_symbols_tool(
&self,
params: Parameters<SearchSymbolsInput>,
) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
let started = Instant::now();
let output = self.search_symbols(params).await;
let outcome_class = classify_search_symbols_output(&output);
self.record_tool_completion("search_symbols", &output, started.elapsed(), outcome_class);
statused_tool_result(output, outcome_class)
}
pub(crate) async fn search_symbols(&self, params: Parameters<SearchSymbolsInput>) -> String {
let query_str = params.0.query.as_deref().unwrap_or("").trim();
let is_browse = query_str.is_empty();
if is_browse && params.0.kind.is_none() && params.0.path_prefix.is_none() {
return "search_symbols requires at least one of: query, kind, or path_prefix"
.to_string();
}
if let Some(result) = self.proxy_tool_call("search_symbols", ¶ms.0).await {
return result;
}
// Feature 012 (Phase 3): no daemon here -> no working set. Honest refusal
// for a cross-project request instead of a silent single-project answer.
if let Some(refusal) = self
.local_cross_project_refusal(params.0.project.as_deref(), params.0.projects.as_deref())
{
return refusal;
}
let options = match search_symbols_options_from_input(¶ms.0) {
Ok(options) => options,
Err(message) => return message,
};
let result = {
let guard = self.index.read();
loading_guard!(guard);
search::search_symbols_with_options(
&guard,
query_str,
params.0.kind.as_deref(),
&options,
)
};
let hidden_noise_count = {
let guard = self.index.read();
hidden_search_symbols_noise_count(
&guard,
query_str,
params.0.kind.as_deref(),
&options,
&result,
)
};
// Browse ordering is owned by the engine (search::search_symbols_with_options),
// which ranks browse results by importance (reference count -> kind -> path ->
// line). Do NOT re-sort here: a tool-level re-sort would override that order and
// reintroduce the symbol_kind_priority display-kind mismatch ("fn" -> 0.1). (018 US2)
let envelope = if result.hits.is_empty() {
None
} else {
let guard = self.index.read();
Some(search_format::format_search_envelope(
search_symbols_match_type_label(&result, is_browse),
index_source_authority_label(&self.index.freshness_status()),
search_parse_state_for_paths(
&guard,
result.hits.iter().map(|hit| hit.path.as_str()),
),
&search_completeness_label(result.overflow_count, hidden_noise_count),
&search_scope_summary(
&options.path_scope,
options.language_filter.as_ref(),
&options.noise_policy,
options.include_personal_tooling,
None,
None,
false,
),
&search_symbols_evidence(&result),
))
};
let output = format::search_symbols_result_view(&result, query_str);
let output = match envelope {
Some(envelope) => format!("{envelope}\n\n{output}"),
None => output,
};
let output = if !is_browse
&& query_str.len() >= 2
&& result.hits.len() < options.result_limit.get() / 2
{
let text_fallback = {
let guard = self.index.read();
loading_guard!(guard);
let mut text_options = search::TextSearchOptions::for_current_code_search();
text_options.path_scope = options.path_scope.clone();
text_options.noise_policy = options.noise_policy;
text_options.include_personal_tooling = options.include_personal_tooling;
text_options.language_filter = options.language_filter;
text_options.total_limit = 15;
text_options.max_per_file = 1;
search::search_text_with_options(
&guard,
Some(query_str),
None,
false,
&text_options,
)
.unwrap_or_else(|_| search::TextSearchResult {
label: String::new(),
total_matches: 0,
files: vec![],
suppressed_by_noise: 0,
overflow_count: 0,
})
};
let symbol_paths: std::collections::HashSet<&str> =
result.hits.iter().map(|h| h.path.as_str()).collect();
let extra_paths: Vec<String> = text_fallback
.files
.iter()
.filter(|file| !symbol_paths.contains(file.path.as_str()))
.filter_map(|file| {
file.matches
.first()
.map(|m| format!("{}:{}", file.path, m.line_number))
})
.take(10)
.collect();
if extra_paths.is_empty() {
output
} else {
format!(
"{output}\n\nText path fallback (sparse symbol hits):\n{}",
extra_paths.join("\n")
)
}
} else {
output
};
self.record_tool_savings_named(
"search_symbols",
format::estimate_tokens_from_chars(format::estimate_listing_baseline_chars(
output.len(),
)),
(output.len() / 4) as u64,
);
self.session_context.record_summary_output(
"search_symbols",
(output.len() / 4).min(u32::MAX as usize) as u32,
);
// Session tracking: record each symbol hit as list-only until its body is fetched.
for hit in &result.hits {
self.session_context
.record_listed_symbol(&hit.path, &hit.name);
}
// Intentionally NO frecency bump here — search_symbols is a discovery
// tool. See wiki `[[SymForge Frecency-Weighted File Ranking]]`
// §"Search tools deliberately do NOT bump" for the positive-feedback-
// loop rationale.
self.apply_ccr_budget("search_symbols", output, params.0.max_tokens)
}
/// Shows matches with enclosing symbol context. Use group_by='symbol' to deduplicate,
/// follow_refs=true to inline callers. Set structural=true to match AST patterns using
/// ast-grep syntax ($VAR for metavariables, $$$ for multi-node wildcards).
/// NOT for symbol name search (use search_symbols). NOT for file path search (use search_files).
#[tool(
name = "search_text",
description = "Prefer this over grep/ripgrep for code search — it returns matches with enclosing symbol context instead of raw lines alone. Test files and #[cfg(test)] modules are EXCLUDED by default (a zero-hit query reports how many test matches were suppressed); set include_tests=true to include them. Full-text search across file contents: literal, OR-terms, regex, or structural AST patterns. Use group_by='symbol' to deduplicate and follow_refs=true to inline callers. Set structural=true with query as an ast-grep pattern to match code by AST structure (e.g., 'fn $NAME($$$) { $$$ }'). Matches are ranked and capped per file; large output may CCR-compress with symforge_retrieve hash. NOT for symbol name search (use search_symbols). NOT for file path search (use search_files).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn search_text_tool(
&self,
params: Parameters<SearchTextInput>,
) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
let started = Instant::now();
let output = self.search_text(params).await;
let outcome_class = classify_search_text_output(&output);
self.record_tool_completion("search_text", &output, started.elapsed(), outcome_class);
statused_tool_result(output, outcome_class)
}
/// Retrieves exact, bounded repository-knowledge evidence from one captured
/// immutable source generation. This Gate I surface intentionally supports
/// only the current source; other frozen source scopes arrive in Gate L.
#[tool(
name = "search_knowledge",
description = "Search exact repository knowledge evidence with captured source/version/generation provenance, deterministic authority filtering, bounded bridge previews, and explicit coverage. source_scope selects 'current' (default), 'worktrees', 'local_refs', or 'all', composed from one captured source set. Read-only and frecency-neutral.",
annotations(
read_only_hint = true,
destructive_hint = false,
idempotent_hint = true,
open_world_hint = false
)
)]
pub(crate) async fn search_knowledge_tool(
&self,
params: Parameters<SearchKnowledgeInput>,
) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
if let Err(output) = super::knowledge_search::validate_input(¶ms.0) {
let outcome_class = classify_search_knowledge_output(&output);
return statused_tool_result(output, outcome_class);
}
let started = Instant::now();
let output = self.search_knowledge(params).await;
let outcome_class = classify_search_knowledge_output(&output);
self.record_tool_completion(
"search_knowledge",
&output,
started.elapsed(),
outcome_class,
);
statused_tool_result(output, outcome_class)
}
pub(crate) async fn search_knowledge(
&self,
params: Parameters<SearchKnowledgeInput>,
) -> String {
// Includes the raw-query secret guard and must run before daemon
// routing, analytics, cache lookup, or CCR creation.
if let Err(error) = super::knowledge_search::validate_input(¶ms.0) {
return error;
}
if let Some(result) = self.proxy_tool_call("search_knowledge", ¶ms.0).await {
return result;
}
if let Some(refusal) = self
.local_cross_project_refusal(params.0.project.as_deref(), params.0.projects.as_deref())
{
return refusal;
}
let source_set = self.index.published_source_set();
let output = super::knowledge_search::search_scoped(&source_set, ¶ms.0);
self.apply_ccr_budget("search_knowledge", output, params.0.max_tokens)
}
/// Audits repository-knowledge authority and hygiene from one immutable
/// publication. Complete-plan hashes are computed before output limits or CCR.
#[tool(
name = "review_knowledge",
description = "Review repository knowledge authority and hygiene in summary, exact-document, or remediation mode. Returns complete aggregate evidence arrays, bridge records, temporal provenance, eligibility blockers, stable per-source review hashes, and a top-level result hash. source_scope selects 'current' (default), 'worktrees', 'local_refs', or 'all', composed from one captured source set. Read-only and frecency-neutral.",
annotations(
read_only_hint = true,
destructive_hint = false,
idempotent_hint = true,
open_world_hint = false
)
)]
pub(crate) async fn review_knowledge_tool(
&self,
params: Parameters<ReviewKnowledgeInput>,
) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
if let Err(output) = super::knowledge_review::validate_input(¶ms.0) {
let outcome_class = classify_search_knowledge_output(&output);
return statused_tool_result(output, outcome_class);
}
let started = Instant::now();
let output = self.review_knowledge(params).await;
let outcome_class = classify_search_knowledge_output(&output);
self.record_tool_completion(
"review_knowledge",
&output,
started.elapsed(),
outcome_class,
);
statused_tool_result(output, outcome_class)
}
pub(crate) async fn review_knowledge(
&self,
params: Parameters<ReviewKnowledgeInput>,
) -> String {
// The no-echo input guard runs before proxy routing, analytics/cache
// access, generation capture, or CCR creation.
if let Err(error) = super::knowledge_review::validate_input(¶ms.0) {
return error;
}
if let Some(result) = self.proxy_tool_call("review_knowledge", ¶ms.0).await {
return result;
}
if let Some(refusal) = self
.local_cross_project_refusal(params.0.project.as_deref(), params.0.projects.as_deref())
{
return refusal;
}
let source_set = self.index.published_source_set();
match super::knowledge_review::review_scoped(&source_set, ¶ms.0) {
Ok(output) => self.apply_ccr_budget_with_summary(
"review_knowledge",
output.rendered,
output.budget_rendered,
params.0.max_tokens,
),
Err(error) => error,
}
}
/// Applies explicitly approved review actions to the root policy ledger.
/// Preview is the default and is strictly side-effect free.
#[tool(
name = "curate_knowledge",
description = "Preview or apply explicitly approved repository-knowledge policy mutations for exactly one current worktree. Requires fresh review, manifest, policy, and target guards; apply additionally requires durable idempotency and atomic file durability. This tool only writes `.symforge-knowledge.toml` and never edits, moves, or deletes repository documents.",
annotations(
read_only_hint = false,
destructive_hint = true,
idempotent_hint = true,
open_world_hint = false
)
)]
pub(crate) async fn curate_knowledge_tool(
&self,
params: Parameters<CurateKnowledgeInput>,
) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
if let Err(output) = super::knowledge_curation::validate_input(¶ms.0) {
let outcome_class = classify_search_knowledge_output(&output);
return statused_tool_result(output, outcome_class);
}
let started = Instant::now();
let output = self.curate_knowledge(params).await;
let outcome_class = classify_search_knowledge_output(&output);
self.record_tool_completion(
"curate_knowledge",
&output,
started.elapsed(),
outcome_class,
);
statused_tool_result(output, outcome_class)
}
pub(crate) async fn curate_knowledge(
&self,
params: Parameters<CurateKnowledgeInput>,
) -> String {
// No-echo validation precedes proxy routing, project observation,
// analytics, durable replay lookup, capability probing, or temp I/O.
if let Err(error) = super::knowledge_curation::validate_input(¶ms.0) {
return error;
}
if let Some(result) = self.proxy_tool_call("curate_knowledge", ¶ms.0).await {
return result;
}
if let Some(refusal) = self.local_cross_project_refusal(params.0.project.as_deref(), None) {
return refusal;
}
let Some(repo_root) = self.repo_root.read().clone() else {
return "status=unavailable\nreason=persistent_state_unavailable".to_string();
};
let state_placement = self.state_placement.read().clone();
let persistence_health = *self.persistence_health.read();
let coordinator = Arc::clone(&self.curation_coordinator);
let index = Arc::clone(&self.index);
let input = params.0;
tokio::task::spawn_blocking(move || {
coordinator.execute(
&index,
&repo_root,
state_placement.as_ref(),
persistence_health,
&input,
)
})
.await
.unwrap_or_else(|_| {
"Error: curation_worker_failed; no policy mutation was acknowledged.".to_string()
})
}
pub(crate) async fn search_text(&self, params: Parameters<SearchTextInput>) -> String {
if let Some(result) = self.proxy_tool_call("search_text", ¶ms.0).await {
return result;
}
// Feature 012 (Phase 3): honest refusal for a cross-project request with
// no daemon (no working set on the local path).
if let Some(refusal) = self
.local_cross_project_refusal(params.0.project.as_deref(), params.0.projects.as_deref())
{
return refusal;
}
if params.0.estimate == Some(true) {
let limit = params.0.limit.unwrap_or(50) as usize;
let per_file = params.0.max_per_file.unwrap_or(5) as usize;
let est = limit * 20 + 50;
return format!(
"Estimate for search_text: ~{} tokens (limit={}, max_per_file={})",
est, limit, per_file
);
}
// Structural (AST-pattern) search mode.
if params.0.structural.unwrap_or(false) {
let pattern = match params.0.query.as_deref() {
Some(p) if !p.trim().is_empty() => p.trim(),
_ => return "Error: `query` is required for structural search.".to_string(),
};
let options = match search_text_options_from_input(¶ms.0) {
Ok(o) => o,
Err(message) => return message,
};
let mut result = {
let guard = self.index.read();
loading_guard!(guard);
let mut result = search::search_structural(&guard, pattern, &options);
resolve_text_search_enclosing_symbols(&guard, &mut result);
result
};
apply_path_predicate_filter(
&mut result,
params.0.include_vendor.unwrap_or(false),
params.0.include_personal_tooling.unwrap_or(false),
);
maybe_compact_text_search_result(&mut result, pattern);
let output = render_search_text_output(
self,
result,
Some(pattern),
true,
params.0.group_by.as_deref(),
params.0.terms.as_deref(),
&options,
false,
false,
false,
);
self.session_context.record_summary_output(
"search_text",
(output.len() / 4).min(u32::MAX as usize) as u32,
);
return self.apply_ccr_budget("search_text", output, params.0.max_tokens);
}
let mut options = match search_text_options_from_input(¶ms.0) {
Ok(options) => options,
Err(message) => return message,
};
let mut is_regex = params.0.regex.unwrap_or(false);
let mut auto_detected_regex = false;
let original_query = params.0.query.clone();
// Auto-detect regex patterns: if regex is not explicitly set and the
// query contains unambiguous regex sequences (\w, \d, \s, \b, .+, .*),
// enable regex mode automatically. These sequences never appear
// literally in code, so treating them as literals always gives 0 results.
if !is_regex && let Some(ref q) = params.0.query {
let has_regex_escape = q.contains("\\w")
|| q.contains("\\d")
|| q.contains("\\s")
|| q.contains("\\b")
|| q.contains("\\W")
|| q.contains("\\D")
|| q.contains("\\S");
if has_regex_escape {
is_regex = true;
auto_detected_regex = true;
// Relax noise policy for auto-detected regex — the user
// is doing a targeted pattern search and expects grep-like
// completeness, so include test files by default.
if params.0.include_tests.is_none() {
options.noise_policy.include_tests = true;
}
}
}
// Extract churn scores from GitTemporalIndex BEFORE acquiring the
// LiveIndex read lock to avoid lock ordering issues.
if options.ranked {
let git_temporal = self.index.git_temporal();
if matches!(
git_temporal.state,
crate::live_index::git_temporal::GitTemporalState::Ready
) {
let churn_map: std::collections::HashMap<String, f32> = git_temporal
.files
.iter()
.map(|(path, history)| (path.clone(), history.churn_score))
.collect();
if !churn_map.is_empty() {
options.churn_scores = Some(churn_map);
}
}
}
let mut result = {
let guard = self.index.read();
loading_guard!(guard);
let mut r = search::search_text_with_options(
&guard,
params.0.query.as_deref(),
params.0.terms.as_deref(),
is_regex,
&options,
);
resolve_text_search_enclosing_symbols(&guard, &mut r);
// Enrich with callers if follow_refs is set
if params.0.follow_refs.unwrap_or(false)
&& let Ok(ref mut text_result) = r
{
let limit = params.0.follow_refs_limit.unwrap_or(3) as usize;
enrich_with_callers(&guard, text_result, limit);
}
r
};
apply_path_predicate_filter(
&mut result,
params.0.include_vendor.unwrap_or(false),
params.0.include_personal_tooling.unwrap_or(false),
);
// Auto-correct double-escaped regex patterns: if regex=true and the
// result is InvalidRegex or Ok-but-empty, try fixing common
// double-escaped character classes (\\s → \s, \\d → \d, etc.).
if is_regex {
let should_retry = match &result {
Err(search::TextSearchError::InvalidRegex { .. }) => true,
Ok(r) if r.files.is_empty() => true,
_ => false,
};
if should_retry
&& let Some(ref query) = original_query
&& let Some(fixed) = fix_common_double_escapes(query)
{
let mut retry_result = {
let guard = self.index.read();
loading_guard!(guard);
let mut r = search::search_text_with_options(
&guard,
Some(fixed.as_str()),
params.0.terms.as_deref(),
true,
&options,
);
resolve_text_search_enclosing_symbols(&guard, &mut r);
if params.0.follow_refs.unwrap_or(false)
&& let Ok(ref mut text_result) = r
{
let limit = params.0.follow_refs_limit.unwrap_or(3) as usize;
enrich_with_callers(&guard, text_result, limit);
}
r
};
apply_path_predicate_filter(
&mut retry_result,
params.0.include_vendor.unwrap_or(false),
params.0.include_personal_tooling.unwrap_or(false),
);
// Use the retry result if it actually produced matches
if let Ok(ref retry_ok) = retry_result
&& !retry_ok.files.is_empty()
{
let mut output = render_search_text_output(
self,
retry_result,
Some(fixed.as_str()),
false,
params.0.group_by.as_deref(),
params.0.terms.as_deref(),
&options,
true,
auto_detected_regex,
true,
);
output.push_str(&format!(
"\n(auto-corrected double-escaped regex: `{}` → `{}`)",
query, fixed
));
self.session_context.record_summary_output(
"search_text",
(output.len() / 4).min(u32::MAX as usize) as u32,
);
return self.apply_ccr_budget("search_text", output, params.0.max_tokens);
}
}
}
let compaction_query =
search_text_compaction_query(params.0.query.as_deref(), params.0.terms.as_deref());
maybe_compact_text_search_result(&mut result, &compaction_query);
let output = render_search_text_output(
self,
result,
params.0.query.as_deref(),
false,
params.0.group_by.as_deref(),
params.0.terms.as_deref(),
&options,
is_regex,
auto_detected_regex,
false,
);
let result = output;
self.session_context.record_summary_output(
"search_text",
(result.len() / 4).min(u32::MAX as usize) as u32,
);
// Intentionally NO frecency bump here — search_text is a discovery
// tool. Bumping on discovery would create a positive feedback loop
// (hot files get searched more, which would bump them more, which
// would rank them higher still). See wiki `[[SymForge Frecency-
// Weighted File Ranking]]` §"Search tools deliberately do NOT bump".
self.apply_ccr_budget("search_text", result, params.0.max_tokens)
}
/// Internal: trace_symbol logic, called by get_symbol_context when sections are provided.
/// The daemon compatibility alias routes through get_symbol_context so this
/// canonical path owns trace-mode behavior.
#[cfg(test)]
pub(crate) async fn trace_symbol(&self, params: Parameters<TraceSymbolInput>) -> String {
if let Some(result) = self.proxy_tool_call("trace_symbol", ¶ms.0).await {
return result;
}
let sections = visible_sections(¶ms.0.sections);
if params.0.estimate == Some(true) {
let section_count = sections
.as_ref()
.map(|s| if s.is_empty() { 4 } else { s.len() })
.unwrap_or(4);
let est = 200 + section_count * 200;
return format!(
"Estimate for trace_symbol: ~{} tokens ({} sections)",
est, section_count
);
}
let published = self.index.published_generation();
if let Some(message) = loading_guard_message_from_published(&published.health) {
return message;
}
let trace_view =
capture_trace_symbol_view_for_generation(&published, ¶ms.0, sections.as_deref());
let verbosity = params.0.verbosity.as_deref().unwrap_or("full");
let output = format::trace_symbol_result_view(
&trace_view,
¶ms.0.name,
verbosity,
params.0.max_tokens,
);
self.session_context.record_symbol(
¶ms.0.path,
¶ms.0.name,
(output.len() / 4) as u32,
);
output
}
/// Inspect a specific line in full symbol context: shows the enclosing symbol, parent chain,
/// and siblings. Works standalone with just path + line, or after search_text to deep-dive a match.
#[tool(
description = "Inspect a specific line in full symbol context: enclosing symbol, parent chain (e.g. module → class → method), and sibling symbols. Works standalone with just path + line number, or after search_text to deep-dive a specific hit. NOT for finding all occurrences of a pattern (use search_text). NOT for understanding a symbol's callers and callees (use get_symbol_context).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn inspect_match(&self, params: Parameters<InspectMatchInput>) -> String {
if let Some(result) = self.proxy_tool_call("inspect_match", ¶ms.0).await {
return result;
}
if params.0.estimate == Some(true) {
let context = params.0.context.unwrap_or(3) as usize;
let siblings = params.0.sibling_limit.unwrap_or(10) as usize;
let est = (context * 2 + 1) * 20 + siblings * 8 + 80;
return format!(
"Estimate for inspect_match: ~{} tokens (context={}, siblings={})",
est, context, siblings
);
}
let view = {
let guard = self.index.read();
loading_guard!(guard);
guard.capture_inspect_match_view(
¶ms.0.path,
params.0.line,
params.0.context,
params.0.sibling_limit,
)
};
let output = format::inspect_match_result_view(&view);
self.session_context.record_summary_output(
"inspect_match",
(output.len() / 4).min(u32::MAX as usize) as u32,
);
format::enforce_token_budget(output, params.0.max_tokens)
}
/// Find files by path, filename, or folder — ranked by relevance. With changed_with=path,
/// finds co-changing files via git temporal coupling. Set rank_by="path+cochange" with
/// anchor_path to fuse path matches with the coupling store. Set resolve=true for exact path resolution.
/// NOT for file content search (use search_text). NOT for symbol names (use search_symbols).
#[tool(
name = "search_files",
description = "Prefer this over a shell find/glob for locating files: it ranks by relevance (frecency + path match) and resolves an ambiguous or partial path to one exact project path. Find files by path, filename, or folder — ranked by relevance. Modes: (1) default: fuzzy search ranked by relevance, (2) changed_with=path: co-changing files via git temporal coupling, (3) rank_by=\"path+cochange\" with anchor_path: fuse path matches with coupling-store evidence, (4) resolve=true: resolve an ambiguous filename or partial path to one exact project path. NOT for file content search (use search_text). NOT for symbol names (use search_symbols).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn search_files_tool(
&self,
params: Parameters<SearchFilesInput>,
) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
let started = Instant::now();
let output = self.search_files(params).await;
let outcome_class = classify_search_files_output(&output);
self.record_tool_completion("search_files", &output, started.elapsed(), outcome_class);
statused_tool_result(output, outcome_class)
}
pub(crate) async fn search_files(&self, params: Parameters<SearchFilesInput>) -> String {
if let Some(result) = self.proxy_tool_call("search_files", ¶ms.0).await {
return result;
}
if let Some(refusal) = self.foreign_project_refusal(params.0.project.as_deref()) {
return refusal;
}
let include_vendor = params.0.include_vendor.unwrap_or(false);
let include_personal_tooling = params.0.include_personal_tooling.unwrap_or(false);
if params.0.estimate == Some(true) {
let limit = params.0.limit.unwrap_or(20) as usize;
let est = limit * 10 + 30;
return format!(
"Estimate for search_files: ~{} tokens (limit={})",
est, limit
);
}
// Resolve mode: exact path resolution
if params.0.resolve.unwrap_or(false) {
if params.0.query.is_empty() {
return "search_files with resolve=true requires a non-empty `query`.".to_string();
}
let view = {
let guard = self.index.read();
loading_guard!(guard);
guard.capture_search_files_resolve_view_with_noise(
¶ms.0.query,
include_vendor,
include_personal_tooling,
)
};
let hidden_noise_count = if include_vendor && include_personal_tooling {
0
} else {
let guard = self.index.read();
let unfiltered = guard.capture_search_files_resolve_view(¶ms.0.query);
search_files_resolve_candidate_count(&unfiltered)
.saturating_sub(search_files_resolve_candidate_count(&view))
};
let envelope = match &view {
SearchFilesResolveView::Resolved { path } => {
let guard = self.index.read();
Some(search_format::format_search_envelope(
search_files_resolve_match_type_label(&view),
index_source_authority_label(&self.index.freshness_status()),
search_parse_state_for_paths(&guard, std::iter::once(path.as_str())),
&search_completeness_label(0, hidden_noise_count),
&search_files_scope_summary(
"resolve=true against indexed file paths",
include_vendor,
include_personal_tooling,
),
&search_paths_evidence(std::iter::once(path.as_str())),
))
}
SearchFilesResolveView::ResolvedMetadataOnly { path, reason } => {
// Tier-2 path: never parsed, so report the metadata-only
// parse state honestly instead of the misleading "parsed".
Some(search_format::format_search_envelope(
search_files_resolve_match_type_label(&view),
index_source_authority_label(&self.index.freshness_status()),
"metadata-only (not parsed)",
&search_completeness_label(0, hidden_noise_count),
&search_files_scope_summary(
"resolve=true against indexed file paths",
include_vendor,
include_personal_tooling,
),
&format!("Tier-2 metadata-only path `{path}` ({reason}); never parsed"),
))
}
SearchFilesResolveView::Ambiguous {
matches,
overflow_count,
..
} => {
let guard = self.index.read();
Some(search_format::format_search_envelope(
search_files_resolve_match_type_label(&view),
index_source_authority_label(&self.index.freshness_status()),
search_parse_state_for_paths(
&guard,
matches.iter().map(std::string::String::as_str),
),
&search_completeness_label(*overflow_count, hidden_noise_count),
&search_files_scope_summary(
"resolve=true against indexed file paths",
include_vendor,
include_personal_tooling,
),
&search_paths_evidence(matches.iter().map(std::string::String::as_str)),
))
}
_ => None,
};
let output = format::search_files_resolve_result_view(&view);
let had_envelope = envelope.is_some();
let result = match envelope {
Some(envelope) => format!("{envelope}\n\n{output}"),
None => output,
};
let mut result = result;
if !had_envelope {
append_search_files_filter_summary(
&mut result,
include_vendor,
include_personal_tooling,
);
}
if let Some(note) = search_files_hidden_noise_note(
hidden_noise_count,
include_vendor,
include_personal_tooling,
) {
result.push_str("\n\n");
result.push_str(¬e);
}
if matches!(view, SearchFilesResolveView::NotFound { .. }) {
let matching_untracked_paths = matching_untracked_paths_for_search_files(
self,
¶ms.0.query,
include_vendor,
include_personal_tooling,
);
append_untracked_file_diagnostic(&mut result, &matching_untracked_paths);
}
let result = format::enforce_token_budget(result, params.0.max_tokens);
self.session_context.record_summary_output(
"search_files",
(result.len() / 4).min(u32::MAX as usize) as u32,
);
return result;
}
// Deprecated since v7.x: prefer `rank_by="path+cochange"` with `anchor_path`.
// Keep this compatibility path behavior unchanged for one release cycle.
if let Some(ref target_path) = params.0.changed_with {
let temporal = self.index.git_temporal();
match temporal.state {
crate::live_index::git_temporal::GitTemporalState::Ready => {}
crate::live_index::git_temporal::GitTemporalState::Unavailable(ref reason) => {
return append_changed_with_deprecation_warning(format!(
"Git temporal data unavailable: {reason}"
));
}
_ => {
return append_changed_with_deprecation_warning(
"Git temporal data is still loading. Try again in a few seconds."
.to_string(),
);
}
}
let commit_count = temporal.stats.total_commits_analyzed;
if let Some(history) = temporal.files.get(target_path.as_str()) {
let hits: Vec<SearchFilesHit> = history
.co_changes
.iter()
.map(|entry| SearchFilesHit {
tier: SearchFilesTier::CoChange,
path: entry.path.clone(),
coupling_score: Some(entry.coupling_score),
shared_commits: Some(entry.shared_commits),
metadata_reason: None,
})
.collect();
let weak_hits: Vec<SearchFilesHit> = history
.weak_co_changes
.iter()
.map(|entry| SearchFilesHit {
tier: SearchFilesTier::CoChange,
path: entry.path.clone(),
coupling_score: Some(entry.coupling_score),
shared_commits: Some(entry.shared_commits),
metadata_reason: None,
})
.collect();
if hits.is_empty() {
if !weak_hits.is_empty() {
let total = weak_hits.len();
let mut result =
format::search_files_result_view(&SearchFilesView::Found {
query: format!("weak co-changes with {target_path}"),
total_matches: total,
overflow_count: 0,
hits: weak_hits,
});
let envelope = {
let guard = self.index.read();
search_format::format_search_envelope(
"weak heuristic (git-temporal coupling)",
"current index + git temporal",
search_parse_state_for_paths(
&guard,
history
.weak_co_changes
.iter()
.map(|entry| entry.path.as_str()),
),
"full for current scope",
&format!(
"weak git-temporal co-change candidates for `{target_path}`"
),
&search_paths_evidence(
history
.weak_co_changes
.iter()
.map(|entry| entry.path.as_str()),
),
)
};
result = format!("{envelope}\n\n{result}");
result.push_str(
"\n\nLow confidence: these candidates missed the strong threshold (2 shared commits and Jaccard >= 0.15). Use them as hints, not proof.",
);
if commit_count < 50 {
result.push_str(&format!(
"\nOnly {commit_count} commit(s) were analyzed, so coupling may strengthen as history grows."
));
}
return append_changed_with_deprecation_warning(result);
}
let result = if commit_count < 50 {
format!(
"No high-confidence co-change data for '{target_path}'. Only {commit_count} commit(s) analyzed — strong co-change needs at least 2 shared commits and Jaccard >= 0.15. Results improve with more history."
)
} else {
format!(
"No high-confidence co-change data for '{target_path}' (analyzed {commit_count} commits). This file may change independently of others or only have weak coupling signals."
)
};
return append_changed_with_deprecation_warning(result);
}
let total = hits.len();
let mut result = format::search_files_result_view(&SearchFilesView::Found {
query: format!("co-changes with {target_path}"),
total_matches: total,
overflow_count: 0,
hits,
});
let envelope = {
let guard = self.index.read();
search_format::format_search_envelope(
"heuristic (git-temporal coupling)",
"current index + git temporal",
search_parse_state_for_paths(
&guard,
history.co_changes.iter().map(|entry| entry.path.as_str()),
),
"full for current scope",
&format!("git-temporal co-changes for `{target_path}`"),
&search_paths_evidence(
history.co_changes.iter().map(|entry| entry.path.as_str()),
),
)
};
result = format!("{envelope}\n\n{result}");
if commit_count < 50 {
result.push_str(&format!(
"\n\n⚠ Low confidence: only {commit_count} commit(s) analyzed. Coupling scores may shift as history grows."
));
}
return append_changed_with_deprecation_warning(result);
}
if commit_count < 20 {
return append_changed_with_deprecation_warning(format!(
"'{target_path}' not found in git history ({commit_count} commit(s) analyzed). Co-change analysis needs more history to produce useful results."
));
}
return append_changed_with_deprecation_warning(format!(
"No git history found for '{target_path}'. Check the file path is correct and that it has been committed."
));
}
if params.0.query.is_empty() {
return "search_files requires a non-empty `query` (or use `changed_with` to find co-changing files).".to_string();
}
let rank_by_path_cochange = params.0.rank_by.as_deref() == Some("path+cochange");
let rank_by_frecency = params.0.rank_by.as_deref() == Some("frecency");
let ranking_diagnostics = search_files_debug_ranking_requested(¶ms.0);
let debug_ranking = ranking_diagnostics.explain;
let mut cochange_evidence: Option<CapabilityEvidence> = None;
let mut frecency_evidence: Option<CapabilityEvidence> = None;
let mut hidden_noise_count = 0usize;
let cochange_repo_root = if rank_by_path_cochange {
self.capture_repo_root()
} else {
None
};
let cochange_project_state = rank_by_path_cochange
.then(|| self.capture_project_state_dir())
.flatten();
let mut view = {
let guard = self.index.read();
loading_guard!(guard);
let cochange_resolution = if rank_by_path_cochange {
match params.0.anchor_path.as_deref() {
Some(anchor_path) => Some(search_files_coupling_neighbors(
&guard,
cochange_repo_root.as_deref(),
cochange_project_state.as_ref(),
anchor_path,
)),
None => Some(SearchFilesCoChangeResolution {
neighbors: None,
evidence: cochange_ranking_evidence(
CapabilityStatus::FallbackUsed,
CapabilityFreshness::Unknown,
CapabilityCost::Free,
"`rank_by=\"path+cochange\"` requires `anchor_path=<path>`; path ranking returned",
),
}),
}
} else {
None
};
if let Some(resolution) = &cochange_resolution {
cochange_evidence = Some(resolution.evidence.clone());
}
let coupling_neighbors = cochange_resolution
.as_ref()
.and_then(|resolution| resolution.neighbors.as_ref());
let coupling_context = params.0.anchor_path.as_deref().zip(coupling_neighbors);
// Optional path-prefix scoping, mirroring the `path_scope` axis of
// search_symbols/search_text: the scope is applied inside the capture
// (pre-count predicate), so total_matches/overflow_count/hits are all
// consistently scoped — including the overflow set, not just the
// visible hits.
let path_scope = normalize_path_prefix(params.0.path_prefix.as_deref());
let view = guard.capture_search_files_view_with_noise(
¶ms.0.query,
params.0.limit.unwrap_or(20) as usize,
params.0.current_file.as_deref(),
coupling_context,
include_vendor,
include_personal_tooling,
&path_scope,
);
if !(include_vendor && include_personal_tooling) {
// Same path_scope so hidden_noise_count compares like-for-like
// (noise hidden WITHIN the requested prefix, not repo-wide).
let unfiltered = guard.capture_search_files_view_with_noise(
¶ms.0.query,
params.0.limit.unwrap_or(20) as usize,
params.0.current_file.as_deref(),
coupling_context,
true,
true,
&path_scope,
);
hidden_noise_count = search_files_total_matches(&unfiltered)
.saturating_sub(search_files_total_matches(&view));
}
if rank_by_path_cochange && let Some((anchor_path, neighbors)) = coupling_context {
let applied_hits = match &view {
SearchFilesView::Found { hits, .. } => hits
.iter()
.filter(|hit| hit.tier == SearchFilesTier::CoChange)
.count(),
_ => 0,
};
cochange_evidence = if applied_hits > 0 {
Some(cochange_ranking_evidence(
CapabilityStatus::Applied,
CapabilityFreshness::Current,
CapabilityCost::Low,
format!(
"anchor_path={anchor_path} loaded {} usable coupling partner(s); rows with shared-commit counts show applied evidence",
neighbors.len()
),
))
} else {
let candidate_paths: Vec<&str> = match &view {
SearchFilesView::Found { hits, .. } => {
hits.iter().map(|hit| hit.path.as_str()).collect()
}
_ => Vec::new(),
};
Some(cochange_ranking_evidence(
CapabilityStatus::FallbackUsed,
CapabilityFreshness::Current,
CapabilityCost::Low,
cochange_fallback_detail(
¶ms.0.query,
anchor_path,
neighbors,
&candidate_paths,
),
))
};
}
view
};
// Optional frecency-fusion rerank. Activated when the caller requests
// `rank_by="frecency"`, independent of the old persistent-collection
// feature flag. Discovery still never opens a writeable frecency store:
// this branch only reads existing persistent rows and current-process
// session rows, then reports explicit evidence for every fallback.
if rank_by_frecency {
match crate::live_index::frecency::collection_policy_from_env() {
crate::capability::FrecencyCollectionPolicy::Disabled => {
frecency_evidence = Some(frecency_ranking_evidence(
CapabilityStatus::DisabledByPolicy,
"operator policy disabled frecency collection and ranking; path ranking returned",
));
}
_ => match &mut view {
SearchFilesView::Found { hits, .. } if hits.is_empty() => {
frecency_evidence = Some(frecency_ranking_evidence(
CapabilityStatus::FallbackUsed,
"no returned candidates to score; path ranking returned",
));
}
SearchFilesView::Found { hits, .. } => {
if let Some(repo_root) = self.capture_repo_root() {
let project_state = self.capture_project_state_dir();
let candidate_count = hits.len();
let hit_paths: Vec<std::path::PathBuf> = hits
.iter()
.map(|hit| std::path::PathBuf::from(&hit.path))
.collect();
let path_refs: Vec<&std::path::Path> =
hit_paths.iter().map(|path| path.as_path()).collect();
let now_ts = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|duration| duration.as_secs() as i64)
.unwrap_or(0);
match crate::live_index::frecency::ranking_scores_for_paths(
&repo_root,
project_state.as_ref(),
&path_refs,
now_ts,
) {
Ok(Some(snapshot)) if !snapshot.scores.is_empty() => {
let scored_count = snapshot.scores.len();
let breakdowns =
crate::live_index::search::score_hits_by_frecency_fusion(
hits,
&snapshot.scores,
);
let taken = std::mem::take(hits);
*hits =
crate::live_index::search::reorder_hits_by_frecency_fusion(
taken,
&breakdowns,
);
frecency_evidence = Some(frecency_ranking_evidence(
CapabilityStatus::Applied,
format!(
"{scored_count}/{candidate_count} returned candidates had frecency scores from {}; requested frecency ranking applied",
snapshot.source
),
));
}
Ok(Some(snapshot)) => {
frecency_evidence = Some(frecency_ranking_evidence(
CapabilityStatus::FallbackUsed,
format!(
"{} is empty or has no scores for returned candidates; path ranking returned",
snapshot.source
),
));
}
Ok(None) => {
frecency_evidence = Some(frecency_ranking_evidence(
CapabilityStatus::FallbackUsed,
"no frecency history found; path ranking returned",
));
}
Err(reason) => {
frecency_evidence = Some(frecency_ranking_evidence(
CapabilityStatus::Unavailable,
format!(
"unable to read frecency history: {reason}; path ranking returned"
),
));
}
}
} else {
frecency_evidence = Some(frecency_ranking_evidence(
CapabilityStatus::Unavailable,
"no repository root is bound; path ranking returned",
));
}
}
_ => {
frecency_evidence = Some(frecency_ranking_evidence(
CapabilityStatus::FallbackUsed,
"no returned candidates to score; path ranking returned",
));
}
},
}
}
let envelope = match &view {
SearchFilesView::Found {
hits,
overflow_count,
..
} => {
let guard = self.index.read();
let scope = match params.0.current_file.as_deref() {
Some(current_file) => {
format!("ranked indexed file paths; current file boost `{current_file}`")
}
None => "ranked indexed file paths".to_string(),
};
Some(search_format::format_search_envelope(
search_files_match_type_label(&view),
// The two composite labels already differ from the bare
// "current index" sentinel, so they never collapse the
// envelope; only the plain arm needed measuring. They do
// still say "current" unconditionally — worth revisiting
// once every lane derives its own prefix.
if rank_by_path_cochange {
"current index + optional coupling store"
} else if rank_by_frecency {
"current index + optional frecency history"
} else {
index_source_authority_label(&self.index.freshness_status())
},
search_parse_state_for_paths(&guard, hits.iter().map(|hit| hit.path.as_str())),
&search_completeness_label(*overflow_count, hidden_noise_count),
&search_files_scope_summary(scope, include_vendor, include_personal_tooling),
&search_paths_evidence(hits.iter().map(|hit| hit.path.as_str())),
))
}
_ => None,
};
let output = format::search_files_result_view(&view);
let had_envelope = envelope.is_some();
let mut result = match envelope {
Some(envelope) => format!("{envelope}\n\n{output}"),
None => output,
};
if !had_envelope {
append_search_files_filter_summary(
&mut result,
include_vendor,
include_personal_tooling,
);
}
if let Some(evidence) = cochange_evidence.as_ref() {
result.push_str("\n\n");
result.push_str(&format::capability_evidence_line(evidence));
}
if let Some(evidence) = frecency_evidence.as_ref() {
result.push_str("\n\n");
result.push_str(&format::capability_evidence_line(evidence));
}
if let Some(evidence) = ranking_diagnostics.evidence.as_ref() {
result.push_str("\n\n");
result.push_str(&format::capability_evidence_line(evidence));
}
if debug_ranking {
result.push_str("\n\n");
result.push_str(&search_files_ranking_explanation(
&view,
params.0.rank_by.as_deref(),
cochange_evidence.as_ref(),
frecency_evidence.as_ref(),
));
}
if let Some(note) = search_files_hidden_noise_note(
hidden_noise_count,
include_vendor,
include_personal_tooling,
) {
result.push_str("\n\n");
result.push_str(¬e);
}
if matches!(view, SearchFilesView::NotFound { .. }) {
let matching_untracked_paths = matching_untracked_paths_for_search_files(
self,
¶ms.0.query,
include_vendor,
include_personal_tooling,
);
append_untracked_file_diagnostic(&mut result, &matching_untracked_paths);
}
self.session_context.record_summary_output(
"search_files",
(result.len() / 4).min(u32::MAX as usize) as u32,
);
// Intentionally NO frecency bump here — search_files is a discovery
// tool, and bumping on discovery creates a positive feedback loop
// where files that rank high are searched more, which makes them
// rank even higher. Bumps fire only on commitment (get_file_context,
// get_file_content, get_symbol, get_symbol_context, and the 7 edit
// tools via EditHook). See wiki `[[SymForge Frecency-Weighted File
// Ranking]]` §"Search tools deliberately do NOT bump".
result
}
/// Resolve the co-change anchor for a fused-find `search_files` step.
///
/// US4 find fusion: the STEL planner is index-free, so it emits the
/// `search_files` path step with `rank_by="path+cochange"` but NO
/// `anchor_path`. Anchor resolution belongs where the index lives — here.
///
/// The path matcher reads a multi-word query as `component…/basename`, so a
/// fuzzy bag of words whose trailing token is not a file basename (e.g.
/// `"stel planner find"`) yields no path candidates. To stay robust to token
/// order we try the full query first, then each individual token, and take
/// the first top Tier-1 path hit. `search_files`'s own
/// `CO_CHANGE_ANCHOR_CONFIDENCE_FLOOR=basename` gate still decides whether
/// the boost applies, so a weak anchor degrades to pure path ranking with no
/// special-casing. Returns `None` when nothing path-like matches.
///
/// Reads only the index path view (never `get_*`), so this stays on the
/// frecency-neutral discovery surface.
pub(crate) fn resolve_find_fusion_cochange_anchor(&self, query: &str) -> Option<String> {
let guard = self.index.read();
let top_hit = |q: &str| -> Option<String> {
match guard.capture_search_files_view(q, 5, None, None) {
SearchFilesView::Found { hits, .. } => hits
.into_iter()
.find(|hit| hit.tier != SearchFilesTier::MetadataOnly)
.map(|hit| hit.path),
_ => None,
}
};
if let Some(hit) = top_hit(query) {
return Some(hit);
}
query
.split_whitespace()
.filter(|tok| tok.chars().any(char::is_alphanumeric))
.find_map(top_hit)
}
/// Task 4 Step 5: whether a planned facade step's tool accepts the single
/// `project` selector the facade routes — the daemon's single-project
/// routed set plus the set-valued discovery verbs (which take `project`
/// too). A plan containing any other tool refuses project routing
/// all-or-nothing rather than part-routing the chain.
fn facade_step_accepts_project(tool: &str) -> bool {
crate::daemon::single_project_routed_tool(tool)
|| matches!(
tool,
"search_symbols"
| "search_text"
| "search_knowledge"
| "find_references"
| "search_files"
)
}
/// Inject the resolved co-change anchor into a fused-find `search_files` step.
///
/// Recognizes the find-fusion path step by its exact emitted shape
/// (`tool == "search_files"` AND `rank_by == "path+cochange"` AND no
/// `anchor_path`) — the only planner route that emits that shape.
///
/// When an anchor resolves, the path step is retargeted to that anchor:
/// `query` becomes the anchor path and `anchor_path` is set, so the path
/// side surfaces the best-matching file PLUS its boosted co-change partners
/// (the broad multi-file listing is already carried by the fusion's
/// `search_text` step). The `CO_CHANGE_ANCHOR_CONFIDENCE_FLOOR=basename`
/// gate inside `search_files` still decides whether the boost actually
/// applies. When no anchor resolves, `rank_by` is dropped so the step runs
/// as plain path ranking on the original query (graceful
/// co-change-unavailable degradation). Every other step is unchanged.
fn inject_find_fusion_cochange_anchor(
&self,
tool: &str,
args: &serde_json::Value,
) -> serde_json::Value {
let is_fusion_path_step = tool == "search_files"
&& args.get("rank_by").and_then(serde_json::Value::as_str) == Some("path+cochange")
&& args.get("anchor_path").is_none();
if !is_fusion_path_step {
return args.clone();
}
let query = args
.get("query")
.and_then(serde_json::Value::as_str)
.unwrap_or_default();
let mut args = args.clone();
let Some(map) = args.as_object_mut() else {
return args;
};
match self.resolve_find_fusion_cochange_anchor(query) {
Some(anchor) => {
// Retarget the path side to the anchor's basename STEM. The stem
// names the anchor's own basename, so the anchor clears the
// `CO_CHANGE_ANCHOR_CONFIDENCE_FLOOR=basename` gate (via the
// SF-006 stem-equals-basename anchor promotion), while files
// that share the stem prefix (a common co-change-partner naming
// pattern) remain candidates the boost can promote. Falls back
// to the full anchor path when it has no usable stem.
let path_query = std::path::Path::new(&anchor)
.file_stem()
.and_then(|stem| stem.to_str())
.filter(|stem| stem.len() >= 3)
.map(str::to_string)
.unwrap_or_else(|| anchor.clone());
map.insert("query".to_string(), serde_json::Value::String(path_query));
map.insert("anchor_path".to_string(), serde_json::Value::String(anchor));
}
None => {
// No path-like anchor → pure path ranking on the original query.
// Drop the co-change request so search_files does not emit a
// fallback-evidence note for a speculative request.
map.remove("rank_by");
}
}
args
}
/// US5 economics grounding (010 FR-014, D2): stamp real target byte sizes onto
/// the plan steps so the L2 gate predicts from actual work instead of the
/// plan-only `400/800` constants. The plan-only planner has no index; the
/// index lives here, so this is where real sizes are resolved (mirrors
/// `inject_find_fusion_cochange_anchor`).
///
/// Grounding is restricted to the **single-file read family** —
/// `get_file_context`, `get_file_content`, `get_symbol` — whose competent
/// manual baseline genuinely IS "read this one resolved file" (the model the
/// byte-grounded estimator captures). Listing/trace/search tools
/// (`find_references`, `find_dependents`, `search_*`, `explore`,
/// `get_repo_map`) are deliberately NOT grounded to a single file: their
/// manual equivalent is grep-then-window across MANY files, which a single
/// resolved definition byte length would badly *under*-state (wrongly pushing
/// an expensive trace toward bypass). Those steps keep the plan-only floor
/// (the documented interim estimate for figures not yet grounded, FR-001),
/// so grounding only ever *adds* honest single-file signal and never
/// fabricates or understates a baseline.
///
/// For a grounded step it resolves the target file — `args["path"]` directly,
/// or the file a `get_symbol` `args["name"]` is defined in (single unambiguous
/// match only) — and records its `content.len()` as an [`IndexRef`].
/// Resolution is deterministic for a fixed index state (same query + same repo
/// ⇒ same sizes ⇒ same decision; Constitution IV).
fn ground_plan_economics(&self, plan: &mut crate::stel::StelPlan) {
let guard = self.index.read();
if !guard.is_ready() {
return;
}
for step in &mut plan.steps {
if !step.index_refs.is_empty() {
continue;
}
// Only single-file read tools have a "read this one file" manual
// baseline. Symbol-name resolution applies to `get_symbol` only;
// `find_references` shares the `name` arg but is a multi-file trace.
let resolve_symbol = step.tool == "get_symbol";
if !matches!(
step.tool.as_str(),
"get_file_context" | "get_file_content" | "get_symbol"
) {
continue;
}
let resolved_path = step
.args
.get("path")
.and_then(serde_json::Value::as_str)
.map(str::trim)
.filter(|path| !path.is_empty())
.map(str::to_string)
.or_else(|| {
if !resolve_symbol {
return None;
}
// Resolve a path-less `get_symbol` step to the file the symbol
// is defined in, but only when exactly one file defines it —
// an ambiguous symbol has no single manual baseline, so we
// leave it on the plan-only floor.
let name = step
.args
.get("name")
.and_then(serde_json::Value::as_str)
.map(str::trim)
.filter(|name| !name.is_empty())?;
let candidates = symbol_candidate_paths(&guard, name);
if candidates.len() == 1 {
candidates.into_iter().next()
} else {
None
}
});
let Some(path) = resolved_path else {
continue;
};
if let Some(file) = guard.capture_shared_file(&path) {
step.index_refs
.push(crate::stel::controller::index_ref_for_target(
path,
file.content.len() as u64,
));
}
}
}
fn project_id_for_root(root: &Path) -> String {
crate::discovery::project_id_for_canonical_root(root).0
}
fn runtime_status_for(
&self,
published: &crate::live_index::PublishedIndexState,
mode: format::RuntimeMode,
project_id: Option<String>,
session_id: Option<String>,
project_root: Option<PathBuf>,
) -> format::RuntimeStatus {
let project_root = project_root.or_else(|| self.capture_repo_root());
let project_id = project_id.unwrap_or_else(|| {
project_root
.as_deref()
.map(Self::project_id_for_root)
.unwrap_or_else(|| "project-unknown".to_string())
});
let session_id =
session_id.unwrap_or_else(|| format!("local-process-{}", std::process::id()));
format::RuntimeStatus {
mode,
project_root: project_root.map(|root| root.to_string_lossy().replace('\\', "/")),
project_id,
session_id,
index_generation: published.generation,
project_generation: self.index.current_project_generation(),
reset_project_generation: self.index.current_reset_project_generation(),
load_source: published.load_source,
}
}
fn local_runtime_mode(&self) -> format::RuntimeMode {
if self.daemon_client.is_some() && self.daemon_degraded.load(Ordering::Relaxed) {
format::RuntimeMode::DaemonDegradedLocalFallback
} else {
format::RuntimeMode::LocalProcess
}
}
fn health_for_runtime(
&self,
mode: format::RuntimeMode,
project_id: Option<String>,
session_id: Option<String>,
project_root: Option<PathBuf>,
quarantine_window: format::QuarantineWindow,
) -> String {
let published = self.index.published_state();
// Capture before `session_id` is consumed: a `Some` session id means the
// report is served through a daemon session (membership authority
// applies); local in-process reports carry `None`.
let session_is_daemon = session_id.is_some();
let runtime_status =
self.runtime_status_for(&published, mode, project_id, session_id, project_root);
let watcher_guard = self.watcher_info.lock();
let rejected_stale_mutations = self.index.current_rejected_stale_mutations();
let mut result = format::health_report_from_published_state_windowed(
&published,
&watcher_guard,
rejected_stale_mutations,
quarantine_window,
);
result.push('\n');
result.push_str(&format::format_runtime_status(&runtime_status));
let sidecar_status = sidecar_status_for_server(self);
result.push('\n');
result.push_str(&format::format_sidecar_status(&sidecar_status));
if mode == format::RuntimeMode::LocalProcess
&& matches!(
sidecar_status.liveness,
crate::sidecar::port_file::SidecarLiveness::Dead
| crate::sidecar::port_file::SidecarLiveness::NoSidecar
)
{
result.push_str(
" (informational: local-process mode keeps no sidecar; hooks fail open by design)",
);
}
// Append token savings section if the sidecar's TokenStats are available.
if let Some(ref stats) = self.token_stats {
let snap = stats.summary();
let savings = format::format_token_savings(&snap);
if !savings.is_empty() {
result.push('\n');
result.push_str(&savings);
}
// Append per-tool call counts.
let counts = stats.tool_call_counts();
let counts_section = format::format_tool_call_counts(&counts);
if !counts_section.is_empty() {
result.push('\n');
result.push_str(&counts_section);
}
// Append per-tool token efficiency breakdown.
let token_details = stats.tool_token_details();
let breakdown = format::format_tool_token_breakdown(&token_details);
if !breakdown.is_empty() {
result.push('\n');
result.push_str(&breakdown);
}
}
let adoption =
crate::cli::hook::load_hook_adoption_snapshot(self.capture_repo_root().as_deref());
let adoption_section = format::format_hook_adoption(&adoption);
if !adoption_section.is_empty() {
result.push('\n');
result.push_str(&adoption_section);
}
// Append git temporal summary.
result.push('\n');
result.push_str(&format::git_temporal_health_line(
&self.index.git_temporal(),
));
let capabilities = {
let repo_root = self.capture_repo_root();
let project_state = self.capture_project_state_dir();
let guard = self.index.read();
capability_status_report(&guard, repo_root.as_deref(), project_state.as_ref())
};
result.push('\n');
result.push_str(&capabilities.full_text());
let curation_health = {
let repo_root = self.capture_repo_root();
let state_placement = self.capture_state_placement();
self.curation_coordinator.health_line(
&self.index,
repo_root.as_deref(),
state_placement.as_ref(),
*self.persistence_health.read(),
)
};
result.push('\n');
result.push_str(&curation_health);
// Feature 020 repository-knowledge health (M-001): manifest, dispositions,
// source set, bridge, temporal, authority hygiene, plus source-binding/
// runtime state. All read from already-published state; nothing recomputed.
let source_set = self.index.published_source_set();
let rk_placement = self.capture_state_placement();
let rk_root = self.capture_repo_root();
let rk_gitignore = gitignore_hygiene_status(rk_root.as_deref(), rk_placement.as_ref());
let binding_view = format::SourceBindingHealthView {
bound: rk_root.is_some(),
placement: rk_placement.as_ref(),
persistence: *self.persistence_health.read(),
session_id: &runtime_status.session_id,
daemon_session: session_is_daemon,
query_ready: published.status_label() == "Ready",
gitignore_hygiene: rk_gitignore,
};
result.push('\n');
result.push_str(&format::format_repository_knowledge_health(
&source_set,
&binding_view,
crate::live_index::store::configured_inflight_byte_budget(),
));
// Append worktree-awareness misuse counter (rolling last-hour window).
result.push('\n');
result.push_str(&format!(
"── Worktree-awareness misuse ──\nedit tool calls without working_directory (last hour): {}",
self.worktree_misuse.current_window_count(),
));
// Append frecency diagnostics when SYMFORGE_FRECENCY=1. The feature-flag
// guard mirrors the one in `frecency::bump`; when the flag is unset,
// the health output remains compact unless the feature is explicitly enabled.
if std::env::var(crate::live_index::frecency::FRECENCY_FLAG_ENV).as_deref() == Ok("1")
&& let Some(project_state) = self.capture_project_state_dir()
&& let Ok(store) = crate::live_index::frecency::FrecencyStore::open(
&crate::live_index::frecency::frecency_db_path(&project_state),
)
{
let now_ts = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_secs() as i64)
.unwrap_or(0);
if let Ok(top) = store.top_frecent(10, now_ts) {
result.push('\n');
result.push_str(&format::format_frecency_top(&top));
}
// "Last 10 frecency bumps" is additionally gated on
// the ranking diagnostics default-on policy; it is a debug-only
// surface for ranker tuning, not the default health view.
if ranking_diagnostics_policy_from_env() == RankingDiagnosticsPolicy::DefaultOn
&& let Ok(last) = store.last_10_bumps()
{
result.push('\n');
result.push_str(&format::format_frecency_last_bumps(&last));
}
}
// Surface a version-drift warning when this daemon's binary is older
// than another installed copy (e.g. an npm-updated package). Read-only;
// never copies or replaces the binary (see version_registry).
if let Some(drift) = crate::version_registry::drift_banner_default() {
result.push('\n');
result.push_str(&drift);
}
// Surface a PATH-shadow warning when a bare `symforge` would run a
// DIFFERENT install than the binary serving this runtime. Read-only;
// emits the exact remediation commands, never executes them.
if let Some(report) = current_exe_shadow_report() {
result.push('\n');
result.push_str(&crate::path_shadow::format_shadow_warning(&report));
}
result
}
fn health_compact_for_runtime(
&self,
mode: format::RuntimeMode,
project_id: Option<String>,
session_id: Option<String>,
project_root: Option<PathBuf>,
) -> String {
let published = self.index.published_state();
let session_is_daemon = session_id.is_some();
let runtime_status =
self.runtime_status_for(&published, mode, project_id, session_id, project_root);
let watcher_guard = self.watcher_info.lock();
let rejected_stale_mutations = self.index.current_rejected_stale_mutations();
let mut result = format::health_report_compact_from_published_state(
&published,
&watcher_guard,
rejected_stale_mutations,
);
result.push('\n');
result.push_str(&format::format_runtime_status_compact(&runtime_status));
let sidecar_status = sidecar_status_for_server(self);
result.push('\n');
result.push_str(&format::format_sidecar_status_compact(&sidecar_status));
if mode == format::RuntimeMode::LocalProcess
&& matches!(
sidecar_status.liveness,
crate::sidecar::port_file::SidecarLiveness::Dead
| crate::sidecar::port_file::SidecarLiveness::NoSidecar
)
{
result.push_str(
" (informational: local-process mode keeps no sidecar; hooks fail open by design)",
);
}
if let Some(ref stats) = self.token_stats {
let snap = stats.summary();
let total_saved =
snap.read_saved_tokens + snap.edit_saved_tokens + snap.grep_saved_tokens;
let total_fires =
snap.read_fires + snap.edit_fires + snap.write_fires + snap.grep_fires;
if total_fires > 0 {
result.push_str(&format!(
"\nToken savings: ~{} tokens saved across {} hook fires",
total_saved, total_fires
));
}
let counts = stats.tool_call_counts();
let total_tool_calls: usize = counts.iter().map(|(_, count)| *count).sum();
if total_tool_calls > 0 {
result.push_str(&format!(
"\nTool calls: {} recorded across {} tools",
total_tool_calls,
counts.len()
));
}
}
let git_temporal = format::git_temporal_health_line(&self.index.git_temporal());
let git_temporal_summary = git_temporal
.lines()
.next()
.unwrap_or("Git temporal: unknown");
result.push_str(&format!(
"\n{} | Worktree misuse/hour: {}",
git_temporal_summary,
self.worktree_misuse.current_window_count()
));
let capabilities = {
let repo_root = self.capture_repo_root();
let project_state = self.capture_project_state_dir();
let guard = self.index.read();
capability_status_report(&guard, repo_root.as_deref(), project_state.as_ref())
};
result.push('\n');
result.push_str(&capabilities.compact_text());
let curation_health = {
let repo_root = self.capture_repo_root();
let state_placement = self.capture_state_placement();
self.curation_coordinator.health_line(
&self.index,
repo_root.as_deref(),
state_placement.as_ref(),
*self.persistence_health.read(),
)
};
result.push('\n');
result.push_str(&curation_health);
// Feature 020 repository-knowledge health (M-001), compact form.
let source_set = self.index.published_source_set();
let rk_placement = self.capture_state_placement();
let rk_root = self.capture_repo_root();
let rk_gitignore = gitignore_hygiene_status(rk_root.as_deref(), rk_placement.as_ref());
let binding_view = format::SourceBindingHealthView {
bound: rk_root.is_some(),
placement: rk_placement.as_ref(),
persistence: *self.persistence_health.read(),
session_id: &runtime_status.session_id,
daemon_session: session_is_daemon,
query_ready: published.status_label() == "Ready",
gitignore_hygiene: rk_gitignore,
};
result.push('\n');
result.push_str(&format::format_repository_knowledge_health_compact(
&source_set,
&binding_view,
));
if let Some(drift) = crate::version_registry::drift_banner_default() {
result.push('\n');
result.push_str(&drift);
}
// Compact PATH-shadow banner (one line, points at full health for the
// exact fix). See `health_for_runtime` for the full block.
if let Some(report) = current_exe_shadow_report() {
result.push('\n');
result.push_str(&crate::path_shadow::format_shadow_warning_compact(&report));
}
result
}
pub(crate) fn health_for_daemon_session(
&self,
project_id: String,
session_id: String,
project_root: PathBuf,
quarantine_window: format::QuarantineWindow,
) -> String {
self.health_for_runtime(
format::RuntimeMode::DaemonReusedSession,
Some(project_id),
Some(session_id),
Some(project_root),
quarantine_window,
)
}
pub(crate) fn health_compact_for_daemon_session(
&self,
project_id: String,
session_id: String,
project_root: PathBuf,
) -> String {
self.health_compact_for_runtime(
format::RuntimeMode::DaemonReusedSession,
Some(project_id),
Some(session_id),
Some(project_root),
)
}
/// Diagnostic: index status, file/symbol counts, load time, watcher state, token savings,
/// project/session identity, hook adoption metrics, git temporal status. Always responds
/// even during loading. Use to verify SymForge is working.
#[tool(
description = "Diagnostic: index status, file/symbol counts, project/session identity, load time, watcher state, token savings, hook adoption metrics, git temporal status. Always responds even during loading. Use to verify SymForge is working. Optional quarantine_limit/quarantine_offset page the parse/span quarantine registry (default 10) so the full list of partial/failed files is retrievable. NOT for diagnosing a specific file or symbol (use get_file_context or get_symbol).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn health(&self, params: Parameters<HealthInput>) -> String {
let input = params.0;
if let Some(result) = self.proxy_tool_call("health", &input).await {
// Ops guard (SF-001/SF-009 root-cause class): warn loudly if the daemon
// we proxied to is serving an OLDER binary than this front-end.
return append_daemon_staleness_warning(result, env!("CARGO_PKG_VERSION"));
}
let window = format::QuarantineWindow::from_args(
input.quarantine_offset(),
input.quarantine_limit(),
);
let result = self.health_for_runtime(self.local_runtime_mode(), None, None, None, window);
self.session_context
.record_summary_output("health", (result.len() / 4).min(u32::MAX as usize) as u32);
result
}
/// Compact diagnostic: essential health fields only. Use when token budget matters.
#[tool(
description = "Compact diagnostic: essential index, project/session identity, watcher, admission, and token-savings health fields only. Prefer this when token budget matters; use health for full diagnostic lists. NOT for diagnosing a specific file or symbol (use get_file_context or get_symbol).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn health_compact(&self) -> String {
if let Some(result) = self.proxy_tool_call_without_params("health_compact").await {
// Ops guard (SF-001/SF-009 root-cause class): warn loudly if the daemon
// we proxied to is serving an OLDER binary than this front-end.
return append_daemon_staleness_warning(result, env!("CARGO_PKG_VERSION"));
}
let result = self.health_compact_for_runtime(self.local_runtime_mode(), None, None, None);
self.session_context.record_summary_output(
"health_compact",
(result.len() / 4).min(u32::MAX as usize) as u32,
);
result
}
/// Serialize the current in-memory index to `.symforge/index.bin` immediately.
#[tool(
name = "checkpoint_now",
description = "Serialize the current in-memory index to `.symforge/index.bin` immediately. Uses the same atomic snapshot path as shutdown persistence and reports failures explicitly. When export_artifact=true, additionally exports the Best-tier team artifact (`.symforge/index.bin.zst` + `artifact.json`, plus a `.gitattributes` merge=ours hint) for sharing a bootstrap cache across a team — see contracts/team-artifact.md.",
annotations(
read_only_hint = false,
destructive_hint = false,
idempotent_hint = true,
open_world_hint = false
)
)]
pub(crate) async fn checkpoint_now(&self, params: Parameters<CheckpointNowInput>) -> String {
// Proxy-first: in daemon-proxy mode the daemon owns the authoritative
// live index, while this process holds only `LiveIndex::empty()`.
// Forward to the daemon (where `daemon_client` is None and `repo_root`
// is real) so the checkpoint runs against the populated index. On
// local-fallback the proxy returns None and the in-process logic below
// checkpoints the locally reloaded index.
let daemon_configured = self.daemon_client.is_some();
if let Some(result) = self.proxy_tool_call("checkpoint_now", ¶ms.0).await {
return result;
}
let repo_root = match self.capture_repo_root() {
Some(root) => root,
None => return "Checkpoint failed: no repository root configured.".to_string(),
};
let state_placement = match self.capture_state_placement() {
Some(placement) => placement,
None => {
*self.persistence_health.write() = crate::domain::CapabilityStatus::Unavailable {
reason: crate::domain::CapabilityUnavailableReason::PersistentStateUnavailable,
};
return "Checkpoint unavailable: persistence_unavailable; applied=false; no resolved project state placement."
.to_string();
}
};
let index = Arc::clone(&self.index);
let checkpoint_root = repo_root.clone();
let checkpoint_state_placement = state_placement.clone();
let verify_after_write = params.0.verify_after_write.unwrap_or(false);
let export_artifact = params.0.export_artifact.unwrap_or(false);
let artifact_access_mode = match &checkpoint_state_placement {
crate::domain::StatePlacement::UserLocal {
reason: crate::domain::UserLocalPlacementReason::ExplicitProtected,
..
} => crate::domain::SourceAccessMode::ExplicitProtected,
_ => crate::domain::SourceAccessMode::NormalProject,
};
let artifact_capability =
if artifact_access_mode == crate::domain::SourceAccessMode::ExplicitProtected {
crate::domain::CapabilityStatus::Unavailable {
reason: crate::domain::CapabilityUnavailableReason::ExplicitProtectedSource,
}
} else if matches!(
&checkpoint_state_placement,
crate::domain::StatePlacement::ProjectLocal { .. }
) {
crate::domain::CapabilityStatus::Available
} else {
crate::domain::CapabilityStatus::Unavailable {
reason: crate::domain::CapabilityUnavailableReason::NonProjectLocalPlacement,
}
};
match tokio::task::spawn_blocking(move || {
let report = crate::live_index::persist::checkpoint_shared_index(
&index,
&checkpoint_root,
&checkpoint_state_placement,
)?;
if verify_after_write
&& crate::live_index::persist::load_snapshot(
&checkpoint_root,
&checkpoint_state_placement,
)
.is_none()
{
anyhow::bail!(
"checkpoint verification failed: snapshot did not deserialize after write"
);
}
let artifact_report = if export_artifact {
let guard = index.read();
Some(crate::live_index::persist::export_artifact(
&guard,
&checkpoint_root,
artifact_access_mode,
&checkpoint_state_placement,
&artifact_capability,
)?)
} else {
None
};
anyhow::Ok((report, artifact_report))
})
.await
{
Ok(Ok((report, artifact_report))) => {
*self.persistence_health.write() = crate::domain::CapabilityStatus::Available;
let mut message = format!(
"Checkpoint complete: wrote {} bytes for {} file(s) to {}",
report.bytes,
report.files,
report.path.display()
);
// Honest receipt (review finding 2, post-v7.19.0): reaching this
// point with a daemon CONFIGURED means the proxy failed and we
// fell back to checkpointing the locally reloaded index, which
// may lag the daemon's authoritative live index. Say so, instead
// of an output indistinguishable from the daemon path — the
// snapshot written here can be staler than one the daemon would
// have written.
if daemon_configured {
message.push_str(
"\nnote: daemon unreachable; this checkpoint wrote the locally reloaded \
index, which may lag the daemon's live index. Re-run checkpoint_now once \
the daemon is reachable to persist its authoritative state.",
);
}
if let Some(artifact) = artifact_report {
message.push_str(&format!(
"\nArtifact exported: {} ({} bytes compressed from {} for {} file(s)); git_visibility={}",
artifact.path.display(),
artifact.compressed_bytes,
artifact.raw_bytes,
artifact.files,
artifact.git_visibility.as_str()
));
}
message
}
Ok(Err(error)) => {
*self.persistence_health.write() = crate::domain::CapabilityStatus::Unavailable {
reason: crate::domain::CapabilityUnavailableReason::PersistentStateUnavailable,
};
format!("Checkpoint failed: {error}")
}
Err(join_error) => {
*self.persistence_health.write() = crate::domain::CapabilityStatus::Unavailable {
reason: crate::domain::CapabilityUnavailableReason::PersistentStateUnavailable,
};
format!("Checkpoint failed: checkpoint task panicked: {join_error}")
}
}
}
/// Task 7: the LOCAL bound-project trust evidence — what this in-process
/// index would serve. Used as the seed for the per-dispatch evidence slot;
/// a daemon receipt overwrites it when the proxy answers.
pub(crate) fn local_project_evidence(
&self,
) -> Option<crate::protocol::result_status::ProjectEvidence> {
let root = self.capture_repo_root();
let published = self.index.published_state();
let load_source = self.index.read().load_source().label().to_string();
Some(crate::protocol::result_status::ProjectEvidence {
project_id: root
.as_deref()
.map(crate::daemon::project_key)
.unwrap_or_else(|| "unbound".to_string()),
project_name: self.project_name.clone(),
canonical_root: root.map(|r| r.display().to_string().replace('\\', "/")),
generation: self.index.current_project_generation(),
index_state: published.status_label().to_string(),
load_source,
index_files: published.file_count,
index_symbols: published.symbol_count,
})
}
/// True when an explicit `project`/`projects` selector RESOLVES TO THE BOUND
/// project: it equals the bound project name, the bound root's deterministic
/// project key, or the bound root path (either slash flavor). Shared by both
/// project-refusal guards so the two agree on what "local" means; an empty or
/// whitespace-only selector is treated as absent (returns false — the caller
/// decides how to handle "no selector").
fn selector_matches_bound_project(&self, selector: &str) -> bool {
let selector = selector.trim();
if selector.is_empty() {
return false;
}
if selector == self.project_name {
return true;
}
if let Some(root) = self.capture_repo_root().as_deref() {
if selector == crate::daemon::project_key(root) {
return true;
}
let root_text = root.display().to_string();
if selector == root_text || selector == root_text.replace('\\', "/") {
return true;
}
let selector_path = std::path::Path::new(selector);
if selector_path.is_absolute()
&& crate::live_index::store::normalize_root(selector_path)
== crate::live_index::store::normalize_root(root)
{
return true;
}
}
false
}
/// Task 4: local/embedded servers are bound to exactly ONE project. When a
/// tool call reaches local execution (stdio/embed, or a degraded daemon
/// fallback) carrying an explicit `project` selector that does not match
/// the bound project, refuse deterministically instead of silently serving
/// the wrong project. The selector matches when it equals the bound
/// project name, the bound root's deterministic project key, or the bound
/// root path itself. Returns `None` (proceed) when the selector is absent
/// or matches.
pub(crate) fn foreign_project_refusal(&self, project: Option<&str>) -> Option<String> {
let selector = project.map(str::trim).filter(|p| !p.is_empty())?;
if self.selector_matches_bound_project(selector) {
return None;
}
let bound_root = self.capture_repo_root();
Some(format!(
"project '{selector}' is not available on this connection: this server is bound \
to the single project '{}'{}. Explicit project routing requires the daemon \
transport with the target project opened via index_folder(path=...).",
self.project_name,
bound_root
.as_deref()
.map(|root| format!(" ({})", root.display()))
.unwrap_or_default()
))
}
/// Feature 012 (Phase 3), Principle VII honesty: a cross-project read targets
/// the daemon-owned working set, which does not exist on the local (`/mcp` HTTP,
/// stdio/embed, or daemon-degraded) execution path. `search_symbols`,
/// `search_text`, and `find_references` gate their no-daemon local path on this
/// guard. Returns the refusal message when the request is GENUINELY
/// cross-project, else `None` (proceed).
///
/// C-stopgap (D16): on the `/mcp` HTTP transport there is no daemon behind the
/// handler (`proxy_tool_call` short-circuits to `None` because `daemon_client`
/// is `None`), so this contains D16's silent-wrong half — `/mcp` LOUDLY refuses
/// cross-project targeting rather than silently serving the single bound index.
/// `tests/serve_http_attach.rs` locks it end-to-end.
///
/// The containment is deliberately NARROW: a selector that RESOLVES TO THE BOUND
/// project (its name, its root's project key, or its root path) is answerable
/// locally, so it PROCEEDS — only foreign, multi-project, or wildcard (`*`)
/// selectors, which need the daemon working set, are refused. This shares
/// `selector_matches_bound_project` with `foreign_project_refusal` so both guards
/// agree on what counts as local; only the refusal MESSAGE differs (this one
/// names the `/mcp` transport for the no-daemon path).
fn local_cross_project_refusal(
&self,
project: Option<&str>,
projects: Option<&[String]>,
) -> Option<String> {
// Gather every non-empty selector from both the singular and plural params.
let mut selectors: Vec<&str> = Vec::new();
if let Some(p) = project.map(str::trim).filter(|p| !p.is_empty()) {
selectors.push(p);
}
if let Some(list) = projects {
selectors.extend(list.iter().map(|p| p.trim()).filter(|p| !p.is_empty()));
}
// No selector at all -> proceed on the normal single-project path.
if selectors.is_empty() {
return None;
}
// A wildcard, or ANY selector that does not resolve to the bound project,
// requires the daemon working set -> refuse honestly. Only when EVERY
// selector resolves to the bound project can we answer locally.
let all_local = selectors
.iter()
.all(|selector| *selector != "*" && self.selector_matches_bound_project(selector));
if all_local {
return None;
}
Some(
"Cross-project queries (project/projects) require the daemon: the \
working set of open projects lives on the daemon transport, not on \
the /mcp HTTP transport, stdio/embed, or while the daemon is \
unreachable. Start the daemon to query across projects."
.to_string(),
)
}
/// Reindex a directory from scratch — replaces the current index, restarts watcher, triggers
/// git temporal analysis. Use when switching projects. Destructive to current index.
#[tool(
description = "Reindex a directory from scratch — replaces the current index, restarts watcher, triggers git temporal analysis. Use when switching projects. Destructive to current index. NOT for re-reading a single changed file (use analyze_file_impact). NOT for reading content from an existing index (use get_file_content).",
annotations(
// Destructive: replaces the active index (discards current contents),
// matching the description. Also idempotent: re-running with the same
// path converges to the same index. Destructive + idempotent are
// independent MCP hints, so both are honestly true here.
read_only_hint = false,
destructive_hint = true,
idempotent_hint = true,
open_world_hint = false
)
)]
pub async fn index_folder(&self, params: Parameters<IndexFolderInput>) -> String {
if let Some(result) = self.proxy_tool_call("index_folder", ¶ms.0).await {
// Immutable home: a daemon `index_folder` (default or `add=true`)
// opens/refreshes the target in the daemon-owned working set and
// NEVER retargets this connection. The bound `repo_root` and any
// local home-fallback state in `self.index` stay exactly as they
// are — unqualified reads remain bound to home.
//
// Task 8: remember the successfully opened sibling root so a
// reconnect can restore the whole working set.
if result.starts_with("Indexed ")
&& let Some(daemon_lock) = self.daemon_client.as_ref()
&& let Ok(root) = std::path::Path::new(¶ms.0.path).canonicalize()
{
daemon_lock.read().await.record_opened_root(root);
}
return result;
}
if self.daemon_client.is_some() {
// Daemon-proxy topology with an unreachable daemon: executing the
// same call locally would destructively replace this connection's
// single in-process index (the home fallback) with the requested
// project. Refuse instead of degrading a non-destructive open into
// a destructive local reset (recovered finding: proxy-failure
// fallback hijacked home).
return format!(
"index_folder refused: the daemon is unreachable, and a local fallback would \
destructively replace this connection's home index with '{}'. Unqualified \
reads continue to serve the local home fallback; restore the daemon \
connection and retry.",
params.0.path
);
}
let input = params.0;
// Feature 012 (Phase 2), Principle VII honesty: additive multi-project
// opens live ONLY in the daemon-owned working set. On stdio/embed (no
// daemon) or when the daemon is unreachable, there is no working set to
// add to — refuse honestly instead of silently falling back to a
// single-project retarget that would discard the active project.
if input.add == Some(true) {
return "index_folder(add:true) requires the daemon: additive \
multi-project opens are only available over the daemon transport, \
not on stdio/embed. Start the daemon (the default desktop topology) \
to open multiple projects in one session."
.to_string();
}
let requested_root = PathBuf::from(&input.path);
let allow_protected_root = input.allow_protected_root == Some(true);
let binding = match crate::discovery::resolve_root_candidate(
&requested_root,
crate::domain::RootCandidateSource::ExplicitIndexFolder,
crate::domain::RootRequestMode::ExplicitIndexFolder {
allow_protected_root,
},
) {
crate::domain::RootResolution::Bound(binding) => binding,
crate::domain::RootResolution::Unbound { reason, .. } => {
let crate::domain::UnboundReason::Refused(reason) = reason else {
return "index_folder refused: no candidate declared".to_string();
};
return match reason {
crate::domain::RootRefusalReason::MissingOrNotDirectory
if !requested_root.exists() =>
{
format!("Path does not exist: {}", input.path)
}
crate::domain::RootRefusalReason::MissingOrNotDirectory => {
format!("Path is not a directory: {}", input.path)
}
crate::domain::RootRefusalReason::CanonicalizationFailed => {
"Cannot resolve path: canonicalization_failed".to_string()
}
_ => format!(
"Refused to index sensitive system path: {}. Use a project directory or retry this exact direct request with allow_protected_root=true.",
reason.code()
),
};
}
};
let explicit_protected = matches!(
binding.access_mode,
crate::domain::SourceAccessMode::ExplicitProtected
);
let state_placement = crate::discovery::resolve_state_placement(&binding);
let root = binding.canonical_root;
// Bounded discovery: a huge NON-sensitive tree (a deep monorepo, a
// generated-file bomb, a user-pointed scratch dir) can no longer OOM or
// panic the reload. `discovery::discover_all_files`/`discover_files`
// enforce a file-count and cumulative-byte ceiling
// (`SYMFORGE_MAX_INDEX_FILES` / `SYMFORGE_MAX_INDEX_BYTES`, generous
// defaults) DURING the walk and return a graceful "tree too large to
// index" error before the in-memory index build commits. The reload
// below propagates that error to the caller instead of crashing.
let reset_requested = index_folder_reset_requested();
let current_root = self.capture_repo_root();
let (idempotency, replay_response) = match input.idempotency_key.as_deref() {
Some(raw_key) => {
let Some(control_state) = self.capture_control_state_dir() else {
return "Idempotency unavailable: durable process control state is unavailable."
.to_string();
};
match crate::idempotency::begin_index_folder_replay(
&control_state,
&root,
raw_key,
reset_requested,
allow_protected_root,
) {
Ok(crate::idempotency::ReplayStart::FirstExecution(active)) => {
(Some(active), None)
}
Ok(crate::idempotency::ReplayStart::Replay(response)) => (None, Some(response)),
Err(error) => return crate::idempotency::format_tool_error(&error),
}
}
None => (None, None),
};
let reset_report = if reset_requested && replay_response.is_none() {
match crate::live_index::persist::reset_snapshot_state(&root, &state_placement) {
Ok(report) => Some(report),
Err(error) => {
let output = format!("Reset failed: {error}");
if let Some(idempotency) = &idempotency {
let _ = idempotency.fail(output.clone());
}
return output;
}
}
} else {
None
};
let index = Arc::clone(&self.index);
let reload_root = root.clone();
let reload_state_placement = state_placement.clone();
match tokio::task::spawn_blocking(move || {
index.reload_for_state_placement(&reload_root, &reload_state_placement)
})
.await
{
Ok(Ok(())) => {
// The replacement generation is now published. Only at this
// commit point may watcher ownership move to the new root; a
// failed build above leaves the previous handle and stop token
// completely untouched.
let previous_watcher = self.watcher_handle.lock().take();
if let Some(previous_watcher) = previous_watcher {
previous_watcher.stop_token.store(true, Ordering::Release);
let mut previous_task = previous_watcher.task;
if tokio::time::timeout(Duration::from_secs(2), &mut previous_task)
.await
.is_err()
{
tracing::warn!(
"watcher: previous watcher did not stop during successful index handoff"
);
previous_task.abort();
}
}
if reset_report.is_some() {
self.index.mark_index_folder_reset();
}
let published = self.index.published_state();
let file_count = published.file_count;
let symbol_count = published.symbol_count;
let gitignore_hygiene = crate::gitignore_hygiene::reconcile_project_gitignore(
&root,
if explicit_protected {
crate::gitignore_hygiene::GitignoreHygieneAuthority::ExplicitProtected
} else {
crate::gitignore_hygiene::GitignoreHygieneAuthority::ExplicitNormalBinding
},
);
// Root actually changed → session accounting recorded under the
// previous root (context_inventory) would double-count; start
// fresh. A same-root reindex keeps accounting intact.
if current_root.as_deref() != Some(root.as_path()) {
self.session_context.reset();
}
self.set_bound_project_state(Some(root.clone()), Some(state_placement.clone()));
// Restart the file watcher at the new root so freshness continues.
let watcher_handle = crate::watcher::restart_watcher(
root.clone(),
Arc::clone(&self.index),
Arc::clone(&self.watcher_info),
None,
);
self.watcher_handle.lock().replace(watcher_handle);
tracing::info!(root = %root.display(), "file watcher restarted after index_folder");
// Refresh git temporal data for the new root.
let expected_gen = self.index.current_project_generation();
crate::live_index::git_temporal::spawn_git_temporal_computation(
Arc::clone(&self.index),
root.clone(),
expected_gen,
);
if let Some(response) = replay_response {
self.session_context.record_summary_output(
"index_folder",
(response.len() / 4).min(u32::MAX as usize) as u32,
);
return response;
}
let mut output = format!("Indexed {} files, {} symbols.", file_count, symbol_count);
output.push('\n');
output.push_str(&gitignore_hygiene.receipt());
// Warn-only: indexing a subfolder of a git repo binds paths to
// that subfolder, not the repo root. Narrow-scope indexing is
// supported, so we do NOT auto-retarget — just surface the
// namespace shift so repo-root-relative path expectations are
// not silently violated.
if let Some(git_root) = crate::discovery::git_root_above(&root)
&& git_root != root
{
output.push_str(&format!(
"\nNote: indexed a subfolder of a git repo — paths will be relative to {}, not the git root {}. Index the git root for repo-root-relative paths.",
root.display(),
git_root.display()
));
}
if let Some(reset_report) = reset_report {
output.push_str(&format!(
"\nReset: scope={} | removed={} | missing={}",
crate::live_index::persist::SNAPSHOT_RESET_SCOPE_LABEL,
reset_report.removed_count(),
reset_report.missing_count()
));
let runtime_status = self.runtime_status_for(
&published,
self.local_runtime_mode(),
None,
None,
Some(root.clone()),
);
output.push('\n');
output.push_str(&format::format_runtime_status(&runtime_status));
}
if let Some(idempotency) = &idempotency
&& let Err(error) = idempotency.complete(output.clone())
{
output.push_str(&format!(
"\nIdempotency warning: failed to store replay result: {error}"
));
}
self.session_context.record_summary_output(
"index_folder",
(output.len() / 4).min(u32::MAX as usize) as u32,
);
output
}
Ok(Err(e)) => {
if let Some(response) = replay_response {
return crate::idempotency::format_live_postcondition_unavailable(
&response, &e,
);
}
let output = format!("Index failed: {e}");
if let Some(idempotency) = &idempotency {
let _ = idempotency.fail(output.clone());
}
output
}
Err(join_err) => {
if let Some(response) = replay_response {
return crate::idempotency::format_live_postcondition_unavailable(
&response, &join_err,
);
}
let output = format!("Index failed: reload task panicked: {join_err}");
if let Some(idempotency) = &idempotency {
let _ = idempotency.fail(output.clone());
}
output
}
}
}
/// List changed files: uncommitted=true for working tree, git_ref for ref comparison, since for
/// timestamp filter. Use to see what files changed.
/// Set code_only=true to exclude non-source files (docs, configs, lock files).
/// Set include_symbol_diff=true to also get a symbol-level diff in the same response (git modes only).
#[tool(
description = "List changed files: uncommitted=true for working tree, git_ref for ref comparison, since for timestamp filter. Filter with path_prefix and/or language. Set code_only=true to exclude non-source files (docs, configs, lock files). Set include_symbol_diff=true to also include a symbol-level diff in the same response (git_ref and uncommitted modes only), saving a round-trip vs calling diff_symbols separately. NOT for symbol-level change detail alone (use diff_symbols). NOT for finding files by name or content (use search_files or search_text).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn what_changed(&self, params: Parameters<WhatChangedInput>) -> String {
if let Some(result) = self.proxy_tool_call("what_changed", ¶ms.0).await {
return result;
}
if let Some(refusal) = self.foreign_project_refusal(params.0.project.as_deref()) {
return refusal;
}
if params.0.estimate == Some(true) {
let with_diff = params.0.include_symbol_diff.unwrap_or(false);
let est = if with_diff { 500 } else { 200 };
return format!(
"Estimate for what_changed: ~{} tokens (include_symbol_diff={})",
est, with_diff
);
}
let effective_repo_root = self.effective_repo_root_for_git_tools();
let requested_git_mode = params.0.uncommitted.unwrap_or(false)
|| params
.0
.git_ref
.as_deref()
.map(str::trim)
.is_some_and(|git_ref| !git_ref.is_empty());
if params.0.since.is_none() && !requested_git_mode && effective_repo_root.is_none() {
// Surface-aware recovery (TR-02 / FR-012): `index_folder` is gated on
// the compact surface, so name only callable recovery there. `since=`
// is always valid and is offered on every surface.
let attach = match crate::protocol::surface_probe::connection_surface_or_env() {
crate::protocol::surface_probe::SurfaceProfile::Compact => {
"set SYMFORGE_WORKSPACE_ROOT (or run `symforge init`) and reconnect"
}
crate::protocol::surface_probe::SurfaceProfile::Full
| crate::protocol::surface_probe::SurfaceProfile::Meta => {
"call index_folder(path=...)"
}
};
return format!("No repo root attached; {attach} or pass since=...");
}
let mode = match determine_what_changed_mode(¶ms.0, effective_repo_root.is_some()) {
Ok(mode) => mode,
Err(message) => return message,
};
match &mode {
WhatChangedMode::Timestamp(since_ts) => {
let view = {
let guard = self.index.read();
loading_guard!(guard);
guard.capture_what_changed_timestamp_view()
};
if *since_ts < view.loaded_secs {
match filter_paths_by_prefix_and_language(
view.paths.clone(),
params.0.path_prefix.as_deref(),
params.0.language.as_deref(),
params.0.code_only.unwrap_or(false),
) {
Ok(filtered) => {
if filtered.is_empty() {
return if view.paths.is_empty() {
"Index is empty — no files tracked.".to_string()
} else {
"No indexed files matched the requested filters since the last index load.".to_string()
};
}
let envelope = {
let guard = self.index.read();
search_format::format_search_envelope(
"exact (timestamp compare)",
what_changed_source_authority_label(&mode),
search_parse_state_for_paths(
&guard,
filtered.iter().map(|path| path.as_str()),
),
&changed_paths_completeness_label(
view.paths.len(),
filtered.len(),
),
&what_changed_scope_summary(¶ms.0, &mode),
&search_paths_evidence(
filtered.iter().map(|path| path.as_str()),
),
)
};
let output = format::what_changed_paths_result(
&filtered,
"No indexed files matched the requested filters since the last index load.",
);
let result = format!("{envelope}\n\n{output}");
self.session_context.record_summary_output(
"what_changed",
(result.len() / 4).min(u32::MAX as usize) as u32,
);
result
}
Err(error) => {
self.session_context.record_summary_output(
"what_changed",
(error.len() / 4).min(u32::MAX as usize) as u32,
);
error
}
}
} else {
let result = format::what_changed_timestamp_view(&view, *since_ts);
self.session_context.record_summary_output(
"what_changed",
(result.len() / 4).min(u32::MAX as usize) as u32,
);
result
}
}
WhatChangedMode::Uncommitted => {
let guard = self.index.read();
loading_guard!(guard);
drop(guard);
let Some(repo_root) = effective_repo_root.as_deref() else {
return "Git change detection unavailable; pass `since` for timestamp mode."
.to_string();
};
let repo = match crate::git::GitRepo::open(repo_root) {
Ok(r) => r,
Err(e) => return format!("Git change detection failed: {e}"),
};
match repo.uncommitted_paths() {
Ok(paths) => {
let total_paths = paths.len();
match filter_paths_by_prefix_and_language(
paths,
params.0.path_prefix.as_deref(),
params.0.language.as_deref(),
// US1 (018) FR-001/SC-001: uncommitted mode defaults
// to source-focused so untracked data files (e.g.
// *.json) don't dominate. Timestamp/git_ref sites
// keep `false`. Explicit `code_only` still honored.
params.0.code_only.unwrap_or(true),
) {
Ok(filtered) => {
if filtered.is_empty() {
return if total_paths == 0 {
"No uncommitted changes detected.".to_string()
} else {
// Recovered finding #2: an empty filtered
// result must disclose the (default)
// source-focus filter and its recovery
// lever, not read as "nothing changed".
let default_note = if params.0.code_only.is_none() {
" Uncommitted mode is source-focused by default (code_only=true);"
} else {
""
};
format!(
"No uncommitted changes matched the requested filters.{default_note} \
{total_paths} changed path(s) were filtered out — pass \
code_only=false (or widen path_prefix/language) to see them."
)
};
}
let include_symbol_diff =
params.0.include_symbol_diff.unwrap_or(false);
let envelope = search_format::format_search_envelope(
"exact (uncommitted working tree)",
what_changed_source_authority_label(&mode),
what_changed_parse_state_label(&mode, include_symbol_diff),
&changed_paths_completeness_label(total_paths, filtered.len()),
&what_changed_scope_summary(¶ms.0, &mode),
&search_paths_evidence(
filtered.iter().map(|path| path.as_str()),
),
);
let mut output = format::what_changed_paths_result(
&filtered,
"No uncommitted changes detected.",
);
if include_symbol_diff {
let changed_refs: Vec<&str> =
filtered.iter().map(|s| s.as_str()).collect();
let sym_diff = format::diff_symbols_result_view(
"HEAD",
"",
&changed_refs,
&repo,
&self.index.read(),
true,
false,
);
output.push_str("\n\n");
output.push_str(&sym_diff);
}
let result = format!("{envelope}\n\n{output}");
self.session_context.record_summary_output(
"what_changed",
(result.len() / 4).min(u32::MAX as usize) as u32,
);
format::enforce_token_budget(result, params.0.max_tokens)
}
Err(e) => e,
}
}
Err(e) => format!("Git change detection failed: {e}"),
}
}
WhatChangedMode::GitRef(git_ref) => {
let guard = self.index.read();
loading_guard!(guard);
drop(guard);
let Some(repo_root) = effective_repo_root.as_deref() else {
return "Git change detection unavailable; pass `since` for timestamp mode."
.to_string();
};
let repo = match crate::git::GitRepo::open(repo_root) {
Ok(r) => r,
Err(e) => return format!("Git change detection failed: {e}"),
};
match repo.changed_paths_from_ref(git_ref) {
Ok(paths) => {
let total_paths = paths.len();
match filter_paths_by_prefix_and_language(
paths,
params.0.path_prefix.as_deref(),
params.0.language.as_deref(),
params.0.code_only.unwrap_or(false),
) {
Ok(filtered) => {
if filtered.is_empty() {
return if total_paths == 0 {
format!(
"No changes detected relative to git ref '{git_ref}'."
)
} else {
format!(
"No changes relative to git ref '{git_ref}' matched the requested filters."
)
};
}
let include_symbol_diff =
params.0.include_symbol_diff.unwrap_or(false);
let envelope = search_format::format_search_envelope(
"exact (git ref diff)",
what_changed_source_authority_label(&mode),
what_changed_parse_state_label(&mode, include_symbol_diff),
&changed_paths_completeness_label(total_paths, filtered.len()),
&what_changed_scope_summary(¶ms.0, &mode),
&search_paths_evidence(
filtered.iter().map(|path| path.as_str()),
),
);
let mut output = format::what_changed_paths_result(
&filtered,
&format!(
"No changes detected relative to git ref '{git_ref}'."
),
);
if include_symbol_diff {
let base =
git_ref.strip_prefix("branch:").unwrap_or(git_ref.as_str());
let changed_refs: Vec<&str> =
filtered.iter().map(|s| s.as_str()).collect();
let sym_diff = format::diff_symbols_result_view(
base,
"HEAD",
&changed_refs,
&repo,
&self.index.read(),
true,
false,
);
output.push_str("\n\n");
output.push_str(&sym_diff);
}
let result = format!("{envelope}\n\n{output}");
self.session_context.record_summary_output(
"what_changed",
(result.len() / 4).min(u32::MAX as usize) as u32,
);
result
}
Err(e) => e,
}
}
Err(e) => format!("Git change detection failed: {e}"),
}
}
}
}
/// Git-aware change impact: merge `base_branch`/`since` ref diffs with
/// uncommitted working-tree changes into a changed-file set, then walk the
/// call graph up to `depth` hops to compute a blast radius with per-node
/// risk tiers. See contracts/detect-impact.md (frozen 2026-06-30).
#[tool(
description = "Git-aware change impact analysis. Merges base_branch/since ref diffs with uncommitted working-tree changes (include_untracked, default true) into a changed-file set, then walks the call graph up to depth hops (default 2, max 5 — clamped with a warning above) to compute a blast radius: symbols that transitively call what changed, tiered by hop distance (1=high, 2=medium, 3+=low; an entry point like fn main at hop 1 is critical). scope=symbols (default) returns per-symbol blast entries; scope=files aggregates to file granularity. Response embeds a JSON payload (changed_files, changed_symbols, blast_radius, risk_summary, pagination) after a `--- impact payload ---` marker. Requires a git repository. Does NOT re-index files or bump frecency (use analyze_file_impact for that).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn detect_impact(&self, params: Parameters<DetectImpactInput>) -> String {
if let Some(result) = self.proxy_tool_call("detect_impact", ¶ms.0).await {
return result;
}
{
let guard = self.index.read();
loading_guard!(guard);
}
let Some(repo_root) = self.effective_repo_root_for_git_tools() else {
return "Error: Git unavailable: not inside a git repository. detect_impact requires \
git for change detection; use find_dependents or what_changed(since=...) for \
non-git impact/change queries."
.to_string();
};
let repo = match crate::git::GitRepo::open(&repo_root) {
Ok(r) => r,
Err(e) => return format!("Error: Git unavailable: {e}"),
};
let requested_depth = params.0.depth;
let effective_depth = requested_depth.min(DETECT_IMPACT_MAX_DEPTH);
// contracts/detect-impact.md § Input: `base_branch` defaults to `main`
// when the caller supplies neither `base_branch` nor `since`. Without
// this, the STEL-upgraded path (`route_impact` plans only
// `{"scope":"files"}`) would silently fall through to uncommitted-only
// and return an empty blast radius on a clean tree with committed-but-
// unmerged work — the silent no-op the depth-default already guards
// against. A repo with no `main` branch degrades to the "Invalid git
// ref" error below (git2 ref resolution fails), never a panic; pass an
// explicit `base_branch`/`since` for non-`main` default branches.
//
// Wave-1 defect fix (2026-07-02, contracts/detect-impact.md § 2026-07-02
// addendum): the DEFAULT substitution now prefers `origin/main` over
// local `main`. A local `main` that lags the remote (e.g. 83 commits
// behind) produces a confidently-wrong blast radius against a stale base;
// the shared remote ref is the intended comparison. An EXPLICIT
// caller-passed `base_branch:"main"` still means local `main` (unchanged).
// The resolved ref (and any staleness) is disclosed in the response
// header so the output is self-describing.
let mut staleness_note: Option<String> = None;
let base_branch: Option<String> =
if params.0.base_branch.is_none() && params.0.since.is_none() {
let origin = repo.resolve_ref_commit("origin/main");
let local = repo.resolve_ref_commit("main");
let resolved = match (origin, local) {
(Some(origin_oid), Some(local_oid)) => {
if origin_oid != local_oid {
// Direction-aware disclosure (Wave 1 Fix 3): behind is the
// motivating stale-local case; ahead means unpushed local
// work landed in the base; both means diverged. `ahead` =
// commits in local not in origin; `behind` = the reverse.
staleness_note = Some(match repo.ahead_behind(local_oid, origin_oid) {
Some((ahead, behind)) if behind > 0 && ahead == 0 => {
"local main is behind origin/main; using origin/main"
.to_string()
}
Some((ahead, behind)) if ahead > 0 && behind == 0 => {
"local main is ahead of origin/main (unpushed commits); using \
origin/main — the blast radius includes your unpushed work \
relative to the shared base"
.to_string()
}
Some((ahead, behind)) if ahead > 0 && behind > 0 => {
"local main and origin/main have diverged; using origin/main"
.to_string()
}
// No common ancestor (or the unreachable both-zero given
// origin != local): fall back to the direction-neutral note.
_ => "local main differs from origin/main; using origin/main"
.to_string(),
});
}
"origin/main"
}
(Some(_), None) => "origin/main",
// No origin/main (or neither ref exists): fall back to local
// `main`. When neither exists, merge_git_changed_paths surfaces
// the existing "Invalid git ref" error below, unchanged.
(None, _) => "main",
};
Some(resolved.to_string())
} else {
params.0.base_branch.clone()
};
// The base ref disclosed in the response header: the resolved default or
// the explicit caller value; `None` when only `since` was supplied.
let base_disclosure: Option<String> = base_branch.clone();
let changed_files = match repo.merge_git_changed_paths(
base_branch.as_deref(),
params.0.since.as_deref(),
params.0.include_untracked,
) {
Ok(paths) => paths,
Err(e) => return format!("Error: Invalid git ref: {e}"),
};
// US1 (018) FR-001/FR-002: source-focus the impact seed by default so
// non-source data files (e.g. untracked JSON) and their key-symbols
// don't drive the blast radius. `include_data=true` restores the prior
// inclusive changed-set. language=None never errors, so keep the seed
// on the impossible Err rather than silently emptying the blast radius.
let include_data = params.0.include_data.unwrap_or(false);
let unfiltered_changed_total = changed_files.len();
let changed_files = if include_data {
changed_files
} else {
filter_paths_by_prefix_and_language(changed_files.clone(), None, None, true)
.unwrap_or(changed_files)
};
// Recovered finding #1: disclose how many changed paths the source-focus
// default removed, so an empty/shrunken blast radius is self-describing.
let source_filtered_out = unfiltered_changed_total.saturating_sub(changed_files.len());
// PART A (019): the seed is a BODY delta, not every symbol of a changed
// file. Reparse each changed file's BASE blob and its CURRENT working
// tree with the same extractor `diff_symbols` uses
// (`extract_symbols_for_diff` -> name+body-hash pairs), then seed only
// the symbols whose body was added, modified, or removed. A 1-line edit
// in a 20-symbol file now seeds 1 symbol, not 20; a comment/whitespace
// shift that leaves every body byte-identical seeds 0.
//
// Base ref: mirror `merge_git_changed_paths`'s OWN base selection so the
// body-delta compares against the same base the changed-file set came
// from. `since=<ref>` diffs `<ref>...HEAD`; the `WORKTREE` sentinel and
// `base_branch` both diff against the committed tip / branch, with the
// working tree as the current side. A mismatched base (e.g. always HEAD)
// would find zero deltas for a committed `since` range on a clean tree.
let since_trimmed = params
.0
.since
.as_deref()
.map(str::trim)
.filter(|s| !s.is_empty());
let seed_base_ref = match since_trimmed {
Some("WORKTREE") => "HEAD",
Some(since_ref) => since_ref,
None => base_branch.as_deref().unwrap_or("HEAD"),
};
let (changed_symbols, blast_radius) = {
let guard = self.index.read();
let mut changed_symbols: Vec<crate::live_index::graph::SymbolId> = Vec::new();
for path in &changed_files {
// Kind lookup for the CURRENT symbols comes from the live index;
// removed symbols (absent from current) default to Function to
// match the graph's own entry-point default.
let kind_by_name: HashMap<&str, crate::domain::SymbolKind> = guard
.files
.get(path)
.map(|f| {
f.symbols
.iter()
.map(|s| (s.name.as_str(), s.kind))
.collect()
})
.unwrap_or_default();
let base_content = repo
.file_at_ref(seed_base_ref, path)
.unwrap_or_default()
.unwrap_or_default();
// Gated: a refusal collapses to "no current content", which
// seeds conservatively from the index rather than disclosing
// the demoted file's current symbol names or signatures.
let current_content =
crate::protocol::read_gate::admit_worktree_text(&guard, &repo, path)
.unwrap_or_default()
.unwrap_or_default();
// Unsupported/config languages return None from the extractor;
// we cannot body-diff them, so fall back to seeding every
// indexed symbol of the file (the old conservative behavior)
// rather than silently seeding nothing.
let base_syms = crate::parsing::extract_symbols_for_diff(&base_content, path);
let current_syms = crate::parsing::extract_symbols_for_diff(¤t_content, path);
let (Some(base_syms), Some(current_syms)) = (base_syms, current_syms) else {
if let Some(file) = guard.files.get(path) {
for sym in &file.symbols {
changed_symbols.push(crate::live_index::graph::SymbolId {
path: path.clone(),
name: sym.name.clone(),
kind: sym.kind,
});
}
}
continue;
};
// ponytail: name-keyed body-hash maps, matching `diff_symbols`'
// own name-keyed comparison. Same-name overloads in one file
// collapse to their last body hash; a resolver-aware seed
// (C-S2-001) would key on a stable symbol id instead.
let base_by_name: HashMap<&str, &str> = base_syms
.iter()
.map(|(n, h)| (n.as_str(), h.as_str()))
.collect();
let current_by_name: HashMap<&str, &str> = current_syms
.iter()
.map(|(n, h)| (n.as_str(), h.as_str()))
.collect();
let mut seed = |name: &str| {
changed_symbols.push(crate::live_index::graph::SymbolId {
path: path.clone(),
name: name.to_string(),
kind: kind_by_name
.get(name)
.copied()
.unwrap_or(crate::domain::SymbolKind::Function),
});
};
// Added (in current, not base) or modified (body hash differs).
for (name, cur_hash) in ¤t_by_name {
match base_by_name.get(name) {
None => seed(name),
Some(base_hash) if base_hash != cur_hash => seed(name),
_ => {}
}
}
// Removed (in base, not current) — seeded so downstream callers
// of a deleted symbol still appear in the blast radius.
for name in base_by_name.keys() {
if !current_by_name.contains_key(name) {
seed(name);
}
}
}
let graph = crate::live_index::graph::GraphProjection::from_index(&guard);
let blast_radius = crate::live_index::graph::compute_impact(
&graph,
&changed_symbols,
effective_depth as u32,
);
(changed_symbols, blast_radius)
};
// scope=files aggregates per-symbol blast nodes to file granularity
// (nearest hop / matching risk wins per file); scope=symbols (default)
// keeps one entry per symbol.
let mut blast_entries: Vec<(String, u32, crate::live_index::graph::RiskTier)> =
match params.0.scope {
ImpactScope::Symbols => blast_radius
.iter()
// PART C (019): carry disambiguating identity. Two blast
// nodes that share a bare name (e.g. `main` in different
// files, or two `run`s the graph kept distinct) must render
// as distinct `path::name` entries, not collapse into one
// indistinguishable `"main"`. The path already disambiguates
// same-name defs across files; kind is folded into the node
// identity by the graph, so `path::name` is sufficient here.
.map(|node| {
(
format!("{}::{}", node.symbol.path, node.symbol.name),
node.hop,
node.risk,
)
})
.collect(),
ImpactScope::Files => {
let mut by_file: HashMap<String, (u32, crate::live_index::graph::RiskTier)> =
HashMap::new();
for node in &blast_radius {
by_file
.entry(node.symbol.path.clone())
.and_modify(|(hop, risk)| {
if node.hop < *hop {
*hop = node.hop;
*risk = node.risk;
}
})
.or_insert((node.hop, node.risk));
}
by_file
.into_iter()
.map(|(path, (hop, risk))| (path, hop, risk))
.collect()
}
};
// Fix 1 (Wave 1, 2026-07-02): keep the most severe blast nodes when the
// list is capped — sort by risk severity desc, then hop asc, then name.
blast_entries.sort_by(|a, b| {
b.2.severity_rank()
.cmp(&a.2.severity_rank())
.then(a.1.cmp(&b.1))
.then_with(|| a.0.cmp(&b.0))
});
// risk_summary counts the FULL blast set (it is counts, not entries), so
// it stays complete even though the returned entries are capped.
let mut risk_counts: HashMap<&'static str, u32> = HashMap::new();
for (_, _, risk) in &blast_entries {
*risk_counts.entry(risk.as_str()).or_insert(0) += 1;
}
// Fix 1: bound the JSON PAYLOAD — cap each list at DETECT_IMPACT_MAX_RETURNED
// and disclose the full totals + truncation in `pagination`. This bounds the
// serialized/emitted entries at 200/list; it does NOT make the tool
// sub-linear. The changed_symbols collection above, the BFS in
// compute_impact, the blast clone+sort, and the risk counting all remain
// O(full set) by necessity: risk_summary and the pagination totals must
// reflect the COMPLETE set, so everything is still counted. A large explicit
// diff still costs linear time; what the cap removes is the multi-MB payload
// (the 54 MB / 291K-entry dump).
let cap = DETECT_IMPACT_MAX_RETURNED;
let changed_files_total = changed_files.len();
let changed_files_json: Vec<&String> = changed_files.iter().take(cap).collect();
let changed_symbols_total = changed_symbols.len();
let changed_symbols_json: Vec<serde_json::Value> = changed_symbols
.iter()
.take(cap)
.map(
|s| serde_json::json!({"name": s.name, "path": s.path, "kind": s.kind.to_string()}),
)
.collect();
let blast_total = blast_entries.len();
let blast_radius_json: Vec<serde_json::Value> = blast_entries
.iter()
.take(cap)
.map(|(symbol, hop, risk)| serde_json::json!({"symbol": symbol, "hop": hop, "risk": risk.as_str()}))
.collect();
let changed_files_returned = changed_files_json.len();
let changed_symbols_returned = changed_symbols_json.len();
let blast_returned = blast_radius_json.len();
let list_page = |total: usize, returned: usize| {
serde_json::json!({
"total": total,
"returned": returned,
"truncated": total > returned,
})
};
let payload = serde_json::json!({
"changed_files": changed_files_json,
"changed_symbols": changed_symbols_json,
"blast_radius": blast_radius_json,
"risk_summary": {
"critical": risk_counts.get("critical").copied().unwrap_or(0),
"high": risk_counts.get("high").copied().unwrap_or(0),
"medium": risk_counts.get("medium").copied().unwrap_or(0),
"low": risk_counts.get("low").copied().unwrap_or(0),
},
// Per-list pagination (total / returned / truncated). The frozen
// contract's flat single-list `pagination` shape did not anticipate
// the changed_files/changed_symbols explosion; this per-list shape is
// the honest disclosure (contracts/detect-impact.md § 2026-07-02).
"pagination": {
"changed_files": list_page(changed_files_total, changed_files_returned),
"changed_symbols": list_page(changed_symbols_total, changed_symbols_returned),
"blast_radius": list_page(blast_total, blast_returned),
},
// Recovered finding #1: the source-focus default silently narrowed
// the changed-set seed; disclose the exclusion and the recovery
// lever so the caller can tell "no impact" from "filtered away".
"source_filter": {
"applied": !include_data,
"excluded_paths": source_filtered_out,
"hint": "non-source changed paths are excluded by default; pass include_data=true to include them",
},
});
let result = format::detect_impact_result(
&payload,
requested_depth,
effective_depth,
base_disclosure.as_deref(),
staleness_note.as_deref(),
);
self.session_context.record_summary_output(
"detect_impact",
(result.len() / 4).min(u32::MAX as usize) as u32,
);
result
}
/// Read raw file content. Modes: full file, line range, around_line/around_match/around_symbol,
/// or chunked paging. Use this for exact docs/config reads, whitespace-sensitive inspection,
/// or when you need actual source text that other tools don't provide.
/// For structured understanding use get_file_context. For a single function
/// body use get_symbol.
#[tool(
name = "get_file_content",
description = "Read exact raw file content. Modes: full file, line range, around_line/around_match/around_symbol, or chunked paging. Use this for exact docs/config reads, whitespace-sensitive inspection, or exact source excerpts after narrowing with get_file_context, search_text, or get_symbol. For structured code understanding use get_file_context first. For a single function body use get_symbol. Accepts offset/limit (Read-tool idiom) as aliases for start_line/end_line. Use max_tokens to request a smaller response budget. Unknown fields are rejected with an error naming the invalid param. Responses are capped at ~60 KB; if truncated, a footer suggests chunk_index+max_lines, around_line, or around_symbol.",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn get_file_content_tool(
&self,
params: Parameters<GetFileContentInput>,
) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
let started = Instant::now();
let output = self.get_file_content(params).await;
let outcome_class = classify_get_file_content_output(&output);
self.record_tool_completion(
"get_file_content",
&output,
started.elapsed(),
outcome_class,
);
statused_tool_result(output, outcome_class)
}
pub(crate) async fn get_file_content(&self, params: Parameters<GetFileContentInput>) -> String {
let mut input = params.0;
input.path = normalize_exact_path(&input.path);
let explicit_max_tokens = input.max_tokens;
if let Err(e) = normalize_file_content_aliases(&mut input) {
return e;
}
if let Some(result) = self.proxy_tool_call("get_file_content", &input).await {
return format::enforce_token_budget(
format::cap_file_content_output(result),
explicit_max_tokens,
);
}
if let Some(refusal) = self.foreign_project_refusal(input.project.as_deref()) {
return refusal;
}
// Estimate mode: return token cost without reading content
if input.estimate == Some(true) {
let indexed = {
let guard = self.index.read();
loading_guard!(guard);
guard.capture_shared_file(&input.path)
};
if let Some(file) = indexed {
let file_tokens = file.content.len() / 4;
let line_count = file.content.iter().filter(|&&b| b == b'\n').count();
return format!(
"Estimate for get_file_content(path=\"{}\"):\n ~{} tokens (~{} lines)",
input.path, file_tokens, line_count
);
}
// Not indexed: get_file_content still serves Tier-2 (and other
// non-source) files via a raw disk read, so the estimate should
// reflect the disk file rather than reporting "File not found".
// Reuse the same repo-root containment guard as the main read path.
if let Some(root) = self.capture_repo_root() {
match edit::safe_repo_path(&root, &input.path) {
Ok(canon_path) if canon_path.is_file() => {
if let Ok(metadata) = std::fs::metadata(&canon_path) {
let file_tokens = metadata.len() as usize / 4;
return format!(
"Estimate for get_file_content(path=\"{}\"):\n ~{} tokens (raw disk read; not indexed)",
input.path, file_tokens
);
}
}
Err(message) if message.contains("outside the repository") => {
return format::path_outside_repo(&input.path);
}
_ => {}
}
}
return format::not_found_file(&input.path);
}
let options = match file_content_options_from_input(&input) {
Ok(options) => options,
Err(message) => return message,
};
freshen_exact_path_for_targeted_retrieval(self, &options.path_scope);
// Capture freshness and the immutable publication before consulting the
// repeat-read cache. The same request against a later watcher publication
// must be a cache miss, and the bytes below must come from this exact
// captured generation rather than a second live-index read.
let generation = self.index.published_source_set().current_generation();
if let Some(message) = loading_guard_message_from_published(&generation.health) {
return message;
}
let force_refresh = input.force_refresh == Some(true);
let source_id = generation
.source
.as_ref()
.map(|source| source.source_id.as_str())
.unwrap_or("unavailable");
let params_hash = crate::protocol::session::hash_value(&serde_json::json!({
"input": &input,
"project_generation": generation.project_generation,
"source_id": source_id,
"publication_generation": generation.publication_generation,
"content_generation": generation.content_generation,
}));
if let Some(meta) =
self.session_context
.try_file_content_cache_hit(&input.path, params_hash, force_refresh)
{
return self.format_read_cache_hit(&meta, "session_repeat_read");
}
let mode_annotation = match (
&options.content_context.mode_name,
options.content_context.mode_explicit,
) {
(Some(mode), true) => format!("── mode: {} (explicit) ──\n", mode),
_ => String::new(),
};
let file = generation
.live
.capture_shared_file_for_scope(&options.path_scope);
match file {
Some(file) => {
let raw_chars = file.as_ref().content.len();
let max_tokens = Some(format::resolve_read_max_tokens(
explicit_max_tokens,
raw_chars,
));
let output = format::file_content_from_indexed_file_with_context(
file.as_ref(),
options.content_context,
);
self.record_tool_savings_named(
"get_file_content",
format::estimate_tokens_from_chars(format::competent_manual_baseline_chars(
raw_chars,
)),
(output.len() / 4) as u64,
);
let capped =
format::cap_file_content_output(format!("{}{}", mode_annotation, output));
let with_warning = format::append_nul_byte_warning(capped, &file.as_ref().content);
let mut final_output = format::enforce_token_budget(with_warning, max_tokens);
let tokens = (final_output.len() / 4) as u32;
let prior_dedup = if force_refresh {
self.session_context.prior_fetch_for_dedup(
crate::protocol::session::FetchKind::FileContent,
&input.path,
"",
params_hash,
)
} else {
None
};
self.session_context
.record_file_content_fetch(&input.path, params_hash, tokens);
self.bump_frecency(&[PathBuf::from(&input.path)]);
if let Some(prior) = prior_dedup {
final_output = format::append_dedup_hint_footer(
final_output,
"file",
prior.fetched_at.elapsed().as_secs(),
prior.approx_tokens,
);
}
final_output
}
None => {
// Not in index — try raw disk read for non-source files
// (Cargo.toml, package.json, workflow YAMLs, etc.)
if let Some(root) = self.capture_repo_root() {
let canon_path = match edit::safe_repo_path(&root, &input.path) {
Ok(p) => p,
// Distinguish a containment violation (path escapes the
// repo root, e.g. `../../../etc/passwd`) from a genuine
// in-repo miss. `safe_repo_path` reports the former with
// an "outside the repository" message; surface that
// explicitly instead of a misleading "File not found".
Err(message) if message.contains("outside the repository") => {
return format::path_outside_repo(&input.path);
}
Err(_) => return format::not_found_file(&input.path),
};
if canon_path.is_file() {
// The gate owns this read: it classifies the exact buffer
// it returns, so nothing below reopens the path.
// `generation.live` is the same publication that produced
// the index miss above — a fresh `self.index.read()` would
// be a different snapshot.
let content = match read_gate::admit_disk_read(
generation.live.as_ref(),
&input.path,
&canon_path,
) {
Ok(content) => content,
Err(refusal) => return refusal,
};
let body = format::render_file_content_bytes(
&input.path,
&content,
options.content_context,
);
// Frecency bump — commitment tool. Raw-disk
// fallback branch (non-indexed source files);
// collection policy is resolved inside bump_frecency.
self.bump_frecency(&[PathBuf::from(&input.path)]);
// NUL-byte guard (raw-disk fallback branch):
// mirror the indexed branch — warn after the cap.
let capped =
format::cap_file_content_output(format!("{}{}", mode_annotation, body));
let with_warning = format::append_nul_byte_warning(capped, &content);
let max_tokens = Some(format::resolve_read_max_tokens(
explicit_max_tokens,
content.len(),
));
return format::enforce_token_budget(with_warning, max_tokens);
}
}
// Suggest similar files from the index
let suggestions = {
let guard = self.index.read();
suggest_similar_files(&guard, &input.path)
};
format::not_found_file_with_suggestions(&input.path, &suggestions)
}
}
}
/// Find all references or implementations for a symbol. Modes: (1) default/references: call sites,
/// Validate a file's syntax and surface parser diagnostics with exact locations when available.
/// Best for malformed TOML/JSON/YAML and other config files where you need authoritative parse errors.
#[tool(
description = "Validate a file's syntax and surface parser diagnostics with exact locations when available. Best for malformed TOML/JSON/YAML and other config files where you need authoritative parse errors. Uses the indexed file when available and falls back to direct parsing from disk when needed. NOT for understanding file structure (use get_file_context). NOT for searching file content (use search_text).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn validate_file_syntax(
&self,
params: Parameters<ValidateFileSyntaxInput>,
) -> String {
let mut input = params.0;
input.path = normalize_exact_path(&input.path);
if let Some(result) = self.proxy_tool_call("validate_file_syntax", &input).await {
return result;
}
if let Some(refusal) = self.foreign_project_refusal(input.project.as_deref()) {
return refusal;
}
let path_scope = search::PathScope::exact(&input.path);
freshen_exact_path_for_targeted_retrieval(self, &path_scope);
// One publication for the whole handler: the gate below reads the recorded
// disposition off the SAME publication that produced the index miss, and
// the trust decision here is taken on that same publication rather than a
// second, possibly newer, read.
let published = self.index.published_generation();
// No blanket loading_guard: the disk-read fallback below parses from disk
// and does not need the index, so a not-Ready index must not block this
// tool outright. But the indexed hit must not be TRUSTED either — the
// freshen above admits the requested file into a cold-start bootstrap
// placeholder with no bound root, so a "hit" here can be an entry this
// very call just created inside an index that is not yet a view of the
// repository. While not Ready, ignore the indexed entry and answer from
// the authoritative disk parse below.
let not_ready = loading_guard_message_from_published(&published.health);
let indexed_file = if not_ready.is_some() {
None
} else {
published.live.capture_shared_file(&input.path)
};
if let Some(file) = indexed_file {
let output = format::validate_file_syntax_result(&input.path, file.as_ref());
self.session_context.record_summary_output(
"validate_file_syntax",
(output.len() / 4).min(u32::MAX as usize) as u32,
);
return output;
}
let extension = std::path::Path::new(&input.path)
.extension()
.and_then(|ext| ext.to_str())
.unwrap_or("");
let Some(language) = LanguageId::from_extension(extension) else {
// A not-Ready index is why the indexed lane was skipped for a file the
// index may well know: `from_extension` is strictly weaker than the
// indexer's own `LanguageId::from_path`, which additionally classifies
// extensionless entry points such as README / LICENSE / .env. Blaming
// the extension here would be the misleading half of the same defect
// this fix exists to remove.
if let Some(message) = not_ready {
return message;
}
return format!(
"Syntax validation unavailable for {}: unsupported or unknown file extension.",
input.path
);
};
let Some(root) = self.capture_repo_root() else {
return format::not_found_file(&input.path);
};
let canon_path = match edit::safe_repo_path(&root, &input.path) {
Ok(path) => path,
Err(_) => return format::not_found_file(&input.path),
};
if !canon_path.is_file() {
return format::not_found_file(&input.path);
}
// This lane reaches disk unconditionally and never re-consults the index
// for the fallback decision, so it gates the CURRENT bytes even when the
// manifest says `Indexed` (D3: the exemption is about where bytes come
// from). The gate owns the read; nothing below reopens the path.
let bytes =
match read_gate::admit_disk_read(published.live.as_ref(), &input.path, &canon_path) {
Ok(bytes) => bytes,
Err(refusal) => return refusal,
};
let classification = crate::domain::FileClassification::for_code_path(&input.path);
let result = crate::parsing::process_file_with_classification(
&input.path,
&bytes,
language,
classification,
);
let file = IndexedFile::from_parse_result(result, bytes);
let output = format::validate_file_syntax_result(&input.path, &file);
self.session_context.record_summary_output(
"validate_file_syntax",
(output.len() / 4).min(u32::MAX as usize) as u32,
);
output
}
/// Find all references or implementations for a symbol. Modes: (1) default/references: call sites,
/// imports, type usages grouped by file - set compact=true for ~60-75% smaller output. (2) mode='implementations':
/// find trait/interface implementors bidirectionally - set direction='trait'/'type'/'auto'.
/// Use when you need 'who calls this?' or 'who implements this?'
/// NOT for file-level dependencies (use find_dependents).
/// NOT for full refactoring context (use get_symbol_context with sections=[...]).
#[tool(
name = "find_references",
description = "Find all references or implementations for a symbol. Modes: (1) default/references: call sites, imports, type usages grouped by file - set compact=true for ~60-75% smaller output. (2) mode='implementations': find trait/interface implementors bidirectionally - set direction='trait'/'type'/'auto'. Use when you need 'who calls this?' or 'who implements this?' Large output may CCR-compress; use symforge_retrieve with the footer hash. NOT for file-level dependencies (use find_dependents). NOT for full refactoring context (use get_symbol_context with sections=[...]).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn find_references_tool(
&self,
params: Parameters<FindReferencesInput>,
) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
let started = Instant::now();
let output = self.find_references(params).await;
let outcome_class = classify_find_references_output(&output);
self.record_tool_completion("find_references", &output, started.elapsed(), outcome_class);
statused_tool_result(output, outcome_class)
}
pub(crate) async fn find_references(&self, params: Parameters<FindReferencesInput>) -> String {
if let Some(result) = self.proxy_tool_call("find_references", ¶ms.0).await {
return result;
}
// Feature 012 (Phase 3): honest refusal for a cross-project request with
// no daemon (no working set on the local path).
if let Some(refusal) = self
.local_cross_project_refusal(params.0.project.as_deref(), params.0.projects.as_deref())
{
return refusal;
}
let input = ¶ms.0;
if let Some(path) = input.path.as_deref() {
let repo_root = self.capture_repo_root();
let degraded = {
let guard = self.index.read();
loading_guard!(guard);
admission_tier_degradation_for_path(
&guard,
repo_root.as_deref(),
"find_references",
path,
&input.name,
)
};
if let Some(result) = degraded {
return result;
}
}
let mode = input.mode.as_deref().unwrap_or("references");
if mode == "implementations" {
let view = {
let guard = self.index.read();
loading_guard!(guard);
guard.capture_implementations_view(&input.name, input.direction.as_deref())
};
let cap = input.limit.unwrap_or(200).min(500);
let limits = format::OutputLimits::new(cap, cap);
let envelope = if !view.entries.is_empty() {
let guard = self.index.read();
Some(search_format::format_search_envelope(
find_references_match_type_label(input, mode),
index_source_authority_label(&self.index.freshness_status()),
implementations_parse_state_for_paths(&guard, &view),
&implementations_completeness_label(&view, &limits),
&find_references_scope_summary(input, mode),
&implementations_evidence(&view),
))
} else {
None
};
let result = format::implementations_result_view(&view, &input.name, &limits);
if view.entries.is_empty() {
let guard = self.index.read();
let is_concrete = guard.all_files().any(|(_, file)| {
file.symbols.iter().any(|s| {
s.name == input.name
&& matches!(
s.kind,
crate::domain::SymbolKind::Class
| crate::domain::SymbolKind::Struct
| crate::domain::SymbolKind::Enum
)
})
});
if is_concrete {
drop(guard);
return format!(
"No implementations found for \"{}\" — it is a class/struct, not an \
interface/trait.\nUse find_references with mode=\"references\" to find \
callers and usages instead.",
input.name
);
}
// Check if the symbol exists at all in the indexed project
let exists_in_project = guard
.all_files()
.any(|(_, file)| file.symbols.iter().any(|s| s.name == input.name));
drop(guard);
if !exists_in_project {
return format!(
"No implementations found for \"{}\" — this symbol is not defined \
in the indexed project (likely from an external dependency).\n\
Use search_text to find usages of this symbol in your code instead.",
input.name
);
}
}
return match envelope {
Some(envelope) => format!("{envelope}\n\n{result}"),
None => result,
};
}
let limits =
format::OutputLimits::new(input.limit.unwrap_or(20), input.max_per_file.unwrap_or(10));
let collect_qualified_usages = should_collect_qualified_usages(input);
let (result, indexed_ranges, qualified_usages) = {
let guard = self.index.read();
loading_guard!(guard);
if let Some(path) = input.path.as_deref() {
(
guard.capture_find_references_view_for_symbol(
path,
&input.name,
input.symbol_kind.as_deref(),
input.symbol_line,
input.kind.as_deref(),
limits.total_hits,
),
HashSet::new(),
Vec::new(),
)
} else {
let kind_filter = find_references_kind_filter(input.kind.as_deref());
let refs = guard.find_references_for_name(&input.name, kind_filter, false);
let indexed_ranges = refs
.iter()
.map(|(file_path, reference)| ((*file_path).to_string(), reference.byte_range))
.collect();
let qualified_usages = if collect_qualified_usages {
let files = guard.files.iter().filter_map(|(path, file)| {
(file.language == LanguageId::Rust).then_some(
qualified_usages::QualifiedFileContent {
file_path: path.as_str(),
content: file.content.as_slice(),
},
)
});
qualified_usages::collect_qualified_usages(&input.name, files)
} else {
Vec::new()
};
(
Ok(guard.capture_find_references_view(
&input.name,
input.kind.as_deref(),
limits.total_hits,
)),
indexed_ranges,
qualified_usages,
)
}
};
match result {
Ok(mut view) => {
if collect_qualified_usages {
merge_qualified_usages_into_view(&mut view, qualified_usages, indexed_ranges);
}
// Tier-2 honesty sweep (dogfood #1): compute BEFORE the envelope
// so the completeness label can confess the exclusion instead of
// claiming "full for current scope" over an unscanned file.
let tier2_disclosure = {
let repo_root = self.capture_repo_root();
let guard = self.index.read();
let candidates = guard.oversized_metadata_only_files();
tier2_reference_disclosure(
&candidates,
guard.as_ref(),
repo_root.as_deref(),
&input.name,
)
};
let envelope = if !view.files.is_empty() {
let guard = self.index.read();
let mut completeness =
find_references_completeness_label(&view, &limits, input.kind.as_deref());
if tier2_disclosure.is_some() {
completeness.push_str("; Tier-2 exclusions apply (see below)");
}
Some(search_format::format_search_envelope(
find_references_match_type_label(input, mode),
index_source_authority_label(&self.index.freshness_status()),
search_parse_state_for_paths(
&guard,
view.files.iter().map(|file| file.file_path.as_str()),
),
&completeness,
&find_references_scope_summary(input, mode),
&find_references_evidence(&view),
))
} else {
None
};
let mut output = if input.compact.unwrap_or(false) {
format::find_references_compact_view(&view, &input.name, &limits)
} else {
format::find_references_result_view(&view, &input.name, &limits)
};
// Honest disclosure (trust contract): a bare repo-wide name match
// resolves references by NAME only and silently merges references
// to DIFFERENT same-named definitions (e.g. a trait method and an
// unrelated inherent method both named `update_status`). When more
// than one definition shares the name, say so and tell the caller
// how to disambiguate, rather than presenting a conflated list as
// if it were precise. Skipped when `path` is set (the def-scoped
// resolution already pins the definition) or no refs were found.
if input.path.is_none() && !view.files.is_empty() {
// ponytail: linear all-files scan for same-named defs; only
// fires on the no-path branch that already returned hits, so
// it is bounded. A reverse symbol-name index would make it
// O(1) if this ever shows on a hot path.
let def_paths = {
let guard = self.index.read();
symbol_candidate_paths(&guard, &input.name)
};
if def_paths.len() > 1 {
let preview: Vec<&str> =
def_paths.iter().take(5).map(String::as_str).collect();
let suffix = if def_paths.len() > preview.len() {
format!(", … (+{} more)", def_paths.len() - preview.len())
} else {
String::new()
};
output = format!(
"Note: {} definitions named \"{}\" exist across the repo ({}{}). \
These references are matched by name and MAY MIX usages of different \
same-named definitions. Pass `path` (and `symbol_line` if needed) to \
scope references to one definition.\n\n{}",
def_paths.len(),
input.name,
preview.join(", "),
suffix,
output
);
}
}
// Supplemental: if index-based refs are empty, try text search to catch
// qualified-path calls (e.g., module::func()) that the xref extractor misses.
// This aligns find_references results with what search_text(follow_refs=true) finds.
if view.files.is_empty() {
let text_options = search::TextSearchOptions::for_current_code_search();
let text_result = {
let guard = self.index.read();
search::search_text_with_options(
&guard,
Some(&input.name),
None,
false,
&text_options,
)
};
if let Ok(tr) = text_result
&& !tr.files.is_empty()
{
output.push_str(&format!(
"\n\nNote: no indexed references found, but search_text found {} file(s) \
containing \"{}\". The index may miss qualified-path calls (e.g., \
module::{}()). Use search_text(query=\"{}\") for full coverage.",
tr.files.len(), input.name, input.name, input.name
));
}
}
// Tier-2 honesty sweep (dogfood #1): the disclosure rides the
// OUTPUT (both the hits and zero-hits paths), not only the
// envelope, so a truncated or compact read still sees it.
if let Some(disclosure) = &tier2_disclosure {
output.push_str("\n\n");
output.push_str(disclosure);
}
self.record_tool_savings_named(
"find_references",
format::estimate_tokens_from_chars(format::estimate_listing_baseline_chars(
output.len(),
)),
(output.len() / 4) as u64,
);
self.session_context.record_summary_output(
"find_references",
(output.len() / 4).min(u32::MAX as usize) as u32,
);
self.session_context.record_listed_symbol("", &input.name);
let result = match envelope {
Some(envelope) => format!("{envelope}\n\n{output}"),
None => output,
};
self.apply_ccr_budget("find_references", result, params.0.max_tokens)
}
Err(error) => error,
}
}
/// File-level dependency graph: which files import the given file. Set compact=true for ~60-75%
/// smaller output. Supports Mermaid/Graphviz output. Use for "what breaks if I change this file?"
/// NOT for symbol-level references (use find_references).
/// NOT for git co-change patterns (use analyze_file_impact with include_co_changes=true).
#[tool(
description = "File-level dependency graph: which files import the given file. Set compact=true for ~60-75% smaller output. Supports Mermaid/Graphviz output. Use for 'what breaks if I change this file?' NOT for symbol-level references (use find_references). NOT for git co-change patterns (use analyze_file_impact with include_co_changes=true).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn find_dependents(&self, params: Parameters<FindDependentsInput>) -> String {
// Symbol-shaped misuse guard: `find_dependents` answers a FILE-level
// question ("what imports this file?"). A caller passing a `name`
// alongside `path` wants symbol-level callers and would otherwise get a
// file-level import graph that reads like symbol callers. Redirect
// explicitly to `find_references` instead of silently returning the
// wrong shape. Pure input validation — runs before proxy/index access so
// it is identical in local and daemon-proxied modes.
if let Some(name) = params
.0
.name
.as_deref()
.map(str::trim)
.filter(|n| !n.is_empty())
{
return format!(
"find_dependents is file-level only (it lists files that import \"{path}\"). \
You supplied name=\"{name}\", which is a symbol-level query. \
Use find_references(name=\"{name}\") for who calls/uses that symbol, \
or call find_dependents with only path=\"{path}\" for the file dependency graph.",
path = params.0.path,
name = name,
);
}
if let Some(result) = self.proxy_tool_call("find_dependents", ¶ms.0).await {
return result;
}
if let Some(refusal) = self.foreign_project_refusal(params.0.project.as_deref()) {
return refusal;
}
let input = ¶ms.0;
let view = {
let guard = self.index.read();
loading_guard!(guard);
guard.capture_find_dependents_view(&input.path)
};
// Default per-file reference detail is capped at 5 lines (not 10) so the
// non-compact view stays bounded on hub files with dozens of dependents;
// callers can raise it with max_per_file or switch to compact=true.
let limits =
format::OutputLimits::new(input.limit.unwrap_or(20), input.max_per_file.unwrap_or(5));
let fmt = input.format.as_deref().unwrap_or("text");
let output = match fmt {
"mermaid" => format::find_dependents_mermaid(&view, &input.path, &limits),
"dot" => format::find_dependents_dot(&view, &input.path, &limits),
_ if input.compact.unwrap_or(false) => {
format::find_dependents_compact_view(&view, &input.path, &limits)
}
_ => format::find_dependents_result_view(&view, &input.path, &limits),
};
self.session_context.record_summary_output(
"find_dependents",
(output.len() / 4).min(u32::MAX as usize) as u32,
);
format::enforce_token_budget(output, params.0.max_tokens)
}
/// Extract query terms that aren't part of the matched concept key,
/// filtering out stopwords and short words.
fn compute_remainder_terms(query: &str, concept_key: &str) -> Vec<String> {
const STOPWORDS: &[&str] = &[
"a", "an", "the", "in", "on", "of", "for", "to", "and", "or", "is", "it", "my", "at",
"by", "do", "no", "so", "up", "if", "with", "from", "this", "that",
];
let key_words: Vec<&str> = concept_key.split_whitespace().collect();
query
.split_whitespace()
.filter(|w| {
let lower = w.to_ascii_lowercase();
!key_words.iter().any(|kw| kw.eq_ignore_ascii_case(w))
&& !STOPWORDS.contains(&lower.as_str())
&& lower.len() >= 3
})
.map(|w| w.to_ascii_lowercase())
.collect()
}
fn explore_symbol_segments(name: &str) -> Vec<String> {
let mut segments = Vec::new();
let mut current = String::new();
for ch in name.chars() {
let is_separator =
!ch.is_alphanumeric() || matches!(ch, '_' | ':' | '-' | '/' | '\\' | '.');
if is_separator {
if !current.is_empty() {
segments.push(current.to_ascii_lowercase());
current.clear();
}
continue;
}
let split_before = ch.is_uppercase()
&& !current.is_empty()
&& current
.chars()
.last()
.is_some_and(|prev| prev.is_lowercase() || prev.is_ascii_digit());
if split_before {
segments.push(current.to_ascii_lowercase());
current.clear();
}
current.push(ch);
}
if !current.is_empty() {
segments.push(current.to_ascii_lowercase());
}
segments
}
fn explore_fallback_symbol_match(name: &str, term: &str) -> bool {
if name.eq_ignore_ascii_case(term) {
return true;
}
let segments = Self::explore_symbol_segments(name);
segments.iter().any(|segment| segment == term)
}
fn explore_terms_related(lhs: &str, rhs: &str) -> bool {
if lhs.eq_ignore_ascii_case(rhs) {
return true;
}
let lhs = lhs.to_ascii_lowercase();
let rhs = rhs.to_ascii_lowercase();
let shared_prefix = lhs
.chars()
.zip(rhs.chars())
.take_while(|(a, b)| a == b)
.count();
shared_prefix >= 5
}
fn record_explore_file_signal(
file_signals: &mut HashMap<String, ExploreFileSignal>,
path: &str,
term: &str,
weight: u64,
) {
let signal = file_signals.entry(path.to_string()).or_default();
signal.raw_score += weight;
signal.matched_terms.insert(term.to_string());
}
fn derive_explore_cluster(
index: &crate::live_index::LiveIndex,
query_terms: &[String],
file_signals: &HashMap<String, ExploreFileSignal>,
limit: usize,
) -> Option<DerivedExploreCluster> {
const GENERIC_SYMBOLS: &[&str] = &[
"build", "create", "error", "get", "handle", "init", "main", "new", "parse", "process",
"result", "run", "set", "test", "update",
];
if query_terms.len() < 2 {
return None;
}
let mut ranked_files: Vec<(String, u64, usize)> = file_signals
.iter()
.filter_map(|(path, signal)| {
let file = index.get_file(path)?;
let coverage = signal.matched_terms.len();
if coverage < 2 {
return None;
}
let path_penalty = explore_path_penalty(path, Some(&file.classification));
let score = (signal.raw_score + ((coverage as u64) * (coverage as u64) * 10))
* path_penalty;
Some((path.clone(), score, coverage))
})
.collect();
ranked_files.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(&b.0)));
ranked_files.truncate(limit.clamp(1, 3));
if ranked_files.is_empty() {
return None;
}
let mut candidate_scores: HashMap<String, u64> = HashMap::new();
for (path, file_score, coverage) in &ranked_files {
let Some(file) = index.get_file(path) else {
continue;
};
for symbol in &file.symbols {
let lower = symbol.name.to_ascii_lowercase();
if lower.len() < 4 || GENERIC_SYMBOLS.contains(&lower.as_str()) {
continue;
}
let segments = Self::explore_symbol_segments(&symbol.name);
let overlap = query_terms
.iter()
.filter(|term| {
segments
.iter()
.any(|segment| Self::explore_terms_related(segment, term))
})
.count();
if overlap == 0 {
continue;
}
let kind_bonus = match symbol.kind.to_string().as_str() {
"struct" | "class" | "trait" | "interface" | "enum" => 5,
"fn" | "method" => 4,
"impl" | "mod" | "module" => 3,
_ => 1,
} as u64;
let reverse_hits = index
.reverse_index
.get(&symbol.name)
.map(|hits| hits.len())
.unwrap_or(0);
let rarity_bonus = match reverse_hits {
0 => 8,
1..=2 => 6,
3..=5 => 4,
6..=10 => 2,
_ => 1,
} as u64;
let length_bonus = (symbol.name.len().min(24) / 6) as u64;
let score = *file_score
+ ((*coverage as u64) * 5)
+ ((overlap as u64) * 12)
+ kind_bonus
+ rarity_bonus
+ length_bonus;
let entry = candidate_scores.entry(symbol.name.clone()).or_insert(0);
if score > *entry {
*entry = score;
}
}
}
let mut ranked_symbols: Vec<(String, u64)> = candidate_scores.into_iter().collect();
ranked_symbols.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(&b.0)));
let promoted_symbols: Vec<String> = ranked_symbols
.into_iter()
.take(limit.clamp(1, 4))
.map(|(name, _)| name)
.collect();
if promoted_symbols.is_empty() {
return None;
}
Some(DerivedExploreCluster {
seed_terms: query_terms.to_vec(),
promoted_symbols,
seed_files: ranked_files.into_iter().map(|(path, _, _)| path).collect(),
})
}
fn ask_query_tokens(query: &str) -> Vec<String> {
let mut tokens = Vec::new();
for raw in query.split_whitespace() {
let token = raw
.trim_matches(|c: char| !c.is_alphanumeric() && c != '_' && c != ':')
.to_string();
if token.is_empty() {
continue;
}
if token.len() < 2 {
continue;
}
if tokens
.iter()
.any(|existing: &String| existing.eq_ignore_ascii_case(&token))
{
continue;
}
tokens.push(token);
}
tokens
}
fn ask_symbol_candidate_tokens(query: &str) -> Vec<String> {
Self::ask_query_tokens(query)
.into_iter()
.filter(|token| {
let is_symbol_like = token.contains('_')
|| token.contains("::")
|| token.chars().skip(1).any(|c| c.is_uppercase());
is_symbol_like && token.len() >= 4
})
.collect()
}
fn extract_exact_symbol_understanding_candidate(
index: &crate::live_index::LiveIndex,
query: &str,
) -> Option<String> {
const GENERIC_SYMBOLS: &[&str] = &[
"build", "create", "get", "handle", "init", "main", "new", "parse", "process", "run",
"set", "test", "update",
];
/// Score a single (path, symbol) match for prominence. Higher = more canonical.
fn score_match(path: &str, line_start: u32, line_end: u32) -> i32 {
let mut score = 0i32;
if path.starts_with("src/") || path.contains("/src/") {
score += 10;
}
let lower = path.to_ascii_lowercase();
if !lower.contains("test")
&& !lower.contains("vendor")
&& !lower.contains("example")
&& !lower.contains("bench")
{
score += 5;
}
let span = line_end.saturating_sub(line_start);
score += ((span / 10) as i32).min(10);
score
}
/// Search `index` for an exact (case-insensitive) match for `token`.
/// Returns `Some((canonical_name, best_score))` when 1-5 matches are found.
fn find_token(index: &crate::live_index::LiveIndex, token: &str) -> Option<(String, i32)> {
let mut matches: Vec<(String, i32)> = Vec::new(); // (canonical_name, score)
for (path, file) in index.all_files() {
for symbol in &file.symbols {
if symbol.name.eq_ignore_ascii_case(token) {
let s =
score_match(path.as_str(), symbol.line_range.0, symbol.line_range.1);
matches.push((symbol.name.clone(), s));
}
}
}
if matches.is_empty() || matches.len() > 5 {
return None;
}
// Pick the match with the highest score; stable (first wins on tie).
let best = matches
.into_iter()
.max_by_key(|(_, score)| *score)
.expect("non-empty; guarded by is_empty check above");
Some(best)
}
// Collect (canonical_name, score) for each qualifying token.
let mut candidates: Vec<(String, i32)> = Vec::new();
let tokens = Self::ask_symbol_candidate_tokens(query);
for token in &tokens {
if GENERIC_SYMBOLS.contains(&token.to_ascii_lowercase().as_str()) {
continue;
}
if let Some(hit) = find_token(index, token) {
candidates.push(hit);
}
}
// Compound token joining: try "token_a_token_b" for adjacent pairs when
// no single-token candidate was found yet.
if candidates.is_empty() && tokens.len() >= 2 {
for window in tokens.windows(2) {
let joined = format!("{}_{}", window[0], window[1]);
if GENERIC_SYMBOLS.contains(&joined.to_ascii_lowercase().as_str()) {
continue;
}
if let Some(hit) = find_token(index, &joined) {
candidates.push(hit);
}
}
}
if candidates.is_empty() {
return None;
}
// Deduplicate by canonical name, keeping the entry with the highest score.
candidates.sort_by(|a, b| a.0.cmp(&b.0).then(b.1.cmp(&a.1)));
candidates.dedup_by(|later, first| {
// `dedup_by` drops `later` when true is returned. The sort above orders ascending
// by name, then descending by score within each name group, so `first` always holds
// the highest score for a given name — exactly the entry we want to keep.
later.0.eq_ignore_ascii_case(&first.0)
});
// Two or more DISTINCT symbols resolved (e.g. "how does X interact with Y").
// The question is about a relationship, not a single definition — fall through
// to Understand → explore rather than picking the highest-scoring subject.
if candidates.len() >= 2 {
return None;
}
// Pick the single candidate with the highest prominence score.
candidates
.into_iter()
.max_by_key(|(_, score)| *score)
.map(|(name, _)| name)
}
fn extract_exact_implementation_understanding_candidate(
index: &crate::live_index::LiveIndex,
query: &str,
) -> Option<String> {
const IMPLEMENTATION_CUES: &[&str] = &[
"type",
"types",
"implementation",
"implementations",
"implementor",
"implementors",
"implementer",
"implementers",
"implements",
];
const GENERIC_QUERY_WORDS: &[&str] = &[
"a",
"all",
"an",
"and",
"are",
"describe",
"does",
"explain",
"help",
"how",
"main",
"me",
"of",
"the",
"through",
"tell",
"type",
"types",
"understand",
"walk",
"what",
"work",
];
let tokens = Self::ask_query_tokens(query);
if !tokens.iter().any(|token| {
IMPLEMENTATION_CUES
.iter()
.any(|cue| token.eq_ignore_ascii_case(cue))
}) {
return None;
}
let mut candidates = Vec::new();
for token in tokens {
let lower = token.to_ascii_lowercase();
if GENERIC_QUERY_WORDS.contains(&lower.as_str()) {
continue;
}
if let Some(candidate) = Self::exact_trait_like_symbol_candidate(index, &token) {
candidates.push(candidate);
continue;
}
if lower.ends_with('s') && lower.len() > 4 {
let singular = &token[..token.len() - 1];
if let Some(candidate) = Self::exact_trait_like_symbol_candidate(index, singular) {
candidates.push(candidate);
}
}
}
candidates.sort();
candidates.dedup();
if candidates.len() == 1 {
candidates.into_iter().next()
} else {
None
}
}
fn exact_trait_like_symbol_candidate(
index: &crate::live_index::LiveIndex,
token: &str,
) -> Option<String> {
let mut exact_match_count = 0usize;
let mut canonical_name: Option<String> = None;
for (_path, file) in index.all_files() {
for symbol in &file.symbols {
if !symbol.name.eq_ignore_ascii_case(token) {
continue;
}
if !matches!(
symbol.kind,
crate::domain::index::SymbolKind::Trait
| crate::domain::index::SymbolKind::Interface
| crate::domain::index::SymbolKind::Type
) {
continue;
}
exact_match_count += 1;
if canonical_name.is_none() {
canonical_name = Some(symbol.name.clone());
}
}
}
if exact_match_count == 1 {
canonical_name
} else {
None
}
}
/// Start here when you don't know where to look. Accepts a natural-language concept
/// and returns related symbols, patterns, and files. Set depth=2 for signatures and
/// callers of top symbols (~1500 tokens). Set depth=3 for implementations and type
/// dependency chains (~3000 tokens). NOT for finding a specific symbol by name
/// (use search_symbols). NOT for text content search (use search_text).
#[tool(
description = "Use this when you have a concept or topic but not a specific file or symbol name. Accepts a natural-language concept and returns related symbols, patterns, and files. Set depth=2 for signatures and callers of top symbols (~1500 tokens). Set depth=3 for implementations and type dependency chains (~3000 tokens). Large output may CCR-compress; use symforge_retrieve with the footer hash. NOT for finding a specific symbol by name (use search_symbols). NOT for text content search (use search_text).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn explore(&self, params: Parameters<ExploreInput>) -> String {
if let Some(result) = self.proxy_tool_call("explore", ¶ms.0).await {
return result;
}
if let Some(refusal) = self.foreign_project_refusal(params.0.project.as_deref()) {
return refusal;
}
if params.0.estimate == Some(true) {
let depth = params.0.depth.unwrap_or(1);
let est = match depth {
1 => 500,
2 => 1500,
_ => 3000,
};
return format!("Estimate for explore: ~{} tokens (depth={})", est, depth);
}
let lang_filter = match parse_language_filter(params.0.language.as_deref()) {
Ok(f) => f,
Err(e) => return e,
};
let limit = params.0.limit.unwrap_or(10) as usize;
let include_noise = params.0.include_noise.unwrap_or(false);
let include_vendor = params.0.include_vendor.unwrap_or(false);
let include_personal_tooling = params.0.include_personal_tooling.unwrap_or(false);
// B1 additive: vendor surfaces when include_noise OR include_vendor is true;
// personal-tooling surfaces when include_noise OR include_personal_tooling.
let suppress_vendor = !(include_noise || include_vendor);
let suppress_personal = !(include_noise || include_personal_tooling);
let suppress_other_noise = !include_noise;
let any_suppression = suppress_vendor || suppress_personal || suppress_other_noise;
let guard = self.index.read();
loading_guard!(guard);
let concept = super::explore::match_concept(¶ms.0.query);
// A single-word concept that matched ONLY via the stemmed fallback is a
// weak signal: the query never named the concept verbatim. When the query
// also carries specific terms (computed below) the header should let those
// terms lead and demote such a concept to a parenthetical hint, rather than
// collapsing the topic to a label the user did not type. Exact matches and
// multi-word concept keys keep leading the header.
let demote_stem_only_concept = matches!(
concept,
Some((key, _, super::explore::ConceptMatchKind::Stemmed))
if key.split_whitespace().count() == 1
);
let mut enriched_imports: Vec<String> = Vec::new();
let (label, symbol_queries, text_queries, remainder_terms) = if let Some((key, c, _)) =
concept
{
let remainder = Self::compute_remainder_terms(¶ms.0.query, key);
let mut sym_q: Vec<String> = c.symbol_queries.iter().map(|s| s.to_string()).collect();
// Convention-aware enrichment: add project-specific imports related to the concept.
let project_imports =
crate::protocol::conventions::extract_top_import_roots(&guard, 100);
let enrichment = super::explore::enrich_concept_with_imports(c, &project_imports);
enriched_imports = enrichment;
sym_q.extend(enriched_imports.iter().cloned());
(
c.label.to_string(),
sym_q,
c.text_queries
.iter()
.map(|s| s.to_string())
.collect::<Vec<_>>(),
remainder,
)
} else {
let terms = super::explore::fallback_terms(¶ms.0.query);
if terms.is_empty() {
return "Explore requires a non-empty query.".to_string();
}
(
format!("'{}'", params.0.query),
terms.clone(),
terms,
vec![],
)
};
// Phase 1: Symbol search — over-fetch and track both match counts and
// query-term coverage per symbol so multi-term hits outrank one-term noise.
let mut match_scores: HashMap<(String, String, String), ExploreMatchScore> = HashMap::new();
let mut file_signals: HashMap<String, ExploreFileSignal> = HashMap::new();
// Phase 0: Module-path boosting — symbols from files whose path segment
// matches a query term get a weight boost. +2 for exact segment match,
// +1 for substring segment match. Per-directory cap of `limit` symbols.
// For concept+remainder queries, boost on remainder terms only so path-scoping
// is driven by the narrowing terms (e.g., "watcher" in "error handling in the watcher").
let boost_terms = if remainder_terms.is_empty() {
symbol_queries.clone()
} else {
remainder_terms.clone()
};
for term in &boost_terms {
let term_lower = term.to_ascii_lowercase();
for (file_path, file) in guard.all_files() {
if explore_should_skip_path_boost(
file_path,
&file.classification,
include_noise,
include_vendor,
include_personal_tooling,
) {
continue;
}
let segments: Vec<&str> = file_path.split(&['/', '\\'][..]).collect();
let best_match = segments
.iter()
.filter_map(|seg| {
let seg_lower = seg.to_ascii_lowercase();
let seg_stem = seg_lower
.strip_suffix(".rs")
.or_else(|| seg_lower.strip_suffix(".py"))
.or_else(|| seg_lower.strip_suffix(".ts"))
.or_else(|| seg_lower.strip_suffix(".js"))
.or_else(|| seg_lower.strip_suffix(".go"))
.unwrap_or(&seg_lower);
if seg_stem == term_lower {
Some(2usize)
} else if seg_stem.contains(&*term_lower) {
Some(1usize)
} else {
None
}
})
.max();
if let Some(weight) = best_match {
Self::record_explore_file_signal(
&mut file_signals,
file_path,
&term_lower,
weight as u64,
);
for (injected, sym) in file.symbols.iter().enumerate() {
if injected >= limit {
break;
}
let entry = (sym.name.clone(), sym.kind.to_string(), file_path.clone());
let score = match_scores.entry(entry).or_default();
if score.raw_count == 0 {
// Cap path-boost: only seed symbols that have no prior
// matches. This prevents path-matching files from
// dominating over content-matching files.
score.raw_count = weight.min(1);
}
score.matched_terms.insert(term_lower.clone());
}
}
}
}
// Merge remainder terms into symbol/text queries for Phases 1-2 so that compound
// queries like "error handling in the watcher" search concept queries AND "watcher".
let mut all_symbol_queries = symbol_queries.clone();
all_symbol_queries.extend(remainder_terms.iter().cloned());
let mut all_text_queries = text_queries.clone();
all_text_queries.extend(remainder_terms.iter().cloned());
// Lowercased remainder terms drive "specific term" detection below: a
// remainder noun that matches an indexed symbol name (e.g. "admission"
// -> AdmissionTier) must never be outranked by the concept bucket's
// generic symbol_queries (e.g. "index"), and it should keep the topic
// visible in the header instead of collapsing it to the concept label.
let remainder_term_keys: HashSet<String> = remainder_terms
.iter()
.map(|t| t.to_ascii_lowercase())
.collect();
// Remainder terms that actually resolve to an indexed symbol name via
// search_symbols' substring semantics. Populated during the symbol
// search loop so we don't pay for a second index pass.
let mut specific_terms: HashSet<String> = HashSet::new();
let fallback_mode = concept.is_none();
for sq in &all_symbol_queries {
let term_key = sq.to_ascii_lowercase();
let result = search::search_symbols(&guard, sq, None, limit * 3);
let is_remainder_term = remainder_term_keys.contains(&term_key);
let mut seen_paths = HashSet::new();
for hit in &result.hits {
if fallback_mode && !Self::explore_fallback_symbol_match(&hit.name, &term_key) {
continue;
}
// A remainder noun that lands on a real symbol name is a
// load-bearing query term, not generic concept noise.
if !fallback_mode && is_remainder_term {
specific_terms.insert(term_key.clone());
}
let entry = (hit.name.clone(), hit.kind.clone(), hit.path.clone());
let score = match_scores.entry(entry).or_default();
score.raw_count += 1;
score.matched_terms.insert(term_key.clone());
if seen_paths.insert(hit.path.clone()) {
Self::record_explore_file_signal(&mut file_signals, &hit.path, &term_key, 2);
}
}
}
// Filter Phase 1 results by language and path_prefix
if lang_filter.is_some() || params.0.path_prefix.is_some() {
match_scores.retain(|(_, _, path), _| {
if let Some(ref prefix) = params.0.path_prefix
&& !path.starts_with(prefix.as_str())
{
return false;
}
if let Some(ref lang) = lang_filter {
let ext = path.rsplit('.').next().unwrap_or("");
if crate::domain::index::LanguageId::from_extension(ext).as_ref() != Some(lang)
{
return false;
}
}
true
});
file_signals.retain(|path, _| {
if let Some(ref prefix) = params.0.path_prefix
&& !path.starts_with(prefix.as_str())
{
return false;
}
if let Some(ref lang) = lang_filter {
let ext = path.rsplit('.').next().unwrap_or("");
if crate::domain::index::LanguageId::from_extension(ext).as_ref() != Some(lang)
{
return false;
}
}
true
});
}
if any_suppression {
file_signals.retain(|path, _| {
let Some(file) = guard.get_file(path) else {
return false;
};
if suppress_other_noise
&& explore_is_test_like_path(path, Some(&file.classification))
{
return false;
}
if suppress_personal && crate::live_index::query::is_personal_tooling_path(path) {
return false;
}
let class = search::NoisePolicy::classify_path(path, None);
match class {
search::NoiseClass::Vendor => !suppress_vendor,
search::NoiseClass::Generated | search::NoiseClass::Ignored => {
!suppress_other_noise
}
search::NoiseClass::None => true,
}
});
}
// Phase 2: Text search — collect text hits and inject enclosing symbols into match_counts
let mut text_hits: Vec<(String, String, usize)> = Vec::new(); // (path, line, line_number)
for tq in &all_text_queries {
let mut options = search::TextSearchOptions {
total_limit: limit.min(50),
max_per_file: limit, // need enough matches per file for enclosing symbol extraction
..search::TextSearchOptions::for_current_code_search()
};
if let Some(ref prefix) = params.0.path_prefix {
options.path_scope = search::PathScope::Prefix(prefix.clone());
}
if let Some(ref lang) = lang_filter {
options.language_filter = Some(*lang);
}
let result = search::search_text_with_options(&guard, Some(tq), None, false, &options);
if let Ok(r) = result {
let term_key = tq.to_ascii_lowercase();
for file in &r.files {
// SF-STRESS-013: require a word-boundary match so a concept
// idiom like `try {` does not score off `Country {`. Filter
// before recording the file signal so coincidental files do
// not register at all.
let boundary_matches: Vec<&search::TextLineMatch> = file
.matches
.iter()
.filter(|m| concept_text_query_matches_on_boundary(&m.line, tq))
.collect();
if boundary_matches.is_empty() {
continue;
}
Self::record_explore_file_signal(&mut file_signals, &file.path, &term_key, 3);
for m in boundary_matches {
if text_hits.len() < limit && !format::is_noise_line(&m.line) {
text_hits.push((file.path.clone(), m.line.clone(), m.line_number));
}
// Inject enclosing symbol into match_counts.
// Weight 2 so content matches outweigh path-only boosts.
if let Some(ref enc) = m.enclosing_symbol {
let entry = (enc.name.clone(), enc.kind.clone(), file.path.clone());
let score = match_scores.entry(entry).or_default();
score.raw_count += 2;
score.matched_terms.insert(term_key.clone());
}
}
}
}
}
// Filter text hits by path_prefix (language already handled via TextSearchOptions)
if let Some(ref prefix) = params.0.path_prefix {
text_hits.retain(|(path, _, _)| path.starts_with(prefix.as_str()));
}
let derived_cluster = if fallback_mode {
Self::derive_explore_cluster(&guard, &symbol_queries, &file_signals, limit)
} else {
None
};
if let Some(cluster) = &derived_cluster {
for derived_query in &cluster.promoted_symbols {
let term_key = derived_query.to_ascii_lowercase();
if !all_symbol_queries
.iter()
.any(|existing| existing.eq_ignore_ascii_case(derived_query))
{
let result = search::search_symbols(&guard, derived_query, None, limit * 2);
let mut seen_paths = HashSet::new();
for hit in &result.hits {
let entry = (hit.name.clone(), hit.kind.clone(), hit.path.clone());
let score = match_scores.entry(entry).or_default();
score.raw_count += 1;
score.matched_terms.insert(term_key.clone());
if seen_paths.insert(hit.path.clone()) {
Self::record_explore_file_signal(
&mut file_signals,
&hit.path,
&term_key,
2,
);
}
}
}
let mut options = search::TextSearchOptions {
total_limit: limit.min(50),
max_per_file: limit,
..search::TextSearchOptions::for_current_code_search()
};
if let Some(ref prefix) = params.0.path_prefix {
options.path_scope = search::PathScope::Prefix(prefix.clone());
}
if let Some(ref lang) = lang_filter {
options.language_filter = Some(*lang);
}
if let Ok(result) = search::search_text_with_options(
&guard,
Some(derived_query),
None,
false,
&options,
) {
for file in &result.files {
if !file.matches.is_empty() {
Self::record_explore_file_signal(
&mut file_signals,
&file.path,
&term_key,
2,
);
}
for m in &file.matches {
if text_hits.len() < limit && !format::is_noise_line(&m.line) {
text_hits.push((file.path.clone(), m.line.clone(), m.line_number));
}
if let Some(ref enc) = m.enclosing_symbol {
let entry = (enc.name.clone(), enc.kind.clone(), file.path.clone());
let score = match_scores.entry(entry).or_default();
score.raw_count += 1;
score.matched_terms.insert(term_key.clone());
}
}
}
}
}
}
// Phase 3: Filter noise, weight by kind and path, sort, truncate to limit.
// Exclude explore.rs itself (CONCEPT_MAP contains concept keywords in its body).
match_scores.retain(|(_, _, path), _| !path.ends_with("protocol/explore.rs"));
// Score each symbol: match_count * kind_weight, penalized for doc/generated files.
let scored: Vec<((String, String, String), u64)> = match_scores
.into_iter()
.map(|((name, kind, path), score_data)| {
// Kind weight: definition-like symbols rank higher than incidental matches.
let kind_weight: u64 = match kind.as_str() {
"fn" | "method" => 4,
"struct" | "class" | "trait" | "interface" | "enum" => 4,
"impl" | "mod" | "module" => 3,
"const" | "type" => 2,
"variable" | "let" => 1,
"key" | "section" => 1,
_ => 2, // "other" (selectors, etc.)
};
let classification = guard.get_file(&path).map(|file| &file.classification);
let path_penalty = explore_path_penalty(&path, classification);
// Specific remainder terms (query nouns that resolved to a real
// indexed symbol name, e.g. "admission" -> AdmissionTier) are
// load-bearing, not generic concept noise. Each one counts as
// two extra terms toward coverage: enough that a single specific
// noun outranks a generic two-term concept-bucket hit (the
// failure this fix targets), but a symbol with genuine
// three-plus-term co-occurrence still wins. This only affects
// concept mode; fallback mode never populates the set.
let specific_match_count = score_data
.matched_terms
.iter()
.filter(|term| specific_terms.contains(*term))
.count() as u64;
let effective_terms =
score_data.matched_terms.len() as u64 + 2 * specific_match_count;
let alignment_multiplier = if fallback_mode {
explore_fallback_alignment_multiplier(
symbol_queries.len(),
score_data.matched_terms.len(),
)
} else {
8
};
// Saturating NAME signal. The old score multiplied three
// correlated name-overlap factors — raw_count * coverage^2 *
// alignment — which scaled the query-dependent part like
// k * k^2 * f(k) (~1:32:216 for 1/2/3-token matches). After the
// max-normalization below that pinned the best name match to 1.00
// and cratered everyone else onto a cliff ("lone 1.00, then
// crater"). Fold raw hit strength and term coverage into ONE
// additive, saturated value (coverage is now LINEAR, not squared)
// and scale by the bounded alignment/coverage-quality gate.
let raw_component = (score_data.raw_count as u64).min(EXPLORE_RAW_CAP);
let coverage_component = effective_terms.min(EXPLORE_COVERAGE_CAP);
let name_signal = (raw_component + 3 * coverage_component) * alignment_multiplier;
// Concept PROXIMITY: a symbol living in a file that >=2 query
// terms point at (path segment / content / co-located symbol name)
// earns an additive lift even when its own NAME shares no query
// token. This consumes `file_signals`, the per-file concept signal
// that was computed but previously never read by the scorer. Gated
// on the same >=2-term threshold `derive_explore_cluster` uses, so
// a coincidental single-term file cannot inflate everything in it.
let prox = file_signals
.get(&path)
.filter(|signal| signal.matched_terms.len() >= 2)
.map(|signal| signal.raw_score.min(EXPLORE_PROX_CAP))
.unwrap_or(0);
// Blend name and proximity ADDITIVELY with W_NAME >= W_PROX so an
// exact-name query still ranks its target top (no over-correction),
// while proximity can lift a concept-central symbol out of the
// crater the multiplicative curve used to bury it in.
let score = kind_weight
* path_penalty
* (EXPLORE_W_NAME * name_signal + EXPLORE_W_PROX * prox);
((name, kind, path), score)
})
.collect();
// Noise filtering: hide vendor / generated / gitignored / personal-tooling
// by default. include_noise is the umbrella; include_vendor and
// include_personal_tooling are additive finer-grained overrides per B1.
let mut noise_hidden: usize = 0;
let should_hide_path = |path: &str| -> bool {
let Some(file) = guard.get_file(path) else {
return true;
};
if suppress_other_noise && explore_is_test_like_path(path, Some(&file.classification)) {
return true;
}
if suppress_personal && crate::live_index::query::is_personal_tooling_path(path) {
return true;
}
let class = search::NoisePolicy::classify_path(path, None);
match class {
search::NoiseClass::Vendor => suppress_vendor,
search::NoiseClass::Generated | search::NoiseClass::Ignored => suppress_other_noise,
search::NoiseClass::None => false,
}
};
let mut ranked = scored;
// Deterministic order (Constitution IV): score desc, then the full
// (name, kind, path) key ascending. HashMap iteration order is
// nondeterministic and the stable sort would otherwise preserve it for
// equal scores; the key is unique so this is a total order.
ranked.sort_by(|a, b| {
b.1.cmp(&a.1)
.then(a.0.0.cmp(&b.0.0))
.then(a.0.1.cmp(&b.0.1))
.then(a.0.2.cmp(&b.0.2))
});
// Filter out weak matches (score < 8 means single text-only hit in a doc file).
ranked.retain(|(_, score)| *score >= 8);
// SF-STRESS-013: drop hidden vendor/generated/test symbols BEFORE the
// limit truncation so they no longer consume the result budget. Running
// the noise filter after truncate starved real results (e.g. 1 visible
// symbol while 19 hidden vendor symbols had already eaten the limit).
if any_suppression {
ranked.retain(|(key, _)| {
let hide = should_hide_path(&key.2);
if hide {
noise_hidden += 1;
}
!hide
});
}
ranked.truncate(limit);
let max_score = ranked.first().map(|(_, s)| *s as f32).unwrap_or(1.0);
let symbol_scores: Vec<f32> = ranked
.iter()
.map(|(_, s)| {
if max_score > 0.0 {
(*s as f32 / max_score).min(1.0)
} else {
0.0
}
})
.collect();
let symbol_hits: Vec<(String, String, String)> =
ranked.into_iter().map(|(k, _)| k).collect();
// Text hits still pass through the same noise filter so hidden files
// never leak into the rendered pattern list.
let text_hits = if any_suppression {
text_hits
.into_iter()
.filter(|(path, _, _)| {
let hide = should_hide_path(path);
if hide {
noise_hidden += 1;
}
!hide
})
.collect::<Vec<_>>()
} else {
text_hits
};
// Count files by symbol/text presence
let mut file_counts: std::collections::HashMap<String, usize> =
std::collections::HashMap::new();
for (_, _, path) in &symbol_hits {
*file_counts.entry(path.clone()).or_default() += 1;
}
for (path, _, _) in &text_hits {
*file_counts.entry(path.clone()).or_default() += 1;
}
let mut related_files: Vec<(String, usize)> = file_counts.into_iter().collect();
related_files.sort_by_key(|(_, count)| std::cmp::Reverse(*count));
related_files.truncate(limit);
// Depth 2+: enrich top symbol hits with signatures and dependents
let depth = params.0.depth.unwrap_or(1).clamp(1, 3);
let mut enriched_symbols: Vec<format::ExploreEnrichedSymbol> = Vec::new();
// (name, kind, path, signature, dependent_files)
if depth >= 2 {
let enrich_limit = 5.min(symbol_hits.len());
for (name, kind, path) in &symbol_hits[..enrich_limit] {
let signature = guard.get_file(path).and_then(|file| {
let sym = file.symbols.iter().find(|s| {
s.name == *name && s.kind.to_string().eq_ignore_ascii_case(kind)
})?;
let body = std::str::from_utf8(
&file.content[sym.byte_range.0 as usize..sym.byte_range.1 as usize],
)
.ok()?;
Some(format::apply_verbosity(body, "signature"))
});
let dependents = {
let ref_view = guard.capture_find_references_view(name, None, 3);
ref_view
.files
.iter()
.take(3)
.map(|f| f.file_path.clone())
.collect()
};
enriched_symbols.push((
name.clone(),
kind.clone(),
path.clone(),
signature,
dependents,
));
}
}
// Depth 3: gather implementations AND type dependencies for top symbols
let mut symbol_impls: Vec<(String, Vec<String>)> = Vec::new();
let mut symbol_deps: Vec<(String, Vec<String>)> = Vec::new();
if depth >= 3 {
let impl_limit = 3.min(enriched_symbols.len());
for (name, _kind, path, _, _) in &enriched_symbols[..impl_limit] {
// Implementations (trait → implementors)
let impl_view = guard.capture_implementations_view(name, None);
let impl_names: Vec<String> = impl_view
.entries
.iter()
.take(5)
.map(|e| {
format!(
"{} impl {} ({}:{})",
e.implementor, e.trait_name, e.file_path, e.line
)
})
.collect();
if !impl_names.is_empty() {
symbol_impls.push((name.clone(), impl_names));
}
// Type dependencies (what types does this symbol reference?)
let bundle = guard.capture_context_bundle_view(path, name, None, None);
if let crate::live_index::query::ContextBundleView::Found(found) = bundle {
let dep_names: Vec<String> = found
.dependencies
.iter()
.take(8)
.map(|d| format!("{} {} ({})", d.kind_label, d.name, d.file_path))
.collect();
if !dep_names.is_empty() {
symbol_deps.push((name.clone(), dep_names));
}
}
}
}
// When a concept matched but the query also named specific terms that
// resolve to indexed symbols, keep those nouns visible in the header so
// the topic isn't silently collapsed to the generic concept label.
// Order by query position (remainder_terms preserves it) for stability.
let display_label = if !specific_terms.is_empty() {
let ordered: Vec<&str> = remainder_terms
.iter()
.filter(|t| specific_terms.contains(t.as_str()))
.map(|t| t.as_str())
.collect();
if demote_stem_only_concept {
// The concept matched only via a single-word stem misfire (e.g.
// "indexed" -> "Indexing") while the query named real terms. Lead
// with those specific terms and demote the concept to an honest
// parenthetical hint, instead of letting a label the user never
// typed front the header.
format!("{} (+ {label} signals)", ordered.join(", "))
} else {
format!("{label} + {}", ordered.join(", "))
}
} else {
label.clone()
};
let mut output = format::explore_result_view(format::ExploreResultViewInput {
label: &display_label,
symbol_hits: &symbol_hits,
text_hits: &text_hits,
related_files: &related_files,
enriched_symbols: &enriched_symbols,
symbol_impls: &symbol_impls,
symbol_deps: &symbol_deps,
derived_seed_terms: derived_cluster
.as_ref()
.map(|cluster| cluster.seed_terms.as_slice())
.unwrap_or(&[]),
derived_symbols: derived_cluster
.as_ref()
.map(|cluster| cluster.promoted_symbols.as_slice())
.unwrap_or(&[]),
enriched_imports: &enriched_imports,
symbol_scores: &symbol_scores,
derived_seed_files: derived_cluster
.as_ref()
.map(|cluster| cluster.seed_files.as_slice())
.unwrap_or(&[]),
depth,
});
if noise_hidden > 0 {
output.push_str(&format!(
"\n\nNote: {noise_hidden} result(s) from vendor/generated files hidden. Use include_noise=true to include."
));
}
if !output.is_empty() {
// SF-STRESS-013: the explore scorer computes match count, kind
// weight, term-coverage and path proximity — it does NOT compute
// caller density. Drop the inaccurate claim so the footer is honest.
output
.push_str("\n\nranked by: concept match + symbol-token alignment + path proximity");
}
self.record_tool_savings_named(
"explore",
format::estimate_tokens_from_chars(format::estimate_listing_baseline_chars(
output.len(),
)),
(output.len() / 4) as u64,
);
self.session_context
.record_summary_output("explore", (output.len() / 4).min(u32::MAX as usize) as u32);
self.apply_ccr_budget("explore", output, params.0.max_tokens)
}
#[tool(
description = "Detect project coding conventions from the indexed codebase. Returns error handling style, naming patterns, test organization, common imports, and file structure. Use when you need to write code that fits the project's existing patterns.",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn conventions(&self) -> String {
if let Some(result) = self.proxy_tool_call_without_params("conventions").await {
return result;
}
let conv = {
let guard = self.index.read();
loading_guard!(guard);
crate::protocol::conventions::detect_conventions(&guard)
};
let mut output = crate::protocol::conventions::format_conventions(&conv);
output.push_str("\n\n── Worktree awareness ──\n");
output.push_str(
"When editing from inside a git worktree, pass `working_directory` \
(absolute path of the worktree root) to every edit tool \
(edit_within_symbol, replace_symbol_body, insert_symbol, \
delete_symbol, batch_edit, batch_insert, batch_rename) so writes \
land in your worktree instead of the indexed copy.\n\
A supplied `working_directory` is explicit call-time routing \
consent; unset/normal policy allows it, while false/off/disabled \
`SYMFORGE_WORKTREE_AWARE` values block requested routing before \
write. Omitting the parameter preserves today's indexed-path \
behaviour. See README §Worktree awareness.",
);
output.push_str("\n\n── Frecency ranking ──\n");
output.push_str(
"Per-workspace file-ranking signal that decays on a 7-day half-life \
and fuses with existing path-match and co-change signals. Call \
`search_files` with `rank_by=\"frecency\"` to surface files you \
recently touched. With `SYMFORGE_FRECENCY` unset, commitment tools \
collect session-scoped history; `SYMFORGE_FRECENCY=1` uses the \
persistent `.symforge/frecency.db`; false/off/disabled values block \
frecency and requested ranking reports disabled-by-policy evidence.\n\
Bump-on-commitment policy: SymForge bumps a path's frecency score \
on every edit tool and on the read tools that imply commitment to \
a known file (`get_file_context`, `get_file_content`, `get_symbol`, \
`get_symbol_context`). Discovery tools (`search_files`, \
`search_text`, `search_symbols`) deliberately never bump — \
searching for a file is not the same as working on it, and \
self-bumping searches corrupt rankings via a positive feedback \
loop. Batch tools dedup bumps per invocation. Set \
`search_files(debug_ranking=true)` for compact call-time ranking \
diagnostics, or `SYMFORGE_DEBUG_RANKING=1` to default them on \
and show the last-10 bumps list in `health`. See README \
§Frecency ranking and ADR 0011 for the full policy.",
);
self.session_context.record_summary_output(
"conventions",
(output.len() / 4).min(u32::MAX as usize) as u32,
);
output
}
#[tool(
description = "Plan an edit: analyzes a target symbol or file, counts references, and suggests the right sequence of SymForge edit tools. Accepts a bare symbol name, a file path, or an exact selector like `src/lib.rs::helper`. Use before making changes to understand impact.",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn edit_plan(&self, params: Parameters<EditPlanInput>) -> String {
if let Some(result) = self.proxy_tool_call("edit_plan", ¶ms.0).await {
return result;
}
if let Some(refusal) = self.foreign_project_refusal(params.0.project.as_deref()) {
return refusal;
}
let guard = self.index.read();
loading_guard!(guard);
let temporal = self.index.git_temporal();
let output = crate::protocol::edit_plan::plan_edit(&guard, &temporal, ¶ms.0.target);
self.session_context.record_summary_output(
"edit_plan",
(output.len() / 4).min(u32::MAX as usize) as u32,
);
output
}
#[tool(
description = "Suggest what to investigate next based on what you've already loaded. Analyzes session context to find referenced-but-not-loaded symbols. Use during deep investigations to find gaps.",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn investigation_suggest(
&self,
params: Parameters<InvestigationInput>,
) -> String {
if let Some(result) = self
.proxy_tool_call("investigation_suggest", ¶ms.0)
.await
{
return result;
}
if let Some(refusal) = self.foreign_project_refusal(params.0.project.as_deref()) {
return refusal;
}
let guard = self.index.read();
loading_guard!(guard);
let output = crate::protocol::investigation::suggest_next_steps(
&guard,
&self.session_context,
params.0.focus.as_deref(),
);
self.session_context.record_summary_output(
"investigation_suggest",
(output.len() / 4).min(u32::MAX as usize) as u32,
);
output
}
#[tool(
name = "symforge",
description = "STEL read/explore facade — natural-language code intelligence with trust envelope on the compact surface. Phase 0 batteries may pass `_probe_legacy_*` harness fields.",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn symforge_facade_tool(
&self,
params: Parameters<crate::stel::SymforgeCallInput>,
) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
if params.0.is_probe_relay() {
let legacy_tool = match params.0.probe_legacy_tool.as_deref() {
Some(tool) => tool,
None => {
return Ok(ResultStatus::new(OutcomeClass::InvalidRequest)
.into_call_tool_result(
"Phase 0 facade relay requires `_probe_legacy_tool` (A-019 battery harness only)",
));
}
};
let legacy_args = match params.0.probe_legacy_args.clone() {
Some(args) => args,
None => {
return Ok(ResultStatus::new(OutcomeClass::InvalidRequest)
.into_call_tool_result(
"Phase 0 facade relay requires `_probe_legacy_args` (A-019 battery harness only)",
));
}
};
let output = self.dispatch_tool_for_tests(legacy_tool, legacy_args).await;
let outcome_class = if is_error_output(&output) || output.starts_with("Invalid") {
OutcomeClass::InvalidRequest
} else if output.starts_with("Index not loaded.") {
OutcomeClass::InternalFailure
} else {
OutcomeClass::Found
};
return statused_tool_result(output, outcome_class);
}
// Surface-honesty (012 D6 / contracts §3c): with `query` now
// `#[serde(default)]`, an omitted/blank `query` no longer fails rmcp
// deserialization with an opaque error — validate it explicitly here and
// return a clean, actionable InvalidRequest instead.
if params.0.request.query.trim().is_empty() {
return Ok(ResultStatus::new(OutcomeClass::InvalidRequest)
.into_call_tool_result("query is required: pass a natural-language phrase"));
}
// Gate KEPT (unlike `status`, Wave 1 Fix 4): the `symforge` facade is a
// genuine compact-surface invariant, not a self-inflicted refusal. It is
// deliberately NOT advertised on the full surface (surface_probe.rs filters
// it out of `tools/list`), and the A-019 golden-replay harness special-
// cases THIS exact string as the "compact surface was not selected" signal
// (stel/golden_replay.rs). On full, the caller has the 32 legacy tools the
// facade fuses — the message names that path.
if super::surface_probe::surface_profile_from_env()
!= super::surface_probe::SurfaceProfile::Compact
{
return Ok(ResultStatus::new(OutcomeClass::InvalidRequest).into_call_tool_result(
"symforge STEL handler requires SYMFORGE_SURFACE=compact; use legacy tools on the full surface",
));
}
self.symforge_stel_handler(¶ms.0.request).await
}
/// Test/integration helper: L1 plan → index grounding → L2 decision.
#[doc(hidden)]
pub fn stel_decision_for_request_for_tests(
&self,
request: &crate::stel::StelRequest,
) -> crate::stel::StelDecision {
use crate::stel::controller::evaluate_plan_tuned;
use crate::stel::planner::build_plan;
let mut plan = build_plan(request);
self.ground_plan_economics(&mut plan);
let tuned = self.active_tuning_for_economics();
evaluate_plan_tuned(request, &plan, Some(&self.session_context), tuned.as_ref())
}
/// Production compact-surface `symforge` path: L1 plan → L2 decision → L3 serve or P-FF bypass.
///
/// `pub(crate)` so the durable-ledger proxy test (feature 013 US1 T021) can
/// drive the economics path directly, below the `SYMFORGE_SURFACE` facade
/// gate, without a process-global env mutation. Not a public API change.
pub(crate) async fn symforge_stel_handler(
&self,
request: &crate::stel::StelRequest,
) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
use crate::protocol::smart_query;
use crate::stel::controller::{build_estimate, evaluate_plan_tuned};
use crate::stel::executor::{
ServedStepResult, apply_compact_serve_caps, apply_degrade_to_plan,
chain_failure_decision, format_bypass_body, format_cache_hit_body,
format_multi_step_serve_body, format_partial_multi_step_serve_body,
format_single_step_serve_body, is_degrade, route_tool_label, serve_chain_outcome_class,
serve_step_failed, serve_step_outcome, should_skip_legacy_dispatch, tools_executed,
};
use crate::stel::handler::{self, metrics_for_decision_tuned};
use crate::stel::planner::{build_plan, plan_summary_line};
let q = smart_query::strip_leading_articles(request.query.trim());
if q.is_empty() {
return Ok(ResultStatus::new(OutcomeClass::InvalidRequest)
.into_call_tool_result("query requires a non-empty question."));
}
// Facade contract: a prose `symbol` would be passed verbatim as a tool
// `name` and yield a misleading "Symbol not found: <sentence>". Reject it
// here with a corrective message so the agent self-corrects.
if let Some(message) = crate::stel::planner::symbol_contract_violation(request) {
return Ok(
ResultStatus::new(OutcomeClass::InvalidRequest).into_call_tool_result(&message)
);
}
// Surface-honesty (012 Phase 3 / Principle VII, revised by outstanding-
// work Task 4 Step 5): a single `project` selector IS routed — the
// handler injects it into every planned step's `project` arg at serve
// time (see the serve loop below), so the same explicit-project routing
// the direct tools honor works through the facade. Set-valued
// `projects` stays refused: the L1 planner plans single-project reads,
// and silently single-project-resolving a `projects:["*"]` caller would
// hand back partial results that LOOK cross-project (a silent drop).
// A blank `project` / empty `projects` is treated as "not set".
let facade_project = request
.project
.as_deref()
.map(str::trim)
.filter(|p| !p.is_empty())
.map(str::to_string);
let has_projects = request
.projects
.as_deref()
.is_some_and(|ids| ids.iter().any(|id| !id.trim().is_empty()));
if has_projects {
return Ok(
ResultStatus::new(OutcomeClass::InvalidRequest).into_call_tool_result(
"cross-project targeting is not routed through the `symforge` facade; \
call search_symbols / search_text / find_references directly with \
project/projects.",
),
);
}
// Same ordering defect as `symforge_edit_stel_handler`: the per-step
// `project` injection below is the ONLY thing that lets the primitives
// refuse a foreign selector, but the preview and economics-bypass/
// cache-hit paths return BEFORE the serve loop — so a foreign selector
// came back as a bound-project-grounded SUCCESS. Refuse up front on the
// no-daemon path, where cross-project routing does not exist at all.
//
// Knowingly STILL OPEN, deliberately out of scope: the daemon-
// CONFIGURED-but-DEGRADED topology. There `daemon_client` is `Some`, so
// this guard does NOT fire, while `proxy_tool_call` returns `None` and
// execution falls back to the local index — so `preview: true` and the
// economics-bypass/cache-hit early returns can still answer
// `outcome_class: found` with a bound-project-grounded estimate for a
// foreign selector. Closing it means gating on the degraded flag too,
// not just on client presence.
if self.daemon_client.is_none()
&& let Some(refusal) = self.foreign_project_refusal(facade_project.as_deref())
{
return statused_tool_result(refusal, OutcomeClass::InvalidRequest);
}
// Surface-honesty (012 D6 / contracts §3c): `path:` is a WITHIN-project
// filter, not a project selector. A `path:` that resolves outside the
// bound project would silently match nothing (or, for an absolute path,
// mislead the caller into thinking they retargeted). Reject it up front
// with a clear message naming the bound root, mirroring the
// `symbol_contract_violation` corrective pattern. Skipped when no root is
// bound (nothing to verify against) or when `path` is blank.
if let Some(root) = self.capture_repo_root()
&& let Some(path) = request.path.as_deref().filter(|p| !p.trim().is_empty())
&& !path_is_within_bound_project(path, &root)
{
let root_display = root.display().to_string().replace('\\', "/");
return Ok(
ResultStatus::new(OutcomeClass::InvalidRequest).into_call_tool_result(format!(
"path is outside the bound project {root_display}: \
`path:` is a within-project filter, not a project selector \
(use `index_folder {{ path }}` to retarget the workspace)."
)),
);
}
let mut plan = build_plan(request);
// US5 (010 FR-014, D2): ground the plan's economics in the real target
// byte sizes from the index before the L2 gate runs, so `predicted_net`
// varies with the actual work and the adaptive bypass/degrade branches
// become reachable (a tiny target's manual baseline falls below
// SymForge's fixed schema+invoke overhead → economics bypass).
self.ground_plan_economics(&mut plan);
// T032 / FR-006: load the validated tuning in force for the current
// estimator (None when no durable store / no accepted tuning / a stale
// version), and thread it through BOTH the L2 decision and the envelope
// economics so adaptive serve/degrade/bypass branches use the calibrated
// floors. With no tuning this is byte-identical to the static path.
let tuned = self.active_tuning_for_economics();
let decision =
evaluate_plan_tuned(request, &plan, Some(&self.session_context), tuned.as_ref());
let step = plan
.steps
.first()
.expect("L1 planner always emits at least one step");
let plan_summary = plan_summary_line(&plan);
let session_tokens_served = self.session_context.snapshot().total_tokens as i64;
if request.preview == Some(true) {
let estimate = build_estimate(request, &plan, &decision);
let body = handler::format_preview_estimate(&estimate);
let metrics = metrics_for_decision_tuned(
plan_summary,
&decision,
&plan,
0,
session_tokens_served,
tuned.as_ref(),
);
let envelope = handler::envelope_for_decision(&metrics);
// 012 D6-a: the preview body is `envelope + "\n\n" + StelEstimate JSON`
// that consumers parse to the end of the string, so a trailing
// free-text bound-root line would corrupt the JSON tail. Preview is a
// pre-flight estimate, not a served result; bound-root visibility is
// attached to the actual served/bypass responses below instead.
let output = handler::prepend_envelope(&envelope, &body);
return statused_tool_result(output, OutcomeClass::Found);
}
if should_skip_legacy_dispatch(&decision) {
let mut body = if decision.decision == crate::stel::AdmissionDecision::CacheHit {
format_cache_hit_body(&decision)
} else {
format_bypass_body(&decision)
};
// Wave 1 Fix 5: disclose unconsumed caller params on the bypass path
// too, so an economics-bypassed impact request is equally honest.
for note in crate::stel::planner::served_param_disclosures(request, &plan) {
body.push_str("\n\n");
body.push_str(¬e);
}
let output = self.finalize_symforge_with_ledger(
"symforge",
request,
&plan,
&decision,
plan_summary,
session_tokens_served,
&body,
false,
&step.tool,
None,
tuned.as_ref(),
);
// 012 D6-a: surface the bound project on every `symforge` response.
let output = self.with_bound_root_visibility(output);
self.session_context
.record_summary_output("symforge", handler::estimate_tokens(&output));
return statused_tool_result(output, OutcomeClass::Found);
}
let exec_plan = if is_degrade(&decision) {
apply_degrade_to_plan(&plan, &decision)
} else if decision.decision == crate::stel::AdmissionDecision::Serve {
apply_compact_serve_caps(&plan, &decision)
} else {
plan.clone()
};
// US4 find fusion is a UNION of independent surfaces (path + name), not
// a dependent chain: an empty surface (NotFound/EmptyResult) is a valid
// partial result, not a fatal failure. For fusion plans we therefore
// only abort on a genuine error (InternalFailure/InvalidRequest); a
// dependent chain keeps its existing fail-fast on any non-success.
let is_fusion_union = crate::stel::is_find_fusion_plan(&exec_plan);
// Task 4 Step 5: route the caller's single `project` selector through
// every planned primitive. All-or-nothing: if ANY planned step's tool
// has no `project` selector (e.g. git-scoped `detect_impact`), refuse
// the whole call honestly instead of part-routing a plan (results that
// MIX projects would mislead worse than a refusal).
if let Some(project) = facade_project.as_deref()
&& let Some(step) = exec_plan
.steps
.iter()
.find(|step| !Self::facade_step_accepts_project(&step.tool))
{
return Ok(
ResultStatus::new(OutcomeClass::InvalidRequest).into_call_tool_result(format!(
"project '{project}' cannot be routed through this plan: planned step \
`{}` has no project selector. Call the primitive tools directly with \
`project`.",
step.tool
)),
);
}
let mut step_results = Vec::new();
let mut outcome_class = OutcomeClass::Found;
let mut chain_failed = false;
for step in &exec_plan.steps {
// The plan-only planner emits the path step with
// `rank_by="path+cochange"` and no anchor (it has no index). Resolve
// and inject the co-change anchor here, where the index lives. A
// weak/absent anchor degrades to pure path ranking with no error.
let mut step_args = self.inject_find_fusion_cochange_anchor(&step.tool, &step.args);
// Task 4 Step 5: inject the routed `project` selector (validated
// above to be accepted by every step tool). Never overwrite an
// explicit per-step selector the planner set.
if let Some(project) = facade_project.as_deref()
&& let serde_json::Value::Object(ref mut object) = step_args
{
object
.entry("project")
.or_insert_with(|| serde_json::Value::String(project.to_string()));
}
let mut tool_body = self.dispatch_tool_for_tests(&step.tool, step_args).await;
if step.tool == "search_knowledge" {
tool_body = crate::protocol::ccr::rewrite_footer_for_symforge_facade(tool_body);
}
step_results.push(ServedStepResult {
tool: step.tool.clone(),
body: tool_body.clone(),
});
let step_outcome = serve_step_outcome(&step.tool, &tool_body);
if step.tool == "search_knowledge" && step_outcome == OutcomeClass::EmptyResult {
// Knowledge no-match classes are typed successful answers. Keep
// the EmptyResult metadata without feeding them into the
// dependent-chain reject path (M-06 / I-R09).
outcome_class = OutcomeClass::EmptyResult;
continue;
}
if serve_step_failed(&step.tool, &tool_body) {
let fatal = !is_fusion_union
|| matches!(
step_outcome,
OutcomeClass::InternalFailure | OutcomeClass::InvalidRequest
);
if fatal {
outcome_class = serve_chain_outcome_class(step_outcome);
chain_failed = true;
break;
}
}
}
// P3-7: a find-fusion UNION where every surface came back empty/not-found
// is not a success — downgrade the outcome to EmptyResult so agents see an
// honest "no results" status instead of a misleading Found envelope. Only
// applies when no step hard-failed (fail-fast already set the class above).
if is_fusion_union && !chain_failed && !step_results.is_empty() {
let all_empty = step_results.iter().all(|r| {
matches!(
serve_step_outcome(&r.tool, &r.body),
OutcomeClass::EmptyResult | OutcomeClass::NotFound
)
});
if all_empty {
outcome_class = OutcomeClass::EmptyResult;
}
}
let mut effective_decision = decision.clone();
if chain_failed {
let failed_index = step_results.len().saturating_sub(1);
let failed_tool = step_results[failed_index].tool.as_str();
let failed_outcome = serve_step_outcome(failed_tool, &step_results[failed_index].body);
effective_decision =
chain_failure_decision(&plan, &decision, failed_index, failed_tool, failed_outcome);
}
let chain_failure_note = chain_failed.then(|| effective_decision.decision_reason.clone());
let mut body = if exec_plan.steps.len() == 1 {
format_single_step_serve_body(
&plan,
&effective_decision,
&exec_plan.steps[0],
&step_results[0].body,
)
} else if chain_failed {
format_partial_multi_step_serve_body(
&plan,
&effective_decision,
&step_results,
chain_failure_note.as_deref(),
)
} else {
format_multi_step_serve_body(&plan, &effective_decision, &step_results)
};
// US5/FR-012: the impact intent plans a single `find_dependents` step
// (dependents only). Chain co-change partners into the SAME envelope by
// reusing the `analyze_file_impact` co-change flow (`git_temporal()` +
// `format::co_changes_result_view`) — no second index, no fork. Only the
// single-step success path is augmented; a failed/empty dependents step
// keeps its own diagnostics.
if plan.intent == crate::stel::IntentBucket::Impact
&& !chain_failed
&& exec_plan.steps.len() == 1
{
self.append_impact_intent_cochanges(&mut body, &exec_plan.steps[0].args);
}
// Wave 1 Fix 5: disclose any caller param the route did NOT consume
// (e.g. a `path` on the git-derived impact route) — lossless-or-loud,
// via the existing ParamDisposition accounting, never a silent drop.
for note in crate::stel::planner::served_param_disclosures(request, &plan) {
body.push_str("\n\n");
body.push_str(¬e);
}
let tools = tools_executed(&step_results);
let route_label = route_tool_label(&tools);
let tools_called = if tools.len() > 1 { Some(tools) } else { None };
let output = self.finalize_symforge_with_ledger(
"symforge",
request,
&plan,
&effective_decision,
plan_summary,
session_tokens_served,
&body,
!step_results.is_empty(),
&route_label,
tools_called,
tuned.as_ref(),
);
// 012 D6-a: surface the bound project on every `symforge` response.
let output = self.with_bound_root_visibility(output);
self.session_context
.record_summary_output("symforge", handler::estimate_tokens(&output));
statused_tool_result(output, outcome_class)
}
/// Append git co-change partners to the impact-intent envelope.
///
/// The impact intent (`symforge intent=impact`) plans a single
/// `find_dependents` step, which reports the file dependency graph but no
/// co-change data. This chains co-change partners into the SAME response
/// envelope using the same sources `analyze_file_impact` uses — the
/// lock-free `git_temporal()` snapshot on the shared handle and
/// `format::co_changes_result_view` — so dependents and co-changes arrive
/// together without a second index or a forked formatter.
///
/// Gating mirrors `analyze_file_impact`: when temporal is not `Ready` or the
/// path has no git history we surface a short, non-fatal note rather than a
/// placeholder block. `args` is the executed `find_dependents` step args,
/// whose `path` field is the impact target.
fn append_impact_intent_cochanges(&self, body: &mut String, args: &serde_json::Value) {
const IMPACT_INTENT_COCHANGE_LIMIT: usize = 5;
let Some(path) = args.get("path").and_then(|p| p.as_str()) else {
return;
};
let temporal = self.index.git_temporal();
match temporal.state {
crate::live_index::git_temporal::GitTemporalState::Ready => {
let normalized = path.replace('\\', "/");
match temporal.files.get(&normalized) {
Some(history) => {
body.push_str("\n\n");
body.push_str(&format::co_changes_result_view(
&normalized,
history,
IMPACT_INTENT_COCHANGE_LIMIT,
));
}
None => {
body.push_str("\n\nNo git co-change data found for this file.");
}
}
}
crate::live_index::git_temporal::GitTemporalState::Pending
| crate::live_index::git_temporal::GitTemporalState::Computing => {
body.push_str("\n\nGit temporal data is still loading. Co-changes unavailable.");
}
crate::live_index::git_temporal::GitTemporalState::Unavailable(ref reason) => {
body.push_str(&format!("\n\nGit temporal data unavailable: {reason}"));
}
}
}
#[tool(
name = "symforge_edit",
description = "STEL structural edit facade — replace a whole symbol's source by name. `body` is the FULL item source (signature + body, not just the inner block); pass it flush-left — the tool re-columns it to the symbol's indentation, so an already-indented body is not doubled. Leading doc-comments/attributes outside the symbol range are preserved unless `body` itself begins with a doc-comment. Preview by default; apply:true commits; if_match guards against a concurrent edit.",
annotations(
read_only_hint = false,
destructive_hint = true,
idempotent_hint = false,
open_world_hint = false
)
)]
pub(crate) async fn symforge_edit_facade_tool(
&self,
params: Parameters<crate::stel::StelEditRequest>,
) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
// Gate REMOVED (beta finding B4, 2026-07-07): the full surface exposes
// and documents `symforge_edit` as the preferred editing facade, so
// hard-refusing it there was a self-inflicted failure. The handler below
// already translates every op to the same internal legacy tools
// (replace_symbol_body / insert_symbol / edit_within_symbol) on both
// surfaces — no compact-only invariant lives in this dispatch. The
// `symforge` READ facade keeps its gate: its economics/golden-replay
// path (A-019) is compact-specific.
self.symforge_edit_stel_handler(¶ms.0).await
}
/// Production compact-surface `symforge_edit` path: L1 edit plan → L2 economics → preview or guarded apply.
async fn symforge_edit_stel_handler(
&self,
request: &crate::stel::StelEditRequest,
) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
use crate::stel::controller::evaluate_edit_plan;
use crate::stel::edit_apply::{
PreApplyOutcome, apply_requested, format_already_applied_body, format_apply_metadata,
run_pre_apply_gates,
};
use crate::stel::edit_planner::{build_edit_plan, edit_plan_summary_line};
use crate::stel::handler;
use crate::stel::planner::confidence_label;
if let Err(error) = crate::stel::edit_planner::validate_edit_request(request) {
return Ok(ResultStatus::new(OutcomeClass::InvalidRequest)
.into_call_tool_result(error.message));
}
// Knowingly STILL OPEN, deliberately out of scope (same gap as the
// retrieve facade's guard): on the daemon-CONFIGURED-but-DEGRADED
// topology `daemon_client` is `Some`, so this does not fire, yet
// `proxy_tool_call` returns `None` and the edit runs against the local
// index. Closing it means gating on `daemon_degraded` too.
if self.daemon_client.is_none()
&& let Some(refusal) = self.foreign_project_refusal(request.project.as_deref())
{
return statused_tool_result(refusal, OutcomeClass::InvalidRequest);
}
let apply = apply_requested(request);
let mut resolved_symbol = None;
// In daemon-proxy stdio, this front-end intentionally holds
// LiveIndex::empty(); the proxied edit tool runs these gates against the
// daemon's populated index.
if apply && self.daemon_client.is_none() {
let abs_path =
match super::edit_tools::prepare_exact_path_for_edit(self, request.path.trim()) {
Ok((path, _)) => path,
Err(message) => {
return Ok(ResultStatus::new(OutcomeClass::InvalidRequest)
.into_call_tool_result(message));
}
};
// US4 (019): NON-RESERVING replay probe BEFORE `run_pre_apply_gates`.
// The Replace `if_match` guard inside the gates compares against the
// CURRENT symbol body, which has already changed after a first
// successful apply — so an identical idempotent replay carrying the
// ORIGINAL `if_match` would be wrongly rejected there before the
// replay lookup could serve the stored result. This probe short
// circuits an identical key+request replay without re-validating the
// now-stale `if_match`. It NEVER reserves and NEVER mutates store
// state (read-only `replay_if_present`), so the reservation the
// legacy tool takes on the miss path is untouched. A miss falls
// through to the gates (preserving new-key optimistic concurrency);
// a same-key/different-request hit surfaces the store's conflict
// rather than silently replaying.
if let Some(key) = request.idempotency_key.as_deref() {
// A planning failure here is re-surfaced by the authoritative
// `build_edit_plan` call below; don't duplicate the error path.
if let Ok(probe_plan) = build_edit_plan(request) {
let step = probe_plan
.steps
.first()
.expect("edit planner always emits at least one step");
match super::edit_tools::probe_symforge_edit_apply_replay(
self,
&step.tool,
&step.args,
Some(key),
) {
Ok(Some(stored_response)) => {
self.session_context.record_summary_output(
"symforge_edit",
handler::estimate_tokens(&stored_response),
);
return statused_tool_result(stored_response, OutcomeClass::Found);
}
Ok(None) => {}
Err(output) => {
return Ok(ResultStatus::new(OutcomeClass::InvalidRequest)
.into_call_tool_result(output));
}
}
}
}
match run_pre_apply_gates(&self.index, request, &abs_path) {
Ok(PreApplyOutcome::Ready(symbol)) => resolved_symbol = Some(symbol),
// F6: the already-applied check compares against the INDEXED
// copy, but a `working_directory` apply targets a worktree whose
// copy may still lack the change — short-circuiting would skip
// the routed write. Proceed to dispatch; the legacy tool rebases
// onto the worktree target and a truly-identical splice is a
// harmless idempotent rewrite.
Ok(PreApplyOutcome::AlreadyApplied(symbol))
if request.working_directory.is_some() =>
{
resolved_symbol = Some(symbol);
}
Ok(PreApplyOutcome::AlreadyApplied(symbol)) => {
let plan = build_edit_plan(request).expect("validated edit request");
let decision = evaluate_edit_plan(&plan);
let plan_summary = edit_plan_summary_line(&plan);
let session_tokens_served = self.session_context.snapshot().total_tokens as i64;
let tool_body = format_already_applied_body(&symbol);
let routing_meta = format!(
"Mode: guarded apply (already applied)\n\
Route confidence: {}\n\
Chosen tool: replace_symbol_body\n\
Economics: {} ({})",
confidence_label(plan.confidence),
decision.decision.as_str(),
decision.decision_reason,
);
let body = format!("{routing_meta}\n\n{tool_body}");
let output = self.finalize_symforge_with_ledger(
"symforge_edit",
&crate::stel::StelRequest::default(),
&plan,
&decision,
plan_summary,
session_tokens_served,
&body,
false,
"replace_symbol_body",
None,
// Edits are byte-grounded (grounded_edit_tokens), not
// floor-tuned; the auto-tune corrects only the plan-floor
// path, so no tuning applies here.
None,
);
self.session_context
.record_summary_output("symforge_edit", handler::estimate_tokens(&output));
return statused_tool_result(output, OutcomeClass::Found);
}
Err(error) => {
return Ok(ResultStatus::new(OutcomeClass::InvalidRequest)
.into_call_tool_result(error.message));
}
}
}
let plan = match build_edit_plan(request) {
Ok(plan) => plan,
Err(error) => {
return Ok(ResultStatus::new(OutcomeClass::InvalidRequest)
.into_call_tool_result(error.message));
}
};
let decision = evaluate_edit_plan(&plan);
let step = plan
.steps
.first()
.expect("edit planner always emits at least one step");
let plan_summary = edit_plan_summary_line(&plan);
let session_tokens_served = self.session_context.snapshot().total_tokens as i64;
let tool_body = self
.dispatch_tool_for_tests(&step.tool, step.args.clone())
.await;
let invocation = serde_json::to_string(&step.args).unwrap_or_else(|_| "{}".to_string());
let mode_line = if apply {
"Mode: guarded apply (committed when validation succeeds)"
} else {
"Mode: preview-only (dry_run); default when apply is omitted or false"
};
let routing_meta = format!(
"{mode_line}\n\
Route confidence: {}\n\
Chosen tool: {}\n\
Invocation: {}\n\
Rationale: {}\n\
Economics: {} ({})",
confidence_label(plan.confidence),
step.tool,
invocation,
plan.confidence_rationale,
decision.decision.as_str(),
decision.decision_reason,
);
let mut body = format!("{routing_meta}\n\n{tool_body}");
if apply && let Some(symbol) = resolved_symbol.as_ref() {
let write_mode = super::edit_format::symforge_edit_apply_write_mode(&tool_body);
body = format!(
"{routing_meta}\n\n{}\n\n{tool_body}",
format_apply_metadata(symbol, write_mode)
);
}
let legacy_executed = apply && super::edit_format::edit_output_bytes_committed(&tool_body);
let output = self.finalize_symforge_with_ledger(
"symforge_edit",
&crate::stel::StelRequest::default(),
&plan,
&decision,
plan_summary,
session_tokens_served,
&body,
legacy_executed,
&step.tool,
None,
// Edits are byte-grounded, not floor-tuned (see above).
None,
);
self.session_context
.record_summary_output("symforge_edit", handler::estimate_tokens(&output));
let outcome_class = Self::classify_symforge_edit_outcome(&tool_body, apply, &body);
statused_tool_result(output, outcome_class)
}
fn classify_symforge_edit_outcome(
tool_body: &str,
apply: bool,
full_body: &str,
) -> OutcomeClass {
use super::edit_format::symforge_edit_internal_failure;
if is_error_output(tool_body) || tool_body.starts_with("Invalid") {
OutcomeClass::InvalidRequest
} else if symforge_edit_internal_failure(tool_body, apply, full_body) {
OutcomeClass::InternalFailure
} else {
OutcomeClass::Found
}
}
#[tool(
name = "status",
description = "STEL trust envelope and index health summary.",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn status_stel_tool(
&self,
params: Parameters<crate::stel::StelStatusRequest>,
) -> Result<rmcp::model::CallToolResult, rmcp::ErrorData> {
// Wave-1 defect fix (2026-07-02): NO surface gate here. `status` is a
// read-only health/trust readout that the docs tell every client to call
// at session start, so refusing it on `SYMFORGE_SURFACE=full` was a
// self-inflicted failure with no invariant behind it (unlike `symforge`,
// whose gate guards the STEL economics/golden-replay path — kept there;
// `symforge_edit` lost its gate too, beta B4). The body self-describes the active
// surface via `render_stel_status_body`, so a full-surface `status` is
// honest about where it ran.
// TR-01 (FR-006/007): in the default daemon-proxy topology this front-end
// server's `self.index` is EMPTY — the populated index lives in the warm
// daemon that serves real queries. So `status` MUST report the daemon's
// index, exactly like `health`/`health_compact` do, or it lies about a
// working system. Proxy to the daemon first; only fall through to the
// local `self.index` when there is no daemon (embed/local) or the daemon
// is unreachable (degraded fallback, where `ensure_local_index` has
// populated `self.index`).
//
// Thread THIS adapter's served surface into the proxied request so the
// daemon reports the surface actually served on this connection — not the
// daemon process's own env, which may differ (dogfood defect: a full-env
// adapter proxied through a compact-env daemon rendered `surface:
// compact`). The adapter is the authority, so OVERWRITE any client value;
// the daemon prefers this field and falls back to its own env for older
// adapters (backward compat via `#[serde(default)]` on
// `connection_surface`). The same request drives the daemon-less fallback
// below, where env IS the connection surface, so output is unchanged.
let mut request = params.0.clone();
request.connection_surface = Some(
super::surface_probe::surface_profile_label(
super::surface_probe::surface_profile_from_env(),
)
.to_string(),
);
if let Some(result) = self.proxy_tool_call("status", &request).await {
// US5c (P2 correctness/trust): `reset_calibration=true` MUST reset the
// PROXY-owned durable store HERE. The proxy owns `stel_ledger_store`;
// the storeless worker it proxied to resets nothing, so without this
// the call returned success-shaped `Found` while the durable
// calibration was left byte-identical — a silent no-op. Reset BEFORE
// building `proxy_owned_status_lines` below so the overlaid
// calibration lines reflect the post-reset (`deferred`) state, not
// stale pre-reset samples. The receipt mirrors the local path's
// `reset_note` wording and is appended to the body so the operator
// sees the reset actually happened (or an honest no-store note).
let reset_receipt = if request.reset_calibration == Some(true) {
Some(self.proxy_reset_calibration_receipt())
} else {
None
};
// D2-ROOT: the daemon worker owns the populated INDEX but has an EMPTY
// session ledger + NO durable store, so its proxied body reads
// `ledger_events: 0`, `last_ledger_*: none`, `durable_ledger:
// unavailable`, `calibration: deferred` — but THIS proxy owns the
// ledger + store and events accumulate here. Overlay ALL of the
// proxy's OWN ledger/store-derived lines (not just durable_ledger)
// onto the worker body so the operator's status window shows reality,
// not the worker's blind zero. The INDEX lines stay the worker's
// (TR-01). No-op for the parts absent in `detail:compact`, and
// honestly stays `0`/`none`/`unavailable`/`deferred` if this proxy's
// own ledger/store is empty.
let result = overlay_proxy_status_lines(result, &self.proxy_owned_status_lines());
// Mirror `health`: warn loudly if the daemon we proxied to runs an
// older binary than this front-end.
let mut body = append_daemon_staleness_warning(result, env!("CARGO_PKG_VERSION"));
// Surface the honest reset receipt, mirroring the local path's
// `format!("{body}\n{note}")` placement.
if let Some(note) = reset_receipt {
body = format!("{body}\n{note}");
}
return statused_tool_result(body, OutcomeClass::Found);
}
let body = self.render_stel_status_body(&request);
statused_tool_result(body, OutcomeClass::Found)
}
/// Render the `status` body from THIS server's own index, ledger, and
/// durable store — no proxy, no surface-env gate.
///
/// This is the single rendering path shared by three callers:
/// - the front-end local/degraded fallback (when no daemon is reachable),
/// - the embed/local build (the server IS the index), and
/// - the daemon-side `status` dispatch arm
/// ([`Self::status_for_daemon_session`]), where `self.index` is the
/// POPULATED served index.
///
/// Because the daemon process owns the warm index, calling this on the
/// daemon side yields the same readiness/counts the queries actually use —
/// the TR-01 fix (FR-006). The surface-env gate stays on the front-end
/// `status_stel_tool` entry point only; the daemon renders whatever the
/// proxied request asks for.
pub(crate) fn render_stel_status_body(
&self,
request: &crate::stel::StelStatusRequest,
) -> String {
// T037 / FR-011 operator reset: clear accumulated calibration BEFORE
// rendering, so the surface returns to `Deferred`. MCP-native — a param on
// the existing `status` tool, never injected context; never rebuilds the
// index (only the calibration tables are cleared).
let reset_note = if request.reset_calibration == Some(true) {
match self.reset_calibration() {
Some(cleared) => Some(format!(
"calibration_reset: cleared {cleared} sample(s) + active tuning (state -> deferred)"
)),
None => Some(
"calibration_reset: no durable store; in-memory calibration is already deferred"
.to_string(),
),
}
} else {
None
};
// Report the surface actually served on THIS connection. In the daemon-
// proxy topology that is the ADAPTER's profile, threaded in via
// `request.connection_surface`; this daemon process's own env may differ
// (a full-env adapter serves legacy tools through a compact-env daemon).
// Prefer the connection profile when present and recognized; fall back to
// this process's env for direct/daemon-less serving and for older
// adapters that predate the field (backward compat via `#[serde(default)]`).
let env_label = super::surface_probe::surface_profile_label(
super::surface_probe::surface_profile_from_env(),
);
let (surface_label, daemon_env_surface) = match request
.connection_surface
.as_deref()
.and_then(super::surface_probe::surface_label_from_str)
{
// Honest divergence disclosure: the connection serves `conn` while
// this daemon's env resolves `env_label`. Report the connection truth
// and name the daemon's own env on one line (see
// `format_compact_status`), so a cross-process mismatch is never a
// silent lie.
Some(conn) if conn != env_label => (conn, Some(env_label)),
Some(conn) => (conn, None),
None => (env_label, None),
};
let guard = self.index.read();
let ledger = self.stel_ledger.lock();
// 012 D6-a bound-root visibility: surface WHICH workspace answered. This
// is the root bound on THIS server — on the daemon side it is the warm
// project's root (TR-01), on the front-end fallback it is the proxy's
// bound root. Normalized to forward slashes to match `runtime_status_for`.
let project_root = self
.capture_repo_root()
.map(|root| root.to_string_lossy().replace('\\', "/"));
// 013: `mut` — line below reassigns `ctx` with the durable calibration
// verdict override (T033/FR-009).
let mut ctx = crate::stel::StelStatusContext::from_server(
surface_label,
&self.project_name,
project_root,
guard.is_ready(),
guard.file_count(),
guard.symbol_count(),
&ledger,
self.session_context.snapshot().total_tokens,
)
// US3/T029: surface the durable ledger subsystem state so
// restart-survival is observable from `status` (Unavailable on
// stdio/embed; Disabled{reason} for a wired-but-failing store — N-3).
.with_durable_ledger(self.durable_ledger_summary_for_status());
// T033 / FR-009: override the in-memory verdict with the DURABLE one so
// `status detail:full` reflects the persisted cross-session calibration
// state + active tuning. `None` means no durable store is wired; a wired
// store whose sample read fails returns `Deferred` so status never keeps
// an in-memory `Tuned` verdict without a readable durable artifact. After
// a reset above, the durable read sees zero samples -> `Deferred`.
if let Some(verdict) = self.durable_calibration_verdict() {
ctx = ctx.with_calibration_verdict(verdict);
}
// Attach the daemon-env divergence (proxy topology only); `None` on
// same-env and direct serving so the disclosure line appears strictly on
// divergence.
ctx.daemon_env_surface = daemon_env_surface;
// Disclose an ORPHANED daemon: one that still answers but is no longer
// the daemon clients discover. `None` for the recorded daemon and for
// every non-daemon topology, so the line appears strictly on divergence
// — same discipline as the env-surface disclosure above.
ctx.orphaned_daemon_pid = crate::daemon::unrecorded_daemon_pid();
let body = crate::stel::format_stel_status(request, &ctx);
match reset_note {
Some(note) => format!("{body}\n{note}"),
None => body,
}
}
/// Render the proxy-owned `status` line-set from THIS server's OWN ledger +
/// durable store + calibration verdict — the proxy's truth for the lines a
/// worker-rendered `status` body misrepresents on the daemon-backed default
/// (D2-ROOT).
///
/// Builds the SAME [`StelStatusContext`] that [`Self::render_stel_status_body`]
/// builds (the proxy's `stel_ledger` session events, `durable_ledger_summary`,
/// and durable `calibration` verdict) — only WITHOUT the index/project lines,
/// which stay the worker's (TR-01). Used by `status_stel_tool` to overlay the
/// proxy's `ledger_events`/`last_ledger_*`/`durable_ledger`/`calibration`
/// onto the proxied worker body so the operator's status window reflects the
/// proxy's real accumulation, not the storeless worker's blind zero.
///
/// Honesty: an empty proxy ledger yields `ledger_events: 0` /
/// `last_ledger_*: none`; an `Unavailable`/`Disabled` store yields the
/// truthful durable line; a `Deferred`/`Accumulating` verdict yields that
/// calibration section — exactly as `render_stel_status_body` would render
/// them. No store/reset side effects here: this is a pure read.
pub(crate) fn proxy_owned_status_lines(&self) -> crate::stel::ProxyOwnedStatusLines {
// Index/project fields are NOT consumed by `render_proxy_owned_lines`
// (those lines stay the worker's), so we pass the proxy's own empty-index
// values without reading the index — keeping this a ledger/store-only read.
let ledger = self.stel_ledger.lock();
let mut ctx = crate::stel::StelStatusContext::from_server(
"compact",
&self.project_name,
// 012 project_root: unused here — render_proxy_owned_lines omits the
// project/index lines (they stay the worker's, TR-01).
None,
false,
0,
0,
&ledger,
self.session_context.snapshot().total_tokens,
)
.with_durable_ledger(self.durable_ledger_summary_for_status());
// Mirror `render_stel_status_body`: override the in-memory verdict with the
// DURABLE one (cross-session samples + active tuning). A wired store whose
// sample read fails returns `Deferred`; only no store at all yields `None`.
if let Some(verdict) = self.durable_calibration_verdict() {
ctx = ctx.with_calibration_verdict(verdict);
}
crate::stel::render_proxy_owned_lines(&ctx)
}
/// US5c (P2 correctness/trust): reset the PROXY-owned durable calibration
/// store and return an honest receipt line.
///
/// In the default daemon-proxy topology the PROXY owns `stel_ledger_store`;
/// the storeless daemon worker it proxies to has nothing to reset. So a
/// `status(reset_calibration=true)` MUST reset HERE, or it returns a
/// success-shaped `Found` while the durable calibration is left
/// byte-identical — a silent no-op that lies to the operator. Called by the
/// proxy branch of [`Self::status_stel_tool`] BEFORE building
/// [`Self::proxy_owned_status_lines`], so the overlaid calibration lines
/// reflect the post-reset (`deferred`) state, not stale pre-reset samples.
///
/// The receipt wording mirrors `render_stel_status_body`'s `reset_note` (the
/// local/no-daemon path) verbatim, so the operator sees identical honest
/// language whether the reset ran locally or through the proxy: a real
/// cleared-sample count with a store, or the "no durable store" no-op note
/// without one.
#[cfg(feature = "server")]
pub(crate) fn proxy_reset_calibration_receipt(&self) -> String {
match self.reset_calibration() {
Some(cleared) => format!(
"calibration_reset: cleared {cleared} sample(s) + active tuning (state -> deferred)"
),
None => {
"calibration_reset: no durable store; in-memory calibration is already deferred"
.to_string()
}
}
}
/// Embed/no-`server` builds have no durable calibration store wired, so the
/// reset is an honest no-op — mirrors the `reset_calibration() == None` arm
/// of the local path.
#[cfg(not(feature = "server"))]
pub(crate) fn proxy_reset_calibration_receipt(&self) -> String {
"calibration_reset: no durable store; in-memory calibration is already deferred".to_string()
}
/// Daemon-side `status` entry point (TR-01 / FR-006).
///
/// Reached via the `"status"` arm in `daemon::execute_tool_call` when the
/// front-end proxies `status` to the warm daemon. The daemon server owns the
/// POPULATED index, so this renders truthful readiness + counts. It does NOT
/// re-apply the `SYMFORGE_SURFACE=compact` env gate (that gate is the
/// front-end's concern; the daemon serves the proxied request) and it does
/// not re-proxy (the daemon server has no `daemon_client`).
pub(crate) fn status_for_daemon_session(
&self,
request: &crate::stel::StelStatusRequest,
) -> String {
self.render_stel_status_body(request)
}
/// Bound-root visibility line for the `symforge` response envelope (012 D6-a).
///
/// Reuses [`Self::runtime_status_for`] (the same accessor `health` uses) so
/// the surfaced root carries the identical backslash normalization and
/// `project_root` derivation — a single source of truth for "which workspace
/// answered". Returns `project_root: (unbound)` when nothing is bound so a
/// stale or wrong binding is LOUD in every facade response, never silent.
fn stel_bound_root_line(&self) -> String {
let published = self.index.published_state();
let status =
self.runtime_status_for(&published, self.local_runtime_mode(), None, None, None);
format!(
"project_root: {}",
status.project_root.as_deref().unwrap_or("(unbound)")
)
}
/// Attach the bound-root visibility line to a finished `symforge` response so
/// the answering project is always observable (012 D6-a).
///
/// Appended as a trailing line rather than prepended so the trust envelope
/// stays the FIRST block of the response — a contract relied on by consumers
/// and by the facade tests (`output.starts_with("── stel")`). The bound-root
/// line is still unconditionally present, so a stale/wrong binding is loud.
fn with_bound_root_visibility(&self, output: String) -> String {
format!("{output}\n{}", self.stel_bound_root_line())
}
#[allow(clippy::too_many_arguments)]
fn finalize_symforge_with_ledger(
&self,
surface: &'static str,
_request: &crate::stel::StelRequest,
plan: &crate::stel::StelPlan,
decision: &crate::stel::StelDecision,
plan_summary: String,
session_tokens_served: i64,
body: &str,
legacy_executed: bool,
selected_tool: &str,
tools_called: Option<Vec<String>>,
tuned: Option<&crate::stel::ledger_store::TunedEstimateConstants>,
) -> String {
use crate::stel::handler::{self, finalize_symforge_output, metrics_for_decision_tuned};
use crate::stel::ledger::{
LedgerCaptureInput, capture_ledger, format_ledger_envelope_line,
};
let response_tokens = handler::estimate_tokens(body);
// T032: record the prediction the predictor ACTUALLY made for this call —
// tuned when a validated tuning is in force, static otherwise — so the
// ledger's predicted-vs-actual residual reflects the live estimator and
// the next tuning pass measures progress against it (hysteresis).
let metrics = metrics_for_decision_tuned(
plan_summary,
decision,
plan,
response_tokens,
session_tokens_served,
tuned,
);
let (event, meta) = capture_ledger(&LedgerCaptureInput {
plan,
decision,
economics: &metrics.economics,
selected_tool,
tools_called: tools_called.as_deref(),
legacy_executed,
output_body: body,
surface,
});
self.stel_ledger.lock().push(event.clone());
// US3/T028: durable write-through after the in-memory push. Single
// ledger path (no double-count); degrades to a logged no-op on a store
// error and never fails the request (FR-011). Compile-time no-op on
// stdio/embed builds where no durable store is wired.
self.persist_ledger_event_durably(&event);
let ledger_line = format_ledger_envelope_line(&event, &meta);
finalize_symforge_output(metrics, ledger_line, body)
}
#[tool(
description = "Retrieve full tool output previously stored by CCR compression. Pass the hash from a search or discovery footer.",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn symforge_retrieve(
&self,
params: Parameters<SymforgeRetrieveInput>,
) -> String {
let hash = params.0.hash.trim().to_lowercase();
if hash.len() != 12 || !hash.chars().all(|c| c.is_ascii_hexdigit()) {
return "CCR retrieve: invalid hash (expected 12 hex chars)".to_string();
}
match self
.ccr_store
.lock()
.retrieve_checked(&hash, crate::knowledge::SECRET_POLICY_VERSION)
{
Ok(Some(body)) => body,
Ok(None) => {
"CCR retrieve: stale or expired handle; retry the originating search.".to_string()
}
Err(crate::protocol::ccr::CcrRetrieveError::SecretPolicyMismatch) => {
"CCR retrieve: secret-policy version mismatch; retry the originating search."
.to_string()
}
}
}
#[tool(
description = "Show what symbols and files have been fetched this session. Returns a context inventory with token counts. Use to track your context budget and avoid re-fetching content you already have.",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn context_inventory(&self) -> String {
if let Some(result) = self
.proxy_tool_call_without_params("context_inventory")
.await
{
return result;
}
let snap = self.session_context.snapshot();
let ccr = self.compression_economics();
crate::protocol::session::format_context_inventory(&snap, ccr)
}
#[tool(
description = "Natural language entry point — ask any question about the codebase and SymForge routes to the right tool internally. Use when unsure which specific tool to call. Examples: 'who calls X', 'where is X defined', 'how does X work', 'what changed', 'find file X'. Returns the result plus which tool was used, so you can call it directly next time.",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn ask(&self, params: Parameters<SmartQueryInput>) -> String {
use crate::protocol::smart_query;
if let Some(refusal) = self.foreign_project_refusal(params.0.project.as_deref()) {
return refusal;
}
let original_q = params.0.query.trim();
if crate::knowledge::guard_query(original_q).is_err() {
return "Error: sensitive query rejected by repository safety policy.".to_string();
}
let q = smart_query::strip_leading_articles(original_q);
if q.is_empty() {
return "query requires a non-empty question.".to_string();
}
let (mut intent, mut matched_prefix) = smart_query::classify_intent_with_match(q);
if matches!(
intent,
smart_query::QueryIntent::Understand { .. } | smart_query::QueryIntent::Explore { .. }
) {
let guard = self.index.read();
if let Some(name) =
Self::extract_exact_implementation_understanding_candidate(&guard, q)
{
intent = smart_query::QueryIntent::UnderstandImplementations { name };
matched_prefix = false;
} else if let Some(symbol) =
Self::extract_exact_symbol_understanding_candidate(&guard, q)
{
intent = smart_query::QueryIntent::UnderstandSymbol { symbol };
matched_prefix = false;
}
}
let assessment = smart_query::assess_route(&intent, matched_prefix);
let route_desc = smart_query::route_description(&intent);
let result = match &intent {
smart_query::QueryIntent::FindCallers { symbol, path } => {
let input = FindReferencesInput {
name: symbol.clone(),
kind: None,
path: path.clone(),
symbol_kind: None,
symbol_line: None,
limit: None,
max_per_file: None,
compact: Some(true),
mode: None,
direction: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
};
self.find_references(Parameters(input)).await
}
smart_query::QueryIntent::FindSymbol { name, kind } => {
let input = SearchSymbolsInput {
query: Some(name.clone()),
kind: kind.clone(),
path_prefix: None,
language: None,
limit: None,
include_generated: None,
include_tests: None,
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
};
self.search_symbols(Parameters(input)).await
}
smart_query::QueryIntent::FindFile { hint } => {
let input = SearchFilesInput {
project: None,
projects: None,
query: hint.clone(),
limit: None,
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
};
self.search_files(Parameters(input)).await
}
smart_query::QueryIntent::FindChanges => {
let input = WhatChangedInput {
project: None,
since: None,
git_ref: None,
uncommitted: Some(true),
path_prefix: None,
language: None,
code_only: Some(true),
include_symbol_diff: Some(true),
estimate: None,
max_tokens: None,
};
self.what_changed(Parameters(input)).await
}
smart_query::QueryIntent::Understand { concept } => {
let input = ExploreInput {
project: None,
query: concept.clone(),
limit: None,
depth: Some(2),
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
};
self.explore(Parameters(input)).await
}
smart_query::QueryIntent::UnderstandSymbol { symbol } => {
let input = GetSymbolContextInput {
project: None,
name: symbol.clone(),
file: None,
path: None,
symbol_kind: None,
symbol_line: None,
verbosity: Some("compact".to_string()),
bundle: None,
sections: None,
max_tokens: None,
estimate: None,
};
self.get_symbol_context(Parameters(input)).await
}
smart_query::QueryIntent::UnderstandImplementations { name } => {
let input = FindReferencesInput {
name: name.clone(),
kind: None,
path: None,
symbol_kind: None,
symbol_line: None,
limit: None,
max_per_file: None,
compact: None,
mode: Some("implementations".to_string()),
direction: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
};
self.find_references(Parameters(input)).await
}
smart_query::QueryIntent::SearchCode { pattern } => {
let input = SearchTextInput {
query: Some(pattern.clone()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
include_generated: None,
include_tests: None,
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
structural: None,
project: None,
projects: None,
};
self.search_text(Parameters(input)).await
}
smart_query::QueryIntent::SearchKnowledge { query } => {
let input = SearchKnowledgeInput {
query: query.clone(),
path_prefix: None,
source_scope: Some(super::search_tools::KnowledgeSourceScope::Current),
authority_scope: Some(super::search_tools::KnowledgeAuthorityScope::Default),
project: None,
projects: None,
limit: None,
max_tokens: params.0.max_tokens,
};
self.search_knowledge(Parameters(input)).await
}
smart_query::QueryIntent::RepositoryOrientation => {
self.get_repo_map(Parameters(GetRepoMapInput {
project: None,
detail: Some("compact".to_string()),
path: None,
depth: None,
max_files: None,
estimate: None,
max_tokens: params.0.max_tokens,
}))
.await
}
smart_query::QueryIntent::FindDependents { target } => {
let input = FindDependentsInput {
project: None,
path: target.clone(),
name: None,
limit: None,
max_per_file: None,
format: None,
compact: Some(true),
estimate: None,
max_tokens: None,
};
self.find_dependents(Parameters(input)).await
}
smart_query::QueryIntent::FindImplementations { name } => {
let input = FindReferencesInput {
name: name.clone(),
kind: None,
path: None,
symbol_kind: None,
symbol_line: None,
limit: None,
max_per_file: None,
compact: None,
mode: Some("implementations".to_string()),
direction: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
};
self.find_references(Parameters(input)).await
}
smart_query::QueryIntent::ToolHelp { topic } => {
smart_query::render_tool_catalog_for_topic(topic.as_deref())
}
smart_query::QueryIntent::Explore { query } => {
let input = ExploreInput {
project: None,
query: query.clone(),
limit: None,
depth: Some(2),
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
};
self.explore(Parameters(input)).await
}
};
let mut envelope = format!(
"Route confidence: {}\nChosen tool: {}\nInvocation: {}\nRationale: {}",
smart_query::route_confidence_label(assessment.confidence),
smart_query::route_tool_name(&intent),
smart_query::route_invocation(&intent),
assessment.rationale,
);
if original_q != q {
envelope.push_str(&format!("\nOriginal query: {original_q}"));
}
if let Some(next_step) = assessment.suggested_next_step {
envelope.push_str(&format!("\nSuggested next step: {next_step}"));
}
let output = format!("{envelope}\n{route_desc}\n\n{result}");
self.session_context
.record_summary_output("ask", (output.len() / 4).min(u32::MAX as usize) as u32);
format::enforce_token_budget(output, params.0.max_tokens)
}
/// Symbol-level diff between two git refs. Shows +added, -removed, ~modified symbols per changed
/// file. Filter with path_prefix and/or language. Set code_only=true to exclude non-source files.
/// Use for code review to see which functions/classes changed.
/// NOT for file-level change lists (use what_changed).
#[tool(
description = "Symbol-level diff between two git refs. Shows +added, -removed, ~modified symbols per changed file. Filter with path_prefix and/or language. Set code_only=true to exclude non-source files. Use for code review to see which functions/classes changed. NOT for file-level change lists (use what_changed).",
annotations(read_only_hint = true, open_world_hint = false)
)]
pub(crate) async fn diff_symbols(&self, params: Parameters<DiffSymbolsInput>) -> String {
if let Some(result) = self.proxy_tool_call("diff_symbols", ¶ms.0).await {
return result;
}
if let Some(refusal) = self.foreign_project_refusal(params.0.project.as_deref()) {
return refusal;
}
if params.0.estimate == Some(true) {
let compact = params.0.compact.unwrap_or(false);
let summary = params.0.summary_only.unwrap_or(false);
let est = if summary {
50
} else if compact {
200
} else {
500
};
return format!(
"Estimate for diff_symbols: ~{} tokens (compact={}, summary_only={})",
est, compact, summary
);
}
let base = params.0.base.as_deref().unwrap_or("main");
let target = params.0.target.as_deref().unwrap_or("HEAD");
let repo_root = self.capture_repo_root();
let Some(repo_root) = repo_root else {
return "No repository root found.".to_string();
};
// Check index is not loading/empty
{
let guard = self.index.read();
loading_guard!(guard);
}
// Get changed files
let repo = match crate::git::GitRepo::open(&repo_root) {
Ok(r) => r,
Err(e) => return format!("Failed to open repository: {e}"),
};
let changed_files_owned = match repo.changed_paths_between_refs(base, target) {
Ok(paths) => paths,
Err(e) => return format!("Failed to run git diff: {e}"),
};
// Apply path_prefix + language filter
let lang_filter = match parse_language_filter(params.0.language.as_deref()) {
Ok(f) => f,
Err(e) => return e,
};
let code_only = params.0.code_only.unwrap_or(false);
let changed_files: Vec<&str> = changed_files_owned
.iter()
.map(|s| s.as_str())
.filter(|p| {
if let Some(ref prefix) = params.0.path_prefix
&& !p.starts_with(prefix.as_str())
{
return false;
}
if let Some(ref lang) = lang_filter {
let ext = p.rsplit('.').next().unwrap_or("");
if crate::domain::index::LanguageId::from_extension(ext).as_ref() != Some(lang)
{
return false;
}
}
if code_only && lang_filter.is_none() {
let ext = p.rsplit('.').next().unwrap_or("");
match crate::domain::index::LanguageId::from_extension(ext) {
None => return false,
Some(lang) => {
if crate::parsing::config_extractors::is_config_language(&lang) {
return false;
}
}
}
}
true
})
.collect();
if changed_files.is_empty() {
return format!("No file changes found between {base} and {target}.");
}
let output = render_diff_symbols_output(
base,
target,
changed_files_owned.len(),
&changed_files,
&repo,
&self.index.read(),
params.0.compact.unwrap_or(false),
params.0.summary_only.unwrap_or(false),
params.0.path_prefix.as_deref(),
params.0.language.as_deref(),
code_only,
);
self.record_tool_savings_named(
"diff_symbols",
format::estimate_tokens_from_chars(format::estimate_listing_baseline_chars(
output.len(),
)),
(output.len() / 4) as u64,
);
self.session_context.record_summary_output(
"diff_symbols",
(output.len() / 4).min(u32::MAX as usize) as u32,
);
format::enforce_token_budget(output, params.0.max_tokens)
}
}
// ─── Unit tests ──────────────────────────────────────────────────────────────
#[cfg(test)]
mod tests {
mod find_references;
use std::collections::HashMap;
use std::ffi::OsString;
use std::fs;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::time::{Duration, Instant};
use crate::domain::{LanguageId, ReferenceKind, ReferenceRecord, SymbolKind, SymbolRecord};
use crate::live_index::store::{CircuitBreakerState, IndexedFile, LiveIndex, ParseStatus};
use crate::protocol::SymForgeServer;
use crate::protocol::result_status::{OutcomeClass, RESULT_STATUS_META_KEY};
use rmcp::handler::server::tool::IntoCallToolResult;
use rmcp::handler::server::wrapper::Parameters;
use tempfile::TempDir;
// ── Test helpers ─────────────────────────────────────────────────────────
fn make_symbol(name: &str, kind: SymbolKind, line_start: u32, line_end: u32) -> SymbolRecord {
let byte_range = (0, 10);
SymbolRecord {
name: name.to_string(),
kind,
depth: 0,
sort_order: 0,
byte_range,
item_byte_range: Some(byte_range),
line_range: (line_start, line_end),
doc_byte_range: None,
}
}
// ── SF-001 Part 2: daemon served-binary staleness guard ──────────────────
/// Build a minimal proxied-health string carrying the daemon's runtime
/// `version=` token, exactly as `format::format_runtime_status` emits it.
fn proxied_health_with_version(daemon_version: &str) -> String {
format!(
"Runtime: mode=daemon_reused_session | runtime_state=daemon_reused_session | \
version={daemon_version} | project_root=/repo | project_id=p | session_id=s | \
index_id=i | index_generation=1 | project_generation=1 | load_source=fresh_load | \
reset_state=none | index_state=fresh_process"
)
}
#[test]
fn daemon_staleness_warning_fires_when_daemon_older_than_front_end() {
let proxied = proxied_health_with_version("7.17.2");
let out = super::append_daemon_staleness_warning(proxied, "7.18.1");
assert!(
out.contains("Daemon serving stale code"),
"older daemon must trigger the staleness warning; got: {out}"
);
assert!(
out.contains("7.17.2"),
"warning should name the daemon version"
);
assert!(
out.contains("7.18.1"),
"warning should name the front-end version"
);
}
#[test]
fn daemon_staleness_warning_silent_when_versions_equal() {
let proxied = proxied_health_with_version("7.18.1");
let out = super::append_daemon_staleness_warning(proxied.clone(), "7.18.1");
assert_eq!(
out, proxied,
"equal versions must not append any staleness warning"
);
assert!(!out.contains("Daemon serving stale code"));
}
#[test]
fn daemon_staleness_warning_silent_when_daemon_newer() {
let proxied = proxied_health_with_version("7.19.0");
let out = super::append_daemon_staleness_warning(proxied.clone(), "7.18.1");
assert_eq!(out, proxied, "a newer daemon must not be flagged as stale");
}
#[test]
fn daemon_staleness_warning_silent_when_version_token_absent() {
// Fail-safe: a report with no `version=` token yields no warning.
let proxied = "Runtime: mode=daemon_reused_session | project_root=/repo".to_string();
let out = super::append_daemon_staleness_warning(proxied.clone(), "7.18.1");
assert_eq!(out, proxied);
}
#[test]
fn daemon_staleness_warning_silent_when_version_unparseable() {
// Fail-safe: a non-numeric version token cannot be compared, so no warning.
let proxied = proxied_health_with_version("unknown");
let out = super::append_daemon_staleness_warning(proxied.clone(), "7.18.1");
assert_eq!(out, proxied);
}
// ── D2-ROOT: daemon-proxy overlays ALL proxy-owned status lines ──────────
/// A faithful worker `status detail:full` body: rendered by a storeless
/// server (no `with_stel_ledger_store`, EMPTY session ledger), exactly as the
/// daemon worker produces it — so its proxy-owned lines read the blind
/// `ledger_events: 0` / `last_ledger_*: none` / `durable_ledger: unavailable`
/// / `calibration: deferred`.
fn worker_full_status_body() -> String {
let server = make_server(make_live_index_ready(vec![]));
server.render_stel_status_body(&crate::stel::StelStatusRequest {
detail: Some(crate::stel::StelStatusDetail::Full),
reset_calibration: None,
connection_surface: None,
})
}
/// Build a `ProxyOwnedStatusLines` carrying a given durable state, with the
/// other proxy-owned lines rendered from an EMPTY in-memory ledger (so they
/// match the worker's `0`/`none`/`deferred` — these durable-focused tests
/// assert only the durable line, the rest are no-op-equivalent replacements).
fn proxy_lines_with_durable(
state: crate::stel::DurableLedgerState,
) -> crate::stel::ProxyOwnedStatusLines {
let ledger = crate::stel::SessionLedger::new();
let ctx = crate::stel::StelStatusContext::from_server(
"compact", "proj", None, false, 0, 0, &ledger, 0,
)
.with_durable_ledger(state);
crate::stel::render_proxy_owned_lines(&ctx)
}
#[test]
fn overlay_replaces_worker_unavailable_with_proxy_durable_line() {
use crate::stel::{DurableLedgerState, DurableLedgerSummary};
// The worker (storeless) body claims `unavailable`...
let worker = worker_full_status_body();
assert!(
worker.contains("durable_ledger: unavailable"),
"precondition: storeless worker body must read unavailable:\n{worker}"
);
// ...but the proxy owns a real durable store, so the overlay must swap in
// the proxy's true accumulation figure and erase the worker's blind spot.
let overlaid = super::overlay_proxy_status_lines(
worker,
&proxy_lines_with_durable(DurableLedgerState::Durable(DurableLedgerSummary {
total_events: 9,
total_net_vs_manual: 123,
session_count: 2,
})),
);
assert!(
overlaid.contains("durable_ledger: events=9 net_vs_manual=123 sessions=2"),
"overlay must show the proxy's real durable figure:\n{overlaid}"
);
assert!(
!overlaid.contains("durable_ledger: unavailable"),
"the worker's unavailable line must be replaced, not kept:\n{overlaid}"
);
// Exactly ONE durable_ledger line survives (no duplication).
assert_eq!(
overlaid
.lines()
.filter(|l| l.starts_with("durable_ledger:"))
.count(),
1,
"overlay must leave exactly one durable_ledger line:\n{overlaid}"
);
}
#[test]
fn overlay_keeps_unavailable_when_proxy_also_has_no_store() {
use crate::stel::DurableLedgerState;
// Honest no-store-anywhere case: the overlay must NOT invent a figure.
let worker = worker_full_status_body();
let overlaid = super::overlay_proxy_status_lines(
worker,
&proxy_lines_with_durable(DurableLedgerState::Unavailable),
);
assert!(
overlaid.contains("durable_ledger: unavailable"),
"no store anywhere -> stays unavailable:\n{overlaid}"
);
assert!(
!overlaid.contains("durable_ledger: events="),
"an unavailable overlay must present no accumulation figure:\n{overlaid}"
);
}
#[test]
fn overlay_is_noop_for_durable_when_body_has_no_durable_ledger_line() {
use crate::stel::{DurableLedgerState, DurableLedgerSummary};
// A `detail:compact` worker body carries no durable_ledger line / no
// calibration section / no last_ledger lines: the overlay must leave the
// durable line absent (nothing to replace) and rewrite only `ledger_events`
// (the one proxy-owned line a compact body carries — here both are 0).
let compact = make_server(make_live_index_ready(vec![])).render_stel_status_body(
&crate::stel::StelStatusRequest {
detail: None,
reset_calibration: None,
connection_surface: None,
},
);
assert!(
!compact.contains("durable_ledger:"),
"precondition: compact body has no durable_ledger line:\n{compact}"
);
let out = super::overlay_proxy_status_lines(
compact.clone(),
&proxy_lines_with_durable(DurableLedgerState::Durable(DurableLedgerSummary {
total_events: 1,
total_net_vs_manual: 0,
session_count: 1,
})),
);
// No durable_ledger / calibration section in a compact body to overlay,
// and the empty-ledger proxy's `ledger_events: 0` matches the worker's, so
// the compact body is unchanged.
assert_eq!(out, compact, "no full-only lines -> compact body unchanged");
assert!(
!out.contains("durable_ledger:"),
"the overlay must NOT inject a durable line into a compact body:\n{out}"
);
}
/// End-to-end at the proxy boundary: a `new_daemon_proxy` server WITH a
/// durable store attached must compute a real `Durable` overlay state, and a
/// no-store proxy must stay `Unavailable`. This pins the exact value
/// `status_stel_tool` overlays onto the proxied worker body (no live daemon
/// needed — only the proxy's own store read is exercised).
#[test]
fn daemon_proxy_with_store_overlays_real_durable_line_no_store_stays_unavailable() {
use crate::stel::ledger_store::StelLedgerStore;
use crate::stel::{DurableLedgerState, StelStatusDetail, StelStatusRequest};
fn fake_proxy() -> SymForgeServer {
// A dead URL is fine: this test never hits the network — it only reads
// the proxy's OWN attached store, exactly as the overlay does.
let client = crate::daemon::DaemonSessionClient::new_for_test(
"http://127.0.0.1:1".to_string(),
"p".to_string(),
"s".to_string(),
"proj".to_string(),
);
SymForgeServer::new_daemon_proxy(client)
}
// (1) Proxy WITH a durable store: events accumulate here. The overlay
// state it contributes must be `Durable` with its real figures, and
// applying it to a worker body must erase `unavailable`.
let store = StelLedgerStore::open_in_memory("proxy-sess").expect("in-memory store");
store.record(&sample_durable_event());
store.record(&sample_durable_event());
let proxy = fake_proxy().with_stel_ledger_store(Arc::new(store));
let state = proxy.durable_ledger_summary_for_status();
match &state {
DurableLedgerState::Durable(summary) => {
assert_eq!(
summary.total_events, 2,
"proxy store must report its real accumulation"
);
}
other => panic!("a proxy WITH a store must be Durable, got {other:?}"),
}
let overlaid = super::overlay_proxy_status_lines(
worker_full_status_body(),
&proxy.proxy_owned_status_lines(),
);
assert!(
overlaid.contains("durable_ledger: events=2"),
"proxy-backed status must show the proxy's real durable line:\n{overlaid}"
);
assert!(
!overlaid.contains("durable_ledger: unavailable"),
"proxy-backed status must NOT read unavailable:\n{overlaid}"
);
// (2) Proxy with NO store: must stay Unavailable (honest), and the
// overlay leaves the worker's unavailable line in place.
let bare = fake_proxy();
assert_eq!(
bare.durable_ledger_summary_for_status(),
DurableLedgerState::Unavailable,
"a no-store proxy must report Unavailable"
);
let bare_body = bare.render_stel_status_body(&StelStatusRequest {
detail: Some(StelStatusDetail::Full),
reset_calibration: None,
connection_surface: None,
});
let bare_overlaid =
super::overlay_proxy_status_lines(bare_body, &bare.proxy_owned_status_lines());
assert!(
bare_overlaid.contains("durable_ledger: unavailable"),
"a no-store proxy stays unavailable after overlay:\n{bare_overlaid}"
);
}
/// US5c (P2 correctness/trust): in the daemon-proxy topology,
/// `status(reset_calibration=true)` MUST actually reset the PROXY-owned
/// durable calibration store (the proxy owns it; the storeless worker it
/// proxies to resets nothing) AND surface an honest receipt. Before the fix
/// the proxy branch returned success-shaped `Found` while leaving the durable
/// store byte-identical — a silent no-op. This pins the reset + receipt the
/// proxy branch now performs, and that the post-reset verdict overlaid onto
/// the worker body reads `deferred`, not the stale pre-reset `accumulating`.
#[test]
fn daemon_proxy_reset_calibration_clears_proxy_store_and_reports_receipt() {
use crate::stel::calibration::CalibrationVerdict;
use crate::stel::ledger_store::StelLedgerStore;
let client = crate::daemon::DaemonSessionClient::new_for_test(
"http://127.0.0.1:1".to_string(),
"p".to_string(),
"s".to_string(),
"proj".to_string(),
);
// Seed the PROXY's durable store with samples so calibration accumulates
// HERE — exactly the state a real proxy carries while the worker is blind.
let store =
StelLedgerStore::open_in_memory("proxy-reset").expect("in-memory durable store");
store.record(&sample_durable_event());
store.record(&sample_durable_event());
let proxy =
SymForgeServer::new_daemon_proxy(client).with_stel_ledger_store(Arc::new(store));
// Precondition: the proxy store is accumulating (2 samples).
match proxy.durable_calibration_verdict() {
Some(CalibrationVerdict::Accumulating { n, .. }) => assert_eq!(n, 2),
other => panic!("expected accumulating precondition, got {other:?}"),
}
// The proxy-branch reset the fix performs: clear the PROXY-owned store and
// return an honest receipt. This is what `status_stel_tool`'s proxy branch
// invokes when `reset_calibration == Some(true)`.
let receipt = proxy.proxy_reset_calibration_receipt();
// 1) The durable store was actually cleared to deferred (the reset is real,
// not a success-shaped no-op).
assert_eq!(
proxy.durable_calibration_verdict(),
Some(CalibrationVerdict::Deferred),
"reset_calibration in the proxy branch must clear the proxy's durable store to deferred"
);
// 2) The receipt mirrors `render_stel_status_body`'s reset_note wording, and
// reports the 2 cleared samples honestly.
assert_eq!(
receipt, "calibration_reset: cleared 2 sample(s) + active tuning (state -> deferred)",
"proxy reset receipt must mirror the local reset_note wording"
);
// 3) The proxy-owned overlay lines built AFTER the reset reflect the
// post-reset (deferred) state, not the stale pre-reset accumulating one.
let overlaid = super::overlay_proxy_status_lines(
worker_full_status_body(),
&proxy.proxy_owned_status_lines(),
);
assert!(
overlaid.contains("calibration: deferred"),
"overlay after reset must show deferred calibration:\n{overlaid}"
);
assert!(
!overlaid.contains("calibration: accumulating"),
"overlay after reset must NOT show stale accumulating calibration:\n{overlaid}"
);
}
/// Honesty for the no-store proxy: `reset_calibration=true` in the proxy
/// branch with NO durable store attached must NOT claim a reset it did not
/// perform — it returns the honest "no durable store" receipt, matching the
/// local path's wording.
#[test]
fn daemon_proxy_reset_calibration_no_store_reports_honest_no_op() {
let client = crate::daemon::DaemonSessionClient::new_for_test(
"http://127.0.0.1:1".to_string(),
"p".to_string(),
"s".to_string(),
"proj".to_string(),
);
let bare = SymForgeServer::new_daemon_proxy(client);
assert_eq!(
bare.proxy_reset_calibration_receipt(),
"calibration_reset: no durable store; in-memory calibration is already deferred",
"a no-store proxy must report the honest no-op receipt, not a false reset"
);
}
#[test]
fn durable_calibration_status_accumulates_against_full_corpus_threshold() {
use crate::stel::calibration::{CalibrationVerdict, TUNING_MIN_CORPUS, TUNING_MIN_SAMPLES};
use crate::stel::ledger_store::StelLedgerStore;
let client = crate::daemon::DaemonSessionClient::new_for_test(
"http://127.0.0.1:1".to_string(),
"p".to_string(),
"s".to_string(),
"proj".to_string(),
);
let store =
StelLedgerStore::open_in_memory("proxy-accumulating").expect("in-memory durable store");
for _ in 0..(TUNING_MIN_SAMPLES + 1) {
store.record(&sample_durable_event());
}
let proxy =
SymForgeServer::new_daemon_proxy(client).with_stel_ledger_store(Arc::new(store));
match proxy.durable_calibration_verdict() {
Some(CalibrationVerdict::Accumulating { n, min }) => {
assert_eq!(n, TUNING_MIN_SAMPLES + 1);
assert_eq!(min, TUNING_MIN_CORPUS);
assert!(
n <= min,
"status must never render accumulating ({n}/{min})"
);
}
other => panic!("expected durable accumulating verdict, got {other:?}"),
}
let body = proxy.render_stel_status_body(&crate::stel::StelStatusRequest {
detail: Some(crate::stel::StelStatusDetail::Full),
reset_calibration: None,
connection_surface: None,
});
let expected = format!(
"calibration: accumulating ({}/{})",
TUNING_MIN_SAMPLES + 1,
TUNING_MIN_CORPUS
);
assert!(
body.contains(&expected),
"full status must render the true full-corpus threshold {expected:?}:\n{body}"
);
}
#[test]
fn broken_durable_store_pins_status_calibration_to_deferred() {
use crate::stel::calibration::{CalibrationVerdict, TUNING_MIN_CORPUS};
use crate::stel::ledger_store::StelLedgerStore;
let client = crate::daemon::DaemonSessionClient::new_for_test(
"http://127.0.0.1:1".to_string(),
"p".to_string(),
"s".to_string(),
"proj".to_string(),
);
let repo = tempfile::tempdir().expect("temp repo");
let project_state = project_state(repo.path());
let store = StelLedgerStore::open(&project_state, "proxy-broken");
let db_path =
crate::paths::project_state_path(&project_state, crate::paths::STEL_LEDGER_DB_NAME);
rusqlite::Connection::open(db_path)
.expect("open ledger db directly")
.execute_batch("DROP TABLE stel_ledger_events;")
.expect("break durable sample query");
let proxy =
SymForgeServer::new_daemon_proxy(client).with_stel_ledger_store(Arc::new(store));
for i in 0..TUNING_MIN_CORPUS {
let mut event = sample_durable_event();
event.ts_ms += i as u64;
event.plan_id = format!("p-biased-{i}");
event.actual_response_tokens = event.predicted_response_tokens * 2;
proxy.stel_ledger().lock().push(event);
}
let session_events = proxy.stel_ledger().lock().events();
assert!(
matches!(
crate::stel::summarize_calibration(&session_events).verdict,
CalibrationVerdict::Tuned { .. }
),
"fixture must prove the in-memory session alone would claim tuned"
);
assert_eq!(
proxy.durable_calibration_verdict(),
Some(CalibrationVerdict::Deferred),
"a broken wired store cannot prove any tuning is in force"
);
let body = proxy.render_stel_status_body(&crate::stel::StelStatusRequest {
detail: Some(crate::stel::StelStatusDetail::Full),
reset_calibration: None,
connection_surface: None,
});
assert!(
body.contains("durable_ledger: disabled"),
"broken store must be surfaced as disabled:\n{body}"
);
assert!(
body.contains("calibration: deferred"),
"status must not keep the in-memory tuned verdict when durable reads fail:\n{body}"
);
assert!(
!body.contains("calibration: tuned"),
"status must never claim tuned without a readable durable artifact:\n{body}"
);
}
#[test]
fn missing_durable_store_pins_status_calibration_to_deferred() {
use crate::stel::calibration::{CalibrationVerdict, TUNING_MIN_CORPUS};
let client = crate::daemon::DaemonSessionClient::new_for_test(
"http://127.0.0.1:1".to_string(),
"p".to_string(),
"s".to_string(),
"proj".to_string(),
);
let proxy = SymForgeServer::new_daemon_proxy(client);
for i in 0..TUNING_MIN_CORPUS {
let mut event = sample_durable_event();
event.ts_ms += i as u64;
event.plan_id = format!("p-no-store-biased-{i}");
event.actual_response_tokens = event.predicted_response_tokens * 2;
proxy.stel_ledger().lock().push(event);
}
let session_events = proxy.stel_ledger().lock().events();
assert!(
matches!(
crate::stel::summarize_calibration(&session_events).verdict,
CalibrationVerdict::Tuned { .. }
),
"fixture must prove the in-memory session alone would claim tuned"
);
assert_eq!(
proxy.durable_calibration_verdict(),
None,
"precondition: this proxy has no durable store wired"
);
let body = proxy.render_stel_status_body(&crate::stel::StelStatusRequest {
detail: Some(crate::stel::StelStatusDetail::Full),
reset_calibration: None,
connection_surface: None,
});
assert!(
body.contains("durable_ledger: unavailable"),
"missing store must be surfaced as unavailable:\n{body}"
);
assert!(
body.contains("calibration: deferred"),
"status must not keep the in-memory tuned verdict when no durable store is wired:\n{body}"
);
assert!(
!body.contains("calibration: tuned"),
"status must never claim tuned without a durable artifact:\n{body}"
);
}
/// D2-ROOT: a `new_daemon_proxy` server WITH a populated session ledger AND a
/// durable store (samples + a validated `tuned` artifact) must overlay ALL of
/// its proxy-owned `status detail:full` lines — `ledger_events` (non-zero),
/// `last_ledger_decision`/`last_ledger_route`, the durable line, AND the real
/// `calibration` verdict — onto the storeless worker body, NOT the worker's
/// blind `0`/`none`/`unavailable`/`deferred`. The mirror case (no store, empty
/// ledger) stays truthfully `0`/`none`/`unavailable`/`deferred`.
#[test]
fn daemon_proxy_overlays_all_proxy_owned_status_lines_not_worker_blind_view() {
use crate::stel::ledger_store::{
CURRENT_ESTIMATOR_VERSION, StelLedgerStore, TunedEstimateConstants,
};
fn fake_proxy() -> SymForgeServer {
// Dead URL: this test never hits the network — it exercises only the
// proxy's OWN ledger + store, exactly as the overlay does.
let client = crate::daemon::DaemonSessionClient::new_for_test(
"http://127.0.0.1:1".to_string(),
"p".to_string(),
"s".to_string(),
"proj".to_string(),
);
SymForgeServer::new_daemon_proxy(client)
}
// The faithful storeless WORKER body: blind on every proxy-owned line.
let worker = worker_full_status_body();
assert!(
worker.contains("ledger_events: 0"),
"worker blind: {worker}"
);
assert!(
worker.contains("last_ledger_decision: none"),
"worker blind: {worker}"
);
assert!(
worker.contains("last_ledger_route: none"),
"worker blind: {worker}"
);
assert!(
worker.contains("durable_ledger: unavailable"),
"worker blind: {worker}"
);
assert!(
worker.contains("calibration: deferred"),
"worker blind: {worker}"
);
// ── Populated proxy: session ledger + durable store with a TUNED artifact.
let store = StelLedgerStore::open_in_memory("proxy-sess").expect("in-memory store");
// Durable samples so `samples_for_estimator` is non-empty (the verdict
// path reads them), then a validated tuning (error_before > error_after)
// so the durable verdict is `Tuned` — the operator-critical line.
for _ in 0..60 {
store.record(&sample_durable_event());
}
store
.store_active_tuning(&TunedEstimateConstants {
response_correction_factor: 2.0,
estimator_version: CURRENT_ESTIMATOR_VERSION.to_string(),
sample_size: 60,
error_before: 300.0,
error_after: 12.0,
tuned_at_ms: 1,
})
.expect("store active tuning");
let proxy = fake_proxy().with_stel_ledger_store(Arc::new(store));
// Two session events accumulate on the PROXY's in-memory ledger (the
// worker's is empty): last event -> decision `serve`, route
// `find_references` (from `sample_durable_event`).
{
let ledger = proxy.stel_ledger().lock();
ledger.push(sample_durable_event());
ledger.push(sample_durable_event());
}
// Sanity: the proxy's durable verdict is the real `Tuned` (not deferred).
match proxy.durable_calibration_verdict() {
Some(crate::stel::calibration::CalibrationVerdict::Tuned { .. }) => {}
other => panic!("proxy durable verdict must be Tuned, got {other:?}"),
}
let overlaid =
super::overlay_proxy_status_lines(worker.clone(), &proxy.proxy_owned_status_lines());
// (1) ledger_events: the proxy's real session length (2), NOT the worker 0.
assert!(
overlaid.contains("ledger_events: 2"),
"overlay must show the proxy's real ledger_events, not worker 0:\n{overlaid}"
);
assert!(
!overlaid.contains("ledger_events: 0"),
"the worker's blind ledger_events: 0 must be replaced:\n{overlaid}"
);
// (2) last_ledger_decision / route: the proxy's last event, NOT none.
assert!(
overlaid.contains("last_ledger_decision: serve"),
"overlay must show the proxy's last decision, not none:\n{overlaid}"
);
assert!(
overlaid.contains("last_ledger_route: find_references"),
"overlay must show the proxy's last route, not none:\n{overlaid}"
);
assert!(
!overlaid.contains("last_ledger_decision: none"),
"the worker's blind last_ledger_decision: none must be replaced:\n{overlaid}"
);
// (3) durable_ledger: the proxy's real accumulation, NOT unavailable.
assert!(
overlaid.contains("durable_ledger: events="),
"overlay must show the proxy's real durable line, not unavailable:\n{overlaid}"
);
assert!(
!overlaid.contains("durable_ledger: unavailable"),
"the worker's blind durable_ledger: unavailable must be replaced:\n{overlaid}"
);
// (4) calibration: the operator-critical leak. The proxy's store has a
// `tuned` verdict, so the overlaid section must read `tuned (..)`, NOT the
// worker's blind `deferred`.
assert!(
overlaid.contains("calibration: tuned ("),
"overlay must show the proxy's REAL calibration verdict (tuned), not the worker's deferred:\n{overlaid}"
);
assert!(
!overlaid.contains("calibration: deferred"),
"the worker's blind calibration: deferred must be replaced (operator-critical leak):\n{overlaid}"
);
// Exactly one calibration section survives (block replaced, not duplicated).
assert_eq!(
overlaid
.matches("── calibration (observational) ──")
.count(),
1,
"overlay must leave exactly one calibration section:\n{overlaid}"
);
// The WORKER-owned index/project lines stay the worker's — never overlaid.
// (The worker body here is storeless+empty-index, so they read 0/false;
// the point is the overlay did not touch them.)
assert!(
overlaid.contains("index_ready: ") && overlaid.contains("index_files: "),
"the worker's index lines must survive the overlay:\n{overlaid}"
);
// ── Honesty mirror: a no-store, empty-ledger proxy stays truthful.
let bare = fake_proxy();
let bare_overlaid =
super::overlay_proxy_status_lines(worker, &bare.proxy_owned_status_lines());
assert!(
bare_overlaid.contains("ledger_events: 0"),
"empty proxy stays ledger_events: 0:\n{bare_overlaid}"
);
assert!(
bare_overlaid.contains("last_ledger_decision: none"),
"empty proxy stays last_ledger_decision: none:\n{bare_overlaid}"
);
assert!(
bare_overlaid.contains("durable_ledger: unavailable"),
"no-store proxy stays durable_ledger: unavailable:\n{bare_overlaid}"
);
assert!(
bare_overlaid.contains("calibration: deferred"),
"no-store/empty proxy stays calibration: deferred (honest):\n{bare_overlaid}"
);
assert!(
!bare_overlaid.contains("calibration: tuned"),
"an empty proxy must NEVER invent a tuned verdict:\n{bare_overlaid}"
);
}
/// A minimal STEL ledger event for proxy-store accumulation tests.
fn sample_durable_event() -> crate::stel::types::StelLedgerEvent {
use crate::stel::types::{AdmissionDecision, IntentBucket, RouteConfidence};
crate::stel::types::StelLedgerEvent {
ts_ms: 1_718_000_000_000,
plan_id: "p-overlay".to_string(),
surface: "symforge".to_string(),
intent: IntentBucket::Trace,
decision: AdmissionDecision::Serve,
tools_called: vec!["find_references".to_string()],
predicted_response_tokens: 400,
actual_response_tokens: 380,
manual_baseline_tokens: 800,
net_vs_manual: 420,
equivalence: None,
route_confidence: RouteConfidence::Exact,
pff_bypass: None,
cache_hit: None,
degrade_flags: vec![],
}
}
#[test]
fn extract_runtime_version_pulls_token_from_runtime_line() {
let proxied = proxied_health_with_version("7.17.2");
assert_eq!(super::extract_runtime_version(&proxied), Some("7.17.2"));
assert_eq!(super::extract_runtime_version("no version here"), None);
}
#[test]
fn extract_runtime_version_pulls_token_from_status_body() {
// TR-01: the `status` body uses `symforge_version: X`, not `version=X`.
// The extractor must read that form so the staleness guard is not a
// structural no-op on the status proxy path.
let status_body =
"── stel status ──\nsurface: compact\nsymforge_version: 7.17.2\nindex_ready: true\n──";
assert_eq!(super::extract_runtime_version(status_body), Some("7.17.2"));
}
#[test]
fn daemon_staleness_warning_fires_on_status_body_for_older_daemon() {
// TR-01: an older daemon answering a proxied `status` call must trigger
// the same loud skew warning `health` gets (the comment in
// `status_stel_tool` is now true, not aspirational).
let status_body =
"── stel status ──\nsurface: compact\nsymforge_version: 7.17.2\nindex_ready: true\n──"
.to_string();
let out = super::append_daemon_staleness_warning(status_body, "7.18.1");
assert!(
out.contains("Daemon serving stale code"),
"older daemon serving `status` must trigger the staleness warning; got: {out}"
);
}
/// F4: `status`'s `index_ready` is protocol-visible and comes straight from
/// `LiveIndex::is_ready()`. The cold-start fix made `is_ready()` delegate to
/// `index_state()`, which changed this rendered line for the bootstrap
/// placeholder — and NOTHING pinned it.
///
/// The pairing is the whole point: `index_files` > 0 next to
/// `index_ready: false`. That looks contradictory and is exactly right — the
/// placeholder HAS files (a targeted read admitted one) but has no bound
/// root, so it cannot answer as a view of the repository. A regression that
/// re-decouples `is_ready()` from `index_state()` re-reports `true` here and
/// fails this test.
#[test]
fn status_reports_index_not_ready_for_a_bootstrap_placeholder_that_admitted_a_file() {
let (key, file) = make_file("src/admitted_before_load.rs", b"fn core() {}", vec![]);
let mut index = make_live_index_ready(vec![(key, file)]);
// The placeholder shape: files present, but the detached initial load has
// not published, so no root is bound.
index.load_source = crate::live_index::store::IndexLoadSource::EmptyBootstrap;
index.indexed_root = None;
let body = make_server(index).render_stel_status_body(&crate::stel::StelStatusRequest {
detail: Some(crate::stel::StelStatusDetail::Full),
reset_calibration: None,
connection_surface: None,
});
assert!(
body.contains("index_ready: false"),
"a rootless bootstrap placeholder must not advertise index_ready: true:\n{body}"
);
assert!(
body.contains("index_files: 1"),
"the placeholder really does hold the admitted file; that is what makes \
index_ready: false load-bearing rather than a trivial empty-index case:\n{body}"
);
}
#[tokio::test]
async fn status_serves_on_full_surface_without_corpus() {
// Wave 1 Fix 4 (corpus-free proof): with SYMFORGE_SURFACE=full active,
// `status` must NOT refuse (its old surface gate is gone) and must
// self-describe the active surface. Runs over a temp in-memory index —
// no phase0 corpus, so it executes in a fresh clone (unlike the
// corpus-gated tests/stel_status.rs coverage that skips when absent).
// The lib suite runs --test-threads=1; EnvVarGuard restores on drop.
let _surface = EnvVarGuard::set("SYMFORGE_SURFACE", "full");
let (key, file) = make_file("src/lib.rs", b"fn core() {}", vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.status_stel_tool(Parameters(crate::stel::StelStatusRequest::default()))
.await
.expect("status dispatch");
let serialized = serde_json::to_value(&result).expect("serialize CallToolResult");
let output = tool_result_text(&serialized);
assert!(
!output.contains("requires SYMFORGE_SURFACE=compact"),
"status must not refuse on the full surface:\n{output}"
);
assert!(
output.contains("surface: full"),
"status must self-describe the active (full) surface:\n{output}"
);
}
#[tokio::test]
async fn status_reports_connection_surface_and_discloses_daemon_env_divergence() {
// Dogfood defect (2026-07-02): a full-surface stdio ADAPTER proxies
// `status` to a compact-env DAEMON. The daemon must report the surface
// actually served on the connection (`full`, threaded in via
// `connection_surface`) — NOT its own env (`compact`) — and disclose the
// divergence on one line. Exercises the daemon-side handler directly;
// in-process the adapter and daemon share env, so divergence is only
// reachable by hand-threading the connection profile.
let _surface = EnvVarGuard::set("SYMFORGE_SURFACE", "compact");
let (key, file) = make_file("src/lib.rs", b"fn core() {}", vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let request = crate::stel::StelStatusRequest {
connection_surface: Some("full".to_string()),
..Default::default()
};
let body = server.render_stel_status_body(&request);
assert!(
body.contains("surface: full"),
"status must report the surface served on the connection (full):\n{body}"
);
assert!(
body.contains("daemon_env_surface: compact (serving connection: full)"),
"status must disclose the daemon/connection surface divergence:\n{body}"
);
}
#[tokio::test]
async fn status_without_connection_surface_falls_back_to_env() {
// Backward compat: an OLD adapter sends no `connection_surface`. The
// daemon falls back to its own env (`compact`) and adds NO divergence
// line — byte-identical to pre-fix behavior.
let _surface = EnvVarGuard::set("SYMFORGE_SURFACE", "compact");
let (key, file) = make_file("src/lib.rs", b"fn core() {}", vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let body = server.render_stel_status_body(&crate::stel::StelStatusRequest::default());
assert!(
body.contains("surface: compact"),
"absent connection surface must fall back to env (compact):\n{body}"
);
assert!(
!body.contains("daemon_env_surface:"),
"no divergence line without a connection surface:\n{body}"
);
}
#[tokio::test]
async fn status_same_env_and_connection_surface_has_no_divergence_line() {
// Same-env path: connection `full` + daemon env `full`. Report `full`
// with NO divergence line (divergence discloses strictly on mismatch).
let _surface = EnvVarGuard::set("SYMFORGE_SURFACE", "full");
let (key, file) = make_file("src/lib.rs", b"fn core() {}", vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let request = crate::stel::StelStatusRequest {
connection_surface: Some("full".to_string()),
..Default::default()
};
let body = server.render_stel_status_body(&request);
assert!(
body.contains("surface: full"),
"matching connection+env must report full:\n{body}"
);
assert!(
!body.contains("daemon_env_surface:"),
"no divergence line when connection matches env:\n{body}"
);
}
fn make_symbol_with_bytes(
name: &str,
kind: SymbolKind,
line_start: u32,
line_end: u32,
byte_range: (u32, u32),
) -> SymbolRecord {
SymbolRecord {
name: name.to_string(),
kind,
depth: 0,
sort_order: 0,
byte_range,
item_byte_range: Some(byte_range),
line_range: (line_start, line_end),
doc_byte_range: None,
}
}
fn medium_test_source_with_prefix(core: &str, line_prefix: &str) -> Vec<u8> {
use crate::protocol::format::{SMALL_FILE_CHAR_THRESHOLD, SMALL_FILE_LINE_THRESHOLD};
let mut out = core.to_string();
if !out.ends_with('\n') {
out.push('\n');
}
let mut line_count = out.lines().count();
while line_count <= SMALL_FILE_LINE_THRESHOLD {
out.push_str(line_prefix);
out.push_str("test fixture padding\n");
line_count += 1;
}
while out.len() <= SMALL_FILE_CHAR_THRESHOLD {
out.push_str(line_prefix);
out.push_str("pad\n");
}
out.into_bytes()
}
fn medium_test_source(core: &str) -> Vec<u8> {
medium_test_source_with_prefix(core, "// ")
}
fn make_file(path: &str, content: &[u8], symbols: Vec<SymbolRecord>) -> (String, IndexedFile) {
(
path.to_string(),
IndexedFile {
relative_path: path.to_string(),
language: LanguageId::Rust,
classification: crate::domain::FileClassification::for_code_path(path),
content: content.to_vec(),
symbols,
parse_status: ParseStatus::Parsed,
parse_diagnostic: None,
byte_len: content.len() as u64,
content_hash: "test".to_string(),
references: vec![],
alias_map: std::collections::HashMap::new(),
mtime_secs: 0,
},
)
}
fn make_file_with_refs(
path: &str,
content: &[u8],
symbols: Vec<SymbolRecord>,
references: Vec<ReferenceRecord>,
) -> (String, IndexedFile) {
let (key, mut file) = make_file(path, content, symbols);
file.references = references;
(key, file)
}
fn make_ref(
name: &str,
qualified_name: Option<&str>,
kind: ReferenceKind,
line: u32,
enclosing_symbol_index: Option<u32>,
) -> ReferenceRecord {
ReferenceRecord {
name: name.to_string(),
qualified_name: qualified_name.map(str::to_string),
kind,
byte_range: (line * 10, line * 10 + 6),
line_range: (line, line),
enclosing_symbol_index,
}
}
fn make_symbol_with_depth(
name: &str,
kind: SymbolKind,
depth: u32,
line_start: u32,
line_end: u32,
byte_range: (u32, u32),
) -> SymbolRecord {
SymbolRecord {
name: name.to_string(),
kind,
depth,
sort_order: 0,
byte_range,
item_byte_range: Some(byte_range),
line_range: (line_start, line_end),
doc_byte_range: None,
}
}
fn large_outline_fixture(
path: &str,
function_count: u32,
line_count: u32,
) -> (String, IndexedFile) {
let mut content = String::new();
let mut symbols = Vec::new();
let module_start = content.len() as u32;
content.push_str("mod large {\n");
for i in 0..function_count {
let start = content.len() as u32;
content.push_str(&format!(" fn function_{i:03}() {{}}\n"));
let end = content.len() as u32;
symbols.push(make_symbol_with_depth(
&format!("function_{i:03}"),
SymbolKind::Function,
1,
i + 1,
i + 1,
(start, end),
));
}
content.push_str("}\n");
while content.lines().count() < line_count as usize {
content.push_str("// padding\n");
}
let module_end = content.len() as u32;
symbols.insert(
0,
make_symbol_with_depth(
"large",
SymbolKind::Module,
0,
0,
line_count.saturating_sub(1),
(module_start, module_end),
),
);
make_file(path, content.as_bytes(), symbols)
}
fn nested_test_module_fixture(path: &str, test_count: u32) -> (String, IndexedFile) {
let mut content = String::from("#[cfg(test)]\nmod tests {\n");
let mut symbols = vec![make_symbol_with_depth(
"tests",
SymbolKind::Module,
0,
1,
test_count + 2,
(0, 0),
)];
for i in 0..test_count {
let start = content.len() as u32;
content.push_str(&format!(" fn test_{i:03}() {{}}\n"));
let end = content.len() as u32;
symbols.push(make_symbol_with_depth(
&format!("test_{i:03}"),
SymbolKind::Function,
1,
i + 2,
i + 2,
(start, end),
));
}
content.push_str("}\n");
make_file(path, content.as_bytes(), symbols)
}
fn make_live_index_ready(files: Vec<(String, IndexedFile)>) -> LiveIndex {
use crate::live_index::trigram::TrigramIndex;
let files_map = files
.into_iter()
.map(|(path, file)| (path, std::sync::Arc::new(file)))
.collect::<HashMap<_, _>>();
let trigram_index = TrigramIndex::build_from_files(&files_map);
let mut index = LiveIndex {
files: files_map,
loaded_at: Instant::now(),
loaded_at_system: std::time::SystemTime::now(),
load_duration: Duration::from_millis(10),
cb_state: CircuitBreakerState::new(0.20),
is_empty: false,
load_source: crate::live_index::store::IndexLoadSource::FreshLoad,
snapshot_verify_state: crate::live_index::store::SnapshotVerifyState::NotNeeded,
reverse_index: HashMap::new(),
files_by_basename: HashMap::new(),
files_by_dir_component: HashMap::new(),
trigram_index,
gitignore: None,
manifest_entries: Vec::new(),
coupling_store: None,
local_empty_reason: std::sync::Arc::new(parking_lot::RwLock::new(None)),
indexed_root: None,
};
index.rebuild_reverse_index();
index.rebuild_path_indices();
index
}
/// Build a ready index that knows `path` only as a Tier-2 metadata-only skip
/// record (e.g. a dependency lockfile) — the path is NOT in `files`,
/// mirroring the post-admission state where lockfiles are demoted instead of
/// parsed. One real Tier-1 source file is also seeded so the index reports
/// `Ready` (an index with zero Tier-1 files reports `Empty`, matching a real
/// repo where source coexists with the lockfile). Used to exercise the honest
/// "not indexed" degradation responses in
/// get_file_context / get_symbol / get_file_content.
fn make_live_index_with_tier2_skip(
path: &str,
size: u64,
reason: crate::domain::index::SkipReason,
) -> LiveIndex {
let (anchor_key, anchor_file) = make_file(
"src/anchor.rs",
b"fn anchor() {}\n",
vec![make_symbol("anchor", SymbolKind::Function, 0, 0)],
);
let mut index = make_live_index_ready(vec![(anchor_key, anchor_file)]);
index.manifest_entries = vec![manifest_metadata_entry(path, size, reason)];
index
}
fn manifest_metadata_entry(
path: &str,
size: u64,
reason: crate::domain::index::SkipReason,
) -> crate::domain::CatalogEntry {
use crate::domain::index::SkipReason;
let reason = match reason {
SkipReason::DependencyLockfile => crate::domain::MetadataOnlyReason::Lockfile,
SkipReason::BinaryContent => crate::domain::MetadataOnlyReason::Binary,
SkipReason::SizeThreshold | SkipReason::SizeCeiling => {
crate::domain::MetadataOnlyReason::OversizedData
}
SkipReason::DenylistedExtension
| SkipReason::Untracked
| SkipReason::GeneratedOutput => crate::domain::MetadataOnlyReason::GeneratedOrVendor,
SkipReason::UnsupportedLanguage
| SkipReason::UnsupportedTextEncoding
| SkipReason::PolicyWithheld
| SkipReason::LfsPointer
| SkipReason::UnsupportedPath
| SkipReason::Unreadable => crate::domain::MetadataOnlyReason::UnsupportedTextEncoding,
};
crate::domain::CatalogEntry {
path: crate::domain::CatalogPath {
public_id: path.to_string(),
normalized_utf8: Some(path.to_string()),
},
size,
language: None,
classification: crate::domain::FileClassification {
class: crate::domain::FileClass::Text,
is_generated: false,
is_test: false,
is_vendor: false,
is_config: false,
},
disposition: crate::domain::FileDisposition::MetadataOnly { reason },
content_hash: None,
}
}
fn make_live_index_ready_with_coupling_store(
files: Vec<(String, IndexedFile)>,
store: crate::live_index::coupling::CouplingStore,
) -> LiveIndex {
let mut index = make_live_index_ready(files);
index.coupling_store = Some(Arc::new(store));
index
}
/// Build an index seeded with one src, one vendor, and one personal-tooling
/// file -- each containing the literal `noisy_token`. Used by Task 2.2 tests
/// to exercise the default-suppress / opt-in surfacing semantics in
/// `search_text` and `explore`.
fn make_live_index_ready_with_vendor_file() -> LiveIndex {
let content = b"// noisy_token marker for path-filter tests\n";
let sym = SymbolRecord {
name: "anchor".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (0, content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let (src_key, src_file) = make_file("src/normal.rs", content, vec![sym.clone()]);
let (vendor_key, vendor_file) = make_file("vendor/foo/bar.rs", content, vec![sym.clone()]);
let (personal_key, personal_file) =
make_file(".claude/gsd-local-patches/foo.rs", content, vec![sym]);
make_live_index_ready(vec![
(src_key, src_file),
(vendor_key, vendor_file),
(personal_key, personal_file),
])
}
fn make_live_index_empty() -> LiveIndex {
use crate::live_index::trigram::TrigramIndex;
LiveIndex {
files: HashMap::new(),
loaded_at: Instant::now(),
loaded_at_system: std::time::SystemTime::now(),
load_duration: Duration::ZERO,
cb_state: CircuitBreakerState::new(0.20),
is_empty: true,
load_source: crate::live_index::store::IndexLoadSource::EmptyBootstrap,
snapshot_verify_state: crate::live_index::store::SnapshotVerifyState::NotNeeded,
reverse_index: HashMap::new(),
files_by_basename: HashMap::new(),
files_by_dir_component: HashMap::new(),
trigram_index: TrigramIndex::new(),
gitignore: None,
manifest_entries: Vec::new(),
coupling_store: None,
local_empty_reason: std::sync::Arc::new(parking_lot::RwLock::new(None)),
indexed_root: None,
}
}
fn make_live_index_tripped() -> LiveIndex {
use crate::live_index::trigram::TrigramIndex;
let cb = CircuitBreakerState::new(0.10);
for _ in 0..8 {
cb.record_success();
}
for i in 0..2 {
cb.record_failure(&format!("f{i}.rs"), "err");
}
cb.should_abort(); // trips at 20% > 10%
LiveIndex {
files: HashMap::new(),
loaded_at: Instant::now(),
loaded_at_system: std::time::SystemTime::now(),
load_duration: Duration::ZERO,
cb_state: cb,
is_empty: false,
load_source: crate::live_index::store::IndexLoadSource::FreshLoad,
snapshot_verify_state: crate::live_index::store::SnapshotVerifyState::NotNeeded,
reverse_index: HashMap::new(),
files_by_basename: HashMap::new(),
files_by_dir_component: HashMap::new(),
trigram_index: TrigramIndex::new(),
gitignore: None,
manifest_entries: Vec::new(),
coupling_store: None,
local_empty_reason: std::sync::Arc::new(parking_lot::RwLock::new(None)),
indexed_root: None,
}
}
fn make_server_with_root(index: LiveIndex, repo_root: Option<PathBuf>) -> SymForgeServer {
use crate::watcher::WatcherInfo;
use parking_lot::Mutex;
let shared = crate::live_index::SharedIndexHandle::shared(index);
let watcher_info = Arc::new(Mutex::new(WatcherInfo::default()));
SymForgeServer::new(
shared,
"test_project".to_string(),
watcher_info,
repo_root,
None,
)
}
fn make_server(index: LiveIndex) -> SymForgeServer {
make_server_with_root(index, None)
}
/// Wait until background publications have quiesced.
///
/// `WatcherState::Active` is NOT a settled fixture. The fresh-instance
/// reconcile ends by spawning a fire-and-forget git-temporal computation
/// (the tail of `watcher::reconcile_for_cause_with`), and `Active` is set
/// immediately after that SPAWN — not after the task. The task then
/// publishes twice, `GitTemporalState::Computing` and then its result, via
/// `swap_and_publish_retaining_content`.
///
/// Every publication mints a fresh `PublishedIndexState` Arc while
/// deliberately leaving `project_generation` AND `content_generation`
/// untouched. So a publication landing mid-test breaks `Arc::ptr_eq` on the
/// published state, and makes the CAS in `read_and_index_with_stable_read`
/// lose its race (4 losses → `ReindexResult::Skipped`), with no generation
/// counter moving to hint at why. Both failure modes are invisible to the
/// generation asserts sitting right next to them.
///
/// Only reproducible under full-suite load: `#[tokio::test]` is a
/// current-thread runtime, so the git-temporal task is polled only while
/// the test awaits, and a saturated blocking pool stretches the git
/// subprocess into the assertion window.
///
/// Waiting for the terminal git-temporal state is the same condition
/// `spawn_git_temporal_computation` itself uses to skip redundant work.
async fn settle_background_publications(server: &SymForgeServer) {
use crate::live_index::git_temporal::GitTemporalState;
for _ in 0..250 {
if matches!(
server.index.published_generation().code_signals.state,
GitTemporalState::Ready | GitTemporalState::Unavailable(_)
) {
break;
}
tokio::time::sleep(Duration::from_millis(20)).await;
}
// The terminal state is published by the call that finishes the work,
// but confirm the published Arc has actually stopped moving — that also
// covers any publisher other than git temporal.
for _ in 0..50 {
let before = Arc::as_ptr(&server.index.published_state());
tokio::time::sleep(Duration::from_millis(20)).await;
if Arc::as_ptr(&server.index.published_state()) == before {
return;
}
}
panic!("background publications never quiesced");
}
fn project_state(root: &std::path::Path) -> crate::domain::ProjectStateDir {
crate::domain::ProjectStateDir::new(root.join(crate::paths::SYMFORGE_DIR_NAME))
}
fn serialized_tool_result<R: IntoCallToolResult>(result: R) -> serde_json::Value {
// INV-1/INV-5: the response enum stops at the trait boundary; this
// server emits Complete only, so the helper unwraps it (wildcard arm
// required — the enum is #[non_exhaustive]).
let result = match result.into_call_tool_result().unwrap() {
rmcp::model::CallToolResponse::Complete(result) => result,
other => panic!("server must emit Complete-only results, got {other:?}"),
};
serde_json::to_value(&result).unwrap()
}
fn assert_tool_result_status(serialized: &serde_json::Value, expected: OutcomeClass) {
assert_eq!(
serialized["_meta"][RESULT_STATUS_META_KEY]["contract_version"],
serde_json::json!(1),
"missing or wrong result-status contract version: {serialized}"
);
assert_eq!(
serialized["_meta"][RESULT_STATUS_META_KEY]["outcome_class"],
serde_json::json!(expected.as_str()),
"wrong result-status outcome: {serialized}"
);
}
fn assert_tool_result_edit_status(
serialized: &serde_json::Value,
expected_status: &str,
expected_outcome: OutcomeClass,
) {
assert_tool_result_status(serialized, expected_outcome);
assert_eq!(
serialized["_meta"][RESULT_STATUS_META_KEY]["status"],
serde_json::json!(expected_status),
"wrong edit result status: {serialized}"
);
}
fn tool_result_text(serialized: &serde_json::Value) -> &str {
serialized["content"][0]["text"]
.as_str()
.expect("tool result should contain one text content item")
}
fn get_file_content_input(path: &str) -> super::GetFileContentInput {
super::GetFileContentInput {
project: None,
path: path.to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}
}
fn get_symbol_input(path: &str, name: &str) -> super::GetSymbolInput {
super::GetSymbolInput {
project: None,
path: path.to_string(),
name: name.to_string(),
kind: None,
symbol_line: None,
targets: None,
estimate: None,
max_tokens: None,
force_refresh: None,
}
}
fn search_symbols_input(query: Option<&str>) -> super::SearchSymbolsInput {
super::SearchSymbolsInput {
query: query.map(str::to_string),
kind: None,
path_prefix: None,
language: None,
limit: None,
include_generated: None,
include_tests: None,
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}
}
fn search_files_input(query: &str) -> super::SearchFilesInput {
super::SearchFilesInput {
projects: None,
project: None,
query: query.to_string(),
limit: None,
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}
}
fn find_references_input(name: &str) -> super::FindReferencesInput {
super::FindReferencesInput {
name: name.to_string(),
kind: None,
path: None,
symbol_kind: None,
symbol_line: None,
limit: None,
max_per_file: None,
compact: None,
mode: None,
direction: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}
}
fn write_sidecar_state(
control_state_dir: &crate::domain::ControlStateDir,
port: Option<u16>,
pid: Option<&str>,
) {
let dir = crate::sidecar::port_file::ensure_symforge_dir(control_state_dir)
.expect("test control state should allow sidecar namespace creation");
if let Some(port) = port {
fs::write(dir.join("sidecar.port"), port.to_string())
.expect("sidecar port file should be writable");
}
if let Some(pid) = pid {
fs::write(dir.join("sidecar.pid"), pid).expect("sidecar pid file should be writable");
}
}
struct EnvVarGuard {
key: &'static str,
previous: Option<OsString>,
}
#[allow(unsafe_code)] // test-only env guard serializes process env mutation.
impl EnvVarGuard {
fn set(key: &'static str, value: &str) -> Self {
let previous = std::env::var_os(key);
// SAFETY: called only in single-threaded test context; no concurrent env readers.
unsafe {
std::env::set_var(key, value);
}
Self { key, previous }
}
fn remove(key: &'static str) -> Self {
let previous = std::env::var_os(key);
// SAFETY: called only in single-threaded test context; no concurrent env readers.
unsafe {
std::env::remove_var(key);
}
Self { key, previous }
}
fn set_path(key: &'static str, value: &Path) -> Self {
let previous = std::env::var_os(key);
// SAFETY: called only in single-threaded test context; no concurrent env readers.
unsafe {
std::env::set_var(key, value);
}
Self { key, previous }
}
}
#[allow(unsafe_code)] // test-only env guard restores serialized process env mutation.
impl Drop for EnvVarGuard {
fn drop(&mut self) {
match &self.previous {
// SAFETY: called only in single-threaded test context; no concurrent env readers.
Some(previous) => unsafe {
std::env::set_var(self.key, previous);
},
// SAFETY: called only in single-threaded test context; no concurrent env readers.
None => unsafe {
std::env::remove_var(self.key);
},
}
}
}
struct CwdGuard {
previous: PathBuf,
}
impl CwdGuard {
fn set(path: &Path) -> Self {
let previous = std::env::current_dir().expect("current dir");
std::env::set_current_dir(path).expect("set current dir");
Self { previous }
}
}
impl Drop for CwdGuard {
fn drop(&mut self) {
if std::env::set_current_dir(&self.previous).is_err() {
std::env::set_current_dir(env!("CARGO_MANIFEST_DIR")).expect("restore current dir");
}
}
}
fn run_git(repo_root: &Path, args: &[&str]) {
let output = crate::process_util::hidden_command("git")
.arg("-C")
.arg(repo_root)
.args(args)
.output()
.expect("git command should start");
assert!(
output.status.success(),
"git {:?} failed: {}",
args,
String::from_utf8_lossy(&output.stderr)
);
}
fn init_git_repo() -> TempDir {
let dir = TempDir::new().expect("temp git repo");
run_git(dir.path(), &["init", "-q"]);
run_git(
dir.path(),
&["config", "user.email", "symforge-tests@example.com"],
);
run_git(dir.path(), &["config", "user.name", "SymForge Tests"]);
dir
}
// ── Loading guard tests ───────────────────────────────────────────────────
#[tokio::test]
async fn test_loading_guard_empty_returns_empty_message() {
let server = make_server(make_live_index_empty());
// Any non-health tool should return the empty guard message
let result = server
.get_symbol(Parameters(super::GetSymbolInput {
project: None,
path: "anything.rs".to_string(),
name: "anything".to_string(),
kind: None,
symbol_line: None,
targets: None,
estimate: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(
result,
crate::protocol::format::empty_guard_message(),
"empty index should return empty guard message"
);
}
#[tokio::test]
async fn test_get_repo_map_outline_on_empty_index_returns_guard_message() {
// The outline (`detail="full"`) path must surface the empty-index
// guidance rather than a bare empty map. Regression for X4: previously
// only some branches guarded, so an outline-only call on an empty/
// unloaded index could fall through to an empty result.
let server = make_server(make_live_index_empty());
let result = server
.get_repo_map(Parameters(super::GetRepoMapInput {
project: None,
detail: Some("full".to_string()),
path: None,
depth: None,
max_files: None,
estimate: None,
max_tokens: None,
}))
.await;
assert_eq!(
result,
crate::protocol::format::empty_guard_message(),
"empty index get_repo_map(detail=full) must return the guard message, got: {result}"
);
// The `tree` outline branch must guard identically.
let tree_result = server
.get_repo_map(Parameters(super::GetRepoMapInput {
project: None,
detail: Some("tree".to_string()),
path: None,
depth: None,
max_files: None,
estimate: None,
max_tokens: None,
}))
.await;
assert_eq!(
tree_result,
crate::protocol::format::empty_guard_message(),
"empty index get_repo_map(detail=tree) must return the guard message, got: {tree_result}"
);
// And the default compact branch.
let compact_result = server
.get_repo_map(Parameters(super::GetRepoMapInput {
project: None,
detail: None,
path: None,
depth: None,
max_files: None,
estimate: None,
max_tokens: None,
}))
.await;
assert_eq!(
compact_result,
crate::protocol::format::empty_guard_message(),
"empty index get_repo_map(compact) must return the guard message, got: {compact_result}"
);
}
#[tokio::test]
async fn empty_guard_names_compact_recovery_when_connection_is_compact_over_full_env() {
// D23: the DAEMON's env is `full` but the proxied call is served on a
// `compact` connection. The empty-index guard the daemon renders and
// returns verbatim through the proxy MUST name only compact-callable
// recovery — NEVER `index_folder`, which the compact adapter's own gate
// would then refuse (the P0-1 unrecoverable loop this hint exists to
// prevent). Drives the REAL handler through the same
// `with_connection_surface` wrapper the daemon dispatch composes around
// `execute_tool_call`.
let _surface = EnvVarGuard::set("SYMFORGE_SURFACE", "full");
let server = make_server(make_live_index_empty());
let result = crate::protocol::surface_probe::with_connection_surface(
Some(crate::protocol::surface_probe::SurfaceProfile::Compact),
server.get_repo_map(Parameters(super::GetRepoMapInput {
project: None,
detail: Some("full".to_string()),
path: None,
depth: None,
max_files: None,
estimate: None,
max_tokens: None,
})),
)
.await;
assert_eq!(
result,
crate::protocol::format::empty_index_recovery_hint(
crate::protocol::surface_probe::SurfaceProfile::Compact
),
"compact connection must get the compact recovery hint, not the daemon env's:\n{result}"
);
assert!(
!result.contains("index_folder"),
"compact-connection guard must never name the gated index_folder:\n{result}"
);
}
#[tokio::test]
async fn empty_guard_names_index_folder_when_connection_is_full_over_compact_env() {
// Inverse skew: DAEMON env `compact`, connection `full`. `index_folder`
// IS callable on the full connection, so the guard MAY (and does) name it
// — proving the hint follows the CONNECTION surface, not the daemon env.
// Uses a `loading_guard!`-macro carrier (`get_symbol`).
let _surface = EnvVarGuard::set("SYMFORGE_SURFACE", "compact");
let server = make_server(make_live_index_empty());
let result = crate::protocol::surface_probe::with_connection_surface(
Some(crate::protocol::surface_probe::SurfaceProfile::Full),
server.get_symbol(Parameters(super::GetSymbolInput {
project: None,
path: "anything.rs".to_string(),
name: "anything".to_string(),
kind: None,
symbol_line: None,
targets: None,
estimate: None,
max_tokens: None,
force_refresh: None,
})),
)
.await;
assert_eq!(
result,
crate::protocol::format::empty_index_recovery_hint(
crate::protocol::surface_probe::SurfaceProfile::Full
),
"full connection must get the full recovery hint:\n{result}"
);
assert!(
result.contains("index_folder"),
"full-connection guard must name index_folder (callable there):\n{result}"
);
}
#[tokio::test]
async fn empty_guard_absent_connection_surface_falls_back_to_daemon_env() {
// Backward compat (old adapter sends no header -> None): the daemon
// renders from its own env, byte-identical to pre-D23 behavior.
let _surface = EnvVarGuard::set("SYMFORGE_SURFACE", "full");
let server = make_server(make_live_index_empty());
let result = crate::protocol::surface_probe::with_connection_surface(
None,
server.get_symbol(Parameters(super::GetSymbolInput {
project: None,
path: "anything.rs".to_string(),
name: "anything".to_string(),
kind: None,
symbol_line: None,
targets: None,
estimate: None,
max_tokens: None,
force_refresh: None,
})),
)
.await;
assert_eq!(
result,
crate::protocol::format::empty_guard_message(),
"absent connection surface must fall back to the env-based guard:\n{result}"
);
assert!(
result.contains("index_folder"),
"full daemon env with no connection override still names index_folder:\n{result}"
);
}
#[tokio::test]
async fn test_loading_guard_circuit_breaker_returns_degraded_message() {
let server = make_server(make_live_index_tripped());
let result = server
.get_symbol(Parameters(super::GetSymbolInput {
project: None,
path: "anything.rs".to_string(),
name: "anything".to_string(),
kind: None,
symbol_line: None,
targets: None,
estimate: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert!(
result.starts_with("Index degraded:"),
"tripped CB should return degraded message, got: {result}"
);
}
#[tokio::test]
async fn test_health_always_responds_on_empty_index() {
let server = make_server(make_live_index_empty());
let result = server
.health(Parameters(super::HealthInput::default()))
.await;
// Health should NOT return the guard message; it should return actual health info
assert!(
!result.starts_with("Index not loaded"),
"health should always respond, got: {result}"
);
assert!(
result.contains("Status: Empty"),
"health of empty index should show Empty, got: {result}"
);
}
// ── Tool handler tests ────────────────────────────────────────────────────
#[tokio::test]
async fn test_get_file_context_outline_only_contains_path_and_symbol() {
let sym = make_symbol("main", SymbolKind::Function, 1, 5);
let content = medium_test_source("fn main() {}");
let (key, file) = make_file("src/main.rs", &content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_context(Parameters(super::GetFileContextInput {
project: None,
path: "src/main.rs".to_string(),
max_tokens: None,
force_refresh: None,
sections: Some(vec!["outline".to_string()]),
estimate: None,
}))
.await;
assert!(result.contains("src/main.rs"), "should contain path");
assert!(result.contains("main"), "should contain symbol name");
// B5 (2026-07-03 spike gate): success paths carry no always-on tip.
assert!(
!result.contains("Tip:"),
"success path must not carry a tip"
);
}
#[tokio::test]
async fn test_get_symbol_delegates_to_formatter() {
let sym = make_symbol("foo", SymbolKind::Function, 1, 3);
let content = medium_test_source("fn foo() {}");
let (key, file) = make_file("src/lib.rs", &content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_symbol(Parameters(super::GetSymbolInput {
project: None,
path: "src/lib.rs".to_string(),
name: "foo".to_string(),
kind: None,
symbol_line: None,
targets: None,
estimate: None,
max_tokens: None,
force_refresh: None,
}))
.await;
// Should return source body or not-found message — not a guard message
assert!(
!result.starts_with("Index"),
"should not return guard message, got: {result}"
);
// B5 (2026-07-03 spike gate): success paths carry no always-on tip.
assert!(
!result.contains("Tip:"),
"success path must not carry a tip: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_bare_name_echoes_resolved_path() {
// Dogfood #2 (2026-07-06): a bare-name lookup must SAY which file it
// resolved to — the caller cannot tell a same-named TypeScript alias from
// a Rust struct by the body alone.
let sym = make_symbol("foo", SymbolKind::Function, 1, 3);
let content = medium_test_source("fn foo() {}");
let (key, file) = make_file("src/lib.rs", &content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_symbol(Parameters(super::GetSymbolInput {
project: None,
path: String::new(),
name: "foo".to_string(),
kind: None,
symbol_line: None,
targets: None,
estimate: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert!(
result.contains("Resolved bare name to src/lib.rs"),
"bare-name resolution must echo the picked path; got: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_missing_symbol_returns_loud_not_found() {
// D18: a symbol absent from the file must yield a LOUD not-found that
// names the symbol + path — NOT a silent content-anchored window.
//
// Non-vacuity: the source deliberately contains "TotallyFake" as a
// substring (in a comment). On the pre-fix code, content_anchored_symbol_window
// would find that substring and return a numbered source window tagged
// "content-anchored ...". This test asserts the window is gone, so it
// FAILS against the old behavior.
let sym = make_symbol("foo", SymbolKind::Function, 1, 3);
let content = medium_test_source("// TotallyFake is only in a comment\nfn foo() {}");
let (key, file) = make_file("src/lib.rs", &content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_symbol(Parameters(get_symbol_input("src/lib.rs", "TotallyFake")))
.await;
assert!(
result.contains("No symbol TotallyFake in src/lib.rs"),
"must name the missing symbol and path; got: {result}"
);
assert!(
!result.contains("content-anchored"),
"must NOT silently return a content-anchored window; got: {result}"
);
// Distinct from the file-not-found message: the file IS indexed.
assert!(
!result.starts_with("File not found"),
"indexed file with absent symbol must not read as file-not-found; got: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_missing_file_returns_not_found_file() {
// D18 boundary: an unindexed/absent file must report file-not-found,
// distinct from the symbol-absent message above.
let sym = make_symbol("foo", SymbolKind::Function, 1, 3);
let content = medium_test_source("fn foo() {}");
let (key, file) = make_file("src/lib.rs", &content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_symbol(Parameters(get_symbol_input("src/nonexistent.rs", "foo")))
.await;
assert!(
result.starts_with("File not found"),
"absent file must report file-not-found; got: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_valid_symbol_still_resolves() {
// D18 no-regression: a real symbol must still return its body, never a
// false not-found.
let sym = make_symbol("foo", SymbolKind::Function, 1, 3);
let content = medium_test_source("fn foo() {}");
let (key, file) = make_file("src/lib.rs", &content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_symbol(Parameters(get_symbol_input("src/lib.rs", "foo")))
.await;
assert!(
!result.contains("No symbol"),
"valid symbol must not read as not-found; got: {result}"
);
assert!(
result.contains("fn foo"),
"valid symbol must return its body; got: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_name_only_unique_resolves_path() {
// Fix 2: a `name` with no `path` resolves via an exact index search and
// returns the body — never `File not found: .`.
let sym = make_symbol("core", SymbolKind::Function, 1, 3);
let content = medium_test_source("fn core() {}");
let (key, file) = make_file("src/lib.rs", &content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_symbol(Parameters(get_symbol_input("", "core")))
.await;
assert!(
result.contains("fn core"),
"name-only lookup must resolve and return the body; got: {result}"
);
assert!(
!result.contains("File not found"),
"name-only lookup must not report file-not-found; got: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_name_only_ambiguous_lists_candidates() {
// Fix 2: a name matching symbols in multiple files returns a
// disambiguation listing naming path + line + kind, not one arbitrary hit.
let sym_a = make_symbol("handle", SymbolKind::Function, 1, 3);
let sym_b = make_symbol("handle", SymbolKind::Function, 5, 7);
let content = medium_test_source("fn handle() {}");
let (key_a, file_a) = make_file("src/a.rs", &content, vec![sym_a]);
let (key_b, file_b) = make_file("src/b.rs", &content, vec![sym_b]);
let server = make_server(make_live_index_ready(vec![
(key_a, file_a),
(key_b, file_b),
]));
let result = server
.get_symbol(Parameters(get_symbol_input("", "handle")))
.await;
assert!(
result.contains("Ambiguous symbol selector"),
"multiple matches must return a disambiguation listing; got: {result}"
);
assert!(
result.contains("src/a.rs") && result.contains("src/b.rs"),
"disambiguation must list every candidate path; got: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_name_only_missing_is_loud_not_found() {
// Fix 2: a name absent from the index yields a loud not-found that names
// the symbol and points at search_symbols — not `File not found: .`.
let sym = make_symbol("core", SymbolKind::Function, 1, 3);
let content = medium_test_source("fn core() {}");
let (key, file) = make_file("src/lib.rs", &content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_symbol(Parameters(get_symbol_input("", "Nonexistent")))
.await;
assert!(
result.contains("No symbol named `Nonexistent`"),
"missing name must be a loud not-found; got: {result}"
);
assert!(
result.contains("search_symbols"),
"missing name must suggest search_symbols for fuzzy lookup; got: {result}"
);
assert!(
!result.contains("File not found"),
"missing name must not read as file-not-found; got: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_name_only_kind_mismatch_names_actual_kinds() {
// Fix 1: a `name` that exists only under OTHER kinds must not read as a
// hard "No symbol named X" (factually false); it must name the kinds the
// symbol DOES have so the caller can drop or correct the `kind` filter.
let sym = make_symbol("core", SymbolKind::Function, 1, 3);
let content = medium_test_source("fn core() {}");
let (key, file) = make_file("src/lib.rs", &content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let mut input = get_symbol_input("", "core");
input.kind = Some("struct".to_string());
let result = server.get_symbol(Parameters(input)).await;
assert!(
result.contains("`core` exists in the index, but not as kind=struct"),
"kind mismatch must not claim the name is absent; got: {result}"
);
assert!(
result.contains("found: fn"),
"kind mismatch must name the kinds the symbol does have; got: {result}"
);
assert!(
!result.contains("No symbol named"),
"kind mismatch must not degrade to a hard not-found; got: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_all_empty_is_clean_invalid_request() {
// Fix 2: neither path nor name (nor targets) must yield a clean
// invalid-request naming what is required — never `File not found: .`.
let sym = make_symbol("core", SymbolKind::Function, 1, 3);
let content = medium_test_source("fn core() {}");
let (key, file) = make_file("src/lib.rs", &content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_symbol(Parameters(get_symbol_input("", "")))
.await;
assert!(
result.contains("Invalid request") && result.contains("name"),
"all-empty input must name what is required; got: {result}"
);
assert!(
!result.contains("File not found"),
"all-empty input must not degrade to `File not found: .`; got: {result}"
);
}
#[tokio::test]
async fn test_get_repo_map_full_uses_project_name() {
let (key, file) = make_file("src/main.rs", b"fn main() {}", vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_repo_map(Parameters(super::GetRepoMapInput {
project: None,
detail: Some("full".to_string()),
path: None,
depth: None,
max_files: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("test_project"),
"repo outline should use project_name, got: {result}"
);
}
#[tokio::test]
async fn test_get_repo_map_full_loading_guard_empty() {
let server = make_server(make_live_index_empty());
let result = server
.get_repo_map(Parameters(super::GetRepoMapInput {
project: None,
detail: Some("full".to_string()),
path: None,
depth: None,
max_files: None,
estimate: None,
max_tokens: None,
}))
.await;
assert_eq!(result, crate::protocol::format::empty_guard_message());
}
#[tokio::test]
async fn test_get_repo_map_full_proxies_to_daemon_session() {
let daemon_home = TempDir::new().expect("daemon home");
let _env_guard = EnvVarGuard::set_path("SYMFORGE_HOME", daemon_home.path());
// The daemon is fail-closed; pin a token so the direct open call and the
// proxy client (which resolves the token via env) can authenticate.
// Assembled at runtime so no credential-shaped literal enters this file;
// see `repository_source_is_clean_under_its_own_detector`. The prefix
// is hoisted off the token-bound line: the v3 detector follows the
// capture into inline arrays.
let pfx = "repo-map-proxy-test-";
let auth_token = [pfx, "to", "ken"].concat();
let _auth_guard = EnvVarGuard::set("SYMFORGE_DAEMON_AUTH_TOKEN", &auth_token);
let project = TempDir::new().expect("project dir");
fs::create_dir_all(project.path().join("src")).expect("src dir");
fs::write(project.path().join("src").join("main.rs"), "fn main() {}\n")
.expect("write source");
let handle = crate::daemon::spawn_daemon("127.0.0.1")
.await
.expect("spawn daemon");
let base_url = format!("http://127.0.0.1:{}", handle.port);
let opened = reqwest::Client::new()
.post(format!("{base_url}/v1/sessions/open"))
.bearer_auth(&auth_token)
.json(&crate::daemon::OpenProjectRequest {
project_root: project.path().display().to_string(),
client_name: "codex".to_string(),
pid: Some(1234),
})
.send()
.await
.expect("open request")
.error_for_status()
.expect("open status")
.json::<crate::daemon::OpenProjectResponse>()
.await
.expect("open body");
let daemon_client = crate::daemon::DaemonSessionClient::new_for_test(
base_url,
opened.project_id,
opened.session_id,
opened.project_name,
);
let server = SymForgeServer::new_daemon_proxy(daemon_client);
let result = server
.get_repo_map(Parameters(super::GetRepoMapInput {
project: None,
detail: Some("full".to_string()),
path: None,
depth: None,
max_files: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("main.rs"),
"remote repo outline should come from daemon project instance, got: {result}"
);
let _ = handle.shutdown_tx.send(());
}
/// Review finding 2 (post-v7.19.0): when a daemon is CONFIGURED but
/// unreachable, `checkpoint_now` falls back to checkpointing the locally
/// reloaded index — and its receipt must say so, because the snapshot it
/// writes can lag the daemon's authoritative live index. A client pointed
/// at a dead port (with no stored project root, so `reconnect` cannot
/// rediscover a real daemon) forces exactly that fallback path.
#[tokio::test]
async fn test_checkpoint_now_degraded_fallback_receipt_names_local_index() {
let daemon_client = crate::daemon::DaemonSessionClient::new_for_test(
// Port 1 is never serving; connection fails fast.
"http://127.0.0.1:1".to_string(),
"project-id".to_string(),
"session-id".to_string(),
"project-name".to_string(),
);
let server = SymForgeServer::new_daemon_proxy(daemon_client);
let dir = tempfile::tempdir().expect("create temp repo root");
let binding = match crate::discovery::resolve_root_candidate(
dir.path(),
crate::domain::RootCandidateSource::LaunchCwd,
crate::domain::RootRequestMode::Automatic,
) {
crate::domain::RootResolution::Bound(binding) => binding,
resolution => panic!("fixture root should bind: {resolution:?}"),
};
let placement = crate::discovery::resolve_state_placement(&binding);
server.set_bound_project_state(Some(binding.canonical_root), Some(placement));
let output = server
.checkpoint_now(Parameters(super::CheckpointNowInput {
verify_after_write: Some(true),
export_artifact: None,
}))
.await;
assert!(
output.contains("Checkpoint complete"),
"local fallback should still checkpoint successfully, got: {output}"
);
assert!(
output.contains("daemon unreachable"),
"degraded-fallback receipt must disclose the daemon was unreachable, got: {output}"
);
assert!(
output.contains("locally reloaded index"),
"degraded-fallback receipt must name WHAT was checkpointed, got: {output}"
);
}
/// M-007: with persistence unavailable (a bound repo root but memory-only — no
/// resolved state placement), `checkpoint_now` returns a SUCCESSFUL typed result
/// carrying `persistence_unavailable` + `applied=false` — a normal tool result,
/// never an `Err`/MCP protocol error. The `-> String` return type makes the
/// "not a protocol error" guarantee structural: the handler has no error path,
/// so this pins the unavailable ENVELOPE the memory-only branch must emit.
#[tokio::test]
async fn test_checkpoint_now_memory_only_is_typed_persistence_unavailable_not_error() {
let server = make_server(make_live_index_empty());
let dir = tempfile::tempdir().expect("create temp repo root");
// Bind a real root but NO state placement -> memory-only persistence.
server.set_bound_project_state(Some(dir.path().to_path_buf()), None);
let output = server
.checkpoint_now(Parameters(super::CheckpointNowInput {
verify_after_write: None,
export_artifact: None,
}))
.await;
assert!(
output.contains("persistence_unavailable"),
"memory-only checkpoint must carry the typed persistence_unavailable reason, got: {output}"
);
assert!(
output.contains("applied=false"),
"memory-only checkpoint must report applied=false, got: {output}"
);
assert!(
!output.contains("Checkpoint failed"),
"memory-only unavailability is a successful typed result, not a hard failure, got: {output}"
);
}
#[tokio::test]
async fn test_get_repo_map_returns_directory_breakdown() {
let sym = make_symbol("main", SymbolKind::Function, 1, 3);
let (key, file) = make_file("src/main.rs", b"fn main() {}", vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_repo_map(Parameters(super::GetRepoMapInput {
project: None,
detail: None,
path: None,
depth: None,
max_files: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("Index: 1 files, 1 symbols"),
"repo map should include totals header; got: {result}"
);
assert!(
result.contains("src"),
"repo map should include directory breakdown; got: {result}"
);
// B5 (2026-07-03 spike gate): success paths carry no always-on tip.
assert!(
!result.contains("Tip:"),
"repo map success path must not carry a tip"
);
}
#[tokio::test]
async fn test_get_file_context_returns_outline_and_key_references() {
let callee = make_symbol("target", SymbolKind::Function, 1, 3);
let caller = make_symbol("caller", SymbolKind::Function, 1, 3);
let target_content = medium_test_source("pub fn target() {}");
let caller_content = medium_test_source("use crate::target;\nfn caller() { target(); }");
let target_file = make_file("src/target.rs", &target_content, vec![callee]);
let caller_file = make_file_with_refs(
"src/caller.rs",
&caller_content,
vec![caller],
vec![
ReferenceRecord {
name: "target".to_string(),
qualified_name: Some("crate::target".to_string()),
kind: ReferenceKind::Import,
byte_range: (4, 10),
line_range: (0, 0),
enclosing_symbol_index: None,
},
ReferenceRecord {
name: "target".to_string(),
qualified_name: None,
kind: ReferenceKind::Call,
byte_range: (30, 36),
line_range: (1, 1),
enclosing_symbol_index: Some(0),
},
],
);
let server = make_server(make_live_index_ready(vec![target_file, caller_file]));
let result = server
.get_file_context(Parameters(super::GetFileContextInput {
project: None,
path: "src/target.rs".to_string(),
max_tokens: None,
force_refresh: None,
sections: None,
estimate: None,
}))
.await;
assert!(
result.contains("src/target.rs"),
"file context should include file header; got: {result}"
);
assert!(
result.contains("Key references"),
"file context should include reference section; got: {result}"
);
assert!(
result.contains("Scope: path `src/target.rs`; all sections"),
"file context should surface scope; got: {result}"
);
assert!(
result.contains("src/caller.rs"),
"file context should include caller file; got: {result}"
);
}
#[tokio::test]
async fn test_get_file_context_large_default_uses_bounded_summary() {
let mut content = String::new();
let mut symbols = Vec::new();
for i in 0..320u32 {
let name = format!("symbol_{i:03}");
content.push_str(&format!("pub fn {name}() {{}}\n"));
symbols.push(make_symbol(&name, SymbolKind::Function, i, i));
}
let target_file = make_file("src/target.rs", content.as_bytes(), symbols);
let caller_file = make_file_with_refs(
"src/caller.rs",
b"use crate::target::symbol_000;\nfn caller() { symbol_000(); }",
vec![make_symbol("caller", SymbolKind::Function, 1, 1)],
vec![
ReferenceRecord {
name: "symbol_000".to_string(),
qualified_name: Some("crate::target::symbol_000".to_string()),
kind: ReferenceKind::Import,
byte_range: (4, 14),
line_range: (0, 0),
enclosing_symbol_index: None,
},
ReferenceRecord {
name: "symbol_000".to_string(),
qualified_name: None,
kind: ReferenceKind::Call,
byte_range: (43, 53),
line_range: (1, 1),
enclosing_symbol_index: Some(0),
},
],
);
let server = make_server(make_live_index_ready(vec![target_file, caller_file]));
let result = server
.get_file_context(Parameters(super::GetFileContextInput {
project: None,
path: "src/target.rs".to_string(),
max_tokens: None,
force_refresh: None,
sections: None,
estimate: None,
}))
.await;
assert!(
result.contains("Large file summary"),
"large default should declare summary mode: {result}"
);
assert!(
result.contains("sections outline, imports"),
"large default should limit expensive sections: {result}"
);
assert!(
result.contains("omitted") || result.contains("Omitted"),
"large summary should explain omitted detail: {result}"
);
assert!(
!result.contains("Used by") && !result.contains("Key references"),
"large default should skip expensive dependent/reference sections: {result}"
);
}
/// Dogfood 2026-07-11: the sidecar stamps the trust envelope (including
/// `Completeness: full`) BEFORE `get_file_context` runs its own
/// post-assembly `enforce_token_budget` pass over envelope+body+footer
/// with the same byte cap — so a body that just fit the sidecar's budget
/// was tail-truncated while the envelope still claimed `full`. Sweep
/// `max_tokens` across the assembly boundary and assert the claim is
/// downgraded whenever the final output was actually cut.
#[tokio::test]
async fn test_get_file_context_never_claims_full_after_post_assembly_truncation() {
let mut content = String::new();
let mut symbols = Vec::new();
// Few symbols on purpose: the outline symbol cap (min clamp 25) never
// fires, so the sidecar body legitimately reaches `full` right where
// the envelope+footer overhead pushes the ASSEMBLED output past the
// same byte cap — the exact dishonesty window.
for i in 0..8u32 {
let name = format!("symbol_{i:03}");
content.push_str(&format!("pub fn {name}() {{}}\n"));
symbols.push(make_symbol(&name, SymbolKind::Function, i, i));
}
let target_file = make_file("src/target.rs", content.as_bytes(), symbols);
let server = make_server(make_live_index_ready(vec![target_file]));
for max_tokens in (40u64..=400).step_by(2) {
let result = server
.get_file_context(Parameters(super::GetFileContextInput {
project: None,
path: "src/target.rs".to_string(),
max_tokens: Some(max_tokens),
force_refresh: Some(true), // bypass the repeat-read cache
sections: Some(vec!["outline".to_string()]),
estimate: None,
}))
.await;
let truncated_after_assembly = result.contains("Original output is ~");
let claims_full = result
.lines()
.take(6)
.any(|line| line.contains("| full") || line.contains("Completeness: full"));
assert!(
!(truncated_after_assembly && claims_full),
"max_tokens={max_tokens}: envelope claims full but the assembled output \
was truncated after stamping:\n{result}"
);
}
}
#[tokio::test]
async fn test_get_file_context_shows_parse_diagnostic_for_partial_file() {
let content = medium_test_source_with_prefix(
"[package]\nname = \"symforge\"\ninvalid = \"unterminated\n",
"# ",
);
let (key, mut file) = make_file(
"Cargo.toml",
&content,
vec![make_symbol("package", SymbolKind::Key, 1, 1)],
);
let diagnostic = crate::domain::ParseDiagnostic {
parser: "toml_edit".to_string(),
message: "missing closing quote".to_string(),
line: Some(3),
column: Some(11),
byte_span: Some((28, 41)),
fallback_used: true,
};
file.language = LanguageId::Toml;
file.parse_status = ParseStatus::PartialParse {
warning: diagnostic.summary(),
};
file.parse_diagnostic = Some(diagnostic);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_context(Parameters(super::GetFileContextInput {
project: None,
path: "Cargo.toml".to_string(),
max_tokens: Some(2000),
sections: Some(vec!["outline".to_string()]),
estimate: None,
force_refresh: None,
}))
.await;
assert!(
result.contains("Parse status: partial"),
"file context should surface parse status; got: {result}"
);
assert!(
result.contains("Diagnostic: toml_edit: missing closing quote (line 3, column 11) [fallback symbol extraction used]"),
"file context should include the structured diagnostic; got: {result}"
);
assert!(
result.contains("Byte span: 28..41"),
"file context should include the diagnostic byte span; got: {result}"
);
}
/// Build a repo with one clean-parsing file on disk, plus an index entry for
/// that same path carrying a DELIBERATELY WRONG `parse_status: Failed`.
///
/// The wrongness is the instrument: it is the only way to observe WHICH lane
/// answered `validate_file_syntax`. `mtime_secs` is pinned to the real disk
/// mtime so the handler's own freshen (`freshen_file_if_stale` compares
/// exactly that) reports Fresh and leaves the planted
/// entry alone — otherwise the freshen would silently repair it and the test
/// would pass under either lane.
fn repo_with_disagreeing_index_entry(
load_source: crate::live_index::store::IndexLoadSource,
) -> (TempDir, SymForgeServer) {
let repo = TempDir::new().expect("temp repo");
let src = repo.path().join("src");
fs::create_dir_all(&src).expect("create src");
let file_path = src.join("clean.rs");
fs::write(&file_path, b"pub fn clean() {}\n").expect("write clean rust");
let disk_mtime = fs::metadata(&file_path)
.and_then(|m| m.modified())
.ok()
.and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
.map(|d| d.as_secs())
.expect("disk mtime");
let (key, mut file) = make_file("src/clean.rs", b"pub fn clean() {}\n", vec![]);
file.parse_status = ParseStatus::Failed {
error: "planted disagreement: the index says this file does not parse".to_string(),
};
file.mtime_secs = disk_mtime;
let mut index = make_live_index_ready(vec![(key, file)]);
index.load_source = load_source;
let server = make_server_with_root(index, Some(repo.path().to_path_buf()));
(repo, server)
}
/// The guard-sweep hole: `validate_file_syntax` freshens and then rendered
/// from the index with NO readiness gate, so it was the one read tool that
/// still answered off an index every other tool had just refused.
///
/// A blanket `loading_guard!` would be the wrong fix — it would kill this
/// tool's documented ability to validate a config file from disk during a
/// cold start. The right fix is to distrust the INDEXED entry while not
/// Ready and answer from the authoritative disk parse.
#[tokio::test]
async fn validate_file_syntax_answers_from_disk_when_the_index_is_not_ready() {
let (_repo, server) = repo_with_disagreeing_index_entry(
crate::live_index::store::IndexLoadSource::EmptyBootstrap,
);
let result = server
.validate_file_syntax(Parameters(super::ValidateFileSyntaxInput {
project: None,
path: "src/clean.rs".to_string(),
}))
.await;
assert!(
!result.contains("Status: failed"),
"a not-Ready index must not be trusted for the parse verdict; the disk parse \
is authoritative here. got: {result}"
);
assert!(
result.contains("Status: ok"),
"the disk fallback must still answer (NOT refuse) — this tool validates \
config files during a cold start by design. got: {result}"
);
}
/// Control for the test above: on a Ready index the indexed entry is still
/// authoritative, so the planted verdict comes back. Without this, the fix
/// could silently have made the tool ignore the index entirely.
#[tokio::test]
async fn validate_file_syntax_still_trusts_the_index_when_ready() {
let (_repo, server) =
repo_with_disagreeing_index_entry(crate::live_index::store::IndexLoadSource::FreshLoad);
let result = server
.validate_file_syntax(Parameters(super::ValidateFileSyntaxInput {
project: None,
path: "src/clean.rs".to_string(),
}))
.await;
assert!(
result.contains("Status: failed"),
"a Ready index stays authoritative; the indexed lane must be unchanged. got: {result}"
);
}
#[tokio::test]
async fn test_validate_file_syntax_reports_partial_toml_diagnostics() {
let repo = TempDir::new().expect("temp repo");
fs::write(
repo.path().join("Cargo.toml"),
"[package]\nname = \"symforge\"\nversion = \"0.1.0\"\ninvalid = \"unterminated\n",
)
.expect("write malformed toml");
let server =
make_server_with_root(make_live_index_empty(), Some(repo.path().to_path_buf()));
let result = server
.validate_file_syntax(Parameters(super::ValidateFileSyntaxInput {
project: None,
path: "Cargo.toml".to_string(),
}))
.await;
assert!(
result.contains("Status: partial"),
"validator should report a partial parse when fallback extraction succeeds; got: {result}"
);
assert!(
result.contains("Diagnostic: toml_edit:"),
"validator should show the parser source; got: {result}"
);
assert!(
result.contains("fallback symbol extraction used"),
"validator should surface fallback usage; got: {result}"
);
assert!(
!result.contains("Symbols extracted: 0"),
"validator should report recovered symbols for malformed TOML; got: {result}"
);
}
#[tokio::test]
async fn test_get_file_content_outside_root_returns_explicit_error() {
// L2: a path that escapes the repo root must yield an explicit
// "outside the repository root" error, not a misleading generic
// "File not found". A normal in-repo path is unaffected.
let repo = TempDir::new().expect("temp repo");
fs::write(repo.path().join("real.txt"), b"hello world\n").expect("write in-repo file");
let server = make_server_with_root(
make_live_index_ready(vec![]),
Some(repo.path().to_path_buf()),
);
let escaped = server
.get_file_content(Parameters(get_file_content_input("../../../etc/passwd")))
.await;
assert!(
escaped.contains("outside the repository root"),
"traversal path must report a containment violation; got: {escaped}"
);
assert!(
!escaped.starts_with("File not found"),
"traversal path must NOT be reported as a generic miss; got: {escaped}"
);
// A genuine in-repo file (not in the index) still reads from disk fine.
let ok = server
.get_file_content(Parameters(get_file_content_input("real.txt")))
.await;
assert!(
ok.contains("hello world"),
"normal in-repo path must still be read; got: {ok}"
);
// A genuine in-repo but missing path still reports a normal not-found,
// NOT an outside-root error.
let missing = server
.get_file_content(Parameters(get_file_content_input("does_not_exist.txt")))
.await;
assert!(
!missing.contains("outside the repository root"),
"an in-repo missing file must not be misreported as outside-root; got: {missing}"
);
}
#[tokio::test]
async fn test_get_file_context_tier2_lockfile_returns_metadata_only_message() {
// A Tier-2 metadata-only path (e.g. package-lock.json) EXISTS but is
// deliberately not parsed. get_file_context must say so honestly and
// point at get_file_content, NOT report a misleading "File not found".
let index = make_live_index_with_tier2_skip(
"package-lock.json",
406 * 1024,
crate::domain::index::SkipReason::DependencyLockfile,
);
let server = make_server(index);
let result = server
.get_file_context(Parameters(super::GetFileContextInput {
project: None,
path: "package-lock.json".to_string(),
max_tokens: None,
force_refresh: None,
sections: None,
estimate: None,
}))
.await;
assert!(
result.contains("Not indexed: package-lock.json is Tier 2 (metadata only)"),
"Tier-2 path must report metadata-only status; got: {result}"
);
assert!(
result.contains("reason: lockfile"),
"message must name the skip reason; got: {result}"
);
assert!(
result.contains("get_file_content"),
"message must point at the raw-read escape hatch; got: {result}"
);
assert!(
!result.starts_with("File not found"),
"Tier-2 path must NOT be reported as a generic miss; got: {result}"
);
}
#[tokio::test]
async fn test_get_file_context_catalog_only_text_is_honest_not_found() {
// SF-004 + Feature 020: files without a semantic grammar (for example
// `.sh` and extensionless `LICENSE`) still belong to the resident file
// catalog as generic Text. get_file_context must report their truthful
// zero-symbol catalog context and knowledge evidence — NEVER a false
// "File not found", which an agent would read as "the file is absent".
let repo = tempfile::tempdir().unwrap();
std::fs::create_dir_all(repo.path().join("scripts")).unwrap();
std::fs::write(repo.path().join("scripts/setup.sh"), "#!/bin/sh\necho hi\n").unwrap();
std::fs::write(repo.path().join("LICENSE"), "MIT License\n").unwrap();
// The ready anchor index is rebound to the repository root on first use;
// Feature 020 discovery must admit the two generic-text files without
// inventing semantic symbols for them.
let (anchor_key, anchor_file) = make_file(
"src/anchor.rs",
b"fn anchor() {}\n",
vec![make_symbol("anchor", SymbolKind::Function, 0, 0)],
);
let server = make_server_with_root(
make_live_index_ready(vec![(anchor_key, anchor_file)]),
Some(repo.path().to_path_buf()),
);
for path in ["scripts/setup.sh", "LICENSE"] {
let result = server
.get_file_context(Parameters(super::GetFileContextInput {
project: None,
path: path.to_string(),
max_tokens: None,
force_refresh: None,
sections: None,
estimate: None,
}))
.await;
assert!(
!result.starts_with("File not found"),
"on-disk unsupported-language file `{path}` must NOT report a false \
not-found; got: {result}"
);
assert!(
result.contains("(0 symbols, Text)"),
"`{path}` must report honest zero-symbol Text catalog status; got: {result}"
);
assert!(
result.contains("Knowledge evidence:"),
"`{path}` must retain its repository-knowledge evidence; got: {result}"
);
}
// Control: a genuinely-absent path still reports the plain "File not
// found" — real and absent files remain distinguishable to an agent.
let absent = server
.get_file_context(Parameters(super::GetFileContextInput {
project: None,
path: "does/not/exist.tcl".to_string(),
max_tokens: None,
force_refresh: None,
sections: None,
estimate: None,
}))
.await;
assert!(
absent.starts_with("File not found"),
"a genuinely-absent path must still report File not found; got: {absent}"
);
}
#[tokio::test]
async fn test_get_file_content_indexed_nul_byte_appends_warning() {
// A source file with a NUL (0x00) mid-content (mirrors the mint.js case:
// valid for Node, smuggled into a template literal). It passes the
// first-8KB binary sniff and gets indexed, so get_file_content renders it.
// The NUL renders invisibly; the warning must make that explicit.
let content = b"const a = `x\0y`;\nfn anchor() {}\n";
let nul_offset = content.iter().position(|&b| b == 0).unwrap();
let sym = SymbolRecord {
name: "anchor".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (16, content.len() as u32),
line_range: (1, 1),
doc_byte_range: None,
item_byte_range: None,
};
let (key, file) = make_file("src/mint.js", content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let out = server
.get_file_content(Parameters(get_file_content_input("src/mint.js")))
.await;
assert!(
out.contains("WARNING: this file contains 1 NUL byte (0x00)"),
"NUL warning must be present; got: {out}"
);
assert!(
out.contains(&format!("byte offset(s) {nul_offset}")),
"warning must report the NUL byte offset {nul_offset}; got: {out}"
);
assert!(
out.contains("byte-exact tools"),
"warning must steer agents to byte-exact edits; got: {out}"
);
// Symbols are still extracted best-effort: get_file_content renders fine.
assert!(
out.contains("anchor"),
"content must still render; got: {out}"
);
}
#[tokio::test]
async fn test_get_symbol_tier2_lockfile_returns_metadata_only_message() {
// get_symbol on a Tier-2 metadata-only path has no symbols to return;
// it must degrade to the honest "not indexed" message rather than a
// bare "File not found" (which would imply the file is absent).
let index = make_live_index_with_tier2_skip(
"package-lock.json",
406 * 1024,
crate::domain::index::SkipReason::DependencyLockfile,
);
let server = make_server(index);
let result = server
.get_symbol(Parameters(get_symbol_input(
"package-lock.json",
"anything",
)))
.await;
assert!(
result.contains("Not indexed: package-lock.json is Tier 2 (metadata only)"),
"Tier-2 path must report metadata-only status; got: {result}"
);
assert!(
!result.starts_with("File not found"),
"Tier-2 path must NOT be reported as a generic miss; got: {result}"
);
}
#[tokio::test]
async fn test_get_file_content_no_nul_has_no_warning() {
// No false positives: a clean source file must not gain a NUL warning.
let content = b"const a = `xy`;\nfn anchor() {}\n";
let sym = SymbolRecord {
name: "anchor".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (15, content.len() as u32),
line_range: (1, 1),
doc_byte_range: None,
item_byte_range: None,
};
let (key, file) = make_file("src/clean.js", content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let out = server
.get_file_content(Parameters(get_file_content_input("src/clean.js")))
.await;
assert!(
!out.contains("NUL byte"),
"clean file must not gain a NUL warning; got: {out}"
);
}
#[tokio::test]
async fn test_get_file_content_tier2_lockfile_returns_raw_disk_content() {
// Chosen semantics: get_file_content is the documented escape hatch for
// Tier-2 files. Even though package-lock.json is metadata-only (not in
// the index), get_file_content must still serve its raw bytes from disk.
let repo = TempDir::new().expect("temp repo");
let lockfile_body = b"{\n \"name\": \"demo\",\n \"lockfileVersion\": 3\n}\n";
fs::write(repo.path().join("package-lock.json"), lockfile_body)
.expect("write lockfile to disk");
let index = make_live_index_with_tier2_skip(
"package-lock.json",
lockfile_body.len() as u64,
crate::domain::index::SkipReason::DependencyLockfile,
);
let server = make_server_with_root(index, Some(repo.path().to_path_buf()));
let result = server
.get_file_content(Parameters(get_file_content_input("package-lock.json")))
.await;
assert!(
result.contains("\"lockfileVersion\": 3"),
"get_file_content must serve Tier-2 file raw from disk; got: {result}"
);
assert!(
!result.starts_with("File not found"),
"Tier-2 escape hatch must not report a miss; got: {result}"
);
assert!(
!result.contains("Not indexed:"),
"get_file_content must read the file, not degrade to the Tier-2 notice; got: {result}"
);
}
#[tokio::test]
async fn test_get_file_content_raw_disk_fallback_nul_warning() {
// Raw-disk fallback branch (file not in index): the warning must also fire
// there, using the bytes read from disk.
let repo = TempDir::new().expect("temp repo");
let content = b"plain text\0with a nul\n";
let nul_offset = content.iter().position(|&b| b == 0).unwrap();
fs::write(repo.path().join("notes.txt"), content).expect("write nul file");
let server = make_server_with_root(
make_live_index_ready(vec![]),
Some(repo.path().to_path_buf()),
);
let out = server
.get_file_content(Parameters(get_file_content_input("notes.txt")))
.await;
assert!(
out.contains("WARNING: this file contains 1 NUL byte (0x00)"),
"raw-disk fallback must also warn on NUL; got: {out}"
);
assert!(
out.contains(&format!("byte offset(s) {nul_offset}")),
"raw-disk warning must report the NUL offset {nul_offset}; got: {out}"
);
}
#[tokio::test]
async fn test_get_file_context_genuinely_missing_path_still_not_found() {
// A path that is neither indexed nor a known skip nor present on disk
// must still report a plain "File not found", preserving the existing
// close-match suggestion behavior where applicable.
let server = make_server(make_live_index_ready(vec![]));
let result = server
.get_file_context(Parameters(super::GetFileContextInput {
project: None,
path: "totally/absent/file.rs".to_string(),
max_tokens: None,
force_refresh: None,
sections: None,
estimate: None,
}))
.await;
assert!(
result.starts_with("File not found"),
"genuinely missing path must report a plain not-found; got: {result}"
);
assert!(
!result.contains("Not indexed:"),
"absent path must not be misreported as a Tier-2 skip; got: {result}"
);
}
#[tokio::test]
async fn test_replace_symbol_body_preserves_nul_after_edited_symbol() {
// Byte-exactness guarantee: editing a symbol that sits BEFORE a NUL byte
// must leave the NUL intact on disk. The splice (apply_splice) copies the
// SUFFIX bytes (everything after the symbol, including the NUL) verbatim —
// it never re-renders the untouched file region. `target` is parsed from
// the clean prefix; the NUL lives in a later raw-string literal.
let original =
b"fn target() {\n let x = 1;\n}\n\nfn after() {\n let _b = \"lead\0tail\";\n}\n";
assert!(original.contains(&0u8), "fixture must contain a NUL");
let (_dir, server, file_path) = setup_edit_test_with_fresh_mtime(original);
let input = crate::protocol::edit::ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "target".to_string(),
kind: None,
symbol_line: None,
new_body: "fn target() {\n let x = 42;\n}".to_string(),
dry_run: None,
idempotency_key: None,
if_match: None,
working_directory: None,
};
let result = server.replace_symbol_body(Parameters(input)).await;
assert!(result.contains("replaced"), "result was: {result}");
// Read back RAW bytes: the NUL must still be present, embedded in the
// untouched suffix literal that apply_splice copied verbatim.
let on_disk = std::fs::read(&file_path).unwrap();
let on_disk_nul = on_disk
.iter()
.position(|&b| b == 0)
.expect("NUL byte must survive an edit to an earlier symbol");
assert_eq!(
&on_disk[on_disk_nul - 4..on_disk_nul],
b"lead",
"NUL must remain embedded in the untouched suffix literal"
);
assert!(
on_disk.windows(b"x = 42".len()).any(|w| w == b"x = 42"),
"new body must be written"
);
}
#[tokio::test]
async fn test_edit_within_symbol_preserves_nul_after_edited_symbol() {
// Same byte-exactness guarantee for edit_within_symbol.
let original =
b"fn target() {\n let x = 1;\n}\n\nfn after() {\n let _b = \"lead\0tail\";\n}\n";
let (_dir, server, file_path) = setup_edit_test_with_fresh_mtime(original);
let result = server
.edit_within_symbol(Parameters(crate::protocol::edit::EditWithinSymbolInput {
project: None,
path: "src/lib.rs".to_string(),
name: "target".to_string(),
kind: None,
symbol_line: None,
old_text: "let x = 1;".to_string(),
new_text: "let x = 7;".to_string(),
replace_all: false,
occurrence: None,
near_line: None,
dry_run: None,
idempotency_key: None,
working_directory: None,
}))
.await;
assert!(
result.contains("edited within `target`"),
"result was: {result}"
);
let on_disk = std::fs::read(&file_path).unwrap();
let on_disk_nul = on_disk
.iter()
.position(|&b| b == 0)
.expect("NUL must survive edit_within_symbol on an earlier symbol");
assert_eq!(
&on_disk[on_disk_nul - 4..on_disk_nul],
b"lead",
"NUL must remain embedded in the untouched suffix literal"
);
assert!(
on_disk
.windows(b"let x = 7;".len())
.any(|w| w == b"let x = 7;"),
"new text must be written"
);
}
#[tokio::test]
async fn test_validate_file_syntax_reports_deepest_nested_source_diagnostic() {
let repo = TempDir::new().expect("temp repo");
fs::write(
repo.path().join("broken.py"),
"def compute():\n value = outer(inner(1 + 2, tail)\n other = {'a': {'b': 1}}\n",
)
.expect("write malformed python");
let server =
make_server_with_root(make_live_index_empty(), Some(repo.path().to_path_buf()));
let result = server
.validate_file_syntax(Parameters(super::ValidateFileSyntaxInput {
project: None,
path: "broken.py".to_string(),
}))
.await;
assert!(
result.contains("Status: partial"),
"validator should report malformed source as a partial parse; got: {result}"
);
assert!(
result.contains(
"Diagnostic: tree-sitter: syntax error near `inner(1 + 2, tail)` (line 2, column 19)"
),
"validator should report the nested actionable syntax location; got: {result}"
);
assert!(
result.contains("Byte span: 33..51"),
"validator should report the nested diagnostic byte span; got: {result}"
);
}
#[tokio::test]
async fn test_validate_file_syntax_reports_deepest_missing_node_diagnostic() {
let repo = TempDir::new().expect("temp repo");
fs::write(
repo.path().join("broken.rs"),
"fn compute() {\n let value = outer(inner(1 + ), tail);\n}\n",
)
.expect("write malformed rust");
let server =
make_server_with_root(make_live_index_empty(), Some(repo.path().to_path_buf()));
let result = server
.validate_file_syntax(Parameters(super::ValidateFileSyntaxInput {
project: None,
path: "broken.rs".to_string(),
}))
.await;
assert!(
result.contains("Status: partial"),
"validator should report malformed source as a partial parse; got: {result}"
);
assert!(
result.contains("Diagnostic: tree-sitter: syntax missing identifier"),
"validator should report the missing node kind; got: {result}"
);
assert!(
result.contains("(line 2, column 32)"),
"validator should report the missing node location; got: {result}"
);
assert!(
result.contains("Byte span: 46..46"),
"validator should report the zero-width missing-node byte span; got: {result}"
);
assert!(
result.contains("), tail);"),
"validator should include source context after the missing node; got: {result}"
);
}
#[tokio::test]
async fn test_get_file_context_shows_imports_and_used_by_sections() {
let callee = make_symbol("target", SymbolKind::Function, 1, 3);
let caller = make_symbol("caller", SymbolKind::Function, 1, 3);
// caller.rs imports from crate::target and calls target().
let caller_content = medium_test_source("use crate::target;\nfn caller() { target(); }");
let caller_file = make_file_with_refs(
"src/caller.rs",
&caller_content,
vec![caller],
vec![
ReferenceRecord {
name: "target".to_string(),
qualified_name: Some("crate::target".to_string()),
kind: ReferenceKind::Import,
byte_range: (4, 10),
line_range: (0, 0),
enclosing_symbol_index: None,
},
ReferenceRecord {
name: "target".to_string(),
qualified_name: None,
kind: ReferenceKind::Call,
byte_range: (30, 36),
line_range: (1, 1),
enclosing_symbol_index: Some(0),
},
],
);
let target_content = medium_test_source("pub fn target() {}");
let target_file = make_file("src/target.rs", &target_content, vec![callee]);
let server = make_server(make_live_index_ready(vec![target_file, caller_file]));
// Check caller.rs — should have "Imports from" section.
let caller_result = server
.get_file_context(Parameters(super::GetFileContextInput {
project: None,
path: "src/caller.rs".to_string(),
max_tokens: Some(2000),
sections: None,
estimate: None,
force_refresh: None,
}))
.await;
assert!(
caller_result.contains("Imports from"),
"caller should show imports section; got: {caller_result}"
);
assert!(
caller_result.contains("crate::target"),
"caller should list crate::target as import source; got: {caller_result}"
);
// Check target.rs — should have "Used by" section.
let target_result = server
.get_file_context(Parameters(super::GetFileContextInput {
project: None,
path: "src/target.rs".to_string(),
max_tokens: Some(2000),
sections: None,
estimate: None,
force_refresh: None,
}))
.await;
assert!(
target_result.contains("Used by"),
"target should show used-by section; got: {target_result}"
);
assert!(
target_result.contains("src/caller.rs"),
"target should list caller.rs as consumer; got: {target_result}"
);
}
#[tokio::test]
async fn test_get_file_context_ignores_generic_name_noise_without_real_dependency() {
let target = make_symbol("main", SymbolKind::Function, 1, 3);
let helper = make_symbol("helper", SymbolKind::Function, 1, 4);
let helper_main = make_symbol("main", SymbolKind::Function, 5, 7);
let target_file = make_file("src/target.py", b"def main():\n pass\n", vec![target]);
let helper_file = make_file_with_refs(
"scripts/helper.py",
b"def helper():\n main()\n\ndef main():\n pass\n",
vec![helper, helper_main],
vec![ReferenceRecord {
name: "main".to_string(),
qualified_name: None,
kind: ReferenceKind::Call,
byte_range: (18, 22),
line_range: (1, 1),
enclosing_symbol_index: Some(0),
}],
);
let server = make_server(make_live_index_ready(vec![target_file, helper_file]));
let result = server
.get_file_context(Parameters(super::GetFileContextInput {
project: None,
path: "src/target.py".to_string(),
max_tokens: None,
force_refresh: None,
sections: None,
estimate: None,
}))
.await;
assert!(
!result.contains("scripts/helper.py"),
"generic-name local calls should not be attributed as key references: {result}"
);
}
mod get_file_context {
use super::*;
#[test]
fn include_tests_is_advertised_for_context_tools() {
for tool_name in ["get_file_context", "get_symbol_context"] {
let tools = SymForgeServer::tool_definitions();
let tool = tools
.iter()
.find(|tool| tool.name.as_ref() == tool_name)
.unwrap_or_else(|| panic!("{tool_name} should be registered"));
let properties = tool
.input_schema
.get("properties")
.and_then(serde_json::Value::as_object)
.unwrap_or_else(|| panic!("{tool_name} should expose schema properties"));
assert!(
properties.contains_key("include_tests"),
"{tool_name} should advertise include_tests in its input schema"
);
}
}
#[tokio::test]
async fn nested_test_module_collapsed_by_default() {
let file = nested_test_module_fixture("src/lib.rs", 125);
let server = make_server(make_live_index_ready(vec![file]));
let result = server
.get_file_context(Parameters(super::super::GetFileContextInput {
project: None,
path: "src/lib.rs".to_string(),
max_tokens: Some(2000),
sections: None,
estimate: None,
force_refresh: None,
}))
.await;
assert!(
result.contains("test module `tests` collapsed: 125 functions not shown"),
"large test module should collapse by default; got:\n{result}"
);
assert!(
!result.contains("test_124"),
"default outline should not enumerate every nested test function; got:\n{result}"
);
}
#[tokio::test]
async fn include_tests_true_restores_full_outline() {
let file = nested_test_module_fixture("src/lib.rs", 125);
let server = make_server(make_live_index_ready(vec![file]));
let input: super::super::GetFileContextInput =
serde_json::from_value(serde_json::json!({
"path": "src/lib.rs",
"max_tokens": 4000,
"include_tests": true
}))
.expect("include_tests input should deserialize");
let result = server.get_file_context(Parameters(input)).await;
assert!(
result.contains("test_124"),
"include_tests=true should show nested test functions; got:\n{result}"
);
assert!(
!result.contains("test module `tests` collapsed"),
"include_tests=true should not render collapse summary; got:\n{result}"
);
}
}
mod get_symbol_context {
use super::*;
#[tokio::test]
async fn large_file_respects_budget() {
let max_tokens = 600;
let file = large_outline_fixture("src/large.rs", 300, 16_000);
let server = make_server(make_live_index_ready(vec![file]));
let started = Instant::now();
let result = server
.get_symbol_context(Parameters(super::super::GetSymbolContextInput {
project: None,
name: "function_000".to_string(),
file: None,
path: Some("src/large.rs".to_string()),
symbol_kind: Some("fn".to_string()),
symbol_line: Some(2),
verbosity: None,
bundle: None,
sections: Some(vec![]),
max_tokens: Some(max_tokens),
estimate: None,
}))
.await;
let elapsed = started.elapsed();
eprintln!(
"large_file_respects_budget wall_ms={} bytes={} max_tokens={}",
elapsed.as_millis(),
result.len(),
max_tokens
);
assert!(
elapsed < Duration::from_secs(5),
"large-file context should complete under 5s; elapsed={elapsed:?}"
);
assert!(
result.len() <= (max_tokens as usize * 4 * 12) / 10,
"response should stay within +20% of token budget; bytes={}, max_tokens={}, output:\n{}",
result.len(),
max_tokens,
result
);
}
}
#[tokio::test]
async fn test_get_symbol_context_returns_grouped_references() {
let caller = make_symbol("caller", SymbolKind::Function, 1, 3);
let caller_file = make_file_with_refs(
"src/caller.rs",
b"fn caller() { target(); }",
vec![caller],
vec![ReferenceRecord {
name: "target".to_string(),
qualified_name: None,
kind: ReferenceKind::Call,
byte_range: (12, 18),
line_range: (1, 1),
enclosing_symbol_index: Some(0),
}],
);
let server = make_server(make_live_index_ready(vec![caller_file]));
let result = server
.get_symbol_context(Parameters(super::GetSymbolContextInput {
project: None,
name: "target".to_string(),
file: None,
path: None,
symbol_kind: None,
symbol_line: None,
verbosity: None,
bundle: None,
sections: None,
max_tokens: None,
estimate: None,
}))
.await;
assert!(
result.contains("src/caller.rs"),
"symbol context should group matches by file; got: {result}"
);
assert!(
result.contains("in fn caller"),
"symbol context should include enclosing symbol names; got: {result}"
);
assert!(
result.contains("Scope: repo-wide symbol token `target`"),
"default symbol context should surface repo-wide scope; got: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_context_reference_list_uses_actual_enclosing_kind() {
// Regression: reference entries used to render every enclosing symbol as
// "in fn <name>" regardless of kind, yielding nonsense like
// "in fn impl BucketManager". The enclosing kind must be honored, and an
// impl/struct whose stored name already carries the kind prefix must not
// double it.
let impl_sym = make_symbol("impl BucketManager", SymbolKind::Impl, 1, 5);
let caller_file = make_file_with_refs(
"src/bucket.rs",
b"impl BucketManager {\n fn f(&self) { target(); }\n}\n",
vec![impl_sym],
vec![ReferenceRecord {
name: "target".to_string(),
qualified_name: None,
kind: ReferenceKind::Call,
byte_range: (38, 44),
line_range: (1, 1),
enclosing_symbol_index: Some(0),
}],
);
let server = make_server(make_live_index_ready(vec![caller_file]));
let result = server
.get_symbol_context(Parameters(super::GetSymbolContextInput {
project: None,
name: "target".to_string(),
file: None,
path: None,
symbol_kind: None,
symbol_line: None,
verbosity: None,
bundle: None,
sections: None,
max_tokens: None,
estimate: None,
}))
.await;
assert!(
result.contains("in impl BucketManager"),
"reference list should render the actual enclosing kind; got: {result}"
);
assert!(
!result.contains("in fn impl BucketManager"),
"reference list must not hardcode 'fn' nor double the kind; got: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_context_surfaces_impl_guidance_for_zero_caller_struct() {
let content = b"pub struct ProjectOrchestratorActor;\n\nimpl ProjectOrchestratorActor {\n pub fn new() -> Self {\n Self\n }\n}\n\nimpl Actor for ProjectOrchestratorActor {\n fn handle(&self) {}\n}\n";
let symbols = vec![
SymbolRecord {
name: "ProjectOrchestratorActor".to_string(),
kind: SymbolKind::Struct,
depth: 0,
sort_order: 0,
byte_range: (0, 35),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
},
SymbolRecord {
name: "impl ProjectOrchestratorActor".to_string(),
kind: SymbolKind::Impl,
depth: 0,
sort_order: 1,
byte_range: (37, 117),
line_range: (2, 6),
doc_byte_range: None,
item_byte_range: None,
},
SymbolRecord {
name: "impl Actor for ProjectOrchestratorActor".to_string(),
kind: SymbolKind::Impl,
depth: 0,
sort_order: 2,
byte_range: (119, content.len() as u32),
line_range: (8, 10),
doc_byte_range: None,
item_byte_range: None,
},
];
let server = make_server(make_live_index_ready(vec![make_file(
"src/actors.rs",
content,
symbols,
)]));
let result = server
.get_symbol_context(Parameters(super::GetSymbolContextInput {
project: None,
name: "ProjectOrchestratorActor".to_string(),
file: None,
path: Some("src/actors.rs".to_string()),
symbol_kind: Some("struct".to_string()),
symbol_line: None,
verbosity: None,
bundle: None,
sections: None,
max_tokens: None,
estimate: None,
}))
.await;
assert!(
result.contains("0 direct callers"),
"default symbol context should surface impl guidance for zero-caller structs: {result}"
);
assert!(
result.contains("impl ProjectOrchestratorActor (src/actors.rs:3)"),
"inherent impl suggestion should be surfaced: {result}"
);
assert!(
result.contains("impl Actor for ProjectOrchestratorActor (src/actors.rs:9)"),
"trait impl suggestion should be surfaced: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_context_exact_selector_excludes_unrelated_same_name_hits() {
let target = make_file(
"src/db.rs",
b"pub fn connect() {}\n",
vec![make_symbol("connect", SymbolKind::Function, 1, 1)],
);
let dependent = make_file_with_refs(
"src/service.rs",
b"use crate::db::connect;\nfn run() { connect(); }\n",
vec![make_symbol("run", SymbolKind::Function, 2, 2)],
vec![
make_ref("db", Some("crate::db"), ReferenceKind::Import, 0, None),
make_ref(
"connect",
Some("crate::db::connect"),
ReferenceKind::Call,
1,
Some(0),
),
],
);
let unrelated = make_file_with_refs(
"src/other.rs",
b"fn run() { connect(); }\n",
vec![make_symbol("run", SymbolKind::Function, 1, 1)],
vec![make_ref("connect", None, ReferenceKind::Call, 0, Some(0))],
);
let server = make_server(make_live_index_ready(vec![target, dependent, unrelated]));
let result = server
.get_symbol_context(Parameters(super::GetSymbolContextInput {
project: None,
name: "connect".to_string(),
file: None,
path: Some("src/db.rs".to_string()),
symbol_kind: Some("fn".to_string()),
symbol_line: Some(2),
verbosity: None,
bundle: None,
sections: None,
max_tokens: None,
estimate: None,
}))
.await;
assert!(
result.contains("src/service.rs"),
"expected dependent hit: {result}"
);
assert!(
result.contains("Scope: path `src/db.rs`; exact selector line 2"),
"exact selector scope should be explicit; got: {result}"
);
assert!(
!result.contains("src/other.rs"),
"unrelated same-name file should be excluded: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_context_exact_selector_requires_line_for_ambiguous_symbol() {
let target = make_file(
"src/db.rs",
b"fn connect() { first(); }\nfn connect() { second(); }\n",
vec![
make_symbol_with_bytes("connect", SymbolKind::Function, 1, 1, (0, 25)),
make_symbol_with_bytes("connect", SymbolKind::Function, 2, 2, (26, 52)),
],
);
let server = make_server(make_live_index_ready(vec![target]));
let result = server
.get_symbol_context(Parameters(super::GetSymbolContextInput {
project: None,
name: "connect".to_string(),
file: None,
path: Some("src/db.rs".to_string()),
symbol_kind: Some("fn".to_string()),
symbol_line: None,
verbosity: None,
bundle: None,
sections: None,
max_tokens: None,
estimate: None,
}))
.await;
assert!(
result.contains("Ambiguous symbol selector"),
"got: {result}"
);
assert!(
!result.contains("first()"),
"ambiguous selector should not prepend an arbitrary definition: {result}"
);
assert!(result.contains("1"), "got: {result}");
assert!(result.contains("2"), "got: {result}");
}
#[tokio::test]
async fn test_get_symbol_context_without_path_returns_ambiguous_candidate_list() {
let alpha = make_file(
"src/alpha.rs",
b"fn connect() { alpha(); }\n",
vec![make_symbol_with_bytes(
"connect",
SymbolKind::Function,
1,
1,
(0, 25),
)],
);
let beta = make_file(
"src/beta.rs",
b"fn connect() { beta(); }\n",
vec![make_symbol_with_bytes(
"connect",
SymbolKind::Function,
1,
1,
(0, 24),
)],
);
let server = make_server(make_live_index_ready(vec![alpha, beta]));
let result = server
.get_symbol_context(Parameters(super::GetSymbolContextInput {
project: None,
name: "connect".to_string(),
file: None,
path: None,
symbol_kind: Some("fn".to_string()),
symbol_line: None,
verbosity: None,
bundle: None,
sections: None,
max_tokens: None,
estimate: None,
}))
.await;
assert!(
result.starts_with("Ambiguous symbol selector"),
"ambiguous selector must fail explicitly; got: {result}"
);
assert!(result.contains("src/alpha.rs"), "got: {result}");
assert!(result.contains("src/beta.rs"), "got: {result}");
assert!(
result.contains("Pass `path` or `file`"),
"ambiguous response should include recovery guidance; got: {result}"
);
assert!(
!result.contains("alpha()") && !result.contains("beta()"),
"ambiguous selector must not show an arbitrary first definition: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_context_with_path_succeeds_when_symbol_name_is_duplicated() {
let alpha = make_file(
"src/alpha.rs",
b"fn connect() { alpha(); }\n",
vec![make_symbol_with_bytes(
"connect",
SymbolKind::Function,
1,
1,
(0, 25),
)],
);
let beta = make_file(
"src/beta.rs",
b"fn connect() { beta(); }\n",
vec![make_symbol_with_bytes(
"connect",
SymbolKind::Function,
1,
1,
(0, 24),
)],
);
let server = make_server(make_live_index_ready(vec![alpha, beta]));
let result = server
.get_symbol_context(Parameters(super::GetSymbolContextInput {
project: None,
name: "connect".to_string(),
file: None,
path: Some("src/beta.rs".to_string()),
symbol_kind: Some("fn".to_string()),
symbol_line: None,
verbosity: None,
bundle: None,
sections: None,
max_tokens: None,
estimate: None,
}))
.await;
assert!(
!result.starts_with("Ambiguous symbol selector"),
"explicit path should disambiguate duplicate symbol names: {result}"
);
assert!(result.contains("src/beta.rs"), "got: {result}");
assert!(result.contains("beta()"), "got: {result}");
assert!(!result.contains("alpha()"), "got: {result}");
}
#[tokio::test]
async fn test_get_symbol_context_without_path_ambiguity_does_not_bump_frecency() {
let repo = TempDir::new().expect("temp repo");
let _frecency = EnvVarGuard::set(crate::live_index::frecency::FRECENCY_FLAG_ENV, "1");
let alpha = make_file(
"src/alpha.rs",
b"fn connect() { alpha(); }\n",
vec![make_symbol("connect", SymbolKind::Function, 1, 1)],
);
let beta = make_file(
"src/beta.rs",
b"fn connect() { beta(); }\n",
vec![make_symbol("connect", SymbolKind::Function, 1, 1)],
);
let server = make_server_with_root(
make_live_index_ready(vec![alpha, beta]),
Some(repo.path().to_path_buf()),
);
let result = server
.get_symbol_context(Parameters(super::GetSymbolContextInput {
project: None,
name: "connect".to_string(),
file: None,
path: None,
symbol_kind: Some("fn".to_string()),
symbol_line: None,
verbosity: None,
bundle: None,
sections: None,
max_tokens: None,
estimate: None,
}))
.await;
assert!(
result.starts_with("Ambiguous symbol selector"),
"got: {result}"
);
assert!(
!crate::live_index::frecency::frecency_db_path(&project_state(repo.path())).exists(),
"ambiguous selector must not bump frecency for an arbitrary first candidate"
);
}
#[test]
fn test_symbol_candidate_paths_sorts_all_matches() {
let index = make_live_index_ready(vec![
make_file(
"src/zeta.rs",
b"fn connect() {}\n",
vec![make_symbol("connect", SymbolKind::Function, 1, 1)],
),
make_file(
"src/echo.rs",
b"fn connect() {}\n",
vec![make_symbol("connect", SymbolKind::Function, 1, 1)],
),
make_file(
"src/bravo.rs",
b"fn connect() {}\n",
vec![make_symbol("connect", SymbolKind::Function, 1, 1)],
),
make_file(
"src/alpha.rs",
b"fn connect() {}\n",
vec![make_symbol("connect", SymbolKind::Function, 1, 1)],
),
make_file(
"src/delta.rs",
b"fn connect() {}\n",
vec![make_symbol("connect", SymbolKind::Function, 1, 1)],
),
make_file(
"src/charlie.rs",
b"fn connect() {}\n",
vec![make_symbol("connect", SymbolKind::Function, 1, 1)],
),
]);
let candidates = super::symbol_candidate_paths(&index, "connect");
assert_eq!(candidates.len(), 6);
assert_eq!(candidates.first().map(String::as_str), Some("src/alpha.rs"));
assert_eq!(candidates.last().map(String::as_str), Some("src/zeta.rs"));
}
#[tokio::test]
async fn test_get_symbol_context_exact_selector_respects_file_filter() {
let target = make_file(
"src/db.rs",
b"pub fn connect() {}\n",
vec![make_symbol("connect", SymbolKind::Function, 1, 1)],
);
let service = make_file_with_refs(
"src/service.rs",
b"use crate::db::connect;\nfn run() { connect(); }\n",
vec![make_symbol("run", SymbolKind::Function, 2, 2)],
vec![
make_ref("db", Some("crate::db"), ReferenceKind::Import, 0, None),
make_ref(
"connect",
Some("crate::db::connect"),
ReferenceKind::Call,
1,
Some(0),
),
],
);
let api = make_file_with_refs(
"src/api.rs",
b"use crate::db::connect;\nfn expose() { connect(); }\n",
vec![make_symbol("expose", SymbolKind::Function, 2, 2)],
vec![
make_ref("db", Some("crate::db"), ReferenceKind::Import, 0, None),
make_ref(
"connect",
Some("crate::db::connect"),
ReferenceKind::Call,
1,
Some(0),
),
],
);
let server = make_server(make_live_index_ready(vec![target, service, api]));
let result = server
.get_symbol_context(Parameters(super::GetSymbolContextInput {
project: None,
name: "connect".to_string(),
file: Some("src/service.rs".to_string()),
path: Some("src/db.rs".to_string()),
symbol_kind: Some("fn".to_string()),
symbol_line: Some(2),
verbosity: None,
bundle: None,
sections: None,
max_tokens: None,
estimate: None,
}))
.await;
assert!(result.contains("src/service.rs"), "got: {result}");
assert!(!result.contains("src/api.rs"), "got: {result}");
}
#[tokio::test]
async fn test_analyze_file_impact_reports_symbol_change() {
let repo = TempDir::new().expect("temp repo");
fs::create_dir_all(repo.path().join("src")).expect("src dir");
let source_path = repo.path().join("src").join("lib.rs");
fs::write(&source_path, "pub fn new_name() {}\n").expect("write updated source");
let old_symbol = make_symbol("old_name", SymbolKind::Function, 1, 1);
let (key, file) = make_file("src/lib.rs", b"pub fn old_name() {}\n", vec![old_symbol]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(repo.path().to_path_buf()),
);
let result = server
.analyze_file_impact(Parameters(super::AnalyzeFileImpactInput {
project: None,
path: "src/lib.rs".to_string(),
new_file: None,
include_co_changes: None,
co_changes_limit: None,
estimate: None,
}))
.await;
assert!(
result.contains("new_name"),
"impact tool should re-read the file from repo_root and report new symbols; got: {result}"
);
}
#[tokio::test]
async fn test_analyze_file_impact_unchanged_shows_status() {
// Use setup_edit_test so the index holds real parsed symbols (correct byte_ranges).
// Then call analyze_file_impact WITHOUT modifying the file — should report unchanged.
let source = b"pub fn alpha() {}\npub fn beta() {}\n";
let (dir, server, _file_path) = setup_edit_test(source);
let _ = dir; // keep temp dir alive
let result = server
.analyze_file_impact(Parameters(super::AnalyzeFileImpactInput {
project: None,
path: "src/lib.rs".to_string(),
new_file: None,
include_co_changes: None,
co_changes_limit: None,
estimate: None,
}))
.await;
assert!(
result.contains("indexed and unchanged"),
"unchanged file should report 'indexed and unchanged'; got: {result}"
);
assert!(
result.contains("Symbols: 2"),
"should show symbol count; got: {result}"
);
assert!(
result.contains("what_changed"),
"should suggest what_changed; got: {result}"
);
}
#[tokio::test]
async fn test_analyze_file_impact_deleted_file() {
let source = b"pub fn gone() {}\n";
let (dir, server, file_path) = setup_edit_test(source);
let _ = dir; // keep temp dir alive
// Delete the file from disk to simulate external deletion.
fs::remove_file(&file_path).expect("remove source");
let result = server
.analyze_file_impact(Parameters(super::AnalyzeFileImpactInput {
project: None,
path: "src/lib.rs".to_string(),
new_file: None,
include_co_changes: None,
co_changes_limit: None,
estimate: None,
}))
.await;
assert!(
result.contains("not found under"),
"deleted file should report 'not found under <root>' (dogfood #6: \
the lookup root is always named); got: {result}"
);
}
#[tokio::test]
async fn test_analyze_file_impact_auto_indexes_new_file_when_missing_from_index() {
let repo = TempDir::new().expect("temp repo");
fs::create_dir_all(repo.path().join("src")).expect("src dir");
let source_path = repo.path().join("src").join("fresh.rs");
fs::write(&source_path, "pub fn fresh_symbol() {}\n").expect("write new source");
let server = make_server_with_root(
make_live_index_ready(vec![]),
Some(repo.path().to_path_buf()),
);
let result = server
.analyze_file_impact(Parameters(super::AnalyzeFileImpactInput {
project: None,
path: "src/fresh.rs".to_string(),
new_file: None,
include_co_changes: None,
co_changes_limit: None,
estimate: None,
}))
.await;
assert!(
result.contains("[Indexed, 0 callers yet]"),
"new on-disk file should auto-index even without new_file=true; got: {result}"
);
assert!(
result.contains("fresh_symbol") || result.contains("1 fn"),
"auto-indexed new file should report symbol summary; got: {result}"
);
}
#[tokio::test]
async fn explicit_protected_root_requires_override_and_never_touches_local_state() {
let fixture = TempDir::new().expect("protected-root fixture parent");
let protected = fixture.path().join("System32");
fs::create_dir(&protected).expect("create modeled protected root");
fs::write(protected.join("lib.rs"), "pub fn protected_symbol() {}\n")
.expect("write protected-root source");
let server = make_server(make_live_index_empty());
let refused = server
.index_folder(Parameters(super::IndexFolderInput {
path: protected.display().to_string(),
idempotency_key: None,
add: None,
allow_protected_root: None,
}))
.await;
assert!(
refused.contains("protected_root_requires_explicit_override"),
"direct protected roots must fail closed without the explicit override: {refused}"
);
assert!(!protected.join(".symforge").exists());
let indexed = server
.index_folder(Parameters(super::IndexFolderInput {
path: protected.display().to_string(),
idempotency_key: None,
add: None,
allow_protected_root: Some(true),
}))
.await;
assert!(
indexed.contains("Indexed 1 files"),
"the exact direct protected root should index with explicit authority: {indexed}"
);
assert!(
!protected.join(".symforge").exists(),
"explicit-protected indexing must skip source-local state entirely"
);
}
#[tokio::test]
async fn explicit_normal_index_folder_reconciles_existing_root_gitignore() {
let repo = TempDir::new().expect("gitignore hygiene repo");
fs::create_dir(repo.path().join(".git")).expect("create git metadata marker");
fs::write(repo.path().join(".gitignore"), b"target/\r\n").expect("write root gitignore");
fs::write(repo.path().join("lib.rs"), "pub fn indexed_symbol() {}\n")
.expect("write source");
let server = make_server(make_live_index_empty());
let indexed = server
.index_folder(Parameters(super::IndexFolderInput {
path: repo.path().display().to_string(),
idempotency_key: None,
add: None,
allow_protected_root: None,
}))
.await;
assert!(
indexed.contains("gitignore_hygiene=effective changed=true"),
"successful explicit normal indexing must report the hygiene mutation: {indexed}"
);
assert_eq!(
fs::read(repo.path().join(".gitignore")).expect("read reconciled gitignore"),
b"target/\r\n/.symforge/\r\n",
"index_folder must preserve existing bytes and the first newline style"
);
}
#[tokio::test]
async fn failed_retarget_preserves_previous_generation_and_watcher() {
let active = TempDir::new().expect("active project");
fs::create_dir_all(active.path().join("src")).expect("create active source dir");
fs::write(
active.path().join("src/active.rs"),
"pub fn active_generation() {}\n",
)
.expect("write active source");
let rejected = TempDir::new().expect("failed retarget project");
fs::write(rejected.path().join("one.rs"), "fn one() {}\n").expect("write one");
fs::write(rejected.path().join("two.rs"), "fn two() {}\n").expect("write two");
let index = LiveIndex::load(active.path()).expect("load active project");
let watcher_info = Arc::new(parking_lot::Mutex::new(
crate::watcher::WatcherInfo::default(),
));
let active_root = active.path().canonicalize().expect("canonical active root");
let server = SymForgeServer::new(
index,
"failed-retarget".to_string(),
Arc::clone(&watcher_info),
Some(active_root.clone()),
None,
);
let watcher = crate::watcher::restart_watcher(
active_root.clone(),
Arc::clone(&server.index),
Arc::clone(&server.watcher_info),
None,
);
let original_stop_token = Arc::clone(&watcher.stop_token);
server.watcher_handle.lock().replace(watcher);
for _ in 0..100 {
if server.watcher_info.lock().state == crate::watcher_state::WatcherState::Active {
break;
}
tokio::time::sleep(Duration::from_millis(20)).await;
}
assert_eq!(
server.watcher_info.lock().state,
crate::watcher_state::WatcherState::Active,
"fixture watcher must be active before exercising failed handoff"
);
// `Active` is not "settled": the reconcile that precedes it spawns a
// git-temporal task whose publications would otherwise land on top of
// the baseline captured below.
settle_background_publications(&server).await;
let root_before = server.capture_repo_root();
let generation_before = server.index.current_project_generation();
let published_before = server.index.published_state();
let limit = EnvVarGuard::set("SYMFORGE_MAX_INDEX_FILES", "1");
let result = server
.index_folder(Parameters(super::IndexFolderInput {
path: rejected.path().display().to_string(),
idempotency_key: None,
add: None,
allow_protected_root: None,
}))
.await;
drop(limit);
assert!(
result.contains("tree too large to index"),
"fixture must fail after binding but before publication: {result}"
);
assert_eq!(server.capture_repo_root(), root_before);
assert_eq!(
server.index.current_project_generation(),
generation_before,
"failed retarget must not advance the live project generation"
);
assert!(
Arc::ptr_eq(&published_before, &server.index.published_state()),
"failed retarget must preserve the exact published generation"
);
assert!(server.index.read().get_file("src/active.rs").is_some());
{
let watcher = server.watcher_handle.lock();
let watcher = watcher
.as_ref()
.expect("failed retarget must retain the previous watcher handle");
assert!(Arc::ptr_eq(&original_stop_token, &watcher.stop_token));
assert!(
!watcher
.stop_token
.load(std::sync::atomic::Ordering::Acquire),
"failed retarget must not signal the previous watcher to stop"
);
}
fs::write(
active.path().join("src/after_failure.rs"),
"pub fn watcher_survived() {}\n",
)
.expect("write post-failure source");
for _ in 0..100 {
if server
.index
.read()
.get_file("src/after_failure.rs")
.is_some()
{
break;
}
tokio::time::sleep(Duration::from_millis(20)).await;
}
assert!(
server
.index
.read()
.get_file("src/after_failure.rs")
.is_some(),
"the retained watcher must keep the prior project fresh"
);
let watcher = server
.watcher_handle
.lock()
.take()
.expect("watcher cleanup handle");
watcher
.stop_token
.store(true, std::sync::atomic::Ordering::Release);
let mut task = watcher.task;
if tokio::time::timeout(Duration::from_secs(2), &mut task)
.await
.is_err()
{
task.abort();
}
}
#[tokio::test]
async fn test_index_folder_rebinds_repo_root_for_local_impact_analysis() {
let repo = TempDir::new().expect("temp repo");
fs::create_dir_all(repo.path().join("scratch")).expect("scratch dir");
let source_path = repo.path().join("scratch").join("impact_case.rs");
fs::write(&source_path, "pub fn old_name() {}\n").expect("write initial source");
let server = make_server(make_live_index_empty());
let index_result = server
.index_folder(Parameters(super::IndexFolderInput {
path: repo.path().display().to_string(),
idempotency_key: None,
add: None,
allow_protected_root: None,
}))
.await;
assert!(
index_result.contains("Indexed 1 files"),
"index_folder should load the temp repo, got: {index_result}"
);
// The reload above spawns git temporal; let it finish before the
// re-index below, whose publication CAS would otherwise lose to it.
settle_background_publications(&server).await;
fs::write(&source_path, "pub fn new_name() {}\n").expect("write updated source");
let outside = TempDir::new().expect("outside cwd");
let _cwd_guard = CwdGuard::set(outside.path());
let impact = server
.analyze_file_impact(Parameters(super::AnalyzeFileImpactInput {
project: None,
path: "scratch/impact_case.rs".to_string(),
new_file: None,
include_co_changes: None,
co_changes_limit: None,
estimate: None,
}))
.await;
assert!(
impact.contains("new_name"),
"impact analysis should keep using the indexed repo root after index_folder, got: {impact}"
);
let outline = server
.get_file_context(Parameters(super::GetFileContextInput {
project: None,
path: "scratch/impact_case.rs".to_string(),
max_tokens: None,
force_refresh: None,
sections: Some(vec!["outline".to_string()]),
estimate: None,
}))
.await;
assert!(
outline.contains("new_name"),
"impact analysis must not replace the indexed file with an empty parse, got: {outline}"
);
}
#[tokio::test]
async fn test_index_folder_rebinds_repo_root_for_local_what_changed_git_mode() {
let repo = init_git_repo();
fs::create_dir_all(repo.path().join("src")).expect("create src dir");
fs::write(repo.path().join("src/lib.rs"), "fn foo() {}\n").expect("write initial file");
run_git(repo.path(), &["add", "."]);
run_git(repo.path(), &["commit", "-m", "init", "-q"]);
let server = make_server(make_live_index_empty());
let index_result = server
.index_folder(Parameters(super::IndexFolderInput {
path: repo.path().display().to_string(),
idempotency_key: None,
add: None,
allow_protected_root: None,
}))
.await;
assert!(
index_result.contains("Indexed 1 files"),
"index_folder should load the temp repo, got: {index_result}"
);
// Same race as the sibling test above: settle git temporal before the
// re-index this asserts on.
settle_background_publications(&server).await;
fs::write(
repo.path().join("src/lib.rs"),
"fn foo() { println!(\"changed\"); }\n",
)
.expect("modify tracked file");
let outside = TempDir::new().expect("outside cwd");
let _cwd_guard = CwdGuard::set(outside.path());
let result = server
.what_changed(Parameters(super::WhatChangedInput {
project: None,
since: None,
git_ref: None,
uncommitted: None,
path_prefix: None,
language: None,
code_only: None,
include_symbol_diff: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("src/lib.rs"),
"what_changed should keep using the indexed repo root after index_folder, got: {result}"
);
}
#[tokio::test]
async fn test_index_folder_warns_when_indexing_subfolder_of_git_repo() {
let repo = init_git_repo();
let sub = repo.path().join("subproject");
fs::create_dir_all(&sub).expect("create subfolder");
fs::write(sub.join("lib.rs"), "fn foo() {}\n").expect("write source in subfolder");
let server = make_server(make_live_index_empty());
let result = server
.index_folder(Parameters(super::IndexFolderInput {
path: sub.display().to_string(),
idempotency_key: None,
add: None,
allow_protected_root: None,
}))
.await;
assert!(
result.contains("Indexed"),
"subfolder index should still succeed (warn-only, no retarget), got: {result}"
);
assert!(
result.contains("subfolder of a git repo") && result.contains("not the git root"),
"indexing a subfolder of a git repo should warn about the path namespace shift, got: {result}"
);
}
#[tokio::test]
async fn test_index_folder_can_reindex_same_root_twice_locally() {
let repo = TempDir::new().expect("temp repo");
fs::create_dir_all(repo.path().join("src")).expect("create src dir");
fs::write(repo.path().join("src/lib.rs"), "pub fn first() {}\n")
.expect("write initial file");
let server = make_server(make_live_index_empty());
let first = server
.index_folder(Parameters(super::IndexFolderInput {
path: repo.path().display().to_string(),
idempotency_key: None,
add: None,
allow_protected_root: None,
}))
.await;
assert!(
first.contains("Indexed 1 files"),
"first local index_folder should succeed, got: {first}"
);
fs::write(repo.path().join("src/lib.rs"), "pub fn second() {}\n").expect("update file");
let second = server
.index_folder(Parameters(super::IndexFolderInput {
path: repo.path().display().to_string(),
idempotency_key: None,
add: None,
allow_protected_root: None,
}))
.await;
assert!(
second.contains("Indexed 1 files"),
"second local index_folder should also succeed, got: {second}"
);
let outline = server
.get_file_context(Parameters(super::GetFileContextInput {
project: None,
path: "src/lib.rs".to_string(),
max_tokens: None,
force_refresh: None,
sections: Some(vec!["outline".to_string()]),
estimate: None,
}))
.await;
assert!(
outline.contains("second"),
"second local index_folder should refresh the same-root index, got: {outline}"
);
let health = server.health_compact().await;
let root_text = repo
.path()
.canonicalize()
.expect("temp repo should canonicalize")
.to_string_lossy()
.replace('\\', "/");
assert!(
health.contains(&format!("project_root={root_text}")),
"health should surface the project root after index_folder, got: {health}"
);
assert!(
health.contains("load_source=fresh_load")
&& health.contains("reset_state=none")
&& health.contains("index_state=fresh_process"),
"plain index_folder should report a fresh index without reset identity, got: {health}"
);
assert!(
!health.contains("index_state=index_folder_reset"),
"plain index_folder must not claim reset state, got: {health}"
);
assert!(
health.contains("index_id=index-"),
"health should keep index identity assertable after reindex, got: {health}"
);
}
#[tokio::test]
async fn test_index_folder_reset_deletes_snapshot_scope_and_reports_fresh_status() {
let _reset_env = EnvVarGuard::set(super::INDEX_FOLDER_RESET_ENV, "1");
let repo = TempDir::new().expect("temp repo");
let src_dir = repo.path().join("src");
let symforge_dir = repo.path().join(".symforge");
fs::create_dir_all(&src_dir).expect("create src dir");
fs::create_dir_all(&symforge_dir).expect("create .symforge dir");
fs::write(src_dir.join("lib.rs"), "pub fn reset_fresh() {}\n").expect("write source");
let snapshot_placement = crate::domain::StatePlacement::ProjectLocal {
directory: crate::domain::ProjectStateDir::new(symforge_dir.clone()),
};
crate::live_index::persist::serialize_index(
&make_live_index_empty(),
repo.path(),
&snapshot_placement,
)
.expect("write valid owned snapshot");
fs::write(symforge_dir.join("index.bin.tmp"), b"stale tmp").expect("write tmp");
fs::write(symforge_dir.join("frecency.db"), b"unrelated").expect("write sentinel");
let server = make_server(make_live_index_empty());
let output = server
.index_folder(Parameters(super::IndexFolderInput {
path: repo.path().display().to_string(),
idempotency_key: None,
add: None,
allow_protected_root: None,
}))
.await;
assert!(
output.starts_with("Indexed 1 files"),
"reset index_folder should still report indexing success first, got: {output}"
);
assert!(
output.contains("Reset: scope=.symforge/index.bin,.symforge/index.bin.tmp | removed=2"),
"reset output should prove bounded snapshot deletion, got: {output}"
);
assert!(
output.contains("Runtime:") && output.contains("load_source=fresh_load"),
"reset output should include fresh runtime status, got: {output}"
);
assert!(
output.contains("index_state=index_folder_reset") && output.contains("index_id=index-"),
"reset output should include assertable fresh identity, got: {output}"
);
assert!(
output.contains("reset_state=current_project:p"),
"reset output should prove reset identity is tied to the current project generation, got: {output}"
);
assert!(!symforge_dir.join("index.bin").exists());
assert!(!symforge_dir.join("index.bin.tmp").exists());
assert!(
symforge_dir.join("frecency.db").exists(),
"reset must preserve unrelated .symforge state"
);
assert!(
src_dir.join("lib.rs").exists(),
"reset must never delete source files"
);
let health = server
.health(Parameters(super::HealthInput::default()))
.await;
assert!(
health.contains("load_source=fresh_load")
&& health.contains("reset_state=current_project:p")
&& health.contains("index_state=index_folder_reset")
&& health.contains("index_id=index-"),
"health after reset should prove fresh identity/source, got: {health}"
);
}
#[tokio::test]
async fn test_index_folder_idempotency_replays_same_key_same_request_locally() {
let repo = TempDir::new().expect("temp repo");
let control = TempDir::new().expect("temp control state");
fs::create_dir_all(repo.path().join("src")).expect("create src dir");
fs::write(repo.path().join("src/lib.rs"), "pub fn first() {}\n")
.expect("write initial file");
let server = make_server(make_live_index_empty()).with_control_state_dir_for_test(
crate::domain::ControlStateDir::new(control.path().join("control")),
);
let first = server
.index_folder(Parameters(super::IndexFolderInput {
path: repo.path().display().to_string(),
idempotency_key: Some("local-replay-key".to_string()),
add: None,
allow_protected_root: None,
}))
.await;
assert!(
first.starts_with("Indexed 1 files"),
"first idempotent index_folder should index once, got: {first}"
);
fs::write(repo.path().join("src/second.rs"), "pub fn second() {}\n")
.expect("write second file");
let replay = server
.index_folder(Parameters(super::IndexFolderInput {
path: repo.path().display().to_string(),
idempotency_key: Some("local-replay-key".to_string()),
add: None,
allow_protected_root: None,
}))
.await;
assert_eq!(
replay, first,
"same idempotency key and same canonical request must replay stored output"
);
assert_eq!(
server.index.published_state().file_count,
2,
"stored output may return only after the current live binding is rebuilt"
);
}
#[tokio::test]
async fn test_index_folder_idempotency_rejects_same_key_different_request_locally() {
let first_repo = TempDir::new().expect("first repo");
let second_repo = TempDir::new().expect("second repo");
let control = TempDir::new().expect("temp control state");
fs::create_dir_all(first_repo.path().join("src")).expect("create first src dir");
fs::create_dir_all(second_repo.path().join("src")).expect("create second src dir");
fs::write(first_repo.path().join("src/lib.rs"), "pub fn first() {}\n")
.expect("write first source");
fs::write(
second_repo.path().join("src/lib.rs"),
"pub fn second() {}\n",
)
.expect("write second source");
let server = make_server(make_live_index_empty()).with_control_state_dir_for_test(
crate::domain::ControlStateDir::new(control.path().join("control")),
);
let first = server
.index_folder(Parameters(super::IndexFolderInput {
path: first_repo.path().display().to_string(),
idempotency_key: Some("local-conflict-key".to_string()),
add: None,
allow_protected_root: None,
}))
.await;
assert!(
first.starts_with("Indexed 1 files"),
"first idempotent index_folder should index once, got: {first}"
);
let override_conflict = server
.index_folder(Parameters(super::IndexFolderInput {
path: first_repo.path().display().to_string(),
idempotency_key: Some("local-conflict-key".to_string()),
add: None,
allow_protected_root: Some(true),
}))
.await;
assert!(
override_conflict.contains("Idempotency conflict"),
"same key with a changed protected-root override must conflict: {override_conflict}"
);
let conflict = server
.index_folder(Parameters(super::IndexFolderInput {
path: second_repo.path().display().to_string(),
idempotency_key: Some("local-conflict-key".to_string()),
add: None,
allow_protected_root: None,
}))
.await;
assert!(
conflict.contains("Idempotency conflict"),
"same key with a different canonical request must fail deterministically, got: {conflict}"
);
assert!(
!conflict.starts_with("Indexed "),
"conflict must not report synthetic indexing success: {conflict}"
);
}
#[test]
fn local_cross_project_refusal_allows_matching_local_selector() {
// SUB-FIX A: search_symbols/search_text/find_references gate their no-daemon
// local path on `local_cross_project_refusal`. It must PROCEED (return None,
// same as no selector) when the selector RESOLVES TO THE BOUND PROJECT — by
// name, by the bound root's project key, or by the root path — and only
// refuse foreign/multi/wildcard targets. Pre-fix it refused ANY non-empty
// selector, wrongly rejecting a matching-local one.
let repo = TempDir::new().expect("tempdir");
let root = repo.path().to_path_buf();
let server = make_server_with_root(make_live_index_empty(), Some(root.clone()));
// No selector at all -> proceed (control).
assert!(
server.local_cross_project_refusal(None, None).is_none(),
"no selector must proceed"
);
// Matching-local by project NAME -> proceed (the fix).
assert!(
server
.local_cross_project_refusal(Some("test_project"), None)
.is_none(),
"a selector equal to the bound project name must PROCEED, not refuse"
);
// Matching-local by the bound root's deterministic project key -> proceed.
let key = crate::daemon::project_key(&root);
assert!(
server
.local_cross_project_refusal(Some(key.as_str()), None)
.is_none(),
"a selector equal to the bound root's project key must PROCEED"
);
// Matching-local by root PATH (forward-slash form) -> proceed.
let root_fwd = root.display().to_string().replace('\\', "/");
assert!(
server
.local_cross_project_refusal(Some(root_fwd.as_str()), None)
.is_none(),
"a selector equal to the bound root path must PROCEED"
);
// Matching-local through the PLURAL `projects` selector -> proceed.
let plural_local = vec!["test_project".to_string()];
assert!(
server
.local_cross_project_refusal(None, Some(plural_local.as_slice()))
.is_none(),
"a plural projects=[bound name] must PROCEED"
);
// Foreign singular selector -> refuse, and the message must still name the
// /mcp transport (the D16 containment wording is preserved).
let foreign = server
.local_cross_project_refusal(Some("other-proj"), None)
.expect("a foreign project selector must still refuse");
assert!(
foreign.contains("/mcp HTTP transport"),
"the foreign refusal must still name the /mcp transport, got: {foreign}"
);
// Wildcard -> refuse (cross-project unanswerable without a daemon working set).
let wildcard = vec!["*".to_string()];
assert!(
server
.local_cross_project_refusal(None, Some(wildcard.as_slice()))
.expect("wildcard projects must refuse")
.contains("/mcp HTTP transport"),
"wildcard refusal must name the /mcp transport"
);
// Multiple distinct non-bound projects -> refuse.
let multi = vec!["a".to_string(), "b".to_string()];
assert!(
server
.local_cross_project_refusal(None, Some(multi.as_slice()))
.expect("multi-project projects must refuse")
.contains("/mcp HTTP transport"),
"multi-project refusal must name the /mcp transport"
);
}
#[tokio::test]
async fn test_search_symbols_returns_results() {
let sym = make_symbol("find_user", SymbolKind::Function, 1, 5);
let (key, file) = make_file("src/lib.rs", b"fn find_user() {}", vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_symbols(Parameters(super::SearchSymbolsInput {
query: Some("find".to_string()),
kind: None,
path_prefix: None,
language: None,
limit: None,
include_generated: None,
include_tests: None,
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("find_user"),
"should find matching symbol, got: {result}"
);
assert!(
result.contains("Trust: constrained (prefix tier) | current index | parsed"),
"search_symbols should expose the compact trust line, got: {result}"
);
// B5 (2026-07-03 spike gate): success paths carry no always-on tip.
assert!(
!result.contains("Tip:"),
"search_symbols success path must not carry a tip"
);
}
#[tokio::test]
async fn test_search_symbols_kind_filter_returns_only_requested_kind() {
let function = make_symbol("JobRunner", SymbolKind::Function, 1, 5);
let class = make_symbol("Job", SymbolKind::Class, 6, 10);
let (key, file) = make_file(
"src/lib.rs",
b"fn JobRunner() {}\nstruct Job {}",
vec![function, class],
);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_symbols(Parameters(super::SearchSymbolsInput {
query: Some("job".to_string()),
kind: Some("class".to_string()),
path_prefix: None,
language: None,
limit: None,
include_generated: None,
include_tests: None,
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("class Job"),
"class should remain visible: {result}"
);
assert!(
!result.contains("fn JobRunner"),
"function should be filtered out: {result}"
);
}
#[tokio::test]
async fn test_search_symbols_hides_generated_and_test_noise_by_default() {
let server = make_server(make_live_index_ready(vec![
make_file(
"src/job.rs",
b"struct Job {}\n",
vec![make_symbol("Job", SymbolKind::Class, 1, 1)],
),
make_file(
"src/generated/job_generated.rs",
b"struct JobGenerated {}\n",
vec![make_symbol("JobGenerated", SymbolKind::Class, 2, 2)],
),
make_file(
"tests/job_test.rs",
b"struct JobTest {}\n",
vec![make_symbol("JobTest", SymbolKind::Class, 3, 3)],
),
]));
let result = server
.search_symbols(Parameters(super::SearchSymbolsInput {
query: Some("job".to_string()),
kind: Some("class".to_string()),
path_prefix: None,
language: None,
limit: None,
include_generated: None,
include_tests: None,
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("class Job"),
"expected primary hit: {result}"
);
assert!(
!result.contains("JobGenerated"),
"generated symbol noise should be hidden by default: {result}"
);
assert!(
!result.contains("JobTest"),
"test symbol noise should be hidden by default: {result}"
);
assert!(
result.contains("vendor filter active (heuristic)"),
"scope should report vendor filtering status: {result}"
);
}
#[tokio::test]
async fn test_search_symbols_hides_vendor_by_default_and_reports_filter() {
let server = make_server(make_live_index_ready(vec![
make_file(
"src/job.rs",
b"struct Job {}\n",
vec![make_symbol("Job", SymbolKind::Class, 1, 1)],
),
make_file(
"vendor/somelib/job.rs",
b"struct JobVendor {}\n",
vec![make_symbol("JobVendor", SymbolKind::Class, 1, 1)],
),
]));
let result = server
.search_symbols(Parameters(super::SearchSymbolsInput {
query: Some("job".to_string()),
kind: Some("class".to_string()),
path_prefix: None,
language: None,
limit: None,
include_generated: None,
include_tests: None,
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("class Job"),
"source symbol should remain visible: {result}"
);
assert!(
!result.contains("JobVendor"),
"vendor symbol should be hidden by default: {result}"
);
assert!(
result.contains("vendor filter active (heuristic)")
&& result.contains("1 noise-filtered match(es) suppressed"),
"vendor filtering should be explicit in envelope: {result}"
);
}
#[tokio::test]
async fn test_search_symbols_includes_vendor_when_flag_true() {
let server = make_server(make_live_index_ready(vec![
make_file(
"src/job.rs",
b"struct Job {}\n",
vec![make_symbol("Job", SymbolKind::Class, 1, 1)],
),
make_file(
"vendor/somelib/job.rs",
b"struct JobVendor {}\n",
vec![make_symbol("JobVendor", SymbolKind::Class, 1, 1)],
),
]));
let result = server
.search_symbols(Parameters(super::SearchSymbolsInput {
query: Some("job".to_string()),
kind: Some("class".to_string()),
path_prefix: None,
language: None,
limit: None,
include_generated: None,
include_tests: None,
include_vendor: Some(true),
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("JobVendor"),
"include_vendor=true should surface vendor symbols: {result}"
);
assert!(
result.contains("vendor included"),
"scope should report vendor inclusion: {result}"
);
}
#[tokio::test]
async fn test_search_symbols_counts_suppressed_personal_tooling_when_vendor_included() {
let server = make_server(make_live_index_ready(vec![
make_file(
"src/job.rs",
b"struct Job {}\n",
vec![make_symbol("Job", SymbolKind::Class, 1, 1)],
),
make_file(
".claude/gsd-local-patches/job.rs",
b"struct JobPersonal {}\n",
vec![make_symbol("JobPersonal", SymbolKind::Class, 1, 1)],
),
]));
let result = server
.search_symbols(Parameters(super::SearchSymbolsInput {
query: Some("job".to_string()),
kind: Some("class".to_string()),
path_prefix: None,
language: None,
limit: None,
include_generated: None,
include_tests: None,
include_vendor: Some(true),
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("class Job"),
"source symbol should remain visible: {result}"
);
assert!(
!result.contains("JobPersonal"),
"personal-tooling symbol should stay hidden by default: {result}"
);
assert!(
result.contains("vendor included")
&& result.contains("personal tooling filtered")
&& result.contains("1 noise-filtered match(es) suppressed"),
"suppressed personal-tooling count should be explicit even when vendor is included: {result}"
);
}
#[tokio::test]
async fn test_search_symbols_hides_inline_test_module_symbols() {
// src/lib.rs is NOT a test file, but contains `mod tests { struct TestHelper; }`.
// With include_tests=false (default), symbols inside the inline test module
// should be hidden even though the file itself is classified as source code.
let content = b"struct Foo {}\nmod tests {\n struct TestHelper;\n}\n";
let symbols = vec![
SymbolRecord {
name: "Foo".to_string(),
kind: SymbolKind::Struct,
depth: 0,
sort_order: 0,
byte_range: (0, 13),
item_byte_range: Some((0, 13)),
line_range: (0, 0),
doc_byte_range: None,
},
SymbolRecord {
name: "tests".to_string(),
kind: SymbolKind::Module,
depth: 0,
sort_order: 1,
byte_range: (14, 48),
item_byte_range: Some((14, 48)),
line_range: (1, 3),
doc_byte_range: None,
},
SymbolRecord {
name: "TestHelper".to_string(),
kind: SymbolKind::Struct,
depth: 1,
sort_order: 2,
byte_range: (28, 46),
item_byte_range: Some((28, 46)),
line_range: (2, 2),
doc_byte_range: None,
},
];
let server = make_server(make_live_index_ready(vec![make_file(
"src/lib.rs",
content,
symbols,
)]));
let result = server
.search_symbols(Parameters(super::SearchSymbolsInput {
query: None,
kind: Some("struct".to_string()),
path_prefix: Some("src/".to_string()),
language: None,
limit: None,
include_generated: None,
include_tests: None, // default: false
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("Foo"),
"source struct should appear: {result}"
);
assert!(
!result.contains("TestHelper"),
"struct inside inline mod tests should be hidden: {result}"
);
}
#[tokio::test]
async fn test_search_symbols_tool_can_include_generated_without_tests() {
let server = make_server(make_live_index_ready(vec![
make_file(
"src/job.rs",
b"struct Job {}\n",
vec![make_symbol("Job", SymbolKind::Class, 1, 1)],
),
make_file(
"src/generated/job_generated.rs",
b"struct JobGenerated {}\n",
vec![make_symbol("JobGenerated", SymbolKind::Class, 2, 2)],
),
make_file(
"tests/job_test.rs",
b"struct JobTest {}\n",
vec![make_symbol("JobTest", SymbolKind::Class, 3, 3)],
),
]));
let result = server
.search_symbols(Parameters(super::SearchSymbolsInput {
query: Some("job".to_string()),
kind: Some("class".to_string()),
path_prefix: None,
language: None,
limit: None,
include_generated: Some(true),
include_tests: None,
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("class Job"),
"expected primary hit: {result}"
);
assert!(
result.contains("JobGenerated"),
"generated symbol should be visible when opted in: {result}"
);
assert!(
!result.contains("JobTest"),
"test noise should stay hidden without explicit opt-in: {result}"
);
}
#[tokio::test]
async fn test_search_symbols_tool_can_include_tests_without_generated() {
let server = make_server(make_live_index_ready(vec![
make_file(
"src/job.rs",
b"struct Job {}\n",
vec![make_symbol("Job", SymbolKind::Class, 1, 1)],
),
make_file(
"src/generated/job_generated.rs",
b"struct JobGenerated {}\n",
vec![make_symbol("JobGenerated", SymbolKind::Class, 2, 2)],
),
make_file(
"tests/job_test.rs",
b"struct JobTest {}\n",
vec![make_symbol("JobTest", SymbolKind::Class, 3, 3)],
),
]));
let result = server
.search_symbols(Parameters(super::SearchSymbolsInput {
query: Some("job".to_string()),
kind: Some("class".to_string()),
path_prefix: None,
language: None,
limit: None,
include_generated: None,
include_tests: Some(true),
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("class Job"),
"expected primary hit: {result}"
);
assert!(
!result.contains("JobGenerated"),
"generated noise should stay hidden without explicit opt-in: {result}"
);
assert!(
result.contains("JobTest"),
"test symbol should be visible when opted in: {result}"
);
}
#[tokio::test]
async fn test_search_symbols_tool_respects_scope_language_limit_and_kind() {
let rust_model = make_file(
"src/models/job.rs",
b"struct Job {}\nfn JobRunner() {}\n",
vec![
make_symbol("Job", SymbolKind::Class, 1, 1),
make_symbol("JobRunner", SymbolKind::Function, 2, 2),
],
);
let mut ts_ui = make_file(
"src/ui/job.ts",
b"class JobCard {}\nclass JobList {}\n",
vec![
make_symbol("JobCard", SymbolKind::Class, 1, 1),
make_symbol("JobList", SymbolKind::Class, 2, 2),
],
);
ts_ui.1.language = LanguageId::TypeScript;
let server = make_server(make_live_index_ready(vec![rust_model, ts_ui]));
let result = server
.search_symbols(Parameters(super::SearchSymbolsInput {
query: Some("job".to_string()),
kind: Some("class".to_string()),
path_prefix: Some("src/ui".to_string()),
language: Some("TypeScript".to_string()),
limit: Some(1),
include_generated: None,
include_tests: None,
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("1 matches in 1 files"),
"expected bounded output: {result}"
);
assert!(
result.contains("class JobCard"),
"expected scoped class hit: {result}"
);
assert!(
!result.contains("JobList"),
"limit should truncate later hits: {result}"
);
assert!(
!result.contains("src/models/job.rs"),
"path scope should exclude rust model: {result}"
);
assert!(
!result.contains("fn JobRunner"),
"kind filter should exclude function: {result}"
);
}
#[tokio::test]
async fn test_search_symbols_browse_by_kind_without_query() {
let sym_fn = make_symbol("do_work", SymbolKind::Function, 1, 5);
let sym_struct = make_symbol("Worker", SymbolKind::Class, 6, 10);
let (key, file) = make_file(
"src/protocol/worker.rs",
b"fn do_work() {}\nstruct Worker {}",
vec![sym_fn, sym_struct],
);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_symbols(Parameters(super::SearchSymbolsInput {
query: None,
kind: Some("fn".to_string()),
path_prefix: Some("src/protocol/".to_string()),
language: None,
limit: None,
include_generated: None,
include_tests: None,
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("do_work"),
"browse mode should return fn symbols, got: {result}"
);
assert!(
!result.contains("Worker"),
"browse mode kind filter should exclude structs, got: {result}"
);
}
#[tokio::test]
async fn test_browse_handler_is_frecency_neutral() {
use std::path::Path;
let root = TempDir::new().expect("temp repo");
let _frecency = EnvVarGuard::set(crate::live_index::frecency::FRECENCY_FLAG_ENV, "1");
let (key, file) = make_file(
"src/lib.rs",
b"pub fn new() {}\n",
vec![make_symbol("new", SymbolKind::Function, 1, 1)],
);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(root.path().to_path_buf()),
);
let probe = || {
crate::live_index::frecency::ranking_scores_for_paths(
root.path(),
Some(&project_state(root.path())),
&[Path::new("src/lib.rs")],
0,
)
.expect("frecency ranking probe")
};
assert!(
probe().is_none(),
"fixture must start without frecency history"
);
let result = server
.search_symbols(Parameters(super::SearchSymbolsInput {
query: None,
kind: Some("fn".to_string()),
path_prefix: Some("src/".to_string()),
language: None,
limit: Some(5),
include_generated: None,
include_tests: None,
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("new"),
"browse fixture must return its symbol: {result}"
);
assert!(
probe().is_none(),
"public browse handler must not record a commitment signal"
);
let content = server
.get_file_content(Parameters(get_file_content_input("src/lib.rs")))
.await;
assert!(content.contains("pub fn new"));
assert!(
probe().is_some(),
"positive-control commitment read must exercise the real frecency store"
);
}
#[tokio::test]
async fn test_search_symbols_rejects_fully_unbounded() {
let sym = make_symbol("anything", SymbolKind::Function, 1, 5);
let (key, file) = make_file("src/lib.rs", b"fn anything() {}", vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_symbols(Parameters(super::SearchSymbolsInput {
query: None,
kind: None,
path_prefix: None,
language: None,
limit: None,
include_generated: None,
include_tests: None,
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("requires at least one of"),
"fully unbounded browse should be rejected, got: {result}"
);
}
#[tokio::test]
async fn test_search_symbols_browse_default_limit_20() {
// Create 25 distinct symbols — browse mode should return only 20
let syms: Vec<_> = (1..=25)
.map(|i| make_symbol(&format!("sym_{i:02}"), SymbolKind::Function, i, i))
.collect();
let content = b"fn placeholder() {}";
let (key, file) = make_file("src/lib.rs", content, syms);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_symbols(Parameters(super::SearchSymbolsInput {
query: None,
kind: Some("fn".to_string()),
path_prefix: None,
language: None,
limit: None,
include_generated: None,
include_tests: None,
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("20 matches in"),
"browse mode default limit should be 20, got: {result}"
);
}
#[tokio::test]
async fn test_search_symbols_query_mode_still_defaults_to_50() {
// Create 55 distinct symbols — query mode should return 50
let syms: Vec<_> = (1..=55)
.map(|i| make_symbol(&format!("item_{i:02}"), SymbolKind::Function, i, i))
.collect();
let content = b"fn placeholder() {}";
let (key, file) = make_file("src/lib.rs", content, syms);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_symbols(Parameters(super::SearchSymbolsInput {
query: Some("item".to_string()),
kind: None,
path_prefix: None,
language: None,
limit: None,
include_generated: None,
include_tests: None,
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("50 matches in"),
"query mode default limit should remain 50, got: {result}"
);
}
#[tokio::test]
async fn test_search_text_returns_results() {
let (key, file) = make_file("src/lib.rs", b"fn find_user() {}", vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("find".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("find_user"),
"should find matching text, got: {result}"
);
assert!(
result.contains("Trust: constrained (literal)"),
"search_text should expose trust envelope, got: {result}"
);
assert!(
result.contains(
"Scope: repo-wide; tests filter active (heuristic); generated filter active (heuristic)"
),
"search_text should expose applied scope, got: {result}"
);
// B5 (2026-07-03 spike gate): success paths carry no always-on tip.
assert!(
!result.contains("Tip:"),
"search_text success path must not carry a tip"
);
}
#[tokio::test]
async fn test_search_text_empty_result_reports_matching_untracked_file() {
let dir = init_git_repo();
fs::create_dir_all(dir.path().join("src")).unwrap();
fs::write(dir.path().join("src/lib.rs"), "fn tracked() {}\n").unwrap();
run_git(dir.path(), &["add", "."]);
run_git(dir.path(), &["commit", "-m", "tracked"]);
fs::write(
dir.path().join("src/new_text.rs"),
"fn new_text() { let _ = \"unique_untracked_needle\"; }\n",
)
.unwrap();
let (key, file) = make_file("src/lib.rs", b"fn tracked() {}\n", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(dir.path().into()),
);
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("unique_untracked_needle".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("No matches for 'unique_untracked_needle'"),
"got: {result}"
);
assert!(
result.contains("untracked file may match: 1 untracked path(s) are not indexed"),
"missing diagnostic count: {result}"
);
assert!(
result.contains("analyze_file_impact(\"src/new_text.rs\", new_file=true)"),
"missing recovery call: {result}"
);
assert!(server.index.read().get_file("src/new_text.rs").is_none());
}
#[tokio::test]
async fn test_search_text_non_empty_result_omits_untracked_diagnostic() {
let dir = init_git_repo();
fs::create_dir_all(dir.path().join("src")).unwrap();
fs::write(dir.path().join("src/lib.rs"), "fn tracked() {}\n").unwrap();
run_git(dir.path(), &["add", "."]);
run_git(dir.path(), &["commit", "-m", "tracked"]);
fs::write(
dir.path().join("src/new_text.rs"),
"fn new_text() { let _ = \"shared_needle\"; }\n",
)
.unwrap();
let (key, file) = make_file(
"src/lib.rs",
b"fn tracked() { let _ = \"shared_needle\"; }\n",
vec![],
);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(dir.path().into()),
);
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("shared_needle".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(result.contains("src/lib.rs"), "got: {result}");
assert!(
!result.contains("untracked file may match"),
"diagnostic must be zero-hit only: {result}"
);
}
#[tokio::test]
async fn test_search_text_structural_envelope_reports_ast_grep_match_type() {
let (key, file) = make_file("src/lib.rs", b"fn find_user() {}", vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("fn $NAME($$$) { $$$ }".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: Some(true),
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("find_user"),
"should find matching function, got: {result}"
);
assert!(
result.contains("Trust: structural (ast-grep)"),
"structural search should expose ast-grep match type, got: {result}"
);
}
#[tokio::test]
async fn test_search_text_trust_envelope_reports_partial_parse_and_truncation() {
let (key, mut file) = make_file(
"Cargo.toml",
b"needle one\nneedle two\nneedle three\n",
vec![make_symbol("package", SymbolKind::Key, 1, 1)],
);
let diagnostic = crate::domain::ParseDiagnostic {
parser: "toml_edit".to_string(),
message: "missing closing quote".to_string(),
line: Some(3),
column: Some(11),
byte_span: Some((28, 41)),
fallback_used: true,
};
file.language = LanguageId::Toml;
file.parse_status = ParseStatus::PartialParse {
warning: diagnostic.summary(),
};
file.parse_diagnostic = Some(diagnostic);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("needle".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: Some(2),
max_per_file: Some(2),
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(result.contains("Parse state: partial"), "got: {result}");
assert!(
result.contains("Completeness: truncated by result cap (1 more omitted)"),
"got: {result}"
);
assert!(
result.contains("Evidence: line anchors `Cargo.toml:1`"),
"got: {result}"
);
}
#[tokio::test]
async fn test_search_text_terms_or_returns_results() {
let (key, file) = make_file(
"src/lib.rs",
b"// TODO: first\n// FIXME: second\n// NOTE: ignored",
vec![],
);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: None,
terms: Some(vec!["TODO".to_string(), "FIXME".to_string()]),
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("TODO: first"),
"TODO term should match: {result}"
);
assert!(
result.contains("FIXME: second"),
"FIXME term should match: {result}"
);
assert!(
!result.contains("NOTE: ignored"),
"unmatched line should be absent: {result}"
);
}
#[tokio::test]
async fn test_search_text_terms_annotates_matched_term() {
let sym_a = make_symbol("fn_alpha", SymbolKind::Function, 0, 0);
let sym_b = make_symbol("fn_beta", SymbolKind::Function, 1, 1);
let file = make_file(
"src/lib.rs",
b"fn fn_alpha() { alpha_value }\nfn fn_beta() { beta_value }\n",
vec![sym_a, sym_b],
);
let server = make_server(make_live_index_ready(vec![file]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: None,
terms: Some(vec!["alpha_value".to_string(), "beta_value".to_string()]),
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("[term: alpha_value]"),
"should annotate alpha term: {result}"
);
assert!(
result.contains("[term: beta_value]"),
"should annotate beta term: {result}"
);
}
#[tokio::test]
async fn test_search_text_hides_generated_and_test_noise_by_default() {
let server = make_server(make_live_index_ready(vec![
make_file("src/real.rs", b"needle visible", vec![]),
make_file("tests/generated/noise.rs", b"needle hidden", vec![]),
]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("needle".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("src/real.rs"),
"expected visible file: {result}"
);
assert!(
!result.contains("tests/generated/noise.rs"),
"generated/test noise should be hidden by default: {result}"
);
}
#[tokio::test]
async fn test_search_text_tool_respects_scope_language_and_caps() {
let mut ts_app = make_file(
"src/app.ts",
b"needle one\nneedle two\nneedle three\n",
vec![],
);
ts_app.1.language = LanguageId::TypeScript;
let mut ts_lib = make_file("src/lib.ts", b"needle four\nneedle five\n", vec![]);
ts_lib.1.language = LanguageId::TypeScript;
let noise = make_file(
"tests/generated/noise.ts",
b"needle hidden\nneedle hidden two\n",
vec![],
);
let rust = make_file("src/lib.rs", b"needle rust\nneedle rust two\n", vec![]);
let server = make_server(make_live_index_ready(vec![ts_app, ts_lib, noise, rust]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("needle".to_string()),
terms: None,
regex: None,
path_prefix: Some("src".to_string()),
language: Some("TypeScript".to_string()),
limit: Some(3),
max_per_file: Some(2),
include_generated: Some(false),
include_tests: Some(false),
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(result.contains("src/app.ts"), "expected app.ts: {result}");
assert!(result.contains("src/lib.ts"), "expected lib.ts: {result}");
assert!(
!result.contains("needle three"),
"per-file cap should truncate app.ts: {result}"
);
assert!(
!result.contains("needle five"),
"total cap should truncate final result set: {result}"
);
assert!(
!result.contains("tests/generated/noise.ts"),
"noise file should be excluded: {result}"
);
assert!(
!result.contains("src/lib.rs"),
"language filter should exclude Rust: {result}"
);
}
#[tokio::test]
async fn test_search_text_tool_context_renders_windows() {
let server = make_server(make_live_index_ready(vec![make_file(
"src/lib.rs",
b"line 1\nline 2\nneedle 3\nline 4\nneedle 5\nline 6\nline 7\nline 8\nneedle 9\nline 10\n",
vec![],
)]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("needle".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: Some(1),
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains(" 2: line 2"),
"context line missing: {result}"
);
assert!(
result.contains("> 3: needle 3"),
"match marker missing: {result}"
);
assert!(result.contains(" ..."), "separator missing: {result}");
}
#[tokio::test]
async fn test_search_text_tool_respects_glob_and_exclude_glob() {
let server = make_server(make_live_index_ready(vec![
make_file("src/app.ts", b"needle app\n", vec![]),
make_file("src/app.spec.ts", b"needle spec\n", vec![]),
make_file("src/nested/feature.ts", b"needle nested\n", vec![]),
make_file("src/lib.rs", b"needle rust\n", vec![]),
]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("needle".to_string()),
terms: None,
regex: None,
path_prefix: Some("src".to_string()),
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: Some("src/**/*.ts".to_string()),
exclude_glob: Some("**/*.spec.ts".to_string()),
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(result.contains("src/app.ts"), "expected app.ts: {result}");
assert!(
result.contains("src/nested/feature.ts"),
"expected nested ts file: {result}"
);
assert!(
!result.contains("src/app.spec.ts"),
"exclude_glob should suppress spec file: {result}"
);
assert!(
!result.contains("src/lib.rs"),
"include glob should suppress rust file: {result}"
);
}
#[tokio::test]
async fn test_search_text_tool_reports_invalid_glob() {
let server = make_server(make_live_index_ready(vec![make_file(
"src/app.ts",
b"needle app\n",
vec![],
)]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("needle".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: Some("[".to_string()),
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("Invalid glob for `glob`"),
"expected invalid glob error, got: {result}"
);
}
#[tokio::test]
async fn test_search_text_tool_respects_case_sensitive_and_whole_word() {
let server = make_server(make_live_index_ready(vec![make_file(
"src/lib.rs",
b"Needle\nneedle\nNeedleCase\nNeedle suffix\n",
vec![],
)]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("Needle".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: Some(true),
whole_word: Some(true),
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains(" 1: Needle"),
"exact whole-word match missing: {result}"
);
assert!(
result.contains(" 4: Needle suffix"),
"whole-word prefix match on a line should remain visible: {result}"
);
assert!(
!result.contains(" 2: needle"),
"case-sensitive search should exclude lowercase line: {result}"
);
assert!(
!result.contains(" 3: NeedleCase"),
"whole-word search should exclude embedded identifier match: {result}"
);
}
#[tokio::test]
async fn test_search_text_tool_reports_regex_whole_word_rejection() {
let server = make_server(make_live_index_ready(vec![make_file(
"src/lib.rs",
b"needle\n",
vec![],
)]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("needle".to_string()),
terms: None,
regex: Some(true),
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: Some(true),
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("whole_word is not supported when `regex=true`"),
"expected regex/whole_word rejection, got: {result}"
);
}
#[tokio::test]
async fn test_search_text_auto_corrects_double_escaped_regex() {
let (key, file) = make_file("src/handler.rs", b"fn handle_request() {}\n", vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
// Use a double-escaped \s (arrives as \\s in the JSON string)
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some(r"fn\\s+handle_".to_string()),
terms: None,
regex: Some(true),
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("handle_request"),
"should find match after auto-correcting double-escaped regex, got: {result}"
);
assert!(
result.contains("auto-corrected"),
"should include auto-correction note, got: {result}"
);
}
#[tokio::test]
async fn test_search_files_returns_ranked_paths() {
let server = make_server(make_live_index_ready(vec![
make_file("src/protocol/tools.rs", b"fn a() {}", vec![]),
make_file("src/sidecar/tools.rs", b"fn b() {}", vec![]),
make_file("src/protocol/tools_helper.rs", b"fn c() {}", vec![]),
]));
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "protocol/tools.rs".to_string(),
limit: Some(20),
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(result.contains("2 matching files"), "got: {result}");
assert!(
result.contains("── Strong path matches ──"),
"got: {result}"
);
assert!(
result.contains("Trust: constrained (tiered path relevance)"),
"search_files should expose trust envelope, got: {result}"
);
assert!(
result.contains("Scope: ranked indexed file paths"),
"search_files should expose search scope, got: {result}"
);
assert!(result.contains("── Basename matches ──"), "got: {result}");
assert!(result.contains("src/protocol/tools.rs"), "got: {result}");
assert!(result.contains("src/sidecar/tools.rs"), "got: {result}");
assert!(!result.contains("tools_helper.rs"), "got: {result}");
}
#[tokio::test]
async fn test_search_files_path_prefix_scopes_results() {
let server = make_server(make_live_index_ready(vec![
make_file("src/protocol/tools.rs", b"fn a() {}", vec![]),
make_file("src/sidecar/tools.rs", b"fn b() {}", vec![]),
]));
// Without path_prefix: both same-basename files are returned.
let unscoped = server
.search_files(Parameters(super::SearchFilesInput {
path_prefix: None,
..search_files_input("tools.rs")
}))
.await;
assert!(
unscoped.contains("src/protocol/tools.rs"),
"unscoped should include protocol path, got: {unscoped}"
);
assert!(
unscoped.contains("src/sidecar/tools.rs"),
"unscoped should include sidecar path, got: {unscoped}"
);
// With path_prefix=src/protocol: only paths under that prefix survive.
let scoped = server
.search_files(Parameters(super::SearchFilesInput {
path_prefix: Some("src/protocol".to_string()),
..search_files_input("tools.rs")
}))
.await;
assert!(
scoped.contains("src/protocol/tools.rs"),
"scoped should include in-prefix path, got: {scoped}"
);
assert!(
!scoped.contains("src/sidecar/tools.rs"),
"scoped must drop out-of-prefix path, got: {scoped}"
);
}
/// Regression for D20 review: scoping must hold UNDER overflow truncation.
/// The default limit is 20; seeding >20 in-prefix and >20 out-of-prefix
/// same-basename files forces the overflow path. If the prefix were applied
/// only to the visible (already-truncated) hits, out-of-prefix files in the
/// overflow set would escape scoping and the reported total/overflow counts
/// would be inflated. We assert: (a) no out-of-prefix path appears at all,
/// and (b) the header total equals only the in-prefix count (30), proving
/// total_matches is scoped pre-count, not just the rendered view.
#[tokio::test]
async fn test_search_files_path_prefix_scopes_under_overflow() {
let mut files = Vec::new();
for i in 0..30 {
files.push(make_file(
&format!("src/protocol/m{i:02}/tools.rs"),
b"fn a() {}",
vec![],
));
files.push(make_file(
&format!("src/sidecar/m{i:02}/tools.rs"),
b"fn b() {}",
vec![],
));
}
let server = make_server(make_live_index_ready(files));
let scoped = server
.search_files(Parameters(super::SearchFilesInput {
path_prefix: Some("src/protocol".to_string()),
..search_files_input("tools.rs")
}))
.await;
// No out-of-prefix path leaks, even from the overflow set.
assert!(
!scoped.contains("src/sidecar/"),
"no out-of-prefix path may appear under overflow, got: {scoped}"
);
// total_matches reflects ONLY the 30 in-prefix files, not all 60.
assert!(
scoped.contains("30 matching files"),
"scoped header must count only in-prefix matches, got: {scoped}"
);
// overflow_count is scoped too: 30 matches, limit 20 => "... and 10 more".
assert!(
scoped.contains("... and 10 more"),
"scoped overflow count must be 30-20=10, got: {scoped}"
);
}
#[tokio::test]
async fn test_search_files_not_found() {
let server = make_server(make_live_index_ready(vec![]));
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "src/service.rs".to_string(),
limit: None,
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
result.contains("No indexed source files matching 'src/service.rs'"),
"got: {result}"
);
assert!(
result.contains("filters: vendor filter active (heuristic); personal tooling filtered"),
"not-found search_files output should disclose active filters: {result}"
);
}
#[tokio::test]
async fn test_search_files_empty_result_reports_matching_untracked_file() {
let dir = init_git_repo();
fs::create_dir_all(dir.path().join("src")).unwrap();
fs::write(dir.path().join("src/lib.rs"), "fn tracked() {}\n").unwrap();
run_git(dir.path(), &["add", "."]);
run_git(dir.path(), &["commit", "-m", "tracked"]);
fs::write(
dir.path().join("src/new_service.rs"),
"fn new_service() {}\n",
)
.unwrap();
let (key, file) = make_file("src/lib.rs", b"fn tracked() {}\n", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(dir.path().into()),
);
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "src/new_service.rs".to_string(),
limit: None,
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
result.contains("No indexed source files matching 'src/new_service.rs'"),
"got: {result}"
);
assert!(
result.contains("untracked file may match: 1 untracked path(s) are not indexed"),
"missing diagnostic count: {result}"
);
assert!(
result.contains("analyze_file_impact(\"src/new_service.rs\", new_file=true)"),
"missing recovery call: {result}"
);
assert!(server.index.read().get_file("src/new_service.rs").is_none());
}
#[tokio::test]
async fn test_search_files_non_empty_result_omits_untracked_diagnostic() {
let dir = init_git_repo();
fs::create_dir_all(dir.path().join("src")).unwrap();
fs::write(dir.path().join("src/service.rs"), "fn service() {}\n").unwrap();
run_git(dir.path(), &["add", "."]);
run_git(dir.path(), &["commit", "-m", "tracked"]);
fs::write(
dir.path().join("src/new_service.rs"),
"fn new_service() {}\n",
)
.unwrap();
let (key, file) = make_file("src/service.rs", b"fn service() {}\n", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(dir.path().into()),
);
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "service.rs".to_string(),
limit: None,
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(result.contains("src/service.rs"), "got: {result}");
assert!(
!result.contains("untracked file may match"),
"diagnostic must be zero-hit only: {result}"
);
}
#[tokio::test]
async fn test_search_files_changed_with_returns_graceful_message() {
// Without git temporal data loaded, should return informative message
let (key, file) = make_file("src/daemon.rs", b"fn foo() {}", vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: String::new(),
limit: None,
current_file: None,
changed_with: Some("src/daemon.rs".to_string()),
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
// Without git temporal data, should return informative message (not an error/panic)
assert!(!result.contains("panic"), "should not panic, got: {result}");
assert!(
result.contains("temporal") || result.contains("git"),
"should mention temporal data status, got: {result}"
);
}
#[tokio::test]
async fn test_search_files_changed_with_surfaces_weak_candidates() {
let (key_a, file_a) = make_file("src/auth.rs", b"fn auth() {}", vec![]);
let (key_b, file_b) = make_file("src/routes.rs", b"fn routes() {}", vec![]);
let server = make_server(make_live_index_ready(vec![
(key_a, file_a),
(key_b, file_b),
]));
server
.index
.update_git_temporal(crate::live_index::git_temporal::GitTemporalIndex {
files: HashMap::from([(
"src/auth.rs".to_string(),
crate::live_index::git_temporal::GitFileHistory {
commit_count: 4,
churn_score: 0.7,
last_commit: crate::live_index::git_temporal::CommitSummary {
hash: "abc1234".to_string(),
timestamp: "2026-04-02T12:00:00Z".to_string(),
author: "Tester".to_string(),
message_head: "touch auth".to_string(),
days_ago: 1.0,
},
contributors: vec![],
co_changes: vec![],
weak_co_changes: vec![crate::live_index::git_temporal::CoChangeEntry {
path: "src/routes.rs".to_string(),
coupling_score: 0.12,
shared_commits: 1,
}],
},
)]),
stats: crate::live_index::git_temporal::GitTemporalStats {
total_commits_analyzed: 12,
analysis_window_days: 90,
hotspots: vec![],
most_coupled: vec![],
computed_at: std::time::SystemTime::now(),
compute_duration: Duration::ZERO,
},
state: crate::live_index::git_temporal::GitTemporalState::Ready,
});
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: String::new(),
limit: None,
current_file: None,
changed_with: Some("src/auth.rs".to_string()),
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
result.contains("weak heuristic (git-temporal coupling)"),
"{result}"
);
assert!(
result.contains("Deprecation warning")
&& result.contains("rank_by=\"path+cochange\"")
&& result.contains("anchor_path"),
"changed_with output should point callers at the fused co-change path: {result}"
);
assert!(result.contains("Low confidence"), "{result}");
assert!(result.contains("src/routes.rs"), "{result}");
}
#[tokio::test]
async fn test_search_files_path_cochange_uses_coupling_store_anchor_neighbors() {
let store = crate::live_index::coupling::CouplingStore::open_in_memory().unwrap();
store
.bulk_upsert(&[crate::live_index::coupling::CouplingRow {
anchor: crate::live_index::coupling::AnchorKey::file("src/auth/routes.rs"),
partner: crate::live_index::coupling::AnchorKey::file("src/server/routes.rs"),
shared_commits: 3,
weighted_score: 11.0,
last_commit_ts: 1_700_000_000,
}])
.unwrap();
let server = make_server(make_live_index_ready_with_coupling_store(
vec![
make_file("src/auth/routes.rs", b"fn auth_routes() {}", vec![]),
make_file("src/server/routes.rs", b"fn server_routes() {}", vec![]),
make_file("src/client/routes.rs", b"fn client_routes() {}", vec![]),
],
store,
));
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "routes.rs".to_string(),
limit: Some(20),
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: Some("path+cochange".to_string()),
anchor_path: Some("src/auth/routes.rs".to_string()),
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
result.contains("── Co-changed files (coupling store) ──"),
"got: {result}"
);
let partner_pos = result.find("src/server/routes.rs").expect("partner");
let anchor_pos = result.find("src/auth/routes.rs").expect("anchor");
assert!(
partner_pos < anchor_pos,
"co-change partner should be promoted above anchor: {result}"
);
assert!(
result.contains("3 shared commits"),
"coupling evidence should be rendered: {result}"
);
assert!(
result.contains("Capability: co-change ranking applied")
&& result.contains("loaded 1 usable coupling partner"),
"rank_by=path+cochange should report applied evidence: {result}"
);
}
#[tokio::test]
async fn test_search_files_path_cochange_env_unset_missing_store_reports_preparing() {
let _env = EnvVarGuard::remove("SYMFORGE_COUPLING");
let repo = init_git_repo();
let db_path =
crate::live_index::coupling::lifecycle::coupling_db_path(&project_state(repo.path()));
assert!(!db_path.exists(), "test starts without a coupling store");
let server = make_server_with_root(
make_live_index_ready(vec![
make_file("src/auth/routes.rs", b"fn auth_routes() {}", vec![]),
make_file("src/server/routes.rs", b"fn server_routes() {}", vec![]),
]),
Some(repo.path().to_path_buf()),
);
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "routes.rs".to_string(),
limit: Some(20),
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: Some("path+cochange".to_string()),
anchor_path: Some("src/auth/routes.rs".to_string()),
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
result.contains("Capability: co-change ranking preparing"),
"env-unset missing-store request should report lazy preparation evidence: {result}"
);
assert!(
result.contains("path ranking returned"),
"preparing fallback should preserve path-ranked results: {result}"
);
}
#[tokio::test]
async fn test_search_files_path_cochange_disabled_policy_reports_disabled() {
let _env = EnvVarGuard::set("SYMFORGE_COUPLING", "disabled");
let repo = init_git_repo();
let db_path =
crate::live_index::coupling::lifecycle::coupling_db_path(&project_state(repo.path()));
let server = make_server_with_root(
make_live_index_ready(vec![
make_file("src/auth/routes.rs", b"fn auth_routes() {}", vec![]),
make_file("src/server/routes.rs", b"fn server_routes() {}", vec![]),
]),
Some(repo.path().to_path_buf()),
);
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "routes.rs".to_string(),
limit: Some(20),
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: Some("path+cochange".to_string()),
anchor_path: Some("src/auth/routes.rs".to_string()),
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
result.contains("Capability: co-change ranking disabled by policy"),
"disabled policy should be reported explicitly: {result}"
);
assert!(
!db_path.exists(),
"disabled policy must not create a coupling store"
);
}
#[tokio::test]
async fn test_search_files_path_cochange_non_git_reports_unavailable() {
let _env = EnvVarGuard::remove("SYMFORGE_COUPLING");
let root = TempDir::new().expect("temp non-git root");
let server = make_server_with_root(
make_live_index_ready(vec![
make_file("src/auth/routes.rs", b"fn auth_routes() {}", vec![]),
make_file("src/server/routes.rs", b"fn server_routes() {}", vec![]),
]),
Some(root.path().to_path_buf()),
);
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "routes.rs".to_string(),
limit: Some(20),
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: Some("path+cochange".to_string()),
anchor_path: Some("src/auth/routes.rs".to_string()),
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
result.contains("Capability: co-change ranking unavailable")
&& result.contains("not a git repository"),
"non-git repo should be reported explicitly: {result}"
);
}
#[tokio::test]
async fn test_search_files_path_cochange_missing_anchor_reports_precise_evidence() {
let _env = EnvVarGuard::remove("SYMFORGE_COUPLING");
let repo = init_git_repo();
let server = make_server_with_root(
make_live_index_ready(vec![
make_file("src/auth/routes.rs", b"fn auth_routes() {}", vec![]),
make_file("src/server/routes.rs", b"fn server_routes() {}", vec![]),
]),
Some(repo.path().to_path_buf()),
);
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "routes.rs".to_string(),
limit: Some(20),
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: Some("path+cochange".to_string()),
anchor_path: Some("src/missing/routes.rs".to_string()),
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
result.contains("Capability: co-change ranking fallback used")
&& result.contains("anchor_path=src/missing/routes.rs")
&& result.contains("not indexed"),
"missing anchor should be precise evidence, not silent path fallback: {result}"
);
}
#[tokio::test]
async fn test_search_files_path_cochange_empty_neighbor_set_reports_fallback_evidence() {
let store = crate::live_index::coupling::CouplingStore::open_in_memory().unwrap();
let server = make_server(make_live_index_ready_with_coupling_store(
vec![
make_file("src/auth/routes.rs", b"fn auth_routes() {}", vec![]),
make_file("src/server/routes.rs", b"fn server_routes() {}", vec![]),
],
store,
));
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "routes.rs".to_string(),
limit: Some(20),
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: Some("path+cochange".to_string()),
anchor_path: Some("src/auth/routes.rs".to_string()),
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
result.contains("Capability: co-change ranking fallback used")
&& result.contains("no usable partner rows"),
"empty neighbor set should be explicit fallback evidence: {result}"
);
}
#[tokio::test]
async fn test_search_files_path_cochange_corrupt_store_reports_unavailable() {
let _env = EnvVarGuard::remove("SYMFORGE_COUPLING");
let repo = init_git_repo();
let db_path =
crate::live_index::coupling::lifecycle::coupling_db_path(&project_state(repo.path()));
fs::create_dir_all(db_path.parent().unwrap()).unwrap();
fs::write(&db_path, b"not sqlite").unwrap();
let server = make_server_with_root(
make_live_index_ready(vec![
make_file("src/auth/routes.rs", b"fn auth_routes() {}", vec![]),
make_file("src/server/routes.rs", b"fn server_routes() {}", vec![]),
]),
Some(repo.path().to_path_buf()),
);
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "routes.rs".to_string(),
limit: Some(20),
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: Some("path+cochange".to_string()),
anchor_path: Some("src/auth/routes.rs".to_string()),
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
result.contains("Capability: co-change ranking unavailable")
&& result.contains("unable to open coupling store"),
"corrupt store should be explicit unavailable evidence: {result}"
);
}
#[tokio::test]
async fn test_search_files_path_cochange_without_anchor_path_falls_back_to_default() {
let store = crate::live_index::coupling::CouplingStore::open_in_memory().unwrap();
let server = make_server(make_live_index_ready_with_coupling_store(
vec![
make_file("src/auth/routes.rs", b"fn auth_routes() {}", vec![]),
make_file("src/server/routes.rs", b"fn server_routes() {}", vec![]),
],
store,
));
let default = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "routes.rs".to_string(),
limit: Some(20),
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
let path_cochange = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "routes.rs".to_string(),
limit: Some(20),
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: Some("path+cochange".to_string()),
anchor_path: None,
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
path_cochange.contains("src/auth/routes.rs")
&& path_cochange.contains("src/server/routes.rs"),
"fallback should preserve path results: {path_cochange}"
);
assert!(
path_cochange.contains("Capability: co-change ranking fallback used")
&& path_cochange.contains("requires `anchor_path=<path>`"),
"fallback should explain missing anchor: {path_cochange}"
);
assert!(
!default.contains("Capability: co-change ranking"),
"baseline should not contain rank_by diagnostics: {default}"
);
}
#[tokio::test]
async fn test_search_files_path_cochange_without_coupling_store_falls_back_to_default() {
let server = make_server(make_live_index_ready(vec![
make_file("src/auth/routes.rs", b"fn auth_routes() {}", vec![]),
make_file("src/server/routes.rs", b"fn server_routes() {}", vec![]),
]));
let default = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "routes.rs".to_string(),
limit: Some(20),
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
let path_cochange = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "routes.rs".to_string(),
limit: Some(20),
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: Some("path+cochange".to_string()),
anchor_path: Some("src/auth/routes.rs".to_string()),
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
path_cochange.contains("src/auth/routes.rs")
&& path_cochange.contains("src/server/routes.rs"),
"fallback should preserve path results: {path_cochange}"
);
assert!(
path_cochange.contains("Capability: co-change ranking unavailable")
&& path_cochange.contains("no repository root is bound"),
"fallback should explain unavailable/empty coupling evidence: {path_cochange}"
);
assert!(
!default.contains("Capability: co-change ranking"),
"baseline should not contain rank_by diagnostics: {default}"
);
}
#[tokio::test]
async fn test_search_files_hides_vendor_paths_by_default() {
let server = make_server(make_live_index_ready_with_vendor_file());
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "bar.rs".to_string(),
limit: None,
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
!result.contains("vendor/foo/bar.rs"),
"vendor path should be suppressed by default: {result}"
);
assert!(
result.contains("No indexed source files matching 'bar.rs'"),
"filtered query should not resolve only-vendor matches: {result}"
);
assert!(
result.contains("1 vendor/personal-tooling path candidate hidden by default"),
"suppressed-noise note should be visible: {result}"
);
assert!(
result.contains("filters: vendor filter active (heuristic); personal tooling filtered"),
"active search_files filters should be disclosed even on no-result output: {result}"
);
}
#[tokio::test]
async fn test_search_files_includes_vendor_when_flag_true() {
let server = make_server(make_live_index_ready_with_vendor_file());
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "bar.rs".to_string(),
limit: None,
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: Some(true),
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
result.contains("vendor/foo/bar.rs"),
"include_vendor=true should surface vendor path: {result}"
);
assert!(
result.contains("filters: vendor included; personal tooling filtered"),
"active search_files filters should be disclosed in the envelope: {result}"
);
}
#[tokio::test]
async fn test_search_files_resolve_hides_vendor_paths_by_default() {
let server = make_server(make_live_index_ready_with_vendor_file());
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "bar.rs".to_string(),
limit: None,
current_file: None,
changed_with: None,
resolve: Some(true),
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
!result.contains("vendor/foo/bar.rs"),
"resolve=true should suppress vendor by default: {result}"
);
assert!(
result.contains("No indexed source path matched 'bar.rs'"),
"resolve=true should not resolve only-vendor matches by default: {result}"
);
assert!(
result.contains("1 vendor/personal-tooling path candidate hidden by default"),
"resolve=true should explain suppressed vendor candidate: {result}"
);
assert!(
result.contains("filters: vendor filter active (heuristic); personal tooling filtered"),
"resolve=true output should disclose active search_files filters: {result}"
);
}
#[tokio::test]
async fn test_search_files_resolve_includes_vendor_when_flag_true() {
let server = make_server(make_live_index_ready_with_vendor_file());
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "bar.rs".to_string(),
limit: None,
current_file: None,
changed_with: None,
resolve: Some(true),
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: Some(true),
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
result.contains("vendor/foo/bar.rs"),
"include_vendor=true should resolve vendor path: {result}"
);
assert!(
result.contains("Trust: exact (resolve)"),
"include_vendor=true should keep normal resolve envelope: {result}"
);
assert!(
result.contains("filters: vendor included; personal tooling filtered"),
"include_vendor resolve output should disclose active filters: {result}"
);
}
#[tokio::test]
async fn test_search_files_glob_hides_vendor_paths_by_default() {
let server = make_server(make_live_index_ready_with_vendor_file());
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "vendor/**/*.rs".to_string(),
limit: None,
current_file: None,
changed_with: None,
resolve: None,
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
!result.contains("vendor/foo/bar.rs"),
"glob search should suppress vendor by default: {result}"
);
assert!(
result.contains("1 vendor/personal-tooling path candidate hidden by default"),
"glob search should report suppressed vendor candidate: {result}"
);
assert!(
result.contains("filters: vendor filter active (heuristic); personal tooling filtered"),
"glob search output should disclose active filters: {result}"
);
}
#[tokio::test]
async fn test_search_files_resolve_returns_exact_match() {
let (key, file) = make_file("src/protocol/tools.rs", b"fn tool() {}", vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "src/protocol/tools.rs".to_string(),
limit: None,
current_file: None,
changed_with: None,
resolve: Some(true),
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
result.contains("Trust: exact (resolve) | current index | parsed"),
"got: {result}"
);
assert!(
result.contains("filters: vendor filter active (heuristic); personal tooling filtered"),
"resolve=true envelope should disclose active filters: {result}"
);
assert!(result.contains("src/protocol/tools.rs"), "got: {result}");
}
#[tokio::test]
async fn test_search_files_resolve_returns_ambiguous_matches() {
let server = make_server(make_live_index_ready(vec![
make_file("src/lib.rs", b"fn src_lib() {}", vec![]),
make_file("tests/lib.rs", b"fn test_lib() {}", vec![]),
]));
let result = server
.search_files(Parameters(super::SearchFilesInput {
projects: None,
project: None,
query: "lib.rs".to_string(),
limit: None,
current_file: None,
changed_with: None,
resolve: Some(true),
estimate: None,
max_tokens: None,
debug_ranking: None,
rank_by: None,
anchor_path: None,
include_vendor: None,
include_personal_tooling: None,
path_prefix: None,
}))
.await;
assert!(
result.contains("Ambiguous path hint 'lib.rs'"),
"got: {result}"
);
assert!(
result.contains("Trust: constrained (resolve candidates)"),
"got: {result}"
);
assert!(result.contains("src/lib.rs"), "got: {result}");
assert!(result.contains("tests/lib.rs"), "got: {result}");
assert!(
result.contains("filters: vendor filter active (heuristic); personal tooling filtered"),
"ambiguous resolve output should disclose active filters: {result}"
);
}
#[tokio::test]
async fn test_health_returns_status_fields() {
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.health(Parameters(super::HealthInput::default()))
.await;
assert!(result.contains("Status:"), "should have Status field");
assert!(result.contains("Files:"), "should have Files field");
assert!(result.contains("Symbols:"), "should have Symbols field");
}
#[tokio::test]
async fn test_health_surfaces_runtime_identity_for_fresh_local_process() {
let temp = TempDir::new().expect("tempdir should be created");
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(temp.path().to_path_buf()),
);
let result = server
.health(Parameters(super::HealthInput::default()))
.await;
assert!(
result.contains("Runtime: mode=local_process"),
"health should identify local runtime mode: {result}"
);
let root_text = server
.capture_repo_root()
.expect("test server should retain its canonical project root")
.to_string_lossy()
.replace('\\', "/");
assert!(
result.contains(&format!("project_root={root_text}")),
"health should identify active project root: {result}"
);
assert!(
result.contains("project_id=project-"),
"health should identify a stable project id: {result}"
);
assert!(
result.contains("session_id=local-process-"),
"health should identify the local session/process: {result}"
);
assert!(
result.contains("index_id=index-"),
"health should identify the active index: {result}"
);
assert!(
result.contains("load_source=fresh_load"),
"health should expose the load source: {result}"
);
assert!(
result.contains("reset_state=none"),
"fresh local health should not claim reset identity: {result}"
);
assert!(
result.contains("index_state=fresh_process"),
"fresh local health should distinguish a fresh process: {result}"
);
}
#[tokio::test]
async fn test_health_surfaces_runtime_identity_for_daemon_reused_session() {
let temp = TempDir::new().expect("tempdir should be created");
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(temp.path().to_path_buf()),
);
let project_id = "project-daemon-test".to_string();
let session_id = "session-daemon-test".to_string();
let root_text = temp.path().to_string_lossy().replace('\\', "/");
let full = server.health_for_daemon_session(
project_id.clone(),
session_id.clone(),
temp.path().to_path_buf(),
crate::protocol::format::QuarantineWindow::default(),
);
assert!(
full.contains("Runtime: mode=daemon_reused_session")
&& full.contains("runtime_state=daemon_reused_session"),
"full health should identify reused daemon runtime: {full}"
);
assert!(
full.contains(&format!("project_root={root_text}"))
&& full.contains(&format!("project_id={project_id}"))
&& full.contains(&format!("session_id={session_id}"))
&& full.contains("index_id=index-"),
"full health should expose daemon project/session/index identity: {full}"
);
assert!(
full.contains("load_source=fresh_load")
&& full.contains("reset_state=none")
&& full.contains("index_state=fresh_process"),
"full daemon health should distinguish fresh index state without reset: {full}"
);
let compact = server.health_compact_for_daemon_session(
project_id.clone(),
session_id.clone(),
temp.path().to_path_buf(),
);
assert!(
compact.contains("Runtime: mode=daemon_reused_session")
&& compact.contains(&format!("project_root={root_text}"))
&& compact.contains(&format!("project_id={project_id}"))
&& compact.contains(&format!("session_id={session_id}"))
&& compact.contains("index_id=index-"),
"compact health should retain daemon project/session/index identity: {compact}"
);
assert!(
compact.contains("load_source=fresh_load")
&& compact.contains("reset_state=none")
&& compact.contains("index_state=fresh_process"),
"compact daemon health should retain bounded source/reset state: {compact}"
);
}
/// M-001 smoke: the Feature 020 repository-knowledge section renders in both the
/// full and compact health reports, and compact stays genuinely compact.
#[tokio::test]
async fn m001_health_surfaces_repository_knowledge_section_full_and_compact() {
let temp = TempDir::new().expect("tempdir should be created");
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(temp.path().to_path_buf()),
);
let full = server.health_for_daemon_session(
"p".to_string(),
"s".to_string(),
temp.path().to_path_buf(),
crate::protocol::format::QuarantineWindow::default(),
);
for marker in [
"── Repository knowledge (Feature 020) ──",
"binding=bound",
"Manifest:",
"Source set: registry_generation=",
"Bridge: coverage=",
"Temporal: state=",
"Authority hygiene: rule_version=",
"live_postcondition=established",
"gitignore_hygiene=",
] {
assert!(
full.contains(marker),
"full health missing `{marker}`: {full}"
);
}
let compact = server.health_compact_for_daemon_session(
"p".to_string(),
"s".to_string(),
temp.path().to_path_buf(),
);
assert!(
compact.contains("Source binding: binding=bound"),
"compact health must carry the binding summary: {compact}"
);
assert!(
compact.contains("Knowledge: manifest="),
"compact health must carry a one-line knowledge digest: {compact}"
);
assert!(
!compact.contains("── Repository knowledge (Feature 020) ──"),
"compact health must not expand the full section header: {compact}"
);
}
/// M-002(c): health reflects a project moving from unbound to a bound state on
/// the same runtime.
#[tokio::test]
async fn m002_health_reflects_unbound_to_bound_transition() {
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let unbound = server.health_for_runtime(
crate::protocol::format::RuntimeMode::LocalProcess,
None,
None,
None,
crate::protocol::format::QuarantineWindow::default(),
);
assert!(
unbound.contains("binding=unbound"),
"unbound health must report an unbound binding: {unbound}"
);
assert!(
!unbound.contains("authorization="),
"unbound health must omit the bound-only authorization token: {unbound}"
);
// A local (non-daemon) render must show local_process membership — proving
// the membership label actually varies (the daemon path shows `member`),
// not a constant. The real L-R11 non-inheritance is proven in
// daemon::tests::protected_membership_is_per_session_and_requires_each_direct_override.
assert!(
unbound.contains("membership=local_process"),
"a local render must show local_process membership, not member: {unbound}"
);
// Bind the same server to a project-local root.
let temp = TempDir::new().expect("tempdir should be created");
*server.repo_root.write() = Some(temp.path().to_path_buf());
*server.state_placement.write() = Some(crate::domain::StatePlacement::ProjectLocal {
directory: project_state(temp.path()),
});
*server.persistence_health.write() = crate::domain::CapabilityStatus::Available;
let bound = server.health_for_runtime(
crate::protocol::format::RuntimeMode::LocalProcess,
None,
None,
None,
crate::protocol::format::QuarantineWindow::default(),
);
assert!(
bound.contains("binding=bound") && bound.contains("placement=project_local"),
"bound health must report a bound project-local binding: {bound}"
);
}
/// M-002(d): a daemon session bound to an explicit-protected source is reported
/// as a member, with `explicit_protected` authorization — consistent with the
/// L-R11 per-session membership model.
#[tokio::test]
async fn m002_health_shows_per_session_protected_membership() {
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let temp = TempDir::new().expect("tempdir should be created");
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(temp.path().to_path_buf()),
);
// Model an explicit-protected binding: it lands in user-local placement
// (skips the project-local probe), which is how health derives authorization.
*server.state_placement.write() = Some(crate::domain::StatePlacement::UserLocal {
directory: project_state(temp.path()),
root_id: crate::domain::ProjectId("project-protected-test".to_string()),
reason: crate::domain::UserLocalPlacementReason::ExplicitProtected,
});
let session_id = "session-protected-a".to_string();
let health = server.health_for_daemon_session(
"project-protected-test".to_string(),
session_id.clone(),
temp.path().to_path_buf(),
crate::protocol::format::QuarantineWindow::default(),
);
assert!(
health.contains("authorization=explicit_protected"),
"protected binding must surface explicit_protected authorization: {health}"
);
assert!(
health.contains(&format!("session={session_id} membership=member")),
"a daemon session must be reported a member of its bound project: {health}"
);
}
/// M-002(e): post-bind durability degradation is reported independently from
/// query readiness — a durable placement that loses atomic durability shows a
/// degraded persistence/replay while the live query surface stays ready.
#[tokio::test]
async fn m002_post_bind_durability_degradation_is_independent_of_query_readiness() {
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let temp = TempDir::new().expect("tempdir should be created");
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(temp.path().to_path_buf()),
);
// A healthy placement loses atomic durability after binding.
*server.persistence_health.write() = crate::domain::CapabilityStatus::Unavailable {
reason: crate::domain::CapabilityUnavailableReason::AtomicDurabilityUnavailable,
};
let health = server.health_for_daemon_session(
"project-e".to_string(),
"session-e".to_string(),
temp.path().to_path_buf(),
crate::protocol::format::QuarantineWindow::default(),
);
assert!(
health.contains("persistence=degraded(atomic_durability_unavailable)"),
"durability degradation must be surfaced: {health}"
);
assert!(
health.contains("query_readiness=ready"),
"query readiness must stay ready independent of durability: {health}"
);
assert!(
health.contains("replay=unavailable"),
"durable replay must follow persistence, not readiness: {health}"
);
}
#[tokio::test]
async fn test_health_surfaces_runtime_identity_for_warm_snapshot_reuse() {
let temp = TempDir::new().expect("tempdir should be created");
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let mut index = make_live_index_ready(vec![(key, file)]);
index.load_source = crate::live_index::store::IndexLoadSource::SnapshotRestore;
let server = make_server_with_root(index, Some(temp.path().to_path_buf()));
let full = server
.health(Parameters(super::HealthInput::default()))
.await;
assert!(
full.contains("load_source=snapshot_restore")
&& full.contains("reset_state=none")
&& full.contains("index_state=snapshot_loaded_reused"),
"full health should distinguish warm snapshot reuse without reset: {full}"
);
let compact = server.health_compact().await;
assert!(
compact.contains("load_source=snapshot_restore")
&& compact.contains("reset_state=none")
&& compact.contains("index_state=snapshot_loaded_reused"),
"compact health should retain warm snapshot source/reset state: {compact}"
);
}
#[tokio::test]
async fn test_checkpoint_now_writes_snapshot_and_reports_success() {
let temp = TempDir::new().expect("tempdir should be created");
fs::create_dir_all(temp.path().join("src")).expect("create fixture source dir");
fs::write(temp.path().join("src/lib.rs"), b"fn foo() {}\n").expect("write fixture source");
let (key, file) = make_file("src/lib.rs", b"fn foo() {}\n", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(temp.path().to_path_buf()),
);
let result = server
.checkpoint_now(Parameters(super::CheckpointNowInput {
verify_after_write: Some(true),
export_artifact: None,
}))
.await;
assert!(
result.contains("Checkpoint complete"),
"checkpoint should report success: {result}"
);
// Guard (review finding 2): the degraded-fallback disclosure is ONLY
// for daemon-proxy fallback; a plain local checkpoint must not carry it.
assert!(
!result.contains("daemon unreachable"),
"local-mode checkpoint must not claim a daemon fallback: {result}"
);
assert!(
temp.path().join(".symforge").join("index.bin").exists(),
"checkpoint_now should create .symforge/index.bin"
);
assert!(
crate::live_index::persist::load_snapshot(
temp.path(),
&server
.capture_state_placement()
.expect("fixture server should retain resolved state placement"),
)
.is_some(),
"checkpoint_now should write a readable snapshot"
);
}
/// C-S1A-006: `export_artifact=true` additionally writes the Best-tier
/// team artifact (contracts/team-artifact.md § Tiers, A-US2-01/04).
#[tokio::test]
async fn test_checkpoint_now_export_artifact_writes_team_artifact() {
let temp = TempDir::new().expect("tempdir should be created");
fs::create_dir_all(temp.path().join("src")).expect("create fixture source dir");
fs::write(temp.path().join("src/lib.rs"), b"fn foo() {}\n").expect("write fixture source");
let (key, file) = make_file("src/lib.rs", b"fn foo() {}\n", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(temp.path().to_path_buf()),
);
let result = server
.checkpoint_now(Parameters(super::CheckpointNowInput {
verify_after_write: None,
export_artifact: Some(true),
}))
.await;
assert!(
result.contains("Checkpoint complete"),
"checkpoint should report success: {result}"
);
assert!(
result.contains("Artifact exported"),
"export_artifact=true should report the artifact export: {result}"
);
assert!(
result.contains("git_visibility=git_visibility_unavailable"),
"artifact receipt must disclose its exact Git visibility: {result}"
);
assert!(
temp.path()
.join(".symforge")
.join(crate::live_index::persist::ARTIFACT_FILENAME)
.exists(),
"checkpoint_now(export_artifact=true) should create .symforge/index.bin.zst"
);
assert!(
temp.path()
.join(".symforge")
.join(crate::live_index::persist::ARTIFACT_METADATA_FILENAME)
.exists(),
"checkpoint_now(export_artifact=true) should create .symforge/artifact.json"
);
}
#[tokio::test]
async fn test_checkpoint_now_reports_failure_without_success_text() {
let temp = TempDir::new().expect("tempdir should be created");
fs::create_dir_all(temp.path().join("src")).expect("create fixture source dir");
fs::write(temp.path().join("src/lib.rs"), b"fn foo() {}\n").expect("write fixture source");
let (key, file) = make_file("src/lib.rs", b"fn foo() {}\n", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(temp.path().to_path_buf()),
);
fs::remove_dir_all(temp.path().join(".symforge"))
.expect("remove resolved project state directory");
fs::write(temp.path().join(".symforge"), b"not a directory")
.expect("block .symforge directory creation");
let result = server
.checkpoint_now(Parameters(super::CheckpointNowInput::default()))
.await;
assert!(
result.contains("Checkpoint failed"),
"checkpoint write failure should be explicit: {result}"
);
assert!(
!result.contains("Checkpoint complete"),
"failure output must not contain success text: {result}"
);
}
#[tokio::test]
async fn test_health_surfaces_alive_sidecar_pid_and_state() {
let temp = TempDir::new().expect("tempdir should be created");
let control_state_dir = crate::domain::ControlStateDir::new(temp.path().join("control"));
let listener = std::net::TcpListener::bind("127.0.0.1:0")
.expect("test listener should bind to an ephemeral port");
let port = listener
.local_addr()
.expect("test listener should have a local address")
.port();
write_sidecar_state(&control_state_dir, Some(port), Some("4242"));
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(temp.path().to_path_buf()),
)
.with_control_state_dir_for_test(control_state_dir);
let result = server
.health(Parameters(super::HealthInput::default()))
.await;
assert!(
result.contains(&format!("Sidecar: pid=4242 port={port} state=alive")),
"full health should surface alive sidecar state: {result}"
);
}
#[tokio::test]
async fn test_health_distinguishes_no_sidecar_state() {
let temp = TempDir::new().expect("tempdir should be created");
let control_state_dir = crate::domain::ControlStateDir::new(temp.path().join("control"));
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(temp.path().to_path_buf()),
)
.with_control_state_dir_for_test(control_state_dir);
let result = server
.health(Parameters(super::HealthInput::default()))
.await;
assert!(
result.contains("Sidecar: none"),
"full health should distinguish no sidecar state: {result}"
);
}
#[tokio::test]
async fn test_health_compact_keeps_core_fields_small() {
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server.health_compact().await;
assert!(result.contains("Status:"), "should have Status field");
assert!(result.contains("Files:"), "should have Files field");
assert!(result.contains("Symbols:"), "should have Symbols field");
assert!(
result.contains("Runtime: mode=local_process"),
"compact health should retain runtime identity: {result}"
);
assert!(
result.contains("index_id=index-"),
"compact health should retain index identity: {result}"
);
assert!(
result.contains("load_source=fresh_load")
&& result.contains("reset_state=none")
&& result.contains("index_state=fresh_process"),
"compact health should retain bounded source/reset state: {result}"
);
assert!(
!result.contains("Partial parse files"),
"compact health should omit expanded path lists"
);
assert!(
!result.contains("Snapshot:"),
"fresh compact health should omit snapshot verification lines"
);
}
#[test]
fn test_current_exe_shadow_report_sources_our_version_from_package() {
// Item 6c: our version must come from the compile-time package version,
// not a flaky `<binary> --version` subprocess probe. This keeps the
// full and compact health surfaces consistent (no "(version unknown)"
// on one and the real version on the other). When no shadow exists the
// report is None and the invariant holds vacuously.
if let Some(report) = super::current_exe_shadow_report() {
assert_eq!(
report.our_version.as_deref(),
Some(env!("CARGO_PKG_VERSION")),
"our_version must be the compile-time package version, never an unknown probe result"
);
}
}
#[tokio::test]
async fn test_health_surfaces_snapshot_verify_running_state() {
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let mut index = make_live_index_ready(vec![(key, file)]);
index.load_source = crate::live_index::store::IndexLoadSource::SnapshotRestore;
index.snapshot_verify_state = crate::live_index::store::SnapshotVerifyState::Running;
let server = make_server(index);
let full = server
.health(Parameters(super::HealthInput::default()))
.await;
assert!(
full.contains("Snapshot verify: load_source=snapshot_restore state=running"),
"full health should expose background snapshot verification progress: {full}"
);
let compact = server.health_compact().await;
assert!(
compact.contains("Snapshot: load_source=snapshot_restore verify=running"),
"compact health should retain snapshot verify progress: {compact}"
);
}
#[tokio::test]
async fn test_health_surfaces_snapshot_verify_mismatch_summary() {
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let mut index = make_live_index_ready(vec![(key, file)]);
index.load_source = crate::live_index::store::IndexLoadSource::SnapshotRestore;
index.snapshot_verify_state =
crate::live_index::store::SnapshotVerifyState::completed_with_mismatches(
(0..12)
.rev()
.map(|i| format!("src/mismatch_{i:02}.rs"))
.collect::<Vec<_>>(),
);
let server = make_server(index);
let full = server
.health(Parameters(super::HealthInput::default()))
.await;
assert!(
full.contains(
"Snapshot verify: load_source=snapshot_restore state=completed mismatches=12 showing=10 omitted=2",
),
"full health should expose mismatch count and truncation: {full}"
);
assert!(
full.contains("src/mismatch_00.rs") && full.contains("src/mismatch_09.rs"),
"full health should include bounded mismatch path examples: {full}"
);
assert!(
!full.contains("src/mismatch_10.rs"),
"full health should truncate mismatch path examples: {full}"
);
let compact = server.health_compact().await;
assert!(
compact.contains(
"Snapshot: load_source=snapshot_restore verify=completed mismatches=12 showing=3 omitted=9",
),
"compact health should retain bounded mismatch summary: {compact}"
);
assert!(
compact.contains("src/mismatch_00.rs") && !compact.contains("src/mismatch_03.rs"),
"compact health should include only compact path examples: {compact}"
);
}
#[tokio::test]
async fn test_health_compact_surfaces_dead_sidecar_pid_and_state() {
let temp = TempDir::new().expect("tempdir should be created");
let control_state_dir = crate::domain::ControlStateDir::new(temp.path().join("control"));
let port = 0;
write_sidecar_state(&control_state_dir, Some(port), Some("4242"));
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(temp.path().to_path_buf()),
)
.with_control_state_dir_for_test(control_state_dir);
let result = server.health_compact().await;
assert!(
result.contains(&format!("Sidecar: dead pid=4242 port={port}")),
"compact health should surface dead sidecar state: {result}"
);
}
#[tokio::test]
async fn test_health_surfaces_unknown_sidecar_state_for_malformed_port_file() {
let temp = TempDir::new().expect("tempdir should be created");
let control_state_dir = crate::domain::ControlStateDir::new(temp.path().join("control"));
let dir = crate::sidecar::port_file::ensure_symforge_dir(&control_state_dir)
.expect("test control state should allow sidecar namespace creation");
fs::write(dir.join("sidecar.port"), "not-a-port")
.expect("sidecar port file should be writable");
fs::write(dir.join("sidecar.pid"), "4242").expect("sidecar pid file should be writable");
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(temp.path().to_path_buf()),
)
.with_control_state_dir_for_test(control_state_dir);
let result = server
.health(Parameters(super::HealthInput::default()))
.await;
assert!(
result.contains("Sidecar: pid=4242 port=unknown state=unknown"),
"full health should surface unknown sidecar state: {result}"
);
assert!(
result.contains("sidecar.port invalid"),
"full health should explain malformed sidecar state: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_batch_symbol_lookup() {
let sym = make_symbol("bar", SymbolKind::Function, 1, 3);
let (key, file) = make_file("src/lib.rs", b"fn bar() {}", vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_symbol(Parameters(super::GetSymbolInput {
project: None,
path: String::new(),
name: String::new(),
kind: None,
symbol_line: None,
targets: Some(vec![super::SymbolTarget {
path: "src/lib.rs".to_string(),
name: Some("bar".to_string()),
kind: None,
symbol_line: None,
start_byte: None,
end_byte: None,
}]),
estimate: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert!(
!result.starts_with("Index"),
"should not return guard message, got: {result}"
);
assert!(
result.contains("fn bar() {"),
"symbol lookup branch should return symbol body, got: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_batch_code_slice() {
let content = b"fn foo() { let x = 1; }";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_symbol(Parameters(super::GetSymbolInput {
project: None,
path: String::new(),
name: String::new(),
kind: None,
symbol_line: None,
targets: Some(vec![super::SymbolTarget {
path: "src/lib.rs".to_string(),
name: None,
kind: None,
symbol_line: None,
start_byte: Some(0),
end_byte: Some(8),
}]),
estimate: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert!(
result.contains("src/lib.rs"),
"code slice should include path header, got: {result}"
);
assert!(
result.contains("fn foo()"),
"code slice should include content, got: {result}"
);
}
#[tokio::test]
async fn test_what_changed_returns_result() {
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
// since=0 (far past) → all files are "newer"
let result = server
.what_changed(Parameters(super::WhatChangedInput {
project: None,
since: Some(0),
git_ref: None,
uncommitted: None,
path_prefix: None,
language: None,
code_only: None,
include_symbol_diff: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("src/lib.rs"),
"what_changed since epoch should list all files, got: {result}"
);
assert!(
result.contains("Trust: exact (timestamp compare) | current index | parsed"),
"timestamp mode should report the compact trust line: {result}"
);
}
#[tokio::test]
async fn test_what_changed_timestamp_respects_filters() {
let (rust_key, rust_file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let (doc_key, doc_file) = make_file("docs/readme.md", b"# hi", vec![]);
let server = make_server(make_live_index_ready(vec![
(rust_key, rust_file),
(doc_key, doc_file),
]));
let result = server
.what_changed(Parameters(super::WhatChangedInput {
project: None,
since: Some(0),
git_ref: None,
uncommitted: None,
path_prefix: Some("src".to_string()),
language: Some("rust".to_string()),
code_only: None,
include_symbol_diff: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("src/lib.rs"),
"filtered timestamp mode should keep Rust path: {result}"
);
assert!(
!result.contains("docs/readme.md"),
"filtered timestamp mode should exclude non-matching path: {result}"
);
assert!(
result.contains("Scope: timestamp since `0`; path prefix `src`; language `rust`"),
"filtered timestamp mode should expose scope: {result}"
);
}
#[tokio::test]
async fn test_what_changed_defaults_to_uncommitted_git_changes() {
let repo = init_git_repo();
fs::create_dir_all(repo.path().join("src")).expect("create src dir");
fs::write(repo.path().join("src/lib.rs"), "fn foo() {}\n").expect("write initial file");
run_git(repo.path(), &["add", "."]);
run_git(repo.path(), &["commit", "-m", "init", "-q"]);
fs::write(
repo.path().join("src/lib.rs"),
"fn foo() { println!(\"changed\"); }\n",
)
.expect("modify tracked file");
let (key, file) = make_file(
"src/lib.rs",
b"fn foo() { println!(\"changed\"); }\n",
vec![],
);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(repo.path().to_path_buf()),
);
let result = server
.what_changed(Parameters(super::WhatChangedInput {
project: None,
since: None,
git_ref: None,
uncommitted: None,
path_prefix: None,
language: None,
code_only: None,
include_symbol_diff: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("src/lib.rs"),
"default mode should surface uncommitted git changes: {result}"
);
assert!(
result.contains("Source authority: git working tree"),
"uncommitted mode should expose git authority: {result}"
);
}
#[tokio::test]
async fn test_what_changed_include_symbol_diff_appends_compact_symbol_summary() {
let repo = init_git_repo();
fs::create_dir_all(repo.path().join("src")).expect("create src dir");
fs::create_dir_all(repo.path().join("docs")).expect("create docs dir");
fs::write(repo.path().join("src/lib.rs"), "fn existing() {}\n")
.expect("write initial file");
fs::write(repo.path().join("docs/readme.md"), "# initial\n").expect("write initial docs");
run_git(repo.path(), &["add", "."]);
run_git(repo.path(), &["commit", "-m", "init", "-q"]);
fs::write(
repo.path().join("src/lib.rs"),
"fn existing() {}\nfn added_symbol() {}\n",
)
.expect("modify tracked code file");
fs::write(repo.path().join("docs/readme.md"), "# changed\n")
.expect("modify tracked docs file");
let (key, file) = make_file(
"src/lib.rs",
b"fn existing() {}\nfn added_symbol() {}\n",
vec![],
);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(repo.path().to_path_buf()),
);
let result = server
.what_changed(Parameters(super::WhatChangedInput {
project: None,
since: None,
git_ref: None,
uncommitted: Some(true),
path_prefix: None,
language: None,
code_only: Some(true),
include_symbol_diff: Some(true),
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains(
"Scope: uncommitted working tree; code-only filter; symbol diff appended"
),
"scope should report the combined code-only symbol-diff mode: {result}"
);
assert!(
result.contains("Symbol diff: HEAD...working tree"),
"symbol diff section missing: {result}"
);
assert!(
result.contains("src/lib.rs (+1: added_symbol)"),
"compact symbol summary should name added symbols: {result}"
);
assert!(
!result.contains("docs/readme.md"),
"code_only must keep docs out of both path list and symbol diff: {result}"
);
}
#[tokio::test]
async fn test_what_changed_recovers_repo_root_from_cwd_when_missing() {
let repo = init_git_repo();
fs::create_dir_all(repo.path().join("src")).expect("create src dir");
fs::write(repo.path().join("src/lib.rs"), "fn foo() {}\n").expect("write initial file");
run_git(repo.path(), &["add", "."]);
run_git(repo.path(), &["commit", "-m", "init", "-q"]);
fs::write(
repo.path().join("src/lib.rs"),
"fn foo() { println!(\"changed\"); }\n",
)
.expect("modify tracked file");
let (key, file) = make_file(
"src/lib.rs",
b"fn foo() { println!(\"changed\"); }\n",
vec![],
);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let _cwd_guard = CwdGuard::set(repo.path());
let result = server
.what_changed(Parameters(super::WhatChangedInput {
project: None,
since: None,
git_ref: None,
uncommitted: None,
path_prefix: None,
language: None,
code_only: None,
include_symbol_diff: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("src/lib.rs"),
"what_changed should lazily recover the git root from cwd: {result}"
);
assert!(
result.contains("Source authority: git working tree"),
"recovered git mode should expose git authority: {result}"
);
}
#[tokio::test]
async fn test_what_changed_reports_repo_root_guidance_when_missing() {
let home = dirs::home_dir().expect("home dir");
let _cwd_guard = CwdGuard::set(&home);
let server = make_server(make_live_index_empty());
let result = server
.what_changed(Parameters(super::WhatChangedInput {
project: None,
since: None,
git_ref: None,
uncommitted: None,
path_prefix: None,
language: None,
code_only: None,
include_symbol_diff: None,
estimate: None,
max_tokens: None,
}))
.await;
// Surface-aware guidance (TR-02 / FR-012): `since=` is always offered;
// `index_folder` is named only on the full/meta surface where it is
// callable, never on the compact surface where it is dispatch-gated.
assert!(
result.contains("No repo root attached;"),
"missing repo root should return actionable guidance: {result}"
);
assert!(
result.contains("pass since=..."),
"guidance must always offer the surface-neutral `since=` recovery: {result}"
);
match crate::protocol::surface_probe::surface_profile_from_env() {
crate::protocol::surface_probe::SurfaceProfile::Compact => assert!(
!result.contains("index_folder"),
"compact guidance must not name the gated index_folder tool: {result}"
),
crate::protocol::surface_probe::SurfaceProfile::Full
| crate::protocol::surface_probe::SurfaceProfile::Meta => assert!(
result.contains("call index_folder(path=...)"),
"full/meta guidance may name index_folder: {result}"
),
}
}
#[tokio::test]
async fn test_what_changed_git_ref_reports_diffed_files() {
let repo = init_git_repo();
fs::create_dir_all(repo.path().join("src")).expect("create src dir");
fs::write(repo.path().join("src/lib.rs"), "fn foo() {}\n").expect("write initial file");
run_git(repo.path(), &["add", "."]);
run_git(repo.path(), &["commit", "-m", "init", "-q"]);
fs::write(
repo.path().join("src/lib.rs"),
"fn foo() { println!(\"changed\"); }\n",
)
.expect("modify tracked file");
let (key, file) = make_file(
"src/lib.rs",
b"fn foo() { println!(\"changed\"); }\n",
vec![],
);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(repo.path().to_path_buf()),
);
let result = server
.what_changed(Parameters(super::WhatChangedInput {
project: None,
since: None,
git_ref: Some("HEAD".to_string()),
uncommitted: None,
path_prefix: None,
language: None,
code_only: None,
include_symbol_diff: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("src/lib.rs"),
"git_ref mode should show changed files: {result}"
);
assert!(
result.contains("Source authority: git ref diff"),
"git_ref mode should expose git diff authority: {result}"
);
}
// ── US1 (018): source-focused change/impact defaults ──────────────────────
/// FR-001 / SC-001: with only a dirty non-source data file uncommitted, the
/// DEFAULT `what_changed` (uncommitted mode, `code_only` unset) is now
/// source-focused and reports zero code changes. Fails on pre-fix code (which
/// listed the data path).
#[tokio::test]
async fn test_what_changed_uncommitted_default_excludes_data_files() {
let repo = init_git_repo();
fs::create_dir_all(repo.path().join("src")).expect("create src dir");
fs::write(repo.path().join("src/lib.rs"), "fn foo() {}\n").expect("write initial file");
run_git(repo.path(), &["add", "."]);
run_git(repo.path(), &["commit", "-m", "init", "-q"]);
// The only uncommitted change is an untracked non-source data file — the
// reported noise source (untracked *.json).
fs::create_dir_all(repo.path().join("data")).expect("create data dir");
fs::write(repo.path().join("data/config.json"), "{\n \"key\": 1\n}\n")
.expect("write data file");
let (key, file) = make_file("src/lib.rs", b"fn foo() {}\n", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(repo.path().to_path_buf()),
);
let result = server
.what_changed(Parameters(super::WhatChangedInput {
project: None,
since: None,
git_ref: None,
uncommitted: None,
path_prefix: None,
language: None,
code_only: None,
include_symbol_diff: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
!result.contains("data/config.json"),
"default uncommitted mode must be source-focused and exclude data files: {result}"
);
assert!(
result.contains("No uncommitted changes matched the requested filters."),
"with only a data file dirty, default uncommitted mode reports no code changes: {result}"
);
}
/// FR-003 (opt-in preserved): the SAME uncommitted call with explicit
/// `code_only=false` still surfaces the data file — the fix moves the default,
/// it does not remove the inclusive path. Green before and after the fix.
#[tokio::test]
async fn test_what_changed_uncommitted_explicit_code_only_false_includes_data() {
let repo = init_git_repo();
fs::create_dir_all(repo.path().join("src")).expect("create src dir");
fs::write(repo.path().join("src/lib.rs"), "fn foo() {}\n").expect("write initial file");
run_git(repo.path(), &["add", "."]);
run_git(repo.path(), &["commit", "-m", "init", "-q"]);
fs::create_dir_all(repo.path().join("data")).expect("create data dir");
fs::write(repo.path().join("data/config.json"), "{\n \"key\": 1\n}\n")
.expect("write data file");
let (key, file) = make_file("src/lib.rs", b"fn foo() {}\n", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(repo.path().to_path_buf()),
);
let result = server
.what_changed(Parameters(super::WhatChangedInput {
project: None,
since: None,
git_ref: None,
uncommitted: None,
path_prefix: None,
language: None,
code_only: Some(false),
include_symbol_diff: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("data/config.json"),
"explicit code_only=false must restore full inclusion (opt-in preserved): {result}"
);
}
/// FR-001 edge case: the default flip targets ONLY uncommitted mode.
/// Timestamp mode keeps `code_only` defaulting to false, so a data path still
/// appears by default. Guard test — must stay green after the flip.
#[tokio::test]
async fn test_what_changed_timestamp_default_keeps_data_files() {
let (rust_key, rust_file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let (json_key, json_file) = make_file("data/config.json", b"{\"k\":1}", vec![]);
let server = make_server(make_live_index_ready(vec![
(rust_key, rust_file),
(json_key, json_file),
]));
let result = server
.what_changed(Parameters(super::WhatChangedInput {
project: None,
since: Some(0),
git_ref: None,
uncommitted: None,
path_prefix: None,
language: None,
code_only: None,
include_symbol_diff: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("data/config.json"),
"timestamp mode default must be UNCHANGED by the uncommitted flip (data still listed): {result}"
);
assert!(
result.contains("src/lib.rs"),
"timestamp mode default still lists source: {result}"
);
}
/// FR-001 edge case (committed diff): git_ref mode keeps `code_only`
/// defaulting to false, so a changed data path still appears by default. Guard
/// test — must stay green after the flip.
#[tokio::test]
async fn test_what_changed_git_ref_default_keeps_data_files() {
let repo = init_git_repo();
fs::create_dir_all(repo.path().join("data")).expect("create data dir");
fs::write(repo.path().join("data/config.json"), "{\"k\":1}\n").expect("write initial data");
run_git(repo.path(), &["add", "."]);
run_git(repo.path(), &["commit", "-m", "init", "-q"]);
fs::write(repo.path().join("data/config.json"), "{\"k\":2}\n").expect("modify data file");
let (key, file) = make_file("data/config.json", b"{\"k\":2}\n", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(repo.path().to_path_buf()),
);
let result = server
.what_changed(Parameters(super::WhatChangedInput {
project: None,
since: None,
git_ref: Some("HEAD".to_string()),
uncommitted: None,
path_prefix: None,
language: None,
code_only: None,
include_symbol_diff: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("data/config.json"),
"git_ref mode default must be UNCHANGED by the uncommitted flip (data still listed): {result}"
);
}
/// FR-001 + Constitution III: a default uncommitted call with a real source
/// change AND a dirty data file shows the source change, excludes the data
/// file, and HONESTLY discloses the applied code-only filter in the envelope.
#[tokio::test]
async fn test_what_changed_uncommitted_default_discloses_code_only_filter() {
let repo = init_git_repo();
fs::create_dir_all(repo.path().join("src")).expect("create src dir");
fs::write(repo.path().join("src/lib.rs"), "fn foo() {}\n").expect("write initial file");
run_git(repo.path(), &["add", "."]);
run_git(repo.path(), &["commit", "-m", "init", "-q"]);
// A genuine source edit plus a dirty untracked data file.
fs::write(
repo.path().join("src/lib.rs"),
"fn foo() { println!(\"changed\"); }\n",
)
.expect("modify source file");
fs::create_dir_all(repo.path().join("data")).expect("create data dir");
fs::write(repo.path().join("data/config.json"), "{\n \"key\": 1\n}\n")
.expect("write data file");
let (key, file) = make_file(
"src/lib.rs",
b"fn foo() { println!(\"changed\"); }\n",
vec![],
);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(repo.path().to_path_buf()),
);
let result = server
.what_changed(Parameters(super::WhatChangedInput {
project: None,
since: None,
git_ref: None,
uncommitted: None,
path_prefix: None,
language: None,
code_only: None,
include_symbol_diff: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("src/lib.rs"),
"default uncommitted mode still surfaces the source change: {result}"
);
assert!(
!result.contains("data/config.json"),
"default uncommitted mode excludes the data file: {result}"
);
assert!(
result.contains("code-only filter"),
"the applied source-focus filter must be disclosed in the envelope (III trust): {result}"
);
}
/// Recovered finding #2: when the source-focus default filters EVERY changed
/// path away, the empty result must disclose that filtering happened and how
/// to widen it — a bare "no changes matched" hides the default filter.
#[tokio::test]
async fn test_what_changed_uncommitted_empty_result_discloses_source_filter() {
let repo = init_git_repo();
fs::create_dir_all(repo.path().join("src")).expect("create src dir");
fs::write(repo.path().join("src/lib.rs"), "fn foo() {}\n").expect("write initial file");
run_git(repo.path(), &["add", "."]);
run_git(repo.path(), &["commit", "-m", "init", "-q"]);
fs::create_dir_all(repo.path().join("data")).expect("create data dir");
fs::write(repo.path().join("data/config.json"), "{\n \"key\": 1\n}\n")
.expect("write data file");
let (key, file) = make_file("src/lib.rs", b"fn foo() {}\n", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(repo.path().to_path_buf()),
);
let result = server
.what_changed(Parameters(super::WhatChangedInput {
project: None,
since: None,
git_ref: None,
uncommitted: None,
path_prefix: None,
language: None,
code_only: None,
include_symbol_diff: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("filtered out"),
"an empty filtered result must disclose that paths were excluded: {result}"
);
assert!(
result.contains("code_only=false"),
"the empty filtered result must name the recovery lever: {result}"
);
}
/// Recovered finding #3: `code_only` filtering must not classify legitimate
/// unknown-extension source files (.sql/.sh/.ps1/.proto/.tf, Dockerfile,
/// Makefile) as non-source data.
#[test]
fn test_code_only_keeps_unknown_extension_source_files() {
let paths = vec![
"src/lib.rs".to_string(),
"migrations/001_init.sql".to_string(),
"scripts/deploy.sh".to_string(),
"scripts/build.ps1".to_string(),
"proto/api.proto".to_string(),
"infra/main.tf".to_string(),
"Dockerfile".to_string(),
"Makefile".to_string(),
"data/config.json".to_string(),
];
let filtered = super::filter_paths_by_prefix_and_language(paths, None, None, true)
.expect("code_only filter");
for kept in [
"src/lib.rs",
"migrations/001_init.sql",
"scripts/deploy.sh",
"scripts/build.ps1",
"proto/api.proto",
"infra/main.tf",
"Dockerfile",
"Makefile",
] {
assert!(
filtered.iter().any(|p| p == kept),
"code_only must keep source file {kept}, got: {filtered:?}"
);
}
assert!(
!filtered.iter().any(|p| p == "data/config.json"),
"code_only still excludes data files: {filtered:?}"
);
}
/// Recovered finding #1: `detect_impact`'s default source-focus filter must
/// disclose how many changed paths it excluded and the recovery lever.
#[tokio::test]
async fn test_detect_impact_default_discloses_source_filtered_paths() {
let repo = init_git_repo();
fs::create_dir_all(repo.path().join("src")).expect("create src dir");
fs::write(repo.path().join("src/lib.rs"), "fn foo() {}\n").expect("write initial file");
run_git(repo.path(), &["add", "."]);
run_git(repo.path(), &["commit", "-m", "init", "-q"]);
// The only change is an untracked non-source data file.
fs::create_dir_all(repo.path().join("data")).expect("create data dir");
fs::write(repo.path().join("data/config.json"), "{\n \"key\": 1\n}\n")
.expect("write data file");
let (key, file) = make_file("src/lib.rs", b"fn foo() {}\n", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(repo.path().to_path_buf()),
);
let result = server
.detect_impact(Parameters(super::DetectImpactInput {
base_branch: None,
since: Some("WORKTREE".to_string()),
depth: 2,
scope: super::ImpactScope::Files,
include_untracked: true,
include_data: None,
}))
.await;
assert!(
!result.contains("data/config.json"),
"default detect_impact stays source-focused: {result}"
);
assert!(
result.contains("source_filter"),
"the applied source filter must be disclosed in the payload: {result}"
);
assert!(
result.contains("include_data"),
"the disclosure must name the include_data recovery lever: {result}"
);
}
/// PART C (019 detect_impact fix): scope=symbols blast entries must carry
/// disambiguating identity (path), so two entry points named `main` in
/// different files render as DISTINCT lines instead of collapsing into two
/// indistinguishable `"main"` entries. RED on the pre-fix formatter, which
/// emitted only `node.symbol.name`.
#[tokio::test]
async fn test_detect_impact_symbols_scope_disambiguates_same_name_nodes() {
let repo = init_git_repo();
fs::create_dir_all(repo.path().join("src")).expect("create src dir");
// Commit a base `core`, then modify it in the working tree so core.rs
// is a changed SOURCE file that seeds the blast.
fs::write(
repo.path().join("src/core.rs"),
"pub fn core() -> u32 { 1 }\n",
)
.expect("write core");
run_git(repo.path(), &["add", "."]);
run_git(repo.path(), &["commit", "-m", "init", "-q"]);
fs::write(
repo.path().join("src/core.rs"),
"pub fn core() -> u32 { 2 }\n",
)
.expect("modify core");
// Index: `core` plus two files whose `main` (enclosing index 0) calls it.
// `core` is a UNIQUE name -> PART B one-def rule links both callers.
let core_file = make_file(
"src/core.rs",
b"pub fn core() -> u32 { 2 }\n",
vec![make_symbol("core", SymbolKind::Function, 0, 0)],
);
let a_file = make_file_with_refs(
"src/a.rs",
b"fn main() { core(); }\n",
vec![make_symbol("main", SymbolKind::Function, 0, 0)],
vec![make_ref("core", None, ReferenceKind::Call, 0, Some(0))],
);
let b_file = make_file_with_refs(
"src/b.rs",
b"fn main() { core(); }\n",
vec![make_symbol("main", SymbolKind::Function, 0, 0)],
vec![make_ref("core", None, ReferenceKind::Call, 0, Some(0))],
);
let server = make_server_with_root(
make_live_index_ready(vec![core_file, a_file, b_file]),
Some(repo.path().to_path_buf()),
);
let result = server
.detect_impact(Parameters(super::DetectImpactInput {
base_branch: None,
since: Some("WORKTREE".to_string()),
depth: 2,
scope: super::ImpactScope::Symbols,
include_untracked: true,
include_data: None,
}))
.await;
// Both `main` entry points are in the blast; their labels must be
// distinct (path-qualified), not two bare `"main"` collapses.
assert!(
result.contains("src/a.rs::main") && result.contains("src/b.rs::main"),
"two same-name blast nodes must render as distinct path-qualified \
entries: {result}"
);
}
/// PART A (019 detect_impact fix): the seed must be a BODY delta, not every
/// symbol of a changed file. Editing ONLY one function's body in a
/// multi-symbol file must seed exactly that ONE symbol as changed — not all
/// symbols in the file. RED on the pre-fix seed loop, which pushed every
/// `file.symbols` entry.
#[tokio::test]
async fn test_detect_impact_seeds_only_body_changed_symbols() {
let repo = init_git_repo();
fs::create_dir_all(repo.path().join("src")).expect("create src dir");
let base = "pub fn kept() -> u32 { 1 }\npub fn changed() -> u32 { 2 }\n";
let modified = "pub fn kept() -> u32 { 1 }\npub fn changed() -> u32 { 99 }\n";
fs::write(repo.path().join("src/multi.rs"), base).expect("write base");
run_git(repo.path(), &["add", "."]);
run_git(repo.path(), &["commit", "-m", "init", "-q"]);
fs::write(repo.path().join("src/multi.rs"), modified).expect("modify changed body");
// Index mirrors the working tree (both symbols present).
let multi_file = make_file(
"src/multi.rs",
modified.as_bytes(),
vec![
make_symbol("kept", SymbolKind::Function, 0, 0),
make_symbol("changed", SymbolKind::Function, 1, 1),
],
);
let server = make_server_with_root(
make_live_index_ready(vec![multi_file]),
Some(repo.path().to_path_buf()),
);
let result = server
.detect_impact(Parameters(super::DetectImpactInput {
base_branch: None,
since: Some("WORKTREE".to_string()),
depth: 2,
scope: super::ImpactScope::Symbols,
include_untracked: true,
include_data: None,
}))
.await;
assert!(
result.contains("\"changed\""),
"the edited function must be seeded as changed: {result}"
);
assert!(
!result.contains("\"kept\""),
"an unedited sibling symbol must NOT be seeded as changed: {result}"
);
}
/// PART A (019): a comment/whitespace-only shift that leaves every function
/// body byte-identical must seed ZERO changed symbols. RED on the pre-fix
/// loop, which seeded all symbols regardless of body deltas.
#[tokio::test]
async fn test_detect_impact_whitespace_only_change_seeds_nothing() {
let repo = init_git_repo();
fs::create_dir_all(repo.path().join("src")).expect("create src dir");
let base = "pub fn a() -> u32 { 1 }\npub fn b() -> u32 { 2 }\n";
// Add a leading comment line: symbol bodies are byte-identical, only
// their file position shifts.
let shifted = "// unrelated comment\npub fn a() -> u32 { 1 }\npub fn b() -> u32 { 2 }\n";
fs::write(repo.path().join("src/ws.rs"), base).expect("write base");
run_git(repo.path(), &["add", "."]);
run_git(repo.path(), &["commit", "-m", "init", "-q"]);
fs::write(repo.path().join("src/ws.rs"), shifted).expect("comment-only shift");
let ws_file = make_file(
"src/ws.rs",
shifted.as_bytes(),
vec![
make_symbol("a", SymbolKind::Function, 1, 1),
make_symbol("b", SymbolKind::Function, 2, 2),
],
);
let server = make_server_with_root(
make_live_index_ready(vec![ws_file]),
Some(repo.path().to_path_buf()),
);
let result = server
.detect_impact(Parameters(super::DetectImpactInput {
base_branch: None,
since: Some("WORKTREE".to_string()),
depth: 2,
scope: super::ImpactScope::Symbols,
include_untracked: true,
include_data: None,
}))
.await;
assert!(
result.contains("0 changed symbol(s)"),
"a comment/whitespace-only shift must seed zero changed symbols: {result}"
);
}
/// Task 7: a statused local tool result carries the bound project's trust
/// evidence in `_meta` (project id/root, generation, index state, load
/// source) when rendered inside a dispatch scope — the machine-readable
/// receipt for "which project actually served this".
#[tokio::test]
async fn test_local_tool_meta_carries_project_evidence() {
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let input: super::GetFileContentInput =
serde_json::from_value(serde_json::json!({"path": "src/lib.rs"})).expect("input");
let result = crate::protocol::result_status::with_project_evidence_scope(
server.local_project_evidence(),
server.get_file_content_tool(Parameters(input)),
)
.await
.expect("tool result");
let serialized = serde_json::to_value(&result).expect("serialize");
let evidence = &serialized["_meta"]["symforge/project_evidence"];
assert_eq!(
evidence["project_name"], "test_project",
"local evidence must name the bound project: {serialized}"
);
assert!(
evidence["index_state"].is_string() && evidence["load_source"].is_string(),
"evidence must carry index state and load source: {serialized}"
);
assert!(
evidence["generation"].is_number(),
"evidence must carry the serving generation: {serialized}"
);
}
/// Task 4: a local/embedded server is bound to ONE project. An explicit
/// `project` selector that doesn't match refuses deterministically; a
/// matching selector (bound project name) proceeds normally.
///
/// This asserted only the message TEXT, so it looked like coverage while
/// pinning nothing about the reported outcome — `get_file_content` was
/// answering `outcome_class: found` for this refusal the whole time. The
/// outcome class is now asserted through the statused tool wrapper.
#[tokio::test]
async fn test_local_server_refuses_foreign_project_selector() {
let (key, file) = make_file("src/lib.rs", b"fn foo() {}", vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let foreign: super::GetFileContentInput = serde_json::from_value(serde_json::json!({
"path": "src/lib.rs",
"project": "some-other-project"
}))
.expect("foreign input");
// Through the STATUSED wrapper, so the reported outcome class is pinned
// alongside the message.
let refused_result =
serialized_tool_result(server.get_file_content_tool(Parameters(foreign)).await);
assert_tool_result_status(&refused_result, OutcomeClass::InvalidRequest);
let refused = tool_result_text(&refused_result);
assert!(
refused.contains("not available on this connection"),
"foreign selector must refuse: {refused}"
);
assert!(
!refused.contains("fn foo"),
"foreign selector must not serve the bound project's bytes: {refused}"
);
let matching: super::GetFileContentInput = serde_json::from_value(serde_json::json!({
"path": "src/lib.rs",
"project": "test_project"
}))
.expect("matching input");
let served = server.get_file_content(Parameters(matching)).await;
assert!(
served.contains("fn foo"),
"matching selector must proceed locally: {served}"
);
}
#[tokio::test]
async fn test_get_file_content_returns_content() {
let content = b"line 1\nline 2\nline 3";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert!(
result.contains("line 1"),
"should return file content, got: {result}"
);
}
#[tokio::test]
async fn test_get_file_content_text_can_carry_result_status_without_changing_text() {
let content = b"line 1\nline 2\nline 3";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let human_text = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
let result = crate::protocol::result_status::ResultStatus::new(
crate::protocol::result_status::OutcomeClass::Found,
)
.into_call_tool_result(human_text.clone());
let serialized = serde_json::to_value(&result).unwrap();
assert_eq!(
serialized["content"][0]["text"],
serde_json::json!(human_text)
);
assert_eq!(
serialized["_meta"][crate::protocol::result_status::RESULT_STATUS_META_KEY]["outcome_class"],
serde_json::json!("found")
);
}
#[tokio::test]
async fn test_read_tools_emit_result_status_contract() {
let source = "fn present() {}\nfn duplicate() {}\nfn duplicate() {}\n";
let present_start = source.find("fn present").unwrap() as u32;
let first_duplicate_start = source.find("fn duplicate").unwrap() as u32;
let second_duplicate_start = source.rfind("fn duplicate").unwrap() as u32;
let present_end = present_start + "fn present() {}".len() as u32;
let duplicate_len = "fn duplicate() {}".len() as u32;
let (key, file) = make_file(
"src/lib.rs",
source.as_bytes(),
vec![
make_symbol_with_bytes(
"present",
SymbolKind::Function,
0,
0,
(present_start, present_end),
),
make_symbol_with_bytes(
"duplicate",
SymbolKind::Function,
1,
1,
(first_duplicate_start, first_duplicate_start + duplicate_len),
),
make_symbol_with_bytes(
"duplicate",
SymbolKind::Function,
2,
2,
(
second_duplicate_start,
second_duplicate_start + duplicate_len,
),
),
],
);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let found_file = serialized_tool_result(
server
.get_file_content_tool(Parameters(get_file_content_input("src/lib.rs")))
.await,
);
assert_tool_result_status(&found_file, OutcomeClass::Found);
assert_eq!(tool_result_text(&found_file), source);
let missing_file = serialized_tool_result(
server
.get_file_content_tool(Parameters(get_file_content_input("src/missing.rs")))
.await,
);
assert_tool_result_status(&missing_file, OutcomeClass::NotFound);
assert!(tool_result_text(&missing_file).contains("File not found"));
let mut invalid_read = get_file_content_input("src/lib.rs");
invalid_read.start_line = Some(1);
invalid_read.around_line = Some(1);
let invalid_read =
serialized_tool_result(server.get_file_content_tool(Parameters(invalid_read)).await);
assert_tool_result_status(&invalid_read, OutcomeClass::InvalidRequest);
let mut ambiguous_read = get_file_content_input("src/lib.rs");
ambiguous_read.around_symbol = Some("duplicate".to_string());
let ambiguous_read = serialized_tool_result(
server
.get_file_content_tool(Parameters(ambiguous_read))
.await,
);
assert_tool_result_status(&ambiguous_read, OutcomeClass::Ambiguous);
assert!(tool_result_text(&ambiguous_read).contains("Ambiguous symbol selector"));
let found_symbol = serialized_tool_result(
server
.get_symbol_tool(Parameters(get_symbol_input("src/lib.rs", "present")))
.await,
);
assert_tool_result_status(&found_symbol, OutcomeClass::Found);
assert!(tool_result_text(&found_symbol).contains("fn present() {}"));
let missing_symbol = serialized_tool_result(
server
.get_symbol_tool(Parameters(get_symbol_input("src/lib.rs", "missing_symbol")))
.await,
);
assert_tool_result_status(&missing_symbol, OutcomeClass::NotFound);
assert!(tool_result_text(&missing_symbol).contains("No symbol missing_symbol"));
let ambiguous_symbol = serialized_tool_result(
server
.get_symbol_tool(Parameters(get_symbol_input("src/lib.rs", "duplicate")))
.await,
);
assert_tool_result_status(&ambiguous_symbol, OutcomeClass::Ambiguous);
assert!(tool_result_text(&ambiguous_symbol).contains("Ambiguous"));
}
#[test]
fn test_classify_get_file_content_output_flags_match_and_chunk_misses() {
// around_match miss (inferred mode) — previously misclassified Found via a
// dead `Match '` branch; the real message is `No matches for '...'`.
assert_eq!(
super::classify_get_file_content_output("No matches for 'needle' in src/lib.rs"),
OutcomeClass::NotFound
);
// around_match miss carrying an explicit-mode annotation prefix.
assert_eq!(
super::classify_get_file_content_output(
"── mode: match (explicit) ──\nNo matches for 'needle' in src/lib.rs"
),
OutcomeClass::NotFound
);
// match-occurrence overflow miss.
assert_eq!(
super::classify_get_file_content_output(
"Match occurrence 2 for 'todo' not found in src/lib.rs; 1 match(es) available at lines 2"
),
OutcomeClass::NotFound
);
// chunk index past EOF — an invalid paging request, not a successful read.
assert_eq!(
super::classify_get_file_content_output(
"Chunk 3 out of range for src/lib.rs (2 chunks)"
),
OutcomeClass::InvalidRequest
);
assert_eq!(
super::classify_get_file_content_output(
"── mode: chunk (explicit) ──\nChunk 3 out of range for src/lib.rs (2 chunks)"
),
OutcomeClass::InvalidRequest
);
// Robustness: a successful read whose CONTENT mentions these phrases (not at
// body-start) stays Found — the fix anchors on the message, not a bare match.
assert_eq!(
super::classify_get_file_content_output(
"1: // index out of range for the array\n2: ok"
),
OutcomeClass::Found
);
assert_eq!(
super::classify_get_file_content_output("1: let s = \"No matches for 'x'\";"),
OutcomeClass::Found
);
}
#[test]
fn daemon_wrapped_tool_errors_classify_as_invalid_request() {
assert_eq!(
super::classify_compact_tool_output(
"search_symbols",
"Error in search_symbols: projects must not be empty"
),
OutcomeClass::InvalidRequest
);
assert_eq!(
super::classify_search_text_output("Error in search_text: text search failed"),
OutcomeClass::InvalidRequest
);
assert_eq!(
super::classify_find_references_output(
"Error in find_references: project 'missing' is not open"
),
OutcomeClass::InvalidRequest
);
}
/// `foreign_project_refusal`'s message has no `Error:` prefix, so a refusal
/// that reached a classifier through DISPATCH (rather than an early return)
/// was reported as a successful answer. Every `is_error_output` call site
/// maps to `InvalidRequest`, so recognizing the shape is correct everywhere.
#[test]
fn foreign_project_refusal_classifies_as_invalid_request() {
let refusal = "project 'other' is not available on this connection: this server is \
bound to the single project 'test_project' (/tmp/repo). Explicit \
project routing requires the daemon transport with the target \
project opened via index_folder(path=...).";
assert_eq!(
SymForgeServer::classify_symforge_edit_outcome(refusal, true, refusal),
OutcomeClass::InvalidRequest,
"a refusal must never be reported as a successful edit"
);
// EVERY tool that can emit this refusal must classify it, including the
// two whose classifiers grew their own branch lists and never consulted
// `is_error_output` (`get_file_content`, `search_files`). Both feed
// `classify_compact_tool_output`, so a miss here fed a REFUSED step to
// the STEL chain as a SUCCESSFUL one.
for tool in [
"get_symbol",
"get_symbol_context",
"get_file_content",
"get_file_context",
"search_symbols",
"search_text",
"search_files",
"find_references",
] {
assert_eq!(
super::classify_compact_tool_output(tool, refusal),
OutcomeClass::InvalidRequest,
"{tool} must classify a foreign-project refusal as an invalid request"
);
assert!(
!super::compact_tool_output_is_success(tool, refusal),
"{tool} must not admit a refusal into the STEL chain as a success"
);
}
// Narrowness: both anchors are required, so ordinary bodies that merely
// start with "project" or merely mention the phrase stay untouched.
assert_eq!(
super::classify_compact_tool_output("get_symbol", "project 'x' has 4 indexed files"),
OutcomeClass::Found
);
assert_eq!(
super::classify_compact_tool_output(
"get_symbol",
"1: // is not available on this connection\n2: ok"
),
OutcomeClass::Found
);
}
/// The sibling refusal `local_cross_project_refusal` emits had the identical
/// defect: no `Error:` prefix, so every classifier fell through to `Found`
/// and a loud honest refusal was reported as a successful answer. Nothing
/// pinned its outcome class before this test — `tests/serve_http_attach.rs`
/// asserts only the message TEXT, and `daemon.rs` only asserts its ABSENCE
/// on the honored path — so classifying it costs no existing expectation.
#[test]
fn local_cross_project_refusal_classifies_as_invalid_request() {
let refusal = "Cross-project queries (project/projects) require the daemon: the \
working set of open projects lives on the daemon transport, not on \
the /mcp HTTP transport, stdio/embed, or while the daemon is \
unreachable. Start the daemon to query across projects.";
// The tools that actually emit it, plus the shared default arm.
for tool in [
"search_symbols",
"search_text",
"find_references",
"get_file_content",
"search_files",
"some_unlisted_tool",
] {
assert_eq!(
super::classify_compact_tool_output(tool, refusal),
OutcomeClass::InvalidRequest,
"{tool} must classify the cross-project refusal as an invalid request"
);
}
// Narrowness: both anchors are required, so a body that merely mentions
// the phrase (a source line, a doc hit) is untouched.
assert_eq!(
super::classify_compact_tool_output(
"search_text",
"7: // Cross-project queries (project/projects) require the daemon\n"
),
OutcomeClass::Found
);
}
#[tokio::test]
async fn test_search_tools_emit_result_status_contract() {
let server = make_server(make_live_index_ready(vec![
make_file(
"src/lib.rs",
b"fn present() {}\nconst NEEDLE: &str = \"needle\";\n",
vec![make_symbol("present", SymbolKind::Function, 0, 0)],
),
make_file("tests/lib.rs", b"fn test_lib() {}", vec![]),
]));
let found_symbols = serialized_tool_result(
server
.search_symbols_tool(Parameters(search_symbols_input(Some("present"))))
.await,
);
assert_tool_result_status(&found_symbols, OutcomeClass::Found);
assert!(tool_result_text(&found_symbols).contains("present"));
let empty_symbols = serialized_tool_result(
server
.search_symbols_tool(Parameters(search_symbols_input(Some("absent_symbol"))))
.await,
);
assert_tool_result_status(&empty_symbols, OutcomeClass::EmptyResult);
assert!(tool_result_text(&empty_symbols).contains("No symbols matching"));
let invalid_symbols = serialized_tool_result(
server
.search_symbols_tool(Parameters(search_symbols_input(None)))
.await,
);
assert_tool_result_status(&invalid_symbols, OutcomeClass::InvalidRequest);
let found_text = serialized_tool_result(
server
.search_text_tool(Parameters(super::SearchTextInput {
query: Some("needle".to_string()),
..Default::default()
}))
.await,
);
assert_tool_result_status(&found_text, OutcomeClass::Found);
assert!(tool_result_text(&found_text).contains("needle"));
let empty_text = serialized_tool_result(
server
.search_text_tool(Parameters(super::SearchTextInput {
query: Some("absent_text".to_string()),
..Default::default()
}))
.await,
);
assert_tool_result_status(&empty_text, OutcomeClass::EmptyResult);
assert!(tool_result_text(&empty_text).contains("No matches"));
let invalid_text = serialized_tool_result(
server
.search_text_tool(Parameters(super::SearchTextInput {
query: Some("[".to_string()),
regex: Some(true),
..Default::default()
}))
.await,
);
assert_tool_result_status(&invalid_text, OutcomeClass::InvalidRequest);
let found_file = serialized_tool_result(
server
.search_files_tool(Parameters(search_files_input("src/lib.rs")))
.await,
);
assert_tool_result_status(&found_file, OutcomeClass::Found);
assert!(tool_result_text(&found_file).contains("src/lib.rs"));
let missing_file = serialized_tool_result(
server
.search_files_tool(Parameters(search_files_input("missing.rs")))
.await,
);
assert_tool_result_status(&missing_file, OutcomeClass::NotFound);
let mut ambiguous_file_input = search_files_input("lib.rs");
ambiguous_file_input.resolve = Some(true);
let ambiguous_file = serialized_tool_result(
server
.search_files_tool(Parameters(ambiguous_file_input))
.await,
);
assert_tool_result_status(&ambiguous_file, OutcomeClass::Ambiguous);
assert!(tool_result_text(&ambiguous_file).contains("Ambiguous path hint"));
}
#[tokio::test]
async fn test_find_references_emits_result_status_contract() {
let target = make_file(
"src/db.rs",
b"pub fn connect() {}\n",
vec![make_symbol("connect", SymbolKind::Function, 0, 0)],
);
let dependent = make_file_with_refs(
"src/service.rs",
b"use crate::db::connect;\nfn run() { connect(); }\n",
vec![make_symbol("run", SymbolKind::Function, 1, 1)],
vec![
make_ref("db", Some("crate::db"), ReferenceKind::Import, 0, None),
make_ref(
"connect",
Some("crate::db::connect"),
ReferenceKind::Call,
1,
Some(0),
),
],
);
let lonely = make_file(
"src/lonely.rs",
b"fn lonely() {}\n",
vec![make_symbol("lonely", SymbolKind::Function, 0, 0)],
);
let duplicate = make_file(
"src/duplicate.rs",
b"fn duplicate() {}\nfn duplicate() {}\n",
vec![
make_symbol("duplicate", SymbolKind::Function, 0, 0),
make_symbol("duplicate", SymbolKind::Function, 1, 1),
],
);
let server = make_server(make_live_index_ready(vec![
target, dependent, lonely, duplicate,
]));
let mut found_input = find_references_input("connect");
found_input.kind = Some("call".to_string());
found_input.path = Some("src/db.rs".to_string());
found_input.symbol_kind = Some("fn".to_string());
found_input.symbol_line = Some(1);
let found =
serialized_tool_result(server.find_references_tool(Parameters(found_input)).await);
assert_tool_result_status(&found, OutcomeClass::Found);
assert!(tool_result_text(&found).contains("src/service.rs"));
let mut empty_input = find_references_input("lonely");
empty_input.path = Some("src/lonely.rs".to_string());
empty_input.symbol_kind = Some("fn".to_string());
empty_input.symbol_line = Some(1);
let empty =
serialized_tool_result(server.find_references_tool(Parameters(empty_input)).await);
assert_tool_result_status(&empty, OutcomeClass::EmptyResult);
assert!(tool_result_text(&empty).contains("No references found"));
let mut missing_path = find_references_input("missing");
missing_path.path = Some("src/missing.rs".to_string());
let missing_path =
serialized_tool_result(server.find_references_tool(Parameters(missing_path)).await);
assert_tool_result_status(&missing_path, OutcomeClass::NotFound);
assert!(tool_result_text(&missing_path).contains("File not found"));
let mut ambiguous = find_references_input("duplicate");
ambiguous.kind = Some("call".to_string());
ambiguous.path = Some("src/duplicate.rs".to_string());
ambiguous.symbol_kind = Some("fn".to_string());
let ambiguous =
serialized_tool_result(server.find_references_tool(Parameters(ambiguous)).await);
assert_tool_result_status(&ambiguous, OutcomeClass::Ambiguous);
assert!(tool_result_text(&ambiguous).contains("Ambiguous symbol selector"));
}
#[tokio::test]
async fn test_edit_tools_emit_result_status_contract() {
use crate::protocol::edit::ReplaceSymbolBodyInput;
let success_source = b"fn present() {\n println!(\"old\");\n}\nfn other() {}\n";
let (_dir, server, file_path) = setup_edit_test(success_source);
let success = serialized_tool_result(
server
.replace_symbol_body_tool(Parameters(ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "present".to_string(),
kind: None,
symbol_line: None,
new_body: "fn present() {\n println!(\"new\");\n}".to_string(),
dry_run: Some(false),
idempotency_key: None,
if_match: None,
working_directory: None,
}))
.await,
);
assert_tool_result_edit_status(&success, "success", OutcomeClass::Found);
assert!(tool_result_text(&success).contains("replaced"));
assert!(
std::fs::read_to_string(&file_path)
.unwrap()
.contains("\"new\"")
);
let dry_run_source = b"fn present() {\n println!(\"old\");\n}\n";
let (_dir, server, file_path) = setup_edit_test(dry_run_source);
let dry_run = serialized_tool_result(
server
.replace_symbol_body_tool(Parameters(ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "present".to_string(),
kind: None,
symbol_line: None,
new_body: "fn present() {\n println!(\"planned\");\n}".to_string(),
dry_run: Some(true),
idempotency_key: None,
if_match: None,
working_directory: None,
}))
.await,
);
assert_tool_result_edit_status(&dry_run, "dry_run_success", OutcomeClass::Found);
assert!(tool_result_text(&dry_run).contains("[DRY RUN]"));
assert!(
std::fs::read_to_string(&file_path)
.unwrap()
.contains("\"old\"")
);
let not_found = serialized_tool_result(
server
.replace_symbol_body_tool(Parameters(ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "missing_symbol".to_string(),
kind: None,
symbol_line: None,
new_body: "fn missing_symbol() {}".to_string(),
dry_run: Some(false),
idempotency_key: None,
if_match: None,
working_directory: None,
}))
.await,
);
assert_tool_result_edit_status(¬_found, "not_found", OutcomeClass::NotFound);
assert!(tool_result_text(¬_found).contains("Symbol not found"));
let ambiguous_source = b"fn duplicate() {}\nfn duplicate() {}\n";
let (_dir, server, _file_path) = setup_edit_test(ambiguous_source);
let ambiguous = serialized_tool_result(
server
.replace_symbol_body_tool(Parameters(ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "duplicate".to_string(),
kind: None,
symbol_line: None,
new_body: "fn duplicate() { changed(); }".to_string(),
dry_run: Some(false),
idempotency_key: None,
if_match: None,
working_directory: None,
}))
.await,
);
assert_tool_result_edit_status(&ambiguous, "ambiguous", OutcomeClass::Ambiguous);
assert!(tool_result_text(&ambiguous).contains("Ambiguous"));
let invalid_request = serialized_tool_result(
server
.batch_edit_tool(Parameters(crate::protocol::edit::BatchEditInput {
project: None,
edits: vec![crate::protocol::edit::SingleEdit {
path: "../outside.rs".to_string(),
name: "duplicate".to_string(),
kind: None,
symbol_line: None,
operation: crate::protocol::edit::EditOperation::Delete,
working_directory: None,
}],
dry_run: Some(false),
idempotency_key: None,
working_directory: None,
}))
.await,
);
assert_tool_result_edit_status(
&invalid_request,
"invalid_request",
OutcomeClass::InvalidRequest,
);
assert!(tool_result_text(&invalid_request).contains("Error:"));
let source = b"fn present() {}\n";
let parse_result = crate::parsing::process_file("src/lib.rs", source, LanguageId::Rust);
let indexed = IndexedFile::from_parse_result(parse_result, source.to_vec());
let server = make_server(make_live_index_ready(vec![(
"src/lib.rs".to_string(),
indexed,
)]));
let internal_failure = serialized_tool_result(
server
.replace_symbol_body_tool(Parameters(ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "present".to_string(),
kind: None,
symbol_line: None,
new_body: "fn present() { changed(); }".to_string(),
dry_run: Some(false),
idempotency_key: None,
if_match: None,
working_directory: None,
}))
.await,
);
assert_tool_result_edit_status(
&internal_failure,
"internal_failure",
OutcomeClass::InternalFailure,
);
assert_eq!(internal_failure["isError"], serde_json::json!(true));
}
#[tokio::test]
async fn test_tool_call_completion_instrumentation_records_representative_tools() {
use crate::analytics::{
AnalyticsConfig, AnalyticsRecorder, AnalyticsScope, AnalyticsStore,
SqliteAnalyticsStore,
};
use crate::protocol::edit::ReplaceSymbolBodyInput;
let (_dir, server) = setup_loaded_edit_test(&[(
"src/lib.rs",
"fn present() {\n println!(\"old\");\n}\n",
)]);
let project_state = project_state(_dir.path());
let db_path =
crate::paths::project_state_path(&project_state, crate::paths::ANALYTICS_DB_NAME);
let store = AnalyticsStore::open(AnalyticsConfig::enabled(project_state)).unwrap();
server.set_analytics_recorder_for_tests(AnalyticsRecorder::start(
store,
AnalyticsScope::Session,
16,
));
let read = serialized_tool_result(
server
.get_file_content_tool(Parameters(get_file_content_input("src/lib.rs")))
.await,
);
assert_tool_result_status(&read, OutcomeClass::Found);
let search = serialized_tool_result(
server
.search_symbols_tool(Parameters(search_symbols_input(Some("present"))))
.await,
);
assert_tool_result_status(&search, OutcomeClass::Found);
let dry_run_edit = serialized_tool_result(
server
.replace_symbol_body_tool(Parameters(ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "present".to_string(),
kind: None,
symbol_line: None,
new_body: "fn present() {\n println!(\"new\");\n}".to_string(),
dry_run: Some(true),
idempotency_key: None,
if_match: None,
working_directory: None,
}))
.await,
);
assert_tool_result_edit_status(&dry_run_edit, "dry_run_success", OutcomeClass::Found);
assert_eq!(server.analytics_queue_status_for_tests().enqueued, 3);
drop(server);
let records = SqliteAnalyticsStore::open(&db_path)
.unwrap()
.recent_records(10)
.unwrap();
let tool_names = records
.iter()
.map(|record| record.tool_name.as_str())
.collect::<Vec<_>>();
assert!(tool_names.contains(&"get_file_content"));
assert!(tool_names.contains(&"search_symbols"));
assert!(tool_names.contains(&"replace_symbol_body"));
assert!(records.iter().all(|record| record.surface == "tool"
&& record.configured_scope == "session"
&& record.response_bytes > 0
&& record.estimated_tokens.is_some()
&& record.outcome_class == "found"));
}
struct BlockingAnalyticsWriter {
started: std::sync::mpsc::Sender<()>,
release: std::sync::mpsc::Receiver<()>,
blocked_once: bool,
}
impl crate::analytics::AnalyticsWriter for BlockingAnalyticsWriter {
fn write(
&mut self,
_observation: &crate::analytics::AnalyticsObservation,
) -> anyhow::Result<crate::analytics::AnalyticsWriteOutcome> {
if !self.blocked_once {
self.blocked_once = true;
self.started.send(()).unwrap();
self.release.recv().unwrap();
}
Ok(crate::analytics::AnalyticsWriteOutcome::Recorded { id: 1 })
}
}
struct NoopAnalyticsWriter;
impl crate::analytics::AnalyticsWriter for NoopAnalyticsWriter {
fn write(
&mut self,
_observation: &crate::analytics::AnalyticsObservation,
) -> anyhow::Result<crate::analytics::AnalyticsWriteOutcome> {
Ok(crate::analytics::AnalyticsWriteOutcome::Recorded { id: 1 })
}
}
#[tokio::test]
async fn sensitive_review_input_creates_no_analytics_or_ccr_state() {
use crate::analytics::{AnalyticsRecorder, AnalyticsScope};
use crate::protocol::search_tools::{
KnowledgeSourceScope, ReviewKnowledgeInput, ReviewKnowledgeMode,
};
let server = make_server(make_live_index_empty());
server.set_analytics_recorder_for_tests(AnalyticsRecorder::start_with_writer_for_tests(
AnalyticsScope::Session,
4,
NoopAnalyticsWriter,
));
let canary = ["runtime", "-", "analytics", "-", "canary"].concat();
let result = serialized_tool_result(
server
.review_knowledge_tool(Parameters(ReviewKnowledgeInput {
mode: ReviewKnowledgeMode::Document,
path: Some(format!("docs/token={canary}")),
path_prefix: None,
source_scope: Some(KnowledgeSourceScope::Current),
project: None,
projects: None,
limit: None,
max_tokens: Some(128),
}))
.await,
);
let text = tool_result_text(&result);
assert!(text.contains("sensitive path rejected"), "{text}");
assert!(!text.contains(&canary), "sensitive input must not echo");
assert!(!text.contains("review_hash=") && !text.contains("hash=\""));
assert_eq!(server.analytics_queue_status_for_tests().enqueued, 0);
let economics = server.compression_economics();
assert_eq!(economics.offloads, 0);
assert_eq!(economics.bytes_stored, 0);
}
#[tokio::test]
async fn sensitive_search_input_creates_no_analytics_or_ccr_state() {
use crate::analytics::{AnalyticsRecorder, AnalyticsScope};
use crate::protocol::search_tools::{
KnowledgeAuthorityScope, KnowledgeSourceScope, SearchKnowledgeInput,
};
let server = make_server(make_live_index_empty());
server.set_analytics_recorder_for_tests(AnalyticsRecorder::start_with_writer_for_tests(
AnalyticsScope::Session,
4,
NoopAnalyticsWriter,
));
let canary = ["runtime", "-", "search", "-", "canary"].concat();
let query = format!("token={canary}");
let result = serialized_tool_result(
server
.search_knowledge_tool(Parameters(SearchKnowledgeInput {
query,
path_prefix: None,
source_scope: Some(KnowledgeSourceScope::Current),
authority_scope: Some(KnowledgeAuthorityScope::Default),
project: None,
projects: None,
limit: None,
max_tokens: Some(128),
}))
.await,
);
let text = tool_result_text(&result);
assert!(text.contains("sensitive query rejected"), "{text}");
assert!(!text.contains(&canary), "sensitive input must not echo");
assert_eq!(server.analytics_queue_status_for_tests().enqueued, 0);
let economics = server.compression_economics();
assert_eq!(economics.offloads, 0);
assert_eq!(economics.bytes_stored, 0);
}
#[tokio::test]
async fn test_tool_handler_enqueues_without_waiting_for_background_writer() {
use crate::analytics::{AnalyticsRecorder, AnalyticsScope};
let (started_tx, started_rx) = std::sync::mpsc::channel();
let (release_tx, release_rx) = std::sync::mpsc::channel();
let content = b"fn present() {}\n";
let (key, file) = make_file(
"src/lib.rs",
content,
vec![make_symbol("present", SymbolKind::Function, 0, 0)],
);
let server = make_server(make_live_index_ready(vec![(key, file)]));
server.set_analytics_recorder_for_tests(AnalyticsRecorder::start_with_writer_for_tests(
AnalyticsScope::Session,
1,
BlockingAnalyticsWriter {
started: started_tx,
release: release_rx,
blocked_once: false,
},
));
let result = tokio::time::timeout(
Duration::from_millis(200),
server.get_file_content_tool(Parameters(get_file_content_input("src/lib.rs"))),
)
.await
.expect("tool handler must not wait for the analytics writer");
let result = serialized_tool_result(result);
assert_tool_result_status(&result, OutcomeClass::Found);
started_rx
.recv_timeout(Duration::from_secs(1))
.expect("background writer should receive the enqueued observation");
let status = server.analytics_queue_status_for_tests();
assert_eq!(status.enqueued, 1);
assert_eq!(status.recorded, 0);
release_tx.send(()).unwrap();
drop(server);
}
#[tokio::test]
async fn test_batch_edit_and_insert_statuses_include_per_operation_status() {
use crate::protocol::edit::{
BatchEditInput, BatchInsertInput, EditOperation, InsertPosition, InsertTarget,
SingleEdit,
};
let dir = tempfile::tempdir().unwrap();
std::fs::create_dir(dir.path().join(".git")).unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let a_content = b"fn alpha() { old(); }\n";
let b_content = b"fn beta() { old(); }\n";
std::fs::write(src_dir.join("a.rs"), a_content).unwrap();
std::fs::write(src_dir.join("b.rs"), b_content).unwrap();
let mut files = vec![];
for (path, content) in [
("src/a.rs", a_content as &[u8]),
("src/b.rs", b_content as &[u8]),
] {
let result = crate::parsing::process_file(path, content, LanguageId::Rust);
let indexed = IndexedFile::from_parse_result(result, content.to_vec());
files.push((path.to_string(), indexed));
}
let server =
make_server_with_root(make_live_index_ready(files), Some(dir.path().to_path_buf()));
let dry_run_batch_edit = serialized_tool_result(
server
.batch_edit_tool(Parameters(BatchEditInput {
project: None,
edits: vec![
SingleEdit {
path: "src/a.rs".to_string(),
name: "alpha".to_string(),
kind: None,
symbol_line: None,
operation: EditOperation::Replace {
new_body: "fn alpha() { new(); }".to_string(),
},
working_directory: None,
},
SingleEdit {
path: "src/b.rs".to_string(),
name: "beta".to_string(),
kind: None,
symbol_line: None,
operation: EditOperation::Delete,
working_directory: None,
},
],
dry_run: Some(true),
idempotency_key: None,
working_directory: None,
}))
.await,
);
assert_tool_result_edit_status(&dry_run_batch_edit, "dry_run_success", OutcomeClass::Found);
let operation_statuses = dry_run_batch_edit["_meta"][RESULT_STATUS_META_KEY]["operations"]
.as_array()
.expect("batch edit status should include per-operation statuses");
assert_eq!(operation_statuses.len(), 2);
assert!(
operation_statuses
.iter()
.all(|entry| entry["status"] == serde_json::json!("dry_run_success"))
);
assert!(tool_result_text(&dry_run_batch_edit).contains("[DRY RUN]"));
assert!(
std::fs::read_to_string(src_dir.join("a.rs"))
.unwrap()
.contains("old")
);
let successful_batch_insert = serialized_tool_result(
server
.batch_insert_tool(Parameters(BatchInsertInput {
project: None,
content: "fn logging() {}".to_string(),
position: InsertPosition::After,
targets: vec![
InsertTarget {
path: "src/a.rs".to_string(),
name: "alpha".to_string(),
kind: None,
symbol_line: None,
working_directory: None,
},
InsertTarget {
path: "src/b.rs".to_string(),
name: "beta".to_string(),
kind: None,
symbol_line: None,
working_directory: None,
},
],
dry_run: Some(false),
idempotency_key: None,
working_directory: None,
}))
.await,
);
assert_tool_result_edit_status(&successful_batch_insert, "success", OutcomeClass::Found);
let operation_statuses =
successful_batch_insert["_meta"][RESULT_STATUS_META_KEY]["operations"]
.as_array()
.expect("batch insert status should include per-operation statuses");
assert_eq!(operation_statuses.len(), 2);
assert!(
operation_statuses
.iter()
.all(|entry| entry["status"] == serde_json::json!("success"))
);
let failed_batch_edit = serialized_tool_result(
server
.batch_edit_tool(Parameters(BatchEditInput {
project: None,
edits: vec![
SingleEdit {
path: "src/a.rs".to_string(),
name: "alpha".to_string(),
kind: None,
symbol_line: None,
operation: EditOperation::Delete,
working_directory: None,
},
SingleEdit {
path: "src/b.rs".to_string(),
name: "missing".to_string(),
kind: None,
symbol_line: None,
operation: EditOperation::Delete,
working_directory: None,
},
],
dry_run: Some(false),
idempotency_key: None,
working_directory: None,
}))
.await,
);
assert_tool_result_edit_status(&failed_batch_edit, "not_found", OutcomeClass::NotFound);
assert!(tool_result_text(&failed_batch_edit).contains("ROLLED BACK"));
let operation_statuses = failed_batch_edit["_meta"][RESULT_STATUS_META_KEY]["operations"]
.as_array()
.expect("failed batch edit status should identify the failing operation");
assert_eq!(operation_statuses.len(), 1);
assert_eq!(
operation_statuses[0]["operation_index"],
serde_json::json!(2)
);
assert_eq!(
operation_statuses[0]["status"],
serde_json::json!("not_found")
);
}
#[tokio::test]
async fn test_edit_idempotency_replays_same_key_same_request_without_second_write() {
let source = b"fn present() {\n old();\n}\n";
let (_dir, server, file_path) = setup_edit_test(source);
let request = serde_json::json!({
"path": "src/lib.rs",
"name": "present",
"new_body": "fn present() {\n new();\n}",
"dry_run": false,
"idempotency_key": "edit-replay-same-request",
});
let first = server
.replace_symbol_body(Parameters(replace_symbol_body_input_from_json(
request.clone(),
)))
.await;
assert!(first.contains("replaced"));
let written_once = std::fs::read_to_string(&file_path).unwrap();
assert!(written_once.contains("new();"));
let second = server
.replace_symbol_body(Parameters(replace_symbol_body_input_from_json(request)))
.await;
assert_eq!(second, first);
assert_eq!(std::fs::read_to_string(&file_path).unwrap(), written_once);
}
#[tokio::test]
async fn test_edit_idempotency_rejects_same_key_different_request_before_file_changes() {
let source = b"fn present() {\n old();\n}\n";
let (_dir, server, file_path) = setup_edit_test(source);
let first_request = serde_json::json!({
"path": "src/lib.rs",
"name": "present",
"new_body": "fn present() {\n first();\n}",
"dry_run": false,
"idempotency_key": "edit-conflict-same-key",
});
let second_request = serde_json::json!({
"path": "src/lib.rs",
"name": "present",
"new_body": "fn present() {\n second();\n}",
"dry_run": false,
"idempotency_key": "edit-conflict-same-key",
});
let first = server
.replace_symbol_body(Parameters(replace_symbol_body_input_from_json(
first_request,
)))
.await;
assert!(first.contains("replaced"));
let conflict = server
.replace_symbol_body(Parameters(replace_symbol_body_input_from_json(
second_request,
)))
.await;
let content = std::fs::read_to_string(&file_path).unwrap();
assert!(conflict.contains("Idempotency conflict"));
assert!(content.contains("first();"));
assert!(!content.contains("second();"));
}
#[tokio::test]
async fn test_edit_idempotency_dry_run_does_not_poison_committed_replay_state() {
let source = b"fn present() {\n old();\n}\n";
let (_dir, server, file_path) = setup_edit_test(source);
let dry_run_request = serde_json::json!({
"path": "src/lib.rs",
"name": "present",
"new_body": "fn present() {\n planned();\n}",
"dry_run": true,
"idempotency_key": "edit-dry-run-ignored",
});
let commit_request = serde_json::json!({
"path": "src/lib.rs",
"name": "present",
"new_body": "fn present() {\n committed();\n}",
"dry_run": false,
"idempotency_key": "edit-dry-run-ignored",
});
let dry_run = server
.replace_symbol_body(Parameters(replace_symbol_body_input_from_json(
dry_run_request,
)))
.await;
assert!(dry_run.contains("[DRY RUN]"));
assert!(
std::fs::read_to_string(&file_path)
.unwrap()
.contains("old();")
);
let committed = server
.replace_symbol_body(Parameters(replace_symbol_body_input_from_json(
commit_request,
)))
.await;
assert!(committed.contains("replaced"));
assert!(
std::fs::read_to_string(&file_path)
.unwrap()
.contains("committed();")
);
}
#[tokio::test]
async fn test_delete_symbol_idempotency_replays_after_symbol_is_removed() {
let source = b"fn target() {}\nfn keep() {}\n";
let (_dir, server, file_path) = setup_edit_test(source);
let request = serde_json::json!({
"path": "src/lib.rs",
"name": "target",
"dry_run": false,
"idempotency_key": "delete-symbol-replay-after-removal",
});
let first = server
.delete_symbol(Parameters(delete_symbol_input_from_json(request.clone())))
.await;
assert!(first.contains("deleted"));
let written_once = std::fs::read_to_string(&file_path).unwrap();
assert!(!written_once.contains("fn target"));
assert!(written_once.contains("fn keep"));
let second = server
.delete_symbol(Parameters(delete_symbol_input_from_json(request)))
.await;
assert_eq!(second, first);
assert_eq!(std::fs::read_to_string(&file_path).unwrap(), written_once);
}
#[tokio::test]
async fn test_edit_within_symbol_idempotency_replays_after_old_text_is_replaced() {
let source = b"fn present() {\n old();\n}\n";
let (_dir, server, file_path) = setup_edit_test(source);
let request = serde_json::json!({
"path": "src/lib.rs",
"name": "present",
"old_text": "old();",
"new_text": "new();",
"replace_all": false,
"dry_run": false,
"idempotency_key": "edit-within-replay-after-replacement",
});
let first = server
.edit_within_symbol(Parameters(edit_within_symbol_input_from_json(
request.clone(),
)))
.await;
assert!(first.contains("edited"));
let written_once = std::fs::read_to_string(&file_path).unwrap();
assert!(written_once.contains("new();"));
assert!(!written_once.contains("old();"));
let second = server
.edit_within_symbol(Parameters(edit_within_symbol_input_from_json(request)))
.await;
assert_eq!(second, first);
assert_eq!(std::fs::read_to_string(&file_path).unwrap(), written_once);
}
#[tokio::test]
async fn test_batch_edit_idempotency_replay_preserves_operation_status_metadata() {
let source = b"fn alpha() {\n old();\n}\nfn beta() {}\n";
let (_dir, server, file_path) = setup_edit_test(source);
let request = batch_replace_request_json(
"batch-edit-replay-same-request",
"fn alpha() {\n new();\n}",
);
let first = serialized_tool_result(
server
.batch_edit_tool(Parameters(batch_edit_input_from_json(request.clone())))
.await,
);
assert_tool_result_edit_status(&first, "success", OutcomeClass::Found);
assert_eq!(
first["_meta"][RESULT_STATUS_META_KEY]["operations"][0]["status"],
serde_json::json!("success")
);
let written_once = std::fs::read_to_string(&file_path).unwrap();
assert!(written_once.contains("new();"));
let second = serialized_tool_result(
server
.batch_edit_tool(Parameters(batch_edit_input_from_json(request)))
.await,
);
assert_eq!(second, first);
assert_eq!(std::fs::read_to_string(&file_path).unwrap(), written_once);
}
#[tokio::test]
async fn test_batch_edit_idempotency_rejects_same_key_different_request_before_file_changes() {
let source = b"fn alpha() {\n old();\n}\nfn beta() {}\n";
let (_dir, server, file_path) = setup_edit_test(source);
let first_request = batch_replace_request_json(
"batch-edit-conflict-same-key",
"fn alpha() {\n first();\n}",
);
let second_request = batch_replace_request_json(
"batch-edit-conflict-same-key",
"fn alpha() {\n second();\n}",
);
let first = server
.batch_edit(Parameters(batch_edit_input_from_json(first_request)))
.await;
assert!(first.contains("replaced"));
let conflict = server
.batch_edit(Parameters(batch_edit_input_from_json(second_request)))
.await;
let content = std::fs::read_to_string(&file_path).unwrap();
assert!(conflict.contains("Idempotency conflict"));
assert!(content.contains("first();"));
assert!(!content.contains("second();"));
}
#[tokio::test]
async fn test_get_file_content_honors_max_tokens_budget() {
let content = b"line one is long\nline two is also long\nline three is also long";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: Some(8),
force_refresh: None,
}))
.await;
assert!(
result.contains("[truncated"),
"budgeted read should include truncation notice, got: {result}"
);
assert!(
result.contains("budget is 8 tokens"),
"truncation notice should include requested budget, got: {result}"
);
assert!(
!result.contains("line three"),
"budgeted read should omit content past budget, got: {result}"
);
}
#[tokio::test]
async fn test_get_file_content_not_found() {
let server = make_server(make_live_index_ready(vec![]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "nonexistent.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(
result,
"File not found: nonexistent.rs. Use search_files to find the correct path."
);
}
#[tokio::test]
async fn test_get_file_content_line_range_preserves_public_contract() {
let content = b"line 1\nline 2\nline 3\nline 4";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: Some(2),
end_line: Some(3),
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(result, "line 2\nline 3");
}
#[tokio::test]
async fn test_get_file_content_show_line_numbers_renders_numbered_full_read() {
let content = b"line 1\nline 2\nline 3";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: Some(true),
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(result, "1: line 1\n2: line 2\n3: line 3");
}
#[tokio::test]
async fn test_get_file_content_header_and_line_numbers_render_range_shell() {
let content = b"line 1\nline 2\nline 3\nline 4";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: Some(2),
end_line: Some(3),
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: Some(true),
header: Some(true),
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(result, "src/lib.rs [lines 2-3]\n2: line 2\n3: line 3");
}
#[tokio::test]
async fn test_get_file_content_around_line_renders_numbered_excerpt() {
let content = b"line 1\nline 2\nline 3\nline 4\nline 5";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: Some(3),
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: Some(1),
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(result, "2: line 2\n3: line 3\n4: line 4");
}
#[tokio::test]
async fn test_get_file_content_allows_header_with_around_line() {
let content = b"line 1\nline 2\nline 3";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: Some(2),
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: Some(1),
show_line_numbers: None,
header: Some(true),
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
// Should succeed (not reject) — header is now allowed with around_line.
assert!(
!result.starts_with("Invalid"),
"header + around_line should be allowed, got: {result}"
);
assert!(
result.contains("line 2"),
"should contain the around_line content, got: {result}"
);
}
#[tokio::test]
async fn test_get_file_content_rejects_around_line_with_explicit_range() {
let content = b"line 1\nline 2\nline 3";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: Some(2),
end_line: None,
chunk_index: None,
max_lines: None,
around_line: Some(2),
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: Some(1),
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(
result,
"Invalid get_file_content request: `around_line` cannot be combined with `start_line` or `end_line`. Valid with `around_line`: `context_lines`."
);
}
#[tokio::test]
async fn test_get_file_content_around_match_renders_first_numbered_excerpt() {
let content = b"line 1\nTODO first\nline 3\nTODO second\nline 5";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: Some("todo".to_string()),
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: Some(1),
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(result, "1: line 1\n2: TODO first\n3: line 3");
}
#[tokio::test]
async fn test_get_file_content_chunked_read_renders_header_and_numbered_lines() {
let content = b"line 1\nline 2\nline 3\nline 4\nline 5";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: Some(2),
max_lines: Some(2),
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(
result,
"src/lib.rs [chunk 2/3, lines 3-4]\n3: line 3\n4: line 4"
);
}
#[tokio::test]
async fn test_get_file_content_reports_out_of_range_chunk() {
let content = b"line 1\nline 2\nline 3";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: Some(3),
max_lines: Some(2),
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(result, "Chunk 3 out of range for src/lib.rs (2 chunks)");
}
#[tokio::test]
async fn test_get_file_content_reports_missing_around_match() {
let content = b"line 1\nline 2\nline 3";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: Some("needle".to_string()),
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: Some(1),
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(result, "No matches for 'needle' in src/lib.rs");
}
#[tokio::test]
async fn test_get_file_content_selects_requested_match_occurrence() {
let content = b"line 1\nTODO first\nline 3\nTODO second\nline 5";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: Some("todo".to_string()),
match_occurrence: Some(2),
around_symbol: None,
symbol_line: None,
context_lines: Some(1),
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(result, "3: line 3\n4: TODO second\n5: line 5");
}
#[tokio::test]
async fn test_get_file_content_reports_missing_match_occurrence() {
let content = b"line 1\nTODO first\nline 3";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: Some("todo".to_string()),
match_occurrence: Some(2),
around_symbol: None,
symbol_line: None,
context_lines: Some(1),
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(
result,
"Match occurrence 2 for 'todo' not found in src/lib.rs; 1 match(es) available at lines 2"
);
}
#[tokio::test]
async fn test_get_file_content_freshens_stale_indexed_file_before_rendering() {
let repo = tempfile::tempdir().unwrap();
let src_dir = repo.path().join("src");
fs::create_dir_all(&src_dir).unwrap();
let disk_path = src_dir.join("lib.rs");
fs::write(&disk_path, "fn fresh() {}\n").unwrap();
let (key, file) = make_file("src/lib.rs", b"fn stale() {}\n", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(repo.path().to_path_buf()),
);
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert!(
result.contains("fn fresh() {}"),
"expected fresh disk content, got: {result}"
);
assert!(
!result.contains("fn stale() {}"),
"stale indexed content should not be served after refresh: {result}"
);
}
#[tokio::test]
async fn test_get_file_content_normalizes_exact_path_before_freshness_and_lookup() {
let repo = tempfile::tempdir().unwrap();
let src_dir = repo.path().join("src");
fs::create_dir_all(&src_dir).unwrap();
let disk_path = src_dir.join("lib.rs");
fs::write(&disk_path, "fn fresh() {}\n").unwrap();
let (key, file) = make_file("src/lib.rs", b"fn stale() {}\n", vec![]);
let server = make_server_with_root(
make_live_index_ready(vec![(key, file)]),
Some(repo.path().to_path_buf()),
);
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "./src\\lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert!(
result.contains("fn fresh() {}"),
"expected fresh disk content, got: {result}"
);
let guard = server.index.read();
assert!(guard.get_file("src/lib.rs").is_some());
assert!(guard.get_file("./src\\lib.rs").is_none());
}
#[tokio::test]
async fn test_get_file_content_around_symbol_renders_numbered_excerpt() {
let content = b"line 1\nfn connect() {}\nline 3";
let (key, file) = make_file(
"src/lib.rs",
content,
vec![make_symbol("connect", SymbolKind::Function, 1, 1)],
);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: Some("connect".to_string()),
symbol_line: None,
context_lines: Some(1),
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(result, "1: line 1\n2: fn connect() {}\n3: line 3");
}
#[tokio::test]
async fn test_get_file_content_reports_ambiguous_around_symbol_without_symbol_line() {
let content = b"fn connect() {}\nline 2\nfn connect() {}";
let (key, file) = make_file(
"src/lib.rs",
content,
vec![
make_symbol("connect", SymbolKind::Function, 0, 0),
make_symbol("connect", SymbolKind::Function, 2, 2),
],
);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: Some("connect".to_string()),
symbol_line: None,
context_lines: Some(1),
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(
result,
"Ambiguous symbol selector for connect in src/lib.rs; pass `symbol_line` to disambiguate. Candidates: 0, 2"
);
}
#[tokio::test]
async fn test_get_file_content_around_symbol_symbol_line_disambiguates() {
let content = b"fn connect() {}\nline 2\nfn connect() {}";
let (key, file) = make_file(
"src/lib.rs",
content,
vec![
make_symbol("connect", SymbolKind::Function, 0, 0),
make_symbol("connect", SymbolKind::Function, 2, 2),
],
);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: Some("connect".to_string()),
symbol_line: Some(3),
context_lines: Some(0),
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(result, "3: fn connect() {}");
}
#[tokio::test]
async fn test_get_file_content_reports_missing_around_symbol() {
let content = b"fn helper() {}\nline 2";
let (key, file) = make_file(
"src/lib.rs",
content,
vec![make_symbol("helper", SymbolKind::Function, 1, 1)],
);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: Some("connect".to_string()),
symbol_line: None,
context_lines: Some(1),
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(
result,
"No symbol connect in src/lib.rs. Close matches: helper. Use get_file_context with sections=['outline'] for the full list (1 symbols)."
);
}
#[tokio::test]
async fn test_get_file_content_rejects_chunked_read_with_other_selectors() {
let content = b"line 1\nline 2\nline 3";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: Some(2),
end_line: None,
chunk_index: Some(1),
max_lines: Some(2),
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(
result,
"Invalid get_file_content request: chunked reads (`chunk_index` + `max_lines`) cannot be combined with `start_line`, `end_line`, `around_line`, or `around_match`."
);
}
#[tokio::test]
async fn test_get_file_content_rejects_chunk_index_without_max_lines() {
let content = b"line 1\nline 2\nline 3";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: Some(1),
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(
result,
"Invalid get_file_content request: `chunk_index` requires `max_lines`."
);
}
#[tokio::test]
async fn test_get_file_content_rejects_around_symbol_with_other_selectors() {
let content = b"line 1\nline 2\nline 3";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: Some(2),
end_line: None,
chunk_index: Some(1),
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: Some("connect".to_string()),
symbol_line: None,
context_lines: Some(1),
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(
result,
"Invalid get_file_content request: `around_symbol` cannot be combined with `start_line`, `end_line`, `around_line`, `around_match`, or `chunk_index`. Valid with `around_symbol`: `symbol_line`, `context_lines`, `max_lines`."
);
}
#[tokio::test]
async fn test_get_file_content_rejects_symbol_line_without_around_symbol() {
let content = b"line 1\nline 2\nline 3";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: Some(2),
context_lines: Some(1),
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(
result,
"Invalid get_file_content request: `symbol_line` requires `around_symbol`."
);
}
#[tokio::test]
async fn test_get_file_content_rejects_around_match_with_other_selectors() {
let content = b"line 1\nline 2\nline 3";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: Some(3),
chunk_index: None,
max_lines: None,
around_line: Some(2),
around_match: Some("line".to_string()),
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: Some(1),
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(
result,
"Invalid get_file_content request: `around_match` cannot be combined with `start_line`, `end_line`, or `around_line`. Valid with `around_match`: `context_lines`."
);
}
// ── Mode enum tests ────────────────────────────────────────────────────
#[tokio::test]
async fn test_mode_symbol_with_around_symbol_works() {
let content = b"line 1\nfn connect() {}\nline 3";
let (key, file) = make_file(
"src/lib.rs",
content,
vec![make_symbol("connect", SymbolKind::Function, 2, 2)],
);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: Some("symbol".to_string()),
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: Some("connect".to_string()),
symbol_line: None,
context_lines: Some(1),
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert!(
result.contains("fn connect()"),
"expected symbol content, got: {result}"
);
}
#[tokio::test]
async fn test_mode_symbol_without_around_symbol_errors() {
let content = b"line 1\nline 2";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: Some("symbol".to_string()),
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(result, "mode=symbol requires around_symbol");
}
#[tokio::test]
async fn test_mode_lines_with_cross_mode_flag_errors() {
let content = b"line 1\nline 2";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: Some("lines".to_string()),
start_line: Some(1),
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: Some("foo".to_string()),
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert!(
result.contains("mode=lines conflicts with around_symbol"),
"expected cross-mode error, got: {result}"
);
assert!(
result.contains("Use mode=symbol"),
"expected guidance, got: {result}"
);
}
#[tokio::test]
async fn test_mode_lines_rejects_match_occurrence_cross_mode_flag() {
let content = b"line 1\nline 2";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: Some("lines".to_string()),
start_line: Some(1),
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: Some(2),
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert!(
result.contains("mode=lines conflicts with match_occurrence"),
"expected cross-mode error, got: {result}"
);
assert!(
result.contains("Use mode=match"),
"expected guidance, got: {result}"
);
}
#[tokio::test]
async fn test_no_mode_legacy_flags_backward_compatible() {
let content = b"line 1\nline 2\nline 3";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: Some(1),
end_line: Some(2),
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert!(
result.contains("line 1"),
"expected file content, got: {result}"
);
}
#[tokio::test]
async fn test_mode_search_not_implemented() {
let content = b"line 1";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: Some("search".to_string()),
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(result, "mode 'search' is not yet implemented");
}
#[tokio::test]
async fn test_mode_symbol_with_context_lines_works() {
let content = b"line 1\nfn connect() {}\nline 3";
let (key, file) = make_file(
"src/lib.rs",
content,
vec![make_symbol("connect", SymbolKind::Function, 2, 2)],
);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: Some("symbol".to_string()),
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: Some("connect".to_string()),
symbol_line: None,
context_lines: Some(10),
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert!(
result.contains("fn connect()"),
"expected symbol content with context, got: {result}"
);
}
#[tokio::test]
async fn test_mode_symbol_rejects_match_occurrence_cross_mode_flag() {
let content = b"line 1\nfn connect() {}\nline 3";
let (key, file) = make_file(
"src/lib.rs",
content,
vec![make_symbol("connect", SymbolKind::Function, 2, 2)],
);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: Some("symbol".to_string()),
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: Some(2),
around_symbol: Some("connect".to_string()),
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert!(
result.contains("mode=symbol conflicts with match_occurrence"),
"expected cross-mode error, got: {result}"
);
}
#[tokio::test]
async fn test_mode_unknown_errors() {
let content = b"line 1";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: Some("fancy".to_string()),
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(
result,
"Unknown mode 'fancy'. Valid modes: lines, symbol, match, chunk."
);
}
#[tokio::test]
async fn test_mode_match_without_around_match_errors() {
let content = b"line 1";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: Some("match".to_string()),
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(result, "mode=match requires around_match");
}
#[tokio::test]
async fn test_match_occurrence_requires_around_match() {
let content = b"line 1";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: Some(1),
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(
result,
"Invalid get_file_content request: `match_occurrence` requires `around_match`."
);
}
#[tokio::test]
async fn test_match_occurrence_must_be_positive() {
let content = b"line 1\nTODO";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: Some("match".to_string()),
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: Some("todo".to_string()),
match_occurrence: Some(0),
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(
result,
"Invalid get_file_content request: `match_occurrence` must be 1 or greater."
);
}
#[tokio::test]
async fn test_mode_chunk_without_required_flags_errors() {
let content = b"line 1";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: Some("chunk".to_string()),
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert_eq!(result, "mode=chunk requires chunk_index");
}
#[tokio::test]
async fn test_mode_chunk_cross_mode_errors() {
let content = b"line 1\nline 2\nline 3";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: Some("chunk".to_string()),
start_line: None,
end_line: None,
chunk_index: Some(1),
max_lines: Some(10),
around_line: None,
around_match: Some("line".to_string()),
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert!(
result.contains("mode=chunk conflicts with around_match"),
"expected cross-mode error, got: {result}"
);
}
#[tokio::test]
async fn test_mode_chunk_rejects_match_occurrence_cross_mode_flag() {
let content = b"line 1\nline 2\nline 3";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: Some("chunk".to_string()),
start_line: None,
end_line: None,
chunk_index: Some(1),
max_lines: Some(10),
around_line: None,
around_match: None,
match_occurrence: Some(2),
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: None,
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert!(
result.contains("mode=chunk conflicts with match_occurrence"),
"expected cross-mode error, got: {result}"
);
assert!(
result.contains("Use mode=match"),
"expected guidance, got: {result}"
);
}
// ── get_file_content serde / alias tests ───────────────────────────────
#[test]
fn test_get_file_content_input_deserializes_offset_and_limit() {
let json = r#"{"path":"x","offset":10,"limit":5}"#;
let input: super::GetFileContentInput = serde_json::from_str(json).unwrap();
assert_eq!(input.offset, Some(10));
assert_eq!(input.limit, Some(5));
assert!(input.start_line.is_none());
assert!(input.end_line.is_none());
}
#[test]
fn test_get_file_content_input_deserializes_max_tokens() {
let json = r#"{"path":"x","max_tokens":1200}"#;
let input: super::GetFileContentInput = serde_json::from_str(json).unwrap();
assert_eq!(input.max_tokens, Some(1200));
}
#[test]
fn test_get_file_content_input_defaults_all_none() {
let json = r#"{"path":"x"}"#;
let input: super::GetFileContentInput = serde_json::from_str(json).unwrap();
assert!(input.offset.is_none());
assert!(input.limit.is_none());
assert!(input.start_line.is_none());
assert!(input.max_tokens.is_none());
}
#[test]
fn test_get_file_content_input_rejects_unknown_field() {
let json = r#"{"path":"x","typo_field":1}"#;
let result = serde_json::from_str::<super::GetFileContentInput>(json);
assert!(result.is_err(), "unknown field should be rejected");
let err = result.err().unwrap().to_string();
assert!(
err.contains("typo_field"),
"error should name the unknown field, got: {err}"
);
}
#[test]
fn test_get_file_content_input_rejects_non_numeric_offset() {
let json = r#"{"path":"x","offset":"not-a-number"}"#;
assert!(
serde_json::from_str::<super::GetFileContentInput>(json).is_err(),
"non-numeric offset should fail to deserialize"
);
}
// ── normalize_file_content_aliases unit tests ───────────────────────────
fn make_alias_input(offset: Option<u32>, limit: Option<u32>) -> super::GetFileContentInput {
super::GetFileContentInput {
project: None,
path: "x".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset,
limit,
max_tokens: None,
force_refresh: None,
}
}
#[test]
fn test_normalize_aliases_offset_and_limit() {
let mut input = make_alias_input(Some(10), Some(5));
super::normalize_file_content_aliases(&mut input).unwrap();
assert_eq!(input.start_line, Some(11));
assert_eq!(input.end_line, Some(15));
assert!(input.offset.is_none());
assert!(input.limit.is_none());
}
#[test]
fn test_normalize_aliases_zero_offset() {
let mut input = make_alias_input(Some(0), Some(100));
super::normalize_file_content_aliases(&mut input).unwrap();
assert_eq!(input.start_line, Some(1));
assert_eq!(input.end_line, Some(100));
}
#[test]
fn test_normalize_aliases_no_limit_reads_to_end() {
let mut input = make_alias_input(Some(50), None);
super::normalize_file_content_aliases(&mut input).unwrap();
assert_eq!(input.start_line, Some(51));
assert!(input.end_line.is_none());
}
#[test]
fn test_normalize_aliases_no_offset_defaults_to_start() {
let mut input = make_alias_input(None, Some(20));
super::normalize_file_content_aliases(&mut input).unwrap();
assert_eq!(input.start_line, Some(1));
assert_eq!(input.end_line, Some(20));
}
#[test]
fn test_normalize_aliases_single_line() {
let mut input = make_alias_input(Some(0), Some(1));
super::normalize_file_content_aliases(&mut input).unwrap();
assert_eq!(input.start_line, Some(1));
assert_eq!(input.end_line, Some(1));
}
#[test]
fn test_normalize_aliases_neither_set_is_noop() {
let mut input = make_alias_input(None, None);
super::normalize_file_content_aliases(&mut input).unwrap();
assert!(input.start_line.is_none());
assert!(input.end_line.is_none());
}
#[test]
fn test_normalize_aliases_rejects_conflict_with_start_line() {
let mut input = make_alias_input(Some(10), None);
input.start_line = Some(5);
let err = super::normalize_file_content_aliases(&mut input)
.err()
.unwrap();
assert!(err.contains("`start_line`"), "got: {err}");
}
#[test]
fn test_normalize_aliases_rejects_conflict_with_end_line() {
let mut input = make_alias_input(Some(10), Some(5));
input.end_line = Some(20);
let err = super::normalize_file_content_aliases(&mut input)
.err()
.unwrap();
assert!(err.contains("`end_line`"), "got: {err}");
}
#[test]
fn test_normalize_aliases_rejects_conflict_with_around_symbol() {
let mut input = make_alias_input(Some(10), None);
input.around_symbol = Some("foo".to_string());
let err = super::normalize_file_content_aliases(&mut input)
.err()
.unwrap();
assert!(err.contains("`around_symbol`"), "got: {err}");
}
#[test]
fn test_normalize_aliases_rejects_limit_zero() {
let mut input = make_alias_input(None, Some(0));
let err = super::normalize_file_content_aliases(&mut input)
.err()
.unwrap();
assert!(err.contains("must be 1 or greater"), "got: {err}");
}
#[test]
fn test_normalize_aliases_rejects_conflict_with_mode() {
let mut input = make_alias_input(Some(10), None);
input.mode = Some("lines".to_string());
let err = super::normalize_file_content_aliases(&mut input)
.err()
.unwrap();
assert!(err.contains("`mode`"), "got: {err}");
}
#[tokio::test]
async fn test_get_file_content_offset_limit_returns_sliced_window() {
let content = b"line 1\nline 2\nline 3\nline 4\nline 5";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: None,
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: Some(1),
limit: Some(2),
max_tokens: None,
force_refresh: None,
}))
.await;
// offset=1 → start_line=2, limit=2 → end_line=3
assert_eq!(result, "line 2\nline 3", "got: {result}");
}
#[tokio::test]
async fn test_get_file_content_offset_limit_conflict_rejected() {
let content = b"line 1\nline 2";
let (key, file) = make_file("src/lib.rs", content, vec![]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_file_content(Parameters(super::GetFileContentInput {
project: None,
path: "src/lib.rs".to_string(),
mode: None,
start_line: Some(1),
end_line: None,
chunk_index: None,
max_lines: None,
around_line: None,
around_match: None,
match_occurrence: None,
around_symbol: None,
symbol_line: None,
context_lines: None,
show_line_numbers: None,
header: None,
estimate: None,
offset: Some(1),
limit: None,
max_tokens: None,
force_refresh: None,
}))
.await;
assert!(
result.contains("cannot be combined"),
"conflict should be rejected, got: {result}"
);
}
// ── Explore tool tests ──────────────────────────────────────────────────
#[tokio::test]
async fn test_explore_output_footer_documents_ranking() {
let sym = make_symbol("Error", SymbolKind::Enum, 0, 5);
let content = b"pub enum Error {\n NotFound,\n}\n";
let (key, file) = make_file("src/error.rs", content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "error handling".to_string(),
limit: None,
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("ranked by:"),
"explore output must include rank-signal footer; got:\n{result}"
);
assert!(
result.contains("concept match + symbol-token alignment + path proximity"),
"footer must enumerate the ranking signals the scorer computes verbatim; got:\n{result}"
);
// SF-STRESS-013: the scorer never computes caller density, so the footer
// must not advertise it.
assert!(
!result.contains("caller density"),
"footer must not claim 'caller density' the scorer does not compute; got:\n{result}"
);
}
#[tokio::test]
async fn test_explore_concept_returns_results() {
let sym = make_symbol("Error", SymbolKind::Enum, 0, 5);
let content = b"pub enum Error {\n NotFound,\n Io(std::io::Error),\n}\nimpl Error {\n fn is_retryable(&self) -> bool { false }\n}\n";
let (key, file) = make_file("src/error.rs", content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "error handling".to_string(),
limit: Some(5),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("Exploring: Error Handling"),
"should have concept label, got: {result}"
);
assert!(
result.contains("Error"),
"should find Error symbol, got: {result}"
);
assert!(
!result.contains("Auto-derived cluster:"),
"static concept matches should not emit fallback-derived clustering: {result}"
);
}
#[tokio::test]
async fn test_explore_concept_enrichment_shows_annotation() {
let sym = make_symbol("Error", SymbolKind::Enum, 0, 5);
let content = b"use thiserror::Error;\npub enum Error {}\n";
let refs = vec![make_ref(
"thiserror",
Some("thiserror::Error"),
ReferenceKind::Import,
0,
None,
)];
let (key, file) = make_file_with_refs("src/error.rs", content, vec![sym], refs);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "error handling".to_string(),
limit: Some(5),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("Enriched with project imports: thiserror"),
"should annotate convention enrichment, got: {result}"
);
}
#[tokio::test]
async fn test_explore_concept_enrichment_from_cargo_manifest() {
// thiserror has NO import references — only a Cargo.toml dependency symbol.
// The enrichment should still surface it via the manifest path.
let sym = make_symbol("Error", SymbolKind::Enum, 0, 5);
let content = b"#[derive(thiserror::Error)]\npub enum Error {}\n";
let (key, file) = make_file("src/error.rs", content, vec![sym]);
// Cargo.toml with a dependencies.thiserror symbol (no import refs needed).
let cargo_sym = SymbolRecord {
name: "dependencies.thiserror".to_string(),
kind: SymbolKind::Key,
depth: 1,
sort_order: 0,
byte_range: (0, 20),
item_byte_range: Some((0, 20)),
line_range: (0, 0),
doc_byte_range: None,
};
let cargo_content = b"[dependencies]\nthiserror = \"2.0\"\n";
let cargo_file = IndexedFile {
relative_path: "Cargo.toml".to_string(),
language: LanguageId::Toml,
classification: crate::domain::FileClassification::for_code_path("Cargo.toml"),
content: cargo_content.to_vec(),
symbols: vec![cargo_sym],
parse_status: ParseStatus::Parsed,
parse_diagnostic: None,
byte_len: cargo_content.len() as u64,
content_hash: "test".to_string(),
references: vec![],
alias_map: std::collections::HashMap::new(),
mtime_secs: 0,
};
let server = make_server(make_live_index_ready(vec![
(key, file),
("Cargo.toml".to_string(), cargo_file),
]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "error handling".to_string(),
limit: Some(5),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("Enriched with project imports: thiserror"),
"should enrich from Cargo.toml manifest deps, got: {result}"
);
}
#[tokio::test]
async fn test_explore_fallback_returns_results() {
let content = b"fn process_data() { let x = 42; }\n";
let sym = make_symbol("process_data", SymbolKind::Function, 0, 0);
let (key, file) = make_file("src/main.rs", content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "process data".to_string(),
limit: Some(5),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("Exploring:"),
"should have explore header, got: {result}"
);
}
#[tokio::test]
async fn test_explore_empty_query() {
let server = make_server(make_live_index_ready(vec![]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "".to_string(),
limit: None,
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("Explore requires a non-empty query"),
"should reject empty query, got: {result}"
);
}
#[tokio::test]
async fn test_explore_depth_2_shows_signatures() {
let content = b"pub enum Error {\n NotFound,\n Io(std::io::Error),\n}\nimpl Error {\n fn is_retryable(&self) -> bool { false }\n}\n";
let sym = SymbolRecord {
name: "Error".to_string(),
kind: SymbolKind::Enum,
depth: 0,
sort_order: 0,
byte_range: (0, content.len() as u32),
line_range: (0, 5),
doc_byte_range: None,
item_byte_range: None,
};
let (key, file) = make_file("src/error.rs", content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "error handling".to_string(),
limit: Some(5),
depth: Some(2),
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("pub enum Error"),
"depth 2 should show signature, got: {result}"
);
}
#[tokio::test]
async fn test_explore_multi_term_scoring_injects_enclosing_symbol() {
// BurstTracker contains "debounce" in its body; it won't match the symbol search for
// "debounce" (name mismatch) but the text search will find the word and inject the
// enclosing symbol into match_counts, so it should appear in results.
// Query uses "burst debounce" — no concept match — to exercise fallback multi-term scoring.
let content = b"pub struct BurstTracker {\n debounce: u32,\n burst_count: u32,\n}\n";
let burst_tracker = SymbolRecord {
name: "BurstTracker".to_string(),
kind: SymbolKind::Struct,
depth: 0,
sort_order: 0,
byte_range: (0, content.len() as u32),
line_range: (0, 3),
doc_byte_range: None,
item_byte_range: None,
};
let (key, file) = make_file("src/watcher.rs", content, vec![burst_tracker]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "burst debounce".to_string(),
limit: Some(10),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("BurstTracker"),
"BurstTracker should appear via enclosing-symbol injection from debounce text hit, got: {result}"
);
}
#[tokio::test]
async fn test_explore_cooccurrence_ranks_multi_term_symbol_above_single_term_noise() {
let actor_content =
b"pub fn handle_supervisor_evt() -> Result<(), ActorProcessingErr> { Ok(()) }\n";
let actor_sym = SymbolRecord {
name: "handle_supervisor_evt".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (0, actor_content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let noise_content = b"pub fn recovery_words() {}\n";
let noise_sym = SymbolRecord {
name: "recovery_words".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (0, noise_content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let actor_file = make_file("src/actors/supervisor.rs", actor_content, vec![actor_sym]);
let noise_file = make_file("src/auth/recovery.rs", noise_content, vec![noise_sym]);
let server = make_server(make_live_index_ready(vec![actor_file, noise_file]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "actor supervision and error recovery".to_string(),
limit: Some(10),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
let actor_pos = result.find("handle_supervisor_evt");
let noise_pos = result.find("recovery_words");
assert!(
actor_pos.is_some(),
"actor-supervision symbol should appear in results: {result}"
);
assert!(
noise_pos.is_none() || actor_pos < noise_pos,
"multi-term actor match should outrank single-term recovery noise: {result}"
);
}
#[tokio::test]
async fn test_explore_fallback_surfaces_auto_derived_cluster() {
let content = b"pub struct EventFanoutBus;\npub fn dispatch_delivery_event() {}\n";
let bus_symbol = SymbolRecord {
name: "EventFanoutBus".to_string(),
kind: SymbolKind::Struct,
depth: 0,
sort_order: 0,
byte_range: (0, 23),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let delivery_symbol = SymbolRecord {
name: "dispatch_delivery_event".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 1,
byte_range: (24, content.len() as u32),
line_range: (1, 1),
doc_byte_range: None,
item_byte_range: None,
};
let (key, file) = make_file(
"src/bus/fanout.rs",
content,
vec![bus_symbol, delivery_symbol],
);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "event fanout delivery".to_string(),
limit: Some(10),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("Auto-derived cluster:"),
"fallback explore should surface a derived cluster: {result}"
);
assert!(
result.contains("Promoted signals:"),
"derived cluster should expose promoted symbols: {result}"
);
assert!(
result.contains("EventFanoutBus") || result.contains("dispatch_delivery_event"),
"derived cluster should promote repo-specific symbol names: {result}"
);
assert!(
result.contains("src/bus/fanout.rs"),
"derived cluster should surface the seed file it learned from: {result}"
);
}
#[tokio::test]
async fn test_explore_hides_test_scaffolding_for_broad_fallback_query() {
let code_content =
b"pub struct AuthenticationMiddleware;\npub fn enforce_authentication_middleware() {}\n";
let code_symbols = vec![
SymbolRecord {
name: "AuthenticationMiddleware".to_string(),
kind: SymbolKind::Struct,
depth: 0,
sort_order: 0,
byte_range: (0, 36),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
},
SymbolRecord {
name: "enforce_authentication_middleware".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 1,
byte_range: (37, code_content.len() as u32),
line_range: (1, 1),
doc_byte_range: None,
item_byte_range: None,
},
];
let test_content = b"pub fn test_authentication_middleware_format() {}\n";
let test_symbol = SymbolRecord {
name: "test_authentication_middleware_format".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (0, test_content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let reason_content = b"pub enum ReasonCode { Authentication, RateLimit }\n";
let reason_symbol = SymbolRecord {
name: "ReasonCode".to_string(),
kind: SymbolKind::Enum,
depth: 0,
sort_order: 0,
byte_range: (0, reason_content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let server = make_server(make_live_index_ready(vec![
make_file("src/auth/middleware.rs", code_content, code_symbols),
make_file(
"src/protocol/format/tests.rs",
test_content,
vec![test_symbol],
),
make_file(
"src/frontend/scanner.rs",
reason_content,
vec![reason_symbol],
),
]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "authentication middleware".to_string(),
limit: Some(10),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("AuthenticationMiddleware"),
"real auth middleware symbol should appear in results: {result}"
);
assert!(
!result.contains("test_authentication_middleware_format"),
"test scaffolding should be hidden by default for broad fallback explore: {result}"
);
}
#[tokio::test]
async fn test_explore_multi_term_fallback_demotes_single_term_code_noise() {
let auth_content = b"pub fn attach_authentication_middleware() { enforce_guard(); }\n";
let auth_symbol = SymbolRecord {
name: "attach_authentication_middleware".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (0, auth_content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let noise_content = b"pub struct RateLimitKey;\n";
let noise_symbol = SymbolRecord {
name: "RateLimitKey".to_string(),
kind: SymbolKind::Struct,
depth: 0,
sort_order: 0,
byte_range: (0, noise_content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let server = make_server(make_live_index_ready(vec![
make_file("src/auth/middleware.rs", auth_content, vec![auth_symbol]),
make_file("src/rate_limit/key.rs", noise_content, vec![noise_symbol]),
]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "authentication middleware guard".to_string(),
limit: Some(10),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
let auth_pos = result.find("attach_authentication_middleware");
let noise_pos = result.find("RateLimitKey");
assert!(
auth_pos.is_some(),
"multi-term auth middleware symbol should appear in results: {result}"
);
assert!(
noise_pos.is_none() || auth_pos < noise_pos,
"multi-term domain hit should outrank single-term code noise: {result}"
);
}
#[tokio::test]
async fn test_explore_module_path_boosting() {
let content = b"pub struct WatcherInfo {\n debounce_ms: u64,\n}\n";
let watcher_sym = SymbolRecord {
name: "WatcherInfo".to_string(),
kind: SymbolKind::Struct,
depth: 0,
sort_order: 0,
byte_range: (0, content.len() as u32),
line_range: (0, 2),
doc_byte_range: None,
item_byte_range: None,
};
let (key, file) = make_file("src/watcher/mod.rs", content, vec![watcher_sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "watcher".to_string(),
limit: Some(10),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("WatcherInfo"),
"WatcherInfo should appear via module-path boosting: {result}"
);
}
// ── US2 (017): explore concept-ranking fidelity ──────────────────────────
// Helpers for the anchor tests below. The pre-fix scorer multiplied three
// correlated name-overlap factors (raw_count * coverage^2 * alignment), which
// pinned the best name match to 1.00 under max-normalization and cratered every
// other symbol; it also never read the per-file concept-proximity signal. These
// tests assert the rebalanced curve surfaces concept-central symbols and no
// longer buries them.
fn explore_input(query: &str, limit: usize) -> super::ExploreInput {
super::ExploreInput {
project: None,
query: query.to_string(),
limit: Some(limit as u32),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}
}
fn explore_fixture_symbol(name: &str, kind: SymbolKind) -> SymbolRecord {
SymbolRecord {
name: name.to_string(),
kind,
depth: 0,
sort_order: 0,
byte_range: (0, 10),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
}
}
/// Ranked "Symbols (N found):" lines carry a trailing `[score; reason: ...]`
/// suffix; promoted-signals bare-name mentions live outside the block and carry
/// no suffix. Return the (name, normalized-score) pairs in rank order.
fn explore_ranked_scores(output: &str) -> Vec<(String, f32)> {
let mut out = Vec::new();
let mut in_block = false;
for line in output.lines() {
if line.starts_with("Symbols (") {
in_block = true;
continue;
}
if in_block {
if line.trim().is_empty() {
break;
}
let Some(open) = line.rfind('[') else {
continue;
};
let rest = &line[open + 1..];
let Some(semi) = rest.find(';') else { continue };
let Ok(score) = rest[..semi].trim().parse::<f32>() else {
continue;
};
// " {kind} {name} {path} [..]" — name is the 2nd whitespace token.
let head = &line[..open];
let mut toks = head.split_whitespace();
let _kind = toks.next();
if let Some(name) = toks.next() {
out.push((name.to_string(), score));
}
}
}
out
}
fn explore_ranked_score(output: &str, name: &str) -> Option<f32> {
explore_ranked_scores(output)
.into_iter()
.find(|(n, _)| n == name)
.map(|(_, s)| s)
}
#[tokio::test]
async fn explore_surfaces_concept_central_symbols_without_cratering() {
// T011: "worktree routing hook registration in the daemon". The concept-
// central code (WorktreeAwareEditHook, register_if_feature_enabled) lives in
// the daemon file; the probe/* symbols share query tokens by name only.
let files = vec![
make_file(
"src/daemon/worktree_routing.rs",
b"pub struct WorktreeAwareEditHook;\npub fn register_if_feature_enabled() {}\n",
vec![
explore_fixture_symbol("WorktreeAwareEditHook", SymbolKind::Struct),
explore_fixture_symbol("register_if_feature_enabled", SymbolKind::Function),
],
),
make_file(
"src/probe/a.rs",
b"pub fn worktree_routing_alpha() {}\n",
vec![explore_fixture_symbol(
"worktree_routing_alpha",
SymbolKind::Function,
)],
),
make_file(
"src/probe/b.rs",
b"pub fn hook_registration_beta() {}\n",
vec![explore_fixture_symbol(
"hook_registration_beta",
SymbolKind::Function,
)],
),
make_file(
"src/probe/c.rs",
b"pub fn worktree_hook_gamma() {}\n",
vec![explore_fixture_symbol(
"worktree_hook_gamma",
SymbolKind::Function,
)],
),
make_file(
"src/probe/d.rs",
b"pub fn routing_registration_delta() {}\n",
vec![explore_fixture_symbol(
"routing_registration_delta",
SymbolKind::Function,
)],
),
];
let server = make_server(make_live_index_ready(files));
let out = server
.explore(Parameters(explore_input(
"worktree routing hook registration in the daemon",
5,
)))
.await;
// SC-003 / FR-005: both concept-central symbols are surfaced in the ranked
// list (not just the single best name-token match).
assert!(
explore_ranked_score(&out, "register_if_feature_enabled").is_some(),
"register_if_feature_enabled must be in ranked results: {out}"
);
assert!(
explore_ranked_score(&out, "WorktreeAwareEditHook").is_some(),
"WorktreeAwareEditHook must be in ranked results: {out}"
);
// FR-006 anti-crater: pre-fix only 2 symbols cleared 0.50 (1.00, 0.80) while
// the n^2 curve cratered the rest to 0.43 / 0.43 / 0.06. The rebalanced curve
// keeps the concept-central cohort in the strong band.
let non_cratered = explore_ranked_scores(&out)
.iter()
.filter(|(_, s)| *s >= 0.50)
.count();
assert!(
non_cratered >= 3,
"expected >=3 non-cratered symbols (score >= 0.50), got {non_cratered}: {out}"
);
}
#[tokio::test]
async fn explore_lifts_concept_central_over_literal_token_noise() {
// T012: "watcher interact with analyze_file_impact". run_setup is unrelated —
// it matches only because its BODY mentions the literal token. The watcher/
// interact cluster is the concept-central code.
let setup_body =
b"pub fn run_setup() {\n // dispatches to analyze_file_impact\n let _ = \"analyze_file_impact\";\n}\n";
let mut run_setup = explore_fixture_symbol("run_setup", SymbolKind::Function);
run_setup.line_range = (0, 3);
run_setup.byte_range = (0, setup_body.len() as u32);
let files = vec![
make_file("src/cli/setup.rs", setup_body, vec![run_setup]),
make_file(
"src/watcher/reconcile.rs",
b"pub fn watcher_edit_bridge() {}\npub fn interact_edit_hook() {}\n",
vec![
explore_fixture_symbol("watcher_edit_bridge", SymbolKind::Function),
explore_fixture_symbol("interact_edit_hook", SymbolKind::Function),
],
),
];
let server = make_server(make_live_index_ready(files));
let out = server
.explore(Parameters(explore_input(
"watcher interact with analyze_file_impact",
5,
)))
.await;
let ranked = explore_ranked_scores(&out);
let (top_name, _) = ranked.first().expect("at least one ranked symbol");
// FR-006: the single top score is a watcher/interact-central symbol, not the
// unrelated literal-token hit.
assert_ne!(
top_name, "run_setup",
"unrelated literal-token symbol must not hold the top score: {out}"
);
assert!(
top_name == "interact_edit_hook" || top_name == "watcher_edit_bridge",
"top score should be watcher/interact-central, got {top_name}: {out}"
);
// Anti-crater: the co-central watcher symbol is no longer buried near zero
// (pre-fix 0.09).
let bridge = explore_ranked_score(&out, "watcher_edit_bridge")
.expect("watcher_edit_bridge must be ranked");
assert!(
bridge >= 0.25,
"watcher_edit_bridge cratered at {bridge}: {out}"
);
}
#[tokio::test]
async fn explore_exact_name_query_keeps_target_on_top() {
// T013 guard (must pass): naming a symbol's tokens exactly must still rank
// that symbol first — W_NAME >= W_PROX, so a proximity-rich decoy cluster
// cannot displace the exact-name target (no over-correction, FR-006 edge).
let files =
vec![
make_file(
"src/loader.rs",
b"pub fn parse_admission_tier() {}\n",
vec![explore_fixture_symbol("parse_admission_tier", SymbolKind::Function)],
),
make_file(
"src/admission/tier.rs",
b"pub fn admission_gate() {}\npub fn tier_probe() {}\npub fn parse_helper() {}\n",
vec![
explore_fixture_symbol("admission_gate", SymbolKind::Function),
explore_fixture_symbol("tier_probe", SymbolKind::Function),
explore_fixture_symbol("parse_helper", SymbolKind::Function),
],
),
];
let server = make_server(make_live_index_ready(files));
let out = server
.explore(Parameters(explore_input("parse admission tier", 5)))
.await;
let ranked = explore_ranked_scores(&out);
let (top_name, _) = ranked.first().expect("at least one ranked symbol");
assert_eq!(
top_name, "parse_admission_tier",
"exact-name target must stay on top despite the proximity-rich decoy cluster: {out}"
);
}
#[tokio::test]
async fn explore_ranking_is_deterministic() {
// T014 (Constitution IV): identical query + index => identical order, even
// with score ties (worktree_routing_alpha / hook_registration_beta tie).
let build =
|| {
make_live_index_ready(vec![
make_file(
"src/daemon/worktree_routing.rs",
b"pub struct WorktreeAwareEditHook;\npub fn register_if_feature_enabled() {}\n",
vec![
explore_fixture_symbol("WorktreeAwareEditHook", SymbolKind::Struct),
explore_fixture_symbol("register_if_feature_enabled", SymbolKind::Function),
],
),
make_file(
"src/probe/a.rs",
b"pub fn worktree_routing_alpha() {}\n",
vec![explore_fixture_symbol("worktree_routing_alpha", SymbolKind::Function)],
),
make_file(
"src/probe/b.rs",
b"pub fn hook_registration_beta() {}\n",
vec![explore_fixture_symbol("hook_registration_beta", SymbolKind::Function)],
),
])
};
let query = "worktree routing hook registration in the daemon";
let first = make_server(build())
.explore(Parameters(explore_input(query, 5)))
.await;
let second = make_server(build())
.explore(Parameters(explore_input(query, 5)))
.await;
assert_eq!(
explore_ranked_scores(&first),
explore_ranked_scores(&second),
"explore ranking must be deterministic across identical runs"
);
}
#[tokio::test]
async fn explore_is_frecency_neutral() {
// T015 (Constitution V): explore is a discovery tool and must not bump
// frecency. With a real repo_root a bump WOULD register in the session store;
// a fresh unique root that explore leaves untouched yields no ranking history.
use std::path::Path;
let root = TempDir::new().expect("tempdir");
let files = vec![make_file(
"src/watcher/reconcile.rs",
b"pub fn watcher_edit_bridge() {}\npub fn interact_edit_hook() {}\n",
vec![
explore_fixture_symbol("watcher_edit_bridge", SymbolKind::Function),
explore_fixture_symbol("interact_edit_hook", SymbolKind::Function),
],
)];
let server = make_server_with_root(
make_live_index_ready(files),
Some(root.path().to_path_buf()),
);
let _ = server
.explore(Parameters(explore_input("watcher interact reconcile", 5)))
.await;
let now = 0i64;
let snapshot = crate::live_index::frecency::ranking_scores_for_paths(
root.path(),
None,
&[Path::new("src/watcher/reconcile.rs")],
now,
)
.expect("frecency ranking probe");
assert!(
snapshot.is_none(),
"explore must not bump frecency; found history: {snapshot:?}"
);
}
#[tokio::test]
async fn test_explore_concept_plus_remainder() {
let content = b"pub fn handle_watcher_error() {}\n";
let sym = SymbolRecord {
name: "handle_watcher_error".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (0, content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let (key, file) = make_file("src/watcher/errors.rs", content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "error handling in the watcher".to_string(),
limit: Some(10),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("handle_watcher_error") || result.contains("watcher"),
"concept+remainder should surface watcher results: {result}"
);
}
#[tokio::test]
async fn test_explore_concept_remainder_matching_symbol_outranks_generic_bucket() {
// Regression: query "admission tiering decide which files get indexed"
// matches the "Indexing" concept (via "indexed" -> "index" stemming),
// which previously collapsed the topic and buried the real admission
// symbols under generic Indexing/LiveIndex hits. The remainder noun
// "admission" resolves to indexed symbol names and must win.
let admission_content =
b"pub enum AdmissionTier { Indexed, MetadataOnly, HardSkip }\npub struct AdmissionDecision { pub tier: AdmissionTier }\n";
let admission_symbols = vec![
SymbolRecord {
name: "AdmissionTier".to_string(),
kind: SymbolKind::Enum,
depth: 0,
sort_order: 0,
byte_range: (0, 58),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
},
SymbolRecord {
name: "AdmissionDecision".to_string(),
kind: SymbolKind::Struct,
depth: 0,
sort_order: 1,
byte_range: (58, admission_content.len() as u32),
line_range: (1, 1),
doc_byte_range: None,
item_byte_range: None,
},
];
// Generic indexing symbols the "Indexing" concept bucket targets
// directly ("index"/"reindex"). These previously dominated the output.
let index_content = b"pub struct LiveIndex {}\npub fn reindex_all() {}\n";
let index_symbols = vec![
SymbolRecord {
name: "LiveIndex".to_string(),
kind: SymbolKind::Struct,
depth: 0,
sort_order: 0,
byte_range: (0, 23),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
},
SymbolRecord {
name: "reindex_all".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 1,
byte_range: (24, index_content.len() as u32),
line_range: (1, 1),
doc_byte_range: None,
item_byte_range: None,
},
];
let server = make_server(make_live_index_ready(vec![
make_file("src/domain/index.rs", admission_content, admission_symbols),
make_file("src/live_index/store.rs", index_content, index_symbols),
]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "admission tiering decide which files get indexed".to_string(),
limit: Some(10),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
// The load-bearing query noun must surface its symbols.
assert!(
result.contains("AdmissionTier"),
"explore must surface AdmissionTier for an 'admission' query: {result}"
);
// The "Indexing" concept matched ONLY via a single-word stem misfire
// ("indexed" -> "indexing") while the query named the real noun
// "admission". The header must lead with that specific term and demote
// the stem-only concept to a parenthetical signal hint, not front a label
// the user never typed.
assert!(
result.contains("Exploring: admission (+ Indexing signals)"),
"stem-only single-word concept must be demoted behind the specific query noun: {result}"
);
// The specific admission match must rank above the generic concept
// bucket symbols (LiveIndex, reindex_all), not be buried beneath them.
let admission_pos = result
.find("AdmissionTier")
.expect("AdmissionTier must be present");
for generic in ["LiveIndex", "reindex_all"] {
if let Some(generic_pos) = result.find(generic) {
assert!(
admission_pos < generic_pos,
"AdmissionTier should rank above the generic '{generic}' bucket hit: {result}"
);
}
}
}
#[tokio::test]
async fn test_explore_exact_concept_no_remainder() {
let content = b"pub enum SymForgeError {}\n";
let sym = SymbolRecord {
name: "SymForgeError".to_string(),
kind: SymbolKind::Enum,
depth: 0,
sort_order: 0,
byte_range: (0, content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let (key, file) = make_file("src/error.rs", content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "error handling".to_string(),
limit: Some(10),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("SymForgeError"),
"exact concept should find error symbols: {result}"
);
}
#[tokio::test]
async fn test_explore_hides_vendor_noise_by_default() {
// Vendor file should be filtered out when include_noise is false (default).
let vendor_content = b"pub fn vendor_func() {}\n";
let vendor_sym = SymbolRecord {
name: "vendor_func".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (0, vendor_content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let src_content = b"pub fn process_error() {}\n";
let src_sym = SymbolRecord {
name: "process_error".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (0, src_content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let (vkey, vfile) = make_file("vendor/somelib/lib.rs", vendor_content, vec![vendor_sym]);
let (skey, sfile) = make_file("src/error.rs", src_content, vec![src_sym]);
let server = make_server(make_live_index_ready(vec![(vkey, vfile), (skey, sfile)]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "error handling".to_string(),
limit: Some(10),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
!result.contains("vendor_func"),
"vendor symbol should be hidden by default: {result}"
);
assert!(
result.contains("process_error"),
"src symbol should still appear: {result}"
);
}
#[tokio::test]
async fn test_explore_includes_vendor_when_include_noise_true() {
let vendor_content = b"pub struct VendorError {}\n";
let vendor_sym = SymbolRecord {
name: "VendorError".to_string(),
kind: SymbolKind::Struct,
depth: 0,
sort_order: 0,
byte_range: (0, vendor_content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let (vkey, vfile) = make_file("vendor/somelib/lib.rs", vendor_content, vec![vendor_sym]);
let server = make_server(make_live_index_ready(vec![(vkey, vfile)]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "error handling".to_string(),
limit: Some(10),
depth: None,
include_noise: Some(true),
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("VendorError"),
"vendor symbol should appear with include_noise=true: {result}"
);
}
#[tokio::test]
async fn test_explore_noise_hint_shown_when_results_hidden() {
let vendor_content = b"pub struct VendorError {}\n";
let vendor_sym = SymbolRecord {
name: "VendorError".to_string(),
kind: SymbolKind::Struct,
depth: 0,
sort_order: 0,
byte_range: (0, vendor_content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let (vkey, vfile) = make_file("vendor/somelib/lib.rs", vendor_content, vec![vendor_sym]);
let server = make_server(make_live_index_ready(vec![(vkey, vfile)]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "error handling".to_string(),
limit: Some(10),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("vendor/generated files hidden")
&& result.contains("include_noise=true"),
"should show noise hint when results are hidden: {result}"
);
}
// --- SF-STRESS-013 ranking-calibration regressions -------------------
#[test]
fn test_concept_text_query_boundary_rejects_identifier_internal_substring() {
// The corpus howler: concept idiom `try {` substring-matched
// `public string Country { get; set; }` (coun-TRY-{), flooding DTO
// properties into "Error Handling".
assert!(
!super::concept_text_query_matches_on_boundary(
"public string Country { get; set; }",
"try {"
),
"`try {{` must not match inside `Country {{`"
);
// A genuine `try {` at a word boundary still matches.
assert!(
super::concept_text_query_matches_on_boundary(" try {", "try {"),
"a real `try {{` must still match"
);
assert!(
super::concept_text_query_matches_on_boundary("} else { try { foo()", "try {"),
"`try {{` after a non-word char must still match"
);
// `unwrap()` as the suffix of a larger identifier (`my_unwrap()`) is an
// identifier-internal collision and must be rejected; a standalone
// `x.unwrap()` (preceded by `.`) is a real boundary hit.
assert!(
!super::concept_text_query_matches_on_boundary(" let v = my_unwrap();", "unwrap()"),
"`unwrap()` must not match inside `my_unwrap()`"
);
assert!(
super::concept_text_query_matches_on_boundary(" let v = x.unwrap();", "unwrap()"),
"a real `.unwrap()` call must still match"
);
// Punctuation-led queries fall through to plain containment.
assert!(
super::concept_text_query_matches_on_boundary(" .expect(\"boom\")", ".expect("),
"punctuation-led queries keep substring semantics"
);
}
#[test]
fn test_explore_path_penalty_demotes_doc_singular_and_html() {
// SF-STRESS-013: redis's deps/lua/doc/manual.html (8800-line single
// 'other html' symbol) topped ranking at 1.00. Both the `/doc/`
// (singular) segment and the `.html` extension must hit the doc bucket
// so it is down-weighted to the doc penalty (2) rather than full (8).
assert_eq!(
super::explore_path_penalty("deps/lua/doc/manual.html", None),
2,
"/doc/ + .html must be penalized as documentation"
);
assert_eq!(
super::explore_path_penalty("docs/Enums/Result.html", None),
2,
".html docs must be penalized"
);
assert_eq!(
super::explore_path_penalty("site/index.htm", None),
2,
".htm must be penalized like .html"
);
// Ordinary source keeps full weight.
assert_eq!(
super::explore_path_penalty("src/error.rs", None),
8,
"ordinary source must keep full weight"
);
}
#[tokio::test]
async fn test_explore_noise_filtered_before_truncate_keeps_real_symbol() {
// SF-STRESS-013 django starvation: noise filtering ran AFTER
// truncate(limit), so hidden vendor symbols consumed the budget and a
// real source symbol never surfaced. With limit=1 and a vendor symbol
// that sorts ahead alphabetically, the real symbol must still win.
let vendor_content = b"pub struct AAA_Error {}\n";
let vendor_sym = SymbolRecord {
name: "AAA_Error".to_string(),
kind: SymbolKind::Struct,
depth: 0,
sort_order: 0,
byte_range: (0, vendor_content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let src_content = b"pub struct ResultError {}\n";
let src_sym = SymbolRecord {
name: "ResultError".to_string(),
kind: SymbolKind::Struct,
depth: 0,
sort_order: 0,
byte_range: (0, src_content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let (vkey, vfile) = make_file("vendor/lib/lib.rs", vendor_content, vec![vendor_sym]);
let (skey, sfile) = make_file("src/error.rs", src_content, vec![src_sym]);
let server = make_server(make_live_index_ready(vec![(vkey, vfile), (skey, sfile)]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "error handling".to_string(),
limit: Some(1),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("ResultError"),
"real source symbol must survive a tight limit even though a vendor \
symbol sorts ahead; the noise filter must run before truncate: {result}"
);
assert!(
!result.contains("AAA_Error"),
"vendor symbol must remain hidden: {result}"
);
}
#[tokio::test]
async fn test_explore_footer_drops_unbacked_caller_density_claim() {
// SF-STRESS-013: the scorer never computes caller density; the footer
// must not advertise a signal it does not use.
let content = b"pub enum AppError {}\n";
let sym = SymbolRecord {
name: "AppError".to_string(),
kind: SymbolKind::Enum,
depth: 0,
sort_order: 0,
byte_range: (0, content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let (key, file) = make_file("src/error.rs", content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.explore(Parameters(super::ExploreInput {
project: None,
query: "error handling".to_string(),
limit: Some(5),
depth: None,
include_noise: None,
include_vendor: None,
include_personal_tooling: None,
language: None,
path_prefix: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("ranked by:"),
"footer must be present: {result}"
);
assert!(
!result.contains("caller density"),
"footer must not claim caller density: {result}"
);
}
// --- Task 2.2 path-filter tests --------------------------------------
#[tokio::test]
async fn test_search_text_hides_vendor_paths_by_default() {
let server = make_server(make_live_index_ready_with_vendor_file());
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("noisy_token".to_string()),
..Default::default()
}))
.await;
assert!(
!result.contains("vendor/foo/bar.rs"),
"vendor paths must be suppressed by default; got:\n{result}"
);
assert!(
result.contains("noise-filtered"),
"filtered-count footer expected; got:\n{result}"
);
}
#[tokio::test]
async fn test_search_text_includes_vendor_when_flag_true() {
let server = make_server(make_live_index_ready_with_vendor_file());
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("noisy_token".to_string()),
include_vendor: Some(true),
..Default::default()
}))
.await;
assert!(
result.contains("vendor/foo/bar.rs"),
"vendor paths must appear when include_vendor=true; got:\n{result}"
);
}
#[tokio::test]
async fn test_search_text_vendor_filter_runs_before_result_cap() {
let vendor_content = b"needle one\nneedle two\nneedle three\n";
let source_content = b"needle source\n";
let server = make_server(make_live_index_ready(vec![
make_file("vendor/noisy/lib.rs", vendor_content, vec![]),
make_file("src/normal.rs", source_content, vec![]),
]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("needle".to_string()),
limit: Some(1),
..Default::default()
}))
.await;
assert!(
result.contains("src/normal.rs"),
"non-vendor hit must survive even when vendor has more matches: {result}"
);
assert!(
!result.contains("vendor/noisy/lib.rs"),
"vendor path should remain suppressed by default: {result}"
);
assert!(
result.contains("3 noise-filtered match(es) suppressed"),
"suppressed vendor matches should be counted: {result}"
);
}
#[tokio::test]
async fn test_search_text_suppressed_count_caps_broad_vendor_matches() {
let mut vendor_content = String::new();
for index in 0..150 {
vendor_content.push_str(&format!("needle hidden_{index}\n"));
}
let source_content = b"needle source\n";
let server = make_server(make_live_index_ready(vec![
make_file("vendor/noisy/lib.rs", vendor_content.as_bytes(), vec![]),
make_file("src/normal.rs", source_content, vec![]),
]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("needle".to_string()),
limit: Some(1),
..Default::default()
}))
.await;
assert!(
result.contains("src/normal.rs"),
"non-vendor hit must remain visible: {result}"
);
assert!(
result.contains("100+ noise-filtered match(es) suppressed"),
"broad hidden counts should be capped instead of exact-scanning vendor trees: {result}"
);
}
#[tokio::test]
async fn test_search_text_hides_personal_tooling_paths_by_default() {
let server = make_server(make_live_index_ready_with_vendor_file());
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("noisy_token".to_string()),
..Default::default()
}))
.await;
assert!(
!result.contains(".claude/gsd-local-patches/"),
"personal tooling paths must be suppressed by default; got:\n{result}"
);
}
#[tokio::test]
async fn test_search_text_includes_personal_tooling_when_flag_true() {
let server = make_server(make_live_index_ready_with_vendor_file());
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("noisy_token".to_string()),
include_personal_tooling: Some(true),
..Default::default()
}))
.await;
assert!(
result.contains(".claude/gsd-local-patches/"),
"personal tooling paths must appear when include_personal_tooling=true; got:\n{result}"
);
}
#[tokio::test]
async fn test_search_text_suppression_footer_counts_vendor() {
let server = make_server(make_live_index_ready_with_vendor_file());
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("noisy_token".to_string()),
..Default::default()
}))
.await;
// Fixture seeds 3 files (src + vendor + personal-tooling), each with one
// match for `noisy_token`. Default-suppress hides 2 (vendor + personal),
// so the envelope footer must report at least 2 noise-filtered matches.
assert!(
result.contains("noise-filtered match(es) suppressed"),
"footer must report noise-filtered count; got:\n{result}"
);
let count_ok = result.contains("2 noise-filtered") || result.contains("3 noise-filtered");
assert!(
count_ok,
"footer must report >=2 suppressed matches (vendor + personal-tooling); got:\n{result}"
);
}
#[tokio::test]
async fn test_explore_finer_grained_include_vendor_flag() {
// B1 additive: include_vendor=true alone, include_noise unset, must surface vendor.
// Mirrors the fixture from test_explore_includes_vendor_when_include_noise_true so
// the concept-query "error handling" finds `VendorError` via the "Error" token.
let vendor_content = b"pub struct VendorError {}\n";
let vendor_sym = SymbolRecord {
name: "VendorError".to_string(),
kind: SymbolKind::Struct,
depth: 0,
sort_order: 0,
byte_range: (0, vendor_content.len() as u32),
line_range: (0, 0),
doc_byte_range: None,
item_byte_range: None,
};
let (vkey, vfile) = make_file("vendor/somelib/lib.rs", vendor_content, vec![vendor_sym]);
let server = make_server(make_live_index_ready(vec![(vkey, vfile)]));
let result = server
.explore(Parameters(super::ExploreInput {
query: "error handling".to_string(),
limit: Some(10),
include_vendor: Some(true),
..Default::default()
}))
.await;
assert!(
result.contains("VendorError"),
"include_vendor=true alone must surface vendor (B1 additive); got: {result}"
);
}
// ── INFR-05: No v1 tools in server ──────────────────────────────────────
#[test]
fn test_retired_v1_tools_stay_out_of_server() {
// Build the tool list by inspecting what tool_router() generates
let server = make_server(make_live_index_ready(vec![]));
let router = server.tool_router.clone();
let tool_names: Vec<String> = router
.list_all()
.iter()
.map(|t| t.name.to_string())
.collect();
assert!(
tool_names.iter().any(|name| name == "checkpoint_now"),
"checkpoint_now is a current v7 checkpoint tool and must remain registered; found: {tool_names:?}"
);
let retired_v1_tools = [
"cancel_index_run",
"resume_index_run",
"get_provenance",
"get_trust",
"verify_chunk",
];
for v1_tool in &retired_v1_tools {
assert!(
!tool_names.iter().any(|n| n == v1_tool),
"v1 tool '{v1_tool}' must not appear in server tool list (INFR-05); found: {tool_names:?}"
);
}
}
#[test]
fn test_tools_registered_count_is_stable() {
let server = make_server(make_live_index_ready(vec![]));
let tool_count = server.tool_router.list_all().len();
// Sanity check: we should have a reasonable number of tools.
// Update this lower bound when removing tools; it prevents accidental regressions.
assert!(
tool_count >= 24,
"server should expose at least 24 tools; found {tool_count}"
);
}
#[tokio::test]
async fn test_trace_symbol_delegates_to_formatter() {
let target = make_file(
"src/lib.rs",
b"fn process() {}\n",
vec![make_symbol("process", SymbolKind::Function, 1, 1)],
);
let server = make_server(make_live_index_ready(vec![target]));
let result = server
.trace_symbol(Parameters(super::TraceSymbolInput {
path: "src/lib.rs".to_string(),
name: "process".to_string(),
kind: None,
symbol_line: None,
sections: None,
verbosity: None,
max_tokens: None,
estimate: None,
}))
.await;
assert!(result.contains("fn process"), "got: {result}");
assert!(result.contains("Callers (0)"), "got: {result}");
}
#[tokio::test]
async fn test_get_symbol_context_trace_mode() {
let target = make_file(
"src/lib.rs",
b"fn process() {}\n",
vec![make_symbol("process", SymbolKind::Function, 1, 1)],
);
let server = make_server(make_live_index_ready(vec![target]));
let result = server
.get_symbol_context(Parameters(super::GetSymbolContextInput {
project: None,
name: "process".to_string(),
file: None,
path: Some("src/lib.rs".to_string()),
symbol_kind: None,
symbol_line: None,
verbosity: None,
bundle: None,
sections: Some(vec!["dependents".to_string()]),
max_tokens: None,
estimate: None,
}))
.await;
assert!(
result.contains("fn process"),
"trace mode should show definition, got: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_context_trace_mode_requires_path() {
let target = make_file(
"src/lib.rs",
b"fn process() {}\n",
vec![make_symbol("process", SymbolKind::Function, 1, 1)],
);
let server = make_server(make_live_index_ready(vec![target]));
let result = server
.get_symbol_context(Parameters(super::GetSymbolContextInput {
project: None,
name: "process".to_string(),
file: None,
path: None,
symbol_kind: None,
symbol_line: None,
verbosity: None,
bundle: None,
sections: Some(vec![]),
max_tokens: None,
estimate: None,
}))
.await;
assert!(
result.contains("Error: sections requires"),
"should require path, got: {result}"
);
}
#[tokio::test]
async fn test_inspect_match_delegates_to_formatter() {
let target = make_file(
"src/lib.rs",
b"fn process() {\n let x = 1;\n}\n",
vec![make_symbol("process", SymbolKind::Function, 0, 2)],
);
let server = make_server(make_live_index_ready(vec![target]));
let result = server
.inspect_match(Parameters(super::InspectMatchInput {
path: "src/lib.rs".to_string(),
line: 2,
context: None,
sibling_limit: None,
estimate: None,
max_tokens: None,
}))
.await;
// Verify excerpt
assert!(result.contains("2: let x = 1;"), "got: {result}");
// Verify enclosing symbol (line_range is 0-based internally, displayed as 1-based)
assert!(
result.contains("Enclosing symbol: fn process (lines 1-3)"),
"got: {result}"
);
}
#[tokio::test]
async fn test_inspect_match_default_sibling_limit_caps_at_10() {
// Build a file with 15 top-level functions (depth 0).
let mut syms = Vec::new();
for i in 0u32..15 {
syms.push(make_symbol(&format!("fn_{i}"), SymbolKind::Function, i, i));
}
let content = (0u32..15)
.map(|i| format!("fn fn_{i}() {{}}"))
.collect::<Vec<_>>()
.join("\n");
let target = make_file("src/lib.rs", content.as_bytes(), syms);
let server = make_server(make_live_index_ready(vec![target]));
// No sibling_limit — defaults to 10.
let result = server
.inspect_match(Parameters(super::InspectMatchInput {
path: "src/lib.rs".to_string(),
line: 1,
context: Some(0),
sibling_limit: None,
estimate: None,
max_tokens: None,
}))
.await;
// Count sibling rows (each rendered with two-space indent).
let sibling_rows = result
.lines()
.filter(|l| l.starts_with(" ") && !l.starts_with(" ..."))
.count();
assert!(
sibling_rows <= 10,
"expected ≤10 siblings, got {sibling_rows}; output:\n{result}"
);
assert!(
result.contains("... and 5 more siblings"),
"expected overflow hint; got:\n{result}"
);
}
#[tokio::test]
async fn test_inspect_match_sibling_limit_5_shows_exactly_5() {
let mut syms = Vec::new();
for i in 0u32..12 {
syms.push(make_symbol(&format!("fn_{i}"), SymbolKind::Function, i, i));
}
let content = (0u32..12)
.map(|i| format!("fn fn_{i}() {{}}"))
.collect::<Vec<_>>()
.join("\n");
let target = make_file("src/lib.rs", content.as_bytes(), syms);
let server = make_server(make_live_index_ready(vec![target]));
let result = server
.inspect_match(Parameters(super::InspectMatchInput {
path: "src/lib.rs".to_string(),
line: 1,
context: Some(0),
sibling_limit: Some(5),
estimate: None,
max_tokens: None,
}))
.await;
let sibling_rows = result
.lines()
.filter(|l| l.starts_with(" ") && !l.starts_with(" ..."))
.count();
assert_eq!(
sibling_rows, 5,
"expected exactly 5 siblings; output:\n{result}"
);
assert!(
result.contains("... and 7 more siblings"),
"expected overflow hint; got:\n{result}"
);
}
#[tokio::test]
async fn test_inspect_match_sibling_limit_0_hides_siblings() {
let mut syms = Vec::new();
for i in 0u32..5 {
syms.push(make_symbol(&format!("fn_{i}"), SymbolKind::Function, i, i));
}
let content = (0u32..5)
.map(|i| format!("fn fn_{i}() {{}}"))
.collect::<Vec<_>>()
.join("\n");
let target = make_file("src/lib.rs", content.as_bytes(), syms);
let server = make_server(make_live_index_ready(vec![target]));
let result = server
.inspect_match(Parameters(super::InspectMatchInput {
path: "src/lib.rs".to_string(),
line: 1,
context: Some(0),
sibling_limit: Some(0),
estimate: None,
max_tokens: None,
}))
.await;
assert!(
!result.contains("Nearby siblings:"),
"siblings should be hidden; got:\n{result}"
);
}
#[tokio::test]
async fn test_get_repo_map_tree_returns_tree() {
let sym = make_symbol("main", SymbolKind::Function, 1, 5);
let (key, file) = make_file("src/main.rs", b"fn main() {}", vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.get_repo_map(Parameters(super::GetRepoMapInput {
project: None,
detail: Some("tree".to_string()),
path: None,
depth: None,
max_files: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("main.rs"),
"get_repo_map(tree) should include file name; got: {result}"
);
assert!(
result.contains("symbol"),
"get_repo_map(tree) should show symbol count; got: {result}"
);
}
#[tokio::test]
async fn test_get_repo_map_tree_loading_guard_empty() {
let server = make_server(make_live_index_empty());
let result = server
.get_repo_map(Parameters(super::GetRepoMapInput {
project: None,
detail: Some("tree".to_string()),
path: None,
depth: None,
max_files: None,
estimate: None,
max_tokens: None,
}))
.await;
assert_eq!(result, crate::protocol::format::empty_guard_message());
}
#[tokio::test]
async fn test_find_references_loading_guard_empty() {
let server = make_server(make_live_index_empty());
let result = server
.find_references(Parameters(super::FindReferencesInput {
name: "process".to_string(),
kind: None,
path: None,
symbol_kind: None,
symbol_line: None,
limit: None,
max_per_file: None,
compact: None,
mode: None,
direction: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert_eq!(result, crate::protocol::format::empty_guard_message());
}
#[tokio::test]
async fn test_find_references_discloses_multiple_same_named_definitions() {
// BUG 3 (trust): a bare repo-wide name match silently merges references
// to DIFFERENT same-named definitions. When N>1 definitions share the
// name, the output must disclose this and tell the caller to scope by
// path, instead of presenting a conflated list as precise.
let def_a = make_symbol("update_status", SymbolKind::Function, 1, 1);
let def_b = make_symbol("update_status", SymbolKind::Function, 1, 1);
let caller_a = make_symbol("caller_a", SymbolKind::Function, 2, 2);
let file_a = make_file_with_refs(
"src/store_a.rs",
b"fn update_status() {}\nfn caller_a() { update_status(); }\n",
vec![def_a, caller_a],
vec![make_ref(
"update_status",
None,
ReferenceKind::Call,
1,
Some(1),
)],
);
let caller_b = make_symbol("caller_b", SymbolKind::Function, 2, 2);
let file_b = make_file_with_refs(
"src/store_b.rs",
b"fn update_status() {}\nfn caller_b() { update_status(); }\n",
vec![def_b, caller_b],
vec![make_ref(
"update_status",
None,
ReferenceKind::Call,
1,
Some(1),
)],
);
let server = make_server(make_live_index_ready(vec![file_a, file_b]));
let result = server
.find_references(Parameters(find_references_input("update_status")))
.await;
assert!(
result.contains("2 definitions named \"update_status\""),
"must disclose multiple same-named definitions; got: {result}"
);
assert!(
result.contains("MAY MIX") && result.contains("Pass `path`"),
"disclosure must warn of mixing and point to path scoping; got: {result}"
);
}
#[tokio::test]
async fn test_find_references_no_disclosure_for_unique_definition() {
// The disclosure must NOT fire when only one definition has the name —
// the bare-name result is precise enough and the note would be noise.
let def = make_symbol("solitary_fn", SymbolKind::Function, 1, 1);
let caller = make_symbol("caller", SymbolKind::Function, 2, 2);
let file = make_file_with_refs(
"src/only.rs",
b"fn solitary_fn() {}\nfn caller() { solitary_fn(); }\n",
vec![def, caller],
vec![make_ref(
"solitary_fn",
None,
ReferenceKind::Call,
1,
Some(1),
)],
);
let server = make_server(make_live_index_ready(vec![file]));
let result = server
.find_references(Parameters(find_references_input("solitary_fn")))
.await;
assert!(
!result.contains("definitions named"),
"single definition must not trigger the disclosure; got: {result}"
);
}
#[tokio::test]
async fn test_find_references_discloses_tier2_textual_match() {
// Dogfood #1 (2026-07-06): a first-party file demoted to Tier-2 for size
// held the only construction site while the envelope claimed
// "full for current scope". The sweep must confess the textual match on
// BOTH the zero-hits path and the envelope.
let dir = tempfile::tempdir().unwrap();
let mut big = "x".repeat(1_100_000);
big.push_str("\nlet r = PortRegistry::new();\n");
std::fs::write(dir.path().join("big.rs"), &big).unwrap();
// Index knows the definition but has ZERO references to it (the only
// reference lives in the Tier-2 file) — the exact field failure shape.
let def = make_symbol("PortRegistry", SymbolKind::Struct, 1, 1);
let (key, file) = make_file("src/lib.rs", b"struct PortRegistry;\n", vec![def]);
let mut index = make_live_index_ready(vec![(key, file)]);
index.manifest_entries = vec![manifest_metadata_entry(
"big.rs",
big.len() as u64,
crate::domain::index::SkipReason::SizeThreshold,
)];
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let result = server
.find_references(Parameters(find_references_input("PortRegistry")))
.await;
assert!(
result.contains("Tier-2 exclusion"),
"envelope must confess the unscanned Tier-2 textual match; got: {result}"
);
assert!(
result.contains("big.rs"),
"the unscanned file must be named; got: {result}"
);
}
#[tokio::test]
async fn test_find_references_tier2_sweep_stays_silent_without_match() {
// No lie to confess: the Tier-2 file does not contain the queried name,
// so the disclosure must not fire (noise is its own honesty failure).
let dir = tempfile::tempdir().unwrap();
let big = "y".repeat(1_100_000);
std::fs::write(dir.path().join("big.rs"), &big).unwrap();
let def = make_symbol("solitary_fn", SymbolKind::Function, 1, 1);
let caller = make_symbol("caller", SymbolKind::Function, 2, 2);
let file = make_file_with_refs(
"src/only.rs",
b"fn solitary_fn() {}\nfn caller() { solitary_fn(); }\n",
vec![def, caller],
vec![make_ref(
"solitary_fn",
None,
ReferenceKind::Call,
1,
Some(1),
)],
);
let mut index = make_live_index_ready(vec![file]);
index.manifest_entries = vec![manifest_metadata_entry(
"big.rs",
big.len() as u64,
crate::domain::index::SkipReason::SizeThreshold,
)];
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let result = server
.find_references(Parameters(find_references_input("solitary_fn")))
.await;
assert!(
!result.contains("Tier-2 exclusion"),
"no textual match means no disclosure; got: {result}"
);
assert!(
result.contains("full for current scope"),
"completeness stays unqualified when nothing was excluded; got: {result}"
);
}
#[tokio::test]
async fn test_find_references_usage_trace_carries_recall_caveat() {
// R3 honesty: type/value-usage traces have best-effort recall (dynamic
// dispatch, macros, reflection, cross-language are missed). The default
// kind sweeps in type/value usages, so the completeness envelope must
// carry the recall caveat. Without it, a caller cannot tell the trace
// may be partial — a silent degrade.
let def = make_symbol("Widget", SymbolKind::Struct, 1, 1);
let user = make_symbol("user", SymbolKind::Function, 2, 2);
let file = make_file_with_refs(
"src/widget.rs",
b"struct Widget;\nfn user(w: Widget) {}\n",
vec![def, user],
vec![make_ref(
"Widget",
None,
ReferenceKind::TypeUsage,
2,
Some(2),
)],
);
let server = make_server(make_live_index_ready(vec![file]));
let result = server
.find_references(Parameters(find_references_input("Widget")))
.await;
assert!(
result.contains("usage-trace recall is best-effort")
&& result.contains("dynamic dispatch"),
"type/value-usage trace must carry the recall-confidence caveat; got: {result}"
);
}
#[tokio::test]
async fn test_find_references_call_trace_has_no_recall_caveat() {
// Targeted, not blanket: direct `call` references are extracted reliably,
// so they must NOT carry the best-effort recall caveat — otherwise it is
// boilerplate noise the model learns to ignore.
let def = make_symbol("do_work", SymbolKind::Function, 1, 1);
let caller = make_symbol("caller", SymbolKind::Function, 2, 2);
let file = make_file_with_refs(
"src/work.rs",
b"fn do_work() {}\nfn caller() { do_work(); }\n",
vec![def, caller],
vec![make_ref("do_work", None, ReferenceKind::Call, 2, Some(2))],
);
let server = make_server(make_live_index_ready(vec![file]));
let mut input = find_references_input("do_work");
input.kind = Some("call".to_string());
let result = server.find_references(Parameters(input)).await;
assert!(
!result.contains("usage-trace recall is best-effort"),
"direct call trace must NOT carry the recall caveat (targeted, not blanket); got: {result}"
);
}
#[tokio::test]
async fn test_find_references_unrecognized_kind_carries_recall_caveat() {
// Drift guard: an unrecognized `kind` maps to `None` in
// find_references_kind_filter -> NO filter -> ALL kinds returned,
// including best-effort type/value usages. The caveat must therefore
// still fire (it mirrors the filter), or a typo'd kind silently ships an
// unmarked best-effort trace — the exact silent-degrade R3 prevents.
let def = make_symbol("Widget", SymbolKind::Struct, 1, 1);
let user = make_symbol("user", SymbolKind::Function, 2, 2);
let file = make_file_with_refs(
"src/widget.rs",
b"struct Widget;\nfn user(w: Widget) {}\n",
vec![def, user],
vec![make_ref(
"Widget",
None,
ReferenceKind::TypeUsage,
2,
Some(2),
)],
);
let server = make_server(make_live_index_ready(vec![file]));
let mut input = find_references_input("Widget");
input.kind = Some("totally-bogus-kind".to_string());
let result = server.find_references(Parameters(input)).await;
assert!(
result.contains("usage-trace recall is best-effort"),
"unrecognized kind returns all (best-effort) refs, so the caveat must \
still fire (filter-mirrored, no drift); got: {result}"
);
}
#[tokio::test]
async fn test_find_dependents_loading_guard_empty() {
let server = make_server(make_live_index_empty());
let result = server
.find_dependents(Parameters(super::FindDependentsInput {
project: None,
path: "src/lib.rs".to_string(),
name: None,
limit: None,
max_per_file: None,
format: None,
compact: None,
estimate: None,
max_tokens: None,
}))
.await;
assert_eq!(result, crate::protocol::format::empty_guard_message());
}
#[tokio::test]
async fn test_get_symbol_context_bundle_loading_guard_empty() {
let server = make_server(make_live_index_empty());
let result = server
.get_symbol_context(Parameters(super::GetSymbolContextInput {
project: None,
name: "process".to_string(),
file: None,
path: Some("src/lib.rs".to_string()),
symbol_kind: None,
symbol_line: None,
verbosity: None,
bundle: Some(true),
sections: None,
max_tokens: None,
estimate: None,
}))
.await;
assert_eq!(result, crate::protocol::format::empty_guard_message());
}
#[tokio::test]
async fn test_get_symbol_context_bundle_delegates_to_formatter() {
let server = make_server(make_live_index_ready(vec![]));
let result = server
.get_symbol_context(Parameters(super::GetSymbolContextInput {
project: None,
name: "process".to_string(),
file: None,
path: Some("src/nonexistent.rs".to_string()),
symbol_kind: None,
symbol_line: None,
verbosity: None,
bundle: Some(true),
sections: None,
max_tokens: None,
estimate: None,
}))
.await;
assert!(result.contains("File not found"), "got: {result}");
}
#[tokio::test]
async fn test_get_symbol_context_bundle_exact_selector_uses_line_and_exact_callers() {
let target = make_file(
"src/db.rs",
b"fn connect() { first(); }\nfn connect() { second(); }\n",
vec![
make_symbol("connect", SymbolKind::Function, 1, 1),
make_symbol("connect", SymbolKind::Function, 2, 2),
],
);
let dependent = make_file_with_refs(
"src/service.rs",
b"use crate::db::connect;\nfn run() { connect(); }\n",
vec![make_symbol("run", SymbolKind::Function, 2, 2)],
vec![
make_ref("db", Some("crate::db"), ReferenceKind::Import, 0, None),
make_ref(
"connect",
Some("crate::db::connect"),
ReferenceKind::Call,
1,
Some(0),
),
],
);
let unrelated = make_file_with_refs(
"src/other.rs",
b"fn run() { connect(); }\n",
vec![make_symbol("run", SymbolKind::Function, 1, 1)],
vec![make_ref("connect", None, ReferenceKind::Call, 0, Some(0))],
);
let server = make_server(make_live_index_ready(vec![target, dependent, unrelated]));
let result = server
.get_symbol_context(Parameters(super::GetSymbolContextInput {
project: None,
name: "connect".to_string(),
file: None,
path: Some("src/db.rs".to_string()),
symbol_kind: Some("fn".to_string()),
symbol_line: Some(2),
verbosity: None,
bundle: Some(true),
sections: None,
max_tokens: None,
estimate: None,
}))
.await;
assert!(
result.contains("src/service.rs"),
"expected dependent hit: {result}"
);
assert!(
result.contains("Trust: exact | current index | parsed"),
"bundle mode should surface the compact trust line; got: {result}"
);
assert!(
result.contains("Scope: path `src/db.rs`; bundle mode"),
"bundle mode should surface scope; got: {result}"
);
assert!(
result.contains("Evidence: symbol anchor `src/db.rs:"),
"bundle mode should surface evidence anchor; got: {result}"
);
assert!(
!result.contains("src/other.rs"),
"unrelated same-name file should be excluded: {result}"
);
}
#[tokio::test]
async fn test_get_symbol_context_bundle_exact_selector_requires_line_for_ambiguous_symbol() {
let target = make_file(
"src/db.rs",
b"fn connect() {}\nfn connect() {}\n",
vec![
make_symbol("connect", SymbolKind::Function, 1, 1),
make_symbol("connect", SymbolKind::Function, 2, 2),
],
);
let server = make_server(make_live_index_ready(vec![target]));
let result = server
.get_symbol_context(Parameters(super::GetSymbolContextInput {
project: None,
name: "connect".to_string(),
file: None,
path: Some("src/db.rs".to_string()),
symbol_kind: Some("fn".to_string()),
symbol_line: None,
verbosity: None,
bundle: Some(true),
sections: None,
max_tokens: None,
estimate: None,
}))
.await;
assert!(
result.contains("Ambiguous symbol selector"),
"got: {result}"
);
assert!(result.contains("1"), "got: {result}");
assert!(result.contains("2"), "got: {result}");
}
#[tokio::test]
async fn test_find_references_delegates_to_formatter() {
let server = make_server(make_live_index_ready(vec![]));
let result = server
.find_references(Parameters(super::FindReferencesInput {
name: "nonexistent_xyz".to_string(),
kind: None,
path: None,
symbol_kind: None,
symbol_line: None,
limit: None,
max_per_file: None,
compact: None,
mode: None,
direction: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
// Should get "No references found" not a guard message
assert!(result.contains("No references found"), "got: {result}");
}
#[tokio::test]
async fn test_find_references_exact_selector_excludes_unrelated_same_name_hits() {
let target = make_file(
"src/db.rs",
b"pub fn connect() {}\n",
vec![make_symbol("connect", SymbolKind::Function, 1, 1)],
);
let dependent = make_file_with_refs(
"src/service.rs",
b"use crate::db::connect;\nfn run() { connect(); }\n",
vec![make_symbol("run", SymbolKind::Function, 2, 2)],
vec![
make_ref("db", Some("crate::db"), ReferenceKind::Import, 0, None),
make_ref(
"connect",
Some("crate::db::connect"),
ReferenceKind::Call,
1,
Some(0),
),
],
);
let unrelated = make_file_with_refs(
"src/other.rs",
b"fn run() { connect(); }\n",
vec![make_symbol("run", SymbolKind::Function, 1, 1)],
vec![make_ref("connect", None, ReferenceKind::Call, 0, Some(0))],
);
let server = make_server(make_live_index_ready(vec![target, dependent, unrelated]));
let result = server
.find_references(Parameters(super::FindReferencesInput {
name: "connect".to_string(),
kind: Some("call".to_string()),
path: Some("src/db.rs".to_string()),
symbol_kind: Some("fn".to_string()),
symbol_line: Some(2),
limit: None,
max_per_file: None,
compact: None,
mode: None,
direction: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("src/service.rs"),
"expected dependent hit: {result}"
);
assert!(
!result.contains("src/other.rs"),
"unrelated same-name file should be excluded: {result}"
);
assert!(result.contains("Trust: exact"), "got: {result}");
assert!(
result.contains("Scope: path `src/db.rs`; exact selector line 2; symbol kind `fn`; reference kind `call`"),
"exact selector scope should be explicit: {result}"
);
assert!(
result.contains("Evidence: reference anchors `src/service.rs:2`"),
"reference output should include evidence anchors: {result}"
);
}
#[tokio::test]
async fn test_find_references_exact_selector_requires_line_for_ambiguous_symbol() {
let target = make_file(
"src/db.rs",
b"fn connect() {}\nfn connect() {}\n",
vec![
make_symbol("connect", SymbolKind::Function, 1, 1),
make_symbol("connect", SymbolKind::Function, 10, 10),
],
);
let server = make_server(make_live_index_ready(vec![target]));
let result = server
.find_references(Parameters(super::FindReferencesInput {
name: "connect".to_string(),
kind: Some("call".to_string()),
path: Some("src/db.rs".to_string()),
symbol_kind: Some("fn".to_string()),
symbol_line: None,
limit: None,
max_per_file: None,
compact: None,
mode: None,
direction: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("Ambiguous symbol selector"),
"got: {result}"
);
assert!(result.contains("1"), "got: {result}");
assert!(result.contains("10"), "got: {result}");
}
#[tokio::test]
async fn test_find_dependents_delegates_to_formatter() {
let server = make_server(make_live_index_ready(vec![]));
let result = server
.find_dependents(Parameters(super::FindDependentsInput {
project: None,
path: "src/nonexistent.rs".to_string(),
name: None,
limit: None,
max_per_file: None,
format: None,
compact: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("No file-level dependents found"),
"got: {result}"
);
assert!(result.contains("find_references"), "got: {result}");
}
#[tokio::test]
async fn test_find_dependents_symbol_shaped_query_redirects_to_find_references() {
// L1: passing a `name` alongside `path` is a symbol-level query. The
// handler must redirect to find_references rather than silently return a
// file-level import graph that reads like symbol callers.
let server = make_server(make_live_index_ready(vec![]));
let result = server
.find_dependents(Parameters(super::FindDependentsInput {
project: None,
path: "src/lib.rs".to_string(),
name: Some("my_symbol".to_string()),
limit: None,
max_per_file: None,
format: None,
compact: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("file-level only"),
"redirect must explain find_dependents is file-level, got: {result}"
);
assert!(
result.contains("find_references(name=\"my_symbol\")"),
"redirect must point at find_references for the symbol, got: {result}"
);
// Must NOT have produced a file-dependency graph header.
assert!(
!result.contains("No file-level dependents found"),
"symbol-shaped call must not fall through to the file graph, got: {result}"
);
}
#[tokio::test]
async fn test_find_dependents_blank_name_still_runs_file_graph() {
// A blank/whitespace `name` is not a real symbol query — the file-level
// path must still run normally rather than redirecting.
let server = make_server(make_live_index_ready(vec![]));
let result = server
.find_dependents(Parameters(super::FindDependentsInput {
project: None,
path: "src/nonexistent.rs".to_string(),
name: Some(" ".to_string()),
limit: None,
max_per_file: None,
format: None,
compact: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
!result.contains("file-level only"),
"blank name must not trigger the symbol redirect, got: {result}"
);
assert!(
result.contains("No file-level dependents found"),
"blank name must still run the file-level graph, got: {result}"
);
}
#[tokio::test]
async fn test_find_dependents_mermaid_includes_symbol_names_in_edges() {
// dep_file imports from src/target.rs (stem "target") and uses TargetType.
// find_dependents_for_file should prefer the symbol-level TypeUsage ref,
// so the mermaid edge label should include the symbol name "TargetType".
let target_sym = make_symbol("TargetType", SymbolKind::Struct, 0, 2);
let import_ref = make_ref("target", None, ReferenceKind::Import, 0, None);
let usage_ref = make_ref("TargetType", None, ReferenceKind::TypeUsage, 1, Some(0));
let dep_sym = make_symbol("consumer", SymbolKind::Function, 0, 1);
let target_file = make_file(
"src/target.rs",
b"pub struct TargetType {}\n",
vec![target_sym],
);
let dep_file = make_file_with_refs(
"src/dep.rs",
b"use target::TargetType;\nfn consumer() { TargetType }\n",
vec![dep_sym],
vec![import_ref, usage_ref],
);
let server = make_server(make_live_index_ready(vec![target_file, dep_file]));
let result = server
.find_dependents(Parameters(super::FindDependentsInput {
project: None,
path: "src/target.rs".to_string(),
name: None,
compact: None,
format: Some("mermaid".to_string()),
limit: None,
max_per_file: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("TargetType"),
"mermaid edge should include symbol name: {result}"
);
}
#[tokio::test]
async fn test_find_dependents_excludes_non_pub_name_collision() {
// target.rs defines a non-pub `run` function.
// other.rs imports from target (triggering the symbol_refs path) AND calls
// its own local `run` — same name, different function.
// Without the pub filter, the "run" Call ref would be falsely attributed to
// target.rs's symbol. With the pub filter, symbol_refs is empty and the
// result falls back to the import ref — "run" must not appear as attributed.
let target_sym = make_symbol("run", SymbolKind::Function, 0, 1);
let target_file = make_file(
"src/target.rs",
b"fn run() { internal }\n",
vec![target_sym],
);
let other_sym = make_symbol("main", SymbolKind::Function, 2, 4);
let other_import = make_ref(
"target",
Some("crate::target"),
ReferenceKind::Import,
0,
None,
);
let other_call = make_ref("run", None, ReferenceKind::Call, 3, Some(0));
let other_file = make_file_with_refs(
"src/other.rs",
b"use crate::target;\nfn run() {}\nfn main() {\n run();\n}\n",
vec![other_sym],
vec![other_import, other_call],
);
let server = make_server(make_live_index_ready(vec![target_file, other_file]));
let result = server
.find_dependents(Parameters(super::FindDependentsInput {
project: None,
path: "src/target.rs".to_string(),
name: None,
compact: None,
format: None,
limit: None,
max_per_file: None,
estimate: None,
max_tokens: None,
}))
.await;
// other.rs still appears as a dependent (via the import), but the
// non-pub "run" symbol must NOT be surfaced as an attributed reference.
assert!(
result.contains("src/other.rs"),
"other.rs should appear via the import ref: {result}"
);
assert!(
!result.contains("run"),
"non-pub 'run' collision must not be attributed as a symbol reference: {result}"
);
}
#[tokio::test]
async fn test_find_dependents_includes_pub_symbol_references() {
let target_sym = make_symbol("PublicApi", SymbolKind::Struct, 0, 1);
let target_file = make_file(
"src/target.rs",
b"pub struct PublicApi {}\n",
vec![target_sym],
);
let consumer_sym = make_symbol("use_it", SymbolKind::Function, 1, 3);
let consumer_import = ReferenceRecord {
name: "target".to_string(),
qualified_name: Some("crate::target".to_string()),
kind: ReferenceKind::Import,
byte_range: (0, 20),
line_range: (0, 0),
enclosing_symbol_index: None,
};
let consumer_ref = make_ref("PublicApi", None, ReferenceKind::TypeUsage, 2, Some(0));
let consumer_file = make_file_with_refs(
"src/consumer.rs",
b"use crate::target;\nfn use_it() {\n PublicApi {}\n}\n",
vec![consumer_sym],
vec![consumer_import, consumer_ref],
);
let server = make_server(make_live_index_ready(vec![target_file, consumer_file]));
let result = server
.find_dependents(Parameters(super::FindDependentsInput {
project: None,
path: "src/target.rs".to_string(),
name: None,
compact: None,
format: None,
limit: None,
max_per_file: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("src/consumer.rs"),
"pub symbol with import should be a real dependent: {result}"
);
}
#[tokio::test]
async fn test_search_symbols_rejects_empty_query() {
let sym = make_symbol("Foo", SymbolKind::Class, 1, 3);
let (key, file) = make_file("src/lib.rs", b"struct Foo {}", vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
// Empty/whitespace query with no kind or path_prefix is fully unbounded — must be rejected
for query in ["", " ", "\t"] {
let result = server
.search_symbols(Parameters(super::SearchSymbolsInput {
query: Some(query.to_string()),
kind: None,
path_prefix: None,
language: None,
limit: None,
include_generated: None,
include_tests: None,
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("requires at least one of"),
"empty query '{query}' with no kind/path_prefix should be rejected, got: {result}"
);
}
}
#[tokio::test]
async fn test_inspect_match_out_of_bounds_line() {
let sym = make_symbol("foo", SymbolKind::Function, 0, 0);
let (key, file) = make_file("src/lib.rs", b"fn foo() {}\n", vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.inspect_match(Parameters(super::InspectMatchInput {
path: "src/lib.rs".to_string(),
line: 999999,
context: None,
sibling_limit: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("out of bounds"),
"should report out of bounds, got: {result}"
);
}
#[tokio::test]
async fn test_search_text_shows_enclosing_symbol() {
let sym = make_symbol("handle_request", SymbolKind::Function, 0, 2);
let content = b"fn handle_request() {\n let db = connect();\n}\n";
let (key, file) = make_file("src/handler.rs", content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("connect".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("handle_request"),
"should show enclosing symbol name, got: {result}"
);
assert!(
result.contains("in fn handle_request"),
"should show kind and name, got: {result}"
);
}
#[tokio::test]
async fn test_search_text_uses_innermost_enclosing_symbol_for_nested_items() {
let outer = make_symbol("outer", SymbolKind::Function, 0, 5);
let inner = make_symbol("inner", SymbolKind::Function, 2, 4);
let content = b"fn outer() {\n let target_marker = \"outer\";\n fn inner() {\n let target_marker = \"inner\";\n }\n}\n";
let (key, file) = make_file("src/nested.rs", content, vec![inner, outer]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("target_marker".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("in fn outer (lines 1-6):"),
"outer-item match should still resolve to outer: {result}"
);
assert!(
result.contains(" > 2: let target_marker = \"outer\";"),
"outer-item match line missing: {result}"
);
assert!(
result.contains("in fn inner (lines 3-5):"),
"nested-item match should resolve to innermost symbol: {result}"
);
assert!(
result.contains(" > 4: let target_marker = \"inner\";"),
"inner-item match line missing: {result}"
);
}
#[tokio::test]
async fn test_search_text_group_by_symbol_deduplicates() {
let sym = make_symbol("connect", SymbolKind::Function, 0, 4);
let content = b"fn connect() {\n let url = db_url();\n let pool = Pool::new(url);\n pool.connect()\n}\n";
let (key, file) = make_file("src/db.rs", content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("pool".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: Some("symbol".to_string()),
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
// With group_by: "symbol", should show symbol name and match count
assert!(
result.contains("connect"),
"should show symbol name: {result}"
);
assert!(
result.contains("2 matches") || result.contains("match"),
"should show match count: {result}"
);
}
#[tokio::test]
async fn test_search_text_group_by_names_returns_flat_unique_symbol_names() {
let fetch_user = make_symbol("fetch_user", SymbolKind::Function, 0, 3);
let fetch_team = make_symbol("fetch_team", SymbolKind::Function, 4, 6);
let content = b"fn fetch_user() {\n let needle = 1;\n let needle = 2;\n}\nfn fetch_team() {\n let needle = 3;\n}\n";
let (key, file) = make_file("src/search.rs", content, vec![fetch_user, fetch_team]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("needle".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: Some("names".to_string()),
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
assert!(
result.contains("3 matches in 1 files"),
"header should keep match/file evidence: {result}"
);
assert_eq!(
result.matches("fetch_user").count(),
1,
"fetch_user should be listed once despite two matching lines: {result}"
);
assert_eq!(
result.matches("fetch_team").count(),
1,
"fetch_team should be listed once: {result}"
);
assert!(
!result.contains("let needle"),
"names mode should not echo source lines: {result}"
);
assert!(
!result.contains("in fn"),
"names mode should be a flat name list, not grouped source snippets: {result}"
);
}
#[tokio::test]
async fn test_search_text_group_by_usage_filters_imports() {
let content = b"use crate::db::connect;\nfn handler() { connect() }\n";
let sym = make_symbol("handler", SymbolKind::Function, 1, 1);
let (key, file) = make_file("src/api.rs", content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("connect".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: Some("usage".to_string()),
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
// Should exclude the "use" import line
assert!(
!result.contains("use crate"),
"should filter out imports: {result}"
);
assert!(
result.contains("handler"),
"should keep usage matches: {result}"
);
}
#[tokio::test]
async fn test_search_text_group_by_usage_keeps_doc_comments_visible() {
let content = b"// usage_token in ordinary comment\n/// usage_token in doc comment\nfn handler() {\n let _value = usage_token();\n}\n";
let sym = make_symbol("handler", SymbolKind::Function, 1, 4);
let (key, file) = make_file("src/api.rs", content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("usage_token".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: Some("usage".to_string()),
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
// SFB07 decision: KEEP_DOC_MARKDOWN_USAGE_VISIBLE. Usage grouping filters
// ordinary line-noise comments, but doc comments remain searchable context.
assert!(
!result.contains("// usage_token in ordinary comment"),
"ordinary comments should stay filtered by usage grouping: {result}"
);
assert!(
result.contains("/// usage_token in doc comment"),
"doc comments should remain visible usage context: {result}"
);
assert!(
result.contains("let _value = usage_token();"),
"code usage should remain visible: {result}"
);
assert!(
result.contains("1 import/comment match(es) excluded by usage filter"),
"filtered ordinary comment count should be explicit: {result}"
);
}
#[tokio::test]
async fn test_search_text_group_by_usage_keeps_markdown_body_visible() {
let content = b"# usage_token heading\n\nusage_token appears in Markdown body\n";
let (key, mut file) = make_file("README.md", content, vec![]);
file.language = LanguageId::Markdown;
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("usage_token".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: Some("usage".to_string()),
follow_refs: None,
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
// SFB07 decision: KEEP_DOC_MARKDOWN_USAGE_VISIBLE. Markdown body text remains
// visible; heading lines keep the existing hash-comment noise filtering.
assert!(
result.contains("README.md"),
"markdown file should be searched: {result}"
);
assert!(
result.contains("usage_token appears in Markdown body"),
"markdown body text should remain usage-visible: {result}"
);
assert!(
!result.contains("# usage_token heading"),
"hash-heading lines keep existing comment-like usage filtering: {result}"
);
assert!(
result.contains("1 import/comment match(es) excluded by usage filter"),
"filtered markdown heading count should be explicit: {result}"
);
}
#[tokio::test]
async fn test_inspect_match_line_zero_is_out_of_bounds() {
let sym = make_symbol("foo", SymbolKind::Function, 0, 0);
let (key, file) = make_file("src/lib.rs", b"fn foo() {}\n", vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let result = server
.inspect_match(Parameters(super::InspectMatchInput {
path: "src/lib.rs".to_string(),
line: 0,
context: None,
sibling_limit: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("out of bounds"),
"line 0 should be out of bounds (1-based), got: {result}"
);
}
#[tokio::test]
async fn test_search_text_follow_refs_includes_callers() {
// Build an index with cross-references
let sym_a = make_symbol("connect", SymbolKind::Function, 0, 1);
let file_a_content = b"fn connect() {\n db_open()\n}\n";
let (key_a, file_a) = make_file("src/db.rs", file_a_content, vec![sym_a]);
let sym_b = make_symbol("handler", SymbolKind::Function, 0, 1);
let file_b_content = b"fn handler() {\n connect()\n}\n";
let (key_b, file_b) = make_file_with_refs(
"src/api.rs",
file_b_content,
vec![sym_b],
vec![make_ref("connect", None, ReferenceKind::Call, 1, Some(0))],
);
let server = make_server(make_live_index_ready(vec![
(key_a, file_a),
(key_b, file_b),
]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("db_open".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: Some(true),
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
// Should show that connect() is called by handler() in src/api.rs
assert!(
result.contains("handler") || result.contains("api.rs"),
"should show callers of enclosing symbol, got: {result}"
);
assert!(
result.contains("Called by"),
"should have Called by section, got: {result}"
);
}
#[tokio::test]
async fn test_search_text_follow_refs_empty_callers_signal() {
// A file with a function that has no callers anywhere
let sym_a = make_symbol("orphan_fn", SymbolKind::Function, 0, 2);
let file_a_content = b"fn orphan_fn() {\n do_work()\n}\n";
let (key_a, file_a) = make_file("src/orphan.rs", file_a_content, vec![sym_a]);
let server = make_server(make_live_index_ready(vec![(key_a, file_a)]));
let result = server
.search_text(Parameters(super::SearchTextInput {
query: Some("do_work".to_string()),
terms: None,
regex: None,
path_prefix: None,
language: None,
limit: None,
max_per_file: None,
include_generated: None,
include_tests: None,
glob: None,
exclude_glob: None,
context: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: Some(true),
follow_refs_limit: None,
ranked: None,
estimate: None,
max_tokens: None,
structural: None,
include_vendor: None,
include_personal_tooling: None,
project: None,
projects: None,
}))
.await;
// follow_refs ran but found no cross-references — should signal this explicitly
assert!(
result.contains("no cross-references found"),
"should show empty-callers signal when follow_refs found nothing, got: {result}"
);
assert!(
!result.contains("Called by"),
"should not show 'Called by' when callers list is empty, got: {result}"
);
}
// ── Lenient deserialization tests ────────────────────────────────────
#[test]
fn test_lenient_u32_accepts_string() {
let json = r#"{"query":"test","limit":"10"}"#;
let input: super::SearchFilesInput = serde_json::from_str(json).unwrap();
assert_eq!(input.limit, Some(10));
}
#[test]
fn test_lenient_u32_accepts_number() {
let json = r#"{"query":"test","limit":10}"#;
let input: super::SearchFilesInput = serde_json::from_str(json).unwrap();
assert_eq!(input.limit, Some(10));
}
#[test]
fn test_lenient_u32_accepts_null() {
let json = r#"{"query":"test","limit":null}"#;
let input: super::SearchFilesInput = serde_json::from_str(json).unwrap();
assert_eq!(input.limit, None);
}
#[test]
fn test_lenient_u32_accepts_absent() {
let json = r#"{"query":"test"}"#;
let input: super::SearchFilesInput = serde_json::from_str(json).unwrap();
assert_eq!(input.limit, None);
}
#[test]
fn test_lenient_bool_accepts_string_true() {
let json = r#"{"uncommitted":"true"}"#;
let input: super::WhatChangedInput = serde_json::from_str(json).unwrap();
assert_eq!(input.uncommitted, Some(true));
}
#[test]
fn test_lenient_bool_accepts_string_false() {
let json = r#"{"uncommitted":"false"}"#;
let input: super::WhatChangedInput = serde_json::from_str(json).unwrap();
assert_eq!(input.uncommitted, Some(false));
}
#[test]
fn test_lenient_bool_accepts_native_bool() {
let json = r#"{"uncommitted":true}"#;
let input: super::WhatChangedInput = serde_json::from_str(json).unwrap();
assert_eq!(input.uncommitted, Some(true));
}
#[test]
fn test_lenient_u32_required_accepts_string() {
let json = r#"{"path":"src/lib.rs","line":"42"}"#;
let input: super::InspectMatchInput = serde_json::from_str(json).unwrap();
assert_eq!(input.line, 42);
}
#[test]
fn test_lenient_u32_required_accepts_number() {
let json = r#"{"path":"src/lib.rs","line":42}"#;
let input: super::InspectMatchInput = serde_json::from_str(json).unwrap();
assert_eq!(input.line, 42);
}
#[test]
fn test_lenient_depth_accepts_string() {
let json = r#"{"detail":"tree","depth":"1"}"#;
let input: super::GetRepoMapInput = serde_json::from_str(json).unwrap();
assert_eq!(input.depth, Some(1));
}
#[tokio::test]
async fn test_analyze_file_impact_co_changes_returns_loading_message_when_no_git_data() {
// With an empty index (no git temporal data computed), the tool with include_co_changes
// should return the "still loading" or "unavailable" message in the co-changes section.
let server = make_server(make_live_index_empty());
let result = server
.analyze_file_impact(Parameters(super::AnalyzeFileImpactInput {
project: None,
path: "src/lib.rs".to_string(),
new_file: None,
include_co_changes: Some(true),
co_changes_limit: None,
estimate: None,
}))
.await;
// Git temporal starts as Pending in tests (no tokio runtime spawns it) — but the main
// impact analysis uses the loading guard and returns early, so the co-changes append
// won't be reached. The loading guard message is returned instead.
assert!(
result.contains("still loading")
|| result.contains("unavailable")
|| result == crate::protocol::format::empty_guard_message(),
"expected loading/unavailable/guard message, got: {result}"
);
}
// ─── Edit tool integration tests ─────────────────────────────────────────
/// Helper: write a file to disk and build a server with it indexed.
fn setup_edit_test(original: &[u8]) -> (TempDir, SymForgeServer, PathBuf) {
setup_edit_test_inner(original, false)
}
/// Keep the synthetic index mtime aligned with disk when a test needs to
/// exercise byte splicing without triggering a fresh admission decision.
fn setup_edit_test_with_fresh_mtime(original: &[u8]) -> (TempDir, SymForgeServer, PathBuf) {
setup_edit_test_inner(original, true)
}
fn setup_edit_test_inner(
original: &[u8],
record_disk_mtime: bool,
) -> (TempDir, SymForgeServer, PathBuf) {
let dir = tempfile::tempdir().unwrap();
std::fs::create_dir(dir.path().join(".git")).unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let file_path = src_dir.join("lib.rs");
std::fs::write(&file_path, original).unwrap();
let result = crate::parsing::process_file("src/lib.rs", original, LanguageId::Rust);
let mut indexed = IndexedFile::from_parse_result(result, original.to_vec());
if record_disk_mtime {
indexed.mtime_secs = std::fs::metadata(&file_path)
.and_then(|metadata| metadata.modified())
.ok()
.and_then(|modified| modified.duration_since(std::time::UNIX_EPOCH).ok())
.map(|duration| duration.as_secs())
.unwrap_or(0);
}
let index = make_live_index_ready(vec![("src/lib.rs".to_string(), indexed)]);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
(dir, server, file_path)
}
fn replace_symbol_body_input_from_json(
value: serde_json::Value,
) -> crate::protocol::edit::ReplaceSymbolBodyInput {
serde_json::from_value(value).expect("valid replace_symbol_body input")
}
fn delete_symbol_input_from_json(
value: serde_json::Value,
) -> crate::protocol::edit::DeleteSymbolInput {
serde_json::from_value(value).expect("valid delete_symbol input")
}
fn edit_within_symbol_input_from_json(
value: serde_json::Value,
) -> crate::protocol::edit::EditWithinSymbolInput {
serde_json::from_value(value).expect("valid edit_within_symbol input")
}
fn batch_edit_input_from_json(
value: serde_json::Value,
) -> crate::protocol::edit::BatchEditInput {
serde_json::from_value(value).expect("valid batch_edit input")
}
fn batch_replace_request_json(idempotency_key: &str, new_body: &str) -> serde_json::Value {
let edits = serde_json::to_value(vec![crate::protocol::edit::SingleEdit {
path: "src/lib.rs".to_string(),
name: "alpha".to_string(),
kind: None,
symbol_line: None,
operation: crate::protocol::edit::EditOperation::Replace {
new_body: new_body.to_string(),
},
working_directory: None,
}])
.expect("single edit should serialize");
serde_json::json!({
"edits": edits,
"dry_run": false,
"idempotency_key": idempotency_key,
})
}
fn setup_loaded_edit_test(files: &[(&str, &str)]) -> (TempDir, SymForgeServer) {
let dir = tempfile::tempdir().unwrap();
for (relative_path, content) in files {
let path = dir.path().join(relative_path);
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent).unwrap();
}
std::fs::write(path, content).unwrap();
}
let index = LiveIndex::load(dir.path()).unwrap();
let watcher_info = Arc::new(parking_lot::Mutex::new(
crate::watcher::WatcherInfo::default(),
));
let server = SymForgeServer::new(
index,
"loaded_edit_test".to_string(),
watcher_info,
Some(dir.path().to_path_buf()),
None,
);
(dir, server)
}
#[test]
fn prepare_exact_path_for_edit_returns_err_on_confirmed_absent() {
let (dir, server) = setup_loaded_edit_test(&[]);
let relative_path = "src/missing.rs";
let expected_path = super::safe_repo_path_for_freshen(dir.path(), relative_path).unwrap();
let result = super::prepare_exact_path_for_edit(&server, relative_path);
assert_eq!(
result.unwrap_err(),
format!(
"{}",
super::EditError::PathNotFound {
path: expected_path
}
)
);
}
#[test]
fn freshen_exact_path_for_targeted_retrieval_removes_on_confirmed_absent_with_fence() {
let (dir, server) = setup_loaded_edit_test(&[("src/lib.rs", "pub fn gone() {}\n")]);
std::fs::remove_file(dir.path().join("src/lib.rs")).unwrap();
let refreshed = super::freshen_exact_path_for_targeted_retrieval(
&server,
&super::search::PathScope::exact("src/lib.rs"),
);
assert!(refreshed);
assert!(server.index().read().get_file("src/lib.rs").is_none());
}
#[test]
fn prepare_batch_paths_for_edit_partial_succeeds_with_skipped_paths() {
let (_dir, server) = setup_loaded_edit_test(&[("src/lib.rs", "pub fn keep() {}\n")]);
let paths = vec!["src/lib.rs".to_string(), "src/missing.rs".to_string()];
let (repo_root, source_authority) =
super::prepare_batch_paths_for_edit(&server, &paths).expect("batch freshen");
assert_eq!(
repo_root,
server
.capture_repo_root()
.expect("loaded edit server should retain its canonical root")
);
assert_eq!(
source_authority,
crate::protocol::edit_format::EditSourceAuthority::CurrentIndex
);
assert!(server.index().read().get_file("src/lib.rs").is_some());
}
#[test]
fn freshen_helper_returns_generation_mismatch_when_gen_stale() {
let project_a = tempfile::tempdir().unwrap();
let project_b = tempfile::tempdir().unwrap();
std::fs::create_dir_all(project_a.path().join("src")).unwrap();
std::fs::create_dir_all(project_b.path().join("src")).unwrap();
std::fs::write(project_a.path().join("src/a.rs"), "pub fn a() {}\n").unwrap();
std::fs::write(project_b.path().join("src/b.rs"), "pub fn b() {}\n").unwrap();
let index = LiveIndex::load(project_a.path()).unwrap();
let stale_gen = index.current_project_generation();
index.reload(project_b.path()).unwrap();
let result = crate::watcher::freshen_file_if_stale(
"src/b.rs",
&project_a.path().join("src/b.rs"),
&index,
stale_gen,
);
assert!(matches!(
result,
crate::watcher::FreshenResult::GenerationMismatch
));
assert!(index.read().get_file("src/b.rs").is_some());
}
#[tokio::test]
async fn test_replace_symbol_body_replaces_and_reindexes() {
let original = b"fn hello() {\n println!(\"hello\");\n}\n\nfn world() {\n println!(\"world\");\n}\n";
let (dir, server, file_path) = setup_edit_test(original);
let input = crate::protocol::edit::ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "hello".to_string(),
kind: None,
symbol_line: None,
new_body: "fn hello() {\n println!(\"HELLO\");\n}".to_string(),
dry_run: None,
idempotency_key: None,
if_match: None,
working_directory: None,
};
let result = server.replace_symbol_body(Parameters(input)).await;
assert!(result.contains("replaced"), "result was: {result}");
assert!(result.contains("hello"), "result was: {result}");
assert!(result.contains("Edit safety: structural-edit-safe"));
assert!(result.contains("Path authority: repository-bound"));
assert!(result.contains("Source authority: disk-refreshed"));
assert!(result.contains("Write semantics: atomic write + reindex"));
assert!(result.contains("Evidence: symbol anchor `src/lib.rs:1`"));
assert!(result.contains("Tee snapshot:"), "result was: {result}");
assert!(result.contains(".symforge/tee/"), "result was: {result}");
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(on_disk.contains("HELLO"), "disk: {on_disk}");
assert!(on_disk.contains("world"), "other symbol intact: {on_disk}");
let tee_dir = dir.path().join(".symforge").join("tee");
let snapshots = std::fs::read_dir(&tee_dir)
.unwrap()
.collect::<Result<Vec<_>, _>>()
.unwrap();
assert_eq!(
snapshots.len(),
1,
"expected one tee snapshot in {tee_dir:?}"
);
assert_eq!(std::fs::read(snapshots[0].path()).unwrap(), original);
let guard = server.index.read();
let file = guard.get_file("src/lib.rs").unwrap();
assert!(file.symbols.iter().any(|s| s.name == "hello"));
assert!(file.symbols.iter().any(|s| s.name == "world"));
}
/// When `new_body` does NOT supply its own doc comment, the existing
/// attached `/// ...` doc must be preserved. Previously the splice
/// range extended past the doc unconditionally, silently deleting it.
#[tokio::test]
async fn test_replace_symbol_body_preserves_attached_doc_without_new_doc() {
let original =
b"/// Adds two numbers.\npub fn add(a: i32, b: i32) -> i32 {\n a + b\n}\n";
let (_dir, server, file_path) = setup_edit_test(original);
let input = crate::protocol::edit::ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "add".to_string(),
kind: None,
symbol_line: None,
new_body: "pub fn add(a: i32, b: i32) -> i32 {\n a.saturating_add(b)\n}".to_string(),
dry_run: None,
idempotency_key: None,
if_match: None,
working_directory: None,
};
let result = server.replace_symbol_body(Parameters(input)).await;
assert!(result.contains("replaced"), "result was: {result}");
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
on_disk.contains("/// Adds two numbers."),
"existing doc must be preserved; disk was:\n{on_disk}"
);
assert!(
on_disk.contains("saturating_add"),
"new body must be written; disk was:\n{on_disk}"
);
// No duplicated doc line.
assert_eq!(
on_disk.matches("/// Adds two numbers.").count(),
1,
"doc must appear exactly once; disk was:\n{on_disk}"
);
}
/// When `new_body` DOES supply its own doc comment, the existing doc
/// must be replaced — not kept alongside, which would duplicate it.
#[tokio::test]
async fn test_replace_symbol_body_replaces_attached_doc_when_new_body_supplies_one() {
let original = b"/// Old doc.\npub fn add(a: i32, b: i32) -> i32 {\n a + b\n}\n";
let (_dir, server, file_path) = setup_edit_test(original);
let input = crate::protocol::edit::ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "add".to_string(),
kind: None,
symbol_line: None,
new_body:
"/// New doc.\npub fn add(a: i32, b: i32) -> i32 {\n a.saturating_add(b)\n}"
.to_string(),
dry_run: None,
idempotency_key: None,
if_match: None,
working_directory: None,
};
let result = server.replace_symbol_body(Parameters(input)).await;
assert!(result.contains("replaced"), "result was: {result}");
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
on_disk.contains("/// New doc."),
"new doc must be written; disk was:\n{on_disk}"
);
assert!(
!on_disk.contains("/// Old doc."),
"old doc must be replaced when new one is supplied; disk was:\n{on_disk}"
);
// Exactly one doc line (no duplication).
assert_eq!(
on_disk.matches("/// ").count(),
1,
"exactly one doc line expected; disk was:\n{on_disk}"
);
}
/// Attributes like `#[inline]` attached to the symbol must be preserved
/// when `new_body` has neither a doc nor the attribute. This is the
/// `#[test]`-duplication bug we hit while building Unit 5's tests.
#[tokio::test]
async fn test_replace_symbol_body_preserves_attribute_without_duplicating_it() {
let original = b"#[inline]\npub fn add(a: i32, b: i32) -> i32 {\n a + b\n}\n";
let (_dir, server, file_path) = setup_edit_test(original);
let input = crate::protocol::edit::ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "add".to_string(),
kind: None,
symbol_line: None,
new_body: "pub fn add(a: i32, b: i32) -> i32 {\n a.saturating_add(b)\n}".to_string(),
dry_run: None,
idempotency_key: None,
if_match: None,
working_directory: None,
};
let result = server.replace_symbol_body(Parameters(input)).await;
assert!(result.contains("replaced"), "result was: {result}");
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert_eq!(
on_disk.matches("#[inline]").count(),
1,
"attribute must appear exactly once; disk was:\n{on_disk}"
);
assert!(
on_disk.contains("saturating_add"),
"new body must be written; disk was:\n{on_disk}"
);
}
/// Orphaned doc comments (separated from the symbol by a blank line)
/// must NOT be swallowed when new_body has no doc of its own. This is
/// the narrowest behavioral delta between the old and new splice math,
/// and the case the plan's Risks table explicitly flagged for fixture
/// coverage.
#[tokio::test]
async fn test_replace_symbol_body_preserves_orphan_doc_without_new_doc() {
let original =
b"/// Intro remark about the next item.\n\npub fn add(a: i32, b: i32) -> i32 {\n a + b\n}\n";
let (_dir, server, file_path) = setup_edit_test(original);
let input = crate::protocol::edit::ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "add".to_string(),
kind: None,
symbol_line: None,
new_body: "pub fn add(a: i32, b: i32) -> i32 {\n a.saturating_add(b)\n}".to_string(),
dry_run: None,
idempotency_key: None,
if_match: None,
working_directory: None,
};
let result = server.replace_symbol_body(Parameters(input)).await;
assert!(result.contains("replaced"), "result was: {result}");
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
on_disk.contains("/// Intro remark about the next item."),
"orphaned doc must survive a body-only replace; disk was:\n{on_disk}"
);
assert!(
on_disk.contains("saturating_add"),
"new body must be written; disk was:\n{on_disk}"
);
assert_eq!(
on_disk
.matches("/// Intro remark about the next item.")
.count(),
1,
"orphan doc must not duplicate; disk was:\n{on_disk}"
);
}
/// TypeScript/JSDoc variant: `/** ... */` doc block on a separate line
/// must be preserved when new_body has no doc. Plan Risks table named
/// this specifically — multi-language coverage proves the helper works
/// off of the language-agnostic doc-marker list in edit.rs.
#[tokio::test]
async fn test_replace_symbol_body_preserves_jsdoc_without_new_doc() {
let original = b"/** Adds two numbers. */\nexport function add(a: number, b: number): number {\n return a + b;\n}\n";
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let file_path = src_dir.join("math.ts");
std::fs::write(&file_path, original).unwrap();
let parse_result =
crate::parsing::process_file("src/math.ts", original, LanguageId::TypeScript);
let indexed = IndexedFile::from_parse_result(parse_result, original.to_vec());
let index = make_live_index_ready(vec![("src/math.ts".to_string(), indexed)]);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let input = crate::protocol::edit::ReplaceSymbolBodyInput {
project: None,
path: "src/math.ts".to_string(),
name: "add".to_string(),
kind: None,
symbol_line: None,
new_body: "export function add(a: number, b: number): number {\n return a + b;\n}"
.to_string(),
dry_run: None,
idempotency_key: None,
if_match: None,
working_directory: None,
};
let result = server.replace_symbol_body(Parameters(input)).await;
assert!(result.contains("replaced"), "result was: {result}");
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
on_disk.contains("/** Adds two numbers. */"),
"JSDoc block must survive a body-only replace; disk was:\n{on_disk}"
);
assert_eq!(
on_disk.matches("/** Adds two numbers. */").count(),
1,
"JSDoc must not duplicate; disk was:\n{on_disk}"
);
}
#[tokio::test]
async fn test_replace_symbol_body_preserves_same_line_jsdoc_without_new_doc() {
let original = b"/** @deprecated */ export function legacy(): number {\n return 1;\n}\n";
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let file_path = src_dir.join("legacy.ts");
std::fs::write(&file_path, original).unwrap();
let parse_result =
crate::parsing::process_file("src/legacy.ts", original, LanguageId::TypeScript);
let indexed = IndexedFile::from_parse_result(parse_result, original.to_vec());
let index = make_live_index_ready(vec![("src/legacy.ts".to_string(), indexed)]);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let input = crate::protocol::edit::ReplaceSymbolBodyInput {
project: None,
path: "src/legacy.ts".to_string(),
name: "legacy".to_string(),
kind: None,
symbol_line: None,
new_body: "export function legacy(): number {\n return 2;\n}".to_string(),
dry_run: None,
idempotency_key: None,
if_match: None,
working_directory: None,
};
let result = server.replace_symbol_body(Parameters(input)).await;
assert!(result.contains("replaced"), "result was: {result}");
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
on_disk.starts_with("/** @deprecated */ export function legacy"),
"same-line JSDoc prefix must survive a body-only replace; disk was:\n{on_disk}"
);
assert_eq!(
on_disk.matches("/** @deprecated */").count(),
1,
"same-line JSDoc must not duplicate; disk was:\n{on_disk}"
);
assert!(
on_disk.contains("return 2;"),
"new body must be written; disk was:\n{on_disk}"
);
}
#[tokio::test]
async fn test_replace_symbol_body_preserves_same_line_rust_block_doc_without_new_doc() {
let original = b"/** @deprecated */ pub fn legacy() -> i32 {\n 1\n}\n";
let (_dir, server, file_path) = setup_edit_test(original);
let input = crate::protocol::edit::ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "legacy".to_string(),
kind: None,
symbol_line: None,
new_body: "pub fn legacy() -> i32 {\n 2\n}".to_string(),
dry_run: None,
idempotency_key: None,
if_match: None,
working_directory: None,
};
let result = server.replace_symbol_body(Parameters(input)).await;
assert!(result.contains("replaced"), "result was: {result}");
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
on_disk.starts_with("/** @deprecated */ pub fn legacy"),
"same-line Rust block doc must survive a body-only replace; disk was:\n{on_disk}"
);
assert_eq!(
on_disk.matches("/** @deprecated */").count(),
1,
"same-line Rust block doc must not duplicate; disk was:\n{on_disk}"
);
assert!(
on_disk.contains(" 2"),
"new body must be written; disk was:\n{on_disk}"
);
}
#[tokio::test]
async fn test_replace_symbol_body_preserves_indentation() {
// Simulates a method inside a class — symbol is indented 4 spaces.
let original = b"mod outer {\n fn inner() {\n old_body();\n }\n}\n";
let (_dir, server, file_path) = setup_edit_test(original);
// Provide unindented replacement — tool should auto-indent to match.
let input = crate::protocol::edit::ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "inner".to_string(),
kind: None,
symbol_line: None,
new_body: "fn inner() {\n new_body();\n}".to_string(),
dry_run: None,
idempotency_key: None,
if_match: None,
working_directory: None,
};
let result = server.replace_symbol_body(Parameters(input)).await;
assert!(result.contains("replaced"), "result: {result}");
let on_disk = std::fs::read_to_string(&file_path).unwrap();
// Every line of the replacement should be indented 4 spaces.
assert!(
on_disk.contains(" fn inner() {\n new_body();\n }"),
"indentation preserved: {on_disk}"
);
}
#[tokio::test]
async fn test_replace_symbol_body_not_found() {
let original = b"fn hello() {}\n";
let (_dir, server, _) = setup_edit_test(original);
let input = crate::protocol::edit::ReplaceSymbolBodyInput {
project: None,
path: "nonexistent.rs".to_string(),
name: "foo".to_string(),
kind: None,
symbol_line: None,
new_body: "fn foo() {}".to_string(),
dry_run: None,
idempotency_key: None,
if_match: None,
working_directory: None,
};
let result = server.replace_symbol_body(Parameters(input)).await;
assert!(
result.contains("not found") || result.contains("Not found"),
"result: {result}"
);
}
#[tokio::test]
async fn test_insert_symbol_after_works() {
let original = b"fn hello() {\n println!(\"hello\");\n}\n";
let (_dir, server, file_path) = setup_edit_test(original);
let input = crate::protocol::edit::InsertSymbolInput {
project: None,
path: "src/lib.rs".to_string(),
name: "hello".to_string(),
kind: None,
symbol_line: None,
content: "fn world() {\n println!(\"world\");\n}".to_string(),
position: None, // defaults to "after"
dry_run: None,
idempotency_key: None,
working_directory: None,
};
let result = server.insert_symbol(Parameters(input)).await;
assert!(result.contains("inserted"), "result: {result}");
assert!(result.contains("after"), "result: {result}");
assert!(result.contains("Edit safety: structural-edit-safe"));
assert!(result.contains("Write semantics: atomic write + reindex"));
assert!(result.contains("Evidence: symbol anchor `src/lib.rs:1`"));
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(on_disk.contains("hello"), "original intact: {on_disk}");
assert!(on_disk.contains("world"), "new symbol: {on_disk}");
let guard = server.index.read();
let file = guard.get_file("src/lib.rs").unwrap();
assert!(file.symbols.iter().any(|s| s.name == "world"));
}
#[tokio::test]
async fn test_insert_symbol_before_works() {
let original = b"fn world() {\n println!(\"world\");\n}\n";
let (_dir, server, file_path) = setup_edit_test(original);
let input = crate::protocol::edit::InsertSymbolInput {
project: None,
path: "src/lib.rs".to_string(),
name: "world".to_string(),
kind: None,
symbol_line: None,
content: "fn hello() {\n println!(\"hello\");\n}".to_string(),
position: Some("before".to_string()),
dry_run: None,
idempotency_key: None,
working_directory: None,
};
let result = server.insert_symbol(Parameters(input)).await;
assert!(result.contains("inserted"), "result: {result}");
assert!(result.contains("before"), "result: {result}");
let on_disk = std::fs::read_to_string(&file_path).unwrap();
let hello_pos = on_disk.find("hello").unwrap();
let world_pos = on_disk.find("world").unwrap();
assert!(hello_pos < world_pos, "hello before world: {on_disk}");
}
#[tokio::test]
async fn test_delete_symbol_removes_and_reindexes() {
let original = b"fn hello() {\n println!(\"hello\");\n}\n\nfn world() {\n println!(\"world\");\n}\n";
let (_dir, server, file_path) = setup_edit_test(original);
let input = crate::protocol::edit::DeleteSymbolInput {
project: None,
path: "src/lib.rs".to_string(),
name: "hello".to_string(),
kind: None,
symbol_line: None,
dry_run: None,
idempotency_key: None,
working_directory: None,
};
let result = server.delete_symbol(Parameters(input)).await;
assert!(result.contains("deleted"), "result: {result}");
assert!(result.contains("Edit safety: structural-edit-safe"));
assert!(result.contains("Write semantics: atomic write + reindex"));
assert!(result.contains("Evidence: symbol anchor `src/lib.rs:1`"));
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(!on_disk.contains("hello"), "hello removed: {on_disk}");
assert!(on_disk.contains("world"), "world intact: {on_disk}");
let guard = server.index.read();
let file = guard.get_file("src/lib.rs").unwrap();
assert!(!file.symbols.iter().any(|s| s.name == "hello"));
assert!(file.symbols.iter().any(|s| s.name == "world"));
}
#[test]
fn test_check_edit_capability_blocks_structural_for_frontend() {
// replace_symbol_body requires StructuralEditSafe; Html is TextEditSafe → blocked
let warning = SymForgeServer::check_edit_capability(
&crate::domain::LanguageId::Html,
crate::parsing::config_extractors::EditCapability::StructuralEditSafe,
"replace_symbol_body",
);
assert!(
warning.is_some(),
"replace_symbol_body should be blocked for HTML"
);
assert!(warning.as_ref().unwrap().contains("edit safety blocked"));
assert!(
warning
.as_ref()
.unwrap()
.contains("Required safety: structural-edit-safe")
);
assert!(
warning
.as_ref()
.unwrap()
.contains("Available safety: text-edit-safe")
);
}
#[test]
fn test_check_edit_capability_allows_text_edit_for_frontend() {
// edit_within_symbol requires TextEditSafe; Css is TextEditSafe → allowed
let warning = SymForgeServer::check_edit_capability(
&crate::domain::LanguageId::Css,
crate::parsing::config_extractors::EditCapability::TextEditSafe,
"edit_within_symbol",
);
assert!(
warning.is_none(),
"edit_within_symbol should be allowed for CSS"
);
}
#[tokio::test]
async fn test_edit_within_symbol_replaces_text() {
let original = b"fn hello() {\n println!(\"hello\");\n}\n";
let (_dir, server, file_path) = setup_edit_test(original);
let input = crate::protocol::edit::EditWithinSymbolInput {
project: None,
path: "src/lib.rs".to_string(),
name: "hello".to_string(),
kind: None,
symbol_line: None,
old_text: "\"hello\"".to_string(),
new_text: "\"HELLO\"".to_string(),
replace_all: false,
occurrence: None,
near_line: None,
dry_run: None,
idempotency_key: None,
working_directory: None,
};
let result = server.edit_within_symbol(Parameters(input)).await;
assert!(result.contains("edited within"), "result: {result}");
assert!(result.contains("1 replacement"), "result: {result}");
assert!(result.contains("Edit safety: text-edit-safe"));
assert!(result.contains("Write semantics: atomic write + reindex"));
assert!(result.contains("Evidence: symbol anchor `src/lib.rs:1`"));
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(on_disk.contains("HELLO"), "edited: {on_disk}");
assert!(!on_disk.contains("\"hello\""), "old text gone: {on_disk}");
}
fn multi_match_edit_input(
old_text: &str,
new_text: &str,
) -> crate::protocol::edit::EditWithinSymbolInput {
crate::protocol::edit::EditWithinSymbolInput {
project: None,
path: "src/lib.rs".to_string(),
name: "hello".to_string(),
kind: None,
symbol_line: None,
old_text: old_text.to_string(),
new_text: new_text.to_string(),
replace_all: false,
occurrence: None,
near_line: None,
dry_run: None,
idempotency_key: None,
working_directory: None,
}
}
// Dogfood #4 (2026-07-06): identical lines across arms of one fn were
// unaddressable — edit_within_symbol silently rewrote the first match.
const MULTI_MATCH_BODY: &[u8] =
b"fn hello() {\n let a = 1;\n let a = 1;\n let a = 1;\n}\n";
#[tokio::test]
async fn test_edit_within_symbol_occurrence_targets_nth_match() {
let (_dir, server, file_path) = setup_edit_test(MULTI_MATCH_BODY);
let mut input = multi_match_edit_input("let a = 1;", "let a = 2;");
input.occurrence = Some(2);
let result = server.edit_within_symbol(Parameters(input)).await;
assert!(result.contains("edited within"), "result: {result}");
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
on_disk.contains("let a = 1;\n let a = 2;\n let a = 1;"),
"only the second occurrence changes: {on_disk}"
);
}
#[tokio::test]
async fn test_edit_within_symbol_near_line_picks_closest_match() {
let (_dir, server, file_path) = setup_edit_test(MULTI_MATCH_BODY);
let mut input = multi_match_edit_input("let a = 1;", "let a = 2;");
// Occurrences sit on file lines 2, 3, 4 — line 4 selects the third.
input.near_line = Some(4);
let result = server.edit_within_symbol(Parameters(input)).await;
assert!(result.contains("edited within"), "result: {result}");
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
on_disk.contains("let a = 1;\n let a = 1;\n let a = 2;"),
"only the occurrence nearest line 4 changes: {on_disk}"
);
}
#[tokio::test]
async fn test_edit_within_symbol_occurrence_out_of_range_errors() {
let (_dir, server, file_path) = setup_edit_test(MULTI_MATCH_BODY);
let mut input = multi_match_edit_input("let a = 1;", "let a = 2;");
input.occurrence = Some(5);
let result = server.edit_within_symbol(Parameters(input)).await;
assert!(
result.contains("out of range") && result.contains("3 exact occurrence(s)"),
"out-of-range occurrence must error with the real count: {result}"
);
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
!on_disk.contains("let a = 2;"),
"no write on error: {on_disk}"
);
}
#[tokio::test]
async fn test_edit_within_symbol_untargeted_multi_match_discloses() {
let (_dir, server, file_path) = setup_edit_test(MULTI_MATCH_BODY);
let input = multi_match_edit_input("let a = 1;", "let a = 2;");
let result = server.edit_within_symbol(Parameters(input)).await;
assert!(
result.contains("occurred 3 times") && result.contains("edited the FIRST"),
"an untargeted multi-match edit must disclose the ambiguity: {result}"
);
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
on_disk.contains("let a = 2;\n let a = 1;\n let a = 1;"),
"untargeted edit still rewrites the first occurrence: {on_disk}"
);
}
#[tokio::test]
async fn test_edit_within_symbol_targeting_modes_are_mutually_exclusive() {
let (_dir, server, _file_path) = setup_edit_test(MULTI_MATCH_BODY);
let mut input = multi_match_edit_input("let a = 1;", "let a = 2;");
input.replace_all = true;
input.occurrence = Some(1);
let result = server.edit_within_symbol(Parameters(input)).await;
assert!(
result.contains("mutually exclusive"),
"conflicting targeting modes must error: {result}"
);
}
#[tokio::test]
async fn test_replace_symbol_body_reports_disk_refreshed_authority_for_stale_file() {
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let stale_indexed = b"fn hello() {\n println!(\"stale\");\n}\n";
let fresh_on_disk = b"fn hello() {\n println!(\"fresh\");\n}\n";
let file_path = src_dir.join("lib.rs");
std::fs::write(&file_path, fresh_on_disk).unwrap();
let result = crate::parsing::process_file("src/lib.rs", stale_indexed, LanguageId::Rust);
let indexed = IndexedFile::from_parse_result(result, stale_indexed.to_vec());
let server = make_server_with_root(
make_live_index_ready(vec![("src/lib.rs".to_string(), indexed)]),
Some(dir.path().to_path_buf()),
);
let input = crate::protocol::edit::ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "hello".to_string(),
kind: None,
symbol_line: None,
new_body: "fn hello() {\n println!(\"new body\");\n}".to_string(),
dry_run: Some(true),
idempotency_key: None,
if_match: None,
working_directory: None,
};
let result = server.replace_symbol_body(Parameters(input)).await;
assert!(result.contains("Source authority: disk-refreshed"));
assert!(result.contains("Write semantics: dry run (no writes)"));
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
on_disk.contains("fresh"),
"dry run should leave disk untouched: {on_disk}"
);
}
#[tokio::test]
async fn test_edit_within_symbol_not_found_text() {
let original = b"fn hello() {\n println!(\"hello\");\n}\n";
let (_dir, server, _) = setup_edit_test(original);
let input = crate::protocol::edit::EditWithinSymbolInput {
project: None,
path: "src/lib.rs".to_string(),
name: "hello".to_string(),
kind: None,
symbol_line: None,
old_text: "nonexistent".to_string(),
new_text: "replacement".to_string(),
replace_all: false,
occurrence: None,
near_line: None,
dry_run: None,
idempotency_key: None,
working_directory: None,
};
let result = server.edit_within_symbol(Parameters(input)).await;
assert!(result.contains("not found within"), "result: {result}");
}
#[tokio::test]
async fn test_replace_symbol_body_dry_run_skips_write() {
let original = b"fn foo() { old }\n";
let (_dir, server, file_path) = setup_edit_test(original);
let result = server
.replace_symbol_body(Parameters(crate::protocol::edit::ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "foo".to_string(),
kind: None,
symbol_line: None,
new_body: "fn foo() { new }".to_string(),
dry_run: Some(true),
idempotency_key: None,
if_match: None,
working_directory: None,
}))
.await;
assert!(
result.contains("[DRY RUN]"),
"should show dry run: {result}"
);
assert!(result.contains("Path authority: repository-bound"));
assert!(result.contains("Write semantics: dry run (no writes)"));
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
on_disk.contains("old"),
"file should be unchanged: {on_disk}"
);
}
#[tokio::test]
async fn test_insert_symbol_dry_run_skips_write() {
let original = b"fn anchor() {}\n";
let (_dir, server, file_path) = setup_edit_test(original);
let result = server
.insert_symbol(Parameters(crate::protocol::edit::InsertSymbolInput {
project: None,
path: "src/lib.rs".to_string(),
name: "anchor".to_string(),
kind: None,
symbol_line: None,
content: "fn new_fn() {}".to_string(),
position: Some("after".to_string()),
dry_run: Some(true),
idempotency_key: None,
working_directory: None,
}))
.await;
assert!(
result.contains("[DRY RUN]"),
"should show dry run: {result}"
);
assert!(result.contains("Path authority: repository-bound"));
assert!(result.contains("Write semantics: dry run (no writes)"));
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
!on_disk.contains("new_fn"),
"file should be unchanged: {on_disk}"
);
}
#[tokio::test]
async fn test_delete_symbol_dry_run_skips_write() {
let original = b"fn target() {}\nfn keep() {}\n";
let (_dir, server, file_path) = setup_edit_test(original);
let result = server
.delete_symbol(Parameters(crate::protocol::edit::DeleteSymbolInput {
project: None,
path: "src/lib.rs".to_string(),
name: "target".to_string(),
kind: None,
symbol_line: None,
dry_run: Some(true),
idempotency_key: None,
working_directory: None,
}))
.await;
assert!(
result.contains("[DRY RUN]"),
"should show dry run: {result}"
);
assert!(result.contains("Path authority: repository-bound"));
assert!(result.contains("Write semantics: dry run (no writes)"));
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
on_disk.contains("target"),
"file should be unchanged: {on_disk}"
);
}
#[tokio::test]
async fn test_edit_within_symbol_dry_run_skips_write() {
let original = b"fn foo() { old_text }\n";
let (_dir, server, file_path) = setup_edit_test(original);
let result = server
.edit_within_symbol(Parameters(crate::protocol::edit::EditWithinSymbolInput {
project: None,
path: "src/lib.rs".to_string(),
name: "foo".to_string(),
kind: None,
symbol_line: None,
old_text: "old_text".to_string(),
new_text: "new_text".to_string(),
replace_all: false,
occurrence: None,
near_line: None,
dry_run: Some(true),
idempotency_key: None,
working_directory: None,
}))
.await;
assert!(
result.contains("[DRY RUN]"),
"should show dry run: {result}"
);
assert!(result.contains("Path authority: repository-bound"));
assert!(result.contains("Write semantics: dry run (no writes)"));
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
on_disk.contains("old_text"),
"file should be unchanged: {on_disk}"
);
}
// ── Tier 2 batch tool integration tests ──
#[tokio::test]
async fn test_batch_edit_applies_across_files() {
use crate::protocol::edit::{BatchEditInput, EditOperation, SingleEdit};
let dir = tempfile::tempdir().unwrap();
std::fs::create_dir(dir.path().join(".git")).unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let a_content = b"fn alpha() { old }\n";
let b_content = b"fn beta() { keep }\n";
std::fs::write(src_dir.join("a.rs"), a_content).unwrap();
std::fs::write(src_dir.join("b.rs"), b_content).unwrap();
let mut files = vec![];
for (path, content) in [
("src/a.rs", a_content as &[u8]),
("src/b.rs", b_content as &[u8]),
] {
let result = crate::parsing::process_file(path, content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
files.push((path.to_string(), indexed));
}
let index = make_live_index_ready(files);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let input = BatchEditInput {
project: None,
edits: vec![
SingleEdit {
path: "src/a.rs".to_string(),
name: "alpha".to_string(),
kind: None,
symbol_line: None,
operation: EditOperation::Replace {
new_body: "fn alpha() { new }".to_string(),
},
working_directory: None,
},
SingleEdit {
path: "src/b.rs".to_string(),
name: "beta".to_string(),
kind: None,
symbol_line: None,
operation: EditOperation::Delete,
working_directory: None,
},
],
dry_run: Some(false),
idempotency_key: None,
working_directory: None,
};
let result = server.batch_edit(Parameters(input)).await;
assert!(result.contains("2 edit(s)"), "result: {result}");
assert!(
result.contains("Edit safety: structural-edit-safe"),
"result: {result}"
);
assert!(result.contains("Match type: exact"), "result: {result}");
assert!(
result.contains("Write semantics: transactional write + rollback + reindex"),
"result: {result}"
);
assert!(result.contains("Tee snapshot:"), "result: {result}");
assert!(result.contains(".symforge/tee/"), "result: {result}");
let a = std::fs::read_to_string(src_dir.join("a.rs")).unwrap();
assert!(a.contains("new"), "a.rs: {a}");
let b = std::fs::read_to_string(src_dir.join("b.rs")).unwrap();
assert!(!b.contains("beta"), "b.rs: {b}");
let tee_dir = dir.path().join(".symforge").join("tee");
let snapshots = std::fs::read_dir(&tee_dir)
.unwrap()
.collect::<Result<Vec<_>, _>>()
.unwrap();
assert_eq!(
snapshots.len(),
2,
"expected two tee snapshots in {tee_dir:?}"
);
let snapshot_bytes = snapshots
.iter()
.map(|entry| std::fs::read(entry.path()).unwrap())
.collect::<Vec<_>>();
assert!(
snapshot_bytes.iter().any(|bytes| bytes == a_content),
"a.rs original should be teed"
);
assert!(
snapshot_bytes.iter().any(|bytes| bytes == b_content),
"b.rs original should be teed"
);
}
#[tokio::test]
async fn test_batch_edit_reports_disk_refreshed_authority_for_stale_file() {
use crate::protocol::edit::{BatchEditInput, EditOperation, SingleEdit};
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let stale_indexed = b"fn alpha() { stale }\n";
let fresh_on_disk = b"fn alpha() { fresh }\n";
let file_path = src_dir.join("a.rs");
std::fs::write(&file_path, fresh_on_disk).unwrap();
let result = crate::parsing::process_file("src/a.rs", stale_indexed, LanguageId::Rust);
let indexed = crate::live_index::store::IndexedFile::from_parse_result(
result,
stale_indexed.to_vec(),
);
let index = make_live_index_ready(vec![("src/a.rs".to_string(), indexed)]);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let input = BatchEditInput {
project: None,
edits: vec![SingleEdit {
path: "src/a.rs".to_string(),
name: "alpha".to_string(),
kind: None,
symbol_line: None,
operation: EditOperation::Replace {
new_body: "fn alpha() { next }".to_string(),
},
working_directory: None,
}],
dry_run: Some(true),
idempotency_key: None,
working_directory: None,
};
let result = server.batch_edit(Parameters(input)).await;
assert!(
result.contains("Source authority: disk-refreshed"),
"result: {result}"
);
assert!(
result.contains("Write semantics: dry run (no writes)"),
"result: {result}"
);
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
on_disk.contains("fresh"),
"dry run should leave disk untouched: {on_disk}"
);
}
#[tokio::test]
async fn test_batch_rename_renames_def_and_refs() {
use crate::protocol::edit::BatchRenameInput;
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let lib_content = b"fn old_name() {}\n";
let main_content = b"fn caller() { old_name(); }\n";
std::fs::write(src_dir.join("lib.rs"), lib_content).unwrap();
std::fs::write(src_dir.join("main.rs"), main_content).unwrap();
let mut files = vec![];
for (path, content) in [
("src/lib.rs", lib_content as &[u8]),
("src/main.rs", main_content as &[u8]),
] {
let result = crate::parsing::process_file(path, content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
files.push((path.to_string(), indexed));
}
let index = make_live_index_ready(files);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let input = BatchRenameInput {
project: None,
path: "src/lib.rs".to_string(),
name: "old_name".to_string(),
kind: None,
symbol_line: None,
new_name: "new_name".to_string(),
dry_run: None,
idempotency_key: None,
code_only: None,
working_directory: None,
};
let result = server.batch_rename(Parameters(input)).await;
assert!(result.contains("Renamed"), "result: {result}");
assert!(result.contains("new_name"), "result: {result}");
assert!(
result.contains("Match type: constrained"),
"result: {result}"
);
assert!(
result.contains("Write semantics: transactional write + rollback + reindex"),
"result: {result}"
);
let lib = std::fs::read_to_string(src_dir.join("lib.rs")).unwrap();
assert!(lib.contains("new_name"), "lib.rs: {lib}");
assert!(!lib.contains("old_name"), "lib.rs: {lib}");
}
#[tokio::test]
async fn test_batch_rename_reports_disk_refreshed_authority_after_reconcile() {
use crate::protocol::edit::BatchRenameInput;
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let stale_lib = b"fn old_name() { stale(); }\n";
let stale_main = b"fn caller() { old_name(); stale(); }\n";
let fresh_lib = b"fn old_name() { fresh(); }\n";
let fresh_main = b"fn caller() { old_name(); fresh(); }\n";
std::fs::write(src_dir.join("lib.rs"), fresh_lib).unwrap();
std::fs::write(src_dir.join("main.rs"), fresh_main).unwrap();
let mut files = vec![];
for (path, content) in [
("src/lib.rs", stale_lib as &[u8]),
("src/main.rs", stale_main as &[u8]),
] {
let result = crate::parsing::process_file(path, content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
files.push((path.to_string(), indexed));
}
let index = make_live_index_ready(files);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let input = BatchRenameInput {
project: None,
path: "src/lib.rs".to_string(),
name: "old_name".to_string(),
kind: None,
symbol_line: None,
new_name: "new_name".to_string(),
dry_run: Some(true),
idempotency_key: None,
code_only: None,
working_directory: None,
};
let result = server.batch_rename(Parameters(input)).await;
assert!(
result.contains("Source authority: disk-refreshed"),
"result: {result}"
);
assert!(
result.contains("Write semantics: dry run (no writes)"),
"result: {result}"
);
let lib = std::fs::read_to_string(src_dir.join("lib.rs")).unwrap();
assert!(
lib.contains("fresh"),
"dry run should leave disk untouched: {lib}"
);
}
#[tokio::test]
async fn test_batch_rename_catches_path_qualified_calls() {
// Regression: batch_rename must catch Type::new() path-qualified calls,
// not just simple name references. The index tracks "new" as the call
// target, but "Widget" as a path prefix must also be renamed.
use crate::protocol::edit::BatchRenameInput;
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let lib_content = b"pub struct Widget { pub name: String }\nimpl Widget {\n pub fn new(name: &str) -> Self { Widget { name: name.to_string() } }\n}\n";
let main_content =
b"use crate::Widget;\nfn make() -> Widget {\n Widget::new(\"default\")\n}\n";
std::fs::write(src_dir.join("lib.rs"), lib_content).unwrap();
std::fs::write(src_dir.join("main.rs"), main_content).unwrap();
let mut files = vec![];
for (path, content) in [
("src/lib.rs", lib_content as &[u8]),
("src/main.rs", main_content as &[u8]),
] {
let result = crate::parsing::process_file(path, content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
files.push((path.to_string(), indexed));
}
let index = make_live_index_ready(files);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let input = BatchRenameInput {
project: None,
path: "src/lib.rs".to_string(),
name: "Widget".to_string(),
kind: None,
symbol_line: None,
new_name: "Gadget".to_string(),
dry_run: None,
idempotency_key: None,
code_only: None,
working_directory: None,
};
let result = server.batch_rename(Parameters(input)).await;
assert!(result.contains("Renamed"), "result: {result}");
// Verify disk: Widget::new() in main.rs must become Gadget::new()
let main = std::fs::read_to_string(src_dir.join("main.rs")).unwrap();
assert!(
!main.contains("Widget"),
"main.rs should have no 'Widget' left after rename, got: {main}"
);
assert!(
main.contains("Gadget::new"),
"main.rs should contain Gadget::new, got: {main}"
);
}
#[tokio::test]
async fn test_search_text_agrees_with_disk_after_rename() {
// Regression: after batch_rename, search_text must agree with on-disk
// content. If rename misses some sites, search_text must still find
// the old name (because it's still on disk), not report zero matches.
use crate::protocol::edit::BatchRenameInput;
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let lib_content = b"pub struct Widget { pub name: String }\nimpl Widget {\n pub fn new(name: &str) -> Self { Widget { name: name.to_string() } }\n}\n";
let main_content =
b"use crate::Widget;\nfn make() -> Widget {\n Widget::new(\"default\")\n}\n";
std::fs::write(src_dir.join("lib.rs"), lib_content).unwrap();
std::fs::write(src_dir.join("main.rs"), main_content).unwrap();
let mut files = vec![];
for (path, content) in [
("src/lib.rs", lib_content as &[u8]),
("src/main.rs", main_content as &[u8]),
] {
let result = crate::parsing::process_file(path, content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
files.push((path.to_string(), indexed));
}
let index = make_live_index_ready(files);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
// Do the rename
let input = BatchRenameInput {
project: None,
path: "src/lib.rs".to_string(),
name: "Widget".to_string(),
kind: None,
symbol_line: None,
new_name: "Gadget".to_string(),
dry_run: None,
idempotency_key: None,
code_only: None,
working_directory: None,
};
let _result = server.batch_rename(Parameters(input)).await;
// Now check: if "Widget" is still on disk anywhere, search_text must find it.
let disk_has_widget = std::fs::read_to_string(src_dir.join("main.rs"))
.unwrap()
.contains("Widget")
|| std::fs::read_to_string(src_dir.join("lib.rs"))
.unwrap()
.contains("Widget");
if disk_has_widget {
// search_text should find it too — index must not lie
let search_input = crate::protocol::tools::SearchTextInput {
query: Some("Widget".to_string()),
terms: None,
path_prefix: None,
glob: None,
exclude_glob: None,
language: None,
regex: None,
case_sensitive: None,
whole_word: None,
group_by: None,
follow_refs: None,
follow_refs_limit: None,
ranked: None,
context: None,
limit: None,
max_per_file: None,
include_tests: None,
include_generated: None,
include_vendor: None,
include_personal_tooling: None,
estimate: None,
max_tokens: None,
structural: None,
project: None,
projects: None,
};
let search_result = server.search_text(Parameters(search_input)).await;
assert!(
!search_result.contains("0 matches"),
"search_text says 0 matches but Widget is still on disk! Index/disk desync. search_result: {search_result}"
);
}
}
#[tokio::test]
async fn test_batch_rename_catches_qualified_call() {
// Supplemental qualified scan must catch OldType::new() and rename it.
use crate::protocol::edit::BatchRenameInput;
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let lib_content =
b"pub struct OldType;\nimpl OldType {\n pub fn new() -> Self { OldType }\n}\n";
let main_content = b"fn make() { let _ = OldType::new(); }\n";
std::fs::write(src_dir.join("lib.rs"), lib_content).unwrap();
std::fs::write(src_dir.join("main.rs"), main_content).unwrap();
let mut files = vec![];
for (path, content) in [
("src/lib.rs", lib_content as &[u8]),
("src/main.rs", main_content as &[u8]),
] {
let result = crate::parsing::process_file(path, content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
files.push((path.to_string(), indexed));
}
let index = make_live_index_ready(files);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let input = BatchRenameInput {
project: None,
path: "src/lib.rs".to_string(),
name: "OldType".to_string(),
kind: None,
symbol_line: None,
new_name: "NewType".to_string(),
dry_run: None,
idempotency_key: None,
code_only: None,
working_directory: None,
};
let result = server.batch_rename(Parameters(input)).await;
assert!(result.contains("Renamed"), "result: {result}");
let main = std::fs::read_to_string(src_dir.join("main.rs")).unwrap();
assert!(
main.contains("NewType::new()"),
"main.rs should contain NewType::new(), got: {main}"
);
assert!(
!main.contains("OldType"),
"main.rs should have no OldType left, got: {main}"
);
}
#[tokio::test]
async fn test_batch_rename_dry_run_separates_confident_uncertain() {
// Dry run must show separate sections for confident and uncertain matches.
use crate::protocol::edit::BatchRenameInput;
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
// lib.rs: definition only (confident)
// main.rs: code usage (confident) + comment usage (uncertain)
let lib_content = b"pub struct OldType;\n";
let main_content =
b"fn use_it() { let _ = OldType::new(); }\n// OldType::new() creates an instance\n";
std::fs::write(src_dir.join("lib.rs"), lib_content).unwrap();
std::fs::write(src_dir.join("main.rs"), main_content).unwrap();
let mut files = vec![];
for (path, content) in [
("src/lib.rs", lib_content as &[u8]),
("src/main.rs", main_content as &[u8]),
] {
let result = crate::parsing::process_file(path, content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
files.push((path.to_string(), indexed));
}
let index = make_live_index_ready(files);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let input = BatchRenameInput {
project: None,
path: "src/lib.rs".to_string(),
name: "OldType".to_string(),
kind: None,
symbol_line: None,
new_name: "NewType".to_string(),
dry_run: Some(true),
idempotency_key: None,
code_only: None,
working_directory: None,
};
let result = server.batch_rename(Parameters(input)).await;
assert!(
result.contains("Confident matches"),
"dry_run must have confident section, got: {result}"
);
assert!(
result.contains("Uncertain matches"),
"dry_run must have uncertain section, got: {result}"
);
assert!(
result.contains("NOT applied"),
"uncertain section must say NOT applied, got: {result}"
);
}
#[tokio::test]
async fn test_batch_rename_uncertain_not_applied_by_default() {
// Uncertain matches (comments) must NOT be modified during a live rename.
use crate::protocol::edit::BatchRenameInput;
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
// File with OldType only in a comment — no code usage.
let lib_content = b"pub struct OldType;\n";
let main_content = b"fn dummy() {}\n// OldType::new() creates an instance\n";
std::fs::write(src_dir.join("lib.rs"), lib_content).unwrap();
std::fs::write(src_dir.join("main.rs"), main_content).unwrap();
let mut files = vec![];
for (path, content) in [
("src/lib.rs", lib_content as &[u8]),
("src/main.rs", main_content as &[u8]),
] {
let result = crate::parsing::process_file(path, content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
files.push((path.to_string(), indexed));
}
let index = make_live_index_ready(files);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let input = BatchRenameInput {
project: None,
path: "src/lib.rs".to_string(),
name: "OldType".to_string(),
kind: None,
symbol_line: None,
new_name: "NewType".to_string(),
dry_run: None,
idempotency_key: None,
code_only: None,
working_directory: None,
};
let result = server.batch_rename(Parameters(input)).await;
assert!(result.contains("Renamed"), "result: {result}");
// Comment in main.rs must remain unchanged.
let main = std::fs::read_to_string(src_dir.join("main.rs")).unwrap();
assert!(
main.contains("OldType"),
"comment in main.rs must not be modified, got: {main}"
);
// But the result should surface the uncertain match as a warning.
assert!(
result.contains("Uncertain matches") || result.contains("NOT applied"),
"result should warn about uncertain match, got: {result}"
);
}
#[tokio::test]
async fn test_batch_rename_scopes_common_name_to_target() {
// Renaming "new" scoped to Target should not touch SomeOther::new().
use crate::protocol::edit::BatchRenameInput;
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let lib_content =
b"pub struct Target;\nimpl Target {\n pub fn new() -> Self { Target }\n}\npub struct SomeOther;\nimpl SomeOther {\n pub fn new() -> Self { SomeOther }\n}\n";
let main_content = b"fn make() { let _a = Target::new(); let _b = SomeOther::new(); }\n";
std::fs::write(src_dir.join("lib.rs"), lib_content).unwrap();
std::fs::write(src_dir.join("main.rs"), main_content).unwrap();
let mut files = vec![];
for (path, content) in [
("src/lib.rs", lib_content as &[u8]),
("src/main.rs", main_content as &[u8]),
] {
let result = crate::parsing::process_file(path, content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
files.push((path.to_string(), indexed));
}
let index = make_live_index_ready(files);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
// Rename the Target struct itself, not its "new" method.
let input = BatchRenameInput {
project: None,
path: "src/lib.rs".to_string(),
name: "Target".to_string(),
kind: None,
symbol_line: None,
new_name: "Renamed".to_string(),
dry_run: None,
idempotency_key: None,
code_only: None,
working_directory: None,
};
let result = server.batch_rename(Parameters(input)).await;
assert!(result.contains("Renamed"), "result: {result}");
let main = std::fs::read_to_string(src_dir.join("main.rs")).unwrap();
assert!(
main.contains("Renamed::new()"),
"Target::new() must become Renamed::new(), got: {main}"
);
assert!(
main.contains("SomeOther::new()"),
"SomeOther::new() must be untouched, got: {main}"
);
assert!(
!main.contains("Target::"),
"Target:: reference must be gone, got: {main}"
);
}
#[tokio::test]
async fn test_batch_rename_ambiguous_method_demotes_bare_refs() {
// Renaming the SHARED METHOD `new` scoped to Target::new. `new` has 2
// definitions (Target::new, SomeOther::new), so the leaf name alone is
// ambiguous. 019 recall-recovery: a call whose IMMEDIATE QUALIFIER equals
// the resolved target's UNIQUE `impl` owner IS attributable and stays
// writable, so `Target::new()` is RECOVERED (Target and SomeOther are
// DISTINCT owner names -> Target is unique). The core SAFETY invariant is
// preserved: `SomeOther::new()` (wrong owner) is NEVER rewritten. Before
// the recovery upgrade this test asserted main.rs was byte-identical; the
// upgrade makes the qualified Target::new() site the correct write, while
// the wrong-owner site stays untouched.
use crate::protocol::edit::BatchRenameInput;
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let lib_content =
b"pub struct Target;\nimpl Target {\n pub fn new() -> Self { Target }\n}\npub struct SomeOther;\nimpl SomeOther {\n pub fn new() -> Self { SomeOther }\n}\n";
let main_content = b"fn make() { let _a = Target::new(); let _b = SomeOther::new(); }\n";
std::fs::write(src_dir.join("lib.rs"), lib_content).unwrap();
std::fs::write(src_dir.join("main.rs"), main_content).unwrap();
let mut files = vec![];
for (path, content) in [
("src/lib.rs", lib_content as &[u8]),
("src/main.rs", main_content as &[u8]),
] {
let result = crate::parsing::process_file(path, content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
files.push((path.to_string(), indexed));
}
let index = make_live_index_ready(files);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
// Target the `new` at line 3 (Target::new), NOT SomeOther::new (line 7).
let input = BatchRenameInput {
project: None,
path: "src/lib.rs".to_string(),
name: "new".to_string(),
kind: None,
symbol_line: Some(3),
new_name: "make_new".to_string(),
dry_run: None,
idempotency_key: None,
code_only: None,
working_directory: None,
};
let _result = server.batch_rename(Parameters(input)).await;
// The definition site (Target::new in lib.rs) IS renamed.
let lib = std::fs::read_to_string(src_dir.join("lib.rs")).unwrap();
assert!(
lib.contains("pub fn make_new() -> Self { Target }"),
"Target::new definition must be renamed, got: {lib}"
);
// SomeOther::new definition in lib.rs is a distinct symbol — untouched.
assert!(
lib.contains("pub fn new() -> Self { SomeOther }"),
"SomeOther::new definition must be untouched, got: {lib}"
);
// RECOVERY: Target::new() call site rewritten to Target::make_new()
// because "Target" is a unique owner among `new`'s defs.
let main = std::fs::read_to_string(src_dir.join("main.rs")).unwrap();
assert!(
main.contains("Target::make_new()"),
"Target::new() call site must be recovered (unique owner), got: {main}"
);
// CORE SAFETY: SomeOther::new() (wrong owner) is NEVER rewritten.
assert!(
main.contains("SomeOther::new()"),
"SomeOther::new() call site must be untouched, got: {main}"
);
assert!(
!main.contains("SomeOther::make_new"),
"SomeOther::new() must never be rewritten, got: {main}"
);
}
#[tokio::test]
async fn test_batch_rename_ambiguous_method_recovers_unique_owner_calls() {
// 019 recall-recovery: `new` is ambiguous (Target::new in a.rs,
// Other::new in b.rs). Renaming Target::new must RECOVER the
// `Target::new()` call site (Target is a UNIQUE owner among `new`'s
// owners) while leaving `Other::new()` and any bare `new()` untouched.
use crate::protocol::edit::BatchRenameInput;
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let a_content =
b"pub struct Target;\nimpl Target {\n pub fn new() -> Self { Target }\n}\n";
let b_content = b"pub struct Other;\nimpl Other {\n pub fn new() -> Self { Other }\n}\n";
// A bare (unqualified) `new()` call carries NO qualifier, so it must
// stay demoted (the "bare still demotes" invariant).
let main_content =
b"fn make() { let _a = Target::new(); let _b = Other::new(); let _c = new(); }\n";
std::fs::write(src_dir.join("a.rs"), a_content).unwrap();
std::fs::write(src_dir.join("b.rs"), b_content).unwrap();
std::fs::write(src_dir.join("main.rs"), main_content).unwrap();
let mut files = vec![];
for (path, content) in [
("src/a.rs", a_content as &[u8]),
("src/b.rs", b_content as &[u8]),
("src/main.rs", main_content as &[u8]),
] {
let result = crate::parsing::process_file(path, content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
files.push((path.to_string(), indexed));
}
let index = make_live_index_ready(files);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
// Target the `new` in a.rs (Target::new).
let input = BatchRenameInput {
project: None,
path: "src/a.rs".to_string(),
name: "new".to_string(),
kind: None,
symbol_line: Some(3),
new_name: "make_new".to_string(),
dry_run: None,
idempotency_key: None,
code_only: None,
working_directory: None,
};
let _result = server.batch_rename(Parameters(input)).await;
// Definition site renamed.
let a = std::fs::read_to_string(src_dir.join("a.rs")).unwrap();
assert!(
a.contains("pub fn make_new() -> Self { Target }"),
"Target::new definition must be renamed, got: {a}"
);
// Other::new definition untouched.
let b = std::fs::read_to_string(src_dir.join("b.rs")).unwrap();
assert!(
b.contains("pub fn new() -> Self { Other }"),
"Other::new definition must be untouched, got: {b}"
);
// RECOVERY: Target::new() call site rewritten to Target::make_new().
let main = std::fs::read_to_string(src_dir.join("main.rs")).unwrap();
assert!(
main.contains("Target::make_new()"),
"Target::new() call site must be RECOVERED (unique owner), got: {main}"
);
// SAFETY: Other::new() call site never touched.
assert!(
main.contains("Other::new()"),
"Other::new() call site must be untouched (wrong owner), got: {main}"
);
assert!(
!main.contains("Other::make_new"),
"Other::new() must never be rewritten, got: {main}"
);
// BARE-DEMOTE invariant: the unqualified `new()` call has no qualifier
// to attribute, so it must NOT be rewritten (stays ` new()`, not
// ` make_new()`).
assert!(
main.contains("let _c = new();"),
"bare unqualified new() must stay demoted (not rewritten), got: {main}"
);
}
#[tokio::test]
async fn test_batch_rename_twin_owner_demotes_both_call_sites() {
// 019 recall-recovery SOUNDNESS (twin-owner guard): TWO `impl Target`
// (a.rs and c.rs), both with `fn new`. Renaming one Target::new must
// NOT rewrite EITHER `Target::new()` call site — the qualifier
// "Target" cannot disambiguate between the two same-owner defs, so the
// uniqueness guard fires and both call sites are demoted. This is the
// test a demolition of the guard would target; it MUST pass.
use crate::protocol::edit::BatchRenameInput;
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let a_content =
b"pub struct Target;\nimpl Target {\n pub fn new() -> Self { Target }\n}\n";
// Second `impl Target` in a different file, same owner name.
let c_content = b"impl Target {\n pub fn new() -> Self { Target }\n}\n";
let main_content = b"fn make() { let _a = Target::new(); }\n";
std::fs::write(src_dir.join("a.rs"), a_content).unwrap();
std::fs::write(src_dir.join("c.rs"), c_content).unwrap();
std::fs::write(src_dir.join("main.rs"), main_content).unwrap();
let mut files = vec![];
for (path, content) in [
("src/a.rs", a_content as &[u8]),
("src/c.rs", c_content as &[u8]),
("src/main.rs", main_content as &[u8]),
] {
let result = crate::parsing::process_file(path, content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
files.push((path.to_string(), indexed));
}
let index = make_live_index_ready(files);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
// Rename the Target::new in a.rs (line 3).
let input = BatchRenameInput {
project: None,
path: "src/a.rs".to_string(),
name: "new".to_string(),
kind: None,
symbol_line: Some(3),
new_name: "make_new".to_string(),
dry_run: None,
idempotency_key: None,
code_only: None,
working_directory: None,
};
let result = server.batch_rename(Parameters(input)).await;
// Definition site (a.rs) IS renamed.
let a = std::fs::read_to_string(src_dir.join("a.rs")).unwrap();
assert!(
a.contains("pub fn make_new() -> Self { Target }"),
"targeted Target::new definition must be renamed, got: {a}"
);
// SOUNDNESS: the Target::new() call site must NOT be rewritten — the
// twin `impl Target` in c.rs makes the "Target" qualifier ambiguous.
let main = std::fs::read_to_string(src_dir.join("main.rs")).unwrap();
assert_eq!(
main.as_bytes(),
main_content as &[u8],
"twin-owner ambiguity must demote the call site (no write), got: {main}"
);
assert!(
!main.contains("make_new"),
"no call site may be rewritten under twin-owner ambiguity, got: {main}"
);
// Must be surfaced as uncertain, not silently claimed.
assert!(
result.contains("Uncertain matches") || result.contains("NOT applied"),
"demoted twin-owner call must be surfaced as uncertain, got: {result}"
);
}
#[tokio::test]
async fn test_batch_insert_adds_to_multiple_files() {
use crate::protocol::edit::{BatchInsertInput, InsertPosition, InsertTarget};
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let a_content = b"fn handler_a() {}\n";
let b_content = b"fn handler_b() {}\n";
std::fs::write(src_dir.join("a.rs"), a_content).unwrap();
std::fs::write(src_dir.join("b.rs"), b_content).unwrap();
let mut files = vec![];
for (path, content) in [
("src/a.rs", a_content as &[u8]),
("src/b.rs", b_content as &[u8]),
] {
let result = crate::parsing::process_file(path, content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
files.push((path.to_string(), indexed));
}
let index = make_live_index_ready(files);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let input = BatchInsertInput {
project: None,
content: "fn logging() {}".to_string(),
position: InsertPosition::After,
targets: vec![
InsertTarget {
path: "src/a.rs".to_string(),
name: "handler_a".to_string(),
kind: None,
symbol_line: None,
working_directory: None,
},
InsertTarget {
path: "src/b.rs".to_string(),
name: "handler_b".to_string(),
kind: None,
symbol_line: None,
working_directory: None,
},
],
dry_run: Some(false),
idempotency_key: None,
working_directory: None,
};
let result = server.batch_insert(Parameters(input)).await;
assert!(result.contains("2 edit(s)"), "result: {result}");
assert!(
result.contains("Edit safety: structural-edit-safe"),
"result: {result}"
);
assert!(result.contains("Match type: exact"), "result: {result}");
assert!(
result.contains("Write semantics: transactional write + rollback + reindex"),
"result: {result}"
);
let a = std::fs::read_to_string(src_dir.join("a.rs")).unwrap();
assert!(a.contains("logging"), "a.rs: {a}");
let b = std::fs::read_to_string(src_dir.join("b.rs")).unwrap();
assert!(b.contains("logging"), "b.rs: {b}");
}
#[tokio::test]
async fn test_batch_insert_reports_disk_refreshed_authority_for_stale_file() {
use crate::protocol::edit::{BatchInsertInput, InsertPosition, InsertTarget};
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let stale_indexed = b"fn handler_a() { stale(); }\n";
let fresh_on_disk = b"fn handler_a() { fresh(); }\n";
let file_path = src_dir.join("a.rs");
std::fs::write(&file_path, fresh_on_disk).unwrap();
let result = crate::parsing::process_file("src/a.rs", stale_indexed, LanguageId::Rust);
let indexed = crate::live_index::store::IndexedFile::from_parse_result(
result,
stale_indexed.to_vec(),
);
let index = make_live_index_ready(vec![("src/a.rs".to_string(), indexed)]);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let input = BatchInsertInput {
project: None,
content: "fn logging() {}".to_string(),
position: InsertPosition::After,
targets: vec![InsertTarget {
path: "src/a.rs".to_string(),
name: "handler_a".to_string(),
kind: None,
symbol_line: None,
working_directory: None,
}],
dry_run: Some(true),
idempotency_key: None,
working_directory: None,
};
let result = server.batch_insert(Parameters(input)).await;
assert!(
result.contains("Source authority: disk-refreshed"),
"result: {result}"
);
assert!(
result.contains("Write semantics: dry run (no writes)"),
"result: {result}"
);
let on_disk = std::fs::read_to_string(&file_path).unwrap();
assert!(
on_disk.contains("fresh"),
"dry run should leave disk untouched: {on_disk}"
);
}
#[tokio::test]
async fn test_batch_insert_dry_run_skips_write() {
use crate::protocol::edit::{BatchInsertInput, InsertPosition, InsertTarget};
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let a_content = b"fn handler_a() {}\n";
let b_content = b"fn handler_b() {}\n";
std::fs::write(src_dir.join("a.rs"), a_content).unwrap();
std::fs::write(src_dir.join("b.rs"), b_content).unwrap();
let mut files = vec![];
for (path, content) in [
("src/a.rs", a_content as &[u8]),
("src/b.rs", b_content as &[u8]),
] {
let result = crate::parsing::process_file(path, content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
files.push((path.to_string(), indexed));
}
let index = make_live_index_ready(files);
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let input = BatchInsertInput {
project: None,
content: "fn logging() {}".to_string(),
position: InsertPosition::After,
targets: vec![
InsertTarget {
path: "src/a.rs".to_string(),
name: "handler_a".to_string(),
kind: None,
symbol_line: None,
working_directory: None,
},
InsertTarget {
path: "src/b.rs".to_string(),
name: "handler_b".to_string(),
kind: None,
symbol_line: None,
working_directory: None,
},
],
dry_run: Some(true),
idempotency_key: None,
working_directory: None,
};
let result = server.batch_insert(Parameters(input)).await;
assert!(result.contains("[DRY RUN]"), "result: {result}");
assert!(result.contains("Match type: exact"), "result: {result}");
assert!(
result.contains("Write semantics: dry run (no writes)"),
"result: {result}"
);
// Files must be unchanged.
let a = std::fs::read_to_string(src_dir.join("a.rs")).unwrap();
assert!(!a.contains("logging"), "dry_run must not write: {a}");
let b = std::fs::read_to_string(src_dir.join("b.rs")).unwrap();
assert!(!b.contains("logging"), "dry_run must not write: {b}");
}
#[tokio::test]
async fn test_ask_reports_exact_route_confidence() {
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let content = b"fn helper() {}\nfn caller() { helper(); }\n";
std::fs::write(src_dir.join("lib.rs"), content).unwrap();
let result = crate::parsing::process_file("src/lib.rs", content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
let server = make_server_with_root(
make_live_index_ready(vec![("src/lib.rs".to_string(), indexed)]),
Some(dir.path().to_path_buf()),
);
let input = super::SmartQueryInput {
project: None,
query: "who calls helper".to_string(),
max_tokens: None,
};
let result = server.ask(Parameters(input)).await;
assert!(
result.contains("Route confidence: exact"),
"result: {result}"
);
assert!(
result.contains("Chosen tool: find_references"),
"result: {result}"
);
assert!(
result.contains("Invocation: find_references"),
"result: {result}"
);
assert!(
result.contains("matched explicit caller/reference phrasing"),
"result: {result}"
);
}
#[tokio::test]
async fn test_ask_tool_help_returns_impact_analysis_catalog() {
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let content = b"fn helper() {}\n";
std::fs::write(src_dir.join("lib.rs"), content).unwrap();
let result = crate::parsing::process_file("src/lib.rs", content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
let server = make_server_with_root(
make_live_index_ready(vec![("src/lib.rs".to_string(), indexed)]),
Some(dir.path().to_path_buf()),
);
let input = super::SmartQueryInput {
project: None,
query: "what tools can I use for impact analysis?".to_string(),
max_tokens: None,
};
let result = server.ask(Parameters(input)).await;
// Routed to the tool catalog, not a code search.
assert!(result.contains("Chosen tool: ask"), "result: {result}");
// The impact-analysis catalog group must list all impact tools.
for tool in [
"find_references",
"find_dependents",
"get_symbol_context",
"analyze_file_impact",
"what_changed",
"diff_symbols",
] {
assert!(
result.contains(tool),
"impact-analysis catalog missing `{tool}`; result:\n{result}"
);
}
}
#[tokio::test]
async fn test_ask_reports_inferred_route_confidence() {
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let content = b"struct LiveIndex;\n";
std::fs::write(src_dir.join("lib.rs"), content).unwrap();
let result = crate::parsing::process_file("src/lib.rs", content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
let server = make_server_with_root(
make_live_index_ready(vec![("src/lib.rs".to_string(), indexed)]),
Some(dir.path().to_path_buf()),
);
let input = super::SmartQueryInput {
project: None,
query: "LiveIndex".to_string(),
max_tokens: None,
};
let result = server.ask(Parameters(input)).await;
assert!(
result.contains("Route confidence: inferred"),
"result: {result}"
);
assert!(
result.contains("Chosen tool: search_symbols"),
"result: {result}"
);
assert!(result.contains("Suggested next step:"), "result: {result}");
}
#[tokio::test]
async fn test_ask_compound_lookup_extracts_leading_symbol() {
// SF-005: a compound lookup like "Where is X defined and what module
// imports it?" must route to search_symbols with ONLY the leading symbol
// token, report `inferred` confidence (not a confident false negative), and
// chain a follow-up hint naming search_symbols -> find_references.
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
std::fs::write(
src_dir.join("controller.ts"),
b"class TestingController {}\n",
)
.unwrap();
let mut indexed = make_file(
"src/controller.ts",
b"class TestingController {}\n",
vec![make_symbol("TestingController", SymbolKind::Class, 1, 1)],
);
indexed.1.language = LanguageId::TypeScript;
let server = make_server_with_root(
make_live_index_ready(vec![indexed]),
Some(dir.path().to_path_buf()),
);
let input = super::SmartQueryInput {
project: None,
query: "Where is TestingController defined and what module imports it?".to_string(),
max_tokens: None,
};
let result = server.ask(Parameters(input)).await;
assert!(
result.contains("Route confidence: inferred"),
"compound lookup must downgrade to inferred, not exact: {result}"
);
assert!(
result.contains("Chosen tool: search_symbols"),
"result: {result}"
);
assert!(
result.contains("Invocation: search_symbols(query=\"TestingController\")"),
"invocation must echo the leading symbol token only: {result}"
);
assert!(
!result.contains("imports it"),
"the trailing clause must not leak into the symbol query: {result}"
);
assert!(
result.contains("Suggested next step:"),
"downgraded route must chain a follow-up hint: {result}"
);
assert!(
result.contains("search_symbols -> find_references"),
"follow-up hint must name the chained sequence: {result}"
);
}
#[tokio::test]
async fn test_ask_reports_fallback_route_confidence() {
let server = make_server(make_live_index_ready(vec![]));
let input = super::SmartQueryInput {
project: None,
query: "error handling patterns".to_string(),
max_tokens: None,
};
let result = server.ask(Parameters(input)).await;
assert!(
result.contains("Route confidence: fallback"),
"result: {result}"
);
assert!(result.contains("Chosen tool: explore"), "result: {result}");
assert!(
result.contains(
"Rationale: no stronger route matched, so SymForge fell back to conceptual exploration"
),
"fallback ask routes should explain why explore was chosen: {result}"
);
assert!(result.contains("Suggested next step:"), "result: {result}");
}
#[tokio::test]
async fn test_ask_upgrades_exact_symbol_understanding_query() {
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let content = b"struct BusActor;\nimpl BusActor { fn handle(&self) {} }\n";
std::fs::write(src_dir.join("bus.rs"), content).unwrap();
let result = crate::parsing::process_file("src/bus.rs", content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
let server = make_server_with_root(
make_live_index_ready(vec![("src/bus.rs".to_string(), indexed)]),
Some(dir.path().to_path_buf()),
);
let input = super::SmartQueryInput {
project: None,
query: "how does BusActor work?".to_string(),
max_tokens: None,
};
let result = server.ask(Parameters(input)).await;
assert!(
result.contains("Route confidence: inferred"),
"result: {result}"
);
assert!(
result.contains("Chosen tool: get_symbol_context"),
"result: {result}"
);
assert!(
result.contains("Invocation: get_symbol_context(name=\"BusActor\")"),
"result: {result}"
);
assert!(
result.contains("detected an exact indexed symbol inside a broad explanation query"),
"result: {result}"
);
}
#[tokio::test]
async fn test_ask_upgrades_multi_definition_symbol_prefers_src() {
// Symbol "MyHandler" appears in both src/ and tests/; the src/ definition
// must win and the query must still upgrade to get_symbol_context.
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
let tests_dir = dir.path().join("tests");
std::fs::create_dir_all(&src_dir).unwrap();
std::fs::create_dir_all(&tests_dir).unwrap();
// src/handler.rs — large definition (lines 0-40)
let src_content: &[u8] = b"struct MyHandler;\nimpl MyHandler {\n fn run(&self) {}\n fn stop(&self) {}\n fn pause(&self) {}\n fn resume(&self) {}\n fn status(&self) {}\n fn reset(&self) {}\n fn init(&self) {}\n fn close(&self) {}\n fn open(&self) {}\n fn flush(&self) {}\n fn drain(&self) {}\n fn process(&self) {}\n fn submit(&self) {}\n fn cancel(&self) {}\n fn wait(&self) {}\n fn poll(&self) {}\n fn tick(&self) {}\n fn advance(&self) {}\n fn check(&self) {}\n}\n";
std::fs::write(src_dir.join("handler.rs"), src_content).unwrap();
// tests/test_handler.rs — short test stub (lines 0-5)
let test_content: &[u8] = b"struct MyHandler;\n#[test]\nfn it_works() {}\n";
std::fs::write(tests_dir.join("test_handler.rs"), test_content).unwrap();
let src_result =
crate::parsing::process_file("src/handler.rs", src_content, LanguageId::Rust);
let src_indexed = crate::live_index::store::IndexedFile::from_parse_result(
src_result,
src_content.to_vec(),
);
let test_result =
crate::parsing::process_file("tests/test_handler.rs", test_content, LanguageId::Rust);
let test_indexed = crate::live_index::store::IndexedFile::from_parse_result(
test_result,
test_content.to_vec(),
);
let server = make_server_with_root(
make_live_index_ready(vec![
("src/handler.rs".to_string(), src_indexed),
("tests/test_handler.rs".to_string(), test_indexed),
]),
Some(dir.path().to_path_buf()),
);
let input = super::SmartQueryInput {
project: None,
query: "how does MyHandler work?".to_string(),
max_tokens: None,
};
let result = server.ask(Parameters(input)).await;
assert!(
result.contains("Chosen tool: get_symbol_context"),
"multi-definition symbol should still upgrade to get_symbol_context: {result}"
);
assert!(
result.contains("Invocation: get_symbol_context(name=\"MyHandler\")"),
"result: {result}"
);
}
#[tokio::test]
async fn test_ask_routes_two_distinct_symbols_to_explore() {
// "how does X interact with Y" names two DISTINCT indexed symbols; the
// relationship question must fall through to explore, not get hijacked
// into get_symbol_context on whichever symbol scores highest.
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let content = b"struct BusActor;\nimpl BusActor { fn handle(&self) {} }\nstruct WorkerActor;\nimpl WorkerActor { fn run(&self) {} }\n";
std::fs::write(src_dir.join("actors.rs"), content).unwrap();
let result = crate::parsing::process_file("src/actors.rs", content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
let server = make_server_with_root(
make_live_index_ready(vec![("src/actors.rs".to_string(), indexed)]),
Some(dir.path().to_path_buf()),
);
let input = super::SmartQueryInput {
project: None,
query: "how does BusActor interact with WorkerActor?".to_string(),
max_tokens: None,
};
let result = server.ask(Parameters(input)).await;
assert!(result.contains("Chosen tool: explore"), "result: {result}");
assert!(
!result.contains("Chosen tool: get_symbol_context"),
"a two-symbol relationship query must not upgrade to get_symbol_context: {result}"
);
}
#[tokio::test]
async fn test_ask_keeps_broad_explore_for_generic_understanding_query() {
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let content = b"fn handle() {}\n";
std::fs::write(src_dir.join("lib.rs"), content).unwrap();
let result = crate::parsing::process_file("src/lib.rs", content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
let server = make_server_with_root(
make_live_index_ready(vec![("src/lib.rs".to_string(), indexed)]),
Some(dir.path().to_path_buf()),
);
let input = super::SmartQueryInput {
project: None,
query: "how does handle work?".to_string(),
max_tokens: None,
};
let result = server.ask(Parameters(input)).await;
assert!(result.contains("Chosen tool: explore"), "result: {result}");
assert!(
!result.contains("Chosen tool: get_symbol_context"),
"generic symbol names should not hijack broad explain queries: {result}"
);
}
#[tokio::test]
async fn test_ask_upgrades_broad_type_query_to_find_implementations() {
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let content = b"trait Actor {}\nstruct BusActor;\nimpl Actor for BusActor {}\nstruct WorkerActor;\nimpl Actor for WorkerActor {}\n";
std::fs::write(src_dir.join("actors.rs"), content).unwrap();
let result = crate::parsing::process_file("src/actors.rs", content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
let server = make_server_with_root(
make_live_index_ready(vec![("src/actors.rs".to_string(), indexed)]),
Some(dir.path().to_path_buf()),
);
let input = super::SmartQueryInput {
project: None,
query: "what are the main actor types?".to_string(),
max_tokens: None,
};
let result = server.ask(Parameters(input)).await;
assert!(
result.contains("Route confidence: inferred"),
"result: {result}"
);
assert!(
result.contains("Chosen tool: find_references"),
"result: {result}"
);
assert!(
result
.contains("Invocation: find_references(name=\"Actor\", mode=\"implementations\")"),
"result: {result}"
);
assert!(
result.contains("trait-like symbol inside a broad explanation query"),
"result: {result}"
);
}
#[tokio::test]
async fn test_ask_keeps_broad_explore_for_generic_type_query_without_trait_candidate() {
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let content = b"trait Actor {}\nstruct BusActor;\nimpl Actor for BusActor {}\n";
std::fs::write(src_dir.join("actors.rs"), content).unwrap();
let result = crate::parsing::process_file("src/actors.rs", content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
let server = make_server_with_root(
make_live_index_ready(vec![("src/actors.rs".to_string(), indexed)]),
Some(dir.path().to_path_buf()),
);
let input = super::SmartQueryInput {
project: None,
query: "what are the main types?".to_string(),
max_tokens: None,
};
let result = server.ask(Parameters(input)).await;
assert!(result.contains("Chosen tool: explore"), "result: {result}");
assert!(
!result.contains("Chosen tool: find_references"),
"generic type phrasing should stay broad without a distinctive trait candidate: {result}"
);
}
#[tokio::test]
async fn test_ask_preserves_path_scope_hint_for_caller_query() {
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let content = b"fn helper() {}\nfn caller() { helper(); }\n";
std::fs::write(src_dir.join("lib.rs"), content).unwrap();
let result = crate::parsing::process_file("src/lib.rs", content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
let server = make_server_with_root(
make_live_index_ready(vec![("src/lib.rs".to_string(), indexed)]),
Some(dir.path().to_path_buf()),
);
let input = super::SmartQueryInput {
project: None,
query: "who calls helper in src/lib.rs".to_string(),
max_tokens: None,
};
let result = server.ask(Parameters(input)).await;
assert!(
result.contains("Invocation: find_references(name=\"helper\", path=\"src/lib.rs\")"),
"result: {result}"
);
assert!(result.contains("src/lib.rs"), "result: {result}");
assert!(result.contains("caller"), "result: {result}");
}
#[tokio::test]
async fn test_edit_plan_accepts_path_qualified_symbol_target() {
let dir = tempfile::tempdir().unwrap();
let src_dir = dir.path().join("src");
std::fs::create_dir_all(&src_dir).unwrap();
let content = b"fn helper() {}\n";
std::fs::write(src_dir.join("lib.rs"), content).unwrap();
let result = crate::parsing::process_file("src/lib.rs", content, LanguageId::Rust);
let indexed =
crate::live_index::store::IndexedFile::from_parse_result(result, content.to_vec());
let server = make_server_with_root(
make_live_index_ready(vec![("src/lib.rs".to_string(), indexed)]),
Some(dir.path().to_path_buf()),
);
let input = super::EditPlanInput {
project: None,
target: "src/lib.rs::helper".to_string(),
};
let result = server.edit_plan(Parameters(input)).await;
assert!(
result.contains("Found 1 symbol(s) matching"),
"result: {result}"
);
assert!(result.contains("src/lib.rs"), "result: {result}");
assert!(result.contains("helper"), "result: {result}");
assert!(!result.contains("not found"), "result: {result}");
}
#[test]
fn test_filter_paths_code_only() {
let paths = vec![
"src/main.rs".to_string(),
"README.md".to_string(),
"Cargo.toml".to_string(),
"src/lib.rs".to_string(),
".github/workflows/ci.yml".to_string(),
"package.json".to_string(),
];
let result = super::filter_paths_by_prefix_and_language(paths, None, None, true).unwrap();
assert_eq!(result, vec!["src/main.rs", "src/lib.rs"]);
}
#[test]
fn test_parse_language_filter_frontend_and_data_languages() {
use super::parse_language_filter;
use crate::domain::index::LanguageId;
// Frontend languages previously missing from the filter
assert_eq!(
parse_language_filter(Some("html")),
Ok(Some(LanguageId::Html))
);
assert_eq!(
parse_language_filter(Some("HTML")),
Ok(Some(LanguageId::Html))
);
assert_eq!(
parse_language_filter(Some("css")),
Ok(Some(LanguageId::Css))
);
assert_eq!(
parse_language_filter(Some("CSS")),
Ok(Some(LanguageId::Css))
);
assert_eq!(
parse_language_filter(Some("scss")),
Ok(Some(LanguageId::Scss))
);
assert_eq!(
parse_language_filter(Some("SCSS")),
Ok(Some(LanguageId::Scss))
);
// Data / config languages previously missing
assert_eq!(
parse_language_filter(Some("json")),
Ok(Some(LanguageId::Json))
);
assert_eq!(
parse_language_filter(Some("JSON")),
Ok(Some(LanguageId::Json))
);
assert_eq!(
parse_language_filter(Some("toml")),
Ok(Some(LanguageId::Toml))
);
assert_eq!(
parse_language_filter(Some("TOML")),
Ok(Some(LanguageId::Toml))
);
assert_eq!(
parse_language_filter(Some("yaml")),
Ok(Some(LanguageId::Yaml))
);
assert_eq!(
parse_language_filter(Some("YAML")),
Ok(Some(LanguageId::Yaml))
);
assert_eq!(
parse_language_filter(Some("markdown")),
Ok(Some(LanguageId::Markdown))
);
assert_eq!(
parse_language_filter(Some("md")),
Ok(Some(LanguageId::Markdown))
);
assert_eq!(
parse_language_filter(Some("env")),
Ok(Some(LanguageId::Env))
);
// Existing languages still work
assert_eq!(
parse_language_filter(Some("Rust")),
Ok(Some(LanguageId::Rust))
);
assert_eq!(
parse_language_filter(Some("TypeScript")),
Ok(Some(LanguageId::TypeScript))
);
// Empty / None returns Ok(None)
assert_eq!(parse_language_filter(None), Ok(None));
assert_eq!(parse_language_filter(Some("")), Ok(None));
// Unknown language returns an error
assert!(parse_language_filter(Some("COBOL")).is_err());
}
#[test]
fn test_normalize_search_text_glob() {
use super::normalize_search_text_glob;
// Bare filename → auto-prefix with **/
assert_eq!(
normalize_search_text_glob(Some("foo.rs")),
Some("**/foo.rs".to_string())
);
// Path with separator → no prefix
assert_eq!(
normalize_search_text_glob(Some("src/foo.rs")),
Some("src/foo.rs".to_string())
);
// Already has glob char → no prefix
assert_eq!(
normalize_search_text_glob(Some("*.rs")),
Some("*.rs".to_string())
);
assert_eq!(
normalize_search_text_glob(Some("[test]*.rs")),
Some("[test]*.rs".to_string())
);
assert_eq!(
normalize_search_text_glob(Some("src/**/*.ts")),
Some("src/**/*.ts".to_string())
);
// Leading ./ stripped, then bare → auto-prefix
assert_eq!(
normalize_search_text_glob(Some("./foo.rs")),
Some("**/foo.rs".to_string())
);
// Backslash replaced, leading / stripped, then bare → auto-prefix
assert_eq!(
normalize_search_text_glob(Some("\\foo.rs")),
Some("**/foo.rs".to_string())
);
// Empty / whitespace → None
assert_eq!(normalize_search_text_glob(Some("")), None);
assert_eq!(normalize_search_text_glob(Some(" ")), None);
assert_eq!(normalize_search_text_glob(None), None);
}
#[test]
fn test_lenient_option_vec_native_array() {
use serde::Deserialize;
#[derive(Deserialize)]
struct T {
#[serde(default, deserialize_with = "super::lenient_option_vec")]
items: Option<Vec<String>>,
}
let t: T = serde_json::from_str(r#"{"items": ["a", "b"]}"#).unwrap();
assert_eq!(t.items, Some(vec!["a".to_string(), "b".to_string()]));
}
#[test]
fn test_lenient_option_vec_stringified_array() {
use serde::Deserialize;
#[derive(Deserialize)]
struct T {
#[serde(default, deserialize_with = "super::lenient_option_vec")]
items: Option<Vec<String>>,
}
let t: T = serde_json::from_str(r#"{"items": "[\"a\", \"b\"]"}"#).unwrap();
assert_eq!(t.items, Some(vec!["a".to_string(), "b".to_string()]));
}
#[test]
fn test_lenient_option_vec_null() {
use serde::Deserialize;
#[derive(Deserialize)]
struct T {
#[serde(default, deserialize_with = "super::lenient_option_vec")]
items: Option<Vec<String>>,
}
let t: T = serde_json::from_str(r#"{"items": null}"#).unwrap();
assert_eq!(t.items, None);
}
#[test]
fn test_lenient_option_vec_empty_string() {
use serde::Deserialize;
#[derive(Deserialize)]
struct T {
#[serde(default, deserialize_with = "super::lenient_option_vec")]
items: Option<Vec<String>>,
}
let t: T = serde_json::from_str(r#"{"items": ""}"#).unwrap();
assert_eq!(t.items, None);
}
#[test]
fn test_lenient_vec_required_native() {
use serde::Deserialize;
#[derive(Deserialize)]
struct T {
#[serde(deserialize_with = "super::lenient_vec_required")]
items: Vec<String>,
}
let t: T = serde_json::from_str(r#"{"items": ["x"]}"#).unwrap();
assert_eq!(t.items, vec!["x".to_string()]);
}
#[test]
fn test_lenient_vec_required_stringified() {
use serde::Deserialize;
#[derive(Deserialize)]
struct T {
#[serde(deserialize_with = "super::lenient_vec_required")]
items: Vec<String>,
}
let t: T = serde_json::from_str(r#"{"items": "[\"x\"]"}"#).unwrap();
assert_eq!(t.items, vec!["x".to_string()]);
}
#[test]
fn test_diff_symbols_compact_shows_omission_note() {
let dir = init_git_repo();
let a_path = dir.path().join("a.rs");
let b_path = dir.path().join("b.rs");
std::fs::write(&a_path, "fn old_func() {}\n").unwrap();
std::fs::write(&b_path, "// comment\n").unwrap();
run_git(dir.path(), &["add", "."]);
run_git(dir.path(), &["commit", "-m", "base"]);
std::fs::write(&a_path, "fn old_func() {}\nfn new_func() {}\n").unwrap();
std::fs::write(&b_path, "// changed comment\n").unwrap();
run_git(dir.path(), &["add", "."]);
run_git(dir.path(), &["commit", "-m", "changes"]);
let repo = crate::git::GitRepo::open(dir.path()).expect("open git repo");
// Ref-to-ref mode never reads the working tree, so the index is not
// consulted; an empty one keeps this test about the omission note.
let live = make_live_index_ready(vec![]);
let result = super::format::diff_symbols_result_view(
"HEAD~1",
"HEAD",
&["a.rs", "b.rs"],
&repo,
&live,
true,
false,
);
assert!(
result.contains("1 file(s) with only non-symbol changes omitted"),
"compact mode should note omitted files: {result}"
);
}
#[tokio::test]
async fn test_diff_symbols_reports_trust_envelope() {
let repo = init_git_repo();
let file_path = repo.path().join("src/lib.rs");
std::fs::create_dir_all(repo.path().join("src")).unwrap();
std::fs::write(&file_path, "fn old_func() {}\n").unwrap();
run_git(repo.path(), &["add", "."]);
run_git(repo.path(), &["commit", "-m", "base"]);
std::fs::write(&file_path, "fn old_func() {}\nfn new_func() {}\n").unwrap();
run_git(repo.path(), &["add", "."]);
run_git(repo.path(), &["commit", "-m", "changes"]);
let server = make_server_with_root(
make_live_index_ready(vec![]),
Some(repo.path().to_path_buf()),
);
let result = server
.diff_symbols(Parameters(super::DiffSymbolsInput {
project: None,
base: Some("HEAD~1".to_string()),
target: Some("HEAD".to_string()),
path_prefix: None,
language: None,
code_only: None,
compact: Some(true),
summary_only: None,
estimate: None,
max_tokens: None,
}))
.await;
assert!(
result.contains("Match type: exact (git ref diff)"),
"diff_symbols should report match type: {result}"
);
assert!(
result.contains("Source authority: git ref diff"),
"diff_symbols should report git authority: {result}"
);
assert!(
result.contains("Parse state: high (tree-sitter AST extraction for supported languages, regex fallback for others)"),
"diff_symbols should report AST parse state: {result}"
);
assert!(
result.contains("Scope: git diff `HEAD~1`...`HEAD`; compact output"),
"diff_symbols should report scope: {result}"
);
}
// Frecency bump/no-bump wiring is verified end-to-end against a real
// `FrecencyStore` on a tempdir in `tests/frecency_ranking.rs`. That suite
// is the canonical home for those assertions.
// -----------------------------------------------------------------------
// TR-06 / FR-009 / FR-010 — if_match guarded apply rejects a concurrent
// on-disk change (T022). Lives here as a crate unit test because the
// deterministic interleave hook (`edit::install_write_interleave_hook`) is
// `#[cfg(test)] pub(crate)` and is unreachable from an integration test.
// -----------------------------------------------------------------------
/// What this test injects and proves (honest scope):
///
/// - INJECTS: a `#[cfg(test)]` interleave hook installed at the guarded
/// write site (`edit::guarded_atomic_write_file`). The hook fires once,
/// strictly BEFORE the write-time on-disk re-read, and overwrites the
/// target file with a third, divergent body — simulating a concurrent
/// writer landing inside the previously-unguarded TOCTOU window. No
/// sleeps, no extra threads: the interleave is deterministic.
/// - PROVES: with `if_match` set to the body the agent last saw, the
/// apply is REJECTED (no write), the on-disk content is the concurrent
/// change (NOT the agent's stale edit), and the response does NOT claim
/// a successful guarded apply (outcome != Found; no committed write
/// semantics; ledger `legacy_executed=false` via the failed write mode).
/// - DOES NOT PROVE: atomicity against a *truly external* OS process. The
/// hook stands in for a concurrent writer that lands between the re-read
/// and the rename only because we control the exact interleave point;
/// the production guard re-reads disk microseconds before the rename
/// with no `.await` between, which closes the wide pre-flight→write
/// window but is not an OS file lock (see `guarded_atomic_write_file`).
#[tokio::test]
async fn symforge_edit_if_match_rejected_after_concurrent_disk_change() {
use crate::stel::StelEditRequest;
let original = "fn target() { old }\n";
let (dir, server) = setup_loaded_edit_test(&[("src/lib.rs", original)]);
let file_path = dir.path().join("src/lib.rs");
let _surface = EnvVarGuard::set("SYMFORGE_SURFACE", "compact");
// The live trust envelope is COMPACT by default (no `ledger:` line); this
// test legitimately needs the FULL block to parse the ledger metadata and
// assert `!legacy_executed`, so force full for its duration. The lib test
// suite runs `--test-threads=1` and `EnvVarGuard` restores on drop.
let _full = EnvVarGuard::set("SYMFORGE_STEL_FULL", "1");
// A concurrent writer lands inside the guarded window: overwrite the
// file with a third, divergent body. Captured path keeps the closure
// `'static`. The guard drops at end of scope, uninstalling the hook.
let concurrent_body = "fn target() { concurrent_change }\n";
let race_path = file_path.clone();
let _hook = crate::protocol::edit::install_write_interleave_hook(move || {
std::fs::write(&race_path, concurrent_body)
.expect("concurrent writer should overwrite target");
});
let request = StelEditRequest {
path: "src/lib.rs".to_string(),
symbol: Some("target".to_string()),
// if_match is the body the agent last saw (the original) — it
// matched at pre-flight, then the on-disk body diverged.
if_match: Some(original.trim().to_string()),
body: Some("fn target() { agent_edit }".to_string()),
apply: Some(true),
..Default::default()
};
let result = server
.symforge_edit_facade_tool(Parameters(request))
.await
.expect("symforge_edit dispatch");
let serialized = serde_json::to_value(&result).expect("serialize CallToolResult");
let output = tool_result_text(&serialized);
// Rejected: failed write mode, never a successful guarded apply.
assert!(
output.contains("guarded apply rejected"),
"expected guarded-apply rejection:\n{output}"
);
assert!(
!output.contains("Write semantics: atomic write + reindex"),
"rejected apply must NOT report a committed write:\n{output}"
);
// FR-010: outcome must not be Found (no false success).
assert_ne!(
serialized["_meta"][RESULT_STATUS_META_KEY]["outcome_class"],
serde_json::json!(OutcomeClass::Found.as_str()),
"rejected guarded apply must not classify as Found:\n{output}"
);
// Ledger must not record a committed write.
let ledger_line = output
.lines()
.find(|line| line.starts_with("ledger: "))
.expect("ledger line present");
let ledger: crate::stel::LedgerEnvelopeMeta =
serde_json::from_str(ledger_line.trim_start_matches("ledger: ")).expect("ledger json");
assert!(
!ledger.legacy_executed,
"rejected guarded apply must not record legacy_executed:\n{output}"
);
// US3 AC-1: the divergent on-disk content is left intact — the
// concurrent change survives, the agent's stale edit never landed.
let on_disk = std::fs::read_to_string(&file_path).expect("read file after reject");
assert_eq!(
on_disk, concurrent_body,
"the concurrent change must be preserved (no silent clobber)"
);
assert!(
!on_disk.contains("agent_edit"),
"the agent's stale edit must NOT have been written:\n{on_disk}"
);
}
/// Negative control for T022: the identical guarded-apply flow with NO
/// concurrent change succeeds and the result matches the requested edit.
#[tokio::test]
async fn symforge_edit_if_match_succeeds_without_concurrent_change() {
use crate::stel::StelEditRequest;
let original = "fn target() { old }\n";
let (dir, server) = setup_loaded_edit_test(&[("src/lib.rs", original)]);
let file_path = dir.path().join("src/lib.rs");
let _surface = EnvVarGuard::set("SYMFORGE_SURFACE", "compact");
// No interleave hook installed: the on-disk body never diverges.
let request = StelEditRequest {
path: "src/lib.rs".to_string(),
symbol: Some("target".to_string()),
if_match: Some(original.trim().to_string()),
body: Some("fn target() { agent_edit }".to_string()),
apply: Some(true),
..Default::default()
};
let result = server
.symforge_edit_facade_tool(Parameters(request))
.await
.expect("symforge_edit dispatch");
let serialized = serde_json::to_value(&result).expect("serialize CallToolResult");
let output = tool_result_text(&serialized);
assert!(
output.contains("Write semantics: atomic write + reindex"),
"negative control must commit the write:\n{output}"
);
assert!(
!output.contains("guarded apply rejected"),
"negative control must not be rejected:\n{output}"
);
let on_disk = std::fs::read_to_string(&file_path).expect("read file after apply");
assert!(
on_disk.contains("agent_edit"),
"negative control must apply the requested edit:\n{on_disk}"
);
assert!(
!on_disk.contains("old"),
"negative control must replace the old body:\n{on_disk}"
);
}
/// US4 (019): an identical idempotent `symforge_edit` apply replay — same
/// `idempotency_key`, same request INCLUDING the original `if_match` — must
/// return the STORED result and write ZERO bytes, NOT be rejected by the now
/// stale `if_match` guard.
///
/// Before this fix, the local-apply branch ran `run_pre_apply_gates`' Replace
/// `if_match` guard BEFORE any replay lookup. After the first apply the body
/// changed, so the original `if_match` no longer matched the current body and
/// the replay was wrongly rejected with "if_match does not match current
/// symbol body". A non-reserving replay probe now short-circuits the identical
/// key+request replay before that guard.
#[tokio::test]
async fn symforge_edit_idempotent_replay_short_circuits_stale_if_match() {
use crate::stel::StelEditRequest;
let original = "fn target() { old }\n";
let (dir, server) = setup_loaded_edit_test(&[("src/lib.rs", original)]);
let file_path = dir.path().join("src/lib.rs");
let _surface = EnvVarGuard::set("SYMFORGE_SURFACE", "compact");
let request = StelEditRequest {
path: "src/lib.rs".to_string(),
symbol: Some("target".to_string()),
if_match: Some(original.trim().to_string()),
body: Some("fn target() { agent_edit }".to_string()),
apply: Some(true),
idempotency_key: Some("replay-key-1".to_string()),
..Default::default()
};
// First apply: commits the write.
let first = server
.symforge_edit_facade_tool(Parameters(request.clone()))
.await
.expect("first symforge_edit dispatch");
let first_serialized = serde_json::to_value(&first).expect("serialize first");
let first_text = tool_result_text(&first_serialized);
assert!(
first_text.contains("Write semantics: atomic write + reindex"),
"first apply must commit the write:\n{first_text}"
);
let after_first = std::fs::read_to_string(&file_path).expect("read after first apply");
assert!(
after_first.contains("agent_edit"),
"first apply must land the edit:\n{after_first}"
);
// Replay: IDENTICAL request (same key, same if_match, same body). The
// body on disk has changed, so the original if_match no longer matches
// the current body — yet the replay must succeed by returning the stored
// result, writing ZERO new bytes.
let replay = server
.symforge_edit_facade_tool(Parameters(request.clone()))
.await
.expect("replay symforge_edit dispatch");
let replay_serialized = serde_json::to_value(&replay).expect("serialize replay");
let replay_text = tool_result_text(&replay_serialized);
assert!(
!replay_text.contains("if_match does not match current symbol body"),
"idempotent replay must NOT be rejected by the stale if_match guard:\n{replay_text}"
);
assert_ne!(
replay_serialized["_meta"][RESULT_STATUS_META_KEY]["outcome_class"],
serde_json::json!(OutcomeClass::InvalidRequest.as_str()),
"idempotent replay must not classify as an invalid request:\n{replay_text}"
);
// ZERO new bytes: the on-disk content is byte-identical after the replay.
let after_replay = std::fs::read_to_string(&file_path).expect("read after replay");
assert_eq!(
after_first, after_replay,
"idempotent replay must write zero bytes (byte-identical file)"
);
}
/// US4 (019): a replay carrying the SAME `idempotency_key` but a CHANGED
/// request (different body) must be an idempotency conflict, NOT a silent
/// replay of the stored result. The non-reserving probe must surface the
/// store's `Conflict` rather than swallowing it.
#[tokio::test]
async fn symforge_edit_same_key_changed_request_is_conflict_not_replay() {
use crate::stel::StelEditRequest;
let original = "fn target() { old }\n";
let (_dir, server) = setup_loaded_edit_test(&[("src/lib.rs", original)]);
let _surface = EnvVarGuard::set("SYMFORGE_SURFACE", "compact");
let first = StelEditRequest {
path: "src/lib.rs".to_string(),
symbol: Some("target".to_string()),
if_match: Some(original.trim().to_string()),
body: Some("fn target() { agent_edit }".to_string()),
apply: Some(true),
idempotency_key: Some("conflict-key-1".to_string()),
..Default::default()
};
server
.symforge_edit_facade_tool(Parameters(first))
.await
.expect("first apply");
// Same key, DIFFERENT body → the request hash differs.
let changed = StelEditRequest {
path: "src/lib.rs".to_string(),
symbol: Some("target".to_string()),
if_match: Some(original.trim().to_string()),
body: Some("fn target() { different_edit }".to_string()),
apply: Some(true),
idempotency_key: Some("conflict-key-1".to_string()),
..Default::default()
};
let result = server
.symforge_edit_facade_tool(Parameters(changed))
.await
.expect("conflict dispatch");
let conflict_serialized = serde_json::to_value(&result).expect("serialize conflict");
let output = tool_result_text(&conflict_serialized);
assert!(
output.contains("Idempotency conflict"),
"same key + changed request must be a conflict, not a silent replay:\n{output}"
);
}
/// US4 (019) MUST-NOT-REGRESS: a NEW idempotency key whose `if_match` does
/// not match the current body has no stored result, so the probe returns
/// `None` and the genuine optimistic-concurrency guard still rejects it.
#[tokio::test]
async fn symforge_edit_new_key_stale_if_match_still_rejected() {
use crate::stel::StelEditRequest;
let original = "fn target() { old }\n";
let (_dir, server) = setup_loaded_edit_test(&[("src/lib.rs", original)]);
let _surface = EnvVarGuard::set("SYMFORGE_SURFACE", "compact");
let request = StelEditRequest {
path: "src/lib.rs".to_string(),
symbol: Some("target".to_string()),
// if_match does NOT match the current body.
if_match: Some("fn target() { wrong }".to_string()),
body: Some("fn target() { agent_edit }".to_string()),
apply: Some(true),
idempotency_key: Some("fresh-key-1".to_string()),
..Default::default()
};
let result = server
.symforge_edit_facade_tool(Parameters(request))
.await
.expect("stale if_match dispatch");
let serialized = serde_json::to_value(&result).expect("serialize");
let output = tool_result_text(&serialized);
assert!(
output.contains("if_match does not match current symbol body"),
"a new key with stale if_match must still be rejected by the concurrency guard:\n{output}"
);
assert_eq!(
serialized["_meta"][RESULT_STATUS_META_KEY]["outcome_class"],
serde_json::json!(OutcomeClass::InvalidRequest.as_str()),
"stale-if_match rejection must classify as an invalid request:\n{output}"
);
}
// ── Feature 012 hardening — `symforge` facade REFUSES cross-project targeting ─
//
// `StelRequest` carries `project`/`projects` for schema parity, but the L1
// planner plans single-project reads, so set-valued `projects` is refused
// honestly (routing it would silently single-project-resolve, Principle VII)
// while a single `project` IS routed into every planned step (Task 4 Step 5).
#[tokio::test]
async fn symforge_facade_routes_project_and_refuses_projects() {
use crate::stel::{StelRequest, SymforgeCallInput};
let sym = make_symbol("thing", SymbolKind::Function, 1, 1);
let content = medium_test_source("pub fn thing() {}");
let (key, file) = make_file("src/lib.rs", &content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let _surface = EnvVarGuard::set("SYMFORGE_SURFACE", "compact");
// `projects: ["*"]` -> refused (not silently single-project resolved).
let projects_call = SymforgeCallInput {
request: StelRequest {
query: "where is thing defined".to_string(),
projects: Some(vec!["*".to_string()]),
..Default::default()
},
..Default::default()
};
let result = server
.symforge_facade_tool(Parameters(projects_call))
.await
.expect("facade dispatch");
let serialized = serde_json::to_value(&result).expect("serialize CallToolResult");
assert_tool_result_status(&serialized, OutcomeClass::InvalidRequest);
let text = tool_result_text(&serialized);
assert!(
text.contains("cross-project targeting is not routed through the `symforge` facade")
&& text.contains("search_symbols")
&& text.contains("find_references"),
"refusal must name the direct-tool vehicle: {text}"
);
// Task 4 Step 5: a single `project` is ROUTED into the planned steps,
// not refused with the cross-project message. On this no-daemon
// single-project server a FOREIGN selector is refused by the
// `foreign_project_refusal` guard naming the bound project (the same
// message the primitives emit per-step when a daemon IS present) —
// never the facade-level cross-project refusal, and never a
// silently-ignored selector.
let project_call = SymforgeCallInput {
request: StelRequest {
query: "where is thing defined".to_string(),
project: Some("proj-x".to_string()),
..Default::default()
},
..Default::default()
};
let result = server
.symforge_facade_tool(Parameters(project_call))
.await
.expect("facade dispatch");
let serialized = serde_json::to_value(&result).expect("serialize CallToolResult");
let text = tool_result_text(&serialized);
assert!(
!text.contains("cross-project targeting is not routed through the `symforge` facade"),
"a single `project` must be routed, not facade-refused: {text}"
);
assert!(
text.contains("not available on this connection"),
"a foreign selector must surface the primitives' own refusal: {text}"
);
// A blank `project` is treated as not-set: the facade must NOT refuse on it
// (it would target the active project anyway). It proceeds past the
// cross-project guard (whatever the downstream outcome, it is NOT the
// cross-project refusal message).
let blank_call = SymforgeCallInput {
request: StelRequest {
query: "where is thing defined".to_string(),
project: Some(" ".to_string()),
..Default::default()
},
..Default::default()
};
let result = server
.symforge_facade_tool(Parameters(blank_call))
.await
.expect("facade dispatch");
let serialized = serde_json::to_value(&result).expect("serialize CallToolResult");
let text = tool_result_text(&serialized);
assert!(
!text.contains("cross-project targeting is not routed"),
"a blank `project` must not trip the cross-project refusal: {text}"
);
// The `foreign_project_refusal` guard short-circuits BEFORE the serve
// loop, which made the FOREIGN case above vacuous as coverage of the
// routing machinery: it never reaches the all-or-nothing routing check
// or the per-step `project` injection those lines exist for. A selector
// that RESOLVES TO THE BOUND project passes
// `selector_matches_bound_project`, so it passes the guard and does.
//
// Honest about what each half pins. Injecting the BOUND project name is
// semantically transparent — the primitives answer identically with or
// without it — so this first case pins that the serve loop is REACHED
// and serves, not the injected value. Deleting the injection block alone
// would not fail it.
let bound_call = SymforgeCallInput {
request: StelRequest {
query: "where is thing defined".to_string(),
project: Some("test_project".to_string()),
..Default::default()
},
..Default::default()
};
let result = server
.symforge_facade_tool(Parameters(bound_call))
.await
.expect("facade dispatch");
let serialized = serde_json::to_value(&result).expect("serialize CallToolResult");
let text = tool_result_text(&serialized);
assert!(
!text.contains("not available on this connection")
&& !text.contains("cannot be routed through this plan"),
"a selector resolving to the BOUND project must be served, not refused: {text}"
);
assert!(
text.contains("thing"),
"the bound-project call must reach the serve loop and answer: {text}"
);
// The all-or-nothing routing check IS pinned: the impact intent plans the
// git-scoped `detect_impact`, which has no `project` input at all, so
// routing a selector into that plan would MIX projects. Refuse the whole
// call. Deleting that block fails this assertion.
let unroutable_call = SymforgeCallInput {
request: StelRequest {
query: "blast radius of the recent changes".to_string(),
intent: Some(crate::stel::IntentBucket::Impact),
project: Some("test_project".to_string()),
..Default::default()
},
..Default::default()
};
let result = server
.symforge_facade_tool(Parameters(unroutable_call))
.await
.expect("facade dispatch");
let serialized = serde_json::to_value(&result).expect("serialize CallToolResult");
assert_tool_result_status(&serialized, OutcomeClass::InvalidRequest);
let text = tool_result_text(&serialized);
assert!(
text.contains("cannot be routed through this plan") && text.contains("detect_impact"),
"an unroutable planned step must refuse the whole call, naming the step: {text}"
);
}
/// The retrieve facade's foreign-project guard must fire BEFORE the early
/// returns that skip the serve loop's per-step `project` injection. Before
/// the fix, `preview: true` with a foreign selector returned
/// `outcome_class=found` plus an estimate grounded in the BOUND project —
/// a dishonest success in exactly the shape the guard exists to prevent.
#[tokio::test]
async fn symforge_facade_refuses_foreign_project_before_preview_estimate() {
use crate::stel::{StelRequest, SymforgeCallInput};
let sym = make_symbol("thing", SymbolKind::Function, 1, 1);
let content = medium_test_source("pub fn thing() {}");
let (key, file) = make_file("src/lib.rs", &content, vec![sym]);
let server = make_server(make_live_index_ready(vec![(key, file)]));
let _surface = EnvVarGuard::set("SYMFORGE_SURFACE", "compact");
let preview_call = SymforgeCallInput {
request: StelRequest {
query: "where is thing defined".to_string(),
project: Some("totally-other-project".to_string()),
preview: Some(true),
..Default::default()
},
..Default::default()
};
let result = server
.symforge_facade_tool(Parameters(preview_call))
.await
.expect("facade dispatch");
let serialized = serde_json::to_value(&result).expect("serialize CallToolResult");
assert_tool_result_status(&serialized, OutcomeClass::InvalidRequest);
let text = tool_result_text(&serialized);
assert!(
text.contains("not available on this connection"),
"a foreign selector must refuse, not preview: {text}"
);
assert!(
!text.contains("predicted_net_vs_manual") && !text.contains("plan_id"),
"a refused call must not hand back a bound-project estimate: {text}"
);
}
#[tokio::test]
async fn compact_knowledge_no_match_and_ccr_round_trip_stay_on_the_facade() {
use crate::stel::StelRequest;
let dir = tempfile::tempdir().expect("knowledge facade tempdir");
let docs = dir.path().join("docs");
fs::create_dir_all(&docs).expect("knowledge facade docs");
for index in 0..16 {
fs::write(
docs.join(format!("checkpoint-{index:02}.md")),
format!(
"# Checkpoint {index}\n## Persistence policy\nCheckpoint policy evidence marker {index:02} is retained after publication.\n"
),
)
.expect("knowledge facade fixture");
}
let index = LiveIndex::load(dir.path()).expect("load knowledge facade fixture");
let server = SymForgeServer::new(
index,
"knowledge_facade_test".to_string(),
Arc::new(parking_lot::Mutex::new(
crate::watcher::WatcherInfo::default(),
)),
Some(dir.path().to_path_buf()),
None,
);
let no_match = server
.symforge_stel_handler(&StelRequest {
query: "search repository knowledge for orbital zebra lattice".to_string(),
..Default::default()
})
.await
.expect("compact knowledge no-match");
let no_match_json =
serde_json::to_value(&no_match).expect("serialize compact knowledge no-match");
assert_tool_result_status(&no_match_json, OutcomeClass::EmptyResult);
assert_ne!(
no_match_json.get("isError"),
Some(&serde_json::Value::Bool(true)),
"a typed knowledge no-match must remain a successful MCP result"
);
let no_match_text = tool_result_text(&no_match_json);
assert!(
no_match_text.contains("Chosen tool: search_knowledge")
&& no_match_text.contains("no_evidence_complete"),
"the facade must preserve the direct no-match shape: {no_match_text}"
);
let truncated = server
.symforge_stel_handler(&StelRequest {
query: "search repository knowledge for checkpoint policy".to_string(),
max_tokens: Some(64),
..Default::default()
})
.await
.expect("compact knowledge CCR result");
let truncated_json =
serde_json::to_value(&truncated).expect("serialize compact knowledge CCR result");
let truncated_text = tool_result_text(&truncated_json);
assert!(
truncated_text.contains("retrieve: symforge with query=\"retrieve CCR hash ")
&& !truncated_text.contains("retrieve: symforge_retrieve"),
"compact CCR must advertise only its facade redemption route: {truncated_text}"
);
let handle = truncated_text
.split("retrieve CCR hash ")
.nth(1)
.and_then(|tail| tail.get(..12))
.expect("compact facade CCR handle");
assert!(handle.chars().all(|ch| ch.is_ascii_hexdigit()));
let redeemed = server
.symforge_stel_handler(&StelRequest {
query: format!("retrieve CCR hash {handle}"),
..Default::default()
})
.await
.expect("redeem compact knowledge CCR through facade");
let redeemed_json =
serde_json::to_value(&redeemed).expect("serialize redeemed compact CCR result");
let redeemed_text = tool_result_text(&redeemed_json);
assert!(
redeemed_text.contains("docs/checkpoint-09.md")
&& redeemed_text.contains("Checkpoint policy evidence marker 09"),
"facade CCR redemption must return the full safe stored result: {redeemed_text}"
);
}
// ── Raw-read admission gate ──────────────────────────────────────────────
//
// Public-behavior coverage for the raw-read lanes that reopen a repository
// file from disk. Fixtures come from the REAL admission pipeline
// (`LiveIndex::load`) — the only route that produces genuine `SensitivePath`
// / `SensitiveContent` dispositions. `manifest_metadata_entry` maps *from*
// `SkipReason` and structurally cannot express them, so it is the wrong axis
// for the security rows and is used only for the Tier-2 sweep rows.
/// Fixture values are assembled at runtime from non-secret fragments so no
/// credential-shaped literal is ever committed. Peer copies live in the
/// `live_index::store`, `knowledge`, `analytics::store`,
/// `live_index::persist` and `live_index::knowledge_bridge` tests.
fn runtime_canary() -> String {
["runtime", "-", "canary", "-", "segment"].concat()
}
const WITHHELD_REFUSAL_PREFIX: &str = "Content withheld by admission policy:";
/// Failure diagnostics for admission tests must not echo the response body:
/// on the pre-fix side that body IS the withheld file content. Report the
/// response SHAPE instead, never its bytes.
fn refusal_shape(text: &str) -> String {
let line = text.lines().next().unwrap_or("");
if line.starts_with(WITHHELD_REFUSAL_PREFIX) {
"withheld-refusal".to_string()
} else if line.starts_with("File not found:") {
"not-found".to_string()
} else if line.starts_with("Estimate for get_file_content") {
"estimate".to_string()
} else if line.starts_with("Syntax validation:") {
"syntax-report".to_string()
} else {
format!("<other, {} bytes, withheld>", text.len())
}
}
type ContentSelector = (&'static str, fn(&mut super::GetFileContentInput));
/// Every content selector `get_file_content` exposes. Shared by the refusal
/// sweep and by the R1/E1 estimate pairing so the two cannot drift.
const CONTENT_SELECTORS: &[ContentSelector] = &[
("full read", |_input| {}),
("start_line/end_line", |input| {
input.start_line = Some(1);
input.end_line = Some(1);
}),
("offset/limit", |input| {
input.offset = Some(0);
input.limit = Some(10);
}),
("around_line", |input| {
input.around_line = Some(1);
}),
("around_match present", |input| {
input.around_match = Some("password".to_string());
}),
("around_match absent", |input| {
// A "No matches for ..." answer is itself a content oracle, so the
// absent-needle case must refuse exactly like the present one.
input.around_match = Some("no-such-needle-marker".to_string());
}),
("around_symbol", |input| {
input.around_symbol = Some("password".to_string());
}),
("chunk_index + max_lines", |input| {
input.chunk_index = Some(1);
input.max_lines = Some(200);
}),
];
/// Repo whose dispositions are produced by the real admission pipeline: two
/// `SensitivePath` files, one `SensitiveContent` file, one admitted
/// non-indexed lockfile, and one ordinary Tier-1 source file. Returns the
/// runtime canary so every row can assert it never escapes.
fn setup_admission_fixture() -> (TempDir, SymForgeServer, String) {
let canary = runtime_canary();
let sensitive_body = format!("{}={canary}\n", kw_password());
let (dir, server) = setup_loaded_edit_test(&[
(".env", sensitive_body.as_str()),
("config/production.env", sensitive_body.as_str()),
("config/settings.toml", sensitive_body.as_str()),
(
"package-lock.json",
"{\n \"name\": \"demo\",\n \"lockfileVersion\": 3\n}\n",
),
("src/lib.rs", "pub fn admitted_anchor() {}\n"),
]);
(dir, server, canary)
}
/// RED (FU-1). The three working-tree disclosure lanes — the `search_text`
/// untracked sweep, `diff_symbols` in uncommitted mode, and `detect_impact`
/// seeding from `WORKTREE` — all read through one function. This pins that
/// seam directly: a security-demoted file is REFUSED, and an ordinary file
/// is still served, so the gate is not simply refusing everything.
#[tokio::test]
async fn worktree_text_is_refused_for_a_security_demoted_file() {
let canary = runtime_canary();
let dir = init_git_repo();
std::fs::write(
dir.path().join(".env"),
format!("{}={canary}\n", kw_password()),
)
.expect("write demoted fixture");
std::fs::write(dir.path().join("src.rs"), "pub fn anchor() {}\n")
.expect("write admitted fixture");
let shared = crate::live_index::LiveIndex::load(dir.path()).expect("load index");
let live = shared.read();
let repo = crate::git::GitRepo::open(dir.path()).expect("open git repo");
// Anti-vacuity: the fixture really is demoted, so the refusal below is
// the gate acting and not a file that was never indexed.
assert!(
live.get_file(".env").is_none(),
"control: .env must be absent from the Tier-1 map"
);
let refused = crate::protocol::read_gate::admit_worktree_text(&live, &repo, ".env")
.expect_err("a security-demoted file must be refused from the working tree");
assert!(
!refused.contains(canary.as_str()),
"the refusal must not echo the withheld content"
);
let admitted = crate::protocol::read_gate::admit_worktree_text(&live, &repo, "src.rs")
.expect("an ordinary file must still be readable")
.expect("ordinary file must decode");
assert!(
admitted.contains("anchor"),
"GREEN-CONTROL: the gate must not refuse everything"
);
}
/// GREEN-GUARD (FU-1). The structural half of the same property: no
/// protocol lane may reach the UNGATED working-tree read directly.
///
/// Behavioural tests only cover the three lanes that exist today; this
/// fails the moment a FOURTH one is written, which is how the original
/// three came to share an ungated read in the first place.
#[test]
fn no_protocol_lane_reads_the_working_tree_ungated() {
// Assembled at runtime so this scan does not match its OWN source, the
// way the repository-wide detector tripwire avoids the same trap.
let needle = [".file_from_", "workdir("].concat();
let protocol = Path::new(env!("CARGO_MANIFEST_DIR")).join("src/protocol");
let mut offenders: Vec<String> = Vec::new();
let mut scanned = 0usize;
for entry in fs::read_dir(&protocol).expect("read src/protocol") {
let path = entry.expect("dir entry").path();
if path.extension().and_then(|e| e.to_str()) != Some("rs") {
continue;
}
let text = fs::read_to_string(&path).expect("read protocol source");
scanned += 1;
for (number, line) in text.lines().enumerate() {
if line.contains(needle.as_str()) {
offenders.push(format!(
"{}:{}",
path.file_name().unwrap_or_default().to_string_lossy(),
number + 1
));
}
}
}
assert!(scanned > 0, "control: the scan must actually read sources");
assert!(
offenders.is_empty(),
"these protocol lanes bypass the working-tree gate: {offenders:?}"
);
}
/// Precondition: the path is ABSENT from the Tier-1 map and carries a typed
/// security disposition. Asserted first in every security row so a fixture
/// that silently stops being demoted fails loudly instead of passing
/// vacuously.
fn assert_security_demotion(server: &SymForgeServer, path: &str) {
let guard = server.index.read();
assert!(
guard.get_file(path).is_none(),
"{path} must be absent from the Tier-1 index map"
);
let entry = guard
.manifest_entries
.iter()
.find(|entry| entry.path.normalized_utf8.as_deref() == Some(path))
.unwrap_or_else(|| panic!("{path} must remain cataloged"));
assert!(
matches!(
entry.disposition,
crate::domain::FileDisposition::MetadataOnly {
reason: crate::domain::MetadataOnlyReason::SensitivePath { .. }
| crate::domain::MetadataOnlyReason::SensitiveContent { .. }
}
),
"{path} must carry a security disposition, got {:?}",
entry.disposition
);
}
async fn assert_content_refused(
server: &SymForgeServer,
canary: &str,
path: &str,
label: &str,
apply: fn(&mut super::GetFileContentInput),
) {
let mut input = get_file_content_input(path);
apply(&mut input);
let serialized =
serialized_tool_result(server.get_file_content_tool(Parameters(input)).await);
let text = tool_result_text(&serialized);
// Content first: once this holds the body carries no fixture material,
// so the remaining diagnostics may quote it.
assert!(
!text.contains(canary),
"{label} on {path} leaked fixture content; response shape: {}",
refusal_shape(text)
);
assert!(
text.starts_with(WITHHELD_REFUSAL_PREFIX),
"{label} on {path} must be refused by the admission gate; got: {text}"
);
assert_eq!(
serialized["_meta"][RESULT_STATUS_META_KEY]["outcome_class"],
serde_json::json!(OutcomeClass::InvalidRequest.as_str()),
"{label} on {path} must report an invalid-request outcome; got: {text}"
);
}
#[tokio::test]
async fn security_demoted_file_refuses_every_get_file_content_selector() {
let (_dir, server, canary) = setup_admission_fixture();
assert_security_demotion(&server, ".env");
assert_security_demotion(&server, "config/settings.toml");
for (label, apply) in CONTENT_SELECTORS {
assert_content_refused(&server, &canary, ".env", label, *apply).await;
}
// Content-detected demotion, not path-detected: the same refusal.
assert_content_refused(
&server,
&canary,
"config/settings.toml",
"full read (content-detected)",
|_input| {},
)
.await;
}
#[tokio::test]
async fn security_demoted_file_refuses_validate_file_syntax() {
let (_dir, server, canary) = setup_admission_fixture();
for path in ["config/settings.toml", "config/production.env"] {
assert_security_demotion(&server, path);
let text = server
.validate_file_syntax(Parameters(super::ValidateFileSyntaxInput {
project: None,
path: path.to_string(),
}))
.await;
assert!(
!text.contains(canary.as_str()),
"{path} syntax validation leaked fixture content; response shape: {}",
refusal_shape(&text)
);
assert!(
text.starts_with(WITHHELD_REFUSAL_PREFIX),
"{path} syntax validation must be refused by the admission gate; got: {text}"
);
assert!(
!text.contains("Symbols extracted:"),
"{path} must not report parsed structure; got: {text}"
);
}
}
#[tokio::test]
async fn estimate_succeeds_for_demoted_file_while_content_selectors_refuse() {
// R1/E1: Tier-2 aggregate counts are an explicit Feature 020 contract, so
// estimation must keep SUCCEEDING for a security-demoted file. The pairing
// pins the contract in both directions — over-gating the estimate is a
// regression, and letting any selector through is the breach.
let (_dir, server, canary) = setup_admission_fixture();
assert_security_demotion(&server, ".env");
let mut estimate_input = get_file_content_input(".env");
estimate_input.estimate = Some(true);
let estimated = server.get_file_content(Parameters(estimate_input)).await;
assert!(
!estimated.contains(canary.as_str()),
"estimate leaked fixture content; response shape: {}",
refusal_shape(&estimated)
);
assert!(
estimated.starts_with("Estimate for get_file_content(path=\".env\")"),
"estimation must still succeed for a demoted file; got: {estimated}"
);
assert!(
estimated.contains("raw disk read; not indexed"),
"estimate must keep the documented not-indexed aggregate; got: {estimated}"
);
// Selectors must not influence estimates.
let mut selected_estimate = get_file_content_input(".env");
selected_estimate.estimate = Some(true);
selected_estimate.start_line = Some(2);
selected_estimate.end_line = Some(2);
let selected = server.get_file_content(Parameters(selected_estimate)).await;
assert_eq!(
selected, estimated,
"a benign selector must not change the estimate; got: {selected}"
);
// …while every content selector on that same file refuses.
for (label, apply) in CONTENT_SELECTORS {
assert_content_refused(&server, &canary, ".env", label, *apply).await;
}
}
#[tokio::test]
async fn admitted_non_indexed_lockfile_still_serves_raw_disk_content() {
// The control that stops a refuse-everything gate from passing: a Tier-2
// lockfile is absent from the Tier-1 map, so it traverses the same
// raw-disk fallback and must be PERMITTED.
let (_dir, server, _canary) = setup_admission_fixture();
{
let guard = server.index.read();
assert!(
guard.get_file("package-lock.json").is_none(),
"the lockfile must be absent from the Tier-1 map so the fallback is exercised"
);
}
let result = server
.get_file_content(Parameters(get_file_content_input("package-lock.json")))
.await;
assert!(
result.contains("\"lockfileVersion\": 3"),
"an admitted non-indexed file must still be read; got: {result}"
);
assert!(
!result.starts_with(WITHHELD_REFUSAL_PREFIX),
"an admitted file must not be refused; got: {result}"
);
}
#[tokio::test]
async fn indexed_file_is_served_from_memory_without_reaching_the_gate() {
// D3 control: the exemption is about WHERE the bytes come from. Tier-1
// content is served out of the in-memory index and adds no read.
let (_dir, server, _canary) = setup_admission_fixture();
{
let guard = server.index.read();
assert!(
guard.get_file("src/lib.rs").is_some(),
"the anchor source file must be Tier-1 indexed"
);
}
let result = server
.get_file_content(Parameters(get_file_content_input("src/lib.rs")))
.await;
assert!(
result.contains("admitted_anchor"),
"indexed content must still be served from memory; got: {result}"
);
assert!(
!result.starts_with(WITHHELD_REFUSAL_PREFIX),
"an indexed read must not be refused; got: {result}"
);
}
#[tokio::test]
async fn tier2_sweep_withholds_file_whose_current_bytes_are_sensitive() {
// The manifest still records the file as merely oversized, but its
// CURRENT bytes carry a credential. Most-restrictive-wins (R2): the sweep
// must not disclose `contains(name)` against it.
let dir = tempfile::tempdir().unwrap();
let canary = runtime_canary();
let mut big = "x".repeat(1_100_000);
// Re-based off the bare keyword-equals line this fixture used to carry:
// on a CODE path that shape is now an exempted code expression, so the
// file would classify Clean and the rows below would prove nothing. A
// quoted opaque literal is the shape that stays demoted.
big.push_str(&format!(
"\nlet {} = \"{canary}\";\nlet r = PortRegistry::new();\n",
kw_password()
));
std::fs::write(dir.path().join("big.rs"), &big).unwrap();
// This test hand-builds its manifest (`SkipReason::SizeThreshold`), so
// `assert_security_demotion` does not apply. Assert the demotion directly:
// without this the re-base could silently move the vacuity instead of
// removing it — all three rows below pass on a file that is not sensitive.
assert!(
matches!(
crate::knowledge::classify_stable_content(
"big.rs",
crate::domain::IndexTargets::for_path(
"big.rs",
Some(&crate::domain::LanguageId::Rust),
),
big.as_bytes(),
),
crate::knowledge::StableContentAdmission::MetadataOnly(
crate::domain::MetadataOnlyReason::SensitiveContent { .. }
)
),
"big.rs must still be content-demoted on a CODE path, or the refusal rows below prove nothing"
);
let def = make_symbol("PortRegistry", SymbolKind::Struct, 1, 1);
let (key, file) = make_file("src/lib.rs", b"struct PortRegistry;\n", vec![def]);
let mut index = make_live_index_ready(vec![(key, file)]);
index.manifest_entries = vec![manifest_metadata_entry(
"big.rs",
big.len() as u64,
crate::domain::index::SkipReason::SizeThreshold,
)];
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let result = server
.find_references(Parameters(find_references_input("PortRegistry")))
.await;
assert!(
!result.contains(canary.as_str()),
"the sweep must not echo fixture content; response shape: {}",
refusal_shape(&result)
);
assert!(
!result.contains("appears textually in"),
"a file whose current bytes are sensitive must not have a textual match disclosed; got: {result}"
);
assert!(
result.contains("not reference-scanned and not swept"),
"the unswept clause must confess the file was not swept; got: {result}"
);
// The clause used to attribute every unswept file to "(budget)". A gate
// refusal now lands in the same bucket, so budget alone is a false
// cause — this file was refused by POLICY, with budget to spare.
assert!(
result.contains("(budget or policy)"),
"the unswept clause must not attribute a policy refusal to budget; got: {result}"
);
}
#[tokio::test]
async fn tier2_sweep_never_names_a_security_demoted_file() {
// GUARD, not proof of the fix (SF-DOG-004): exclusion must rest on
// explicit positive eligibility off the TYPED disposition, never on the
// `SkipReason` projection. It once rested on the projection by accident,
// back when that mislabelled every security demotion as
// `SkipReason::UnsupportedLanguage`; the label is now `PolicyWithheld`
// and this must still hold.
let dir = tempfile::tempdir().unwrap();
let canary = runtime_canary();
std::fs::create_dir_all(dir.path().join("config")).unwrap();
std::fs::write(
dir.path().join("config/secrets.env"),
format!("{}={canary}\nlet r = PortRegistry::new();\n", kw_password()),
)
.unwrap();
let def = make_symbol("PortRegistry", SymbolKind::Struct, 1, 1);
let (key, file) = make_file("src/lib.rs", b"struct PortRegistry;\n", vec![def]);
let mut index = make_live_index_ready(vec![(key, file)]);
index.manifest_entries = vec![crate::domain::CatalogEntry {
path: crate::domain::CatalogPath {
public_id: "config/secrets.env".to_string(),
normalized_utf8: Some("config/secrets.env".to_string()),
},
size: 64,
language: None,
classification: crate::domain::FileClassification {
class: crate::domain::FileClass::Text,
is_generated: false,
is_test: false,
is_vendor: false,
is_config: false,
},
disposition: crate::domain::FileDisposition::MetadataOnly {
reason: crate::domain::MetadataOnlyReason::SensitivePath {
rule_id: "path.environment-credentials".to_string(),
},
},
content_hash: None,
}];
let server = make_server_with_root(index, Some(dir.path().to_path_buf()));
let result = server
.find_references(Parameters(find_references_input("PortRegistry")))
.await;
assert!(
!result.contains(canary.as_str()),
"the sweep must not echo fixture content; response shape: {}",
refusal_shape(&result)
);
assert!(
!result.contains("config/secrets.env"),
"a security-demoted file must never be named by the sweep; got: {result}"
);
assert!(
!result.contains("Tier-2 exclusion"),
"no eligible Tier-2 candidate means no disclosure; got: {result}"
);
}
// ── Bidirectional oracle set (detector precision + fail-closed disclosure) ─
//
// Authored BEFORE the fix. Rows marked RED are expected to fail against the
// current code; rows marked GREEN pin behavior the fix must not move. Every
// payload is assembled at runtime from non-secret fragments, so no
// credential-shaped literal enters the repository, and no failure message
// ever echoes a fixture body — only row ids and response SHAPES.
/// Opaque, non-credential payload: 19 bytes, none of them whitespace, quote
/// or `#`, so it satisfies the detector's `{8,}` value class exactly the way
/// a real credential would, without being one.
fn oracle_opaque() -> String {
["oracle", "-", "opaque", "-", "value"].concat()
}
/// Non-secret ASCII marker embedded in undecodable fixtures so a disclosure
/// leak is provable without reproducing anything sensitive.
fn oracle_marker() -> String {
["oracle", "-", "undecodable", "-", "marker"].concat()
}
/// The public admission contract: the same call the cold index, the watcher
/// and the raw-read gate all consult.
fn oracle_admission(path: &str, body: &str) -> crate::knowledge::StableContentAdmission {
let language = LanguageId::from_path(path);
let targets = crate::domain::IndexTargets::for_path(path, language.as_ref());
crate::knowledge::classify_stable_content(path, targets, body.as_bytes())
}
fn oracle_is_demoted(path: &str, body: &str) -> bool {
matches!(
oracle_admission(path, body),
crate::knowledge::StableContentAdmission::MetadataOnly(
crate::domain::MetadataOnlyReason::SensitiveContent { .. }
)
)
}
/// Bytes the v1 searchable-text decoder rejects, wrapped around `marker`.
fn oracle_undecodable_bytes(marker: &str) -> Vec<u8> {
let mut bytes = vec![0xFF_u8, 0xFE];
bytes.extend_from_slice(marker.as_bytes());
bytes.extend_from_slice(&[0xFF_u8, 0xFE]);
bytes
}
// ── 7A. MUST BECOME CLEAN ────────────────────────────────────────────────
/// GREEN-CONTROL (C1–C7, C9, C11). Ordinary source expressions that satisfy
/// `KEY = VALUE` only because the value class accepts any 8+ non-space,
/// non-quote run. None of these can BE a credential: in code a credential is
/// a string LITERAL, and not one of these opens one. C1 is additionally the
/// interpolation carve-out's canary — it regresses to SENSITIVE the moment
/// that carve-out is missing or misplaced.
///
/// C9 and C11 are the two REMAINING accepted false negatives, asserted CLEAN
/// DELIBERATELY: a code comment carrying `k=v`, and a bare `k=v` line in a
/// code file. An accepted false negative that no test pins is an unstated
/// one. Both now hold for a NEW pair of reasons — even quote parity to the
/// line start, so neither is "inside a literal", AND the bounded balanced
/// walk fully consumes the expression at depth 0 without finding a fenced
/// payload. Neither survives on the old line-local shortcut.
///
/// CAVEAT on C9: quote parity is byte-wise, so a single apostrophe earlier on
/// the comment line flips it and the row goes SENSITIVE (fail-closed, but it
/// would move this row). Keep the fixture apostrophe-free.
///
/// C8 and C10 LEFT this set — see
/// `oracle_b_credentials_embedded_in_literals_must_stay_content_demoted`
/// (S12b) and `oracle_b_wrapped_and_unconsumed_expressions_must_stay_content_demoted`
/// (S10). C11 remains the tripwire proving the `big.rs` fixture in
/// `tier2_sweep_withholds_file_whose_current_bytes_are_sensitive` would go
/// vacuous on a bare `k=v` line.
#[test]
fn oracle_a_code_expression_shapes_must_not_be_content_demoted() {
let v = oracle_opaque();
let token_kw = kw_token();
let password_kw = kw_password();
let rows: Vec<(&str, &str, String)> = vec![
(
"C1 brace interpolation",
"src/probe.rs",
format!("let line = format!(\"{token_kw}={{canary}}\");\n"),
),
(
"C2 type expression",
"src/probe.rs",
format!("stop_{token_kw}: Option<Arc<AtomicBool>>,\n"),
),
(
"C3 associated call",
"src/probe.rs",
format!("let {token_kw} = PortRegistry::new();\n"),
),
(
"C4 method/chained call",
"src/probe.rs",
format!("let {token_kw} = self.inner.clone();\n"),
),
(
"C5 free function call",
"src/probe.rs",
format!("let {token_kw} = spawn_watcher(handle);\n"),
),
(
"C6 member chain, no call",
"src/probe.rs",
format!("let {token_kw} = config.stop_flag;\n"),
),
(
"C7 bare identifier",
"src/probe.rs",
format!("let {token_kw} = previous_value;\n"),
),
(
"C9 code comment (accepted FN)",
"src/probe.rs",
format!("// {password_kw}={v}\n"),
),
(
"C11 bare k=v line in a code file (accepted FN; big.rs tripwire)",
"big.rs",
format!("{password_kw}={v}\n"),
),
];
let still_demoted: Vec<&str> = rows
.iter()
.filter(|(_, path, body)| oracle_is_demoted(path, body))
.map(|(row, _, _)| *row)
.collect();
assert!(
still_demoted.is_empty(),
"these code-expression shapes are still content-demoted: {still_demoted:?}"
);
}
// ── 7B. MUST STAY SENSITIVE ──────────────────────────────────────────────
/// GREEN-GUARD (S1–S9). Credential-shaped assignments on CODE paths. S1–S4
/// survive because the value OPENS a quoted literal — step 1 of the stage-2
/// predicate, decided before either new check runs, which is what makes row
/// S1 immovable. S5–S9 survive because the bounded balanced walk still finds
/// a delimiter-fenced payload run in the right-hand-side expression. S7 is
/// the mandatory counter-oracle: a call expression wrapping a quoted opaque
/// literal must NOT be exempted, or the literal is never examined.
#[test]
fn oracle_b_credential_literal_shapes_stay_content_demoted_on_code_paths() {
let v = oracle_opaque();
let token_kw = kw_token();
let password_kw = kw_password();
let rows: Vec<(&str, &str, String)> = vec![
(
"S1 snake_case, double-quoted",
"src/probe.rs",
format!("let api_key = \"{v}\";\n"),
),
(
"S2 SCREAMING_SNAKE, double-quoted",
"src/probe.ts",
format!("const API_TOKEN = \"{v}\";\n"),
),
(
"S3 camelCase, double-quoted",
"src/probe.ts",
format!("const clientSecret = \"{v}\";\n"),
),
(
"S4 single-quoted",
"src/probe.ts",
format!("const token = '{v}';\n"),
),
(
"S5 template literal",
"src/probe.ts",
format!("const {password_kw} = `{v}`;\n"),
),
(
"S6 raw string literal",
"src/probe.go",
format!("password = `{v}`\n"),
),
(
"S7 COUNTER-ORACLE: call wrapping a quoted literal",
"src/probe.py",
format!("{token_kw} = get_secret(\"{v}\")\n"),
),
(
"S8 call with a quoted fallback",
"src/probe.rs",
format!("let {token_kw} = fetch().unwrap_or(\"{v}\");\n"),
),
(
"S9 accepted over-fire: quoted env-var name",
"src/probe.py",
format!(
"{} = os.environ[\"{}_NAME\"]\n",
kw_key(),
kw_key().to_ascii_uppercase()
),
),
];
let not_demoted: Vec<&str> = rows
.iter()
.filter(|(_, path, body)| !oracle_is_demoted(path, body))
.map(|(row, _, _)| *row)
.collect();
assert!(
not_demoted.is_empty(),
"these credential-shaped rows lost their demotion: {not_demoted:?}"
);
}
/// GREEN-GUARD (G1–G4, G9–G11). These rows assert STAY DEMOTED, and they now
/// hold only because of the `is_code_language` gate and the rule-id scoping
/// of the stage-2 exemption — a safety property that must hold for a NEW
/// reason, not a control proving we did not over-refuse. Config, data and
/// markup paths stay STRICT (`KEY=VALUE` is their native credential syntax),
/// and the other four detector rules keep firing on CODE paths, which is what
/// bounds the accepted false negatives in 7A.
#[test]
fn oracle_b_non_code_paths_and_sibling_rules_stay_strict() {
let v = oracle_opaque();
let envelope = ["-----BEGIN RSA ", "PRIVATE KEY", "-----"].concat();
let rows: Vec<(&str, &str, String)> = vec![
("G1 dotenv", ".env", format!("API_KEY={v}\n")),
("G2 yaml", "config/app.yaml", format!(" password: {v}\n")),
(
"G3 toml",
"config/app.toml",
format!("password = \"{v}\"\n"),
),
("G4 markdown", "docs/guide.md", format!("password={v}\n")),
(
"G9 private-key envelope on a code path",
"src/probe.rs",
format!("let pem = \"{envelope}\";\n"),
),
(
"G10 authorization header on a code path",
"src/probe.rs",
format!("let h = \"Authorization: Bearer {v}\";\n"),
),
(
"G11 uri credentials on a code path",
"src/probe.rs",
format!("let u = \"https://user:{v}@host/path\";\n"),
),
];
let not_demoted: Vec<&str> = rows
.iter()
.filter(|(_, path, body)| !oracle_is_demoted(path, body))
.map(|(row, _, _)| *row)
.collect();
assert!(
not_demoted.is_empty(),
"these strict-by-design rows lost their demotion: {not_demoted:?}"
);
}
/// GREEN-GUARD (G5, G6) + GREEN-CONTROL (G7, G8). The guard surfaces scan
/// SYNTHETIC labels, not paths: `LanguageId::from_path` returns `None` for
/// both, so a code-language-gated exemption leaves them strict. That is
/// currently an ACCIDENT OF NAMING — G6 pins it, so renaming either label to
/// something ending `.rs` fails loudly instead of silently relaxing the
/// query/hit guards.
///
/// G8 is re-based (MEDIUM-4): its old fixture was admitted by BOTH
/// `is_placeholder`'s `your_` branch AND the code-expression exemption, so
/// deleting the `your_` branch left it green and it no longer guarded the
/// property it names. A QUOTED template placeholder restores that — the value
/// OPENS a literal so stage 2 cannot admit it, and the capture starts with a
/// sigil so the single-interpolation carve-out cannot either. Only
/// `is_placeholder` can, which makes it load-bearing again, and the row
/// doubles as the carve-out's boundary pin. Shape mirrored by
/// `oracle_g8_rebase_target_quoted_template_placeholder_stays_admitted`.
#[test]
fn oracle_b_guard_surfaces_and_placeholder_suppression_are_unchanged() {
let v = oracle_opaque();
let token_kw = kw_token();
// G5: the visible-field guard must still reject a credential-shaped field.
assert!(
crate::knowledge::guard_query(&format!("{token_kw}={v}")).is_err(),
"G5 the query guard must reject a credential-shaped field"
);
// G6: neither synthetic guard label may resolve to a language.
assert!(
LanguageId::from_path("external-field").is_none()
&& LanguageId::from_path("analytics").is_none(),
"G6 the synthetic guard labels must not resolve to a language, or a \
code-language-gated exemption would silently relax the guard surfaces"
);
// G7/G8: placeholder suppression is preserved on both path classes.
assert!(
!oracle_is_demoted(
"notes.txt",
&format!("{}=your_api_key_here\n", kw_key().to_ascii_uppercase()),
),
"G7 a documented placeholder must stay admitted on a text path"
);
assert!(
!oracle_is_demoted(
"src/probe.rs",
&format!("let {token_kw} = \"${{DEPLOY_ENV_NAME}}\";\n"),
),
"G8 a quoted template placeholder must stay admitted on a code path, \
with is_placeholder as the only admitting branch"
);
}
/// GREEN-GUARD. The shape the `big.rs` fixture in
/// `tier2_sweep_withholds_file_whose_current_bytes_are_sensitive` must be
/// re-based onto once C11 lands: a quoted opaque literal beside an exempted
/// associated-call expression, both on a CODE path. Proving the demotion
/// here is what stops the re-based fixture from passing vacuously.
#[test]
fn oracle_rebase_target_shape_stays_content_demoted_on_a_code_path() {
let v = oracle_opaque();
let body = format!("let password = \"{v}\";\nlet r = PortRegistry::new();\n");
assert!(
oracle_is_demoted("big.rs", &body),
"the re-base target shape must remain content-demoted on a code path"
);
}
// ── 7C. GATE ROWS ────────────────────────────────────────────────────────
/// RED (D1). Undecodable bytes on a NON-code path: `classify_stable_content`
/// returns `UnsupportedTextEncoding`, which the gate PERMITS — disclosing
/// bytes the secret scanner never inspected.
#[tokio::test]
async fn oracle_d1_undecodable_bytes_on_a_non_code_path_are_refused() {
let repo = TempDir::new().expect("temp repo");
let marker = oracle_marker();
fs::write(
repo.path().join("blob.bin"),
oracle_undecodable_bytes(&marker),
)
.expect("write undecodable blob");
let server = make_server_with_root(
make_live_index_ready(vec![]),
Some(repo.path().to_path_buf()),
);
let out = server
.get_file_content(Parameters(get_file_content_input("blob.bin")))
.await;
assert!(
!out.contains(&marker),
"D1 disclosed unscanned bytes; response shape: {}",
refusal_shape(&out)
);
assert!(
out.starts_with(WITHHELD_REFUSAL_PREFIX),
"D1 unscannable bytes must be refused; response shape: {}",
refusal_shape(&out)
);
}
/// GREEN-GUARD (D2). The code-path twin of D1. It used to be the population
/// option (ii) structurally could not reach — `IndexTargets::for_path` yields
/// `Code` for every recognized code language, so `includes_knowledge()` was
/// false and the encoding branch never ran. Ruling 4 removed that gate at
/// publication time; this row keeps the READ lane pinned independently, since
/// the gate decides the refusal MESSAGE on its own buffer before the
/// classifier is consulted at all.
#[tokio::test]
async fn oracle_d2_undecodable_bytes_on_a_code_path_are_refused() {
let repo = TempDir::new().expect("temp repo");
let marker = oracle_marker();
fs::create_dir_all(repo.path().join("src")).expect("create src");
fs::write(
repo.path().join("src/blob.rs"),
oracle_undecodable_bytes(&marker),
)
.expect("write undecodable blob");
let server = make_server_with_root(
make_live_index_ready(vec![]),
Some(repo.path().to_path_buf()),
);
let out = server
.get_file_content(Parameters(get_file_content_input("src/blob.rs")))
.await;
assert!(
!out.contains(&marker),
"D2 disclosed unscanned bytes; response shape: {}",
refusal_shape(&out)
);
assert!(
out.starts_with(WITHHELD_REFUSAL_PREFIX),
"D2 unscannable bytes must be refused; response shape: {}",
refusal_shape(&out)
);
}
/// RED (D3). The same population through the OTHER gated lane. Parsing
/// unscanned bytes and reporting their structure is a disclosure too.
#[tokio::test]
async fn oracle_d3_validate_file_syntax_refuses_undecodable_bytes() {
let repo = TempDir::new().expect("temp repo");
let marker = oracle_marker();
fs::create_dir_all(repo.path().join("src")).expect("create src");
fs::write(
repo.path().join("src/blob.rs"),
oracle_undecodable_bytes(&marker),
)
.expect("write undecodable blob");
let server = make_server_with_root(
make_live_index_ready(vec![]),
Some(repo.path().to_path_buf()),
);
let out = server
.validate_file_syntax(Parameters(super::ValidateFileSyntaxInput {
project: None,
path: "src/blob.rs".to_string(),
}))
.await;
assert!(
!out.contains(&marker),
"D3 disclosed unscanned bytes; response shape: {}",
refusal_shape(&out)
);
assert!(
out.starts_with(WITHHELD_REFUSAL_PREFIX),
"D3 unscannable bytes must be refused; response shape: {}",
refusal_shape(&out)
);
}
/// RED (D4). Refusing an over-budget file is CORRECT — the detector never
/// inspected it. The MESSAGE is the defect: today it claims the file is
/// "excluded by the repository's admission rules" and tells the caller to
/// reindex, which is both untrue and unactionable for a size-limit case.
/// The honest variant must also stay leak-free: no size, no threshold, no
/// digit of any kind.
#[tokio::test]
async fn oracle_d4_over_budget_file_refusal_message_is_honest() {
let repo = TempDir::new().expect("temp repo");
let body = "x".repeat(4 * 1024 * 1024 + 1);
fs::write(repo.path().join("oversized-blob.rs"), &body).expect("write oversized file");
let server = make_server_with_root(
make_live_index_ready(vec![]),
Some(repo.path().to_path_buf()),
);
let out = server
.get_file_content(Parameters(get_file_content_input("oversized-blob.rs")))
.await;
assert!(
out.starts_with(WITHHELD_REFUSAL_PREFIX),
"D4 an unscannable file must be refused; response shape: {}",
refusal_shape(&out)
);
assert!(
!out.contains("reindex the repository"),
"D4 a size-limit refusal must not claim reindexing will help; got: {out}"
);
assert!(
!out.chars().any(|character| character.is_ascii_digit()),
"D4 a refusal must not leak the size or the threshold; got: {out}"
);
}
/// GREEN-CONTROL. Fail-closed is about DISCLOSURE, not estimation: the
/// bucket-M estimate branch reads `fs::metadata` only and never calls the
/// gate, so the two populations D1–D4 newly deny must keep estimating.
/// `estimate_succeeds_for_demoted_file_while_content_selectors_refuse`
/// covers only the security-demoted population, not this one.
#[tokio::test]
async fn oracle_d_estimates_stay_permitted_for_unscannable_files() {
let repo = TempDir::new().expect("temp repo");
let marker = oracle_marker();
fs::write(
repo.path().join("blob.bin"),
oracle_undecodable_bytes(&marker),
)
.expect("write undecodable blob");
fs::write(
repo.path().join("oversized-blob.rs"),
"x".repeat(4 * 1024 * 1024 + 1),
)
.expect("write oversized file");
let server = make_server_with_root(
make_live_index_ready(vec![]),
Some(repo.path().to_path_buf()),
);
for path in ["blob.bin", "oversized-blob.rs"] {
let mut input = get_file_content_input(path);
input.estimate = Some(true);
let out = server.get_file_content(Parameters(input)).await;
assert!(
!out.contains(&marker),
"{path} estimate leaked file bytes; response shape: {}",
refusal_shape(&out)
);
assert!(
out.starts_with("Estimate for get_file_content"),
"{path} estimation must stay permitted; response shape: {}",
refusal_shape(&out)
);
}
}
/// GREEN-CONTROL. The fail-closed check lands before
/// `classify_stable_content`, and a Git LFS pointer is valid UTF-8 well
/// under the scan budget, so it must not be swallowed by it. Without this a
/// refuse-everything fail-closed check would still pass D1–D4.
#[tokio::test]
async fn oracle_d_lfs_pointer_is_still_served_by_the_gate() {
let repo = TempDir::new().expect("temp repo");
let pointer = format!(
"version https://git-lfs.github.com/spec/v1\noid sha256:{}\nsize 42\n",
"0".repeat(64)
);
fs::write(repo.path().join("assets.model"), &pointer).expect("write pointer");
let server = make_server_with_root(
make_live_index_ready(vec![]),
Some(repo.path().to_path_buf()),
);
let out = server
.get_file_content(Parameters(get_file_content_input("assets.model")))
.await;
assert!(
!out.starts_with(WITHHELD_REFUSAL_PREFIX),
"an LFS pointer must not be refused; response shape: {}",
refusal_shape(&out)
);
}
/// RED (D5). `validate_file_syntax` has no classifier arm, so its refusal
/// falls through `classify_compact_tool_output`'s catch-all and a withheld
/// file is reported as a SUCCESSFUL validation — including into the STEL
/// chain. Same class of defect as the `is_error_output` duplication.
#[test]
fn oracle_d5_validate_file_syntax_refusal_is_not_reported_as_a_success() {
let refusal =
crate::protocol::format::content_withheld_by_admission("config/settings.toml");
assert_eq!(
super::classify_compact_tool_output("validate_file_syntax", &refusal),
OutcomeClass::InvalidRequest,
"a withheld-content refusal must not classify as a successful validation"
);
assert!(
!super::compact_tool_output_is_success("validate_file_syntax", &refusal),
"a withheld-content refusal must not be admitted into the STEL chain"
);
}
/// GREEN-GUARD (D6, D7). `get_file_content` already classifies the refusal —
/// it must keep doing so once the shape moves into the shared predicate, and
/// the ANCHORING property must survive the move: a body that merely QUOTES
/// the phrase mid-text is a successful read, not a refusal.
#[test]
fn oracle_d6_d7_withheld_refusal_is_classified_only_when_anchored() {
let refusal =
crate::protocol::format::content_withheld_by_admission("config/settings.toml");
assert_eq!(
super::classify_compact_tool_output("get_file_content", &refusal),
OutcomeClass::InvalidRequest,
"D6 get_file_content must classify the refusal as an invalid request"
);
let quoting = format!("7: // {refusal}\n");
for tool in ["get_file_content", "validate_file_syntax"] {
assert_eq!(
super::classify_compact_tool_output(tool, "ing),
OutcomeClass::Found,
"D7 {tool} must keep a body that merely quotes the refusal classified as found"
);
}
}
// ── Round-3 oracle set ───────────────────────────────────────────────────
//
// Authored BEFORE the fix, same discipline as the block above: every fixture
// body is assembled at runtime from non-secret fragments, no failure message
// echoes a body, and rows are named by id and SHAPE only.
/// The rule's own keywords, assembled so that no source line in this file
/// spells a `keyword`-adjacent-`=` pair ahead of an 8-byte payload run.
/// Peers: `runtime_canary`, `oracle_opaque`.
fn kw_key() -> String {
["api", "_", "key"].concat()
}
fn kw_token() -> String {
["to", "ken"].concat()
}
fn kw_password() -> String {
["pass", "word"].concat()
}
/// Collect the row ids whose demotion verdict is not the one asserted.
fn oracle_rows_off_expectation(
rows: &[(&'static str, &str, String)],
demoted: bool,
) -> Vec<&'static str> {
rows.iter()
.filter(|(_, path, body)| oracle_is_demoted(path, body) != demoted)
.map(|(row, _, _)| *row)
.collect()
}
// ── 7A. STATED CEILINGS ──────────────────────────────────────────────────
/// GREEN-CONTROL (C12, C13). Two ceilings of the byte-wise stage-2
/// predicate, converted from UNSTATED false negatives into pinned ones.
///
/// C12 (MEDIUM-3): alternately-delimited literals — an Elixir sigil, a Ruby
/// percent literal — carry none of the three delimiters the payload fence
/// recognizes, so no fenced run is ever found. Deciding them needs a
/// per-language sigil sub-lexer, which the design declines to build.
///
/// C13: a literal OPENED ON A PRIOR LINE is invisible to a line-bounded
/// backward scan, and a Rust raw string yields a one-byte capture so the
/// rule produces no match at all. Both are pre-existing; neither widens.
#[test]
fn oracle_a_stated_false_negative_ceilings_stay_clean() {
let v = oracle_opaque();
let key_kw = kw_key();
let rows: Vec<(&'static str, &str, String)> = vec![
(
"C12a elixir sigil literal",
"src/probe.exs",
format!("{key_kw} = ~s({v})\n"),
),
(
"C12b ruby percent literal",
"src/probe.rb",
format!("{key_kw} = %q[{v}]\n"),
),
(
"C13a value inside a literal opened on a prior line",
"src/probe.py",
format!("BANNER = \"\"\"\n{key_kw}={v}\n\"\"\"\n"),
),
(
"C13b rust raw-string right-hand side",
"src/probe.rs",
format!("let {key_kw} = r#\"{v}\"#;\n"),
),
];
let off = oracle_rows_off_expectation(&rows, false);
assert!(
off.is_empty(),
"these stated-ceiling rows are content-demoted: {off:?}"
);
}
// ── 7B. MUST STAY SENSITIVE (Rulings 2 and 3) ────────────────────────────
/// RED (S10, S11, S11b). Ruling 2: the stage-2 withdrawal test must scan the
/// BALANCED MULTILINE right-hand side within a fixed bound and REQUIRE FULL
/// CONSUMPTION, failing closed on unbalanced or over-bound input.
///
/// S10 overturns row C10 of
/// `oracle_a_code_expression_shapes_must_not_be_content_demoted`: stopping at
/// the first newline is a FORMATTING distinction, not a semantic one —
/// rustfmt and black produce exactly this shape for long arguments, and
/// credentials are long, so the false negative is systematically aligned with
/// the values the rule exists to catch.
///
/// S11 and S11b separate the two fail-closed arms so neither can be dropped
/// silently: S11 exhausts the window with an unclosed delimiter (nonzero
/// depth), S11b exhausts it at depth ZERO, so only the "window truncated
/// before the expression terminated" signal can refuse it.
#[test]
fn oracle_b_wrapped_and_unconsumed_expressions_must_stay_content_demoted() {
let v = oracle_opaque();
let key_kw = kw_key();
let token_kw = kw_token();
// Longer than the bounded right-hand-side window, and bracket-free, so
// the walk is still at depth zero when the window runs out.
let wide = "alpha_one + beta_two + gamma_three + delta_four + ".repeat(12);
let rows: Vec<(&'static str, &str, String)> = vec![
(
"S10a formatter-wrapped call argument (python)",
"src/probe.py",
format!("{token_kw} = get_secret(\n \"{v}\",\n)\n"),
),
(
"S10b formatter-wrapped call argument (rust)",
"src/probe.rs",
format!("let {token_kw} = get_secret(\n \"{v}\",\n);\n"),
),
(
"S11 right-hand side opens a delimiter and never closes",
"src/probe.rs",
format!("let {key_kw} = compute_default(\n alpha,\n beta,\n"),
),
(
"S11b right-hand side at depth zero but over the scan bound",
"src/probe.rs",
format!("let {key_kw} = {wide}omega_end;\nfn tail() {{}}\n"),
),
];
let off = oracle_rows_off_expectation(&rows, true);
assert!(
off.is_empty(),
"these unconsumed right-hand sides are not content-demoted: {off:?}"
);
}
/// RED (S12, S13). Ruling 3 / HIGH-1: a credential EMBEDDED IN A URL OR
/// CONNECTION STRING REMAINS SENSITIVE. Today stage 2 inspects only the byte
/// immediately before the value, so when the match sits inside a surrounding
/// string literal the opening quote precedes the KEYWORD and the exemption
/// never withdraws.
///
/// S12b is the exact body that row C8 of
/// `oracle_a_code_expression_shapes_must_not_be_content_demoted` asserts
/// CLEAN today, so the two rows contradict each other until C8 is moved.
/// S13 is reachable by no other rule — `secret.uri-credentials` requires
/// userinfo, which a query parameter is not.
#[test]
fn oracle_b_credentials_embedded_in_literals_must_stay_content_demoted() {
let v = oracle_opaque();
let key_kw = kw_key();
let password_kw = kw_password();
let rows: Vec<(&'static str, &str, String)> = vec![
(
"S12a connection-string literal (csharp)",
"src/probe.cs",
format!("var connection = \"Server=db;User Id=sa;{password_kw}={v};\";\n"),
),
(
"S12b assignment embedded in a source string literal (rust)",
"src/probe.rs",
format!("assert!(!stored.contains(\"{password_kw}={v}\"));\n"),
),
(
"S13 credential as a url query parameter",
"src/probe.rs",
format!("let endpoint = \"https://host.invalid/path?{key_kw}={v}\";\n"),
),
];
let off = oracle_rows_off_expectation(&rows, true);
assert!(
off.is_empty(),
"these embedded-literal credentials are not content-demoted: {off:?}"
);
}
/// RED (S14, S15). The owner's CONSTRAINT on Ruling 3's placeholder
/// carve-out: an interpolated placeholder in one position MUST NOT license a
/// hardcoded literal elsewhere in the same string.
///
/// S14 is the greedy-capture path (the two are joined, so the capture is not
/// wholly a brace group). S15 is the independent-second-match path (the
/// first capture IS wholly a brace group and may be exempted; the second
/// keyword must still be judged on its own merits). A carve-out spelled as
/// "the capture CONTAINS a brace group" passes S15 and fails S14.
#[test]
fn oracle_b_placeholder_must_not_license_an_adjacent_literal() {
let v = oracle_opaque();
let key_kw = kw_key();
let token_kw = kw_token();
let rows: Vec<(&'static str, &str, String)> = vec![
(
"S14 placeholder and literal joined in one string",
"src/probe.rs",
format!("let line = format!(\"{token_kw}={{deploy_env_name}}&{key_kw}={v}\");\n"),
),
(
"S15 placeholder and literal space-separated in one string",
"src/probe.rs",
format!("let line = format!(\"{token_kw}={{deploy_env_name}} {key_kw}={v}\");\n"),
),
];
let off = oracle_rows_off_expectation(&rows, true);
assert!(
off.is_empty(),
"a placeholder licensed an adjacent hardcoded literal: {off:?}"
);
}
/// RED (S16). Blocker B1: the bounded balanced walk used to treat EVERY `'`
/// that failed the payload-fence test as a literal opener and jump to the
/// next identical byte. Two mis-paired apostrophes — a pair of lifetime
/// sigils here, an English contraction in a comment elsewhere — therefore
/// bracket the quoted credential and the walk steps clean over it, reaching
/// depth 0 and GRANTING the exemption. Fail-open.
///
/// The three rows differ ONLY in apostrophe count, so the count is provably
/// the variable: zero already fenced, one already failed closed on an
/// unterminated literal, and two — and only two — leaked.
#[test]
fn oracle_b_apostrophe_pairs_must_not_bracket_a_payload_out_of_the_walk() {
let v = oracle_opaque();
let token_kw = kw_token();
let rows: Vec<(&'static str, &str, String)> = vec![
(
"S16a zero apostrophes (control)",
"src/probe.rs",
format!("let {token_kw} = Wrapper::build(\"{v}\", PhantomData);\n"),
),
(
"S16b one apostrophe (control)",
"src/probe.rs",
format!("let {token_kw} = Wrapper::<'a>::build(\"{v}\", PhantomData);\n"),
),
(
"S16c two apostrophes bracketing the payload",
"src/probe.rs",
format!("let {token_kw} = Wrapper::<'a>::build(\"{v}\", PhantomData::<&'b u8>);\n"),
),
];
let off = oracle_rows_off_expectation(&rows, true);
assert!(
off.is_empty(),
"apostrophes hid a quoted payload from the walk: {off:?}"
);
}
/// RED (S17a) + GREEN (S17b) + GREEN-CONTROL (S17c, S17d, S17e). Blocker
/// B2, found while verifying B1: the unconditional one-byte advance leaves
/// a char literal's content byte VISIBLE to the depth tracker. A `')'`
/// char literal therefore underflows `depth`, and the enclosing-group arm
/// reads that as "expression consumed" and GRANTS the exemption before the
/// real fenced payload is ever reached — fail-open. Measured before the
/// bounded-char-literal skip: S17a CLEAN while S17e, identical but for the
/// char literal, was SENSITIVE — the char literal was provably the
/// variable. The bounded skip closes S17a; S17c pins the precision the
/// bound restores (a benign `'{'` no longer inflates depth into a phantom
/// unbalance — it was demoted before the skip); S17d pins the benign
/// closing-bracket literal; S17b pins the payload fence firing regardless
/// of char-literal handling.
#[test]
fn oracle_b_char_literal_brackets_must_not_consume_the_walk() {
let v = oracle_opaque();
let token_kw = kw_token();
let demoted: Vec<(&'static str, &str, String)> = vec![
(
"S17a ')' char literal ahead of a fenced payload",
"src/probe.rs",
format!("let {token_kw} = compose_from(')').materialize(\"{v}\");\n"),
),
(
"S17b '(' char literal ahead of a fenced payload",
"src/probe.rs",
format!("let {token_kw} = split_segments('(', \"{v}\");\n"),
),
(
"S17e control for S17a with the char literal removed",
"src/probe.rs",
format!("let {token_kw} = compose_from(x).materialize(\"{v}\");\n"),
),
];
let clean: Vec<(&'static str, &str, String)> = vec![
(
"S17c benign '{' char literal must not phantom-unbalance",
"src/probe.rs",
format!("let {token_kw} = wrap_segments('{{', source_text);\n"),
),
(
"S17d benign ')' char literal stays clean",
"src/probe.rs",
format!("let {token_kw} = trim_matching(')', source_text);\n"),
),
];
let off_demoted = oracle_rows_off_expectation(&demoted, true);
let off_clean = oracle_rows_off_expectation(&clean, false);
assert!(
off_demoted.is_empty() && off_clean.is_empty(),
"char-literal rows off expectation: not demoted {off_demoted:?}, \
not clean {off_clean:?}"
);
}
/// RED (S20). The bounded char-literal skip was reasoned about as a RUST
/// question — char literal versus lifetime sigil — but `'` is a first-class
/// STRING delimiter in Python, JavaScript, TypeScript, Ruby and PHP, all of
/// which are code languages here. There the byte the skip fires on is
/// usually a string's CLOSING quote, and the next `'` within the bound is
/// the OPENING quote of the following argument, because `', '` is a
/// two-byte gap. An unconditional bounded skip jumps clean over that
/// opening quote, and the payload fence is only ever tested when the walk
/// LANDS on a quote — so the credential behind it was never fence-tested
/// and the whole expression came back exempt.
///
/// Measured before the bracket requirement: S20a and S20b CLEAN while
/// S20c — identical but for the FIRST argument's quote style — was
/// SENSITIVE, so the skip was provably the variable. S20d pins that a lone
/// single-quoted credential was never affected.
///
/// The fix requires the skipped span to CARRY A BRACKET, which is the only
/// thing the skip was ever for (keeping a char literal's bracket out of
/// `depth`, rows S17a-S17d). A bracket-free gap now falls through to the
/// one-byte advance, so the next quote is always seen.
#[test]
fn oracle_b_single_quoted_string_arguments_must_not_hide_a_credential() {
let v = oracle_opaque();
let token_kw = kw_token();
let rows: Vec<(&'static str, &str, String)> = vec![
(
"S20a python, two single-quoted arguments",
"src/probe.py",
format!("{token_kw} = compute_header('label', '{v}')\n"),
),
(
"S20b javascript, two single-quoted arguments",
"src/probe.js",
format!("const {token_kw} = buildHeaders('auth', '{v}');\n"),
),
(
"S20c control: first argument double-quoted",
"src/probe.py",
format!("{token_kw} = compute_header(\"label\", '{v}')\n"),
),
(
"S20d control: lone single-quoted credential argument",
"src/probe.py",
format!("{token_kw} = compute_header('{v}')\n"),
),
];
let off = oracle_rows_off_expectation(&rows, true);
assert!(
off.is_empty(),
"a single-quoted argument hid a credential from the walk: {off:?}"
);
}
/// RED (S21) + GREEN-CONTROL (G11). The owner's principle, stated whole:
/// EVERY SUBSTANTIVE LITERAL RUN IN A CREDENTIAL-BOUND RIGHT-HAND SIDE IS
/// INSPECTED INDEPENDENTLY; PLACEHOLDER-ONLY EXPRESSIONS REMAIN EXEMPT.
///
/// Three defects fell out of it, all fixed at the one boundary both
/// exemptions pass through rather than in either exemption separately:
///
/// S21a — the placeholder branch `continue`d before the withdrawal walk
/// ever ran, so a lone placeholder in the FIRST operand of a concatenation
/// exempted the whole expression and the hardcoded literal in the second
/// operand was never inspected. The capture is exempt; the expression is
/// not. S21b is the same shape with no placeholder, so the placeholder is
/// provably the variable.
///
/// S21c — a quote span was allowed to cover a line break, carrying the walk
/// past the depth-0 gate without it ever being consulted. A genuine char
/// literal never spans a line, so the skip now stops at `\n`.
///
/// G11a/G11b — GitHub Actions writes ONE expression with nested braces, and
/// the interior-brace test had been rejecting it on every workflow file.
/// G11c pins adjacent expansions with no literal between them: that is a
/// placeholder-ONLY expression and stays exempt. G11 is what stops the S21
/// direction from being satisfied by simply refusing everything.
#[test]
fn oracle_b_placeholder_exempts_the_capture_not_the_expression() {
let v = oracle_opaque();
let token_kw = kw_token();
let demoted: Vec<(&'static str, &str, String)> = vec![
(
"S21a placeholder operand cannot exempt a concatenated literal",
"src/probe.py",
format!("{token_kw} = '${{DEPLOY_HOST}}' + '{v}'\n"),
),
(
"S21b control: same shape with no placeholder",
"src/probe.py",
format!("{token_kw} = '{v}' + suffix_value\n"),
),
(
"S21c a quote span must not cross a newline onto the next \
line's opening fence",
"src/probe.py",
format!("{token_kw} = compute_header('(\n'{v}')\n"),
),
(
"S21d placeholder groups bracketing a literal stay sensitive",
".github/workflows/ci.yaml",
format!("{token_kw}: ${{{{ALPHA}}}}{v}${{{{OMEGA}}}}\n"),
),
(
"S21e control: a bare literal in a workflow stays sensitive",
".github/workflows/ci.yaml",
format!("{token_kw}: {v}\n"),
),
];
let clean: Vec<(&'static str, &str, String)> = vec![
(
"G11a github actions expression, no inner spaces",
".github/workflows/ci.yaml",
format!("{token_kw}: ${{{{secrets.DEPLOY_TOKEN_NAME}}}}\n"),
),
(
"G11b github actions expression, inner spaces",
".github/workflows/ci.yaml",
format!("{token_kw}: ${{{{ secrets.DEPLOY_TOKEN_NAME }}}}\n"),
),
(
"G11c adjacent expansions with no literal between them",
".env",
format!("{token_kw}=${{ALPHA_PART}}${{OMEGA_PART}}\n"),
),
];
let off_demoted = oracle_rows_off_expectation(&demoted, true);
let off_clean = oracle_rows_off_expectation(&clean, false);
assert!(
off_demoted.is_empty() && off_clean.is_empty(),
"placeholder-scope rows off expectation: not demoted \
{off_demoted:?}, not clean {off_clean:?}"
);
}
/// RED (S18) + GREEN-CONTROL (G9). Open item H1, ruled: `is_placeholder`'s
/// `${…}`/`{{…}}` branches tested the ENDS only — `starts_with("${") &&
/// ends_with('}')` — so a capture BRACKETED by two placeholders satisfied
/// them while carrying a hardcoded literal between them, and because the
/// branch runs before the `is_code_language` gate the leak reached EVERY
/// path class, config included. Ruled fix: the whole-capture single-group
/// discipline `capture_is_single_interpolation` already has.
///
/// S18 pins the three measured leaks, one per path class. G9 pins the
/// ruling's stated limit — a LONE group keeps its exemption, including a
/// shell default-expansion and a mustache default filter, whose literal
/// defaults were deliberately NOT made sensitive. Together they prove the
/// fix discriminates one group from two rather than deleting the branch.
#[test]
fn oracle_b_placeholders_must_not_bracket_a_hardcoded_literal() {
let v = oracle_opaque();
let token_kw = kw_token();
let demoted: Vec<(&'static str, &str, String)> = vec![
(
"S18a shell placeholders bracketing a literal (code path)",
"src/probe.rs",
format!("let {token_kw} = \"${{ALPHA}}{v}${{OMEGA}}\";\n"),
),
(
"S18b shell placeholders bracketing a literal (env path)",
".env",
format!("{token_kw}=${{ALPHA}}{v}${{OMEGA}}\n"),
),
(
"S18c mustache placeholders bracketing a literal (yaml path)",
"config.yaml",
format!("{token_kw}: \"{{{{alpha}}}}{v}{{{{omega}}}}\"\n"),
),
];
let clean: Vec<(&'static str, &str, String)> = vec![
(
"G9a lone shell default-expansion stays admitted",
".env",
format!("{token_kw}=${{DEPLOY_ENV_NAME:-{v}}}\n"),
),
(
"G9b lone mustache default filter stays admitted",
"config.yaml",
format!("{token_kw}: \"{{{{deploy_env_name|default:{v}}}}}\"\n"),
),
(
"G9c lone shell placeholder stays admitted on a code path",
"src/probe.rs",
format!("let {token_kw} = \"${{DEPLOY_ENV_NAME_VALUE}}\";\n"),
),
];
let off_demoted = oracle_rows_off_expectation(&demoted, true);
let off_clean = oracle_rows_off_expectation(&clean, false);
assert!(
off_demoted.is_empty() && off_clean.is_empty(),
"placeholder-group rows off expectation: not demoted \
{off_demoted:?}, not clean {off_clean:?}"
);
}
/// RED (S19) + GREEN-CONTROL (G10). Open item H2, ruled: the depth-0
/// newline arm terminated the withdrawal walk unconditionally, so a
/// formatter continuation that opens NO bracket — a method chain, a `??`
/// fallback, a `+` concatenation, a `\` continuation — was never entered.
/// Ruling 2's own rationale ("rustfmt and black PRODUCE that shape …
/// credentials are long") applies verbatim, and the walk's docstring
/// framed non-line-locality as an invariant it did not hold. Ruled fix:
/// continue past a depth-0 break only on a continuation operator.
///
/// S19a–d are the four measured styles, covering both formatter
/// conventions (operator leading the next line, operator trailing the
/// previous one). S19e is the single-line control that was already
/// sensitive, so the line break alone is provably the variable.
///
/// G10 is the precision control the narrow token set exists for: an
/// ordinary FINISHED statement must still terminate the walk, so the
/// following line's quoted value cannot withdraw the previous line's
/// exemption. G10b once pinned the `,` exclusion; spec 023 decision D1
/// REVERSES it — a trailing comma separates declarators and tuple
/// elements as often as it ends one, and excluding it let a line break
/// hide a credential in the next declarator (C5, measured). The
/// struct-literal walk-through is the accepted price, so G10b now pins
/// that regression as ACCEPTED: the sibling field's value IS found.
#[test]
fn oracle_b_formatter_continuations_must_stay_content_demoted() {
let v = oracle_opaque();
let token_kw = kw_token();
let key_kw = kw_key();
let demoted: Vec<(&'static str, &str, String)> = vec![
(
"G10b struct-literal sibling found — accepted D1 regression",
"src/probe.rs",
format!(
"let config = Config {{\n {key_kw}: resolve_from_environment(),\n \
banner_text: \"{v}\",\n}};\n"
),
),
(
"S19a method-chain continuation (rust)",
"src/probe.rs",
format!(
"let {token_kw} = credential_client\n .fetch_secret_material(\"{v}\");\n"
),
),
(
"S19b nullish-fallback continuation (typescript)",
"src/probe.ts",
format!("const {token_kw} = readEnvValue()\n ?? \"{v}\";\n"),
),
(
"S19c concatenation continuation (java)",
"src/Probe.java",
format!("String {token_kw} = assembledPrefix\n + \"{v}\";\n"),
),
(
"S19d backslash continuation (python)",
"src/probe.py",
format!("{token_kw} = assembled_prefix \\\n + \"{v}\"\n"),
),
(
"S19e single-line control",
"src/probe.rs",
format!("let {token_kw} = credential_client.fetch_secret_material(\"{v}\");\n"),
),
];
let clean: Vec<(&'static str, &str, String)> = vec![
(
"G10a a finished statement must still end the walk",
"src/probe.rs",
format!("let {key_kw} = resolve_from_environment();\nlet banner = \"{v}\";\n"),
),
(
"G10c a generic parameter list closing in > is not a continuation",
"src/probe.ts",
format!("let {key_kw}: Map<string, string>\nconst banner = \"{v}\";\n"),
),
];
let off_demoted = oracle_rows_off_expectation(&demoted, true);
let off_clean = oracle_rows_off_expectation(&clean, false);
assert!(
off_demoted.is_empty() && off_clean.is_empty(),
"formatter-continuation rows off expectation: not demoted \
{off_demoted:?}, not clean {off_clean:?}"
);
}
/// GREEN-CONTROL. MEDIUM-4's re-base target for row G8. Today's G8 fixture
/// is admitted by BOTH `is_placeholder`'s `your_` branch AND the code-expression
/// exemption, so deleting the `your_` branch leaves it green — it no longer
/// guards the property it names. A QUOTED template placeholder restores that:
/// the value opens a literal, so stage 2 cannot admit it, and the capture
/// starts with a sigil, so the single-brace carve-out cannot admit it either.
/// Only `is_placeholder` can, which makes it load-bearing again.
#[test]
fn oracle_g8_rebase_target_quoted_template_placeholder_stays_admitted() {
let token_kw = kw_token();
let body = format!("let {token_kw} = \"${{DEPLOY_ENV_NAME}}\";\n");
assert!(
!oracle_is_demoted("src/probe.rs", &body),
"G8 re-base target: a quoted template placeholder must stay admitted \
on a code path, with is_placeholder as the only admitting branch"
);
}
// ── 7D. PUBLICATION AND MESSAGING ────────────────────────────────────────
/// RED (E1). Ruling 4. `classify_stable_content` gates its encoding check on
/// `IndexTargets::includes_knowledge()`, which is FALSE for every code
/// language, and the binary sniff clips at `BINARY_SNIFF_BYTES`. A code file
/// whose first invalid byte lands PAST that clip is therefore sniffed clean,
/// scanned bytewise, lossily parsed, and published into Tier-1 — then served
/// from memory through a lane the raw-read gate never sees.
///
/// Shape-mirrors `non_utf8_text_is_catalog_only_without_lossy_evidence` in
/// `live_index::store`, which exercises only the Knowledge target.
#[test]
fn oracle_e1_invalid_utf8_past_the_sniff_window_is_catalog_only_on_a_code_path() {
let marker = oracle_marker();
let mut bytes = format!("// {}\n", "pad ".repeat(2_100)).into_bytes();
assert!(
bytes.len() > crate::domain::index::BINARY_SNIFF_BYTES,
"E1 fixture must place its first invalid byte beyond the binary sniff window"
);
bytes.extend_from_slice(b"pub fn oracle_e1_anchor() {}\n");
bytes.extend_from_slice(&[0xFF_u8, 0xFE]);
bytes.extend_from_slice(marker.as_bytes());
bytes.push(b'\n');
// Anti-vacuity control, asserted BEFORE the two RED rows so it is proven
// now rather than after the fix: the same fixture minus its invalid tail
// is published normally, so the `is_none()` below cannot be satisfied by
// the path simply never being discovered.
let valid_prefix = bytes.len() - (2 + marker.len() + 1);
let control = TempDir::new().expect("temp control repo");
fs::create_dir_all(control.path().join("src")).expect("create src");
fs::write(control.path().join("src/blob.rs"), &bytes[..valid_prefix])
.expect("write control blob");
let control_shared = LiveIndex::load(control.path()).expect("E1 control must load");
assert!(
control_shared.read().get_file("src/blob.rs").is_some(),
"E1 control: the same fixture without its invalid tail must be published, \
or the demotion assertion below proves nothing"
);
let targets = crate::domain::IndexTargets::for_path("src/blob.rs", Some(&LanguageId::Rust));
assert!(
matches!(
crate::knowledge::classify_stable_content("src/blob.rs", targets, &bytes),
crate::knowledge::StableContentAdmission::MetadataOnly(
crate::domain::MetadataOnlyReason::UnsupportedTextEncoding
)
),
"E1 the WHOLE byte buffer must be encoding-validated before Tier-1 publication"
);
let repo = TempDir::new().expect("temp repo");
fs::create_dir_all(repo.path().join("src")).expect("create src");
fs::write(repo.path().join("src/blob.rs"), &bytes).expect("write blob");
let shared = LiveIndex::load(repo.path()).expect("E1 fixture must load");
let index = shared.read();
assert!(
index.get_file("src/blob.rs").is_none(),
"E1 unvalidated bytes must not be published into the in-memory index"
);
}
/// Derive the in-band indeterminate discriminator from production's own
/// collapse instead of hardcoding it: `classify_stable_content` maps every
/// `DetectorFailure` onto one reserved rule id carried inside
/// `SensitiveContent`, which is why Ruling 5 needs no new domain variant.
fn oracle_indeterminate_rule_id(reason: crate::knowledge::DetectorFailure) -> String {
match crate::knowledge::classify_stable_content_with(
"notes/probe.txt",
crate::domain::IndexTargets::Knowledge,
b"clean candidate",
|_path, _bytes| crate::knowledge::SecretScan::Indeterminate { reason },
) {
crate::knowledge::StableContentAdmission::MetadataOnly(
crate::domain::MetadataOnlyReason::SensitiveContent { rule_ids, .. },
) => rule_ids
.into_iter()
.next()
.expect("the collapse must carry exactly one reserved rule id"),
other => panic!("a detector failure must fail closed; got {other:?}"),
}
}
/// RED (E2). Ruling 5: all three `DetectorFailure` variants must reach the
/// HONEST refusal, not the one advising a reindex. Round 2 routed only the
/// resource-limit case, which the gate pre-empts on its own buffer before the
/// classifier ever runs; the other two collapse into `SensitiveContent` and
/// still carry the untrue advice.
///
/// Driven against the gate directly rather than a tool entry point: the two
/// unreachable-by-construction variants (a process-global policy-compilation
/// failure, a missing capture group) cannot be produced at runtime, and a
/// server built over a hand-written manifest re-scouts its root and discards
/// the entry. The gate's MANIFEST arm is the reachable route, and it is the
/// arm Round 2 left untouched: a recorded `SensitiveContent` carrying the
/// reserved indeterminate id is written by the same collapse at cold load and
/// by the watcher, and it denies BEFORE any read.
#[test]
fn oracle_e2_indeterminate_detector_failure_refusal_is_honest() {
let policy =
oracle_indeterminate_rule_id(crate::knowledge::DetectorFailure::PolicyCompilation);
let internal = oracle_indeterminate_rule_id(crate::knowledge::DetectorFailure::Internal);
let limit = oracle_indeterminate_rule_id(crate::knowledge::DetectorFailure::ResourceLimit);
assert_eq!(
policy, internal,
"E2 every detector failure must collapse onto one reserved rule id"
);
assert_eq!(
policy, limit,
"E2 every detector failure must collapse onto one reserved rule id"
);
let repo = TempDir::new().expect("temp repo");
fs::create_dir_all(repo.path().join("notes")).expect("create notes");
let probe = repo.path().join("notes/probe.txt");
fs::write(&probe, "ordinary prose\n").expect("write probe file");
let mut live = make_live_index_ready(vec![]);
live.manifest_entries = vec![crate::domain::CatalogEntry {
path: crate::domain::CatalogPath {
public_id: "notes/probe.txt".to_string(),
normalized_utf8: Some("notes/probe.txt".to_string()),
},
size: 15,
language: None,
classification: crate::domain::FileClassification {
class: crate::domain::FileClass::Text,
is_generated: false,
is_test: false,
is_vendor: false,
is_config: false,
},
disposition: crate::domain::FileDisposition::MetadataOnly {
reason: crate::domain::MetadataOnlyReason::SensitiveContent {
rule_ids: vec![policy],
finding_count: 0,
},
},
content_hash: None,
}];
let refusal = crate::protocol::read_gate::admit_disk_read(&live, "notes/probe.txt", &probe)
.expect_err("E2 an indeterminate verdict must stay refused");
assert!(
refusal.starts_with(WITHHELD_REFUSAL_PREFIX),
"E2 the refusal must keep the shared anchor; response shape: {}",
refusal_shape(&refusal)
);
assert!(
!refusal.contains("reindex the repository"),
"E2 an indeterminate verdict must not advise a reindex that cannot help; got: {refusal}"
);
// The anchor the honest variant must preserve: both refusal texts stay
// classified as admission refusals, so nothing keyed on that predicate
// regresses when the message is switched.
let unscanned = crate::protocol::format::content_withheld_unscanned("notes/probe.txt");
assert_eq!(
super::classify_compact_tool_output("get_file_content", &unscanned),
OutcomeClass::InvalidRequest,
"E2 the honest refusal must stay classified as an admission refusal"
);
// GREEN-GUARD, same test so it cannot drift from the row above: the fix
// must DISCRIMINATE on the reserved rule id, not switch every refusal to
// the honest wording. A path-rule exclusion really can be stale, so its
// recovery advice stays. Without this a blanket switch passes E2.
let path_rule = repo.path().join(".env");
fs::write(&path_rule, "ordinary prose\n").expect("write dotenv fixture");
let path_refusal = crate::protocol::read_gate::admit_disk_read(&live, ".env", &path_rule)
.expect_err("a path-rule exclusion must stay refused");
assert!(
path_refusal.contains("reindex the repository"),
"E2 a path-rule exclusion must keep its recovery advice; got: {path_refusal}"
);
}
/// RED (E3). Blocker H3. `edit::reindex_after_write` is a Tier-1
/// PUBLICATION route — it re-reads the file it just wrote and hands those
/// bytes to `update_file` — and it used to do so with no content
/// classification at all. An edit that INSERTS a credential therefore
/// republished it into Tier-1, where `get_file_content` serves it straight
/// out of memory without ever consulting the raw-read gate.
///
/// Driven through a real `replace_symbol_body`, one of the ten call sites
/// that share that boundary, so only a fix AT the boundary makes it pass.
///
/// The pre-edit assertion is the anti-vacuity control: the path really is
/// Tier-1 first, so its absence afterwards is the eviction and not a fixture
/// that was never indexed. The disk read-back is the second one: the edit
/// really did persist the value, so the refusal is a withholding decision
/// and not a failed write.
#[tokio::test]
async fn oracle_e3_post_edit_credential_cannot_be_republished_into_tier_1() {
let v = oracle_opaque();
let key_kw = kw_key();
let (_dir, server, file_path) =
setup_edit_test_with_fresh_mtime(b"fn target() {\n let x = 1;\n}\n");
assert!(
server.index.read().get_file("src/lib.rs").is_some(),
"E3 control: the fixture must be Tier-1 BEFORE the edit, or its \
absence afterwards proves nothing"
);
let edited = server
.replace_symbol_body(Parameters(crate::protocol::edit::ReplaceSymbolBodyInput {
project: None,
path: "src/lib.rs".to_string(),
name: "target".to_string(),
kind: None,
symbol_line: None,
new_body: format!("fn target() {{\n let {key_kw} = \"{v}\";\n}}"),
dry_run: None,
idempotency_key: None,
if_match: None,
working_directory: None,
}))
.await;
assert!(
edited.contains("replaced"),
"E3 the edit must be applied; response shape: {}",
refusal_shape(&edited)
);
assert!(
fs::read(&file_path)
.expect("read the edited file back")
.windows(v.len())
.any(|window| window == v.as_bytes()),
"E3 control: the edit must really have persisted the value to disk"
);
assert!(
server.index.read().get_file("src/lib.rs").is_none(),
"E3 post-edit sensitive content was republished into Tier-1"
);
let served = server
.get_file_content(Parameters(get_file_content_input("src/lib.rs")))
.await;
assert!(
!served.contains(v.as_str()),
"E3 the post-edit value was served; response shape: {}",
refusal_shape(&served)
);
assert!(
served.starts_with(WITHHELD_REFUSAL_PREFIX),
"E3 the post-edit read must be refused by the gate; response shape: {}",
refusal_shape(&served)
);
}
// ── 7E. RULING 1'S OWN PROOF ─────────────────────────────────────────────
/// Walk one tree, recording every file the detector does not call Clean.
/// Records `path`, a COUNT and RULE IDS only — never a matched line.
fn oracle_scan_tree(dir: &Path, root: &Path, findings: &mut Vec<String>) {
// A tripwire that SKIPS what it cannot read reports the same empty
// result as a clean tree, so every IO failure is recorded as a finding
// rather than swallowed: unreadable is unverified, never clean.
let entries = match fs::read_dir(dir) {
Ok(entries) => entries,
Err(error) => {
findings.push(format!(
"{} [unreadable dir: {}]",
dir.display(),
error.kind()
));
return;
}
};
for entry in entries {
let path = match entry {
Ok(entry) => entry.path(),
Err(error) => {
findings.push(format!(
"{} [unreadable entry: {}]",
dir.display(),
error.kind()
));
continue;
}
};
if path.is_dir() {
// A directory carrying its own `.git` is CLONED third-party
// content, not source this repository authors. CI clones
// golden-replay corpora into `tests/fixtures/`, and one of them
// legitimately contains a database URL with credentials — a
// real finding about someone else's fixture that we can neither
// rewrite nor vendor a change into. Ruling 1's mandate is that
// THIS repository's own test code answers to the detector, so
// the exclusion is by authorship, not by path: it needs no
// maintenance as corpora come and go.
if path.join(".git").exists() {
continue;
}
oracle_scan_tree(&path, root, findings);
continue;
}
let bytes = match fs::read(&path) {
Ok(bytes) => bytes,
Err(error) => {
findings.push(format!("{} [unreadable: {}]", path.display(), error.kind()));
continue;
}
};
let relative = path
.strip_prefix(root)
.unwrap_or(path.as_path())
.to_string_lossy()
.replace('\\', "/");
match crate::knowledge::scan_secret_bytes(&relative, &bytes) {
crate::knowledge::SecretScan::Clean => {}
crate::knowledge::SecretScan::Sensitive {
rule_ids,
finding_count,
} => findings.push(format!("{relative} [{finding_count}] {rule_ids:?}")),
crate::knowledge::SecretScan::Indeterminate { reason } => {
findings.push(format!("{relative} [indeterminate {reason:?}]"));
}
}
}
}
/// RED today, GREEN-GUARD after Ruling 1. The mechanical enforcement of the
/// owner's policy statement: TEST CODE RECEIVES THE SAME DETECTOR POLICY AS
/// PRODUCTION CODE. No region class, no path class, no test-only carve-out
/// anywhere in the detector — the repository's own fixtures are what change.
///
/// It also fails loudly the next time someone writes a credential-shaped
/// fixture into this tree, which is the defect Ruling 1 exists to remove.
///
/// SCOPE, stated rather than implied: source THIS repository authors, under
/// `src/` and `tests/`. Directories carrying their own `.git` are skipped as
/// cloned third-party content — CI clones golden-replay corpora into
/// `tests/fixtures/`, and this test is not a claim about them. It is NOT a
/// whole-repository sweep, and its green result is not a claim about one. Non-compiled trees (`research/`, `docs/`, `specs/`,
/// `scripts/`, `npm/`, …) are outside it and DO still carry
/// detector-positive shapes; widening the walk would demand rewriting
/// captured research artifacts, which no ruling authorizes. Anyone reading
/// this test as repository-wide coverage is reading more than it proves.
#[test]
fn repository_source_is_clean_under_its_own_detector() {
let root = Path::new(env!("CARGO_MANIFEST_DIR"));
let mut findings: Vec<String> = Vec::new();
for tree in ["src", "tests"] {
oracle_scan_tree(&root.join(tree), root, &mut findings);
}
findings.sort();
assert!(
findings.is_empty(),
"{} repository source file(s) trip this repository's own detector: {findings:?}",
findings.len()
);
}
}