tix/

search.rs

//! Shared search corpus and matchers for `tix search` (CLI, WP04) and the
//! `/` fuzzy filter (TUI, WP05).
//!
//! Both consumers search **exactly the same corpus**: the complete serialized
//! markdown of every issue (`Issue::to_file_contents()`, i.e. frontmatter +
//! body + comments). A single engine here keeps the CLI and TUI behavior from
//! drifting (C-005, FR-012):
//!
//! - [`Corpus::build`] snapshots every issue's full file text.
//! - [`search_substring`] is the case-insensitive single-occurrence matcher
//!   the CLI uses, returning matched-line context.
//! - [`fuzzy_score`] is the deterministic subsequence scorer the TUI uses to
//!   rank filter results on each keystroke.
//!
//! Nothing here touches the `-assets/` directories (C-005): binary contents
//! are never indexed, and [`Corpus::build`] inherits that from
//! [`Store::list`], which already excludes non-`.md` files and `-assets` dirs.

use serde::{Deserialize, Serialize};

use crate::error::Result;
use crate::model::Issue;
use crate::storage::Store;

/// The corpus: one `Issue` per file (in [`Store::list`] order) and the
/// byte-for-byte serialized file text matching it.
pub struct Corpus {
    pub issues: Vec<Issue>,
    pub texts: Vec<String>,
}

impl Corpus {
    /// Snapshot the full serialized text of every issue under `store`.
    ///
    /// `texts[i]` is exactly `issues[i].to_file_contents()`, so the corpus is
    /// byte-identical to the on-disk files (modulo whatever the serializer
    /// itself produces). Files are read once here, through [`Store::list`];
    /// consumers never re-read them (C-005/NFR-007 keep the corpus a single,
    /// stable source).
    pub fn build(store: &Store) -> Result<Corpus> {
        Self::build_with(store, false)
    }

    /// Snapshot the corpus, optionally including archived issues (issue #1492).
    ///
    /// `with_archived == false` is the default path and reads
    /// [`Store::list`], which never opens an archived file. `true` reads
    /// [`Store::list_all`] so `tix search --with-archived` can match the archived
    /// set; the archived issues carry `archived == true`.
    pub fn build_with(store: &Store, with_archived: bool) -> Result<Corpus> {
        let issues = if with_archived {
            store.list_all()?
        } else {
            store.list()?
        };
        let texts = issues
            .iter()
            .map(|issue| issue.to_file_contents())
            .collect();
        Ok(Corpus { issues, texts })
    }

    /// Index of the issue with `number` `n`, if present (stable, linear scan).
    pub fn by_number(&self, n: u32) -> Option<usize> {
        self.issues.iter().position(|issue| issue.number == n)
    }
}

/// One substring search hit: the issue and every corpus line that contains
/// the matched query (context for the CLI result block, NFR-007).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SearchHit {
    pub issue: Issue,
    pub matched_lines: Vec<String>,
}

/// Case-insensitive substring search over the corpus.
///
/// For each corpus text containing `query` (case-insensitive), every line
/// containing the match is collected verbatim as matched-line context. Hits
/// are ordered by issue `number` ascending (stable, NFR-007).
///
/// An empty query matches **nothing** by contract: the CLI refuses it via
/// clap, and the TUI treats an empty filter as "no filter" — callers decide,
/// this function returns an empty vec so they never see a surprise.
pub fn search_substring(corpus: &Corpus, query: &str) -> Vec<SearchHit> {
    if query.is_empty() {
        return Vec::new();
    }
    let needle = query.to_lowercase();
    let mut hits: Vec<SearchHit> = Vec::new();
    for (issue, text) in corpus.issues.iter().zip(corpus.texts.iter()) {
        let hay = text.to_lowercase();
        if !hay.contains(&needle) {
            continue;
        }
        let matched_lines: Vec<String> = text
            .lines()
            .filter(|line| line.to_lowercase().contains(&needle))
            .map(str::to_string)
            .collect();
        hits.push(SearchHit {
            issue: issue.clone(),
            matched_lines,
        });
    }
    hits.sort_by_key(|hit| hit.issue.number);
    hits
}

/// Deterministic fuzzy subsequence score: higher is a better match, `None`
/// when `query` is not a subsequence of `haystack` (case-insensitive).
///
/// The scorer is the fzf/vim-style "fast substring" heuristic, kept simple
/// and pure (no normalization, no unicode tables, no dependencies):
///
/// - every matched character contributes a presence bonus plus an
///   earlier-position bonus (`1000 - position`), so matches near the start of
///   the text outrank those buried deep in it;
/// - adjacent matched characters (contiguous runs) get a run bonus;
/// - a match that starts at the very beginning gets a prefix bonus;
/// - an exact match (equal strings, case-insensitive) dominates.
///
/// An empty query is an implicit match with score `Some(0)` — the TUI treats
/// it as "no filter". Deterministic and fast enough for > 500 issues per
/// keystroke (verified by the perf tripwire test).
pub fn fuzzy_score(query: &str, haystack: &str) -> Option<u32> {
    let q = query.to_lowercase();
    let h = haystack.to_lowercase();
    if q.is_empty() {
        return Some(0);
    }
    if q == h {
        return Some(EXACT_MATCH_SCORE);
    }
    let positions = greedy_subsequence_positions(&q, &h)?;
    let mut score = 0u32;
    let mut prev: Option<usize> = None;
    for pos in &positions {
        score += 100;
        score += (1000 - (*pos).min(1000)) as u32;
        if prev.is_some_and(|p| *pos == p + 1) {
            score += RUN_BONUS;
        }
        prev = Some(*pos);
    }
    if positions.first() == Some(&0) {
        score += PREFIX_BONUS;
    }
    Some(score)
}

/// Bonus for a contiguous pair of matched characters.
const RUN_BONUS: u32 = 150;
/// Bonus when the first matched character is the first character of the text.
const PREFIX_BONUS: u32 = 500;
/// Score for an exact (case-insensitive) equality — dominates any partial.
const EXACT_MATCH_SCORE: u32 = 50_000;

/// Greedy leftmost subsequence match, case-insensitive. Returns the haystack
/// positions of `query`'s characters in order, or `None` when `query` is not
/// a subsequence of `haystack`.
fn greedy_subsequence_positions(query: &str, haystack: &str) -> Option<Vec<usize>> {
    let q: Vec<char> = query.chars().collect();
    if q.is_empty() {
        return Some(Vec::new());
    }
    let h: Vec<char> = haystack.chars().collect();
    let mut positions = Vec::with_capacity(q.len());
    let mut hi = 0usize;
    /* tolerate differing-cased surrogates the same way the lowercase scan does */
    for qc in &q {
        let found = h[hi..]
            .iter()
            .position(|hc| *hc == *qc)
            .map(|off| off + hi)?;
        positions.push(found);
        hi = found + 1;
    }
    Some(positions)
}

// ---------------------------------------------------------------------------
// Structured filtering (FR-007..FR-013)
// ---------------------------------------------------------------------------

/// A selectable structured-filter criterion.
///
/// [`FilterField::ALL`] is the single ordered field list the filter modal
/// renders its rows from (risk: field/modal drift) and [`StructuredFilter`]
/// evaluates over — adding a criterion (FR-011) is one more `Option<String>`
/// field on [`StructuredFilter`] plus one variant / match arm here.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FilterField {
    Assignee,
    Label,
    Status,
    Priority,
    Cycle,
    Milestone,
    Reviewer,
    StartDate,
    DueDate,
    /// An issue's **direct** parent, by selector (WP06 T024).
    Parent,
    /// An issue's resolved workflow category, by category key (WP08 T034).
    ///
    /// **Derived, not stored.** Unlike the nine above, this criterion matches
    /// nothing an issue's file contains: there is no `category` frontmatter key
    /// (research R2), and the value comes from the issue's `status` resolved
    /// through the board's `category_map`. See [`FilterField::key`] for what
    /// that means for diagnostics.
    Category,
}

impl FilterField {
    /// The criteria in modal row order (research D-05).
    ///
    /// `Parent` is **appended** rather than interleaved: a row's position is a
    /// user's muscle memory and a TUI test's golden index, and moving eight
    /// existing rows to make room for a ninth helps nobody (T024 step 2).
    ///
    /// `Category` is **appended** after `Parent`, for the same reason T024 step 2
    /// gave: a row's position is a user's muscle memory and the TUI's golden
    /// index, and it is also the position a user reaches last. A category is the
    /// one criterion a user cannot reach from the file itself, so it is the one
    /// they will look up last.
    pub const ALL: [FilterField; 11] = [
        FilterField::Assignee,
        FilterField::Label,
        FilterField::Status,
        FilterField::Priority,
        FilterField::Cycle,
        FilterField::Milestone,
        FilterField::Reviewer,
        FilterField::StartDate,
        FilterField::DueDate,
        FilterField::Parent,
        FilterField::Category,
    ];

    pub fn label(self) -> &'static str {
        match self {
            FilterField::Assignee => "Assignee",
            FilterField::Label => "Label",
            FilterField::Status => "Status",
            FilterField::Priority => "Priority",
            FilterField::Cycle => "Cycle",
            FilterField::Milestone => "Milestone",
            FilterField::Reviewer => "Reviewer",
            FilterField::StartDate => "Start date",
            FilterField::DueDate => "Due date",
            FilterField::Parent => "Parent",
            FilterField::Category => "Category",
        }
    }

    /// The serialized frontmatter key each criterion matches against
    /// (`Issue::to_file_contents` emits these). Used by diagnostics.
    ///
    /// **For [`FilterField::Category`] this is the token name, not a frontmatter
    /// key**, because there is no `category` key: the criterion is derived from the
    /// issue's `status` through the board's `category_map` (research R2). T034
    /// step 4 asked what to report here and warned that leaving a nonexistent key
    /// in the diagnostics would be a quiet lie, so the honest spelling is
    /// `category` — which is exactly what the user types, and what the grammar
    /// parses — plus [`FilterField::is_derived`] for any surface that has to
    /// *explain* the criterion rather than merely echo it.
    ///
    /// The distinction is not cosmetic. `key()` feeds two things that read very
    /// differently: a hint bar, where `category:completed` is exactly right, and
    /// an error, where "no issue has `category:completed`" would send a user
    /// looking for a field that does not exist. [`is_derived`] is what keeps the
    /// second from happening.
    pub fn key(self) -> &'static str {
        match self {
            FilterField::Assignee => "assignee",
            FilterField::Label => "labels",
            FilterField::Status => "status",
            FilterField::Priority => "priority",
            FilterField::Cycle => "cycle",
            FilterField::Milestone => "milestone",
            FilterField::Reviewer => "reviewer",
            FilterField::StartDate => "start_date",
            FilterField::DueDate => "due_date",
            // The exact key `Issue` serializes. T024 step 4 asks for a test that
            // fails if this drifts from the model, because `key()` feeds the
            // diagnostics: a mismatch makes `tix lint` point at a field that does
            // not exist, with no error anywhere.
            FilterField::Parent => "parent",
            // The **token** name, and the only correct spelling here: the grammar
            // parses `category:` and the hint bar echoes it. Not a frontmatter key,
            // and `is_derived` is what stops it being read as one.
            FilterField::Category => "category",
        }
    }

    /// Whether this criterion is **derived** from other data rather than read off
    /// a frontmatter field (WP08 T034 step 4).
    ///
    /// `Category` is the only one. It is derived from `status` through the board's
    /// `category_map`, so a diagnostic that names it as a field points at a field
    /// that does not exist. Any surface printing *why* a criterion matched, or why
    /// it found nothing, must say so through this.
    pub fn is_derived(self) -> bool {
        matches!(self, FilterField::Category)
    }

    /// The criterion as a user should read it in an explanation: `category` on its
    /// own, or `category (derived from status)` where the extra clause matters.
    ///
    /// Split from [`key`] so a caller has to choose. A hint bar that appends
    /// "(derived from status)" on every keystroke is noise, and an error that
    /// omits it sends the user hunting for a field; this hands each surface the
    /// short form and lets the ones that explain pick the long one.
    pub fn describe(self) -> String {
        if self.is_derived() {
            format!("{} (derived from status)", self.key())
        } else {
            self.key().to_string()
        }
    }

    /// Row index of this criterion in [`FilterField::ALL`].
    pub fn row(self) -> usize {
        FilterField::ALL
            .iter()
            .position(|field| *field == self)
            .expect("FilterField variants are all in ALL")
    }

    pub fn next(self) -> Self {
        let all = FilterField::ALL;
        all[(self.row() + 1) % all.len()]
    }

    pub fn prev(self) -> Self {
        let all = FilterField::ALL;
        all[(self.row() + all.len() - 1) % all.len()]
    }

    /// The criterion value when set *and* non-empty. An empty string is
    /// treated as "no criterion" everywhere (canonical invariant), so the
    /// filter modal can edit a slot without a live-match surprise.
    pub fn value(self, filter: &StructuredFilter) -> Option<&str> {
        let value = match self {
            FilterField::Assignee => filter.assignee.as_deref(),
            FilterField::Label => filter.label.as_deref(),
            FilterField::Status => filter.status.as_deref(),
            FilterField::Priority => filter.priority.as_deref(),
            FilterField::Cycle => filter.cycle.as_deref(),
            FilterField::Milestone => filter.milestone.as_deref(),
            FilterField::Reviewer => filter.reviewer.as_deref(),
            FilterField::StartDate => filter.start_date.as_deref(),
            FilterField::DueDate => filter.due_date.as_deref(),
            FilterField::Parent => filter.parent.as_deref(),
            FilterField::Category => filter.category.as_deref(),
        };
        value.filter(|s| !s.is_empty())
    }

    /// Mutable access to the criterion buffer, materializing an empty one
    /// when the criterion is unset (the filter modal types into it and
    /// `StructuredFilter::normalize` promotes empty back to `None`).
    pub fn value_mut(self, filter: &mut StructuredFilter) -> &mut String {
        match self {
            FilterField::Assignee => filter.assignee.get_or_insert_default(),
            FilterField::Label => filter.label.get_or_insert_default(),
            FilterField::Status => filter.status.get_or_insert_default(),
            FilterField::Priority => filter.priority.get_or_insert_default(),
            FilterField::Cycle => filter.cycle.get_or_insert_default(),
            FilterField::Milestone => filter.milestone.get_or_insert_default(),
            FilterField::Reviewer => filter.reviewer.get_or_insert_default(),
            FilterField::StartDate => filter.start_date.get_or_insert_default(),
            FilterField::DueDate => filter.due_date.get_or_insert_default(),
            FilterField::Parent => filter.parent.get_or_insert_default(),
            // The criterion is typed into the modal and validated when the query is
            // **run** (see `resolve_category_criterion`), not per keystroke: the
            // modal edits a buffer, and rejecting a half-typed `comp` because it is
            // not yet a category would make the row unusable. The service has no
            // business being called from a text field.
            FilterField::Category => filter.category.get_or_insert_default(),
        }
    }

    /// Clear the criterion back to `None`.
    pub fn unset(self, filter: &mut StructuredFilter) {
        match self {
            FilterField::Assignee => filter.assignee = None,
            FilterField::Label => filter.label = None,
            FilterField::Status => filter.status = None,
            FilterField::Priority => filter.priority = None,
            FilterField::Cycle => filter.cycle = None,
            FilterField::Milestone => filter.milestone = None,
            FilterField::Reviewer => filter.reviewer = None,
            FilterField::StartDate => filter.start_date = None,
            FilterField::DueDate => filter.due_date = None,
            FilterField::Parent => filter.parent = None,
            FilterField::Category => filter.category = None,
        }
    }

    /// Whether this criterion is a **parent reference** rather than a text field.
    ///
    /// The distinction drives two things: the free-typing path is bypassed in
    /// favour of the issue picker (WP06 T026), and `evaluate` compares exactly
    /// rather than by substring, because a number must not match a longer number
    /// that merely contains it.
    pub fn is_reference(self) -> bool {
        matches!(self, FilterField::Parent)
    }

    /// Whether this criterion holds a date (picker-only, no free typing).
    pub fn is_date(self) -> bool {
        matches!(self, FilterField::StartDate | FilterField::DueDate)
    }
}

