3eacefe18d
Extracts H3-headers from README ## API section. Pattern handles
optional namespace-prefix (e.g. 'input.bind' -> 'bind'). Returns
{ documented = [...] } per spec section 4.2.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
44 lines
1.8 KiB
Lua
44 lines
1.8 KiB
Lua
-- lib-core.api-discovery — Pure-Lua surface-discovery + README-parsing.
|
|
-- See: meta/docs/superpowers/specs/2026-05-16-api-doc-convention-design.md
|
|
local M = {}
|
|
|
|
-- Extracts public/private surface from Lua source code.
|
|
-- Convention: `M.<name> = function(...)` is public; `M._<name> = ...` is private.
|
|
-- Returns: { public = ["foo","bar",...], private = ["_baz",...] }
|
|
function M.parse_lua_surface(source_string)
|
|
local public = {}
|
|
local private = {}
|
|
for name in string.gmatch(source_string, "M%.([_%w]+)%s*=%s*function") do
|
|
if string.sub(name, 1, 1) == "_" then
|
|
table.insert(private, name)
|
|
else
|
|
table.insert(public, name)
|
|
end
|
|
end
|
|
return { public = public, private = private }
|
|
end
|
|
|
|
-- Extracts documented function-names from README's "## API" section.
|
|
-- Parses H3-Headers like "### `input.bind(action_name, keys)`" → "bind".
|
|
-- Convention: H3 header opens with backtick, function-name follows after optional namespace-dot.
|
|
-- Returns: { documented = ["bind","unbind",...] }
|
|
function M.parse_readme_api(markdown_string)
|
|
local documented = {}
|
|
-- Find "## API" section start (allow trailing whitespace/content)
|
|
local api_start = string.find(markdown_string, "\n## API[%s\n]")
|
|
if not api_start then
|
|
return { documented = documented }
|
|
end
|
|
-- Find next H2 (terminate API section)
|
|
local api_end = string.find(markdown_string, "\n## ", api_start + 5)
|
|
local section = string.sub(markdown_string, api_start, api_end or #markdown_string)
|
|
|
|
-- Match H3 headers: "### `[namespace.]name(...)`" — capture name portion
|
|
for line in string.gmatch(section, "###%s+`[^.`]*%.?([_%w]+)%s*[%(`]") do
|
|
table.insert(documented, line)
|
|
end
|
|
return { documented = documented }
|
|
end
|
|
|
|
return M
|