pkg

package
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Sep 12, 2025 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package pkg provides shared utilities and types for the gh-issue-dependency extension.

This package contains GitHub API integration, error handling, repository context detection, and other common functionality used across all commands.

Package pkg provides output formatting for dependency data

Package pkg provides validation utilities for dependency removal operations.

This file implements comprehensive validation logic for removing GitHub issue dependency relationships, including relationship existence verification, permission checking, and input validation.

Package pkg provides integration functions for the remove command validation.

This file demonstrates how to integrate the RemovalValidator with the existing remove command structure from cmd/remove.go.

Index

Examples

Constants

View Source
const (
	CacheDir      = ".gh-issue-dependency-cache"
	CacheDuration = 5 * time.Minute // Cache for 5 minutes
)

Cache configuration

Variables

This section is empty.

Functions

func CleanExpiredCache

func CleanExpiredCache() error

CleanExpiredCache removes expired cache entries

func FormatUserError

func FormatUserError(err error) string

Error Formatting and User Display

func GetCurrentRepo

func GetCurrentRepo() (owner, repo string, err error)

GetCurrentRepo gets the current repository context using the GitHub CLI. It uses 'gh repo view' to determine the repository based on the current working directory. This function requires that the user is in a directory associated with a GitHub repository and that they have authenticated with the GitHub CLI.

Returns the repository owner and name, or an error if the repository cannot be determined.

func HandleHTTPError

func HandleHTTPError(resp *http.Response, operation string) error

HandleHTTPError converts HTTP response errors to appropriate AppErrors

func IsErrorType

func IsErrorType(err error, errType ErrorType) bool

IsErrorType checks if an error is of a specific type

func IsTerminal

func IsTerminal() bool

IsTerminal detects if the output is going to a terminal/TTY

func ParseIssueReference

func ParseIssueReference(ref string) (repo string, issueNum int, err error)

ParseIssueReference parses various issue reference formats and validates them

func ParseIssueURL

func ParseIssueURL(url string) (owner, repo string, issueNumber int, err error)

ParseIssueURL parses GitHub issue URLs to extract repository and issue number

func ParseRepoFlag

func ParseRepoFlag(repoFlag string) (owner, repo string, err error)

ParseRepoFlag validates and parses the --repo flag value

func ResolveRepository

func ResolveRepository(repoFlag, issueRef string) (owner, repo string, err error)

ResolveRepository resolves repository context using the priority order: 1. --repo flag (if provided) 2. Issue URL parsing (if issue is URL) 3. Current repository detection via `gh repo view` 4. Error if no context available

func SetupGitHubClient

func SetupGitHubClient() error

SetupGitHubClient sets up a GitHub API client using gh CLI's authentication

func ValidateRepoAccess

func ValidateRepoAccess(owner, repo string) error

ValidateRepoAccess validates that the user has access to the specified repository

func ValidateRepository

func ValidateRepository(repo string) error

ValidateRepository validates repository name format

Types

type AppError

type AppError struct {
	Type        ErrorType         // Category of error for exit code determination
	Message     string            // User-facing error message
	Cause       error             // Underlying error that caused this error
	Context     map[string]string // Additional context information (repository, issue, etc.)
	Suggestions []string          // Actionable suggestions for resolving the error
}

AppError represents a structured error with context and user guidance. This is the primary error type used throughout the application to provide consistent, user-friendly error messages with actionable suggestions.

func NewAppError

func NewAppError(errType ErrorType, message string, cause error) *AppError

NewAppError creates a new structured application error

func NewAuthTokenError

func NewAuthTokenError() *AppError

func NewCircularDependencyError

func NewCircularDependencyError(issueA, issueB string) *AppError

func NewDependencyExistsError

func NewDependencyExistsError(issueA, issueB string) *AppError

func NewEmptyValueError

func NewEmptyValueError(field string) *AppError

func NewIssueNotFoundError

func NewIssueNotFoundError(repo string, issueNumber int) *AppError

Issue Errors

func NewIssueNumberValidationError

func NewIssueNumberValidationError(value string) *AppError

func NewPermissionDeniedError

func NewPermissionDeniedError(operation, repo string) *AppError

