linear_api/

relations.rs

//! Issue relations — the blocks/blocked-by DAG edges between issues.
//!
//! # Direction semantics
//!
//! Linear's `IssueRelationType` enum has **no** `blockedBy` value — direction
//! is positional. `type: blocks` means *`issueId` **blocks**
//! `relatedIssueId`*. To express "X is blocked by Y", create the relation as
//! `create(issue = Y, related = X, Blocks)`, or read it from X's
//! `inverseRelations`.
//!
//! On an issue, `Issue.relations` holds the **outgoing** edges (this issue →
//! related issue) and `Issue.inverseRelations` holds the **incoming** edges
//! (other issue → this issue). [`RelationsService::of_issue`] returns both
//! sides as an [`IssueRelations`], whose [`blocks`](IssueRelations::blocks)
//! and [`blocked_by`](IssueRelations::blocked_by) views apply these rules so
//! callers never have to.

use serde::{Deserialize, Serialize};

use crate::client::LinearClient;
use crate::error::{Error, Result};
use crate::ids::{IssueRef, IssueRelationId};
use crate::types::{IssueRelationType, IssueStub, ensure_success};

/// Appends the canonical fragments to an operation. Documents must be
/// self-contained: each one that spreads `...RelationFields` carries the
/// fragment definitions itself. The field sets MUST stay in sync with
/// [`IssueRelation`] and [`IssueStub`].
macro_rules! with_fragments {
    ($doc:literal) => {
        concat!(
            $doc,
            " fragment RelationFields on IssueRelation",
            " { id type issue { ...IssueStubFields } relatedIssue { ...IssueStubFields } }",
            " fragment IssueStubFields on Issue { id identifier title }"
        )
    };
}

const ISSUE_RELATION_CREATE: &str = with_fragments!(
    "mutation IssueRelationCreate($input: IssueRelationCreateInput!) \
     { issueRelationCreate(input: $input) { success issueRelation { ...RelationFields } } }"
);

const ISSUE_RELATION_DELETE: &str =
    "mutation IssueRelationDelete($id: String!) { issueRelationDelete(id: $id) { success } }";

const ISSUE_RELATIONS_OF: &str = with_fragments!(
    "query IssueRelationsOf($id: String!) \
     { issue(id: $id) \
     { relations(first: 50) { nodes { ...RelationFields } } \
     inverseRelations(first: 50) { nodes { ...RelationFields } } } }"
);

pub(crate) const DOCUMENTS: &[(&str, &str)] = &[
    ("IssueRelationCreate", ISSUE_RELATION_CREATE),
    ("IssueRelationDelete", ISSUE_RELATION_DELETE),
    ("IssueRelationsOf", ISSUE_RELATIONS_OF),
];

/// One directed relation edge between two issues.
///
/// Direction is positional: for [`IssueRelationType::Blocks`], [`issue`]
/// blocks [`related_issue`] — there is no `blockedBy` relation type.
///
/// [`issue`]: IssueRelation::issue
/// [`related_issue`]: IssueRelation::related_issue
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct IssueRelation {
    /// Relation ID.
    pub id: IssueRelationId,
    /// How [`issue`](IssueRelation::issue) relates to
    /// [`related_issue`](IssueRelation::related_issue).
    #[serde(rename = "type")]
    pub relation_type: IssueRelationType,
    /// The source issue the relation originates from.
    pub issue: IssueStub,
    /// The target issue the relation points at.
    pub related_issue: IssueStub,
}

/// Both directions of an issue's relation edges, as returned by
/// [`RelationsService::of_issue`].
///
/// `outgoing` mirrors `Issue.relations` (this issue is the source);
/// `incoming` mirrors `Issue.inverseRelations` (this issue is the target).
/// With `type: blocks` meaning *source blocks target*: the issues this one
/// blocks live in `outgoing`, and the issues blocking this one live in
/// `incoming` — use [`blocks`](Self::blocks) / [`blocked_by`](Self::blocked_by)
/// instead of filtering by hand.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct IssueRelations {
    /// Edges where this issue is the source (`Issue.relations`).
    pub outgoing: Vec<IssueRelation>,
    /// Edges where this issue is the target (`Issue.inverseRelations`).
    pub incoming: Vec<IssueRelation>,
}

impl IssueRelations {
    /// The issues this issue **blocks**: outgoing edges with
    /// [`IssueRelationType::Blocks`], yielding each edge's target.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// let client = linear_api::LinearClient::from_env()?;
    /// let relations = client
    ///     .relations()
    ///     .of_issue(linear_api::IssueRef::identifier("ENG-3"))
    ///     .await?;
    /// for blocked in relations.blocks() {
    ///     println!("ENG-3 blocks {}", blocked.identifier);
    /// }
    /// # Ok(()) }
    /// ```
    pub fn blocks(&self) -> Vec<&IssueStub> {
        self.outgoing
            .iter()
            .filter(|r| r.relation_type == IssueRelationType::Blocks)
            .map(|r| &r.related_issue)
            .collect()
    }

