report

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2026 License: 0BSD Imports: 21 Imported by: 0

Documentation

Overview

Package report owns stable machine-readable command result envelopes.

Index

Constants

View Source 
const CheckSchemaVersion = 2

CheckSchemaVersion is the combined-check machine-report schema. It differs from the version-1 formatter and lint schemas because incomplete checks can report the additional pending format status.

View Source 
const SchemaVersion = 1

Variables

This section is empty.

Functions

func MarshalCheckJSON 

func MarshalCheckJSON(result CheckResult) ([]byte, error)

func MarshalJSON 

func MarshalJSON(result Result) ([]byte, error)

func MarshalLintJSON 

func MarshalLintJSON(result LintResult) ([]byte, error)

MarshalLintJSON buffers one complete lint result before emitting JSON.

func MarshalLintStatisticsJSON 

func MarshalLintStatisticsJSON(statistics LintStatistics) ([]byte, error)

MarshalLintStatisticsJSON encodes one canonical stats document.

func RenderGitHub 

func RenderGitHub(input IntegrationInput) ([]byte, error)

RenderGitHub renders deterministic GitHub workflow-command annotations.

func RenderLintFixShortText 

func RenderLintFixShortText(inputs []LintFixTextInput) ([]byte, error)

RenderLintFixShortText renders remaining source-free diagnostics and rejected-fix reasons.

func RenderLintFixText 

func RenderLintFixText(inputs []LintFixTextInput) ([]byte, error)

RenderLintFixText renders remaining diagnostics and rejected-fix reasons.

func RenderLintShortText 

func RenderLintShortText(inputs []LintTextInput) ([]byte, error)

RenderLintShortText renders source-free, location-oriented human diagnostics.

func RenderLintStatisticsText 

func RenderLintStatisticsText(statistics LintStatistics) []byte

RenderLintStatisticsText renders a concise, deterministic stats report.

func RenderLintText 

func RenderLintText(inputs []LintTextInput) ([]byte, error)

RenderLintText renders ordered human diagnostics with bounded physical-source frames. Machine reporters retain their source-free contracts.

func RenderPackageLintShortText 

func RenderPackageLintShortText(
	inputs []LintTextInput,
	packageDiagnostics []analysis.PackageDiagnostic,
	sourceProblems []analysis.PackageSourceProblem,
) ([]byte, error)

RenderPackageLintShortText renders package prerequisites and source-free location-oriented rule diagnostics.

func RenderPackageLintText 

func RenderPackageLintText(
	inputs []LintTextInput,
	packageDiagnostics []analysis.PackageDiagnostic,
	sourceProblems []analysis.PackageSourceProblem,
) ([]byte, error)

RenderPackageLintText renders prerequisite problems before exact-source rule diagnostics while preserving their distinct ownership channels.

func RenderRuleCatalogMarkdown 

func RenderRuleCatalogMarkdown(registry *rules.Registry) ([]byte, error)

RenderRuleCatalogMarkdown renders every registered rule from canonical metadata in deterministic rule-ID order.

func RenderRuleJSON 

func RenderRuleJSON(registry *rules.Registry, ruleID string) ([]byte, bool, error)

RenderRuleJSON renders one rule's canonical metadata as versioned JSON.

func RenderRuleListText 

func RenderRuleListText(registry *rules.Registry, options RuleListOptions) ([]byte, error)

RenderRuleListText renders ID-ordered rule discovery output.

func RenderRuleText 

func RenderRuleText(registry *rules.Registry, ruleID string) ([]byte, bool)

RenderRuleText renders one rule's canonical metadata for human readers.

func RenderSARIF 

func RenderSARIF(input IntegrationInput) ([]byte, error)

RenderSARIF renders one deterministic SARIF 2.1.0 log.

func RequirementName 

func RequirementName(requirement rules.Requirement) string

RequirementName returns the canonical machine-facing tier name.

Types

type BaselineProblem 

