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:

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:

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

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

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

• Current active imports:

-- 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/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:

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:

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:

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:

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

Then create and check out the migration branch:

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

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

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:

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:

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:

lua/lazy_setup.lua

Current audited state:

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

Required change:

version = "^6"

Keep:

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:

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:

lua/plugins/treesitter.lua

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

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:

-- 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:

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:

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

If found, replace:

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:

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:

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:

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:

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:

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

If old anonymous default handler is found:

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

migrate to v6-style:

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

Commit only if source edits are actually needed:

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:

lua/plugins/mason.lua

Planning audit found:

"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:

nvim

Then inside Neovim:

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

Alternative headless commands if appropriate:

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:

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

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

Useful checks:

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

Commit lockfile and only generated plugin-lock changes:

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:

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

Run Tree-sitter health:

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

Manual markdown crash reproduction test:

Create or open a markdown file containing fenced code blocks:

# Tree-sitter crash test

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

```bash
echo hello
```

Open it with the migrated config:

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:

: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:

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:

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

Use for any startup warnings caused by changed APIs.

Possible commit:

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:

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:

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:

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:

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.