    /// The issues this issue is **blocked by**: incoming edges with
    /// [`IssueRelationType::Blocks`], yielding each edge's source.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// let client = linear_api::LinearClient::from_env()?;
    /// let relations = client
    ///     .relations()
    ///     .of_issue(linear_api::IssueRef::identifier("ENG-3"))
    ///     .await?;
    /// for blocker in relations.blocked_by() {
    ///     println!("ENG-3 is blocked by {}", blocker.identifier);
    /// }
    /// # Ok(()) }
    /// ```
    pub fn blocked_by(&self) -> Vec<&IssueStub> {
        self.incoming
            .iter()
            .filter(|r| r.relation_type == IssueRelationType::Blocks)
            .map(|r| &r.issue)
            .collect()
    }
}

/// Wire shape of `IssueRelationCreateInput`.
#[derive(Debug, Clone, Serialize)]
#[serde(rename_all = "camelCase")]
struct CreateVarsInput {
    issue_id: String,
    related_issue_id: String,
    #[serde(rename = "type")]
    relation_type: IssueRelationType,
}

/// Issue-relation operations: the blocks/blocked-by DAG edges between
/// issues. Obtain via [`LinearClient::relations`].
///
/// # Direction semantics
///
/// The relation type enum has **no** `blockedBy` value; direction is
/// positional. `type: blocks` means the **source** issue (`issueId`) blocks
/// the **target** issue (`relatedIssueId`). "X is blocked by Y" is therefore
/// created as `create(Y, X, Blocks)` — or with
/// [`create_blocks`](Self::create_blocks), which names its parameters — and
/// read from X's incoming edges via
/// [`IssueRelations::blocked_by`].
#[derive(Clone, Copy)]
pub struct RelationsService<'a> {
    client: &'a LinearClient,
}

impl LinearClient {
    /// Issue-relation operations (blocks/blocked-by DAG edges).
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// let client = linear_api::LinearClient::from_env()?;
    /// let relations = client
    ///     .relations()
    ///     .of_issue(linear_api::IssueRef::identifier("ENG-3"))
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub fn relations(&self) -> RelationsService<'_> {
        RelationsService { client: self }
    }
}

