tix-tracker 0.4.0

//! WP06 T029 — `tix lint`'s workflow families, through the real binary.
//!
//! Two families are covered, and only two are *reachable*:
//!
//! - **`unmapped_column_default`** — the safe default is reported, as a warning that
//!   does not set the exit code.
//! - **`direct_edit_policy_violation`** — a file whose `status` contradicts its own
//!   History is reported, and **nothing is written**.
//!
//! ## The configuration scenarios T029 lists are unreachable, and that is recorded
//!
//! T029 step 2 asks for a board with no `completed` mapping, an unknown category,
//! and a mapping for an unconfigured column. All three are refused at **config
//! load** (`contracts/category-vocabulary.md` §3 makes them fatal), so `tix lint`
//! cannot run on such a config at all — the same reachability problem WP05 found
//! with `tix workflow show`. Asserting those here would mean asserting a success the
//! tool never reaches, so they are pinned as *load failures* instead, which is the
//! stronger statement: the condition cannot be silently tolerated, because the tool
//! will not start.
//!
//! Every case here is TTY-free, network-free, and deterministic.

use std::fs;
use std::path::{Path, PathBuf};

use assert_cmd::Command;
use predicates::prelude::*;
use tempfile::TempDir;

fn tix() -> Command {
    Command::cargo_bin("tix").unwrap()
}

/// A repo whose board **declares a `category_map`**, so transition policy applies and
/// a terminal exit is a real refusal.
///
/// `triage=backlog, wip=active, review=active, shipped=completed,
/// abandoned=canceled`.
fn mapped_repo() -> (TempDir, PathBuf) {
    let tmp = TempDir::new().unwrap();
    let dir = tmp.path().to_path_buf();
    fs::create_dir_all(dir.join("docs").join("issues")).unwrap();
    fs::write(
        dir.join("tix.toml"),
        "issues_dir = \"docs/issues\"\n\n\
         [kanban.default]\n\
         columns = [\"triage\", \"wip\", \"review\", \"shipped\", \"abandoned\"]\n\
         done_column = \"shipped\"\n\n\
         [kanban.default.category_map]\n\
         triage = \"backlog\"\n\
         wip = \"active\"\n\
         review = \"active\"\n\
         shipped = \"completed\"\n\
         abandoned = \"canceled\"\n",
    )
    .unwrap();
    (tmp, dir)
}

/// The single issue file, whatever assignee segment it landed in.
fn issue_file(dir: &Path, title: &str) -> PathBuf {
    let slug = title.to_lowercase().replace(' ', "-");
    let issues = dir.join("docs").join("issues");
    for entry in fs::read_dir(&issues).unwrap() {
        let path = entry.unwrap().path();
        if path.is_dir() {
            for child in fs::read_dir(&path).unwrap() {
                let child = child.unwrap().path();
                if child
                    .file_name()
                    .and_then(|n| n.to_str())
                    .is_some_and(|n| n.contains(&slug))
                {
                    return child;
                }
            }
        } else if path
            .file_name()
            .and_then(|n| n.to_str())
            .is_some_and(|n| n.contains(&slug))
        {
            return path;
        }
    }
    panic!("no issue file matching {title:?}");
}

/// Every byte under `docs/issues`, sorted — the only honest proof of "nothing was
/// written", History sections included.
fn snapshot(dir: &Path) -> Vec<(PathBuf, Vec<u8>)> {
    let mut out = Vec::new();
    let mut stack = vec![dir.join("docs").join("issues")];
    while let Some(cur) = stack.pop() {
        for entry in fs::read_dir(&cur).unwrap() {
            let path = entry.unwrap().path();
            if path.is_dir() {
                stack.push(path);
            } else {
                out.push((path.clone(), fs::read(&path).unwrap()));
            }
        }
    }
    out.sort();
    out
}

#[test]
fn t029_the_safe_default_is_reported_without_failing_the_exit_code() {
    // T026 step 3 / step 6. The board here declares no `category_map`, so every
    // column relies on the documented default — and that must be *visible*.
    let tmp = TempDir::new().unwrap();
    let dir = tmp.path().to_path_buf();
    tix().current_dir(&dir).arg("init").assert().success();
    tix()
        .current_dir(&dir)
        .args(["create", "--title", "Alpha"])
        .assert()
        .success();

    tix()
        .current_dir(&dir)
        .arg("lint")
        .assert()
        // **Not** an error: a column relying on the default is a valid
        // configuration, and it is what every repository in the world has.
        .success()
        .code(0)
        .stderr(predicate::str::contains("unmapped_column_default"))
        // The finding names the board and every column relying on the default, so
        // the remedy is legible. `tix init` writes `todo`/`in progress`/`in review`/
        // `done`, and `done` is excluded (it resolves through the completion
        // reconciliation, which is working as intended) — so three columns.
        .stderr(predicate::str::contains("board `default`"))
        .stderr(predicate::str::contains("todo"))
        .stderr(predicate::str::contains("in review"))
        .stderr(predicate::str::contains("does not affect the exit code"))
        .stdout(predicate::str::contains("Lint OK with 1 warning"));
}

