sqlite-graphrag 1.2.8

//! Keeps every shipped subcommand reachable from the operator documentation.
//!
//! A subcommand is added to `src/cli/commands.rs` and the help output grows for
//! free. The documents do not: they only grow when someone remembers. Nothing
//! coupled the two, so `docs/AGENTS.md` — the document written for the agents
//! that drive this CLI — reached v1.2.5 never naming `memory-entities` or
//! `split-body`, and `INTEGRATIONS.md` was missing thirteen of fifty.
//!
//! An undocumented command is not a cosmetic gap. The reader cannot invoke what
//! the reader cannot find, so the feature is shipped and invisible at once.
//!
//! GAP-SG-294: this file used to read the `Commands:` block of `--help` for the
//! ROOT only, so it measured 49 verbs and never the 32 leaves below them —
//! `config list-keys`, `fts rebuild`, `vec purge-orphan` and the rest were
//! required by no document at all. The inventory now walks the BUILT clap tree,
//! which is the same technique `tests/docs_surface_gate.rs` already proved here.
//! `build()` is mandatory before walking: it is what synthesises `--help` and
//! `--version`, and an unbuilt tree reports a different surface than the binary.
//!
//! Like `docs_consistency.rs`, this is a test rather than a CI job because this
//! project forbids CI by design; `cargo test` is the only automatic gate.

use clap::CommandFactory;
use sqlite_graphrag::cli::Cli;
use std::collections::BTreeSet;

/// Documents that must name every subcommand.
///
/// `CROSS_PLATFORM`, `TESTING`, `TEST_PLAN`, `MIGRATION`, `SECURITY` and
/// `DOCUMENTATION_FRAMEWORK` are deliberately absent: each covers one axis —
/// portability, test strategy, upgrade path, threat model, document structure —
/// and naming all fifty commands there would be noise, not coverage.
const INVENTORY_DOCS: [&str; 17] = [
    "README.md",
    "README.pt-BR.md",
    "docs/HOW_TO_USE.md",
    "docs/HOW_TO_USE.pt-BR.md",
    "docs/AGENTS.md",
    "docs/AGENTS.pt-BR.md",
    "docs/COOKBOOK.md",
    "docs/COOKBOOK.pt-BR.md",
    "docs/HEADLESS_INVOCATION.md",
    "docs/HEADLESS_INVOCATION.pt-BR.md",
    "INTEGRATIONS.md",
    "INTEGRATIONS.pt-BR.md",
    "llms.txt",
    "llms.pt-BR.txt",
    "llms-full.txt",
    "skills/sqlite-graphrag-en/SKILL.md",
    "skills/sqlite-graphrag-pt/SKILL.md",
];

/// Commands excluded from the inventory requirement.
///
/// `help` is generated by clap and is not a product surface.
const NOT_A_PRODUCT_SURFACE: [&str; 1] = ["help"];

/// True when clap keeps this command out of the help an operator reads.
///
/// Walking the tree instead of the help text surfaced `debug-schema`, declared
/// with `hide = true`. A hidden command is not a documentation gap: the parser
/// hides it precisely because it is not offered to the reader, so demanding
/// seventeen documents name it would be the gate crying wolf on its first run.
fn is_hidden(cmd: &clap::Command) -> bool {
    cmd.is_hide_set()
}

/// Reads a repository file relative to the crate root.
fn read_repo_file(relative: &str) -> String {
    let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join(relative);
    std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("cannot read {}: {e}", path.display()))
}

/// The parser's own command tree, built, as the paths an operator types.
///
/// Returns `("config", "config list-keys")`-shaped pairs: the depth-1 verb that
/// owns the entry, and the full path. Aliases are skipped on purpose — an alias
/// is a second spelling of a surface the canonical name already covers, and
/// demanding both would fail every document for no reader-visible gain.
fn command_paths() -> Vec<(String, String)> {
    fn walk(cmd: &clap::Command, prefix: &str, root: &str, out: &mut Vec<(String, String)>) {
        for sub in cmd.get_subcommands() {
            let name = sub.get_name();
            if NOT_A_PRODUCT_SURFACE.contains(&name) || is_hidden(sub) {
                continue;
            }
            let path = if prefix.is_empty() {
                name.to_string()
            } else {
                format!("{prefix} {name}")
            };
            let owner = if root.is_empty() { name } else { root };
            out.push((owner.to_string(), path.clone()));
            walk(sub, &path, owner, out);
        }
    }
    let mut root = Cli::command();
    root.build();
    let mut out = Vec::new();
    walk(&root, "", "", &mut out);
    out
}

