mirador 1.22.0

//! Share prices: the data model, the pluggable source behind it, and the
//! persisted watchlist.
//!
//! **The source is a trait on purpose, from the first commit.** Yahoo gates on
//! IP reputation rather than on authentication, and blocks datacenter and VPN
//! ranges wholesale — so the default source works perfectly on a laptop and
//! fails flatly on a VPS, for the same user with the same build. That is not a
//! bug anyone can fix in the client; it can only be routed around by using a
//! different source. Making that swappable later would mean rewriting the panel.
//!
//! Licensing ruled out several otherwise-obvious providers, and the reasoning
//! is recorded here so nobody re-derives it:
//!
//! - **Finnhub is unusable at any tier.** Its terms restrict *every* plan,
//!   including paid ones, to personal use, so no user of a distributed tool can
//!   ever be compliant.
//! - **FMP** forbids displaying its data in a software product.
//! - **Alpha Vantage** allows 25 requests a day, which is not a watchlist.
//!
//! Operational rules, also deliberate: never bundle a shared API key (it would
//! be a shared secret in a public binary, and rate limits are per key); poll no
//! faster than once a minute; request symbols one at a time with a pause
//! between them rather than firing a burst; and never write quotes to disk —
//! prices are session state, and a stale price read as live is worse than no
//! price.

use std::path::{Path, PathBuf};
use std::time::Duration;

use anyhow::{Context, Result};
use serde::{Deserialize, Serialize};

/// How long any single request may take.
const HTTP_TIMEOUT: Duration = Duration::from_secs(10);

/// Yahoo rejects requests without a browser user agent with HTTP 429, whatever
/// the request rate. This is not an attempt to hide what mirador is — the
/// endpoint simply refuses anything that does not look like a browser.
const BROWSER_UA: &str = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) \
                          AppleWebKit/537.36 (KHTML, like Gecko) \
                          Chrome/126.0.0.0 Safari/537.36";

/// One symbol's current state.
#[derive(Debug, Clone, PartialEq)]
pub struct Quote {
    pub symbol: String,
    pub price: f64,
    /// Yesterday's close, which is what the day's change is measured against.
    pub previous_close: f64,
    pub currency: Option<String>,
    /// Intraday closes, oldest first, for the sparkline. May be empty.
    pub series: Vec<f64>,
    /// Whether the source declares its data delayed.
    pub delayed: bool,
}

impl Quote {
    pub fn change(&self) -> f64 {
        self.price - self.previous_close
    }

    /// Day change as a percentage.
    ///
    /// Returns zero rather than infinity when the previous close is zero, which
    /// happens for a symbol that has never traded. A row reading `inf%` looks
    /// like a broken panel; `0.00%` reads as "nothing has happened". That is
    /// true only while the price has not moved either, so [`parse_chart`]
    /// refuses a quote with a change beside such a close; the guard stays for
    /// a quote built any other way.
    ///
    /// Measured against the close's size, not its sign, so the percentage
    /// always runs the way the change does. A close can be negative — oil
    /// futures settled at −37.63 in April 2020 — and dividing by it signed
    /// put `-50.00%` beside a rise from −10 to −5, painted on the gain ramp.
    pub fn change_pct(&self) -> f64 {
        if self.close_is_zero() {
            return 0.0;
        }
        (self.change() / self.previous_close.abs()) * 100.0
    }

    /// Whether the previous close is too near zero to divide by, which is
    /// when [`Quote::change_pct`] answers zero instead.
    fn close_is_zero(&self) -> bool {
        self.previous_close.abs() < f64::EPSILON
    }
}

/// Where quotes come from.
///
/// Object-safe, because the panel holds one as a `Box<dyn QuoteSource>` chosen
/// by config at startup.
pub trait QuoteSource: Send {
    /// Name shown in the panel, so a user can tell which source produced a
    /// number — and which one is failing.
    fn name(&self) -> &'static str;

    /// Fetch one symbol. Implementations must not retry internally; the panel
    /// owns the cadence.
    fn fetch(&self, symbol: &str) -> Result<Quote>;
}

/// Every source id accepted in `[stocks].source`.
pub const SOURCE_NAMES: &[&str] = &["yahoo"];

/// Build a source by id.
pub fn source_for(name: &str) -> Option<Box<dyn QuoteSource>> {
    match name {
        "yahoo" => Some(Box::new(YahooChart)),
        _ => None,
    }
}

// ---------------------------------------------------------------------------
// Yahoo
// ---------------------------------------------------------------------------

/// Yahoo Finance's `/v8/finance/chart/` endpoint.
///
/// Chosen over `/v7/finance/quote`, which now needs a cookie-and-crumb pair and
/// returns 401 without one. One GET to v8 returns the price, the previous
/// close, the currency *and* the intraday series, so a watchlist row costs
/// exactly one request.
pub struct YahooChart;

