fix(parser): fixes incorrect parsing of metadata tags and values (#111)

Should not parse malformed @tag(value)

Should correctly parse complex values, e.g. with nested parentheses

Author: bngarren

lua/checkmate/api.lua

@@ -1362,7 +1362,7 @@ function M.rebuild_line_with_sorted_metadata(line, metadata)
   local log = require("checkmate.log")
 
   -- remove all metadata tags but preserve all other content including whitespace
-  local content_without_metadata = line:gsub("@%w+%([^)]*%)", "")
+  local content_without_metadata = line:gsub("@[%a][%w_%-]*%b()", "")
 
   -- remove trailing whitespace but keep all indentation
   content_without_metadata = content_without_metadata:gsub("%s+$", "")
@@ -1373,7 +1373,6 @@ function M.rebuild_line_with_sorted_metadata(line, metadata)
 
   local sorted_entries = M.sort_metadata_entries(metadata.entries)
 
-  -- Rebuild the line with content and sorted metadata
   local result_line = content_without_metadata
 
   -- add back each metadata tag in sorted order

lua/checkmate/parser.lua

@@ -1,6 +1,7 @@
 local M = {}
 
 ---@alias checkmate.TodoItemState "checked" | "unchecked"
+--@alias checkmate.TodoItemState "checked" | "unchecked"
 
 --- @class TodoMarkerInfo
 --- @field position {row: integer, col: integer} Position of the marker (0-indexed)
@@ -63,7 +64,8 @@ local FULL_TODO_QUERY = vim.treesitter.query.parse(
 ]]
 )
 
-local METADATA_PATTERN = "@([%a][%w_%-]*)%(%s*(.-)%s*%)"
+-- match the @tag and then a balanced sequence %b(), which is everything in the outer parentheses
+local METADATA_PATTERN = "@([%a][%w_%-]*)(%b())"
 
 M.list_item_markers = { "-", "+", "*" }
 
@@ -774,27 +776,44 @@ function M.extract_metadata(line, row)
     by_tag = {},
   }
 
+  ---@param _line string String to search
+  ---@param from_byte_pos integer start looking at this byte position
+  ---@return string? tag, string? value, integer? start_byte, integer? end_byte
+  local function find_metadata(_line, from_byte_pos)
+    local s, e, tag, raw = _line:find(METADATA_PATTERN, from_byte_pos)
+    if not s or not e then
+      return nil
+    end
+
+    -- raw is "( ... )", so we gotta strip outer parens
+    local inner = raw:sub(2, -2)
+
+    -- trim whitespace
+    local value = inner:match("^%s*(.-)%s*$")
+
+    return tag, value, s, e
+  end
+
   -- find all @tag(value) patterns and their positions
   local byte_pos = 1
   while true do
-    -- will capture tag names that include underscores and hypens
-    local tag_start_byte, tag_end_byte, tag, value = line:find(METADATA_PATTERN, byte_pos)
-    if not tag_start_byte or not tag_end_byte then
+    local tag, value, start_byte, end_byte = find_metadata(line, byte_pos)
+    if not tag or not start_byte or not end_byte then
       break
     end
 
     ---@type checkmate.MetadataEntry
     local entry = {
       tag = tag,
-      value = value,
+      value = value or "",
       range = {
-        start = { row = row, col = tag_start_byte - 1 }, -- 0-indexed column
+        start = { row = row, col = start_byte - 1 }, -- 0-indexed column
         -- For the end col, we need 0 indexed (subtract 1) and since it is end-exclusive we add 1, cancelling out
         -- end-exclusive means the end col points to the pos after the last char
-        ["end"] = { row = row, col = tag_end_byte },
+        ["end"] = { row = row, col = end_byte },
       },
       alias_for = nil, -- Will be set later if it's an alias
-      position_in_line = tag_start_byte, -- track original position in the line, use byte pos for sorting
+      position_in_line = start_byte, -- track original position in the line, use byte pos for sorting
     }
 
     -- check if this is an alias and map to canonical name
@@ -827,10 +846,10 @@ function M.extract_metadata(line, row)
     end
 
     -- move position for next search
-    byte_pos = tag_end_byte + 1
+    byte_pos = end_byte + 1
 
     log.debug(
-      string.format("Metadata found: %s=%s at [%d,%d]-[%d,%d]", tag, value, row, tag_start_byte - 1, row, tag_end_byte),
+      string.format("Metadata found: %s=%s at [%d,%d]-[%d,%d]", tag, value, row, start_byte - 1, row, end_byte),
       { module = "parser" }
     )
   end

tests/checkmate/api_spec.lua

@@ -743,6 +743,37 @@ Line 2
       end)
     end)
 
+    it("should remove metadata with complex value", function()
+      local config = require("checkmate.config")
+      local unchecked = config.get_defaults().todo_markers.unchecked
+      local file_path = h.create_temp_file()
+
+      local content = [[
+- [ ] Task @issue(issue #1 - fix(api): broken! @author)
+      ]]
+
+      local bufnr = setup_todo_buffer(file_path, content, {})
+
+      local todo_map = require("checkmate.parser").discover_todos(bufnr)
+      local first_todo = h.find_todo_by_text(todo_map, "- " .. unchecked .. " Task @issue")
+
+      assert.is_not_nil(first_todo)
+      ---@cast first_todo checkmate.TodoItem
+
+      assert.is_not_nil(first_todo.metadata)
+      assert.is_true(#first_todo.metadata.entries > 0)
+
+      -- remove @issue
+      vim.api.nvim_win_set_cursor(0, { first_todo.range.start.row + 1, 0 }) -- adjust from 0 index to 1-indexed
+      require("checkmate").remove_metadata("issue")
+
+      vim.cmd("sleep 10m")
+      local lines = vim.api.nvim_buf_get_lines(bufnr, 0, -1, false)
+
+      assert.no.matches("@issue", lines[1])
+      assert.matches("- " .. vim.pesc(unchecked) .. " Task", lines[1])
+    end)
+
     it("should remove all metadata from todo items", function()
       local config = require("checkmate.config")
       local unchecked = config.get_defaults().todo_markers.unchecked

tests/checkmate/parser_spec.lua

@@ -629,6 +629,18 @@ Line that should not affect parent-child relationship
       assert.same(metadata.entries[3], metadata.by_tag.tags)
     end)
 
+    it("should not malformed metadata", function()
+      local parser = require("checkmate.parser")
+
+      -- space between @tag and ()
+      local line = "- □ Task @tag (value)"
+      local row = 0
+
+      local metadata = parser.extract_metadata(line, row)
+
+      assert.equal(0, #metadata.entries)
+    end)
+
     it("should handle metadata with spaces in values", function()
       local parser = require("checkmate.parser")
       local line = "- □ Task @note(this is a note with spaces)"
@@ -650,7 +662,19 @@ Line that should not affect parent-child relationship
 
       assert.equal(1, #metadata.entries)
       assert.equal("note", metadata.entries[1].tag)
-      assert.equal("spaced value", metadata.entries[1].value) -- Spaces should be trimmed
+      assert.equal("spaced value", metadata.entries[1].value)
+    end)
+
+    it("should handle metadata with parentheses in value", function()
+      local parser = require("checkmate.parser")
+      local line = "- □ Task @issue(fix(api))"
+      local row = 0
+
+      local metadata = parser.extract_metadata(line, row)
+
+      assert.equal(1, #metadata.entries)
+      assert.equal("issue", metadata.entries[1].tag)
+      assert.equal("fix(api)", metadata.entries[1].value)
     end)
 
     it("should properly track position_in_line", function()