projectatlas/

structural.rs

//! Deterministic structural summaries for files without declaration symbols.

use cssparser::{Parser as CssParser, ParserInput as CssParserInput, Token as CssToken};
use jsonc_parser::{ParseOptions as JsoncParseOptions, parse_to_serde_value};
use projectatlas_core::language::{StructuralSummaryOwner, language_capability};
use projectatlas_symbols::{MarkdownFacts, extract_markdown_facts};
use scraper::{Html, Selector};
use serde_json::Value as JsonValue;
use std::collections::BTreeSet;
use toml::Value as TomlValue;
use yaml_rust2::{Yaml, YamlLoader};

/// Maximum named items rendered into one structural summary list.
const LIST_LIMIT: usize = 4;

/// Maximum characters retained for a single extracted label.
const LABEL_LIMIT: usize = 80;

/// Build a deterministic one-line structural summary for an indexed file.
pub(crate) fn structural_summary_for_path(
    path: &str,
    language: Option<&str>,
    content: &str,
) -> Option<String> {
    let owner = structural_summary_owner(path, language)?;
    match owner {
        StructuralSummaryOwner::Markdown => markdown_summary(content),
        StructuralSummaryOwner::Json => json_summary(path, content),
        StructuralSummaryOwner::Yaml => yaml_summary(path, content),
        StructuralSummaryOwner::Toml => toml_summary(path, content),
        StructuralSummaryOwner::Xml => xml_summary(content),
        StructuralSummaryOwner::Css => css_summary(content),
        StructuralSummaryOwner::Html => html_summary(content),
        StructuralSummaryOwner::Toon => toon_summary(content),
        StructuralSummaryOwner::PowerShell => powershell_summary(content),
        StructuralSummaryOwner::ConfigText => config_text_summary(path, content),
    }
}

/// Return whether a file family has a lightweight structural adapter.
pub(crate) fn is_structural_summary_candidate(path: &str, language: Option<&str>) -> bool {
    structural_summary_owner(path, language).is_some()
}

/// Select the registry-owned structural adapter, with legacy TOON inference when undetected.
fn structural_summary_owner(path: &str, language: Option<&str>) -> Option<StructuralSummaryOwner> {
    match language {
        Some(language) => {
            language_capability(language).and_then(|capability| capability.structural_summary)
        }
        None => has_extension(path, "toon").then_some(StructuralSummaryOwner::Toon),
    }
}

/// Return whether a repository path has a case-insensitive extension.
fn has_extension(path: &str, extension: &str) -> bool {
    path.rsplit(['/', '\\'])
        .next()
        .and_then(|file_name| file_name.rsplit_once('.').map(|(_stem, ext)| ext))
        .is_some_and(|ext| ext.eq_ignore_ascii_case(extension))
}

/// Return whether a stored summary is still only the scanner byte fallback.
pub(crate) fn is_scanner_fallback_summary(summary: &str) -> bool {
    let trimmed = summary.trim_end_matches('.');
    let Some((_, tail)) = trimmed.rsplit_once(", ") else {
        return false;
    };
    let Some(number) = tail.strip_suffix(" bytes") else {
        return false;
    };
    !number.is_empty() && number.chars().all(|character| character.is_ascii_digit())
}

/// Summarize a bounded literal excerpt without inferring document headings or titles.
pub(crate) fn document_summary_from_facts(facts: &projectatlas_symbols::DocumentFacts) -> String {
    let prefix = facts
        .text
        .split_whitespace()
        .flat_map(|word| word.chars().chain(std::iter::once(' ')))
        .take(LABEL_LIMIT + 1)
        .collect::<String>();
    let excerpt = prefix.trim_end();
    let incomplete = matches!(
        facts.completeness,
        projectatlas_symbols::DocumentCompleteness::Partial { .. }
    );
    if excerpt.is_empty() {
        if incomplete {
            format!("{} document with incomplete text coverage.", facts.format)
        } else {
            format!("{} document with no extracted text.", facts.format)
        }
    } else {
        let excerpt = if excerpt.chars().count() > LABEL_LIMIT {
            truncate_chars(excerpt, LABEL_LIMIT)
        } else {
            excerpt.to_owned()
        };
        if incomplete {
            format!(
                "{} document text (incomplete coverage): {excerpt}",
                facts.format
            )
        } else {
            format!("{} document text: {excerpt}", facts.format)
        }
    }
}

/// Summarize a Markdown or MDX document from parsed `CommonMark` headings.
fn markdown_summary(content: &str) -> Option<String> {
    markdown_summary_from_facts(
        &extract_markdown_facts(content),
        content
            .lines()
            .filter(|line| !line.trim().is_empty())
            .count(),
    )
}