type BaselineProblem struct {
	Kind              baseline.ProblemKind `json:"kind"`
	Path              string               `json:"path"`
	RuleID            string               `json:"rule_id"`
	MessageKey        string               `json:"message_key"`
	SourceFingerprint string               `json:"source_fingerprint"`
	Count             int                  `json:"count"`
	Remaining         int                  `json:"remaining"`
	Reason            string               `json:"reason,omitempty"`
	ExpiresOn         string               `json:"expires_on,omitempty"`
}

type ByteRange 

type ByteRange struct {
	Start int `json:"start"`
	End   int `json:"end"`
}

type CheckFile 

type CheckFile struct {
	Path         string            `json:"path"`
	SourceDigest string            `json:"source_digest"`
	FormatStatus CheckFormatStatus `json:"format_status"`
}

type CheckFormatOutcome 

type CheckFormatOutcome struct {
	Path        string
	Digest      source.Digest
	Pending     bool
	Different   bool
	Preexisting bool
}

CheckFormatOutcome binds a format comparison to one analyzed source version.

type CheckFormatStatus 

type CheckFormatStatus string
const (
	CheckFormatPending     CheckFormatStatus = "pending"
	CheckFormatUnchanged   CheckFormatStatus = "unchanged"
	CheckFormatDifferent   CheckFormatStatus = "different"
	CheckFormatPreexisting CheckFormatStatus = "preexisting"
)

type CheckResult 

type CheckResult struct {
	SchemaVersion       int                     `json:"schema_version"`
	Command             string                  `json:"command"`
	Mode                string                  `json:"mode"`
	Outcome             Outcome                 `json:"outcome"`
	Summary             CheckSummary            `json:"summary"`
	Files               []CheckFile             `json:"files"`
	Diagnostics         []LintDiagnostic        `json:"diagnostics"`
	SuppressionProblems []SuppressionProblem    `json:"suppression_problems"`
	UnusedSuppressions  []UnusedSuppression     `json:"unused_suppressions"`
	BaselineProblems    []BaselineProblem       `json:"baseline_problems"`
	PackageDiagnostics  []LintPackageDiagnostic `json:"package_diagnostics,omitempty"`
	SourceProblems      []LintSourceProblem     `json:"source_problems,omitempty"`
	Errors              []Error                 `json:"errors"`
}

func NewCheckResult 

func NewCheckResult(
	category string,
	exitCode int,
	complete bool,
	analyses []analysis.Result,
	formats []CheckFormatOutcome,
	errs []Error,
) (CheckResult, error)

NewCheckResult validates and combines formatting and lint outcomes produced from the same source versions.

func NewPackageCheckResult 

func NewPackageCheckResult(
	category string,
	exitCode int,
	complete bool,
	packageResult analysis.PackageResult,
	formats []CheckFormatOutcome,
	errs []Error,
) (CheckResult, error)

NewPackageCheckResult combines formatting with package-aware lint outcomes produced from the package loader's exact source versions.

type CheckSummary 

type CheckSummary struct {
	Files                            int  `json:"files"`
	FormattingDifferences            int  `json:"formatting_differences"`
	PreexistingFormattingDifferences int  `json:"preexisting_formatting_differences,omitempty"`
	Diagnostics                      int  `json:"diagnostics"`
	PreexistingDiagnostics           int  `json:"preexisting_diagnostics,omitempty"`
	Suppressed                       int  `json:"suppressed"`
	Baselined                        int  `json:"baselined"`
	BaselineProblems                 int  `json:"baseline_problems"`
	SuppressionProblems              int  `json:"suppression_problems"`
	UnusedSuppressions               int  `json:"unused_suppressions"`
	PackageDiagnostics               int  `json:"package_diagnostics,omitempty"`
	SourceProblems                   int  `json:"source_problems,omitempty"`
	Complete                         bool `json:"complete"`
}

type Error 

type Error struct {
	Message string `json:"message"`
}

type File 

type File struct {
	Path   string     `json:"path"`
	Status FileStatus `json:"status"`
}

