feat: update helpdocs

doc/forge.nvim.txt

@@ -240,16 +240,14 @@ All subcommands support tab completion.
 PICKERS                                                        *forge-pickers*
 
                                                                 *forge-picker*
-FORGE PICKER ~
+FORGE PICKER ~ The main entry point. Adapts based on the detected forge and
-The main entry point. Adapts based on the detected forge and current
+current buffer. Lists: PRs/MRs, Issues, CI/CD, Browse Remote, Open File, Yank
-buffer. Lists: PRs/MRs, Issues, CI/CD, Browse Remote, Open File, Yank
+Commit URL, Yank Branch URL, Commits, Branches, Worktrees. Items that require
-Commit URL, Yank Branch URL, Commits, Branches, Worktrees. Items that
+a forge are hidden when no forge is detected. "Open File" and yank entries
-require a forge are hidden when no forge is detected. "Open File" and yank
+require a named buffer on a branch.
-entries require a named buffer on a branch.
 
                                                              *forge-picker-pr*
-PR PICKER ~
+PR PICKER ~ Lists PRs/MRs with number, title, author, and relative time.
-Lists PRs/MRs with number, title, author, and relative time.
 
   Action      Default Key    Description ~
   `checkout`    `<cr>`           Check out the PR branch
@@ -263,8 +261,7 @@ Lists PRs/MRs with number, title, author, and relative time.
   `refresh`     `<c-r>`          Clear cache and re-fetch
 
                                                           *forge-picker-issue*
-ISSUE PICKER ~
+ISSUE PICKER ~ Lists issues with number, title, author, and relative time.
-Lists issues with number, title, author, and relative time.
 
   Action      Default Key    Description ~
   `browse`      `<cr>`           Open issue in browser
@@ -273,9 +270,8 @@ Lists issues with number, title, author, and relative time.
   `refresh`     `<c-r>`          Clear cache and re-fetch
 
                                                              *forge-picker-ci*
-CI PICKER ~
+CI PICKER ~ Used for both per-PR checks (`:Forge pr ci {num}`) and repo-wide
-Used for both per-PR checks (`:Forge pr ci {num}`) and repo-wide CI runs
+CI runs (`:Forge ci`). Both share the `keys.ci` bindings.
-(`:Forge ci`). Both share the `keys.ci` bindings.
 
   Action      Default Key    Description ~
   `log`         `<cr>`           View log (tail for running, failed-only for
@@ -288,8 +284,7 @@ Used for both per-PR checks (`:Forge pr ci {num}`) and repo-wide CI runs
   `refresh`     `<c-r>`          Re-fetch runs
 
                                                         *forge-picker-commits*
-COMMITS PICKER ~
+COMMITS PICKER ~ Git log with colored output and commit preview.
-Git log with colored output and commit preview.
 
   Action      Default Key    Description ~
   `checkout`    `<cr>`           Checkout commit (detached HEAD)
@@ -298,18 +293,16 @@ Git log with colored output and commit preview.
   `yank`        `<c-y>`          Yank commit hash to `+` register
 
                                                        *forge-picker-branches*
-BRANCHES PICKER ~
+BRANCHES PICKER ~ Uses fzf-lua's `git_branches` with additional actions.
-Uses fzf-lua's `git_branches` with additional actions.
 
   Action      Default Key    Description ~
   `diff`        `<c-d>`          Review diff against branch
   `browse`      `<c-x>`          Open branch on forge
 
                                                          *forge-picker-manage*
-MANAGE PICKER ~
+MANAGE PICKER ~ Contextual actions for a specific PR, shown based on
-Contextual actions for a specific PR, shown based on permissions and
+permissions and state: Approve, Merge (per available method: squash, rebase,
-state: Approve, Merge (per available method: squash, rebase, merge),
+merge), Close/Reopen, Mark as draft/Mark as ready.
-Close/Reopen, Mark as draft/Mark as ready.
 
 ==============================================================================
 REVIEW                                                          *forge-review*
@@ -371,7 +364,15 @@ Template discovery: ~
   Codeberg: `.gitea/pull_request_template.md`,
             `.github/pull_request_template.md`
 
-Highlight groups: ~
+See |forge-highlights| for compose buffer highlight groups.
+
+==============================================================================
+HIGHLIGHTS                                                  *forge-highlights*
+
+All highlight groups are defined with `default = true`, so they can be
+overridden by colorschemes or user config.
+
+Compose buffer: ~
 
   Group                    Default Link      Description ~
   `ForgeComposeComment`      `Comment`          Comment block lines
@@ -382,7 +383,19 @@ Highlight groups: ~
   `ForgeComposeAdded`        `Added`            Addition indicators (+)
   `ForgeComposeRemoved`      `Removed`          Deletion indicators (-)
 
-All groups are defined with `default = true`.
+Picker lines: ~
+
+  Group                    Default Link        Description ~
+  `ForgeNumber`              `Number`             PR/issue number (#123)
+  `ForgeOpen`                `DiagnosticInfo`     Open status icon
+  `ForgeMerged`              `Constant`           Merged status icon
+  `ForgeClosed`              `Comment`            Closed status icon
+  `ForgePass`                `DiagnosticOk`       Passed CI status icon
+  `ForgeFail`                `DiagnosticError`    Failed CI status icon
+  `ForgePending`             `DiagnosticWarn`     In-progress CI status icon
+  `ForgeSkip`                `Comment`            Skipped/cancelled CI icon
+  `ForgeBranch`              `Special`            Branch name in CI runs
+  `ForgeDim`                 `Comment`            Author, age, elapsed time
 
 ==============================================================================
 SOURCES                                                        *forge-sources*
@@ -394,9 +407,9 @@ Built-in sources: ~
   `gitlab`        `glab`      `gitlab`
   `codeberg`      `tea`       `codeberg`, `gitea`, `forgejo`
 
-Sources are lazy-loaded the first time a matching remote is detected.
+Sources are lazy-loaded the first time a matching remote is detected. Built-in
-Built-in host patterns are checked after user-configured `sources` hosts,
+host patterns are checked after user-configured `sources` hosts, so user
-so user overrides take priority.
+overrides take priority.
 
 HOST OVERRIDES ~
                                                          *forge-sources-hosts*
@@ -413,15 +426,14 @@ CUSTOM SOURCE REGISTRATION ~
 Register a custom source with `require('forge').register()`: >lua
     local my_source = { ... }
     require('forge').register('myforgejo', my_source)
-<
+< The name must match the key used in `sources` host config. The source module
-The name must match the key used in `sources` host config. The source
+is also discoverable as `forge.<name>` (e.g. `require('forge.myforgejo')` if
-module is also discoverable as `forge.<name>` (e.g. `require('forge.myforgejo')`
+placed at `lua/forge/myforgejo.lua`).
-if placed at `lua/forge/myforgejo.lua`).
 
 THE `forge.Forge` INTERFACE ~
                                                        *forge-Forge-interface*
-A source must implement all methods in the `forge.Forge` class. Each
+A source must implement all methods in the `forge.Forge` class. Each source is
-source is a table with these fields and methods:
+a table with these fields and methods:
 
 Fields: ~
   `name`        `string`       Source name (e.g. `"github"`).

lua/forge/init.lua

@@ -13,11 +13,11 @@ local M = {}
 ---@field hosts string[]
 
 ---@class forge.KeysConfig
----@field pr forge.PRPickerKeys
+---@field pr forge.PRPickerKeys?
----@field issue forge.IssuePickerKeys
+---@field issue forge.IssuePickerKeys?
----@field ci forge.CIPickerKeys
+---@field ci forge.CIPickerKeys?
----@field commits forge.CommitsPickerKeys
+---@field commits forge.CommitsPickerKeys?
----@field branches forge.BranchesPickerKeys
+---@field branches forge.BranchesPickerKeys?
 
 ---@class forge.PRPickerKeys
 ---@field checkout string|false
@@ -256,6 +256,7 @@ end
 ---@field create_pr_cmd fun(self: forge.Forge, title: string, body: string, base: string, draft: boolean, reviewers: string[]?): string[]
 ---@field create_pr_web_cmd fun(self: forge.Forge): string[]?
 ---@field default_branch_cmd fun(self: forge.Forge): string[]
+---@field checks_json_cmd (fun(self: forge.Forge, num: string): string[])?
 ---@field template_paths fun(self: forge.Forge): string[]
 
 ---@type table<string, forge.Forge>
@@ -461,12 +462,12 @@ local function parse_iso(iso)
     return nil
   end
   local ok, ts = pcall(os.time, {
-    year = tonumber(y),
+    year = tonumber(y) --[[@as integer]],
-    month = tonumber(mo),
+    month = tonumber(mo) --[[@as integer]],
-    day = tonumber(d),
+    day = tonumber(d) --[[@as integer]],
-    hour = tonumber(h),
+    hour = tonumber(h) --[[@as integer]],
-    min = tonumber(mi),
+    min = tonumber(mi) --[[@as integer]],
-    sec = tonumber(s),
+    sec = tonumber(s) --[[@as integer]],
   })
   if ok and ts then
     return ts

lua/forge/pickers.lua

@@ -1,6 +1,6 @@
 local M = {}
 
----@param result vim.SystemCompleted
+---@param result { code: integer, stdout: string?, stderr: string? }
 ---@param fallback string
 ---@return string
 local function cmd_error(result, fallback)
@@ -186,12 +186,14 @@ local function pr_actions(f, num)
     },
   }
 
+  ---@type table<string, function>
   local name_to_fn = {}
   for _, def in ipairs(defs) do
     name_to_fn[def.name] = def.fn
   end
 
   local actions = build_actions('pr', defs)
+  ---@type table<string, function>
   actions._by_name = name_to_fn
   return actions
 end
@@ -522,7 +524,7 @@ function M.ci(f, branch)
   end
 end
 
----@param f forge.Forge
+---@param f forge.Forge?
 function M.commits(f)
   local forge_mod = require('forge')
   local review = require('forge.review')

lua/forge/review.lua

@@ -19,11 +19,6 @@ end
 function M.stop()
   M.state.base = nil
   M.state.mode = 'unified'
-  local cfg = require('forge').config()
-  local lhs = cfg.keys ~= false and cfg.keys.review_toggle
-  if lhs then
-    pcall(vim.keymap.del, 'n', lhs)
-  end
   vim.api.nvim_clear_autocmds({ group = review_augroup })
 end
 
@@ -61,11 +56,6 @@ end
 function M.start(base, mode)
   M.state.base = base
   M.state.mode = mode or 'unified'
-  local cfg = require('forge').config()
-  local lhs = cfg.keys ~= false and cfg.keys.review_toggle
-  if lhs then
-    vim.keymap.set('n', lhs, M.toggle, { desc = 'toggle review split/unified' })
-  end
   vim.api.nvim_clear_autocmds({ group = review_augroup })
   vim.api.nvim_create_autocmd('BufWipeout', {
     group = review_augroup,