Help us shape the future of Go! Take the 2026 Go Developer Survey

workspace

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Oct 11, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package workspace groups repositories so one radar gate checks them together. It owns the local registry, repository identity, repo IDs and the pure rules that turn an invocation into a scope, targets and bases.

Index

Constants

View Source 
const (
	SourceRegistry = "registry"
	SourceWith     = "--with"
	SourceReplay   = "replay"
	SourceTeamFile = "team file"
)

Scope sources: where the set of repositories came from.

View Source 
const ConsumesPath = ".radar/consumes.json"
View Source 
const MaxIDLength = 64

MaxIDLength bounds repo IDs and workspace names, which also name run directories.

View Source 
const RegistryFile = "workspaces.json"

RegistryFile is the registry's name inside the configuration directory.

View Source 
const RegistryVersion = 1

RegistryVersion is the local registry format version.

View Source 
const TeamPath = ".radar/workspace.json"

Variables

This section is empty.

Functions

func AdhocKey 

func AdhocKey(current Location) string

AdhocKey names the run records of a one-off scope started from a repository that is not in a workspace. Every worktree of the repository derives the same key.

func ConfigDir 

func ConfigDir() (string, error)

ConfigDir is RADAR_CONFIG_DIR, or <user config dir>/radar.

func DefaultID 

func DefaultID(folder string) string

DefaultID derives a valid ID from a folder name: invalid characters become '-', and a name that does not start with a letter is prefixed with "repo-".

func ShellPath 

func ShellPath(p string) string

ShellPath quotes a value for a copyable POSIX shell command unless every character is known to be safe there. Suggested commands are presentation only, but must stay one safe command when pasted.

func Update 

func Update(dir string, fn func(*Registry) error) error

Update applies fn to the registry under an exclusive lock and replaces the file atomically, so concurrent writers serialize and readers never see a partial file. fn's changes are discarded when it returns an error.

func Usable 

func Usable(ctx context.Context, repo Repo) string

Usable reports why the registered path of repo cannot be used now, or "".

func ValidID 

func ValidID(id string) error

ValidID checks a repo ID or workspace name: a letter, then letters, digits, '-' or '_'.

func WriteAtomic 

func WriteAtomic(path string, data []byte) error

WriteAtomic replaces path with data through a synced temporary file and a rename in the same directory.

Types

type AddResult 

type AddResult struct {
	Workspace string      `json:"workspace"`
	Created   bool        `json:"created"`
	Added     []Repo      `json:"added"`
	Updated   *PathChange `json:"updated,omitempty"`
	Unchanged bool        `json:"unchanged"`
	Repo      Repo        `json:"repo"`
}

AddResult describes what Add changed.

type Consume 

type Consume struct {
	Contract string   `json:"contract"`
	Fields   []string `json:"fields"`
	Source   string   `json:"source,omitempty"`
}

type ConsumesFile 

type ConsumesFile struct {
	Version  int       `json:"version"`
	Consumes []Consume `json:"consumes"`
}

func ParseConsumes 

func ParseConsumes(data []byte) (*ConsumesFile, error)

ParseConsumes validates consumer expectations; malformed entries stay errors.

type Error 

type Error struct {
	Message string
	Next    string
}

Error is an invocation error that ends with one next action.

func (*Error) Error 

func (e *Error) Error() string
type Link struct {
	ID        string `json:"id"`
	Direction string `json:"direction,omitempty"`
	Producer  string `json:"producer"`
	Consumer  string `json:"consumer"`
}

type Location 

type Location struct {
	Root      string `json:"root"`
	CommonDir string `json:"common_dir"`
	MainPath  string `json:"main_path"`
}

Location identifies the repository a checkout belongs to. Root is the checkout's top level; MainPath is the main worktree, which names the repo.

func Locate 

func Locate(ctx context.Context, path string) (Location, error)

Locate resolves path to its repository. Linked worktrees of one repository share CommonDir, so they locate to the same repository.

func (Location) DefaultRepoID 

func (l Location) DefaultRepoID() string

DefaultRepoID is the ID a repository gets unless one is chosen: its main worktree's folder name, normalized.

type PathChange 

type PathChange struct {
	ID  string `json:"id"`
	Old string `json:"old"`
	New string `json:"new"`
}

PathChange records a registered repository whose location was updated.

type Producer 

type Producer struct{ Repo, Path, Pointer string }

Producer identifies a schema in a workspace repository.

func ParseProducer 

func ParseProducer(value string) (Producer, error)

ParseProducer parses repo:path#pointer without performing Git or file I/O.

type Registry 

type Registry struct {
	Version    int         `json:"version"`
	Workspaces []Workspace `json:"workspaces"`
}

Registry is the machine-local list of workspaces. It holds absolute paths, so it is never committed. Only `radar workspace add/remove` write it.

func Load 

func Load(dir string) (Registry, error)

Load reads the registry in dir. A missing registry is empty.

func (*Registry) Add 

func (r *Registry) Add(current, target Location, id, name string, usable func(Repo) string) (AddResult, error)

Add registers target in the workspace of current, creating the workspace (current plus target) when current is in none. id overrides the default repo ID; an existing ID given explicitly moves that repo to target. name names a new workspace. usable reports why a registered location is gone.

func (Registry) Find 

func (r Registry) Find(commonDir string) (int, int, bool)

Find returns the workspace and repo indexes holding commonDir.

func (Registry) Named 

func (r Registry) Named(name string) int

Named returns the index of the workspace called name.

func (*Registry) Remove 

