rmcp-server-kit 3.11.0

//! Pins `file:line` citations referenced from the agent-facing docs
//! (`docs/ARCHITECTURE.md`, `AGENTS.md`, `docs/MINDMAP.md`).
//!
//! When code moves, this test fails first so docs stay accurate.
//!
//! Two layers of validation:
//!
//! 1. **Existence / length** (all citations): the cited file exists and
//!    has at least the cited line count.
//! 2. **Symbol anchoring** (citations with a recognizable symbol on the
//!    same doc line): at least one anchor symbol - a backticked token
//!    like `` `TlsListener` `` or a parenthesized identifier like
//!    `(build_app_router)` - must appear within `TOLERANCE` lines of the
//!    cited location in the cited file. This catches silent drift that
//!    the length check cannot (a file that only ever grows keeps every
//!    stale citation "valid" forever).
//!
//! Recognized citation forms (all require the `src/<file>.rs` path on
//! the same doc line):
//!   `src/<file>.rs:<line>`            (single line)
//!   `src/<file>.rs:<line>-<line>`     (range)
//!   `src/<file>.rs` ... `(~line <line>)`   (AGENTS.md table style)
//!   `src/<file>.rs` ... `~L<line>`         (MINDMAP.md table style)
//!
//! Out of scope: mindmap nodes whose file is implied by a parent node
//! (no path on the line), and prose without a `src/*.rs` mention.
//!
//! Drift fixes are easy: re-read the cited code and update the number.

#![allow(
    clippy::expect_used,
    clippy::missing_docs_in_private_items,
    clippy::panic,
    clippy::print_stderr
)]

use std::{collections::BTreeMap, fs, path::PathBuf};

use rmcp_server_kit::{
    config::{ObservabilityConfig, ServerConfig},
    rbac::RbacConfig,
};
use serde::Deserialize;

/// How far (in lines, each direction) an anchor symbol may sit from the
/// cited line/range. The doc headers promise "approximate" citations;
/// this is the enforced meaning of approximate.
const TOLERANCE: usize = 30;

/// Anchor candidates shorter than this are ignored (too noisy).
const MIN_ANCHOR_LEN: usize = 3;

/// Identifier-like tokens that are too generic to anchor anything.
const ANCHOR_STOPLIST: &[&str] = &[
    "src", "the", "and", "for", "rs", "line", "str", "Vec", "Arc", "Some", "None", "Option",
    "String", "true", "false", "usize", "bool",
];

#[derive(Debug, Clone)]
struct Citation {
    /// e.g. "src/transport.rs"
    file: String,
    /// 1-based first cited line.
    start: usize,
    /// 1-based last cited line; equals `start` for single-line.
    end: usize,
    /// Line in the doc where the citation appears.
    doc_line: usize,
    /// Symbol candidates extracted from the same doc line. Empty means
    /// "length-check only".
    anchors: Vec<String>,
}

#[derive(Debug)]
struct TomlFence {
    line: usize,
    info: String,
    body: String,
}

#[derive(Debug, Deserialize)]
struct GuideOperatorConfig {
    server: Option<ServerConfig>,
    rbac: Option<RbacConfig>,
    observability: Option<ObservabilityConfig>,
}

fn workspace_root() -> PathBuf {
    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
}

/// Leading `[A-Za-z_][A-Za-z0-9_]*` run after skipping any non-identifier
/// prefix characters (`&`, `[`, `*`, spaces, ...).
fn leading_identifier(s: &str) -> Option<&str> {
    let trimmed = s.trim_start_matches(|c: char| !(c.is_ascii_alphabetic() || c == '_'));
    let len = trimmed
        .bytes()
        .take_while(|b| b.is_ascii_alphanumeric() || *b == b'_')
        .count();
    if len == 0 { None } else { trimmed.get(..len) }
}

fn keep_anchor(candidate: &str, file: &str) -> bool {
    if candidate.len() < MIN_ANCHOR_LEN {
        return false;
    }
    if ANCHOR_STOPLIST.contains(&candidate) {
        return false;
    }
    // The file stem ("transport" for src/transport.rs) appears in every
    // module path and anchors nothing.
    let stem = file
        .rsplit('/')
        .next()
        .and_then(|n| n.strip_suffix(".rs"))
        .unwrap_or("");
    candidate != stem
}