func NewRepositoryAccessError

func NewRepositoryAccessError(repo string, err error) *AppError

func NewRepositoryFormatError

func NewRepositoryFormatError(value string) *AppError

func NewRepositoryNotFoundError

func NewRepositoryNotFoundError(repo string) *AppError

Repository Errors

func NewTimeoutError

func NewTimeoutError(operation string) *AppError

func WrapAPIError

func WrapAPIError(statusCode int, err error) *AppError

API Errors

func WrapAuthError

func WrapAuthError(err error) *AppError

Authentication Errors

func WrapInternalError

func WrapInternalError(operation string, err error) *AppError

Internal Errors

func WrapNetworkError

func WrapNetworkError(err error) *AppError

Network Errors

func WrapPermissionError

func WrapPermissionError(repo string, err error) *AppError

Permission Errors

func WrapValidationError

func WrapValidationError(field, value string, err error) *AppError

Validation Errors

func (*AppError) Error

func (e *AppError) Error() string

func (*AppError) Unwrap

func (e *AppError) Unwrap() error

func (*AppError) WithContext

func (e *AppError) WithContext(key, value string) *AppError

WithContext adds contextual information to an error

func (*AppError) WithSuggestion

func (e *AppError) WithSuggestion(suggestion string) *AppError

WithSuggestion adds a recovery suggestion to an error

type CacheEntry

type CacheEntry struct {
	Data      DependencyData `json:"data"`
	ExpiresAt time.Time      `json:"expires_at"`
}

CacheEntry represents a cached dependency data entry

type DependencyData

type DependencyData struct {
	SourceIssue            Issue                `json:"source_issue"`
	BlockedBy              []DependencyRelation `json:"blocked_by"`
	Blocking               []DependencyRelation `json:"blocking"`
	FetchedAt              time.Time            `json:"fetched_at"`
	TotalCount             int                  `json:"total_count"`
	OriginalBlockedByCount int                  `json:"original_blocked_by_count,omitempty"`
	OriginalBlockingCount  int                  `json:"original_blocking_count,omitempty"`
}

DependencyData contains all dependency information for an issue

func FetchIssueDependencies

func FetchIssueDependencies(ctx context.Context, owner, repo string, issueNumber int) (*DependencyData, error)

FetchIssueDependencies is the main exported function for retrieving dependency data

type DependencyRelation

type DependencyRelation struct {
	Issue      Issue  `json:"issue"`
	Type       string `json:"type"`       // "blocked_by" or "blocks"
	Repository string `json:"repository"` // Repository of the related issue
}

DependencyRelation represents a relationship between issues

type DependencyRemover

type DependencyRemover struct {
	// contains filtered or unexported fields
}

DependencyRemover provides GitHub API integration for removing dependency relationships. It handles DELETE operations, error processing, retry logic, and success confirmation.

func NewDependencyRemover

func NewDependencyRemover() (*DependencyRemover, error)

NewDependencyRemover creates a new dependency remover with GitHub API client

func (*DependencyRemover) RemoveAllRelationships

func (r *DependencyRemover) RemoveAllRelationships(issue IssueRef, opts RemoveOptions) error

RemoveAllRelationships removes all dependency relationships for an issue

func (*DependencyRemover) RemoveBatchRelationships

func (r *DependencyRemover) RemoveBatchRelationships(source IssueRef, targets []IssueRef, relType string, opts RemoveOptions) error

RemoveBatchRelationships removes multiple dependency relationships in batch

func (*DependencyRemover) RemoveCrossRepositoryRelationship

func (r *DependencyRemover) RemoveCrossRepositoryRelationship(source, target IssueRef, relType string, opts RemoveOptions) error

RemoveCrossRepositoryRelationship handles dependency removal across different repositories

func (*DependencyRemover) RemoveRelationship

func (r *DependencyRemover) RemoveRelationship(source, target IssueRef, relType string, opts RemoveOptions) error

RemoveRelationship removes a single dependency relationship between two issues

type ErrorType

type ErrorType string

ErrorType represents the category of error for proper handling. This allows the CLI to determine appropriate exit codes and error formatting.

