diff options
| author | Paul Buetow <paul@buetow.org> | 2025-09-07 14:29:35 +0300 |
|---|---|---|
| committer | Paul Buetow <paul@buetow.org> | 2025-09-07 14:29:35 +0300 |
| commit | 23482b5d8da5c67da1fc501ddbafdd123be3972c (patch) | |
| tree | 452dc7c418055ebb79a88a303e50d2dbc1877f09 /docs | |
| parent | 76f388f9759cdc15cb1eba985cd87cde1906208b (diff) | |
feat: rename hexai-action -> hexai-tmux-action; remove --tmux/--no-tmux; tmux-only flow; update docs and Magefile
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/configuration.md | 6 | ||||
| -rw-r--r-- | docs/go-unit-tests.md | 27 | ||||
| -rw-r--r-- | docs/source-structure.md | 79 | ||||
| -rw-r--r-- | docs/testing.md | 30 | ||||
| -rw-r--r-- | docs/usage.md | 8 |
5 files changed, 7 insertions, 143 deletions
diff --git a/docs/configuration.md b/docs/configuration.md index dc4adbd..09ff519 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -42,11 +42,11 @@ Hexai Action (TUI) configuration This is mostly useful when Helix runs in a [tmux](https://tmux.github.io/) session! -- Helix integration (recommended): bind a key to pipe the current selection to `hexai-action` and replace it with the output. - - Example: `C-a = ":pipe hexai-action"` +- Helix integration (recommended): bind a key to pipe the current selection to `hexai-tmux-action` and replace it with the output. + - Example: `C-a = ":pipe hexai-tmux-action"` - Default behavior: - Inline TUI when run in a real terminal (TTY). - - When invoked via Helix `:pipe` and a tmux session is available, `hexai-action` opens a split pane to render the menu and returns the result on stdout for Helix to apply. + - When invoked via Helix `:pipe`, `hexai-tmux-action` opens a split pane to render the menu and returns the result on stdout for Helix to apply. - If no TTY and no tmux are available, it falls back to echoing the input. - Flags: - `--infile` Read input from the given file instead of stdin. diff --git a/docs/go-unit-tests.md b/docs/go-unit-tests.md deleted file mode 100644 index 1be9fd0..0000000 --- a/docs/go-unit-tests.md +++ /dev/null @@ -1,27 +0,0 @@ -# Go unit tests via code action - -Hexai can generate Go unit tests for the function at your cursor. - -- Scope: Available only for Go source files ending with `.go` (not `_test.go`). -- Trigger: Use your editor's code actions on the current selection/position and pick "Implement unit test". - -What happens - -- Function detection: Hexai finds the nearest `func` definition above the cursor and captures the function body by balancing braces. -- Test generation: - - If an LLM provider is configured, Hexai asks it to generate one or more `Test*` functions using the `testing` package. The provider must return only the test function code (no package/import lines). - - If no provider is configured or the request fails, Hexai inserts a small stub test `Test<Name>` with a TODO. -- File handling and navigation: - - If `<file>_test.go` exists, the test function is appended to the end of that file. - - If it does not exist, Hexai creates it, writing `package <pkg>` (inferred from the source file) and `import "testing"`, followed by the generated test function(s). - - After applying the edit, Hexai asks the editor to focus the test file and place the cursor at the start of the newly added test function. - -Notes and limitations - -- Imports on append: when appending to an existing test file, Hexai assumes `testing` is available. If not, add `import "testing"` to the test file and re-run `go test`. -- Method names: for methods with receivers, test names default to `TestMethod` (stub fallback). Future improvement may generate `TestType_Method` automatically. -- Formatting: run `go fmt ./...` or your editor's formatter to normalize whitespace if needed. - -Examples - -In Helix, position the cursor inside a function and invoke code actions; choose "Implement unit test". Hexai will create or update `<file>_test.go` accordingly. diff --git a/docs/source-structure.md b/docs/source-structure.md deleted file mode 100644 index 0c7f56f..0000000 --- a/docs/source-structure.md +++ /dev/null @@ -1,79 +0,0 @@ -# Source code structure - -This document provides a high‑level map of the Hexai source layout and how the -main packages relate to each other. - -## Diagram - -```mermaid -graph TD - %% Entrypoints - A[cmd/hexai\nCLI entrypoint] --> B[internal/hexaicli\nCLI runner] - C[cmd/hexai-lsp\nLSP entrypoint] --> D[internal/hexailsp\nLSP runner] - - %% Shared/internal packages - subgraph internal/ - I[appconfig\nLoad config from file/env] - L[llm\nClient + providers] - G[logging\nBound logger + helpers] - S[lsp\nJSON-RPC, server, handlers] - end - - %% Relationships - B --> I - B --> L - B --> G - - D --> I - D --> L - D --> G - D --> S - - S --> L - S --> G - - %% LLM providers - subgraph internal/llm - P1[openai.go] - P2[ollama.go] - P3[copilot.go] - end - L --> P1 - L --> P2 - L --> P3 - - %% Version info - V[internal/version.go\nVersion string] --> A - V --> C -``` - -## Module overview - -- cmd/hexai: CLI binary that parses flags, prints version via `internal.Version`, - and delegates to `internal/hexaicli.Run`. -- cmd/hexai-lsp: LSP server binary that parses flags, prints version, and calls - `internal/hexailsp.Run` (stdio JSON‑RPC server). -- internal/hexaicli: CLI flow — reads stdin/args, loads config, builds an LLM - client, constructs messages, and runs a single chat request (streaming when - supported). -- internal/hexailsp: LSP orchestration — binds logging, loads config, builds the - LLM client, constructs `internal/lsp.ServerOptions`, and runs the server. -- internal/lsp: Minimal LSP over stdio — document store, JSON‑RPC handlers - (initialize, completion, code action, etc.), context building, and a small - completion cache. -- internal/llm: Provider‑agnostic client interface plus concrete providers for - OpenAI, GitHub Copilot, and Ollama, including streaming support where - available. -- internal/appconfig: Loads user configuration from file and environment, shared - by both CLI and LSP paths. -- internal/logging: Central logger binding and small helpers for consistent, - readable logs and chat summaries. -- internal/version.go: Single place for the version string used by both - binaries. - -## Typical flows - -- CLI: `cmd/hexai` → `internal/hexaicli` → `internal/appconfig` → `internal/llm` - (providers) → print output and a short summary line. -- LSP: `cmd/hexai-lsp` → `internal/hexailsp` → `internal/lsp.Server` → - request handlers → `internal/llm` for completions/actions. diff --git a/docs/testing.md b/docs/testing.md deleted file mode 100644 index 86d88b1..0000000 --- a/docs/testing.md +++ /dev/null @@ -1,30 +0,0 @@ -# Testing Guide - -This repository includes a growing test suite designed to be realistic and robust. - -Key patterns: - -- Table‑driven tests: consolidate repetitive scenarios into concise tables (see `internal/lsp/*_table_test.go`). -- Shared fixtures: use `internal/testutil/fixtures.go` for multi‑line docblocks, chat replies, function suggestions, and markdown fences. -- Provider mocks: use `httptest.Server` and/or custom `http.RoundTripper` to simulate OpenAI/Copilot/Ollama responses, including success, stream (SSE), and error cases. -- E2E LSP tests: capture JSON‑RPC frames from the in‑memory server (`captureResponse`, `captureRequest`) and validate code actions, resolves, and chat edits. - -Suggested additions: - -- Expand table‑driven coverage for completion edit computations and label/filter selection. -- Add more negative tests (malformed SSE/JSON payloads) to assert robust error handling. - -## Running Tests - -- Full suite with coverage: - - `HEXAI_TEST_SKIP_NET=1 go test ./... -cover` - - The `HEXAI_TEST_SKIP_NET=1` env var disables any tests that require network access, keeping runs deterministic in CI/sandboxes. - -- Package-specific runs: - - `HEXAI_TEST_SKIP_NET=1 go test ./internal/hexaiaction -cover` - - `HEXAI_TEST_SKIP_NET=1 go test ./internal/hexaiaction -cover` - -Notes - -- Some environments restrict writes to the Go build cache; if you see cache permission errors, re-run in a less-restricted shell or allow the command to write to the cache. -- Always format Go code before committing: `gofumpt -w .` diff --git a/docs/usage.md b/docs/usage.md index 05d6c55..fb65596 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -105,7 +105,7 @@ hexai 'install ripgrep on macOS and explain' ## Hexai Action (TUI) -`hexai-action` runs code actions over a selection or diagnostics+selection piped from stdin, or read from a file. +`hexai-tmux-action` runs code actions over a selection or diagnostics+selection piped from stdin, or read from a file. - Choose an action with arrow keys, `j/k`, `g/G`, Enter, or hotkeys `[s] [r] [c] [t]`. - Output is written to stdout by default, or to a file via `--outfile`. @@ -122,11 +122,11 @@ Examples ```sh # From stdin -cat input.go | hexai-action +cat input.go | hexai-tmux-action # From file to file -hexai-action --infile input.go --outfile output.go +hexai-tmux-action --infile input.go --outfile output.go # Using shell redirection -hexai-action < input.go > output.go +hexai-tmux-action < input.go > output.go ``` |