#[derive(Debug, Deserialize)]
struct ChartEnvelope {
    chart: ChartBody,
}

#[derive(Debug, Deserialize)]
struct ChartBody {
    #[serde(default)]
    result: Vec<ChartResult>,
    #[serde(default)]
    error: Option<ChartError>,
}

#[derive(Debug, Deserialize)]
struct ChartError {
    #[serde(default)]
    description: Option<String>,
    #[serde(default)]
    code: Option<String>,
}

#[derive(Debug, Deserialize)]
struct ChartResult {
    meta: ChartMeta,
    #[serde(default)]
    indicators: Option<Indicators>,
}

#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
struct ChartMeta {
    symbol: String,
    #[serde(default)]
    regular_market_price: Option<f64>,
    #[serde(default)]
    chart_previous_close: Option<f64>,
    #[serde(default)]
    previous_close: Option<f64>,
    #[serde(default)]
    currency: Option<String>,
}

#[derive(Debug, Deserialize)]
struct Indicators {
    #[serde(default)]
    quote: Vec<QuoteSeries>,
}

#[derive(Debug, Deserialize)]
struct QuoteSeries {
    /// Nulls appear for minutes with no trades, so the element type is optional
    /// and the gaps are dropped rather than read as zero — a zero would draw
    /// the sparkline straight to the floor.
    #[serde(default)]
    close: Vec<Option<f64>>,
}

/// The most of the quote service's own error text that is kept, in cells.
/// Yahoo's run to about forty — `No data found, symbol may be delisted` — so
/// this is twice anything real and still bounds what a frame copies.
const MAX_DETAIL: usize = 80;

/// Turn a v8 chart response into a [`Quote`].
///
/// Split from the request so it can be tested against captured JSON; the test
/// suite makes no network calls.
pub fn parse_chart(body: &str) -> Result<Quote> {
    let parsed: ChartEnvelope = serde_json::from_str(body).context("parsing the chart response")?;

    if let Some(error) = parsed.chart.error {
        let detail = error
            .description
            .or(error.code)
            .unwrap_or_else(|| "unknown error".to_string());
        // Clipped here, where somebody else's text comes in. The board draws
        // this on every frame, and the body it came in may be ten megabytes.
        let detail = crate::grid::truncate(&detail, MAX_DETAIL);
        anyhow::bail!("the quote service rejected the symbol: {detail}");
    }

    let result = parsed
        .chart
        .result
        .into_iter()
        .next()
        .context("the quote service returned no data for this symbol")?;

    let price = result
        .meta
        .regular_market_price
        .context("the response carried no price")?;

    // `chartPreviousClose` is the one that lines up with the returned series;
    // `previousClose` is the fallback for responses that omit it.
    let previous_close = result
        .meta
        .chart_previous_close
        .or(result.meta.previous_close)
        .unwrap_or(price);

    let series = result
        .indicators
        .and_then(|i| i.quote.into_iter().next())
        .map(|q| bounded(q.close.into_iter().flatten().collect()))
        .unwrap_or_default();

    let quote = Quote {
        symbol: result.meta.symbol,
        price,
        previous_close,
        currency: result.meta.currency,
        series,
        delayed: false,
    };

    // The parser refuses a number too large for an `f64`, but two it accepts
    // can still make one: `1e308` less `-1e308` is infinite, and so is `1e308`
    // over a close of `1e-10`. Clamping either to zero would put `+0.00%`
    // beside a figure three hundred digits long, and that is what
    // `change_pct` already does for a close too near zero to divide by — so a
    // moved price beside such a close is refused with the overflows. A close
    // of zero with no change is left to the clamp, because there "nothing has
    // happened" is true. A refused row falls back the way any failed fetch
    // does — to the last good price with its age, or to `–` — with the reason
    // front-loaded for a status row that is cut to the panel.
    let unmeasurable = quote.close_is_zero() && quote.change().abs() >= f64::EPSILON;
    anyhow::ensure!(
        quote.change().is_finite() && quote.change_pct().is_finite() && !unmeasurable,
        "numbers out of range in the response"
    );
    Ok(quote)
}

/// The most intraday samples a quote keeps.
///
/// The chart asked for is a day at five-minute intervals, which is 78 points,
/// and a day of one-minute bars would be 390; the markets panel draws its
/// sparkline twelve cells wide at most. Nothing bounded it before, so a body
/// at `ureq`'s ten-megabyte cap
/// could hold two million samples, kept resident for every symbol until the
/// next fetch and walked again each time a sparkline was drawn from them — the
/// unbounded headline in `feed`, reached through a number instead of a string.
const MAX_SERIES: usize = 1_000;

