util

func NewCmdContext ¶

func NewCmdContext() (ctx CmdContext, err error)

func NewExternalCommandExitError ¶

func NewExternalCommandExitError(err *exec.ExitError) ExternalCommandExitError

func NewNoResultsError ¶

func NewNoResultsError(message string) NoResultsError

func Parse ¶ added in v0.8.0

func Parse(ctx CmdContext, raw string, opts ParseOptions) (*Path, error)

Parse splits raw command input into a Path using deterministic Azure DevOps-style scope rules. Heuristics never decide whether a segment is an organization, project, or target: an explicit "ORG:" prefix carries the organization and a leading "/" marks the no-project form.

The input is trimmed, then an optional ORG: prefix is recognized. The remainder is split on "/", each segment is trimmed, and empty segments are rejected. After the organization prefix the grammar is:

PROJECT/TARGET...   project-first form; the first segment is the project
/TARGET...          no-project form; every segment is a target

The project rule (required, optional, or disallowed) and the target range select the valid shapes for a mode:

• AllowImplicitOrg allows the ORG: prefix to be omitted. When omitted, Parse loads the default organization from the user configuration.
• RequireProject requires the project-first form.
• DisallowProject requires the no-project form.
• DisallowTargets rejects any target segments.
• MinTargets defines the required trailing target count.
• MaxTargets defines the allowed trailing target count. Zero means unbounded; DisallowTargets is the only way to express that no targets are allowed.

Ambiguous inputs such as a legacy "ORG/SUBJECT" are interpreted as canonical project-first forms (PROJECT/SUBJECT) and are never auto-detected as an organization. Structurally detectable legacy organization forms — for example "ORG/PROJECT" where a mode cannot accept a project-plus-extra-segment shape — are rejected with ORG: guidance. The no-project form requires the "/" marker; an organization-only input in a mode that accepts targets must use "ORG:/".

Examples:

Parse(ctx, "org:/group", ParseOptions{AllowImplicitOrg: false, MinTargets: 1, MaxTargets: 1})
// => &Path{Organization: "org", Targets: []string{"group"}}

Parse(nil, "org:project/group", ParseOptions{AllowImplicitOrg: false, MinTargets: 1, MaxTargets: 1})
// => &Path{Organization: "org", Project: "project", Targets: []string{"group"}}

Parse(ctx, "/group", ParseOptions{AllowImplicitOrg: true, MinTargets: 1, MaxTargets: 1})
// => &Path{Organization: <default org>, Targets: []string{"group"}}

Parse(ctx, "project/group", ParseOptions{AllowImplicitOrg: true, MinTargets: 1, MaxTargets: 1})
// => &Path{Organization: <default org>, Project: "project", Targets: []string{"group"}}

Parse(ctx, "project", ParseOptions{AllowImplicitOrg: true, DisallowTargets: true})
// => &Path{Organization: <default org>, Project: "project"}

Parse(ctx, "org:", ParseOptions{AllowImplicitOrg: true, DisallowTargets: true})
// => &Path{Organization: "org"}

Parse(ctx, "/pool/agent", ParseOptions{AllowImplicitOrg: true, DisallowProject: true, MinTargets: 2, MaxTargets: 2})
// => &Path{Organization: <default org>, Targets: []string{"pool", "agent"}}

Error conditions:

• opts are invalid, for example a negative target count, MaxTargets below MinTargets, DisallowTargets combined with a positive target bound, or RequireProject combined with DisallowProject
• the input contains multiple or misplaced colons, an empty ORG: prefix, or an empty segment after trimming, for example "org:project/" or "org:/ /x"
• the input shape violates the project rule or the target range
• an explicit organization is required but the ORG: prefix is missing
• a structurally detectable legacy ORGANIZATION/... form is used without ORG:
• "ORG:" is used in a mode that accepts targets instead of the "ORG:/" marker
• organization is omitted but ctx is nil
• organization is omitted and the default organization lookup fails or returns empty

func ParsePoolAgentTargetWithDefaultOrganization ¶ added in v0.8.0

func ParsePoolAgentTargetWithDefaultOrganization(ctx CmdContext, raw string) (*Path, error)

ParsePoolAgentTargetWithDefaultOrganization resolves a pool/agent target that allows an implicit organization by falling back to the configured default. Accepted forms are /POOL/AGENT and ORG:/POOL/AGENT; the no-project marker is required because this mode disallows projects.

func ParseProjectScope ¶ added in v0.6.0

func ParseProjectScope(ctx CmdContext, arg string) (*Path, error)

ParseProjectScope parses arguments of the form PROJECT or ORG:PROJECT. When the organization prefix is omitted the default organization from the user's configuration is used. Legacy ORGANIZATION/PROJECT inputs are rejected with ORG: guidance.

func ParseProjectTargetWithDefaultOrganization ¶ added in v0.6.0

func ParseProjectTargetWithDefaultOrganization(ctx CmdContext, target string) (*Path, error)

ParseProjectTargetWithDefaultOrganization resolves targets that must include a project segment. Accepted forms are PROJECT/TARGET and ORG:PROJECT/TARGET, falling back to the user's default organization when the organization prefix is omitted.

func ParseScope ¶ added in v0.5.0

func ParseScope(ctx CmdContext, scope string) (*Path, error)

ParseScope resolves the organization and optional project from an input argument. Accepted forms are PROJECT, ORG:, and ORG:PROJECT; an empty input resolves to the default organization from the user configuration. Bare segments are project-first, so a bare ORG is parsed as a project.

func ParseTarget ¶ added in v0.6.0

func ParseTarget(target string) (*Path, error)

ParseTarget validates and parses a target argument of the form ORG:/TARGET or ORG:PROJECT/TARGET. An explicit organization is required.

func ParseTargetWithDefaultOrganization ¶ added in v0.6.0

func ParseTargetWithDefaultOrganization(ctx CmdContext, target string) (*Path, error)

ParseTargetWithDefaultOrganization resolves a target that allows an implicit organization by falling back to the configured default. Accepted forms are /TARGET, PROJECT/TARGET, ORG:/TARGET, and ORG:PROJECT/TARGET. A legacy ORG/TARGET input is parsed as a project-first PROJECT/TARGET.