api

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Apr 7, 2026 License: MIT Imports: 11 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AffectedEntryPoint added in v0.3.1 

type AffectedEntryPoint struct {
	File string `json:"file"`
	Name string `json:"name"`
	Type string `json:"type"`
}

AffectedEntryPoint is an entry point affected by changes to the target.

type AffectedFile added in v0.3.1 

type AffectedFile struct {
	File                   string `json:"file"`
	DirectDependencies     int    `json:"directDependencies"`
	TransitiveDependencies int    `json:"transitiveDependencies"`
}

AffectedFile is a file affected by changes to the target.

type AffectedFunction added in v0.3.1 

type AffectedFunction struct {
	File         string `json:"file"`
	Name         string `json:"name"`
	Line         int    `json:"line,omitempty"`
	Type         string `json:"type"`
	Distance     int    `json:"distance"`
	Relationship string `json:"relationship"`
}

AffectedFunction is a function affected by changes to the target.

type AliveCode added in v0.2.0 

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 BlastRadius added in v0.3.1 

type BlastRadius struct {
	DirectDependents     int      `json:"directDependents"`
	TransitiveDependents int      `json:"transitiveDependents"`
	AffectedFiles        int      `json:"affectedFiles"`
	AffectedDomains      []string `json:"affectedDomains,omitempty"`
	RiskScore            string   `json:"riskScore"`
	RiskFactors          []string `json:"riskFactors,omitempty"`
}

BlastRadius holds blast radius metrics for a target.

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 added in v0.2.0 

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) AnalyzeIncremental added in v0.4.0 

func (c *Client) AnalyzeIncremental(ctx context.Context, zipPath string, changedFiles []string, idempotencyKey string) (*SidecarIR, error)

AnalyzeIncremental uploads a zip of changed files and requests an incremental graph update from the API. changedFiles is sent on every request (initial and retries) so the server always has the full context.

func (*Client) AnalyzeRaw added in v0.2.0 

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 / docs generation).

func (*Client) AnalyzeSidecars added in v0.4.0 

func (c *Client) AnalyzeSidecars(ctx context.Context, zipPath, idempotencyKey string) (*SidecarIR, error)

AnalyzeSidecars uploads a repository ZIP and runs the full analysis pipeline, returning the complete SidecarIR response with full Node/Relationship data required for sidecar rendering (IDs, labels, properties preserved).

func (*Client) DeadCode added in v0.2.0 

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.

func (*Client) Impact added in v0.3.1 

func (c *Client) Impact(ctx context.Context, zipPath, idempotencyKey, targets, diffPath string) (*ImpactResult, error)

Impact uploads a repository ZIP (and optional diff) and runs impact analysis, polling until the async job completes and returning the result.

func (*Client) Share added in v0.4.0 

func (c *Client) Share(ctx context.Context, req ShareRequest) (string, error)

Share uploads a rendered report and returns a public URL.

type CriticalFileMetric added in v0.3.1 

type CriticalFileMetric struct {
	File           string `json:"file"`
	DependentCount int    `json:"dependentCount"`
}

CriticalFileMetric identifies a high-dependent-count file.

type CrossDomainDependency added in v0.3.1 

type CrossDomainDependency struct {
	Source       string `json:"source"`
	Target       string `json:"target"`
	SourceDomain string `json:"sourceDomain"`
	TargetDomain string `json:"targetDomain"`
}

CrossDomainDependency identifies a dependency crossing domain boundaries.

type DeadCodeCandidate added in v0.2.0 

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 added in v0.2.0 

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 added in v0.2.0 

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 added in v0.2.0 

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 added in v0.2.0 

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 added in v0.2.0 

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

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

type IRMetadata added in v0.2.0 

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

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

type IRNode added in v0.2.0 

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

IRNode is a single node in the IRGraph.

type IRRelationship added in v0.2.0 

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 added in v0.2.0 

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

IRSubdomain is a named sub-area within an IRDomain.

type ImpactGlobalMetrics added in v0.3.1 

type ImpactGlobalMetrics struct {
	MostCriticalFiles       []CriticalFileMetric    `json:"mostCriticalFiles,omitempty"`
	CrossDomainDependencies []CrossDomainDependency `json:"crossDomainDependencies,omitempty"`
}

ImpactGlobalMetrics holds global metrics across all analyzed targets.

type ImpactMetadata added in v0.3.1 

type ImpactMetadata struct {
	TotalFiles        int    `json:"totalFiles"`
	TotalFunctions    int    `json:"totalFunctions"`
	TargetsAnalyzed   int    `json:"targetsAnalyzed"`
	AnalysisMethod    string `json:"analysisMethod"`
	AnalysisStartTime string `json:"analysisStartTime"`
	AnalysisEndTime   string `json:"analysisEndTime"`
}

ImpactMetadata holds summary stats for an impact analysis.

type ImpactResult added in v0.3.1 

type ImpactResult struct {
	Metadata      ImpactMetadata      `json:"metadata"`
	Impacts       []ImpactTarget      `json:"impacts"`
	GlobalMetrics ImpactGlobalMetrics `json:"globalMetrics"`
}

ImpactResult is the result from /v1/analysis/impact.

type ImpactTarget added in v0.3.1 

type ImpactTarget struct {
	Target              ImpactTargetInfo     `json:"target"`
	BlastRadius         BlastRadius          `json:"blastRadius"`
	AffectedFunctions   []AffectedFunction   `json:"affectedFunctions"`
	AffectedFiles       []AffectedFile       `json:"affectedFiles"`
	EntryPointsAffected []AffectedEntryPoint `json:"entryPointsAffected"`
}

ImpactTarget is the impact analysis result for a single target.

type ImpactTargetInfo added in v0.3.1 

type ImpactTargetInfo struct {
	File string `json:"file"`
	Name string `json:"name,omitempty"`
	Line int    `json:"line,omitempty"`
	Type string `json:"type"`
}

ImpactTargetInfo identifies the file or function being analyzed.

type JobResponse added in v0.2.0 

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 ShareRequest added in v0.4.0 

type ShareRequest struct {
	ProjectName string `json:"project_name"`
	Status      string `json:"status"`
	Content     string `json:"content"` // rendered Markdown report
}

ShareRequest is the payload for POST /v1/share.

type ShareResponse added in v0.4.0 

type ShareResponse struct {
	URL string `json:"url"`
}

ShareResponse is returned by POST /v1/share.

type SidecarDomain added in v0.4.0 

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

SidecarDomain is a semantic domain from the API with file references.

type SidecarGraph added in v0.4.0 

type SidecarGraph struct {
	Nodes         []Node         `json:"nodes"`
	Relationships []Relationship `json:"relationships"`
}

SidecarGraph is the full node/relationship graph embedded in SidecarIR.

type SidecarIR added in v0.4.0 

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

SidecarIR is the full structured response from /v1/graphs/supermodel used by the sidecars vertical slice. Unlike SupermodelIR (which uses simplified IRNode/IRRelationship stubs), SidecarIR preserves the complete node graph with IDs, labels, and properties required for sidecar rendering.

type SidecarSubdomain added in v0.4.0 

type SidecarSubdomain struct {
	Name               string   `json:"name"`
	DescriptionSummary string   `json:"descriptionSummary"`
	Files              []string `json:"files"`
	KeyFiles           []string `json:"keyFiles"`
}

SidecarSubdomain is a named sub-area within a SidecarDomain.

type SupermodelIR added in v0.2.0 

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.

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.