requestinventory package - github.com/jmrplens/gitlab-mcp-server/v3/cmd/internal/requestinventory

Documentation ¶

Overview ¶

Package requestinventory holds the committed record of what this server sends GitLab, and the one definition of which catalog actions it covers.

The artifact itself is written by cmd/gen_request_inventory out of the shards internal/testutil records, and read by cmd/audit_1to1's paths scope, which audits it. Both need the same answer to "which package was seen issuing nothing", and two answers to that question would be worse than none: the generator's summary and the auditor's gate would disagree about the number while both looked right.

What a row is, and what it is not ¶

One row per package, method and templated endpoint, carrying the union of the parameter names that package was seen to send it. A row is not keyed by action, because nothing on the wire names one: the httptest server answers on its own goroutine while the test goroutine that called the handler is out of reach, and the catalog's route is a closure over its handler, so neither the stack nor the catalog can hand back an action to attribute a request to.

The consequence runs through everything here. Coverage is per owning package, so "covered" means the package that owns this action issued some request, never that this action's request was seen. It is the strongest statement the recording can support, and saying more would be a guess dressed as a measurement.

Index ¶

Constants
func PackageDir(root, owner string) string
func Packages(owners []Owner) []string
func Render(rows []Row) []byte
type Action
- func Actions() ([]Action, error)
type Coverage
- func Classify(root string, rows []Row, actions []Action) Coverage
type Inventory
- func Read(root string) (Inventory, error)
type Owner
type Row

Constants ¶

View Source

const (
	// Path is where the committed artifact lives, relative to the repository
	// root.
	Path = "docs/development/request-inventory.json"

	// Note is the header the artifact carries, since JSON has no comments and
	// the file is long enough that a reader will meet a row before any prose
	// about it.
	Note = "Generated by `make gen-request-inventory`; do not edit. " +
		"One row per package, method and templated endpoint: what the unit suite was seen to send " +
		"through internal/testutil.NewTestClient, which is not the same as everything this server can send. " +
		"`query`, `body` and `variables` are the union of the names that package sent that endpoint, never one call's set. " +
		"A segment the shape rule could not recognize as an identifier is still a fixture value, " +
		"so one endpoint reached with two branch names is two rows: the rule is in internal/testutil/request_shape.go " +
		"and what a row is is in cmd/internal/requestinventory. " +
		"Recorded on Linux; a run on another platform may legitimately skip a test and record less."

	// KindREST and KindGraphQL are the two shapes a row comes in.
	KindREST    = "rest"
	KindGraphQL = "graphql"
)

View Source

const RootOwner = "tools"

RootOwner is what the catalog calls the orchestration package itself, which is ToolsDir rather than a directory under it: a spec group that declares no owner is given this one, and TestCollectedActionSpecs_DeclareCatalogOwnership admits it beside the domain names. Resolving it to the root package is what keeps an action owned by it from being classified as owned by nothing.

View Source

const ToolsDir = "internal/tools"

ToolsDir is where a domain package lives, and the prefix a recorded package name carries when the catalog knows it as an owner.

Variables ¶

This section is empty.

Functions ¶

func PackageDir ¶

func PackageDir(root, owner string) string

PackageDir is where the package an owner names lives, which is ToolsDir itself for RootOwner and a directory under it for every domain.

func Packages ¶

func Packages(owners []Owner) []string

Packages names the owners in a list, for a report that wants the packages without the actions under them.

func Render ¶

func Render(rows []Row) []byte

Render marshals rows as the committed artifact, with the trailing newline a text file in this repository ends with.

The marshal goes through cmdutil.Must because it cannot fail on a value built out of strings, and a caller handed that error could only print it and stop, which is what the panic already does.

Types ¶

type Action ¶

type Action struct {
	ID    string
	Owner string
}

Action is one catalog action as this dimension sees it: an identity and the package that owns it, which is the only handle the recording can be joined on.

func Actions ¶

func Actions() ([]Action, error)

Actions returns every action in the catalog at the widest tier, so the counts below are of the whole surface rather than one licence's.

type Coverage ¶

type Coverage struct {
	Total    int
	Covered  int
	Silent   int
	Unmapped int
	// Silent and Unmapped owners are sorted by package, and each one's actions
	// are sorted too, so a report of them is stable between runs.
	SilentOwners   []Owner
	UnmappedOwners []Owner
}

Coverage counts what the recording could and could not see of the catalog.

The three counts are disjoint and none of them is per action, which is the point of keeping them apart. Covered means the package owning the action issued some request, not that this action's request was seen; silent means the package issued none; unmapped means the action's owner names no package at all, neither the orchestration package nor a domain under it, so the recording could not have seen it either way and the fault is in the catalog's ownership metadata rather than in any test.

Silent is weaker than "never exercised" for a second reason beyond the coarse grain, and internal/tools/adminspecs is the whole of it today: a package may declare specs whose handlers live in other packages, and the request is then recorded under the package that made it while the count of silent actions blames the one that declared them. Reading the silent list as a work list means reading it package by package, not action by action.

func Classify ¶

func Classify(root string, rows []Row, actions []Action) Coverage

Classify sorts every action by whether the package that owns it was recorded issuing anything. The root is needed to tell a package that recorded nothing from a name that is no package at all.

type Inventory ¶

type Inventory struct {
	Note     string `json:"note"`
	Requests []Row  `json:"requests"`
}

Inventory is the committed artifact.

func Read ¶

func Read(root string) (Inventory, error)

Read loads the committed inventory from a repository root.

An artifact with no rows in it is an error rather than an empty inventory: every caller here answers a question of the form "which of these did the suite never issue", and an empty file answers all of them with "none of them", which is the loudest possible wrong answer.

type Owner ¶

type Owner struct {
	Package string   `json:"package"`
	Actions []string `json:"actions"`
}

Owner is one package the catalog names as owning actions, with the actions it owns, listed so a report can name the work rather than score it.

type Row ¶

type Row struct {
	Package string `json:"package"`
	Kind    string `json:"kind"`
	Method  string `json:"method"`
	Path    string `json:"path"`
	// Query, Body and Variables are the union of every name this package was
	// seen sending this endpoint, never one call's set. Two calls that differ
	// only in which optional filter they pass are the same endpoint, so the
	// union answers which names were sent it and deliberately not which of
	// them were sent together: a combination is a property of the tests, and
	// reading one off this file would be reading a fixture as a contract.
	Query     []string `json:"query,omitempty"`
	Body      []string `json:"body,omitempty"`
	Operation string   `json:"operation,omitempty"`
	Variables []string `json:"variables,omitempty"`
}

Row is one endpoint one package was seen to call.

Source Files ¶

View all Source files

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