/// Extract anchor candidates from a doc line: the leading identifier of
/// every backticked segment (plus, for `path::to::item` forms, the final
/// segment), and every `(identifier)` group.
fn extract_anchors(line: &str, file: &str) -> Vec<String> {
    let mut out: Vec<String> = Vec::new();
    let mut push = |candidate: &str| {
        if keep_anchor(candidate, file) && !out.iter().any(|a| a == candidate) {
            out.push(candidate.to_owned());
        }
    };

    // Backticked segments: odd-indexed pieces of a split on '`'.
    for (idx, segment) in line.split('`').enumerate() {
        if idx % 2 != 1 {
            continue;
        }
        if let Some(ident) = leading_identifier(segment) {
            push(ident);
        }
        // `transport::healthz` / `RbacPolicy::check(...)`: the segment
        // after the last `::` (up to any argument list) is usually the
        // most specific anchor.
        let head = segment.split('(').next().unwrap_or(segment);
        if let Some(last) = head.rsplit("::").next()
            && last != head
            && let Some(ident) = leading_identifier(last)
        {
            push(ident);
        }
    }

    // Parenthesized single identifiers: "(build_app_router)".
    let mut tail = line;
    while let Some(open) = tail.find('(') {
        let inner = tail.get(open + 1..).unwrap_or("");
        let len = inner
            .bytes()
            .take_while(|b| b.is_ascii_alphanumeric() || *b == b'_')
            .count();
        if len > 0
            && inner.get(len..).is_some_and(|rest| rest.starts_with(')'))
            && let Some(ident) = inner.get(..len)
        {
            push(ident);
        }
        tail = inner;
    }

    out
}

/// Parse a single token of the form `src/foo.rs:NNN` or `src/foo.rs:NNN-MMM`
/// starting at the beginning of `tail`. Returns the citation (without
/// anchors) and the number of bytes consumed, or `None` if `tail` does not
/// start with a valid citation. A bare `src/foo.rs` without `:NNN` returns
/// the file name with `start == 0` so callers can pair it with `~line`
/// style locators found elsewhere on the same line.
fn parse_path_at(tail: &str) -> Option<(String, usize, usize, usize)> {
    let rest = tail.strip_prefix("src/")?;

    let name_len = rest
        .bytes()
        .take_while(|b| b.is_ascii_alphanumeric() || *b == b'_')
        .count();
    if name_len == 0 {
        return None;
    }
    let name = rest.get(..name_len)?;
    let after_name = rest.get(name_len..)?;

    let file = format!("src/{name}.rs");
    let base_consumed = "src/".len() + name_len + ".rs".len();

    let Some(after_ext) = after_name.strip_prefix(".rs:") else {
        // Bare path (no :NNN) - still a valid file mention.
        if after_name.starts_with(".rs") {
            return Some((file, 0, 0, base_consumed));
        }
        return None;
    };

    let start_digits_len = after_ext.bytes().take_while(u8::is_ascii_digit).count();
    if start_digits_len == 0 {
        return Some((file, 0, 0, base_consumed));
    }
    let start: usize = after_ext.get(..start_digits_len)?.parse().ok()?;
    let after_start = after_ext.get(start_digits_len..)?;

    let (end, range_consumed) = if let Some(after_dash) = after_start.strip_prefix('-') {
        let end_digits_len = after_dash.bytes().take_while(u8::is_ascii_digit).count();
        if end_digits_len == 0 {
            (start, 0)
        } else if let Some(parsed) = after_dash
            .get(..end_digits_len)
            .and_then(|d| d.parse::<usize>().ok())
        {
            (parsed, 1 + end_digits_len)
        } else {
            (start, 0)
        }
    } else {
        (start, 0)
    };

    let consumed = base_consumed + ":".len() + start_digits_len + range_consumed;
    Some((file, start, end, consumed))
}

