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        symbol_start_line: None,
732        related_symbol: None,
733        related_path: None,
734        authority,
735        router: None,
736        mount_parent: None,
737        url: None,
738        call: None,
739        lines,
740        status: if confirmed {
741            SourceEpistemicStatus::Confirmed
742        } else {
743            SourceEpistemicStatus::Ambiguous
744        },
745        confidence: if confirmed { 1.0 } else { 0.0 },
746        warnings,
747    }
748}
749
750#[expect(
751    clippy::too_many_arguments,
752    reason = "Incomplete observations preserve every available direct coordinate"
753)]
754fn incomplete_observation(
755    language: SourceLanguage,
756    framework: SourceFramework,
757    role: SourceRole,
758    method: Option<String>,
759    path: Option<String>,
760    symbol_name: Option<String>,
761    lines: SourceLineRange,
762    warning: SourceWarning,
763) -> SourceObservation {
764    SourceObservation {
765        language,
766        framework,
767        role,
768        method,
769        path,
770        symbol_name,
771        symbol_start_line: None,
772        related_symbol: None,
773        related_path: None,
774        authority: None,
775        router: None,
776        mount_parent: None,
777        url: None,
778        call: None,
779        lines,
780        status: SourceEpistemicStatus::Incomplete,
781        confidence: 0.0,
782        warnings: vec![warning],
783    }
784}
785
786/// Removes a trailing `//` comment that starts outside string literals.
787fn strip_line_comment(line: &str) -> &str {
788    let mut quote = None;
789    let mut previous = '\0';
790    for (index, character) in line.char_indices() {
791        match quote {
792            Some(active) if character == active && previous != '\\' => quote = None,
793            None if matches!(character, '\'' | '"' | '`') => quote = Some(character),
794            None if character == '/' && previous == '/' => return &line[..index - 1],
795            Some(_) | None => {}
796        }
797        previous = if previous == '\\' && character == '\\' {
798            '\0'
799        } else {
800            character
801        };
802    }
803    line
804}
805
806fn first_literal_after_call(text: &str) -> Option<String> {
807    let open = text.find('(')?;
808    quoted_value(&text[open + 1..])
809}
810
811fn literal_after(text: &str, marker: &str) -> Option<String> {
812    let start = text.find(marker)? + marker.len();
813    quoted_value(&text[start..])
814}
815
816fn quoted_value(text: &str) -> Option<String> {
817    quoted_values(text).into_iter().next()
818}
819
820pub(crate) fn quoted_values(text: &str) -> Vec<String> {
821    let mut values = Vec::new();
822    let mut quote = None;
823    let mut start = 0;
824    for (index, character) in text.char_indices() {
825        if let Some(active) = quote {
826            if character == active && !text[..index].ends_with('\\') {
827                values.push(text[start..index].to_owned());
828                quote = None;
829            }
830        } else if character == '\'' || character == '"' || character == '`' {
831            quote = Some(character);
832            start = index + character.len_utf8();
833        }
834    }
835    values
836}
837
838fn assigned_receivers(source: &str, factory: &str) -> BTreeSet<String> {
839    source
840        .lines()
841        .filter_map(|line| {
842            let (left, right) = line.split_once('=')?;
843            if !right.contains(&format!("{factory}("))
844                && !right.contains(&format!("{factory}.Router("))
845            {
846                return None;
847            }
848            left.split_whitespace()
849                .next_back()
850                .map(|name| name.trim().to_owned())
851        })
852        .collect()
853}
854
855/// Handler symbol of a route registration: its last argument as a dotted name, unwrapped from
856/// single-argument wrapper calls such as `asyncHandler(controller.list)`, or `METHOD path` for an
857/// inline function, which has no name of its own.
858fn route_symbol(text: &str, method: Option<&str>) -> Option<String> {
859    let arguments = top_level_arguments(text)?;
860    if arguments.len() < 2 {
861        return None;
862    }
863    let mut handler = arguments.last()?.trim();
864    loop {
865        let unprefixed = handler
866            .strip_prefix("async")
867            .map_or(handler, str::trim_start);
868        let inline = ["function", "(", "func(", "func "]
869            .iter()
870            .any(|prefix| unprefixed.starts_with(prefix))
871            || unprefixed
872                .split_once("=>")
873                .is_some_and(|(parameter, _)| is_dotted_name(parameter.trim()));
874        if inline {
875            let path = first_literal_after_call(text)?;
876            return Some(match method {
877                Some(method) => format!("{method} {path}"),
878                None => path,
879            });
880        }
881        let name = handler.trim_start_matches('&');
882        if is_dotted_name(name) {
883            return Some(name.to_owned());
884        }
885        let (callee, rest) = handler.split_once('(')?;
886        let inner = rest.strip_suffix(')')?.trim();
887        if !is_dotted_name(callee.trim())
888            || inner.is_empty()
889            || top_level_arguments(&format!("({inner})"))?.len() != 1
890        {
891            return None;
892        }
893        handler = inner;
894    }
895}
896
897fn is_dotted_name(text: &str) -> bool {
898    !text.is_empty()
899        && !text.starts_with('.')
900        && !text.ends_with('.')
901        && !text.starts_with(|character: char| character.is_ascii_digit())
902        && text.chars().all(|character| {
903            character.is_ascii_alphanumeric() || matches!(character, '_' | '$' | '.')
904        })
905}
906
907/// Top-level arguments of the first call in `text`, ignoring nested groups and string contents.
908fn top_level_arguments(text: &str) -> Option<Vec<&str>> {
909    let open = text.find('(')?;
910    let mut arguments = Vec::new();
911    let mut depth = 0_u32;
912    let mut quote = None;
913    let mut escaped = false;
914    let mut start = open + 1;
915    for (offset, character) in text[open + 1..].char_indices() {
916        let index = open + 1 + offset;
917        if let Some(delimiter) = quote {
918            if escaped {
919                escaped = false;
920            } else if character == '\\' {
921                escaped = true;
922            } else if character == delimiter {
923                quote = None;
924            }
925            continue;
926        }
927        match character {
928            '"' | '\'' | '`' => quote = Some(character),
929            '(' | '[' | '{' => depth += 1,
930            ')' | ']' | '}' if depth == 0 => {
931                arguments.push(&text[start..index]);
932                return Some(arguments);
933            }
934            ')' | ']' | '}' => depth -= 1,
935            ',' if depth == 0 => {
936                arguments.push(&text[start..index]);
937                start = index + 1;
938            }
939            _ => {}
940        }
941    }
942    None
943}
944
945fn canonical_method(value: &str) -> Option<String> {
946    METHODS.iter().find_map(|(name, method)| {
947        name.eq_ignore_ascii_case(value)
948            .then_some((*method).to_owned())
949    })
950}
951
952fn literal_path(value: &str) -> Option<String> {
953    if value.contains("${") || value.contains('{') && !value.starts_with('/') {
954        return None;
955    }
956    let path = if value.starts_with('/') {
957        value
958    } else {
959        let after_scheme = value
960            .strip_prefix("http://")
961            .or_else(|| value.strip_prefix("https://"))?;
962        after_scheme
963            .find('/')
964            .map_or("/", |index| &after_scheme[index..])
965    };
966    Some(normalize_source_http_path(
967        path.split(['?', '#']).next().unwrap_or(path),
968    ))
969}
970
971/// Whether the annotation on `index` precedes a class or interface declaration.
972fn java_annotates_type(lines: &[&str], index: usize) -> bool {
973    if !lines[index].trim_start().starts_with('@') {
974        return false;
975    }
976    lines
977        .iter()
978        .skip(index + 1)
979        .map(|line| line.trim())
980        .find(|line| !line.is_empty() && !line.starts_with('@') && !line.starts_with("//"))
981        .is_some_and(|declaration| {
982            declaration
983                .split_whitespace()
984                .any(|token| matches!(token, "class" | "interface" | "record"))
985        })
986}
987
988fn feign_path(line: &str) -> Option<String> {
989    let at = line.find("path")?;
990    let rest = line[at + "path".len()..].trim_start().strip_prefix('=')?;
991    quoted_value(rest)
992}
993
994fn java_mapping(line: &str) -> Option<(Option<String>, Option<String>)> {
995    for (annotation, method) in [
996        ("@DeleteMapping", "DELETE"),
997        ("@GetMapping", "GET"),
998        ("@PatchMapping", "PATCH"),
999        ("@PostMapping", "POST"),
1000        ("@PutMapping", "PUT"),
1001    ] {
1002        if line.starts_with(annotation) {
1003            return Some((Some(method.to_owned()), literal_after(line, annotation)));
1004        }
1005    }
1006    if line.starts_with("@RequestMapping") {
1007        let method = METHODS.iter().find_map(|(_, method)| {
1008            line.contains(&format!("RequestMethod.{method}"))
1009                .then_some((*method).to_owned())
1010        });
1011        return Some((method, quoted_value(line)));
1012    }
1013    None
1014}
1015
1016fn nest_mapping(line: &str) -> Option<(String, Option<String>)> {
1017    for (name, method) in [
1018        ("Delete", "DELETE"),
1019        ("Get", "GET"),
1020        ("Head", "HEAD"),
1021        ("Options", "OPTIONS"),
1022        ("Patch", "PATCH"),
1023        ("Post", "POST"),
1024        ("Put", "PUT"),
1025    ] {
1026        let marker = format!("@{name}(");
1027        if let Some(at) = line.find(&marker) {
1028            let arguments = &line[at + marker.len()..];
1029            let literal = (!arguments.trim_start().starts_with(')'))
1030                .then(|| literal_after(line, &marker))
1031                .flatten();
1032            return Some((method.to_owned(), literal));
1033        }
1034    }
1035    None
1036}
1037
1038fn java_method_name(line: &str) -> Option<String> {
1039    let before = line.split('(').next()?.trim();
1040    before
1041        .split_whitespace()
1042        .next_back()
1043        .filter(|name| !name.starts_with('@'))
1044        .map(str::to_owned)
1045}
1046
1047fn ecmascript_method_name(line: &str) -> Option<String> {
1048    let before = line.split('(').next()?.trim();
1049    before
1050        .split_whitespace()
1051        .next_back()
1052        .filter(|name| {
1053            !name.starts_with('@')
1054                && name
1055                    .chars()
1056                    .all(|character| character.is_ascii_alphanumeric() || character == '_')
1057        })
1058        .map(str::to_owned)
1059}
1060
1061fn finish(mut observations: Vec<SourceObservation>) -> Vec<SourceObservation> {
1062    observations.sort_by(|left, right| {
1063        (
1064            left.lines,
1065            left.framework,
1066            left.role,
1067            &left.method,
1068            &left.path,
1069            &left.symbol_name,
1070        )
1071            .cmp(&(
1072                right.lines,
1073                right.framework,
1074                right.role,
1075                &right.method,
1076                &right.path,
1077                &right.symbol_name,
1078            ))
1079    });
1080    observations.dedup();
1081    observations
1082}
1083
1084fn line_number(index: usize) -> u32 {
1085    u32::try_from(index.saturating_add(1)).unwrap_or(u32::MAX)
1086}
1087
1088#[cfg(test)]
1089mod tests {
1090    use super::{
1091        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
1092    };
1093    use crate::{
1094        ExtractionBudgets, ExtractionResource, ExtractionTracker, SourceEpistemicStatus, SourceFramework, SourceRole
1095    };
1096
1097    #[test]
1098    fn polyglot_parser_should_charge_each_attempted_observation_before_retention() {
1099        let budgets = ExtractionBudgets {
1100            max_observations_per_artifact: 1,
1101            ..ExtractionBudgets::default()
1102        };
1103        let mut tracker = ExtractionTracker::new("client.js", "source.javascript", &budgets);
1104        let result = parse_javascript_source_at_path_with_tracker(
1105            "client.js",
1106            "fetch('/one');\nfetch('/two');\n",
1107            &mut tracker,
1108        );
1109
1110        assert!(matches!(
1111            result,
1112            Err(error)
1113                if error.resource == ExtractionResource::Observations
1114                    && error.observed == 2
1115                    && error.maximum == 1
1116        ));
1117    }
1118
1119    #[test]
1120    fn route_handlers_should_be_named_through_members_middleware_wrappers_and_inline_functions() {
1121        let express = r#"
1122import express from "express";
1123const app = express();
1124app.get("/orders", auth, orders.list);
1125app.post("/orders", asyncHandler(orders.create));
1126app.delete("/orders/:id", async (req, res) => { res.sendStatus(204); });
1127"#;
1128        let gin = r#"
1129package main
1130import "github.com/gin-gonic/gin"
1131func main() {
1132	r := gin.Default()
1133	r.GET("/orders/:id", handlers.GetOrder)
1134}
1135"#;
1136        let handlers = parse_typescript_source(express)
1137            .into_iter()
1138            .chain(parse_go_source(gin))
1139            .filter(|item| item.role == SourceRole::Provider)
1140            .map(|item| item.symbol_name.unwrap_or_default())
1141            .collect::<Vec<_>>();
1142
1143        assert_eq!(
1144            handlers,
1145            [
1146                "orders.list",
1147                "orders.create",
1148                "DELETE /orders/:id",
1149                "handlers.GetOrder"
1150            ]
1151        );
1152    }
1153
1154    #[test]
1155    fn spring_handlers_should_be_the_method_declared_after_the_mapping() {
1156        let source = r#"
1157import org.springframework.web.bind.annotation.*;
1158
1159@RestController
1160@RequestMapping("/orders")
1161class OrdersController {
1162    @GetMapping("/{id}")
1163    @Operation(
1164        summary = "Read one order (by id)",
1165        description = "Returns the order")
1166    @PreAuthorize("hasRole('reader')")
1167    public Order read(@PathVariable String id) { return null; }
1168
1169    @PostMapping public Order create(@RequestBody Order order) { return order; }
1170}
1171"#;
1172        let handlers = parse_java_source(source)
1173            .into_iter()
1174            .filter(|item| item.role == SourceRole::Provider)
1175            .map(|item| item.symbol_name.unwrap_or_default())
1176            .collect::<Vec<_>>();
1177
1178        assert_eq!(handlers, ["read", "create"]);
1179    }
1180
1181    #[test]
1182    fn typescript_should_extract_fetch_axios_express_fastify_and_nestjs() {
1183        let source = r#"
1184import express from "express";
1185import fastify from "fastify";
1186import axios from "axios";
1187import { Controller, Get } from "@nestjs/common";
1188const app = express();
1189const server = fastify();
1190app.post("/orders", createOrder);
1191server.get("/health", health);
1192fetch("https://api.test/items", { method: "PATCH" });
1193axios.delete("/items/1");
1194@Get("/users")
1195listUsers() {}
1196"#;
1197        let result = parse_typescript_source(source);
1198
1199        assert!(
1200            [
1201                SourceFramework::Fetch,
1202                SourceFramework::Axios,
1203                SourceFramework::Express,
1204                SourceFramework::Fastify,
1205                SourceFramework::NestJs,
1206            ]
1207            .into_iter()
1208            .all(|framework| result.iter().any(|item| item.framework == framework))
1209        );
1210    }
1211
1212    #[test]
1213    fn absolute_urls_should_survive_comment_stripping_and_record_their_authority() {
1214        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";
1215
1216        let result = parse_typescript_source(source);
1217        let calls = result
1218            .iter()
1219            .map(|item| (item.status, item.path.as_deref(), item.authority.as_deref()))
1220            .collect::<Vec<_>>();
1221
1222        assert_eq!(
1223            calls,
1224            [
1225                (
1226                    SourceEpistemicStatus::Confirmed,
1227                    Some("/v1/orders/42"),
1228                    Some("orders-api:8080")
1229                ),
1230                (
1231                    SourceEpistemicStatus::Confirmed,
1232                    Some("/v1/orders/42"),
1233                    Some("payments.example.com")
1234                ),
1235            ]
1236        );
1237    }
1238
1239    #[test]
1240    fn multiline_fetch_should_preserve_literal_method_and_path() {
1241        let result = parse_typescript_source(include_str!(
1242            "../../../fixtures/platform-demo/web/src/checkout.ts"
1243        ));
1244
1245        assert!(
1246            result.iter().any(|item| {
1247                item.framework == SourceFramework::Fetch
1248                    && item.method.as_deref() == Some("POST")
1249                    && item.path.as_deref() == Some("/api/orders")
1250            }),
1251            "{result:?}"
1252        );
1253    }
1254
1255    #[test]
1256    fn next_app_router_should_derive_static_and_dynamic_file_routes() {
1257        let javascript = "export async function POST(request) {}\n";
1258        let typescript = "export const GET = async () => {};\n";
1259
1260        let post =
1261            parse_javascript_source_at_path("frontend/src/app/api/cloudflare/route.js", javascript);
1262        let get = parse_typescript_source_at_path(
1263            "src/app/(public)/users/[user_id]/route.ts",
1264            typescript,
1265        );
1266
1267        assert!(post.iter().any(|item| {
1268            item.framework == SourceFramework::NextJs
1269                && item.method.as_deref() == Some("POST")
1270                && item.path.as_deref() == Some("/api/cloudflare")
1271        }));
1272        assert!(get.iter().any(|item| {
1273            item.framework == SourceFramework::NextJs
1274                && item.method.as_deref() == Some("GET")
1275                && item.path.as_deref() == Some("/users/{user_id}")
1276        }));
1277    }
1278
1279    #[test]
1280    fn go_should_extract_net_http_gin_and_chi_without_promoting_handle_func_method() {
1281        let source = r#"
1282import "net/http"
1283import "github.com/gin-gonic/gin"
1284import "github.com/go-chi/chi/v5"
1285http.NewRequest("POST", "https://api.test/orders", nil)
1286http.HandleFunc("/health", health)
1287router.GET("/users", users)
1288r.Delete("/users/{id}", deleteUser)
1289"#;
1290        let result = parse_go_source(source);
1291
1292        assert!(
1293            result
1294                .iter()
1295                .any(|item| item.framework == SourceFramework::GoNetHttp
1296                    && item.role == SourceRole::Consumer
1297                    && item.method.as_deref() == Some("POST"))
1298        );
1299        assert!(
1300            result
1301                .iter()
1302                .any(|item| item.framework == SourceFramework::Gin)
1303        );
1304        assert!(
1305            result
1306                .iter()
1307                .any(|item| item.framework == SourceFramework::Chi)
1308        );
1309        assert!(result.iter().any(|item| {
1310            item.framework == SourceFramework::GoNetHttp
1311                && item.status == SourceEpistemicStatus::Incomplete
1312        }));
1313    }
1314
1315    #[test]
1316    fn java_should_extract_spring_webclient_and_feign_roles() {
1317        let spring = r#"
1318import org.springframework.web.bind.annotation.GetMapping;
1319import org.springframework.web.reactive.function.client.WebClient;
1320@GetMapping("/orders")
1321public List<Order> orders() {}
1322client.post().uri("/events").retrieve();
1323"#;
1324        let feign = r#"
1325import org.springframework.web.bind.annotation.PostMapping;
1326import org.springframework.cloud.openfeign.FeignClient;
1327@FeignClient(name = "orders")
1328@PostMapping("/orders")
1329Order create();
1330"#;
1331        let spring_result = parse_java_source(spring);
1332        let feign_result = parse_java_source(feign);
1333
1334        assert!(spring_result.iter().any(|item| {
1335            item.framework == SourceFramework::SpringMvc && item.role == SourceRole::Provider
1336        }));
1337        assert!(
1338            spring_result
1339                .iter()
1340                .any(|item| item.framework == SourceFramework::WebClient)
1341        );
1342        assert!(
1343            feign_result
1344                .iter()
1345                .any(|item| item.framework == SourceFramework::Feign
1346                    && item.role == SourceRole::Consumer)
1347        );
1348    }
1349}