graphjson

package
v0.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 12, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package graphjson renders graph.json — the PRIMARY machine-/LLM-queryable artifact: a compact, schemaVersion-stamped, fully parseable manifest of the analyzed corpus (nodes, edges, sections, components, HITS, and every gap/ orphan/broken-link signal). It is infrastructure: it reads the frozen emit.View + graphmodel + corpus and never mutates the domain (ADR 0004).

Determinism contract: the schema is struct-defined (stable field order) and every slice is sorted. HITS hub/authority scores are floats — Go map iteration is randomized and float text can vary — so they are formatted at a FIXED precision (HITSFloatPrecision decimals) into a typed Float so output is byte-stable across runs. See the package test for the round-trip + stability proofs and docs/schemas/graph.schema.json for the published contract.

Index

Constants

View Source 
const GraphJSONName = "graph.json"

GraphJSONName is the conventional graph.json filename.

View Source 
const HITSFloatPrecision = 6

HITSFloatPrecision is the FIXED number of decimal places HITS hub/authority scores are rounded to in graph.json. HITS scores are L2-normalized into [0,1] and the power iteration converges to ~1e-8 (hits.go), so 6 decimals preserves all signal while guaranteeing byte-stable text: 'f' format with a fixed precision never emits exponent notation or run-dependent trailing digits. The P3 panel flagged float formatting as the determinism risk; this is the fix.

View Source 
const SchemaVersion = 7

SchemaVersion is the graph.json schema version. Additive fields are backward-compatible; renaming/removing a field bumps this. It is mirrored by docs/schemas/graph.schema.json (kept in lockstep; a test validates against it). v2 (ADR 0012) adds per-node bowtie/underLinked/deadEnd, top-level underLinked/ deadEnd arrays, a bowtie summary, and underLinked/deadEnd summary counts. v3 (ADR 0013) adds the top-level suggestedLinks array (topology-based link-prediction suggestions) and a suggestedLinks summary count. v4 (ADR 0014) adds a summary.navigability object (compactness, stratum, characteristic/median path length, clustering coefficient, diameter, reachablePairs) — corpus-level navigability scalars, pure data. v5 (ADR 0015) adds critical-path analysis: per-node betweenness (number) and isArticulation (bool); a top-level betweenness object {topDocs:[{id,score}]}; top-level articulationPoints ([]string) and bridges ([]{from,to}); and summary.articulationPoints / summary.bridges counts — all pure data. v6 (ADR 0016) adds PageRank: a per-node pageRank (number) and a top-level pageRank object {topDocs:[{id,score}]} parallel to betweenness — pure data. v7 (ADR 0021) adds hops-from-root: a per-node hopsFromRoot (integer, -1 for unreachable docs and for every node when the root set is indeterminate), a top-level farFromRoot ([]string) of docs at/beyond the hop-distance threshold, and a summary.farFromRoot count — all pure data.

Variables

This section is empty.

Functions

func JSON 

func JSON(v emit.View) ([]byte, error)

JSON renders the View as the canonical graph.json bytes (pretty-printed, trailing newline). Deterministic: struct field order + sorted slices + fixed float precision. The hostile-title fixture test asserts encoding/json escapes node titles/paths (they are JSON string values, never interpolated).

Types

type Ambiguous 

type Ambiguous struct {
	File       string   `json:"file"`
	Line       int      `json:"line"`
	Target     string   `json:"target"`
	Candidates []string `json:"candidates"`
	Detail     string   `json:"detail"`
}

Ambiguous is a reference that matched more than one candidate document.

type Betweenness 

type Betweenness struct {
	TopDocs []Ranked `json:"topDocs"`
}

Betweenness holds the top load-bearing documents by betweenness centrality (ADR 0015), parallel to the HITS block. Scores use the fixed-precision Float type so graph.json is byte-stable.

type BowtieSummary 

type BowtieSummary struct {
	Core         int    `json:"core"`
	In           int    `json:"in"`
	Out          int    `json:"out"`
	Tendril      int    `json:"tendril"`
	Disconnected int    `json:"disconnected"`
	GiantSCC     string `json:"giantScc"`
	GiantSCCSize int    `json:"giantSccSize"`
}

BowtieSummary is the corpus-level bow-tie tally relative to the giant SCC (the "core"): the per-bucket document counts plus the giant SCC's ID and size. A giantSCCSize of 1 means the corpus has no cyclic core (every SCC is a singleton); the buckets are still populated deterministically (ADR 0012).

type Bridge 

type Bridge struct {
	From string `json:"from"`
	To   string `json:"to"`
}

Bridge is a cut edge of the undirected closure (ADR 0015): the only link between two parts of the corpus. from < to canonically.

type BrokenAnchor 

type BrokenAnchor struct {
	File         string `json:"file"`
	Line         int    `json:"line"`
	Target       string `json:"target"`
	ExpectedSlug string `json:"expectedSlug"`
	Detail       string `json:"detail"`
}