/// Find a `(~line NNN)` (AGENTS.md) or `~LNNN` (MINDMAP.md) locator on a
/// doc line.
fn parse_tilde_line(line: &str) -> Option<usize> {
    let mut tail = line;
    while let Some(pos) = tail.find('~') {
        let after = tail.get(pos + 1..).unwrap_or("");
        let digits_part = if let Some(rest) = after.strip_prefix("line ") {
            rest
        } else if let Some(rest) = after.strip_prefix('L') {
            rest
        } else {
            tail = after;
            continue;
        };
        let len = digits_part.bytes().take_while(u8::is_ascii_digit).count();
        if len > 0
            && let Some(n) = digits_part.get(..len).and_then(|d| d.parse::<usize>().ok())
        {
            return Some(n);
        }
        tail = after;
    }
    None
}

fn parse_citations(doc: &str) -> Vec<Citation> {
    let mut out = Vec::new();
    for (doc_idx, line) in doc.lines().enumerate() {
        let doc_line_no = doc_idx + 1;
        let mut bare_file: Option<String> = None;

        let mut tail = line;
        while let Some(rel) = tail.find("src/") {
            let candidate = tail.get(rel..).unwrap_or("");
            if let Some((file, start, end, consumed)) = parse_path_at(candidate) {
                if start > 0 {
                    out.push(Citation {
                        anchors: extract_anchors(line, &file),
                        file,
                        start,
                        end,
                        doc_line: doc_line_no,
                    });
                } else if bare_file.is_none() {
                    bare_file = Some(file);
                }
                tail = candidate.get(consumed..).unwrap_or("");
            } else {
                tail = candidate.get(1..).unwrap_or("");
            }
        }

        // Pair a bare path with a `~line N` / `~LN` locator on the same line.
        if let Some(file) = bare_file
            && let Some(n) = parse_tilde_line(line)
        {
            out.push(Citation {
                anchors: extract_anchors(line, &file),
                file,
                start: n,
                end: n,
                doc_line: doc_line_no,
            });
        }
    }
    out
}

fn check_doc(doc_name: &str, doc: &str) -> (usize, Vec<String>) {
    let root = workspace_root();
    let citations = parse_citations(doc);

    let mut file_lines: BTreeMap<String, Option<Vec<String>>> = BTreeMap::new();
    let mut failures: Vec<String> = Vec::new();

    for c in &citations {
        let lines = file_lines.entry(c.file.clone()).or_insert_with(|| {
            fs::read_to_string(root.join(&c.file))
                .ok()
                .map(|t| t.lines().map(str::to_owned).collect())
        });

        let Some(lines) = lines else {
            failures.push(format!(
                "{doc_name}:{} cites {}:{} but the file does not exist",
                c.doc_line,
                c.file,
                fmt_range(c)
            ));
            continue;
        };
        let n = lines.len();

        if c.end > n {
            failures.push(format!(
                "{doc_name}:{} cites {}:{} but file only has {n} lines",
                c.doc_line,
                c.file,
                fmt_range(c)
            ));
            continue;
        }

        if c.anchors.is_empty() {
            continue;
        }

        // Window: [start - TOLERANCE, end + TOLERANCE], clamped, 1-based.
        let win_start = c.start.saturating_sub(TOLERANCE).max(1);
        let win_end = c.end.saturating_add(TOLERANCE).min(n);
        let window: String = lines
            .get(win_start - 1..win_end)
            .unwrap_or_default()
            .join("\n");

        if !c.anchors.iter().any(|a| window_has_anchor(&window, a)) {
            failures.push(format!(
                "{doc_name}:{} cites {}:{} but none of the anchor symbols {:?} \
                 appear within {TOLERANCE} lines of the cited location \
                 (searched lines {win_start}-{win_end}); update the citation",
                c.doc_line,
                c.file,
                fmt_range(c),
                c.anchors,
            ));
        }
    }

    (citations.len(), failures)
}

/// True when `anchor` occurs in `window` as a standalone identifier: the
/// characters immediately surrounding the match (when present) must not
/// be identifier characters. Plain substring matching let generic
/// anchors like `serve` match inside `server` / `observed`, silently
/// masking stale citations.
fn window_has_anchor(window: &str, anchor: &str) -> bool {
    fn is_ident(b: u8) -> bool {
        b.is_ascii_alphanumeric() || b == b'_'
    }
    let bytes = window.as_bytes();
    window.match_indices(anchor).any(|(pos, _)| {
        let before_ok = pos == 0 || !bytes.get(pos - 1).copied().is_some_and(is_ident);
        let after_ok = !bytes.get(pos + anchor.len()).copied().is_some_and(is_ident);
        before_ok && after_ok
    })
}

