symforge 11.22.0

SymForge — in-memory code intelligence MCP server for Claude Code, Codex, and Gemini CLI
Documentation
//! Rich symbol reads use the same selector, renderer, and inspection views as MCP.
use super::embed_query::{Budget, EmbeddedQuerySnapshot, symbol_row, validate_kind, validate_path};
use super::embed_session::QuerySession;
use super::guidance::{source, symbol_read};
use crate::embed::parity::symbol::*;
use crate::embed::parity::{QueryOutput, QueryRefusalKind};
use crate::live_index::query::{SymbolSelectorMatch, resolve_symbol_selector};

pub(super) fn validate(request: &SymbolReadRequest) -> Result<(), QueryRefusalKind> {
    if request.max_tokens == Some(0) || request.symbol_line == Some(0) {
        return Err(QueryRefusalKind::InvalidRequest);
    }
    if let Some(targets) = &request.targets {
        if targets.is_empty() || targets.len() > 10_000 {
            return Err(QueryRefusalKind::InvalidRequest);
        }
        for target in targets {
            validate_path(&target.path, false)?;
            validate_kind(target.kind.as_deref())?;
            if target.symbol_line == Some(0)
                || target
                    .name
                    .as_ref()
                    .is_some_and(|name| name.trim().is_empty())
                || (target.name.is_none() && target.start_byte.is_none())
            {
                return Err(QueryRefusalKind::InvalidRequest);
            }
        }
    } else {
        if request.name.trim().is_empty() {
            return Err(QueryRefusalKind::InvalidRequest);
        }
        if !request.path.is_empty() {
            validate_path(&request.path, false)?;
        }
        validate_kind(request.kind.as_deref())?;
    }
    Ok(())
}

pub(super) fn validate_inspect(request: &InspectMatchRequest) -> Result<(), QueryRefusalKind> {
    validate_path(&request.path, false)?;
    // Line 0 is refused by the lane, with MCP's out-of-bounds text (it names the
    // file's line count).
    if request.max_tokens == Some(0) {
        return Err(QueryRefusalKind::InvalidRequest);
    }
    Ok(())
}

fn entry(path: String) -> SymbolReadEntry {
    SymbolReadEntry {
        path,
        symbol: None,
        start_byte: None,
        end_byte: None,
        content_hash: None,
        source: None,
        refusal: None,
        withheld: None,
        candidates: Vec::new(),
    }
}

fn target(
    snapshot: &EmbeddedQuerySnapshot,
    target: &SymbolTarget,
    estimate: bool,
    line_numbers: Option<bool>,
    single: bool,
    budget: &mut Budget,
) -> Result<(SymbolReadEntry, String), QueryRefusalKind> {
    let mut row = entry(target.path.clone());
    if let Err(refusal) = super::embed_read::admit(snapshot, &target.path, None, budget) {
        row.refusal = Some(refusal);
        row.withheld = budget.withheld.take();
        return Ok((row, format!("Source withheld: {}", target.path)));
    }
    let Some(file) = snapshot.generation.live.get_file(&target.path) else {
        row.refusal = Some(QueryRefusalKind::NotFound);
        // MCP's single read suggests similar paths; its batch names the path only.
        let text = if single {
            let suggestions = super::guidance::file_read::suggest_similar_files(
                &snapshot.generation.live,
                &target.path,
            );
            super::guidance::file_read::not_found_file_with_suggestions(&target.path, &suggestions)
        } else {
            super::guidance::file_read::not_found_file(&target.path)
        };
        return Ok((row, text));
    };
    if let Err(refusal) =
        super::embed_read::admit(snapshot, &target.path, Some(&file.content), budget)
    {
        row.refusal = Some(refusal);
        row.withheld = budget.withheld.take();
        return Ok((row, format!("Source withheld: {}", target.path)));
    }
    let (start, end, rendered) = if let Some(name) = &target.name {
        let rendered = symbol_read::symbol_detail_from_indexed_file_with(
            file,
            name,
            target.kind.as_deref(),
            target.symbol_line,
            line_numbers,
        );
        match resolve_symbol_selector(file, name, target.kind.as_deref(), target.symbol_line) {
            SymbolSelectorMatch::Selected(index, symbol) => {
                row.symbol = Some(symbol_row(file, index, symbol)?);
                (
                    symbol.effective_start() as usize,
                    symbol.byte_range.1 as usize,
                    rendered,
                )
            }
            SymbolSelectorMatch::NotFound => {
                row.refusal = Some(QueryRefusalKind::NotFound);
                return Ok((row, rendered));
            }
            SymbolSelectorMatch::Ambiguous(lines) => {
                row.refusal = Some(QueryRefusalKind::AmbiguousSymbol);
                for (index, symbol) in file.symbols.iter().enumerate() {
                    if symbol.name == *name && lines.contains(&symbol.line_range.0) {
                        row.candidates.push(symbol_row(file, index, symbol)?);
                    }
                }
                return Ok((row, rendered));
            }
        }
    } else {
        let start_byte = target.start_byte.ok_or(QueryRefusalKind::InvalidRequest)? as usize;
        let end_byte = target.end_byte.map(|end| end as usize);
        let (start, end) =
            symbol_read::clamp_code_slice_range(file.content.len(), start_byte, end_byte);
        (
            start,
            end,
            symbol_read::code_slice_view_with(
                &target.path,
                &file.content,
                start,
                end,
                line_numbers,
            ),
        )
    };
    let bytes = file
        .content
        .get(start..end)
        .ok_or(QueryRefusalKind::InvalidSpan)?;
    row.start_byte = Some(u32::try_from(start).map_err(|_| QueryRefusalKind::InvalidSpan)?);
    row.end_byte = Some(u32::try_from(end).map_err(|_| QueryRefusalKind::InvalidSpan)?);
    row.content_hash = Some(crate::hash::digest_hex(&file.content));
    if !estimate {
        if bytes.len() > budget.remaining_bytes() {
            return Err(QueryRefusalKind::BudgetTooSmall);
        }
        row.source = Some(bytes.to_vec());
    }
    Ok((row, rendered))
}

