feat(recur): add recurrence parsing and next-date computation

Problem: the plugin has no concept of recurring tasks, which is
needed for habits and repeating deadlines.

Solution: add recur.lua with parse(), validate(), next_due(),
to_rrule(), and shorthand_list(). Supports named shorthands (daily,
weekdays, weekly, etc.), interval notation (Nd, Nw, Nm, Ny), raw
RRULE passthrough, and ! prefix for completion-based mode. Includes
day-clamping for month/year advancement.

lua/pending/recur.lua

@@ -0,0 +1,160 @@
+---@class pending.RecurSpec
+---@field freq 'daily'|'weekly'|'monthly'|'yearly'
+---@field interval integer
+---@field byday? string[]
+---@field from_completion boolean
+
+---@class pending.recur
+local M = {}
+
+---@type table<string, pending.RecurSpec>
+local named = {
+  daily = { freq = 'daily', interval = 1, from_completion = false },
+  weekdays = { freq = 'weekly', interval = 1, byday = { 'MO', 'TU', 'WE', 'TH', 'FR' }, from_completion = false },
+  weekly = { freq = 'weekly', interval = 1, from_completion = false },
+  biweekly = { freq = 'weekly', interval = 2, from_completion = false },
+  monthly = { freq = 'monthly', interval = 1, from_completion = false },
+  quarterly = { freq = 'monthly', interval = 3, from_completion = false },
+  yearly = { freq = 'yearly', interval = 1, from_completion = false },
+  annual = { freq = 'yearly', interval = 1, from_completion = false },
+}
+
+---@param spec string
+---@return pending.RecurSpec?
+function M.parse(spec)
+  local from_completion = false
+  local s = spec
+
+  if s:sub(1, 1) == '!' then
+    from_completion = true
+    s = s:sub(2)
+  end
+
+  local lower = s:lower()
+
+  local base = named[lower]
+  if base then
+    return {
+      freq = base.freq,
+      interval = base.interval,
+      byday = base.byday,
+      from_completion = from_completion,
+    }
+  end
+
+  local n, unit = lower:match('^(%d+)([dwmy])$')
+  if n then
+    local num = tonumber(n) --[[@as integer]]
+    if num < 1 then
+      return nil
+    end
+    local freq_map = { d = 'daily', w = 'weekly', m = 'monthly', y = 'yearly' }
+    return {
+      freq = freq_map[unit],
+      interval = num,
+      from_completion = from_completion,
+    }
+  end
+
+  if s:match('^FREQ=') then
+    return {
+      freq = 'daily',
+      interval = 1,
+      from_completion = from_completion,
+      _raw = s,
+    }
+  end
+
+  return nil
+end
+
+---@param spec string
+---@return boolean
+function M.validate(spec)
+  return M.parse(spec) ~= nil
+end
+
+---@param base_date string
+---@param freq string
+---@param interval integer
+---@return string
+local function advance_date(base_date, freq, interval)
+  local y, m, d = base_date:match('^(%d+)-(%d+)-(%d+)$')
+  local yn = tonumber(y) --[[@as integer]]
+  local mn = tonumber(m) --[[@as integer]]
+  local dn = tonumber(d) --[[@as integer]]
+
+  if freq == 'daily' then
+    return os.date('%Y-%m-%d', os.time({ year = yn, month = mn, day = dn + interval })) --[[@as string]]
+  elseif freq == 'weekly' then
+    return os.date('%Y-%m-%d', os.time({ year = yn, month = mn, day = dn + interval * 7 })) --[[@as string]]
+  elseif freq == 'monthly' then
+    local new_m = mn + interval
+    local new_y = yn
+    while new_m > 12 do
+      new_m = new_m - 12
+      new_y = new_y + 1
+    end
+    local last_day = os.date('*t', os.time({ year = new_y, month = new_m + 1, day = 0 })) --[[@as osdate]]
+    local clamped_d = math.min(dn, last_day.day)
+    return os.date('%Y-%m-%d', os.time({ year = new_y, month = new_m, day = clamped_d })) --[[@as string]]
+  elseif freq == 'yearly' then
+    local new_y = yn + interval
+    local last_day = os.date('*t', os.time({ year = new_y, month = mn + 1, day = 0 })) --[[@as osdate]]
+    local clamped_d = math.min(dn, last_day.day)
+    return os.date('%Y-%m-%d', os.time({ year = new_y, month = mn, day = clamped_d })) --[[@as string]]
+  end
+  return base_date
+end
+
+---@param base_date string
+---@param spec string
+---@param mode 'scheduled'|'completion'
+---@return string
+function M.next_due(base_date, spec, mode)
+  local parsed = M.parse(spec)
+  if not parsed then
+    return base_date
+  end
+
+  local today = os.date('%Y-%m-%d') --[[@as string]]
+
+  if mode == 'completion' then
+    return advance_date(today, parsed.freq, parsed.interval)
+  end
+
+  local next_date = advance_date(base_date, parsed.freq, parsed.interval)
+  while next_date <= today do
+    next_date = advance_date(next_date, parsed.freq, parsed.interval)
+  end
+  return next_date
+end
+
+---@param spec string
+---@return string
+function M.to_rrule(spec)
+  local parsed = M.parse(spec)
+  if not parsed then
+    return ''
+  end
+
+  if parsed._raw then
+    return 'RRULE:' .. parsed._raw
+  end
+
+  local parts = { 'FREQ=' .. parsed.freq:upper() }
+  if parsed.interval > 1 then
+    table.insert(parts, 'INTERVAL=' .. parsed.interval)
+  end
+  if parsed.byday then
+    table.insert(parts, 'BYDAY=' .. table.concat(parsed.byday, ','))
+  end
+  return 'RRULE:' .. table.concat(parts, ';')
+end
+
+---@return string[]
+function M.shorthand_list()
+  return { 'daily', 'weekdays', 'weekly', 'biweekly', 'monthly', 'quarterly', 'yearly', 'annual' }
+end
+
+return M