/// `series`, averaged down to [`MAX_SERIES`] samples if it is longer.
///
/// Averaged rather than cut: the sparkline is the whole day, so keeping the
/// first thousand samples would draw a morning beside the latest price, and
/// keeping the last thousand would draw an afternoon under a column headed
/// `today`. Every genuine series is far shorter and comes back untouched.
fn bounded(series: Vec<f64>) -> Vec<f64> {
    if series.len() <= MAX_SERIES {
        return series;
    }
    bucket_means(&series, MAX_SERIES).collect()
}

impl QuoteSource for YahooChart {
    fn name(&self) -> &'static str {
        "yahoo"
    }

    fn fetch(&self, symbol: &str) -> Result<Quote> {
        let url = format!(
            "https://query1.finance.yahoo.com/v8/finance/chart/{}\
             ?range=1d&interval=5m",
            crate::fetch::percent_encode(symbol)
        );
        let body = http_get(&url)?;
        parse_chart(&body)
    }
}

/// A blocking GET with a timeout, presenting a browser user agent.
///
/// **Makes no request under `cfg(test)`**, because [`crate::fetch::get`]
/// refuses every one there. The rule is that no test opens a socket (#147),
/// and building a dashboard in a test was once enough to break it: a panel
/// spawns its fetch thread when it is *constructed*, and `Layout::default()`
/// places the stocks panel, so a Windows runner got a real HTTP 404 back for
/// a made-up symbol and rendered it. This function refused for itself from
/// then on, while the weather and news panels and the update check went on
/// reaching the network through `fetch::get`; the guard lives there now,
/// where every request goes through, and a second copy here said nothing
/// the first does not.
fn http_get(url: &str) -> Result<String> {
    crate::fetch::get(url, HTTP_TIMEOUT, Some(BROWSER_UA)).map_err(explain)
}

/// What a failed request says on the board.
///
/// The 429 message used to end by telling the reader that another
/// `[stocks].source` was needed, when `yahoo` is the only one there is and any
/// other value is refused at startup. It says what is true now: Yahoo limits by
/// address, the panel tries again on its own, and on a datacenter or VPN
/// address waiting will not help. The fact comes first, because the status row
/// is cut to the panel and what goes is the end of the sentence. When a second
/// source ships, the advice to choose it belongs back here.
fn explain(error: ureq::Error) -> anyhow::Error {
    match error {
        ureq::Error::StatusCode(429) => anyhow::anyhow!(
            "rate-limited by Yahoo (HTTP 429), which limits by IP address; \
             wait and it tries again, though datacenter and VPN addresses are \
             refused outright"
        ),
        ureq::Error::StatusCode(404) => {
            anyhow::anyhow!("no such symbol")
        }
        ureq::Error::StatusCode(code) => {
            anyhow::anyhow!("the quote service returned HTTP {code}")
        }
        other => anyhow::anyhow!("network request failed: {other}"),
    }
}

// ---------------------------------------------------------------------------
// The watchlist
// ---------------------------------------------------------------------------

/// Symbols the user is watching, persisted so the UI can add and remove them.
///
/// This is a *data* file next to the tasks and notes, not part of the config.
/// That is the whole reason the panel can edit it: mirador deliberately never
/// rewrites the config file, so a watchlist that lived there could only ever be
/// changed in an editor. Config still seeds the first run and nothing more.
#[derive(Debug)]
pub struct Watchlist {
    path: PathBuf,
    symbols: Vec<String>,
    dirty: bool,
    pub last_error: Option<String>,
}

/// Owned when read and borrowed when written, so a save does not copy the
/// list to serialise it.
#[derive(Debug, Default, Serialize, Deserialize)]
struct WatchlistFile<L = Vec<String>> {
    #[serde(default)]
    symbols: L,
}

/// The watchlist's header, and what its errors call it.
const WATCHLIST_FILE: crate::store::TomlFile = crate::store::TomlFile {
    what: "the watchlist",
    header: "# mirador watchlist. Safe to edit by hand.\n\
             # Only the symbols live here — prices are never written to disk.",
};

impl Watchlist {
    /// Load from `path`, falling back to `seed` when the file does not exist.
    pub fn load(path: impl Into<PathBuf>, seed: &[String]) -> Result<Self> {
        let path = path.into();
        let (symbols, dirty) = match WATCHLIST_FILE.read::<WatchlistFile>(&path)? {
            Some(file) => (file.symbols, false),
            // Seeded, and marked dirty so the seed is written out once and the
            // user has a file to edit by hand if they prefer.
            None => (seed.to_vec(), !seed.is_empty()),
        };

        Ok(Self {
            path,
            symbols: symbols.into_iter().map(|s| normalise(&s)).collect(),
            dirty,
            last_error: None,
        })
    }

    pub fn path(&self) -> &Path {
        &self.path
    }