/// Reuse one bounded Markdown parse for structural summary projection.
pub(crate) fn markdown_summary_from_facts(
    facts: &MarkdownFacts,
    non_empty_lines: usize,
) -> Option<String> {
    let headings = &facts.headings;
    if headings.is_empty() {
        return (non_empty_lines > 0)
            .then(|| format!("markdown document with {non_empty_lines} non-empty lines."));
    }
    let title = headings
        .iter()
        .find(|heading| heading.level == 1)
        .unwrap_or(&headings[0]);
    let title_text = compact_label(&title.text);
    let section_names = headings
        .iter()
        .filter(|heading| heading.text != title.text)
        .map(|heading| compact_label(&heading.text))
        .collect::<Vec<_>>();
    if section_names.is_empty() {
        Some(format!("markdown document titled {title_text}."))
    } else {
        Some(format!(
            "markdown document titled {} with sections {}.",
            title_text,
            join_limited(section_names.iter().map(String::as_str).collect())
        ))
    }
}

/// Summarize JSON and JSONC files from parsed object structure.
fn json_summary(path: &str, content: &str) -> Option<String> {
    let value: JsonValue = parse_to_serde_value(content, &JsoncParseOptions::default()).ok()?;
    let object = value.as_object()?;
    if path.ends_with("package.json") {
        return Some(package_json_summary(object));
    }
    let keys = object.keys().map(String::as_str).collect::<Vec<_>>();
    if object.contains_key("datasets") || path.ends_with("datasets.manifest.json") {
        let (dataset_count, dataset_ids) = dataset_manifest_facts(object.get("datasets"));
        let key_list = join_limited(keys);
        if dataset_ids.is_empty() {
            return Some(format!(
                "json dataset manifest with {dataset_count} datasets and keys {key_list}."
            ));
        }
        return Some(format!(
            "json dataset manifest with {dataset_count} datasets including {} and keys {key_list}.",
            join_limited(dataset_ids.iter().map(String::as_str).collect())
        ));
    }
    if keys.is_empty() {
        None
    } else {
        Some(format!(
            "json document with top-level keys {}.",
            join_limited(keys)
        ))
    }
}

/// Extract dataset count and bounded identifiers from common manifest shapes.
fn dataset_manifest_facts(value: Option<&JsonValue>) -> (usize, Vec<String>) {
    let Some(value) = value else {
        return (0, Vec::new());
    };
    if let Some(object) = value.as_object() {
        let ids = object.keys().cloned().collect::<Vec<_>>();
        return (ids.len(), ids);
    }
    let Some(array) = value.as_array() else {
        return (0, Vec::new());
    };
    let ids = array
        .iter()
        .filter_map(|item| {
            item.as_object().and_then(|object| {
                object
                    .get("id")
                    .or_else(|| object.get("name"))
                    .and_then(JsonValue::as_str)
                    .map(compact_label)
            })
        })
        .collect::<Vec<_>>();
    (array.len(), ids)
}

/// Build a package.json summary from common manifest keys.
fn package_json_summary(object: &serde_json::Map<String, JsonValue>) -> String {
    let name = object
        .get("name")
        .and_then(JsonValue::as_str)
        .map_or_else(|| "unnamed package".to_string(), compact_label);
    let script_names = object_keys(object.get("scripts"));
    let dependency_names = object_keys(object.get("dependencies"));
    let dev_dependency_names = object_keys(object.get("devDependencies"));
    let dependencies = dependency_names
        .len()
        .saturating_add(dev_dependency_names.len());
    if script_names.is_empty() && dependencies == 0 {
        format!("package manifest for {name}.")
    } else if script_names.is_empty() {
        format!("package manifest for {name} with {dependencies} dependencies.")
    } else {
        format!(
            "package manifest for {name} with scripts {} and {dependencies} dependencies.",
            join_limited(script_names.iter().map(String::as_str).collect())
        )
    }
}

/// Return sorted object keys for a JSON object value.
fn object_keys(value: Option<&JsonValue>) -> Vec<String> {
    let mut keys = value
        .and_then(JsonValue::as_object)
        .map(|object| object.keys().cloned().collect::<Vec<_>>())
        .unwrap_or_default();
    keys.sort();
    keys
}