type FileStatus 

type FileStatus string
const (
	FilePending           FileStatus = "pending"
	FileUnchanged         FileStatus = "unchanged"
	FileDifferent         FileStatus = "different"
	FileFormatted         FileStatus = "formatted"
	FileConflict          FileStatus = "conflict"
	FileFailed            FileStatus = "failed"
	FilePossiblyFormatted FileStatus = "possibly_formatted"
)

type Format 

type Format string
const (
	Text   Format = "text"
	Short  Format = "short"
	JSON   Format = "json"
	GitHub Format = "github"
	SARIF  Format = "sarif"
)

type IntegrationInput 

type IntegrationInput struct {
	Files              []LintTextInput
	Formats            []CheckFormatOutcome
	PackageDiagnostics []analysis.PackageDiagnostic
	SourceProblems     []analysis.PackageSourceProblem
	Errors             []Error
	Registry           *rules.Registry
}

IntegrationInput binds diagnostics and non-rule findings to exact source versions for GitHub workflow annotations and SARIF output.

type LintAppliedFix 

type LintAppliedFix struct {
	RuleID       string    `json:"rule_id"`
	FixName      string    `json:"fix_name"`
	Path         string    `json:"path"`
	SourceDigest string    `json:"source_digest"`
	Range        ByteRange `json:"range"`
}

type LintDiagnostic 

type LintDiagnostic struct {
	RuleID        string            `json:"rule_id"`
	Severity      rules.Severity    `json:"severity"`
	Targets       []string          `json:"targets,omitempty"`
	MessageKey    string            `json:"message_key"`
	Message       string            `json:"message"`
	Path          string            `json:"path"`
	SourceDigest  string            `json:"source_digest"`
	Range         ByteRange         `json:"range"`
	Related       []LintRelated     `json:"related"`
	Notes         []string          `json:"notes"`
	Help          string            `json:"help"`
	Fixes         []LintFix         `json:"fixes"`
	WithheldFixes []LintWithheldFix `json:"withheld_fixes,omitempty"`
}

type LintFile 

type LintFile struct {
	Path         string         `json:"path"`
	SourceDigest string         `json:"source_digest"`
	ResultDigest string         `json:"result_digest,omitempty"`
	Status       LintFileStatus `json:"status"`
}

type LintFileStatus 

type LintFileStatus string
const (
	LintFileAnalyzed      LintFileStatus = "analyzed"
	LintFilePending       LintFileStatus = "pending"
	LintFileUnchanged     LintFileStatus = "unchanged"
	LintFileFixed         LintFileStatus = "fixed"
	LintFileConflict      LintFileStatus = "conflict"
	LintFileFailed        LintFileStatus = "failed"
	LintFilePossiblyFixed LintFileStatus = "possibly_fixed"
)

type LintFix 

type LintFix struct {
	Name   string          `json:"name"`
	Safety rules.FixSafety `json:"safety"`
}

type LintFixOutcome 

type LintFixOutcome struct {
	Path          string
	SourceDigest  source.Digest
	Status        LintFileStatus
	Applied       []fixengine.Applied
	Rejected      []fixengine.Rejection
	ImportChanges []fixengine.ImportChange
}

LintFixOutcome binds one original source version to its fix transaction.

type LintFixTextInput 

type LintFixTextInput struct {
	File       *source.File
	ResultFile *source.File
	Result     analysis.Result
	Outcome    LintFixOutcome
}

type LintImportChange 

type LintImportChange struct {
	Action       fixengine.ImportAction `json:"action"`
	ImportPath   string                 `json:"import_path"`
	ImportName   string                 `json:"import_name"`
	Path         string                 `json:"path"`
	SourceDigest string                 `json:"source_digest"`
}

type LintPackageDiagnostic 

type LintPackageDiagnostic struct {
	PackageID string   `json:"package_id"`
	Targets   []string `json:"targets,omitempty"`
	Kind      string   `json:"kind"`
	Position  string   `json:"position,omitempty"`
	Message   string   `json:"message"`
}

