docs: use generated types and better type annotations

lua/octo/commands.lua

@@ -654,7 +654,7 @@ function M.delete_comment()
       cb = function(output)
         -- TODO: deleting the last review thread comment, it deletes the whole thread and review
         -- In issue buffers, we should hide the thread snippet
-        local resp = vim.json.decode(output)
+        local resp = vim.json.decode(output) ---@type {data: {deletePullRequestReviewComment: octo.gh.DeletePullRequestReviewCommentPayload?}}
 
         -- remove comment lines from the buffer
         if comment.reactionLine then
@@ -745,6 +745,10 @@ function M.delete_comment()
   end
 end
 
+---@param bufnr integer
+---@param thread octo.gh.PullRequestReviewThread
+---@param thread_id string
+---@param thread_line integer
 local function update_review_thread_header(bufnr, thread, thread_id, thread_line)
   local start_line = thread.originalStartLine ~= vim.NIL and thread.originalStartLine or thread.originalLine
   local end_line = thread.originalLine
@@ -788,9 +792,10 @@ function M.resolve_thread()
       if stderr and not utils.is_blank(stderr) then
         utils.error(stderr)
       elseif output then
-        local resp = vim.json.decode(output)
+        local resp = vim.json.decode(output) ---@type {data: {resolveReviewThread: octo.gh.ResolveReviewThreadPayload}}
         local thread = resp.data.resolveReviewThread.thread
-        if thread.isResolved then
+        if thread ~= vim.NIL and thread.isResolved then
+          ---@cast thread -vim.NIL
           update_review_thread_header(bufnr, thread, thread_id, thread_line)
           --vim.cmd(string.format("%d,%dfoldclose", thread_line, thread_line))
         end
@@ -818,9 +823,10 @@ function M.unresolve_thread()
       if stderr and not utils.is_blank(stderr) then
         utils.error(stderr)
       elseif output then
-        local resp = vim.json.decode(output)
+        local resp = vim.json.decode(output) ---@type {data: {unresolveReviewThread: octo.gh.UnresolveReviewThreadPayload}}
         local thread = resp.data.unresolveReviewThread.thread
-        if not thread.isResolved then
+        if thread ~= vim.NIL and not thread.isResolved then
+          ---@cast thread -vim.NIL
           update_review_thread_header(bufnr, thread, thread_id, thread_line)
         end
       end
@@ -961,7 +967,7 @@ function M.save_issue(opts)
       if stderr and not utils.is_blank(stderr) then
         utils.error(stderr)
       elseif output then
-        local resp = vim.json.decode(output)
+        local resp = vim.json.decode(output) ---@type {data: {createIssue: octo.gh.CreateIssuePayload}}
         require("octo").create_buffer("issue", resp.data.createIssue.issue, opts.repo, true)
         vim.fn.execute "normal! Gk"
         vim.fn.execute "startinsert"
@@ -1175,7 +1181,7 @@ function M.save_pr(opts)
         if stderr and not utils.is_blank(stderr) then
           utils.error(stderr)
         elseif output then
-          local resp = vim.json.decode(output)
+          local resp = vim.json.decode(output) ---@type {data: {createPullRequest: octo.gh.CreatePullRequestPayload}}
           local pr = resp.data.createPullRequest.pullRequest
           utils.info(string.format("#%d - `%s` created successfully", pr.number, pr.title))
           require("octo").create_buffer("pull", pr, opts.repo, true)
@@ -1231,8 +1237,8 @@ function M.pr_checks()
       if stderr and not utils.is_blank(stderr) then
         utils.error(stderr)
       elseif output then
-        local max_lengths = {}
-        local parts = {}
+        local max_lengths = {} ---@type integer[]
+        local parts = {} ---@type string[][]
         for _, l in pairs(vim.split(output, "\n")) do
           local line_parts = vim.split(l, "\t")
           for i, p in pairs(line_parts) do
@@ -1330,15 +1336,24 @@ function M.show_pr_diff()
   }
 end
 
+---@param bufnr integer
+---@param extmark integer
+---@return integer
 local function get_reaction_line(bufnr, extmark)
   local prev_extmark = extmark
   local mark = vim.api.nvim_buf_get_extmark_by_id(bufnr, constants.OCTO_COMMENT_NS, prev_extmark, { details = true })
   local _, end_line = utils.get_extmark_region(bufnr, mark)
   return end_line + 3
 end
 
