doccounts

Documentation

Overview

Package doccounts is the one census of the compliance map's status markers and the one statement of which documentation lines derive from it: the guard in cmd/pilot-diff checks those lines against it, cmd/doc-counts rewrites them from it, and neither parses the markers itself.

Index

• Constants
• func FindLine(content, marker string) (int, bool)
• func IsRuleRow(line string) bool
• func ReadSelfAssessedRows(root string) (int, error)
• func Rewrite(content string, spec Line, counts RuleCounts) (string, error)
• func RewriteBaselineLine(content string, spec BaselineLine, counts RefereedCounts) (string, error)
• func RewriteBlock(content string, spec Block, counts RefereedCounts) (string, error)
• type BaselineLine
  • func BaselineLines() []BaselineLine
• type Block
  • func Blocks() []Block
• type ErrataCounts
• type Line
  • func Lines() []Line
• type RefereedCounts
  • func ReadRefereedCounts(root string) (RefereedCounts, error)
• type RuleCounts
  • func CountRules(content string) RuleCounts

Constants

const (
	SpecCompliancePath = "docs/project/spec-compliance.md"
	ReadmePath         = "README.md"
	ArchitecturePath   = "docs/internals/architecture.md"
)

Paths of the compliance map and of the files carrying a derived line, relative to the repository root.

Functions

func FindLine

func FindLine(content, marker string) (int, bool)

FindLine returns the index of the first line of content carrying the marker.

func IsRuleRow

func IsRuleRow(line string) bool

IsRuleRow reports whether a line is a compliance-map table row carrying exactly one status marker. Header, separator and prose lines carry none, and a row naming several statuses in its notes is not a census of one status.

func ReadSelfAssessedRows

func ReadSelfAssessedRows(root string) (int, error)

ReadSelfAssessedRows counts rows in sections without an external referee.

func Rewrite

func Rewrite(content string, spec Line, counts RuleCounts) (string, error)

Rewrite returns content with spec's numbers restated from counts and every other byte untouched. Prose the pattern does not match is an error, not a rewrite.

func RewriteBaselineLine

func RewriteBaselineLine(content string, spec BaselineLine, counts RefereedCounts) (string, error)

RewriteBaselineLine restates one baseline-derived line without other changes.

func RewriteBlock

func RewriteBlock(content string, spec Block, counts RefereedCounts) (string, error)

RewriteBlock replaces a named generated block and preserves surrounding bytes.

Types

type BaselineLine

type BaselineLine struct {
	Path    string
	Marker  string
	Pattern *regexp.Regexp
	Values  func(RefereedCounts) []string
}

BaselineLine is a line whose values come from the committed oracle baselines.

func BaselineLines

func BaselineLines() []BaselineLine

BaselineLines lists the single-copy oracle lines regenerated from baselines.

type Block

type Block struct {
	Path       string
	Name       string
	LinkPrefix string
}

Block describes a generated named block and its consumer-relative links.

func Blocks

func Blocks() []Block

Blocks lists the consumers of the shared refereed-figures block.

type ErrataCounts

type ErrataCounts struct {
	Registry        int
	Corrections     int
	Documented      int
	Files           int
	FilesAgreeing   int
	OursOnly        int
	PilotOnly       int
	Silent          int
	RejectCases     int
	RejectPilotOnly int
}

ErrataCounts is the errata-applied census, read from the same baselines' errata sections so the two figures cannot come from different runs.

type Line

type Line struct {
	Path    string
	Marker  string
	Pattern *regexp.Regexp
	Values  func(RuleCounts) []int
	Labels  []string
	// Sources names, per value, the rows the census read it from.
	Sources []string
}

Line is a documentation line whose numbers are a function of the census. Marker locates it, Pattern captures its numbers in the order Values states them, and Labels names them for a mismatch message.

func Lines

func Lines() []Line

Lines are the documentation lines derived from the census, in the order the regenerator rewrites them.

type RefereedCounts

type RefereedCounts struct {
	RuleCounts             RuleCounts
	Files                  int
	FilesAgreeing          int
	OursOnly               int
	PilotOnly              int
	DeclaredErrors         int
	Silent                 int
	DeclaredAgree          int
	WordingOnly            int
	LocationOnly           int
	SeverityDiffers        int
	Elsewhere              int
	ScopeExact             int
	ScopeTotal             int
	RejectCases            int
	RejectPilotOnly        int
	RejectBoth             int
	RejectDefaultPilotOnly int
	RejectDefaultBoth      int
	RejectStrictOnly       int
	SelfAssessed           int
	PilotTag               string
	PilotArtifact          string
	// Errata is the same census with the declared corrections applied. It is a
	// secondary diagnostic figure; the fields above stay the conformance ones.
	Errata ErrataCounts
}

RefereedCounts is the five-figure census read from the committed baselines.

func ReadRefereedCounts

func ReadRefereedCounts(root string) (RefereedCounts, error)

ReadRefereedCounts reads and derives all five headline figures.

type RuleCounts

type RuleCounts struct {
	Total          int
	Faithful       int
	Approximate    int
	NotImplemented int
	Deliberate     int
	KnownFailure   int
}

RuleCounts is the census of the compliance map's rule rows: a row is one table row carrying exactly one status marker.

func CountRules

func CountRules(content string) RuleCounts

CountRules counts the status markers of every rule row of the compliance map.