catalogue

package
v1.0.0 Latest Latest
Warning

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

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

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

View Source
const (
	DeclarationsFile = "declarations.json"
	MembersFile      = "members.json"
	ReceiptFile      = "review.json"
)

The three files of a package directory.

View Source
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.

View Source
const DefaultReview = "api-naming.md"

DefaultReview is the review note a new receipt names unless told otherwise. It is resolved relative to docs/contributing.

View Source
const Dir = "internal/apiinventory/catalogues"

Dir is the catalogue directory, relative to the module root.

Variables

View Source
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

func Approve(c Config, named []string, review string) ([]string, error)

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

func CheckCatalogue(root, pkg string, surface Surface) error

CheckCatalogue runs CheckDeclarations and CheckMembers.

func CheckDeclarations

func CheckDeclarations(root, pkg string, surface Surface) error

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

func CheckLayout(root string) error

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

func CheckMembers(root, pkg string, surface Surface) error

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

func CheckReceipt(root, pkg string, surface Surface) error

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

func DefaultPage(pkg string) string

DefaultPage is the usage page of a package: the README.md in the package directory.

func Directories

func Directories(root string) ([]string, error)

Directories returns the packages that have a catalogue directory: every directory below Dir that holds at least one of the three files.

func Discover

func Discover(root string) ([]string, error)

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

func ExportedNames(root, pkg string) ([]string, error)

ExportedNames returns the names a package exports, with methods as Type.Method.

func Generate

func Generate(c Config, packages []string) (map[string]Surface, error)

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 Markdown

func Markdown(rows []Row, total Row) string

Markdown renders the aggregate as a table.

func Marshal

func Marshal(value any) ([]byte, error)

Marshal serializes a catalogue or receipt. The bytes are the file content and the input of the receipt hashes.

func MembersInFile

func MembersInFile(pkg string, file *ast.File) (map[string][]string, error)

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

func PackageDir(root, pkg string) string

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

func Regenerate(c Config, named []string) ([]string, error)

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).

func Summarize

func Summarize(root string) ([]Row, Row, error)

Summarize reads the committed per-package files and returns one row per catalogue directory in package order, and the totals. It is a computed view for reviewers: nothing aggregated is committed. It does not read the source and does not judge staleness; the tests do.

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

type Config struct {
	Root      string
	Proposals map[string]string
}

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

type Reader func(rev, path string) ([]byte, error)

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

func LoadReceipt(root, pkg string) (Receipt, error)

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

type ResolveOptions struct {
	Base, Ours, Theirs string
	Read               Reader
}

ResolveOptions names the three revisions of a merge.

type Row

type Row struct {
	Package      string
	Declarations int
	Members      int
	Types        int
	Review       string
	Page         string
}

Row is the committed state of one package.

type State

type State struct {
	Declarations []byte
	Members      []byte
	Receipt      []byte
}

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.

func ReadState

func ReadState(read Reader, rev, pkg string) (State, error)

ReadState loads one package's three files at a revision.

type Surface

type Surface struct {
	Declarations Declarations
	Members      Members
}

Surface is the source-derived catalogue of one package.

Jump to

Keyboard shortcuts

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