/// Typed, extensible structured filter (FR-007..FR-010, FR-011).
///
/// Every criterion is optional; an `None`/empty criterion narrows nothing.
/// Criteria match **case-insensitively** against the serialized corpus text
/// (the same haystack [`fuzzy_score`] runs over), following the existing
/// fuzzy matcher's `to_lowercase()` behavior — this keeps the predicate a
/// pure, config-independent function of the corpus (WP02 runs in parallel
/// with WP01 for exactly that reason).
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct StructuredFilter {
    pub assignee: Option<String>,
    pub label: Option<String>,
    pub status: Option<String>,
    pub priority: Option<String>,
    pub cycle: Option<String>,
    pub milestone: Option<String>,
    pub reviewer: Option<String>,
    pub start_date: Option<String>,
    pub due_date: Option<String>,
    pub overdue: Option<bool>,
    /// The referenced parent, as a **resolved issue number** (WP06 T025).
    ///
    /// A number, not the selector the user typed, because matching happens against
    /// an issue's rendered frontmatter and that carries `parent: 7`. Resolution
    /// happens once, at the command layer, where the store is available; matching
    /// then stays a pure string comparison and `query_matches` keeps its
    /// store-free signature.
    ///
    /// Direct children only, and by construction: an issue's `parent:` field *is*
    /// its direct parent, so a grandchild's file says `parent: 2` and never matches
    /// a criterion of `parent: 1`. A transitive implementation would have to walk
    /// the chain explicitly, and this way there is nothing to get wrong.
    pub parent: Option<String>,
    /// A workflow **category key** (WP08 T035), never a column name.
    ///
    /// A category key rather than a column, because several columns can share one
    /// category and the whole point of the criterion is to select across that
    /// boundary: `category:completed` on a board with `shipped`, `done` and
    /// `released` all complete returns every one of them, where `status:done`
    /// returns one.
    ///
    /// Validated through the service's `from_key` when the query runs
    /// ([`resolve_category_criterion`]), so this never holds a value the
    /// vocabulary does not contain. The TUI modal types into it unchecked — see
    /// [`FilterField::value_mut`] for why that is the right layer to do it at.
    pub category: Option<String>,
    /// The columns a `scope:` token selected (WP02 T010).
    ///
    /// A set of **column names**, not a name, because the columns are not
    /// knowable from the query: `scope:triage` means "the columns `[triage]`
    /// names", and only the config can answer that — the same reason `parent:`
    /// and `category:` are resolved rather than matched from bytes. Filled by
    /// [`resolve_filter_criteria`] through
    /// [`crate::triage::inbox::scope_columns`], and judged by
    /// [`Self::scope_matches`], which needs the issue the way `category` does.
    ///
    /// Deliberately **not** a [`FilterField`]: the filter modal has no row for
    /// it and no user can type a scope into it, and appending a variant would
    /// change `FilterField::ALL`'s length — which the modal's row layout, its
    /// click mapping and its own tests all count. The extensibility promise on
    /// [`FilterField`] is about criteria a user can enter; this is a resolved
    /// selection a *token* produces, and `overdue` already shows a
    /// `StructuredFilter` field that is not a modal row.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub scope: Option<Vec<String>>,
    /// Whether the issue is **archived** (issue #1492), from an
    /// `archived:true|false` token.
    ///
    /// A **derived** criterion, like `overdue` and `scope`, and for the same
    /// reason: `archived` is not a frontmatter key. The marker is the leading dot
    /// of the issue's filename, mirrored onto [`Issue::archived`], so nothing in
    /// the serialized bytes can answer the question and the token is lifted out
    /// by [`resolve_filter_criteria`] into this field, then judged by
    /// [`Self::archived_matches`], which has the issue.
    ///
    /// `None` (no token) narrows nothing.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub archived: Option<bool>,
}

impl StructuredFilter {
    /// The active (set, non-empty) criteria, in [`FilterField::ALL`] order.
    pub fn criteria(&self) -> impl Iterator<Item = (FilterField, &str)> {
        FilterField::ALL
            .into_iter()
            .filter_map(move |field| field.value(self).map(|value| (field, value)))
    }

    /// True when at least one criterion is active. When false the board must
    /// render unchanged (no criteria → pass-through).
    ///
    /// The `scope` criterion is counted here even though it is not a
    /// [`FilterField`] and so never appears in [`Self::criteria`]: a query that
    /// selected rows is active however it selected them, and omitting it would
    /// make `has_active_criteria` disagree with [`Self::evaluate_issue`] about
    /// whether the same filter narrowed anything.
    pub fn has_active_criteria(&self) -> bool {
        self.criteria().next().is_some() || self.scope.is_some() || self.archived.is_some()
    }

    /// AND predicate over the serialized corpus text (FR-012, C-002).
    ///
    /// Applies *every* active criterion; the first miss short-circuits the
    /// entry to `false`. The caller (WP03's `build_filtered`) invokes this
    /// once per corpus entry, giving **one linear O(entries) pass** (NFR-001)
    /// — `haystack` is lowercased once and each active criterion is a single
    /// substring `contains` on that pre-lowered text, with no nested
    /// field×corpus loops.
    ///
    /// Matching is case-insensitive and substring-based, consistently across
    /// assignee/label/status/priority, exactly as WP02's prompt specifies
    /// (T009). The stricter per-criterion "equals"/"contains-in-labels" rules
    /// in `contracts/filtering.md` would require re-parsing the issue; on the
    /// serialized corpus the substring rule is the single consistent gate.
    pub fn evaluate(&self, haystack: &str) -> bool {
        let hay = haystack.to_lowercase();
        // The parent criterion is **not** a substring test, and is handled before
        // the generic loop rather than inside it.
        //
        // Two reasons. First, a substring test over the whole haystack would match
        // an issue whose *body* mentions the number, or whose `parent: 17` contains
        // `1` — so `parent:1` would return the children of #17 as well. Second, the
        // generic loop would also be reached for an issue with **no** `parent:` key
        // at all, where `hay.contains("1")` is true for any issue whose text
        // mentions 1. Every other criterion is a text field where substring is the
        // right semantic; a reference is a value.
        if let Some(number) = &self.parent
            && field_value(haystack, "parent") != Some(number.as_str())
        {
            return false;
        }
        for (field, value) in self.criteria() {
            // `parent` was already compared exactly above, and `category` cannot be
            // compared here at all — see `evaluate_issue`.
            if field.is_reference() || field.is_derived() {
                continue;
            }
            if !hay.contains(&value.to_lowercase()) {
                return false;
            }
        }
        if let Some(cycle) = &self.cycle
            && !hay.contains(&cycle.to_lowercase())
        {
            return false;
        }
        if let Some(milestone) = &self.milestone
            && !hay.contains(&milestone.to_lowercase())
        {
            return false;
        }
        if let Some(reviewer) = &self.reviewer
            && !hay.contains(&reviewer.to_lowercase())
        {
            return false;
        }
        if let Some(start_date) = &self.start_date
            && !hay.contains(start_date)
        {
            return false;
        }
        if let Some(due_date) = &self.due_date
            && !hay.contains(due_date)
        {
            return false;
        }
        if self.overdue == Some(true) && !is_overdue_haystack(haystack) {
            return false;
        }
        true
    }

    /// The full structured predicate for an issue, including the criteria
    /// [`Self::evaluate`] structurally cannot judge.
    ///
    /// WP08 T035. [`evaluate`] takes a haystack and is therefore store-free; the
    /// category criterion needs the issue's `status` **and** the board's
    /// `category_map`, so it is judged here instead, where both are available.
    /// The two halves AND together, exactly as `evaluate` ANDs its own criteria.
    ///
    /// `text` is passed in rather than re-serialized from `issue`, because
    /// `Corpus` already holds the exact bytes every issue was matched against and
    /// a second `to_file_contents()` per issue per keystroke is measurable work
    /// for an identical string.
    pub fn evaluate_issue(
        &self,
        issue: &Issue,
        text: &str,
        resolution: &crate::workflow::CategoryResolution,
    ) -> bool {
        self.evaluate(text)
            && self.category_matches(issue, resolution)
            && self.scope_matches(issue)
            && self.archived_matches(issue)
    }

    /// Whether `issue`'s archived state matches the `archived:` criterion
    /// (issue #1492).
    ///
    /// Judged here rather than in [`Self::evaluate`] because the archived flag is
    /// derived from the *filename* and never appears in the haystack; `None`
    /// narrows nothing, and a set value is an exact `bool` comparison —
    /// `archived:false` selects the active issues, `archived:true` the archived
    /// ones.
    pub fn archived_matches(&self, issue: &Issue) -> bool {
        match self.archived {
            None => true,
            Some(want) => issue.archived == want,
        }
    }

    /// Whether `issue` is in one of the columns the `scope:` token selected.
    ///
    /// WP02 T010. The same three-way reasoning as [`Self::category_matches`],
    /// in reverse: a scope is a **membership set**, so an issue either has a
    /// status in it or does not, and there is no category to default. `None` (no
    /// token) passes everything — an unset criterion narrows nothing — and a set
    /// that fails to contain `issue.status` fails closed, because a scope the
    /// issue is not in is precisely what was asked for.
    ///
    /// Judged here rather than in [`Self::evaluate`] for the reason that
    /// function gives: `evaluate` has a haystack and no issue, and the issue's
    /// status is not reliably *in* the haystack in a form this can compare —
    /// `status: triage` is a line of frontmatter, but a scope is a set of
    /// columns and substring-matching the set against the file would call an
    /// issue whose title contains `todo` a member of the `todo` column.
    pub fn scope_matches(&self, issue: &Issue) -> bool {
        match &self.scope {
            None => true,
            Some(columns) => columns.iter().any(|c| issue.status.is(c)),
        }
    }

