api

Documentation

Overview

Package api provides the HTTP client and base request primitives for the Supermodel API. It handles authentication headers, idempotency keys, error parsing, and response decoding.

This is a shared kernel package. It must contain no business logic. Slice packages under internal/ may import it freely.

Index

• type AliveCode
• type Client
  • func New(cfg *config.Config) *Client
  • func (c *Client) Analyze(ctx context.Context, zipPath, idempotencyKey string) (*Graph, error)
  • func (c *Client) AnalyzeDomains(ctx context.Context, zipPath, idempotencyKey string) (*SupermodelIR, error)
  • func (c *Client) AnalyzeRaw(ctx context.Context, zipPath, idempotencyKey string) (json.RawMessage, error)
  • func (c *Client) DeadCode(ctx context.Context, zipPath, idempotencyKey, minConfidence string, limit int) (*DeadCodeResult, error)
  • func (c *Client) DisplayGraph(ctx context.Context, repoID, idempotencyKey string) (*Graph, error)
• type DeadCodeCandidate
• type DeadCodeMetadata
• type DeadCodeResult
• type EntryPoint
• type Error
  • func (e *Error) Error() string
• type Graph
  • func (g *Graph) NodeByID(id string) (Node, bool)
  • func (g *Graph) NodesByLabel(label string) []Node
  • func (g *Graph) Rels() []Relationship
  • func (g *Graph) RepoID() string
• type IRDomain
• type IRGraph
• type IRMetadata
• type IRNode
• type IRRelationship
• type IRSubdomain
• type JobResponse
• type Node
  • func (n Node) HasLabel(label string) bool
  • func (n Node) Prop(keys ...string) string
• type Relationship
• type SupermodelIR

Types

type AliveCode

type AliveCode struct {
	File        string `json:"file"`
	Name        string `json:"name"`
	Line        int    `json:"line"`
	Type        string `json:"type"`
	CallerCount int    `json:"callerCount"`
}

AliveCode is a function confirmed as reachable.

type Client

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

Client is an authenticated Supermodel API client.

func New

func New(cfg *config.Config) *Client

New returns a Client configured from cfg.

func (*Client) Analyze

func (c *Client) Analyze(ctx context.Context, zipPath, idempotencyKey string) (*Graph, error)

Analyze uploads a repository ZIP and runs the full analysis pipeline, polling until the async job completes and returning the Graph.

func (*Client) AnalyzeDomains

func (c *Client) AnalyzeDomains(ctx context.Context, zipPath, idempotencyKey string) (*SupermodelIR, error)

AnalyzeDomains uploads a repository ZIP and runs the full analysis pipeline, returning the complete SupermodelIR response (domains, summary, metadata, graph). Use this instead of Analyze when you need high-level domain information.

func (*Client) AnalyzeRaw

func (c *Client) AnalyzeRaw(ctx context.Context, zipPath, idempotencyKey string) (json.RawMessage, error)

AnalyzeRaw uploads a repository ZIP and runs the full analysis pipeline, returning the raw result JSON from the completed job. Use this when you need the full response payload (e.g. for graph2md / arch-docs generation).

func (*Client) DeadCode

func (c *Client) DeadCode(ctx context.Context, zipPath, idempotencyKey, minConfidence string, limit int) (*DeadCodeResult, error)

DeadCode uploads a repository ZIP and runs dead code analysis, polling until the async job completes and returning the result.

func (*Client) DisplayGraph

func (c *Client) DisplayGraph(ctx context.Context, repoID, idempotencyKey string) (*Graph, error)

DisplayGraph fetches the composed display graph for an already-analyzed repo.

type DeadCodeCandidate

type DeadCodeCandidate struct {
	File       string `json:"file"`
	Name       string `json:"name"`
	Line       int    `json:"line"`
	Type       string `json:"type"`
	Confidence string `json:"confidence"`
	Reason     string `json:"reason"`
}

DeadCodeCandidate is a function flagged as unreachable.

type DeadCodeMetadata

type DeadCodeMetadata struct {
	TotalDeclarations  int    `json:"totalDeclarations"`
	DeadCodeCandidates int    `json:"deadCodeCandidates"`
	AliveCode          int    `json:"aliveCode"`
	AnalysisMethod     string `json:"analysisMethod"`
	AnalysisStartTime  string `json:"analysisStartTime"`
	AnalysisEndTime    string `json:"analysisEndTime"`
}

DeadCodeMetadata holds summary stats for a dead code analysis.

type DeadCodeResult

