scanreport

package
v0.12.2 Latest Latest
Warning

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

 Go to latest Published: Sep 21, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package scanreport is the cobra-free scan report: one in-memory View, with JSON and human renderers. jsonOutput and friends are encode-only projections of View, not a second domain graph.

Index

Constants

View Source 
const JSONSchemaVersion = 1

JSONSchemaVersion is the version of the top-level `scan --json` contract. Consumers should treat an unknown version as unsupported. The historical `worktrees` field stays as a 0.x compatibility alias for the canonical `items` array during the 0.x period (see docs/JSON_SCHEMA.md).

Variables

This section is empty.

Functions

func AgeString added in v0.12.1 

func AgeString(d time.Duration) string

AgeString renders a rounded age as "today" or whole days.

func AutoRelaxCacheAge 

func AutoRelaxCacheAge() (bool, string)

AutoRelaxCacheAge reports whether default-clean should ignore --age for official regenerable caches on the home volume. True only when that volume is critical. The returned device limits relaxation to that volume.

func CleanAgeDisplay added in v0.12.1 

func CleanAgeDisplay(age time.Duration) string

CleanAgeDisplay renders a policy age as days, hours, or a Go duration.

func DefaultCleanPolicy 

func DefaultCleanPolicy() types.PruneOptions

DefaultCleanPolicy is the prune policy scan uses for the default-clean estimate. It matches clean's own defaults, including the agent-state idle floor and automatic critical-volume cache relaxation.

func DisplayHomePath added in v0.12.1 

func DisplayHomePath(home, path string) string

DisplayHomePath rewrites path as ~/rel when it is inside home.

func Headline 

func Headline(found int64, paths []ReclaimPath, report *volume.Report) string

Headline is the one-line scan summary: found size, largest non-default reclaim, and home-volume pressure.

func HomeDefaultCleanSize 

func HomeDefaultCleanSize(items []types.DebrisInfo, defaultPolicy types.PruneOptions, fallback int64) int64

HomeDefaultCleanSize is the default-clean eligible size on the home volume, or fallback when the home device cannot be resolved.

func HomeVolumeReport 

func HomeVolumeReport(items []types.DebrisInfo) *volume.Report

HomeVolumeReport inspects the home volume and attributes physical debris to that device versus others.

func ItemAgeAndStatus added in v0.12.1 

func ItemAgeAndStatus(w types.DebrisInfo) string

ItemAgeAndStatus is the age/status label shared by scan largest rows and clean target rows.

func ItemCleanupKind added in v0.12.1 

func ItemCleanupKind(w types.DebrisInfo) types.CleanupKind

ItemCleanupKind is the effective cleanup kind, defaulting to remove-path.

func ItemName added in v0.12.1 

func ItemName(w types.DebrisInfo) string

ItemName is the display name shared by scan largest rows and clean target rows.

func ItemNoun added in v0.12.1 

func ItemNoun(count int) string

ItemNoun pluralizes "item" for counts.

func ItemProject added in v0.12.1 

func ItemProject(w types.DebrisInfo) string

ItemProject is the project label shared by scan largest rows and clean target rows.

func ItemReason added in v0.12.1 

func ItemReason(w types.DebrisInfo) string

ItemReason is the JSON/human reason string derived from category, status, classification, or an explicit scanner reason.

func ItemRisk added in v0.12.1 

func ItemRisk(w types.DebrisInfo) string

ItemRisk is the JSON/human risk label derived from category.

func PressureEstimate 

func PressureEstimate(items []types.DebrisInfo, defaultPolicy types.PruneOptions) int64

PressureEstimate is the home-volume reclaim size under relaxed cache age. When the home device is unknown the estimate falls back to default-clean size for the full item set.

func SizeByLabel 

func SizeByLabel(paths []ReclaimPath, label string) int64

SizeByLabel returns the estimated size of the named reclaim path, or 0.

func StripEstimate 

func StripEstimate(items []types.DebrisInfo, opts types.PruneOptions) int64

StripEstimate is the strippable-byte total clean --strip would reclaim from the current working directory.

func WriteCleanupDiagnostics added in v0.12.1 

func WriteCleanupDiagnostics(w io.Writer, summary CleanupProjection, opts types.PruneOptions)

WriteCleanupDiagnostics prints default-clean blocked-reason buckets.

func WriteHeadline added in v0.12.1 

func WriteHeadline(w io.Writer, found int64, paths []ReclaimPath, report *volume.Report)

WriteHeadline prints the one-line scan summary and optional pressure hint.

func WriteHuman added in v0.12.1 

func WriteHuman(w io.Writer, view View)

WriteHuman renders the human scan report from View.

func WriteHumanExclusions added in v0.12.1 

