Allow checks for inadvertent AST modifications

This check is enabled when the QUARTO_JOG_CHECK environment variable is
set.

Author: tarleb

src/resources/filters/ast/runemulation.lua

@@ -47,6 +47,95 @@ local function remove_vault(doc)
   end
 end
 
+--- Create a deep copy of a table.
+local function copy_table (tbl, depth)
+  if type(tbl) == 'table' then
+    if tbl.clone then
+      return tbl:clone()
+    end
+
+    local copy = {}
+    -- Iterate 'raw' pairs, i.e., without using metamethods
+    for key, value in next, tbl, nil do
+      if depth == 'shallow' then
+        copy[key] = value
+      else
+        copy[copy_table(key)] = copy_table(value)
+      end
+    end
+    return setmetatable(copy, getmetatable(tbl))
+  elseif type(tbl) == 'userdata' then
+    return tbl:clone()
+  else -- number, string, boolean, etc
+    return tbl
+  end
+end
+
+--- Checks if two tables are equal
+function equals(o1, o2)
+  if o1 == o2 then
+    return true
+  end
+  local o1type = type(o1)
+  local o2type = type(o2)
+  if o1type ~= o2type or o1type ~= 'table' then
+    return false
+  end
+
+  local keys = {}
+
+  for key1, value1 in pairs(o1) do
+    local value2 = o2[key1]
+    if value2 == nil or equals(value1, value2) == false then
+      return false
+    end
+    keys[key1] = true
+  end
+
+  for key2, _ in pairs(o2) do
+    if not keys[key2] then return false end
+  end
+  return true
+end
+
+--- Checks if a filter follows the "nondestructive" property.
+-- The nondestructive property is fulfilled if filter functions returns
+-- an explicit object, or if it returns `nil` while leaving the passed
+-- in object unmodified.
+--
+-- An error is raised if the property is violated.
+--
+-- Only filters with this property can use jog safely, without
+-- unintended consequences.
+local function check_nondestructive_property (namedfilter)
+  for name, fn in pairs(namedfilter.filter) do
+    if type(fn) == 'function' then
+      local copy = function (x)
+        return type(x) == 'table' and copy_table(x) or x:clone()
+      end
+      namedfilter.filter[name] = function (obj, context)
+        local orig = copy(obj)
+        local result, descend = fn(obj, context)
+        if result == nil then
+          if not equals(obj, orig) then
+            warn(
+              "\nFunction '" .. name .. "' in filter '" .. namedfilter.name ..
+              "' returned `nil`, but modified the input."
+            )
+          end
+        -- elseif result.t == obj.t and not rawequal(result, obj) then
+        --   warn(
+        --     "\nFunction '" .. name .. "' in filter '" .. namedfilter.name ..
+        --     "' returned a new object instead of passing the original one through."
+        --   )
+        end
+        return result, descend
+      end
+    end
+  end
+  return namedfilter
+end
+
 local function run_emulated_filter_chain(doc, filters, afterFilterPass, profiling)
   init_trace(doc)
   local compare_jog_and_walk = os.getenv 'QUARTO_JOG_CHECK'
@@ -82,17 +171,9 @@ local function run_emulated_filter_chain(doc, filters, afterFilterPass, profilin
         _quarto.ast._current_doc = doc
 
         if compare_jog_and_walk and not v.force_pandoc_walk then
-          local expected = run_emulated_filter(doc:clone(), v.filter, true)
-          doc = run_emulated_filter(doc:clone(), v.filter, false)
-          if doc == expected then
-            io.stderr:write("[ OK ] " .. v.name .. '\n')
-          else
-            io.stderr:write("[FAIL] " .. v.name .. '\n')
-            doc = expected
-          end
-        else
-          doc = run_emulated_filter(doc, v.filter, v.force_pandoc_walk)
+          v = check_nondestructive_property(v)
         end
+        doc = run_emulated_filter(doc, v.filter, v.force_pandoc_walk)
 
         ensure_vault(doc)