func (r *Registry) Remove(current Location, id string) (string, Repo, error)

Remove unregisters repo id from the workspace of current. A workspace left without repositories is deleted.

func (Registry) Validate 

func (r Registry) Validate() error

Validate enforces the registry invariants: valid unique names and IDs, absolute paths, and each repository in at most one workspace.

type Repo 

type Repo struct {
	ID        string `json:"id"`
	Path      string `json:"path"`
	CommonDir string `json:"common_dir"`
}

Repo locates one repository. CommonDir, the absolute Git common directory, identifies it: every worktree of a repository shares it.

type Scope 

type Scope struct {
	// Workspace is the registered workspace name; empty for a one-off scope
	// built only from --with.
	Workspace string
	// Key names the run-record directory: the workspace name, or a key
	// derived from the current repository for an unregistered one.
	Key    string
	Source string
	// OneOff is set when --with added repositories for this run only.
	OneOff bool
	// Only lists the --only repo IDs; All is every repo ID before --only.
	Only []string
	All  []string
	// Current is the ID of the repository radar runs in.
	Current  string
	Repos    []ScopeRepo
	Excluded []ScopeRepo
}

Scope is the resolved set of repositories one gate run checks.

func ResolveScope 

func ResolveScope(in ScopeInput) (*Scope, error)

ResolveScope applies the scope rules: the registered workspace of the current repository, else a one-off scope when --with is given, else nil for the unchanged single-repository gate. --with adds repositories and --only restricts the run to the named repo IDs.

func ResolveTeamScope 

func ResolveTeamScope(scope Scope, team *TeamFile, member func(ScopeRepo, string) bool) (Scope, error)

ResolveTeamScope applies team membership before --only, retaining explicit --with additions. member reports whether a registered repository is the one a team entry identifies. A team repo with no usable registered location is kept as Missing, so it is reported (or excluded by --only) instead of stopping the run; a registered repository with another identity is an error.

func (Scope) AssignBases 

func (s Scope) AssignBases(values []string) (map[string]string, error)

AssignBases maps --base values (REF for the current repo, REPO:REF for a workspace repo) to repo IDs. Two bases for one repo are ambiguous.

func (Scope) AssignTargets 

func (s Scope) AssignTargets(targets []Target) (map[string][]string, error)

AssignTargets groups targets by repo ID, keeping argument order, which is the merge order within each repository.

func (Scope) Has 

func (s Scope) Has(id string) bool

Has reports whether id is checked in this run.

func (Scope) Partial 

func (s Scope) Partial() bool

Partial reports whether --only excluded repositories.

func (Scope) Qualify 

func (s Scope) Qualify(targets []Target) []string

Qualify returns targets with every repo spelled out, so a repeated run resolves them the same way from any repository of the workspace.

func (Scope) QualifyBases 

func (s Scope) QualifyBases(values []string) []string

QualifyBases is Qualify for --base values.

type ScopeInput 

type ScopeInput struct {
	Registry Registry
	Current  Location
	// With are the --with locations, in argument order, with the raw
	// arguments for messages.
	With     []Location
	WithArgs []string
	Only     []string
	// Usable reports why a registered location cannot be used now, or "".
	Usable func(Repo) string
}

ScopeInput is everything scope resolution reads; it performs no I/O.

type ScopeRepo 

type ScopeRepo struct {
	ID        string `json:"id"`
	Path      string `json:"path"`
	CommonDir string `json:"common_dir"`
	Origin    string `json:"origin"`
	Missing   string `json:"missing,omitempty"`
	TeamBase  string `json:"team_base,omitempty"`
}

ScopeRepo is one repository in a gate run. Missing explains why its registered location cannot be used; such a repo is reported, not checked.

type Target 

type Target struct {
	Repo      string `json:"repo"`
	Ref       string `json:"ref"`
	Qualified bool   `json:"-"`
}

Target is one positional gate argument: REF names a ref of the current repository and REPO:REF a ref of that workspace repository. Git ref names cannot contain ':', so the first ':' always separates the repo ID.

func ParseTarget 

func ParseTarget(arg string) Target

ParseTarget splits arg at its first ':'.

func ParseTargets 

func ParseTargets(args []string, valid func(Target) bool) []Target

ParseTargets applies the single-repository rule to every positional argument: an argument that names a valid target is kept whole (commas are legal in ref names); otherwise it is a comma-separated list of targets. valid reports whether a target names a known repository and an existing ref.

func (Target) String 

func (t Target) String() string

type TeamFile 

type TeamFile struct {
	Version int                    `json:"version"`
	Repos   []TeamRepo             `json:"repos"`
	Links   []Link                 `json:"links"`
	Retired []contracts.Retirement `json:"retired,omitempty"`
}

TeamFile is the committed declaration of repository membership and links.

func ParseTeam 

func ParseTeam(data []byte) (*TeamFile, error)

ParseTeam validates a team declaration without reading any repository files.

type TeamRepo 

type TeamRepo struct {
	ID       string `json:"id"`
	Identity string `json:"identity"`
	Base     string `json:"base,omitempty"`
}

type Workspace 

type Workspace struct {
	Name  string `json:"name"`
	Home  string `json:"home,omitempty"`
	Repos []Repo `json:"repos"`
}

Workspace names a group of repositories checked together.

func (Workspace) IDs 

func (w Workspace) IDs() []string

IDs returns the workspace's repo IDs in sorted order.

func (Workspace) Repo 

func (w Workspace) Repo(id string) (Repo, bool)

Repo returns the repo with id.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.