fn fmt_range(c: &Citation) -> String {
    if c.end == c.start {
        format!("{}", c.start)
    } else {
        format!("{}-{}", c.start, c.end)
    }
}

fn run_doc_test(doc_rel_path: &str) {
    let root = workspace_root();
    let path = root.join(doc_rel_path);
    let doc = fs::read_to_string(&path).unwrap_or_else(|e| panic!("read {doc_rel_path}: {e}"));

    let (total, failures) = check_doc(doc_rel_path, &doc);
    assert!(
        total > 0,
        "no src/*.rs citations parsed from {doc_rel_path} - parser is likely broken"
    );
    assert!(
        failures.is_empty(),
        "{} stale citation(s) in {doc_rel_path} (out of {total} total):\n{}",
        failures.len(),
        failures.join("\n")
    );
}

fn extract_toml_fences(doc: &str) -> Vec<TomlFence> {
    let mut fences = Vec::new();
    let mut open: Option<TomlFence> = None;

    for (idx, line) in doc.lines().enumerate() {
        let line_no = idx + 1;
        let trimmed = line.trim_start();

        if let Some(mut fence) = open.take() {
            if trimmed == "```" {
                fences.push(fence);
            } else {
                fence.body.push_str(line);
                fence.body.push('\n');
                open = Some(fence);
            }
            continue;
        }

        if let Some(info) = trimmed.strip_prefix("```") {
            let info = info.trim();
            if info == "toml" || info.starts_with("toml,") {
                open = Some(TomlFence {
                    line: line_no,
                    info: info.to_owned(),
                    body: String::new(),
                });
            }
        }
    }

    fences
}

fn assert_operator_root_keys(block: &TomlFence, table: &toml::Table) {
    for key in table.keys() {
        assert!(
            matches!(key.as_str(), "server" | "rbac" | "observability"),
            "docs/GUIDE.md:{} has unknown operator-config root table/key `{key}`",
            block.line
        );
    }
}

fn assert_operator_config_block_parses(block: &TomlFence) {
    let table: toml::Table = toml::from_str(&block.body).unwrap_or_else(|error| {
        panic!(
            "docs/GUIDE.md:{} operator TOML is not valid TOML: {error}\n{}",
            block.line, block.body
        )
    });
    assert_operator_root_keys(block, &table);

    let parsed: GuideOperatorConfig = toml::from_str(&block.body).unwrap_or_else(|error| {
        panic!(
            "docs/GUIDE.md:{} operator TOML does not match rmcp-server-kit config schema: {error}\n{}",
            block.line, block.body
        )
    });
    assert!(
        parsed.server.is_some() || parsed.rbac.is_some() || parsed.observability.is_some(),
        "docs/GUIDE.md:{} operator TOML block must contain server, rbac, or observability config",
        block.line
    );
}

fn assert_cargo_toml_block_parses(block: &TomlFence) {
    toml::from_str::<toml::Value>(&block.body).unwrap_or_else(|error| {
        panic!(
            "docs/GUIDE.md:{} Cargo TOML is not valid TOML: {error}\n{}",
            block.line, block.body
        )
    });
}

fn assert_toml_fragment_parses(block: &TomlFence) {
    toml::from_str::<toml::Value>(&block.body).unwrap_or_else(|error| {
        panic!(
            "docs/GUIDE.md:{} TOML fragment is not valid TOML: {error}\n{}",
            block.line, block.body
        )
    });
}

fn extract_embedded_config(source: &str) -> &str {
    let Some((_, tail)) = source.split_once("const EMBEDDED_CONFIG: &str = r#\"") else {
        panic!("examples/config_file_server.rs no longer declares EMBEDDED_CONFIG")
    };
    let Some((config, _)) = tail.split_once("\"#;") else {
        panic!("examples/config_file_server.rs EMBEDDED_CONFIG raw string is not terminated")
    };
    config
}

