Skip to main content

logicaffeine_language/analysis/
dependencies.rs

1//! Dependency Scanner for the Hyperlink Module System.
2//!
3//! Scans the "Abstract" (first paragraph) of a LOGOS document for Markdown links,
4//! which are interpreted as module dependencies.
5//!
6//! Syntax: `[Alias](URI)` where:
7//! - Alias: The name to reference the module by (e.g., "Geometry")
8//! - URI: The location of the module source (e.g., "file:./geo.md", "logos:std")
9
10/// One name selected by a per-name import (`Import double as dbl from Util.`).
11#[derive(Debug, Clone, PartialEq, Eq)]
12pub struct SelectedName {
13    /// The real name exported by the module (`double`).
14    pub name: String,
15    /// The local alias the importer uses, if `as <alias>` was given (`dbl`).
16    pub alias: Option<String>,
17}
18
19/// A dependency declaration found in the document's abstract.
20#[derive(Debug, Clone, PartialEq, Eq)]
21pub struct Dependency {
22    /// The alias to use when referencing this module (e.g., "Geometry")
23    pub alias: String,
24    /// The URI pointing to the module source (e.g., "file:./geo.md")
25    pub uri: String,
26    /// Start position in the source for error reporting
27    pub start: usize,
28    /// End position in the source for error reporting
29    pub end: usize,
30    /// For a SELECTIVE import (`Import double from Util.`), the specific names
31    /// brought into scope (each with an optional per-name alias). `None` means a
32    /// whole-module import — every public definition is in scope.
33    pub selection: Option<Vec<SelectedName>>,
34}
35
36/// Scans the first paragraph (Abstract) of a LOGOS file for `[Alias](URI)` links.
37///
38/// The Abstract is defined as the first non-empty block of text following the
39/// module header (# Name). Links inside this paragraph are treated as imports.
40/// Scanning stops at the first empty line after the abstract or when a code
41/// block header (`##`) is encountered.
42///
43/// # Example
44///
45/// ```text
46/// # My Game
47///
48/// This module uses [Geometry](file:./geo.md) for math.
49///
50/// ## Main
51/// Let x be 1.
52/// ```
53///
54/// Returns: `[Dependency { alias: "Geometry", uri: "file:./geo.md", ... }]`
55pub fn scan_dependencies(source: &str) -> Vec<Dependency> {
56    let mut dependencies = Vec::new();
57    // `in_abstract` is true until the opening paragraph ends; `abstract_started` marks that some
58    // prose has been seen, so leading blank lines do not close an abstract that never opened.
59    let mut in_abstract = true;
60    let mut abstract_started = false;
61    let mut current_pos = 0;
62
63    for line in source.lines() {
64        let line_start = current_pos;
65        let trimmed = line.trim();
66
67        // Track position for the next line
68        current_pos += line.len() + 1; // +1 for newline
69
70        // A blank line ends the ABSTRACT — the opening paragraph, which is the only place a
71        // literate Markdown LINK counts as a dependency. Scanning past it for links would make
72        // every `[see also](…)` in a module's prose a module the loader must resolve.
73        if trimmed.is_empty() {
74            if abstract_started {
75                in_abstract = false;
76            }
77            continue;
78        }
79
80        // Skip the header line (# Title)
81        if trimmed.starts_with("# ") && !trimmed.starts_with("## ") {
82            continue;
83        }
84
85        // ★ THE PROSE REGION ENDS AT THE FIRST BLOCK HEADER, AND NOWHERE EARLIER.
86        //
87        // This used to stop at the first BLANK LINE after any prose — the file's opening
88        // "abstract" — which meant a `.lg` written the way every literate module in this repo is
89        // written (title, an explanation of what the module is for, THEN the imports) had its
90        // imports silently invisible. Nothing was scanned, so nothing was resolved, so the module
91        // was never spliced and its type declarations never reached the registry; the program then
92        // compiled on as though the record had never been declared. See `import_scan_lock`.
93        //
94        // Past a `## ` header the file is CODE, where `Import` is a statement the parser handles
95        // and a line beginning with that word is not necessarily one at all — so the scan stops
96        // there rather than mining the program's text for dependencies.
97        if trimmed.starts_with("## ") {
98            break;
99        }
100
101        abstract_started = true;
102
103        // An INDENTED line in the prose region is a Markdown code block — an illustration of what
104        // an import looks like, not an import. Reading the trimmed line would turn every example
105        // in every guide into a dependency the loader then fails to resolve.
106        let indented = line.starts_with("    ") || line.starts_with('\t');
107
108        // ★ AN EXPLICIT `Import …` COUNTS ANYWHERE IN THE PROSE; A LINK ONLY IN THE ABSTRACT.
109        //
110        // The two are not the same kind of thing, and treating them alike was the bug in both
111        // directions. An `Import Shared.` is a DECLARATION — it says the module depends on
112        // Shared, and it means that wherever the author put it. A `[see also](other.md)` is
113        // PROSE: a module's explanation may link to things it does not depend on at all, which
114        // is why the abstract-only rule exists for links and is worth keeping.
115        //
116        // Reading only the abstract for BOTH meant an `Import` after the opening paragraph — how
117        // every literate `.lg` in this repo is written — was silently dropped: not scanned, so
118        // not resolved, so not spliced, and the program compiled on as though the module had
119        // never been named. See `import_scan_lock`.
120        if !indented {
121            let imports = parse_import_statement(trimmed, line_start);
122            if !imports.is_empty() {
123                dependencies.extend(imports);
124                continue;
125            }
126        }
127
128        if in_abstract {
129            scan_line_for_links(line, line_start, &mut dependencies);
130        }
131    }
132
133    dependencies
134}
135
136/// A file's first `## ` section header outside a ``` fence, as its 1-based line and its text: the line
137/// above which an `Import` must stand to import anything.
138pub fn first_section_header(source: &str) -> Option<(usize, &str)> {
139    let mut in_fence = false;
140    for (i, line) in source.lines().enumerate() {
141        let trimmed = line.trim();
142        if trimmed.starts_with("```") {
143            in_fence = !in_fence;
144        } else if !in_fence && trimmed.starts_with("## ") {
145            return Some((i + 1, trimmed));
146        }
147    }
148    None
149}
150
151/// Every `Import` sentence below a file's first `## ` header, each with its byte span. That is where
152/// [`scan_dependencies`] does not read, so such a sentence imports nothing: the module is never
153/// spliced and the program runs on without it. A caller refuses each at its own line. A line inside a
154/// ``` fence or indented as a code block illustrates an import and is never one.
155pub fn misplaced_imports(source: &str) -> Vec<Dependency> {
156    let mut found = Vec::new();
157    let mut past_header = false;
158    let mut in_fence = false;
159    let mut line_start = 0;
160    for line in source.lines() {
161        let start = line_start;
162        line_start += line.len() + 1;
163        let trimmed = line.trim();
164        if trimmed.starts_with("```") {
165            in_fence = !in_fence;
166            continue;
167        }
168        if in_fence {
169            continue;
170        }
171        if trimmed.starts_with("## ") {
172            past_header = true;
173            continue;
174        }
175        let indented = line.starts_with("    ") || line.starts_with('\t');
176        if past_header && !indented {
177            let sentence_start = start + (line.len() - line.trim_start().len());
178            found.extend(parse_import_statement(trimmed, sentence_start));
179        }
180    }
181    found
182}
183
184/// Parse an explicit import statement into one or more dependencies:
185///
186/// * `Import Geometry.` — the bare name resolves to a project file
187///   (`geometry.lg` / `geometry.md`, tried by the loader), bound under the
188///   alias `Geometry`.
189/// * `Import Geometry and Colors.` / `Import Lexer, Parser, Ast.` — several
190///   modules in one natural sentence.
191/// * `Import Geometry from "shapes/geometry.lg".` — an explicit path (for a
192///   subdirectory, or when the file name differs from the alias).
193/// * `Import Geometry as Geo.` — bind the module under a different alias
194///   (`Geo::…`), e.g. to disambiguate two modules that would share a name.
195///
196/// The trailing period is optional. Returns an empty vec for a line that is not
197/// an import statement (ordinary abstract prose flows on to link scanning).
198fn parse_import_statement(line: &str, line_start: usize) -> Vec<Dependency> {
199    let Some(rest) = line
200        .strip_prefix("Import ")
201        .or_else(|| line.strip_prefix("import "))
202    else {
203        return Vec::new();
204    };
205    let rest = rest.trim();
206    let rest = rest.strip_suffix('.').unwrap_or(rest).trim();
207    if rest.is_empty() {
208        return Vec::new();
209    }
210    let end = line_start + line.len();
211    // A SELECTIVE import — `<names> from <Bareword>` (unquoted source module) —
212    // is decided at the STATEMENT level, before clause-splitting, so the `,`/`and`
213    // list is read as NAMES, not modules. `from "quoted"` stays a path import.
214    if let Some(dep) = parse_selective_import(rest, line_start, end) {
215        return vec![dep];
216    }
217    split_import_clauses(rest)
218        .into_iter()
219        .filter_map(|clause| parse_one_import(clause, line_start, end))
220        .collect()
221}
222
223/// Parse `<names> from <Bareword>` into a single selective dependency, or `None`
224/// if this isn't the selective shape (no `from`, or a quoted/multi-word source —
225/// those are whole-module path imports handled by [`parse_one_import`]).
226fn parse_selective_import(rest: &str, start: usize, end: usize) -> Option<Dependency> {
227    let idx = rest.rfind(" from ")?;
228    let names_part = rest[..idx].trim();
229    let source = rest[idx + " from ".len()..].trim();
230    // A quoted or multi-word source is a PATH (whole-module import), not selective.
231    if source.is_empty() || source.starts_with('"') || source.contains(char::is_whitespace) {
232        return None;
233    }
234    let selection: Vec<SelectedName> = split_import_clauses(names_part)
235        .into_iter()
236        .filter_map(parse_selected_name)
237        .collect();
238    if selection.is_empty() {
239        return None;
240    }
241    Some(Dependency {
242        alias: source.to_string(),
243        uri: format!("file:./{}", source.to_lowercase()),
244        start,
245        end,
246        selection: Some(selection),
247    })
248}
249
250/// One entry of a selective import's name list: `<name> [as <alias>]`.
251fn parse_selected_name(clause: &str) -> Option<SelectedName> {
252    let clause = clause.trim();
253    let (name, alias) = match clause.rsplit_once(" as ") {
254        Some((n, a)) => (n.trim(), Some(a.trim())),
255        None => (clause, None),
256    };
257    if name.is_empty() || name.contains(char::is_whitespace) {
258        return None;
259    }
260    let alias = alias
261        .filter(|a| !a.is_empty() && !a.contains(char::is_whitespace))
262        .map(str::to_string);
263    Some(SelectedName {
264        name: name.to_string(),
265        alias,
266    })
267}
268
269/// One import clause: `<name> [from "<path>"] [as <alias>]`.
270fn parse_one_import(clause: &str, start: usize, end: usize) -> Option<Dependency> {
271    // `as <alias>` renames the binding; the module is still resolved from <name>.
272    let (head, bind) = match clause.rsplit_once(" as ") {
273        Some((h, b)) => (h.trim(), Some(b.trim())),
274        None => (clause, None),
275    };
276    // `from "<path>"` gives an explicit path; otherwise resolve by name.
277    let (name, path) = match head.split_once(" from ") {
278        Some((n, p)) => (n.trim(), Some(p.trim().trim_matches('"').trim())),
279        None => (head, None),
280    };
281    if name.is_empty() || name.contains(char::is_whitespace) {
282        return None;
283    }
284    let alias = bind
285        .filter(|b| !b.is_empty() && !b.contains(char::is_whitespace))
286        .unwrap_or(name);
287    let uri = match path {
288        Some(p) if p.is_empty() => return None,
289        Some(p) if p.starts_with("./") || p.starts_with("../") => format!("file:{p}"),
290        Some(p) => format!("file:./{p}"),
291        None => format!("file:./{}", name.to_lowercase()),
292    };
293    Some(Dependency {
294        alias: alias.to_string(),
295        uri,
296        start,
297        end,
298        selection: None,
299    })
300}
301
302/// Split an import list on `,` and ` and ` (list + English style) into clauses —
303/// but only OUTSIDE double quotes, so a `from "a and b.lg"` path with an
304/// embedded separator stays one clause. Separators are ASCII (`"`, `,`, ` `), so
305/// every slice boundary is a valid char boundary.
306fn split_import_clauses(s: &str) -> Vec<&str> {
307    const AND: &str = " and ";
308    let bytes = s.as_bytes();
309    let mut clauses = Vec::new();
310    let mut in_quotes = false;
311    let mut clause_start = 0;
312    let mut i = 0;
313    while i < bytes.len() {
314        match bytes[i] {
315            b'"' => {
316                in_quotes = !in_quotes;
317                i += 1;
318            }
319            b',' if !in_quotes => {
320                clauses.push(&s[clause_start..i]);
321                i += 1;
322                clause_start = i;
323            }
324            b' ' if !in_quotes && s[i..].starts_with(AND) => {
325                clauses.push(&s[clause_start..i]);
326                i += AND.len();
327                clause_start = i;
328            }
329            _ => i += 1,
330        }
331    }
332    clauses.push(&s[clause_start..]);
333    clauses
334        .into_iter()
335        .map(str::trim)
336        .filter(|p| !p.is_empty())
337        .collect()
338}
339
340/// Scans a single line for Markdown link patterns `[Alias](URI)`.
341fn scan_line_for_links(line: &str, line_start: usize, deps: &mut Vec<Dependency>) {
342    let bytes = line.as_bytes();
343    let mut i = 0;
344
345    while i < bytes.len() {
346        // Look for opening bracket
347        if bytes[i] == b'[' {
348            let link_start = line_start + i;
349            i += 1;
350
351            // Read the alias (text between [ and ])
352            let alias_start = i;
353            while i < bytes.len() && bytes[i] != b']' {
354                i += 1;
355            }
356
357            if i >= bytes.len() {
358                // No closing bracket found
359                break;
360            }
361
362            let alias = &line[alias_start..i];
363            i += 1; // Skip ]
364
365            // Expect immediate opening parenthesis
366            if i >= bytes.len() || bytes[i] != b'(' {
367                continue;
368            }
369            i += 1; // Skip (
370
371            // Read the URI (text between ( and ))
372            let uri_start = i;
373            let mut paren_depth = 1;
374            while i < bytes.len() && paren_depth > 0 {
375                if bytes[i] == b'(' {
376                    paren_depth += 1;
377                } else if bytes[i] == b')' {
378                    paren_depth -= 1;
379                }
380                if paren_depth > 0 {
381                    i += 1;
382                }
383            }
384
385            if paren_depth != 0 {
386                // No closing parenthesis found
387                break;
388            }
389
390            let uri = &line[uri_start..i];
391            let link_end = line_start + i + 1;
392            i += 1; // Skip )
393
394            // Skip empty aliases or URIs
395            if alias.is_empty() || uri.is_empty() {
396                continue;
397            }
398
399            deps.push(Dependency {
400                alias: alias.trim().to_string(),
401                uri: uri.trim().to_string(),
402                start: link_start,
403                end: link_end,
404                selection: None,
405            });
406        } else {
407            i += 1;
408        }
409    }
410}
411
412#[cfg(test)]
413#[path = "../../../logicaffeine_tests/unit/logicaffeine_language/analysis/dependencies/tests.rs"]
414mod tests;