Function resolveExplicitRef

internal/skills/discovery/discovery.go:236–273

resolveExplicitRef resolves a user-supplied version string. It supports: - fully qualified refs: "refs/tags/v1.0" or "refs/heads/main" - short names: tried as branch first, then tag, then commit SHA - bare SHAs: resolved as commit SHA When a short name matches both a branch and a tag, the branch wi

(client *api.Client, host, owner, repo, ref string)

// The returned Ref is always a fully qualified ref (refs/heads/* or refs/tags/*)
// unless the input resolves to a bare commit SHA.
func resolveExplicitRef(client *api.Client, host, owner, repo, ref string) (*ResolvedRef, error) {
	// Handle fully-qualified refs: resolve directly without ambiguity.
	if after, ok := strings.CutPrefix(ref, "refs/tags/"); ok {
		return resolveTagRef(client, host, owner, repo, after)
	}
	if after, ok := strings.CutPrefix(ref, "refs/heads/"); ok {
		return resolveBranchRef(client, host, owner, repo, after)
	}

	// Short name: try branch first, then tag, then commit SHA.
	// Only fall through on 404 (not found); surface other errors
	// (403, 500, network) immediately to avoid masking real failures.
	if resolved, err := resolveBranchRef(client, host, owner, repo, ref); err == nil {
		return resolved, nil
	} else if !isNotFound(err) {
		return nil, err
	}
	if resolved, err := resolveTagRef(client, host, owner, repo, ref); err == nil {
		return resolved, nil
	} else if !isNotFound(err) {
		return nil, err
	}

	commitPath, err := safeurl.JoinPath("repos", owner, repo, "commits", ref)
	if err != nil {
		return nil, err
	}
	var commitResp struct {
		SHA string `json:"sha"`
	}
	if err := client.REST(host, "GET", commitPath.String(), nil, &commitResp); err == nil {
		return &ResolvedRef{Ref: commitResp.SHA, SHA: commitResp.SHA}, nil
	} else if !isNotFound(err) {
		return nil, err
	}

	return nil, fmt.Errorf("ref %q not found as branch, tag, or commit in %s/%s", ref, owner, repo)
}

// resolveTagRef looks up a tag by short name and returns a fully qualified ref.
// For annotated tags, the tag object is dereferenced to obtain the commit SHA.