trusty-mpm 1.8.2

//! Mechanical verification that a filed issue satisfies the ticketing standard
//! (#7097).
//!
//! Why: #7067 made a milestone, a project, and native relationships mandatory
//! on every new issue, but the only thing enforcing that was the filing agent's
//! own self-check. An issue filed outside a `ticketing` dispatch — #7092 and
//! #7093 were the trigger — could carry or miss any of it with nothing
//! producing evidence either way. This module is the check that reads the
//! filed artifact back and says which requirements it actually meets.
//!
//! What: the [`IssueFacts`] wire shape `gh issue view --json` /
//! `gh issue list --json` return, [`audit_issue`] folding one issue's facts
//! against a [`ResolvedTicketing`] and a [`ComponentLabels`] set into an
//! [`IssueAudit`], and the two renderers ([`render_audit`] for one issue,
//! [`render_summary`] for a batch). Everything here is pure — the `gh` reads
//! live in [`crate::core::issue_audit_gh`] and the Cargo-manifest reads in
//! [`crate::core::component_labels`], so every verdict is unit-testable against
//! fixture JSON with no network and no filesystem.
//!
//! # What is and is not a failure
//!
//! A missing milestone or project is a FAIL only when the operator's
//! `agents.ticketing` block requires it; an unset requirement renders as INFO
//! so the report never invents a rule the config does not carry. A
//! `no-milestone: <reason>` comment is the standard's own escape hatch and
//! renders as SKIP with the reason quoted, never as a pass — a reader must be
//! able to tell "no milestone was needed, here is why" from "a milestone is
//! present". `no-component-label: <reason>` is the same hatch for the component
//! row (#7198): when no component unit owns the changed path — a Cargo crate
//! here, an npm workspace package or a Go module elsewhere; a `website/` or
//! CI-only issue is the shape — applying no component label is policy-correct.
//! Relationships are always INFO: a standalone issue legitimately has
//! no parent, no blocker, and no sub-issues, so their absence is a fact to
//! report and never a violation.
//!
//! Test: `issue_audit_tests.rs`.

use serde::Deserialize;

use crate::core::component_labels::ComponentLabels;
use crate::core::trusty_tools_config::ResolvedTicketing;

/// The `--json` field list both `gh issue view` and `gh issue list` are asked
/// for.
///
/// Why: the audit's two entry points must read the SAME facts, or a batch run
/// would silently evaluate fewer requirements than a single-issue run. Naming
/// the list once is what keeps them in agreement.
/// What: the seven fields the requirements read, plus the three relationship
/// fields. `gh` 2.98 serves `parent`, `blockedBy` and `subIssues` from both
/// verbs, so the audit needs no separate `gh api` call for them. `title` is
/// read by `tm pr open` for a phase issue's `[EPIC_N PHASE_M]` tag (#9571).
/// Test: `json_fields_cover_every_audited_requirement`.
pub const AUDIT_JSON_FIELDS: &str = "number,title,milestone,projectItems,labels,comments,state,\
     createdAt,parent,blockedBy,subIssues";

/// The comment prefix that excuses an unset milestone (#7067's escape hatch).
pub const NO_MILESTONE_PREFIX: &str = "no-milestone:";

/// The comment prefix that excuses an absent component label (#7198).
///
/// Why: when no component unit owns the changed path — the unit is a Cargo
/// crate here and an npm package or Go module in another stack; a `website/` or
/// CI-only issue is the shape — `tm-ticketing` policy is that applying no
/// component label is correct, so the audit needs the same recorded-waiver
/// escape hatch the milestone row already has.
/// Test: `a_missing_component_label_with_a_reason_comment_is_a_skip`.
pub const NO_COMPONENT_LABEL_PREFIX: &str = "no-component-label:";