#[test]
fn t029_a_fully_mapped_board_reports_no_workflow_finding() {
    // The other half: a board that declared every column has nothing to be told.
    let (_tmp, dir) = mapped_repo();
    tix()
        .current_dir(&dir)
        .args(["create", "--title", "Alpha"])
        .assert()
        .success();
    tix()
        .current_dir(&dir)
        .arg("lint")
        .assert()
        .success()
        .stdout(predicate::str::contains("Lint OK:"))
        .stderr(predicate::str::contains("unmapped_column_default").not());
}

#[test]
fn t029_a_hand_edited_status_is_reported_exactly_once() {
    // T029 step 3. The whole point of the check: a status changed behind `tix`'s
    // back is *visible*, without being touched.
    let (_tmp, dir) = mapped_repo();
    tix()
        .current_dir(&dir)
        .args(["create", "--title", "Alpha", "--status", "triage"])
        .assert()
        .success();
    // One accepted move, so the file has a decision to contradict.
    tix()
        .current_dir(&dir)
        .args(["move", "1", "wip"])
        .assert()
        .success();

    let file = issue_file(&dir, "Alpha");
    let text = fs::read_to_string(&file).unwrap();
    assert!(
        text.contains("transition_accepted"),
        "precondition: a decision was recorded to contradict"
    );
    // The hand edit: straight to `review`, bypassing `tix` entirely.
    fs::write(&file, text.replace("status: wip", "status: review")).unwrap();

    tix()
        .current_dir(&dir)
        .arg("lint")
        .assert()
        .failure()
        .stderr(predicate::str::contains("direct_edit_policy_violation"))
        // T027 step 2: a finding that says only "something changed" is not
        // acceptable, so **both** sides of the disagreement must be named.
        .stderr(predicate::str::contains("wip"))
        .stderr(predicate::str::contains("review"))
        // …and the *sentence* has to say why, not merely the two columns. The
        // columns above also appear in the finding's `value`, so they render in the
        // title even when the message is a stub — asserting them alone let a
        // reverted message pass. These phrases exist only in the message.
        .stderr(predicate::str::contains("History records"))
        .stderr(predicate::str::contains("outside `tix`"));
}

#[test]
fn t029_lint_writes_nothing_about_a_hand_edited_file() {
    // T029 step 4, the assertion a reviewer checks first for C-005. Byte-identity of
    // the whole directory, so a repair, an appended History entry, or a rewritten
    // existing entry all fail here.
    let (_tmp, dir) = mapped_repo();
    tix()
        .current_dir(&dir)
        .args(["create", "--title", "Alpha", "--status", "triage"])
        .assert()
        .success();
    tix()
        .current_dir(&dir)
        .args(["move", "1", "wip"])
        .assert()
        .success();
    let file = issue_file(&dir, "Alpha");
    let text = fs::read_to_string(&file).unwrap();
    fs::write(&file, text.replace("status: wip", "status: review")).unwrap();

    let before = snapshot(&dir);
    tix().current_dir(&dir).arg("lint").assert().failure();
    assert_eq!(
        snapshot(&dir),
        before,
        "C-005: lint is observational. It must not repair the file, append a History \
         entry, rewrite an existing one, or touch anything else."
    );
}

#[test]
fn t029_a_consistent_history_reports_nothing() {
    // The negative control. Without it, a check that fires on every file would pass
    // the case above.
    let (_tmp, dir) = mapped_repo();
    tix()
        .current_dir(&dir)
        .args(["create", "--title", "Alpha", "--status", "triage"])
        .assert()
        .success();
    tix()
        .current_dir(&dir)
        .args(["move", "1", "wip"])
        .assert()
        .success();
    tix()
        .current_dir(&dir)
        .arg("lint")
        .assert()
        .success()
        .stderr(predicate::str::contains("direct_edit_policy_violation").not());
}

#[test]
fn t029_an_issue_never_moved_reports_nothing() {
    // The most important negative case, and the one a naive implementation gets
    // wrong. A file with **no** decision at all has not been hand-edited — an issue
    // created directly into a column was never moved, so there is nothing to
    // contradict. Reporting every such file would fire on every issue in every
    // repository that has not been moved, which is lint's characteristic failure
    // mode: a finding nobody reads.
    let (_tmp, dir) = mapped_repo();
    for title in ["Alpha", "Bravo", "Charlie"] {
        tix()
            .current_dir(&dir)
            .args(["create", "--title", title, "--status", "wip"])
            .assert()
            .success();
    }
    tix()
        .current_dir(&dir)
        .arg("lint")
        .assert()
        .success()
        .stderr(predicate::str::contains("direct_edit_policy_violation").not());
}