LintPackageDiagnostic is one stable package-loading, parse, or type error.

type LintRejectedFix 

type LintRejectedFix struct {
	RuleID       string                    `json:"rule_id"`
	FixName      string                    `json:"fix_name"`
	Path         string                    `json:"path"`
	SourceDigest string                    `json:"source_digest"`
	Range        ByteRange                 `json:"range"`
	Reason       fixengine.RejectionReason `json:"reason"`
	Message      string                    `json:"message"`
}

type LintRelated 

type LintRelated struct {
	Range   ByteRange `json:"range"`
	Message string    `json:"message"`
}

type LintResult 

type LintResult struct {
	SchemaVersion       int                     `json:"schema_version"`
	Command             string                  `json:"command"`
	Mode                string                  `json:"mode"`
	Outcome             Outcome                 `json:"outcome"`
	Summary             LintSummary             `json:"summary"`
	Files               []LintFile              `json:"files"`
	Diagnostics         []LintDiagnostic        `json:"diagnostics"`
	SuppressionProblems []SuppressionProblem    `json:"suppression_problems"`
	UnusedSuppressions  []UnusedSuppression     `json:"unused_suppressions"`
	BaselineProblems    []BaselineProblem       `json:"baseline_problems"`
	PackageDiagnostics  []LintPackageDiagnostic `json:"package_diagnostics,omitempty"`
	SourceProblems      []LintSourceProblem     `json:"source_problems,omitempty"`
	AppliedFixes        []LintAppliedFix        `json:"applied_fixes,omitempty"`
	RejectedFixes       []LintRejectedFix       `json:"rejected_fixes,omitempty"`
	ImportChanges       []LintImportChange      `json:"import_changes,omitempty"`
	Errors              []Error                 `json:"errors"`
}

func NewLintFixResult 

func NewLintFixResult(
	category string,
	exitCode int,
	complete bool,
	results []analysis.Result,
	outcomes []LintFixOutcome,
	errs []Error,
) (LintResult, error)

NewLintFixResult validates and maps one ordered set of fix transactions.

func NewLintResult 

func NewLintResult(
	mode, category string,
	exitCode int,
	complete bool,
	results []analysis.Result,
	errs []Error,
) (LintResult, error)

NewLintResult validates and maps ordered analysis results into schema version 1.

func NewPackageLintResult 

func NewPackageLintResult(
	mode, category string,
	exitCode int,
	complete bool,
	packageResult analysis.PackageResult,
	errs []Error,
) (LintResult, error)

NewPackageLintResult adds typed prerequisite and source-model problems to a versioned lint result without treating them as rule diagnostics.

type LintSourceProblem 

type LintSourceProblem struct {
	Path         string   `json:"path"`
	SourceDigest string   `json:"source_digest"`
	Targets      []string `json:"targets,omitempty"`
	Message      string   `json:"message"`
}

LintSourceProblem is one source-model failure retained outside rule results.

type LintStatistics 

type LintStatistics struct {
	SchemaVersion    int                   `json:"schema_version"`
	Command          string                `json:"command"`
	Outcome          Outcome               `json:"outcome"`
	Complete         bool                  `json:"complete"`
	MaximumTier      string                `json:"maximum_tier"`
	Packages         int                   `json:"packages"`
	Files            int                   `json:"files"`
	LoadedFiles      int                   `json:"loaded_files"`
	Total            LintStatisticsMetric  `json:"total"`
	Phases           []LintStatisticsPhase `json:"phases"`
	Tiers            []LintStatisticsTier  `json:"tiers"`
	Rules            []LintStatisticsRule  `json:"rules"`
	Cache            LintStatisticsCache   `json:"cache"`
	DependencySyntax LintStatisticsLoad    `json:"dependency_syntax"`
	EffectFacts      LintStatisticsLoad    `json:"effect_facts"`
}

LintStatistics is the schema-versioned opt-in lint profiling document.

func NewLintStatistics 