/// Depth-1 verbs: `remember`, `config`, `fts`.
fn top_level_commands() -> BTreeSet<String> {
    command_paths()
        .into_iter()
        .filter(|(_, path)| !path.contains(' '))
        .map(|(_, path)| path)
        .collect()
}

/// Everything below depth 1: `config list-keys`, `fts rebuild`.
fn nested_command_paths() -> Vec<(String, String)> {
    command_paths()
        .into_iter()
        .filter(|(_, path)| path.contains(' '))
        .collect()
}

/// True when `doc` names `command` in a context an operator can copy.
///
/// Two shapes count: a real invocation (`sqlite-graphrag graph`) and a code
/// span, optionally carrying a subcommand (`` `fts` ``, `` `fts rebuild` ``).
/// A bare word does not: `export`, `list`, `read` and `related` are ordinary
/// English, and matching them by word boundary reported full coverage for a
/// document that never showed the command at all.
fn documents_command(doc: &str, command: &str) -> bool {
    let invocation = format!("sqlite-graphrag {command}");
    if doc
        .match_indices(&invocation)
        .any(|(index, _)| ends_on_boundary(doc, index + invocation.len()))
    {
        return true;
    }

    // A multi-word path is unambiguous on its own: no English sentence opens a
    // code span with `config list-keys`, so whatever follows inside the span is
    // an argument and not evidence of prose. Only the single-word case needs
    // the strict tail below, which is what keeps `list` from matching
    // `` `list of names` ``.
    let is_path = command.contains(' ');

    let span_start = format!("`{command}");
    doc.match_indices(&span_start).any(|(index, _)| {
        let rest = &doc[index + span_start.len()..];
        match rest.find('`') {
            // `cmd` — nothing between the name and the closing backtick.
            Some(0) => true,
            // `cmd sub` — one space plus a lowercase token.
            Some(end) => {
                let tail = &rest[..end];
                if is_path {
                    return tail.starts_with(' ');
                }
                tail.starts_with(' ')
                    && tail.len() > 1
                    && tail[1..]
                        .chars()
                        .all(|c| c.is_ascii_lowercase() || c == '-' || c == ' ')
            }
            None => false,
        }
    })
}

/// True when position `at` is the end of the text or a non-name character.
fn ends_on_boundary(text: &str, at: usize) -> bool {
    text[at..]
        .chars()
        .next()
        .is_none_or(|c| !c.is_ascii_alphanumeric() && c != '-' && c != '_')
}

/// The language a document is written in, read off its own path.
///
/// Derived, never listed: a new translation named `X.pt-BR.md` or filed under a
/// `-pt/` directory joins the Portuguese side by existing.
fn is_portuguese(doc: &str) -> bool {
    doc.contains("pt-BR") || doc.contains("-pt/")
}

/// The command names the binary's own root `--help` prints.
///
/// A SECOND source, deliberately. The walk above reads the clap tree in this
/// process; this reads what the shipped binary shows an operator. Comparing the
/// two replaces the hand-written floor that used to guard this test: a number
/// typed once is a claim about a past release, and it goes stale without ever
/// saying so.
fn commands_in_root_help() -> BTreeSet<String> {
    let output = std::process::Command::new(env!("CARGO_BIN_EXE_sqlite-graphrag"))
        .arg("--help")
        .output()
        .expect("cannot run the binary to read its command inventory");
    let help = String::from_utf8_lossy(&output.stdout);

    let mut names = BTreeSet::new();
    let mut inside = false;
    for line in help.lines() {
        if line.starts_with("Commands:") {
            inside = true;
            continue;
        }
        if !inside {
            continue;
        }
        if line.trim().is_empty() || line.starts_with("Options:") {
            break;
        }
        // Command rows are indented by exactly two spaces; wrapped description
        // text is indented further.
        let trimmed = line.trim_start();
        if line.len() - trimmed.len() != 2 {
            continue;
        }
        let Some(name) = trimmed.split_whitespace().next() else {
            continue;
        };
        if name.chars().all(|c| c.is_ascii_lowercase() || c == '-')
            && !NOT_A_PRODUCT_SURFACE.contains(&name)
        {
            names.insert(name.to_string());
        }
    }
    names
}

