hotspot

package

v0.7.0 Latest Latest Go to latest Published: Aug 23, 2026 License: AGPL-3.0 Imports: 21 Imported by: 0

Documentation ¶

Overview ¶

Package hotspot provides deterministic, read-only structural source analysis.

The package never executes target source, invokes a shell, follows symlinks, loads target plugins, or inspects Git history. JSON is the machine authority; terminal and Markdown output are deterministic renderings of the same Report.

Index ¶

Constants
Variables
func MarshalJSON(report Report) ([]byte, error)
func RenderMarkdown(report Report) ([]byte, error)
func RenderTerminal(report Report) ([]byte, error)
type AggregateMetric
type Availability
type Confidence
type DeferredCapability
type Exclusion
type FileRow
type Filters
type FiltersJSON
type Language
type LanguageAggregate
type Limits
type Metric
type OwnerRow
type PrimarySize
type Ranking
type RankingMetric
type RefactoringCandidate
type RegionRow
type Report
- func Analyze(ctx context.Context, request Request) (Report, error)
type Request
- func DefaultRequest(root string) Request
- func ParseRequestJSON(content []byte) (Request, error)
type ScanConfiguration
type SurfaceCapability
type Warning

Constants ¶

View Source

const (
	RequestSchemaV1    = "apg.hotspot-request/v1"
	ReportSchemaV1     = "apg.hotspot-report/v1"
	CapabilityMatrixV1 = "apg.hotspot-capabilities/v1"
	ProducerVersion    = "devel"
)

View Source

const (
	MetricBytes           = "bytes"
	MetricPhysicalLines   = "physical-lines"
	MetricProseLines      = "prose-lines"
	MetricFenceLines      = "fence-lines"
	MetricStatements      = "statements"
	MetricSymbols         = "symbols"
	MetricCyclomatic      = "cyclomatic"
	MetricNesting         = "nesting"
	MetricParameters      = "parameters"
	MetricProceduralSize  = "top-level-procedural-size"
	MetricFileSize        = "file-size"
	MetricLexicalLines    = "lexical-lines"
	MetricHeadings        = "headings"
	MetricFences          = "fences"
	MetricLinks           = "links"
	MetricEmbeddedLines   = "embedded-lines"
	MetricEmbeddedRegions = "embedded-regions"
	MetricElements        = "elements"
	MetricAttributes      = "attributes"
	MetricSelectors       = "selectors"
	MetricDeclarations    = "declarations"
	MetricObjects         = "objects"
	MetricKeys            = "keys"
	MetricArrays          = "arrays"
	MetricScalars         = "scalars"
	MetricMaxObjectKeys   = "max-object-keys"
	MetricMaxArrayLength  = "max-array-length"
	MetricInstructions    = "instructions"
	MetricStages          = "stages"
	MetricRuns            = "run-instructions"
	MetricKeysStructural  = "structural-keys"
	MetricBlocks          = "blocks"
	MetricCommands        = "commands"
	MetricControlTokens   = "control-tokens"
	MetricClauses         = "clauses"
)

View Source

const (
	CompletionComplete = "complete"
)

Variables ¶

View Source

var (
	ErrInvalidRequest = errors.New("invalid hotspot request")
	ErrRootSafety     = errors.New("hotspot root safety violation")
	ErrLimitExceeded  = errors.New("hotspot scan limit exceeded")
	ErrFileDrift      = errors.New("hotspot file drift")
	ErrUnreadable     = errors.New("hotspot file unreadable")
	ErrInvalidReport  = errors.New("invalid hotspot report")
)

Functions ¶

func MarshalJSON ¶

func MarshalJSON(report Report) ([]byte, error)

MarshalJSON emits complete deterministic schema-v1 JSON terminated by one newline.

func RenderMarkdown ¶

func RenderMarkdown(report Report) ([]byte, error)

RenderMarkdown returns a deterministic detailed report with a complete file appendix.

func RenderTerminal ¶

func RenderTerminal(report Report) ([]byte, error)

RenderTerminal returns the bounded concise situational view configured by Report.

Types ¶

type AggregateMetric ¶

type AggregateMetric struct {
	Name  string `json:"name"`
	Value int64  `json:"value"`
	Unit  string `json:"unit"`
}

type Availability ¶

type Availability string

const (
	AvailabilityExact         Availability = "exact"
	AvailabilityStructural    Availability = "structural"
	AvailabilityUnavailable   Availability = "unavailable"
	AvailabilityNotApplicable Availability = "not-applicable"
)

type Confidence ¶

type Confidence string

const (
	ConfidenceHigh   Confidence = "high"
	ConfidenceMedium Confidence = "medium"
	ConfidenceLow    Confidence = "low"
)

type DeferredCapability ¶

