workspace

Documentation

Overview

Package workspace resolves the cross-repo scope for a command invocation. It is the source of truth for "which repos should this verb iterate?":

• When a *.code-workspace file is reachable (via flag, env, or walking up from CWD), the scope is the workspace and the folders enumerated from its folders[] array.
• When no workspace file is reachable but CWD is inside a project whose gh-optivem.yaml declares a non-empty repos:, the scope is the project — the listed local repos are iterated.
• When neither of the above resolves but CWD is inside a git repo, the scope shrinks to that single repo.
• When none of the above is true, the call errors.

The project / single-repo fallbacks let the cross-repo verbs (commit, sync, …) Just Do The Right Thing whether the operator is inside a multi-repo workspace, a multitier project, or a standalone clone. The mode is surfaced to callers via Scope.Mode so the banner can announce which scope resolved.

Index

• Constants
• type Mode
• type Scope
  • func Resolve(flagValue string) (Scope, error)

Constants

const EnvVar = "GH_OPTIVEM_WORKSPACE"

EnvVar names the environment variable that pins the workspace root when the operator does not pass --workspace.

Types

type Mode

type Mode int

Mode discriminates the three possible resolved scopes.

const (
	// ModeWorkspace means Folders enumerates every repo declared in the
	// resolved *.code-workspace file.
	ModeWorkspace Mode = iota
	// ModeProject means Folders enumerates every repo declared in the
	// resolved gh-optivem.yaml's repos: field — a multitier project's
	// constituent local repos. Only reached by walk-up; the flag and
	// env-var cascade entries still target workspace files.
	ModeProject
	// ModeSingleRepo means Folders contains exactly one entry — the git
	// repo the operator is inside. Neither a workspace file nor a
	// project config with non-empty repos: was reachable.
	ModeSingleRepo
)

type Scope

type Scope struct {
	Mode Mode
	// Root is the workspace root directory (ModeWorkspace) or the git
	// repo's root directory (ModeSingleRepo).
	Root string
	// Folders is every targeted repo. In ModeSingleRepo it has exactly
	// one entry equal to Root.
	Folders []string
	// SourceFile is the absolute path to the file the scope was derived
	// from — the resolved *.code-workspace in ModeWorkspace, the
	// resolved gh-optivem.yaml in ModeProject, or "" in ModeSingleRepo.
	SourceFile string
}

Scope is the resolved cross-repo scope for one command invocation.

func Resolve

func Resolve(flagValue string) (Scope, error)

Resolve returns the resolved scope for the current invocation. Cascade:

1. flagValue (if non-empty) — treated as a directory containing a *.code-workspace file → ModeWorkspace.
2. $GH_OPTIVEM_WORKSPACE — same semantics as flagValue.
3. Walk up from CWD for a *.code-workspace file → ModeWorkspace, BUT only if the CWD's git repo is one of the workspace's folders[] entries. If the workspace file doesn't claim CWD's repo as a member, the walk-up is treated as a non-match and the cascade falls through to row 4. This prevents a git worktree (or any standalone repo) placed inside a workspace tree from being silently overridden by the surrounding workspace's folder list.
4. Walk up from CWD for a gh-optivem.yaml with non-empty repos: → ModeProject, BUT only if the config "claims" CWD's repo: either it sits at CWD's git repo root (monolith), or its repos: include CWD's git repo (multitier subrepo). A stray outer gh-optivem.yaml reached by walk-up but not claiming CWD's repo is silently skipped — same protection as row 3 for *.code-workspace files. Parse errors on such an outer file are also suppressed (it's not our config; surfacing its problems would be noise — e.g. a stale academy-level gh-optivem.yaml above an ATDD rehearsal worktree).
5. Walk up from CWD for a .git/ entry → ModeSingleRepo with Folders = []string{<repo root>}.
6. Nothing → error.

Within ModeWorkspace, repos declared in folders[] but missing on disk or without a .git/ subdir are silently filtered out (matches the commit.sh:183 behavior). Malformed JSON, missing/empty folders[], and flag/env paths that do not exist are errors. The flag/env entries do NOT apply the membership check from row 3 — those are explicit operator intent and are honored even when CWD is outside the workspace tree.

Within ModeProject, the same filter applies to repos: entries — non-existent paths and non-git folders are skipped. If gh-optivem.yaml has no repos: field, an empty repos:, or every entry filters out, the cascade falls through to the .git walk-up rather than erroring (the project simply has no cross-repo scope to express). A malformed or schema-invalid gh-optivem.yaml is surfaced when it belongs to CWD (sits at CWD's repo root, or there is no git repo above CWD); when it's an outer file that doesn't claim CWD's repo, the error is suppressed and the cascade falls through.