aede_core/

doctor.rs

//! Library diagnosis.
//!
//! A real library is always damaged: missing tags, duplicates, incomplete
//! albums, mixed editions. This module brings them to light without changing
//! anything — automatic correction will come later, and will have to be
//! reversible.

use std::collections::{BTreeMap, BTreeSet};

use crate::model::{self, Catalog, Id};
use crate::text;

/// How much a problem hurts, from the most serious to the least.
///
/// The declaration order is the order of the report: the derived comparison puts `Error` before
/// `Warning` before `Info`, and [`diagnose`] sorts on it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum Severity {
    /// Prevents the rest from working (no title, no duration).
    Error,
    /// Degrades browsing or ranking.
    Warning,
    /// Plain completeness remark.
    Info,
}

impl Severity {
    /// Short lowercase name of the level, meant to prefix a report line or to filter on.
    pub fn label(self) -> &'static str {
        match self {
            Severity::Error => "error",
            Severity::Warning => "warning",
            Severity::Info => "info",
        }
    }
}

/// Nature of a problem found in the library, independent of the file it was found on.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum IssueKind {
    /// No title in the tags: the one on display was inferred from the file name.
    MissingTitle,
    /// No artist in the tags, so the track hangs off no discography.
    MissingArtist,
    /// No album in the tags: the track will stay on its own, outside any release.
    MissingAlbum,
    /// No usable year, which leaves the track out of any chronological ordering.
    MissingDate,
    /// No track number, so playback order within the album cannot be guaranteed.
    MissingTrackNumber,
    /// Duration could not be read, which usually points at a truncated or corrupted file.
    MissingDuration,
    /// Same artist and title heard again at a near-identical duration: the copies waste space.
    DuplicateTrack,
    /// The same audio, proved by fingerprint rather than guessed from tags.
    ///
    /// Stronger than [`IssueKind::DuplicateTrack`] and it catches what that
    /// cannot: two files whose tags say quite different things, or nothing at
    /// all, and whose sound is the same recording. A tag-based guess has to
    /// call itself "likely"; this one does not.
    SameAudio,
    /// A whole album is present twice, in the same quality: one of the two copies is dead weight.
    DuplicateAlbum,
    /// The same album is kept in two encodings. Not a defect — worth knowing.
    OtherEdition,
    /// A decoder found the audio no longer matches the MD5 the file carries.
    Md5Mismatch,
    /// Tracks missing from a disc, the sign of a rip left unfinished — whether
    /// they are gaps in the numbering or a tail short of the announced total.
    IncompleteAlbum,
    /// One release mixes codecs or sample rates, which usually means it was assembled from
    /// different sources.
    MixedQuality,
    /// The release carries no cover art, neither embedded nor beside the files.
    MissingCover,
    /// The announced year falls outside the plausible range for a recording.
    SuspiciousYear,
    /// A checksum carried by the file does not match its contents: the audio
    /// has been damaged since it was written.
    DamagedAudio,
    /// Two artist rows that look like one musician written two ways.
    ///
    /// **Suggested, never applied**, and that is the whole design. A shared
    /// `MUSICBRAINZ_ARTISTID` merges two spellings with no heuristic at all;
    /// this is the other half of the problem — files that never met
    /// MusicBrainz — where nobody outside the owner of the disk can know the
    /// answer. Matching on a fragment of a name merges Angus Young with Neil
    /// Young, so what this does is put a pair in front of somebody who can
    /// tell, and name the command that acts on it.
    SameArtistMaybe,
    /// A source and the tags say different things about the same release.
    ///
    /// Reported, never resolved. Which of the two is right is not something
    /// this program can know — a tag may be wrong, and so may MusicBrainz —
    /// and the whole reason a fetched value is kept beside the tag rather than
    /// on top of it is that the disagreement stays visible and the user
    /// decides.
    SourceDisagrees,
    /// Two trusted external sources contradict one another.
    SourcesDisagree,
    /// An approximate attachment has not been accepted or rejected yet.
    SourceNeedsReview,
    /// An exact MusicBrainz identity contradicts the identifier in local tags.
    SourceIdentityConflict,
    /// A trusted recording identity exists, but its relationship pass has not
    /// completed, so credits and works may be missing.
    IncompleteSourceCredits,
    /// A personal note points to a relationship no longer in the current graph.
    OrphanedRelationAnnotation,
}

impl IssueKind {
    /// Weight given to this kind of problem, which fixes its rank in the report.
    pub fn severity(self) -> Severity {
        match self {
            IssueKind::MissingTitle
            | IssueKind::MissingArtist
            | IssueKind::MissingDuration
            | IssueKind::DamagedAudio
            | IssueKind::Md5Mismatch => Severity::Error,
            IssueKind::MissingAlbum
            | IssueKind::DuplicateTrack
            | IssueKind::SameAudio
            | IssueKind::DuplicateAlbum
            | IssueKind::IncompleteAlbum
            | IssueKind::MixedQuality
            | IssueKind::SuspiciousYear => Severity::Warning,
            IssueKind::MissingDate
            | IssueKind::MissingTrackNumber
            | IssueKind::MissingCover
            | IssueKind::SourceDisagrees
            | IssueKind::SourcesDisagree
            | IssueKind::SourceNeedsReview
            | IssueKind::SourceIdentityConflict
            | IssueKind::IncompleteSourceCredits
            | IssueKind::OrphanedRelationAnnotation
            | IssueKind::SameArtistMaybe
            | IssueKind::OtherEdition => Severity::Info,
        }
    }