pub(super) fn read(
    snapshot: &EmbeddedQuerySnapshot,
    request: &SymbolReadRequest,
    session: Option<&QuerySession>,
    budget: &mut Budget,
) -> Result<QueryOutput, QueryRefusalKind> {
    if request.project.as_ref().is_some_and(|project| {
        snapshot
            .root
            .to_str()
            .is_none_or(|root| project != root && *project != root.replace('\\', "/"))
    }) {
        return Err(QueryRefusalKind::AdmissionUnavailable);
    }
    let estimate = request.estimate == Some(true);
    if !estimate
        && let Some((handle, rendered)) = session
            .and_then(|session| session.symbol_read_cache_hit(snapshot, request, budget.limits()))
    {
        budget.reused_handle = Some(handle);
        return Ok(QueryOutput::SymbolRead(SymbolReadResult {
            entries: Vec::new(),
            rendered: budget.text(&rendered)?,
            cache_hit: true,
            estimated_tokens: None,
        }));
    }
    let mut targets = request.targets.clone().unwrap_or_else(|| {
        vec![SymbolTarget {
            path: request.path.clone(),
            name: Some(request.name.clone()),
            kind: request.kind.clone(),
            symbol_line: request.symbol_line,
            start_byte: None,
            end_byte: None,
        }]
    });
    let mut unresolved = None;
    if request.targets.is_none() && request.path.is_empty() {
        match symbol_read::resolve_symbol_path_by_name(
            &snapshot.generation.live,
            &request.name,
            request.kind.as_deref(),
            request.symbol_line,
        ) {
            symbol_read::SymbolNameLookup::Unique { path, symbol_name } => {
                targets[0].path = path;
                targets[0].name = Some(symbol_name);
            }
            symbol_read::SymbolNameLookup::NotFound(rendered) => {
                let mut row = entry(String::new());
                row.refusal = Some(QueryRefusalKind::NotFound);
                unresolved = Some((row, rendered));
            }
            symbol_read::SymbolNameLookup::Ambiguous(rendered, hits) => {
                let mut row = entry(String::new());
                row.refusal = Some(QueryRefusalKind::AmbiguousSymbol);
                for hit in hits {
                    let Some(file) = snapshot.generation.live.get_file(&hit.path) else {
                        continue;
                    };
                    for (index, symbol) in file.symbols.iter().enumerate() {
                        if symbol.name == hit.name
                            && symbol.line_range.0 + 1 == hit.line
                            && symbol.kind.to_string() == hit.kind
                        {
                            row.candidates.push(symbol_row(file, index, symbol)?);
                        }
                    }
                }
                unresolved = Some((row, rendered));
            }
        }
    }
    let mut entries = Vec::new();
    let mut rendered = Vec::new();
    for target_request in &targets {
        budget.check()?;
        if budget.remaining_rows() == 0 {
            budget.truncated = true;
            break;
        }
        let (mut row, text) = match unresolved.take() {
            Some(value) => value,
            None => target(
                snapshot,
                target_request,
                estimate,
                request.line_numbers,
                request.targets.is_none(),
                budget,
            )?,
        };
        let candidates = std::mem::take(&mut row.candidates);
        budget.required(super::embed_usage::decoded_bytes(&row) as usize)?;
        for candidate in candidates {
            if !budget.row(super::embed_usage::decoded_bytes(&candidate) as usize) {
                break;
            }
            row.candidates.push(candidate);
        }
        entries.push(row);
        rendered.push(text);
    }
    let rendered = rendered.join("\n\n");
    let estimated_tokens =
        estimate.then(|| crate::stel::handler::estimate_tokens_from_bytes(rendered.len() as u64));
    let mut full = SymbolReadResult {
        entries,
        rendered,
        cache_hit: false,
        estimated_tokens,
    };
    if estimate {
        full.rendered = format!("Estimated tokens: {}", estimated_tokens.unwrap_or(0));
    } else {
        // Only a read that served every target is replayed: a repeat hit has
        // no rows, so it must stand for a found read (as on MCP).
        if full.entries.iter().all(|entry| entry.refusal.is_none()) {
            budget.cache_output = Some(QueryOutput::SymbolRead(full.clone()));
            budget.cache_truncated = budget.truncated;
        }
        // FR-024: only an explicit `max_tokens` budgets a named symbol; without one the
        // hard cap and its continuation line are those of the server lane.
        let explicit = request.max_tokens.filter(|limit| *limit > 0);
        let (rendered, truncated) = match (explicit, request.targets.is_none()) {
            (None, true) => {
                let cut =
                    full.rendered.len() > super::guidance::file_read::GET_FILE_CONTENT_MAX_BYTES;
                let capped = source::enforce_default_output_cap(full.rendered, |bytes| {
                    source::symbol_read_continuation(
                        &targets[0].path,
                        targets[0].name.as_deref().unwrap_or(&request.name),
                        request.kind.as_deref(),
                        request.symbol_line,
                        bytes,
                    )
                });
                (capped, cut)
            }
            _ => source::enforce_token_budget_flagged(full.rendered, explicit),
        };
        full.rendered = rendered;
        budget.truncated |= truncated;
    }
    full.rendered = budget.text(&full.rendered)?;
    Ok(QueryOutput::SymbolRead(full))
}