type DeadCodeResult struct {
	Metadata           DeadCodeMetadata    `json:"metadata"`
	DeadCodeCandidates []DeadCodeCandidate `json:"deadCodeCandidates"`
	AliveCode          []AliveCode         `json:"aliveCode"`
	EntryPoints        []EntryPoint        `json:"entryPoints"`
}

DeadCodeResult is the result from /v1/analysis/dead-code.

type EntryPoint

type EntryPoint struct {
	File string `json:"file"`
}

EntryPoint is a detected entry point that should not be flagged as dead.

type Error

type Error struct {
	StatusCode int    `json:"-"`
	Status     int    `json:"status"`
	Code       string `json:"code"`
	Message    string `json:"message"`
}

Error represents a non-2xx response from the API.

func (*Error) Error

func (e *Error) Error() string

type Graph

type Graph struct {
	Nodes         []Node         `json:"nodes"`
	Edges         []Relationship `json:"edges"`
	Relationships []Relationship `json:"relationships"`
	Metadata      map[string]any `json:"metadata,omitempty"`
}

Graph is the unified response type for /v1/graphs/supermodel and /v1/repos/{id}/graph/display. The API serialises relationships as either "edges" or "relationships" depending on the endpoint; Rels() unifies both.

func (*Graph) NodeByID

func (g *Graph) NodeByID(id string) (Node, bool)

NodeByID returns the node with the given ID, if present.

func (*Graph) NodesByLabel

func (g *Graph) NodesByLabel(label string) []Node

NodesByLabel returns all nodes that carry the given label.

func (*Graph) Rels

func (g *Graph) Rels() []Relationship

Rels returns all relationships regardless of which JSON field they came from.

func (*Graph) RepoID

func (g *Graph) RepoID() string

RepoID returns the repoId from graph metadata, or "".

type IRDomain

type IRDomain struct {
	Name               string        `json:"name"`
	DescriptionSummary string        `json:"descriptionSummary"`
	KeyFiles           []string      `json:"keyFiles"`
	Responsibilities   []string      `json:"responsibilities"`
	Subdomains         []IRSubdomain `json:"subdomains"`
}

IRDomain is the raw representation of a semantic domain from the API.

type IRGraph

type IRGraph struct {
	Nodes         []IRNode         `json:"nodes"`
	Relationships []IRRelationship `json:"relationships"`
}

IRGraph is the raw node/relationship sub-graph embedded in SupermodelIR.

type IRMetadata

type IRMetadata struct {
	FileCount int      `json:"fileCount"`
	Languages []string `json:"languages"`
}

IRMetadata holds file-count and language statistics from the API response.

type IRNode

type IRNode struct {
	Type string `json:"type"`
	Name string `json:"name"`
}

IRNode is a single node in the IRGraph.

type IRRelationship

type IRRelationship struct {
	Type   string `json:"type"`
	Source string `json:"source"`
	Target string `json:"target"`
}

IRRelationship is a directed edge in the IRGraph.

type IRSubdomain

type IRSubdomain struct {
	Name               string `json:"name"`
	DescriptionSummary string `json:"descriptionSummary"`
}

IRSubdomain is a named sub-area within an IRDomain.

type JobResponse

type JobResponse struct {
	Status     string          `json:"status"`
	JobID      string          `json:"jobId"`
	RetryAfter int             `json:"retryAfter"`
	Error      *string         `json:"error"`
	Result     json.RawMessage `json:"result"`
}

JobResponse is the async envelope returned by the API for long-running jobs.

type Node

type Node struct {
	ID         string         `json:"id"`
	Labels     []string       `json:"labels"`
	Properties map[string]any `json:"properties"`
}

Node represents a graph node returned by the Supermodel API.

func (Node) HasLabel

func (n Node) HasLabel(label string) bool

HasLabel reports whether the node carries the given label.

func (Node) Prop

func (n Node) Prop(keys ...string) string

Prop returns the first non-empty string value from the node's properties.

type Relationship

type Relationship struct {
	ID         string         `json:"id"`
	Type       string         `json:"type"`
	StartNode  string         `json:"startNode"`
	EndNode    string         `json:"endNode"`
	Properties map[string]any `json:"properties,omitempty"`
}

Relationship is a directed edge between two graph nodes.

type SupermodelIR

type SupermodelIR struct {
	Repo     string         `json:"repo"`
	Summary  map[string]any `json:"summary"`
	Metadata IRMetadata     `json:"metadata"`
	Domains  []IRDomain     `json:"domains"`
	Graph    IRGraph        `json:"graph"`
}

SupermodelIR is the full structured response returned inside a completed job result from /v1/graphs/supermodel. It contains high-level domain information in addition to the raw node/edge graph captured by Graph.