Documentation
¶
Overview ¶
Package concurrencydoc holds the CI doc-scan gate that enforces the CLAUDE.md mandate: "Every exported type carries a godoc clause stating whether it is safe for concurrent use; ambiguity is a defect."
The package is test-only support: it exposes a single scanner that enumerates exported types across the public source trees and classifies each as documented-for-concurrency or not. The gate test in this package (concurrencydoc_test.go) asserts that the count of undocumented exported types never rises above a baseline that ratchets down as types are documented over time.
Concurrency ¶
The scanner is stateless apart from the *ScanResult it returns; a ScanResult is constructed once by Scan and then read-only, so it is safe for concurrent reads once Scan has returned. Scan itself is meant to be driven from a single test goroutine.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type ScanResult ¶
type ScanResult struct {
// Types holds every exported type discovered, sorted by Qualified().
Types []TypeInfo
// Packages holds the repository-relative import path (slash-separated,
// e.g. "graph/lpg", "metrics", or "." for the module root) of every
// scanned package — that is, every non-excluded directory that contains
// at least one non-test .go file. It records the scan's UNIVERSE
// independently of whether a package declared exported types, so the gate
// can prove its universe matches the public-package set. Sorted.
Packages []string
// SkippedDirs records directories that failed to parse and were
// skipped (with the reason), so the scan never panics on an
// unparseable tree and the test can surface the skip.
SkippedDirs []string
}
ScanResult is the immutable outcome of a Scan over the public trees.
Concurrency ¶
A ScanResult is populated once by Scan and then treated as read-only, so it is safe for concurrent reads without external locking.
func Scan ¶
func Scan(repoRoot string) (*ScanResult, error)
Scan enumerates every exported type in every non-generated, non-test public package rooted at repoRoot, classifying each as documented-for-concurrency or not. The universe is the whole repository minus the excludedTopLevel directories (internal/examples/cmd/bench/…) and the skipDirComponents (gen/testdata), so any public package — present or future — is covered, not just the historical six trees.
The scan never panics: a directory whose Go files fail to parse is skipped and recorded in ScanResult.SkippedDirs rather than aborting the whole scan.
func (*ScanResult) Documented ¶
func (r *ScanResult) Documented() []TypeInfo
Documented returns the subset of Types whose concurrency contract is stated.
func (*ScanResult) Lookup ¶
func (r *ScanResult) Lookup(qualified string) (TypeInfo, bool)
Lookup returns the TypeInfo for the given qualified name ("pkg.Name") and whether it was found.
func (*ScanResult) Undocumented ¶
func (r *ScanResult) Undocumented() []TypeInfo
Undocumented returns the subset of Types whose concurrency contract is NOT stated, in sorted order.
type TypeInfo ¶
type TypeInfo struct {
// Pkg is the import-path-style package identifier relative to the
// repository root (e.g. "cypher/expr").
Pkg string
// Name is the exported type name (e.g. "NodeValue").
Name string
// Documented reports whether the type's own doc comment or its
// package doc comment carries a concurrency marker.
Documented bool
}
TypeInfo records one exported type discovered by the scan.
Source Files