    /// Whether `issue` is in the requested category (WP08 T035).
    ///
    /// Three cases, and the third is the one the surfaces already distinguish:
    ///
    /// 1. **A mapped column** → its category, from the service's resolution.
    /// 2. **A configured but unmapped column** → the **safe default**, because
    ///    that is what it resolves to. T035 step 3 asks for this explicitly, and it
    ///    is what keeps the criterion consistent with `tix workflow show`, which
    ///    reports the same default for the same column.
    /// 3. **A column the board does not configure** → matches **nothing**. There
    ///    is no category to report: `resolve` is `None`, `tix list --show category`
    ///    prints `(unmapped)`, and MCP returns `category: null` (WP07). A criterion
    ///    has to agree with the surfaces that show the same fact, and silently
    ///    folding this into the safe default would make `category:unstarted` return
    ///    issues every other surface call unmapped.
    ///
    /// The unknown-category case is *not* handled here and cannot be: a value the
    /// vocabulary does not contain is an error at the command layer
    /// ([`resolve_category_criterion`]), not a match decision here. A criterion
    /// that reached this function unchecked compares against a key nothing
    /// resolves to and therefore matches nothing — the same empty result an
    /// unknown `status:` gives, which is the established behaviour for a bad value
    /// in a haystack criterion.
    pub fn category_matches(
        &self,
        issue: &Issue,
        resolution: &crate::workflow::CategoryResolution,
    ) -> bool {
        let Some(want) = self.category.as_deref().filter(|s| !s.is_empty()) else {
            return true;
        };
        match resolution.resolve(issue.status.display()) {
            Some(actual) => actual.key() == want,
            // Case 3. `None` only for a column this board does not configure.
            None => false,
        }
    }

    /// Trim every criterion; values that trim to empty become `None` (the
    /// canonical "unset" state). Used by the filter modal's commit path.
    pub fn normalize(&mut self) {
        for field in FilterField::ALL {
            let empty = field.value_mut(self).trim().is_empty();
            if empty {
                field.unset(self);
            } else {
                let value = field.value_mut(self);
                let trimmed = value.trim().to_string();
                *value = trimmed;
            }
        }
    }
}

impl std::fmt::Display for StructuredFilter {
    /// Diagnostics for the hint bar: `assignee:alice, status:todo`, or
    /// `(no active criteria)`.
    ///
    /// Built as a list rather than written field by field, because there are
    /// now three sources of a part — the [`FilterField`] criteria, an active
    /// `scope`, and `overdue` — and the first version returned early when the
    /// *criteria* were empty. A scope-only filter would then have printed
    /// `(no active criteria)` while actively filtering, which is the hint bar
    /// telling the user the opposite of what the board is doing.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let mut parts: Vec<String> = self
            .criteria()
            .map(|(field, value)| format!("{}:{value}", field.key()))
            .collect();
        if let Some(columns) = &self.scope {
            parts.push(format!("scope:{}", columns.join(",")));
        }
        if let Some(archived) = self.archived {
            parts.push(format!("archived:{archived}"));
        }
        if self.overdue == Some(true) {
            parts.push("overdue:true".to_string());
        }
        if parts.is_empty() {
            return write!(f, "(no active criteria)");
        }
        write!(f, "{}", parts.join(", "))
    }
}

/// Composite predicate: the `/` fuzzy text layer **and** the structured
/// filter both apply (FR-013).
///
/// - empty `query` → structured filter only;
/// - empty structured filter → text query only;
/// - both active → an entry must satisfy **both** layers.
///
/// Zero matches is a valid board, never an error (consumers render empty
/// columns).
pub fn matches(query: &str, filter: &StructuredFilter, haystack: &str) -> bool {
    let text_matches = query_matches(query, haystack);
    text_matches && filter.evaluate(haystack)
}

/// The full predicate for one corpus entry, including the derived criteria
/// (WP08 T035, WP02 T010).
///
/// **Every** consumer should call this rather than [`matches`]. `matches` cannot
/// judge a `category:` or `scope:` criterion — both need the issue (and the
/// board's map, for `category`), and it has neither — and a consumer that calls
/// it directly would therefore **silently ignore** an active category or scope
/// criterion: the query would return the unfiltered set and read as "every issue
/// is in that category/scope". One composition point is what keeps the CLI, the
/// TUI board, and `tix search` from disagreeing, which is the property the
/// module header exists to protect (C-005).
///
/// `text` is the corpus's own bytes for this entry, so no caller re-serializes.
pub fn matches_issue(
    query: &str,
    filter: &StructuredFilter,
    issue: &Issue,
    text: &str,
    resolution: &crate::workflow::CategoryResolution,
) -> bool {
    query_matches(query, text) && filter.evaluate_issue(issue, text, resolution)
}

/// Resolve a `parent:<selector>` query token to the **number** it names.
///
/// Matching happens against an issue's rendered frontmatter, and that carries
/// `parent: 7` — a number. The user types a *selector*, so something has to close
/// that gap, and the only place with a store is the command layer. Doing it here,
/// once, keeps `query_matches` and `evaluate` pure string comparisons and
/// store-free, which is the property every other criterion already has.
///
/// The substitution is textual on the **query**, not on the results: `parent:5` in,
/// `parent:5` out, with the selector replaced by the number it resolves to. That
/// means no new plumbing in the matchers, and no second code path for a criterion
/// that only needs one comparison.
///
/// A selector that resolves to nothing is an **error**, not an empty result: a user
/// who typed `parent:Epicc` has made a typo, and "no issues found" is a different
/// answer from "there is no such issue". Every other command's selector handling
/// errors the same way.
///
/// Returns the query unchanged when it carries no `parent:` token, so a caller can
/// use the result unconditionally.
pub fn resolve_parent_criterion(store: &crate::storage::Store, query: &str) -> Result<String> {
    let mut out: Vec<String> = Vec::with_capacity(8);
    let mut touched = false;
    for token in query.split_whitespace() {
        let Some((key, value)) = parse_token(token) else {
            out.push(token.to_string());
            continue;
        };
        if !key.eq_ignore_ascii_case("parent") {
            out.push(token.to_string());
            continue;
        }
        let target = crate::commands::parse_selector(store, value)?;
        // The store's own message, propagated as-is. The first version wrapped it in
        // a fresh `NotFound`, and the user saw `not found: not found: issue matching
        // …` — the same class of doubled prefix the relationship renderer fixed in
        // WP03. One message, from one place.
        let number = store
            .get(target)
            .map_err(|_| {
                crate::error::TixError::NotFound(format!(
                    "issue matching '{value}' by number, filename or title"
                ))
            })?
            .number;
        out.push(format!("parent:{number}"));
        touched = true;
    }
    if !touched {
        return Ok(query.to_string());
    }
    Ok(out.join(" "))
}

/// **Lift** the `category:<value>` criterion out of `query`, validating the value
/// against the project's closed vocabulary (WP08 T035).
///
/// Returns `(query-without-the-token, Some(canonical_key))`. "Lift", not "rewrite":
/// the token is **removed** and the criterion travels in the
/// [`StructuredFilter`] instead, because that is the only shape that works. The
/// first version rewrote `category:Completed` to `category:completed` and left the
/// token in the string, so [`query_matches`] still met a `category` key, still
/// refused it, and the filter matched **nothing** — while the canonicalization test
/// beside it passed. Two green results and an empty board.
///
/// The validation this closes is the one a substring matcher cannot do. A bad
/// `status:` value is a legitimate test that matches nothing; a bad *category* is a
/// typo in a closed set of at most six words, and "0 issues found" is a silent dead
/// end where one line names the words that would have worked.
///
/// Checked against the **project's** `[categories] order` rather than
/// [`crate::config::CATEGORY_KEYS`] because `order` may be a **subset**: a project
/// declaring `["backlog", "active", "completed", "canceled"]` has said its
/// vocabulary is four words, and accepting `unstarted` would return results from a
/// category it never declared. The error names that project's list.
///
/// `None` when the query carries no `category:` token, so a caller can use the
/// result unconditionally. Same shape and same reason as
/// [`resolve_parent_criterion`]: the matchers are pure string comparisons over a
/// store-free haystack, so anything needing the config is resolved once, in the one
/// layer that has it.
fn lift_category_criterion(
    config: &crate::config::Config,
    query: &str,
) -> crate::error::Result<(String, Option<String>)> {
    let mut out: Vec<String> = Vec::with_capacity(8);
    let mut category = None;
    for token in query.split_whitespace() {
        let Some((key, value)) = parse_token(token) else {
            out.push(token.to_string());
            continue;
        };
        if !key.eq_ignore_ascii_case("category") {
            out.push(token.to_string());
            continue;
        }
        let lowered = value.to_lowercase();
        if !config.categories.contains(&lowered) {
            return Err(crate::error::TixError::InvalidInput(format!(
                "unknown category '{value}' — this project's categories are: {}",
                config.categories.order.join(", ")
            )));
        }
        // `contains` and `from_key` read the same six words, so this cannot fail
        // after the check above. `from_key` is still what produces the canonical
        // spelling rather than trusting the user's casing, and it is the same
        // function `WorkflowCategory::key` is compared against when matching.
        category = Some(
            crate::workflow::WorkflowCategory::from_key(&lowered)
                .expect("categories.order is validated against the global vocabulary at load")
                .key()
                .to_string(),
        );
        // Dropped, not pushed: `out` is the query the store-free matcher will see.
    }
    Ok((out.join(" "), category))
}

/// Resolve a `scope:<name>` query token to the columns it selects (WP02 T010).
///
/// Same shape as [`lift_category_criterion`], and for the same reason: the
/// columns a scope names are a **config** fact, so a store-free matcher cannot
/// reach them, and leaving the token in the string would have [`query_matches`]
/// refuse it and return an empty result that reads as "no matches".
///
/// One token rather than a new grammar. `scope:` is the `key:value` shape every
/// other criterion already uses, resolved through the same entry point, with no
/// new operator, no list syntax and no precedence — the module's own extension
/// promise ("adding a criterion is one more field on `StructuredFilter` plus one
/// match arm"), minus the `FilterField` variant, which would change the modal's
/// row count (see [`StructuredFilter::scope`]).
///
/// A token the project cannot honour is an **error**, not an empty selection:
/// see [`crate::triage::inbox::scope_columns`].
///
/// Returns the query with every `scope:` token removed, so a caller can use the
/// result unconditionally.
fn lift_scope_criterion(
    config: &crate::config::Config,
    query: &str,
) -> crate::error::Result<(String, Option<Vec<String>>)> {
    let mut out: Vec<String> = Vec::with_capacity(8);
    let mut scope = None;
    for token in query.split_whitespace() {
        let Some((key, value)) = parse_token(token) else {
            out.push(token.to_string());
            continue;
        };
        if !key.eq_ignore_ascii_case("scope") {
            out.push(token.to_string());
            continue;
        }
        // Validated *and* resolved in one call, so a caller cannot keep a token
        // it failed to check. The last one wins, as `category:` does.
        scope = Some(crate::triage::inbox::scope_columns(config, value)?);
        // Dropped, not pushed: `out` is the query the store-free matcher will see.
    }
    Ok((out.join(" "), scope))
}

/// Resolve a `--filter` / query string into the **pair** a match needs: the
/// canonicalized query, and the criteria the store-free matchers cannot judge
/// (WP08 T035).
///
/// Every consumer that takes a filter string should call this and hand both parts
/// to [`matches_issue`]. One function rather than two calls, because the failure
/// mode of getting it half-right is silent: a query whose `category:` token was
/// validated but not canonicalized into the structured criterion still matches
/// **nothing** (the token matcher refuses it), and a query that was canonicalized
/// but never validated accepts a category this project did not declare. Neither
/// error is visible in a return value.
///
/// `parent:` is resolved here too. It was always resolved at the command layer —
/// it is the same shape of problem — but in four separate call sites, and the
/// `category:` work would have made that four more. One entry point means a fifth
/// surface gets both.
///
/// Returns the query unchanged when it carries neither token, so a caller can use
/// the result unconditionally.
pub fn resolve_filter_criteria(
    store: &crate::storage::Store,
    query: &str,
) -> Result<(String, StructuredFilter)> {
    let query = resolve_parent_criterion(store, query)?;
    // `parent:`'s resolver **rewrites** its token — a selector becomes a number, and
    // the haystack holds the number. `category:`'s **lifts** its token out. The
    // asymmetry is not an oversight: the parent criterion is compared against a
    // rendered frontmatter field, so it can stay in the string, while the category
    // criterion has no field to compare against and must arrive as a structured
    // value. Both are resolved here so no call site has to know which is which.
    // `scope:` is a `category:` in kind — a selection nothing in the file bytes
    // can answer — and is lifted the same way (WP02 T010).
    let (query, category) = lift_category_criterion(&store.config, &query)?;
    let (query, scope) = lift_scope_criterion(&store.config, &query)?;
    let (query, archived) = lift_archived_criterion(&query)?;
    Ok((
        query,
        StructuredFilter {
            category,
            scope,
            archived,
            ..StructuredFilter::default()
        },
    ))
}