/// Summarize YAML files, including GitHub Actions workflow structure.
fn yaml_summary(path: &str, content: &str) -> Option<String> {
    let document = YamlLoader::load_from_str(content)
        .ok()?
        .into_iter()
        .next()?;
    let keys = yaml_mapping_keys(&document);
    let jobs = yaml_child_mapping_keys(&document, "jobs");
    let triggers = yaml_triggers(&document);
    let workflow_name = yaml_scalar_value(&document, "name");
    if path.contains(".github/workflows/") || (!jobs.is_empty() && !triggers.is_empty()) {
        let name = workflow_name
            .as_deref()
            .map_or_else(|| "unnamed workflow".to_string(), compact_label);
        return Some(format!(
            "yaml workflow {name} triggered by {} with jobs {}.",
            join_limited(triggers.iter().map(String::as_str).collect()),
            join_limited(jobs.iter().map(String::as_str).collect())
        ));
    }
    if keys.is_empty() {
        None
    } else {
        Some(format!(
            "yaml document with top-level keys {}.",
            join_limited(keys.iter().map(String::as_str).collect())
        ))
    }
}

/// Extract mapping keys from a YAML node.
fn yaml_mapping_keys(value: &Yaml) -> Vec<String> {
    let mut keys = value
        .as_hash()
        .map(|hash| {
            hash.iter()
                .filter_map(|(key, _value)| key.as_str().map(compact_label))
                .collect::<Vec<_>>()
        })
        .unwrap_or_default();
    keys.sort();
    keys.dedup();
    keys
}

/// Extract child mapping keys from a top-level YAML key.
fn yaml_child_mapping_keys(value: &Yaml, key: &str) -> Vec<String> {
    yaml_mapping_keys(&value[key])
}

/// Extract GitHub Actions trigger names from a YAML document.
fn yaml_triggers(value: &Yaml) -> Vec<String> {
    let trigger = &value["on"];
    if let Some(trigger) = trigger.as_str() {
        return trigger
            .trim_matches(['[', ']'])
            .split(',')
            .map(str::trim)
            .filter(|item| !item.is_empty())
            .map(compact_label)
            .collect();
    }
    if let Some(triggers) = trigger.as_vec() {
        return triggers
            .iter()
            .filter_map(Yaml::as_str)
            .map(compact_label)
            .collect();
    }
    yaml_mapping_keys(trigger)
}

/// Extract a scalar string for a top-level YAML key.
fn yaml_scalar_value(value: &Yaml, key: &str) -> Option<String> {
    value[key].as_str().map(ToString::to_string)
}

/// Summarize TOML configuration and manifest files.
fn toml_summary(path: &str, content: &str) -> Option<String> {
    let value = toml::from_str::<TomlValue>(content).ok()?;
    let table = value.as_table()?;
    let keys = table.keys().map(String::as_str).collect::<Vec<_>>();
    if path.ends_with("Cargo.toml") {
        let package = table
            .get("package")
            .and_then(TomlValue::as_table)
            .and_then(|package| package.get("name"))
            .and_then(TomlValue::as_str)
            .map_or_else(|| "workspace".to_string(), compact_label);
        return Some(format!(
            "cargo manifest for {package} with tables {}.",
            join_limited(keys)
        ));
    }
    if path.ends_with(".projectatlas/config.toml") || path.ends_with("projectatlas.toml") {
        let excludes = table
            .get("scan")
            .and_then(TomlValue::as_table)
            .map_or(0, toml_scan_exclude_count);
        return Some(format!(
            "ProjectAtlas config with tables {} and {excludes} scan excludes.",
            join_limited(keys)
        ));
    }
    if keys.is_empty() {
        None
    } else {
        Some(format!("toml document with tables {}.", join_limited(keys)))
    }
}

/// Count configured scan exclude entries in a TOML scan table.
fn toml_scan_exclude_count(scan: &toml::map::Map<String, TomlValue>) -> usize {
    ["exclude_dir_names", "exclude_path_prefixes"]
        .iter()
        .filter_map(|key| scan.get(*key))
        .filter_map(TomlValue::as_array)
        .map(Vec::len)
        .sum()
}

/// Summarize CSS-like stylesheets from parser tokens.
fn css_summary(content: &str) -> Option<String> {
    let mut input = CssParserInput::new(content);
    let mut parser = CssParser::new(&mut input);
    let mut facts = CssFacts::default();
    scan_css_tokens(&mut parser, CssMode::StyleSheet, &mut facts);
    if facts.selectors.is_empty() && facts.custom_properties.is_empty() {
        return None;
    }
    let selector_list = facts
        .selectors
        .iter()
        .map(String::as_str)
        .collect::<Vec<_>>();
    let property_list = facts
        .custom_properties
        .iter()
        .map(String::as_str)
        .collect::<Vec<_>>();
    Some(format!(
        "css stylesheet with selectors {}, custom properties {}, {} media queries, and {} supports queries.",
        join_or_none(selector_list),
        join_or_none(property_list),
        facts.media_queries,
        facts.supports_queries
    ))
}

