From 0457d5c798a2d2eb5a1e27318e12f60c764f0ab2 Mon Sep 17 00:00:00 2001
From: Axel Meyer <axel.meyer@durania.net>
Date: Sat, 16 May 2026 13:22:57 +0200
Subject: [PATCH] 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 | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/init.lua b/init.lua
index 98da418..3617a7f 100644
--- a/init.lua
+++ b/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