+---@param bufnr integer
+---@param buffer OctoBuffer
+---@return integer reaction_line
+---@return octo.gh.ReactionGroup[] reaction_groups
+---@return boolean insert_line
+---@return string id
 local function get_reaction_info(bufnr, buffer)
-  local reaction_groups, reaction_line, insert_line, id
+  local reaction_groups, reaction_line, insert_line, id ---@type octo.gh.ReactionGroup[], integer, boolean, string
   local comment = buffer:get_comment_at_cursor()
   if comment then
     -- found a comment at cursor
@@ -1379,7 +1394,7 @@ function M.reaction_action(reaction)
 
   local reaction_line, reaction_groups, insert_line, id = get_reaction_info(bufnr, buffer)
 
-  local action
+  local action ---@type "add" | "remove"
   for _, reaction_group in ipairs(reaction_groups) do
     if reaction_group.content == reaction and reaction_group.viewerHasReacted then
       action = "remove"
@@ -1403,8 +1418,10 @@ function M.reaction_action(reaction)
       elseif output then
         local resp = vim.json.decode(output)
         if action == "add" then
+          ---@cast resp {data: {addReaction: octo.gh.AddReactionPayload}}
           reaction_groups = resp.data.addReaction.subject.reactionGroups
         elseif action == "remove" then
+          ---@cast resp {data: {removeReaction: octo.gh.RemoveReactionPayload}}
           reaction_groups = resp.data.removeReaction.subject.reactionGroups
         end
 
@@ -1527,7 +1544,7 @@ function M.set_project_v2_card()
         if add_stderr and not utils.is_blank(add_stderr) then
           utils.error(add_stderr)
         elseif add_output then
-          local resp = vim.json.decode(add_output)
+          local resp = vim.json.decode(add_output) ---@type {data: {addProjectV2ItemById: octo.gh.AddProjectV2ItemByIdPayload}}
           local update_query = graphql(
             "update_project_v2_item_mutation",
             project_id,
@@ -1631,7 +1648,7 @@ function M.create_label(label)
       if stderr and not utils.is_blank(stderr) then
         utils.error(stderr)
       elseif output then
-        local resp = vim.json.decode(output)
+        local resp = vim.json.decode(output) ---@type {data: {createLabel: octo.gh.CreateLabelPayload}}
         local label = resp.data.createLabel.label
         utils.info("Created label: " .. label.name)
 

lua/octo/gh/init.lua

@@ -244,7 +244,7 @@ end
 
 ---Run a graphql query
 ---@param opts table the options for the graphql query
----@return table|nil
+---@return string|nil
 function M.graphql(opts)
   local run_opts = opts.opts or {}
   return M.run {

lua/octo/init.lua

@@ -15,8 +15,8 @@ local writers = require "octo.ui.writers"
 local utils = require "octo.utils"
 local vim = vim
 
-_G.octo_repo_issues = {}
-_G.octo_buffers = {}
+_G.octo_repo_issues = {} ---@type table<string, {number: integer, title: string}> repo -> issues_metadata
+_G.octo_buffers = {} ---@type table<integer, OctoBuffer> buffer -> OctoBuffer
 _G.octo_colors_loaded = false
 
 local M = {}
@@ -128,9 +128,13 @@ function M.load_buffer(opts)
   end)
 end
 
+---@param repo string
+---@param kind string
+---@param number integer
+---@param cb function
 function M.load(repo, kind, number, cb)
   local owner, name = utils.split_repo(repo)
-  local query, key
+  local query, key ---@type string, string
 
   if kind == "pull" then
     query = graphql("pull_request_query", owner, name, number, _G.octo_pv2_fragment)
@@ -184,12 +188,12 @@ function M.on_cursor_hold()
         if stderr and not utils.is_blank(stderr) then
           vim.api.nvim_err_writeln(stderr)
         elseif output then
-          local resp = vim.json.decode(output)
-          local reactions = {}
+          local resp = vim.json.decode(output) ---@type {data: {node: {reactionGroups: octo.gh.ReactionGroup[]}}}
+          local reactions = {} ---@type table<octo.gh.ReactionContent, string[]>
           local reactionGroups = resp.data.node.reactionGroups
           for _, reactionGroup in ipairs(reactionGroups) do
             local users = reactionGroup.users.nodes
-            local logins = {}
+            local logins = {} ---@type string[]
             for _, user in ipairs(users) do
               table.insert(logins, user.login)
             end
@@ -220,7 +224,7 @@ function M.on_cursor_hold()
         if stderr and not utils.is_blank(stderr) then
           vim.api.nvim_err_writeln(stderr)
         elseif output then
-          local resp = vim.json.decode(output)
+          local resp = vim.json.decode(output) ---@type {data: {user: octo.gh.User}}
           local user = resp.data.user
           local popup_bufnr = vim.api.nvim_create_buf(false, true)
           local lines, max_length = writers.write_user_profile(popup_bufnr, user)
@@ -248,7 +252,7 @@ function M.on_cursor_hold()
       if stderr and not utils.is_blank(stderr) then
         vim.api.nvim_err_writeln(stderr)
       elseif output then
-        local resp = vim.json.decode(output)
+        local resp = vim.json.decode(output) ---@type {data: {repository: octo.gh.Repository}}
         local issue = resp.data.repository.issueOrPullRequest
         local popup_bufnr = vim.api.nvim_create_buf(false, true)
         local max_length = 80
@@ -263,13 +267,17 @@ function M.on_cursor_hold()
   }
 end
 