    /// Wording of the problem in one short phrase, ready to head a report line.
    pub fn label(self) -> &'static str {
        match self {
            IssueKind::SourceDisagrees => "source disagrees",
            IssueKind::SourcesDisagree => "sources disagree",
            IssueKind::SourceNeedsReview => "source claim needs review",
            IssueKind::SourceIdentityConflict => "source identity conflict",
            IssueKind::IncompleteSourceCredits => "source credits incomplete",
            IssueKind::OrphanedRelationAnnotation => "relation annotation is waiting",
            // "possibly", and the word is doing work: nothing here is a
            // finding, and a line reading "the same artist" would be a claim
            // this program has no way to make.
            IssueKind::SameArtistMaybe => "possibly one artist",
            IssueKind::MissingTitle => "missing title",
            IssueKind::MissingArtist => "missing artist",
            IssueKind::MissingAlbum => "missing album",
            IssueKind::MissingDate => "missing year",
            IssueKind::MissingTrackNumber => "missing track number",
            IssueKind::MissingDuration => "unreadable duration",
            IssueKind::DuplicateTrack => "likely duplicate",
            // Not "likely": the audio is the same audio. The word is what
            // separates this from the guess above it, and a reader deciding
            // whether to delete a file needs to know which of the two they
            // are looking at.
            IssueKind::SameAudio => "the same audio",
            IssueKind::DuplicateAlbum => "album present twice",
            IssueKind::OtherEdition => "album kept in two encodings",
            IssueKind::Md5Mismatch => "audio does not match its MD5",
            IssueKind::IncompleteAlbum => "incomplete album",
            IssueKind::MixedQuality => "mixed quality within an album",
            IssueKind::MissingCover => "missing cover art",
            IssueKind::SuspiciousYear => "implausible year",
            IssueKind::DamagedAudio => "damaged audio",
        }
    }
}

/// How many parts the file says the whole holds, if it says so at all.
///
/// One helper for two questions — how many tracks on this disc, how many discs
/// in this set — because they are the same question asked of two vocabularies,
/// and both are read the same way: a dedicated total field, or the trailing
/// half of a `9/12` written into the number itself, which many taggers do.
/// `field` names the total, `numbered` the field that may carry the pair.
///
/// Only the leading digits of a value are kept, and a value that does not parse
/// is no answer rather than a wrong one. The names given here are the canonical
/// ones: `tags::canonical_key` has already folded `totaltracks`, `disctotal`
/// and the rest into a single spelling, so this must not keep a second list of
/// aliases that would then have to be maintained beside it.
fn announced(file: &crate::model::AudioFile, field: &str, numbered: &str) -> Option<u32> {
    let leading = |value: &str| {
        let digits: String = value
            .trim()
            .chars()
            .take_while(|c| c.is_ascii_digit())
            .collect();
        digits.parse::<u32>().ok()
    };
    let from_pair = file
        .first_tag(numbered)
        .and_then(|value| value.split_once('/').map(|(_, total)| total.to_string()))
        .and_then(|total| leading(&total));
    let from_field = file.first_tag(field).and_then(leading);
    from_pair.into_iter().chain(from_field).max()
}

/// How many tracks the file says its disc holds, if it says so at all.
fn announced_total(file: &crate::model::AudioFile) -> Option<u32> {
    announced(file, "tracktotal", "tracknumber")
}

/// How many discs the file says its set holds, if it says so at all.
fn announced_discs(file: &crate::model::AudioFile) -> Option<u32> {
    announced(file, "disctotal", "discnumber")
}

/// One observation made on the library, tied to the files that carry it.
#[derive(Debug, Clone)]
pub struct Issue {
    /// What was observed, which also decides how serious the observation is.
    pub kind: IssueKind,
    /// Plain description, ready to be displayed.
    pub detail: String,
    /// Files concerned (a single one, or several for duplicates).
    pub files: Vec<String>,
}

impl Issue {
    /// Weight of the observation, taken from its kind: no problem carries a level of its own.
    pub fn severity(&self) -> Severity {
        self.kind.severity()
    }
}

/// Full analysis. The result is sorted by severity then by kind, for a display
/// that is stable from one run to the next.
pub fn diagnose(catalog: &Catalog, sources: &crate::sources::Sources) -> Vec<Issue> {
    let mut issues = Vec::new();
    check_tracks(catalog, &mut issues);
    check_integrity(catalog, &mut issues);
    check_imported_analyses(catalog, &mut issues);
    check_source_quality(catalog, sources, &mut issues);
    check_sources(catalog, sources, &mut issues);
    check_duplicate_albums(catalog, &mut issues);
    check_other_editions(catalog, &mut issues);
    check_duplicates(catalog, &mut issues);
    check_same_audio(catalog, &mut issues);
    check_releases(catalog, &mut issues);
    check_same_person(catalog, &mut issues);

    issues.sort_by(|a, b| {
        a.severity()
            .cmp(&b.severity())
            .then_with(|| a.kind.cmp(&b.kind))
            .then_with(|| a.files.cmp(&b.files))
    });
    issues
}

/// Personal relationship annotations whose edge is absent from the current graph.
///
/// They are kept rather than deleted: a disconnected drive, a rejected source
/// claim, or a later rescan can make the relationship visible again.
/// Account-specific callers must first scope the supplied relationship
/// annotations to their owner; this generic helper does not select one.
pub fn orphaned_relation_annotations(
    catalog: &Catalog,
    sources: &crate::sources::Sources,
    user: &crate::user::UserData,
) -> Vec<Issue> {
    let current = crate::graph::edges(catalog, sources)
        .into_iter()
        .map(|edge| edge.reference)
        .collect::<BTreeSet<_>>();
    user.relation_annotations
        .iter()
        .filter(|annotation| {
            !current.contains(&annotation.relation)
                && (!annotation.relation.kind.starts_with("credit:")
                    || !current.iter().any(|relation| {
                        crate::user::same_annotation_relation(catalog, &annotation.relation, relation)
                    }))
        })
        .map(|annotation| Issue {
            kind: IssueKind::OrphanedRelationAnnotation,
            detail: format!(
                "{} → {} → {} is not in the current graph; it is kept — aede relation {} --remove drops your annotation",
                annotation.relation.source.to_token(),
                annotation.relation.kind,
                annotation.relation.target.to_token(),
                annotation.relation.id()
            ),
            files: Vec::new(),
        })
        .collect()
}

/// Number of problems per severity.
pub fn summary(issues: &[Issue]) -> BTreeMap<Severity, usize> {
    let mut out = BTreeMap::new();
    for issue in issues {
        *out.entry(issue.severity()).or_insert(0) += 1;
    }
    out
}

