//! The harvested widget summaries must stay accurate and stay present.
//!
//! 147 of 197 widget structs carried a doc comment that reached no user: the trait has no
//! description, the inspector shows ports and parameters, the site's reference is a table
//! of ids. The text existed and had no path out.
use flowrs_core::graph::widget::WidgetRegistry;
use flowrs_core::graph::widget_docs::{WIDGET_DOCS, describe};

#[test]
fn every_summary_belongs_to_a_widget_that_exists() {
    // A summary for a widget that has been renamed or removed is documentation pointing
    // at nothing, and the table is generated — so a stale entry means the generator was
    // not re-run.
    let reg = WidgetRegistry::with_builtins();
    let orphans: Vec<&str> = WIDGET_DOCS
        .iter()
        .map(|(id, _)| *id)
        .filter(|id| reg.get(id).is_none())
        .collect();
    assert!(
        orphans.is_empty(),
        "{} summaries describe widgets that no longer exist — re-run \
         tools/harvest_widget_docs.py:\n  {}",
        orphans.len(),
        orphans.join("\n  ")
    );
}

#[test]
fn most_widgets_are_documented_and_the_count_does_not_slip() {
    let reg = WidgetRegistry::with_builtins();
    let total = reg.all().len();
    let documented = reg
        .all()
        .iter()
        .filter(|w| describe(&w.id()).is_some())
        .count();

    // A ratchet, not a target. Adding a widget without a doc comment is allowed — writing
    // one later is fine — but the proportion should not quietly fall.
    const KNOWN_DOCUMENTED: usize = 266;
    assert!(
        documented >= KNOWN_DOCUMENTED,
        "widget documentation went backwards: {documented} of {total} documented, was \
         {KNOWN_DOCUMENTED}. A widget lost its doc comment, or the generator needs re-running."
    );
    assert!(
        documented <= KNOWN_DOCUMENTED,
        "good news: {documented} of {total} widgets are documented, up from \
         {KNOWN_DOCUMENTED}. Raise KNOWN_DOCUMENTED to {documented} to hold the gain."
    );
}

#[test]
fn a_summary_says_something() {
    // Guards the generator's own failure mode: taking a truncated or empty first line and
    // shipping "Fft." as documentation.
    for (id, doc) in WIDGET_DOCS {
        assert!(
            doc.len() >= 25,
            "{id}: summary too short to be useful: {doc:?}"
        );
        assert!(
            doc.ends_with('.') || doc.ends_with('!') || doc.ends_with('?'),
            "{id}: summary looks truncated: {doc:?}"
        );
        assert!(
            !doc.contains("**"),
            "{id}: markdown leaked into the summary"
        );
    }
}