docs

Documentation

Overview

Package docs provides deterministic markdown documentation operations. The CheckLinksResult JSON schema is stable — field names and types must not change after first merge. Skills parse `nightgauge docs check-links --json` output; any breaking change requires incrementing the V field.

The check-links verb replaces the bash + grep + dirname link-validation chain duplicated across docs-write Phase 7 and update-docs Phase 4.5 (audit row B6). It is non-fatal by design: missing files become findings[]; unreadable files become warnings[]; only hard input errors (e.g. unresolvable root) return a non-nil error.

Package docs provides deterministic markdown documentation operations. FreshnessResult JSON schema is stable — field names and types must not change after first merge. Skills parse `nightgauge docs check-freshness --json` output; any breaking change requires incrementing the V field.

The check-freshness verb replaces the bash + git log prose in update-docs Phase 4.8 (audit row B36).

Package docs provides deterministic markdown documentation operations. PatternDetectResult JSON schema is stable — field names and types must not change after first merge. Skills parse `nightgauge docs detect-patterns --json` output; any breaking change requires incrementing the V field.

The detect-patterns verb replaces the inline bash grep loop in docs-write Phase 1.5 Step 1.5.1 (audit row B35). It is non-fatal by design: unreadable files produce warnings; only hard input errors (invalid glob syntax) return a non-nil error.

Package docs provides deterministic markdown documentation operations. VersionConsistencyResult JSON schema is stable — field names and types must not change after first merge. Skills parse `nightgauge docs version-consistency --json` output; any breaking change requires incrementing the V field.

The version-consistency verb replaces the bash project-type detection and version extraction prose in update-docs Phase 4.6 (audit row B36).

Index

• Constants
• func PrintDetectPatternsHuman(r *PatternDetectResult) string
• type ChangeEntry
• type CheckFreshnessOptions
• type CheckLinksOptions
• type CheckLinksResult
  • func Run(_ context.Context, opts CheckLinksOptions) (*CheckLinksResult, error)
• type Entry
• type Finding
• type FreshnessResult
  • func CheckFreshness(_ context.Context, opts CheckFreshnessOptions) (*FreshnessResult, error)
• type Pattern
• type PatternDetectOptions
• type PatternDetectResult
  • func DetectPatterns(opts PatternDetectOptions) (*PatternDetectResult, error)
• type RemoveEntry
• type SnapshotDiffOptions
• type SnapshotDiffResult
  • func SnapshotDiff(opts SnapshotDiffOptions) (*SnapshotDiffResult, error)
• type StaleFinding
• type VersionConsistencyOptions
• type VersionConsistencyResult
  • func VersionConsistency(_ context.Context, opts VersionConsistencyOptions) (*VersionConsistencyResult, error)
• type VersionMismatch

Constants

const (
	ReasonFileNotFound = "file_not_found"
	ReasonOutsideRoot  = "outside_root"
	ReasonUnreadable   = "unreadable"
)

Reason values emitted in Finding.Reason. The enum is closed to keep skills parsing simple — additions require bumping V.

Functions

func PrintDetectPatternsHuman

func PrintDetectPatternsHuman(r *PatternDetectResult) string

PrintDetectPatternsHuman renders detect-patterns result in human-readable form.

Types

type ChangeEntry

type ChangeEntry struct {
	URL     string `json:"url"`
	Hash    string `json:"hash"`     // current sha256 hex
	OldHash string `json:"old_hash"` // hash recorded in the snapshot
}

ChangeEntry describes a page whose content hash differs from the snapshot.

type CheckFreshnessOptions

type CheckFreshnessOptions struct {
	// Root is the directory tree to scan. When empty, the caller's CWD is used.
	Root string
	// GitRunner allows tests to substitute a mock git executor. When nil the
	// real git binary is used. Returns (dateString, warning); warning is
	// non-empty when the runner encountered a non-fatal problem.
	GitRunner func(file string) (string, string)
}

CheckFreshnessOptions controls a single check-freshness run.

type CheckLinksOptions