    pub fn symbols(&self) -> &[String] {
        &self.symbols
    }

    /// Add a symbol. Returns false when it is blank or already present.
    pub fn add(&mut self, symbol: &str) -> bool {
        let symbol = normalise(symbol);
        if symbol.is_empty() || self.symbols.contains(&symbol) {
            return false;
        }
        self.symbols.push(symbol);
        self.dirty = true;
        true
    }

    pub fn remove(&mut self, symbol: &str) -> bool {
        let symbol = normalise(symbol);
        let before = self.symbols.len();
        self.symbols.retain(|s| *s != symbol);
        let removed = self.symbols.len() != before;
        self.dirty |= removed;
        removed
    }

    /// Write atomically if there are pending changes.
    pub fn save(&mut self) -> Result<()> {
        if !self.dirty {
            return Ok(());
        }
        WATCHLIST_FILE.write(
            &self.path,
            &WatchlistFile {
                symbols: self.symbols.as_slice(),
            },
        )?;

        self.dirty = false;
        Ok(())
    }

    pub fn save_reporting(&mut self) {
        crate::store::report(self.save(), &mut self.last_error);
    }
}

/// Symbols are upper-case and unpadded everywhere, so `aapl` and `AAPL ` cannot
/// both end up in the list as separate entries.
fn normalise(symbol: &str) -> String {
    symbol.trim().to_uppercase()
}

// ---------------------------------------------------------------------------
// Sparkline
// ---------------------------------------------------------------------------

/// Eight levels in a single cell.
const BLOCKS: [char; 8] = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];

/// A one-row sparkline of `series`, exactly `width` cells wide.
///
/// Blocks rather than the braille used by the CPU and network graphs: braille
/// packs two samples into a cell by splitting it vertically, which is the right
/// trade when a graph owns several rows and needs horizontal resolution. In a
/// single row inside a table it just halves the height resolution for detail
/// nobody can read at that size.
///
/// A flat series draws at mid-height rather than at the floor, because a stock
/// that has not moved has not crashed.
pub fn sparkline(series: &[f64], width: usize) -> String {
    if width == 0 || series.is_empty() {
        return String::new();
    }

    let low = series.iter().copied().fold(f64::INFINITY, f64::min);
    let high = series.iter().copied().fold(f64::NEG_INFINITY, f64::max);
    let span = high - low;

    // Bucket the samples so the whole series is represented however narrow
    // the column is, rather than showing only the first `width` of them.
    bucket_means(series, width)
        .map(|mean| {
            if span.abs() < f64::EPSILON {
                return BLOCKS[BLOCKS.len() / 2];
            }
            let ratio = (mean - low) / span;
            #[expect(
                clippy::cast_possible_truncation,
                clippy::cast_sign_loss,
                reason = "ratio is clamped to 0..=1, so the product is a valid index"
            )]
            let index = (ratio * (BLOCKS.len() - 1) as f64).round() as usize;
            BLOCKS[index.min(BLOCKS.len() - 1)]
        })
        .collect()
}