#[test]
fn t029_lint_is_deterministic_across_runs() {
    // T028 step 5. Two runs over the same tree must produce byte-identical output;
    // a "sorted" list built from a `HashMap` iteration would pass an ordering
    // assertion spuriously, which is why this compares the two runs rather than
    // checking the sort.
    let (_tmp, dir) = mapped_repo();
    tix()
        .current_dir(&dir)
        .args(["create", "--title", "Alpha", "--status", "triage"])
        .assert()
        .success();
    tix()
        .current_dir(&dir)
        .args(["move", "1", "wip"])
        .assert()
        .success();
    // Two more, edited, so the findings list has more than one element to order.
    for (n, title) in [(2, "Bravo"), (3, "Charlie")] {
        tix()
            .current_dir(&dir)
            .args(["create", "--title", title, "--status", "triage"])
            .assert()
            .success();
        tix()
            .current_dir(&dir)
            .args(["move", &n.to_string(), "wip"])
            .assert()
            .success();
        let file = issue_file(&dir, title);
        let text = fs::read_to_string(&file).unwrap();
        fs::write(&file, text.replace("status: wip", "status: review")).unwrap();
    }

    let run = || {
        let out = tix().current_dir(&dir).arg("lint").output().unwrap();
        String::from_utf8_lossy(&out.stdout).to_string() + &String::from_utf8_lossy(&out.stderr)
    };
    let first = run();
    let second = run();
    assert_eq!(
        first, second,
        "two runs over the same tree must be byte-identical"
    );
    assert!(
        first.matches("direct_edit_policy_violation").count() == 2,
        "and both edited files are reported: {first}"
    );
}

#[test]
fn t029_a_tightened_category_map_reports_a_historical_decision() {
    // The second condition, and the subtle one: a decision that was *legitimate* when
    // recorded, judged against a policy that has since changed. The record stays
    // accurate — the finding says so — and nothing is rewritten.
    let (_tmp, dir) = mapped_repo();
    tix()
        .current_dir(&dir)
        .args(["create", "--title", "Alpha", "--status", "triage"])
        .assert()
        .success();
    // Two moves, so the **last** recorded one is `wip -> review` — `active ->
    // active`, which is legal under the current map because a category may move to
    // itself.
    tix()
        .current_dir(&dir)
        .args(["move", "1", "wip"])
        .assert()
        .success();
    tix()
        .current_dir(&dir)
        .args(["move", "1", "review"])
        .assert()
        .success();
    // Now map `review` to `backlog`, so the recorded move re-evaluates as `active ->
    // backlog` — backwards, and refused.
    //
    // The first version of this fixture made a single `triage -> review` move and
    // then tightened `review` to `backlog`, which re-evaluates as `backlog ->
    // backlog` and is *legal*. The case was green for the wrong reason: it passed
    // because `lint_direct_edits` had a bug that evaluated the *reverse* of every
    // recorded move, not because the policy had tightened. Fixing the bug exposed
    // this, and the fixture had to be rebuilt so the tightened map is genuinely
    // invalid — which is why there are two moves rather than one.
    let config = fs::read_to_string(dir.join("tix.toml")).unwrap();
    fs::write(
        dir.join("tix.toml"),
        config.replace("review = \"active\"", "review = \"backlog\""),
    )
    .unwrap();

    let before = snapshot(&dir);
    let out = tix().current_dir(&dir).arg("lint").output().unwrap();
    let stderr = String::from_utf8_lossy(&out.stderr);
    assert!(
        stderr.contains("direct_edit_policy_violation")
            && stderr.contains("no longer permitted")
            // Both sides of the *recorded* move, not the reverse of it.
            && stderr.contains("`wip` -> `review`"),
        "the recorded decision is now against policy, and the finding says so: {stderr}"
    );
    assert_eq!(
        snapshot(&dir),
        before,
        "and the record is still the record: nothing is rewritten"
    );
}

#[test]
fn t029_a_load_fatal_configuration_is_refused_before_lint_runs() {
    // T029 step 2's three scenarios, pinned as what they actually are: the tool will
    // not start. `missing_completion_category` here; the other two are pinned by
    // WP04's and WP05's suites, which assert the same refusal.
    let tmp = TempDir::new().unwrap();
    let dir = tmp.path().to_path_buf();
    fs::create_dir_all(dir.join("docs").join("issues")).unwrap();
    fs::write(
        dir.join("tix.toml"),
        "issues_dir = \"docs/issues\"\n\n\
         [kanban.default]\n\
         columns = [\"a\", \"b\"]\n\
         done_column = \"b\"\n\n\
         [kanban.default.category_map]\n\
         a = \"backlog\"\n\
         b = \"active\"\n",
    )
    .unwrap();
    tix()
        .current_dir(&dir)
        .arg("lint")
        .assert()
        .failure()
        .stderr(predicate::str::contains("missing_completion_category"));
}