fn check_tracks(catalog: &Catalog, issues: &mut Vec<Issue>) {
    for track in &catalog.tracks {
        let Some(file) = catalog.file(track.file_id) else {
            continue;
        };
        let path = file.path.clone();

        if file.first_tag("title").is_none() {
            issues.push(Issue {
                kind: IssueKind::MissingTitle,
                detail: format!("title inferred from the file name: \"{}\"", track.title),
                files: vec![path.clone()],
            });
        }
        if file
            .first_tag("artists")
            .or_else(|| file.first_tag("artist"))
            .is_none()
        {
            issues.push(Issue {
                kind: IssueKind::MissingArtist,
                detail: "no artist in the tags".into(),
                files: vec![path.clone()],
            });
        }
        if file.first_tag("album").is_none() {
            issues.push(Issue {
                kind: IssueKind::MissingAlbum,
                detail: "track cannot be attached to an album".into(),
                files: vec![path.clone()],
            });
        }
        if track.duration_ms.is_none() || track.duration_ms == Some(0) {
            issues.push(Issue {
                kind: IssueKind::MissingDuration,
                detail: "duration not determined: file possibly corrupted".into(),
                files: vec![path.clone()],
            });
        }
        if track.track_no.is_none() {
            issues.push(Issue {
                kind: IssueKind::MissingTrackNumber,
                detail: "playback order not guaranteed within the album".into(),
                files: vec![path.clone()],
            });
        }

        let year = file
            .first_tag("originaldate")
            .or_else(|| file.first_tag("date"))
            .and_then(text::extract_year);
        match year {
            None => issues.push(Issue {
                kind: IssueKind::MissingDate,
                detail: "no usable year".into(),
                files: vec![path],
            }),
            Some(year) if !(1860..=2100).contains(&year) => issues.push(Issue {
                kind: IssueKind::SuspiciousYear,
                detail: format!("year announced: {year}"),
                files: vec![path],
            }),
            Some(_) => {}
        }
    }
}

/// Reports the files whose stored checksums did not match.
///
/// Only what `aede check` has already established: this never reads a file, so
/// `doctor` stays instant. Files with no verdict are silently passed over here
/// and counted by the command itself, which can say how to obtain one.
fn check_integrity(catalog: &Catalog, issues: &mut Vec<Issue>) {
    for file in &catalog.files {
        if let Some(record) = &file.integrity
            && let crate::audit::integrity::Verdict::Damaged { detail } = &record.verdict
        {
            issues.push(Issue {
                kind: IssueKind::DamagedAudio,
                detail: format!("{detail} — restore from a backup or rip again"),
                files: vec![file.path.clone()],
            });
        }
    }
}

/// Reports what an imported analysis found and Aède cannot see.
///
/// An MD5 mismatch is an **error**, even when Aède's own check said the file
/// was intact: the two look at different things. The frame checksums prove the
/// container was not corrupted; the MD5 proves the decoded audio is the audio
/// that was encoded. A file can pass the first and fail the second — a stream
/// re-encoded by a non-conforming tool — and that case is exactly what Aède
/// cannot see before it decodes anything itself.
/// Where a source and the tags say different things about one release.
///
/// Only releases for now, and on purpose: an artist's country has no tag to
/// disagree with, so a fetched artist fact is an addition rather than a second
/// opinion. A release is where the two actually meet — Picard writes
/// `RELEASETYPE`, `DATE` and `LABEL` — and it is therefore the only place this
/// report has anything to say.
///
/// A record the catalog cannot place is skipped rather than reported, exactly
/// as a waiting analysis is: it is not a defect that MusicBrainz holds
/// something about an album nobody has scanned yet.
fn check_source_quality(
    catalog: &Catalog,
    sources: &crate::sources::Sources,
    issues: &mut Vec<Issue>,
) {
    use crate::sources::{Facts, ReviewReason};

    for item in sources
        .review_items(catalog)
        .into_iter()
        .filter(|item| item.decision.is_none())
    {
        let (kind, detail) = match item.reason {
            ReviewReason::Approximate { score } => (
                IssueKind::SourceNeedsReview,
                format!(
                    "{} {}: {} proposed {} at {score}% — aede review --accept={} or --reject={}",
                    item.entity.kind.as_str(),
                    item.entity.key,
                    item.source,
                    item.source_id
                        .as_deref()
                        .unwrap_or("an unidentified candidate"),
                    item.id,
                    item.id
                ),
            ),
            ReviewReason::IdentityConflict {
                local_id,
                sourced_id,
            } => (
                IssueKind::SourceIdentityConflict,
                format!(
                    "{} {}: local identity {local_id}, {} says {sourced_id} — \
                     aede review --accept={} or --reject={}",
                    item.entity.kind.as_str(),
                    item.entity.key,
                    item.source,
                    item.id,
                    item.id
                ),
            ),
            ReviewReason::PriorDecision => continue,
        };
        issues.push(Issue {
            kind,
            files: files_for_entity(catalog, &item.entity),
            detail,
        });
    }

    // A trusted recording may still carry only identification facts. That is
    // not an ambiguous identity any more, but it does mean the graph cannot
    // claim its credits are complete. Another placement can already carry a
    // trusted completed answer for this same canonical recording.
    let complete_recordings: BTreeSet<_> = crate::credit_coverage::recordings(catalog, sources)
        .into_iter()
        .filter(|coverage| {
            matches!(
                coverage.status,
                crate::credit_coverage::CreditStatus::Empty
                    | crate::credit_coverage::CreditStatus::Credited
            )
        })
        .map(|coverage| coverage.recording_id)
        .collect();
    let mut reported_recordings = BTreeSet::new();
    let mut incomplete_files = Vec::new();
    for record in &sources.records {
        let Facts::Track(facts) = &record.facts else {
            continue;
        };
        if !sources.is_trusted(catalog, record)
            || facts.recording.is_none()
            || facts.relationships_complete
        {
            continue;
        }
        let entity = record.entity();
        let Some(track_id) = entity.resolve(catalog) else {
            continue;
        };
        let Some(recording_id) = catalog.track(track_id).map(|track| track.recording_id) else {
            continue;
        };
        if complete_recordings.contains(&recording_id) || !reported_recordings.insert(recording_id)
        {
            continue;
        }
        incomplete_files.extend(files_for_entity(catalog, &entity));
    }
    if !reported_recordings.is_empty() {
        issues.push(Issue {
            kind: IssueKind::IncompleteSourceCredits,
            detail: format!(
                "{} identified without a complete relationship pass — run aede fetch --credits",
                match reported_recordings.len() {
                    1 => "1 recording is".to_string(),
                    count => format!("{count} recordings are"),
                }
            ),
            files: incomplete_files,
        });
    }

    check_source_disagreements(catalog, sources, issues);
}

