onetaskgraph 0.2.31

//! What a person sees.
//!
//! Machine-readable output is the response types themselves, serialised — a stable
//! contract an SDK is generated from, and validated in the journeys against the schema
//! this binary emits. Everything in this file is the *other* output: minimal, aligned,
//! and deliberately not a second contract. Nothing here reshapes a response; it renders
//! one.
//!
//! Every vocabulary a line spells — a status category, a predicate, a dependency kind —
//! is taken from the type's own `Serialize`, never from a `match` written out again
//! here. A second spelling of `in-progress` in this file would be a second place for it
//! to drift from the one a filter compares against.

use onetaskgraph_core::{
    CommentList, CopyReport, DeletedComment, Predicate, Qualified, QualifiedEdge, QueryPlan,
    SearchHit, SourceListing, SourceState,
};
use onetaskgraph_plugin_api::{
    Capabilities, Comment, Document, Label, Location, Project, Support, Task,
};
use serde::Serialize;

/// One value as the wire spells it — `in-progress`, `search-title`, `blocks`.
///
/// Every caller passes a unit-like enum of the contract, which serialises to a quoted
/// string and cannot fail; stripping the quotes is the whole of the work. Taking the
/// spelling from `Serialize` rather than from a `match` written out again here is what
/// stops a second spelling of `in-progress` existing to drift from the one a filter
/// compares against.
fn wire(value: &impl Serialize) -> String {
    serde_json::to_string(value)
        .expect("a contract enum serialises")
        .trim_matches('"')
        .to_owned()
}

/// Lay `rows` out as aligned columns, one line each.
///
/// The last column is never padded, so nothing trails a line with blanks that a shell
/// pipeline would then have to strip.
fn columns(rows: &[Vec<String>]) -> String {
    let width = rows.iter().map(Vec::len).max().unwrap_or(0);
    let widths: Vec<usize> = (0..width)
        .map(|column| {
            rows.iter()
                .filter_map(|row| row.get(column))
                .map(|cell| cell.chars().count())
                .max()
                .unwrap_or(0)
        })
        .collect();

    let mut rendered = String::new();
    for row in rows {
        let last = row.len().saturating_sub(1);
        for (index, cell) in row.iter().enumerate() {
            if index == last {
                rendered.push_str(cell);
            } else {
                let pad = widths[index].saturating_sub(cell.chars().count());
                rendered.push_str(cell);
                rendered.push_str(&" ".repeat(pad));
                rendered.push_str("  ");
            }
        }
        rendered.push('\n');
    }
    rendered
}

/// One line per task: qualified id, normalised status, title.
///
/// The normalised category rather than the source's own wording, because this list
/// crosses sources and the category is the one vocabulary they share — and it is what
/// `--status` compares against. `task show` prints both.
pub fn tasks(items: &[Qualified<Task>]) -> String {
    columns(
        &items
            .iter()
            .map(|task| {
                vec![
                    task.id.to_string(),
                    wire(&task.item.status.category),
                    task.item.title.clone(),
                ]
            })
            .collect::<Vec<_>>(),
    )
}

/// Where an entity is, as one cell: which kind of place, then the place itself.
///
/// The key is the kind, read off the type's own `Serialize` rather than written out again
/// in a `match`, for the reason [`wire`] gives: `Location` is externally tagged with
/// exactly two variants, so what a consumer branches on in JSON is what a reader sees here.
fn located(location: &Location) -> String {
    let rendered = serde_json::to_value(location).expect("a contract enum serialises");
    let (kind, place) = rendered
        .as_object()
        .and_then(|object| object.iter().next())
        .expect("an externally tagged enum is an object of exactly one member");
    format!("{kind} {}", place.as_str().unwrap_or_default())
}