BrokenAnchor is a reference whose document resolved but the anchor did not. 

type BrokenLink struct {
	File   string `json:"file"`
	Line   int    `json:"line"`
	Target string `json:"target"`
	Detail string `json:"detail"`
}

BrokenLink is a reference whose target does not resolve to a corpus document.

type Component 

type Component struct {
	ID      string   `json:"id"`
	Members []string `json:"members"`
}

Component is one component: its ID (sorted-min member) and sorted members.

type Components 

type Components struct {
	WCC []Component `json:"wcc"`
	SCC []Component `json:"scc"`
}

Components groups documents by weak (WCC) and strong (SCC) component.

type Document 

type Document struct {
	SchemaVersion int       `json:"schemaVersion"`
	Tool          string    `json:"tool"`
	GeneratedNote string    `json:"generatedNote"`
	Summary       Summary   `json:"summary"`
	Nodes         []Node    `json:"nodes"`
	Edges         []Edge    `json:"edges"`
	Sections      []Section `json:"sections"`
	Orphans       []string  `json:"orphans"`
	Unreachable   []string  `json:"unreachable"`
	UnderLinked   []string  `json:"underLinked"`
	DeadEnd       []string  `json:"deadEnd"`
	// FarFromRoot are documents reachable but at/beyond the hop-distance threshold
	// from every root (ADR 0021): reachable but hard to discover by link
	// traversal. Sorted DocumentIDs; empty when reachability is indeterminate.
	FarFromRoot    []string        `json:"farFromRoot"`
	Bowtie         BowtieSummary   `json:"bowtie"`
	BrokenLinks    []BrokenLink    `json:"brokenLinks"`
	BrokenAnchors  []BrokenAnchor  `json:"brokenAnchors"`
	Ambiguous      []Ambiguous     `json:"ambiguous"`
	Components     Components      `json:"components"`
	HITS           HITS            `json:"hits"`
	Betweenness    Betweenness     `json:"betweenness"`
	PageRank       PageRank        `json:"pageRank"`
	Gaps           []Gap           `json:"gaps"`
	SuggestedLinks []SuggestedLink `json:"suggestedLinks"`
	// ArticulationPoints are cut vertices; Bridges are cut edges of the undirected
	// closure (ADR 0015) — the corpus' single points of failure, pure data.
	ArticulationPoints []string     `json:"articulationPoints"`
	Bridges            []Bridge     `json:"bridges"`
	RootSet            []string     `json:"rootSet"`
	Reachability       Reachability `json:"reachability"`
}

Document is the top-level graph.json shape. Field order is the wire order (encoding/json preserves struct field order); every slice field is sorted.

func Build 

func Build(v emit.View) Document

Build assembles the typed graph.json Document from the frozen View. A View with no metrics/corpus yields a valid empty-but-stamped document.

type Edge 

type Edge struct {
	From   string `json:"from"`
	To     string `json:"to"`
	Type   string `json:"type"`
	Health string `json:"health"`
}

Edge is a directed document-projection navigational edge. Health is always "valid" here: the projection retains only resolved in-corpus edges (ADR 0007); unresolved targets are reported in brokenLinks/brokenAnchors instead.

type Float 

type Float float64

Float is a float64 that marshals as a JSON number with FIXED precision so graph.json is byte-stable. It round-trips: it unmarshals from a JSON number back into the float. Stored pre-rounded (newFloat) so equal inputs are equal.

func (Float) MarshalJSON 

func (f Float) MarshalJSON() ([]byte, error)

MarshalJSON renders the float at the fixed precision as a bare JSON number.

func (*Float) UnmarshalJSON 

func (f *Float) UnmarshalJSON(b []byte) error

UnmarshalJSON parses a JSON number back into the fixed-precision float, so the typed struct round-trips from emitted bytes.

type Gap 

type Gap struct {
	ComponentA      string `json:"componentA"`
	ComponentB      string `json:"componentB"`
	RepresentativeA string `json:"representativeA"`
	RepresentativeB string `json:"representativeB"`
}

Gap is a candidate bridge between two distinct weak components.

type HITS 

type HITS struct {
	TopHubs        []Ranked `json:"topHubs"`
	TopAuthorities []Ranked `json:"topAuthorities"`
}

HITS holds the top hubs and authorities (importance-ranked, fixed precision). 

type Navigability struct {
	Compactness              Float `json:"compactness"`
	Stratum                  Float `json:"stratum"`
	CharacteristicPathLength Float `json:"characteristicPathLength"`
	MedianPathLength         Float `json:"medianPathLength"`
	ClusteringCoefficient    Float `json:"clusteringCoefficient"`
	Diameter                 int   `json:"diameter"`
	ReachablePairs           int   `json:"reachablePairs"`
}

Navigability is the wire shape of the corpus navigability scalars (ADR 0014). The float fields reuse the fixed-precision Float type (the HITS determinism mechanism) so output is byte-stable; diameter and reachablePairs are integers.

type Node 

type Node struct {
	ID                string `json:"id"`
	Kind              string `json:"kind"`
	Title             string `json:"title"`
	Path              string `json:"path"`
	Description       string `json:"description"`
	Category          string `json:"category"`
	InDegree          int    `json:"inDegree"`
	OutDegree         int    `json:"outDegree"`
	Component         string `json:"component"`
	HubScore          Float  `json:"hubScore"`
	AuthorityScore    Float  `json:"authorityScore"`
	Reachable         bool   `json:"reachable"`
	Orphan            bool   `json:"orphan"`
	IntentionalOrphan bool   `json:"intentionalOrphan"`
	// UnderLinked / DeadEnd are the graduated structure tiers (ADR 0012);
	// mutually exclusive with Orphan and each other.
	UnderLinked bool `json:"underLinked"`
	DeadEnd     bool `json:"deadEnd"`
	// Bowtie is the node's bow-tie bucket: core/in/out/tendril/disconnected.
	Bowtie string `json:"bowtie"`
	// Betweenness is the node's directed betweenness-centrality score in [0,1]
	// (ADR 0015): how load-bearing it is as a shortest-path connector. Fixed
	// precision (Float) so graph.json is byte-stable. IsArticulation marks it a
	// cut vertex of the undirected closure.
	Betweenness    Float `json:"betweenness"`
	IsArticulation bool  `json:"isArticulation"`
	// PageRank is the node's PageRank score (ADR 0016): global importance via the
	// random-surfer stationary distribution. Fixed precision (Float) so graph.json
	// is byte-stable.
	PageRank Float `json:"pageRank"`
	// HopsFromRoot is the node's shortest hop distance from the nearest root
	// (ADR 0021), or -1 when it is unreachable OR the root set is indeterminate
	// (an agent-discoverability signal: lower is easier to reach by link traversal).
	HopsFromRoot int `json:"hopsFromRoot"`
}

Node is a document (or section) vertex with its presentation + analysis data.

type PageRank 

type PageRank struct {
	TopDocs []Ranked `json:"topDocs"`
}

PageRank holds the top documents by PageRank (ADR 0016), parallel to the HITS and Betweenness blocks. Scores use the fixed-precision Float type so graph.json is byte-stable.

type Ranked 

type Ranked struct {
	ID    string `json:"id"`
	Score Float  `json:"score"`
}

Ranked pairs a document with a fixed-precision HITS score.

type Reachability 

type Reachability struct {
	Indeterminate bool `json:"indeterminate"`
}

Reachability mirrors the analysis reachability state. Indeterminate is true when no root set was found (reachability was not computed); consumers must not treat every non-reached doc as unreachable in that case (ADR 0007).

type Section 

type Section struct {
	ID    string `json:"id"`
	Doc   string `json:"doc"`
	Slug  string `json:"slug"`
	Level int    `json:"level"`
	Title string `json:"title"`
}

Section is a heading-scoped vertex: its node id, owning document, slug, level, and title. 

type SuggestedLink struct {
	DocA             string `json:"docA"`
	DocB             string `json:"docB"`
	SharedNeighbours int    `json:"sharedNeighbours"`
	Coupling         int    `json:"coupling"`
	CoCitation       int    `json:"coCitation"`
	AdamicAdar       Float  `json:"adamicAdar"`
}

SuggestedLink is a topology-based suggestion that two UNLINKED but structurally-close documents may warrant a navigational link (ADR 0013). DocA < DocB. The Adamic/Adar score reuses the fixed-precision Float type (the HITS determinism mechanism) so output is byte-stable.

type Summary 

type Summary struct {
	Documents   int `json:"documents"`
	Sections    int `json:"sections"`
	Edges       int `json:"edges"`
	References  int `json:"references"`
	Components  int `json:"components"`
	Orphans     int `json:"orphans"`
	Unreachable int `json:"unreachable"`
	UnderLinked int `json:"underLinked"`
	DeadEnd     int `json:"deadEnd"`
	// FarFromRoot counts documents at/beyond the hop-distance threshold from every
	// root (ADR 0021). Pure data; never gates the exit code.
	FarFromRoot    int `json:"farFromRoot"`
	BrokenLinks    int `json:"brokenLinks"`
	BrokenAnchors  int `json:"brokenAnchors"`
	Ambiguous      int `json:"ambiguous"`
	KnowledgeGaps  int `json:"knowledgeGaps"`
	SuggestedLinks int `json:"suggestedLinks"`
	// ArticulationPoints / Bridges are the critical-path structure counts
	// (ADR 0015): cut vertices and cut edges of the undirected closure.
	ArticulationPoints int `json:"articulationPoints"`
	Bridges            int `json:"bridges"`
	// Navigability holds the corpus-level navigability scalars (ADR 0014). Floats
	// use the fixed-precision Float type so graph.json stays byte-stable.
	Navigability Navigability `json:"navigability"`
}

Summary holds the corpus-overview counts.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.