/// The `gh` invocation that actually attaches an issue to a project (#7952).
///
/// Why: `gh issue edit <N> --add-project "<title>"` exits 0 and attaches
/// NOTHING when the title does not resolve inside the scope gh derives from the
/// repository — several projects share the title, or the project is owned by a
/// different login. The caller reads exit 0 as success, so the miss surfaces
/// only when this audit fails on the same issue afterwards. Naming the
/// owner-and-number form in the remediation is what stops the silent form from
/// being retried. `tm issue standard` prints each open project's number beside
/// its title, so the number never has to be guessed.
/// What: `gh project item-add <number> --owner <owner> --url <issue-url>` —
/// owner-scoped and keyed by number, so it names exactly one project.
/// Test: `a_missing_project_names_the_owner_scoped_attach`,
/// `issue_audit_warning_names_the_owner_scoped_attach`.
pub const PROJECT_ATTACH_HINT: &str =
    "gh project item-add <number> --owner <owner> --url <issue-url>";

/// A `{"title": …}` node — a milestone or a project item.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct TitleRef {
    /// The milestone or project title.
    #[serde(default)]
    pub title: String,
}

/// A `{"name": …}` node — a label.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct NameRef {
    /// The label name.
    #[serde(default)]
    pub name: String,
}

/// A `{"body": …}` node — an issue comment.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct CommentRef {
    /// The comment body.
    #[serde(default)]
    pub body: String,
}

/// A `{"number": …}` node — the `parent` link.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct NumberRef {
    /// The linked issue's number.
    #[serde(default)]
    pub number: u64,
}

/// A GraphQL connection (`blockedBy`, `subIssues`).
///
/// Why: gh renders these as `{"nodes":[…],"totalCount":N}`, and `totalCount`
/// can exceed the returned `nodes` page. Reporting the count rather than the
/// node list keeps the INFO line honest about a truncated page.
/// Test: `relationships_report_what_is_set` — which failed until the
/// `camelCase` rename landed here, since `rename_all` on [`IssueFacts`] does
/// not reach a nested type and `totalCount` silently parsed as 0.
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Connection {
    /// The nodes gh returned on this page.
    #[serde(default)]
    pub nodes: Vec<NumberRef>,
    /// The server-side total, which may exceed `nodes.len()`.
    #[serde(default)]
    pub total_count: u64,
}

/// One issue's audited facts, as `gh` returns them.
///
/// Why: the audit reads exactly what GitHub holds, so a fixture of this shape
/// is a faithful stand-in for a live issue and every verdict is testable
/// offline.
/// What: deserialized from a `gh issue view --json <AUDIT_JSON_FIELDS>` object,
/// or one element of the `gh issue list` array. Every field defaults, so a
/// caller that asks for fewer fields still parses.
/// Test: `facts_parse_a_live_view_payload`, `facts_parse_a_list_payload`.
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct IssueFacts {
    /// Issue number.
    #[serde(default)]
    pub number: u64,
    /// Issue title; `tm pr open` reads its phase tag (#9571).
    #[serde(default)]
    pub title: String,
    /// The single milestone, or `None` when unset.
    #[serde(default)]
    pub milestone: Option<TitleRef>,
    /// The GitHub Projects (v2) items the issue belongs to.
    #[serde(default)]
    pub project_items: Vec<TitleRef>,
    /// Every label on the issue.
    #[serde(default)]
    pub labels: Vec<NameRef>,
    /// Every comment body, searched for the `no-milestone:` escape hatch.
    #[serde(default)]
    pub comments: Vec<CommentRef>,
    /// `OPEN` / `CLOSED`.
    #[serde(default)]
    pub state: String,
    /// RFC-3339 creation timestamp, used by the `--since` window.
    #[serde(default)]
    pub created_at: String,
    /// The parent issue, when this is a sub-issue.
    #[serde(default)]
    pub parent: Option<NumberRef>,
    /// Issues this one is blocked by.
    #[serde(default)]
    pub blocked_by: Connection,
    /// Issues nested under this one.
    #[serde(default)]
    pub sub_issues: Connection,
}

