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 ¶
- Constants
- func CleanExpiredCache() error
- func FormatUserError(err error) string
- func GetCurrentRepo() (owner, repo string, err error)
- func HandleHTTPError(resp *http.Response, operation string) error
- func IsErrorType(err error, errType ErrorType) bool
- func IsTerminal() bool
- func ParseIssueReference(ref string) (repo string, issueNum int, err error)
- func ParseIssueURL(url string) (owner, repo string, issueNumber int, err error)
- func ParseRepoFlag(repoFlag string) (owner, repo string, err error)
- func ResolveRepository(repoFlag, issueRef string) (owner, repo string, err error)
- func SetupGitHubClient() error
- func ValidateRepoAccess(owner, repo string) error
- func ValidateRepository(repo string) error
- type AppError
- func NewAppError(errType ErrorType, message string, cause error) *AppError
- func NewAuthTokenError() *AppError
- func NewCircularDependencyError(issueA, issueB string) *AppError
- func NewDependencyExistsError(issueA, issueB string) *AppError
- func NewEmptyValueError(field string) *AppError
- func NewIssueNotFoundError(repo string, issueNumber int) *AppError
- func NewIssueNumberValidationError(value string) *AppError
- func NewPermissionDeniedError(operation, repo string) *AppError
- func NewRepositoryAccessError(repo string, err error) *AppError
- func NewRepositoryFormatError(value string) *AppError
- func NewRepositoryNotFoundError(repo string) *AppError
- func NewTimeoutError(operation string) *AppError
- func WrapAPIError(statusCode int, err error) *AppError
- func WrapAuthError(err error) *AppError
- func WrapInternalError(operation string, err error) *AppError
- func WrapNetworkError(err error) *AppError
- func WrapPermissionError(repo string, err error) *AppError
- func WrapValidationError(field, value string, err error) *AppError
- type CacheEntry
- type DependencyData
- type DependencyRelation
- type DependencyRemover
- func (r *DependencyRemover) RemoveAllRelationships(issue IssueRef, opts RemoveOptions) error
- func (r *DependencyRemover) RemoveBatchRelationships(source IssueRef, targets []IssueRef, relType string, opts RemoveOptions) error
- func (r *DependencyRemover) RemoveCrossRepositoryRelationship(source, target IssueRef, relType string, opts RemoveOptions) error
- func (r *DependencyRemover) RemoveRelationship(source, target IssueRef, relType string, opts RemoveOptions) error
- type ErrorType
- type Issue
- type IssueRef
- type Label
- type OutputFormat
- type OutputFormatter
- type OutputOptions
- type RemovalExecutor
- type RemovalValidator
- func (v *RemovalValidator) ValidateBatchRemoval(source IssueRef, targets []IssueRef, relType string) error
- func (v *RemovalValidator) ValidateRemoval(source, target IssueRef, relType string) error
- func (v *RemovalValidator) VerifyRelationshipExists(source, target IssueRef, relType string) (bool, error)
- type RemoveOptions
- type RepoInfo
- type RepositoryInfo
- type User
- type ValidationIssue
- type ValidationResult
Examples ¶
Constants ¶
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 GetCurrentRepo ¶
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 ¶
HandleHTTPError converts HTTP response errors to appropriate AppErrors
func IsErrorType ¶
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 ¶
ParseIssueReference parses various issue reference formats and validates them
func ParseIssueURL ¶
ParseIssueURL parses GitHub issue URLs to extract repository and issue number
func ParseRepoFlag ¶
ParseRepoFlag validates and parses the --repo flag value
func ResolveRepository ¶
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 ¶
ValidateRepoAccess validates that the user has access to the specified repository
func ValidateRepository ¶
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 ¶
NewAppError creates a new structured application error
func NewAuthTokenError ¶
func NewAuthTokenError() *AppError
func NewEmptyValueError ¶
func NewIssueNotFoundError ¶
Issue Errors
func NewRepositoryNotFoundError ¶
Repository Errors
func NewTimeoutError ¶
func WrapInternalError ¶
Internal Errors
func WrapPermissionError ¶
Permission Errors
func WrapValidationError ¶
Validation Errors
func (*AppError) WithContext ¶
WithContext adds contextual information to an error
func (*AppError) WithSuggestion ¶
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 ¶
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 ¶
CreateIssueRef creates an IssueRef from individual components
func ParseIssueRefWithRepo ¶
ParseIssueRefWithRepo parses an issue reference string and creates an IssueRef It handles the same formats as the existing ParseIssueReference function
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 ¶
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 ValidationIssue ¶
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