issues.graphql

# ------------------------------------------------------------
# Optimized GraphQL queries for issue operations
#
# This module contains highly optimized GraphQL queries that fetch
# all necessary issue data in single requests, eliminating N+1 query
# problem common with Linear SDK. Each query uses comprehensive
# fragments to ensure consistent data structures.
# ------------------------------------------------------------

# Complete issue fragment with all relationships
#
# Combines all issue fragments into a comprehensive field selection.
# This is used when full issue details are needed including all
# relationships (state, assignee, team, project, labels, comments).
fragment CompleteIssueFields on Issue {
  id
  identifier
  title
  description
  branchName
  priority
  estimate
  dueDate
  createdAt
  updatedAt
  state {
    id
    name
  }
  assignee {
    id
    name
  }
  team {
    id
    key
    name
  }
  project {
    id
    name
  }
  labels {
    nodes {
      id
      name
    }
  }
  cycle {
    id
    name
    number
  }
  projectMilestone {
    id
    name
    targetDate
  }
  parent {
    id
    identifier
    title
  }
  children {
    nodes {
      id
      identifier
      title
    }
  }
  relations {
    nodes {
      id
      type
      relatedIssue {
        id
        identifier
      }
    }
  }
  inverseRelations {
    nodes {
      id
      type
      issue {
        id
        identifier
      }
    }
  }
}

# Minimal comment fields preserved for default issue reads
fragment IssueReadDefaultCommentFields on Comment {
  id
  body
}

# Comment fields for issue read discussion expansion
fragment IssueReadCommentFields on Comment {
  id
  body
  createdAt
  editedAt
  parentId
  user {
    id
    displayName
  }
}

# Complete issue fragment with all relationships and default comments
#
# Preserves the historical issue read payload while keeping richer
# discussion metadata behind explicit flags.
fragment CompleteIssueWithDefaultCommentsFields on Issue {
  ...CompleteIssueFields
  comments {
    nodes {
      ...IssueReadDefaultCommentFields
    }
  }
}

# Complete issue fragment with all relationships and comments
#
# Combines all issue fragments into a comprehensive field selection.
# This is used when full issue details are needed including all
# relationships (state, assignee, team, project, labels, comments).
fragment CompleteIssueWithCommentsFields on Issue {
  ...CompleteIssueFields
  comments {
    nodes {
      ...IssueReadCommentFields
    }
  }
}

# Complete issue search fragment with all relationships
#
# Combines all issue fragments into a comprehensive field selection.
# This is used when full issue details are needed including all
# relationships (state, assignee, team, project, labels, comments).
fragment CompleteIssueSearchFields on IssueSearchResult {
  id
  identifier
  title
  description
  branchName
  priority
  estimate
  dueDate
  createdAt
  updatedAt
  state {
    id
    name
  }
  assignee {
    id
    name
  }
  team {
    id
    key
    name
  }
  project {
    id
    name
  }
  labels {
    nodes {
      id
      name
    }
  }
  cycle {
    id
    name
    number
  }
  projectMilestone {
    id
    name
    targetDate
  }
  parent {
    id
    identifier
    title
  }
  children {
    nodes {
      id
      identifier
      title
    }
  }
  relations {
    nodes {
      id
      type
      relatedIssue {
        id
        identifier
      }
    }
  }
  inverseRelations {
    nodes {
      id
      type
      issue {
        id
        identifier
      }
    }
  }
}