type CheckLinksOptions struct {
	// Root is the directory tree to scan. When empty, the caller's CWD is
	// used. The path is resolved to its absolute form before scanning.
	Root string
	// Target restricts validation to a single markdown file (path relative
	// to Root, or absolute). When empty, the entire Root tree is walked.
	Target string
	// Section restricts validation to links found between a `## Section`
	// (or any heading whose text equals Section, case-insensitive) and the
	// next heading of the same-or-greater level. When empty, all links in
	// each file are validated.
	Section string
	// ExcludeTemplates skips skill and command files that contain template
	// content referencing files the template will create in target repos.
	// When true, paths matching `*/skills/*/SKILL.md` and
	// `*/claude-plugins/*/commands/*` are not scanned.
	ExcludeTemplates bool
}

CheckLinksOptions controls a single check-links run.

type CheckLinksResult

type CheckLinksResult struct {
	V            int       `json:"v"`             // schema version, always 1
	Root         string    `json:"root"`          // absolute path that was scanned
	FilesScanned int       `json:"files_scanned"` // count of markdown files inspected
	LinksTotal   int       `json:"links_total"`   // total relative links examined (broken + resolved)
	LinksBroken  int       `json:"links_broken"`  // count of findings (== len(Findings))
	Findings     []Finding `json:"findings"`      // one entry per broken link
	Warnings     []string  `json:"warnings"`      // non-fatal scan warnings (unreadable files, etc.)
}

CheckLinksResult is the stable JSON output schema for `nightgauge docs check-links`. Schema version 1 — do not rename or remove fields after first merge.

func Run

func Run(_ context.Context, opts CheckLinksOptions) (*CheckLinksResult, error)

Run executes the check-links scan and returns the structured result. The function never returns a non-nil error for missing-file findings or unreadable files — those are recorded inside Findings/Warnings. err is reserved for hard input errors (unresolvable root, target outside root).

type Entry

type Entry struct {
	URL  string `json:"url"`
	Hash string `json:"hash"` // sha256 hex of the page body
}

Entry describes a newly discovered page.

type Finding

type Finding struct {
	File     string `json:"file"`     // path relative to Root
	Line     int    `json:"line"`     // 1-based line number where the link appeared
	Link     string `json:"link"`     // raw link text inside the markdown ()
	Resolved string `json:"resolved"` // absolute resolved path (or attempted resolution)
	Anchor   string `json:"anchor"`   // anchor portion after #, "" when absent
	Reason   string `json:"reason"`   // closed enum: file_not_found, outside_root, unreadable
}

Finding records a single broken relative link discovered in a scanned markdown file. Anchors are recorded verbatim but not verified — v1 only validates the file part. See ADR-003 in the issue knowledge base.

type FreshnessResult

type FreshnessResult struct {
	V                        int            `json:"v"`                           // schema version, always 1
	Root                     string         `json:"root"`                        // absolute path scanned
	FilesScanned             int            `json:"files_scanned"`               // count of markdown files inspected
	FilesWithUpdatedMetadata int            `json:"files_with_updated_metadata"` // count with an "Updated:" line
	StaleFindings            []StaleFinding `json:"stale_findings"`              // one entry per stale file
	StaleCount               int            `json:"stale_count"`                 // len(StaleFindings)
	Warnings                 []string       `json:"warnings"`                    // non-fatal scan warnings
}

FreshnessResult is the stable JSON output schema for `nightgauge docs check-freshness`. Schema version 1 — do not rename or remove fields after first merge.

func CheckFreshness

func CheckFreshness(_ context.Context, opts CheckFreshnessOptions) (*FreshnessResult, error)

CheckFreshness detects markdown files whose "Updated:" metadata lags behind the most recent git commit that touched each file.

type Pattern

type Pattern struct {
	Slug  string   `json:"slug"`
	Files []string `json:"files"`
}

Pattern records a single matched pattern slug and the files that matched it.

type PatternDetectOptions

type PatternDetectOptions struct {
	// FilesGlob is a glob pattern passed to filepath.Glob. Required.
	FilesGlob string
	// JSON controls whether the caller wants JSON output (for CLI flag wiring).
	JSON bool
}

PatternDetectOptions controls a single detect-patterns run.

type PatternDetectResult

type PatternDetectResult struct {
	V        int       `json:"v"`        // schema version, always 1
	Patterns []Pattern `json:"patterns"` // slugs with ≥1 matching file
	Warnings []string  `json:"warnings"` // non-fatal warnings (unreadable files, etc.)
}

PatternDetectResult is the stable JSON output schema for `nightgauge docs detect-patterns`. Schema version 1 — do not rename or remove fields after first merge.

func DetectPatterns