#[test]
fn guide_toml_fences_parse() {
    let root = workspace_root();
    let doc = fs::read_to_string(root.join("docs/GUIDE.md")).expect("read GUIDE.md");
    let fences = extract_toml_fences(&doc);

    assert_eq!(fences.len(), 17, "GUIDE.md TOML fence count drifted");
    for block in &fences {
        match block.info.as_str() {
            "toml" => assert_operator_config_block_parses(block),
            "toml,cargo" => assert_cargo_toml_block_parses(block),
            "toml,fragment" => assert_toml_fragment_parses(block),
            other => panic!(
                "docs/GUIDE.md:{} uses unsupported TOML fence info string `{other}`; use `toml` for complete operator config, `toml,cargo` for Cargo snippets, or `toml,fragment` for intentionally incomplete excerpts",
                block.line
            ),
        }
    }
}

#[test]
fn config_file_server_embedded_toml_parses() {
    let root = workspace_root();
    let source = fs::read_to_string(root.join("examples/config_file_server.rs"))
        .expect("read config_file_server.rs");
    let config = extract_embedded_config(&source);
    let parsed: GuideOperatorConfig = toml::from_str(config).unwrap_or_else(|error| {
        panic!(
            "examples/config_file_server.rs EMBEDDED_CONFIG does not match rmcp-server-kit config schema: {error}\n{config}"
        )
    });
    assert!(
        parsed.server.is_some(),
        "embedded config must include [server]"
    );
    assert!(
        parsed.observability.is_some(),
        "embedded config must include [observability]"
    );
    assert!(parsed.rbac.is_some(), "embedded config must include [rbac]");
}

/// The kit's section structs reject unknown *keys*, but only an
/// application-owned root type can reject a misspelled *table name*
/// (`[serverr]`). `config_file_server` is the canonical consumer example, so
/// it must keep modelling that; without the attribute a mistyped section is
/// silently dropped and the server starts with defaults for it.
#[test]
fn config_file_server_root_denies_unknown_tables() {
    let root = workspace_root();
    let source = fs::read_to_string(root.join("examples/config_file_server.rs"))
        .expect("read config_file_server.rs");

    let struct_pos = source
        .find("struct AppConfig")
        .expect("examples/config_file_server.rs must define the AppConfig root type");
    let preamble = source
        .get(..struct_pos)
        .expect("struct_pos is a char boundary returned by find");

    assert!(
        preamble.contains("#[serde(deny_unknown_fields)]"),
        "examples/config_file_server.rs: the application-owned `AppConfig` root must carry \
         #[serde(deny_unknown_fields)] so a misspelled table name is rejected rather than \
         silently ignored"
    );
}

#[test]
fn architecture_citations_resolve() {
    run_doc_test("docs/ARCHITECTURE.md");
}

#[test]
fn agents_citations_resolve() {
    run_doc_test("AGENTS.md");
}

#[test]
fn mindmap_citations_resolve() {
    run_doc_test("docs/MINDMAP.md");
}

#[test]
fn anchor_matching_requires_identifier_boundaries() {
    assert!(window_has_anchor("pub async fn serve<H, F>(", "serve"));
    assert!(window_has_anchor("calls serve() here", "serve"));
    assert!(
        !window_has_anchor("the server observed traffic", "serve"),
        "substring inside larger identifiers must not match"
    );
    assert!(!window_has_anchor("preserved", "serve"));
    assert!(window_has_anchor("get(healthz)", "healthz"));
    assert!(!window_has_anchor("healthz_returns_ok", "healthz"));
}

#[test]
fn anchored_citations_exist() {
    // Guard the guard: if anchor extraction silently breaks (returns no
    // anchors for every citation), the symbol check degrades to the old
    // length-only behavior without anyone noticing. ARCHITECTURE.md is
    // dense with backticked symbols, so a healthy parser must find a
    // meaningful number of anchored citations there.
    let root = workspace_root();
    let doc = fs::read_to_string(root.join("docs/ARCHITECTURE.md")).expect("read ARCHITECTURE.md");
    let citations = parse_citations(&doc);
    let anchored = citations.iter().filter(|c| !c.anchors.is_empty()).count();
    assert!(
        anchored >= 10,
        "expected >=10 symbol-anchored citations in docs/ARCHITECTURE.md, found {anchored} \
         (out of {} citations) - anchor extraction is likely broken",
        citations.len()
    );
}