neovim-dots/.opencode/astronvim-v6-neovim-0-12-treesitter-migration-atomic-git-plan.md

# Task: AstroNvim v6 migration for Neovim 0.12 Tree-sitter compatibility with atomic git operations

## Objective

Migrate the user's modified AstroNvim v5-based Neovim dotfiles to an AstroNvim v6-compatible configuration while preserving the user's commits and avoiding destructive changes to `main` until the migration branch is reviewed and accepted.

Primary bug to fix:

```text
Decoration provider "start" (ns=nvim.treesitter.highlighter):
Lua: /usr/share/nvim/runtime/lua/vim/treesitter/languagetree.lua:215:
/usr/share/nvim/runtime/lua/vim/treesitter.lua:196:
attempt to call method 'range' (a nil value)
```

Root cause established by research/audit:

- User is on Neovim 0.12.
- AstroNvim v5 pins/uses old `nvim-treesitter` `master`/old snapshot behavior.
- `nvim-treesitter` `master` is not compatible with Neovim 0.12.
- AstroNvim v6 is the supported AstroNvim line for Neovim 0.12 Tree-sitter/LSP API changes.
- The migration must not be just `version = "^6"`; Tree-sitter config must move to AstroCore v6 style, and lockfile/runtime state must be refreshed through Lazy.

## Repository/context facts

- Working repo: `/home/kbot/.config/nvim`
- This is the user's personal dotfiles repo, not AstroNvim itself.
- Current branch during audit: `main`
- Remote during audit: `https://git.cyber.ayyalasomayajula.net/marsultor/neovim-dots.git`
- AstroNvim itself is a Lazy-managed plugin checkout under:

```text
/home/kbot/.local/share/nvim/lazy/AstroNvim
```

- Do not edit or commit files inside Lazy plugin checkouts:

```text
~/.local/share/nvim/lazy/AstroNvim
~/.local/share/nvim/lazy/nvim-treesitter
```

- Current active imports:

```lua
-- lua/lazy_setup.lua
{ import = "community" },
{ import = "plugins" },
```

- `lua/community.lua` is disabled with `if true then return {} end`, but this does not block active AstroCommunity usage because `lua/plugins/astrocommunity.lua` is imported through `plugins`.

- Active AstroCommunity imports:

```lua
-- lua/plugins/astrocommunity.lua
astrocommunity.colorscheme.oxocarbon-nvim
astrocommunity.git.neogit
astrocommunity.git.diffview-nvim
astrocommunity.markdown-and-latex.vimtex
```

- These modules exist on current AstroCommunity. Watch item: the `vimtex` module may still touch `nvim-treesitter` to disable LaTeX highlighting; test after migration.

## Key constraints and best practices

1. Use atomic git operations.
2. Use a dedicated migration branch, not `main`.
3. The user will merge back to `main` manually when satisfied.
4. Preserve current WIP before rewriting it.
5. Do not merge AstroNvim upstream git history into the dotfiles repo.
6. Consume AstroNvim updates through Lazy/AstroNvim plugin specs and `lazy-lock.json`.
7. Do not hand-edit Lazy plugin checkouts.
8. Avoid committing a confusing lockfile state where `nvim-treesitter` says `branch = "main"` but still points to old commit `42fc28ba...`.
9. Prefer source migration commits before lockfile refresh commit.
10. Run tests/health checks before recommending merge.

## Branch strategy

Use this branch:

```bash
migrate/astronvim-v6-nvim-0.12
```

All implementation work should happen on that branch.

The user explicitly requested:

> use a different branch. check that branch out. when we like it i'll merge and go back to main

So the orchestrator/build agent should check out this branch and leave the repo on this branch for testing. Do not switch back to `main` unless asked.

## Current WIP to preserve

At audit time, uncommitted files included:

```text
lazy-lock.json
lua/plugins/treesitter.lua
```

`lua/plugins/treesitter.lua` had been changed from disabled to active and made a direct `nvim-treesitter` spec with:

```lua
branch = "main",
build = ":TSUpdate",
ensure_installed = { "lua", "markdown", "markdown_inline", "vim" }
```

This is not the desired final v6 config, but it should be checkpointed before further changes.