/// CSS parser traversal mode.
#[derive(Clone, Copy, Eq, PartialEq)]
enum CssMode {
    /// Parse rule preludes as stylesheet selectors.
    StyleSheet,
    /// Parse rule bodies as declarations.
    DeclarationBlock,
}

/// Kind of CSS rule prelude most recently seen.
#[derive(Clone, Copy, Eq, PartialEq)]
enum CssRuleKind {
    /// No rule prelude has been classified yet.
    None,
    /// The prelude is an `@media` rule.
    Media,
    /// The prelude is an `@supports` rule.
    Supports,
    /// The prelude is a qualified selector rule.
    Qualified,
}

/// Structural facts extracted from CSS tokens.
#[derive(Default)]
struct CssFacts {
    /// Selector labels from qualified rules.
    selectors: BTreeSet<String>,
    /// Custom property names declared in rule bodies.
    custom_properties: BTreeSet<String>,
    /// Number of media query at-rules.
    media_queries: usize,
    /// Number of supports query at-rules.
    supports_queries: usize,
}

/// Walk CSS parser tokens and collect stable structural facts.
fn scan_css_tokens(parser: &mut CssParser<'_, '_>, mode: CssMode, facts: &mut CssFacts) {
    let mut pending_delimiter: Option<char> = None;
    let mut after_colon = false;
    let mut rule_kind = CssRuleKind::None;
    while let Ok(token) = parser.next_including_whitespace_and_comments().cloned() {
        match token {
            CssToken::AtKeyword(name) => {
                if name.eq_ignore_ascii_case("media") {
                    facts.media_queries = facts.media_queries.saturating_add(1);
                    rule_kind = CssRuleKind::Media;
                } else if name.eq_ignore_ascii_case("supports") {
                    facts.supports_queries = facts.supports_queries.saturating_add(1);
                    rule_kind = CssRuleKind::Supports;
                }
            }
            CssToken::IDHash(name) | CssToken::Hash(name) if mode == CssMode::StyleSheet => {
                facts.selectors.insert(format!("#{}", compact_label(&name)));
                rule_kind = CssRuleKind::Qualified;
            }
            CssToken::Delim('.') if mode == CssMode::StyleSheet => {
                pending_delimiter = Some('.');
            }
            CssToken::Colon if mode == CssMode::StyleSheet => {
                after_colon = true;
            }
            CssToken::Ident(name) => {
                let name = name.as_ref();
                if name.starts_with("--") {
                    facts.custom_properties.insert(compact_label(name));
                } else if mode == CssMode::StyleSheet {
                    if let Some(delimiter) = pending_delimiter.take() {
                        facts
                            .selectors
                            .insert(format!("{delimiter}{}", compact_label(name)));
                        rule_kind = CssRuleKind::Qualified;
                    } else if after_colon {
                        facts.selectors.insert(format!(":{}", compact_label(name)));
                        rule_kind = CssRuleKind::Qualified;
                    } else if is_css_type_selector(name) {
                        facts.selectors.insert(compact_label(name));
                        rule_kind = CssRuleKind::Qualified;
                    }
                    after_colon = false;
                }
            }
            CssToken::Comma if mode == CssMode::StyleSheet => {
                after_colon = false;
                pending_delimiter = None;
            }
            CssToken::CurlyBracketBlock => {
                let nested_mode = if matches!(rule_kind, CssRuleKind::Media | CssRuleKind::Supports)
                {
                    CssMode::StyleSheet
                } else {
                    CssMode::DeclarationBlock
                };
                let nested_result: Result<(), cssparser::ParseError<'_, ()>> = parser
                    .parse_nested_block(|nested| {
                        scan_css_tokens(nested, nested_mode, facts);
                        Ok(())
                    });
                drop(nested_result);
                after_colon = false;
                pending_delimiter = None;
                rule_kind = CssRuleKind::None;
            }
            _ => {}
        }
    }
}

/// Return whether an identifier is a useful type selector label.
fn is_css_type_selector(name: &str) -> bool {
    matches!(
        name.to_ascii_lowercase().as_str(),
        "body" | "html" | "main" | "section" | "article" | "header" | "footer"
    )
}

