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;