fn files_for_entity(catalog: &Catalog, entity: &crate::user::EntityRef) -> Vec<String> {
    let Some(id) = entity.resolve(catalog) else {
        return Vec::new();
    };
    let track_ids: Vec<Id> = match entity.kind {
        model::EntityKind::Track => vec![id],
        model::EntityKind::Release => catalog
            .release(id)
            .map(|release| release.track_ids.clone())
            .unwrap_or_default(),
        model::EntityKind::Artist => catalog.tracks_of_artist(id),
        model::EntityKind::Label => catalog.tracks_of_label(id),
        _ => Vec::new(),
    };
    track_ids
        .into_iter()
        .filter_map(|track| catalog.track(track))
        .filter_map(|track| catalog.file(track.file_id))
        .map(|file| file.path.clone())
        .take(1)
        .collect()
}

fn check_source_disagreements(
    catalog: &Catalog,
    sources: &crate::sources::Sources,
    issues: &mut Vec<Issue>,
) {
    use crate::sources::Facts;

    let mut by_entity: BTreeMap<(model::EntityKind, String), Vec<&crate::sources::SourceRecord>> =
        BTreeMap::new();
    for record in &sources.records {
        if sources.is_trusted(catalog, record) {
            by_entity
                .entry((record.facts.kind(), record.key.clone()))
                .or_default()
                .push(record);
        }
    }
    for ((kind, key), records) in by_entity {
        if records.len() < 2 {
            continue;
        }
        let entity = crate::user::EntityRef {
            kind,
            key: key.clone(),
        };
        for left_index in 0..records.len() {
            for right in records.iter().skip(left_index + 1) {
                let left = records[left_index];
                for (field, a, b) in conflicting_fields(&left.facts, &right.facts) {
                    issues.push(Issue {
                        kind: IssueKind::SourcesDisagree,
                        detail: format!(
                            "{} {key}: {} says {field} is \"{a}\", {} says \"{b}\"",
                            kind.as_str(),
                            left.source,
                            right.source
                        ),
                        files: files_for_entity(catalog, &entity),
                    });
                }
            }
        }
    }

    fn conflicting_fields(left: &Facts, right: &Facts) -> Vec<(&'static str, String, String)> {
        let mut out = Vec::new();
        let compare = |out: &mut Vec<(&'static str, String, String)>,
                       field: &'static str,
                       a: Option<&str>,
                       b: Option<&str>| {
            let (Some(a), Some(b)) = (a, b) else {
                return;
            };
            if !a.trim().is_empty()
                && !b.trim().is_empty()
                && crate::text::normalize(a) != crate::text::normalize(b)
            {
                out.push((field, a.to_string(), b.to_string()));
            }
        };
        match (left, right) {
            (Facts::Artist(a), Facts::Artist(b)) => {
                compare(&mut out, "type", a.kind.as_deref(), b.kind.as_deref());
                compare(&mut out, "area", a.area.as_deref(), b.area.as_deref());
                compare(
                    &mut out,
                    "begin date",
                    a.began.as_deref(),
                    b.began.as_deref(),
                );
                compare(&mut out, "end date", a.ended.as_deref(), b.ended.as_deref());
            }
            (Facts::Release(a), Facts::Release(b)) => {
                compare(
                    &mut out,
                    "release type",
                    a.primary_type.as_deref(),
                    b.primary_type.as_deref(),
                );
                if let (Some(a), Some(b)) = (&a.first_released, &b.first_released)
                    && matches!(
                        crate::sources::verdict_date(a, Some(b)),
                        crate::sources::Verdict::Differs { .. }
                    )
                {
                    out.push(("first release date", a.clone(), b.clone()));
                }
                compare(&mut out, "label", a.label.as_deref(), b.label.as_deref());
            }
            (Facts::Track(a), Facts::Track(b)) => {
                compare(
                    &mut out,
                    "recording",
                    a.recording.as_deref(),
                    b.recording.as_deref(),
                );
                compare(&mut out, "title", a.title.as_deref(), b.title.as_deref());
                compare(&mut out, "album", a.album.as_deref(), b.album.as_deref());
                if !a.artists.is_empty()
                    && !b.artists.is_empty()
                    && !matches!(
                        crate::sources::verdict_set(&a.artists, &b.artists),
                        crate::sources::Verdict::Agrees
                    )
                {
                    out.push(("artists", a.artists.join(", "), b.artists.join(", ")));
                }
            }
            _ => {}
        }
        out
    }
}

fn check_sources(catalog: &Catalog, sources: &crate::sources::Sources, issues: &mut Vec<Issue>) {
    use crate::sources::{Facts, Verdict};
    use crate::user::EntityRef;

    for record in &sources.records {
        if !sources.is_trusted(catalog, record) {
            continue;
        }
        let Facts::Release(facts) = &record.facts else {
            continue;
        };
        let entity: EntityRef = record.entity();
        let Some(release) = entity.resolve(catalog).and_then(|id| catalog.release(id)) else {
            continue;
        };

        // The first file of the release answers for its tags: `RELEASETYPE`
        // and `LABEL` belong to the edition, not to one track of it.
        let tag = |name: &str| -> Option<String> {
            release
                .track_ids
                .first()
                .and_then(|&t| catalog.track(t))
                .and_then(|t| catalog.file(t.file_id))
                .and_then(|f| f.first_tag(name).map(str::to_string))
        };

        let label_tag = release
            .label_ids
            .first()
            .and_then(|&id| catalog.label(id))
            .map(|l| l.name.clone());

        let comparisons = [
            (
                "release type",
                facts.primary_type.as_deref(),
                tag("releasetype"),
                false,
            ),
            (
                "date",
                facts.first_released.as_deref(),
                release.date.clone(),
                true,
            ),
            ("label", facts.label.as_deref(), label_tag, false),
        ];

        for (what, theirs, yours, is_date) in comparisons {
            let Some(theirs) = theirs else { continue };
            let verdict = match is_date {
                true => crate::sources::verdict_date(theirs, yours.as_deref()),
                false => crate::sources::verdict(theirs, yours.as_deref()),
            };
            let Verdict::Differs { theirs, yours } = verdict else {
                continue;
            };
            issues.push(Issue {
                kind: IssueKind::SourceDisagrees,
                detail: format!(
                    "\"{}\": {} says the {what} is \"{theirs}\", the tags say \"{yours}\"",
                    release.title, record.source
                ),
                files: release
                    .track_ids
                    .iter()
                    .filter_map(|&t| catalog.track(t))
                    .filter_map(|t| catalog.file(t.file_id))
                    .map(|f| f.path.clone())
                    .take(1)
                    .collect(),
            });
        }
    }
}

fn check_imported_analyses(catalog: &Catalog, issues: &mut Vec<Issue>) {
    let files: BTreeMap<&str, &model::AudioFile> =
        catalog.files.iter().map(|f| (f.path.as_str(), f)).collect();
    for record in &catalog.analyses {
        // An analysis of a file the catalog does not hold is not a problem to
        // report: it is waiting for the folder it speaks of to be scanned.
        let Some(file) = files.get(record.path.as_str()) else {
            continue;
        };
        // An analysis of bytes that changed since says nothing about the file
        // that is there now.
        if !record.still_applies(file.size, file.mtime) {
            continue;
        }

        if record.md5_failed() {
            let contradiction = matches!(
                file.integrity.as_ref().map(|r| &r.verdict),
                Some(crate::audit::integrity::Verdict::Intact)
            );
            let detail = if contradiction {
                format!(
                    "{} decoded the audio and it does not match the file's own MD5, \
                     although the frame checksums are valid: the stream was re-encoded",
                    record.source
                )
            } else {
                format!(
                    "{} found the audio does not match the file's own MD5",
                    record.source
                )
            };
            issues.push(Issue {
                kind: IssueKind::Md5Mismatch,
                detail,
                files: vec![file.path.clone()],
            });
        }

        // The spectral verdicts — transcoding, upscaling, upsampling — are read
        // from the report, stored and kept up to date, and deliberately not
        // reported here. See `analysis::FileAnalysis::suspect_encoding`, which
        // nothing calls on purpose.
    }
}

/// Reports the albums the model linked to a copy of themselves.
///
/// Only the copies that are identical in quality: a hi-res edition beside the
/// CD rip is a deliberate second copy and not something to fix.
fn check_duplicate_albums(catalog: &Catalog, issues: &mut Vec<Issue>) {
    let mut seen: std::collections::BTreeSet<(Id, Id)> = Default::default();
    for relation in &catalog.relations {
        if relation.source_kind == model::EntityKind::Release
            && relation.target_kind == model::EntityKind::Release
            && relation.kind == model::DUPLICATE
        {
            let Some(release) = catalog.release(relation.source_id) else {
                continue;
            };
            let other_id = relation.target_id;
            let pair = (release.id.min(other_id), release.id.max(other_id));
            if !seen.insert(pair) {
                continue;
            }
            let Some(other) = catalog.release(other_id) else {
                continue;
            };
            // The smaller of the two is what deleting one would free; both are
            // named, since only the user knows which folder to keep.
            let wasted = release_size(catalog, release.id).min(release_size(catalog, other_id));
            issues.push(Issue {
                kind: IssueKind::DuplicateAlbum,
                detail: format!(
                    "\"{}\" is present twice in the same quality ({} recoverable)",
                    release.title,
                    text::format_size(wasted)
                ),
                files: vec![release.folder.clone(), other.folder.clone()],
            });
        }
    }
}

/// `true` when the tracks all come from releases the model already tied
/// together, whichever way.
///
/// A copied album would otherwise be reported once per track, and so would a
/// hi-res edition sitting beside its CD rip — which is not a defect at all. The
/// album-level lines say both things once, and name the folders.
fn covered_by_the_album(catalog: &Catalog, cluster: &[(Id, u64)]) -> bool {
    let releases: Vec<Id> = cluster
        .iter()
        .filter_map(|&(id, _)| catalog.track(id))
        .filter_map(|t| t.release_id)
        .collect();
    if releases.len() != cluster.len() || releases.len() < 2 {
        return false;
    }
    let first = releases[0];
    let linked: std::collections::BTreeSet<Id> = catalog
        .related_releases(first, model::DUPLICATE)
        .into_iter()
        .chain(catalog.related_releases(first, model::OTHER_EDITION))
        .collect();
    releases
        .iter()
        .skip(1)
        .all(|other| *other == first || linked.contains(other))
}

/// Notes the albums kept in two encodings. Not a defect: a hi-res copy beside
/// the CD rip is a choice, and saying nothing at all would look like an
/// oversight next to the duplicate lines.
fn check_other_editions(catalog: &Catalog, issues: &mut Vec<Issue>) {
    let mut seen: std::collections::BTreeSet<(Id, Id)> = Default::default();
    for relation in &catalog.relations {
        if relation.source_kind == model::EntityKind::Release
            && relation.target_kind == model::EntityKind::Release
            && relation.kind == model::OTHER_EDITION
        {
            let Some(release) = catalog.release(relation.source_id) else {
                continue;
            };
            let other_id = relation.target_id;
            let pair = (release.id.min(other_id), release.id.max(other_id));
            if !seen.insert(pair) {
                continue;
            }
            let Some(other) = catalog.release(other_id) else {
                continue;
            };
            issues.push(Issue {
                kind: IssueKind::OtherEdition,
                detail: format!(
                    "\"{}\" is kept in two encodings ({} and {})",
                    release.title,
                    quality_summary(catalog, release.id),
                    quality_summary(catalog, other_id)
                ),
                files: vec![release.folder.clone(), other.folder.clone()],
            });
        }
    }
}

/// The formats a release is made of, in one short phrase.
fn quality_summary(catalog: &Catalog, release_id: Id) -> String {
    let labels: std::collections::BTreeSet<String> = catalog
        .release(release_id)
        .map(|r| {
            r.track_ids
                .iter()
                .filter_map(|&id| catalog.track(id))
                .filter_map(|t| catalog.file(t.file_id))
                .map(|f| f.properties.quality_label())
                .collect()
        })
        .unwrap_or_default();
    labels.into_iter().collect::<Vec<_>>().join(", ")
}

fn release_size(catalog: &Catalog, release_id: Id) -> u64 {
    catalog
        .release(release_id)
        .map(|r| {
            r.track_ids
                .iter()
                .filter_map(|&id| catalog.track(id))
                .filter_map(|t| catalog.file(t.file_id))
                .map(|f| f.size)
                .fold(0u64, u64::saturating_add)
        })
        .unwrap_or(0)
}

/// Files whose fingerprints are identical: the same audio, whatever the tags
/// say about it.
///
/// This is what a fingerprint buys beyond identifying a file, and it is worth
/// more than the identification for a library somebody has been keeping for
/// years: [`IssueKind::DuplicateTrack`] compares artist, title and duration,
/// so it can only find copies whose *tags* already agree. Two rips of one
/// track filed under different titles — or under none — are invisible to it
/// and obvious here.
///
/// Only files that have been fingerprinted take part, which is what makes the
/// report honest: a library where nothing has been fingerprinted reports no
/// identical audio, and that is a silence rather than a clean bill of health.
/// `aede fingerprint --full` is what fills it in.
fn check_same_audio(catalog: &Catalog, issues: &mut Vec<Issue>) {
    let mut groups: BTreeMap<&str, Vec<&crate::model::AudioFile>> = BTreeMap::new();
    for file in &catalog.files {
        if let Some(print) = &file.fingerprint {
            groups.entry(print.data.as_str()).or_default().push(file);
        }
    }
    for (_, files) in groups {
        if files.len() < 2 {
            continue;
        }
        // Everything after the first is what could go, which is the number a
        // reader is actually deciding about.
        let wasted = files
            .iter()
            .skip(1)
            .map(|f| f.size)
            .fold(0u64, u64::saturating_add);
        issues.push(Issue {
            kind: IssueKind::SameAudio,
            detail: format!(
                "{} files are the same recording ({} recoverable)",
                files.len(),
                text::format_size(wasted)
            ),
            files: files.iter().map(|f| f.path.clone()).collect(),
        });
    }
}

/// Suggests copies with matching tagged artist/title and readable durations.
///
/// Filename-derived titles are not identity evidence. A group spans at most
/// three seconds, so intermediate durations cannot join different versions.
fn check_duplicates(catalog: &Catalog, issues: &mut Vec<Issue>) {
    let mut groups: BTreeMap<(String, String), Vec<(Id, u64)>> = BTreeMap::new();

    for track in &catalog.tracks {
        let Some(file) = catalog.file(track.file_id) else {
            continue;
        };
        let Some(duration) = track.duration_ms.filter(|duration| *duration > 0) else {
            continue;
        };
        let artist = file.first_tag("artist").unwrap_or("");
        let title = file.first_tag("title").unwrap_or("");
        let key = (text::normalize(artist), text::normalize(title));
        if key.0.is_empty() || key.1.is_empty() {
            continue;
        }
        groups.entry(key).or_default().push((track.id, duration));
    }

    for ((artist, title), mut entries) in groups {
        if entries.len() < 2 {
            continue;
        }
        entries.sort_by_key(|&(_, duration)| duration);

        // Every member must be close to the shortest version. Comparing only
        // neighbours would chain studio and live performances into one group.
        let mut cluster: Vec<(Id, u64)> = vec![entries[0]];
        let mut clusters: Vec<Vec<(Id, u64)>> = Vec::new();
        for &entry in &entries[1..] {
            let first = cluster.first().map(|&(_, d)| d).unwrap_or(0);
            if entry.1.abs_diff(first) <= 3_000 {
                cluster.push(entry);
            } else {
                clusters.push(std::mem::take(&mut cluster));
                cluster = vec![entry];
            }
        }
        clusters.push(cluster);

        for cluster in clusters.into_iter().filter(|c| c.len() > 1) {
            // A copied album would otherwise be reported once per track: the
            // album-level issue already names the two folders, and thirteen
            // lines saying the same thing bury everything else.
            if covered_by_the_album(catalog, &cluster) {
                continue;
            }
            let files: Vec<String> = cluster
                .iter()
                .filter_map(|&(id, _)| catalog.track(id))
                .filter_map(|t| catalog.file(t.file_id))
                .map(|f| f.path.clone())
                .collect();
            let wasted: u64 = cluster
                .iter()
                .skip(1)
                .filter_map(|&(id, _)| catalog.track(id))
                .filter_map(|t| catalog.file(t.file_id))
                .map(|f| f.size)
                .fold(0u64, u64::saturating_add);
            issues.push(Issue {
                kind: IssueKind::DuplicateTrack,
                detail: format!(
                    "\"{title}\" by \"{artist}\" present {} times ({} recoverable)",
                    cluster.len(),
                    text::format_size(wasted)
                ),
                files,
            });
        }
    }
}

/// What names an album across the folders it may be spread over.
///
/// Deliberately *not* the release identity, which includes the folder — that is
/// what tells a CD rip from a vinyl rip of the same record, and it is exactly
/// the part that has to be dropped here to see the two halves of one set.
fn album_key(release: &model::Release) -> (String, Option<Id>) {
    (release.key.clone(), release.album_artist_id)
}

/// Every disc the library holds of each album, wherever it sits on disk.
fn discs_by_album(catalog: &Catalog) -> BTreeMap<(String, Option<Id>), BTreeSet<u32>> {
    let mut out: BTreeMap<(String, Option<Id>), BTreeSet<u32>> = BTreeMap::new();
    for release in &catalog.releases {
        let discs = out.entry(album_key(release)).or_default();
        for track in release.track_ids.iter().filter_map(|&id| catalog.track(id)) {
            discs.insert(track.disc_no.unwrap_or(1));
        }
    }
    out
}

fn check_releases(catalog: &Catalog, issues: &mut Vec<Issue>) {
    let discs_elsewhere = discs_by_album(catalog);
    for release in &catalog.releases {
        let tracks: Vec<_> = release
            .track_ids
            .iter()
            .filter_map(|&id| catalog.track(id))
            .collect();
        if tracks.is_empty() {
            continue;
        }
        let paths: Vec<String> = tracks
            .iter()
            .filter_map(|t| catalog.file(t.file_id))
            .map(|f| f.path.clone())
            .collect();

        // Gaps in the numbering, disc by disc — and what the files themselves
        // say the disc should hold, which is the only way to see the tracks
        // missing from the *end*. On gaps alone, an album truncated after track
        // 9 of 12 looks perfectly whole: there is nothing between 1 and 9 left
        // to be missing. That is exactly the shape an interrupted rip has, so
        // the check was blind to its most common case.
        let mut by_disc: BTreeMap<u32, (Vec<u32>, u32)> = BTreeMap::new();
        for track in &tracks {
            if let Some(no) = track.track_no {
                let entry = by_disc.entry(track.disc_no.unwrap_or(1)).or_default();
                entry.0.push(no);
                if let Some(total) = catalog.file(track.file_id).and_then(announced_total) {
                    entry.1 = entry.1.max(total);
                }
            }
        }
        for (disc, (mut numbers, announced)) in by_disc {
            numbers.sort_unstable();
            numbers.dedup();
            let Some(&last) = numbers.last() else {
                continue;
            };
            // A total smaller than what is present is a wrong tag, not a
            // missing track, so the ceiling is whichever of the two is larger.
            let max = last.max(announced);
            // Only twelve positions and an ellipsis are displayed. Totals
            // come from untrusted tags and must not allocate billions of rows.
            let missing: Vec<u32> = (1..=max)
                .filter(|n| numbers.binary_search(n).is_err())
                .take(13)
                .collect();
            if !missing.is_empty() {
                let list: Vec<String> = missing.iter().take(12).map(|n| n.to_string()).collect();
                issues.push(Issue {
                    kind: IssueKind::IncompleteAlbum,
                    detail: format!(
                        "\"{}\" disc {disc}: missing tracks {}{}",
                        release.title,
                        list.join(", "),
                        if missing.len() > 12 { "…" } else { "" }
                    ),
                    files: paths.clone(),
                });
            }
        }

        // A whole disc missing, which the check above cannot see: every disc
        // that is there is complete, and nothing in the numbering says how many
        // there should be. A four-disc soundtrack ripped as three looks perfect
        // until the day it is played. `disctotal` answers it, and so does a
        // hole in the disc numbers themselves.
        let present: BTreeSet<u32> = tracks.iter().map(|t| t.disc_no.unwrap_or(1)).collect();
        let announced = tracks
            .iter()
            .filter_map(|t| catalog.file(t.file_id))
            .filter_map(announced_discs)
            .max();
        // Same rule as the tracks: a total smaller than what is here is a wrong
        // tag rather than a missing disc.
        let ceiling = present
            .iter()
            .copied()
            .max()
            .unwrap_or(1)
            .max(announced.unwrap_or(0));
        let sibling = discs_elsewhere.get(&album_key(release));
        let missing: Vec<u32> = (1..=ceiling)
            .filter(|n| !present.contains(n))
            // Not missing, merely somewhere else: a set laid out as two folders
            // the disc-folder rule does not recognise — "Album CD1" beside
            // "Album CD2" rather than under a common parent — makes two
            // releases, each of which would otherwise report the other as
            // missing. Look for it in the library before calling it lost.
            .filter(|n| !sibling.is_some_and(|discs| discs.contains(n)))
            .take(13)
            .collect();
        if !missing.is_empty() {
            let list: Vec<String> = missing.iter().take(12).map(|n| n.to_string()).collect();
            issues.push(Issue {
                kind: IssueKind::IncompleteAlbum,
                detail: format!(
                    "\"{}\": missing {} {}{}{}",
                    release.title,
                    if missing.len() > 1 { "discs" } else { "disc" },
                    list.join(", "),
                    if missing.len() > 12 { "…" } else { "" },
                    match announced {
                        Some(total) => format!(" of {total}"),
                        None => String::new(),
                    }
                ),
                files: paths.clone(),
            });
        }

        // A mix of codecs or sample rates within a single album: the sign of an
        // album pieced together from different sources.
        let files: Vec<_> = tracks
            .iter()
            .filter_map(|t| catalog.file(t.file_id))
            .collect();
        let codecs: std::collections::BTreeSet<&str> =
            files.iter().map(|f| f.properties.codec.as_str()).collect();
        let rates: std::collections::BTreeSet<u32> = files
            .iter()
            .filter_map(|f| f.properties.sample_rate)
            .collect();
        if codecs.len() > 1 || rates.len() > 1 {
            let mut details = Vec::new();
            if codecs.len() > 1 {
                details.push(format!(
                    "codecs: {}",
                    codecs.iter().copied().collect::<Vec<_>>().join(", ")
                ));
            }
            if rates.len() > 1 {
                details.push(format!(
                    "sample rates: {}",
                    rates
                        .iter()
                        .map(|r| r.to_string())
                        .collect::<Vec<_>>()
                        .join(", ")
                ));
            }
            issues.push(Issue {
                kind: IssueKind::MixedQuality,
                detail: format!("\"{}\" — {}", release.title, details.join("; ")),
                files: paths.clone(),
            });
        }

        // Cover art: embedded, or dropped in the folder.
        let has_cover = release.cover_path.is_some() || files.iter().any(|f| f.has_embedded_art);
        if !has_cover {
            issues.push(Issue {
                kind: IssueKind::MissingCover,
                detail: format!("\"{}\" has no cover art", release.title),
                files: vec![release.folder.clone()],
            });
        }
    }
}

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

#[cfg(test)]
#[path = "doctor_source_tests.rs"]
mod source_tests;

/// Pairs of artist rows that look like one musician written two ways.
///
/// **Suggestions, and nothing here ever acts on one.** The half of artist
/// identity that has an exact answer — two spellings under one
/// `MUSICBRAINZ_ARTISTID` — is settled in `model::identity` before anything is
/// interned, so anything still standing as two rows by the time this runs is a
/// pair no authority can rule on. Matching on a fragment of a name merges
/// Angus Young with Neil Young; the only safe thing to do with a resemblance is
/// to show it to somebody who knows.
///
/// Two shapes are reported, and each has to earn it.
///
/// **An initialism.** `O. Osbourne` beside `Ozzy Osbourne`: the same number of
/// words, each word either identical or a single letter that opens the other.
/// Tight enough to stand on its own — the abbreviated spelling usually lives on
/// a different album, so there is nothing else to corroborate it with.
///
/// **A shortened name that shares an album.** `Osbourne` beside `Ozzy
/// Osbourne`, where one name's words end the other's. Loose on its own, which
/// is why it is only reported when the two are credited on **the same release
/// folder**: two people who differ by a dropped first name and appear on one
/// record together are, in practice, one person tagged twice.
///
/// A pair whose two rows carry **different** MusicBrainz identifiers is never
/// reported: that is not a resemblance, it is two people, said so by the only
/// authority on the question.
fn check_same_person(catalog: &Catalog, issues: &mut Vec<Issue>) {
    // Artists with nothing behind them are skipped: a name credited on no
    // track is usually a stray tag, and a report of two strays helps nobody.
    let named: Vec<&model::Artist> = catalog
        .artists
        .iter()
        .filter(|a| !catalog.tracks_of_artist(a.id).is_empty())
        .collect();

    for (at, one) in named.iter().enumerate() {
        for other in named.iter().skip(at + 1) {
            // Two identifiers are two people. Two rows sharing one would
            // already be one row, so this only ever excludes real pairs.
            if let (Some(a), Some(b)) = (&one.mbid, &other.mbid)
                && a != b
            {
                continue;
            }
            let together = || shares_a_release(catalog, one.id, other.id);
            let why = if initialism(&one.key, &other.key) {
                "one is the other with a first name reduced to its initial"
            } else if shortened(&one.key, &other.key) && together() {
                "one is the other without its first name, and both are credited on one album"
            } else {
                continue;
            };
            // The longer spelling second, so the line reads the way the
            // command that acts on it is typed: the short one gives way.
            let (short, long) = match one.key.len() <= other.key.len() {
                true => (one, other),
                false => (other, one),
            };
            issues.push(Issue {
                kind: IssueKind::SameArtistMaybe,
                detail: format!(
                    "\"{}\" ({}) and \"{}\" ({}): {why}. \
                     If they are, aede merge \"{}\" \"{}\" says so — \
                     nothing in your files changes",
                    short.name,
                    crate::text::plural(catalog.tracks_of_artist(short.id).len(), "track"),
                    long.name,
                    crate::text::plural(catalog.tracks_of_artist(long.id).len(), "track"),
                    short.name,
                    long.name,
                ),
                // A couple of files from the lesser spelling, because the way
                // to settle this is to look at what they are tagged with.
                files: catalog
                    .tracks_of_artist(short.id)
                    .iter()
                    .filter_map(|&t| catalog.track(t))
                    .filter_map(|t| catalog.file(t.file_id))
                    .map(|f| f.path.clone())
                    .take(2)
                    .collect(),
            });
        }
    }
}

/// `true` when two normalised names differ only by a first name reduced to its
/// initial: `o osbourne` and `ozzy osbourne`.
///
/// Word for word, so a shared letter anywhere else cannot trigger it, and at
/// least one word has to actually be an initial — otherwise two identical names
/// would qualify, and they are one row already.
fn initialism(one: &str, other: &str) -> bool {
    let (a, b): (Vec<&str>, Vec<&str>) = (one.split(' ').collect(), other.split(' ').collect());
    if a.len() != b.len() || a.len() < 2 {
        return false;
    }
    let mut abbreviated = false;
    for (left, right) in a.iter().zip(&b) {
        if left == right {
            continue;
        }
        let opens = |short: &str, full: &str| {
            short.chars().count() == 1 && full.starts_with(short) && full.chars().count() > 1
        };
        match opens(left, right) || opens(right, left) {
            true => abbreviated = true,
            false => return false,
        }
    }
    abbreviated
}

/// `true` when one name's words are the tail of the other's: `osbourne` inside
/// `ozzy osbourne`.
///
/// Whole words, never a substring, because a substring match is what merges
/// `Young` into everybody. On its own this is far too loose to act on, which is
/// why its caller also demands a shared release.
fn shortened(one: &str, other: &str) -> bool {
    let (a, b): (Vec<&str>, Vec<&str>) = (one.split(' ').collect(), other.split(' ').collect());
    let (short, long) = if a.len() < b.len() { (a, b) } else { (b, a) };
    !short.is_empty() && short.len() < long.len() && long.ends_with(&short[..])
}

/// `true` when two artists are credited on one and the same release.
fn shares_a_release(catalog: &Catalog, one: Id, other: Id) -> bool {
    let mine: BTreeSet<Id> = catalog.releases_of_artist(one).into_iter().collect();
    catalog
        .releases_of_artist(other)
        .iter()
        .any(|id| mine.contains(id))
}