docscheck

package
v0.47.2 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package docscheck is the documentation gate of card 110: the structural rules every release must pass, checked offline against the tree.

The documentation is one tree for humans and one for agents. Humans enter at README.md, which names five personas; each persona root names its topics; each topic root names its actions with a TL;DR and a Details link; the leaves hold the details. Agents enter at CLAUDE.md, whose @imports load the rule files under docs/agent/repository/. A harness Brigade ships a package for is one entry in docs/harnesses.json and six pages the gate requires. Run reports every rule the tree breaks; nothing here reaches the network, so a site going down is never a red build (cavalry ADR 0006).

Index

Constants

View Source
const (
	ReadmeFile       = "README.md"
	AgentsFile       = "AGENTS.md"
	ClaudeFile       = "CLAUDE.md"
	ChangelogFile    = "CHANGELOG.md"
	MakefileFile     = "Makefile"
	VersionFile      = "plugin/bin/VERSION"
	PluginManifest   = "plugin/.claude-plugin/plugin.json"
	RegistryFile     = "docs/harnesses.json"
	DocsDir          = "docs"
	ResearchDir      = "docs/research"
	ExperimentsDir   = "docs/experiments"
	ExperimentsIndex = "docs/experiments/README.md"
	RulesDir         = "docs/agent/repository"
	AgentTeamDir     = "docs/agent/in-a-team"
	OptionsPage      = "docs/team-member/configure/options.md"
	MakeTargetsPage  = "docs/developer/reference/make-targets.md"
	CommandsPage     = "docs/developer/reference/commands.md"

	// IfYouWantTo is the heading of the navigation table every persona root
	// and topic root carries.
	IfYouWantTo = "If you want to"
	// DetailsPrefix starts the line of an action section that names its leaf.
	DetailsPrefix = "Details:"
	// MaxOverviewSentences bounds a persona root's topic section.
	MaxOverviewSentences = 2
	// MaxActionLines bounds a topic root's action section: a TL;DR, not the page.
	MaxActionLines = 20
	// PreReleaseVersion is the pin of a tree that has not been released.
	PreReleaseVersion = "0.0.0"
)

The files and directories the gate knows by name, relative to the root.

Variables

View Source
var ErrFindings = errors.New("docscheck: the documentation breaks a rule")

ErrFindings is returned by Check when the tree breaks a rule.

View Source
var Personas = []Persona{
	{Dir: "project-owner", Title: "Project Owner"},
	{Dir: "team-admin", Title: "Team Admin"},
	{Dir: "team-member", Title: "Team Member"},
	{Dir: "developer", Title: "Developer"},
	{Dir: "agent", Title: "AI Agent"},
}

Personas is the order README.md lists them in.

Functions

func Check

func Check(root string) (string, error)

Check runs the gate and formats the result as the lines a person reads: one finding per line, then the summary. It returns ErrFindings when there is anything to fix.

func GenerateCommands added in v0.36.0

func GenerateCommands() ([]byte, int)

GenerateCommands renders the command reference page from internal/cli's command table (card 112): the `brigade help --all` block, then one section per command with the text `brigade help <name>` prints and the flags the command registers. It reads no file, so the gate stays offline and needs no built binary. The count is the number of commands.

func GenerateMakeTargets

func GenerateMakeTargets(root string) ([]byte, int, error)

GenerateMakeTargets renders the make-target reference page from the Makefile's `target: ## help` lines, in Makefile order.

func Run

func Run(root string) ([]Finding, Summary, error)

Run checks the repository at root and returns every finding. An error is a tree the gate cannot read at all (no README.md, an unreadable registry), not a finding.

Types

type Finding

type Finding struct {
	Check   string // readme, persona, topic, links, reach, harness, agent, options, make, commands, coverage, changelog
	Path    string // the file the finding is about, relative to the root
	Message string
}

Finding is one rule the tree breaks.

func (Finding) String

func (f Finding) String() string

type Harness

type Harness struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Vendor  string `json:"vendor"`
	Host    string `json:"host"`
	Package string `json:"package"`
	Skills  string `json:"skills"`
}

Harness is one entry of docs/harnesses.json.

type Persona

type Persona struct {
	Dir   string // the directory under docs/
	Title string // the H1 of its root page
}

Persona is one of the five readers the tree is organised for.

type Registry

type Registry struct {
	Comment   string    `json:"_comment"`
	Harnesses []Harness `json:"harnesses"`
}

Registry is docs/harnesses.json.

func LoadRegistry

func LoadRegistry(root string) (*Registry, error)

LoadRegistry reads docs/harnesses.json under root.

type Summary

type Summary struct {
	Pages     int
	Links     int
	Harnesses int
	Targets   int
	Commands  int
}

Summary is what a passing run counted.

func (Summary) String

func (s Summary) String() string

Jump to

Keyboard shortcuts

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