/// One requirement's verdict.
///
/// Why: PASS/FAIL alone cannot express the two states the standard actually
/// has beyond them — a requirement waived on the record, and a fact reported
/// without a rule attached. Collapsing either into PASS is what would let a
/// waived milestone read as a set one.
/// What: `Pass`, `Fail` (the only verdict that exits 1), `Skip` (satisfied by
/// the recorded escape hatch), `Info` (reported, never gating).
/// Test: `an_unset_milestone_with_a_reason_comment_is_a_skip`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Verdict {
    /// The requirement is met.
    Pass,
    /// The requirement is violated — the audit exits 1.
    Fail,
    /// Waived by a recorded reason.
    Skip,
    /// Reported for the reader; never gating.
    Info,
}

impl Verdict {
    /// The four-or-fewer-character tag printed in a report line.
    #[must_use]
    pub fn tag(self) -> &'static str {
        match self {
            Self::Pass => "PASS",
            Self::Fail => "FAIL",
            Self::Skip => "SKIP",
            Self::Info => "INFO",
        }
    }
}

/// One audited requirement.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct AuditRow {
    /// The requirement's stable name (`project`, `milestone`, …).
    pub requirement: &'static str,
    /// Its verdict.
    pub verdict: Verdict,
    /// The evidence behind the verdict — the value found, or why it is absent.
    pub detail: String,
}

impl AuditRow {
    /// Build a row.
    ///
    /// Why: the type is `#[non_exhaustive]`, so a caller outside this crate —
    /// the `tm issue audit` epic rows (#8448) — cannot use a struct literal.
    /// Test: `audit_rows_pass_a_tracker_whose_block_matches`.
    #[must_use]
    pub fn new(requirement: &'static str, verdict: Verdict, detail: impl Into<String>) -> Self {
        Self {
            requirement,
            verdict,
            detail: detail.into(),
        }
    }
}

/// One issue's complete audit.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct IssueAudit {
    /// The audited issue's number.
    pub number: u64,
    /// One row per requirement, in report order.
    pub rows: Vec<AuditRow>,
}

impl IssueAudit {
    /// Whether any requirement FAILED.
    ///
    /// Why: this is the exit-code decision, and it must read only [`Verdict::Fail`]
    /// — a SKIP is a satisfied requirement and an INFO was never a requirement.
    /// Test: `a_skip_does_not_fail_the_audit`, `a_missing_project_fails`.
    #[must_use]
    pub fn failed(&self) -> bool {
        self.rows.iter().any(|r| r.verdict == Verdict::Fail)
    }

    /// The names of the failing requirements, for a one-line summary.
    /// Test: `a_missing_project_fails`.
    #[must_use]
    pub fn failing_requirements(&self) -> Vec<&'static str> {
        self.rows
            .iter()
            .filter(|r| r.verdict == Verdict::Fail)
            .map(|r| r.requirement)
            .collect()
    }
}

/// Requirement names, in the order [`audit_issue`] emits them.
const REQ_PROJECT: &str = "project";
const REQ_MILESTONE: &str = "milestone";
const REQ_COMPONENT: &str = "component label";
const REQ_RELATIONSHIPS: &str = "relationships";

/// The requirement columns a batch summary table carries.
pub const SUMMARY_REQUIREMENTS: &[&str] = &[REQ_PROJECT, REQ_MILESTONE, REQ_COMPONENT];