/// Summarize HTML documents from parsed title, metadata, headings, and structured data.
fn html_summary(content: &str) -> Option<String> {
    let document = Html::parse_document(content);
    let title = first_html_text(&document, "title");
    let description = first_html_attribute(
        &document,
        "meta[name=\"description\"], meta[property=\"description\"], meta[property=\"og:description\"]",
        "content",
    );
    let headings = html_texts(&document, "h1, h2", LIST_LIMIT);
    let link_rels = html_link_rel_values(&document, LIST_LIMIT);
    let has_structured_data = html_select(&document, "script[type=\"application/ld+json\"]")
        .is_some_and(|selector| document.select(&selector).next().is_some());
    if title.is_none()
        && description.is_none()
        && headings.is_empty()
        && link_rels.is_empty()
        && !has_structured_data
    {
        return None;
    }
    let mut parts = Vec::new();
    if let Some(title) = title {
        parts.push(format!("title {title}"));
    }
    if let Some(description) = description {
        parts.push(format!("meta description {description}"));
    }
    if !headings.is_empty() {
        parts.push(format!(
            "headings {}",
            join_limited(headings.iter().map(String::as_str).collect())
        ));
    }
    if !link_rels.is_empty() {
        parts.push(format!(
            "link rels {}",
            join_limited(link_rels.iter().map(String::as_str).collect())
        ));
    }
    if has_structured_data {
        parts.push("structured data".to_string());
    }
    Some(format!("html document with {}.", parts.join(", ")))
}

/// Extract bounded link relation markers from an HTML document.
fn html_link_rel_values(document: &Html, limit: usize) -> Vec<String> {
    let Some(selector) = html_select(document, "link[rel]") else {
        return Vec::new();
    };
    let mut rels = document
        .select(&selector)
        .filter_map(|element| element.attr("rel"))
        .flat_map(|value| {
            value
                .split_ascii_whitespace()
                .map(compact_label)
                .collect::<Vec<_>>()
        })
        .filter(|value| !value.is_empty())
        .collect::<BTreeSet<_>>()
        .into_iter()
        .collect::<Vec<_>>();
    rels.truncate(limit);
    rels
}

/// Summarize `PowerShell` scripts from declared function names.
fn powershell_summary(content: &str) -> Option<String> {
    let functions = content
        .lines()
        .filter_map(powershell_function_name)
        .collect::<BTreeSet<_>>()
        .into_iter()
        .collect::<Vec<_>>();
    if !functions.is_empty() {
        return Some(format!(
            "powershell script defining functions {}.",
            join_limited(functions.iter().map(String::as_str).collect())
        ));
    }
    let lines = content
        .lines()
        .filter(|line| !line.trim().is_empty())
        .count();
    (lines > 0).then(|| format!("powershell script with {lines} non-empty lines."))
}

/// Extract one `PowerShell` function declaration name.
fn powershell_function_name(line: &str) -> Option<String> {
    let trimmed = line.trim_start();
    let mut parts = trimmed.split_whitespace();
    if !parts.next()?.eq_ignore_ascii_case("function") {
        return None;
    }
    let raw_name = parts.next()?;
    let name = raw_name.split(['(', '{']).next().unwrap_or_default().trim();
    let name = name.rsplit_once(':').map_or(name, |(_, scoped)| scoped);
    let valid = !name.is_empty()
        && name
            .chars()
            .all(|character| character.is_ascii_alphanumeric() || matches!(character, '_' | '-'));
    valid.then(|| compact_label(name))
}

/// Compile an HTML selector.
fn html_select(_document: &Html, selector: &str) -> Option<Selector> {
    Selector::parse(selector).ok()
}

/// Extract first text value for an HTML selector.
fn first_html_text(document: &Html, selector: &str) -> Option<String> {
    html_texts(document, selector, 1).into_iter().next()
}

/// Extract text values for an HTML selector.
fn html_texts(document: &Html, selector: &str, limit: usize) -> Vec<String> {
    let Some(selector) = html_select(document, selector) else {
        return Vec::new();
    };
    document
        .select(&selector)
        .filter_map(|element| {
            let text = element.text().collect::<Vec<_>>().join(" ");
            let text = compact_label(&text);
            (!text.is_empty()).then_some(text)
        })
        .take(limit)
        .collect()
}

/// Extract one attribute from the first matching HTML element.
fn first_html_attribute(document: &Html, selector: &str, attribute: &str) -> Option<String> {
    let selector = html_select(document, selector)?;
    document
        .select(&selector)
        .find_map(|element| element.attr(attribute))
        .map(compact_label)
}