/// The mean of each of the `n` runs `series` is cut into, oldest first.
///
/// Shared by the sparkline and by [`bounded`], so a series averaged down at
/// parse is cut along the same lines a sparkline cuts it. Every sample lands
/// in exactly one run when the series is longer than `n`; when it is shorter,
/// a run repeats a sample rather than coming out empty, so a short series
/// still fills every cell. `series` must not be empty.
fn bucket_means(series: &[f64], n: usize) -> impl Iterator<Item = f64> + '_ {
    let len = series.len();
    (0..n).map(move |run| {
        let start = run * len / n;
        let end = (((run + 1) * len) / n).max(start + 1);
        let bucket = &series[start.min(len - 1)..end.min(len)];
        bucket.iter().sum::<f64>() / bucket.len() as f64
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::store::testing::TempDir;

    /// The rule that no test opens a socket, made checkable (#147).
    ///
    /// It used to rest on `parse_chart` being split from the request — true,
    /// and not enough: constructing a stocks panel spawns a fetch thread, and
    /// `Layout::default()` places that panel, so building a dashboard in a test
    /// was sufficient to call Yahoo. The guard is [`crate::fetch::get`]'s,
    /// which refuses under `cfg(test)` every request the program makes; this
    /// holds the quote source to it from the outside. Delete the `cfg!(test)`
    /// branch there and this goes red rather than going quiet — on a real
    /// request to Yahoo, which either answers, so there is no error to expect,
    /// or fails with something other than the guard's own words.
    #[test]
    fn the_network_is_refused_while_testing() {
        let err = YahooChart
            .fetch("AAPL")
            .expect_err("a live fetch must not be possible from a test");
        assert!(
            err.to_string().contains("under cfg(test)"),
            "the refusal must come from fetch::get's cfg(test) guard, not from the wire: {err}"
        );
    }

    /// A trimmed but structurally faithful v8 chart response.
    const SAMPLE: &str = r#"{
      "chart": {
        "result": [{
          "meta": {
            "currency": "USD",
            "symbol": "AAPL",
            "regularMarketPrice": 213.5,
            "chartPreviousClose": 211.0,
            "previousClose": 210.0
          },
          "timestamp": [1, 2, 3, 4],
          "indicators": {
            "quote": [{ "close": [211.0, null, 212.5, 213.5] }]
          }
        }],
        "error": null
      }
    }"#;

    /// Shown, or refused with the front of the reason the status row gives.
    const SHOWN: Option<&str> = None;
    const UNPARSED: Option<&str> = Some("parsing the chart response");
    const OUT_OF_RANGE: Option<&str> = Some("numbers out of range");

    /// The bodies `hostile_numbers_never_reach_the_screen_as_inf_or_nan` feeds
    /// the parser: a name, the price, the previous close, the series, and what
    /// must become of it.
    const HOSTILE: &[(&str, &str, &str, &str, Option<&str>)] = &[
        // Out-of-range literals are refused outright by the JSON parser,
        // which is a stronger defence than any guard downstream.
        (
            "a price too large for an f64",
            "1e400",
            "211.0",
            "[211.0, 212.5]",
            UNPARSED,
        ),
        (
            "a previous close too large",
            "213.5",
            "1e400",
            "[211.0, 212.5]",
            UNPARSED,
        ),
        (
            "a value in the series too large",
            "1.0",
            "1.0",
            "[1e400, 1.0]",
            UNPARSED,
        ),
        // Finite on the wire, and not once divided or subtracted.
        (
            "a tiny previous close",
            "1e308",
            "1e-10",
            "[1.0]",
            OUT_OF_RANGE,
        ),
        (
            "a change too large for an f64",
            "1e308",
            "-1e308",
            "[1.0]",
            OUT_OF_RANGE,
        ),
        // Too near zero to divide by, so `change_pct` answers zero, and
        // that is true only while nothing has moved.
        (
            "a previous close of zero",
            "213.5",
            "0.0",
            "[211.0, 212.5]",
            OUT_OF_RANGE,
        ),
        (
            "a close below the divisor guard",
            "1e308",
            "1e-300",
            "[1.0]",
            OUT_OF_RANGE,
        ),
        ("nothing traded at all", "0.0", "0.0", "[]", SHOWN),
        // Absurd, but finite and measurable: how large a price may be is
        // a different question from whether it can be shown.
        (
            "a price beyond any market",
            "1e308",
            "211.0",
            "[1.0]",
            SHOWN,
        ),
        (
            "negative prices",
            "-5.0",
            "-10.0",
            "[-1.0, -2.0, -3.0]",
            SHOWN,
        ),
        ("an empty series", "1.0", "1.0", "[]", SHOWN),
        ("a flat series", "1.0", "1.0", "[7.0, 7.0, 7.0]", SHOWN),
    ];

    /// A quote response is untrusted network input carrying numbers straight
    /// into arithmetic and onto a screen. These are the shapes that break float
    /// code: a value too large for an `f64`, a sum or quotient of two finite
    /// values that is not, a divisor of zero, a series with no span, nothing
    /// at all.
    ///
    /// The outcome to insist on is that a row never reads `inf%` or `NaN`, nor
    /// a percentage that contradicts the change beside it. A wrong-looking
    /// number in a money column is worse than a missing one, which is why a
    /// refused quote leaves the row its last good price, muted and labelled
    /// with its age, or `–` when there never was one.
    ///
    /// Each row says whether the quote must be shown or refused, and a refusal
    /// names the front of its reason: the reason is what the status row says
    /// about the symbol, cut to the panel's width, so it has to lead with what
    /// was wrong. This test used to skip any body that failed to parse, on the
    /// reasoning that the JSON parser refuses `1e400` outright — which is true,
    /// and was pinned by nothing, and the skip would as happily have passed a
    /// body refused for any other reason. Two bodies the parser *accepts*
    /// overflowed all the same: `1e308` over a close of `1e-10` read `+inf%`,
    /// and `1e308` over `-1e308` read `+inf` in the change column itself. And
    /// a price beside a close of zero read `+0.00%` beside a change of the
    /// whole price — `change_pct`'s guard saying "nothing has happened" about
    /// a quote where something had. The contradiction was asserted by nothing
    /// until the `negative prices` row was checked for it, and failed: a rise
    /// from −10 to −5 read `+5.00` beside `-50.00%`, the percentage divided by
    /// a close whose sign it took.
    #[test]
    fn hostile_numbers_never_reach_the_screen_as_inf_or_nan() {
        let swap = |price: &str, prev: &str, series: &str| {
            SAMPLE
                .replace("213.5,", &format!("{price},"))
                .replace(
                    "\"chartPreviousClose\": 211.0",
                    &format!("\"chartPreviousClose\": {prev}"),
                )
                .replace("[211.0, null, 212.5, 213.5]", series)
        };

        for &(name, price, prev, series, refusal) in HOSTILE {
            let parsed = parse_chart(&swap(price, prev, series));
            if let Some(reason) = refusal {
                let err = parsed.map_or_else(
                    |e| format!("{e:#}"),
                    |q| panic!("{name}: must be refused, got {q:?}"),
                );
                assert!(err.starts_with(reason), "{name}: `{reason}…`, got `{err}`");
                continue;
            }
            let quote = parsed.unwrap_or_else(|e| panic!("{name}: must be shown, got {e:#}"));

            assert!(quote.price.is_finite(), "{name}: price is {}", quote.price);
            assert!(
                quote.change().is_finite(),
                "{name}: `{:+.2}` would read as a broken panel",
                quote.change()
            );
            assert!(
                quote.change_pct().is_finite(),
                "{name}: `{}%` would read as a broken panel",
                quote.change_pct()
            );
            // The percentage runs the way the change does, or one is zero:
            // their product is negative only when the two signs disagree.
            let (change, pct) = (quote.change(), quote.change_pct());
            assert!(
                change * pct >= 0.0,
                "{name}: `{change:+.2}` beside `{pct:+.2}%` contradicts itself"
            );
            // And the sparkline neither panics nor overruns its width.
            for width in [0, 1, 8, 40] {
                assert!(
                    sparkline(&quote.series, width).chars().count() <= width,
                    "{name}: sparkline overran {width} cells"
                );
            }
        }
    }

    #[test]
    fn a_chart_response_becomes_a_quote() {
        let q = parse_chart(SAMPLE).unwrap();
        assert_eq!(q.symbol, "AAPL");
        assert!((q.price - 213.5).abs() < f64::EPSILON);
        assert!(
            (q.previous_close - 211.0).abs() < f64::EPSILON,
            "chartPreviousClose wins: it matches the returned series"
        );
        assert_eq!(q.currency.as_deref(), Some("USD"));
    }

    #[test]
    fn gaps_in_the_series_are_dropped_rather_than_read_as_zero() {
        let q = parse_chart(SAMPLE).unwrap();
        assert_eq!(
            q.series,
            vec![211.0, 212.5, 213.5],
            "a null minute must not become a zero and floor the sparkline"
        );
    }

    #[test]
    fn the_day_change_is_measured_against_the_previous_close() {
        let q = parse_chart(SAMPLE).unwrap();
        assert!((q.change() - 2.5).abs() < 1e-9);
        assert!((q.change_pct() - (2.5 / 211.0 * 100.0)).abs() < 1e-9);
    }

    #[test]
    fn a_zero_previous_close_reports_no_change_rather_than_infinity() {
        let q = Quote {
            symbol: "NEW".into(),
            price: 10.0,
            previous_close: 0.0,
            currency: None,
            series: vec![],
            delayed: false,
        };
        assert!(q.change_pct().is_finite(), "`inf%` reads as a broken panel");
        assert!((q.change_pct() - 0.0).abs() < f64::EPSILON);
    }

    #[test]
    fn an_error_envelope_becomes_an_error_not_an_empty_quote() {
        let body = r#"{"chart":{"result":[],"error":{"code":"Not Found",
                       "description":"No data found, symbol may be delisted"}}}"#;
        let err = parse_chart(body).unwrap_err().to_string();
        assert!(err.contains("delisted"), "got `{err}`");
    }

    /// The quote service's error text is somebody else's string, and the board
    /// draws it on every frame, formatting it into the status row before the
    /// row cuts it to the panel. Unbounded, a response up to `ureq`'s 10 MB
    /// cap decided how much each frame copied — the `feed` and `themes`
    /// findings again, at the third parser that reads the network.
    #[test]
    fn the_services_error_text_is_bounded_where_it_is_read() {
        let huge = "symbol may be delisted ".repeat(50_000);
        let body = format!(
            r#"{{"chart":{{"result":[],"error":{{"code":"Not Found","description":"{huge}"}}}}}}"#
        );
        let err = format!("{:#}", parse_chart(&body).unwrap_err());
        assert!(err.len() < 200, "a {}-byte error survived", err.len());
        assert!(err.ends_with('\u{2026}'), "a cut reason says so: `{err}`");
    }

    /// `[stocks].source` takes one value, and the HTTP 429 message told the
    /// reader to choose another — which mirador then refuses at startup. It
    /// says what is true instead, and says it first, because the status row is
    /// cut to the panel and the end of a sentence is the part that is lost.
    #[test]
    fn a_rate_limit_says_what_is_true() {
        let message = format!("{:#}", explain(ureq::Error::StatusCode(429)));
        if SOURCE_NAMES.len() == 1 {
            assert!(
                !message.contains("[stocks].source"),
                "there is no other source to choose: `{message}`"
            );
        }
        assert!(
            crate::grid::truncate(&message, 30).contains("rate-limited by Yahoo"),
            "the fact has to survive a narrow status row: `{message}`"
        );
        assert!(
            message.contains("IP address"),
            "say why waiting may not help: `{message}`"
        );
    }

    #[test]
    fn a_response_with_no_price_is_an_error_rather_than_a_zero() {
        let body = r#"{"chart":{"result":[{"meta":{"symbol":"X"}}],"error":null}}"#;
        assert!(
            parse_chart(body).is_err(),
            "a missing price must not render as 0.00"
        );
    }

    #[test]
    fn a_response_without_a_series_still_yields_a_quote() {
        // The panel must survive a source that has no intraday data: the price
        // is the point, the sparkline is a bonus.
        let body = r#"{"chart":{"result":[{"meta":{"symbol":"X",
                       "regularMarketPrice":5.0,"previousClose":4.0}}],"error":null}}"#;
        let q = parse_chart(body).unwrap();
        assert!(q.series.is_empty(), "{:?}", q.series);
        assert!((q.change() - 1.0).abs() < f64::EPSILON);
    }

    /// The chart's samples are somebody else's numbers, and nothing bounded
    /// how many were kept: the request asks for 78, and a body at `ureq`'s cap
    /// holds two million, resident for every symbol and walked by every
    /// sparkline drawn from them. Averaged down rather than cut, so the line
    /// still runs from the open to the close.
    #[test]
    fn a_series_longer_than_any_real_day_is_averaged_down_to_the_bound() {
        let rising: Vec<String> = (0..100_000).map(|i| format!("{i}.0")).collect();
        let body = SAMPLE.replace(
            "[211.0, null, 212.5, 213.5]",
            &format!("[{}]", rising.join(",")),
        );
        let q = parse_chart(&body).unwrap();
        assert_eq!(q.series.len(), MAX_SERIES, "bounded where it is read");
        let (first, last) = (q.series[0], q.series[MAX_SERIES - 1]);
        assert!(
            first < 100.0 && last > 99_900.0,
            "the whole day, not the first or last of it: {first} .. {last}"
        );
        assert!(
            q.series.windows(2).all(|pair| pair[0] < pair[1]),
            "and still in the order it was traded"
        );
    }

    /// The bound is far above anything a real chart carries, so a real one
    /// is kept sample for sample: a day of one-minute bars, five times the
    /// five-minute series the request asks for.
    #[test]
    fn a_real_days_series_is_kept_sample_for_sample() {
        // Quarters, which a float holds exactly, so the comparison is exact.
        let day: Vec<f64> = (0..390).map(|i| 200.0 + f64::from(i) * 0.25).collect();
        let close: Vec<String> = day.iter().map(f64::to_string).collect();
        let body = SAMPLE.replace(
            "[211.0, null, 212.5, 213.5]",
            &format!("[{}]", close.join(",")),
        );
        assert_eq!(parse_chart(&body).unwrap().series, day);
    }

    #[test]
    fn only_advertised_sources_can_be_built() {
        for name in SOURCE_NAMES {
            assert!(
                source_for(name).is_some(),
                "{name} is advertised but absent"
            );
        }
        assert!(source_for("finnhub").is_none(), "ruled out on licence");
        assert!(source_for("").is_none());
    }

    // -- sparkline ----------------------------------------------------------

    #[test]
    fn a_sparkline_is_exactly_as_wide_as_it_was_asked_to_be() {
        for width in [1, 5, 12, 40] {
            let line = sparkline(&[1.0, 2.0, 3.0, 4.0, 5.0], width);
            assert_eq!(line.chars().count(), width, "at width {width}");
        }
    }

    #[test]
    fn a_rising_series_ends_higher_than_it_starts() {
        let line: Vec<char> = sparkline(&[1.0, 2.0, 3.0, 4.0], 4).chars().collect();
        assert_eq!(line[0], BLOCKS[0]);
        assert_eq!(line[3], BLOCKS[7]);
    }

    #[test]
    fn a_flat_series_draws_at_mid_height_not_on_the_floor() {
        let line = sparkline(&[7.0; 6], 6);
        assert!(
            line.chars().all(|c| c == BLOCKS[BLOCKS.len() / 2]),
            "a stock that has not moved has not crashed: `{line}`"
        );
    }

    #[test]
    fn a_sparkline_covers_the_whole_series_even_when_narrow() {
        // Two cells for ten samples must average across all ten. Taking only
        // the first two would hide the whole day and leave the two cells
        // almost level; averaging puts them far apart.
        let level = |c: char| BLOCKS.iter().position(|b| *b == c).unwrap();

        let mut series: Vec<f64> = (0..10).map(f64::from).collect();
        let line: Vec<char> = sparkline(&series, 2).chars().collect();
        assert!(
            level(line[1]) >= level(line[0]) + 3,
            "the tail of a rising series must sit well above its head: `{}`",
            line.iter().collect::<String>()
        );

        series.reverse();
        let line: Vec<char> = sparkline(&series, 2).chars().collect();
        assert!(
            level(line[0]) >= level(line[1]) + 3,
            "and a falling series inverts: `{}`",
            line.iter().collect::<String>()
        );
    }

    #[test]
    fn degenerate_sparklines_do_not_panic() {
        assert_eq!(sparkline(&[], 10), "");
        assert_eq!(sparkline(&[1.0], 0), "");
        assert_eq!(sparkline(&[1.0], 3).chars().count(), 3);
    }

    // -- watchlist ----------------------------------------------------------

    fn watchlist(name: &str, seed: &[&str]) -> (Watchlist, TempDir) {
        let dir = TempDir::new(&format!("watch-{name}"));
        let seed: Vec<String> = seed.iter().map(|s| (*s).to_string()).collect();
        let list = Watchlist::load(dir.join("watchlist.toml"), &seed).unwrap();
        (list, dir)
    }

    #[test]
    fn a_missing_watchlist_is_seeded_from_config_and_then_owns_itself() {
        let (mut list, guard) = watchlist("seed", &["AAPL", "MSFT"]);
        assert_eq!(list.symbols(), ["AAPL", "MSFT"]);
        list.save().unwrap();

        // Reloading with a *different* seed must not resurrect it: once the
        // file exists it is the truth, or removing a symbol would never stick.
        let reloaded =
            Watchlist::load(guard.join("watchlist.toml"), &["TSLA".to_string()]).unwrap();
        assert_eq!(reloaded.symbols(), ["AAPL", "MSFT"]);
    }

    #[test]
    fn symbols_are_normalised_so_the_same_ticker_cannot_appear_twice() {
        let (mut list, _g) = watchlist("dupes", &[]);
        assert!(list.add("aapl"));
        assert!(!list.add("AAPL"), "case must not create a second entry");
        assert!(!list.add("  aapl  "), "nor padding");
        assert_eq!(list.symbols(), ["AAPL"]);
    }

    #[test]
    fn blank_symbols_are_refused() {
        let (mut list, _g) = watchlist("blank", &[]);
        assert!(!list.add(""));
        assert!(!list.add("   "));
        assert!(list.symbols().is_empty(), "{:?}", list.symbols());
    }

    #[test]
    fn removing_a_symbol_survives_a_reload() {
        let (mut list, guard) = watchlist("remove", &["AAPL", "MSFT"]);
        assert!(list.remove("aapl"), "removal is case-insensitive too");
        list.save().unwrap();

        let reloaded = Watchlist::load(guard.join("watchlist.toml"), &[]).unwrap();
        assert_eq!(reloaded.symbols(), ["MSFT"]);
    }

    /// A watchlist exactly as 1.20.0 wrote it, captured from that build: a
    /// class share and an index, the two symbol shapes that are not letters.
    const WRITTEN_BY_1_20_0: &str = r#"# mirador watchlist. Safe to edit by hand.