/// Audit one issue's facts against the resolved ticketing standard.
///
/// Why: the whole point of #7097 — the standard was enforced only by the filing
/// agent's self-report, so this reads the artifact back and states, per
/// requirement, what it found. Taking [`ResolvedTicketing`] rather than
/// hardcoded booleans is what keeps the audit and `tm issue standard` reporting
/// the same rules.
/// What: four rows in a fixed order. `project` and `milestone` are PASS/FAIL
/// only when `project_required` / `milestone_required` are set and INFO
/// otherwise; an unset milestone with a `no-milestone: <reason>` comment is
/// SKIP with the reason quoted. `component label` requires at least one label
/// from `components` — the accepted set [`ComponentLabels`] derives, which is
/// the seed table plus the repository's own crate labels (#7123). The
/// `ws/<session>` workstream label is never in it, since a workstream is not a
/// component. `relationships` is always INFO.
/// Test: `a_compliant_issue_passes_every_requirement`, `a_missing_project_fails`,
/// `an_unset_milestone_with_a_reason_comment_is_a_skip`,
/// `an_unset_milestone_without_a_comment_fails`,
/// `an_unrequired_milestone_is_informational`,
/// `a_missing_component_label_fails`,
/// `a_non_mpm_crate_component_label_passes`,
/// `relationships_are_never_a_failure`.
#[must_use]
pub fn audit_issue(
    facts: &IssueFacts,
    ticketing: &ResolvedTicketing,
    components: &ComponentLabels,
) -> IssueAudit {
    let rows = vec![
        project_row(facts, ticketing),
        milestone_row(facts, ticketing),
        component_row(facts, components),
        relationships_row(facts),
    ];
    IssueAudit {
        number: facts.number,
        rows,
    }
}

/// The `project` row.
fn project_row(facts: &IssueFacts, ticketing: &ResolvedTicketing) -> AuditRow {
    let titles: Vec<&str> = facts
        .project_items
        .iter()
        .map(|p| p.title.as_str())
        .filter(|t| !t.is_empty())
        .collect();
    let (verdict, detail) = if titles.is_empty() {
        // #7097: an unset requirement reports the absence rather than inventing
        // a rule the operator's config does not carry.
        if ticketing.project_required {
            // #7952: the remediation names the owner-scoped attach, never
            // `gh issue edit --add-project`, which exits 0 without attaching.
            (
                Verdict::Fail,
                format!("no project — `{PROJECT_ATTACH_HINT}` (numbers: `tm issue standard`)"),
            )
        } else {
            (
                Verdict::Info,
                "no project (project_required: false)".to_string(),
            )
        }
    } else {
        (Verdict::Pass, titles.join(", "))
    };
    AuditRow {
        requirement: REQ_PROJECT,
        verdict,
        detail,
    }
}

/// The `milestone` row, including the `no-milestone:` escape hatch.
fn milestone_row(facts: &IssueFacts, ticketing: &ResolvedTicketing) -> AuditRow {
    let title = facts
        .milestone
        .as_ref()
        .map(|m| m.title.as_str())
        .filter(|t| !t.is_empty());
    let (verdict, detail) = match title {
        Some(title) => (Verdict::Pass, title.to_string()),
        None => match no_milestone_reason(&facts.comments) {
            // #7097: SKIP, never PASS — a reader must be able to tell a waived
            // milestone from a set one.
            Some(reason) => (Verdict::Skip, format!("({reason})")),
            None if ticketing.milestone_required => (
                Verdict::Fail,
                "no milestone and no `no-milestone: <reason>` comment".to_string(),
            ),
            None => (
                Verdict::Info,
                "no milestone (milestone_required: false)".to_string(),
            ),
        },
    };
    AuditRow {
        requirement: REQ_MILESTONE,
        verdict,
        detail,
    }
}

/// The reason from the first `no-milestone: <reason>` comment, if any.
///
/// Test: `an_unset_milestone_with_a_reason_comment_is_a_skip`,
/// `the_no_milestone_comment_is_matched_case_insensitively`,
/// `a_no_milestone_note_inside_a_longer_comment_counts`.
fn no_milestone_reason(comments: &[CommentRef]) -> Option<String> {
    waiver_reason(comments, NO_MILESTONE_PREFIX)
}

