feat(mvp): MVP (#3)

.github/workflows/ci.yml

@@ -26,6 +26,17 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+      - name: Install commons.nvim
+        if: ${{ github.ref != 'refs/heads/main' }}
+        shell: bash
+        run: |
+          git clone --depth=1 https://github.com/linrongbin16/commons.nvim.git ~/.commons.nvim
+          rm -rf ./lua/gentags/commons
+          mkdir -p ./lua/gentags/commons
+          cp -rf ~/.commons.nvim/lua/commons/*.lua ./lua/gentags/commons
+          cp ~/.commons.nvim/version.txt ./lua/gentags/commons/version.txt
+          cd ./lua/gentags/commons
+          find . -type f -name '*.lua' -exec sed -i 's/require("commons/require("gentags.commons/g' {} \;
       - name: Luacheck
         uses: lunarmodules/luacheck@v1
         with:
@@ -36,21 +47,15 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           version: latest
           args: --config-path .stylua.toml ./lua ./test
-      - name: Add json.lua
-        if: ${{ github.ref != 'refs/heads/main' }}
-        shell: bash
-        run: |
-          echo "pwd"
-          echo $PWD
-          git clone --depth=1 https://github.com/actboy168/json.lua.git ~/.json.lua
-          cp ~/.json.lua/json.lua ./lua/gentags/actboy168_json.lua
       - name: Auto Commit
         if: ${{ github.ref != 'refs/heads/main' }}
         uses: stefanzweifel/git-auto-commit-action@v4
         with:
           commit_message: "chore(pr): auto-commit"
   unit_test:
     name: Unit Test
+    needs:
+      - luacheck
     strategy:
       matrix:
         nvim_version: [stable, nightly, v0.7.0]
@@ -99,7 +104,6 @@ jobs:
     name: Release
     if: ${{ github.ref == 'refs/heads/main' }}
     needs:
-      - luacheck
       - unit_test
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -41,3 +41,6 @@ luac.out
 
 # macOS
 .DS_Store
+
+# tags
+tags

.luacov

@@ -4,5 +4,5 @@ modules = {
 }
 
 exclude = {
-    "lua/actboy168_json.lua",
+    "lua/gentags/commons/*.lua",
 }

.styluaignore

@@ -0,0 +1 @@
+lua/gentags/commons/*.lua

README.md

@@ -1,8 +1,11 @@
+<!-- markdownlint-disable MD001 MD013 MD034 MD033 MD051 -->
+
 # gentags.nvim
 
 <p align="center">
 <a href="https://github.com/neovim/neovim/releases/v0.7.0"><img alt="Neovim" src="https://img.shields.io/badge/Neovim-v0.7+-57A143?logo=neovim&logoColor=57A143" /></a>
-<a href="https://luarocks.org/modules/linrongbin16/gentags.nvim"><img alt="luarocks" src="https://custom-icon-badges.demolab.com/luarocks/v/linrongbin16/gentags.nvim?label=Luarocks&labelColor=063B70&logo=feed-tag&logoColor=fff&color=008B8B" /></a>
+<a href="https://github.com/linrongbin16/commons.nvim"><img alt="commons.nvim" src="https://custom-icon-badges.demolab.com/badge/Powered_by-commons.nvim-teal?logo=heart&logoColor=fff&labelColor=deeppink" /></a>
+<a href="https://luarocks.org/modules/linrongbin16/gentags.nvim"><img alt="luarocks" src="https://custom-icon-badges.demolab.com/luarocks/v/linrongbin16/gentags.nvim?label=LuaRocks&labelColor=063B70&logo=tag&logoColor=fff&color=blue" /></a>
 <a href="https://github.com/linrongbin16/gentags.nvim/actions/workflows/ci.yml"><img alt="ci.yml" src="https://img.shields.io/github/actions/workflow/status/linrongbin16/gentags.nvim/ci.yml?label=GitHub%20CI&labelColor=181717&logo=github&logoColor=fff" /></a>
 <a href="https://app.codecov.io/github/linrongbin16/gentags.nvim"><img alt="codecov" src="https://img.shields.io/codecov/c/github/linrongbin16/gentags.nvim?logo=codecov&logoColor=F01F7A&label=Codecov" /></a>
 </p>
@@ -11,25 +14,97 @@
 Tags generator/management for old school vimers in Neovim.
 </i></p>
 
-> [!WARNING]
->
-> Don't use this plugin now, it's not finished yet!
+## Table of Contents
+
+- [Features](#features)
+- [Install](#install)
+- [Usage](#usage)
+- [Configuration](#configuration)
+- [Alternatives](#alternatives)
+- [Development](#development)
+- [Contribute](#contribute)
+
+## Features
+
+- [x] Support both workspace/single file.
+- [ ] Incremental update on file save.
+- [ ] Disk cache management and garbage collection.
+- [x] Async run & terminate immediately on nvim leave.
+- [ ] Real-time status for Neovim components such as statusline.
 
 ## Install
 
+Requirements:
+
+- Neovim &ge; 0.7.0.
+
+For now the required (or supported) backends are:
+
+- [universal-ctags](https://github.com/universal-ctags/ctags).
+
+PRs are welcome to add other backends.
+
 <details>
-<summary><b>With <a href="https://github.com/folke/lazy.nvim">lazy.nvim</a>.</b></summary>
+<summary><b>With <a href="https://github.com/folke/lazy.nvim">lazy.nvim</a></b></summary>
 
 ```lua
-require('lazy').setup({
-  { "linrongbin16/gentags.nvim", opts = {} }
+require("lazy").setup({
+  {
+    "linrongbin16/gentags.nvim",
+    config = function()
+      require('gentags').setup()
+    end,
+  },
 })
 ```
 
 </details>
 
-## Credits
+<details>
+<summary><b>With <a href="https://github.com/lewis6991/pckr.nvim">pckr.nvim</a></b></summary>
+
+```lua
+require("pckr").add({
+  {
+    "linrongbin16/gentags.nvim",
+    config = function()
+      require("gentags").setup()
+    end,
+  },
+})
+```
+
+</details>
+
+## Usage
+
+Gentags will automatically run below jobs in backend when you work in the nvim editor:
+
+- Load a tags for the whole worksapce or the single file on first open a file.
+- Generate tags for the whole worksapce or the single file on first open a file.
+- Update tags after you save writtens on a file.
+- Terminate all background child processes when you leave nvim.
+
+By default all tags are generated in `stdpath('cache') . '/gentags.nvim'` directory.
+
+- For UNIX/Linux: `~/.cache/nvim/gentags.nvim`.
+- For Windows: `$env:USERPROFILE\AppData\Local\Temp\nvim\gentags.nvim`.
+
+## Configuration
+
+To configure default options, please use:
+
+```lua
+require('gentags').setup(opts)
+```
+
+The `otps` is an optional lua table that overwrites default options.
+
+For complete options and defaults, please see [configs.lua](https://github.com/linrongbin16/gentags.nvim/tree/main/lua/gentags/configs.lua).
+
+## Alternatives
 
+- [gentags.lua](https://github.com/JMarkin/gentags.lua)
 - [vim-gutentags](https://github.com/ludovicchabant/vim-gutentags)
 
 ## Development

codecov.yml

@@ -7,4 +7,4 @@ coverage:
       default:
         threshold: 90%
 ignore:
-  - "lua/actboy168_json.lua"
+  - "lua/gentags/commons/*.lua"

lua/gentags.lua

@@ -1,5 +1,67 @@
+local logging = require("gentags.commons.logging")
+local LogLevels = require("gentags.commons.logging").LogLevels
+local configs = require("gentags.configs")
+
 local M = {}
 
-M.setup = function() end
+--- @param opts gentags.Options?
+M.setup = function(opts)
+  local cfg = configs.setup(opts)
+  -- print(vim.inspect(cfg))
+
+  logging.setup({
+    name = "gentags",
+    level = cfg.debug.enable and LogLevels.DEBUG or LogLevels.INFO,
+    console_log = cfg.debug.console_log,
+    file_log = cfg.debug.file_log,
+    file_log_name = "gentags.log",
+  })
+  local logger = logging.get("gentags") --[[@as commons.logging.Logger]]
+
+  -- cache dir
+  logger:ensure(
+    vim.fn.filereadable(cfg.cache_dir) <= 0,
+    "%s (cache_dir) already exist but not a directory!",
+    vim.inspect(cfg.cache_dir)
+  )
+  vim.fn.mkdir(cfg.cache_dir, "p")
+
+  -- init tags (first generate) when open/create file
+  vim.api.nvim_create_autocmd({
+    "BufReadPre",
+    "BufNewFile",
+    "FileReadPre",
+  }, {
+    callback = function(event)
+      logging
+        .get("gentags")
+        :debug("|setup| enter buffer:%s", vim.inspect(event))
+      require("gentags.dispatcher").load()
+      require("gentags.dispatcher").init()
+    end,
+  })
+
+  -- update tags when write/modify file
+  vim.api.nvim_create_autocmd({
+    "BufWritePost",
+    "FileWritePost",
+    "FileAppendPost",
+  }, {
+    callback = function(event)
+      logging
+        .get("gentags")
+        :debug("|setup| write buffer:%s", vim.inspect(event))
+      require("gentags.dispatcher").update()
+    end,
+  })
+
+  -- terminate before leaving vim
+  vim.api.nvim_create_autocmd({ "VimLeavePre" }, {
+    callback = function(event)
+      logging.get("gentags"):debug("|setup| leave vim:%s", vim.inspect(event))
+      require("gentags.dispatcher").terminate()
+    end,
+  })
+end
 
 return M