Documentation
¶
Overview ¶
Package doctor detects state anomalies in spec and prompt files.
Index ¶
- func FormatAuditLine(entry AuditEntry) string
- func WriteAuditEntry(ctx context.Context, path string, entry AuditEntry) error
- type AppliedFix
- type ApplyOptions
- type ApplyResult
- type AuditEntry
- type Category
- type Checker
- type Deps
- type FailedFix
- type Finding
- type Fixer
- type FixerDeps
- type PromptManager
- type SkippedFix
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 ¶
Checker detects state anomalies in spec and prompt files.
func NewChecker ¶
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 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.
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 ¶
SkippedFix records a fix that was skipped.
Source Files
¶
- audit.go
- doc.go
- doctor.go
- duplicate_spec_numbers.go
- fix_legacy_lock_file.go
- fix_orphan_in_progress.go
- fix_renumber.go
- fix_status_dir_mismatch.go
- fix_sweep.go
- fix_unlink.go
- fixer.go
- generating_without_prompt.go
- legacy_lock_file.go
- missing_completed_prompt.go
- orphan_in_progress_prompt.go
- orphan_prompt_link.go
- parse_errors.go
- prompted_not_swept.go
- releaselock.go
- status_dir_mismatch.go
- verifying_stale.go