feat: add diff_surface (S2 Phase 1)

Set-difference between code-surface.public and README documented-list.
Returns { missing_docs, stale_docs } sorted, per spec section 4.2.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

init.lua

@@ -40,4 +40,25 @@ function M.parse_readme_api(markdown_string)
     return { documented = documented }
 end
 
+-- Diffs code-surface vs README-doc.
+-- Compares surface.public (set) vs readme.documented (set).
+-- Returns: { missing_docs = [...], stale_docs = [...] }
+function M.diff_surface(surface, readme)
+    local public_set = {}
+    for _, name in ipairs(surface.public) do public_set[name] = true end
+    local doc_set = {}
+    for _, name in ipairs(readme.documented) do doc_set[name] = true end
+
+    local missing = {}
+    for name in pairs(public_set) do
+        if not doc_set[name] then table.insert(missing, name) end
+    end
+    local stale = {}
+    for name in pairs(doc_set) do
+        if not public_set[name] then table.insert(stale, name) end
+    end
+    table.sort(missing); table.sort(stale)
+    return { missing_docs = missing, stale_docs = stale }
+end
+
 return M