spec/recur_spec.lua

@@ -0,0 +1,220 @@
+require('spec.helpers')
+
+describe('recur', function()
+  local recur = require('pending.recur')
+
+  describe('parse', function()
+    it('parses daily', function()
+      local r = recur.parse('daily')
+      assert.are.equal('daily', r.freq)
+      assert.are.equal(1, r.interval)
+      assert.is_false(r.from_completion)
+    end)
+
+    it('parses weekdays', function()
+      local r = recur.parse('weekdays')
+      assert.are.equal('weekly', r.freq)
+      assert.are.same({ 'MO', 'TU', 'WE', 'TH', 'FR' }, r.byday)
+    end)
+
+    it('parses weekly', function()
+      local r = recur.parse('weekly')
+      assert.are.equal('weekly', r.freq)
+      assert.are.equal(1, r.interval)
+    end)
+
+    it('parses biweekly', function()
+      local r = recur.parse('biweekly')
+      assert.are.equal('weekly', r.freq)
+      assert.are.equal(2, r.interval)
+    end)
+
+    it('parses monthly', function()
+      local r = recur.parse('monthly')
+      assert.are.equal('monthly', r.freq)
+      assert.are.equal(1, r.interval)
+    end)
+
+    it('parses quarterly', function()
+      local r = recur.parse('quarterly')
+      assert.are.equal('monthly', r.freq)
+      assert.are.equal(3, r.interval)
+    end)
+
+    it('parses yearly', function()
+      local r = recur.parse('yearly')
+      assert.are.equal('yearly', r.freq)
+      assert.are.equal(1, r.interval)
+    end)
+
+    it('parses annual as yearly', function()
+      local r = recur.parse('annual')
+      assert.are.equal('yearly', r.freq)
+    end)
+
+    it('parses 3d as every 3 days', function()
+      local r = recur.parse('3d')
+      assert.are.equal('daily', r.freq)
+      assert.are.equal(3, r.interval)
+    end)
+
+    it('parses 2w as biweekly', function()
+      local r = recur.parse('2w')
+      assert.are.equal('weekly', r.freq)
+      assert.are.equal(2, r.interval)
+    end)
+
+    it('parses 6m as every 6 months', function()
+      local r = recur.parse('6m')
+      assert.are.equal('monthly', r.freq)
+      assert.are.equal(6, r.interval)
+    end)
+
+    it('parses 2y as every 2 years', function()
+      local r = recur.parse('2y')
+      assert.are.equal('yearly', r.freq)
+      assert.are.equal(2, r.interval)
+    end)
+
+    it('parses ! prefix as completion-based', function()
+      local r = recur.parse('!weekly')
+      assert.are.equal('weekly', r.freq)
+      assert.is_true(r.from_completion)
+    end)
+
+    it('parses raw RRULE fragment', function()
+      local r = recur.parse('FREQ=MONTHLY;BYDAY=1MO')
+      assert.is_not_nil(r)
+    end)
+
+    it('returns nil for invalid input', function()
+      assert.is_nil(recur.parse(''))
+      assert.is_nil(recur.parse('garbage'))
+      assert.is_nil(recur.parse('0d'))
+    end)
+
+    it('is case insensitive', function()
+      local r = recur.parse('Weekly')
+      assert.are.equal('weekly', r.freq)
+    end)
+  end)
+
+  describe('validate', function()
+    it('returns true for valid specs', function()
+      assert.is_true(recur.validate('daily'))
+      assert.is_true(recur.validate('2w'))
+      assert.is_true(recur.validate('!monthly'))
+    end)
+
+    it('returns false for invalid specs', function()
+      assert.is_false(recur.validate('garbage'))
+      assert.is_false(recur.validate(''))
+    end)
+  end)
+
+  describe('next_due', function()
+    it('advances daily by 1 day', function()
+      local result = recur.next_due('2099-03-01', 'daily', 'scheduled')
+      assert.are.equal('2099-03-02', result)
+    end)
+
+    it('advances weekly by 7 days', function()
+      local result = recur.next_due('2099-03-01', 'weekly', 'scheduled')
+      assert.are.equal('2099-03-08', result)
+    end)
+
+    it('advances monthly and clamps day', function()
+      local result = recur.next_due('2099-01-31', 'monthly', 'scheduled')
+      assert.are.equal('2099-02-28', result)
+    end)
+
+    it('advances yearly and handles leap year', function()
+      local result = recur.next_due('2096-02-29', 'yearly', 'scheduled')
+      assert.are.equal('2097-02-28', result)
+    end)
+
+    it('advances biweekly by 14 days', function()
+      local result = recur.next_due('2099-03-01', 'biweekly', 'scheduled')
+      assert.are.equal('2099-03-15', result)
+    end)
+
+    it('advances quarterly by 3 months', function()
+      local result = recur.next_due('2099-01-15', 'quarterly', 'scheduled')
+      assert.are.equal('2099-04-15', result)
+    end)
+
+    it('scheduled mode skips to future if overdue', function()
+      local result = recur.next_due('2020-01-01', 'yearly', 'scheduled')
+      local today = os.date('%Y-%m-%d') --[[@as string]]
+      assert.is_true(result > today)
+    end)
+
+    it('completion mode advances from today', function()
+      local today = os.date('*t') --[[@as osdate]]
+      local expected = os.date('%Y-%m-%d', os.time({
+        year = today.year,
+        month = today.month,
+        day = today.day + 7,
+      }))
+      local result = recur.next_due('2020-01-01', 'weekly', 'completion')
+      assert.are.equal(expected, result)
+    end)
+
+    it('advances 3d by 3 days', function()
+      local result = recur.next_due('2099-06-10', '3d', 'scheduled')
+      assert.are.equal('2099-06-13', result)
+    end)
+  end)
+
+  describe('to_rrule', function()
+    it('converts daily', function()
+      assert.are.equal('RRULE:FREQ=DAILY', recur.to_rrule('daily'))
+    end)
+
+    it('converts weekly', function()
+      assert.are.equal('RRULE:FREQ=WEEKLY', recur.to_rrule('weekly'))
+    end)
+
+    it('converts biweekly with interval', function()
+      assert.are.equal('RRULE:FREQ=WEEKLY;INTERVAL=2', recur.to_rrule('biweekly'))
+    end)
+
+    it('converts weekdays with BYDAY', function()
+      assert.are.equal('RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR', recur.to_rrule('weekdays'))
+    end)
+
+    it('converts monthly', function()
+      assert.are.equal('RRULE:FREQ=MONTHLY', recur.to_rrule('monthly'))
+    end)
+
+    it('converts quarterly with interval', function()
+      assert.are.equal('RRULE:FREQ=MONTHLY;INTERVAL=3', recur.to_rrule('quarterly'))
+    end)
+
+    it('converts yearly', function()
+      assert.are.equal('RRULE:FREQ=YEARLY', recur.to_rrule('yearly'))
+    end)
+
+    it('converts 2w with interval', function()
+      assert.are.equal('RRULE:FREQ=WEEKLY;INTERVAL=2', recur.to_rrule('2w'))
+    end)
+
+    it('prefixes raw RRULE fragment', function()
+      assert.are.equal('RRULE:FREQ=MONTHLY;BYDAY=1MO', recur.to_rrule('FREQ=MONTHLY;BYDAY=1MO'))
+    end)
+
+    it('returns empty string for invalid spec', function()
+      assert.are.equal('', recur.to_rrule('garbage'))
+    end)
+  end)
+
+  describe('shorthand_list', function()
+    it('returns a list of named shorthands', function()
+      local list = recur.shorthand_list()
+      assert.is_true(#list >= 8)
+      assert.is_true(vim.tbl_contains(list, 'daily'))
+      assert.is_true(vim.tbl_contains(list, 'weekly'))
+      assert.is_true(vim.tbl_contains(list, 'monthly'))
+    end)
+  end)
+end)