func WriteHumanExclusions(w io.Writer, view View)

WriteHumanExclusions prints discovery-only exclusion diagnostics.

func WriteJSON added in v0.12.1 

func WriteJSON(w io.Writer, view View)

WriteJSON encodes view as the public scan --json document.

func WriteNext added in v0.12.1 

func WriteNext(w io.Writer, view View)

WriteNext prints the reclaim ladder, review-only line, and scan --json hint.

func WriteRetention added in v0.12.1 

func WriteRetention(w io.Writer, projection types.RetentionProjection)

WriteRetention prints the read-only retention projection.

func WriteReviewOnlyLine added in v0.12.1 

func WriteReviewOnlyLine(w io.Writer, n int, size int64)

WriteReviewOnlyLine prints the next-section review-only worktree summary.

func WriteVolumePressure added in v0.12.1 

func WriteVolumePressure(w io.Writer, report *volume.Report)

WriteVolumePressure prints the home-volume pressure lines.

Types

type CleanupBucket 

type CleanupBucket struct {
	Count int
	Size  int64
}

CleanupBucket is one blocked-reason count/size pair.

type CleanupProjection 

type CleanupProjection struct {
	EligibleCount               int
	EligibleSize                int64
	ActiveCount                 int
	ActiveSize                  int64
	RiskyCount                  int
	RiskySize                   int64
	AgeCount                    int
	AgeSize                     int64
	FilterCount                 int
	FilterSize                  int64
	AgentStateLiveCount         int
	AgentStateLiveSize          int64
	AgentStateUndeterminedCount int
	AgentStateUndeterminedSize  int64
	OtherBlocked                map[cleaner.EligibilityReason]CleanupBucket
}

CleanupProjection is the default-clean estimate plus the reason buckets the human scan printer shows. One evaluation of eligibility + normalize.

func SummarizeCleanup 

func SummarizeCleanup(items []types.DebrisInfo, opts types.PruneOptions) CleanupProjection

SummarizeCleanup projects items through eligibility + target normalization.

type CodexActivityNotice added in v0.12.1 

type CodexActivityNotice struct {
	ProtectedCount int
}

CodexActivityNotice is the optional human-only Codex activity line. JSON does not serialize it. cmd fills it from the session index.

type Item added in v0.12.1 

type Item struct {
	Tool             types.Tool
	Category         types.Category
	ID               string
	Project          string
	Source           string
	Path             string
	Size             int64
	ModTime          time.Time
	Status           types.WorktreeStatus
	Classification   types.EntryClass
	Risk             string
	Reason           string
	CleanupKind      types.CleanupKind
	CleanupCommand   []string
	PhysicalTargetID string
	StrippableBytes  int64
	StrippablePaths  []string
	ReviewOnly       bool
}

Item is one scan-report row with derived presentation fields. JSON encoding projects this onto the public schema; it is not a second debris graph.

type JSONExcludedScope added in v0.12.1 

type JSONExcludedScope struct {
	Pattern  string `json:"pattern"`
	Resolved string `json:"resolved"`
	Source   string `json:"source"`
	Count    int    `json:"count"`
}

JSONExcludedScope is the encode-only honored exclusion row.

type JSONExclusions added in v0.12.1 

type JSONExclusions struct {
	ExcludedCount int                   `json:"excluded_count"`
	Scopes        []JSONExcludedScope   `json:"scopes"`
	Rejected      []JSONRejectedExclude `json:"rejected"`
}

JSONExclusions is the encode-only top-level exclusions object.

func JSONExclusionsFrom added in v0.12.1 

func JSONExclusionsFrom(excludedByUser int, scopes []types.ExcludedScope, rejected []types.RejectedExclude) *JSONExclusions

JSONExclusionsFrom is the encode-only exclusions object shared by scan JSON and clean JSON. It is nil when no exclusion configuration was honored or rejected, so schema_version stays 1.

func JSONExclusionsFromResult added in v0.12.1 

func JSONExclusionsFromResult(result *types.ScanResult) *JSONExclusions

JSONExclusionsFromResult projects ScanResult exclusion diagnostics. Nil results and scans without exclusion configuration omit the object.

type JSONItem added in v0.12.1 

type JSONItem struct {
	Tool             string   `json:"tool"`
	Category         string   `json:"category"`
	ID               string   `json:"id"`
	Project          string   `json:"project"`
	Source           string   `json:"source"`
	Path             string   `json:"path"`
	Size             int64    `json:"size"`
	ModTime          string   `json:"mod_time"`
	Status           string   `json:"status"`
	Classification   string   `json:"classification,omitempty"`
	Risk             string   `json:"risk"`
	Reason           string   `json:"reason"`
	CleanupKind      string   `json:"cleanup_kind"`
	CleanupCommand   []string `json:"cleanup_command"`
	PhysicalTargetID string   `json:"physical_target_id"`
	StrippableBytes  int64    `json:"strippable_bytes,omitempty"`
	StrippablePaths  []string `json:"strippable_paths,omitempty"`
}

