Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 15 additions & 9 deletions .agents/skills/nvim-headless/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Everything data-level:
- `vim.uv` timers under `vim.wait`
- keymaps via `feedkeys` with `"x"` (execute immediately) flag
- treesitter parsers and queries
- git operations via `tests/helpers` (`create_temp_git_repo`, `git_cmd`)
- git operations via `require("tests.support")` (`create_temp_git_repo`, `git_cmd`)

## What needs a workaround

Expand All @@ -42,13 +42,18 @@ vim.api.nvim_exec_autocmds("WinScrolled", {})

This is what existing specs already do.

## What is not possible
## What requires a separate UI

- **Rendered screen content** (which character is at row/col, its color).
Neovim's own test suite solves this by spawning a child `nvim --embed` and
attaching a fake UI over RPC — a different architecture from ours.
- **`UIEnter`** never fires. Plugins that lazy-load on `UIEnter` (e.g.
`snacks.nvim`) must be initialized manually with `.enable()` or equivalent.
- **Rendered screen content** (which character is at row/col, its color) is not
observable in the synchronous headless test process. Use
`tests/framework/screen.lua`, which starts `nvim --embed` and attaches an RPC
UI. Close it in `after_each`, even on assertion failure.
- **`UIEnter`** does not fire without an attached UI. Plugins that lazy-load on
it (e.g. `snacks.nvim`) need explicit initialization in a plain headless spec.

The observation tool does not define the test level. Screen checks that call
renderers directly are integration tests; public commands or actual key input
through the complete application belong in `tests/e2e/`.

## Driving styles

Expand Down Expand Up @@ -94,8 +99,9 @@ vim.defer_fn(resume, 100)
| What | Where |
|---|---|
| Test bootstrap | `tests/init.lua` |
| Helpers (git repos, waiters) | `tests/helpers.lua` |
| Helpers (git repos, waiters) | `tests/support/init.lua` (`require("tests.support")`) |
| Framework (describe/it/assert) | `tests/framework/init.lua` |
| Run all specs | `./tests/run_tests.sh` or `make test-lua` |
| Run one spec | `nvim --headless --noplugin -u tests/init.lua -c "lua require('tests.framework').run_and_exit('tests/path/to_spec.lua')"` |
| Run one layer | `./tests/run_tests.sh unit` / `integration` / `e2e` |
| Run one spec | `./tests/run_tests.sh tests/unit/core/path_spec.lua` |
| Throwaway repro | Save to `/tmp/repro.lua`, run with `nvim --headless -u tests/init.lua -c "luafile /tmp/repro.lua" -c "qa!"` |
7 changes: 5 additions & 2 deletions .github/instructions/tests.instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ applyTo: "tests/**"
When working with tests in this directory:

- **Headless boundaries**: Read `.agents/skills/nvim-headless/SKILL.md` before writing specs that involve scroll events, timers, or window geometry
- **Extend existing tests**: Add new test cases to existing test files whenever possible; only create new test files when covering genuinely distinct functionality
- **Test runner**: Spec files are auto-discovered by `tests/framework/supervisor.lua`; a new `*_spec.lua` under `tests/` runs in CI with no runner changes
- **Test levels**: Put runnable specs under `tests/unit/`, `tests/integration/`, or `tests/e2e/`, then group by feature. Isolated logic belongs in unit; direct component calls and Neovim/Git/FFI boundaries belong in integration; public commands or real user input through the whole application belong in E2E. Using Git or an embedded screen alone does not make a component test E2E.
- **Names and shared code**: Use behavior-based `*_spec.lua` names, without redundant `_e2e`/`_integration` suffixes. Keep issue references inside cases. Shared drivers and the Git factory belong in `tests/support/`, data in `tests/fixtures/`, and the runner/RPC transport in `tests/framework/`. Infrastructure self-tests also belong in a test layer.
- **Extend existing tests**: Add new test cases to existing test files whenever possible; only create new test files when covering genuinely distinct functionality.
- **Fixtures and imports**: Use the shared repository factory rather than the source checkout's Git history. Import helpers through `require("tests.support")` and its submodules, not cwd-relative `dofile` or old-path adapters. Use `support.project_root` rather than counting a spec's parent directories.
- **Test runner**: Specs are auto-discovered by `tests/framework/supervisor.lua` with no CI enumeration changes. `tests/run_tests.sh` and `.cmd` accept `all`, `unit`, `integration`, `e2e`, a directory, or a single spec. Discovery self-tests enforce the directory boundary.
- **No legacy API in tests**: When fixing tests, always update them to use the latest API; never add backward compatibility or reintroduce removed APIs for test compatibility—tests must use current production APIs
7 changes: 7 additions & 0 deletions .github/workflows/_platform-windows.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ jobs:
build:
name: ${{ inputs.artifact }}
runs-on: ${{ inputs.runs-on }}
timeout-minutes: 30
steps:
- name: Checkout repository
uses: actions/checkout@v5
Expand Down Expand Up @@ -60,6 +61,12 @@ jobs:

