view

Documentation

Overview

Package view builds component-level projections (quotient graphs) of the code graph: a deterministic partition of symbols into components plus induced edges aggregated from the primitive edges that cross it.

Two invariants hold for everything this package produces (see the view contract):

1. Provenance — every induced edge carries the constituent primitive edges (sites) that induced it; Weight carries the full count when the site list is capped. Abstraction is evidence-backed, never narrative.
2. Tier honesty — every induced edge reports the capability-tier distribution of its constituent evidence, and a derived result's tier is the minimum over its load-bearing evidence. View results claim "complete-at-tier", never "closed".

The partition is structural and deterministic (directory of each symbol's file path, optionally truncated to a depth). Semantic naming or clustering may annotate a view; it never defines one.

Index

• func IsTestPath(filePath string) bool
• func MinTier(tiers map[string]int) string
• type Component
• type Cycle
• type InducedEdge
• type Options
• type Rule
  • func ParseRule(s string) (Rule, error)
  • func ParseRules(raw []string) ([]Rule, error)
• type Site
• type View
  • func Build(symbols []grove.SymbolRecord, edges []grove.Edge, opts Options) *View
  • func (v *View) CheckRules(rules []Rule) []Violation
  • func (v *View) Cycles() []Cycle
  • func (v *View) Edge(from, to string) *InducedEdge
• type Violation

Functions

func IsTestPath

func IsTestPath(filePath string) bool

IsTestPath reports whether a repo-relative file path is a test file by the naming conventions of the indexed languages. Deterministic and purely lexical — a wrong classification here only moves a file between the production and test views; it never invents or drops evidence.

func MinTier

func MinTier(tiers map[string]int) string

MinTier returns the weakest tier present in a tier-count distribution — the tier of the derived claim built on that evidence.

Types

type Component

type Component struct {
	Name     string `json:"name"`
	Files    int    `json:"files"`
	Symbols  int    `json:"symbols"`
	Exported int    `json:"exported"`
	FanIn    int    `json:"fanIn"`  // distinct components depending on this one
	FanOut   int    `json:"fanOut"` // distinct components this one depends on
}

Component is one partition cell: a directory (or depth-truncated prefix).

type Cycle

type Cycle struct {
	Components []string      `json:"components"`
	Edges      []InducedEdge `json:"edges"`
}

Cycle is one strongly connected component of size > 1 in the induced graph, with the induced edges among its members as evidence.

type InducedEdge

type InducedEdge struct {
	From   string         `json:"from"`
	To     string         `json:"to"`
	Weight int            `json:"weight"` // total constituent primitive edges
	Kinds  map[string]int `json:"kinds"`  // breakdown by primitive edge kind
	Tiers  map[string]int `json:"tiers"`  // breakdown by evidence tier
	Sites  []Site         `json:"sites"`  // capped at MaxSites; Weight carries the truth
}

InducedEdge is one component-level dependency: the aggregation of every primitive dependency edge crossing from one component to another.

type Options

type Options struct {
	// Depth truncates component keys to the first N path segments
	// (0 = full directory path).
	Depth int
	// MaxSites caps the constituent sites kept per induced edge; Weight
	// carries the full count. 0 = default (5).
	MaxSites int
	// IncludeTests keeps test-file symbols in the view. Default false:
	// an architecture map describes the production shape; test files
	// otherwise pollute it with helper-induced edges (measured on this
	// repository: a heuristic test-only edge manufactured a false
	// httpapi<->mcp cycle). Excluded files are counted, not hidden —
	// View.TestFilesExcluded reports how many were left out.
	IncludeTests bool
}

Options configures a Build.

type Rule

type Rule struct {
	Raw  string `json:"raw"`
	From string `json:"from"`
	To   string `json:"to"`
}

Rule is one parsed deny rule.

func ParseRule

func ParseRule(s string) (Rule, error)

ParseRule parses "<from> -> <to>". Each side is a component name (directory), a prefix (covers subdirectories), a path.Match glob, or "*".

func ParseRules

func ParseRules(raw []string) ([]Rule, error)

ParseRules parses a rule list, collecting every error (a bad rule must fail loudly, not silently weaken the gate).

type Site

type Site struct {
	FromSymbol string `json:"fromSymbol"`
	FromFile   string `json:"fromFile"`
	FromLine   int    `json:"fromLine"`
	ToSymbol   string `json:"toSymbol"`
	ToFile     string `json:"toFile"`
	ToLine     int    `json:"toLine"`
	Kind       string `json:"kind"`
	Tier       string `json:"tier"`
}

Site is one constituent primitive edge of an induced edge — the expansion evidence: a concrete crossing of the component boundary.

type View

type View struct {
	Components []Component   `json:"components"`
	Edges      []InducedEdge `json:"edges"`
	// TierSummary aggregates the tier distribution over every induced
	// edge's constituent evidence.
	TierSummary map[string]int `json:"tierSummary"`
	// Depth echoes Options.Depth (0 = full directory path).
	Depth int `json:"depth"`
	// IncludeTests echoes Options.IncludeTests.
	IncludeTests bool `json:"includeTests"`
	// TestFilesExcluded counts distinct test files left out of the view
	// (0 when IncludeTests is true). Exclusion is reported, never silent.
	TestFilesExcluded int `json:"testFilesExcluded"`
}

View is the quotient graph: components plus induced edges. All slices are deterministically ordered.

func Build

func Build(symbols []grove.SymbolRecord, edges []grove.Edge, opts Options) *View

Build constructs the quotient view from a full graph snapshot. It is a pure function: identical inputs (in any order) produce identical output.

func (*View) CheckRules

func (v *View) CheckRules(rules []Rule) []Violation

CheckRules validates the view against the rules. Exact over the induced graph: every reported violation is backed by concrete primitive edges, and the verdict's confidence is bounded by the weakest evidence tier of each violating edge (a heuristic-tier violation deserves a look, not an automatic build break — the caller decides).

func (*View) Cycles

func (v *View) Cycles() []Cycle

Cycles returns the strongly connected components of size > 1 in the induced graph (Tarjan), each with its member edges as evidence. The algorithm is exact; the result's tier is the weakest constituent edge tier — an exact algorithm over measured evidence yields a measured claim.

func (*View) Edge

func (v *View) Edge(from, to string) *InducedEdge

Edge returns the induced edge from one component to another, or nil.

type Violation

type Violation struct {
	Rule    string      `json:"rule"`
	Edge    InducedEdge `json:"edge"`
	MinTier string      `json:"minTier"`
}

Violation is one induced edge that breaks a declared rule. The edge carries its constituent sites — the exact file:line crossings to fix.