`lazy-lock.json` had unrelated plugin updates and a weird Tree-sitter state:

- `nvim-treesitter` branch changed to `main`
- old commit remained around `42fc28ba...`
- unrelated plugin pins also changed, including some of:
  - `astrocommunity`
  - `milli.nvim`
  - `neo-tree.nvim`
  - `neogit`
  - `vimtex`

The first atomic operation should checkpoint or otherwise preserve this current state intentionally.

## Phased implementation plan

### Phase 1: Inspect and create migration branch

Run diagnostic status first:

```bash
cd /home/kbot/.config/nvim
git status --short --branch
git log --oneline --decorate -8
```

Then create and check out the migration branch:

```bash
git switch -c migrate/astronvim-v6-nvim-0.12
```

If the branch already exists, do not overwrite it blindly. Inspect:

```bash
git branch --list migrate/astronvim-v6-nvim-0.12
git status --short --branch
```

If it exists, ask the user whether to reuse, reset, or create a suffixed branch such as:

```text
migrate/astronvim-v6-nvim-0.12-2
```

Expected output: repo is now on the migration branch.

### Phase 2: Atomic checkpoint commit of current WIP

If working tree is dirty, preserve it exactly:

```bash
git add -A
git commit -m "checkpoint: preserve pre AstroNvim v6 migration state"
```

If working tree is clean, skip this commit and note that no checkpoint commit was needed.

Expected output: current WIP is preserved on the migration branch before any migration edits.

### Phase 3: Migrate AstroNvim version constraint

Affected file:

```text
lua/lazy_setup.lua
```

Current audited state:

```lua
{
  "AstroNvim/AstroNvim",
  version = "^5",
  import = "astronvim.plugins",
  opts = {
    pin_plugins = nil,
  },
}
```

Required change:

```lua
version = "^6"
```

Keep:

```lua
pin_plugins = nil
```

Reasoning:

- AstroNvim v6 is the official compatibility path for Neovim 0.12.
- `pin_plugins = nil` lets AstroNvim decide based on versioned release behavior.
- Do not remove version tracking unless the user wants nightly AstroNvim.

Commit:

```bash
git add lua/lazy_setup.lua
git commit -m "chore: migrate AstroNvim constraint to v6"
```

### Phase 4: Migrate Tree-sitter config to AstroCore v6 style

Affected file:

```text
lua/plugins/treesitter.lua
```

Do not keep old v5/direct `nvim-treesitter` feature config such as:

```lua
return {
  "nvim-treesitter/nvim-treesitter",
  branch = "main",
  build = ":TSUpdate",
  opts = {
    ensure_installed = { ... },
  },
}
```

AstroNvim v6 treats `nvim-treesitter` primarily as a parser download utility. Tree-sitter features should be configured via `AstroNvim/astrocore` under `opts.treesitter`.

Target config:

```lua
-- Customize Treesitter through AstroCore for AstroNvim v6

---@type LazySpec
return {
  {
    "AstroNvim/astrocore",
    ---@type AstroCoreOpts
    opts = {
      treesitter = {
        ensure_installed = {
          "lua",
          "vim",
          "vimdoc",
          "markdown",
          "markdown_inline",
        },
        highlight = true,
        indent = true,
      },
    },
  },
}
```

Notes:

- AstroNvim v6 defaults already include many parsers such as `bash`, `c`, `lua`, `markdown`, `markdown_inline`, `python`, `query`, `vim`, `vimdoc`.
- The explicit list above is acceptable and focused on the user's known needs.
- Do not configure `highlight = { enable = true }`; v6 AstroCore uses `highlight = true`.
- Do not use old `nvim-treesitter.configs` options.

Commit:

```bash
git add lua/plugins/treesitter.lua
git commit -m "refactor: migrate treesitter config to AstroCore"
```

### Phase 5: Audit plugin rename/removal references

Search active config for renamed plugin repository names:

```bash
rg 'Saghen/blink\.cmp|echasnovski/mini\.icons|echanovski/mini\.icons|williamboman/mason\.nvim|williamboman/mason-lspconfig\.nvim' lua
```

If found, replace:

```text
Saghen/blink.cmp                  -> saghen/blink.cmp
echasnovski/mini.icons            -> nvim-mini/mini.icons
williamboman/mason.nvim           -> mason-org/mason.nvim
williamboman/mason-lspconfig.nvim -> mason-org/mason-lspconfig.nvim
```

Search active config for removed plugin references:

```bash
rg 'JoosepAlviste/nvim-ts-context-commentstring|folke/neoconf\.nvim|kevinhwang91/nvim-ufo|RRethy/vim-illuminate' lua
```

If active source references are found, remove/migrate them.

Audit result from planning phase:

- No active source references were found for renamed plugin repo names.
- No active source references were found for removed plugins.
- `lazy-lock.json` may still contain stale entries for old defaults like `neoconf.nvim` and `vim-illuminate`; this should be handled by Lazy sync/lock refresh, not manual source edits.

Commit only if source edits were needed:

```bash
git add lua/
git commit -m "chore: update plugin references for AstroNvim v6"
```

If no source edits were needed, skip this commit.

### Phase 6: Audit AstroLSP config

Affected file if needed:

```text
lua/plugins/astrolsp.lua
```

Planning audit found no active v6-breaking patterns:

- no root-level `capabilities`
- no root-level `flags`
- no active `require("lspconfig")`
- no active `require("astrolsp").lsp_opts`
- `handlers` table exists but is empty

Still, confirm with searches:

```bash
rg 'capabilities\s*=|flags\s*=|require\(["'"']lspconfig["'"']\)|lsp_opts|handlers\s*=\s*\{' lua/plugins/astrolsp.lua
```

If root-level `capabilities` or `flags` are found, migrate to:

```lua
config = {
  ["*"] = {
    capabilities = ...,
    flags = ...,
  },
}
```

If old anonymous default handler is found:

```lua
handlers = {
  function(server, opts)
    require("lspconfig")[server].setup(opts)
  end,
}
```

migrate to v6-style:

```lua
handlers = {
  ["*"] = function(server)
    vim.lsp.enable(server)
  end,
}
```

Commit only if source edits are actually needed:

```bash
git add lua/plugins/astrolsp.lua
git commit -m "refactor: migrate AstroLSP config for v6 APIs"
```

### Phase 7: Review Mason config and `tree-sitter-cli`

Affected file:

```text
lua/plugins/mason.lua
```

Planning audit found:

```lua
"tree-sitter-cli"
```

Research notes:

- New `nvim-treesitter` main expects modern Tree-sitter tooling.
- Keeping `tree-sitter-cli` installed through Mason is probably fine.
- Do not remove it unless v6 health checks indicate it is wrong/outdated.

Action:

- Inspect only.
- No commit expected.

### Phase 8: Run Lazy sync/update on the migration branch

Important: do not manually edit plugin checkouts.

Run from the migration branch. Prefer interactive Neovim first if possible:

```bash
nvim
```

Then inside Neovim:

```vim
:Lazy sync
:TSUpdate
:checkhealth nvim-treesitter
:checkhealth vim.lsp
```

Alternative headless commands if appropriate:

```bash
nvim --headless "+Lazy! sync" +qa
nvim --headless "+TSUpdate" +qa
```

Caveat:

- If headless Lazy sync exits nonzero due to plugin changes needing restart, report output and continue with manual/interactive flow.
- Do not run `:Lazy restore` while the lockfile still has old v5 pins unless intentionally rolling back.

Expected result:

- AstroNvim moves to v6-compatible commit.
- `nvim-treesitter` moves away from old commit `42fc28ba...`.
- `nvim-treesitter` should be on the v6-compatible `main` branch/snapshot.
- Lazy regenerates `lazy-lock.json`.

### Phase 9: Commit regenerated lockfile atomically

Inspect lockfile diff:

```bash
git diff -- lazy-lock.json
git status --short
```

Verify `nvim-treesitter` is no longer old `42fc28ba...`.

Useful checks:

```bash
rg '"nvim-treesitter"|"AstroNvim"|"astrocore"|"astrolsp"|"nvim-treesitter-textobjects"|"nvim-ts-autotag"' lazy-lock.json
```

Commit lockfile and only generated plugin-lock changes:

```bash
git add lazy-lock.json
git commit -m "chore: refresh lazy lockfile for AstroNvim v6"
```

If Lazy sync also changes source files unexpectedly, inspect carefully before staging. Do not blindly include unrelated source changes in the lockfile commit.

### Phase 10: Verification

Run startup check:

```bash
nvim --headless +'lua print("startup ok")' +qa
```

Run Tree-sitter health:

```bash
nvim --headless '+checkhealth nvim-treesitter' +qa
```

Manual markdown crash reproduction test:

Create or open a markdown file containing fenced code blocks:

````markdown
# Tree-sitter crash test

```lua
print("hello")
```

```bash
echo hello
```
````

Open it with the migrated config:

```bash
nvim /tmp/treesitter-crash-test.md
```

Confirm:

- no `range()` nil crash
- highlighting starts without decoration-provider error
- `:checkhealth nvim-treesitter` is acceptable
- `:Lazy show nvim-treesitter` shows a new compatible commit, not `42fc28ba...`

Also run:

```vim
:checkhealth vim.lsp
```

because AstroNvim v6 uses newer LSP APIs.

### Phase 11: Optional follow-up fixes

Only create these commits if testing reveals real issues.

Possible commit:

```bash
git commit -m "fix: adjust AstroCommunity vimtex treesitter integration"
```

Use if `astrocommunity.markdown-and-latex.vimtex` causes Tree-sitter option issues under v6.

Possible commit:

```bash
git commit -m "fix: resolve AstroNvim v6 startup warnings"
```

Use for any startup warnings caused by changed APIs.

Possible commit:

```bash
git commit -m "chore: clean stale v5 plugin locks"
```

Use only if stale lockfile entries remain after `:Lazy sync` and are confirmed unused.

## Final state before user merge

Before handing back to the user, provide:

```bash
git status --short --branch
git log --oneline --decorate -8
git diff main...HEAD --stat
```

Expected:

- branch is `migrate/astronvim-v6-nvim-0.12`
- working tree clean
- commits are atomic and understandable
- startup and Tree-sitter tests pass

The user will merge manually when satisfied:

```bash
git switch main
git merge --ff-only migrate/astronvim-v6-nvim-0.12
```

If non-fast-forward is needed, user should inspect first. Do not force merge.

## Rollback plan

If migration branch fails:

```bash
git switch main
```

Since migration work is isolated to the branch, `main` remains available.

If runtime/plugin state was changed and user needs old v5 runtime back, options:

1. Use `:Lazy restore` from the old lockfile on `main`, or
2. restore backed-up runtime folders if backups were created, or
3. clean Lazy plugin dirs and reinstall from `main` lockfile.

Before destructive runtime cleanup, ask the user.

Supported fallback matrix:

```text
AstroNvim v5 + Neovim 0.11.x = supported old path
AstroNvim v6 + Neovim 0.12.x = supported new path
AstroNvim v5 + Neovim 0.12.x = unsupported/problematic
```

## Open questions for orchestrator/build agent

1. If branch `migrate/astronvim-v6-nvim-0.12` already exists, ask before reusing or creating a suffixed branch.
2. If `:Lazy sync` changes many unrelated lock entries, decide whether to accept as part of v6 migration or split additional lockfile commits.
3. If `tree-sitter-cli` health fails, inspect Mason-installed version before removing/changing Mason config.
4. If `vimtex` AstroCommunity module conflicts with v6 Tree-sitter configuration, patch that module via user config rather than editing plugin checkout.

## Sources/research basis

- Official AstroNvim v6 migration guide provided by user.
- AstroNvim v6 docs: Tree-sitter feature configuration moved to AstroCore `opts.treesitter`.
- AstroNvim v6 docs: AstroLSP uses Neovim `vim.lsp.config` / `vim.lsp.enable` APIs.
- `nvim-treesitter` current behavior: `main` branch is required/targeted for Neovim 0.12; old `master` is incompatible.
- Local audit found no active source references to v6-renamed plugin names or removed plugin names.
- Local audit found `astrolsp.lua` likely does not need migration.
- Local audit found active AstroCommunity imports are under `lua/plugins/astrocommunity.lua`, not disabled `lua/community.lua`.