func NewLintStatistics(
	command string,
	category string,
	exitCode int,
	snapshot analysis.StatisticsSnapshot,
	results []analysis.Result,
) LintStatistics

NewLintStatistics combines analysis telemetry with final reporter-visible diagnostic dispositions in canonical order.

type LintStatisticsCache 

type LintStatisticsCache struct {
	Lookups       uint64 `json:"lookups"`
	Hits          uint64 `json:"hits"`
	Misses        uint64 `json:"misses"`
	Invalidations uint64 `json:"invalidations"`
	Writes        uint64 `json:"writes"`
}

LintStatisticsCache reports observable persistent cache outcomes. An invalidation is a found entry rejected by semantic validation; ordinary key changes appear as misses.

type LintStatisticsLoad 

type LintStatisticsLoad struct {
	Loaded  bool     `json:"loaded"`
	Reasons []string `json:"reasons"`
}

LintStatisticsLoad explains an optional package-loading expansion.

type LintStatisticsMetric 

type LintStatisticsMetric struct {
	Calls               uint64 `json:"calls"`
	DurationNanoseconds int64  `json:"duration_ns"`
	Allocations         uint64 `json:"allocations"`
	AllocatedBytes      uint64 `json:"allocated_bytes"`
}

LintStatisticsMetric is one process-local cost measurement. Allocation values cover this process and exclude allocations in Go tool subprocesses.

type LintStatisticsPhase 

type LintStatisticsPhase struct {
	Name   string               `json:"name"`
	Metric LintStatisticsMetric `json:"metric"`
}

LintStatisticsPhase compares package loading with in-process analysis.

type LintStatisticsRule 

type LintStatisticsRule struct {
	ID                  string `json:"id"`
	Tier                string `json:"tier"`
	Calls               uint64 `json:"calls"`
	DurationNanoseconds int64  `json:"duration_ns"`
	Allocations         uint64 `json:"allocations"`
	AllocatedBytes      uint64 `json:"allocated_bytes"`
	Findings            int    `json:"findings"`
	Diagnostics         int    `json:"diagnostics"`
	Preexisting         int    `json:"preexisting"`
	Suppressed          int    `json:"suppressed"`
	Baselined           int    `json:"baselined"`
}

LintStatisticsRule combines one rule's cost and final disposition counts.

type LintStatisticsTier 

type LintStatisticsTier struct {
	Tier    string               `json:"tier"`
	Reasons []string             `json:"reasons"`
	Metric  LintStatisticsMetric `json:"metric"`
}

LintStatisticsTier explains why a representation was constructed.

type LintSummary 

type LintSummary struct {
	Files                  int  `json:"files"`
	Diagnostics            int  `json:"diagnostics"`
	PreexistingDiagnostics int  `json:"preexisting_diagnostics,omitempty"`
	Suppressed             int  `json:"suppressed"`
	Baselined              int  `json:"baselined"`
	BaselineProblems       int  `json:"baseline_problems"`
	SuppressionProblems    int  `json:"suppression_problems"`
	UnusedSuppressions     int  `json:"unused_suppressions"`
	PackageDiagnostics     int  `json:"package_diagnostics,omitempty"`
	SourceProblems         int  `json:"source_problems,omitempty"`
	FixedFiles             int  `json:"fixed_files,omitempty"`
	AppliedFixes           int  `json:"applied_fixes,omitempty"`
	RejectedFixes          int  `json:"rejected_fixes,omitempty"`
	ImportChanges          int  `json:"import_changes,omitempty"`
	Complete               bool `json:"complete"`
}

type LintTextInput 

type LintTextInput struct {
	File   *source.File
	Result analysis.Result
}

LintTextInput binds one analysis result to the source used for locations.

type LintWithheldFix 

type LintWithheldFix struct {
	Name    string                     `json:"name"`
	Reason  rules.FixWithholdingReason `json:"reason"`
	Message string                     `json:"message"`
}

type Outcome 