+---@param kind string
+---@param obj {number: integer, id: string}
+---@param repo string
+---@param create boolean
 function M.create_buffer(kind, obj, repo, create)
   if not obj.id then
     utils.error("Cannot find " .. repo)
     return
   end
 
-  local bufnr
+  local bufnr ---@type integer
   if create then
     bufnr = vim.api.nvim_create_buf(true, false)
     vim.api.nvim_set_current_buf(bufnr)

lua/octo/model/body-metadata.lua

@@ -8,8 +8,8 @@ local M = {}
 ---@field startLine integer
 ---@field endLine integer
 ---@field viewerCanUpdate boolean
--- @field reactionGroups table[]
--- @field reactionLine integer
+---@field reactionGroups octo.gh.ReactionGroup
+---@field reactionLine integer
 local BodyMetadata = {}
 BodyMetadata.__index = BodyMetadata
 

lua/octo/model/comment-metadata.lua

@@ -10,7 +10,7 @@ local M = {}
 ---@field startLine integer
 ---@field endLine integer
 ---@field namespace integer
----@field reactionGroups table[]
+---@field reactionGroups octo.gh.ReactionGroup
 ---@field reactionLine integer
 ---@field viewerCanUpdate boolean
 ---@field viewerCanDelete boolean

lua/octo/model/octo-buffer.lua

@@ -22,12 +22,15 @@ local M = {}
 ---@field bodyMetadata BodyMetadata
 ---@field commentsMetadata CommentMetadata[]
 ---@field threadsMetadata ThreadMetadata[]
----@field node table
+---@field node octo.gh.Repository
 ---@field taggable_users string[]
+---@field owner string
+---@field name string
 local OctoBuffer = {}
 OctoBuffer.__index = OctoBuffer
 
 ---OctoBuffer constructor.
