audit

Documentation

Index

• Variables
• func ApplyAutoFix(root string, report *DocReport) ([]string, error)
• func IsSafeAutoFix(f Finding) bool
• func PRDescription(report *DocReport, modified []string, reportPath string) string
• type DocReport
  • func RunDocs(opts Options) (*DocReport, error)
  • func (r *DocReport) WriteJSON(w io.Writer) error
  • func (r *DocReport) WriteSummary(w io.Writer)
• type Finding
• type Options
• type Summary

Variables

var RequiredAnchors = []string{
	".claude/CLAUDE.md",
	".claude/docs/VISION.md",
	".claude/docs/FEATURES.md",
	".claude/docs/MASTER-VERSIONS.md",
	".claude/docs/sport/F00-INDEX.md",
	".claude/docs/sport/F01-MASTER-VERSIONS.md",
	".claude/docs/sport/F02-COMMAND-INVENTORY.md",
	".claude/docs/sport/F06-BUNDLE-INVENTORY.md",
	".claude/docs/sport/F07-PRICING-TIERS.md",
	".claude/docs/sport/F15-BRAND-SPEC.md",
}

RequiredAnchors lists files that every audit expects to exist (relative to the project root). Absence is reported as a `missing_file` finding.

Functions

func ApplyAutoFix

func ApplyAutoFix(root string, report *DocReport) ([]string, error)

ApplyAutoFix rewrites banned words in-place to neutral alternatives. Only banned_word and dead_link findings marked AutoFix are applied.

Returns the set of files that were modified. On any write error, the partial changes that succeeded remain in place (caller should pair this with git to revert on failure).

func IsSafeAutoFix

func IsSafeAutoFix(f Finding) bool

IsSafeAutoFix reports whether f is eligible for silent rewrite in a PR. Currently only banned-word fixes are treated as silent-safe.

func PRDescription

func PRDescription(report *DocReport, modified []string, reportPath string) string

PRDescription returns a human-readable PR body describing the auto-fix run.

The CI workflow uses this when opening a "quarterly doc audit" PR. It summarizes the finding counts, lists the modified files, and links to the full JSON report stored in .claude/qa/findings/.

Types

type DocReport

type DocReport struct {
	Timestamp string    `json:"timestamp"`
	Quarter   string    `json:"quarter"` // e.g. "2026-Q3"
	ScanRoots []string  `json:"scan_roots"`
	FilesScan int       `json:"files_scanned"`
	Findings  []Finding `json:"findings"`
	Summary   Summary   `json:"summary"`
}

DocReport aggregates the findings from one audit run.

func RunDocs

func RunDocs(opts Options) (*DocReport, error)

RunDocs runs a full docs audit and returns the DocReport.

It walks every scan root under opts.Root, inspects markdown files, and emits Finding records for banned words, dead links to local files, and missing required anchors.

func (*DocReport) WriteJSON

func (r *DocReport) WriteJSON(w io.Writer) error

WriteJSON marshals the report as pretty-printed JSON to w.

func (*DocReport) WriteSummary

func (r *DocReport) WriteSummary(w io.Writer)

WriteSummary prints a human-readable summary to w.

type Finding

type Finding struct {
	Category string `json:"category"` // "banned_word" | "dead_link" | "missing_file" | "stale_version" | "broken_section"
	Severity string `json:"severity"` // "low" | "medium" | "high"
	File     string `json:"file"`
	Line     int    `json:"line,omitempty"`
	Match    string `json:"match,omitempty"`
	Message  string `json:"message"`
	AutoFix  bool   `json:"auto_fix"` // true if a safe auto-fix is available
}

Finding represents a single doc-audit finding.

type Options

type Options struct {
	Root       string   // project root (defaults to CWD)
	ScanRoots  []string // subdirs to walk; empty = default set
	Quarter    string   // "YYYY-QN"; empty = computed from time.Now
	IncludeExt []string // file extensions to scan; default {.md,.mdx}
}

Options controls an audit run.

type Summary

type Summary struct {
	Total        int `json:"total"`
	BannedWords  int `json:"banned_words"`
	DeadLinks    int `json:"dead_links"`
	MissingFiles int `json:"missing_files"`
	StaleVersion int `json:"stale_version"`
	Broken       int `json:"broken_section"`
	AutoFixable  int `json:"auto_fixable"`
}

Summary groups findings by category.