# Only the symbols live here — prices are never written to disk.

symbols = [
    "AAPL",
    "BRK.B",
    "^GSPC",
]
"#;

    /// Reading and writing go through [`crate::store::TomlFile`] now, and a
    /// file someone keeps by hand must come back exactly as it was. Removed
    /// before the save, so the comparison is of what the save wrote.
    #[test]
    fn a_file_from_1_20_0_is_written_back_byte_for_byte() {
        let (_, guard) = watchlist("bytes", &[]);
        let path = guard.join("watchlist.toml");
        std::fs::write(&path, WRITTEN_BY_1_20_0).unwrap();

        let mut list = Watchlist::load(&path, &["TSLA".to_string()]).unwrap();
        assert_eq!(list.symbols(), ["AAPL", "BRK.B", "^GSPC"]);
        std::fs::remove_file(&path).unwrap();
        list.dirty = true;
        list.save().unwrap();

        assert_eq!(std::fs::read_to_string(&path).unwrap(), WRITTEN_BY_1_20_0);
    }

    #[test]
    fn an_empty_seed_writes_nothing_so_the_user_is_not_given_a_file_of_nothing() {
        let (mut list, guard) = watchlist("empty", &[]);
        list.save().unwrap();
        assert!(
            !guard.join("watchlist.toml").exists(),
            "nothing to persist yet"
        );
    }
}