# hfnissum-byte/hunkpick architecture

> Architecture diagram of the GitHub repository hfnissum-byte/hunkpick, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hfnissum-byte/hunkpick
- Repository: https://github.com/hfnissum-byte/hunkpick

## Overview

Hunkpick is a Node.js CLI that resolves Git content conflicts by generating possible merges, filtering invalid candidates, and asking a model to choose among them; code applies confidence gates. The main flow starts with conflict discovery, rebuilds and parses conflicts, then generates line/token or JSON-key candidates for validation and judgment. Users can inspect a report, apply gated results, or review choices interactively. The graph follows README-documented stages and indexed imports; unsampled details are represented only where the README supports them.

Main entry points: [`hunkpick.mjs`](https://github.com/hfnissum-byte/hunkpick/blob/main/hunkpick.mjs) (CLI orchestration), [`lib/pipeline.mjs`](https://github.com/hfnissum-byte/hunkpick/blob/main/lib/pipeline.mjs) (Candidate pipeline), [`lib/judge.mjs`](https://github.com/hfnissum-byte/hunkpick/blob/main/lib/judge.mjs) (Model request and verdicts), [`lib/candidates.mjs`](https://github.com/hfnissum-byte/hunkpick/blob/main/lib/candidates.mjs) (Line and token merges)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and outcomes"]
  node_cli["CLI orchestration<br/>[hunkpick.mjs]"]
end

subgraph group_merge["Conflict processing"]
  node_git["Git conflict access<br/>[git.mjs]"]
  node_parser["Conflict parsing<br/>[conflicts.mjs]"]
  node_pipeline["Candidate pipeline<br/>[pipeline.mjs]"]
  node_candidates["Line and token merges<br/>[candidates.mjs]"]
  node_structured["JSON key merge<br/>[structured.mjs]"]
  node_validate["Syntax validation<br/>[validate.mjs]"]
end

subgraph group_judgment["Model judgment"]
  node_judge["Model request and verdicts<br/>[judge.mjs]"]
  node_typesafe["TypeSafe client<br/>[typesafe.mjs]"]
end

subgraph group_review["Human review"]
  node_review["Review state and rendering<br/>[review.mjs]"]
  node_ui["Terminal display helpers<br/>[ui.mjs]"]
end

node_user(("User"))
node_service["TypeSafe API"]
node_filesystem["Working tree files"]

node_user -->|"runs options"| node_cli
node_cli -->|"discovers conflicts"| node_git
node_cli -->|"builds outcomes"| node_pipeline
node_pipeline -->|"reads stages"| node_git
node_pipeline -->|"parses conflicts"| node_parser
node_pipeline -->|"generates candidates"| node_candidates
node_pipeline -->|"merges JSON"| node_structured
node_pipeline -->|"checks candidates"| node_validate
node_structured -->|"reuses array merge"| node_candidates
node_cli -->|"requests verdicts"| node_judge
node_judge -->|"summarizes differences"| node_candidates
node_judge -->|"sends request"| node_typesafe
node_typesafe -->|"posts judgment"| node_service
node_cli -->|"starts review"| node_review
node_review -->|"uses display helpers"| node_ui
node_cli -->|"writes accepted results"| node_filesystem
node_cli -->|"reports results"| node_user

click node_cli "https://github.com/hfnissum-byte/hunkpick/blob/main/hunkpick.mjs"
click node_git "https://github.com/hfnissum-byte/hunkpick/blob/main/lib/git.mjs"
click node_parser "https://github.com/hfnissum-byte/hunkpick/blob/main/lib/conflicts.mjs"
click node_pipeline "https://github.com/hfnissum-byte/hunkpick/blob/main/lib/pipeline.mjs"
click node_candidates "https://github.com/hfnissum-byte/hunkpick/blob/main/lib/candidates.mjs"
click node_structured "https://github.com/hfnissum-byte/hunkpick/blob/main/lib/structured.mjs"
click node_validate "https://github.com/hfnissum-byte/hunkpick/blob/main/lib/validate.mjs"
click node_judge "https://github.com/hfnissum-byte/hunkpick/blob/main/lib/judge.mjs"
click node_typesafe "https://github.com/hfnissum-byte/hunkpick/blob/main/lib/typesafe.mjs"
click node_review "https://github.com/hfnissum-byte/hunkpick/blob/main/lib/review.mjs"
click node_ui "https://github.com/hfnissum-byte/hunkpick/blob/main/lib/ui.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_user toneBlue
class node_git,node_parser,node_pipeline,node_candidates,node_structured,node_validate toneAmber
class node_judge,node_typesafe,node_service toneMint
class node_review,node_ui toneRose
class node_filesystem toneIndigo
```

## Components

### CLI and outcomes

- [CLI orchestration](https://github.com/hfnissum-byte/hunkpick/blob/main/hunkpick.mjs): `hunkpick.mjs`

### Conflict processing

- [Git conflict access](https://github.com/hfnissum-byte/hunkpick/blob/main/lib/git.mjs): `lib/git.mjs`
- [Conflict parsing](https://github.com/hfnissum-byte/hunkpick/blob/main/lib/conflicts.mjs): `lib/conflicts.mjs`
- [Candidate pipeline](https://github.com/hfnissum-byte/hunkpick/blob/main/lib/pipeline.mjs): `lib/pipeline.mjs`
- [Line and token merges](https://github.com/hfnissum-byte/hunkpick/blob/main/lib/candidates.mjs): `lib/candidates.mjs`
- [JSON key merge](https://github.com/hfnissum-byte/hunkpick/blob/main/lib/structured.mjs): `lib/structured.mjs`
- [Syntax validation](https://github.com/hfnissum-byte/hunkpick/blob/main/lib/validate.mjs): `lib/validate.mjs`

### Model judgment

- [Model request and verdicts](https://github.com/hfnissum-byte/hunkpick/blob/main/lib/judge.mjs): `lib/judge.mjs`
- [TypeSafe client](https://github.com/hfnissum-byte/hunkpick/blob/main/lib/typesafe.mjs): `lib/typesafe.mjs`

### Human review

- [Review state and rendering](https://github.com/hfnissum-byte/hunkpick/blob/main/lib/review.mjs): `lib/review.mjs`
- [Terminal display helpers](https://github.com/hfnissum-byte/hunkpick/blob/main/lib/ui.mjs): `lib/ui.mjs`

### Other components

- **User**
- **TypeSafe API**
- **Working tree files**

## Connections

- User → CLI orchestration: runs options (evidence: `README.md`)
- CLI orchestration → Git conflict access: discovers conflicts (evidence: `hunkpick.mjs`)
- CLI orchestration → Candidate pipeline: builds outcomes (evidence: `README.md`)
- Candidate pipeline → Git conflict access: reads stages (evidence: `lib/pipeline.mjs`)
- Candidate pipeline → Conflict parsing: parses conflicts (evidence: `lib/pipeline.mjs`)
- Candidate pipeline → Line and token merges: generates candidates (evidence: `lib/pipeline.mjs`)
- Candidate pipeline → JSON key merge: merges JSON (evidence: `lib/pipeline.mjs`)
- Candidate pipeline → Syntax validation: checks candidates (evidence: `lib/pipeline.mjs`)
- JSON key merge → Line and token merges: reuses array merge (evidence: `lib/structured.mjs`)
- CLI orchestration → Model request and verdicts: requests verdicts (evidence: `hunkpick.mjs`)
- Model request and verdicts → Line and token merges: summarizes differences (evidence: `lib/judge.mjs`)
- Model request and verdicts → TypeSafe client: sends request (evidence: `lib/judge.mjs`)
- TypeSafe client → TypeSafe API: posts judgment (evidence: `lib/typesafe.mjs`)
- CLI orchestration → Review state and rendering: starts review (evidence: `hunkpick.mjs`)
- Review state and rendering → Terminal display helpers: uses display helpers (evidence: `lib/review.mjs`)
- CLI orchestration → Working tree files: writes accepted results (evidence: `hunkpick.mjs`)
- CLI orchestration → User: reports results (evidence: `README.md`)