const (
	ErrorTypeAuthentication ErrorType = "authentication"
	ErrorTypePermission     ErrorType = "permission"
	ErrorTypeNetwork        ErrorType = "network"
	ErrorTypeValidation     ErrorType = "validation"
	ErrorTypeAPI            ErrorType = "api"
	ErrorTypeRepository     ErrorType = "repository"
	ErrorTypeIssue          ErrorType = "issue"
	ErrorTypeInternal       ErrorType = "internal"
)

func GetErrorType

func GetErrorType(err error) ErrorType

GetErrorType returns the error type, or ErrorTypeInternal if not an AppError

type Issue

type Issue struct {
	Number     int            `json:"number"`
	Title      string         `json:"title"`
	State      string         `json:"state"`
	Assignees  []User         `json:"assignees"`
	Labels     []Label        `json:"labels"`
	HTMLURL    string         `json:"html_url"`
	Repository RepositoryInfo `json:"repository,omitempty"` // Repository object from GitHub API
}

Issue represents a GitHub issue with dependency-relevant fields

type IssueRef

type IssueRef struct {
	Owner  string
	Repo   string
	Number int
	// FullName returns the full repository name (owner/repo)
	FullName string
}

IssueRef represents a reference to a GitHub issue

func CreateIssueRef

func CreateIssueRef(owner, repo string, number int) IssueRef

CreateIssueRef creates an IssueRef from individual components

func ParseIssueRefWithRepo

func ParseIssueRefWithRepo(issueRefStr, defaultOwner, defaultRepo string) (IssueRef, error)

ParseIssueRefWithRepo parses an issue reference string and creates an IssueRef It handles the same formats as the existing ParseIssueReference function

func (IssueRef) String

func (ref IssueRef) String() string

String returns a string representation of the issue reference

type Label

type Label struct {
	Name        string `json:"name"`
	Color       string `json:"color"`
	Description string `json:"description"`
}

Label represents a GitHub issue label

type OutputFormat

type OutputFormat int

OutputFormat represents the different output formats supported

const (
	FormatAuto  OutputFormat = iota // Auto-detect based on TTY
	FormatTTY                       // Rich TTY output with colors and emojis
	FormatPlain                     // Plain text output
	FormatJSON                      // JSON output
	FormatCSV                       // CSV output
)

type OutputFormatter

type OutputFormatter struct {
	// contains filtered or unexported fields
}

OutputFormatter handles all output formatting operations

func NewOutputFormatter

func NewOutputFormatter(options *OutputOptions) *OutputFormatter

NewOutputFormatter creates a new output formatter with the given options

func (*OutputFormatter) FormatOutput

func (f *OutputFormatter) FormatOutput(data *DependencyData) error

FormatOutput formats dependency data according to the configured output format

type OutputOptions

type OutputOptions struct {
	Format       OutputFormat
	JSONFields   []string // Specific fields to include in JSON output
	Detailed     bool     // Include detailed information
	Writer       io.Writer
	StateFilter  string          // Applied state filter for context-aware messaging
	OriginalData *DependencyData // Original data before filtering for comparison
}

OutputOptions contains configuration for output formatting

func DefaultOutputOptions

func DefaultOutputOptions() *OutputOptions

DefaultOutputOptions returns sensible defaults for output options

type RemovalExecutor

type RemovalExecutor struct {
	// contains filtered or unexported fields
}

RemovalExecutor integrates validation with the remove command execution

func NewRemovalExecutor

func NewRemovalExecutor() (*RemovalExecutor, error)

NewRemovalExecutor creates a new executor with validation capabilities

func (*RemovalExecutor) ExecuteRemoval

func (e *RemovalExecutor) ExecuteRemoval(sourceIssueStr, dependencyRefsStr, relationType string, opts RemoveOptions) error

ExecuteRemoval performs validation and executes dependency removal This function demonstrates the integration pattern for cmd/remove.go

type RemovalValidator

type RemovalValidator struct {
	// contains filtered or unexported fields
}

RemovalValidator provides validation services for dependency removal operations. It leverages existing GitHub API utilities and error handling patterns to ensure safe and reliable dependency relationship removal.

func NewRemovalValidator

