#20

feat(jira): add read-only issue graphs through TWG

Openabhinavbansal19961996wants to merge intofrom

Why

issue-graph currently traces GitHub issues and pull requests, but teams may track related work in Jira. This adds a read-only Jira workflow using the customer-facing Atlassian Teamwork Graph CLI (twg) while preserving the existing GitHub behavior.

What changed

  • Add issue-graph jira ISSUE-KEY for Jira relationship discovery through TWG.
  • Add crawlGraph, a source-neutral bounded graph traversal API.
  • Preserve minimum-depth BFS ordering when source policies jump directly to a depth boundary.
  • Support explicit Atlassian site selection with --site.
  • Emit Markdown in terminals and versioned JSON in pipes.
  • Add the Node-only issue-graph/transport/twg package export.
  • Document Jira setup, permissions, coverage, privacy, library usage, and agent workflows.

Traversal behavior

  • Same-project references recurse to --depth.
  • Structured cross-project issue links and remote links are fetched as one-hop boundaries.
  • Cross-project keys found only in free text are reported but not fetched.
    • This prevents ordinary tokens such as UTF-8, SHA-1, ISO-8601, and RFC-2119 from causing failed Jira reads.
  • Pending nodes are processed by minimum known depth.
    • Nearer work takes priority under --max-nodes.
    • A later shorter path lowers a pending node before it is fetched.
  • Non-Jira remote links are reported but not fetched.
  • Failed reads and capped nodes remain explicit coverage evidence.

TWG compatibility

The transport supports customer TWG builds that either:

  • return raw JSON with summary output disabled, or
  • reject that option and provide JSON through a stats summary file.

Summary files are read and removed immediately.

Safety and privacy

  • Read-only: does not create, edit, transition, or comment on Jira work items.
  • Does not install TWG or read/store Atlassian tokens.
  • Jira mode creates no issue-graph snapshots.
  • Inaccessible work items remain explicit failed nodes rather than being treated as absent.
  • Markdown output escapes untrusted Jira values.
  • Link destinations are parsed, restricted to HTTP(S), normalized, and safely rendered.
  • Live validation used private input only; no customer identifiers or Jira content are retained in this change.

Verification

  • pnpm check — 635 tests passed, plus lint, typecheck, and build
  • pnpm test:docs / pnpm check:docs — 96 tests passed
  • pnpm test:package under Node 24 — 48 package smoke commands passed
  • pnpm build:docs — production documentation build passed
  • Read-only live smoke validation passed with a one-node/depth-zero boundary
  • All commits are SSH-signed and shown as Verified by GitHub

Review focus

  1. crawlGraph minimum-depth admission and node-cap behavior
  2. Jira normalization and confidence-aware edge traversal
  3. TWG output compatibility and temporary-file cleanup
  4. Markdown and URL safety boundaries

Activity

21
vercel[bot]1mo ago

@abhinavbansal19961996 is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

vercel[bot]reviewed1mo ago
vercel[bot]reviewed1mo ago
abhinavbansal19961996reviewed1mo ago
abhinavbansal199619961mo ago

@Railly When you have time, could you please review this contribution?

It adds read-only Jira issue graphs through the customer-facing TWG CLI. I’ve addressed the automated review findings:

  • preserved minimum-depth BFS ordering under node caps
  • prevented cross-project text matches such as UTF-8 and SHA-1 from triggering failed Jira reads
  • escaped untrusted Jira Markdown values and normalized HTTP(S) links
  • added compatibility for different TWG summary-output behaviors
  • ensured temporary TWG output files are removed

Verification is green:

  • 635 source tests
  • 96 docs tests
  • 48 package smoke commands
  • production docs build
  • all commits are signed and Verified

The Vercel preview appears to require Vercel Labs team authorization; please authorize it if a preview is useful for review. Thanks!

vercel[bot]reviewed1mo ago
abhinavbansal19961996reviewed1mo ago
vercel[bot]reviewed1mo ago
Railly1mo ago

Hey @abhinavbansal19961996 looks awesome, will review it this weekend, thank!

abhinavbansal199619961mo ago

Hey @abhinavbansal19961996 looks awesome, will review it this weekend, thank!

Thanks @Railly

abhinavbansal199619961mo ago

PR was merged due to which there was merge conflict @Railly Resolved merge conflicts. You can r/a whenever you get time.

Railly1mo ago

hey @abhinavbansal19961996 I've been doing a huge refactor, and we plan to add linear integration first, then on top of that abstraction, we'll launch jira, and give you proper credits! thanks! will let you know once the linear one is launched!

abhinavbansal199619961mo ago

hey @abhinavbansal19961996 I've been doing a huge refactor, and we plan to add linear integration first, then on top of that abstraction, we'll launch jira, and give you proper credits! thanks! will let you know once the linear one is launched!

Makes sense thanks @Railly

Railly5d ago

@abhinavbansal19961996 will pick this up this week ;)