/// Lift an `archived:true|false` token out of the query into the
/// [`StructuredFilter::archived`] field (issue #1492).
///
/// The archived state is derived from the filename, so it cannot be judged from
/// the serialized bytes and the token has to arrive as a structured value — the
/// same shape as `scope:` and `category:`. The last token wins, as both of those
/// do. A value that is neither `true` nor `false` is refused by name, because
/// `archived:1` matching nothing would be indistinguishable from a correct filter
/// with no matches.
fn lift_archived_criterion(query: &str) -> crate::error::Result<(String, Option<bool>)> {
    let mut out: Vec<String> = Vec::with_capacity(8);
    let mut archived = None;
    for token in query.split_whitespace() {
        let Some((key, value)) = parse_token(token) else {
            out.push(token.to_string());
            continue;
        };
        if !key.eq_ignore_ascii_case("archived") {
            out.push(token.to_string());
            continue;
        }
        archived = match value.to_ascii_lowercase().as_str() {
            "true" => Some(true),
            "false" => Some(false),
            other => {
                return Err(crate::error::TixError::InvalidInput(format!(
                    "invalid archived value '{other}' — use archived:true or archived:false"
                )));
            }
        };
        // Dropped, not pushed: `out` is the query the store-free matcher will see.
    }
    Ok((out.join(" "), archived))
}

/// Parse a structured query token of the form `key:value`.
fn parse_token(token: &str) -> Option<(&str, &str)> {
    let (key, value) = token.split_once(':')?;
    let value = value.trim();
    if key.is_empty() || value.is_empty() {
        return None;
    }
    Some((key, value))
}

pub fn control_token(query: &str, key: &str) -> Option<String> {
    query.split_whitespace().find_map(|token| {
        let (k, v) = token.split_once(':')?;
        if k.eq_ignore_ascii_case(key) {
            Some(v.to_ascii_lowercase())
        } else {
            None
        }
    })
}

/// Apply the new query grammar to a haystack without disturbing the legacy
/// fuzzy-substring semantics for bare terms.
pub fn query_matches(query: &str, haystack: &str) -> bool {
    let mut bare_terms = Vec::new();
    let hay = haystack.to_lowercase();
    for token in query.split_whitespace() {
        if token.eq_ignore_ascii_case("overdue") {
            if !is_overdue_haystack(haystack) {
                return false;
            }
            continue;
        }
        if let Some((key, value)) = parse_token(token) {
            let value = value.to_lowercase();
            let ok = match key.to_lowercase().as_str() {
                // A **pre-existing defect, found while adding `category`** (WP08).
                //
                // `StructuredFilter` has carried `assignee`, `label`, `status` and
                // `priority` since the filter grammar landed, and `evaluate` matches
                // all four — so the TUI's filter modal has always filtered on them.
                // The **token** grammar had no arm for any of them, and the `_ => false`
                // below turned each into a filter that matched nothing:
                //
                //     tix list --filter status:shipped    # → empty table, exit 0
                //     tix list --filter assignee:alice     # → empty table, exit 0
                //
                // Silent, total, and on the four most obvious criteria. A user typing
                // the documented `--filter` had no way to tell a filter from a typo, and
                // the empty table is indistinguishable from a correct filter with no
                // matches.
                //
                // Substring, and lowercased, because that is exactly what `evaluate`
                // does for these four — the module's stated rule, and the one
                // `StructuredFilter`'s own tests pin. The two grammars now agree
                // criterion for criterion instead of the token grammar silently
                // supporting less than the modal does.
                //
                // `label` matches the rendered `labels: [a, b]` list by substring,
                // which is also `evaluate`'s rule, and the one `contracts/filtering.md`
                // §3's stricter "contains-in-labels" spelling would need a re-parse to
                // improve on. Not changed here: one behaviour, two grammars.
                "assignee" | "label" | "status" | "priority" | "cycle" | "milestone"
                | "reviewer" => hay.contains(&value),
                "start" | "due" => hay.contains(&value),
                // Exact, for the same reason `evaluate` is: a number must not
                // match a longer number that contains it. The value here is already
                // a **resolved** number — see `resolve_parent_criterion`.
                "parent" => field_value(haystack, "parent") == Some(value.as_str()),
                // A **category key**, not a field value: an issue's file contains no
                // `category` line, so a substring test here would match the word
                // "category" wherever it appears in a title or body, and would
                // match `completed` against any issue that happens to use the word.
                // This arm exists only to make the refusal **explicit and total**
                // rather than accidental: a store-free matcher cannot judge it, and
                // [`matches_issue`] is the entry point that does, with the
                // criterion carried in the [`StructuredFilter`] that
                // [`resolve_filter_criteria`] fills. Reaching this arm with a real
                // `category:` token therefore means a caller skipped one of those
                // two — and returning `false` for every issue turns that mistake into
                // an empty result a user can see, instead of an unfiltered result
                // they cannot.
                "category" => false,
                // The `scope:` twin of the `category` refusal above, and the
                // same contract: the columns a scope selects are a config fact
                // this store-free matcher does not have, and
                // [`resolve_filter_criteria`] is what lifts the token out before
                // it ever gets here. Reaching this arm with a real `scope:` token
                // means a caller skipped that step — see [`matches_issue`] — and
                // returning `false` for every issue turns the mistake into an
                // empty result a user can see instead of an unfiltered one they
                // cannot. (WP02 T010.)
                "scope" => false,
                // The `archived:` twin of the `category`/`scope` refusals above
                // (issue #1492): the archived flag lives on the filename, not in
                // the bytes, so this store-free matcher cannot judge it and
                // `resolve_filter_criteria` lifts the token into the structured
                // filter instead. A caller that skipped that step gets an empty
                // result rather than an unfiltered one.
                "archived" => false,
                "sort" => matches!(
                    value.as_str(),
                    "created"
                        | "priority"
                        | "status"
                        | "cycle"
                        | "milestone"
                        | "due"
                        | "start"
                        | "reviewer"
                ),
                "group" => matches!(value.as_str(), "cycle" | "milestone"),
                "overdue" => {
                    if value == "true" {
                        is_overdue_haystack(haystack)
                    } else {
                        false
                    }
                }
                _ => false,
            };
            if !ok {
                return false;
            }
        } else {
            bare_terms.push(token);
        }
    }
    let bare = bare_terms.join(" ");
    bare.is_empty() || fuzzy_score(&bare, haystack).is_some()
}

fn field_value<'a>(haystack: &'a str, key: &str) -> Option<&'a str> {
    for line in haystack.lines() {
        let prefix = format!("{key}:");
        if let Some(rest) = line.strip_prefix(&prefix) {
            return Some(rest.trim().trim_matches('"'));
        }
    }
    None
}

fn is_overdue_haystack(haystack: &str) -> bool {
    let status = field_value(haystack, "status").unwrap_or_default();
    let due = field_value(haystack, "due_date").unwrap_or_default();
    !due.is_empty() && due < crate::model::today().as_str() && status != "done"
}