- name: Run Neovim tests
shell: bash
env:
# E2E specs create up to 120 isolated Git/Neovim instances. Avoid
# oversubscribing process startup and give the whole spec a budget;
# individual async assertions retain their bounded timeouts.
CODEDIFF_TEST_JOBS: '4'
CODEDIFF_TEST_TIMEOUT: '900000'
run: ./tests/run_tests.sh

- name: Upload build artifacts
Expand Down
8 changes: 4 additions & 4 deletions .github/workflows/standalone-build-test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -79,14 +79,14 @@ jobs:
- name: Setup Neovim
uses: ./.github/actions/setup-neovim

- name: Run integration test (Ubuntu/macOS)
- name: Run command smoke E2E (Ubuntu/macOS)
if: matrix.os != 'windows-latest'
run: |
nvim --headless --noplugin -u tests/init.lua \
-c "lua require('tests.framework').run_and_exit('tests/full_integration_spec.lua')"
-c "lua require('tests.framework').run_and_exit('tests/e2e/commands/smoke_spec.lua')"

- name: Run integration test (Windows)
- name: Run command smoke E2E (Windows)
if: matrix.os == 'windows-latest'
shell: pwsh
run: |
nvim --headless --noplugin -u tests/init.lua -c "lua require('tests.framework').run_and_exit('tests/full_integration_spec.lua')"
nvim --headless --noplugin -u tests/init.lua -c "lua require('tests.framework').run_and_exit('tests/e2e/commands/smoke_spec.lua')"
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -683,13 +683,14 @@ cmake --build build --config Release
ctest --test-dir build --output-on-failure -C Release
```

Run the Lua integration suite:
Run the Lua test suite or select a test layer:

```bash
./tests/run_tests.sh
./tests/run_tests.sh # all tests
./tests/run_tests.sh e2e # or: unit, integration
```

On Windows, use `tests\run_tests.cmd`.
On Windows, use `tests\run_tests.cmd` with the same arguments. See [tests/README.md](tests/README.md) for test organization and fixtures.

Check Lua formatting:

Expand All @@ -700,8 +701,7 @@ stylua --check lua
Run one Lua spec:

```bash
nvim --headless --noplugin -u tests/init.lua \
-c "lua require('tests.framework').run_and_exit('tests/path/to/spec.lua')"
./tests/run_tests.sh tests/unit/core/path_spec.lua
```

## Contributing
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -62,5 +62,5 @@ not be passed to tools or language servers that only accept `file://` URIs.
- `lua/codediff/core/virtual_file.lua` — URI parsing, loading, and Tree-sitter setup
- `lua/codediff/ui/view/render.lua` — side-by-side rendering after load
- `lua/codediff/ui/inline_view/render.lua` — inline rendering after load
- `tests/core/virtual_file_lsp_spec.lua` — regression coverage ensuring virtual
- `tests/integration/core/virtual_file_spec.lua` — regression coverage ensuring virtual
buffers do not trigger LSP attachment
39 changes: 36 additions & 3 deletions docs/development/05-architecture/auto-refresh-strategy.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,39 @@
# VSCode Diff Highlighting Refresh Strategy - Investigation Report