/// Summarize TOON files from the decoded top-level shape.
fn toon_summary(content: &str) -> Option<String> {
    let mut sections = if let Ok(value) = toon_format::decode_default::<JsonValue>(content) {
        value
            .as_object()
            .map(|object| object.keys().cloned().collect::<Vec<_>>())
            .unwrap_or_default()
    } else {
        Vec::new()
    };
    if sections.is_empty() {
        sections = toon_section_names(content)
            .into_iter()
            .map(str::to_string)
            .collect();
    }
    if sections.is_empty() {
        None
    } else {
        Some(format!(
            "TOON document with sections {}.",
            join_limited(sections.iter().map(String::as_str).collect())
        ))
    }
}

/// Extract declared top-level TOON section names from compact table/list headers.
fn toon_section_names(content: &str) -> Vec<&str> {
    content
        .lines()
        .filter_map(|line| {
            let trimmed = line.trim();
            let (head, _tail) = trimmed.split_once(':')?;
            let name = head
                .split_once('[')
                .map_or(head, |(name, _columns)| name)
                .split_once('{')
                .map_or_else(
                    || head.split_once('[').map_or(head, |(name, _columns)| name),
                    |(name, _columns)| name,
                )
                .trim();
            (!name.is_empty() && !name.starts_with('#')).then_some(name)
        })
        .collect()
}

/// Summarize XML-like documents from their declared element names.
fn xml_summary(content: &str) -> Option<String> {
    let elements = content
        .lines()
        .flat_map(xml_element_names)
        .collect::<BTreeSet<_>>()
        .into_iter()
        .collect::<Vec<_>>();
    if elements.is_empty() {
        None
    } else {
        Some(format!(
            "xml document with elements {}.",
            join_limited(elements.iter().map(String::as_str).collect())
        ))
    }
}

/// Extract XML element names from one line with conservative string scanning.
fn xml_element_names(line: &str) -> Vec<String> {
    let mut names = Vec::new();
    let mut rest = line;
    while let Some((_, after_open)) = rest.split_once('<') {
        let trimmed = after_open.trim_start();
        if trimmed.starts_with(['/', '!', '?']) {
            rest = trimmed.get(1..).unwrap_or_default();
            continue;
        }
        let name = trimmed
            .split(|character: char| character.is_whitespace() || matches!(character, '/' | '>'))
            .next()
            .unwrap_or_default();
        if !name.is_empty()
            && name.chars().all(|character| {
                character.is_ascii_alphanumeric() || matches!(character, '_' | '-' | ':' | '.')
            })
        {
            names.push(name.to_string());
        }
        rest = trimmed
            .split_once('>')
            .map_or("", |(_element, remaining)| remaining);
    }
    names
}

/// Summarize simple config or text files from key-like lines.
fn config_text_summary(path: &str, content: &str) -> Option<String> {
    let keys = content
        .lines()
        .filter_map(config_key)
        .collect::<BTreeSet<_>>()
        .into_iter()
        .collect::<Vec<_>>();
    if keys.is_empty() {
        if has_extension(path, "txt") {
            let excerpt = content
                .lines()
                .map(compact_label)
                .find(|line| !line.is_empty())?;
            let file_name = path.rsplit('/').next().unwrap_or(path);
            return Some(format!("text file {file_name} beginning with {excerpt}."));
        }
        return None;
    }
    let file_name = path.rsplit('/').next().unwrap_or(path);
    Some(format!(
        "config file {file_name} with keys {}.",
        join_limited(keys.iter().map(String::as_str).collect())
    ))
}

/// Extract a key from simple `key=value`, `key: value`, or `export key=value` lines.
fn config_key(line: &str) -> Option<String> {
    let trimmed = line.trim();
    if trimmed.is_empty() || trimmed.starts_with('#') || trimmed.starts_with("//") {
        return None;
    }
    let trimmed = trimmed.strip_prefix("export ").unwrap_or(trimmed);
    for separator in ['=', ':'] {
        if let Some((key, _value)) = trimmed.split_once(separator) {
            let key = key.trim();
            if !key.is_empty()
                && key.chars().all(|character| {
                    character.is_ascii_alphanumeric() || matches!(character, '_' | '-' | '.')
                })
            {
                return Some(key.to_string());
            }
        }
    }
    None
}

/// Join a list with a fixed display limit.
fn join_limited(values: Vec<&str>) -> String {
    let mut values = values
        .into_iter()
        .map(compact_label)
        .filter(|value| !value.is_empty())
        .collect::<Vec<_>>();
    values.sort();
    values.dedup();
    let extra = values.len().saturating_sub(LIST_LIMIT);
    values.truncate(LIST_LIMIT);
    let joined = values.join(", ");
    if extra == 0 {
        joined
    } else {
        format!("{joined}, and {extra} more")
    }
}