#[test]
fn the_walked_inventory_matches_what_the_binary_prints() {
    let walked = top_level_commands();
    let printed = commands_in_root_help();
    assert!(
        !printed.is_empty(),
        "the root help produced no command rows; the layout changed and this \
         cross-check would otherwise compare against nothing"
    );
    assert_eq!(
        walked, printed,
        "the clap tree walked here and the binary's own `--help` disagree about \
         the shipped surface. Hidden commands are already filtered out of both, \
         so a difference means the walk broke or a command is printed without \
         being reachable in the tree."
    );
}

#[test]
fn every_shipped_command_is_named_in_every_inventory_document() {
    let commands = top_level_commands();
    assert_eq!(
        commands,
        commands_in_root_help(),
        "the inventory disagrees with the binary; see \
         `the_walked_inventory_matches_what_the_binary_prints`"
    );

    for doc in INVENTORY_DOCS {
        let text = read_repo_file(doc);
        let missing: Vec<&String> = commands
            .iter()
            .filter(|c| !documents_command(&text, c))
            .collect();
        assert!(
            missing.is_empty(),
            "{doc} names {}/{} shipped commands; a reader cannot invoke what it \
             cannot find. Missing: {:?}",
            commands.len() - missing.len(),
            commands.len(),
            missing
        );
    }
}

/// Every nested subcommand must be reachable from the corpus in BOTH languages.
///
/// The requirement is per LANGUAGE, not per document, and that is a deliberate
/// calibration rather than an oversight. Measured on 2026-08-21: demanding all
/// 32 nested paths from all 17 inventory documents produced 189 offences, with
/// `docs/HEADLESS_INVOCATION.md` alone missing 26 — that document teaches one
/// axis (non-interactive invocation) and has no reason to catalogue
/// `cache clear-models`. A gate that fails every document on its first run is a
/// gate somebody deletes, and the defect being closed here is not "each document
/// is a full catalogue"; it is that a leaf could ship without appearing in the
/// corpus AT ALL, which is exactly what 32 of them were doing.
///
/// The per-document axis for nested paths is therefore declared OUT of scope.
/// If a future document is meant to be an exhaustive catalogue, it needs its own
/// gate stating that intent, not a widening of this one.
#[test]
fn every_nested_subcommand_is_reachable_from_the_corpus_in_both_languages() {
    let nested = nested_command_paths();
    // MEASURED 2026-08-21 against v1.2.8: 32 nested paths under 8 families
    // (graph, fts, vec, slots, embedding, pending-embeddings, cache, config).
    //
    // This one is a NUMBER and the depth-1 floor above is not, and the reason is
    // cost. Cross-checking each family against `<family> --help` would mean one
    // process per depth-1 command; `docs_xdg_coverage` does exactly that walk
    // and takes 133 s for it, which is too much to spend proving a walk that the
    // depth-1 cross-check has already shown to be intact. Raise this number when
    // a family gains a leaf; never lower it to make the test pass.
    assert!(
        nested.len() >= 32,
        "read only {} nested subcommands out of the clap tree, below the 32 \
         measured on 2026-08-21; the walk stopped at depth one again, which is \
         the defect this test exists to close",
        nested.len()
    );

    let corpus: Vec<(&str, String)> = INVENTORY_DOCS
        .iter()
        .map(|doc| (*doc, read_repo_file(doc)))
        .collect();

    let mut missing = Vec::new();
    for (owner, path) in &nested {
        for portuguese in [false, true] {
            let named = corpus
                .iter()
                .filter(|(doc, _)| is_portuguese(doc) == portuguese)
                .any(|(_, text)| documents_command(text, path));
            if !named {
                let side = if portuguese { "pt-BR" } else { "en" };
                missing.push(format!("{path} (owner `{owner}`, missing in {side})"));
            }
        }
    }

    assert!(
        missing.is_empty(),
        "{} nested subcommand(s) are named by no inventory document in the \
         language shown. Fix by writing the full path — `sqlite-graphrag config \
         list-keys` or a `` `config list-keys` `` code span — into ONE document \
         of that language; naming only the owning family does not count, because \
         a reader who sees `config` still cannot guess the leaf.\n{}",
        missing.len(),
        missing.join("\n")
    );
}