/// One line per document: qualified id, where it is, title.
///
/// Where a task list prints the normalised status, this prints the location: a document
/// has no status, and where it is is what a reader does something with — open the link, or
/// read the file out. A document whose source did not say prints `-`, which is not the
/// same as saying it is nowhere.
pub fn documents(items: &[Qualified<Document>]) -> String {
    columns(
        &items
            .iter()
            .map(|document| {
                vec![
                    document.id.to_string(),
                    document
                        .item
                        .location
                        .as_ref()
                        .map_or_else(|| "-".to_owned(), located),
                    document.item.title.clone(),
                ]
            })
            .collect::<Vec<_>>(),
    )
}

/// One line per project: qualified id, normalised status, title.
pub fn projects(items: &[Qualified<Project>]) -> String {
    columns(
        &items
            .iter()
            .map(|project| {
                vec![
                    project.id.to_string(),
                    wire(&project.item.status.category),
                    project.item.title.clone(),
                ]
            })
            .collect::<Vec<_>>(),
    )
}

/// One line per item a copy considered: where it came from, where it went, what happened —
/// and one final line for what it did to the references its documents hold.
///
/// A dry run that would create has no destination id to print, because nothing was
/// created and inventing one would be a claim about an id the destination never issued.
///
/// The reference line is **one** line and always printed, not a second report and not a
/// section a reader has to know to ask for: a silent bound is indistinguishable from a bug,
/// so a copy that recognised nothing says so with zeroes rather than by omission.
pub fn copied(report: &CopyReport) -> String {
    let mut rendered = columns(
        &report
            .items
            .iter()
            .map(|outcome| {
                vec![
                    outcome.source.to_string(),
                    outcome
                        .destination()
                        .map_or_else(|| "-".to_owned(), ToString::to_string),
                    outcome.action.name(),
                ]
            })
            .collect::<Vec<_>>(),
    );
    rendered.push_str(&references(report));
    rendered.push_str(&spent(report));
    rendered
}

/// The one line a copy says about what it spent, when a source in it metered its requests.
///
/// No line at all when none did, for the reason the machine output leaves the member out:
/// a source that does not count what it sends has not sent nothing.
fn spent(report: &CopyReport) -> String {
    let Some(spent) = &report.spent else {
        return String::new();
    };
    let budgets = spent
        .budgets
        .iter()
        .map(|budget| {
            format!(
                "{} {} {}{}",
                budget.budget,
                budget.amount,
                budget.unit,
                if budget.lower_bound { " at least" } else { "" }
            )
        })
        .collect::<Vec<_>>()
        .join(", ");
    format!("spent: {} requests; {budgets}\n", spent.requests)
}

/// The one line a copy says about the references its documents hold.
///
/// The ambiguous figure is spelled as what it is — part of the unresolved one — because
/// the two mean different things to a reader: an unresolved reference is ordinary under
/// the bound the copy works to, while an ambiguous one says the destination holds
/// duplicate records for one work item, or the source reports one location for two, and
/// re-running the copy will never clear it.
fn references(report: &CopyReport) -> String {
    format!(
        "references: {} rewritten, {} unresolved ({} ambiguous)\n",
        report.references_rewritten, report.references_unresolved, report.references_ambiguous
    )
}

/// One line per label: qualified id and the name a filter types.
pub fn labels(items: &[Qualified<Label>]) -> String {
    columns(
        &items
            .iter()
            .map(|label| vec![label.id.to_string(), label.item.name.clone()])
            .collect::<Vec<_>>(),
    )
}

/// One line per edge: where it starts, what it means, where it points.
pub fn edges(items: &[QualifiedEdge]) -> String {
    columns(
        &items
            .iter()
            .map(|edge| {
                vec![
                    format!("{} {}", wire(&edge.from.kind), edge.from.id),
                    wire(&edge.kind),
                    format!("{} {}", wire(&edge.to.kind), edge.to.id),
                ]
            })
            .collect::<Vec<_>>(),
    )
}

/// One line per hit, saying which entity matched.
pub fn hits(items: &[SearchHit]) -> String {
    columns(
        &items
            .iter()
            .map(|hit| match hit {
                SearchHit::Task(task) => vec![
                    "task".to_owned(),
                    task.id.to_string(),
                    task.item.title.clone(),
                ],
                SearchHit::Project(project) => vec![
                    "project".to_owned(),
                    project.id.to_string(),
                    project.item.title.clone(),
                ],
            })
            .collect::<Vec<_>>(),
    )
}

