Documentation
¶
Overview ¶
Package catalogue derives, stores and checks the package-scoped public API catalogues under internal/apiinventory/catalogues.
Every public package owns three files in internal/apiinventory/catalogues/<package>:
- declarations.json and members.json are source-derived output. Only Regenerate writes them.
- review.json is the reviewed receipt. Only Approve writes it, and only for a catalogue that matches the source.
No global index, count or hash file exists. The package list is discovered from the source tree, and the totals are computed on demand by Summarize.
Index ¶
- Constants
- Variables
- func Approve(c Config, named []string, review string) ([]string, error)
- func CheckCatalogue(root, pkg string, surface Surface) error
- func CheckDeclarations(root, pkg string, surface Surface) error
- func CheckLayout(root string) error
- func CheckMembers(root, pkg string, surface Surface) error
- func CheckReceipt(root, pkg string, surface Surface) error
- func DefaultPage(pkg string) string
- func Directories(root string) ([]string, error)
- func Discover(root string) ([]string, error)
- func ExportedNames(root, pkg string) ([]string, error)
- func Generate(c Config, packages []string) (map[string]Surface, error)
- func Markdown(rows []Row, total Row) string
- func Marshal(value any) ([]byte, error)
- func MembersInFile(pkg string, file *ast.File) (map[string][]string, error)
- func PackageDir(root, pkg string) string
- func ProveComposition(pkg string, comp Composition, surface Surface) error
- func Regenerate(c Config, named []string) ([]string, error)
- func Summarize(root string) ([]Row, Row, error)
- type Composition
- type Config
- type Declarations
- type Entry
- type Members
- type Reader
- type Receipt
- type Resolution
- type ResolveOptions
- type Row
- type State
- type Surface
Constants ¶
const ( DeclarationsFile = "declarations.json" MembersFile = "members.json" ReceiptFile = "review.json" )
The three files of a package directory.
const ( DeclarationsSchema = "ceph-api-naming/v2" MembersSchema = "ceph-api-naming-members/v2" ReceiptSchema = "ceph-api-naming-review/v2" )
Schema names and scopes. A schema changes only with the file format.
const DefaultReview = "api-naming.md"
DefaultReview is the review note a new receipt names unless told otherwise. It is resolved relative to docs/contributing.
const Dir = "internal/apiinventory/catalogues"
Dir is the catalogue directory, relative to the module root.
Variables ¶
var Proposals = map[string]string{}
Proposals are review proposals, not compatibility aliases or an API rewrite. Only catalogue rows change when a proposal is edited, and a row with decision "proposal" blocks a finished review. A proposal key is a package-qualified name or a package-qualified receiver type.
Functions ¶
func Approve ¶
Approve writes review.json for the named packages, and only that file. It refuses unless every named package's committed catalogue equals the source (no stale catalogue), no row is a pending proposal, and the review note and reference page exist. Nothing is written when any package is refused. The approval stays a deliberate edit that a reviewer reads as its own diff; the command only removes the hash arithmetic.
func CheckCatalogue ¶
CheckCatalogue runs CheckDeclarations and CheckMembers.
func CheckDeclarations ¶
CheckDeclarations requires the committed declarations.json of a package to equal the source-derived bytes. A missing or stale file, a missing row and a changed signature all fail.
func CheckLayout ¶
CheckLayout requires the catalogue directories to match the discovered packages exactly: no public package without its three files, and no catalogue directory for a package that does not exist.
func CheckMembers ¶
CheckMembers requires the committed members.json of a package to equal the source-derived bytes. A missing type, a missing member and a changed tag all fail.
func CheckReceipt ¶
CheckReceipt requires the package's receipt to bind the current source-derived surface: schema, package, both hashes, both counts, no pending proposal, and an existing review note and reference page. A source change in another package never makes this receipt stale.
func DefaultPage ¶
DefaultPage is the usage page of a package: the README.md in the package directory.
func Directories ¶
Directories returns the packages that have a catalogue directory: every directory below Dir that holds at least one of the three files.
func Discover ¶
Discover returns the public packages below root: every directory outside internal, testdata, vendor and hidden or underscore directories that has a non-test Go source. Names are slash-separated paths relative to root.
func ExportedNames ¶
ExportedNames returns the names a package exports, with methods as Type.Method.
func Generate ¶
Generate derives the catalogue of every named package from source. Pass the whole discovered package list: the name-collision and stale-proposal checks are global, so a subset would report proposals of other packages as stale. It checks only; it writes nothing and approves nothing.
func Marshal ¶
Marshal serializes a catalogue or receipt. The bytes are the file content and the input of the receipt hashes.
func MembersInFile ¶
MembersInFile returns the member rows of the exported types of one file, keyed by the package-qualified type name. A type without members maps to an empty slice so that alternatives with and without members can conflict.
func PackageDir ¶
PackageDir returns the catalogue directory of a package.
func ProveComposition ¶
func ProveComposition(pkg string, comp Composition, surface Surface) error
ProveComposition requires the source-derived surface of the merged tree to consist of exactly the composed rows: no row that neither approved parent contains, and no approved row missing. The first difference found of each kind is reported.
func Regenerate ¶
Regenerate rewrites declarations.json and members.json of the named packages (all when none is named) from source. It never reads or writes review.json, so regenerating cannot approve a changed API. Nothing is written when the derivation is refused (conflicting duplicate, name collision, stale proposal).
Types ¶
type Composition ¶
type Composition struct {
Declarations map[string]Entry
Members map[string]string
Review, Page string
// OursOnly counts composed declaration rows the theirs side does not have
// in that exact form, and TheirsOnly the same for ours.
OursOnly, TheirsOnly int
}
Composition is the row set that two approved parents jointly allow for a merged package, and the receipt fields that follow from them.
func Compose ¶
func Compose(pkg string, base, ours, theirs State) (Composition, error)
Compose computes the three-way merge of the rows of two approved parents. Both ours and theirs must pin their own committed catalogue bytes in their receipt. A row that both sides changed differently, a row the merge result would have to invent, and receipt fields that both sides changed differently are refused. Compose reads no source and writes nothing.
type Config ¶
Config selects the module root and the reviewed rename proposals. Proposals are review inputs, not compatibility aliases or an API rewrite.
type Declarations ¶
type Declarations struct {
Schema string `json:"schema"`
Scope string `json:"scope"`
Package string `json:"package"`
Count int `json:"count"`
Entries []Entry `json:"entries"`
}
Declarations is the declaration catalogue of one package.
type Entry ¶
type Entry struct {
Current string `json:"current"`
Kind string `json:"kind"`
Signature string `json:"signature,omitempty"`
Receiver string `json:"receiver,omitempty"`
Proposed string `json:"proposed"`
Decision string `json:"decision"`
}
Entry is one declared public name.
type Members ¶
type Members struct {
Schema string `json:"schema"`
Scope string `json:"scope"`
Package string `json:"package"`
Count int `json:"count"`
Types map[string][]string `json:"types"`
}
Members is the member catalogue of one package.
type Reader ¶
Reader returns the content of a repository path at a revision. A path that does not exist there is (nil, nil).
type Receipt ¶
type Receipt struct {
Schema string `json:"schema"`
Package string `json:"package"`
DeclarationsSHA256 string `json:"declarations_sha256"`
MembersSHA256 string `json:"members_sha256"`
Declarations int `json:"declarations"`
Members int `json:"members"`
Review string `json:"review"`
Page string `json:"page"`
}
Receipt is the reviewed receipt of one package. It pins the exact catalogue serialization that a human review accepted.
func LoadReceipt ¶
LoadReceipt reads a package's receipt strictly: unknown fields and trailing data are refused.
type Resolution ¶
type Resolution struct {
Package string
Comp Composition
Files []string
}
Resolution is the outcome for one package.
func Resolve ¶
func Resolve(c Config, opts ResolveOptions, named []string) ([]Resolution, error)
Resolve re-derives the catalogue and receipt of every named package (by default every package that both parents changed) after a merge, but only when the merged source surface is a pure composition of the two approved parents (see Compose and ProveComposition). It writes declarations.json, members.json and review.json together and writes nothing at all when any selected package is refused. Unlike Approve it needs no prior catalogue to equal the source: the committed working-tree files may still carry merge conflict markers.
type ResolveOptions ¶
ResolveOptions names the three revisions of a merge.
type State ¶
State is the committed bytes of one package's three catalogue files at one revision. A nil slice means the file does not exist there.
type Surface ¶
type Surface struct {
Declarations Declarations
Members Members
}
Surface is the source-derived catalogue of one package.