From 4710e6197fc941e99a53efe211fdc9dcd508bcb7 Mon Sep 17 00:00:00 2001 From: Barrett Ruth Date: Wed, 11 Mar 2026 12:39:14 -0400 Subject: [PATCH] refactor: tighten LuaCATS annotations across modules Problem: type annotations repeated inline unions with no aliases, used `table` where structured types exist, and had loose `string` where union types should be used. Solution: add `pending.TaskStatus`, `pending.RecurMode`, `pending.TaskExtra`, `pending.ForgeType`, `pending.ForgeState`, `pending.ForgeAuthStatus` aliases and `pending.SyncBackend` interface. Replace inline unions and loose types with the new aliases in `store.lua`, `forge.lua`, `config.lua`, `diff.lua`, `views.lua`, `parse.lua`, `init.lua`, and `oauth.lua`. --- lua/pending/config.lua | 4 +++- lua/pending/diff.lua | 4 ++-- lua/pending/forge.lua | 12 ++++++++---- lua/pending/init.lua | 8 ++++++++ lua/pending/parse.lua | 2 +- lua/pending/store.lua | 24 ++++++++++++++++++------ lua/pending/sync/oauth.lua | 9 +++++++++ lua/pending/views.lua | 2 +- 8 files changed, 50 insertions(+), 15 deletions(-) diff --git a/lua/pending/config.lua b/lua/pending/config.lua index 2ec13cc..ddfc2af 100644 --- a/lua/pending/config.lua +++ b/lua/pending/config.lua @@ -43,7 +43,9 @@ ---@field close? boolean ---@field validate? boolean ---@field warn_missing_cli? boolean ----@field [string] pending.ForgeInstanceConfig +---@field github? pending.ForgeInstanceConfig +---@field gitlab? pending.ForgeInstanceConfig +---@field codeberg? pending.ForgeInstanceConfig ---@class pending.SyncConfig ---@field remote_delete? boolean diff --git a/lua/pending/diff.lua b/lua/pending/diff.lua index 103ba6a..e3d02cc 100644 --- a/lua/pending/diff.lua +++ b/lua/pending/diff.lua @@ -7,11 +7,11 @@ local parse = require('pending.parse') ---@field id? integer ---@field description? string ---@field priority? integer ----@field status? string +---@field status? pending.TaskStatus ---@field category? string ---@field due? string ---@field rec? string ----@field rec_mode? string +---@field rec_mode? pending.RecurMode ---@field forge_ref? pending.ForgeRef ---@field lnum integer diff --git a/lua/pending/forge.lua b/lua/pending/forge.lua index 6116a9f..28c173a 100644 --- a/lua/pending/forge.lua +++ b/lua/pending/forge.lua @@ -1,17 +1,21 @@ local config = require('pending.config') local log = require('pending.log') +---@alias pending.ForgeType 'issue'|'pull_request'|'merge_request'|'repo' +---@alias pending.ForgeState 'open'|'closed'|'merged' +---@alias pending.ForgeAuthStatus 'unknown'|'ok'|'failed' + ---@class pending.ForgeRef ---@field forge string ---@field owner string ---@field repo string ----@field type 'issue'|'pull_request'|'merge_request'|'repo' +---@field type pending.ForgeType ---@field number? integer ---@field url string ---@class pending.ForgeCache ---@field title? string ----@field state 'open'|'closed'|'merged' +---@field state pending.ForgeState ---@field labels? string[] ---@field fetched_at string @@ -27,10 +31,10 @@ local log = require('pending.log') ---@field auth_status_args string[] ---@field default_icon string ---@field default_issue_format string ----@field _auth? 'unknown'|'ok'|'failed' +---@field _auth? pending.ForgeAuthStatus ---@field parse_url fun(self: pending.ForgeBackend, url: string): pending.ForgeRef? ---@field api_args fun(self: pending.ForgeBackend, ref: pending.ForgeRef): string[] ----@field parse_state fun(self: pending.ForgeBackend, decoded: table): 'open'|'closed'|'merged' +---@field parse_state fun(self: pending.ForgeBackend, decoded: table): pending.ForgeState ---@class pending.forge local M = {} diff --git a/lua/pending/init.lua b/lua/pending/init.lua index 9b642ed..e19bd7e 100644 --- a/lua/pending/init.lua +++ b/lua/pending/init.lua @@ -998,6 +998,14 @@ function M.add(text) log.info('Task added: ' .. description) end +---@class pending.SyncBackend +---@field name string +---@field auth fun(): nil +---@field push? fun(): nil +---@field pull? fun(): nil +---@field sync? fun(): nil +---@field health? fun(): nil + ---@type string[]? local _sync_backends = nil diff --git a/lua/pending/parse.lua b/lua/pending/parse.lua index 5a705ef..431c18d 100644 --- a/lua/pending/parse.lua +++ b/lua/pending/parse.lua @@ -4,7 +4,7 @@ local config = require('pending.config') ---@field due? string ---@field cat? string ---@field rec? string ----@field rec_mode? 'scheduled'|'completion' +---@field rec_mode? pending.RecurMode ---@field priority? integer ---@class pending.parse diff --git a/lua/pending/store.lua b/lua/pending/store.lua index fcf420e..5870fc6 100644 --- a/lua/pending/store.lua +++ b/lua/pending/store.lua @@ -1,19 +1,31 @@ local config = require('pending.config') +---@alias pending.TaskStatus 'pending'|'done'|'deleted'|'wip'|'blocked' +---@alias pending.RecurMode 'scheduled'|'completion' + +---@class pending.TaskExtra +---@field _forge_ref? pending.ForgeRef +---@field _forge_cache? pending.ForgeCache +---@field _gtasks_task_id? string +---@field _gtasks_list_id? string +---@field _gcal_event_id? string +---@field _gcal_calendar_id? string +---@field [string] any + ---@class pending.Task ---@field id integer ---@field description string ----@field status 'pending'|'done'|'deleted'|'wip'|'blocked' +---@field status pending.TaskStatus ---@field category? string ---@field priority integer ---@field due? string ---@field recur? string ----@field recur_mode? 'scheduled'|'completion' +---@field recur_mode? pending.RecurMode ---@field entry string ---@field modified string ---@field end? string ---@field order integer ----@field _extra? table +---@field _extra? pending.TaskExtra ---@class pending.Data ---@field version integer @@ -24,14 +36,14 @@ local config = require('pending.config') ---@class pending.TaskFields ---@field description string ----@field status? string +---@field status? pending.TaskStatus ---@field category? string ---@field priority? integer ---@field due? string ---@field recur? string ----@field recur_mode? string +---@field recur_mode? pending.RecurMode ---@field order? integer ----@field _extra? table +---@field _extra? pending.TaskExtra ---@class pending.Store ---@field path string diff --git a/lua/pending/sync/oauth.lua b/lua/pending/sync/oauth.lua index 8e670c1..a49595c 100644 --- a/lua/pending/sync/oauth.lua +++ b/lua/pending/sync/oauth.lua @@ -24,6 +24,15 @@ local BUNDLED_CLIENT_SECRET = 'PLACEHOLDER' ---@field config_key string ---@class pending.OAuthClient : pending.OAuthClientOpts +---@field token_path fun(self: pending.OAuthClient): string +---@field resolve_credentials fun(self: pending.OAuthClient): pending.OAuthCredentials +---@field load_tokens fun(self: pending.OAuthClient): pending.OAuthTokens? +---@field save_tokens fun(self: pending.OAuthClient, tokens: pending.OAuthTokens): boolean +---@field refresh_access_token fun(self: pending.OAuthClient, creds: pending.OAuthCredentials, tokens: pending.OAuthTokens): pending.OAuthTokens? +---@field get_access_token fun(self: pending.OAuthClient): string? +---@field setup fun(self: pending.OAuthClient): nil +---@field auth fun(self: pending.OAuthClient, on_complete?: fun(ok: boolean): nil): nil +---@field clear_tokens fun(self: pending.OAuthClient): nil local OAuthClient = {} OAuthClient.__index = OAuthClient diff --git a/lua/pending/views.lua b/lua/pending/views.lua index b1e691e..6fd1739 100644 --- a/lua/pending/views.lua +++ b/lua/pending/views.lua @@ -13,7 +13,7 @@ local parse = require('pending.parse') ---@field id? integer ---@field due? string ---@field raw_due? string ----@field status? string +---@field status? pending.TaskStatus ---@field category? string ---@field overdue? boolean ---@field show_category? boolean