/// Join a list or return `none` when it is empty.
fn join_or_none(values: Vec<&str>) -> String {
    if values.is_empty() {
        "none".to_string()
    } else {
        join_limited(values)
    }
}

/// Compact a label into one line.
fn compact_label(text: &str) -> String {
    let compact = text
        .split_whitespace()
        .collect::<Vec<_>>()
        .join(" ")
        .trim_matches(['"', '\''])
        .trim_end_matches(['#'])
        .trim()
        .to_string();
    if compact.chars().count() <= LABEL_LIMIT {
        compact
    } else {
        truncate_chars(&compact, LABEL_LIMIT)
    }
}

/// Truncate a string to a character boundary and add an ellipsis marker.
fn truncate_chars(text: &str, limit: usize) -> String {
    let mut output = text
        .chars()
        .take(limit.saturating_sub(3))
        .collect::<String>();
    output.push_str("...");
    output
}

#[cfg(test)]
mod tests {
    use super::{is_scanner_fallback_summary, structural_summary_for_path};

    #[test]
    fn document_summary_preserves_literal_punctuation_and_bounds_unicode() {
        use projectatlas_symbols::{
            DocumentCompleteness, DocumentFacts, DocumentFormat, DocumentParserProvenance,
        };
        let mut facts = DocumentFacts {
            format: DocumentFormat::Docx,
            text: "\"#\"\n\t#".to_owned(),
            facts: Vec::new(),
            symbols: Vec::new(),
            completeness: DocumentCompleteness::Complete,
            provenance: DocumentParserProvenance::QuickXml,
        };
        assert_eq!(
            super::document_summary_from_facts(&facts),
            "docx document text: \"#\" #"
        );
        facts.text = "\n\t".to_owned() + &"界".repeat(1000);
        assert_eq!(
            super::document_summary_from_facts(&facts),
            format!("docx document text: {}...", "界".repeat(77))
        );
        facts.text = " \n\t".to_owned();
        assert_eq!(
            super::document_summary_from_facts(&facts),
            "docx document with no extracted text."
        );
        facts.completeness = DocumentCompleteness::Partial {
            gaps: vec![projectatlas_symbols::DocumentCoverageGap::UnknownSymbolMapping],
        };
        assert_eq!(
            super::document_summary_from_facts(&facts),
            "docx document with incomplete text coverage."
        );
        facts.text = "Before After".to_owned();
        assert_eq!(
            super::document_summary_from_facts(&facts),
            "docx document text (incomplete coverage): Before After"
        );
    }

    #[test]
    fn summarizes_markdown_headings() {
        let summary = structural_summary_for_path(
            "README.md",
            Some("markdown"),
            "# ProjectAtlas\n\n## Install\nUsage\n-----\n",
        );
        assert_eq!(
            summary.as_deref(),
            Some("markdown document titled ProjectAtlas with sections Install, Usage.")
        );
    }

    #[test]
    fn summarizes_package_jsonc() {
        let summary = structural_summary_for_path(
            "package.json",
            Some("json"),
            "{\n  // project name\n  \"name\":\"demo\",\n  \"scripts\":{\"test\":\"vitest\"},\n  \"dependencies\":{\"react\":\"1.0.0\"}\n}",
        );
        assert_eq!(
            summary.as_deref(),
            Some("package manifest for demo with scripts test and 1 dependencies.")
        );
    }

