# Contributing to Hunk

Thanks for helping improve Hunk.

Hunk is a review-first terminal diff viewer. Keep changes focused, verify behavior locally, and prefer small PRs over broad rewrites.

## Development setup

Requirements:

- Bun 1.3+
- Node.js 18+
- Git
- macOS, Linux, or Windows. The Windows path uses native Node/Bun on Windows 10/11 (x64); no WSL or Git Bash required.

> Nix users can use `nix develop` or [direnv](https://direnv.net/) to enter a development shell.

Install dependencies:

```bash
bun install
```

Run Hunk from source:

```bash
bun run src/main.tsx -- diff
```

## Common commands

Validate a typical change:

```bash
bun run typecheck
bun test
bun run test:tty-smoke
```

Format the JS/TS/JSON codebase:

```bash
bun run format
bun run format:check
```

Lint the JS/TS codebase:

```bash
bun run lint
bun run lint:fix
```

`bun install` also installs a local `pre-commit` hook that runs `lint-staged`, so staged JS/TS files are auto-formatted and linted before commit.

Build and verify the npm package:

```bash
bun run build:npm
bun run check:pack
```

Benchmark scripts live in [`benchmarks/`](benchmarks/README.md).

Common runs:

```bash
bun run bench:bootstrap-load
bun run bench:highlight-prefetch
bun run bench:large-stream
bun run bench:large-stream-profile
```

Build and smoke-test the prebuilt npm packages for the current host:

```bash
bun run build:prebuilt:npm
bun run check:prebuilt-pack
bun run smoke:prebuilt-install
```

Prepare the multi-platform release directories from downloaded artifacts and dry-run publish order:

```bash
bun run build:prebuilt:artifact
bun run stage:prebuilt:release
bun run check:prebuilt-pack
bun run publish:prebuilt:npm -- --dry-run
```

## Updating dependencies

After changing JavaScript or Bun dependencies, regenerate the Nix dependency lockfile so CI stays green:

```bash
bun install
bun run nix:update-lock
git add bun.lock nix/bun.lock.nix package.json
```

The `nix:update-lock` script requires a one-time [Nix install](https://nixos.org/download/):

```bash
curl -L https://nixos.org/nix/install | sh
```

If you don't have Nix installed, CI will catch the drift and a maintainer can push the regenerated lockfile as a follow-up commit.

## Validation expectations

- Rendering changes: run `bun run typecheck`, `bun test`, `bun run test:tty-smoke`, and do one real TTY smoke run on an actual diff.
- CLI, config, or pager changes: verify the relevant source invocation still works, such as `diff`, `show`, `patch`, or `pager`.
- Packaging or release changes: run the pack and prebuilt checks locally before opening a PR.

## Test layout

- Most unit tests are colocated in `src/` beside the code they cover.
- `test/helpers/` contains shared test-only fixtures used by those unit tests.
- `test/cli/` covers black-box CLI behavior.
- `test/session/` covers daemon, broker, and session-CLI integration flows.
- `test/pty/` covers PTY-backed live UI integration.
- `test/smoke/` contains opt-in transcript-based TTY smoke tests.

See [`test/README.md`](test/README.md) for the intent behind each top-level test category.

## Architecture

```text
CLI input
  -> parse runtime + config-backed view options
  -> normalize into one Changeset / DiffFile model
  -> App shell coordinates state, layout, and review navigation
  -> pane components render review UI
  -> Pierre-backed terminal renderer draws diff rows
```

Key rules:

- Keep the app review-first: the main pane is one top-to-bottom review stream.
- The sidebar is for navigation. Selecting a file should jump within the main stream, not collapse the review to one file.
- Keep split, stack, and auto layouts driven from the same normalized diff model.
- Preserve mouse and keyboard parity for primary actions.
- Keep agent context beside the code it explains.
- Prefer dedicated helper modules and pane components over growing `App` into a monolith.

## Pull requests

- Keep scope tight and explain user-visible behavior changes clearly.
- Update docs and examples when behavior or workflows change.
- If you want temporary local review notes, you can use `.hunk/latest.json`, but do not commit it.
- `hunk diff` includes untracked working-tree files by default. Use `--exclude-untracked` if you want to review tracked changes only.

## Release notes

- The npm package name is `hunkdiff`.
- The installed CLI command remains `hunk`.
- Add a Changeset for user-visible changes instead of editing `CHANGELOG.md` directly:

  ```bash
  bun run changeset
  ```

  Select `hunkdiff`, then choose `patch` for fixes and small behavior changes, `minor` for new user-facing features, or `major` for breaking changes.

- For maintenance-only PRs that should not appear in release notes, add an empty changeset:

  ```bash
  bun run changeset -- --empty
  ```

- Release prep runs `bun run release:version` to consume pending changesets, update `CHANGELOG.md`, and bump package versions.
- The automated prebuilt publish workflow lives in `.github/workflows/release-prebuilt-npm.yml`.