/// One task in full, body last.
pub fn task_detail(task: &Qualified<Task>) -> String {
    let item = &task.item;
    let mut fields = vec![
        ("id", task.id.to_string()),
        ("title", item.title.clone()),
        (
            "status",
            format!("{} ({})", wire(&item.status.category), item.status.name),
        ),
    ];
    fields.push((
        "project",
        match &item.project {
            Some(project) => format!("{}:{project}", task.id.source),
            None => "none".to_owned(),
        },
    ));
    detail(
        &mut fields,
        &item.labels,
        item.url.as_deref(),
        item.location.as_ref(),
    );
    body(&fields, item.content.as_deref())
}

/// One task in full, body last, and then its comments when its source has them.
///
/// `None` is a source whose tasks have no comments, and says nothing about them: a line
/// reading "no comments" there would claim the source holds comments and this task has none.
pub fn task_with_comments(task: &Qualified<Task>, comments: Option<&[Comment]>) -> String {
    let mut rendered = task_detail(task);
    let Some(comments) = comments else {
        return rendered;
    };
    rendered.push('\n');
    if comments.is_empty() {
        rendered.push_str("comments: none\n");
        return rendered;
    }
    rendered.push_str(&format!("comments: {}\n", comments.len()));
    for held in comments {
        rendered.push('\n');
        rendered.push_str(&comment(held));
    }
    rendered
}

/// One comment in full: the fields a person reads it by, then what it says, unaltered.
///
/// A field the source did not give is left out rather than printed empty, as a task's are.
pub fn comment(comment: &Comment) -> String {
    let mut fields = vec![("comment", comment.id.to_string())];
    if let Some(author) = &comment.author {
        fields.push(("author", author.clone()));
    }
    if let Some(created) = &comment.created_at {
        fields.push(("created", wire(created)));
    }
    if let Some(updated) = &comment.updated_at {
        fields.push(("updated", wire(updated)));
    }
    if let Some(url) = &comment.url {
        fields.push(("url", url.clone()));
    }
    let mut rendered = columns(
        &fields
            .iter()
            .map(|(name, value)| vec![format!("{name}:"), value.clone()])
            .collect::<Vec<_>>(),
    );
    rendered.push('\n');
    rendered.push_str(&comment.body);
    if !comment.body.ends_with('\n') {
        rendered.push('\n');
    }
    rendered
}

/// Every comment on a task, oldest first, each in full with a blank line between.
pub fn comments(list: &CommentList) -> String {
    if list.comments.is_empty() {
        return "no comments\n".to_owned();
    }
    list.comments
        .iter()
        .map(comment)
        .collect::<Vec<_>>()
        .join("\n")
}

/// What a delete removed.
pub fn deleted(deleted: &DeletedComment) -> String {
    format!("deleted comment {}\n", deleted.deleted)
}

/// One document in full, body last.
///
/// No status line, because a document has none — and no dependency line, because it is in
/// no graph. What it has that a task does not print above its body is the same `location`
/// every entity now carries.
pub fn document_detail(document: &Qualified<Document>) -> String {
    let item = &document.item;
    let mut fields = vec![
        ("id", document.id.to_string()),
        ("title", item.title.clone()),
        (
            "project",
            match &item.project {
                Some(project) => format!("{}:{project}", document.id.source),
                None => "none".to_owned(),
            },
        ),
    ];
    detail(
        &mut fields,
        &item.labels,
        item.url.as_deref(),
        item.location.as_ref(),
    );
    body(&fields, item.content.as_deref())
}

/// One project in full, body last.
pub fn project_detail(project: &Qualified<Project>) -> String {
    let item = &project.item;
    let mut fields = vec![
        ("id", project.id.to_string()),
        ("title", item.title.clone()),
        (
            "status",
            format!("{} ({})", wire(&item.status.category), item.status.name),
        ),
    ];
    detail(
        &mut fields,
        &item.labels,
        item.url.as_deref(),
        item.location.as_ref(),
    );
    body(&fields, item.content.as_deref())
}