## Overview
# Refresh Strategy

## Session-data refactor (#558)

Repository watching, polling, invalidation coalescing and stale-result checks now
belong to `lua/codediff/ui/refresh/init.lua`. Explorer, History and diff views
consume data changes rather than managing independent refresh loops.

- `session.panel.data` owns list data, query parameters and the selected file.
Panel views hold a reference to that data and receive `on_data(data, changes)`
notifications. They retain tree expansion, cursor and layout state locally.
- `refresh/panel.lua` reads status, commit lists and commit files, and derives
comparison definitions from selections. User selection goes through
`refresh.select`; a list update never asks the view to reselect an unchanged
comparison.
- `refresh/inputs.lua` reads the session's explicit input definitions, waits for
every candidate and validates working-buffer ticks. It does not inspect panels.
- The controller publishes only actual input changes to `view/render.lua`.
Initial rendering and in-place updates share diff rendering; merge input and
Result rendering remain in `conflict/view/`. Working and Result buffers stay
authoritative for user edits.

Removed the `auto_refresh` entry point, Explorer scheduler and per-panel refresh
modules. The former `refresh/apply.lua` responsibilities now live in the existing
view helpers and renderers; there is no separate refresh rendering pipeline.
Watcher categories remain intact, with a 500 ms polling fallback. Poll ticks
sample only when no selection, read or invalidation is pending; slow Git reads
must finish rather than accumulate an endless polling backlog. Actual repository
invalidations are still queued while a read is running. Unchanged inputs do not
disturb the comparison, and changed merge inputs cannot overwrite an edited Result.

Regression coverage includes native watcher and polling screen-grid E2Es, data
ownership, presentation-only list updates, navigation, hunk actions and stale
callbacks. The investigation below records the earlier VSCode design reference.

