gogh Project Development Guide

Development instructions for contributing to the gogh project, a tool for efficient GitHub repository management inspired by `ghq`.

Output Language

**Explanations**: Primarily in Japanese

**Code elements**: English only

- Code comments

- Error messages

- Test case titles

- Documentation strings

Project Structure

Package Location

**Repository**: `github.com/kyoh86/gogh`

**Versioned packages**: May include version suffixes (e.g., `github.com/kyoh86/gogh/v4`)

Directory Architecture

```

gogh/

├── app/ # Application layer (use cases)

│ ├── auth/ # Authentication-related use cases

│ ├── bundle/ # Bundle (repository batch management) use cases

│ ├── clone/ # Clone operation use cases

│ ├── fork/ # Fork operation use cases

│ ├── repos/ # Repository list display use cases

│ └── service/ # Common services (used across multiple use cases)

│

├── core/ # Core layer (domain models and interfaces)

│ ├── auth/ # Authentication-related interfaces

│ ├── git/ # Git operation interfaces

│ ├── hosting/ # Repository hosting service interfaces

│ ├── repository/ # Repository representation and path operation interfaces

│ ├── store/ # Data persistence interfaces

│ ├── workspace/ # Workspace management interfaces

│ └── *_mock/ # Packages containing mocks for each interface

│

├── infra/ # External system integration layer (implementations of core interfaces)

│ ├── auth/ # Authentication implementation

│ ├── git/ # Git operation implementation

│ ├── github/ # GitHub API integration

│ ├── store/ # Data persistence implementation

│ └── workspace/ # Workspace management implementation

│

└── ui/ # UI layer (user interfaces)

└── cli/ # Command-line interface

└── commands/ # Implementation of various commands

```

Testing Guidelines

Private Function Tests

**File naming**: `_private_test.go`

**Package**: Same package as the code under test

**Location**: Same directory as the implementation

Public Function Tests

**File naming**: `*_test.go`

**Package**: Append `_test` to the original package name

**Import convention**: Import the tested package as `testtarget`

**Location**: Same directory as the implementation

Testing Framework

**Use**: Standard `testing` package only

**Avoid**: `testify/assert` and `testify/require`

**Example**:

```go

package mypackage_test

import (

"testing"

testtarget "github.com/kyoh86/gogh/v4/mypackage"

)

func TestPublicFunction(t *testing.T) {

// Test implementation

}

```

Mock Generation

Mock Placement

**Generator**: `mockgen` from `go.uber.org/mock/gomock`

**Location**: Separate package at the same level as the interface package

**Package naming**: `<original_package>_mock`

**Example**: Mocks for `core/repository` → `core/repository_mock`

Mock File Naming

**Convention**: `gen_<lowercase_interface_name>_mock.go`

**Example**: Mock for `DefaultNameService` → `gen_default_name_service_mock.go`

Generate Directive

**File**: Place `go:generate` commands in `gen.go`

**Purpose**: Automate mock generation

**Example gen.go**:

```go

package repository_mock

//go:generate mockgen -destination=gen_default_name_service_mock.go -package=repository_mock github.com/kyoh86/gogh/v4/core/repository DefaultNameService

```

Architecture Overview

Four-Layer Architecture

#### 1. Core Layer (`core/`)

**Purpose**: Domain entities and external system interfaces

**Dependencies**: None (innermost layer)

**Contains**:

- Repository references

- Hosting service interfaces

- Authentication interfaces

- Domain entities and pure logic

#### 2. Application Layer (`app/`)

**Purpose**: Use case orchestration

**Dependencies**: Core layer interfaces only

**Contains**:

- Use case flows

- Business logic coordination

- Examples: clone, fork, list repositories

#### 3. Infrastructure Layer (`infra/`)

**Purpose**: External system integration and technical implementations

**Dependencies**: Core layer interfaces and types

**Contains**:

- API clients (e.g., GitHub)

- Database connections

- File operations

- Store implementations

#### 4. UI Layer (`ui/`)

**Purpose**: User interaction

**Dependencies**: Application layer

**Contains**:

- CLI commands (Cobra-based)

- Output formatters

- User input handling

Dependency Rules

1. **Core layer**: No imports from other layers

2. **Application layer**: Import core layer only

3. **Infrastructure layer**: Import core layer only

4. **UI layer**: Import application layer

Integration Pattern

1. Core layer **defines** interfaces

2. Infrastructure layer **implements** interfaces

3. Application layer **uses** interfaces to call external systems

Core Concepts of gogh

Repository Reference

**Format**: `github.com/owner/repo`

Interpretation rules for repository identification

Repository Components

Name

Owner

URL format

Basic attributes

Structuring Rules

**Path structure**: `<root>/<host>/<owner>/<name>`

Organized by hosting provider and ownership

Basic Operations

Abstract concepts: cloning, searching, listing

Domain-level operation definitions

Development Workflow

1. **Define interfaces** in the core layer

2. **Implement use cases** in the application layer using core interfaces

3. **Implement external integrations** in the infrastructure layer

4. **Expose functionality** through the UI layer

5. **Generate mocks** using `go generate` for testing

6. **Write tests** following the testing guidelines above

gogh Project Development Guide

gogh Project Development Guide

Output Language

Project Structure

Package Location

Directory Architecture

Testing Guidelines

Private Function Tests

Public Function Tests

Testing Framework

Mock Generation

Mock Placement

Mock File Naming

Generate Directive

Architecture Overview

Four-Layer Architecture

Dependency Rules

Integration Pattern

Core Concepts of gogh

Repository Reference

Repository Components

Structuring Rules

Basic Operations

Development Workflow

Reviews (0)