/// Classify a bare-number `/` query: `Some(n)` iff `raw` trims to a
/// non-empty run of ASCII digits that fits `u32`. Any other input — empty,
/// whitespace-only, non-digit characters, mixed (`55bug`), or overflowing
/// `u32` — returns `None`, signalling "not a number query" so the caller
/// falls back to fuzzy-text behavior (board-filtering FR-02). Leading zeros
/// parse normally (`"055"` → `55`); `"0"` is a valid (if typically
/// matchless) number query.
pub fn number_query(raw: &str) -> Option<u32> {
    let trimmed = raw.trim();
    if trimmed.is_empty() || !trimmed.bytes().all(|b| b.is_ascii_digit()) {
        return None;
    }
    trimmed.parse::<u32>().ok()
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::model::{Issue, Priority, Status};
    use std::fs;

    // ----------------------------------------------------------------------
    // T007 — corpus builder
    // ----------------------------------------------------------------------

    fn make_store() -> (tempfile::TempDir, Store) {
        let tmp = tempfile::TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(&dir).unwrap();
        let config_path = tmp.path().join("tix.toml");
        let config = crate::config::Config {
            issues_dir: dir.clone(),
            ..crate::config::Config::default()
        };
        config.save(&config_path).unwrap();
        let config = crate::config::Config::load_with_warning(&config_path, |_| {}).unwrap();
        let store = Store {
            issues_dir: dir,
            config,
        };
        (tmp, store)
    }

    fn sample_issue(number: u32, title: &str, extra_body: &str) -> Issue {
        let mut issue = Issue {
            number,
            title: title.to_string(),
            status: Status::default(),
            labels: vec!["urgent".to_string()],
            priority: Priority::default(),
            assignee: Some("alice".to_string()),
            estimate: None,
            commit: None,
            gitlab_id: None,
            linear_id: None,
            mission: None,
            task: None,
            relationships: vec![],
            files: vec![],
            cycles: None,
            milestones: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            created: "2026-01-01".to_string(),
            updated: "2026-01-01".to_string(),
            filename: String::new(),
            body: extra_body.to_string(),
            history: crate::model::History::new(),
            has_retired_links_key: false,
            parent: None,
            extra_frontmatter: std::collections::BTreeMap::new(),
            archived: false,
            entered_at: None,
            source: None,
        };
        // Serialized frontmatter carries the title; `filename` is memory-only
        // and never written to disk, so it only needs to be non-empty here.
        issue.filename = format!("alice/{}-{}.md", "2026-01-01", crate::slug::slugify(title));
        issue
    }

    fn write_issue(store: &Store, name: &str, issue: &Issue) {
        fs::write(store.issues_dir.join(name), issue.to_file_contents()).unwrap();
    }

    #[test]
    fn corpus_texts_match_issue_to_file_contents_byte_for_byte() {
        let (_tmp, store) = make_store();
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        let a = sample_issue(1, "Login bug", "Need to reproduce the redirect loop.");
        write_issue(&store, "alice/2026-01-01-login-bug.md", &a);
        let b = sample_issue(
            2,
            "Export csv",
            "## Comments\n\n### alice (2026-01-01)\n\nSort order is wrong.\n",
        );
        write_issue(&store, "alice/2026-01-01-export-csv.md", &b);

        let corpus = Corpus::build(&store).unwrap();
        assert_eq!(corpus.issues.len(), 2);
        // Corpus texts are byte-for-byte the serialized issues, matched by
        // stable number lookup regardless of store order.
        let idx_a = corpus.by_number(1).unwrap();
        let idx_b = corpus.by_number(2).unwrap();
        assert_eq!(corpus.texts[idx_a], a.to_file_contents());
        assert_eq!(corpus.texts[idx_b], b.to_file_contents());
        assert_eq!(corpus.by_number(99), None);
    }

    #[test]
    fn corpus_never_indexes_asset_dirs() {
        let (_tmp, store) = make_store();
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        let a = sample_issue(1, "Login bug", "body");
        write_issue(&store, "alice/2026-01-01-login-bug.md", &a);
        // A `.md` straggler inside an `-assets` dir and a real binary asset.
        let assets = store.issues_dir.join("alice/login-bug-assets");
        fs::create_dir_all(&assets).unwrap();
        fs::write(assets.join("notes.md"), "# not an issue\n").unwrap();
        fs::write(assets.join("diagram.png"), b"\x89PNG").unwrap();

        let corpus = Corpus::build(&store).unwrap();
        assert_eq!(corpus.issues.len(), 1);
        let evil_found = corpus.texts.iter().any(|t| t.contains("not an issue"));
        assert!(
            !evil_found,
            "asset-dir markdown must not leak into the corpus"
        );
    }

    // ----------------------------------------------------------------------
    // T008 — substring matcher + matched context
    // ----------------------------------------------------------------------

    fn two_issue_corpus() -> Corpus {
        let (_tmp, store) = make_store();
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        let a = sample_issue(1, "Login bug", "The redirect URL is broken.");
        write_issue(&store, "alice/2026-01-01-login-bug.md", &a);
        let b = sample_issue(
            2,
            "Export csv",
            "## Comments\n\n### alice (2026-01-01)\n\nHandle empty rows.\n",
        );
        write_issue(&store, "alice/2026-01-01-export-csv.md", &b);
        Corpus::build(&store).unwrap()
    }

    #[test]
    fn substring_matches_frontmatter() {
        let corpus = two_issue_corpus();
        let hits = search_substring(&corpus, "Login bug");
        assert_eq!(hits.len(), 1);
        assert_eq!(hits[0].issue.number, 1);
        assert!(
            hits[0]
                .matched_lines
                .iter()
                .any(|l| l.contains("Login bug")),
            "frontmatter title line must appear as context: {hits:?}"
        );
    }

    #[test]
    fn substring_matches_comment_text_only() {
        let corpus = two_issue_corpus();
        let hits = search_substring(&corpus, "empty rows");
        assert_eq!(hits.len(), 1);
        assert_eq!(hits[0].issue.number, 2);
        assert!(
            hits[0]
                .matched_lines
                .iter()
                .any(|l| l.contains("empty rows")),
            "comment line must appear as context: {hits:?}"
        );
    }

    #[test]
    fn substring_matches_label() {
        let corpus = two_issue_corpus();
        let hits = search_substring(&corpus, "urgent");
        assert_eq!(hits.len(), 2, "both issues carry the `urgent` label");
        assert_eq!(
            hits.iter().map(|h| h.issue.number).collect::<Vec<_>>(),
            vec![1, 2],
            "stable number-ascending order (NFR-007)"
        );
    }

    #[test]
    fn substring_is_case_insensitive() {
        let corpus = two_issue_corpus();
        assert_eq!(search_substring(&corpus, "LOGIN BUG").len(), 1);
        assert_eq!(search_substring(&corpus, "login bug").len(), 1);
    }

    #[test]
    fn substring_orders_by_number_ascending() {
        let (_tmp, store) = make_store();
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        let hi = sample_issue(9, "Zed bug", "The redirect loop");
        let lo = sample_issue(3, "Alpha", "The redirect loop, too");
        write_issue(&store, "alice/2026-01-01-zed-bug.md", &hi);
        write_issue(&store, "alice/2026-01-01-alpha.md", &lo);
        let corpus = Corpus::build(&store).unwrap();
        let hits = search_substring(&corpus, "redirect loop");
        assert_eq!(
            hits.iter().map(|h| h.issue.number).collect::<Vec<_>>(),
            vec![3, 9],
            "hits sorted by number regardless of file order"
        );
    }

    #[test]
    fn substring_zero_matches_is_empty() {
        let corpus = two_issue_corpus();
        assert!(search_substring(&corpus, "nope-nothing-here").is_empty());
    }

    #[test]
    fn substring_empty_query_is_empty() {
        let corpus = two_issue_corpus();
        assert!(search_substring(&corpus, "").is_empty());
    }

    // ----------------------------------------------------------------------
    // T009 — fuzzy subsequence scorer
    // ----------------------------------------------------------------------

    #[test]
    fn fuzzy_exact_match_scores_higher_than_partial() {
        let exact = fuzzy_score("login bug", "login bug").unwrap();
        let partial = fuzzy_score("login bug", "debug the login bug report").unwrap();
        assert!(exact > partial);
    }

    #[test]
    fn fuzzy_contiguous_beats_spread() {
        let contiguous = fuzzy_score("ab", "xyab").unwrap();
        let spread = fuzzy_score("ab", "xayb").unwrap();
        assert!(contiguous > spread);
    }

    #[test]
    fn fuzzy_prefix_beats_mid_string() {
        let prefix = fuzzy_score("ab", "abxy").unwrap();
        let mid = fuzzy_score("ab", "xaby").unwrap();
        assert!(prefix > mid);
    }

    #[test]
    fn fuzzy_non_subsequence_is_none() {
        assert_eq!(fuzzy_score("abc", "aac"), None);
        assert_eq!(fuzzy_score("zzz", "haystack"), None);
    }

    #[test]
    fn fuzzy_is_case_insensitive() {
        assert_eq!(
            fuzzy_score("LOGIN", "login").unwrap(),
            fuzzy_score("login", "login").unwrap()
        );
        assert_eq!(
            fuzzy_score("aBc", "xAbC").unwrap(),
            fuzzy_score("abc", "xabc").unwrap()
        );
    }

    #[test]
    fn fuzzy_empty_query_scores_zero() {
        assert_eq!(fuzzy_score("", "anything"), Some(0));
    }

    #[test]
    fn fuzzy_earlier_positions_beat_later() {
        let early = fuzzy_score("ab", "abcxyz").unwrap();
        let late = fuzzy_score("ab", "xyzabc").unwrap();
        assert!(early > late);
    }

    #[test]
    fn fuzzy_perf_tripwire_500_issue_sweep_stays_fast() {
        // Synthetic 500-issue corpus, each ~1KB of prose — modelled on what
        // a `to_file_contents()` body actually looks like. The scorer runs
        // against each issue's text once per keystroke, so this is the real
        // hot path (C-005: no asset-dir binary reads).
        let issues: Vec<String> = (0..500u32)
            .map(|i| {
                format!(
                    "---\nnumber: {i}\ntitle: \"synthetic issue {i}\"\npriority: medium\n---\n\n\
                     A long body about feature {i} that mentions refunds, retries, idempotency keys, \
                     and a blocking redirect loop. The assigned developer needs to investigate the \
                     flaky test and prepare a hotfix for the staging deploy.\n\n\
                     ## Comments\n\n### alice (2026-01-01)\n\nNotes for issue {i}.\n"
                )
            })
            .collect();
        // Score 10 representative queries against the full corpus (each call
        // = one issue text per keystroke).
        let queries = [
            "issue",
            "transient race",
            "payment",
            "hotfix 3",
            "aAa",
            "zzz",
            "issue 499",
            "staging",
            "deploy",
            "ref",
        ];
        let start = std::time::Instant::now();
        for q in &queries {
            for issue in &issues {
                let _ = fuzzy_score(q, issue);
            }
        }
        let elapsed = start.elapsed();
        // 5000 fuzzy_score calls (10 queries × 500 issues); generous 500ms
        // bound. On modern hardware this runs in < 10ms.
        assert!(
            elapsed < std::time::Duration::from_millis(500),
            "500-issue corpus re-filter must stay under 500ms, took {elapsed:?}"
        );
    }

    // ----------------------------------------------------------------------
    // WP02 phase 0 — T008/T009/T010: StructuredFilter, evaluate, matches
    // ----------------------------------------------------------------------

    #[test]
    fn filter_default_has_no_active_criteria() {
        let filter = StructuredFilter::default();
        assert!(!filter.has_active_criteria());
        assert_eq!(filter.criteria().count(), 0);
        assert_eq!(filter.to_string(), "(no active criteria)");
    }

    #[test]
    fn filter_criteria_lists_only_active_in_all_order() {
        let filter = StructuredFilter {
            label: Some("urgent".to_string()),
            assignee: Some(String::new()),
            status: Some("todo".to_string()),
            priority: None,
            cycle: None,
            milestone: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            overdue: None,
            parent: None,
            category: None,
            scope: None,
            archived: None,
        };
        let criteria: Vec<(FilterField, &str)> = filter.criteria().collect();
        assert_eq!(
            criteria,
            vec![
                (FilterField::Label, "urgent"),
                (FilterField::Status, "todo")
            ]
        );
    }

    // Issue #1492 — the `archived:true|false` criterion and the
    // `--with-archived` corpus. The criterion is derived (the filename is the
    // marker), so it is lifted into the filter and judged against the issue.

    #[test]
    fn archived_criterion_matches_the_issue_state() {
        let mut archived = sample_issue(1, "Old", "");
        archived.archived = true;
        let active = sample_issue(2, "New", "");

        let want_true = StructuredFilter {
            archived: Some(true),
            ..Default::default()
        };
        assert!(want_true.archived_matches(&archived));
        assert!(!want_true.archived_matches(&active));

        let want_false = StructuredFilter {
            archived: Some(false),
            ..Default::default()
        };
        assert!(want_false.archived_matches(&active));
        assert!(!want_false.archived_matches(&archived));

        // Unset narrows nothing.
        assert!(StructuredFilter::default().archived_matches(&archived));
    }

    #[test]
    fn archived_token_is_lifted_out_of_the_query() {
        let (_tmp, store) = make_store();
        let (query, filter) = resolve_filter_criteria(&store, "archived:true status:todo").unwrap();
        assert_eq!(filter.archived, Some(true));
        assert!(
            !query.contains("archived"),
            "the token is lifted, not left for the store-free matcher: {query:?}"
        );
        assert!(filter.has_active_criteria());
        assert_eq!(filter.to_string(), "archived:true");

        let (_query, filter) = resolve_filter_criteria(&store, "archived:false").unwrap();
        assert_eq!(filter.archived, Some(false));
    }

    #[test]
    fn an_invalid_archived_value_is_refused_by_name() {
        let (_tmp, store) = make_store();
        let err = resolve_filter_criteria(&store, "archived:1").unwrap_err();
        assert!(
            err.to_string().contains("archived:true"),
            "the diagnostic names the accepted spellings: {err}"
        );
        // And a caller that skips the lift gets an empty result rather than a
        // silently-unfiltered one.
        assert!(!query_matches("archived:true", "---\nstatus: todo\n---\n"));
    }

    #[test]
    fn corpus_build_with_includes_archived_issues() {
        let (_tmp, store) = make_store();
        fs::create_dir_all(store.issues_dir.join("alice")).unwrap();
        let active = sample_issue(1, "Active", "body");
        write_issue(&store, "alice/2026-01-01-active.md", &active);
        let mut old = sample_issue(2, "Old", "body");
        old.archived = true;
        fs::write(
            store.issues_dir.join("alice/.2026-01-01-old.md"),
            old.to_file_contents(),
        )
        .unwrap();

        assert_eq!(
            Corpus::build(&store).unwrap().issues.len(),
            1,
            "the default corpus never reads the archived file"
        );
        let all = Corpus::build_with(&store, true).unwrap();
        assert_eq!(all.issues.len(), 2);
        assert!(all.issues.iter().any(|issue| issue.archived));
    }

    #[test]
    fn filter_evaluate_is_case_insensitive_substring() {
        let filter = StructuredFilter {
            status: Some("TODO".to_string()),
            ..Default::default()
        };
        assert!(filter.evaluate("---\nstatus: todo\n---\n"));
        assert!(filter.evaluate("---\nstatus: Todo\n---\n"));
        assert!(!filter.evaluate("---\nstatus: done\n---\n"));
        // Substring semantics on the serialized text (T009): a status token
        // must appear anywhere in the haystack, not only as a standalone field.
        assert!(filter.evaluate("todo"));
    }

    #[test]
    fn filter_evaluate_requires_all_active_criteria_and() {
        let haystack = "---\nstatus: todo\nlabels: [urgent]\npriority: high\nassignee: alice\n/**/";
        let all = StructuredFilter {
            assignee: Some("alice".to_string()),
            label: Some("urgent".to_string()),
            status: Some("todo".to_string()),
            priority: Some("high".to_string()),
            cycle: None,
            milestone: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            overdue: None,
            parent: None,
            category: None,
            scope: None,
            archived: None,
        };
        assert!(all.evaluate(haystack), "all four present => match");
        // Same filter, haystack missing one criterion => no match (AND).
        assert!(!all.evaluate("status: todo labels: [urgent] priority: high"));
        assert!(
            !all.evaluate(
                "---\nstatus: todo\nlabels: [urgent]\npriority: medium\nassignee: alice\n"
            )
        );
        assert!(
            !all.evaluate("---\nstatus: todo\nlabels: [other]\npriority: high\nassignee: alice\n")
        );
    }

    #[test]
    fn filter_empty_string_criterion_counts_as_unset() {
        let filter = StructuredFilter {
            assignee: Some(String::new()),
            label: Some("urgent".to_string()),
            ..Default::default()
        };
        assert!(
            filter.evaluate("labels: [urgent]"),
            "empty assignee excluded"
        );
        assert!(filter.has_active_criteria());
    }

    #[test]
    fn filter_no_criteria_matches_everything() {
        let filter = StructuredFilter::default();
        assert!(filter.evaluate("anything at all"));
        assert!(filter.evaluate(""));
    }

    #[test]
    fn filter_display_renders_key_value_pairs() {
        let filter = StructuredFilter {
            assignee: Some("alice".to_string()),
            status: Some("todo".to_string()),
            ..Default::default()
        };
        assert_eq!(filter.to_string(), "assignee:alice, status:todo");
    }

    // ----------------------------------------------------------------------
    // WP02 T010 — the `scope:` criterion
    // ----------------------------------------------------------------------

    #[test]
    fn filter_scope_is_active_even_though_it_is_not_a_modal_row() {
        // A scope is a `StructuredFilter` field but not a `FilterField`, so
        // `criteria()` — which walks `FilterField::ALL` — cannot see it. Both
        // of the things that report "is this filter doing something" have to
        // agree that it is, or the hint bar says `(no active criteria)` while
        // the board is narrowed.
        let filter = StructuredFilter {
            scope: Some(vec!["triage".to_string(), "todo".to_string()]),
            ..Default::default()
        };

        assert!(
            filter.has_active_criteria(),
            "a filter that selects rows is active however it selects them"
        );
        assert_eq!(
            filter.criteria().count(),
            0,
            "and it still is not a modal row — the TUI's row count is unchanged"
        );
        assert_eq!(
            filter.to_string(),
            "scope:triage,todo",
            "the hint bar shows the columns it resolved to, not (no active criteria)"
        );
    }

    #[test]
    fn filter_display_keeps_criteria_overdue_and_scope_together() {
        let filter = StructuredFilter {
            assignee: Some("alice".to_string()),
            status: Some("todo".to_string()),
            overdue: Some(true),
            scope: Some(vec!["triage".to_string()]),
            ..Default::default()
        };
        assert_eq!(
            filter.to_string(),
            "assignee:alice, status:todo, scope:triage, overdue:true",
            "all three sources of a part, in the order they have always printed"
        );
    }

    #[test]
    fn filter_scope_round_trips_through_toml() {
        // `skip_serializing_if` keeps a scope-less filter byte-identical to what
        // it was before WP02, and a set one survives the round trip.
        let plain = StructuredFilter::default();
        assert!(
            !toml::to_string(&plain).unwrap().contains("scope"),
            "an unset scope writes no key at all"
        );

        let filter = StructuredFilter {
            scope: Some(vec!["triage".to_string()]),
            ..Default::default()
        };
        let back: StructuredFilter = toml::from_str(&toml::to_string(&filter).unwrap()).unwrap();
        assert_eq!(back, filter);
    }

    #[test]
    fn filter_scope_criterion_narrows_evaluate_issue_but_its_absence_does_not() {
        let config = mapped_config();
        let resolution = resolution_for(&config);
        let in_box = issue_in(1, "Alpha", "triage");
        let outside = issue_in(2, "Bravo", "wip");
        let in_text = in_box.to_file_contents();
        let out_text = outside.to_file_contents();

        let scoped = StructuredFilter {
            scope: Some(vec!["triage".to_string()]),
            ..Default::default()
        };
        assert!(
            scoped.evaluate_issue(&in_box, &in_text, &resolution),
            "a member of the scope passes"
        );
        assert!(
            !scoped.evaluate_issue(&outside, &out_text, &resolution),
            "and a non-member fails — the scope is what was asked for"
        );

        let unset = StructuredFilter::default();
        assert!(
            unset.evaluate_issue(&outside, &out_text, &resolution),
            "an unset criterion narrows nothing (WP02 T010: a default view is untouched)"
        );
    }

    #[test]
    fn filter_normalize_trims_and_drops_empty() {
        let mut filter = StructuredFilter {
            assignee: Some("  ".to_string()),
            label: Some(" urgent ".to_string()),
            ..Default::default()
        };
        filter.normalize();
        assert_eq!(
            filter,
            StructuredFilter {
                assignee: None,
                label: Some("urgent".to_string()),
                ..Default::default()
            }
        );
    }

    #[test]
    fn filter_round_trips_through_toml() {
        let filter = StructuredFilter {
            assignee: Some("alice".to_string()),
            label: Some("urgent".to_string()),
            status: Some("todo".to_string()),
            priority: Some("high".to_string()),
            cycle: None,
            milestone: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            overdue: None,
            parent: None,
            category: None,
            scope: None,
            archived: None,
        };
        let text = toml::to_string(&filter).unwrap();
        let back: StructuredFilter = toml::from_str(&text).unwrap();
        assert_eq!(back, filter);
    }

    #[test]
    fn number_query_classifies_bare_numbers() {
        assert_eq!(number_query("55"), Some(55));
        assert_eq!(number_query(" 55 "), Some(55), "whitespace-padded trims");
        assert_eq!(number_query("055"), Some(55), "leading zeros parse");
        assert_eq!(number_query("0"), Some(0));
    }

    #[test]
    fn number_query_rejects_non_number_inputs() {
        assert_eq!(number_query(""), None, "empty");
        assert_eq!(number_query("   "), None, "whitespace-only");
        assert_eq!(number_query("login"), None, "non-digit");
        assert_eq!(number_query("55bug"), None, "mixed digits + letters");
        assert_eq!(
            number_query("99999999999999999999"),
            None,
            "overflows u32 -> falls back to fuzzy"
        );
        assert_eq!(number_query("-55"), None, "sign not a bare number");
    }

    #[test]
    fn number_query_accepts_u32_max() {
        assert_eq!(number_query(&u32::MAX.to_string()), Some(u32::MAX));
    }

    #[test]
    fn matches_composes_fuzzy_and_structured() {
        let filter = StructuredFilter {
            label: Some("urgent".to_string()),
            ..Default::default()
        };
        let haystack_1 = "---\ntitle: \"Login bug\"\nlabels: [urgent]\n---\n";
        let haystack_2 = "---\ntitle: \"Export csv\"\nlabels: [urgent]\n---\n";

        // Both layers must hold when both are active (FR-013).
        assert!(matches("Login", &filter, haystack_1));
        assert!(
            !matches("Login", &filter, haystack_2),
            "label matches but text does not"
        );
        assert!(
            !matches("zzz", &filter, haystack_1),
            "text matches but label does not"
        );

        // Empty query => structured filter only.
        assert!(matches("", &filter, haystack_1));
        assert!(!matches("", &filter, "labels: [critical]\n"));

        // Default filter => fuzzy text only.
        let default = StructuredFilter::default();
        assert!(matches("Login", &default, haystack_1));
        assert!(!matches("zzz", &default, haystack_1));

        // Empty layers both => always true.
        assert!(matches("", &default, "anything"));
    }

    #[test]
    fn matches_against_real_corpus() {
        let corpus = two_issue_corpus();
        let filter = StructuredFilter {
            label: Some("urgent".to_string()),
            status: Some("todo".to_string()),
            ..Default::default()
        };
        let matches_by = |query: &str| {
            corpus
                .issues
                .iter()
                .zip(&corpus.texts)
                .filter(|(_, text)| matches(query, &filter, text))
                .map(|(issue, _)| issue.number)
                .collect::<std::collections::BTreeSet<u32>>()
                .into_iter()
                .collect::<Vec<_>>()
        };
        // Both issues carry `urgent` label + todo status: filter-only
        // returns both; fuzzy text narrows: "Login bug" -> issue 1 only,
        // "empty rows" -> issue 2 only, miss -> empty.
        assert_eq!(matches_by(""), vec![1, 2]);
        assert_eq!(matches_by("Login bug"), vec![1]);
        assert_eq!(matches_by("empty rows"), vec![2]);
        assert_eq!(matches_by("zzz-no-hit"), Vec::<u32>::new());
    }

    #[test]
    fn query_matches_supports_token_grammar_and_bare_terms() {
        let haystack = "---\ncycle: Cycle 1\nmilestone: Backlog\nreviewer: alice\nstatus: todo\nstart_date: 2026-09-01\ndue_date: 2000-09-10\n---\nlogin bug\n";
        assert!(query_matches("cycle:Cycle", haystack));
        assert!(query_matches("milestone:Backlog reviewer:alice", haystack));
        assert!(query_matches("overdue:true", haystack));
        assert!(query_matches("overdue", haystack));
        assert!(query_matches("group:cycle sort:due", haystack));
        assert!(!query_matches("group:assignee", haystack));
        assert!(query_matches("login bug", haystack));
        assert!(!query_matches("cycle:Other", haystack));
        assert!(!query_matches("missing term", haystack));
    }

    #[test]
    fn matches_uses_query_tokens_for_board_paths() {
        let filter = StructuredFilter::default();
        let haystack = "---\nstatus: todo\ndue_date: 2000-01-01\ncycle: Cycle 1\n---\nbody\n";
        assert!(matches("overdue cycle:Cycle", &filter, haystack));
        assert!(!matches("overdue cycle:Other", &filter, haystack));
    }

    #[test]
    fn structured_filter_overdue_uses_due_date_and_status() {
        let filter = StructuredFilter {
            overdue: Some(true),
            ..Default::default()
        };
        let overdue_haystack = "---\nstatus: todo\ndue_date: 2000-01-01\n---\nbody\n";
        let done_haystack = "---\nstatus: done\ndue_date: 2000-01-01\n---\nbody\n";
        assert!(filter.evaluate(overdue_haystack));
        assert!(!filter.evaluate(done_haystack));
    }

    #[test]
    fn structured_filter_display_includes_new_fields() {
        let filter = StructuredFilter {
            cycle: Some("Cycle 1".to_string()),
            milestone: Some("Backlog".to_string()),
            reviewer: Some("alice".to_string()),
            start_date: Some("2026-09-01".to_string()),
            due_date: Some("2026-09-10".to_string()),
            overdue: Some(true),
            ..Default::default()
        };
        assert!(filter.to_string().contains("cycle:Cycle 1"));
        assert!(filter.to_string().contains("overdue:true"));
    }

    #[test]
    fn filter_evaluate_perf_tripwire_500_issue_sweep_stays_fast() {
        // Same synthetic corpus as the fuzzy tripwire; `evaluate` runs once
        // per entry per re-filter (NFR-001, C-002). With 4 active criteria
        // each evaluate is a handful of lowercases + contains calls.
        let filter = StructuredFilter {
            assignee: Some("alice".to_string()),
            label: Some("urgent".to_string()),
            status: Some("todo".to_string()),
            priority: Some("medium".to_string()),
            cycle: None,
            milestone: None,
            reviewer: None,
            start_date: None,
            due_date: None,
            overdue: None,
            parent: None,
            category: None,
            scope: None,
            archived: None,
        };
        let issues: Vec<String> = (0..500u32)
            .map(|i| {
                format!(
                    "---\nnumber: {i}\ntitle: \"synthetic issue {i}\"\nstatus: todo\nlabels: [urgent]\npriority: medium\nassignee: alice\n---\n\n\
                     A long body about feature {i}.\n"
                )
            })
            .collect();
        let start = std::time::Instant::now();
        for haystack in &issues {
            assert!(filter.evaluate(haystack));
        }
        let elapsed = start.elapsed();
        assert!(
            elapsed < std::time::Duration::from_millis(500),
            "500-issue structured re-filter must stay under 500ms, took {elapsed:?}"
        );
    }

    // -----------------------------------------------------------------------
    // WP06 / T024 + T025 — the `parent` criterion
    // -----------------------------------------------------------------------

    #[test]
    fn t024_the_parent_key_is_the_key_the_model_serialises() {
        // T024 step 4, the guard against the table and the file format drifting
        // apart. `key()` feeds the diagnostics, so a mismatch would make `tix
        // lint` point at a field that does not exist, with no error anywhere.
        let issue = Issue::parse(
            "---\nnumber: 1\ntitle: T\nstatus: todo\nlabels: []\npriority: medium\nparent: 7\nfiles: []\ncreated: 2026-01-01\nupdated: 2026-01-01\n---\n\nB.",
        )
        .unwrap();
        let fm = issue.frontmatter();
        assert!(
            fm.contains(&format!("\n{}:", FilterField::Parent.key())),
            "`key()` ({}) must be a key the renderer emits:\n{fm}",
            FilterField::Parent.key()
        );
        // And the reverse direction: every criterion's key is a real field, so the
        // guard above is not a one-way check that happens to pass.
        for field in FilterField::ALL {
            let key = field.key();
            if key == "cycle" || key == "milestone" {
                // These two are **not** the frontmatter keys: the model writes
                // `cycles` and `milestones`, and the query grammar uses the
                // singular. Pre-existing, and the reason this assertion is scoped
                // to `parent` rather than generalised.
                continue;
            }
            let mut probe = issue.clone();
            probe.parent = None;
            let rendered = probe.frontmatter();
            assert!(
                rendered.contains(&format!("\n{key}:")) || rendered.contains("\nlabels:"),
                "`{key}` is not a key the model emits"
            );
        }
    }

    #[test]
    fn t024_all_label_and_key_are_consistent_and_the_nine_keep_their_order() {
        // `Parent` is **appended**, so the nine existing criteria keep their
        // relative order (T024 step 2) and any user's muscle memory, or any golden
        // index, still holds.
        let expected: [FilterField; 9] = [
            FilterField::Assignee,
            FilterField::Label,
            FilterField::Status,
            FilterField::Priority,
            FilterField::Cycle,
            FilterField::Milestone,
            FilterField::Reviewer,
            FilterField::StartDate,
            FilterField::DueDate,
        ];
        assert_eq!(
            FilterField::ALL[..9],
            expected,
            "the existing nine criteria must keep their relative order"
        );
        assert_eq!(FilterField::ALL[9], FilterField::Parent, "appended tenth");
        // WP08 T034 step 2: `Category` is appended for the same reason, so `Parent`
        // is no longer last. Both are asserted rather than derived, because a test
        // that computed the expectation from `ALL` would agree with any order.
        assert_eq!(
            FilterField::ALL[10],
            FilterField::Category,
            "and Category is appended eleventh"
        );
        assert_eq!(FilterField::ALL.len(), 11, "and ALL must be complete");

        // Every variant is in ALL exactly once, so `row()` cannot panic and `next()`
        // cannot skip one.
        for field in FilterField::ALL {
            let row = field.row();
            assert_eq!(
                FilterField::ALL[row],
                field,
                "{field:?} is not at its own row"
            );
            assert_eq!(
                FilterField::ALL.iter().filter(|f| **f == field).count(),
                1,
                "{field:?} appears more than once in ALL"
            );
            assert!(!field.label().is_empty(), "{field:?} has an empty label");
            assert!(!field.key().is_empty(), "{field:?} has an empty key");
        }
    }

    #[test]
    fn t024_row_navigation_wraps_at_the_new_bounds() {
        // The first version of the table wrapped correctly by accident of the
        // bounds; with a tenth row the arithmetic is different, so both ends are
        // asserted — and WP08 added an eleventh, so the bound moved again.
        assert_eq!(FilterField::Assignee.row(), 0, "the first row");
        assert_eq!(FilterField::Parent.row(), 9, "not last any more");
        assert_eq!(FilterField::Category.row(), 10, "the new last row");
        assert_eq!(
            FilterField::Category.next(),
            FilterField::Assignee,
            "the last row wraps to the first"
        );
        assert_eq!(
            FilterField::Assignee.prev(),
            FilterField::Category,
            "and the first row's predecessor is the new last"
        );
        // The boundary is `ALL.len()` in both directions, so a twelfth row would
        // wrap correctly without either of the assertions above being edited.
        assert_eq!(
            FilterField::ALL[FilterField::Assignee.row() + FilterField::ALL.len() - 1],
            FilterField::Category,
            "prev is a mod of len, not of a hard-coded index"
        );
        // A full lap visits all eleven, once each.
        let mut field = FilterField::Assignee;
        let mut seen = Vec::new();
        for _ in 0..FilterField::ALL.len() {
            seen.push(field);
            field = field.next();
        }
        assert_eq!(field, FilterField::Assignee, "a full lap returns home");
        seen.sort_by_key(|f| f.row());
        assert_eq!(seen, FilterField::ALL.to_vec(), "visiting each once");
    }

    fn child_file(number: u32, title: &str, parent: Option<u32>) -> String {
        let parent_line = parent.map(|p| format!("parent: {p}\n")).unwrap_or_default();
        format!(
            "---\nnumber: {number}\ntitle: {title}\nstatus: todo\nlabels: []\npriority: medium\n{parent_line}files: []\ncreated: 2026-01-01\nupdated: 2026-01-01\n---\n\nBody text.\n"
        )
    }

    #[test]
    fn t025_a_parent_criterion_matches_exactly_its_direct_children() {
        // #1 has children #2 and #3; #4 is #2's child, and #5 is unrelated.
        let files = [
            child_file(1, "Parent", None),
            child_file(2, "Child A", Some(1)),
            child_file(3, "Child B", Some(1)),
            child_file(4, "Grandchild", Some(2)),
            child_file(5, "Unrelated", None),
        ];
        let filter = StructuredFilter {
            parent: Some("1".to_string()),
            ..StructuredFilter::default()
        };
        let matched: Vec<u32> = files
            .iter()
            .filter(|f| filter.evaluate(f))
            .map(|f| {
                f.lines()
                    .find_map(|l| l.strip_prefix("number: "))
                    .and_then(|n| n.parse().ok())
                    .unwrap()
            })
            .collect();
        assert_eq!(
            matched,
            vec![2, 3],
            "direct children only — a grandchild must not match its grandparent"
        );
    }

    #[test]
    fn t025_the_criterion_compares_the_number_exactly_not_as_a_substring() {
        // The hazard a substring implementation walks into: `parent: 1` would also
        // match `parent: 11`, and `parent: 1` would match any issue whose *body*
        // mentions 1.
        let filter = StructuredFilter {
            parent: Some("1".to_string()),
            ..StructuredFilter::default()
        };
        assert!(filter.evaluate(&child_file(2, "A", Some(1))), "exactly 1");
        assert!(
            !filter.evaluate(&child_file(2, "A", Some(11))),
            "11 must not match a criterion of 1"
        );
        assert!(!filter.evaluate(&child_file(2, "A", Some(10))), "nor 10");
        // An issue with no `parent:` key at all must not match, even though its
        // number is 1 and its body mentions 1.
        let no_parent = "---\nnumber: 1\ntitle: mentions 1\nstatus: todo\nlabels: []\npriority: medium\nfiles: []\ncreated: 2026-01-01\nupdated: 2026-01-01\n---\n\nBody with 1 in it.\n";
        assert!(
            !filter.evaluate(no_parent),
            "an issue with no parent key must not match a parent criterion"
        );
    }

    #[test]
    fn t025_a_child_of_a_deleted_parent_matches_nothing() {
        // T025 step 4. The recorded reference is retained, so the child still says
        // `parent: 1`; but a criterion can only be *set* to a number a user named,
        // and once #1 is gone no selector resolves to it — so nothing is reachable
        // through the query path, which is the outcome the subtask asks for.
        let filter = StructuredFilter {
            parent: Some("1".to_string()),
            ..StructuredFilter::default()
        };
        let orphan = child_file(2, "Orphan", Some(1));
        // The service reports it unresolved, which is the state that matters.
        let parsed = Issue::parse(&orphan).unwrap();
        let index = crate::hierarchy::HierarchyIndex::build(std::slice::from_ref(&parsed));
        assert_eq!(index.unresolved().len(), 1, "the reference is diagnosed");
        // And a criterion naming a *different, live* parent does not match it.
        let other = StructuredFilter {
            parent: Some("7".to_string()),
            ..StructuredFilter::default()
        };
        assert!(
            !other.evaluate(&orphan),
            "a live, different parent does not match"
        );
        // The retained reference still matches its own number, which is the honest
        // answer: the field says 1, so a filter saying 1 selects it. Documented in
        // contracts/cli-surface.md §4 rather than papered over.
        assert!(
            filter.evaluate(&orphan),
            "the recorded reference is retained, so it still matches its own number"
        );
    }

    #[test]
    fn t025_the_query_grammar_matches_parent_exactly_too() {
        // The `query_matches` path, which is what `tix list --filter` and the TUI's
        // text field use — a different entry point from `StructuredFilter::evaluate`.
        let child = child_file(2, "A", Some(1));
        assert!(query_matches("parent:1", &child), "exactly 1");
        // The negative case has to be a fixture whose **other text** contains `11`,
        // or a substring implementation is not actually exercised. The first version
        // of this test used a plain fixture whose remaining text happens not to
        // contain "11" — so reverting the exact comparison to a substring left the
        // test green.
        let decoy = child_file(2, "Issue 11 notes", Some(1))
            .replace("Body text.\n", "Body text. See issue 11 for context.\n");
        assert!(
            !query_matches("parent:11", &decoy),
            "a body mentioning 11 must not match a criterion of 11"
        );
        assert!(
            query_matches("parent:1", &decoy),
            "while the real parent still matches"
        );
        assert!(
            query_matches("parent:11", &child_file(2, "A", Some(11))),
            "and 11 matches when it is the real parent"
        );
        // An empty value is **not** a criterion: `parse_token` rejects a token with
        // an empty value, so `parent:` falls through to the bare-term path and is
        // fuzzy-matched like any other word — which is what every other key does
        // too, and is why `parent` needed no special case here.
        //
        // The first version of this test asserted `!query_matches("parent:", ..)`,
        // reading "not a criterion" as "matches nothing". Measured, it matches — as
        // `status:` and `due:` do. An intermediate attempt asserted consistency by
        // comparing the same query against two different haystacks, which is not a
        // consistency property at all and failed for the right reason: the keys are
        // not interchangeable on one haystack, because `parent:` and `status:` are
        // literally different strings.
        //
        // Measured, an empty `parent:` **does** correlate with "has a parent",
        // because the bare term happens to be the literal string `parent:` and the
        // haystack contains it. That is an accident of the fuzzy path, not a
        // criterion: the *values* are ignored entirely, so two issues with
        // completely different parents both match.
        //
        // Asserted as a pair, because the first half alone is a misleading
        // statement and the second alone is trivially true. Two earlier versions of
        // this test asserted the narrowing property above, which is simply not how
        // it behaves.
        assert!(
            query_matches("parent:", &child_file(2, "A", Some(1)))
                && query_matches("parent:", &child_file(3, "B", Some(7))),
            "an empty value ignores the parent, so any two parents both match"
        );
        assert!(
            !query_matches("parent:", &child_file(4, "C", None)),
            "and an issue with no `parent:` key has no literal to match"
        );
        // And the substring and fuzzy semantics are untouched when a criterion is
        // combined with a bare term.
        assert!(
            query_matches("parent:1 Body", &child),
            "a bare term still applies alongside the criterion"
        );
        assert!(
            !query_matches("parent:1 nonsense", &child),
            "and can still exclude"
        );
    }

    #[test]
    fn t025_an_empty_criterion_behaves_like_the_others() {
        // The canonical invariant: an empty string is "no criterion" everywhere, so
        // the filter modal can edit a slot without a live-match surprise.
        let mut filter = StructuredFilter::default();
        assert_eq!(filter.parent, None);
        // The mutable accessor is what the filter modal types into, and what
        // creates the empty slot (there is no `set()`; `value_mut` is the path).
        assert_eq!(
            FilterField::Parent.value_mut(&mut filter),
            "",
            "value_mut() creates the slot empty"
        );
        assert_eq!(
            FilterField::Parent.value(&filter),
            None,
            "and value() reports no criterion"
        );
        assert!(
            !filter.has_active_criteria(),
            "an empty slot is not an active criterion"
        );
        // Any other active criterion still counts.
        filter.assignee = Some("alice".into());
        assert!(filter.has_active_criteria());
        FilterField::Parent.unset(&mut filter);
        assert_eq!(filter.parent, None, "unset clears the slot");
    }
    // ----------------------------------------------------------------------
    // WP08 T034/T035 — the category criterion
    // ----------------------------------------------------------------------

    /// A board that **declares a `category_map`**, so the criterion has something
    /// to resolve against.
    ///
    /// `triage=backlog, wip=active, review=active, shipped=completed,
    /// abandoned=canceled`. Two properties this fixture is chosen for:
    ///
    /// - `shipped` is complete and `done_column` is `shipped`, so a column
    ///   comparison and a category decision *agree* here — which is why a second
    ///   fixture below inverts them.
    /// - Three columns share `active`, so `category:active` returning three issues
    ///   is a claim a `status:` criterion could not make.
    fn mapped_config() -> crate::config::Config {
        crate::config::Config {
            issues_dir: std::path::PathBuf::from("/nonexistent"),
            kanban: crate::config::KanbanSection {
                configurations: indexmap::IndexMap::from([(
                    "default".to_string(),
                    crate::config::BoardConfiguration {
                        columns: vec![
                            "triage".into(),
                            "wip".into(),
                            "review".into(),
                            "shipped".into(),
                            "abandoned".into(),
                        ],
                        done_column: Some("shipped".to_string()),
                        category_map: indexmap::IndexMap::from([
                            ("triage".to_string(), "backlog".to_string()),
                            ("wip".to_string(), "active".to_string()),
                            ("review".to_string(), "active".to_string()),
                            ("shipped".to_string(), "completed".to_string()),
                            ("abandoned".to_string(), "canceled".to_string()),
                        ]),
                        ..Default::default()
                    },
                )]),
            },
            ..crate::config::Config::default()
        }
    }

    fn issue_in(number: u32, title: &str, column: &str) -> Issue {
        let mut issue = sample_issue(number, title, "");
        issue.status = Status::new(column);
        issue
    }

    fn filter_for(category: Option<&str>) -> StructuredFilter {
        StructuredFilter {
            category: category.map(str::to_string),
            ..StructuredFilter::default()
        }
    }

    fn resolution_for(config: &crate::config::Config) -> crate::workflow::CategoryResolution {
        let (_, resolution) = crate::workflow::active_resolution(config);
        resolution
    }

    #[test]
    fn t034_key_reports_the_token_and_is_derived() {
        // T034 step 4, the design question. `key()` says `category` because that
        // is what the grammar parses and what a hint bar should echo; `is_derived`
        // is what stops a surface from reading it as a frontmatter key.
        assert_eq!(FilterField::Category.key(), "category");
        assert!(FilterField::Category.is_derived());
        assert_eq!(
            FilterField::Category.label(),
            "Category",
            "in the existing style"
        );
        // Every other criterion is a real field, so the derived flag singles out
        // exactly one — a test that only checked `Category` would pass if
        // `is_derived` matched everything.
        for field in FilterField::ALL {
            assert_eq!(
                field.is_derived(),
                field == FilterField::Category,
                "{field:?} derived-flag is wrong"
            );
        }
        // The two spellings differ **only** for the derived one.
        assert_eq!(FilterField::Assignee.describe(), "assignee");
        assert_eq!(
            FilterField::Category.describe(),
            "category (derived from status)",
            "an explanation must not send a user looking for a field that does not exist"
        );
    }

    #[test]
    fn t035_a_mapped_completed_column_matches_category_completed() {
        let config = mapped_config();
        let resolution = resolution_for(&config);
        let shipped = issue_in(1, "Shipped", "shipped");
        let wip = issue_in(2, "Wip", "wip");
        let filter = filter_for(Some("completed"));
        assert!(
            filter.category_matches(&shipped, &resolution),
            "a completed column is in the completed category"
        );
        assert!(
            !filter.category_matches(&wip, &resolution),
            "and nothing else is"
        );
    }

    #[test]
    fn t035_one_category_spans_every_column_mapped_to_it() {
        // The reason the criterion is a category and not a column: three columns
        // resolve to `active`, and all three must match.
        let config = mapped_config();
        let resolution = resolution_for(&config);
        let filter = filter_for(Some("active"));
        for column in ["wip", "review"] {
            assert!(
                filter.category_matches(&issue_in(1, "A", column), &resolution),
                "{column} is active"
            );
        }
        assert!(
            !filter.category_matches(&issue_in(1, "A", "triage"), &resolution),
            "and triage is not"
        );
    }

    #[test]
    fn t035_an_unconfigured_column_matches_no_category() {
        // The third case T035 step 3 does not name, and the one the other two
        // surfaces already distinguish: `tix list --show category` prints
        // `(unmapped)` and MCP returns `category: null` (WP07) for a column the
        // board does not configure. Folding it into the safe default would make
        // `category:unstarted` return issues every other surface call unmapped.
        let config = mapped_config();
        let resolution = resolution_for(&config);
        let orphan = issue_in(1, "Orphan", "not-a-column");
        for category in ["unstarted", "backlog", "active", "completed", "canceled"] {
            assert!(
                !filter_for(Some(category)).category_matches(&orphan, &resolution),
                "an unconfigured column has no category, so `category:{category}` \\
                 must not match it"
            );
        }
    }

    #[test]
    fn t035_a_canceled_column_is_in_canceled_and_not_in_completed() {
        // The C-004 rule, made visible at the criterion: a canceled issue is
        // terminal and **not** complete, and a criterion that conflated the two
        // would put abandoned work in a "done" search.
        let config = mapped_config();
        let resolution = resolution_for(&config);
        let canceled = issue_in(1, "Abandoned", "abandoned");
        assert!(filter_for(Some("canceled")).category_matches(&canceled, &resolution));
        assert!(!filter_for(Some("completed")).category_matches(&canceled, &resolution));
    }

    #[test]
    fn t035_evaluate_ignores_the_category_criterion_but_evaluate_issue_does_not() {
        // `evaluate` is store-free and therefore cannot judge a derived criterion.
        // If it *tried*, `hay.contains("completed")` would match an issue whose
        // **body** mentions the word — so the test pins both halves: `evaluate`
        // does not apply it, and `evaluate_issue` does.
        let config = mapped_config();
        let resolution = resolution_for(&config);
        let filter = filter_for(Some("completed"));
        let in_wip = issue_in(1, "Mentioning shipped work", "wip");
        let text = format!(
            "{}\n\nwe shipped this last quarter\n",
            in_wip.to_file_contents()
        );
        assert!(
            filter.evaluate(&text),
            "a substring test would wrongly match the body"
        );
        assert!(
            !filter.evaluate_issue(&in_wip, &text, &resolution),
            "the real criterion says no"
        );
        let done = issue_in(2, "Done", "shipped");
        let text = done.to_file_contents();
        assert!(filter.evaluate_issue(&done, &text, &resolution));
    }

    #[test]
    fn t035_an_unknown_category_is_an_error_not_an_empty_result() {
        // T037 step 5, at the layer that can produce the error. Through the
        // composed entry point, because that is what every surface calls — a test of
        // the inner function would not show that the *surface* rejects.
        let (_tmp, store) = store_with(mapped_config());
        let err = crate::search::resolve_filter_criteria(&store, "category:finished")
            .unwrap_err()
            .to_string();
        assert!(err.contains("unknown category 'finished'"), "{err}");
        // The message names what *would* have worked — from this project's own
        // vocabulary, not the global six.
        for key in crate::config::CATEGORY_KEYS {
            assert!(err.contains(key), "'{key}' missing from: {err}");
        }
    }

    /// A store over an arbitrary `Config`, holding one issue (`Alpha`, in `triage`),
    /// for the command-layer resolvers.
    ///
    /// The issue is there because `resolve_filter_criteria` resolves a
    /// `parent:<selector>` token through the store, and a fixture with no issues
    /// would fail every query carrying one — so the composed function could not be
    /// exercised on the half of its job that is not about categories.
    fn store_with(config: crate::config::Config) -> (tempfile::TempDir, Store) {
        let tmp = tempfile::TempDir::new().unwrap();
        let dir = tmp.path().join("issues");
        fs::create_dir_all(dir.join("alice")).unwrap();
        let config = crate::config::Config {
            issues_dir: dir.clone(),
            ..config
        };
        config.save(&tmp.path().join("tix.toml")).unwrap();
        let config =
            crate::config::Config::load_with_warning(&tmp.path().join("tix.toml"), |_| {}).unwrap();
        fs::write(
            dir.join("alice/2026-01-01-alpha.md"),
            "---\nnumber: 1\ntitle: Alpha\nstatus: triage\nlabels: []\n\
             priority: medium\ncreated: \"2026-01-01\"\nupdated: \"2026-01-01\"\n\
             ---\n\nbody\n",
        )
        .unwrap();
        let store = Store {
            issues_dir: dir,
            config,
        };
        (tmp, store)
    }

    #[test]
    fn t035_a_reduced_project_vocabulary_rejects_a_key_it_did_not_declare() {
        // The project's `order` may be a subset of the global six. `unstarted` is
        // in the global set but not in this project, so accepting it would return
        // results from a category the project never declared.
        let mut config = mapped_config();
        config.categories.order = vec![
            "backlog".to_string(),
            "active".to_string(),
            "completed".to_string(),
        ];
        config.categories.default = "active".to_string();
        // The board's own map has to fit inside the reduced vocabulary or the config
        // is refused at load. That refusal is the **right** behaviour and a
        // constraint the fixture has to honour rather than work around: the first
        // version kept `abandoned -> canceled`, so the fixture never reached the
        // code under test and the failure it reported was about the board, not
        // about the criterion.
        let board = config.kanban.configurations.get_mut("default").unwrap();
        board.category_map.shift_remove("abandoned");
        board.columns.retain(|c| c != "abandoned");
        let (_tmp, store) = store_with(config);
        let err = crate::search::resolve_filter_criteria(&store, "category:unstarted")
            .unwrap_err()
            .to_string();
        assert!(err.contains("unstarted"), "{err}");
        assert!(
            !err.contains("canceled"),
            "a key the project did not declare must not be offered: {err}"
        );
        assert!(err.contains("backlog, active, completed"), "{err}");
        // A declared key still resolves, and is canonicalized.
        let (query, criteria) =
            crate::search::resolve_filter_criteria(&store, "category:Completed").unwrap();
        assert_eq!(criteria.category.as_deref(), Some("completed"));
        assert_eq!(query, "", "and the token is lifted out of the query");
    }

    #[test]
    fn t035_a_query_without_a_category_token_is_unchanged() {
        let (_tmp, store) = store_with(mapped_config());
        for query in ["", "alice", "assignee:alice", "overdue"] {
            let (resolved, criteria) =
                crate::search::resolve_filter_criteria(&store, query).unwrap();
            assert_eq!(resolved, query, "{query:?} must round-trip");
            assert_eq!(criteria.category, None, "{query:?} gained a criterion");
        }
    }

    #[test]
    fn t035_a_category_token_is_lifted_out_and_canonicalized() {
        // The shape that actually works, and the one the first version got wrong.
        // It rewrote the token in place, so `query_matches` still met a `category`
        // key, still refused it, and every filter came back empty — while this
        // test's own assertion (that the value was canonicalized) passed.
        let (_tmp, store) = store_with(mapped_config());
        let (query, criteria) =
            crate::search::resolve_filter_criteria(&store, "category:COMPLETED alpha").unwrap();
        assert_eq!(
            criteria.category.as_deref(),
            Some("completed"),
            "canonical, and carried structurally"
        );
        assert_eq!(
            query, "alpha",
            "the token is **removed**: a token left in the string meets a key \
             `query_matches` refuses, which is an empty result with no error"
        );
    }

    #[test]
    fn t035_the_parent_and_category_resolvers_compose() {
        // One entry point, so a call site cannot resolve one and forget the other.
        // A `parent:` selector becomes a **number** in the query (a rewrite); a
        // `category:` value leaves the query entirely (a lift).
        let (_tmp, store) = store_with(mapped_config());
        let (query, criteria) =
            crate::search::resolve_filter_criteria(&store, "category:completed parent:1").unwrap();
        assert_eq!(query, "parent:1", "parent stays, category is lifted");
        assert_eq!(criteria.category.as_deref(), Some("completed"));
    }

    #[test]
    fn t035_a_query_with_no_criterion_is_unaffected() {
        // T035 step 4: existing substring and fuzzy behaviour must not change.
        let config = mapped_config();
        let resolution = resolution_for(&config);
        let issue = issue_in(1, "Alpha", "wip");
        let text = issue.to_file_contents();
        let empty = StructuredFilter::default();
        assert!(crate::search::matches_issue(
            "alpha",
            &empty,
            &issue,
            &text,
            &resolution
        ));
        assert!(crate::search::matches_issue(
            "",
            &empty,
            &issue,
            &text,
            &resolution
        ));
        assert!(!crate::search::matches_issue(
            "zzz",
            &empty,
            &issue,
            &text,
            &resolution
        ));
    }

    #[test]
    fn t035_matching_reads_the_service_and_never_the_column_name() {
        // A board whose `category_map` puts `completed` on `shipped` while
        // `done_column` is `done` — so the two disagree. Second time this
        // programme has needed such a board: on `mapped_config` they agree, so a
        // column comparison and a category decision cannot tell each other apart.
        let config = crate::config::Config {
            kanban: crate::config::KanbanSection {
                configurations: indexmap::IndexMap::from([(
                    "default".to_string(),
                    crate::config::BoardConfiguration {
                        columns: vec!["todo".into(), "shipped".into(), "done".into()],
                        done_column: Some("done".to_string()),
                        category_map: indexmap::IndexMap::from([
                            ("todo".to_string(), "unstarted".to_string()),
                            ("shipped".to_string(), "completed".to_string()),
                            ("done".to_string(), "active".to_string()),
                        ]),
                        ..Default::default()
                    },
                )]),
            },
            ..crate::config::Config::default()
        };
        let resolution = resolution_for(&config);
        let shipped = issue_in(1, "Shipped", "shipped");
        let done = issue_in(2, "Done column", "done");
        assert!(
            filter_for(Some("completed")).category_matches(&shipped, &resolution),
            "the service says shipped is complete"
        );
        assert!(
            !filter_for(Some("completed")).category_matches(&done, &resolution),
            "and `done` is not, even though it is the done_column"
        );
        // The derived criterion still finds `todo` under the safe default.
        assert!(
            filter_for(Some("unstarted"))
                .category_matches(&issue_in(3, "Todo", "todo"), &resolution)
        );
    }

    #[test]
    fn t035_the_query_token_matcher_refuses_rather_than_guessing() {
        // `query_matches` cannot judge the criterion, so its `category` arm is an
        // explicit total refusal. This pins the *consequence*: a caller that
        // skipped `matches_issue` gets an empty result a user can see, not an
        // unfiltered one they cannot.
        let issue = issue_in(1, "Shipped", "shipped");
        let text = issue.to_file_contents();
        assert!(!query_matches("category:completed", &text));
        // And it does not fall through to a substring test on the word.
        let mention = issue_in(2, "Mentions completed", "triage");
        assert!(
            !query_matches("category:completed", &mention.to_file_contents()),
            "and never matches the word in a title"
        );
    }

    #[test]
    fn t035_two_boards_with_different_column_names_agree() {
        // T037 step 4, the intake's first acceptance scenario at the criterion
        // layer. Same mapping, different column names: the criterion is about the
        // category, so both boards must return the same answer.
        let a = mapped_config();
        let b = crate::config::Config {
            kanban: crate::config::KanbanSection {
                configurations: indexmap::IndexMap::from([(
                    "default".to_string(),
                    crate::config::BoardConfiguration {
                        columns: vec![
                            "icebox".into(),
                            "doing".into(),
                            "verifying".into(),
                            "released".into(),
                            "dropped".into(),
                        ],
                        done_column: Some("released".to_string()),
                        category_map: indexmap::IndexMap::from([
                            ("icebox".to_string(), "backlog".to_string()),
                            ("doing".to_string(), "active".to_string()),
                            ("verifying".to_string(), "active".to_string()),
                            ("released".to_string(), "completed".to_string()),
                            ("dropped".to_string(), "canceled".to_string()),
                        ]),
                        ..Default::default()
                    },
                )]),
            },
            ..crate::config::Config::default()
        };
        for (column_a, column_b) in [
            ("triage", "icebox"),
            ("wip", "doing"),
            ("shipped", "released"),
            ("abandoned", "dropped"),
        ] {
            for key in crate::config::CATEGORY_KEYS {
                let want = filter_for(Some(key))
                    .category_matches(&issue_in(1, "X", column_a), &resolution_for(&a));
                let got = filter_for(Some(key))
                    .category_matches(&issue_in(1, "X", column_b), &resolution_for(&b));
                assert_eq!(
                    want, got,
                    "{column_a} ({key}) and {column_b} ({key}) disagree"
                );
            }
        }
    }
}