Issue Hierarchy Tracking

Relevant source files

The following files were used as context for generating this wiki page:

• src/entries/background/handlers/hierarchy-handlers.ts
• src/entries/background/helpers.ts
• src/lib/graphql/queries.ts
• src/lib/graphql/mutations.ts
• src/components/bulk/bulk-edit-modal.tsx
• src/components/bulk/bulk-duplicate-modal.tsx
• README.md

Issue Hierarchy Tracking is a core feature of the Refined GitHub Projects extension that enables developers to visualize and manage complex relationships between GitHub issues. It extends the native GitHub Projects V2 capabilities by providing deep visibility into parent-child relationships (sub-issues), blocking dependencies, and project-specific field contexts.

The system allows users to perform bulk updates on these relationships, validate them against circular dependencies, and preserve hierarchies during "Deep Duplication" operations. This ensures that the structural integrity of a project's task breakdown is maintained even when moving or cloning large sets of items.
Sources: README.md:82-82, src/entries/background/handlers/hierarchy-handlers.ts:167-196

Architecture and Data Flow

The hierarchy system operates through a distributed architecture involving the content script (UI), a background service worker (logic and queue management), and the GitHub GraphQL/REST APIs.

Request Flow

When a user requests hierarchy data or attempts a relationship modification, the following flow occurs:

1. ID Resolution: DOM-extracted IDs (e.g., issue:123) are resolved into global GitHub Node IDs using the resolveProjectItemIds helper.
2. Concurrent Data Fetching: The system fetches sub-issues, "blocked by" relationships, and "blocking" relationships in parallel using Promise.all to minimize latency.
3. Validation: For bulk updates, the background script validates the requested changes to prevent issues from blocking themselves or creating invalid parent loops.
4. Sequential Execution: Mutations are processed through a sequential background queue with a 1-second delay to comply with GitHub's secondary rate limits.

Sources: src/entries/background/helpers.ts:476-559, src/entries/background/handlers/hierarchy-handlers.ts:167-184, src/entries/background/handlers/hierarchy-handlers.ts:192-196

System Sequence Diagram

The diagram below illustrates the sequence of messages and API calls required to fetch and resolve hierarchy data for a project item.

Relationship Types

The system tracks and manages three distinct types of relationships for issues:

Relationship	Implementation	Description
Parent	issue.parent	The primary hierarchical container for an issue (sub-issue relationship).
Blocked By	/dependencies/blocked_by	Issues that must be completed before the current issue can proceed.
Blocking	/dependencies/blocking	Issues that are dependent on the completion of the current issue.

Sources: src/entries/background/handlers/hierarchy-handlers.ts:171-196, src/lib/graphql/queries.ts:24-34

Data Structure: HierarchyData

The background handler returns a consolidated HierarchyData object to the UI components.

interface HierarchyData {
  resolvedItemId: string;
  issueNumber: number;
  repoOwner: string;
  repoName: string;
  parent?: IssueRelationshipData;
  subIssues: SubIssueData[];
  totalSubIssues: number;
  completedSubIssues: number;
  blockedBy: IssueRelationshipData[];
  blocking: IssueRelationshipData[];
}

Sources: src/entries/background/handlers/hierarchy-handlers.ts:187-198

Bulk Relationship Management

The BulkEditWizard and BulkDuplicateModal components allow for mass-modification of hierarchies.

Validation Logic

Before applying bulk changes, the getBulkRelationshipValidationErrors function checks for:

• Self-Parenting: An issue cannot be its own parent.
• Self-Blocking: An issue cannot block itself.
• Mutual Blocking: An issue cannot both block and be blocked by the same issue simultaneously.

Sources: src/entries/background/helpers.ts:279-354

Execution Queue

Mutations are never executed in parallel. The system builds a series of QueueTask objects that are run sequentially.

Deep Duplication Support

Hierarchy tracking is critical during the "Deep Duplicate" flow. Unlike GitHub's native duplication, this system allows users to clone the entire relationship tree of an issue.

• Parent Preservation: The duplicated issue can be automatically linked to the same parent as the original.
• Dependency Cloning: Users can choose to carry over all "Blocked by" and "Blocking" relationships to the new item.
• Implementation: The runDeepDuplicate handler creates the new issue first, then executes separate mutations to ADD_SUB_ISSUE and githubRest calls for dependencies.

Sources: src/entries/background/handlers/duplicate-handlers.ts:114-142, src/components/bulk/bulk-duplicate-modal.tsx:488-518

Summary

Issue Hierarchy Tracking in Refined GitHub Projects provides a robust framework for managing complex issue structures. By combining GraphQL for metadata and REST for advanced dependencies, it offers a level of visibility and control not natively available in GitHub Projects V2. The system's emphasis on validation and sequential execution ensures project data remains consistent and free from rate-limiting penalties.