func DetectPatterns(opts PatternDetectOptions) (*PatternDetectResult, error)

DetectPatterns expands the glob in opts.FilesGlob, reads each matched file, and returns which pattern slugs have at least one keyword match. Unreadable files are added to Warnings and skipped — the function still exits 0. An invalid glob expression (one that filepath.Glob rejects) is the only condition that returns a non-nil error.

type RemoveEntry

type RemoveEntry struct {
	URL string `json:"url"`
}

RemoveEntry describes a URL that is in the snapshot but absent from the current URLs file.

type SnapshotDiffOptions

type SnapshotDiffOptions struct {
	// SnapshotFile is the path to an existing snapshot JSON produced by
	// a prior run. Required; the file must exist and contain valid JSON.
	SnapshotFile string
	// URLsFile is a text file with one URL per line (blank lines ignored).
	// Required; the file must exist.
	URLsFile string
	// HTTPClient overrides the default HTTP client. When nil, a client with
	// a 15-second timeout is used (matching the bash script behavior).
	HTTPClient *http.Client
}

SnapshotDiffOptions controls a single snapshot-diff run.

type SnapshotDiffResult

type SnapshotDiffResult struct {
	V        int           `json:"v"`       // schema version, always 1
	New      []Entry       `json:"new"`     // pages in URLs file but not in snapshot
	Changed  []ChangeEntry `json:"changed"` // pages with a different hash than snapshot
	Removed  []RemoveEntry `json:"removed"` // pages in snapshot but not in URLs file
	Warnings []string      `json:"warnings,omitempty"`
}

SnapshotDiffResult is the stable JSON output schema for `nightgauge docs snapshot-diff`. Schema version 1 — do not rename or remove fields after first merge.

func SnapshotDiff

func SnapshotDiff(opts SnapshotDiffOptions) (*SnapshotDiffResult, error)

SnapshotDiff computes the diff between the known snapshot and the current set of URLs, fetching each URL to compute its sha256 hash. It returns a non-nil error only for hard input failures (missing file, malformed JSON). Individual fetch failures are appended to Warnings and skipped.

type StaleFinding

type StaleFinding struct {
	File           string `json:"file"`            // path relative to Root
	Line           int    `json:"line"`            // 1-based line number of the "Updated:" metadata
	DocumentedDate string `json:"documented_date"` // date string extracted from the file (YYYY-MM-DD)
	GitDate        string `json:"git_date"`        // date of most recent git commit touching the file (YYYY-MM-DD)
	DaysStale      int    `json:"days_stale"`      // (git_date - documented_date) in whole days
}

StaleFinding records a single file whose "Updated:" metadata lags behind the most recent git commit that touched that file.

type VersionConsistencyOptions

type VersionConsistencyOptions struct {
	// Root is the directory tree to scan. When empty, the caller's CWD is used.
	Root string
}

VersionConsistencyOptions controls a single version-consistency run.

type VersionConsistencyResult

type VersionConsistencyResult struct {
	V               int               `json:"v"`                // schema version, always 1
	Root            string            `json:"root"`             // absolute path scanned
	ProjectType     string            `json:"project_type"`     // nodejs|python|go|rust|dotnet|skills|unknown
	SourceFile      string            `json:"source_file"`      // file the authoritative version was read from
	SourceVersion   string            `json:"source_version"`   // version string extracted from source file
	Mismatches      []VersionMismatch `json:"mismatches"`       // one entry per stale reference
	MismatchesCount int               `json:"mismatches_count"` // len(Mismatches)
	Warnings        []string          `json:"warnings"`         // non-fatal scan warnings
}

VersionConsistencyResult is the stable JSON output schema for `nightgauge docs version-consistency`. Schema version 1 — do not rename or remove fields after first merge.

func VersionConsistency

func VersionConsistency(_ context.Context, opts VersionConsistencyOptions) (*VersionConsistencyResult, error)

VersionConsistency detects version mismatches across a project tree.

type VersionMismatch

type VersionMismatch struct {
	File            string `json:"file"`             // path relative to Root
	Line            int    `json:"line"`             // 1-based line number
	Context         string `json:"context"`          // raw line text (trimmed)
	FoundVersion    string `json:"found_version"`    // version string found in the file
	ExpectedVersion string `json:"expected_version"` // authoritative version
}

VersionMismatch records a single outdated version reference in a scanned markdown file.