type Outcome struct {
	Category string `json:"category"`
	ExitCode int    `json:"exit_code"`
}

type Result 

type Result struct {
	SchemaVersion int     `json:"schema_version"`
	Command       string  `json:"command"`
	Mode          string  `json:"mode"`
	Outcome       Outcome `json:"outcome"`
	Summary       Summary `json:"summary"`
	Files         []File  `json:"files"`
	Errors        []Error `json:"errors"`
}

func NewFormatResult 

func NewFormatResult(
	mode, category string,
	exitCode, selected, changed int,
	complete bool,
	files []File,
	errs []Error,
) Result

type RuleDeprecation 

type RuleDeprecation struct {
	Since       string `json:"since"`
	Replacement string `json:"replacement,omitempty"`
	Message     string `json:"message"`
}

type RuleExample 

type RuleExample struct {
	Title     string `json:"title"`
	Incorrect string `json:"incorrect"`
	Correct   string `json:"correct"`
}

type RuleExplanation 

type RuleExplanation struct {
	SchemaVersion int          `json:"schema_version"`
	Command       string       `json:"command"`
	Rule          RuleMetadata `json:"rule"`
}

RuleExplanation is the versioned machine-readable explain contract.

type RuleFix 

type RuleFix struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Safety      string `json:"safety"`
}

type RuleListOptions 

type RuleListOptions struct {
	Preset      *rules.Preset
	Requirement *rules.Requirement
	Fixable     bool
}

RuleListOptions filters rule discovery by exact canonical metadata.

type RuleMetadata 

type RuleMetadata struct {
	ID                       string           `json:"id"`
	Summary                  string           `json:"summary"`
	Documentation            string           `json:"documentation"`
	DefaultSeverity          string           `json:"default_severity"`
	Presets                  []string         `json:"presets"`
	MinimumGoVersion         string           `json:"minimum_go_version"`
	AnalysisTier             string           `json:"analysis_tier"`
	NodeInterests            []string         `json:"node_interests"`
	RequiresDependencySyntax bool             `json:"requires_dependency_syntax"`
	RequiresEffectFacts      bool             `json:"requires_effect_facts"`
	RunOnGenerated           bool             `json:"run_on_generated"`
	RunDespiteTypeErrors     bool             `json:"run_despite_type_errors"`
	Categories               []string         `json:"categories"`
	Fixes                    []RuleFix        `json:"fixes"`
	Options                  []RuleOption     `json:"options"`
	Deprecation              *RuleDeprecation `json:"deprecation,omitempty"`
	KnownLimitations         []string         `json:"known_limitations"`
	Examples                 []RuleExample    `json:"examples"`
}

RuleMetadata is the stable machine-readable projection of canonical rule metadata.

type RuleOption 

type RuleOption struct {
	Name     string `json:"name"`
	Summary  string `json:"summary"`
	Kind     string `json:"kind"`
	Required bool   `json:"required"`
	Default  string `json:"default,omitempty"`
	Minimum  *int64 `json:"minimum,omitempty"`
	Maximum  *int64 `json:"maximum,omitempty"`
}

type Summary 

type Summary struct {
	Files    int  `json:"files"`
	Changed  int  `json:"changed"`
	Complete bool `json:"complete"`
}

type SuppressionProblem 

type SuppressionProblem struct {
	Kind         suppressions.ProblemKind `json:"kind"`
	Path         string                   `json:"path"`
	SourceDigest string                   `json:"source_digest"`
	Range        ByteRange                `json:"range"`
	Message      string                   `json:"message"`
}

type UnusedSuppression 

type UnusedSuppression struct {
	RuleID       string    `json:"rule_id"`
	Scope        string    `json:"scope"`
	Path         string    `json:"path"`
	SourceDigest string    `json:"source_digest"`
	Range        ByteRange `json:"range"`
	Target       ByteRange `json:"target"`
	Reason       string    `json:"reason"`
	ExpiresOn    string    `json:"expires_on,omitempty"`
}

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.