# Get issues list with all relationships in single query
#
# Fetches paginated issues excluding completed ones,
# ordered by most recently updated. Includes all relationships
# for comprehensive issue data.
query GetIssues($first: Int!, $after: String, $orderBy: PaginationOrderBy) {
  issues(
    first: $first
    after: $after
    orderBy: $orderBy
    filter: { state: { type: { neq: "completed" } } }
  ) {
    nodes {
      ...CompleteIssueFields
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Get single issue by UUID with lean fields
#
# Fetches issue data by direct UUID lookup with the backward-compatible
# default comment payload.
query GetIssueById($id: String!) {
  issue(id: $id) {
    ...CompleteIssueWithDefaultCommentsFields
  }
}

# Get issue by identifier (team key + number) with lean fields
#
# Fetches issue using TEAM-123 format with the backward-compatible
# default comment payload.
query GetIssueByIdentifier($teamKey: String!, $number: Float!) {
  issues(
    filter: { team: { key: { eq: $teamKey } }, number: { eq: $number } }
    first: 1
  ) {
    nodes {
      ...CompleteIssueWithDefaultCommentsFields
    }
  }
}

# Get single issue by UUID with full comments
query GetIssueByIdWithComments($id: String!) {
  issue(id: $id) {
    ...CompleteIssueWithCommentsFields
  }
}

# Get issue by identifier with full comments
query GetIssueByIdentifierWithComments($teamKey: String!, $number: Float!) {
  issues(
    filter: { team: { key: { eq: $teamKey } }, number: { eq: $number } }
    first: 1
  ) {
    nodes {
      ...CompleteIssueWithCommentsFields
    }
  }
}

# Get issue team by issue ID
#
# Fetches the team associated with an issue by its ID.
query GetIssueTeam($issueId: String!) {
  issue(id: $issueId) {
    team {
      id
    }
  }
}

# Search issues with text search and all relationships in single query
#
# Provides full-text search across Linear issues with complete
# relationship data for each match.
query SearchIssues(
  $term: String!
  $first: Int!
  $after: String
  $filter: IssueFilter
) {
  searchIssues(
    term: $term
    first: $first
    after: $after
    filter: $filter
    includeArchived: false
  ) {
    nodes {
      ...CompleteIssueSearchFields
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Search issues with advanced filters and all relationships in single query
#
# Supports filtering by team, assignee, project, and states.
# Used by the advanced search functionality with multiple criteria.
query FilteredSearchIssues(
  $first: Int!
  $after: String
  $filter: IssueFilter
  $orderBy: PaginationOrderBy
) {
  issues(
    first: $first
    after: $after
    filter: $filter
    orderBy: $orderBy
    includeArchived: false
  ) {
    nodes {
      ...CompleteIssueFields
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Comprehensive batch resolve for update operations
#
# Resolves all necessary entity references in a single batch query
# before issue update. Includes labels, projects, teams, and parent issues.
# This prevents N+1 queries during update operations.
query BatchResolveForUpdate(
  $labelNames: [String!]
  $projectName: String
  $teamKey: String
  $issueNumber: Float
  $milestoneName: String
) {
  # Resolve labels if provided
  labels: issueLabels(filter: { name: { in: $labelNames } }) {
    nodes {
      id
      name
      isGroup
      parent {
        id
        name
      }
      children {
        nodes {
          id
          name
        }
      }
    }
  }

  # Resolve project if provided (case-insensitive to be user-friendly)
  projects(filter: { name: { eqIgnoreCase: $projectName } }, first: 1) {
    nodes {
      id
      name
      projectMilestones {
        nodes {
          id
          name
        }
      }
    }
  }

  # Resolve milestone if provided (standalone query in case no project context)
  milestones: projectMilestones(
    filter: { name: { eq: $milestoneName } }
    first: 1
  ) {
    nodes {
      id
      name
    }
  }

  # Resolve issue identifier if provided
  issues(
    filter: {
      and: [
        { team: { key: { eq: $teamKey } } }
        { number: { eq: $issueNumber } }
      ]
    }
    first: 1
  ) {
    nodes {
      id
      identifier
      labels {
        nodes {
          id
          name
        }
      }
      team {
        id
        key
        name
      }
      project {
        id
        projectMilestones {
          nodes {
            id
            name
          }
        }
      }
    }
  }
}

# Comprehensive batch resolve for create operations
#
# Resolves all entity references needed for issue creation in a single
# batch query. Prevents N+1 queries during issue creation by
# pre-resolving teams, projects, labels, and parent issues.
query BatchResolveForCreate(
  $teamKey: String
  $teamName: String
  $projectName: String
  $labelNames: [String!]
  $parentTeamKey: String
  $parentIssueNumber: Float
) {
  # Resolve team if provided
  teams(
    filter: { or: [{ key: { eq: $teamKey } }, { name: { eq: $teamName } }] }
    first: 1
  ) {
    nodes {
      id
      key
      name
    }
  }

  # Resolve project if provided (case-insensitive to be user-friendly)
  projects(filter: { name: { eqIgnoreCase: $projectName } }, first: 1) {
    nodes {
      id
      name
      projectMilestones {
        nodes {
          id
          name
        }
      }
      # Projects don't own cycles directly, but include teams for context if needed
    }
  }

  # Resolve labels if provided
  labels: issueLabels(filter: { name: { in: $labelNames } }) {
    nodes {
      id
      name
      isGroup
      parent {
        id
        name
      }
      children {
        nodes {
          id
          name
        }
      }
    }
  }

  # Resolve parent issue if provided
  parentIssues: issues(
    filter: {
      and: [
        { team: { key: { eq: $parentTeamKey } } }
        { number: { eq: $parentIssueNumber } }
      ]
    }
    first: 1
  ) {
    nodes {
      id
      identifier
    }
  }

  # Resolve cycles by name (team-scoped lookup is preferred but we also provide global fallback)
}

# Complete issue fragment with attachments
fragment CompleteIssueWithAttachmentsFields on Issue {
  ...CompleteIssueWithDefaultCommentsFields
  attachments {
    nodes {
      ...AttachmentFields
    }
  }
}

# Get single issue by UUID with attachments
query GetIssueByIdWithAttachments($id: String!) {
  issue(id: $id) {
    ...CompleteIssueWithAttachmentsFields
  }
}

# Get issue by identifier with attachments
query GetIssueByIdentifierWithAttachments($teamKey: String!, $number: Float!) {
  issues(
    filter: { team: { key: { eq: $teamKey } }, number: { eq: $number } }
    first: 1
  ) {
    nodes {
      ...CompleteIssueWithAttachmentsFields
    }
  }
}