type DeferredCapability struct {
	Name   string `json:"name"`
	Status string `json:"status"`
}

type Exclusion ¶

type Exclusion struct {
	Rule        string `json:"rule"`
	Description string `json:"description"`
	Directories int    `json:"directories"`
	Files       int    `json:"files"`
}

type FileRow ¶

type FileRow struct {
	ID              string      `json:"id"`
	Path            string      `json:"path"`
	Language        Language    `json:"language"`
	Confidence      Confidence  `json:"confidence"`
	SHA256          string      `json:"sha256"`
	Bytes           int64       `json:"bytes"`
	PhysicalLines   *int64      `json:"physical_lines,omitempty"`
	PrimarySize     PrimarySize `json:"primary_size"`
	Generated       bool        `json:"generated"`
	RankingEligible bool        `json:"ranking_eligible"`
	ParseFailure    string      `json:"parse_failure,omitempty"`
	Metrics         []Metric    `json:"metrics"`
	Ranking         Ranking     `json:"ranking"`
}

type Filters ¶

type Filters struct {
	DisableDefaultExclusions bool
	IncludeLanguages         []Language
	IncludePaths             []string
	ExcludePaths             []string
}

Filters are deterministic, root-relative inclusion and exclusion controls. Paths are literal clean relative path prefixes; they are not globs.

type FiltersJSON ¶

type FiltersJSON struct {
	DisableDefaultExclusions bool       `json:"disable_default_exclusions"`
	IncludeLanguages         []Language `json:"include_languages"`
	IncludePaths             []string   `json:"include_paths"`
	ExcludePaths             []string   `json:"exclude_paths"`
}

type Language ¶

type Language string

const (
	LanguageGo          Language = "go"
	LanguageMarkdown    Language = "markdown"
	LanguageMDX         Language = "mdx"
	LanguageAstro       Language = "astro"
	LanguagePython      Language = "python"
	LanguageJava        Language = "java"
	LanguageKotlin      Language = "kotlin"
	LanguageJavaScript  Language = "javascript"
	LanguageTypeScript  Language = "typescript"
	LanguageJSX         Language = "jsx"
	LanguageTSX         Language = "tsx"
	LanguageHTML        Language = "html"
	LanguageCSS         Language = "css"
	LanguageXML         Language = "xml"
	LanguageXMLPlist    Language = "xml-plist"
	LanguageBinaryPlist Language = "binary-plist"
	LanguageJSON        Language = "json"
	LanguageJSONFamily  Language = "json-family"
	LanguageYAML        Language = "yaml"
	LanguageTOML        Language = "toml"
	LanguageTerraform   Language = "terraform"
	LanguageGradle      Language = "gradle"
	LanguageSQL         Language = "sql"
	LanguageBash        Language = "bash"
	LanguageZsh         Language = "zsh"
	LanguagePOSIXShell  Language = "posix-shell"
	LanguageDockerfile  Language = "dockerfile"
	LanguageVagrantfile Language = "vagrantfile"
	LanguageBinary      Language = "binary"
	LanguageUnknown     Language = "unknown"
)

type LanguageAggregate ¶

type LanguageAggregate struct {
	Language Language          `json:"language"`
	Files    int               `json:"files"`
	Bytes    int64             `json:"bytes"`
	Metrics  []AggregateMetric `json:"metrics"`
}

type Limits ¶

type Limits struct {
	MaxFiles        int
	MaxBytesPerFile int64
	MaxTotalBytes   int64
	MaxDuration     time.Duration
}

Limits bounds all consequence-bearing scan resources.

type Metric ¶

type Metric struct {
	Name         string       `json:"name"`
	Availability Availability `json:"availability"`
	Value        *int64       `json:"value,omitempty"`
	Unit         string       `json:"unit,omitempty"`
	RankClass    string       `json:"rank_class,omitempty"`
	Reason       string       `json:"reason,omitempty"`
}

type OwnerRow ¶

type OwnerRow struct {
	ID          string     `json:"id"`
	Path        string     `json:"path"`
	Language    Language   `json:"language"`
	Kind        string     `json:"kind"`
	DisplayName string     `json:"display_name"`
	StartLine   int        `json:"start_line"`
	EndLine     int        `json:"end_line"`
	Confidence  Confidence `json:"confidence"`
	Generated   bool       `json:"generated"`
	Metrics     []Metric   `json:"metrics"`
	Ranking     Ranking    `json:"ranking"`
}

type PrimarySize ¶

type PrimarySize struct {
	Value int64  `json:"value"`
	Unit  string `json:"unit"`
}

type Ranking ¶

type Ranking struct {
	Score           int             `json:"score"`
	AvailableWeight int             `json:"available_weight"`
	Vector          []RankingMetric `json:"vector"`
}

