Documentation
¶
Overview ¶
Package actionids is the one reader of the canonical action IDs this repository publishes, and the one rule for spotting one inside prose.
Two gates ask the same question of two corpora. `cmd/audit_action_ids` asks it of the source: the RelatedActions list of an ActionSpec, the first argument of toolutil.HintAction, and the dotted IDs a Usage line or an individual tool's Description spells. `cmd/audit_doc_tool_names` asks it of the documentation: the dotted IDs a page teaches a reader to call. What "resolves" means has to be one answer for both, or a spelling the docs gate accepts is one the source gate refuses and a reader cannot tell which is right.
The oracle ¶
Build assembles the catalog this tree builds, at the Ultimate tier, twice: once against a self-managed stub instance and once against GitLab.com. The union is the answer. Orbit registers only for GitLab.com, so a single self-managed build reports its six IDs as dead; taking the union rather than the GitLab.com build alone means an action gated the other way would not read as dead either. The standalone dynamic actions are added the way cmd/server adds them, because gitlab_execute_action takes those IDs too.
A canonical ID and a registered alias are kept apart ¶
IDs.IsID answers for the canonical IDs alone; IDs.Alias answers for a spelling that resolves to one. gitlab_execute_action resolves an alias, so a cross-link naming one works when it is followed; gitlab_find_action publishes canonical IDs, so a model that looks that name up in a listing does not find it. Which of the two a caller demands is the caller's decision, and both gates demand the canonical ID.
Spotting an ID inside prose ¶
IDs.Candidates picks the dotted tokens of a sentence that are offered as action IDs. The shape alone is far too generous, so a token qualifies only when either half is one the catalog uses: a known domain, or a known action name. Requiring the domain alone is blind to the commonest defect, since the usual wrong spelling keeps the action and invents the domain: work_item.get and pipeline_schedule.list are both real actions under domains the catalog does not have. Requiring neither half would admit every example.com and go.mod in the tree. Requiring either half turns those away and keeps the invented domain.
Index ¶
- Variables
- func Catalogs() ([]*actioncatalog.Catalog, error)
- func Normalize(id string) string
- type IDs
- func (o *IDs) Alias(id string) (string, bool)
- func (o *IDs) AliasCount() int
- func (o *IDs) Aliases() map[string]string
- func (o *IDs) Candidates(prose string) []string
- func (o *IDs) Closest(id string) string
- func (o *IDs) Count() int
- func (o *IDs) HasDomain(domain string) bool
- func (o *IDs) HasMember(member string) bool
- func (o *IDs) IsID(id string) bool
- func (o *IDs) Sorted() []string
- func (o *IDs) ToolCount() int
- func (o *IDs) ToolID(tool string) (string, bool)
Constants ¶
This section is empty.
Variables ¶
var DottedToken = regexp.MustCompile(`\b[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*\b`)
DottedToken matches an action-ID-shaped token. The shape alone is far too generous, which is why every match is also held to IDs.Candidates' test that one of its halves is one the catalog uses.
Functions ¶
func Catalogs ¶ added in v3.2.0
func Catalogs() ([]*actioncatalog.Catalog, error)
Catalogs builds the catalog this repository publishes, at Ultimate, for a self-managed instance and for GitLab.com, in that order, standalone dynamic actions included in both.
It is the one place the two builds are made, for every reader that has to answer for the whole surface: Build folds their IDs, and the action request derivation reads every action of both, since Orbit's group is contributed only to the GitLab.com build and the standalone actions only by the step that adds them.
Types ¶
type IDs ¶
type IDs struct {
// contains filtered or unexported fields
}
IDs is what an action ID is judged against: the canonical IDs the catalog builds, the aliases that resolve to one of them, and the two halves of every canonical ID.
The halves are kept because the prose rule needs them. A dotted token in a sentence is only a candidate action ID when one of its halves names something the catalog uses; without that test the rule reports github.com, gitlab.com, go.mod and every JSON path an example binding spells.
func Build ¶
Build builds the catalog twice, self-managed and GitLab.com, and returns the union.
Both are needed, and the union rather than the wider one alone. Orbit's group is contributed only when the client is GitLab.com, so a self-managed build alone reports its six IDs as phantoms; and the union is what keeps the answer right if an action is ever gated the other way, which the catalog has a flag for and no build here could otherwise see.
The standalone dynamic actions are added the way cmd/server adds them: gitlab_execute_action takes those IDs, so a cross-link naming one resolves and must not be called dead.
func New ¶
New builds an IDs over an explicit set of canonical IDs and aliases, which is what a caller with a small, stable catalog of its own uses in place of the whole tree's: a test asserting how a rule judges one ID does not want the answer to move when a domain is added.
It applies the same two rules Build ends with, so a set made here and one read from the catalog cannot disagree: an alias that is also a canonical ID stays an ID, and the halves of every ID are what the prose rule filters on.
func NewWithTools ¶
NewWithTools is New with the individual tool names too, for a caller whose rule asks what a tool name should have been written as.
A tool naming an ID this set does not hold is dropped rather than recorded, because the whole value of the map is that what comes out of it is a canonical ID: a caller that had to re-check the answer would be keeping the invariant itself, which is what putting it here avoids.
func (*IDs) AliasCount ¶
AliasCount is how many registered aliases resolve to one of those IDs.
func (*IDs) Aliases ¶
Aliases is every registered alias mapped to the canonical ID it stands for. The returned map is the one this holds: a caller reads it and does not write to it.
func (*IDs) Candidates ¶
Candidates extracts the dotted tokens of a sentence that are offered as action IDs, deduplicated in the order they appear.
A token qualifies when either half is one the catalog uses: a known domain, or a known action name. The reasoning is in the package comment, and it is the whole difference between a rule that sees work_item.get and one that reports go.mod.
func (*IDs) Closest ¶
Closest names the nearest canonical ID, or nothing when the nearest is too far to be a lead. The bound is a third of the length: past that the nearest ID is an accident of the alphabet and naming it would send a reader off.
func (*IDs) Count ¶
Count is how many canonical IDs the catalog holds, which is what a report says it judged against.
func (*IDs) Sorted ¶
Sorted is the canonical ID set in order. The returned slice is the one this holds: a caller reads it and does not sort it in place.
Source Files