use crate::domain::ReferenceKind;
use crate::domain::index::{AdmissionTier, SkippedFile};
use crate::live_index::{RepoOutlineFileView, RepoOutlineView};
pub fn file_tree_view(files: &[RepoOutlineFileView], path: &str, depth: u32) -> String {
let depth = depth.min(5);
let prefix = path.trim_matches('/');
let matching_files: Vec<&RepoOutlineFileView> = files
.iter()
.filter(|file| {
let p = file.relative_path.as_str();
if prefix.is_empty() {
true
} else {
p.starts_with(prefix)
&& (p.len() == prefix.len() || p.as_bytes().get(prefix.len()) == Some(&b'/'))
}
})
.collect();
if matching_files.is_empty() {
return format!(
"No source files found under '{}'",
if prefix.is_empty() { "." } else { prefix }
);
}
use std::collections::BTreeMap;
let strip_len = if prefix.is_empty() {
0
} else {
prefix.len() + 1
};
let stripped: Vec<(&str, &RepoOutlineFileView)> = matching_files
.into_iter()
.map(|file| {
let p = file.relative_path.as_str();
(
if p.len() >= strip_len {
&p[strip_len..]
} else {
p
},
file,
)
})
.collect();
fn build_lines(
entries: &[(&str, &RepoOutlineFileView)],
current_depth: u32,
max_depth: u32,
indent: usize,
) -> Vec<String> {
let mut dirs: BTreeMap<&str, Vec<(&str, &RepoOutlineFileView)>> = BTreeMap::new();
let mut files_here: Vec<(&str, &RepoOutlineFileView)> = Vec::new();
for (rel, file) in entries {
if let Some(slash) = rel.find('/') {
let dir_part = &rel[..slash];
let rest = &rel[slash + 1..];
dirs.entry(dir_part).or_default().push((rest, file));
} else {
files_here.push((rel, file));
}
}
let pad = " ".repeat(indent);
let mut lines = Vec::new();
files_here.sort_by_key(|(name, _)| *name);
for (name, file) in &files_here {
let sym_count = file.symbol_count;
let sym_label = if sym_count == 1 { "symbol" } else { "symbols" };
let tag = file.noise_class.tag();
if tag.is_empty() {
lines.push(format!(
"{}{} [{}] ({} {})",
pad, name, file.language, sym_count, sym_label
));
} else {
lines.push(format!(
"{}{} [{}] ({} {}) {}",
pad, name, file.language, sym_count, sym_label, tag
));
}
}
for (dir_name, children) in &dirs {
let file_count = count_files(children);
let sym_count: usize = children.iter().map(|(_, f)| f.symbol_count).sum();
let sym_label = if sym_count == 1 { "symbol" } else { "symbols" };
if current_depth >= max_depth {
lines.push(format!(
"{}{}/ ({} files, {} {})",
pad, dir_name, file_count, sym_count, sym_label
));
} else {
lines.push(format!(
"{}{}/ ({} files, {} {})",
pad, dir_name, file_count, sym_count, sym_label
));
let sub_lines = build_lines(children, current_depth + 1, max_depth, indent + 1);
lines.extend(sub_lines);
}
}
lines
}
fn count_files(entries: &[(&str, &RepoOutlineFileView)]) -> usize {
let mut count = 0;
for (rel, _) in entries {
if rel.contains('/') {
} else {
count += 1;
}
}
let mut dirs: std::collections::HashMap<&str, Vec<(&str, &RepoOutlineFileView)>> =
std::collections::HashMap::new();
for (rel, file) in entries {
if let Some(slash) = rel.find('/') {
dirs.entry(&rel[..slash])
.or_default()
.push((&rel[slash + 1..], file));
}
}
for children in dirs.values() {
count += count_files(children);
}
count
}
fn count_dirs(entries: &[(&str, &RepoOutlineFileView)]) -> usize {
let mut dirs: std::collections::HashSet<&str> = std::collections::HashSet::new();
let mut sub_entries: std::collections::HashMap<&str, Vec<(&str, &RepoOutlineFileView)>> =
std::collections::HashMap::new();
for (rel, file) in entries {
if let Some(slash) = rel.find('/') {
let dir_name = &rel[..slash];
dirs.insert(dir_name);
sub_entries
.entry(dir_name)
.or_default()
.push((&rel[slash + 1..], file));
}
}
let mut total = dirs.len();
for children in sub_entries.values() {
total += count_dirs(children);
}
total
}
let body_lines = build_lines(&stripped, 1, depth, 0);
let total_files = stripped.len();
let total_dirs = count_dirs(&stripped);
let total_symbols: usize = stripped.iter().map(|(_, f)| f.symbol_count).sum();
let sym_label = if total_symbols == 1 {
"symbol"
} else {
"symbols"
};
let mut output = body_lines;
output.push(format!(
"{} directories, {} files, {} {}",
total_dirs, total_files, total_symbols, sym_label
));
output.join("\n")
}
pub(crate) fn human_size(bytes: u64) -> String {
if bytes >= 1_073_741_824 {
format!("{:.1} GB", bytes as f64 / 1_073_741_824.0)
} else if bytes >= 1_048_576 {
format!("{:.1} MB", bytes as f64 / 1_048_576.0)
} else if bytes >= 1024 {
format!("{:.0} KB", bytes as f64 / 1024.0)
} else {
format!("{} B", bytes)
}
}
pub fn file_tree_view_with_skipped(
files: &[RepoOutlineFileView],
skipped: &[SkippedFile],
path: &str,
depth: u32,
) -> String {
let prefix = path.trim_matches('/');
let tier2: Vec<&SkippedFile> = skipped
.iter()
.filter(|sf| {
sf.decision.tier == AdmissionTier::MetadataOnly
&& (prefix.is_empty()
|| sf.path.starts_with(prefix)
&& (sf.path.len() == prefix.len()
|| sf.path.as_bytes().get(prefix.len()) == Some(&b'/')))
})
.collect();
let tier3_count = skipped
.iter()
.filter(|sf| {
sf.decision.tier == AdmissionTier::HardSkip
&& (prefix.is_empty()
|| sf.path.starts_with(prefix)
&& (sf.path.len() == prefix.len()
|| sf.path.as_bytes().get(prefix.len()) == Some(&b'/')))
})
.count();
let base = if tier2.is_empty() && files.is_empty() {
file_tree_view(files, path, depth)
} else {
file_tree_view(files, path, depth)
};
let mut lines: Vec<String> = base.lines().map(String::from).collect();
let footer = if lines.len() > 1 { lines.pop() } else { None };
let strip_len = if prefix.is_empty() {
0
} else {
prefix.len() + 1
};
let mut tier2_lines: Vec<(String, String)> = tier2
.iter()
.map(|sf| {
let p = sf.path.as_str();
let rel = if p.len() >= strip_len {
&p[strip_len..]
} else {
p
};
let reason = sf
.decision
.reason
.as_ref()
.map(|r| r.to_string())
.unwrap_or_else(|| "skipped".to_string());
let tag = format!("[skipped: {}, {}]", reason, human_size(sf.size));
(rel.to_string(), tag)
})
.collect();
tier2_lines.sort_by(|a, b| a.0.cmp(&b.0));
for (rel, tag) in &tier2_lines {
let depth_level = rel.chars().filter(|&c| c == '/').count();
let pad = " ".repeat(depth_level);
let filename = rel.rsplit('/').next().unwrap_or(rel.as_str());
lines.push(format!("{}{} {}", pad, filename, tag));
}
if let Some(f) = footer {
lines.push(f);
}
if tier3_count > 0 {
let artifact_label = if tier3_count == 1 {
"artifact"
} else {
"artifacts"
};
lines.push(format!(
"{} hard-skipped {} not shown (>100MB)",
tier3_count, artifact_label
));
}
lines.join("\n")
}
pub fn repo_outline_view(view: &RepoOutlineView, project_name: &str) -> String {
let mut lines = Vec::new();
lines.push(format!(
"{project_name} ({} files, {} symbols)",
view.total_files, view.total_symbols
));
let path_width = view
.files
.iter()
.map(|f| f.relative_path.len())
.max()
.unwrap_or(20)
.clamp(20, 50);
for file in &view.files {
lines.push(format!(
" {:<width$} {:<12} {} symbols",
file.relative_path,
file.language.to_string(),
file.symbol_count,
width = path_width
));
}
lines.join("\n")
}
pub fn build_with_budget(items: &[String], max_bytes: u64) -> (String, usize) {
if max_bytes == 0 || items.is_empty() {
return (items.join("\n"), 0);
}
let mut included = Vec::new();
let mut used_bytes: u64 = 0;
for (i, item) in items.iter().enumerate() {
let item_cost = item.len() as u64 + if i + 1 < items.len() { 1 } else { 0 };
if used_bytes + item_cost > max_bytes && !included.is_empty() {
let remaining = items.len() - included.len();
let mut text = included.join("\n");
text.push_str(&budget_truncation_suffix(max_bytes, remaining));
return (text, remaining);
}
used_bytes += item_cost;
included.push(item.as_str());
}
if included.len() < items.len() {
let remaining = items.len() - included.len();
let mut text = included.join("\n");
text.push_str(&budget_truncation_suffix(max_bytes, remaining));
return (text, remaining);
}
(included.join("\n"), 0)
}
const CANONICAL_TRUNCATION_MARKER: &str = "[truncated]";
fn budget_truncation_suffix(max_bytes: u64, remaining: usize) -> String {
let max_tokens = crate::stel::handler::estimate_tokens_from_bytes(max_bytes);
format!(
"\n{CANONICAL_TRUNCATION_MARKER} Truncated at ~{max_tokens} tokens. {remaining} additional output line(s) not shown."
)
}
pub(crate) fn is_intra_workspace_path(path: &str) -> bool {
if path.contains(':') || path.starts_with('/') || path.starts_with('\\') {
return false;
}
!path
.replace('\\', "/")
.split('/')
.any(|segment| segment == "..")
}
pub(crate) fn repo_map_text_for_generation(
generation: &crate::live_index::PublishedGeneration,
) -> String {
repo_map_text_scoped(generation, None, None)
}
fn map_dir_key(file_path: &str, scope: Option<&str>, depth: usize) -> Option<String> {
let normalized = file_path.replace('\\', "/");
let rest = match scope {
Some(prefix) if normalized == prefix => return Some(prefix.to_string()),
Some(prefix) => normalized.strip_prefix(prefix)?.strip_prefix('/')?,
None => normalized.as_str(),
};
let mut components: Vec<&str> = rest.split('/').collect();
components.pop(); let tail = components[..components.len().min(depth)].join("/");
Some(match (scope, tail.is_empty()) {
(Some(prefix), true) => prefix.to_string(),
(Some(prefix), false) => format!("{prefix}/{tail}"),
(None, true) => "(root)".to_string(),
(None, false) => tail,
})
}
fn map_dir_rank(dir: &str) -> u8 {
match dir.split('/').next().unwrap_or("") {
"tests" | "test" | "benches" | "examples" | "(root)" => 1,
"docs" | "doc" | "research" | "specs" | "spec" | "vendor" | "third_party"
| "node_modules" => 2,
first if first.starts_with('.') => 2,
_ => 0,
}
}
pub(crate) fn repo_map_text_scoped(
generation: &crate::live_index::PublishedGeneration,
path_scope: Option<&str>,
depth: Option<u32>,
) -> String {
let scope = path_scope
.map(|p| p.replace('\\', "/"))
.map(|p| {
let mut p = p.as_str();
while let Some(rest) = p.strip_prefix("./") {
p = rest;
}
p.trim_matches('/').to_string()
})
.filter(|p| !p.is_empty() && p != ".");
let scope = scope.as_deref();
let depth = depth.unwrap_or(2).min(5) as usize;
let guard = generation.live.as_ref();
let total_files = guard.file_count();
let total_symbols = guard.symbol_count();
let mut lang_counts: std::collections::HashMap<String, usize> =
std::collections::HashMap::new();
let mut dir_file_counts: std::collections::HashMap<String, usize> =
std::collections::HashMap::new();
let mut dir_symbol_counts: std::collections::HashMap<String, usize> =
std::collections::HashMap::new();
for (path, file) in guard.all_files() {
if !is_intra_workspace_path(path) {
continue;
}
let Some(dir) = map_dir_key(path, scope, depth) else {
continue;
};
let lang = format!("{:?}", file.language);
*lang_counts.entry(lang).or_insert(0) += 1;
*dir_file_counts.entry(dir.clone()).or_insert(0) += 1;
*dir_symbol_counts.entry(dir).or_insert(0) += file.symbols.len();
}
let mut lang_parts: Vec<String> = lang_counts
.iter()
.map(|(k, v)| format!("{}: {}", k, v))
.collect();
lang_parts.sort();
if let Some(scope) = scope
&& dir_file_counts.is_empty()
{
return format!(
"No entries under {scope} (paths are relative to the project root and case-sensitive); get_repo_map(detail=\"tree\", depth=1) lists the top-level directories."
);
}
let (total_files, total_symbols) = match scope {
Some(_) => (
dir_file_counts.values().sum(),
dir_symbol_counts.values().sum(),
),
None => (total_files, total_symbols),
};
let mut lines: Vec<String> = Vec::new();
lines.push(format!(
"Index{}: {} files, {} symbols [{}]",
scope.map(|p| format!(" under {p}")).unwrap_or_default(),
total_files,
total_symbols,
lang_parts.join(", ")
));
lines.push(String::new());
let mut dirs: Vec<String> = dir_file_counts.keys().cloned().collect();
dirs.sort_by(|a, b| {
map_dir_rank(a)
.cmp(&map_dir_rank(b))
.then_with(|| dir_symbol_counts[b].cmp(&dir_symbol_counts[a]))
.then_with(|| a.cmp(b))
});
for dir in &dirs {
let file_count = dir_file_counts[dir];
let sym_count = dir_symbol_counts[dir];
lines.push(format!(
" {:<35} {:>3} files {:>5} symbols",
dir, file_count, sym_count
));
}
let dir_rows_end = lines.len();
{
let mut entry_points: Vec<(String, String, String)> = Vec::new(); for (path, file) in guard.all_files() {
if !is_intra_workspace_path(path) || map_dir_key(path, scope, depth).is_none() {
continue;
}
let pl = path.to_ascii_lowercase();
if pl.ends_with(".md")
|| pl.contains("/docs/")
|| pl.contains("vendor/")
|| pl.contains("node_modules/")
{
continue;
}
for sym in &file.symbols {
if sym.depth == 0 {
match sym.kind {
crate::domain::SymbolKind::Struct
| crate::domain::SymbolKind::Trait
| crate::domain::SymbolKind::Interface
| crate::domain::SymbolKind::Enum
| crate::domain::SymbolKind::Class => {
entry_points.push((
sym.kind.to_string(),
sym.name.clone(),
path.to_string(),
));
}
_ => {}
}
}
}
}
if !entry_points.is_empty() {
let mut dep_counts: std::collections::HashMap<String, usize> =
std::collections::HashMap::new();
for (_, _, path) in &entry_points {
if !dep_counts.contains_key(path) {
let distinct: std::collections::HashSet<&str> = guard
.find_dependents_for_file(path)
.into_iter()
.map(|(file_path, _)| file_path)
.collect();
dep_counts.insert(path.clone(), distinct.len());
}
}
let temporal = generation.code_signals.temporal.as_ref();
let churn_of = |path: &str| -> f32 {
if generation.code_signals.state
== crate::live_index::git_temporal::GitTemporalState::Ready
{
temporal
.files
.get(path)
.map(|history| history.churn_score)
.unwrap_or(0.0)
} else {
0.0
}
};
entry_points.sort_by(|a, b| {
let (a_kind, a_name, a_path) = a;
let (b_kind, b_name, b_path) = b;
let a_dep = dep_counts.get(a_path.as_str()).copied().unwrap_or(0);
let b_dep = dep_counts.get(b_path.as_str()).copied().unwrap_or(0);
b_dep
.cmp(&a_dep)
.then_with(|| {
churn_of(b_path)
.partial_cmp(&churn_of(a_path))
.unwrap_or(std::cmp::Ordering::Equal)
})
.then_with(|| a_path.cmp(b_path))
.then_with(|| a_name.cmp(b_name))
.then_with(|| a_kind.cmp(b_kind))
});
entry_points.truncate(15);
lines.push(String::new());
lines.push("Key types:".to_string());
for (kind, name, path) in &entry_points {
let dep_count = dep_counts.get(path.as_str()).copied().unwrap_or(0);
if dep_count >= 2 {
lines.push(format!(" {kind} {name} ({path}) (→{dep_count})"));
} else {
lines.push(format!(" {kind} {name} ({path})"));
}
}
if entry_points.len() == 15 {
lines.push(" ...".to_string());
}
}
}
let (mut text, remaining) = build_with_budget(&lines, 4000);
if remaining > 0 {
let kept = lines.len() - remaining;
let omitted_dirs = dir_rows_end.saturating_sub(kept);
let omitted_types = remaining - omitted_dirs;
let mut parts = Vec::new();
if omitted_dirs > 0 {
parts.push(format!("{omitted_dirs} directory row(s)"));
}
if omitted_types > 0 {
parts.push(format!("{omitted_types} line(s) of the key-types section"));
}
text.push_str(&format!(
"\nOmitted at the 1000-token limit: {}.",
parts.join(" and ")
));
if omitted_dirs > 0 {
let next_path = scope.map(|p| format!("path=\"{p}\", ")).unwrap_or_default();
text.push_str(&format!(
" get_repo_map(detail=\"tree\", {next_path}depth={depth}) lists every directory to that level."
));
}
}
text
}
#[derive(Clone, Copy)]
pub(crate) enum ContextSourceAuthority {
DiskRefreshed,
CurrentIndex,
}
fn context_source_authority_label(authority: ContextSourceAuthority) -> &'static str {
match authority {
ContextSourceAuthority::DiskRefreshed => "disk-refreshed",
ContextSourceAuthority::CurrentIndex => "current index",
}
}
pub(crate) fn parse_state_label(file: &crate::live_index::store::IndexedFile) -> &'static str {
match &file.parse_status {
crate::live_index::store::ParseStatus::Parsed => "parsed",
crate::live_index::store::ParseStatus::PartialParse { .. } => {
if crate::live_index::query::is_expected_framework_partial_parse(file) {
return "parsed";
}
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",
}
}
pub(crate) fn format_context_envelope(
match_type: &str,
source_authority: ContextSourceAuthority,
parse_state: &str,
completeness: &str,
scope: impl Into<String>,
evidence: impl Into<String>,
) -> String {
let authority = context_source_authority_label(source_authority);
let scope = scope.into();
let evidence = evidence.into();
if authority == "current index" && parse_state == "parsed" && completeness.starts_with("full") {
format!(
"Trust: {match_type} | {authority} | {parse_state} | {completeness}\nScope: {scope}\nEvidence: {evidence}"
)
} else {
format!(
"Match type: {match_type}\nSource authority: {authority}\nParse state: {parse_state}\nCompleteness: {completeness}\nScope: {scope}\nEvidence: {evidence}"
)
}
}
pub(crate) fn append_parse_status_lines(
lines: &mut Vec<String>,
file: &crate::live_index::store::IndexedFile,
) {
match &file.parse_status {
crate::live_index::store::ParseStatus::Parsed => {}
crate::live_index::store::ParseStatus::PartialParse { warning } => {
if crate::live_index::query::is_expected_framework_partial_parse(file) {
lines.push(
"Parse status: ok (framework limitation: Angular template control-flow \
is not supported by tree-sitter-html; symbols extracted best-effort)"
.to_string(),
);
return;
}
if crate::parsing::is_expected_typescript_import_type_array_limitation(
&file.language,
&file.content,
crate::domain::LanguageId::is_tsx_path(&file.relative_path),
) {
lines.push(
"Parse status: ok (parser limitation: tree-sitter-typescript 0.23.2 \
mis-parses an import-type followed by `[]`; source is valid TypeScript)"
.to_string(),
);
return;
}
lines.push("Parse status: partial".to_string());
if let Some(diagnostic) = &file.parse_diagnostic {
lines.push(format!("Diagnostic: {}", diagnostic.summary()));
if let Some((start, end)) = diagnostic.byte_span {
lines.push(format!("Byte span: {start}..{end}"));
}
} else {
lines.push(format!("Diagnostic: {warning}"));
}
}
crate::live_index::store::ParseStatus::Failed { error } => {
lines.push("Parse status: failed".to_string());
if let Some(diagnostic) = &file.parse_diagnostic {
lines.push(format!("Diagnostic: {}", diagnostic.summary()));
if let Some((start, end)) = diagnostic.byte_span {
lines.push(format!("Byte span: {start}..{end}"));
}
} else {
lines.push(format!("Diagnostic: {error}"));
}
}
}
}
pub(crate) struct OutlineProjectionParams {
pub path: String,
pub max_tokens: Option<u64>,
pub sections: Option<Vec<String>>,
}
fn is_test_module_symbol(sym: &crate::domain::SymbolRecord) -> bool {
sym.kind == crate::domain::SymbolKind::Module
&& (sym.name == "tests" || sym.name.ends_with("_tests") || sym.name.ends_with("Tests"))
}
#[cfg(test)]
pub(crate) fn outline_text_for_generation(
published: &crate::live_index::PublishedGeneration,
params: &OutlineProjectionParams,
include_savings_footer: bool,
source_authority: ContextSourceAuthority,
) -> Option<(String, u64, u64)> {
outline_text_for_generation_with(
published,
params,
include_savings_footer,
source_authority,
true,
)
}
pub(crate) fn outline_text_for_generation_with(
published: &crate::live_index::PublishedGeneration,
params: &OutlineProjectionParams,
include_savings_footer: bool,
source_authority: ContextSourceAuthority,
include_tests: bool,
) -> Option<(String, u64, u64)> {
let guard = published.live.as_ref();
let file = guard.get_file(¶ms.path)?;
let file_bytes = file.byte_len;
let language = format!("{:?}", file.language);
let parse_state = parse_state_label(file);
let include_section = |name: &str| -> bool {
match ¶ms.sections {
None => true,
Some(list) => list.iter().any(|s| s.eq_ignore_ascii_case(name)),
}
};
let include_consumers = include_section("consumers");
let include_references = include_section("references");
let mut body_lines: Vec<String> = Vec::new();
body_lines.push(format!(
"── {} ({} symbols, {}) ──",
params.path,
file.symbols.len(),
language
));
append_parse_status_lines(&mut body_lines, file);
if let Some(ref section_list) = params.sections {
let valid = super::argument_values::FILE_CONTEXT_SECTIONS;
let unknown: Vec<&str> = section_list
.iter()
.filter(|s| !valid.iter().any(|v| s.eq_ignore_ascii_case(v)))
.map(|s| s.as_str())
.collect();
if !unknown.is_empty() {
body_lines.push(format!(
"Warning: unknown section(s): {}. Valid: {}.",
unknown.join(", "),
valid.join(", ")
));
}
}
let mut budget_omissions = false;
if include_section("outline") {
let symbol_cap = params
.max_tokens
.map(|tokens| ((tokens as usize).saturating_div(12)).max(25));
let mut counted = 0usize;
let mut omitted = 0usize;
let mut test_module: Option<(u32, bool)> = None; for sym in file.symbols.iter() {
let mut test_child = false;
if let Some((module_depth, module_rendered)) = test_module {
if sym.depth > module_depth {
if !module_rendered {
continue;
}
test_child = true;
} else {
test_module = None;
}
}
if !test_child && symbol_cap.is_some_and(|cap| counted >= cap) {
omitted += 1;
if test_module.is_none() && is_test_module_symbol(sym) {
test_module = Some((sym.depth, false));
}
continue;
}
if !test_child {
counted += 1;
}
if test_module.is_none() && is_test_module_symbol(sym) {
test_module = Some((sym.depth, true));
}
let indent = " ".repeat(sym.depth as usize);
let kind_str = sym.kind.to_string();
let display_name = if sym.name.starts_with(&format!("{} ", kind_str)) {
&sym.name[kind_str.len() + 1..]
} else {
&sym.name[..]
};
body_lines.push(format!(
"{} {:<10} {} L{}-{}",
indent,
kind_str,
display_name,
sym.line_range.0 + 1,
sym.line_range.1 + 1,
));
}
if omitted > 0 {
budget_omissions = true;
body_lines.push(format!(
" ...omitted {omitted} symbols due to budget; pass a larger max_tokens or request get_file_content(start_line,end_line) for exact text"
));
}
}
if include_section("imports") {
let mut import_sources: std::collections::HashMap<&str, usize> =
std::collections::HashMap::new();
for reference in &file.references {
if reference.kind == ReferenceKind::Import {
let source = reference
.qualified_name
.as_deref()
.unwrap_or(&reference.name);
*import_sources.entry(source).or_insert(0) += 1;
}
}
if !import_sources.is_empty() {
let mut sorted: Vec<_> = import_sources.into_iter().collect();
sorted.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(b.0)));
body_lines.push(String::new());
body_lines.push(format!("Imports from ({} sources):", sorted.len()));
for (source, count) in sorted.iter().take(10) {
body_lines.push(format!(" {} ({} symbols)", source, count));
}
if sorted.len() > 10 {
body_lines.push(format!(" ...and {} more", sorted.len() - 10));
}
}
}
let attributed_dependents = if include_consumers || include_references {
guard.find_dependents_for_file(¶ms.path)
} else {
Vec::new()
};
if include_consumers {
let mut consumers: std::collections::HashMap<&str, usize> =
std::collections::HashMap::new();
for (file_path, _) in &attributed_dependents {
*consumers.entry(*file_path).or_insert(0) += 1;
}
if !consumers.is_empty() {
let mut sorted: Vec<_> = consumers.into_iter().collect();
sorted.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(b.0)));
body_lines.push(String::new());
body_lines.push(format!("Used by ({} files):", sorted.len()));
for (consumer, count) in sorted.iter().take(10) {
body_lines.push(format!(" {} ({} refs)", consumer, count));
}
if sorted.len() > 10 {
body_lines.push(format!(" ...and {} more", sorted.len() - 10));
}
}
}
if include_references {
let mut symbol_callers: Vec<(String, Vec<(String, u32)>)> = Vec::new();
for sym in &file.symbols {
let external_callers: Vec<(String, u32)> = attributed_dependents
.iter()
.filter(|(_, reference)| {
reference.kind != ReferenceKind::Import && reference.name == sym.name
})
.map(|(fp, r)| (fp.to_string(), r.line_range.0 + 1))
.take(3)
.collect();
if !external_callers.is_empty() {
symbol_callers.push((sym.name.clone(), external_callers));
}
}
symbol_callers.sort_by_key(|(_, callers)| std::cmp::Reverse(callers.len()));
symbol_callers.truncate(5);
if !symbol_callers.is_empty() {
body_lines.push(String::new());
body_lines.push("Key references:".to_string());
for (sym_name, callers) in &symbol_callers {
body_lines.push(format!(" {}()", sym_name));
for (caller_file, caller_line) in callers {
body_lines.push(format!(" {} line {}", caller_file, caller_line));
}
}
}
}
if include_section("git") {
use crate::live_index::git_temporal::{
GitTemporalState, churn_bar, churn_label, relative_time,
};
let temporal = &published.code_signals.temporal;
if temporal.state == GitTemporalState::Ready
&& let Some(history) = temporal.files.get(¶ms.path)
{
body_lines.push(String::new());
body_lines.push(format!(
"Git activity: {} {:.2} ({}) {} commits, last {}",
churn_bar(history.churn_score),
history.churn_score,
churn_label(history.churn_score),
history.commit_count,
relative_time(history.last_commit.days_ago),
));
body_lines.push(format!(
" Last: {} \"{}\" ({}, {})",
history.last_commit.hash,
history.last_commit.message_head,
history.last_commit.author,
history.last_commit.timestamp,
));
if !history.contributors.is_empty() {
let owners: Vec<String> = history
.contributors
.iter()
.map(|c| format!("{} {:.0}%", c.author, c.percentage))
.collect();
body_lines.push(format!(" Owners: {}", owners.join(", ")));
}
if !history.co_changes.is_empty() {
body_lines.push(" Co-changes:".to_string());
for entry in &history.co_changes {
body_lines.push(format!(
" {} ({:.2} coupling, {} shared commits)",
entry.path, entry.coupling_score, entry.shared_commits,
));
}
}
}
}
let max_bytes = match params.max_tokens {
Some(n) => n * 4,
None if include_savings_footer => 200 * 4, None => 0, };
if !include_tests {
let collapsed = collapse_large_test_modules(body_lines.join("\n"), false, None);
body_lines = collapsed.lines().map(str::to_string).collect();
}
let (body_text, remaining) = build_with_budget(&body_lines, max_bytes);
let completeness = if remaining > 0 || budget_omissions {
"budget-limited"
} else {
"full"
};
let scope = match ¶ms.sections {
Some(sections) if !sections.is_empty() => {
format!("path `{}`; sections {}", params.path, sections.join(", "))
}
_ => format!("path `{}`; all sections", params.path),
};
let envelope = format_context_envelope(
"exact",
source_authority,
parse_state,
completeness,
scope,
format!("file anchor `{}`", params.path),
);
let mut text = format!("{envelope}\n\n{body_text}");
let output_bytes = text.len() as u64;
if include_savings_footer {
text.push_str(&compact_savings_footer(
output_bytes as usize,
file_bytes as usize,
));
}
Some((text, file_bytes, output_bytes))
}
use super::file_read::{
COMPETENT_READ_WINDOW_LINES, SMALL_FILE_CHAR_THRESHOLD, competent_manual_baseline_chars,
};
pub const SMALL_FILE_LINE_THRESHOLD: usize = 50;
pub fn indexed_file_line_count(content: &[u8]) -> usize {
if content.is_empty() {
return 0;
}
content.iter().filter(|&&b| b == b'\n').count() + 1
}
pub fn is_small_indexed_file(content_len: usize, line_count: usize) -> bool {
content_len < SMALL_FILE_CHAR_THRESHOLD || line_count <= SMALL_FILE_LINE_THRESHOLD
}
pub fn saved_tokens_whole_file(response_chars: usize, raw_chars: usize) -> u64 {
if raw_chars <= response_chars || raw_chars < SMALL_FILE_CHAR_THRESHOLD {
return 0;
}
crate::stel::handler::estimate_tokens_from_bytes(raw_chars.saturating_sub(response_chars) as u64)
}
pub fn saved_tokens_vs_competent_manual(response_chars: usize, raw_chars: usize) -> u64 {
let baseline = competent_manual_baseline_chars(raw_chars);
if baseline <= response_chars {
return 0;
}
crate::stel::handler::estimate_tokens_from_bytes(baseline.saturating_sub(response_chars) as u64)
}
pub fn compact_savings_footer(response_chars: usize, raw_chars: usize) -> String {
if raw_chars <= response_chars || raw_chars < SMALL_FILE_CHAR_THRESHOLD {
return String::new();
}
let whole_saved = saved_tokens_whole_file(response_chars, raw_chars);
let window_saved = saved_tokens_vs_competent_manual(response_chars, raw_chars);
if whole_saved < 50 && window_saved < 10 {
return String::new();
}
let mut parts = Vec::new();
if whole_saved >= 50 {
parts.push(format!(
"~{whole_saved} tokens estimated vs whole-file read"
));
}
if window_saved >= 10 {
parts.push(format!(
"~{window_saved} tokens estimated vs ~{COMPETENT_READ_WINDOW_LINES}-line windowed read (assumed baseline, not measured)"
));
}
if parts.is_empty() {
return String::new();
}
format!("\n\n{}", parts.join("; "))
}
pub fn collapse_large_test_modules(
text: String,
include_tests: bool,
sections: Option<&[String]>,
) -> String {
let _ = sections;
if include_tests {
return text;
}
let lines: Vec<&str> = text.lines().collect();
let mut collapsed = Vec::with_capacity(lines.len());
let mut index = 0;
while index < lines.len() {
let line = lines[index];
let Some((module_indent, module_name)) = parse_test_module_outline_line(line) else {
collapsed.push(line.to_string());
index += 1;
continue;
};
let mut cursor = index + 1;
let mut test_function_count = 0usize;
while cursor < lines.len() {
let child = lines[cursor];
if child.trim().is_empty() || leading_space_count(child) <= module_indent {
break;
}
if child.trim_start().starts_with("fn") {
test_function_count += 1;
}
cursor += 1;
}
if test_function_count > 0 {
collapsed.push(line.to_string());
collapsed.push(format!(
"{} ... test module `{}` collapsed: {} functions not shown (pass include_tests=true to expand)",
" ".repeat(module_indent),
module_name,
test_function_count
));
index = cursor;
} else {
collapsed.push(line.to_string());
index += 1;
}
}
let mut result = collapsed.join("\n");
if text.ends_with('\n') {
result.push('\n');
}
result
}
fn parse_test_module_outline_line(line: &str) -> Option<(usize, &str)> {
let trimmed = line.trim_start();
let mut parts = trimmed.split_whitespace();
if parts.next()? != "mod" {
return None;
}
let name = parts.next()?;
if name == "tests" || name.ends_with("_tests") || name.ends_with("Tests") {
Some((leading_space_count(line), name))
} else {
None
}
}
fn leading_space_count(line: &str) -> usize {
line.bytes().take_while(|byte| *byte == b' ').count()
}
pub(crate) fn withheld_listing(
unverified: &std::collections::BTreeMap<String, String>,
scope: Option<&str>,
limit: usize,
) -> Option<(usize, String)> {
let in_scope: Vec<&str> = unverified
.keys()
.map(String::as_str)
.filter(|path| {
scope.is_none_or(|scope| {
path.strip_prefix(scope)
.is_some_and(|rest| rest.is_empty() || rest.starts_with('/'))
})
})
.collect();
if in_scope.is_empty() {
return None;
}
let mut listed = in_scope
.iter()
.take(limit)
.copied()
.collect::<Vec<_>>()
.join(", ");
if in_scope.len() > limit {
listed.push_str(&format!(" (+{} more)", in_scope.len() - limit));
}
Some((in_scope.len(), listed))
}
pub fn withheld_not_searched_note(
unverified: &std::collections::BTreeMap<String, String>,
scope: Option<&str>,
) -> Option<String> {
let (count, listed) = withheld_listing(unverified, scope, 5)?;
Some(format!(
"Note: {count} files withheld as unverified since restore were not searched: {listed}. \
A successful re-read releases each one, and index_folder rebuilds the project from source."
))
}
#[cfg(test)]
mod tests {
use std::fs;
use tempfile::TempDir;
use super::*;
use crate::index_lifecycle::guidance::file_read::resolve_read_max_tokens;
use crate::live_index::LiveIndex;
#[test]
fn d1_file_context_budget_resolution_pins_all_three_input_shapes() {
let raw_chars = 8_000usize;
for knowledge_requested in [true, false] {
let budget = resolve_read_max_tokens(
Some(400).or_else(|| knowledge_requested.then_some(1000)),
raw_chars,
);
assert_eq!(budget, 400);
}
let budget_default_sections =
resolve_read_max_tokens(None.or_else(|| true.then_some(1000)), raw_chars);
assert_eq!(budget_default_sections, 1000);
let budget_outline_large =
resolve_read_max_tokens(None.or_else(|| false.then_some(1000)), raw_chars);
assert_eq!(budget_outline_large, 1000);
let budget_outline_tiny =
resolve_read_max_tokens(None.or_else(|| false.then_some(1000)), 120);
assert_eq!(budget_outline_tiny, 64);
}
#[test]
fn d3_outline_projection_caps_symbols_when_budgeted_and_stays_unbudgeted_when_none() {
let root = TempDir::new().unwrap();
fs::create_dir_all(root.path().join("src")).unwrap();
let mut source = String::new();
for index in 0..40 {
source.push_str(&format!(
"pub fn item_{index:02}() -> usize {{ {index} }}\n"
));
}
fs::write(root.path().join("src/lib.rs"), &source).unwrap();
let shared = LiveIndex::load(root.path()).unwrap();
let published = shared.published_generation();
let budgeted_params = OutlineProjectionParams {
path: "src/lib.rs".to_string(),
max_tokens: Some(100),
sections: Some(vec!["outline".to_string()]),
};
let (budgeted_text, _, _) = outline_text_for_generation(
&published,
&budgeted_params,
false,
ContextSourceAuthority::CurrentIndex,
)
.expect("indexed file should render budgeted outline");
assert!(
budgeted_text.contains("Completeness: budget-limited"),
"Some(budget) must enforce symbol/byte cap: {budgeted_text}"
);
assert!(
budgeted_text.contains("[truncated]")
|| budgeted_text.contains("...omitted 15 symbols due to budget"),
"Some(100) must enforce the 100-token budget cap: {budgeted_text}"
);
assert!(!budgeted_text.contains("item_39"));
let unbudgeted_params = OutlineProjectionParams {
path: "src/lib.rs".to_string(),
max_tokens: None,
sections: Some(vec!["outline".to_string()]),
};
let (unbudgeted_text, _, _) = outline_text_for_generation(
&published,
&unbudgeted_params,
false,
ContextSourceAuthority::CurrentIndex,
)
.expect("indexed file should render unbudgeted outline");
assert!(
unbudgeted_text.contains("Trust: exact | current index | parsed | full"),
"None with include_savings_footer=false must leave direct projection unbudgeted: {unbudgeted_text}"
);
assert!(unbudgeted_text.contains("item_00"));
assert!(unbudgeted_text.contains("item_39"));
}
}