/// The reason from the first `no-component-label: <reason>` comment, if any.
///
/// Test: `a_missing_component_label_with_a_reason_comment_is_a_skip`,
/// `the_no_component_label_comment_is_matched_case_insensitively`.
// #7198: mirrors `no_milestone_reason` over the component-label prefix.
fn no_component_label_reason(comments: &[CommentRef]) -> Option<String> {
    waiver_reason(comments, NO_COMPONENT_LABEL_PREFIX)
}

/// The reason from the first `<prefix> <reason>` comment line, if any.
///
/// Why: the standard's escape hatches are comments, so the audit has to read
/// comment bodies rather than infer intent from an absent field. #7198 added a
/// second prefix, and one matcher is what keeps the two hatches behaving
/// identically.
/// What: matches `prefix` case-insensitively at the start of any LINE of any
/// comment (an agent posting the note inside a longer comment still counts),
/// and returns the trimmed remainder. An empty remainder still counts as
/// recorded — the standard asks for a reason, and reporting an empty one is
/// more useful than silently treating the comment as absent.
/// Test: `a_no_milestone_note_inside_a_longer_comment_counts`,
/// `the_no_component_label_comment_is_matched_case_insensitively`.
fn waiver_reason(comments: &[CommentRef], prefix: &str) -> Option<String> {
    comments.iter().find_map(|c| {
        c.body.lines().find_map(|line| {
            let line = line.trim();
            let head = line.get(..prefix.len())?;
            head.eq_ignore_ascii_case(prefix)
                .then(|| line[prefix.len()..].trim().to_string())
        })
    })
}

/// The `component label` row.
///
/// Why: #7123 — this row used to build its own accepted set from the labels the
/// harness SEEDS, which on this workspace is `trusty-mpm` alone, so an issue
/// correctly labelled with the crate that owns it failed. The accepted set is
/// now [`ComponentLabels`]'s, and the FAIL line names every label in it so the
/// fix is a label the reader can copy rather than a guess.
/// A `no-component-label: <reason>` comment renders SKIP with the reason
/// quoted, never PASS — the website/CI shape where no crate owns the changed
/// path is policy-correct, and a reader must still be able to tell a waived
/// row from a labelled one (#7198).
/// Test: `a_missing_component_label_fails`,
/// `a_non_mpm_crate_component_label_passes`,
/// `trusty_audit_alone_passes_the_component_label_check`,
/// `a_missing_component_label_with_a_reason_comment_is_a_skip`,
/// `a_present_component_label_wins_over_a_waiver_comment`.
fn component_row(facts: &IssueFacts, components: &ComponentLabels) -> AuditRow {
    let present: Vec<&str> = facts
        .labels
        .iter()
        .map(|l| l.name.as_str())
        .filter(|name| components.accepts(name))
        .collect();
    let (verdict, detail) = if present.is_empty() {
        // #7198: a recorded waiver downgrades the miss to SKIP, mirroring
        // `milestone`'s `no-milestone:` hatch.
        if let Some(reason) = no_component_label_reason(&facts.comments) {
            return AuditRow {
                requirement: REQ_COMPONENT,
                verdict: Verdict::Skip,
                detail: format!("({reason})"),
            };
        }
        (
            Verdict::Fail,
            format!(
                "none of [{}] present and no `no-component-label: <reason>` \
                 comment (labels: {})",
                components.names().join(", "),
                if facts.labels.is_empty() {
                    "none".to_string()
                } else {
                    facts
                        .labels
                        .iter()
                        .map(|l| l.name.as_str())
                        .collect::<Vec<_>>()
                        .join(", ")
                }
            ),
        )
    } else {
        (Verdict::Pass, present.join(", "))
    };
    AuditRow {
        requirement: REQ_COMPONENT,
        verdict,
        detail,
    }
}