impl RelationsService<'_> {
    /// Creates a relation edge: `issue` → `related` with the given type.
    ///
    /// **Direction matters**: for [`IssueRelationType::Blocks`], `issue`
    /// blocks `related` (there is no `blockedBy` type). To record "X is
    /// blocked by Y", call `create(Y, X, Blocks)`. Both sides accept a UUID
    /// [`IssueId`](crate::IssueId) or a human identifier via
    /// [`IssueRef::identifier`].
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// use linear_api::{IssueRef, IssueRelationType, LinearClient};
    ///
    /// let client = LinearClient::from_env()?;
    /// // ENG-1 blocks ENG-2:
    /// let relation = client
    ///     .relations()
    ///     .create(
    ///         IssueRef::identifier("ENG-1"),
    ///         IssueRef::identifier("ENG-2"),
    ///         IssueRelationType::Blocks,
    ///     )
    ///     .await?;
    /// assert_eq!(relation.issue.identifier, "ENG-1");
    /// # Ok(()) }
    /// ```
    pub async fn create(
        &self,
        issue: impl Into<IssueRef>,
        related: impl Into<IssueRef>,
        relation_type: IssueRelationType,
    ) -> Result<IssueRelation> {
        #[derive(Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct Payload {
            success: bool,
            issue_relation: Option<IssueRelation>,
        }
        #[derive(Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct Data {
            issue_relation_create: Payload,
        }

        let input = CreateVarsInput {
            issue_id: issue.into().api_string().to_owned(),
            related_issue_id: related.into().api_string().to_owned(),
            relation_type,
        };
        let payload = self
            .client
            .mutation::<_, Data>(
                "IssueRelationCreate",
                ISSUE_RELATION_CREATE,
                serde_json::json!({ "input": input }),
            )
            .await?
            .issue_relation_create;
        ensure_success("IssueRelationCreate", payload.success)?;
        payload.issue_relation.ok_or(Error::MissingData {
            operation: "IssueRelationCreate",
        })
    }

    /// Records that `blocker` **blocks** `blocked` — shorthand for
    /// [`create(blocker, blocked, Blocks)`](Self::create) with the direction
    /// spelled out in the parameter names.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// use linear_api::{IssueRef, LinearClient};
    ///
    /// let client = LinearClient::from_env()?;
    /// // ENG-2 cannot start until ENG-1 is done:
    /// client
    ///     .relations()
    ///     .create_blocks(
    ///         IssueRef::identifier("ENG-1"), // blocker
    ///         IssueRef::identifier("ENG-2"), // blocked
    ///     )
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub async fn create_blocks(
        &self,
        blocker: impl Into<IssueRef>,
        blocked: impl Into<IssueRef>,
    ) -> Result<IssueRelation> {
        self.create(blocker, blocked, IssueRelationType::Blocks)
            .await
    }

    /// Deletes a relation edge by its ID.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// use linear_api::{IssueRef, LinearClient};
    ///
    /// let client = LinearClient::from_env()?;
    /// let relations = client
    ///     .relations()
    ///     .of_issue(IssueRef::identifier("ENG-3"))
    ///     .await?;
    /// if let Some(edge) = relations.outgoing.first() {
    ///     client.relations().delete(&edge.id).await?;
    /// }
    /// # Ok(()) }
    /// ```
    pub async fn delete(&self, id: &IssueRelationId) -> Result<()> {
        #[derive(Deserialize)]
        struct Payload {
            success: bool,
        }
        #[derive(Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct Data {
            issue_relation_delete: Payload,
        }

        let data = self
            .client
            .mutation::<_, Data>(
                "IssueRelationDelete",
                ISSUE_RELATION_DELETE,
                serde_json::json!({ "id": id }),
            )
            .await?;
        ensure_success("IssueRelationDelete", data.issue_relation_delete.success)
    }

    /// Fetches both directions of an issue's relation edges: `outgoing` =
    /// `Issue.relations` (this issue is the source), `incoming` =
    /// `Issue.inverseRelations` (this issue is the target).
    ///
    /// Fetches up to 50 edges per direction and does **not** paginate —
    /// far beyond any sane card's edge count. Accepts a UUID or a human
    /// identifier via [`IssueRef::identifier`].
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// let client = linear_api::LinearClient::from_env()?;
    /// let relations = client
    ///     .relations()
    ///     .of_issue(linear_api::IssueRef::identifier("ENG-3"))
    ///     .await?;
    /// println!(
    ///     "blocks {} issue(s), blocked by {}",
    ///     relations.blocks().len(),
    ///     relations.blocked_by().len(),
    /// );
    /// # Ok(()) }
    /// ```
    pub async fn of_issue(&self, issue: impl Into<IssueRef>) -> Result<IssueRelations> {
        #[derive(Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct IssueNode {
            #[serde(deserialize_with = "crate::types::nodes")]
            relations: Vec<IssueRelation>,
            #[serde(deserialize_with = "crate::types::nodes")]
            inverse_relations: Vec<IssueRelation>,
        }
        #[derive(Deserialize)]
        struct Data {
            issue: IssueNode,
        }

        let data = self
            .client
            .query::<_, Data>(
                "IssueRelationsOf",
                ISSUE_RELATIONS_OF,
                serde_json::json!({ "id": issue.into().api_string() }),
            )
            .await?;
        Ok(IssueRelations {
            outgoing: data.issue.relations,
            incoming: data.issue.inverse_relations,
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::ids::IssueId;

    #[test]
    fn create_input_wire_shape() {
        let input = CreateVarsInput {
            issue_id: IssueRef::identifier("ENG-1").api_string().to_owned(),
            related_issue_id: IssueRef::from(IssueId::new("uuid-2"))
                .api_string()
                .to_owned(),
            relation_type: IssueRelationType::Blocks,
        };
        assert_eq!(
            serde_json::to_value(&input).unwrap(),
            serde_json::json!({
                "issueId": "ENG-1",
                "relatedIssueId": "uuid-2",
                "type": "blocks"
            })
        );
    }

    #[test]
    fn blocks_and_blocked_by_filter_by_type_and_direction() {
        let stub = |identifier: &str| IssueStub {
            id: IssueId::new(format!("uuid-{identifier}")),
            identifier: identifier.to_owned(),
            title: format!("Issue {identifier}"),
        };
        let edge = |relation_type: IssueRelationType, from: &str, to: &str| IssueRelation {
            id: IssueRelationId::new(format!("rel-{from}-{to}")),
            relation_type,
            issue: stub(from),
            related_issue: stub(to),
        };
        let relations = IssueRelations {
            outgoing: vec![
                edge(IssueRelationType::Blocks, "ENG-3", "ENG-4"),
                edge(IssueRelationType::Related, "ENG-3", "ENG-5"),
            ],
            incoming: vec![
                edge(IssueRelationType::Blocks, "ENG-2", "ENG-3"),
                edge(IssueRelationType::Duplicate, "ENG-6", "ENG-3"),
            ],
        };

        let blocks: Vec<&str> = relations
            .blocks()
            .iter()
            .map(|s| s.identifier.as_str())
            .collect();
        assert_eq!(blocks, vec!["ENG-4"]);

        let blocked_by: Vec<&str> = relations
            .blocked_by()
            .iter()
            .map(|s| s.identifier.as_str())
            .collect();
        assert_eq!(blocked_by, vec!["ENG-2"]);
    }
}