Skip to main content

code_system_graph_core/
source_polyglot.rs

1use std::collections::BTreeSet;
2
3use crate::router_mounts::mount_observation;
4use crate::source_http::{
5    BraceClients, SourceObservationCollector, collect_brace_clients, java_method_lines
6};
7use crate::source_routers::{
8    GoRouterScope, receiver_before, script_imports, script_router_observations
9};
10use crate::{
11    ExtractionLimitExceeded, ExtractionTracker, SourceEpistemicStatus, SourceFramework, SourceLanguage, SourceLineRange, SourceObservation, SourceRole, SourceWarning, SymbolRef, normalize_source_http_path
12};
13
14const METHODS: [(&str, &str); 8] = [
15    ("delete", "DELETE"),
16    ("get", "GET"),
17    ("head", "HEAD"),
18    ("options", "OPTIONS"),
19    ("patch", "PATCH"),
20    ("post", "POST"),
21    ("put", "PUT"),
22    ("trace", "TRACE"),
23];
24
25/// Extracts Fetch, Axios, Express, and Fastify facts from JavaScript.
26#[must_use]
27pub fn parse_javascript_source(source: &str) -> Vec<SourceObservation> {
28    parse_ecmascript(source, SourceLanguage::JavaScript)
29}
30
31/// Extracts JavaScript framework facts with repository-relative file-route context.
32#[must_use]
33pub fn parse_javascript_source_at_path(source_path: &str, source: &str) -> Vec<SourceObservation> {
34    let observations = collect_ecmascript_at_path(
35        source_path,
36        source,
37        SourceLanguage::JavaScript,
38        SourceObservationCollector::unbounded(),
39    );
40    finish(observations.into_unbounded())
41}
42
43/// Extracts JavaScript facts while charging each attempted observation before retention.
44///
45/// # Errors
46///
47/// Returns [`ExtractionLimitExceeded`] before an observation or one of its values exceeds the
48/// effective per-artifact budget.
49pub fn parse_javascript_source_at_path_with_tracker(
50    source_path: &str,
51    source: &str,
52    tracker: &mut ExtractionTracker,
53) -> Result<Vec<SourceObservation>, ExtractionLimitExceeded> {
54    let observations = collect_ecmascript_at_path(
55        source_path,
56        source,
57        SourceLanguage::JavaScript,
58        SourceObservationCollector::bounded(tracker),
59    );
60    Ok(finish(observations.into_result()?))
61}
62
63/// Extracts Fetch, Axios, Express, Fastify, and `NestJS` facts from TypeScript.
64#[must_use]
65pub fn parse_typescript_source(source: &str) -> Vec<SourceObservation> {
66    parse_ecmascript(source, SourceLanguage::TypeScript)
67}
68
69/// Extracts TypeScript framework facts with repository-relative file-route context.
70#[must_use]
71pub fn parse_typescript_source_at_path(source_path: &str, source: &str) -> Vec<SourceObservation> {
72    let observations = collect_ecmascript_at_path(
73        source_path,
74        source,
75        SourceLanguage::TypeScript,
76        SourceObservationCollector::unbounded(),
77    );
78    finish(observations.into_unbounded())
79}
80
81/// Extracts TypeScript facts while charging each attempted observation before retention.
82///
83/// # Errors
84///
85/// Returns [`ExtractionLimitExceeded`] before an observation or one of its values exceeds the
86/// effective per-artifact budget.
87pub fn parse_typescript_source_at_path_with_tracker(
88    source_path: &str,
89    source: &str,
90    tracker: &mut ExtractionTracker,
91) -> Result<Vec<SourceObservation>, ExtractionLimitExceeded> {
92    let observations = collect_ecmascript_at_path(
93        source_path,
94        source,
95        SourceLanguage::TypeScript,
96        SourceObservationCollector::bounded(tracker),
97    );
98    Ok(finish(observations.into_result()?))
99}
100
101/// Extracts `net/http`, Gin, and Chi facts from Go source.
102#[must_use]
103pub fn parse_go_source(source: &str) -> Vec<SourceObservation> {
104    let observations = collect_go_source(source, SourceObservationCollector::unbounded());
105    finish(observations.into_unbounded())
106}
107
108/// Extracts Go facts while charging each attempted observation before retention.
109///
110/// # Errors
111///
112/// Returns [`ExtractionLimitExceeded`] before an observation or one of its values exceeds the
113/// effective per-artifact budget.
114pub fn parse_go_source_with_tracker(
115    source: &str,
116    tracker: &mut ExtractionTracker,
117) -> Result<Vec<SourceObservation>, ExtractionLimitExceeded> {
118    let observations = collect_go_source(source, SourceObservationCollector::bounded(tracker));
119    Ok(finish(observations.into_result()?))
120}
121
122fn collect_go_source<'a>(
123    source: &str,
124    mut observations: SourceObservationCollector<'a>,
125) -> SourceObservationCollector<'a> {
126    let has_http = source.contains("\"net/http\"");
127    let has_gin = source.contains("github.com/gin-gonic/gin");
128    let has_chi = source.contains("github.com/go-chi/chi");
129    let router_framework = if has_gin {
130        SourceFramework::Gin
131    } else if has_chi {
132        SourceFramework::Chi
133    } else {
134        SourceFramework::GoNetHttp
135    };
136    let mut scope = GoRouterScope::default();
137    for statement in go_statements(source) {
138        if has_http || has_gin || has_chi {
139            for mount in scope.observe(&statement, router_framework) {
140                observations.push(mount);
141            }
142        }
143        if has_http {
144            append_go_pattern_route(&mut observations, &statement, &scope);
145        }
146        if has_http
147            && statement.text.contains("http.HandleFunc(")
148            && !first_literal_after_call(&statement.text)
149                .is_some_and(|pattern| pattern.contains(' '))
150        {
151            observations.push(incomplete_observation(
152                SourceLanguage::Go,
153                SourceFramework::GoNetHttp,
154                SourceRole::Provider,
155                None,
156                first_literal_after_call(&statement.text)
157                    .as_deref()
158                    .and_then(literal_path),
159                route_symbol(&statement.text, None),
160                statement.lines,
161                SourceWarning::DynamicMethod,
162            ));
163        }
164        if has_gin {
165            append_receiver_route(
166                &mut observations,
167                SourceFramework::Gin,
168                &statement,
169                true,
170                &scope,
171            );
172        }
173        if has_chi {
174            append_receiver_route(
175                &mut observations,
176                SourceFramework::Chi,
177                &statement,
178                false,
179                &scope,
180            );
181        }
182    }
183    let clients = BraceClients {
184        go_http: has_http,
185        ..BraceClients::default()
186    };
187    collect_brace_clients(source, SourceLanguage::Go, clients, &mut observations);
188    observations
189}
190
191/// Extracts Spring MVC, Spring `WebClient`, and Feign facts from Java source.
192#[must_use]
193pub fn parse_java_source(source: &str) -> Vec<SourceObservation> {
194    let observations = collect_java_source(source, SourceObservationCollector::unbounded());
195    finish(observations.into_unbounded())
196}
197
198/// Extracts Java facts while charging each attempted observation before retention.
199///
200/// # Errors
201///
202/// Returns [`ExtractionLimitExceeded`] before an observation or one of its values exceeds the
203/// effective per-artifact budget.
204pub fn parse_java_source_with_tracker(
205    source: &str,
206    tracker: &mut ExtractionTracker,
207) -> Result<Vec<SourceObservation>, ExtractionLimitExceeded> {
208    let observations = collect_java_source(source, SourceObservationCollector::bounded(tracker));
209    Ok(finish(observations.into_result()?))
210}
211
212fn collect_java_source<'a>(
213    source: &str,
214    mut observations: SourceObservationCollector<'a>,
215) -> SourceObservationCollector<'a> {
216    let spring = source.contains("org.springframework.web.bind.annotation");
217    let web_client = source.contains("org.springframework.web.reactive.function.client.WebClient");
218    let feign = source.contains("@FeignClient") || source.contains("openfeign.FeignClient");
219    let lines = source.lines().collect::<Vec<_>>();
220    let methods = if spring && !feign {
221        java_method_lines(source)
222    } else {
223        Vec::new()
224    };
225    let mut class_prefix = None::<String>;
226    for (index, line) in lines.iter().enumerate() {
227        let trimmed = line.trim();
228        if java_annotates_type(&lines, index) {
229            if trimmed.starts_with("@RequestMapping") {
230                class_prefix = quoted_value(trimmed);
231            } else if trimmed.starts_with("@FeignClient") {
232                class_prefix = feign_path(trimmed);
233            }
234            continue;
235        }
236        if spring
237            && trimmed.starts_with('@')
238            && let Some((method, path)) = java_mapping(trimmed)
239        {
240            let path = match (&class_prefix, path) {
241                (Some(prefix), path) => Some(format!("/{prefix}/{}", path.unwrap_or_default())),
242                (None, path) => path,
243            };
244            let line = line_number(index);
245            let symbol = if feign {
246                lines
247                    .iter()
248                    .skip(index + 1)
249                    .take(5)
250                    .find_map(|candidate| java_method_name(candidate))
251            } else {
252                methods
253                    .iter()
254                    .find(|(start, _)| *start >= line)
255                    .map(|(_, name)| name.clone())
256            };
257            observations.push(http_observation(
258                SourceLanguage::Java,
259                if feign {
260                    SourceFramework::Feign
261                } else {
262                    SourceFramework::SpringMvc
263                },
264                if feign {
265                    SourceRole::Consumer
266                } else {
267                    SourceRole::Provider
268                },
269                method,
270                path,
271                symbol,
272                SourceLineRange {
273                    start: line_number(index),
274                    end: line_number(index),
275                },
276            ));
277        }
278    }
279    let clients = BraceClients {
280        web_client,
281        ..BraceClients::default()
282    };
283    collect_brace_clients(source, SourceLanguage::Java, clients, &mut observations);
284    observations
285}
286
287fn parse_ecmascript(source: &str, language: SourceLanguage) -> Vec<SourceObservation> {
288    let observations = collect_ecmascript_at_path(
289        "",
290        source,
291        language,
292        SourceObservationCollector::unbounded(),
293    );
294    finish(observations.into_unbounded())
295}
296
297fn collect_ecmascript_at_path<'a>(
298    source_path: &str,
299    source: &str,
300    language: SourceLanguage,
301    mut observations: SourceObservationCollector<'a>,
302) -> SourceObservationCollector<'a> {
303    let express = source.contains("from \"express\"")
304        || source.contains("from 'express'")
305        || source.contains("require(\"express\")")
306        || source.contains("require('express')");
307    let fastify = source.contains("from \"fastify\"")
308        || source.contains("from 'fastify'")
309        || source.contains("require(\"fastify\")")
310        || source.contains("require('fastify')");
311    let axios = source.contains("from \"axios\"")
312        || source.contains("from 'axios'")
313        || source.contains("require(\"axios\")")
314        || source.contains("require('axios')");
315    let nest = source.contains("@nestjs/common");
316    let mut express_receivers = assigned_receivers(source, "express");
317    if express && source.contains("Router") {
318        express_receivers.extend(assigned_receivers(source, "Router"));
319    }
320    let fastify_receivers = assigned_receivers(source, "fastify");
321    let statements = statements(source);
322    if express {
323        let imports = script_imports(&statements);
324        for mount in script_router_observations(&statements, language, &express_receivers, &imports)
325        {
326            observations.push(mount);
327        }
328    }
329    for statement in statements {
330        if express {
331            append_js_route(
332                &mut observations,
333                language,
334                SourceFramework::Express,
335                &statement,
336                &express_receivers,
337            );
338        }
339        if fastify {
340            append_js_route(
341                &mut observations,
342                language,
343                SourceFramework::Fastify,
344                &statement,
345                &fastify_receivers,
346            );
347        }
348    }
349    if nest {
350        append_nest_routes(&mut observations, source, language);
351    }
352    if let Some(prefix) = nest_global_prefix(source) {
353        observations.push(mount_observation(
354            language,
355            SourceFramework::NestJs,
356            SymbolRef::Function(NEST_APPLICATION.to_owned()),
357            None,
358            Some(&prefix),
359            SourceLineRange { start: 1, end: 1 },
360        ));
361    }
362    append_next_app_routes(&mut observations, source_path, source, language);
363    let clients = BraceClients {
364        axios,
365        ..BraceClients::default()
366    };
367    collect_brace_clients(source, language, clients, &mut observations);
368    observations
369}
370
371/// Repository-wide router of every `NestJS` controller, mounted by `setGlobalPrefix`.
372const NEST_APPLICATION: &str = "@nestjs";
373
374fn append_nest_routes(
375    observations: &mut SourceObservationCollector<'_>,
376    source: &str,
377    language: SourceLanguage,
378) {
379    let lines = source.lines().collect::<Vec<_>>();
380    let mut controller = None::<String>;
381    for (index, line) in lines.iter().enumerate() {
382        let trimmed = line.trim();
383        if let Some(arguments) = trimmed.strip_prefix("@Controller(") {
384            let prefix = quoted_value(arguments.split(')').next().unwrap_or_default());
385            controller = Some(prefix.unwrap_or_default());
386            continue;
387        }
388        let Some((method, path)) = nest_mapping(trimmed) else {
389            continue;
390        };
391        let symbol = lines
392            .iter()
393            .skip(index + 1)
394            .take(5)
395            .find_map(|candidate| ecmascript_method_name(candidate));
396        let path = match (&controller, path) {
397            (Some(prefix), path) => Some(format!("/{prefix}/{}", path.unwrap_or_default())),
398            (None, Some(path)) if !path.starts_with('/') => Some(format!("/{path}")),
399            (None, path) => path,
400        };
401        let mut observation = http_observation(
402            language,
403            SourceFramework::NestJs,
404            SourceRole::Provider,
405            Some(method),
406            path,
407            symbol,
408            SourceLineRange {
409                start: line_number(index),
410                end: line_number(index),
411            },
412        );
413        observation.router = Some(SymbolRef::Function(NEST_APPLICATION.to_owned()));
414        observations.push(observation);
415    }
416}
417
418fn nest_global_prefix(source: &str) -> Option<String> {
419    let at = source.find(".setGlobalPrefix(")?;
420    quoted_values(&source[at..source[at..].find(')').map_or(source.len(), |end| at + end)])
421        .into_iter()
422        .next()
423}
424
425fn append_next_app_routes(
426    observations: &mut SourceObservationCollector<'_>,
427    source_path: &str,
428    source: &str,
429    language: SourceLanguage,
430) {
431    let Some(path) = next_app_route_path(source_path) else {
432        return;
433    };
434    for (index, line) in source.lines().enumerate() {
435        let Some(method) = next_route_export_method(line) else {
436            continue;
437        };
438        observations.push(http_observation(
439            language,
440            SourceFramework::NextJs,
441            SourceRole::Provider,
442            Some(method.clone()),
443            Some(path.clone()),
444            Some(method),
445            SourceLineRange {
446                start: line_number(index),
447                end: line_number(index),
448            },
449        ));
450    }
451}
452
453fn next_app_route_path(source_path: &str) -> Option<String> {
454    let normalized = source_path.replace('\\', "/");
455    let components = normalized.split('/').collect::<Vec<_>>();
456    let route_file = components.last()?;
457    let stem = route_file
458        .rsplit_once('.')
459        .map_or(*route_file, |(stem, _)| stem);
460    if stem != "route" {
461        return None;
462    }
463    let app = components
464        .windows(2)
465        .position(|window| window == ["src", "app"])
466        .map(|index| index + 2)
467        .or_else(|| {
468            components
469                .iter()
470                .position(|component| *component == "app")
471                .map(|index| index + 1)
472        })?;
473    let segments = components[app..components.len().saturating_sub(1)]
474        .iter()
475        .filter(|component| !(component.starts_with('(') && component.ends_with(')')))
476        .map(|component| {
477            component
478                .strip_prefix("[[...")
479                .and_then(|value| value.strip_suffix("]]"))
480                .or_else(|| {
481                    component
482                        .strip_prefix("[...")
483                        .and_then(|value| value.strip_suffix(']'))
484                })
485                .or_else(|| {
486                    component
487                        .strip_prefix('[')
488                        .and_then(|value| value.strip_suffix(']'))
489                })
490                .map_or_else(|| (*component).to_owned(), |value| format!("{{{value}}}"))
491        })
492        .collect::<Vec<_>>();
493    Some(normalize_source_http_path(&segments.join("/")))
494}
495
496fn next_route_export_method(line: &str) -> Option<String> {
497    let trimmed = line.trim_start();
498    if !trimmed.starts_with("export ") {
499        return None;
500    }
501    let tokens = trimmed
502        .split(|character: char| character.is_whitespace() || matches!(character, '(' | ':' | '='))
503        .filter(|token| !token.is_empty())
504        .collect::<Vec<_>>();
505    let candidate = tokens
506        .windows(2)
507        .find_map(|window| (window[0] == "function").then_some(window[1]))
508        .or_else(|| {
509            tokens
510                .windows(2)
511                .find_map(|window| matches!(window[0], "const" | "let").then_some(window[1]))
512        })?;
513    METHODS
514        .iter()
515        .find_map(|(_, method)| (*method == candidate).then_some((*method).to_owned()))
516}
517
518#[derive(Debug)]
519pub(crate) struct Statement {
520    pub(crate) text: String,
521    pub(crate) lines: SourceLineRange,
522}
523
524fn statements(source: &str) -> Vec<Statement> {
525    split_statements(source, false)
526}
527
528/// Splits Go source into statements, also ending one at each opening or closing block brace so
529/// closures and blocks are visible as separate statements.
530fn go_statements(source: &str) -> Vec<Statement> {
531    split_statements(source, true)
532}
533
534fn split_statements(source: &str, split_blocks: bool) -> Vec<Statement> {
535    let mut output = Vec::new();
536    let mut text = String::new();
537    let mut start = 1_u32;
538    let mut depth = 0_i32;
539    for (index, line) in source.lines().enumerate() {
540        let trimmed = strip_line_comment(line).trim();
541        if trimmed.is_empty() {
542            continue;
543        }
544        if text.is_empty() {
545            start = line_number(index);
546        } else {
547            text.push(' ');
548        }
549        text.push_str(trimmed);
550        depth += delimiter_delta(trimmed);
551        let block_boundary = split_blocks && (trimmed.ends_with('{') || trimmed.starts_with('}'));
552        if depth <= 0 || trimmed.ends_with(';') || block_boundary {
553            output.push(Statement {
554                text: std::mem::take(&mut text),
555                lines: SourceLineRange {
556                    start,
557                    end: line_number(index),
558                },
559            });
560            depth = 0;
561        }
562    }
563    if !text.is_empty() {
564        output.push(Statement {
565            text,
566            lines: SourceLineRange {
567                start,
568                end: u32::try_from(source.lines().count()).unwrap_or(u32::MAX),
569            },
570        });
571    }
572    output
573}
574
575fn delimiter_delta(line: &str) -> i32 {
576    line.chars().fold(0, |depth, character| match character {
577        '(' | '[' => depth + 1,
578        ')' | ']' => depth - 1,
579        _ => depth,
580    })
581}
582
583fn append_js_route(
584    output: &mut SourceObservationCollector<'_>,
585    language: SourceLanguage,
586    framework: SourceFramework,
587    statement: &Statement,
588    receivers: &BTreeSet<String>,
589) {
590    if !receivers
591        .iter()
592        .any(|receiver| statement.text.contains(&format!("{receiver}.")))
593    {
594        return;
595    }
596    let method = METHODS.iter().find_map(|(name, method)| {
597        statement
598            .text
599            .contains(&format!(".{name}("))
600            .then_some((*method).to_owned())
601    });
602    if method.is_none() {
603        return;
604    }
605    let mut observation = http_observation(
606        language,
607        framework,
608        SourceRole::Provider,
609        method.clone(),
610        first_literal_after_call(&statement.text),
611        route_symbol(&statement.text, method.as_deref()),
612        statement.lines,
613    );
614    observation.router = METHODS
615        .iter()
616        .find_map(|(name, _)| receiver_before(&statement.text, name))
617        .filter(|receiver| receivers.contains(*receiver))
618        .map(|receiver| SymbolRef::Local(receiver.to_owned()));
619    output.push(observation);
620}
621
622fn append_receiver_route(
623    output: &mut SourceObservationCollector<'_>,
624    framework: SourceFramework,
625    statement: &Statement,
626    uppercase: bool,
627    scope: &GoRouterScope,
628) {
629    let Some((call, method)) = METHODS.iter().find_map(|(name, method)| {
630        let name = if uppercase {
631            name.to_ascii_uppercase()
632        } else {
633            let mut characters = name.chars();
634            characters.next().map_or_else(String::new, |first| {
635                first.to_ascii_uppercase().to_string() + characters.as_str()
636            })
637        };
638        statement
639            .text
640            .contains(&format!(".{name}("))
641            .then(|| (name, (*method).to_owned()))
642    }) else {
643        return;
644    };
645    let mut observation = http_observation(
646        SourceLanguage::Go,
647        framework,
648        SourceRole::Provider,
649        Some(method.clone()),
650        first_literal_after_call(&statement.text),
651        route_symbol(&statement.text, Some(&method)),
652        statement.lines,
653    );
654    observation.router =
655        receiver_before(&statement.text, &call).map(|receiver| scope.reference(receiver));
656    output.push(observation);
657}
658
659/// Records Go 1.22 `ServeMux` patterns such as `mux.HandleFunc("GET /orders/{id}", handler)`.
660fn append_go_pattern_route(
661    output: &mut SourceObservationCollector<'_>,
662    statement: &Statement,
663    scope: &GoRouterScope,
664) {
665    let Some(call) = ["HandleFunc", "Handle"]
666        .into_iter()
667        .find(|call| statement.text.contains(&format!(".{call}(")))
668    else {
669        return;
670    };
671    let Some(pattern) = first_literal_after_call(&statement.text) else {
672        return;
673    };
674    let Some((method, path)) = pattern.split_once(' ') else {
675        return;
676    };
677    let Some(method) = canonical_method(method) else {
678        return;
679    };
680    let mut observation = http_observation(
681        SourceLanguage::Go,
682        SourceFramework::GoNetHttp,
683        SourceRole::Provider,
684        Some(method.clone()),
685        Some(path.trim().to_owned()),
686        route_symbol(&statement.text, Some(&method)),
687        statement.lines,
688    );
689    observation.router = receiver_before(&statement.text, call)
690        .filter(|receiver| *receiver != "http")
691        .map(|receiver| scope.reference(receiver));
692    output.push(observation);
693}
694
695fn http_observation(
696    language: SourceLanguage,
697    framework: SourceFramework,
698    role: SourceRole,
699    method: Option<String>,
700    literal: Option<String>,
701    symbol_name: Option<String>,
702    lines: SourceLineRange,
703) -> SourceObservation {
704    let literal_missing = literal.is_none();
705    let authority = (role == SourceRole::Consumer)
706        .then(|| literal.as_deref().and_then(crate::routes::url_authority))
707        .flatten();
708    let path = literal.and_then(|value| literal_path(&value));
709    let mut warnings = Vec::new();
710    if method.is_none() {
711        warnings.push(SourceWarning::DynamicMethod);
712    }
713    if literal_missing {
714        warnings.push(SourceWarning::DynamicPath);
715    } else if path.is_none() {
716        warnings.push(SourceWarning::UnsupportedLiteralPath);
717    }
718    if role == SourceRole::Provider && symbol_name.is_none() {
719        warnings.push(SourceWarning::MissingSymbol);
720    }
721    let confirmed = method.is_some()
722        && path.is_some()
723        && (role != SourceRole::Provider || symbol_name.is_some());
724    SourceObservation {
725        language,
726        framework,
727        role,
728        method,
729        path,
730        symbol_name,
731        related_symbol: None,
732        related_path: None,
733        authority,
734        router: None,
735        mount_parent: None,
736        url: None,
737        call: None,
738        lines,
739        status: if confirmed {
740            SourceEpistemicStatus::Confirmed
741        } else {
742            SourceEpistemicStatus::Ambiguous
743        },
744        confidence: if confirmed { 1.0 } else { 0.0 },
745        warnings,
746    }
747}
748
749#[expect(
750    clippy::too_many_arguments,
751    reason = "Incomplete observations preserve every available direct coordinate"
752)]
753fn incomplete_observation(
754    language: SourceLanguage,
755    framework: SourceFramework,
756    role: SourceRole,
757    method: Option<String>,
758    path: Option<String>,
759    symbol_name: Option<String>,
760    lines: SourceLineRange,
761    warning: SourceWarning,
762) -> SourceObservation {
763    SourceObservation {
764        language,
765        framework,
766        role,
767        method,
768        path,
769        symbol_name,
770        related_symbol: None,
771        related_path: None,
772        authority: None,
773        router: None,
774        mount_parent: None,
775        url: None,
776        call: None,
777        lines,
778        status: SourceEpistemicStatus::Incomplete,
779        confidence: 0.0,
780        warnings: vec![warning],
781    }
782}
783
784/// Removes a trailing `//` comment that starts outside string literals.
785fn strip_line_comment(line: &str) -> &str {
786    let mut quote = None;
787    let mut previous = '\0';
788    for (index, character) in line.char_indices() {
789        match quote {
790            Some(active) if character == active && previous != '\\' => quote = None,
791            None if matches!(character, '\'' | '"' | '`') => quote = Some(character),
792            None if character == '/' && previous == '/' => return &line[..index - 1],
793            Some(_) | None => {}
794        }
795        previous = if previous == '\\' && character == '\\' {
796            '\0'
797        } else {
798            character
799        };
800    }
801    line
802}
803
804fn first_literal_after_call(text: &str) -> Option<String> {
805    let open = text.find('(')?;
806    quoted_value(&text[open + 1..])
807}
808
809fn literal_after(text: &str, marker: &str) -> Option<String> {
810    let start = text.find(marker)? + marker.len();
811    quoted_value(&text[start..])
812}
813
814fn quoted_value(text: &str) -> Option<String> {
815    quoted_values(text).into_iter().next()
816}
817
818pub(crate) fn quoted_values(text: &str) -> Vec<String> {
819    let mut values = Vec::new();
820    let mut quote = None;
821    let mut start = 0;
822    for (index, character) in text.char_indices() {
823        if let Some(active) = quote {
824            if character == active && !text[..index].ends_with('\\') {
825                values.push(text[start..index].to_owned());
826                quote = None;
827            }
828        } else if character == '\'' || character == '"' || character == '`' {
829            quote = Some(character);
830            start = index + character.len_utf8();
831        }
832    }
833    values
834}
835
836fn assigned_receivers(source: &str, factory: &str) -> BTreeSet<String> {
837    source
838        .lines()
839        .filter_map(|line| {
840            let (left, right) = line.split_once('=')?;
841            if !right.contains(&format!("{factory}("))
842                && !right.contains(&format!("{factory}.Router("))
843            {
844                return None;
845            }
846            left.split_whitespace()
847                .next_back()
848                .map(|name| name.trim().to_owned())
849        })
850        .collect()
851}
852
853/// Handler symbol of a route registration: its last argument as a dotted name, unwrapped from
854/// single-argument wrapper calls such as `asyncHandler(controller.list)`, or `METHOD path` for an
855/// inline function, which has no name of its own.
856fn route_symbol(text: &str, method: Option<&str>) -> Option<String> {
857    let arguments = top_level_arguments(text)?;
858    if arguments.len() < 2 {
859        return None;
860    }
861    let mut handler = arguments.last()?.trim();
862    loop {
863        let unprefixed = handler
864            .strip_prefix("async")
865            .map_or(handler, str::trim_start);
866        let inline = ["function", "(", "func(", "func "]
867            .iter()
868            .any(|prefix| unprefixed.starts_with(prefix))
869            || unprefixed
870                .split_once("=>")
871                .is_some_and(|(parameter, _)| is_dotted_name(parameter.trim()));
872        if inline {
873            let path = first_literal_after_call(text)?;
874            return Some(match method {
875                Some(method) => format!("{method} {path}"),
876                None => path,
877            });
878        }
879        let name = handler.trim_start_matches('&');
880        if is_dotted_name(name) {
881            return Some(name.to_owned());
882        }
883        let (callee, rest) = handler.split_once('(')?;
884        let inner = rest.strip_suffix(')')?.trim();
885        if !is_dotted_name(callee.trim())
886            || inner.is_empty()
887            || top_level_arguments(&format!("({inner})"))?.len() != 1
888        {
889            return None;
890        }
891        handler = inner;
892    }
893}
894
895fn is_dotted_name(text: &str) -> bool {
896    !text.is_empty()
897        && !text.starts_with('.')
898        && !text.ends_with('.')
899        && !text.starts_with(|character: char| character.is_ascii_digit())
900        && text.chars().all(|character| {
901            character.is_ascii_alphanumeric() || matches!(character, '_' | '$' | '.')
902        })
903}
904
905/// Top-level arguments of the first call in `text`, ignoring nested groups and string contents.
906fn top_level_arguments(text: &str) -> Option<Vec<&str>> {
907    let open = text.find('(')?;
908    let mut arguments = Vec::new();
909    let mut depth = 0_u32;
910    let mut quote = None;
911    let mut escaped = false;
912    let mut start = open + 1;
913    for (offset, character) in text[open + 1..].char_indices() {
914        let index = open + 1 + offset;
915        if let Some(delimiter) = quote {
916            if escaped {
917                escaped = false;
918            } else if character == '\\' {
919                escaped = true;
920            } else if character == delimiter {
921                quote = None;
922            }
923            continue;
924        }
925        match character {
926            '"' | '\'' | '`' => quote = Some(character),
927            '(' | '[' | '{' => depth += 1,
928            ')' | ']' | '}' if depth == 0 => {
929                arguments.push(&text[start..index]);
930                return Some(arguments);
931            }
932            ')' | ']' | '}' => depth -= 1,
933            ',' if depth == 0 => {
934                arguments.push(&text[start..index]);
935                start = index + 1;
936            }
937            _ => {}
938        }
939    }
940    None
941}
942
943fn canonical_method(value: &str) -> Option<String> {
944    METHODS.iter().find_map(|(name, method)| {
945        name.eq_ignore_ascii_case(value)
946            .then_some((*method).to_owned())
947    })
948}
949
950fn literal_path(value: &str) -> Option<String> {
951    if value.contains("${") || value.contains('{') && !value.starts_with('/') {
952        return None;
953    }
954    let path = if value.starts_with('/') {
955        value
956    } else {
957        let after_scheme = value
958            .strip_prefix("http://")
959            .or_else(|| value.strip_prefix("https://"))?;
960        after_scheme
961            .find('/')
962            .map_or("/", |index| &after_scheme[index..])
963    };
964    Some(normalize_source_http_path(
965        path.split(['?', '#']).next().unwrap_or(path),
966    ))
967}
968
969/// Whether the annotation on `index` precedes a class or interface declaration.
970fn java_annotates_type(lines: &[&str], index: usize) -> bool {
971    if !lines[index].trim_start().starts_with('@') {
972        return false;
973    }
974    lines
975        .iter()
976        .skip(index + 1)
977        .map(|line| line.trim())
978        .find(|line| !line.is_empty() && !line.starts_with('@') && !line.starts_with("//"))
979        .is_some_and(|declaration| {
980            declaration
981                .split_whitespace()
982                .any(|token| matches!(token, "class" | "interface" | "record"))
983        })
984}
985
986fn feign_path(line: &str) -> Option<String> {
987    let at = line.find("path")?;
988    let rest = line[at + "path".len()..].trim_start().strip_prefix('=')?;
989    quoted_value(rest)
990}
991
992fn java_mapping(line: &str) -> Option<(Option<String>, Option<String>)> {
993    for (annotation, method) in [
994        ("@DeleteMapping", "DELETE"),
995        ("@GetMapping", "GET"),
996        ("@PatchMapping", "PATCH"),
997        ("@PostMapping", "POST"),
998        ("@PutMapping", "PUT"),
999    ] {
1000        if line.starts_with(annotation) {
1001            return Some((Some(method.to_owned()), literal_after(line, annotation)));
1002        }
1003    }
1004    if line.starts_with("@RequestMapping") {
1005        let method = METHODS.iter().find_map(|(_, method)| {
1006            line.contains(&format!("RequestMethod.{method}"))
1007                .then_some((*method).to_owned())
1008        });
1009        return Some((method, quoted_value(line)));
1010    }
1011    None
1012}
1013
1014fn nest_mapping(line: &str) -> Option<(String, Option<String>)> {
1015    for (name, method) in [
1016        ("Delete", "DELETE"),
1017        ("Get", "GET"),
1018        ("Head", "HEAD"),
1019        ("Options", "OPTIONS"),
1020        ("Patch", "PATCH"),
1021        ("Post", "POST"),
1022        ("Put", "PUT"),
1023    ] {
1024        let marker = format!("@{name}(");
1025        if let Some(at) = line.find(&marker) {
1026            let arguments = &line[at + marker.len()..];
1027            let literal = (!arguments.trim_start().starts_with(')'))
1028                .then(|| literal_after(line, &marker))
1029                .flatten();
1030            return Some((method.to_owned(), literal));
1031        }
1032    }
1033    None
1034}
1035
1036fn java_method_name(line: &str) -> Option<String> {
1037    let before = line.split('(').next()?.trim();
1038    before
1039        .split_whitespace()
1040        .next_back()
1041        .filter(|name| !name.starts_with('@'))
1042        .map(str::to_owned)
1043}
1044
1045fn ecmascript_method_name(line: &str) -> Option<String> {
1046    let before = line.split('(').next()?.trim();
1047    before
1048        .split_whitespace()
1049        .next_back()
1050        .filter(|name| {
1051            !name.starts_with('@')
1052                && name
1053                    .chars()
1054                    .all(|character| character.is_ascii_alphanumeric() || character == '_')
1055        })
1056        .map(str::to_owned)
1057}
1058
1059fn finish(mut observations: Vec<SourceObservation>) -> Vec<SourceObservation> {
1060    observations.sort_by(|left, right| {
1061        (
1062            left.lines,
1063            left.framework,
1064            left.role,
1065            &left.method,
1066            &left.path,
1067            &left.symbol_name,
1068        )
1069            .cmp(&(
1070                right.lines,
1071                right.framework,
1072                right.role,
1073                &right.method,
1074                &right.path,
1075                &right.symbol_name,
1076            ))
1077    });
1078    observations.dedup();
1079    observations
1080}
1081
1082fn line_number(index: usize) -> u32 {
1083    u32::try_from(index.saturating_add(1)).unwrap_or(u32::MAX)
1084}
1085
1086#[cfg(test)]
1087mod tests {
1088    use super::{
1089        parse_go_source, parse_java_source, parse_javascript_source_at_path, parse_javascript_source_at_path_with_tracker, parse_typescript_source, parse_typescript_source_at_path
1090    };
1091    use crate::{
1092        ExtractionBudgets, ExtractionResource, ExtractionTracker, SourceEpistemicStatus, SourceFramework, SourceRole
1093    };
1094
1095    #[test]
1096    fn polyglot_parser_should_charge_each_attempted_observation_before_retention() {
1097        let budgets = ExtractionBudgets {
1098            max_observations_per_artifact: 1,
1099            ..ExtractionBudgets::default()
1100        };
1101        let mut tracker = ExtractionTracker::new("client.js", "source.javascript", &budgets);
1102        let result = parse_javascript_source_at_path_with_tracker(
1103            "client.js",
1104            "fetch('/one');\nfetch('/two');\n",
1105            &mut tracker,
1106        );
1107
1108        assert!(matches!(
1109            result,
1110            Err(error)
1111                if error.resource == ExtractionResource::Observations
1112                    && error.observed == 2
1113                    && error.maximum == 1
1114        ));
1115    }
1116
1117    #[test]
1118    fn route_handlers_should_be_named_through_members_middleware_wrappers_and_inline_functions() {
1119        let express = r#"
1120import express from "express";
1121const app = express();
1122app.get("/orders", auth, orders.list);
1123app.post("/orders", asyncHandler(orders.create));
1124app.delete("/orders/:id", async (req, res) => { res.sendStatus(204); });
1125"#;
1126        let gin = r#"
1127package main
1128import "github.com/gin-gonic/gin"
1129func main() {
1130	r := gin.Default()
1131	r.GET("/orders/:id", handlers.GetOrder)
1132}
1133"#;
1134        let handlers = parse_typescript_source(express)
1135            .into_iter()
1136            .chain(parse_go_source(gin))
1137            .filter(|item| item.role == SourceRole::Provider)
1138            .map(|item| item.symbol_name.unwrap_or_default())
1139            .collect::<Vec<_>>();
1140
1141        assert_eq!(
1142            handlers,
1143            [
1144                "orders.list",
1145                "orders.create",
1146                "DELETE /orders/:id",
1147                "handlers.GetOrder"
1148            ]
1149        );
1150    }
1151
1152    #[test]
1153    fn spring_handlers_should_be_the_method_declared_after_the_mapping() {
1154        let source = r#"
1155import org.springframework.web.bind.annotation.*;
1156
1157@RestController
1158@RequestMapping("/orders")
1159class OrdersController {
1160    @GetMapping("/{id}")
1161    @Operation(
1162        summary = "Read one order (by id)",
1163        description = "Returns the order")
1164    @PreAuthorize("hasRole('reader')")
1165    public Order read(@PathVariable String id) { return null; }
1166
1167    @PostMapping public Order create(@RequestBody Order order) { return order; }
1168}
1169"#;
1170        let handlers = parse_java_source(source)
1171            .into_iter()
1172            .filter(|item| item.role == SourceRole::Provider)
1173            .map(|item| item.symbol_name.unwrap_or_default())
1174            .collect::<Vec<_>>();
1175
1176        assert_eq!(handlers, ["read", "create"]);
1177    }
1178
1179    #[test]
1180    fn typescript_should_extract_fetch_axios_express_fastify_and_nestjs() {
1181        let source = r#"
1182import express from "express";
1183import fastify from "fastify";
1184import axios from "axios";
1185import { Controller, Get } from "@nestjs/common";
1186const app = express();
1187const server = fastify();
1188app.post("/orders", createOrder);
1189server.get("/health", health);
1190fetch("https://api.test/items", { method: "PATCH" });
1191axios.delete("/items/1");
1192@Get("/users")
1193listUsers() {}
1194"#;
1195        let result = parse_typescript_source(source);
1196
1197        assert!(
1198            [
1199                SourceFramework::Fetch,
1200                SourceFramework::Axios,
1201                SourceFramework::Express,
1202                SourceFramework::Fastify,
1203                SourceFramework::NestJs,
1204            ]
1205            .into_iter()
1206            .all(|framework| result.iter().any(|item| item.framework == framework))
1207        );
1208    }
1209
1210    #[test]
1211    fn absolute_urls_should_survive_comment_stripping_and_record_their_authority() {
1212        let source = "export async function load() {\n  await fetch('http://Orders-API:8080/v1/orders/42'); // primary\n  await fetch(\"https://payments.example.com/v1/orders/42\");\n}\n";
1213
1214        let result = parse_typescript_source(source);
1215        let calls = result
1216            .iter()
1217            .map(|item| (item.status, item.path.as_deref(), item.authority.as_deref()))
1218            .collect::<Vec<_>>();
1219
1220        assert_eq!(
1221            calls,
1222            [
1223                (
1224                    SourceEpistemicStatus::Confirmed,
1225                    Some("/v1/orders/42"),
1226                    Some("orders-api:8080")
1227                ),
1228                (
1229                    SourceEpistemicStatus::Confirmed,
1230                    Some("/v1/orders/42"),
1231                    Some("payments.example.com")
1232                ),
1233            ]
1234        );
1235    }
1236
1237    #[test]
1238    fn multiline_fetch_should_preserve_literal_method_and_path() {
1239        let result = parse_typescript_source(include_str!(
1240            "../../../fixtures/platform-demo/web/src/checkout.ts"
1241        ));
1242
1243        assert!(
1244            result.iter().any(|item| {
1245                item.framework == SourceFramework::Fetch
1246                    && item.method.as_deref() == Some("POST")
1247                    && item.path.as_deref() == Some("/api/orders")
1248            }),
1249            "{result:?}"
1250        );
1251    }
1252
1253    #[test]
1254    fn next_app_router_should_derive_static_and_dynamic_file_routes() {
1255        let javascript = "export async function POST(request) {}\n";
1256        let typescript = "export const GET = async () => {};\n";
1257
1258        let post =
1259            parse_javascript_source_at_path("frontend/src/app/api/cloudflare/route.js", javascript);
1260        let get = parse_typescript_source_at_path(
1261            "src/app/(public)/users/[user_id]/route.ts",
1262            typescript,
1263        );
1264
1265        assert!(post.iter().any(|item| {
1266            item.framework == SourceFramework::NextJs
1267                && item.method.as_deref() == Some("POST")
1268                && item.path.as_deref() == Some("/api/cloudflare")
1269        }));
1270        assert!(get.iter().any(|item| {
1271            item.framework == SourceFramework::NextJs
1272                && item.method.as_deref() == Some("GET")
1273                && item.path.as_deref() == Some("/users/{user_id}")
1274        }));
1275    }
1276
1277    #[test]
1278    fn go_should_extract_net_http_gin_and_chi_without_promoting_handle_func_method() {
1279        let source = r#"
1280import "net/http"
1281import "github.com/gin-gonic/gin"
1282import "github.com/go-chi/chi/v5"
1283http.NewRequest("POST", "https://api.test/orders", nil)
1284http.HandleFunc("/health", health)
1285router.GET("/users", users)
1286r.Delete("/users/{id}", deleteUser)
1287"#;
1288        let result = parse_go_source(source);
1289
1290        assert!(
1291            result
1292                .iter()
1293                .any(|item| item.framework == SourceFramework::GoNetHttp
1294                    && item.role == SourceRole::Consumer
1295                    && item.method.as_deref() == Some("POST"))
1296        );
1297        assert!(
1298            result
1299                .iter()
1300                .any(|item| item.framework == SourceFramework::Gin)
1301        );
1302        assert!(
1303            result
1304                .iter()
1305                .any(|item| item.framework == SourceFramework::Chi)
1306        );
1307        assert!(result.iter().any(|item| {
1308            item.framework == SourceFramework::GoNetHttp
1309                && item.status == SourceEpistemicStatus::Incomplete
1310        }));
1311    }
1312
1313    #[test]
1314    fn java_should_extract_spring_webclient_and_feign_roles() {
1315        let spring = r#"
1316import org.springframework.web.bind.annotation.GetMapping;
1317import org.springframework.web.reactive.function.client.WebClient;
1318@GetMapping("/orders")
1319public List<Order> orders() {}
1320client.post().uri("/events").retrieve();
1321"#;
1322        let feign = r#"
1323import org.springframework.web.bind.annotation.PostMapping;
1324import org.springframework.cloud.openfeign.FeignClient;
1325@FeignClient(name = "orders")
1326@PostMapping("/orders")
1327Order create();
1328"#;
1329        let spring_result = parse_java_source(spring);
1330        let feign_result = parse_java_source(feign);
1331
1332        assert!(spring_result.iter().any(|item| {
1333            item.framework == SourceFramework::SpringMvc && item.role == SourceRole::Provider
1334        }));
1335        assert!(
1336            spring_result
1337                .iter()
1338                .any(|item| item.framework == SourceFramework::WebClient)
1339        );
1340        assert!(
1341            feign_result
1342                .iter()
1343                .any(|item| item.framework == SourceFramework::Feign
1344                    && item.role == SourceRole::Consumer)
1345        );
1346    }
1347}