JSONItem is the encode-only projection of View.Items onto the public scan --json item schema. It is not a second domain model.

type JSONOutput added in v0.12.1 

type JSONOutput struct {
	SchemaVersion  int                      `json:"schema_version"`
	Items          []JSONItem               `json:"items"`
	Worktrees      []JSONItem               `json:"worktrees"`
	Summary        JSONSummary              `json:"summary"`
	Retention      JSONRetention            `json:"retention"`
	Volume         *JSONVolume              `json:"volume,omitempty"`
	Exclusions     *JSONExclusions          `json:"exclusions,omitempty"`
	Partial        bool                     `json:"partial,omitempty"`
	ProviderErrors []JSONProviderError      `json:"provider_errors,omitempty"`
	Diagnostics    []JSONProviderDiagnostic `json:"diagnostics,omitempty"`
}

JSONOutput is the encode-only top-level scan --json document. Field names, types, and nesting are the public schema.

func EncodeJSON added in v0.12.1 

func EncodeJSON(view View) JSONOutput

EncodeJSON projects View onto the public JSON schema. Callers that need the encode-only struct (tests) should use this rather than rebuilding fields.

type JSONProtectPaths added in v0.12.1 

type JSONProtectPaths struct {
	ProtectedCount int                   `json:"protected_count"`
	Scopes         []JSONExcludedScope   `json:"scopes"`
	Rejected       []JSONRejectedExclude `json:"rejected"`
}

JSONProtectPaths is the encode-only clean-only protect-path object. It uses the same scopes/rejected row shape as JSONExclusions so JSON consumers can parse rejected pins the same way. Scan JSON never includes this object.

func JSONProtectPathsFrom added in v0.12.1 

func JSONProtectPathsFrom(protectedCount int, scopes []types.ExcludedScope, rejected []types.RejectedExclude) *JSONProtectPaths

JSONProtectPathsFrom is the encode-only protect-path object for clean JSON. It is nil when no --protect-path flags were honored or rejected, so schema_version stays 1. Honored pins that matched zero inventory items still emit a scope with count 0.

type JSONProviderDiagnostic added in v0.12.1 

type JSONProviderDiagnostic struct {
	Tool       string `json:"tool"`
	State      string `json:"state"`
	Count      int    `json:"count"`
	Bytes      int64  `json:"bytes"`
	DurationMS int64  `json:"duration_ms"`
	Error      string `json:"error,omitempty"`
}

JSONProviderDiagnostic is experimental; see docs/JSON_SCHEMA.md.

type JSONProviderError added in v0.12.1 

type JSONProviderError struct {
	Tool    string `json:"tool"`
	Message string `json:"message"`
}

JSONProviderError is the encode-only partial-scan provider error row.

type JSONRejectedExclude added in v0.12.1 

type JSONRejectedExclude struct {
	Pattern string `json:"pattern"`
	Source  string `json:"source"`
	Reason  string `json:"reason"`
}

JSONRejectedExclude is the encode-only rejected exclusion or protect-path row.

type JSONRetention added in v0.12.1 

type JSONRetention struct {
	Buckets        []JSONRetentionBucket        `json:"buckets"`
	Partial        bool                         `json:"partial"`
	ProviderErrors []JSONRetentionProviderError `json:"provider_errors"`
}

JSONRetention is the encode-only top-level retention object.

type JSONRetentionBucket added in v0.12.1 

type JSONRetentionBucket struct {
	StoreID       string `json:"store_id"`
	BucketID      string `json:"bucket_id"`
	UnitCount     int    `json:"unit_count"`
	MemberCount   int    `json:"member_count"`
	ApparentBytes int64  `json:"apparent_bytes"`
	OrphanedCount int    `json:"orphaned_count"`
	OrphanedBytes int64  `json:"orphaned_bytes"`
}

JSONRetentionBucket is the encode-only retention aggregate row.

type JSONRetentionProviderError added in v0.12.1 

type JSONRetentionProviderError struct {
	StoreID string `json:"store_id"`
	Message string `json:"message"`
}

JSONRetentionProviderError is the encode-only retention store error row.

type JSONSummary added in v0.12.1 

