Architecture

Relevant source files

• src/helpers.ts
• src/index.ts
• src/output.ts
• src/repo.ts

This document describes the internal architecture of git-merged-branches, explaining how the major modules are organized, how they interact with each other, and the patterns used throughout the codebase. For detailed information about specific modules, see the subsections: System Overview, CLI Entry Point, Git Repository Operations, Output Formatting System, and Utilities and Helpers.

For information about building and testing the system, see Development. For the end-user perspective, see User Guide.

Module Organization

The codebase follows a layered architecture with clear separation of concerns. The system is organized into the following primary modules:

Module	File	Primary Responsibility
CLI Entry Point	src/index.ts	Orchestration, validation, and error handling
Git Operations	src/repo.ts	Git command execution and repository state queries
Output Formatting	src/output.ts	Branch list formatting, issue URL generation, and deletion coordination
Validation	src/validate.ts	Input validation (e.g., URL checking)
Utilities	src/helpers.ts	Text styling, pluralization, and error logging
Type Definitions	src/types.ts	Shared TypeScript interfaces and types

Sources: src/index.ts1-32 src/repo.ts1-101 src/output.ts1-68 src/helpers.ts1-23

Core Module Structure

The following diagram shows the primary modules and their exported functions, mapping natural language concepts directly to code entities:

Module Structure and Function Exports

This diagram maps each module to its functions, using exact names from the codebase. Arrows show call relationships.

Sources: src/index.ts6-29 src/repo.ts8-100 src/output.ts6-67 src/helpers.ts3-22

Execution Flow

The main execution flow follows a strict validation-query-process-output pipeline:

Main Execution Sequence

This sequence diagram shows the complete execution flow from user invocation through validation, querying, and output.

Sources: src/index.ts6-29 src/repo.ts8-100 src/output.ts39-67

Module Dependencies

The dependency graph shows how modules import and use each other:

Module Import Dependencies

src/index.ts acts as the orchestrator, while src/repo.ts and src/output.ts contain the core logic. src/helpers.ts provides shared utility functions like style and logError.

Sources: src/index.ts1-4 src/output.ts1-4 src/repo.ts1-6

Data Transformation Pipeline

The system transforms data through several stages, from Git repository state to formatted console output:

1. Repository Validation: Checks if the current directory is a Git work tree src/repo.ts8-15 and not in a detached HEAD state src/repo.ts17-24
2. Branch Discovery: Identifies the target branch (main/master) src/repo.ts35-42 and retrieves merged branches src/repo.ts44-56
3. Configuration Loading: Reads package.json to extract git-merged-branches settings src/repo.ts72-81
4. Branch Formatting: Matches branch names against prefixes to generate issue URLs src/output.ts6-22
5. Action Execution: Either prints manual deletion commands or executes automated deletion via deleteBranches src/output.ts54-66

Sources: src/repo.ts8-100 src/output.ts6-67 src/index.ts6-29

Error Handling Strategy

The system uses a two-tier error handling approach:

Validation Errors (Fail-Fast)

Early validation errors in the main entry point cause immediate termination with a non-zero exit code:

• Not a Git repository src/index.ts7-10
• Detached HEAD state src/index.ts11-14
• Missing target (main/master) branch src/index.ts16-20

Runtime Errors (Graceful Degradation)

Errors during execution are caught and logged using logError src/helpers.ts3-9 often returning safe default values:

• Remote fetch failures return an empty list src/repo.ts66-69
• Configuration read failures return an empty object src/repo.ts77-80
• Deletion failures log the error but allow the process to conclude src/repo.ts97-99

Sources: src/index.ts7-28 src/repo.ts58-100 src/helpers.ts3-9

Key Design Patterns

Separation of Concerns

• Logic vs. IO: src/repo.ts handles Git IO, while src/output.ts handles presentation logic.
• Pure Helpers: Functions like pluralize src/helpers.ts11-13 and isValidURL are pure and decoupled from the Git state.

Orchestration Pattern

The main() function in src/index.ts does not contain business logic; it coordinates the flow between the repository layer and the output layer src/index.ts6-29

Configuration-Driven Formatting

The formatting system uses data from package.json to transform branch names into clickable links, separating the tool's logic from project-specific naming conventions src/output.ts24-37

Sources: src/index.ts1-32 src/repo.ts1-101 src/output.ts1-68