graph

Documentation

Overview

Package graph is a pure in-memory model of the Jira issue graph discovered during a gojira crawl. It exposes a Collector that accumulates nodes and edges from parsed Jira issues plus their extracted outbound references, and two renderers — RenderJSON (machine-readable) and RenderD2 (the D2 diagram language source).

The package is deliberately pure: no I/O, no network, no project- internal imports beyond the parse/extract/classify data carriers. Callers (internal/crawl) are responsible for persisting the rendered output. Both renderers produce deterministic, sorted output so they are safe to use as golden-test fixtures.

Index

• func RenderD2(m Model) (string, error)
• func RenderJSON(m Model) ([]byte, error)
• type Collector
  • func NewCollector() *Collector
  • func (c *Collector) Add(issue parse.Issue, refs []extract.Reference)
  • func (c *Collector) MarkFetched(key string)
  • func (c *Collector) Model() Model
• type Edge
• type EdgeKind
• type Model
• type Node
• type NodeKind

Functions

func RenderD2

func RenderD2(m Model) (string, error)

RenderD2 returns valid D2 source describing m. The output:

• starts with a comment header documenting how to render the file,
• declares one D2 shape per node with a quoted key + quoted label,
• declares one D2 connection per edge in deterministic order.

func RenderJSON

func RenderJSON(m Model) ([]byte, error)

RenderJSON returns the indented JSON representation of m. The output is deterministic because Model() pre-sorts.

Types

type Collector

type Collector struct {
	// contains filtered or unexported fields
}

Collector accumulates nodes and edges as issues are processed. Methods are NOT safe for concurrent use; callers must serialize access (the crawler invokes the collector while holding c.mu).

func NewCollector

func NewCollector() *Collector

NewCollector returns an empty Collector ready to accumulate.

func (*Collector) Add

func (c *Collector) Add(issue parse.Issue, refs []extract.Reference)

Add records issue and all relationships derived from issue + refs. Calling Add for an issue.Key implies that issue was fetched (sets Fetched=true and populates the issue-node metadata).

func (*Collector) MarkFetched

func (c *Collector) MarkFetched(key string)

MarkFetched records that an issue was actually fetched. It creates a placeholder issue node if none exists yet, or flips an existing referenced placeholder to Fetched=true.

func (*Collector) Model

func (c *Collector) Model() Model

Model returns the assembled, deterministic Model. It is safe to call multiple times; each call produces an independently-sorted snapshot.

type Edge

type Edge struct {
	From  string   `json:"from"`
	To    string   `json:"to"`
	Kind  EdgeKind `json:"kind"`
	Label string   `json:"label,omitempty"`
}

Edge is a directed relationship between two nodes.

type EdgeKind

type EdgeKind string

EdgeKind labels the kind of a graph edge.

const (
	// EdgeParent connects an issue to its parent issue.
	EdgeParent EdgeKind = "parent"
	// EdgeSubtask connects an issue to one of its subtasks.
	EdgeSubtask EdgeKind = "subtask"
	// EdgeChild connects an issue to a hierarchy child discovered via JQL.
	EdgeChild EdgeKind = "child"
	// EdgeLink connects two issues via a structured Jira issue link.
	EdgeLink EdgeKind = "link"
	// EdgeRemote connects an issue to one of its remote (external) links.
	EdgeRemote EdgeKind = "remote"
	// EdgeDescription connects an issue to a reference found in its description body.
	EdgeDescription EdgeKind = "description"
	// EdgePullRequest connects an issue to a GitHub pull request node.
	EdgePullRequest EdgeKind = "pull_request"
	// EdgeExternal connects an issue to an external (non-Jira / non-PR) URL.
	EdgeExternal EdgeKind = "external"
)

type Model

type Model struct {
	Nodes []Node
	Edges []Edge
}

Model is the assembled, deterministic result of a Collector run. Nodes are sorted by ID; Edges are sorted by (From, To, Kind, Label).

type Node

type Node struct {
	// ID is the canonical, unique identifier. Issue: UPPER issue key
	// ("PROJ-1"). GitHub PR: "owner/repo#N" when parseable, else the URL.
	// External: the URL itself.
	ID   string   `json:"id"`
	Kind NodeKind `json:"kind"`
	// Label is the human-readable label used in the D2 diagram.
	Label string `json:"label"`
	// Issue-only optional metadata; omitted when zero.
	Status   string `json:"status,omitempty"`
	Type     string `json:"type,omitempty"`
	Assignee string `json:"assignee,omitempty"`
	URL      string `json:"url,omitempty"`
	// Fetched is true if this issue was actually fetched/rendered in
	// the crawl; false for nodes that exist only as references from
	// other issues. PR/external nodes are always false.
	Fetched bool `json:"fetched"`
}

Node is a single graph node.

type NodeKind

type NodeKind string

NodeKind labels the kind of a graph node.

const (
	// NodeIssue is a Jira issue node, identified by its UPPER issue key.
	NodeIssue NodeKind = "issue"

	// NodeGitHubPR is a GitHub pull request node, identified by
	// "owner/repo#N" when the URL is parseable, or by its raw URL otherwise.
	NodeGitHubPR NodeKind = "github_pr"

	// NodeExternal is any other URL reference, identified by the URL itself.
	NodeExternal NodeKind = "external"
)