func NewRemovalValidator() (*RemovalValidator, error)

NewRemovalValidator creates a new validator instance for dependency removal operations. It sets up the GitHub API client using the existing authentication patterns.

func (*RemovalValidator) ValidateBatchRemoval

func (v *RemovalValidator) ValidateBatchRemoval(source IssueRef, targets []IssueRef, relType string) error

ValidateBatchRemoval validates removal of multiple dependencies at once

Example

Example batch validation

// validator, err := NewRemovalValidator()
// if err != nil {
// 	fmt.Printf("Failed to create validator: %v\n", err)
// 	return
// }

source := CreateIssueRef("owner", "repo", 123)
targets := []IssueRef{
	CreateIssueRef("owner", "repo", 456),
	CreateIssueRef("owner", "repo", 789),
	CreateIssueRef("other", "repo", 101),
}

// err = validator.ValidateBatchRemoval(source, targets, "blocks")
// if err != nil {
// 	fmt.Printf("Batch validation failed: %v\n", err)
// 	return
// }

fmt.Printf("Batch validation example: %s blocks %d issues\n", source.String(), len(targets))
Output:

Batch validation example: owner/repo#123 blocks 3 issues

func (*RemovalValidator) ValidateRemoval

func (v *RemovalValidator) ValidateRemoval(source, target IssueRef, relType string) error

ValidateRemoval performs comprehensive validation for dependency removal operations. This includes input validation, permission checking, issue accessibility validation, and relationship existence verification.

Example

Example usage patterns for integration with cmd/remove.go

// This example shows how to use the validator in the remove command

// 1. Create validator (would require GitHub CLI auth in real usage)
// validator, err := NewRemovalValidator()
// if err != nil {
// 	fmt.Printf("Failed to create validator: %v\n", err)
// 	return
// }

// 2. Parse issue references
source := CreateIssueRef("owner", "repo", 123)
target := CreateIssueRef("owner", "repo", 456)

// 3. Validate removal (would require API calls in real usage)
// err = validator.ValidateRemoval(source, target, "blocked-by")
// if err != nil {
// 	fmt.Printf("Validation failed: %v\n", err)
// 	return
// }

fmt.Printf("Validation example: %s -> %s (blocked-by)\n", source.String(), target.String())
Output:

Validation example: owner/repo#123 -> owner/repo#456 (blocked-by)

func (*RemovalValidator) VerifyRelationshipExists

func (v *RemovalValidator) VerifyRelationshipExists(source, target IssueRef, relType string) (bool, error)

VerifyRelationshipExists checks if a dependency relationship actually exists between the source and target issues using the GitHub API.

type RemoveOptions

type RemoveOptions struct {
	DryRun bool
	Force  bool
}

RemoveOptions contains options for dependency removal operations

type RepoInfo

type RepoInfo struct {
	Owner string `json:"owner"` // Repository owner (user or organization)
	Name  string `json:"name"`  // Repository name
}

RepoInfo represents repository information returned from GitHub API calls. This structure is used for JSON unmarshaling of repository data.

type RepositoryInfo

type RepositoryInfo struct {
	Name     string `json:"name"`
	FullName string `json:"full_name"`
	HTMLURL  string `json:"html_url"`
	Owner    struct {
		Login string `json:"login"`
	} `json:"owner"`
}

RepositoryInfo represents repository information from GitHub API

func (RepositoryInfo) IsEmpty

func (r RepositoryInfo) IsEmpty() bool

IsEmpty returns true if this is an empty/zero repository info

func (RepositoryInfo) String

func (r RepositoryInfo) String() string

String returns the string representation of the repository (FullName)

type User

type User struct {
	Login   string `json:"login"`
	HTMLURL string `json:"html_url"`
}

User represents a GitHub user or organization

type ValidationIssue

type ValidationIssue struct {
	Type        string
	Message     string
	IssueRef    IssueRef
	Suggestions []string
}

ValidationIssue represents a specific validation problem

type ValidationResult

type ValidationResult struct {
	Valid       bool
	Error       error
	Issues      []ValidationIssue
	Suggestions []string
}

ValidationResult contains the result of a validation operation

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL