Retracted: v0.1.0 was first tagged on a commit main no longer holds, its history since
rewritten; the module proxy keeps that first one. Take v0.1.1.
Documentation
¶
Overview ¶
Package documentalist holds the deterministic part of the documentalist role (roles/documentalist): which docs became suspect because a source changed, which are only pending because the cascade is cut, the hygiene checks (budgets, duplicates, links, identifiers gone from the code), and the judge of the patches the agent proposes for suspect docs.
Index ¶
- func Coverage(repo string, globs []string) (tracked, none, untracked []string, err error)
- func Derive(repo string, docs map[string]string, commands map[string]string) ([]verdict.Finding, map[string]string)
- func Post(runDir, repo string) int
- func Pre(runDir, repo string) int
- func Section(content, anchor string) (string, bool)
- type Budgets
- type Doc
- type Duplicates
- type Freshness
- type Problem
- func ExternalLinks(repo string, docs []string) (problems []Problem, ok bool, err error)
- func Hygiene(t Tree, b Budgets, d Duplicates) []Problem
- func IdentifiersGone(repo string, docs map[string]string) ([]Problem, error)
- func IdentifiersRemoved(repo, rng string, docs map[string]string) ([]Problem, error)
- type Settings
- type Tree
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Coverage ¶
Coverage sorts the docs under the docs globs: those declaring their sources, which alone can be found suspect; those declaring none (`sources: []`), which describe no code; and those declaring nothing.
func Derive ¶
func Derive(repo string, docs map[string]string, commands map[string]string) ([]verdict.Finding, map[string]string)
Derive regenerates the derived blocks of the docs from the commands the project declares by name (`settings.derive`). Commands live in the config, which only people change, never in a doc: a doc names one. Markers shown in code — a fenced block or a code span — are examples, not blocks. It returns what it found, and the new content of each doc whose blocks were stale.
func Post ¶
Post judges the agent's patches, then turns the findings into a verdict. Suspect and pending docs are reported for a person, unless a patch handled them; a source that could not be judged, or a check that could not run, blocks.
Types ¶
type Budgets ¶
type Budgets struct {
DocLines int `json:"doc-lines"`
SectionWords int `json:"section-words"`
CardWords struct {
Min int `json:"min"`
Max int `json:"max"`
} `json:"card-words"`
FolderLines int `json:"folder-lines"`
RootAgentFileLines int `json:"root-agent-file-lines"`
}
Budgets are the size limits of the docs (roles/documentalist/role.yaml).
type Doc ¶
type Doc struct {
Path string
Sources []string
Checked map[string]string // repository name ("" = this one) -> commit
// JudgedInParts is the commit the doc was last judged in parts at: it is
// not put before an agent again until a source changes after it.
JudgedInParts string
// Judged is the commit an agent judged the doc whole at without vouching
// for every sentence: held the same way.
Judged string
}
Doc is a documentation file that declares its sources.
type Duplicates ¶
Duplicates says which repeated passages are worth reporting.
type Freshness ¶
type Freshness struct {
StaleAfterDays int `json:"stale-after-days"`
}
Freshness says how long a doc stays trusted without being read again.
type Problem ¶
type Problem struct {
Rule, Where, Message, Key string
Size int
Other string // a duplicate: the other doc holding the passage
}
Problem is what a hygiene check found. Key names the problem without its size, so the same problem is recognised before and after a patch; Size says how bad it is, so a patch that makes it worse is recognised too.
func ExternalLinks ¶
ExternalLinks checks the docs' links to other sites with lychee (https://lychee.cli.rs), which reads its own lychee.toml and .lycheeignore in the repository. A link answered by an HTTP error is broken; one that could not be reached (no network, a timeout) is only counted, so a run offline is not a flood of findings. ok is false when lychee is not installed: the links stay unchecked, and the caller says why.
func Hygiene ¶
func Hygiene(t Tree, b Budgets, d Duplicates) []Problem
Hygiene runs the checks that need no git history: budgets, duplicates, links, and citations of superseded decisions. A budget that is not set is said, never skipped silently.
func IdentifiersGone ¶
IdentifiersGone reports the identifiers a doc names that were in the code when the doc was last edited, and are gone from it now (DOCER). A name that was never in the code is not reported: it may be a product term.
func IdentifiersRemoved ¶
IdentifiersRemoved reports, for the commits of a range, the identifiers a doc names that these commits removed from the code and that are gone now. It searches the code for those names only: IdentifiersGone searches it at each doc's last edit, minutes on a large repository, too long for a push; what went earlier is left for gardening.
type Settings ¶
type Settings struct {
Docs []string `json:"docs"`
Propagation []struct {
From string `json:"from"`
To string `json:"to"`
When string `json:"when"`
} `json:"propagation"`
Budgets Budgets `json:"budgets"`
Duplicates Duplicates `json:"duplicates"`
Freshness Freshness `json:"freshness"`
// MaxOpenMergeRequests stops gardening while this many of the role's
// merge requests wait for review (ADR-0006).
MaxOpenMergeRequests int `json:"max-open-merge-requests"`
Truth struct {
Doc []string `json:"doc"` // docs the code follows: never rewritten to match it
} `json:"truth"`
AIMaxCalls int `json:"ai-max-calls"`
Derive map[string]string `json:"derive"` // name -> command giving a derived block
// Documented: the code the project wants described; a file of it no
// doc names in its sources is reported.
Documented []string `json:"documented"`
// JudgeInParts judges a doc whose sources do not fit a task in parts,
// instead of leaving it to a person (ADR-0009); PartsMax caps the parts
// of one doc, PartsMaxPerRun those asked in one run.
JudgeInParts bool `json:"judge-in-parts"`
PartsMax int `json:"parts-max"`
PartsMaxPerRun int `json:"parts-max-per-run"`
// For measuring whole against parts on the same doc (tests/evaluation):
// PartsAlways judges in parts even a doc that fits whole, PartChars
// caps the sources' share of a part, so that small sources still split.
PartsAlways bool `json:"parts-always"`
PartChars int `json:"part-chars"`
}
Settings are the role's settings, as merged by the engine.
Source Files