/// The `relationships` row — always INFO.
///
/// Why: a standalone issue legitimately has no parent, no blocker and no
/// sub-issues, so their absence is a fact to report, never a violation.
/// Test: `relationships_are_never_a_failure`, `relationships_report_what_is_set`.
fn relationships_row(facts: &IssueFacts) -> AuditRow {
    let mut parts = Vec::with_capacity(3);
    match &facts.parent {
        Some(p) if p.number != 0 => parts.push(format!("parent #{}", p.number)),
        _ => parts.push("no parent".to_string()),
    }
    parts.push(format!("blocked-by {}", facts.blocked_by.total_count));
    parts.push(format!("sub-issues {}", facts.sub_issues.total_count));
    AuditRow {
        requirement: REQ_RELATIONSHIPS,
        verdict: Verdict::Info,
        detail: parts.join("; "),
    }
}

/// Whether an issue was created on or after `date` (`YYYY-MM-DD`).
///
/// Why: `--since` asks gh for `created:>=<date>`, and gh's search index can lag
/// or over-return. Re-checking the timestamp gh itself returned keeps the
/// reported window equal to the requested one rather than to whatever the
/// search served.
/// What: an RFC-3339 `createdAt` sorts lexicographically, so a prefix
/// comparison against the `YYYY-MM-DD` date is the whole test. An issue with no
/// `createdAt` (a caller that asked for fewer fields) is KEPT — dropping it
/// would silently shrink the audited set.
/// Test: `the_since_window_keeps_the_boundary_day`,
/// `the_since_window_keeps_an_issue_with_no_timestamp`.
#[must_use]
pub fn created_on_or_after(facts: &IssueFacts, date: &str) -> bool {
    facts.created_at.is_empty() || facts.created_at.as_str() >= date
}

/// Render one issue's audit as the per-requirement report.
///
/// Why: one line per requirement is the whole deliverable — a reader must see
/// which rule was checked, what was found, and the verdict, without reading the
/// config.
/// What: a `#<number>` header then one aligned `  <requirement>  <TAG>  <detail>`
/// line per row.
/// Test: `render_audit_prints_one_line_per_requirement`.
#[must_use]
pub fn render_audit(audit: &IssueAudit) -> String {
    let width = audit
        .rows
        .iter()
        .map(|r| r.requirement.len())
        .max()
        .unwrap_or(0);
    let mut out = format!("#{}\n", audit.number);
    for row in &audit.rows {
        out.push_str(&format!(
            "  {:width$}  {}  {}\n",
            row.requirement,
            row.verdict.tag(),
            row.detail,
        ));
    }
    out
}

/// Render a batch of audits as a summary table.
///
/// Why: `--recent`/`--since` audits many issues, and a full per-requirement
/// block for each buries the failures. The table is one row per issue with one
/// column per gating requirement, then a count.
/// What: a header row, one row per audit carrying each
/// [`SUMMARY_REQUIREMENTS`] verdict tag and the overall verdict, then the
/// audited/failing counts. Relationships are omitted — they never gate.
/// Test: `render_summary_tabulates_every_issue`,
/// `render_summary_counts_only_failures`.
#[must_use]
pub fn render_summary(audits: &[IssueAudit]) -> String {
    let mut out = String::from("issue     project   milestone  component  verdict\n");
    for audit in audits {
        let tag = |req: &str| {
            audit
                .rows
                .iter()
                .find(|r| r.requirement == req)
                .map_or("-", |r| r.verdict.tag())
        };
        out.push_str(&format!(
            "{:<9} {:<9} {:<10} {:<10} {}\n",
            format!("#{}", audit.number),
            tag(REQ_PROJECT),
            tag(REQ_MILESTONE),
            tag(REQ_COMPONENT),
            if audit.failed() { "FAIL" } else { "PASS" },
        ));
    }
    let failing = audits.iter().filter(|a| a.failed()).count();
    out.push_str(&format!(
        "\n{} issue(s) audited, {failing} with a FAIL\n",
        audits.len()
    ));
    out
}

#[cfg(test)]
#[path = "issue_audit_tests.rs"]
mod tests;