feat!: event API (#181)

* chore: minor code simplification

* feat!: event api

* fix: test

* feat: provide command interface

* chore(doc): auto generate docs

* feat: add error reporting for linters

* chore(doc): auto generate docs

* ci: add linter test

* ci: more tests

* chore: update bug report issue template

* Update bug_report.yml

* chore(doc): auto generate docs

* wip: add custom event support for formatting

* chore(doc): auto generate docs

* ci: add tests for custom formatter events

* fix: enable/disable-fmt

* fix(side quest): fix generic linters properly

* update

* fix: type check

* scaffold more stuff

* chore(doc): auto generate docs

* feat: add custom linter event logic

* chore(doc): auto generate docs

* update

* feat: auto_lint

* chore(doc): auto generate docs

* special treat

* fix global state

* feat: add lint interval option + naming changes

* chore(doc): auto generate docs

* Update lua/guard/filetype.lua

Co-authored-by: glepnir <[email protected]>

* Update lua/guard/filetype.lua

Co-authored-by: glepnir <[email protected]>

* Update lua/guard/events.lua

Co-authored-by: glepnir <[email protected]>

* Update lua/guard/events.lua

Co-authored-by: glepnir <[email protected]>

* Update lua/guard/events.lua

Co-authored-by: glepnir <[email protected]>

* feat: unify guard info with healthcheck

* chore: tweak issue template

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: glepnir <[email protected]>

Author: 3 people

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,37 +1,44 @@
-# https://github.com/mrcjkb/haskell-tools.nvim/blob/master/.github/ISSUE_TEMPLATE/bug_report.yml
+# Based on https://github.com/mrcjkb/haskell-tools.nvim/blob/master/.github/ISSUE_TEMPLATE/bug_report.yml
 name: Bug Report
 description: Report a problem with guard.nvim
 labels: [bug]
 body:
-
   - type: input
     attributes:
       label: "Neovim version (nvim -v)"
       placeholder: "v0.10.0"
     validations:
       required: true
+
   - type: input
     attributes:
       label: "Operating system/version"
       placeholder: "Fedora Linux 40"
     validations:
       required: true
+
   - type: textarea
     attributes:
-      label: "Output of :checkhealth guard"
-      render: "console"
-      placeholder: |
-        Perhaps the tools are not in your $PATH?
+      label: "Expected behaviour"
+      description: "Describe the behaviour you expect."
     validations:
       required: true
+
   - type: textarea
     attributes:
-      label: "Output of :Guard info"
-      render: "markdown"
+      label: "Actual behaviour"
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: "Output of :checkhealth guard"
+      render: "console"
       placeholder: |
-        Are the autocmds attached?
+        Perhaps the tools are not in your $PATH?
     validations:
       required: true
+
   - type: textarea
     attributes:
       label: "How to reproduce the issue"
@@ -40,29 +47,15 @@ body:
         git clone https://github.com/nvimdev/guard-collection /tmp
         echo "vim.opt.rtp:append('/tmp/guard.nvim')" >> /tmp/repro.lua
         echo "vim.opt.rtp:append('/tmp/guard-collection')" >> /tmp/repro.lua
+        nvim --clean -u /tmp/repro.lua
     validations:
       required: true
-  - type: textarea
-    attributes:
-      label: "Expected behaviour"
-      description: "Describe the behaviour you expect."
-    validations:
-      required: true
-  - type: textarea
-    attributes:
-      label: "Actual behaviour"
-    validations:
-      required: true
-  - type: textarea
-    attributes:
-      label: "The minimal config used to reproduce this issue."
-      description: |
-        Run with `nvim -u /tmp/repro.lua`
-      placeholder: |
-        vim.opt.rtp:append('/tmp/guard.nvim')
-        vim.opt.rtp:append('/tmp/guard-collection')
-        -- do anything else you need to do to reproduce the issue
 
-      render: "Lua"
-    validations:
-      required: true
+  - type: checkboxes
+    attributes:
+      label: Are you sure this is a min repro?
+      options:
+        - label: I understand that if my repro step is too complicated (e.g. here is my 1k+ line config and please help me), developers might not be able to help.
+          required: true
+        - label: I can confirm that my reproduction step only involves `vim.opt.rtp` and configuration themselves
+          required: true

CUSTOMIZE.md

@@ -24,6 +24,7 @@ A tool is specified as follows:
 
     -- special
     parse            -- function: linter only, parses linter output to neovim diagnostic
+    events           -- { name: string, opt: autocmd options }: override default events, for formatter autocmds only the first one is used (passed in from `:fmt`)
 }
 ```
 

README.md

@@ -49,20 +49,23 @@ ft('lang'):fmt('format-tool-1')
           :lint('lint-tool-1')
           :extra(extra_args)
 
--- change this anywhere in your config, these are the defaults
+-- change this anywhere in your config (or not), these are the defaults
 vim.g.guard_config = {
     -- format on write to buffer
     fmt_on_save = true,
     -- use lsp if no formatter was defined for this filetype
     lsp_as_default_formatter = false,
     -- whether or not to save the buffer after formatting
     save_on_fmt = true,
+    -- automatic linting
+    auto_lint = true,
+    -- how frequently can linters be called
+    lint_interval = 500
 }
 ```
 
 - Use `Guard fmt` to manually call format, when there is a visual selection only the selection is formatted. **NOTE**: Regional formatting just sends your selection to the formatter, if there's not enough context incoherent formatting might occur (e.g. indent being erased)
-- `Guard disable` disables auto format for the current buffer, you can also `Guard disable 16` (the buffer number)
-- Use `Guard enable` to re-enable auto format, usage is the same as `Guard disable`
+- `enable-fmt`, `disable-fmt` turns auto formatting on and off for the current buffer.
 
 Format c files with clang-format and lint with clang-tidy:
 
@@ -92,6 +95,9 @@ Lint all your files with `codespell`
 ft('*'):lint('codespell')
 ```
 
+- Use `Guard Lint` to lint manually.
+- `enable-lint` and `disable-lint` controls auto linting for the current buffer.
+
 You can also easily create your own configuration that's not in `guard-collection`, see [CUSTOMIZE.md](./CUSTOMIZE.md).
 
 For more niche use cases, [ADVANCED.md](./ADVANCED.md) demonstrates how to:

doc/guard.nvim.txt

@@ -1,4 +1,4 @@
-*guard.nvim.txt*         For NVIM v0.8.0         Last change: 2024 December 13
+*guard.nvim.txt*         For NVIM v0.8.0         Last change: 2024 December 23
 
 ==============================================================================
 Table of Contents                               *guard.nvim-table-of-contents*
@@ -68,20 +68,23 @@ To register formatters and linters:
               :lint('lint-tool-1')
               :extra(extra_args)
 
-    -- change this anywhere in your config, these are the defaults
+    -- change this anywhere in your config (or not), these are the defaults
     vim.g.guard_config = {
         -- format on write to buffer
         fmt_on_save = true,
         -- use lsp if no formatter was defined for this filetype
         lsp_as_default_formatter = false,
         -- whether or not to save the buffer after formatting
         save_on_fmt = true,
+        -- automatic linting
+        auto_lint = true,
+        -- how frequently can linters be called
+        lint_interval = 500
     }
 <
 
 - Use `Guard fmt` to manually call format, when there is a visual selection only the selection is formatted. **NOTE**: Regional formatting just sends your selection to the formatter, if there’s not enough context incoherent formatting might occur (e.g. indent being erased)
-- `Guard disable` disables auto format for the current buffer, you can also `Guard disable 16` (the buffer number)
-- Use `Guard enable` to re-enable auto format, usage is the same as `Guard disable`
+- `enable-fmt`, `disable-fmt` turns auto formatting on and off for the current buffer.
 
 Format c files with clang-format and lint with clang-tidy:
 
@@ -112,6 +115,9 @@ Lint all your files with `codespell`
     ft('*'):lint('codespell')
 <
 
+- Use `Guard Lint` to lint manually.
+- `enable-lint` and `disable-lint` controls auto linting for the current buffer.
+
 You can also easily create your own configuration that’s not in
 `guard-collection`, see CUSTOMIZE.md <./CUSTOMIZE.md>.
 
@@ -150,6 +156,7 @@ A tool is specified as follows:
 
         -- special
         parse            -- function: linter only, parses linter output to neovim diagnostic
+        events           -- { name: string, opt: autocmd options }: override default events, for formatter autocmds only the first one is used (passed in from `:fmt`)
     }
 <
 

lua/guard/_meta.lua

@@ -4,6 +4,7 @@
 ---@field fname boolean?
 ---@field stdin boolean?
 ---@field fn function?
+---@field events EventOption[]
 ---@field ignore_patterns string|string[]?
 ---@field ignore_error boolean?
 ---@field find string|string[]?
@@ -18,6 +19,7 @@
 ---@field fname boolean?
 ---@field stdin boolean?
 ---@field fn function?
+---@field events EventOption[]
 ---@field parse function
 ---@field ignore_patterns string|string[]?
 ---@field ignore_error boolean?
@@ -26,3 +28,9 @@
 ---@field timeout integer?
 
 ---@alias LintConfig LintConfigTable|fun(): LintConfigTable
+
+---@alias AuOption vim.api.keyset.create_autocmd
+
+---@class EventOption
+---@field name string
+---@field opt AuOption?

lua/guard/api.lua

@@ -0,0 +1,70 @@
+-- These are considered public API and changing their signature would be a breaking change
+local M = {}
+local api = vim.api
+local events = require('guard.events')
+
+---Format bufnr or current buffer
+---@param bufnr number?
+function M.fmt(bufnr)
+  require('guard.format').do_fmt(bufnr)
+end
+
+---Lint bufnr or current buffer
+---@param bufnr number?
+function M.lint(bufnr)
+  require('guard.lint').do_lint(bufnr)
+end
+
+---Enable format for bufnr or current buffer
+---@param bufnr number?
+function M.enable_fmt(bufnr)
+  local buf = bufnr or api.nvim_get_current_buf()
+  local ft_handler = require('guard.filetype')
+  local ft = vim.bo[buf].ft
+  local head = vim.tbl_get(ft_handler, ft, 'formatter', 1)
+  if type(head) == 'table' and type(head.events) == 'table' then
+    events.fmt_attach_custom(ft, head.events)
+  else
+    events.try_attach_fmt_to_buf(buf)
+  end
+end
+
+---Disable format for bufnr or current buffer
+---@param bufnr number?
+function M.disable_fmt(bufnr)
+  local buf = bufnr or api.nvim_get_current_buf()
+  vim.iter(events.get_format_autocmds(buf)):each(function(it)
+    api.nvim_del_autocmd(it.id)
+  end)
+  events.user_fmt_autocmds[vim.bo[buf].ft] = {}
+end
+
+---Enable lint for bufnr or current buffer
+---@param bufnr number?
+function M.enable_lint(bufnr)
+  local buf = bufnr or api.nvim_get_current_buf()
+  local ft = require('guard.filetype')[vim.bo[buf].ft] or {}
+  if ft.linter and #ft.linter > 0 then
+    events.try_attach_lint_to_buf(
+      buf,
+      require('guard.util').linter_events(ft.linter[1]),
+      vim.bo[buf].ft
+    )
+  end
+end
+
+---Disable format for bufnr or current buffer
+---@param bufnr number?
+function M.disable_lint(bufnr)
+  local aus = events.get_lint_autocmds(bufnr or api.nvim_get_current_buf())
+  vim.iter(aus):each(function(au)
+    api.nvim_del_autocmd(au.id)
+  end)
+end
+
+---Show guard info for current buffer
+function M.info()
+  vim.cmd('checkhealth guard')
+end
+
+return M