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-KEYfor 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/twgpackage 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, andRFC-2119from causing failed Jira reads.
- This prevents ordinary tokens such as
- 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.
- Nearer work takes priority under
- 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
statssummary 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 buildpnpm test:docs/pnpm check:docs— 96 tests passedpnpm test:packageunder Node 24 — 48 package smoke commands passedpnpm 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
crawlGraphminimum-depth admission and node-cap behavior- Jira normalization and confidence-aware edge traversal
- TWG output compatibility and temporary-file cleanup
- Markdown and URL safety boundaries
Activity
21@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-8andSHA-1from 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!
Hey @abhinavbansal19961996 looks awesome, will review it this weekend, thank!
Hey @abhinavbansal19961996 looks awesome, will review it this weekend, thank!
Thanks @Railly
PR was merged due to which there was merge conflict @Railly Resolved merge conflicts. You can r/a whenever you get time.
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!
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
@abhinavbansal19961996 will pick this up this week ;)
@abhinavbansal19961996 is attempting to deploy a commit to the Vercel Labs Team on Vercel.
A member of the Team first needs to authorize it.