+---@param opts table
 ---@return OctoBuffer
 function OctoBuffer:new(opts)
   local this = {
@@ -400,10 +403,12 @@ function OctoBuffer:do_save_title_and_body()
           vim.api.nvim_err_writeln(stderr)
         elseif output then
           local resp = vim.json.decode(output)
-          local obj
+          local obj ---@type octo.gh.Issue | octo.gh.PullRequest | vim.NIL
           if self:isPullRequest() then
+            ---@cast resp {data: {updatePullRequest: octo.gh.UpdatePullRequestPayload}}
             obj = resp.data.updatePullRequest.pullRequest
           elseif self:isIssue() then
+            ---@cast resp {data: {updateIssue: octo.gh.UpdateIssuePayload}}
             obj = resp.data.updateIssue.issue
           end
           if title_metadata.body == obj.title then
@@ -437,7 +442,7 @@ function OctoBuffer:do_add_issue_comment(comment_metadata)
       if stderr and not utils.is_blank(stderr) then
         vim.api.nvim_err_writeln(stderr)
       elseif output then
-        local resp = vim.json.decode(output)
+        local resp = vim.json.decode(output) ---@type {data: {addComment: octo.gh.AddCommentPayload}}
         local respBody = resp.data.addComment.commentEdge.node.body
         local respId = resp.data.addComment.commentEdge.node.id
         if utils.trim(comment_metadata.body) == utils.trim(respBody) then
@@ -472,9 +477,9 @@ function OctoBuffer:do_add_thread_comment(comment_metadata)
       if stderr and not utils.is_blank(stderr) then
         vim.api.nvim_err_writeln(stderr)
       elseif output then
-        local resp = vim.json.decode(output)
+        local resp = vim.json.decode(output) ---@type {data: {addPullRequestReviewComment: octo.gh.AddPullRequestReviewCommentPayload}}
         local resp_comment = resp.data.addPullRequestReviewComment.comment
-        local comment_end
+        local comment_end ---@type integer
         if utils.trim(comment_metadata.body) == utils.trim(resp_comment.body) then
           local comments = self.commentsMetadata
           for i, c in ipairs(comments) do
@@ -584,7 +589,7 @@ function OctoBuffer:do_add_new_thread(comment_metadata)
         if stderr and not utils.is_blank(stderr) then
           vim.api.nvim_err_writeln(stderr)
         elseif output then
-          local resp = vim.json.decode(output).data.addPullRequestReviewThread
+          local resp = vim.json.decode(output).data.addPullRequestReviewThread ---@type octo.gh.AddPullRequestReviewThreadPayload
           if not utils.is_blank(resp.thread) then
             local new_comment = resp.thread.comments.nodes[1]
             if utils.trim(comment_metadata.body) == utils.trim(new_comment.body) then
@@ -682,7 +687,7 @@ function OctoBuffer:do_add_new_thread(comment_metadata)
             vim.api.nvim_err_writeln(stderr)
           elseif output then
             local r = vim.json.decode(output)
-            local resp = r.data.addPullRequestReviewComment
+            local resp = r.data.addPullRequestReviewComment ---@type octo.gh.AddPullRequestReviewCommentPayload
             if not utils.is_blank(resp.comment) then
               if utils.trim(comment_metadata.body) == utils.trim(resp.comment.body) then
                 local comments = self.commentsMetadata
@@ -712,6 +717,7 @@ function OctoBuffer:do_add_new_thread(comment_metadata)
 end
 
 ---Replies a review thread w/o creating a new review
+---@param comment_metadata CommentMetadata
 function OctoBuffer:do_add_pull_request_comment(comment_metadata)
   local current_review = require("octo.reviews").get_current_review()
   if not utils.is_blank(current_review) then
@@ -775,10 +781,12 @@ function OctoBuffer:do_update_comment(comment_metadata)
         vim.api.nvim_err_writeln(stderr)
       elseif output then
         local resp = vim.json.decode(output)
-        local resp_comment
+        local resp_comment ---@type octo.gh.IssueComment | octo.gh.PullRequestReview| octo.gh.PullRequestReviewComment | vim.NIL
         if comment_metadata.kind == "IssueComment" then
+          ---@cast resp {data: {updateIssueComment: octo.gh.UpdateIssueCommentPayload}}
           resp_comment = resp.data.updateIssueComment.issueComment
         elseif comment_metadata.kind == "PullRequestReviewComment" then
+          ---@cast resp {data: {updatePullRequestReviewComment: octo.gh.UpdatePullRequestReviewCommentPayload}}
           resp_comment = resp.data.updatePullRequestReviewComment.pullRequestReviewComment
           local threads =
             resp.data.updatePullRequestReviewComment.pullRequestReviewComment.pullRequest.reviewThreads.nodes
@@ -787,6 +795,7 @@ function OctoBuffer:do_update_comment(comment_metadata)
             review:update_threads(threads)
           end
         elseif comment_metadata.kind == "PullRequestReview" then
+          ---@cast resp {data: {updatePullRequestReview: octo.gh.UpdatePullRequestReviewPayload}}
           resp_comment = resp.data.updatePullRequestReview.pullRequestReview
         end
         if resp_comment and utils.trim(comment_metadata.body) == utils.trim(resp_comment.body) then
@@ -1019,6 +1028,8 @@ function OctoBuffer:get_reactions_at_cursor()
 end
 
 ---Updates the reactions groups at cursor (if any)
+---@param reaction_groups octo.gh.ReactionGroup[]
+---@param reaction_line integer
 function OctoBuffer:update_reactions_at_cursor(reaction_groups, reaction_line)
   local cursor = vim.api.nvim_win_get_cursor(0)
   local reactions_count = 0

lua/octo/navigation.lua

@@ -123,7 +123,7 @@ function M.go_to_issue()
       if stderr and not utils.is_blank(stderr) then
         vim.api.nvim_err_writeln(stderr)
       elseif output then
-        local resp = vim.json.decode(output)
+        local resp = vim.json.decode(output) ---@type {data: {repository: octo.gh.Repository}}
         local kind = resp.data.repository.issueOrPullRequest.__typename
         if kind == "Issue" then
           utils.get_issue(number, repo)