assay/
metadata.rs

1/// LDoc-style metadata parsed from `--- @tag value` lines at the top of a Lua module.
2#[derive(Debug, Clone, Default)]
3pub struct ModuleMetadata {
4    /// From `@module` tag
5    pub module_name: String,
6    /// From `@description` tag
7    pub description: String,
8    /// From `@keywords` tag, split by comma and trimmed
9    pub keywords: Vec<String>,
10    /// From `@env` tag, split by comma and trimmed
11    pub env_vars: Vec<String>,
12    /// From `@quickref` tags (one per tag line)
13    pub quickrefs: Vec<QuickRef>,
14    /// Auto-extracted function names from `function c:method(` and `function M.method(` patterns
15    pub auto_functions: Vec<String>,
16}
17
18/// A quick-reference entry parsed from `@quickref signature -> return_hint | description`.
19#[derive(Debug, Clone, Default)]
20pub struct QuickRef {
21    /// e.g. `c:health()`
22    pub signature: String,
23    /// e.g. `{database, version, commit}`
24    pub return_hint: String,
25    /// e.g. `Check Grafana health`
26    pub description: String,
27}
28
29/// Parse LDoc-style metadata from a Lua source string.
30///
31/// 1. Parses `--- @tag value` lines at the TOP of the file (stops at first non-`---` line).
32/// 2. Auto-extracts function names from `function c:method_name(` and `function M.method_name(`
33///    patterns across the entire file.
34///
35/// Never panics — returns a valid [`ModuleMetadata`] even on empty or malformed input.
36pub fn parse_metadata(source: &str) -> ModuleMetadata {
37    let mut meta = ModuleMetadata::default();
38
39    parse_header_tags(source, &mut meta);
40    extract_auto_functions(source, &mut meta);
41
42    meta
43}
44
45/// Parse `--- @tag value` lines from the top of the file, stopping at the first non-`---` line.
46fn parse_header_tags(source: &str, meta: &mut ModuleMetadata) {
47    for line in source.lines() {
48        let trimmed = line.trim();
49
50        if !trimmed.starts_with("---") {
51            break;
52        }
53
54        // Strip the `--- ` prefix and look for `@tag`
55        let after_dashes = trimmed.trim_start_matches('-').trim();
56        if let Some(rest) = after_dashes.strip_prefix('@')
57            && let Some((tag, value)) = rest.split_once(char::is_whitespace)
58        {
59            let value = value.trim();
60            match tag {
61                "module" => meta.module_name = value.to_string(),
62                "description" => meta.description = value.to_string(),
63                "keywords" => {
64                    meta.keywords = split_comma_list(value);
65                }
66                "env" => {
67                    meta.env_vars = split_comma_list(value);
68                }
69                "quickref" => {
70                    if let Some(qr) = parse_quickref(value) {
71                        meta.quickrefs.push(qr);
72                    }
73                }
74                _ => {} // Unknown tags silently ignored
75            }
76        }
77    }
78}
79
80/// Split a comma-separated string into trimmed, non-empty items.
81fn split_comma_list(value: &str) -> Vec<String> {
82    value
83        .split(',')
84        .map(|s| s.trim().to_string())
85        .filter(|s| !s.is_empty())
86        .collect()
87}
88
89/// Parse a quickref value: `signature -> return_hint | description`
90fn parse_quickref(value: &str) -> Option<QuickRef> {
91    // Split on ` -> ` first to get signature and the rest
92    let (signature, rest) = value.split_once(" -> ")?;
93    // Split the rest on ` | ` to get return_hint and description
94    let (return_hint, description) = rest.split_once(" | ")?;
95
96    Some(QuickRef {
97        signature: signature.trim().to_string(),
98        return_hint: return_hint.trim().to_string(),
99        description: description.trim().to_string(),
100    })
101}
102
103/// Scan the entire source for `function c:method_name(` and `function M.method_name(` patterns,
104/// extracting the method/function name.
105fn extract_auto_functions(source: &str, meta: &mut ModuleMetadata) {
106    for line in source.lines() {
107        let trimmed = line.trim();
108
109        // Match `function <ident>:<name>(` or `function <ident>.<name>(`
110        if let Some(rest) = trimmed.strip_prefix("function ") {
111            // Find the separator (`:` or `.`) after the identifier
112            if let Some(name) = extract_function_name(rest)
113                && !name.is_empty()
114            {
115                meta.auto_functions.push(name);
116            }
117        }
118    }
119}
120
121/// Extract function name from patterns like `c:health()` or `M.client(url, opts)`.
122/// Returns the part after `:` or `.` and before `(`.
123fn extract_function_name(rest: &str) -> Option<String> {
124    // Find the separator position (first `:` or `.`)
125    let sep_pos = rest.find([':', '.'])?;
126    let after_sep = &rest[sep_pos + 1..];
127    // Take everything up to `(`
128    let name = after_sep.split('(').next()?;
129    let name = name.trim();
130    if name.is_empty() {
131        return None;
132    }
133    Some(name.to_string())
134}
assay/metadata.rs

assay/
metadata.rs