#[test]
fn the_inventory_leaves_hidden_commands_out() {
    // `debug-schema` carries `hide = true` in src/cli/commands.rs. If it ever
    // becomes visible, this assertion fails and the corpus has to name it —
    // which is the right outcome, not a reason to loosen the filter.
    let commands = top_level_commands();
    assert!(
        !commands.contains("debug-schema"),
        "`debug-schema` is hidden by the parser; a hidden command is not a \
         documentation gap"
    );
    assert!(
        commands.contains("remember") && commands.contains("config"),
        "the walk lost a visible command"
    );
}

#[test]
fn the_command_matcher_rejects_a_bare_english_word() {
    // This is the false positive that made an earlier sweep report 50/50 for a
    // document that never showed the command.
    let doc = "You can export the graph and read the list of related items.";
    assert!(!documents_command(doc, "export"));
    assert!(!documents_command(doc, "read"));
    assert!(!documents_command(doc, "list"));
    assert!(!documents_command(doc, "related"));
}

#[test]
fn the_command_matcher_accepts_an_invocation_and_a_code_span() {
    assert!(documents_command(
        "run `sqlite-graphrag export --json`",
        "export"
    ));
    assert!(documents_command("the `vec` family", "vec"));
    assert!(documents_command("call `fts rebuild` first", "fts"));
}

#[test]
fn the_command_matcher_reads_a_nested_path_carrying_arguments() {
    // The strict single-word tail rejects anything but lowercase words, so
    // `config set embedding.model` would have been read as undocumented while
    // sitting in plain sight.
    assert!(documents_command(
        "run `config set embedding.model qwen3`",
        "config set"
    ));
    assert!(documents_command(
        "see `sqlite-graphrag vec purge-orphan --json`",
        "vec purge-orphan"
    ));
    assert!(!documents_command(
        "the `config` family exists",
        "config set"
    ));
}

#[test]
fn the_command_matcher_rejects_a_longer_command_that_shares_a_prefix() {
    // `remember` must not be credited by a document that only shows
    // `remember-batch`, and `prune-ner` must not be credited by `prune-relations`.
    let doc = "use `remember-batch` for bulk writes";
    assert!(!documents_command(doc, "remember"));
    assert!(documents_command(doc, "remember-batch"));
}

#[test]
fn the_language_split_covers_the_whole_inventory() {
    // A document that lands on neither side would be silently dropped from the
    // per-language scan above, and the leaf it alone documents would be reported
    // as missing forever.
    let english = INVENTORY_DOCS.iter().filter(|d| !is_portuguese(d)).count();
    let portuguese = INVENTORY_DOCS.iter().filter(|d| is_portuguese(d)).count();
    assert_eq!(english + portuguese, INVENTORY_DOCS.len());
    assert!(english >= 8 && portuguese >= 8, "the split is lopsided");
    assert!(is_portuguese("skills/sqlite-graphrag-pt/SKILL.md"));
    assert!(is_portuguese("docs/AGENTS.pt-BR.md"));
    assert!(is_portuguese("llms.pt-BR.txt"));
    assert!(!is_portuguese("skills/sqlite-graphrag-en/SKILL.md"));
}