type JSONSummary struct {
	TotalCount           int                         `json:"total_count"`
	TotalSize            int64                       `json:"total_size"`
	PhysicalUnitCount    int                         `json:"physical_unit_count"`
	PhysicalTotalBytes   int64                       `json:"physical_total_bytes"`
	TotalStrippableBytes int64                       `json:"total_strippable_bytes,omitempty"`
	ByCategory           map[string]JSONSummaryEntry `json:"by_category"`
	ByTool               map[string]JSONSummaryEntry `json:"by_tool"`
}

JSONSummary is the encode-only top-level summary object.

type JSONSummaryEntry added in v0.12.1 

type JSONSummaryEntry struct {
	Count              int   `json:"count"`
	Size               int64 `json:"size"`
	PhysicalUnitCount  int   `json:"physical_unit_count"`
	PhysicalTotalBytes int64 `json:"physical_total_bytes"`
	StrippableBytes    int64 `json:"strippable_bytes,omitempty"`
}

JSONSummaryEntry is the encode-only by_category/by_tool summary row.

type JSONVolume added in v0.12.1 

type JSONVolume struct {
	Role                   string  `json:"role"`
	FSType                 string  `json:"fs_type"`
	ID                     string  `json:"id"`
	TotalBytes             uint64  `json:"total_bytes"`
	UsedBytes              uint64  `json:"used_bytes"`
	AvailableBytes         uint64  `json:"available_bytes"`
	UsedPercent            float64 `json:"used_percent"`
	Band                   string  `json:"band"`
	DebrisBytes            int64   `json:"debris_bytes"`
	OtherVolumeDebrisBytes int64   `json:"other_volume_debris_bytes,omitempty"`
}

JSONVolume is the encode-only home-volume pressure object.

func JSONVolumeFromReport added in v0.12.1 

func JSONVolumeFromReport(report volume.Report) *JSONVolume

JSONVolumeFromReport is the encode-only volume object. Band stays the JSON token (low/critical), not the human word.

type ReclaimPath 

type ReclaimPath struct {
	Label   string
	Size    int64
	Command string
}

ReclaimPath is one operator-facing reclaim command and its estimated size.

func LargestNonDefault 

func LargestNonDefault(paths []ReclaimPath) (ReclaimPath, bool)

LargestNonDefault is the biggest reclaim path that beats default delete.

func ReclaimPaths 

func ReclaimPaths(items []types.DebrisInfo, defaultPolicy types.PruneOptions) []ReclaimPath

ReclaimPaths builds the non-zero reclaim ladder for items under policy.

func (ReclaimPath) Flag 

func (p ReclaimPath) Flag() string

Flag is the operator-facing clean flag for this reclaim path.

type ReviewOnly 

type ReviewOnly struct {
	Count int
	Size  int64
}

ReviewOnly is the review-only worktree count and size. Those units are never cleanup or --strip targets.

func ReviewOnlyStats 

func ReviewOnlyStats(items []types.DebrisInfo) ReviewOnly

ReviewOnlyStats counts worktree units that are not cleanup or --strip targets.

type View 

type View struct {
	Partial              bool
	ProviderErrors       []types.ScanProviderError
	Items                []Item
	TotalCount           int
	TotalSize            int64
	PhysicalUnitCount    int
	PhysicalTotalBytes   int64
	TotalStrippableBytes int64
	ByCategory           map[types.Category]types.CategorySummary
	ByTool               map[types.Tool]types.ToolSummary
	Retention            types.RetentionProjection
	Diagnostics          []types.ProviderDiagnostic
	ExcludedByUser       int
	ExcludedScopes       []types.ExcludedScope
	RejectedExcludes     []types.RejectedExclude
	Policy               types.PruneOptions
	CodexActivity        *CodexActivityNotice

	ReclaimPaths     []ReclaimPath
	DefaultCleanSize int64
	DefaultClean     CleanupProjection
	StripEstimate    int64
	PressureEstimate int64
	Volume           *volume.Report
	ReviewOnly       ReviewOnly
	// contains filtered or unexported fields
}

View is the only in-memory scan report model. JSON and human printers render from this type. Tests should assert this model rather than cobra output snapshots.

func FromResult added in v0.12.1 

func FromResult(r *types.ScanResult, policy types.PruneOptions) View

FromResult projects a ScanResult plus default-clean policy into the single in-memory scan report, including the cleanup/reclaim projections the human report prints. The JSON encode path uses FromResultJSON instead.

func FromResultJSON added in v0.12.1 

func FromResultJSON(r *types.ScanResult) View

FromResultJSON projects a ScanResult into the scan view-model for the JSON encode path only. It fills exactly the fields EncodeJSON consumes and skips the cleanup/reclaim/strip/pressure projections FromResult computes for the human report, so scan --json pays only the HomeVolumeReport inspect.

func New 

func New(items []types.DebrisInfo, policy types.PruneOptions) View

New projects items through the default-clean policy into the scan view-model.

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.