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 AuditConfig
• type AuditReport
  • func RunTableAudit(ctx context.Context) (*AuditReport, error)
  • func RunTableAuditWithConfig(ctx context.Context, cfg AuditConfig) (*AuditReport, error)
• 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 HasuraFilterStatus
• type Options
• type Summary
• type TableAuditResult

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 AuditConfig

type AuditConfig struct {
	// ProjectRoot is the nSelf project directory. When empty, RunTableAudit walks
	// up from cwd looking for .nself/ or docker-compose.yml.
	ProjectRoot string
	// FilterTable, when non-empty, audits only the named table.
	FilterTable string
}

AuditConfig configures a RunTableAudit call.

type AuditReport

type AuditReport struct {
	// AuditAt is the UTC timestamp of the audit run.
	AuditAt string `json:"audit_at"`
	// Tables contains one entry per np_* table found in the public schema.
	Tables []TableAuditResult `json:"tables"`
}

AuditReport is the top-level JSON structure emitted by RunTableAudit.

func RunTableAudit

func RunTableAudit(ctx context.Context) (*AuditReport, error)

RunTableAudit connects to Postgres using NSELF_DB_URL (fallback: DATABASE_URL) and returns an AuditReport for every np_* table in the public schema.

ctx is forwarded to every DB call. The function adds a 30-second timeout around the total audit run to keep the doctor check bounded.

func RunTableAuditWithConfig

func RunTableAuditWithConfig(ctx context.Context, cfg AuditConfig) (*AuditReport, error)

RunTableAuditWithConfig is RunTableAudit with an explicit AuditConfig.

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 HasuraFilterStatus

type HasuraFilterStatus string

HasuraFilterStatus represents the result of checking Hasura metadata.

const (
	// HasuraFilterPresent means source_account_id filter was found in select_permissions.
	HasuraFilterPresent HasuraFilterStatus = "present"
	// HasuraFilterMissing means no source_account_id filter was found.
	HasuraFilterMissing HasuraFilterStatus = "missing"
	// HasuraFilterUnknown means Hasura metadata was not found or could not be parsed.
	HasuraFilterUnknown HasuraFilterStatus = "unknown"
)

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.

type TableAuditResult

type TableAuditResult struct {
	// Table is the table name (e.g. "np_chat_conversations").
	Table string `json:"table"`
	// HasSourceAccountID reports whether source_account_id exists in the table.
	HasSourceAccountID bool `json:"has_source_account_id"`
	// HasHasuraFilter reports whether Hasura metadata contains a source_account_id
	// filter for this table. "present", "missing", or "unknown" (metadata not found).
	HasHasuraFilter HasuraFilterStatus `json:"has_hasura_filter"`
	// TotalRows is the row count across all source_account_id values.
	TotalRows int64 `json:"total_rows"`
	// Accounts maps source_account_id → row count. Nil when HasSourceAccountID is false.
	Accounts map[string]int64 `json:"accounts,omitempty"`
	// Warning is non-empty when a problem is detected (missing column or multi-account).
	Warning string `json:"warning,omitempty"`
}

TableAuditResult holds the audit result for a single table.