refactor: centralize type definitions in dedicated types.lua module

Change-Id: Idfbb1d15fac498475ddc517f85f86838cb19322c
Signed-off-by: Thomas Kosiewski <[email protected]>

Author: ThomasK33

lua/claudecode/config.lua

@@ -6,36 +6,7 @@
 
 local M = {}
 
--- Types (authoritative for configuration shape):
----@class ClaudeCode.DiffOptions
----@field auto_close_on_accept boolean
----@field show_diff_stats boolean
----@field vertical_split boolean
----@field open_in_current_tab boolean
----@field keep_terminal_focus boolean
-
----@class ClaudeCode.ModelOption
----@field name string
----@field value string
-
----@alias ClaudeCode.LogLevel "trace"|"debug"|"info"|"warn"|"error"
-
----@class ClaudeCode.Config
----@field port_range {min: integer, max: integer}
----@field auto_start boolean
----@field terminal_cmd string|nil
----@field env table<string, string>
----@field log_level ClaudeCode.LogLevel
----@field track_selection boolean
----@field visual_demotion_delay_ms number
----@field connection_wait_delay number
----@field connection_timeout number
----@field queue_timeout number
----@field diff_opts ClaudeCode.DiffOptions
----@field models ClaudeCode.ModelOption[]
----@field disable_broadcast_debouncing? boolean
----@field enable_broadcast_debouncing_in_tests? boolean
----@field terminal TerminalConfig|nil
+---@type ClaudeCodeConfig
 M.defaults = {
   port_range = { min = 10000, max = 65535 },
   auto_start = true,
@@ -138,7 +109,7 @@ end
 
 ---Applies user configuration on top of default settings and validates the result.
 ---@param user_config table|nil The user-provided configuration table.
----@return ClaudeCode.Config config The final, validated configuration table.
+---@return ClaudeCodeConfig config The final, validated configuration table.
 function M.apply(user_config)
   local config = vim.deepcopy(M.defaults)
 

lua/claudecode/init.lua

@@ -9,35 +9,8 @@ local M = {}
 
 local logger = require("claudecode.logger")
 
--- Types
-
----@class ClaudeCode.Version
----@field major integer
----@field minor integer
----@field patch integer
----@field prerelease? string
----@field string fun(self: ClaudeCode.Version):string
-
--- Narrow facade of the server module used by this file
----@class ClaudeCode.ServerFacade
----@field start fun(config: ClaudeCode.Config, auth_token: string|nil): boolean, number|string
----@field stop fun(): boolean, string|nil
----@field broadcast fun(method: string, params: table|nil): boolean
----@field get_status fun(): { running: boolean, port: integer|nil, client_count: integer, clients?: table }
-
--- State type for this module
----@class ClaudeCode.State
----@field config ClaudeCode.Config
----@field server ClaudeCode.ServerFacade|nil
----@field port integer|nil
----@field auth_token string|nil
----@field initialized boolean
----@field mention_queue table[]
----@field mention_timer table|nil
----@field connection_timer table|nil
-
 --- Current plugin version
----@type ClaudeCode.Version
+---@type ClaudeCodeVersion
 M.version = {
   major = 0,
   minor = 2,
@@ -53,7 +26,7 @@ M.version = {
 }
 
 -- Module state
----@type ClaudeCode.State
+---@type ClaudeCodeState
 M.state = {
   config = require("claudecode.config").defaults,
   server = nil,
@@ -314,7 +287,7 @@ function M.send_at_mention(file_path, start_line, end_line, context)
 end
 
 ---Set up the plugin with user configuration
----@param opts ClaudeCode.Config|nil Optional configuration table to override defaults.
+---@param opts ClaudeCodeConfig|nil Optional configuration table to override defaults.
 ---@return table module The plugin module
 function M.setup(opts)
   opts = opts or {}

lua/claudecode/logger.lua

@@ -22,7 +22,7 @@ local level_values = {
 local current_log_level_value = M.levels.INFO
 
 ---Setup the logger module
----@param plugin_config ClaudeCode.Config The configuration table (e.g., from claudecode.init.state.config).
+---@param plugin_config ClaudeCodeConfig The configuration table (e.g., from claudecode.init.state.config).
 function M.setup(plugin_config)
   local conf = plugin_config
 
@@ -119,7 +119,7 @@ function M.info(component, ...)
 end
 
 ---Check if a specific log level is enabled
----@param level_name ClaudeCode.LogLevel The level name ("error", "warn", "info", "debug", "trace")
+---@param level_name ClaudeCodeLogLevel The level name ("error", "warn", "info", "debug", "trace")
 ---@return boolean enabled Whether the level is enabled
 function M.is_level_enabled(level_name)
   local level_value = level_values[level_name]

lua/claudecode/types.lua

@@ -0,0 +1,87 @@
+---@brief [[
+--- Centralized type definitions for ClaudeCode.nvim public API.
+--- This module contains all user-facing types and configuration structures.
+---@brief ]]
+---@module 'claudecode.types'
+
+-- Version information type
+---@class ClaudeCodeVersion
+---@field major integer
+---@field minor integer
+---@field patch integer
+---@field prerelease? string
+---@field string fun(self: ClaudeCodeVersion): string
+
+-- Diff behavior configuration
+---@class ClaudeCodeDiffOptions
+---@field auto_close_on_accept boolean
+---@field show_diff_stats boolean
+---@field vertical_split boolean
+---@field open_in_current_tab boolean
+---@field keep_terminal_focus boolean
+
+-- Model selection option
+---@class ClaudeCodeModelOption
+---@field name string
+---@field value string
+
+-- Log level type alias
+---@alias ClaudeCodeLogLevel "trace"|"debug"|"info"|"warn"|"error"
+
+-- @ mention queued for Claude Code
+---@class ClaudeCodeMention
+---@field file_path string The absolute file path to mention
+---@field start_line number? Optional start line (0-indexed for Claude compatibility)
+---@field end_line number? Optional end line (0-indexed for Claude compatibility)
+---@field timestamp number Creation timestamp from vim.loop.now() for expiry tracking
+
+-- Port range configuration
+---@class ClaudeCodePortRange
+---@field min integer
+---@field max integer
+
+-- Server status information
+---@class ClaudeCodeServerStatus
+---@field running boolean
+---@field port integer?
+---@field client_count integer
+---@field clients? table<string, any>
+
+-- Main configuration structure
+---@class ClaudeCodeConfig
+---@field port_range ClaudeCodePortRange
+---@field auto_start boolean
+---@field terminal_cmd string|nil
+---@field env table<string, string>
+---@field log_level ClaudeCodeLogLevel
+---@field track_selection boolean
+---@field visual_demotion_delay_ms number
+---@field connection_wait_delay number
+---@field connection_timeout number
+---@field queue_timeout number
+---@field diff_opts ClaudeCodeDiffOptions
+---@field models ClaudeCodeModelOption[]
+---@field disable_broadcast_debouncing? boolean
+---@field enable_broadcast_debouncing_in_tests? boolean
+---@field terminal TerminalConfig|nil
+
+-- Server interface for main module
+---@class ClaudeCodeServerFacade
+---@field start fun(config: ClaudeCodeConfig, auth_token: string|nil): (success: boolean, port_or_error: number|string)
+---@field stop fun(): (success: boolean, error_message: string?)
+---@field broadcast fun(method: string, params: table?): boolean
+---@field get_status fun(): ClaudeCodeServerStatus
+
+-- Main module state
+---@class ClaudeCodeState
+---@field config ClaudeCodeConfig
+---@field server ClaudeCodeServerFacade|nil
+---@field port integer|nil
+---@field auth_token string|nil
+---@field initialized boolean
+---@field mention_queue ClaudeCodeMention[]
+---@field mention_timer uv.uv_timer_t?  -- (compatible with vim.loop timer)
+---@field connection_timer uv.uv_timer_t?  -- (compatible with vim.loop timer)
+
+-- This module only defines types, no runtime functionality
+return {}