    #[test]
    fn summarizes_object_keyed_dataset_manifest() {
        let summary = structural_summary_for_path(
            "app/public/data/datasets.manifest.json",
            Some("json"),
            r#"{
  "generated_at": "2026-06-28T00:00:00Z",
  "version": "2026.06.28",
  "datasets": {
    "catalog.primary": {"path": "primary.json"},
    "catalog.secondary": {"path": "secondary.json"},
    "catalog.archive": {"path": "archive.json"}
  }
}"#,
        );
        assert_eq!(
            summary.as_deref(),
            Some(
                "json dataset manifest with 3 datasets including catalog.archive, catalog.primary, catalog.secondary and keys datasets, generated_at, version."
            )
        );
    }

    #[test]
    fn summarizes_workflow_yaml() {
        let summary = structural_summary_for_path(
            ".github/workflows/ci.yml",
            Some("yaml"),
            "name: CI\non:\n  push:\n  pull_request:\njobs:\n  test:\n    runs-on: ubuntu-latest\n",
        );
        assert_eq!(
            summary.as_deref(),
            Some("yaml workflow CI triggered by pull_request, push with jobs test.")
        );
    }

    #[test]
    fn summarizes_projectatlas_config_toml() {
        let summary = structural_summary_for_path(
            ".projectatlas/config.toml",
            Some("toml"),
            "[project]\nroot = \".\"\n[scan]\nexclude_dir_names = [\"target\"]\nexclude_path_prefixes = [\"docs/api\"]\n",
        );
        assert_eq!(
            summary.as_deref(),
            Some("ProjectAtlas config with tables project, scan and 2 scan excludes.")
        );
    }

    #[test]
    fn summarizes_xml_elements() {
        let summary = structural_summary_for_path(
            "config/routes.xml",
            Some("xml"),
            r#"<?xml version="1.0"?>
<routes>
  <route id="home" />
  <route id="about"></route>
</routes>
"#,
        );
        assert_eq!(
            summary.as_deref(),
            Some("xml document with elements route, routes.")
        );
    }

    #[test]
    fn summarizes_css_structure() {
        let summary = structural_summary_for_path(
            "app/styles.css",
            Some("css"),
            ":root { --brand: #fff; }\n.card, .panel { color: red; }\n@media (min-width: 40rem) { .card { display: grid; } }\n",
        );
        assert_eq!(
            summary.as_deref(),
            Some(
                "css stylesheet with selectors .card, .panel, :root, custom properties --brand, 1 media queries, and 0 supports queries."
            )
        );
    }

    #[test]
    fn summarizes_html_metadata() {
        let summary = structural_summary_for_path(
            "index.html",
            Some("html"),
            "<html><head><title>Home</title><meta name=\"description\" content=\"Welcome page\"><link rel=\"canonical\" href=\"https://example.test/\"><link rel=\"manifest\" href=\"/site.webmanifest\"><link rel=\"alternate\" href=\"/de/\"></head><body><h1>Hello</h1><script type=\"application/ld+json\">{}</script></body></html>",
        );
        assert_eq!(
            summary.as_deref(),
            Some(
                "html document with title Home, meta description Welcome page, headings Hello, link rels alternate, canonical, manifest, structured data."
            )
        );
    }

    #[test]
    fn summarizes_powershell_functions() {
        let summary = structural_summary_for_path(
            "scripts/install-runtime.ps1",
            Some("powershell"),
            "function Resolve-DefaultProjectRoot {\n}\nfunction global:Get-ReleaseRuntimeInstallPath($Root) {\n}\nfunction Install-ReleaseBinary {\n}\n",
        );
        assert_eq!(
            summary.as_deref(),
            Some(
                "powershell script defining functions Get-ReleaseRuntimeInstallPath, Install-ReleaseBinary, Resolve-DefaultProjectRoot."
            )
        );
    }

    #[test]
    fn supplied_language_overrides_structural_path_owner() {
        assert_eq!(
            structural_summary_for_path("Cargo.toml", Some("json"), "{\"name\":\"atlas\"}",)
                .as_deref(),
            Some("json document with top-level keys name.")
        );
        assert_eq!(
            structural_summary_for_path("scripts/install.ps1", Some("text"), "name=atlas\n",)
                .as_deref(),
            Some("config file install.ps1 with keys name.")
        );
        assert_eq!(
            structural_summary_for_path("data/report.toon", Some("json"), "{\"items\":[]}",)
                .as_deref(),
            Some("json document with top-level keys items.")
        );
        assert!(
            structural_summary_for_path("data/report.toon", Some("rust"), "items[1]{id}:\n  1\n",)
                .is_none()
        );
        assert_eq!(
            structural_summary_for_path("data/report.txt", Some("toon"), "items[1]{id}:\n  1\n",)
                .as_deref(),
            Some("TOON document with sections items.")
        );
    }

    #[test]
    fn missing_language_preserves_toon_path_inference() {
        assert_eq!(
            structural_summary_for_path("data/report.toon", None, "items[1]{id}:\n  1\n",)
                .as_deref(),
            Some("TOON document with sections items.")
        );
    }

    #[test]
    fn summarizes_plain_text_excerpt() {
        let summary =
            structural_summary_for_path("notes.txt", Some("text"), "\n\nProjectAtlas notes\n");
        assert_eq!(
            summary.as_deref(),
            Some("text file notes.txt beginning with ProjectAtlas notes.")
        );
    }

    #[test]
    fn classifies_summary_quality() {
        assert!(is_scanner_fallback_summary("rust file, 120 bytes."));
    }
}