pub(super) fn inspect(
    snapshot: &EmbeddedQuerySnapshot,
    request: &InspectMatchRequest,
    budget: &mut Budget,
) -> Result<QueryOutput, QueryRefusalKind> {
    super::embed_read::admit(snapshot, &request.path, None, budget)?;
    let Some(file) = snapshot.generation.live.get_file(&request.path) else {
        return Err(budget.refuse_with(
            QueryRefusalKind::NotFound,
            super::guidance::file_read::not_found_file(&request.path),
        ));
    };
    super::embed_read::admit(snapshot, &request.path, Some(&file.content), budget)?;
    let view = snapshot.generation.live.capture_inspect_match_view(
        &request.path,
        request.line,
        request.context,
        request.sibling_limit,
    );
    let rendered = symbol_read::inspect_match_result_view(&view);
    let crate::live_index::InspectMatchView::Found(found) = view else {
        return Err(budget.refuse_with(QueryRefusalKind::InvalidRequest, rendered));
    };
    let convert = |value: crate::live_index::EnclosingSymbolView| InspectionSymbol {
        name: value.name,
        kind: value.kind_label,
        start_line: value.line_range.0,
        end_line: value.line_range.1,
    };
    let mut output = InspectMatchResult {
        path: found.path,
        line: found.line,
        excerpt: found.excerpt,
        enclosing: found.enclosing.map(convert),
        parent_chain: found.parent_chain.into_iter().map(convert).collect(),
        siblings: found
            .siblings
            .into_iter()
            .map(|value| InspectionSymbol {
                name: value.name,
                kind: value.kind_label,
                start_line: value.line_range.0,
                end_line: value.line_range.1,
            })
            .collect(),
        siblings_overflow: found.siblings_overflow as u64,
        rendered: String::new(),
        estimated_tokens: (request.estimate == Some(true))
            .then(|| crate::stel::handler::estimate_tokens_from_bytes(rendered.len() as u64)),
    };
    if request.estimate == Some(true) {
        output.excerpt.clear();
    }
    budget.required(super::embed_usage::decoded_bytes(&output) as usize)?;
    let text = if let Some(tokens) = output.estimated_tokens {
        format!("Estimated tokens: {tokens}")
    } else {
        let mut full = output.clone();
        full.rendered = rendered.clone();
        budget.cache_output = Some(QueryOutput::InspectMatch(full));
        let (rendered, truncated) =
            source::enforce_token_budget_flagged(rendered, request.max_tokens);
        budget.truncated |= truncated;
        rendered
    };
    output.rendered = budget.text(&text)?;
    Ok(QueryOutput::InspectMatch(output))
}