type RankingMetric ¶

type RankingMetric struct {
	Name       string `json:"name"`
	Raw        int64  `json:"raw"`
	Percentile int    `json:"percentile"`
	Weight     int    `json:"weight"`
	RankClass  string `json:"rank_class"`
}

type RefactoringCandidate ¶

type RefactoringCandidate struct {
	Kind            string     `json:"kind"`
	TargetID        string     `json:"target_id"`
	Path            string     `json:"path"`
	RiskScore       int        `json:"risk_score"`
	AvailableWeight int        `json:"available_weight"`
	Confidence      Confidence `json:"confidence"`
	ReasonCodes     []string   `json:"reason_codes"`
}

type RegionRow ¶

type RegionRow struct {
	ID          string     `json:"id"`
	Path        string     `json:"path"`
	Language    Language   `json:"language"`
	Kind        string     `json:"kind"`
	DisplayName string     `json:"display_name"`
	StartLine   int        `json:"start_line"`
	EndLine     int        `json:"end_line"`
	Confidence  Confidence `json:"confidence"`
	Metrics     []Metric   `json:"metrics"`
	Ranking     Ranking    `json:"ranking"`
}

type Report ¶

type Report struct {
	SchemaVersion         string                 `json:"schema_version"`
	ToolVersion           string                 `json:"tool_version"`
	RootID                string                 `json:"root_id"`
	CompletionStatus      string                 `json:"completion_status"`
	ScanConfiguration     ScanConfiguration      `json:"scan_configuration"`
	Exclusions            []Exclusion            `json:"exclusions"`
	CapabilityVersion     string                 `json:"capability_version"`
	Capabilities          []SurfaceCapability    `json:"capabilities"`
	DeferredCapabilities  []DeferredCapability   `json:"deferred_capabilities"`
	LanguageAggregates    []LanguageAggregate    `json:"language_aggregates"`
	Files                 []FileRow              `json:"files"`
	Owners                []OwnerRow             `json:"owners"`
	ProceduralRegions     []RegionRow            `json:"procedural_regions"`
	RefactoringCandidates []RefactoringCandidate `json:"refactoring_candidates"`
	Warnings              []Warning              `json:"warnings"`
	Fingerprint           string                 `json:"report_fingerprint"`
}

Report is the complete immutable-by-convention analyzer result consumed by all renderers. It deliberately contains no absolute target root.

func Analyze ¶

func Analyze(ctx context.Context, request Request) (Report, error)

Analyze scans one exact root read-only and returns only complete reports.

type Request ¶

type Request struct {
	SchemaVersion string
	Root          string
	RootID        string
	ToolVersion   string
	Limits        Limits
	Filters       Filters
	DisplayTopN   int
}

Request identifies one exact root and one bounded analysis configuration.

func DefaultRequest ¶

func DefaultRequest(root string) Request

DefaultRequest returns the mandatory bounded v1 defaults. Root remains subject to Analyze's absolute-clean, direct-directory validation.

func ParseRequestJSON ¶

func ParseRequestJSON(content []byte) (Request, error)

ParseRequestJSON decodes the strict request schema and rejects duplicate or unknown consequence-bearing keys before validation by Analyze.

type ScanConfiguration ¶

type ScanConfiguration struct {
	RequestSchemaVersion     string     `json:"request_schema_version"`
	MaxFiles                 int        `json:"max_files"`
	MaxBytesPerFile          int64      `json:"max_bytes_per_file"`
	MaxTotalBytes            int64      `json:"max_total_bytes"`
	MaxDurationMilliseconds  int64      `json:"max_duration_milliseconds"`
	DefaultExclusionsEnabled bool       `json:"default_exclusions_enabled"`
	IncludeLanguages         []Language `json:"include_languages"`
	IncludePaths             []string   `json:"include_paths"`
	ExcludePaths             []string   `json:"exclude_paths"`
	DisplayTopN              int        `json:"display_top_n"`
}

type SurfaceCapability ¶

type SurfaceCapability struct {
	Surface           string       `json:"surface"`
	Languages         []Language   `json:"languages"`
	Classification    Availability `json:"classification"`
	Lines             Availability `json:"lines"`
	Statements        Availability `json:"statements"`
	Symbols           Availability `json:"symbols"`
	Cyclomatic        Availability `json:"cyclomatic"`
	Nesting           Availability `json:"nesting"`
	ProceduralRegions Availability `json:"procedural_regions"`
	StructuralMetrics Availability `json:"structural_metrics"`
	Confidence        Confidence   `json:"confidence"`
}

type Warning ¶

type Warning struct {
	Code   string `json:"code"`
	Path   string `json:"path,omitempty"`
	Detail string `json:"detail"`
}

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL