doctor

package
v0.199.2 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: BSD-2-Clause Imports: 22 Imported by: 0

Documentation

Overview

Package doctor detects state anomalies in spec and prompt files.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FormatAuditLine added in v0.174.1

func FormatAuditLine(entry AuditEntry) string

FormatAuditLine renders one tab-separated audit line for entry. Format: <rfc3339>\t<Category>\t<action>\t<targets>\t<before>\t<after>\n

func WriteAuditEntry

func WriteAuditEntry(ctx context.Context, path string, entry AuditEntry) error

WriteAuditEntry appends one tab-separated line to the file at path. The directory containing path is created with mode 0750 if missing. The file is created with mode 0600 if missing and appended to otherwise.

Types

type AppliedFix

type AppliedFix struct {
	Category    Category
	TargetPaths []string
	FixCommand  string
	AuditLine   string
}

AppliedFix records a fix that was successfully applied.

type ApplyOptions

type ApplyOptions struct {
	// Yes skips interactive confirmation prompts.
	Yes bool
	// Stdin defaults to os.Stdin if nil.
	Stdin io.Reader
	// Stdout defaults to os.Stdout if nil.
	Stdout io.Writer
	// Stderr defaults to os.Stderr if nil.
	Stderr io.Writer
	// AuditLogPath defaults to .dark-factory/doctor.log relative to project root.
	AuditLogPath string
	// FileLockTimeout defaults to 5 seconds if zero.
	FileLockTimeout time.Duration
}

ApplyOptions controls the Fixer.Apply behavior.

type ApplyResult

type ApplyResult struct {
	Applied []AppliedFix
	Skipped []SkippedFix
	Failed  []FailedFix
}

ApplyResult summarises the outcome of Fixer.Apply.

type AuditEntry

type AuditEntry struct {
	Timestamp   time.Time
	Category    Category
	Action      string // "applied", "skipped", "failed"
	TargetPaths []string
	Before      string
	After       string
}

AuditEntry records a single audit log event.

type Category

type Category string

Category describes the type of anomaly detected.

const CategoryDuplicateSpecNumbers Category = "duplicate-spec-numbers"

CategoryDuplicateSpecNumbers indicates two or more spec files share the same numeric prefix.

const CategoryGeneratingWithoutPrompt Category = "generating-without-prompt"

CategoryGeneratingWithoutPrompt indicates a spec parked in generating status with no prompt referencing it. generating is transient and nothing times it out, so a generation that died leaves the spec stuck here silently — no other detector covers it, and status-dir-mismatch explicitly permits generating in specs/in-progress/.

const CategoryLegacyLockFile Category = "legacy-lock-file"

CategoryLegacyLockFile indicates a leftover *.lock sidecar from the abandoned per-file locking scheme (spec 097). These empty files are removed by doctor --fix.

const CategoryMissingCompletedPrompt Category = "missing-completed-prompt"

CategoryMissingCompletedPrompt indicates a prompt number below the highest number present anywhere in prompts/ that has no file in prompts/completed/. This is the gap that makes the execution guard refuse every spec-less prompt below it (reason=previous-prompt-not-completed).

const CategoryOrphanInProgressPrompt Category = "orphan-in-progress-prompt"

CategoryOrphanInProgressPrompt indicates a prompt in in-progress/ links to a completed or rejected spec.

const CategoryOrphanPromptLink Category = "orphan-prompt-link"

CategoryOrphanPromptLink indicates a prompt references a spec that does not exist.

const CategoryParseError Category = "parse-errors"

CategoryParseError indicates a file's YAML frontmatter could not be parsed.

const CategoryPromptedNotSwept Category = "prompted-but-not-swept"

CategoryPromptedNotSwept indicates a spec is in "prompted" status but all linked prompts are terminal.

const CategoryStatusDirMismatch Category = "status-dir-mismatch"

CategoryStatusDirMismatch indicates a file resides in a directory inconsistent with its status field.

const CategoryVerifyingStale Category = "verifying-stale"

CategoryVerifyingStale indicates a spec is in "verifying" status with a stale or missing timestamp.

type Checker

type Checker interface {
	Check(ctx context.Context) ([]Finding, error)
}

Checker detects state anomalies in spec and prompt files.

func NewChecker

func NewChecker(deps Deps) Checker

NewChecker creates a Checker with the given dependencies.

type Deps

type Deps struct {
	SpecsInboxDir         string
	SpecsInProgressDir    string
	SpecsCompletedDir     string
	SpecsRejectedDir      string
	PromptsInboxDir       string
	PromptsInProgressDir  string
	PromptsCompletedDir   string
	PromptsCancelledDir   string
	PromptsRejectedDir    string
	SpecLister            spec.Lister
	PromptManager         PromptManager
	CurrentDateTimeGetter libtime.CurrentDateTimeGetter
	VerifyingStaleHours   int
}

Deps holds the directory paths and scanners required by the Checker.

type FailedFix

type FailedFix struct {
	Category    Category
	TargetPaths []string
	Detail      string
}

FailedFix records a fix that failed.

type Finding

type Finding struct {
	// Category is the type of anomaly detected.
	Category Category
	// TargetPaths are the file paths involved in the anomaly (always sorted lexicographically).
	TargetPaths []string
	// SpecID is the numeric spec identifier associated with the finding (empty when not a spec finding).
	SpecID string
	// Detail is a human-readable one-line description of the anomaly.
	Detail string
	// FixCommand is the copy-paste command to fix the anomaly.
	FixCommand string
}

Finding represents a detected anomaly in spec or prompt files.

type Fixer

type Fixer interface {
	Apply(ctx context.Context, findings []Finding, opts ApplyOptions) (ApplyResult, error)
}

Fixer applies fixes for anomalies detected by Checker.

func NewFixer

func NewFixer(deps FixerDeps) Fixer

NewFixer creates a Fixer with the given dependencies.

type FixerDeps

type FixerDeps struct {
	Deps
	AutoCompleter   spec.AutoCompleter
	Mover           prompt.FileMover
	FileLockFactory func(path string) lock.DirLock
}

FixerDeps holds the dependencies for the Fixer. It reuses the same Deps struct as the Checker (same scanners are needed) and adds the mutating-phase dependencies.

type PromptManager

type PromptManager interface {
	Load(ctx context.Context, path string) (*prompt.PromptFile, error)
	MoveToCancelled(ctx context.Context, path string) error
}

PromptManager is the subset of prompt.Manager that the doctor package uses.

type SkippedFix

type SkippedFix struct {
	Category    Category
	TargetPaths []string
	Detail      string
}

SkippedFix records a fix that was skipped.

Directories

Path Synopsis
Code generated by counterfeiter.
Code generated by counterfeiter.

Jump to

Keyboard shortcuts

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