cleanup

Documentation

Index

• Constants
• func CalculateHealth(result ScanResult) int
• func Classify(files []FileInfo) error
• func EmitFindings(files []FileInfo)
• func Enrich(files []FileInfo, cfg Config) error
• func FindDuplicates(files []FileInfo)
• func Score(f *FileInfo) int
• type CompletenessReport
  • func CheckCompleteness(files []FileInfo) CompletenessReport
• type Config
• type ContentClass
  • func (c ContentClass) String() string
• type FileCandidate
• type FileInfo
  • func Walk(cfg Config) ([]FileInfo, error)
  • func (f *FileInfo) AddFinding(finding Finding)
  • func (f *FileInfo) HasFinding(rule string) bool
• type Finding
• type LabeledFile
• type MissingItem
• type Rules
  • func DefaultRules() Rules
  • func LoadRules() Rules
  • func (r Rules) IsZero() bool
• type ScanResult
  • func Categorize(files []FileInfo, cfg Config) ScanResult

Constants

const (
	CatDelete       = "delete_candidates"
	CatDevArtifact  = "dev_artifact_candidates"
	CatArchive      = "archive_candidates"
	CatBrokenLink   = "broken_links"
	CatLargeFile    = "large_files"
	CatMisplaced    = "misplaced_scripts"
	CatMisplacedDoc = "misplaced_docs"
	CatUntrack      = "untrack_candidates"
	CatRenameDocs   = "rename_docs"
)

Category constants — backward compatible with bash script JSON keys.

const (
	SevInfo  = 0
	SevWarn  = 1
	SevError = 2
)

Severity levels for findings.

const (
	RuleUntracked = "untracked"
	RuleStale     = "stale"
	RuleOrphaned  = "orphaned"
	RuleLargeFile = "large-file"
	RuleEmpty     = "empty"
	RuleGenerated = "generated"
	RuleScratch   = "scratch"
	RuleTodoOnly  = "todo-only"
	RuleLogDump   = "log-dump"
	RuleDuplicate = "duplicate"
)

Rule constants for findings.

const (
	StatusClean           = "clean"
	StatusDelete          = "delete"
	StatusArchive         = "archive"
	StatusUntrack         = "untrack"
	StatusDevArtifact     = "dev_artifact"
	StatusMisplacedDoc    = "misplaced_doc"
	StatusMisplacedScript = "misplaced_script"
	StatusLargeFile       = "large_file"
	StatusBrokenLink      = "broken_link"
	StatusRenameDoc       = "rename_doc"
)

Status labels for file inventory.

Functions

func CalculateHealth

func CalculateHealth(result ScanResult) int

CalculateHealth returns a 0-100 score for the repository. Higher is better. 100 = zero cleanup candidates.

func Classify

func Classify(files []FileInfo) error

Classify reads first and last 256 bytes of ambiguous files and sets Content.

func EmitFindings

func EmitFindings(files []FileInfo)

EmitFindings converts enriched FileInfo fields into normalized findings. Call after Walk, Enrich, Classify, and FindDuplicates.

func Enrich

func Enrich(files []FileInfo, cfg Config) error

Enrich adds git intelligence to FileInfo entries: staleness and orphan detection.

func FindDuplicates

func FindDuplicates(files []FileInfo)

FindDuplicates detects duplicate files and sets FileInfo.Duplicate field. Two signals are used: backup suffix patterns and basename collisions by size.

func Score

func Score(f *FileInfo) int

Score returns a 0-100 cleanup confidence score based on findings.

Types

type CompletenessReport

type CompletenessReport struct {
	Path    string        `json:"path"`
	Missing []MissingItem `json:"missing"`
	Score   int           `json:"score"` // 0-100, 100 = fully complete
}

CompletenessReport holds the results of a repo completeness check.

func CheckCompleteness

func CheckCompleteness(files []FileInfo) CompletenessReport

CheckCompleteness analyzes walked files for missing healthy-repo files.

type Config

type Config struct {
	Path      string
	MaxDepth  int
	StaleDays int
	Rules     Rules
}

Config holds CLI flags.

type ContentClass

type ContentClass int

ContentClass for content-aware classification.

const (
	ContentUnknown ContentClass = iota
	ContentGenerated
	ContentScratch
	ContentTodoOnly
	ContentLogDump
	ContentConfig
	ContentMeaningful
)

func (ContentClass) String

func (c ContentClass) String() string

String returns the lowercase name for a ContentClass.

type FileCandidate

type FileCandidate struct {
	File        string    `json:"file"`
	Reason      string    `json:"reason,omitempty"`
	SizeKB      int64     `json:"size_kb"`
	Tracked     *bool     `json:"tracked,omitempty"`
	Referenced  *bool     `json:"referenced,omitempty"`
	Target      string    `json:"target,omitempty"`
	StaleDays   int       `json:"stale_days,omitempty"`
	Score       int       `json:"score,omitempty"`
	ContentHint string    `json:"content_hint,omitempty"`
	Findings    []Finding `json:"findings,omitempty"`
}

FileCandidate is the enriched JSON output per file (superset of bash fields).

type FileInfo

type FileInfo struct {
	Path       string // absolute
	RelPath    string // relative to Config.Path
	Size       int64
	IsDir      bool
	IsSymlink  bool
	IsEmpty    bool // empty directory
	Tracked    bool
	Ignored    bool // matched by .gitignore
	StaleDays  int  // 0 = recently modified
	ModTime    time.Time
	Content    ContentClass
	LinkTarget string    // for symlinks, readlink value
	Duplicate  string    // if set, path of the original this duplicates
	Executable bool      // has executable permission bit
	Orphaned   bool      // deleted from git history but still exists
	Findings   []Finding // normalized signals from all analyzers
	Suppressed bool      // matched by .repocleanignore
}

FileInfo is the internal enriched representation per file.

func Walk

func Walk(cfg Config) ([]FileInfo, error)

Walk returns enriched FileInfo entries for all files and selected directories under cfg.Path up to cfg.MaxDepth levels deep.

func (*FileInfo) AddFinding

func (f *FileInfo) AddFinding(finding Finding)

AddFinding appends a finding to the file's signal list.

func (*FileInfo) HasFinding

func (f *FileInfo) HasFinding(rule string) bool

HasFinding reports whether the file has a finding with the given rule.

type Finding

type Finding struct {
	Source     string  `json:"source"`     // producer: "git", "classify", "duplicates", "walker"
	Rule       string  `json:"rule"`       // signal name from Rule constants
	Severity   int     `json:"severity"`   // SevInfo, SevWarn, SevError
	Confidence float64 `json:"confidence"` // 0.0-1.0
	Message    string  `json:"message"`    // human-readable
}

Finding is a normalized signal produced by any analyzer.

type LabeledFile

type LabeledFile struct {
	File   string `json:"file"`
	Status string `json:"status"`
	Reason string `json:"reason,omitempty"`
	SizeKB int64  `json:"size_kb"`
}

LabeledFile tags every walked file with a disposition status.

type MissingItem

type MissingItem struct {
	Name     string `json:"name"`
	Severity string `json:"severity"` // "error", "warning", "info"
	Why      string `json:"why"`
}

MissingItem represents a file or pattern that a healthy repo should have.

type Rules

type Rules struct {
	DevArtifactPrefixes   []string `json:"dev_artifact_prefixes,omitempty"`
	DevArtifactSuffixes   []string `json:"dev_artifact_suffixes,omitempty"`
	AllowedRootMD         []string `json:"allowed_root_md,omitempty"`
	IgnoredDevDocSuffixes []string `json:"ignored_dev_doc_suffixes,omitempty"`
	IgnoredDeletePrefixes []string `json:"ignored_delete_prefixes,omitempty"`
	IgnoredSafeDirs       []string `json:"ignored_safe_dirs,omitempty"`
	ScaffoldFiles         []string `json:"scaffold_files,omitempty"`
	UntrackDirs           []string `json:"untrack_dirs,omitempty"`
}

Rules holds configurable pattern lists for categorization. Zero values mean "use built-in defaults".

func DefaultRules

func DefaultRules() Rules

DefaultRules returns the built-in defaults (matching the current hardcoded values).

func LoadRules

func LoadRules() Rules

LoadRules reads ~/.config/repoclean/rules.json and merges with defaults. If the file doesn't exist, returns defaults. Only non-empty fields override.

func (Rules) IsZero

func (r Rules) IsZero() bool

IsZero reports whether r has no user-configured values.

type ScanResult

type ScanResult struct {
	Path                  string          `json:"path"`
	HealthScore           int             `json:"health_score"`
	DeleteCandidates      []FileCandidate `json:"delete_candidates"`
	DevArtifactCandidates []FileCandidate `json:"dev_artifact_candidates"`
	ArchiveCandidates     []FileCandidate `json:"archive_candidates"`
	BrokenLinks           []FileCandidate `json:"broken_links"`
	LargeFiles            []FileCandidate `json:"large_files"`
	MisplacedScripts      []FileCandidate `json:"misplaced_scripts"`
	MisplacedDocs         []FileCandidate `json:"misplaced_docs"`
	UntrackCandidates     []FileCandidate `json:"untrack_candidates"`
	RenameDocs            []FileCandidate `json:"rename_docs,omitempty"`
	AllFiles              []LabeledFile   `json:"all_files,omitempty"`
	Summary               map[string]int  `json:"summary"`
}

ScanResult is the top-level JSON output — backward compatible.

func Categorize

func Categorize(files []FileInfo, cfg Config) ScanResult