## Earlier investigation: VSCode Quick Diff
VSCode uses a sophisticated system called "Quick Diff" (also known as "Dirty Diff") to display real-time diff decorations in the gutter and overview ruler. The implementation is found primarily in two files:
- `quickDiffModel.ts` - Manages diff computation and change tracking
- `quickDiffDecorator.ts` - Handles visual decorations in the editor
Expand Down
210 changes: 105 additions & 105 deletions docs/development/05-architecture/timeout-mechanism.md
Original file line number Diff line number Diff line change
@@ -1,105 +1,105 @@
# Timeout Mechanism - Fixed & Tested
## The Bug
Character-level Myers was hardcoded to timeout=0 (infinite) instead of using the configured timeout.
```c
// BEFORE (Bug):
myers_nd_diff_algorithm(seq1_iface, seq2_iface, 0, &hit_timeout); // ✗ Hardcoded!
// AFTER (Fixed):
myers_nd_diff_algorithm(seq1_iface, seq2_iface, options->timeout_ms, &hit_timeout); // ✓
```
## The Fix
The timeout infrastructure **already existed** in Myers from day one. We just completed the wiring:
1. Added `timeout_ms` to `CharLevelOptions` struct
2. Passed timeout through `refine_diff()` → `char_opts.timeout_ms = timeout->timeout_ms`
3. Used it in char_level.c instead of hardcoded 0
4. Removed misleading comment: `// timeout handled inside refine_diff_char_level`
**This was incomplete plumbing, not a missing feature.**
## Timeout Flow (End-to-End)
```
Lua Config (5000ms)
↓
lua/vscode-diff/config.lua: config.options.diff.max_computation_time_ms
↓
lua/vscode-diff/commands.lua: diff.compute_diff(..., { max_computation_time_ms = 5000 })
↓
lua/vscode-diff/diff.lua: c_options.max_computation_time_ms = 5000
↓
libvscode-diff/api.c: compute_diff(options->max_computation_time_ms)
↓
default_lines_diff_computer.c: timeout.timeout_ms = options->max_computation_time_ms
↓
Line-level Myers: myers_nd_diff_algorithm(..., timeout_ms, ...) ✓
↓
Char-level Myers: myers_nd_diff_algorithm(..., options->timeout_ms, ...) ✓ FIXED!
```
## VSCode Parity: 100% ✓
| Aspect | VSCode | Before Fix | After Fix |
|--------|--------|------------|-----------|
| Timeout in Myers signature | ✓ | ✓ | ✓ |
| Line-level uses timeout | ✓ | ✓ | ✓ |
| Char-level uses timeout | ✓ | ✗ (0) | ✓ |
| Default: 5000ms | ✓ | ✓ | ✓ |
| Early exit on timeout | ✓ | Line only | Both ✓ |
| Trivial diff fallback | ✓ | Line only | Both ✓ |
## Performance Impact
Test file (1150 → 2352 lines):
| Timeout | Time | Hit? | Detail |
|---------|------|------|--------|
| 5000ms | 1221ms | No | Full (1188 inner changes) |
| 50ms | 139ms | Yes | Partial (61 regions, 1 inner each) |
| 10ms | 26ms | Yes | Trivial (1 region, 1 inner) |
## User Configuration
```lua
require("vscode-diff").setup({
diff = {
max_computation_time_ms = 5000, -- Default (VSCode parity)
-- Lower = faster but less detail on large files
-- Higher = more accurate but slower on complex diffs
}
})
```
## Tests: 13/13 Passing ✓
**Location**: `tests/timeout_spec.lua`
Coverage:
- Basic functionality (3): parameter acceptance, completion, defaults
- Large files (3): normal/short/very-short timeouts
- Config integration (2): respects config, VSCode default
- VSCode parity (2): line+char Myers, structure consistency
- Edge cases (3): zero/negative timeout, empty files
Run: `nvim --headless -u tests/init.lua -c "lua require('tests.framework').run_and_exit('tests/timeout_spec.lua')"`
## Files Modified
1. `libvscode-diff/include/char_level.h` - Added timeout_ms field
2. `libvscode-diff/src/char_level.c` - Use timeout instead of 0
3. `libvscode-diff/default_lines_diff_computer.c` - Thread timeout through
4. `libvscode-diff/diff_tool.c` - Test env var support
5. `lua/vscode-diff/config.lua` - Added config option
6. `lua/vscode-diff/auto_refresh.lua` - Pass timeout from config
7. `lua/vscode-diff/commands.lua` - Pass timeout from config (2 places)
8. `tests/timeout_spec.lua` - Comprehensive test suite
9. `tests/run_tests.sh` - Added to test runner
---
**Date**: 2025-01-07
**Status**: ✅ Complete - Bug fixed, tests passing, VSCode parity achieved
# Timeout Mechanism - Fixed & Tested

## The Bug
Character-level Myers was hardcoded to timeout=0 (infinite) instead of using the configured timeout.

```c
// BEFORE (Bug):
myers_nd_diff_algorithm(seq1_iface, seq2_iface, 0, &hit_timeout); // ✗ Hardcoded!

// AFTER (Fixed):
myers_nd_diff_algorithm(seq1_iface, seq2_iface, options->timeout_ms, &hit_timeout); // ✓
```

## The Fix
The timeout infrastructure **already existed** in Myers from day one. We just completed the wiring:

1. Added `timeout_ms` to `CharLevelOptions` struct
2. Passed timeout through `refine_diff()` → `char_opts.timeout_ms = timeout->timeout_ms`
3. Used it in char_level.c instead of hardcoded 0
4. Removed misleading comment: `// timeout handled inside refine_diff_char_level`