/// The fields a task, a project and a document share below their own.
///
/// `location` is a line of its own rather than folded into `url`, and it says which kind
/// of place it names: a reader handed one has to know whether to open a link or read a
/// file out, and the two are different actions. It does not replace `url` — a source that
/// reports one goes on reporting it, and both lines appear when a source gives both.
fn detail(
    fields: &mut Vec<(&'static str, String)>,
    item_labels: &[Label],
    url: Option<&str>,
    location: Option<&Location>,
) {
    if !item_labels.is_empty() {
        fields.push((
            "labels",
            item_labels
                .iter()
                .map(|label| label.name.clone())
                .collect::<Vec<_>>()
                .join(", "),
        ));
    }
    if let Some(url) = url {
        fields.push(("url", url.to_owned()));
    }
    if let Some(location) = location {
        fields.push(("location", located(location)));
    }
}

/// The field table, then the long-form body under a blank line.
fn body(fields: &[(&'static str, String)], content: Option<&str>) -> String {
    let mut rendered = columns(
        &fields
            .iter()
            .map(|(name, value)| vec![format!("{name}:"), value.clone()])
            .collect::<Vec<_>>(),
    );
    if let Some(content) = content.map(str::trim).filter(|body| !body.is_empty()) {
        rendered.push('\n');
        rendered.push_str(content);
        rendered.push('\n');
    }
    rendered
}

/// One line per configured source: what it is, and what it says it can do.
pub fn sources(listings: &[SourceListing]) -> String {
    columns(
        &listings
            .iter()
            .map(|listing| {
                vec![
                    listing.source.to_string(),
                    listing.kind.clone(),
                    match &listing.state {
                        SourceState::Available { capabilities } => declared(capabilities),
                        SourceState::Unavailable { error } => {
                            format!("unavailable — {error}")
                        }
                    },
                ]
            })
            .collect::<Vec<_>>(),
    )
}

/// What one source applies itself, in one line.
fn declared(capabilities: &Capabilities) -> String {
    let native: Vec<&str> = [
        ("label", capabilities.filter_by_label),
        ("status", capabilities.filter_by_status),
        ("search-title", capabilities.search_title),
        ("search-content", capabilities.search_content),
        ("project", capabilities.projects),
        ("orphan-tasks", capabilities.orphan_tasks),
    ]
    .into_iter()
    .filter(|(_, support)| *support == Support::Native)
    .map(|(name, _)| name)
    .collect();

    format!(
        "native: {}; deps: task {}, project {}; page <= {}",
        if native.is_empty() {
            "none".to_owned()
        } else {
            native.join(", ")
        },
        wire(&capabilities.task_dependencies),
        wire(&capabilities.project_dependencies),
        capabilities.max_page_size,
    )
}

/// The plan, per source, with only the lines that have something to say.
///
/// This is the whole reason capability declaration exists: two sources answer the same
/// query by two different plans and both answers are correct, and without this a caller
/// could only guess which of the two they got.
pub fn plan(plan: &QueryPlan) -> String {
    let mut rendered = String::from("plan:\n");
    if plan.per_source.is_empty() {
        rendered.push_str("  (no source was addressed)\n");
        return rendered;
    }
    for source in &plan.per_source {
        rendered.push_str(&format!(
            "  {} ({})  {} page(s)\n",
            source.source, source.kind, source.pages_fetched
        ));
        for (label, predicates) in [
            ("pushed down", &source.pushed_down),
            ("applied locally", &source.applied_locally),
            ("emulated", &source.emulated),
            ("unavailable", &source.unavailable),
        ] {
            if predicates.is_empty() {
                continue;
            }
            rendered.push_str(&format!("    {label}: {}\n", predicate_list(predicates)));
        }
    }
    rendered
}

/// Predicate names, in the wire spelling `--json` publishes.
fn predicate_list(predicates: &[Predicate]) -> String {
    predicates.iter().map(wire).collect::<Vec<_>>().join(", ")
}