**This was incomplete plumbing, not a missing feature.**

## Timeout Flow (End-to-End)

```
Lua Config (5000ms)
↓
lua/vscode-diff/config.lua: config.options.diff.max_computation_time_ms
↓
lua/vscode-diff/commands.lua: diff.compute_diff(..., { max_computation_time_ms = 5000 })
↓
lua/vscode-diff/diff.lua: c_options.max_computation_time_ms = 5000
↓
libvscode-diff/api.c: compute_diff(options->max_computation_time_ms)
↓
default_lines_diff_computer.c: timeout.timeout_ms = options->max_computation_time_ms
↓
Line-level Myers: myers_nd_diff_algorithm(..., timeout_ms, ...) ✓
↓
Char-level Myers: myers_nd_diff_algorithm(..., options->timeout_ms, ...) ✓ FIXED!
```

## VSCode Parity: 100% ✓

| Aspect | VSCode | Before Fix | After Fix |
|--------|--------|------------|-----------|
| Timeout in Myers signature | ✓ | ✓ | ✓ |
| Line-level uses timeout | ✓ | ✓ | ✓ |
| Char-level uses timeout | ✓ | ✗ (0) | ✓ |
| Default: 5000ms | ✓ | ✓ | ✓ |
| Early exit on timeout | ✓ | Line only | Both ✓ |
| Trivial diff fallback | ✓ | Line only | Both ✓ |

## Performance Impact

Test file (1150 → 2352 lines):

| Timeout | Time | Hit? | Detail |
|---------|------|------|--------|
| 5000ms | 1221ms | No | Full (1188 inner changes) |
| 50ms | 139ms | Yes | Partial (61 regions, 1 inner each) |
| 10ms | 26ms | Yes | Trivial (1 region, 1 inner) |

## User Configuration

```lua
require("vscode-diff").setup({
diff = {
max_computation_time_ms = 5000, -- Default (VSCode parity)
-- Lower = faster but less detail on large files
-- Higher = more accurate but slower on complex diffs
}
})
```

## Tests: 13/13 Passing ✓

**Current location**: `tests/integration/core/diff/timeout_spec.lua`

Coverage:
- Basic functionality (3): parameter acceptance, completion, defaults
- Large files (3): normal/short/very-short timeouts
- Config integration (2): respects config, VSCode default
- VSCode parity (2): line+char Myers, structure consistency
- Edge cases (3): zero/negative timeout, empty files

Run: `./tests/run_tests.sh tests/integration/core/diff/timeout_spec.lua`

## Files Modified

1. `libvscode-diff/include/char_level.h` - Added timeout_ms field
2. `libvscode-diff/src/char_level.c` - Use timeout instead of 0
3. `libvscode-diff/default_lines_diff_computer.c` - Thread timeout through
4. `libvscode-diff/diff_tool.c` - Test env var support
5. `lua/vscode-diff/config.lua` - Added config option
6. `lua/vscode-diff/auto_refresh.lua` - Pass timeout from config
7. `lua/vscode-diff/commands.lua` - Pass timeout from config (2 places)
8. `tests/integration/core/diff/timeout_spec.lua` - Comprehensive test suite (current path)
9. `tests/run_tests.sh` - Added to test runner

---

**Date**: 2025-01-07
**Status**: ✅ Complete - Bug fixed, tests passing, VSCode parity achieved
1 change: 1 addition & 0 deletions lua/codediff/commands/handlers/explorer.lua
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ function M.run(revision, revision2, global_opts, pathspec)
status_result = status_result,
focus_file = focus_file, -- Focus on current file if changed
pathspec = pathspec, -- Scope (#74): preserved so refresh re-applies it
source_revisions = revision and { original = revision, modified = revision2 or "WORKING" } or nil,
},
},
git_root = git_root,
Expand Down
Loading
Loading