Skip to main content

code_system_graph_core/
source_http.rs

1//! Dependency-free, evidence-first extraction of focused HTTP and test declarations.
2//!
3//! The parsers in this module recognize only framework-specific syntax and only promote literal
4//! methods and paths to confirmed observations. Dynamic expressions are retained as ambiguous or
5//! incomplete observations so downstream linking cannot mistake missing evidence for an exact
6//! contract.
7
8use std::cmp::Ordering;
9use std::collections::{BTreeMap, BTreeSet};
10
11use serde::{Deserialize, Serialize};
12
13use crate::router_mounts::mount_observation;
14use crate::{ExtractionLimitExceeded, ExtractionTracker};
15
16mod brace_clients;
17mod brace_flows;
18mod brace_lexer;
19mod brace_tests;
20mod python_flows;
21mod rust_bindings;
22mod rust_flows;
23mod rust_routers;
24mod rust_test_clients;
25
26pub(crate) use brace_clients::{BraceClients, collect_brace_clients, java_method_lines};
27use python_flows::{PythonScopes, keyword_argument, record_fixture_requests};
28use rust_flows::RustScopes;
29use rust_routers::{RustRouters, join_prefixes};
30
31const HTTP_METHODS: [&str; 8] = [
32    "DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT", "TRACE",
33];
34
35/// Source language understood by the focused parsers.
36#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
37#[serde(rename_all = "snake_case")]
38pub enum SourceLanguage {
39    /// JavaScript source.
40    JavaScript,
41    /// TypeScript source.
42    TypeScript,
43    /// Rust source.
44    Rust,
45    /// Python source.
46    Python,
47    /// Go source.
48    Go,
49    /// Java source.
50    Java,
51}
52
53/// Framework whose syntax supplied the direct evidence.
54#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
55#[serde(rename_all = "snake_case")]
56pub enum SourceFramework {
57    /// Browser or runtime Fetch API calls.
58    Fetch,
59    /// Axios HTTP client calls.
60    Axios,
61    /// Express route declarations.
62    Express,
63    /// Fastify route declarations.
64    Fastify,
65    /// `NestJS` controller declarations.
66    NestJs,
67    /// Next.js App Router file-route declarations.
68    NextJs,
69    /// Axum router declarations.
70    Axum,
71    /// Actix Web route declarations and route attributes.
72    ActixWeb,
73    /// Utoipa operation declarations, including Actix routes wrapped by `cfg_attr`.
74    Utoipa,
75    /// Reqwest client calls.
76    Reqwest,
77    /// Rust built-in `#[test]` functions.
78    RustTest,
79    /// Tokio `#[tokio::test]` functions.
80    TokioTest,
81    /// Rstest `#[rstest]` functions.
82    Rstest,
83    /// `FastAPI` route decorators.
84    FastApi,
85    /// Flask route decorators.
86    Flask,
87    /// Python requests calls.
88    Requests,
89    /// Python HTTPX calls.
90    Httpx,
91    /// Python aiohttp client-session calls.
92    AioHttp,
93    /// Statically declared Python HTTP method/path registries.
94    PythonHttpRegistry,
95    /// Factory Boy model and sub-factory declarations.
96    FactoryBoy,
97    /// Pytest test functions.
98    Pytest,
99    /// unittest `TestCase` methods.
100    Unittest,
101    /// Canonical `test_` methods in a Python class whose runner inheritance is resolved elsewhere.
102    PythonTest,
103    /// Go standard-library `net/http`.
104    GoNetHttp,
105    /// Gin route declarations.
106    Gin,
107    /// Chi route declarations.
108    Chi,
109    /// Spring MVC route declarations.
110    SpringMvc,
111    /// Spring `WebClient` calls.
112    WebClient,
113    /// Feign client declarations.
114    Feign,
115    /// Spring `RestTemplate` calls.
116    RestTemplate,
117    /// Starlette and `FastAPI` `TestClient`, and HTTPX clients bound to an ASGI or WSGI app.
118    TestClient,
119    /// Flask `app.test_client()` requests.
120    FlaskTestClient,
121    /// Jest tests.
122    Jest,
123    /// Vitest tests.
124    Vitest,
125    /// Mocha tests.
126    Mocha,
127    /// Playwright tests and `APIRequestContext` requests.
128    Playwright,
129    /// Supertest `request(app)` requests.
130    Supertest,
131    /// Go `testing` test functions.
132    GoTest,
133    /// Go `net/http/httptest` requests and servers.
134    Httptest,
135    /// `JUnit` `@Test` methods.
136    JUnit,
137    /// Spring `MockMvc` requests.
138    MockMvc,
139    /// REST Assured requests.
140    RestAssured,
141    /// Spring `WebTestClient` requests.
142    WebTestClient,
143    /// Spring Boot `TestRestTemplate` requests.
144    TestRestTemplate,
145    /// Axum `Router` requests sent with `tower::ServiceExt::oneshot`.
146    AxumOneshot,
147    /// Actix Web `test::TestRequest` requests.
148    ActixTest,
149}
150
151impl SourceFramework {
152    /// Whether requests of this client run in-process against the application of their own
153    /// repository.
154    #[must_use]
155    pub fn is_in_process_client(self) -> bool {
156        matches!(
157            self,
158            Self::TestClient
159                | Self::FlaskTestClient
160                | Self::Supertest
161                | Self::Httptest
162                | Self::MockMvc
163                | Self::RestAssured
164                | Self::WebTestClient
165                | Self::TestRestTemplate
166                | Self::AxumOneshot
167                | Self::ActixTest
168        )
169    }
170}
171
172/// Repository-boundary role represented by an observation.
173#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
174#[serde(rename_all = "snake_case")]
175pub enum SourceRole {
176    /// An HTTP operation served by the repository.
177    Provider,
178    /// An HTTP operation invoked by the repository.
179    Consumer,
180    /// A declared test case.
181    Test,
182    /// A data factory with one statically declared model target.
183    Factory,
184    /// A router mounted under a path prefix on another router or on the application root.
185    Mount,
186    /// A call from the enclosing function to another function of the repository.
187    Call,
188    /// A function, such as a pytest fixture, that returns an in-process test client.
189    Client,
190}
191
192/// Source-level reference to a router or function, resolved per repository.
193#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
194#[serde(rename_all = "snake_case")]
195pub enum SymbolRef {
196    /// A router bound to a name in the declaring file; `default` names a default export.
197    Local(String),
198    /// A router imported from another module, with the module specifier as written.
199    Import {
200        /// Module specifier, such as `./routes/users` or `app.api.users`.
201        module: String,
202        /// Imported name; `default` for default exports.
203        name: String,
204    },
205    /// The router built, returned, or configured by a function defined in the declaring file.
206    Function(String),
207    /// A function referenced by its path as written, such as `users::routes` or `routes.Register`.
208    Call(String),
209    /// A pytest fixture injected by parameter name, declared in the same file or in the nearest
210    /// enclosing `conftest.py`.
211    Fixture(String),
212    /// A parameter of the enclosing function, by name and zero-based position after receivers.
213    Parameter {
214        /// Declared parameter name.
215        name: String,
216        /// Position among the parameters a caller passes.
217        index: usize,
218    },
219}
220
221/// Client URL assembled from literal text and runtime values.
222#[derive(Debug, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
223pub struct UrlTemplate {
224    /// Parts in source order; adjacent text parts are merged.
225    pub parts: Vec<UrlPart>,
226}
227
228/// One part of a [`UrlTemplate`].
229#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
230#[serde(rename_all = "snake_case")]
231pub enum UrlPart {
232    /// Literal text.
233    Text(String),
234    /// A parameter of the enclosing function, by name and zero-based position after receivers.
235    Parameter {
236        /// Declared parameter name.
237        name: String,
238        /// Position among the parameters a caller passes.
239        index: usize,
240    },
241    /// Any other runtime value, named when it is a plain identifier.
242    Value(Option<String>),
243}
244
245/// Call recorded for repository-level client-wrapper and test-helper correlation.
246#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
247pub struct CallSite {
248    /// Called function.
249    pub callee: SymbolRef,
250    /// Arguments in source order, up to the last string expression.
251    #[serde(default, skip_serializing_if = "Vec::is_empty")]
252    pub arguments: Vec<CallArgument>,
253}
254
255/// One argument of a [`CallSite`].
256#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
257pub struct CallArgument {
258    /// Keyword under which the argument is passed.
259    #[serde(default, skip_serializing_if = "Option::is_none")]
260    pub keyword: Option<String>,
261    /// String value; `None` when the argument is not a string expression.
262    #[serde(default, skip_serializing_if = "Option::is_none")]
263    pub value: Option<UrlTemplate>,
264}
265
266/// Epistemic state of a source observation.
267#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
268#[serde(rename_all = "snake_case")]
269pub enum SourceEpistemicStatus {
270    /// Method and path, when applicable, are supported by exact literal syntax.
271    Confirmed,
272    /// A relevant framework operation was found, but a dynamic expression prevents exact identity.
273    Ambiguous,
274    /// Required method, path, or symbol evidence was absent.
275    Incomplete,
276}
277
278/// Inclusive one-based source range supporting an observation.
279#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
280pub struct SourceLineRange {
281    /// First line containing direct evidence.
282    pub start: u32,
283    /// Last line containing direct evidence.
284    pub end: u32,
285}
286
287/// Machine-readable limitation attached to an observation.
288#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
289#[serde(rename_all = "snake_case")]
290pub enum SourceWarning {
291    /// The HTTP method is computed rather than represented by a supported literal or method name.
292    DynamicMethod,
293    /// The URL or route path is computed rather than represented by one literal.
294    DynamicPath,
295    /// A literal URL is not an absolute URL or root-relative path.
296    UnsupportedLiteralPath,
297    /// The framework declaration did not expose an implementation symbol.
298    MissingSymbol,
299    /// Tree-sitter recovered from at least one syntax error in the source artifact.
300    SyntaxErrorRecovery,
301    /// A documentation-oriented declaration may drift from executable framework registration.
302    AdvisoryDeclaration,
303}
304
305/// Conversion-ready source evidence for an HTTP boundary, implementation, or test case.
306///
307/// Confirmed provider observations have enough method, path, and symbol evidence to construct an
308/// HTTP provider plus an implementation anchor. Confirmed consumers have exact method/path
309/// evidence. Test observations intentionally omit method/path; downstream correlation can join
310/// them to consumer observations with the same `symbol_name`.
311#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
312pub struct SourceObservation {
313    /// Language in which the evidence was found.
314    pub language: SourceLanguage,
315    /// Framework whose syntax was recognized.
316    pub framework: SourceFramework,
317    /// Provider, consumer, or test role.
318    pub role: SourceRole,
319    /// Canonical upper-case HTTP method when exactly known.
320    pub method: Option<String>,
321    /// Canonical normalized HTTP path when exactly known.
322    pub path: Option<String>,
323    /// Enclosing implementation symbol or test name when known.
324    pub symbol_name: Option<String>,
325    /// Declaration line of the innermost containing function, when precisely known.
326    #[serde(default, skip_serializing_if = "Option::is_none")]
327    pub symbol_start_line: Option<u32>,
328    /// Related model symbol for declarations such as Factory Boy `Meta.model`.
329    pub related_symbol: Option<String>,
330    /// Repository-relative module path that declares `related_symbol`, when statically imported.
331    pub related_path: Option<String>,
332    /// Lower-case `host[:port]` named by an absolute consumer URL.
333    #[serde(default, skip_serializing_if = "Option::is_none")]
334    pub authority: Option<String>,
335    /// Router a provider route is registered on, the router mounted by a mount observation, or
336    /// the parameter through which a consumer receives its client.
337    #[serde(default, skip_serializing_if = "Option::is_none")]
338    pub router: Option<SymbolRef>,
339    /// Router receiving a mount observation; `None` mounts at the application root.
340    #[serde(default, skip_serializing_if = "Option::is_none")]
341    pub mount_parent: Option<SymbolRef>,
342    /// Consumer URL that depends on parameters of the enclosing function.
343    #[serde(default, skip_serializing_if = "Option::is_none")]
344    pub url: Option<UrlTemplate>,
345    /// Called function and arguments of a call observation.
346    #[serde(default, skip_serializing_if = "Option::is_none")]
347    pub call: Option<CallSite>,
348    /// Inclusive source range containing the direct evidence.
349    pub lines: SourceLineRange,
350    /// Epistemic state of this observation.
351    pub status: SourceEpistemicStatus,
352    /// Normalized confidence in the inclusive range from zero to one.
353    pub confidence: f32,
354    /// Deterministically ordered extraction limitations.
355    pub warnings: Vec<SourceWarning>,
356}
357
358pub(crate) struct SourceObservationCollector<'a> {
359    observations: Vec<SourceObservation>,
360    tracker: Option<&'a mut ExtractionTracker>,
361    error: Option<ExtractionLimitExceeded>,
362}
363
364impl<'a> SourceObservationCollector<'a> {
365    pub(crate) fn unbounded() -> Self {
366        Self {
367            observations: Vec::new(),
368            tracker: None,
369            error: None,
370        }
371    }
372
373    pub(crate) fn bounded(tracker: &'a mut ExtractionTracker) -> Self {
374        Self {
375            observations: Vec::new(),
376            tracker: Some(tracker),
377            error: None,
378        }
379    }
380
381    pub(crate) fn push(&mut self, observation: SourceObservation) {
382        if self.error.is_some() {
383            return;
384        }
385        if let Some(tracker) = self.tracker.as_deref_mut()
386            && let Err(error) = tracker
387                .charge_observation(1)
388                .and_then(|()| charge_source_observation_values(&observation, tracker))
389        {
390            self.error = Some(error);
391            return;
392        }
393        self.observations.push(observation);
394    }
395
396    fn locate_symbols(&mut self, tokens: &[Token], functions: &[FunctionSpan]) {
397        for observation in &mut self.observations {
398            let containing = functions
399                .iter()
400                .filter(|function| {
401                    tokens[function.start_token].line <= observation.lines.start
402                        && tokens[function.end_token].line >= observation.lines.end
403                })
404                .min_by_key(|function| function.end_token - function.start_token);
405            observation.symbol_start_line = containing
406                .filter(|function| {
407                    observation.symbol_name.as_deref() == Some(function.name.as_str())
408                        && functions
409                            .iter()
410                            .filter(|other| {
411                                other.name == function.name
412                                    && tokens[other.start_token].line
413                                        == tokens[function.start_token].line
414                            })
415                            .count()
416                            == 1
417                })
418                .map(|function| tokens[function.start_token].line);
419        }
420    }
421
422    pub(crate) fn into_result(self) -> Result<Vec<SourceObservation>, ExtractionLimitExceeded> {
423        match self.error {
424            Some(error) => Err(error),
425            None => Ok(self.observations),
426        }
427    }
428
429    pub(crate) fn into_unbounded(self) -> Vec<SourceObservation> {
430        self.observations
431    }
432
433    pub(crate) fn has_role(&self, role: SourceRole) -> bool {
434        self.observations
435            .iter()
436            .any(|observation| observation.role == role)
437    }
438}
439
440pub(crate) fn charge_source_observation_values(
441    observation: &SourceObservation,
442    tracker: &mut ExtractionTracker,
443) -> Result<(), ExtractionLimitExceeded> {
444    if let Some(method) = &observation.method {
445        tracker.charge_identifier(method)?;
446    }
447    if let Some(path) = &observation.path {
448        tracker.charge_portable_path(path)?;
449    }
450    for symbol in [
451        observation.symbol_name.as_deref(),
452        observation.related_symbol.as_deref(),
453    ]
454    .into_iter()
455    .flatten()
456    {
457        tracker.charge_identifier(symbol)?;
458    }
459    if let Some(path) = &observation.related_path {
460        tracker.charge_portable_path(path)?;
461    }
462    let call_values = observation
463        .call
464        .iter()
465        .flat_map(|call| &call.arguments)
466        .filter_map(|argument| argument.value.as_ref());
467    for template in observation.url.iter().chain(call_values) {
468        for part in &template.parts {
469            match part {
470                UrlPart::Text(text) => tracker.charge_string(text)?,
471                UrlPart::Parameter { name, .. } | UrlPart::Value(Some(name)) => {
472                    tracker.charge_identifier(name)?;
473                }
474                UrlPart::Value(None) => {}
475            }
476        }
477    }
478    Ok(())
479}
480
481/// Parses the mandatory focused Rust framework matrix.
482///
483/// Supported syntax comprises Axum `route` declarations, Actix Web route attributes and builder
484/// routes, Reqwest convenience/request calls, and built-in, Tokio, and rstest test attributes.
485/// The returned vector is sorted and deduplicated deterministically.
486#[must_use]
487pub fn parse_rust_source(source: &str) -> Vec<SourceObservation> {
488    let collector = collect_rust_source(source, SourceObservationCollector::unbounded());
489    finish(collector.into_unbounded())
490}
491
492fn collect_rust_source<'a>(
493    source: &str,
494    mut observations: SourceObservationCollector<'a>,
495) -> SourceObservationCollector<'a> {
496    let tokens = lex_rust(source);
497    let functions = rust_functions(&tokens);
498    let routers = RustRouters::new(&tokens, &functions);
499    parse_rust_attributes(&tokens, &mut observations);
500    if has_ident(&tokens, "axum") {
501        parse_axum_routes(&tokens, &routers, &mut observations);
502        for mount in routers.mounts(false) {
503            observations.push(mount);
504        }
505    }
506    if has_ident(&tokens, "actix_web") {
507        parse_actix_builder_routes(&tokens, &routers, &mut observations);
508        for mount in routers.mounts(true) {
509            observations.push(mount);
510        }
511    }
512    let scopes = RustScopes::new(&tokens, &functions);
513    rust_test_clients::parse_rust_test_requests(&tokens, &functions, &scopes, &mut observations);
514    let clients = if has_ident(&tokens, "reqwest") {
515        let receivers = rust_bindings::reqwest_receiver_tokens(&tokens, &functions);
516        parse_reqwest_calls(&tokens, &functions, &receivers, &scopes, &mut observations);
517        receivers
518    } else {
519        BTreeSet::new()
520    };
521    let declares_tests = observations.has_role(SourceRole::Test) || has_ident(&tokens, "test");
522    scopes.record_calls(&clients, declares_tests, &mut observations);
523    observations.locate_symbols(&tokens, &functions);
524    observations
525}
526
527/// Parses focused Rust facts while charging each attempted observation before retention.
528///
529/// # Errors
530///
531/// Returns [`ExtractionLimitExceeded`] before an observation or one of its values exceeds the
532/// effective per-artifact budget.
533pub fn parse_rust_source_with_tracker(
534    source: &str,
535    tracker: &mut ExtractionTracker,
536) -> Result<Vec<SourceObservation>, ExtractionLimitExceeded> {
537    let observations = collect_rust_source(source, SourceObservationCollector::bounded(tracker));
538    Ok(finish(observations.into_result()?))
539}
540
541/// Parses the mandatory focused Python framework matrix.
542///
543/// Supported syntax comprises `FastAPI` and Flask decorators, requests, HTTPX and aiohttp
544/// convenience/client calls, static HTTP registries, Factory Boy model declarations, pytest
545/// functions, unittest `TestCase` methods, and canonical class-level `test_` methods whose
546/// indirect runner inheritance cannot be proven in one file. Comments and string contents are
547/// lexically excluded from recognition. The returned vector is sorted and deduplicated.
548#[must_use]
549pub fn parse_python_source(source: &str) -> Vec<SourceObservation> {
550    let collector = collect_python_source(source, SourceObservationCollector::unbounded());
551    finish(collector.into_unbounded())
552}
553
554fn collect_python_source<'a>(
555    source: &str,
556    mut observations: SourceObservationCollector<'a>,
557) -> SourceObservationCollector<'a> {
558    let tokens = lex_python(source);
559    let functions = python_functions(source, &tokens);
560    let contexts = PythonContexts::discover(&tokens);
561    let scopes = PythonScopes::new(&tokens, &functions);
562    parse_python_routes(&tokens, &contexts, &mut observations);
563    parse_python_router_mounts(&tokens, &contexts, &mut observations);
564    parse_python_http_registries(&tokens, &mut observations);
565    parse_python_route_calls(&tokens, &contexts, &mut observations);
566    parse_python_http_calls(&tokens, &functions, &contexts, &scopes, &mut observations);
567    parse_python_client_fixtures(&tokens, &functions, &contexts, &mut observations);
568    parse_python_factories(source, &tokens, &mut observations);
569    parse_python_tests(source, &tokens, &mut observations);
570    let clients = contexts
571        .request_modules
572        .iter()
573        .chain(&contexts.request_clients)
574        .chain(&contexts.httpx_modules)
575        .chain(&contexts.httpx_clients)
576        .chain(&contexts.aiohttp_modules)
577        .chain(&contexts.aiohttp_clients)
578        .chain(contexts.direct_calls.keys())
579        .chain(contexts.test_clients.keys())
580        .map(String::as_str)
581        .collect::<BTreeSet<_>>();
582    let declares_tests = has_ident(&tokens, "pytest")
583        || has_ident(&tokens, "unittest")
584        || functions
585            .iter()
586            .any(|function| function.name.starts_with("test_"));
587    scopes.record_calls(
588        &python_router_imports(&tokens),
589        &clients,
590        declares_tests,
591        &mut observations,
592    );
593    record_fixture_requests(&scopes, &mut observations);
594    observations.locate_symbols(&tokens, &functions);
595    observations
596}
597
598/// Parses focused Python facts while charging each attempted observation before retention.
599///
600/// # Errors
601///
602/// Returns [`ExtractionLimitExceeded`] before an observation or one of its values exceeds the
603/// effective per-artifact budget.
604pub fn parse_python_source_with_tracker(
605    source: &str,
606    tracker: &mut ExtractionTracker,
607) -> Result<Vec<SourceObservation>, ExtractionLimitExceeded> {
608    let observations = collect_python_source(source, SourceObservationCollector::bounded(tracker));
609    Ok(finish(observations.into_result()?))
610}
611
612/// Normalizes a literal path using the same slash and trailing-separator rules as HTTP contracts.
613///
614/// Query strings and fragments must be removed by the caller before invoking this function.
615#[must_use]
616pub fn normalize_source_http_path(path: &str) -> String {
617    let trimmed = path.trim();
618    if trimmed.is_empty() || trimmed == "/" {
619        return "/".to_owned();
620    }
621    let mut normalized = String::with_capacity(trimmed.len() + 1);
622    if !trimmed.starts_with('/') {
623        normalized.push('/');
624    }
625    let mut previous_slash = false;
626    for character in trimmed.chars() {
627        if character == '/' {
628            if !previous_slash {
629                normalized.push('/');
630            }
631            previous_slash = true;
632        } else {
633            normalized.push(character);
634            previous_slash = false;
635        }
636    }
637    while normalized.len() > 1 && normalized.ends_with('/') {
638        normalized.pop();
639    }
640    normalized
641}
642
643#[derive(Debug, Clone, PartialEq, Eq)]
644enum TokenKind {
645    Ident(String),
646    Literal(Option<String>),
647    /// Raw body of a JavaScript template literal, including `${...}` substitutions.
648    Template(String),
649    Punct(char),
650}
651
652#[derive(Debug, Clone, PartialEq, Eq)]
653struct Token {
654    kind: TokenKind,
655    line: u32,
656    end_line: u32,
657}
658
659impl Token {
660    fn is_ident(&self, expected: &str) -> bool {
661        matches!(&self.kind, TokenKind::Ident(value) if value == expected)
662    }
663
664    fn is_punct(&self, expected: char) -> bool {
665        self.kind == TokenKind::Punct(expected)
666    }
667
668    fn literal(&self) -> Option<&str> {
669        match &self.kind {
670            TokenKind::Literal(Some(value)) => Some(value),
671            _ => None,
672        }
673    }
674
675    fn ident(&self) -> Option<&str> {
676        match &self.kind {
677            TokenKind::Ident(value) => Some(value),
678            _ => None,
679        }
680    }
681}
682
683#[derive(Debug, Clone)]
684struct FunctionSpan {
685    name: String,
686    start_token: usize,
687    body_start_token: usize,
688    end_token: usize,
689}
690
691fn has_ident(tokens: &[Token], name: &str) -> bool {
692    tokens.iter().any(|token| token.is_ident(name))
693}
694
695fn lex_rust(source: &str) -> Vec<Token> {
696    let characters = source.chars().collect::<Vec<_>>();
697    let mut tokens = Vec::new();
698    let mut index = 0;
699    let mut line = 1_u32;
700    while index < characters.len() {
701        match characters[index] {
702            '\n' => {
703                line += 1;
704                index += 1;
705            }
706            character if character.is_whitespace() => index += 1,
707            '/' if characters.get(index + 1) == Some(&'/') => {
708                index += 2;
709                while index < characters.len() && characters[index] != '\n' {
710                    index += 1;
711                }
712            }
713            '/' if characters.get(index + 1) == Some(&'*') => {
714                index += 2;
715                let mut depth = 1_u32;
716                while index < characters.len() && depth > 0 {
717                    if characters[index] == '\n' {
718                        line += 1;
719                        index += 1;
720                    } else if characters[index] == '/' && characters.get(index + 1) == Some(&'*') {
721                        depth += 1;
722                        index += 2;
723                    } else if characters[index] == '*' && characters.get(index + 1) == Some(&'/') {
724                        depth -= 1;
725                        index += 2;
726                    } else {
727                        index += 1;
728                    }
729                }
730            }
731            'r' if rust_raw_string_start(&characters, index).is_some() => {
732                let start_line = line;
733                let (next, value) = consume_rust_raw_string(&characters, index, &mut line);
734                tokens.push(Token {
735                    kind: TokenKind::Literal(value),
736                    line: start_line,
737                    end_line: line,
738                });
739                index = next;
740            }
741            '"' => {
742                let start_line = line;
743                let (next, value) = consume_quoted(&characters, index, '"', false, &mut line);
744                tokens.push(Token {
745                    kind: TokenKind::Literal(value),
746                    line: start_line,
747                    end_line: line,
748                });
749                index = next;
750            }
751            '\'' if rust_char_literal_end(&characters, index).is_some() => {
752                let (next, _) = consume_quoted(&characters, index, '\'', false, &mut line);
753                index = next;
754            }
755            character if is_ident_start(character) => {
756                let start = index;
757                index += 1;
758                while index < characters.len() && is_ident_continue(characters[index]) {
759                    index += 1;
760                }
761                tokens.push(Token {
762                    kind: TokenKind::Ident(characters[start..index].iter().collect()),
763                    line,
764                    end_line: line,
765                });
766            }
767            character => {
768                tokens.push(Token {
769                    kind: TokenKind::Punct(character),
770                    line,
771                    end_line: line,
772                });
773                index += 1;
774            }
775        }
776    }
777    tokens
778}
779
780fn rust_char_literal_end(characters: &[char], index: usize) -> Option<usize> {
781    let value = index.checked_add(1)?;
782    let closing = if characters.get(value) == Some(&'\\') {
783        match characters.get(value + 1)? {
784            'u' if characters.get(value + 2) == Some(&'{') => {
785                (value + 3..characters.len()).find(|cursor| characters[*cursor] == '}')? + 1
786            }
787            'x' => value.checked_add(4)?,
788            _ => value.checked_add(2)?,
789        }
790    } else {
791        value.checked_add(1)?
792    };
793    (characters.get(closing) == Some(&'\'')).then_some(closing + 1)
794}
795
796fn rust_raw_string_start(characters: &[char], index: usize) -> Option<usize> {
797    let mut cursor = index + 1;
798    while characters.get(cursor) == Some(&'#') {
799        cursor += 1;
800    }
801    (characters.get(cursor) == Some(&'"')).then_some(cursor - index - 1)
802}
803
804fn consume_rust_raw_string(
805    characters: &[char],
806    index: usize,
807    line: &mut u32,
808) -> (usize, Option<String>) {
809    let hashes = rust_raw_string_start(characters, index).unwrap_or_default();
810    let content_start = index + hashes + 2;
811    let mut cursor = content_start;
812    while cursor < characters.len() {
813        if characters[cursor] == '\n' {
814            *line += 1;
815        }
816        if characters[cursor] == '"'
817            && (0..hashes).all(|offset| characters.get(cursor + 1 + offset) == Some(&'#'))
818        {
819            return (
820                cursor + hashes + 1,
821                Some(characters[content_start..cursor].iter().collect()),
822            );
823        }
824        cursor += 1;
825    }
826    (cursor, None)
827}
828
829fn lex_python(source: &str) -> Vec<Token> {
830    let characters = source.chars().collect::<Vec<_>>();
831    let mut tokens = Vec::new();
832    let mut index = 0;
833    let mut line = 1_u32;
834    while index < characters.len() {
835        match characters[index] {
836            '\n' => {
837                line += 1;
838                index += 1;
839            }
840            character if character.is_whitespace() => index += 1,
841            '#' => {
842                while index < characters.len() && characters[index] != '\n' {
843                    index += 1;
844                }
845            }
846            prefix @ ('r' | 'R' | 'u' | 'U')
847                if matches!(characters.get(index + 1), Some('"' | '\'')) =>
848            {
849                let start_line = line;
850                let quote = characters[index + 1];
851                let triple = characters.get(index + 2) == Some(&quote)
852                    && characters.get(index + 3) == Some(&quote);
853                let (next, value) =
854                    consume_quoted(&characters, index + 1, quote, triple, &mut line);
855                let _ = prefix;
856                tokens.push(Token {
857                    kind: TokenKind::Literal(value),
858                    line: start_line,
859                    end_line: line,
860                });
861                index = next;
862            }
863            quote @ ('"' | '\'') => {
864                let start_line = line;
865                let triple = characters.get(index + 1) == Some(&quote)
866                    && characters.get(index + 2) == Some(&quote);
867                let (next, value) = consume_quoted(&characters, index, quote, triple, &mut line);
868                tokens.push(Token {
869                    kind: TokenKind::Literal(value),
870                    line: start_line,
871                    end_line: line,
872                });
873                index = next;
874            }
875            character if is_ident_start(character) => {
876                let start = index;
877                index += 1;
878                while index < characters.len() && is_ident_continue(characters[index]) {
879                    index += 1;
880                }
881                tokens.push(Token {
882                    kind: TokenKind::Ident(characters[start..index].iter().collect()),
883                    line,
884                    end_line: line,
885                });
886            }
887            character => {
888                tokens.push(Token {
889                    kind: TokenKind::Punct(character),
890                    line,
891                    end_line: line,
892                });
893                index += 1;
894            }
895        }
896    }
897    tokens
898}
899
900fn consume_quoted(
901    characters: &[char],
902    index: usize,
903    quote: char,
904    triple: bool,
905    line: &mut u32,
906) -> (usize, Option<String>) {
907    let delimiter_width = if triple { 3 } else { 1 };
908    let mut cursor = index + delimiter_width;
909    let mut value = String::new();
910    let mut valid = true;
911    while cursor < characters.len() {
912        if characters[cursor] == '\n' {
913            *line += 1;
914            if !triple {
915                valid = false;
916            }
917        }
918        let closes = if triple {
919            characters.get(cursor) == Some(&quote)
920                && characters.get(cursor + 1) == Some(&quote)
921                && characters.get(cursor + 2) == Some(&quote)
922        } else {
923            characters.get(cursor) == Some(&quote)
924        };
925        if closes {
926            return (
927                cursor + delimiter_width,
928                if valid { Some(value) } else { None },
929            );
930        }
931        if characters[cursor] == '\\' && !triple {
932            let Some(escaped) = characters.get(cursor + 1).copied() else {
933                return (characters.len(), None);
934            };
935            match escaped {
936                '\\' => value.push('\\'),
937                '"' => value.push('"'),
938                '\'' => value.push('\''),
939                'n' => value.push('\n'),
940                'r' => value.push('\r'),
941                't' => value.push('\t'),
942                _ => valid = false,
943            }
944            cursor += 2;
945        } else {
946            value.push(characters[cursor]);
947            cursor += 1;
948        }
949    }
950    (cursor, None)
951}
952
953fn is_ident_start(character: char) -> bool {
954    character == '_' || character.is_alphabetic()
955}
956
957fn is_ident_continue(character: char) -> bool {
958    character == '_' || character.is_alphanumeric()
959}
960
961fn matching(tokens: &[Token], open: usize, left: char, right: char) -> Option<usize> {
962    if !tokens.get(open).is_some_and(|token| token.is_punct(left)) {
963        return None;
964    }
965    let mut depth = 0_u32;
966    for (index, token) in tokens.iter().enumerate().skip(open) {
967        if token.is_punct(left) {
968            depth += 1;
969        } else if token.is_punct(right) {
970            depth -= 1;
971            if depth == 0 {
972                return Some(index);
973            }
974        }
975    }
976    None
977}
978
979fn rust_functions(tokens: &[Token]) -> Vec<FunctionSpan> {
980    let mut functions = Vec::new();
981    for (index, token) in tokens.iter().enumerate() {
982        if !token.is_ident("fn") {
983            continue;
984        }
985        let Some(name) = tokens.get(index + 1).and_then(Token::ident) else {
986            continue;
987        };
988        let Some(open) = (index + 2..tokens.len())
989            .find(|candidate| tokens[*candidate].is_punct('{') || tokens[*candidate].is_punct(';'))
990        else {
991            continue;
992        };
993        if tokens[open].is_punct(';') {
994            continue;
995        }
996        let end = matching(tokens, open, '{', '}').unwrap_or(tokens.len().saturating_sub(1));
997        functions.push(FunctionSpan {
998            name: name.to_owned(),
999            start_token: index,
1000            body_start_token: open,
1001            end_token: end,
1002        });
1003    }
1004    functions
1005}
1006
1007/// Position of the smallest function span containing token `index`.
1008fn innermost_function(functions: &[FunctionSpan], index: usize) -> Option<usize> {
1009    functions
1010        .iter()
1011        .enumerate()
1012        .filter(|(_, function)| function.start_token <= index && index <= function.end_token)
1013        .min_by_key(|(_, function)| function.end_token - function.start_token)
1014        .map(|(position, _)| position)
1015}
1016
1017/// Splits `start..end` at top-level `separator` punctuation.
1018fn split_operands(
1019    tokens: &[Token],
1020    start: usize,
1021    end: usize,
1022    separator: char,
1023) -> Vec<(usize, usize)> {
1024    let mut operands = Vec::new();
1025    let mut depth = 0_i32;
1026    let mut operand_start = start;
1027    for (index, token) in tokens.iter().enumerate().take(end).skip(start) {
1028        match token.kind {
1029            TokenKind::Punct('(' | '[' | '{') => depth += 1,
1030            TokenKind::Punct(')' | ']' | '}') => depth -= 1,
1031            TokenKind::Punct(character) if character == separator && depth == 0 => {
1032                operands.push((operand_start, index));
1033                operand_start = index + 1;
1034            }
1035            _ => {}
1036        }
1037    }
1038    operands.push((operand_start, end));
1039    operands
1040}
1041
1042fn enclosing_symbol(functions: &[FunctionSpan], token_index: usize) -> Option<String> {
1043    functions
1044        .iter()
1045        .filter(|function| function.start_token <= token_index && token_index <= function.end_token)
1046        .min_by_key(|function| function.end_token - function.start_token)
1047        .map(|function| function.name.clone())
1048}
1049
1050fn parse_rust_attributes(tokens: &[Token], observations: &mut SourceObservationCollector<'_>) {
1051    let mut index = 0;
1052    while index + 2 < tokens.len() {
1053        if !tokens[index].is_punct('#') || !tokens[index + 1].is_punct('[') {
1054            index += 1;
1055            continue;
1056        }
1057        let Some(close) = matching(tokens, index + 1, '[', ']') else {
1058            break;
1059        };
1060        let Some((function_index, name, signature_end)) = rust_function_after(tokens, close) else {
1061            index = close + 1;
1062            continue;
1063        };
1064        let path = attribute_path(tokens, index + 2, close);
1065        let framework = match path.as_slice() {
1066            [name] if name == "test" => Some(SourceFramework::RustTest),
1067            [first, second] if first == "tokio" && second == "test" => {
1068                Some(SourceFramework::TokioTest)
1069            }
1070            [first, second]
1071                if (first == "actix_web" || first == "actix_rt") && second == "test" =>
1072            {
1073                Some(SourceFramework::RustTest)
1074            }
1075            [name] if name == "rstest" => Some(SourceFramework::Rstest),
1076            _ => None,
1077        };
1078        if let Some(framework) = framework {
1079            observations.push(confirmed_test(
1080                SourceLanguage::Rust,
1081                framework,
1082                name.clone(),
1083                tokens[index].line,
1084                tokens[signature_end].end_line,
1085            ));
1086        }
1087        parse_utoipa_attribute(
1088            tokens,
1089            index,
1090            close,
1091            function_index,
1092            signature_end,
1093            &name,
1094            observations,
1095        );
1096        if has_ident(tokens, "actix_web") {
1097            parse_actix_attribute(
1098                tokens,
1099                index,
1100                close,
1101                function_index,
1102                signature_end,
1103                name,
1104                &path,
1105                observations,
1106            );
1107        }
1108        index = close + 1;
1109    }
1110}
1111
1112fn parse_utoipa_attribute(
1113    tokens: &[Token],
1114    start: usize,
1115    close: usize,
1116    function_index: usize,
1117    signature_end: usize,
1118    symbol: &str,
1119    observations: &mut SourceObservationCollector<'_>,
1120) {
1121    let Some(utoipa_index) = (start..close).find(|index| tokens[*index].is_ident("utoipa")) else {
1122        return;
1123    };
1124    if !tokens[utoipa_index + 1..close]
1125        .iter()
1126        .any(|token| token.is_ident("path"))
1127    {
1128        return;
1129    }
1130    let method = tokens[utoipa_index..close]
1131        .iter()
1132        .filter_map(Token::ident)
1133        .find_map(canonical_method)
1134        .map(str::to_owned);
1135    let explicit_path = parse_keyword_string_values(tokens, utoipa_index, close, "path")
1136        .into_iter()
1137        .next();
1138    let context_path = parse_keyword_string_values(tokens, utoipa_index, close, "context_path")
1139        .into_iter()
1140        .next();
1141    let actix = rust_actix_route_between(tokens, close.saturating_add(1), function_index);
1142    let method = method.or_else(|| actix.as_ref().and_then(|(method, _)| method.clone()));
1143    let path = explicit_path.or_else(|| {
1144        let (context, (_, route)) = (context_path?, actix?);
1145        Some(normalize_source_http_path(&format!("{context}{route}")))
1146    });
1147    let lines = SourceLineRange {
1148        start: tokens[start].line,
1149        end: tokens[signature_end].end_line,
1150    };
1151    let mut observation = http_from_literal(
1152        SourceLanguage::Rust,
1153        SourceFramework::Utoipa,
1154        SourceRole::Provider,
1155        method,
1156        path.as_deref(),
1157        Some(symbol.to_owned()),
1158        lines,
1159        true,
1160    );
1161    if observation.status == SourceEpistemicStatus::Confirmed {
1162        observation.confidence = 0.75;
1163        observation
1164            .warnings
1165            .push(SourceWarning::AdvisoryDeclaration);
1166    }
1167    observations.push(observation);
1168}
1169
1170fn rust_actix_route_between(
1171    tokens: &[Token],
1172    start: usize,
1173    end: usize,
1174) -> Option<(Option<String>, String)> {
1175    let mut index = start;
1176    while index + 3 < end {
1177        if !tokens[index].is_punct('#') || !tokens[index + 1].is_punct('[') {
1178            index += 1;
1179            continue;
1180        }
1181        let close = matching(tokens, index + 1, '[', ']')?;
1182        if close > end {
1183            return None;
1184        }
1185        let method = tokens
1186            .get(index + 2)
1187            .and_then(Token::ident)
1188            .and_then(canonical_method)
1189            .map(str::to_owned);
1190        let open = (index + 2..close).find(|candidate| tokens[*candidate].is_punct('('));
1191        let path = open
1192            .and_then(|open| first_argument(open, close))
1193            .and_then(|argument| tokens.get(argument))
1194            .and_then(Token::literal)
1195            .and_then(route_literal_path)?;
1196        return Some((method, path));
1197    }
1198    None
1199}
1200
1201fn rust_function_after(tokens: &[Token], close: usize) -> Option<(usize, String, usize)> {
1202    let mut index = close + 1;
1203    while index < tokens.len() && index <= close + 24 {
1204        if tokens[index].is_punct('#') {
1205            if tokens
1206                .get(index + 1)
1207                .is_some_and(|token| token.is_punct('['))
1208            {
1209                index = matching(tokens, index + 1, '[', ']')? + 1;
1210                continue;
1211            }
1212            return None;
1213        }
1214        if tokens[index].is_ident("fn") {
1215            let name = tokens.get(index + 1)?.ident()?.to_owned();
1216            let end = (index + 2..tokens.len())
1217                .find(|candidate| {
1218                    tokens[*candidate].is_punct('{') || tokens[*candidate].is_punct(';')
1219                })
1220                .unwrap_or(index + 1);
1221            return Some((index, name, end));
1222        }
1223        index += 1;
1224    }
1225    None
1226}
1227
1228fn attribute_path(tokens: &[Token], start: usize, end: usize) -> Vec<String> {
1229    let mut path = Vec::new();
1230    let mut index = start;
1231    while index < end && !tokens[index].is_punct('(') {
1232        if let Some(name) = tokens[index].ident() {
1233            path.push(name.to_owned());
1234        }
1235        index += 1;
1236    }
1237    path
1238}
1239
1240#[expect(
1241    clippy::too_many_arguments,
1242    reason = "Attribute evidence is passed without allocation"
1243)]
1244fn parse_actix_attribute(
1245    tokens: &[Token],
1246    start: usize,
1247    close: usize,
1248    _function_index: usize,
1249    signature_end: usize,
1250    symbol: String,
1251    path: &[String],
1252    observations: &mut SourceObservationCollector<'_>,
1253) {
1254    let direct_method = match path {
1255        [name] => canonical_method(name),
1256        _ => None,
1257    };
1258    if direct_method.is_none() && path != ["route"] {
1259        return;
1260    }
1261    let open = (start + 2..close).find(|index| tokens[*index].is_punct('('));
1262    let literal = open
1263        .and_then(|open| first_argument(open, close))
1264        .and_then(|argument| tokens.get(argument))
1265        .and_then(Token::literal);
1266    let methods = direct_method
1267        .into_iter()
1268        .map(str::to_owned)
1269        .chain(
1270            parse_keyword_string_values(tokens, start, close, "method")
1271                .into_iter()
1272                .filter_map(|method| canonical_method(&method).map(str::to_owned)),
1273        )
1274        .collect::<BTreeSet<_>>();
1275    if methods.is_empty() {
1276        observations.push(inexact_http(
1277            SourceLanguage::Rust,
1278            SourceFramework::ActixWeb,
1279            SourceRole::Provider,
1280            None,
1281            literal.and_then(route_literal_path),
1282            Some(symbol),
1283            SourceLineRange {
1284                start: tokens[start].line,
1285                end: tokens[signature_end].end_line,
1286            },
1287            SourceWarning::DynamicMethod,
1288        ));
1289        return;
1290    }
1291    for method in methods {
1292        let mut observation = http_from_literal(
1293            SourceLanguage::Rust,
1294            SourceFramework::ActixWeb,
1295            SourceRole::Provider,
1296            Some(method),
1297            literal,
1298            Some(symbol.clone()),
1299            SourceLineRange {
1300                start: tokens[start].line,
1301                end: tokens[signature_end].end_line,
1302            },
1303            true,
1304        );
1305        observation.router = Some(SymbolRef::Function(symbol.clone()));
1306        observations.push(observation);
1307    }
1308}
1309
1310fn parse_axum_routes(
1311    tokens: &[Token],
1312    routers: &RustRouters<'_>,
1313    observations: &mut SourceObservationCollector<'_>,
1314) {
1315    for (index, token) in tokens.iter().enumerate() {
1316        if !token.is_ident("route")
1317            || !tokens
1318                .get(index.wrapping_sub(1))
1319                .is_some_and(|token| token.is_punct('.'))
1320            || !tokens
1321                .get(index + 1)
1322                .is_some_and(|token| token.is_punct('('))
1323        {
1324            continue;
1325        }
1326        let Some(close) = matching(tokens, index + 1, '(', ')') else {
1327            continue;
1328        };
1329        let arguments = top_level_arguments(tokens, index + 1, close);
1330        if arguments.len() < 2 {
1331            continue;
1332        }
1333        let literal = tokens.get(arguments[0]).and_then(Token::literal);
1334        let router = routers.chain_owner(index - 1).router;
1335        let methods = method_calls(tokens, arguments[1], close);
1336        for (method, handler) in methods {
1337            let mut observation = http_from_literal(
1338                SourceLanguage::Rust,
1339                SourceFramework::Axum,
1340                SourceRole::Provider,
1341                Some(method),
1342                literal,
1343                handler,
1344                SourceLineRange {
1345                    start: token.line,
1346                    end: tokens[close].end_line,
1347                },
1348                true,
1349            );
1350            observation.router = Some(router.clone());
1351            observations.push(observation);
1352        }
1353    }
1354}
1355
1356fn parse_actix_builder_routes(
1357    tokens: &[Token],
1358    routers: &RustRouters<'_>,
1359    observations: &mut SourceObservationCollector<'_>,
1360) {
1361    for (index, token) in tokens.iter().enumerate() {
1362        if !token.is_ident("route")
1363            || !tokens
1364                .get(index + 1)
1365                .is_some_and(|token| token.is_punct('('))
1366        {
1367            continue;
1368        }
1369        let Some(close) = matching(tokens, index + 1, '(', ')') else {
1370            continue;
1371        };
1372        let arguments = top_level_arguments(tokens, index + 1, close);
1373        if arguments.len() < 2 || !contains_ident(tokens, arguments[1], close, "web") {
1374            continue;
1375        }
1376        let owner =
1377            (index > 0 && tokens[index - 1].is_punct('.')).then(|| routers.chain_owner(index - 1));
1378        let literal = tokens.get(arguments[0]).and_then(Token::literal);
1379        let literal = match owner.as_ref().and_then(|owner| owner.prefix.as_deref()) {
1380            Some(prefix) => join_prefixes(Some(prefix), literal),
1381            None => literal.map(str::to_owned),
1382        };
1383        for (method, handler) in method_calls(tokens, arguments[1], close) {
1384            let mut observation = http_from_literal(
1385                SourceLanguage::Rust,
1386                SourceFramework::ActixWeb,
1387                SourceRole::Provider,
1388                Some(method),
1389                literal.as_deref(),
1390                handler,
1391                SourceLineRange {
1392                    start: token.line,
1393                    end: tokens[close].end_line,
1394                },
1395                true,
1396            );
1397            observation.router = owner.as_ref().map(|owner| owner.router.clone());
1398            observations.push(observation);
1399        }
1400    }
1401    for (index, token) in tokens.iter().enumerate() {
1402        if !token.is_ident("resource")
1403            || !tokens
1404                .get(index.wrapping_sub(1))
1405                .is_some_and(|token| token.is_punct(':'))
1406            || !tokens
1407                .get(index + 1)
1408                .is_some_and(|token| token.is_punct('('))
1409        {
1410            continue;
1411        }
1412        let Some(resource_close) = matching(tokens, index + 1, '(', ')') else {
1413            continue;
1414        };
1415        let end = (resource_close + 1..tokens.len())
1416            .find(|candidate| tokens[*candidate].is_punct(';'))
1417            .unwrap_or(resource_close);
1418        if !contains_ident(tokens, resource_close + 1, end, "route") {
1419            continue;
1420        }
1421        let literal = tokens.get(index + 2).and_then(Token::literal);
1422        let router = tokens
1423            .get(resource_close + 1)
1424            .is_some_and(|token| token.is_punct('.'))
1425            .then(|| routers.chain_owner(resource_close + 1).router);
1426        for (method, handler) in method_calls(tokens, resource_close + 1, end) {
1427            let mut observation = http_from_literal(
1428                SourceLanguage::Rust,
1429                SourceFramework::ActixWeb,
1430                SourceRole::Provider,
1431                Some(method),
1432                literal,
1433                handler,
1434                SourceLineRange {
1435                    start: token.line,
1436                    end: tokens[end].end_line,
1437                },
1438                true,
1439            );
1440            observation.router.clone_from(&router);
1441            observations.push(observation);
1442        }
1443    }
1444}
1445
1446fn parse_reqwest_calls(
1447    tokens: &[Token],
1448    functions: &[FunctionSpan],
1449    reqwest_receivers: &BTreeSet<usize>,
1450    scopes: &RustScopes<'_>,
1451    observations: &mut SourceObservationCollector<'_>,
1452) {
1453    for index in 0..tokens.len() {
1454        let Some(method_index) = reqwest_method_index(tokens, index, reqwest_receivers) else {
1455            continue;
1456        };
1457        let Some(method_name) = tokens.get(method_index).and_then(Token::ident) else {
1458            continue;
1459        };
1460        if !tokens
1461            .get(method_index + 1)
1462            .is_some_and(|token| token.is_punct('('))
1463        {
1464            continue;
1465        }
1466        let Some(close) = matching(tokens, method_index + 1, '(', ')') else {
1467            continue;
1468        };
1469        let arguments = top_level_arguments(tokens, method_index + 1, close);
1470        let (method, path_argument) = if method_name == "request" {
1471            (
1472                arguments.first().and_then(|argument| {
1473                    let method_end = arguments
1474                        .get(1)
1475                        .map_or(close, |second| second.saturating_sub(1));
1476                    rust_method_expression(tokens, *argument, method_end)
1477                }),
1478                arguments.get(1).copied(),
1479            )
1480        } else {
1481            (
1482                canonical_method(method_name).map(str::to_owned),
1483                arguments.first().copied(),
1484            )
1485        };
1486        if method.is_none() && method_name != "request" {
1487            continue;
1488        }
1489        let template = path_argument.map(|argument| {
1490            let end = arguments
1491                .iter()
1492                .find(|start| **start > argument)
1493                .map_or(close, |next| next - 1);
1494            scopes.template(argument, end, index)
1495        });
1496        let literal = template.as_ref().and_then(UrlTemplate::client_literal);
1497        let mut observation = http_from_literal(
1498            SourceLanguage::Rust,
1499            SourceFramework::Reqwest,
1500            SourceRole::Consumer,
1501            method,
1502            literal.as_deref(),
1503            enclosing_symbol(functions, index),
1504            SourceLineRange {
1505                start: tokens[index].line,
1506                end: tokens[close].end_line,
1507            },
1508            false,
1509        );
1510        if method_name == "request" && observation.method.is_none() {
1511            observation.status = SourceEpistemicStatus::Incomplete;
1512            observation.confidence = 0.0;
1513            observation.warnings.push(SourceWarning::DynamicMethod);
1514            observation.warnings.sort();
1515            observation.warnings.dedup();
1516        }
1517        observation.url = template.filter(UrlTemplate::has_parameters);
1518        observations.push(observation);
1519    }
1520}
1521
1522/// Index of the method name called at token `index` on the `reqwest` or `reqwest::blocking`
1523/// module, or on a Reqwest client receiver.
1524fn reqwest_method_index(
1525    tokens: &[Token],
1526    index: usize,
1527    reqwest_receivers: &BTreeSet<usize>,
1528) -> Option<usize> {
1529    let path_separator = |at: usize| {
1530        tokens.get(at).is_some_and(|token| token.is_punct(':'))
1531            && tokens.get(at + 1).is_some_and(|token| token.is_punct(':'))
1532    };
1533    if tokens[index].is_ident("reqwest") && path_separator(index + 1) {
1534        let direct = index + 3;
1535        let blocking = tokens
1536            .get(direct)
1537            .is_some_and(|token| token.is_ident("blocking"))
1538            && path_separator(direct + 1);
1539        return Some(if blocking { direct + 3 } else { direct });
1540    }
1541    (reqwest_receivers.contains(&index)
1542        && tokens
1543            .get(index + 1)
1544            .is_some_and(|token| token.is_punct('.')))
1545    .then_some(index + 2)
1546}
1547
1548fn rust_method_expression(tokens: &[Token], start: usize, end: usize) -> Option<String> {
1549    if let Some(literal) = tokens.get(start).and_then(Token::literal) {
1550        return canonical_method(literal).map(str::to_owned);
1551    }
1552    (start..end)
1553        .filter_map(|index| tokens[index].ident())
1554        .find_map(|name| canonical_method(name).map(str::to_owned))
1555}
1556
1557fn method_calls(tokens: &[Token], start: usize, end: usize) -> Vec<(String, Option<String>)> {
1558    let mut methods = Vec::new();
1559    for index in start..end {
1560        let Some(name) = tokens[index].ident() else {
1561            continue;
1562        };
1563        let Some(method) = canonical_method(name) else {
1564            continue;
1565        };
1566        if !tokens
1567            .get(index + 1)
1568            .is_some_and(|token| token.is_punct('('))
1569        {
1570            continue;
1571        }
1572        let direct_handler = tokens
1573            .get(index + 2)
1574            .and_then(Token::ident)
1575            .map(str::to_owned);
1576        let actix_handler = (index + 2..end)
1577            .find(|candidate| {
1578                tokens[*candidate].is_ident("to")
1579                    && tokens
1580                        .get(*candidate + 1)
1581                        .is_some_and(|token| token.is_punct('('))
1582            })
1583            .and_then(|to| tokens.get(to + 2))
1584            .and_then(Token::ident)
1585            .map(str::to_owned);
1586        let handler = direct_handler.or(actix_handler);
1587        methods.push((method.to_owned(), handler));
1588    }
1589    methods
1590}
1591
1592fn contains_ident(tokens: &[Token], start: usize, end: usize, name: &str) -> bool {
1593    tokens
1594        .get(start..end)
1595        .is_some_and(|slice| slice.iter().any(|token| token.is_ident(name)))
1596}
1597
1598fn first_argument(open: usize, close: usize) -> Option<usize> {
1599    (open + 1 < close).then_some(open + 1)
1600}
1601
1602fn top_level_arguments(tokens: &[Token], open: usize, close: usize) -> Vec<usize> {
1603    if open + 1 >= close {
1604        return Vec::new();
1605    }
1606    let mut arguments = vec![open + 1];
1607    let mut round = 0_i32;
1608    let mut square = 0_i32;
1609    let mut curly = 0_i32;
1610    for (index, token) in tokens.iter().enumerate().take(close).skip(open + 1) {
1611        match token.kind {
1612            TokenKind::Punct('(') => round += 1,
1613            TokenKind::Punct(')') => round -= 1,
1614            TokenKind::Punct('[') => square += 1,
1615            TokenKind::Punct(']') => square -= 1,
1616            TokenKind::Punct('{') => curly += 1,
1617            TokenKind::Punct('}') => curly -= 1,
1618            TokenKind::Punct(',')
1619                if round == 0 && square == 0 && curly == 0 && index + 1 < close =>
1620            {
1621                arguments.push(index + 1);
1622            }
1623            _ => {}
1624        }
1625    }
1626    arguments
1627}
1628
1629fn parse_keyword_string_values(
1630    tokens: &[Token],
1631    start: usize,
1632    end: usize,
1633    keyword: &str,
1634) -> Vec<String> {
1635    let mut values = Vec::new();
1636    for index in start..end {
1637        if !tokens[index].is_ident(keyword)
1638            || !tokens
1639                .get(index + 1)
1640                .is_some_and(|token| token.is_punct('='))
1641        {
1642            continue;
1643        }
1644        let value_start = index + 2;
1645        if let Some(value) = tokens.get(value_start).and_then(Token::literal) {
1646            values.push(value.to_owned());
1647        } else if tokens
1648            .get(value_start)
1649            .is_some_and(|token| token.is_punct('['))
1650        {
1651            let close = matching(tokens, value_start, '[', ']').unwrap_or(end);
1652            values.extend(
1653                tokens[value_start + 1..close]
1654                    .iter()
1655                    .filter_map(Token::literal)
1656                    .map(str::to_owned),
1657            );
1658        }
1659    }
1660    values
1661}
1662
1663fn canonical_method(name: &str) -> Option<&'static str> {
1664    HTTP_METHODS
1665        .iter()
1666        .copied()
1667        .find(|method| method.eq_ignore_ascii_case(name))
1668}
1669
1670/// Call from function `function` recorded for repository-level flow composition.
1671pub(crate) fn call_observation(
1672    language: SourceLanguage,
1673    callee: SymbolRef,
1674    arguments: Vec<CallArgument>,
1675    function: String,
1676    lines: SourceLineRange,
1677) -> SourceObservation {
1678    let framework = match language {
1679        SourceLanguage::Python => SourceFramework::PythonTest,
1680        SourceLanguage::Rust => SourceFramework::RustTest,
1681        SourceLanguage::TypeScript | SourceLanguage::JavaScript => SourceFramework::Fetch,
1682        SourceLanguage::Go => SourceFramework::GoNetHttp,
1683        SourceLanguage::Java => SourceFramework::SpringMvc,
1684    };
1685    SourceObservation {
1686        language,
1687        framework,
1688        role: SourceRole::Call,
1689        method: None,
1690        path: None,
1691        symbol_name: Some(function),
1692        symbol_start_line: None,
1693        related_symbol: None,
1694        related_path: None,
1695        authority: None,
1696        router: None,
1697        mount_parent: None,
1698        url: None,
1699        call: Some(CallSite { callee, arguments }),
1700        lines,
1701        status: SourceEpistemicStatus::Confirmed,
1702        confidence: 1.0,
1703        warnings: Vec::new(),
1704    }
1705}
1706
1707/// Confirmed consumer of `template` issued from `caller`, with the client coordinates of
1708/// `origin`; `None` when the template does not yield an exact method and path.
1709pub(crate) fn instantiated_consumer(
1710    origin: &SourceObservation,
1711    template: &UrlTemplate,
1712    caller: &str,
1713    lines: SourceLineRange,
1714) -> Option<SourceObservation> {
1715    let literal = template.client_literal()?;
1716    let observation = http_from_literal(
1717        origin.language,
1718        origin.framework,
1719        SourceRole::Consumer,
1720        origin.method.clone(),
1721        Some(&literal),
1722        Some(caller.to_owned()),
1723        lines,
1724        false,
1725    );
1726    (observation.status == SourceEpistemicStatus::Confirmed).then_some(observation)
1727}
1728
1729fn confirmed_test(
1730    language: SourceLanguage,
1731    framework: SourceFramework,
1732    name: String,
1733    start: u32,
1734    end: u32,
1735) -> SourceObservation {
1736    SourceObservation {
1737        language,
1738        framework,
1739        role: SourceRole::Test,
1740        method: None,
1741        path: None,
1742        symbol_name: Some(name),
1743        symbol_start_line: None,
1744        related_symbol: None,
1745        related_path: None,
1746        authority: None,
1747        router: None,
1748        mount_parent: None,
1749        url: None,
1750        call: None,
1751        lines: SourceLineRange { start, end },
1752        status: SourceEpistemicStatus::Confirmed,
1753        confidence: 1.0,
1754        warnings: Vec::new(),
1755    }
1756}
1757
1758#[expect(
1759    clippy::too_many_arguments,
1760    reason = "Observation fields remain explicit at evidence sites"
1761)]
1762fn http_from_literal(
1763    language: SourceLanguage,
1764    framework: SourceFramework,
1765    role: SourceRole,
1766    method: Option<String>,
1767    literal: Option<&str>,
1768    symbol_name: Option<String>,
1769    lines: SourceLineRange,
1770    route: bool,
1771) -> SourceObservation {
1772    let (path, authority) = literal.map_or((None, None), |value| {
1773        if route {
1774            (route_literal_path(value), None)
1775        } else {
1776            client_literal_identity(value)
1777        }
1778    });
1779    let warning = if literal.is_none() {
1780        Some(SourceWarning::DynamicPath)
1781    } else if path.is_none() {
1782        Some(SourceWarning::UnsupportedLiteralPath)
1783    } else {
1784        None
1785    };
1786    let status = if path.is_some() && method.is_some() {
1787        SourceEpistemicStatus::Confirmed
1788    } else {
1789        SourceEpistemicStatus::Ambiguous
1790    };
1791    let mut observation = SourceObservation {
1792        language,
1793        framework,
1794        role,
1795        method,
1796        path,
1797        symbol_name,
1798        symbol_start_line: None,
1799        related_symbol: None,
1800        related_path: None,
1801        authority,
1802        router: None,
1803        mount_parent: None,
1804        url: None,
1805        call: None,
1806        lines,
1807        status,
1808        confidence: if status == SourceEpistemicStatus::Confirmed {
1809            1.0
1810        } else {
1811            0.0
1812        },
1813        warnings: warning.into_iter().collect(),
1814    };
1815    if role == SourceRole::Provider && observation.symbol_name.is_none() {
1816        observation.status = SourceEpistemicStatus::Incomplete;
1817        observation.confidence = 0.0;
1818        observation.warnings.push(SourceWarning::MissingSymbol);
1819    }
1820    observation
1821}
1822
1823#[expect(
1824    clippy::too_many_arguments,
1825    reason = "Observation fields remain explicit at evidence sites"
1826)]
1827fn inexact_http(
1828    language: SourceLanguage,
1829    framework: SourceFramework,
1830    role: SourceRole,
1831    method: Option<String>,
1832    path: Option<String>,
1833    symbol_name: Option<String>,
1834    lines: SourceLineRange,
1835    warning: SourceWarning,
1836) -> SourceObservation {
1837    SourceObservation {
1838        language,
1839        framework,
1840        role,
1841        method,
1842        path,
1843        symbol_name,
1844        symbol_start_line: None,
1845        related_symbol: None,
1846        related_path: None,
1847        authority: None,
1848        router: None,
1849        mount_parent: None,
1850        url: None,
1851        call: None,
1852        lines,
1853        status: SourceEpistemicStatus::Incomplete,
1854        confidence: 0.0,
1855        warnings: vec![warning],
1856    }
1857}
1858
1859fn route_literal_path(value: &str) -> Option<String> {
1860    (value.starts_with('/') && !value.contains(['?', '#']))
1861        .then(|| normalize_source_http_path(value))
1862}
1863
1864fn client_literal_identity(value: &str) -> (Option<String>, Option<String>) {
1865    if value.starts_with('/') {
1866        return (
1867            Some(normalize_source_http_path(
1868                value.split(['?', '#']).next().unwrap_or(value),
1869            )),
1870            None,
1871        );
1872    }
1873    let after_authority = value
1874        .strip_prefix("http://")
1875        .or_else(|| value.strip_prefix("https://"));
1876    let Some(after_authority) = after_authority else {
1877        return (None, None);
1878    };
1879    if after_authority.is_empty() || after_authority.starts_with('/') {
1880        return (None, None);
1881    }
1882    let separator = after_authority.find('/');
1883    let path = separator.map_or("/", |index| &after_authority[index..]);
1884    (
1885        Some(normalize_source_http_path(
1886            path.split(['?', '#']).next().unwrap_or(path),
1887        )),
1888        crate::routes::url_authority(value),
1889    )
1890}
1891
1892#[derive(Debug, Default)]
1893struct PythonContexts {
1894    fastapi_apps: BTreeSet<String>,
1895    route_prefixes: BTreeMap<String, String>,
1896    flask_apps: BTreeSet<String>,
1897    request_modules: BTreeSet<String>,
1898    httpx_modules: BTreeSet<String>,
1899    aiohttp_modules: BTreeSet<String>,
1900    request_clients: BTreeSet<String>,
1901    httpx_clients: BTreeSet<String>,
1902    aiohttp_clients: BTreeSet<String>,
1903    direct_calls: BTreeMap<String, (SourceFramework, String)>,
1904    string_constants: BTreeMap<String, String>,
1905    test_clients: BTreeMap<String, SourceFramework>,
1906}
1907
1908impl PythonContexts {
1909    fn discover(tokens: &[Token]) -> Self {
1910        let mut contexts = Self::default();
1911        contexts.request_modules.insert("requests".to_owned());
1912        contexts.httpx_modules.insert("httpx".to_owned());
1913        contexts.aiohttp_modules.insert("aiohttp".to_owned());
1914        discover_python_import_aliases(tokens, "requests", &mut contexts.request_modules);
1915        discover_python_import_aliases(tokens, "httpx", &mut contexts.httpx_modules);
1916        discover_python_import_aliases(tokens, "aiohttp", &mut contexts.aiohttp_modules);
1917        discover_python_direct_calls(
1918            tokens,
1919            "requests",
1920            SourceFramework::Requests,
1921            &mut contexts.direct_calls,
1922        );
1923        discover_python_direct_calls(
1924            tokens,
1925            "httpx",
1926            SourceFramework::Httpx,
1927            &mut contexts.direct_calls,
1928        );
1929        let request_session_imported = python_imports_item(tokens, "requests", "Session");
1930        let httpx_client_imported = python_imports_item(tokens, "httpx", "Client")
1931            || python_imports_item(tokens, "httpx", "AsyncClient");
1932        let aiohttp_client_imported = python_imports_item(tokens, "aiohttp", "ClientSession");
1933        for index in 0..tokens.len() {
1934            let Some(name) = tokens[index].ident() else {
1935                continue;
1936            };
1937            if !tokens
1938                .get(index + 1)
1939                .is_some_and(|token| token.is_punct('='))
1940            {
1941                continue;
1942            }
1943            let end = python_expression_end(tokens, index + 2);
1944            if let Some(value) =
1945                python_static_string_expression(tokens, index + 2, end, &contexts.string_constants)
1946            {
1947                contexts.string_constants.insert(name.to_owned(), value);
1948            }
1949            if let Some(framework) = python_test_client(tokens, index + 2, end) {
1950                contexts.test_clients.insert(name.to_owned(), framework);
1951                continue;
1952            }
1953            if contains_ident(tokens, index + 2, end, "FastAPI")
1954                || contains_ident(tokens, index + 2, end, "APIRouter")
1955            {
1956                contexts.fastapi_apps.insert(name.to_owned());
1957                if contains_ident(tokens, index + 2, end, "APIRouter")
1958                    && let Some(prefix) =
1959                        python_constructor_prefix(tokens, index + 2, end, "prefix")
1960                {
1961                    contexts.route_prefixes.insert(name.to_owned(), prefix);
1962                }
1963            }
1964            if contains_ident(tokens, index + 2, end, "Flask")
1965                || contains_ident(tokens, index + 2, end, "Blueprint")
1966            {
1967                contexts.flask_apps.insert(name.to_owned());
1968                if contains_ident(tokens, index + 2, end, "Blueprint")
1969                    && let Some(prefix) =
1970                        python_constructor_prefix(tokens, index + 2, end, "url_prefix")
1971                {
1972                    contexts.route_prefixes.insert(name.to_owned(), prefix);
1973                }
1974            }
1975            if contains_ident(tokens, index + 2, end, "Session")
1976                && (contains_any(tokens, index + 2, end, &contexts.request_modules)
1977                    || request_session_imported)
1978            {
1979                contexts.request_clients.insert(name.to_owned());
1980            }
1981            if (contains_ident(tokens, index + 2, end, "Client")
1982                || contains_ident(tokens, index + 2, end, "AsyncClient"))
1983                && (contains_any(tokens, index + 2, end, &contexts.httpx_modules)
1984                    || httpx_client_imported)
1985            {
1986                contexts.httpx_clients.insert(name.to_owned());
1987            }
1988            if contains_ident(tokens, index + 2, end, "ClientSession")
1989                && (contains_any(tokens, index + 2, end, &contexts.aiohttp_modules)
1990                    || aiohttp_client_imported)
1991            {
1992                contexts.aiohttp_clients.insert(name.to_owned());
1993            }
1994        }
1995        contexts.discover_with_targets(tokens, aiohttp_client_imported);
1996        contexts
1997    }
1998
1999    /// Clients bound by `with ... as NAME`.
2000    fn discover_with_targets(&mut self, tokens: &[Token], aiohttp_client_imported: bool) {
2001        for index in 0..tokens.len() {
2002            if !tokens[index].is_ident("as") {
2003                continue;
2004            }
2005            let Some(name) = tokens.get(index + 1).and_then(Token::ident) else {
2006                continue;
2007            };
2008            let start = index.saturating_sub(32);
2009            let with = (start..index)
2010                .rev()
2011                .find(|candidate| tokens[*candidate].is_ident("with"))
2012                .unwrap_or(start);
2013            if let Some(framework) = python_test_client(tokens, with, index) {
2014                self.test_clients.insert(name.to_owned(), framework);
2015            } else if aiohttp_client_imported
2016                && tokens[start..index]
2017                    .iter()
2018                    .any(|token| token.is_ident("ClientSession"))
2019            {
2020                self.aiohttp_clients.insert(name.to_owned());
2021            }
2022        }
2023    }
2024
2025    /// Client receivers and the framework of each.
2026    fn http_receivers(&self) -> BTreeMap<&str, SourceFramework> {
2027        self.request_modules
2028            .iter()
2029            .chain(&self.request_clients)
2030            .map(|name| (name.as_str(), SourceFramework::Requests))
2031            .chain(
2032                self.httpx_modules
2033                    .iter()
2034                    .chain(&self.httpx_clients)
2035                    .map(|name| (name.as_str(), SourceFramework::Httpx)),
2036            )
2037            .chain(
2038                self.aiohttp_clients
2039                    .iter()
2040                    .map(|name| (name.as_str(), SourceFramework::AioHttp)),
2041            )
2042            .chain(
2043                self.test_clients
2044                    .iter()
2045                    .map(|(name, framework)| (name.as_str(), *framework)),
2046            )
2047            .collect()
2048    }
2049}
2050
2051/// In-process test client constructed by the expression in `start..end`.
2052fn python_test_client(tokens: &[Token], start: usize, end: usize) -> Option<SourceFramework> {
2053    if contains_ident(tokens, start, end, "TestClient") {
2054        return Some(SourceFramework::TestClient);
2055    }
2056    let flask = (start.max(1)..end).any(|index| {
2057        tokens[index].is_ident("test_client")
2058            && tokens[index - 1].is_punct('.')
2059            && tokens
2060                .get(index + 1)
2061                .is_some_and(|token| token.is_punct('('))
2062    });
2063    if flask {
2064        return Some(SourceFramework::FlaskTestClient);
2065    }
2066    let httpx = contains_ident(tokens, start, end, "AsyncClient")
2067        || contains_ident(tokens, start, end, "Client");
2068    let in_process = contains_ident(tokens, start, end, "ASGITransport")
2069        || contains_ident(tokens, start, end, "WSGITransport")
2070        || (start.max(1)..end).any(|index| {
2071            tokens[index].is_ident("app")
2072                && (tokens[index - 1].is_punct('(') || tokens[index - 1].is_punct(','))
2073                && tokens
2074                    .get(index + 1)
2075                    .is_some_and(|token| token.is_punct('='))
2076        });
2077    (httpx && in_process).then_some(SourceFramework::TestClient)
2078}
2079
2080/// Functions, such as pytest fixtures, that return or yield an in-process test client.
2081fn parse_python_client_fixtures(
2082    tokens: &[Token],
2083    functions: &[FunctionSpan],
2084    contexts: &PythonContexts,
2085    observations: &mut SourceObservationCollector<'_>,
2086) {
2087    for index in 0..tokens.len() {
2088        if !tokens[index].is_ident("return") && !tokens[index].is_ident("yield") {
2089            continue;
2090        }
2091        let Some(function) = innermost_function(functions, index) else {
2092            continue;
2093        };
2094        let end = python_expression_end(tokens, index + 1);
2095        let named = tokens
2096            .get(index + 1)
2097            .and_then(Token::ident)
2098            .filter(|_| end == index + 2)
2099            .and_then(|name| contexts.test_clients.get(name).copied());
2100        let Some(framework) = named.or_else(|| python_test_client(tokens, index + 1, end)) else {
2101            continue;
2102        };
2103        let mut observation = confirmed_test(
2104            SourceLanguage::Python,
2105            framework,
2106            functions[function].name.clone(),
2107            tokens[index].line,
2108            tokens[index].end_line,
2109        );
2110        observation.role = SourceRole::Client;
2111        observations.push(observation);
2112    }
2113}
2114
2115/// Normalized `keyword=` string of the first call between `start` and `end`.
2116fn python_constructor_prefix(
2117    tokens: &[Token],
2118    start: usize,
2119    end: usize,
2120    keyword: &str,
2121) -> Option<String> {
2122    let open = (start..end).find(|candidate| tokens[*candidate].is_punct('('))?;
2123    let close = matching(tokens, open, '(', ')')?;
2124    let prefix = parse_keyword_string_values(tokens, open, close, keyword)
2125        .into_iter()
2126        .next()?;
2127    Some(normalize_source_http_path(&prefix))
2128}
2129
2130fn python_imports_item(tokens: &[Token], module: &str, item: &str) -> bool {
2131    tokens.iter().enumerate().any(|(index, token)| {
2132        token.is_ident("from")
2133            && tokens
2134                .get(index + 1)
2135                .is_some_and(|token| token.is_ident(module))
2136            && tokens
2137                .get(index + 2)
2138                .is_some_and(|token| token.is_ident("import"))
2139            && (index + 3..tokens.len())
2140                .take_while(|candidate| tokens[*candidate].line == token.line)
2141                .any(|candidate| tokens[candidate].is_ident(item))
2142    })
2143}
2144
2145fn discover_python_direct_calls(
2146    tokens: &[Token],
2147    module: &str,
2148    framework: SourceFramework,
2149    calls: &mut BTreeMap<String, (SourceFramework, String)>,
2150) {
2151    for index in 0..tokens.len() {
2152        if !tokens[index].is_ident("from")
2153            || !tokens
2154                .get(index + 1)
2155                .is_some_and(|token| token.is_ident(module))
2156            || !tokens
2157                .get(index + 2)
2158                .is_some_and(|token| token.is_ident("import"))
2159        {
2160            continue;
2161        }
2162        let mut cursor = index + 3;
2163        while cursor < tokens.len() && tokens[cursor].line == tokens[index].line {
2164            let Some(imported) = tokens[cursor].ident() else {
2165                cursor += 1;
2166                continue;
2167            };
2168            if canonical_method(imported).is_none() && imported != "request" {
2169                cursor += 1;
2170                continue;
2171            }
2172            let (local, advance) = if tokens
2173                .get(cursor + 1)
2174                .is_some_and(|token| token.is_ident("as"))
2175            {
2176                (
2177                    tokens
2178                        .get(cursor + 2)
2179                        .and_then(Token::ident)
2180                        .unwrap_or(imported),
2181                    3,
2182                )
2183            } else {
2184                (imported, 1)
2185            };
2186            calls.insert(local.to_owned(), (framework, imported.to_owned()));
2187            cursor += advance;
2188        }
2189    }
2190}
2191
2192fn python_expression_end(tokens: &[Token], start: usize) -> usize {
2193    let mut round = 0_i32;
2194    let mut square = 0_i32;
2195    let mut curly = 0_i32;
2196    let mut previous_line = tokens.get(start).map_or(0, |token| token.line);
2197    for (index, token) in tokens.iter().enumerate().skip(start) {
2198        if index > start && token.line > previous_line && round == 0 && square == 0 && curly == 0 {
2199            return index;
2200        }
2201        if token.is_punct(';') && round == 0 && square == 0 && curly == 0 {
2202            return index;
2203        }
2204        match token.kind {
2205            TokenKind::Punct('(') => round += 1,
2206            TokenKind::Punct(')') => round -= 1,
2207            TokenKind::Punct('[') => square += 1,
2208            TokenKind::Punct(']') => square -= 1,
2209            TokenKind::Punct('{') => curly += 1,
2210            TokenKind::Punct('}') => curly -= 1,
2211            _ => {}
2212        }
2213        previous_line = token.line;
2214    }
2215    tokens.len()
2216}
2217
2218fn discover_python_import_aliases(tokens: &[Token], module: &str, aliases: &mut BTreeSet<String>) {
2219    for index in 0..tokens.len() {
2220        if !tokens[index].is_ident("import")
2221            || !tokens
2222                .get(index + 1)
2223                .is_some_and(|token| token.is_ident(module))
2224        {
2225            continue;
2226        }
2227        if tokens
2228            .get(index + 2)
2229            .is_some_and(|token| token.is_ident("as"))
2230            && let Some(alias) = tokens.get(index + 3).and_then(Token::ident)
2231        {
2232            aliases.insert(alias.to_owned());
2233        }
2234    }
2235}
2236
2237fn contains_any(tokens: &[Token], start: usize, end: usize, names: &BTreeSet<String>) -> bool {
2238    tokens.get(start..end).is_some_and(|slice| {
2239        slice
2240            .iter()
2241            .filter_map(Token::ident)
2242            .any(|name| names.contains(name))
2243    })
2244}
2245
2246fn python_static_string_expression(
2247    tokens: &[Token],
2248    start: usize,
2249    end: usize,
2250    constants: &BTreeMap<String, String>,
2251) -> Option<String> {
2252    let mut output = String::new();
2253    let mut found = false;
2254    for token in tokens.get(start..end)? {
2255        if let Some(value) = token.literal() {
2256            output.push_str(value);
2257            found = true;
2258        } else if let Some(name) = token.ident() {
2259            output.push_str(constants.get(name)?);
2260            found = true;
2261        } else if !matches!(token.kind, TokenKind::Punct('+' | '(' | ')' | '[' | ']')) {
2262            return None;
2263        }
2264    }
2265    found.then_some(output)
2266}
2267
2268fn python_functions(source: &str, tokens: &[Token]) -> Vec<FunctionSpan> {
2269    let line_count = saturating_u32(source.lines().count().max(1));
2270    let mut functions = Vec::new();
2271    for index in 0..tokens.len() {
2272        if !tokens[index].is_ident("def") {
2273            continue;
2274        }
2275        let Some(name) = tokens.get(index + 1).and_then(Token::ident) else {
2276            continue;
2277        };
2278        let indent = source_indent(source, tokens[index].line);
2279        let end_line = python_block_end(source, tokens[index].line, indent, line_count);
2280        let end_token = (index + 1..tokens.len())
2281            .find(|candidate| tokens[*candidate].line > end_line)
2282            .unwrap_or(tokens.len())
2283            .saturating_sub(1);
2284        functions.push(FunctionSpan {
2285            name: name.to_owned(),
2286            start_token: index,
2287            body_start_token: index,
2288            end_token,
2289        });
2290    }
2291    functions
2292}
2293
2294fn source_indent(source: &str, line: u32) -> usize {
2295    source
2296        .lines()
2297        .nth(line.saturating_sub(1) as usize)
2298        .map_or(0, |value| {
2299            value
2300                .chars()
2301                .take_while(|character| character.is_whitespace())
2302                .count()
2303        })
2304}
2305
2306fn python_block_end(source: &str, start: u32, indent: usize, fallback: u32) -> u32 {
2307    for (offset, line) in source.lines().enumerate().skip(start as usize) {
2308        let trimmed = line.trim();
2309        if trimmed.is_empty() || trimmed.starts_with('#') {
2310            continue;
2311        }
2312        let candidate_indent = line
2313            .chars()
2314            .take_while(|character| character.is_whitespace())
2315            .count();
2316        if candidate_indent <= indent {
2317            return saturating_u32(offset);
2318        }
2319    }
2320    fallback
2321}
2322
2323fn parse_python_routes(
2324    tokens: &[Token],
2325    contexts: &PythonContexts,
2326    observations: &mut SourceObservationCollector<'_>,
2327) {
2328    for index in 0..tokens.len() {
2329        if !tokens[index].is_punct('@') {
2330            continue;
2331        }
2332        let Some((receiver, decorator, open)) = python_decorator_call(tokens, index) else {
2333            continue;
2334        };
2335        let Some(close) = matching(tokens, open, '(', ')') else {
2336            continue;
2337        };
2338        let Some((name, signature_end)) = python_function_after(tokens, close) else {
2339            continue;
2340        };
2341        let framework = if contexts.fastapi_apps.contains(receiver) {
2342            SourceFramework::FastApi
2343        } else if contexts.flask_apps.contains(receiver) {
2344            SourceFramework::Flask
2345        } else {
2346            continue;
2347        };
2348        let path_start = top_level_arguments(tokens, open, close).first().copied();
2349        let resolved_path = path_start.and_then(|start| {
2350            python_static_string_expression(
2351                tokens,
2352                start,
2353                python_argument_end(tokens, start, close),
2354                &contexts.string_constants,
2355            )
2356        });
2357        let raw_path = resolved_path.or_else(|| {
2358            tokens
2359                .get(open + 1)
2360                .and_then(Token::literal)
2361                .map(str::to_owned)
2362        });
2363        let prefixed_path = raw_path.as_ref().map(|path| {
2364            contexts.route_prefixes.get(receiver).map_or_else(
2365                || path.clone(),
2366                |prefix| normalize_source_http_path(&format!("{prefix}{path}")),
2367            )
2368        });
2369        let literal = prefixed_path.as_deref();
2370        let methods = python_route_methods(tokens, open, close, decorator, framework);
2371        let router = Some(SymbolRef::Local(receiver.to_owned()));
2372        if methods.is_empty() {
2373            let mut observation = inexact_http(
2374                SourceLanguage::Python,
2375                framework,
2376                SourceRole::Provider,
2377                None,
2378                literal.and_then(route_literal_path),
2379                Some(name),
2380                SourceLineRange {
2381                    start: tokens[index].line,
2382                    end: tokens[signature_end].end_line,
2383                },
2384                SourceWarning::DynamicMethod,
2385            );
2386            observation.router = router;
2387            observations.push(observation);
2388        } else {
2389            for method in methods {
2390                let mut observation = http_from_literal(
2391                    SourceLanguage::Python,
2392                    framework,
2393                    SourceRole::Provider,
2394                    Some(method),
2395                    literal,
2396                    Some(name.clone()),
2397                    SourceLineRange {
2398                        start: tokens[index].line,
2399                        end: tokens[signature_end].end_line,
2400                    },
2401                    true,
2402                );
2403                observation.router.clone_from(&router);
2404                observations.push(observation);
2405            }
2406        }
2407    }
2408}
2409
2410/// Records `include_router` and `register_blueprint` mounts on known applications and routers.
2411fn parse_python_router_mounts(
2412    tokens: &[Token],
2413    contexts: &PythonContexts,
2414    observations: &mut SourceObservationCollector<'_>,
2415) {
2416    let imports = python_router_imports(tokens);
2417    for index in 0..tokens.len().saturating_sub(3) {
2418        let Some(receiver) = tokens[index].ident() else {
2419            continue;
2420        };
2421        let (framework, keyword) = match tokens[index + 2].ident() {
2422            Some("include_router") if contexts.fastapi_apps.contains(receiver) => {
2423                (SourceFramework::FastApi, "prefix")
2424            }
2425            Some("register_blueprint") if contexts.flask_apps.contains(receiver) => {
2426                (SourceFramework::Flask, "url_prefix")
2427            }
2428            _ => continue,
2429        };
2430        if !tokens[index + 1].is_punct('.') || !tokens[index + 3].is_punct('(') {
2431            continue;
2432        }
2433        let open = index + 3;
2434        let Some(close) = matching(tokens, open, '(', ')') else {
2435            continue;
2436        };
2437        let Some(&first) = top_level_arguments(tokens, open, close).first() else {
2438            continue;
2439        };
2440        let mut dotted = Vec::new();
2441        let mut cursor = first;
2442        while let Some(name) = tokens.get(cursor).and_then(Token::ident) {
2443            dotted.push(name);
2444            if !tokens
2445                .get(cursor + 1)
2446                .is_some_and(|token| token.is_punct('.'))
2447            {
2448                break;
2449            }
2450            cursor += 2;
2451        }
2452        let Some(child) = python_router_reference(&dotted, contexts, &imports) else {
2453            continue;
2454        };
2455        let prefix = parse_keyword_string_values(tokens, open, close, keyword)
2456            .into_iter()
2457            .next();
2458        observations.push(mount_observation(
2459            SourceLanguage::Python,
2460            framework,
2461            child,
2462            Some(SymbolRef::Local(receiver.to_owned())),
2463            prefix.as_deref(),
2464            SourceLineRange {
2465                start: tokens[index].line,
2466                end: tokens[close].end_line,
2467            },
2468        ));
2469    }
2470}
2471
2472/// Routes registered by `FastAPI` `add_api_route(path, endpoint)` and Flask
2473/// `add_url_rule(rule, endpoint, view_func)` calls.
2474fn parse_python_route_calls(
2475    tokens: &[Token],
2476    contexts: &PythonContexts,
2477    observations: &mut SourceObservationCollector<'_>,
2478) {
2479    for index in 0..tokens.len().saturating_sub(3) {
2480        let Some(receiver) = tokens[index].ident() else {
2481            continue;
2482        };
2483        if !tokens[index + 1].is_punct('.') || !tokens[index + 3].is_punct('(') {
2484            continue;
2485        }
2486        let (framework, path_keyword, handler_keyword, handler_position) =
2487            match tokens[index + 2].ident() {
2488                Some("add_api_route") if contexts.fastapi_apps.contains(receiver) => {
2489                    (SourceFramework::FastApi, "path", "endpoint", 1)
2490                }
2491                Some("add_url_rule") if contexts.flask_apps.contains(receiver) => {
2492                    (SourceFramework::Flask, "rule", "view_func", 2)
2493                }
2494                _ => continue,
2495            };
2496        let open = index + 3;
2497        let Some(close) = matching(tokens, open, '(', ')') else {
2498            continue;
2499        };
2500        let arguments = top_level_arguments(tokens, open, close)
2501            .into_iter()
2502            .map(|start| {
2503                let end = python_argument_end(tokens, start, close);
2504                match keyword_argument(tokens, start, end) {
2505                    Some((keyword, value)) => (Some(keyword), value, end),
2506                    None => (None, start, end),
2507                }
2508            })
2509            .collect::<Vec<_>>();
2510        let positional = arguments
2511            .iter()
2512            .filter(|(keyword, ..)| keyword.is_none())
2513            .collect::<Vec<_>>();
2514        let path = arguments
2515            .iter()
2516            .find(|(keyword, ..)| keyword.as_deref() == Some(path_keyword))
2517            .or_else(|| positional.first().copied())
2518            .and_then(|(_, start, end)| {
2519                python_static_string_expression(tokens, *start, *end, &contexts.string_constants)
2520            });
2521        let handler = arguments
2522            .iter()
2523            .find(|(keyword, ..)| keyword.as_deref() == Some(handler_keyword))
2524            .or_else(|| positional.get(handler_position).copied())
2525            .and_then(|(_, start, end)| {
2526                (*start..*end)
2527                    .map(|token| {
2528                        tokens[token]
2529                            .ident()
2530                            .or_else(|| tokens[token].is_punct('.').then_some("."))
2531                    })
2532                    .collect::<Option<String>>()
2533            });
2534        let mut methods =
2535            python_route_methods(tokens, open, close, "route", SourceFramework::Flask);
2536        if methods.is_empty() {
2537            methods.insert("GET".to_owned());
2538        }
2539        for method in methods {
2540            let mut observation = http_from_literal(
2541                SourceLanguage::Python,
2542                framework,
2543                SourceRole::Provider,
2544                Some(method),
2545                path.as_deref(),
2546                handler.clone(),
2547                SourceLineRange {
2548                    start: tokens[index].line,
2549                    end: tokens[close].end_line,
2550                },
2551                true,
2552            );
2553            observation.router = Some(SymbolRef::Local(receiver.to_owned()));
2554            observations.push(observation);
2555        }
2556    }
2557}
2558
2559fn python_router_reference(
2560    dotted: &[&str],
2561    contexts: &PythonContexts,
2562    imports: &BTreeMap<String, (String, String)>,
2563) -> Option<SymbolRef> {
2564    let (head, rest) = dotted.split_first()?;
2565    if let Some((module, name)) = imports.get(*head) {
2566        let name = std::iter::once(name.as_str())
2567            .filter(|name| !name.is_empty())
2568            .chain(rest.iter().copied())
2569            .collect::<Vec<_>>()
2570            .join(".");
2571        return (!name.is_empty()).then(|| SymbolRef::Import {
2572            module: module.clone(),
2573            name,
2574        });
2575    }
2576    (rest.is_empty()
2577        && (contexts.fastapi_apps.contains(*head) || contexts.flask_apps.contains(*head)))
2578    .then(|| SymbolRef::Local((*head).to_owned()))
2579}
2580
2581/// Maps local names to `(module, imported name)`; `import a.b as c` binds `c` to `(a.b, "")`.
2582fn python_router_imports(tokens: &[Token]) -> BTreeMap<String, (String, String)> {
2583    let mut imports = BTreeMap::new();
2584    for index in 0..tokens.len() {
2585        if tokens[index].is_ident("import")
2586            && (index == 0 || tokens[index - 1].line != tokens[index].line)
2587        {
2588            let mut cursor = index + 1;
2589            let mut module = String::new();
2590            while let Some(token) = tokens
2591                .get(cursor)
2592                .filter(|token| token.line == tokens[index].line)
2593            {
2594                match (token.ident(), token.is_punct('.')) {
2595                    (Some(name), _) if name != "as" => module.push_str(name),
2596                    (None, true) => module.push('.'),
2597                    _ => break,
2598                }
2599                cursor += 1;
2600            }
2601            if tokens.get(cursor).is_some_and(|token| token.is_ident("as"))
2602                && let Some(alias) = tokens.get(cursor + 1).and_then(Token::ident)
2603            {
2604                imports.insert(alias.to_owned(), (module, String::new()));
2605            }
2606            continue;
2607        }
2608        if !tokens[index].is_ident("from") {
2609            continue;
2610        }
2611        let Some(import_index) = (index + 1..tokens.len())
2612            .take_while(|candidate| tokens[*candidate].line == tokens[index].line)
2613            .find(|candidate| tokens[*candidate].is_ident("import"))
2614        else {
2615            continue;
2616        };
2617        let module = tokens[index + 1..import_index]
2618            .iter()
2619            .map(|token| token.ident().unwrap_or("."))
2620            .collect::<String>();
2621        let parenthesized = tokens
2622            .get(import_index + 1)
2623            .is_some_and(|token| token.is_punct('('));
2624        let end = if parenthesized {
2625            matching(tokens, import_index + 1, '(', ')').unwrap_or(import_index + 1)
2626        } else {
2627            (import_index + 1..tokens.len())
2628                .find(|candidate| tokens[*candidate].line != tokens[index].line)
2629                .unwrap_or(tokens.len())
2630        };
2631        let mut cursor = import_index + 1;
2632        while cursor < end {
2633            let Some(imported) = tokens[cursor].ident() else {
2634                cursor += 1;
2635                continue;
2636            };
2637            let aliased = tokens
2638                .get(cursor + 1)
2639                .is_some_and(|token| token.is_ident("as"));
2640            let local = if aliased {
2641                tokens
2642                    .get(cursor + 2)
2643                    .and_then(Token::ident)
2644                    .unwrap_or(imported)
2645            } else {
2646                imported
2647            };
2648            imports.insert(local.to_owned(), (module.clone(), imported.to_owned()));
2649            cursor += if aliased { 3 } else { 1 };
2650        }
2651    }
2652    imports
2653}
2654
2655fn python_decorator_call(tokens: &[Token], at: usize) -> Option<(&str, &str, usize)> {
2656    let mut names = Vec::new();
2657    let mut cursor = at.saturating_add(1);
2658    loop {
2659        names.push(tokens.get(cursor)?.ident()?);
2660        if tokens
2661            .get(cursor + 1)
2662            .is_some_and(|token| token.is_punct('.'))
2663        {
2664            cursor = cursor.saturating_add(2);
2665            continue;
2666        }
2667        break;
2668    }
2669    let open = cursor.saturating_add(1);
2670    if names.len() < 2 || !tokens.get(open).is_some_and(|token| token.is_punct('(')) {
2671        return None;
2672    }
2673    Some((names[names.len() - 2], names[names.len() - 1], open))
2674}
2675
2676fn python_argument_end(tokens: &[Token], start: usize, close: usize) -> usize {
2677    let mut round = 0_i32;
2678    let mut square = 0_i32;
2679    let mut curly = 0_i32;
2680    for (index, token) in tokens.iter().enumerate().take(close).skip(start) {
2681        match token.kind {
2682            TokenKind::Punct('(') => round += 1,
2683            TokenKind::Punct(')') => round -= 1,
2684            TokenKind::Punct('[') => square += 1,
2685            TokenKind::Punct(']') => square -= 1,
2686            TokenKind::Punct('{') => curly += 1,
2687            TokenKind::Punct('}') => curly -= 1,
2688            TokenKind::Punct(',') if round == 0 && square == 0 && curly == 0 => return index,
2689            _ => {}
2690        }
2691    }
2692    close
2693}
2694
2695fn python_function_after(tokens: &[Token], close: usize) -> Option<(String, usize)> {
2696    let mut index = close + 1;
2697    while index < tokens.len() && tokens[index].line <= tokens[close].line.saturating_add(12) {
2698        if tokens[index].is_ident("async") {
2699            index += 1;
2700            continue;
2701        }
2702        if tokens[index].is_ident("def") {
2703            let name = tokens.get(index + 1)?.ident()?.to_owned();
2704            let end = (index + 2..tokens.len())
2705                .find(|candidate| tokens[*candidate].is_punct(':'))
2706                .unwrap_or(index + 1);
2707            return Some((name, end));
2708        }
2709        if tokens[index].is_punct('@') {
2710            return None;
2711        }
2712        index += 1;
2713    }
2714    None
2715}
2716
2717fn python_route_methods(
2718    tokens: &[Token],
2719    open: usize,
2720    close: usize,
2721    decorator: &str,
2722    framework: SourceFramework,
2723) -> BTreeSet<String> {
2724    if let Some(method) = canonical_method(decorator) {
2725        return BTreeSet::from([method.to_owned()]);
2726    }
2727    let mut methods = parse_keyword_string_values(tokens, open, close, "methods")
2728        .into_iter()
2729        .filter_map(|method| canonical_method(&method).map(str::to_owned))
2730        .collect::<BTreeSet<_>>();
2731    if framework == SourceFramework::Flask && decorator == "route" && methods.is_empty() {
2732        methods.insert("GET".to_owned());
2733    }
2734    methods
2735}
2736
2737fn parse_python_http_registries(
2738    tokens: &[Token],
2739    observations: &mut SourceObservationCollector<'_>,
2740) {
2741    for index in 0..tokens.len() {
2742        let Some(name) = tokens[index].ident() else {
2743            continue;
2744        };
2745        if !name
2746            .chars()
2747            .all(|character| character.is_ascii_uppercase() || character == '_')
2748            || !tokens
2749                .get(index + 1)
2750                .is_some_and(|token| token.is_punct('='))
2751            || !tokens
2752                .get(index + 2)
2753                .is_some_and(|token| token.is_punct('{'))
2754        {
2755            continue;
2756        }
2757        let open = index + 2;
2758        let Some(close) = matching(tokens, open, '{', '}') else {
2759            continue;
2760        };
2761        parse_python_http_registry_dict(tokens, open, close, "", observations, 0);
2762    }
2763}
2764
2765fn parse_python_http_registry_dict(
2766    tokens: &[Token],
2767    open: usize,
2768    close: usize,
2769    prefix: &str,
2770    observations: &mut SourceObservationCollector<'_>,
2771    depth: usize,
2772) {
2773    if depth >= 32 {
2774        return;
2775    }
2776    let mut cursor = open.saturating_add(1);
2777    while cursor < close {
2778        while cursor < close && tokens[cursor].is_punct(',') {
2779            cursor += 1;
2780        }
2781        let Some(key) = tokens.get(cursor).and_then(Token::literal) else {
2782            cursor += 1;
2783            continue;
2784        };
2785        if !tokens
2786            .get(cursor + 1)
2787            .is_some_and(|token| token.is_punct(':'))
2788        {
2789            cursor += 1;
2790            continue;
2791        }
2792        let value_start = cursor + 2;
2793        let value_end = python_argument_end(tokens, value_start, close);
2794        parse_python_http_registry_value(
2795            tokens,
2796            value_start,
2797            value_end,
2798            prefix,
2799            key,
2800            observations,
2801            depth,
2802        );
2803        cursor = value_end.saturating_add(1);
2804    }
2805}
2806
2807fn parse_python_http_registry_value(
2808    tokens: &[Token],
2809    start: usize,
2810    end: usize,
2811    prefix: &str,
2812    key: &str,
2813    observations: &mut SourceObservationCollector<'_>,
2814    depth: usize,
2815) {
2816    if tokens.get(start).is_some_and(|token| token.is_punct('[')) {
2817        let Some(close) = matching(tokens, start, '[', ']').filter(|close| *close <= end) else {
2818            return;
2819        };
2820        let arguments = top_level_arguments(tokens, start, close);
2821        let Some(method) = arguments
2822            .first()
2823            .and_then(|argument| tokens.get(*argument))
2824            .and_then(Token::literal)
2825            .and_then(canonical_method)
2826        else {
2827            return;
2828        };
2829        let Some(path) = arguments
2830            .get(1)
2831            .and_then(|argument| tokens.get(*argument))
2832            .and_then(Token::literal)
2833        else {
2834            return;
2835        };
2836        let combined = canonical_python_registry_path(prefix, path);
2837        observations.push(http_from_literal(
2838            SourceLanguage::Python,
2839            SourceFramework::PythonHttpRegistry,
2840            SourceRole::Consumer,
2841            Some(method.to_owned()),
2842            Some(&combined),
2843            Some(key.to_owned()),
2844            SourceLineRange {
2845                start: tokens[start].line,
2846                end: tokens[close].end_line,
2847            },
2848            false,
2849        ));
2850        return;
2851    }
2852    if !tokens.get(start).is_some_and(|token| token.is_punct('(')) {
2853        return;
2854    }
2855    let Some(close) = matching(tokens, start, '(', ')').filter(|close| *close <= end) else {
2856        return;
2857    };
2858    let arguments = top_level_arguments(tokens, start, close);
2859    let Some(segment) = arguments
2860        .first()
2861        .and_then(|argument| tokens.get(*argument))
2862        .and_then(Token::literal)
2863    else {
2864        return;
2865    };
2866    let Some(dictionary) = arguments.get(1).copied().filter(|argument| {
2867        tokens
2868            .get(*argument)
2869            .is_some_and(|token| token.is_punct('{'))
2870    }) else {
2871        return;
2872    };
2873    let Some(dictionary_close) = matching(tokens, dictionary, '{', '}') else {
2874        return;
2875    };
2876    let nested_prefix = canonical_python_registry_path(prefix, segment);
2877    parse_python_http_registry_dict(
2878        tokens,
2879        dictionary,
2880        dictionary_close,
2881        &nested_prefix,
2882        observations,
2883        depth.saturating_add(1),
2884    );
2885}
2886
2887fn canonical_python_registry_path(prefix: &str, segment: &str) -> String {
2888    let joined = format!("{prefix}{segment}")
2889        .replace("{{", "{")
2890        .replace("}}", "}");
2891    normalize_source_http_path(&joined)
2892}
2893
2894fn parse_python_factories(
2895    source: &str,
2896    tokens: &[Token],
2897    observations: &mut SourceObservationCollector<'_>,
2898) {
2899    let imported_paths = python_imported_symbol_paths(tokens);
2900    let fallback = saturating_u32(source.lines().count().max(1));
2901    for index in 0..tokens.len() {
2902        if !tokens[index].is_ident("class") {
2903            continue;
2904        }
2905        let Some(factory_name) = tokens.get(index + 1).and_then(Token::ident) else {
2906            continue;
2907        };
2908        let signature_end = (index + 2..tokens.len())
2909            .find(|candidate| tokens[*candidate].is_punct(':'))
2910            .unwrap_or(index + 1);
2911        if !tokens
2912            .get(index + 2..signature_end)
2913            .is_some_and(|signature| {
2914                signature
2915                    .iter()
2916                    .filter_map(Token::ident)
2917                    .any(|base| base == "Factory" || base.ends_with("Factory"))
2918            })
2919        {
2920            continue;
2921        }
2922        let start_line = tokens[index].line;
2923        let end_line = python_block_end(
2924            source,
2925            start_line,
2926            source_indent(source, start_line),
2927            fallback,
2928        );
2929        let model_assignment = (signature_end + 1..tokens.len())
2930            .take_while(|candidate| tokens[*candidate].line <= end_line)
2931            .find_map(|candidate| {
2932                if tokens[candidate].is_ident("model")
2933                    && tokens
2934                        .get(candidate + 1)
2935                        .is_some_and(|token| token.is_punct('='))
2936                {
2937                    Some((
2938                        tokens.get(candidate + 2).and_then(Token::ident)?,
2939                        tokens[candidate].line,
2940                    ))
2941                } else {
2942                    None
2943                }
2944            });
2945        let Some((model_name, model_line)) = model_assignment else {
2946            continue;
2947        };
2948        observations.push(SourceObservation {
2949            language: SourceLanguage::Python,
2950            framework: SourceFramework::FactoryBoy,
2951            role: SourceRole::Factory,
2952            method: None,
2953            path: None,
2954            symbol_name: Some(factory_name.to_owned()),
2955            symbol_start_line: None,
2956            related_symbol: Some(model_name.to_owned()),
2957            related_path: imported_paths.get(model_name).cloned(),
2958            authority: None,
2959            router: None,
2960            mount_parent: None,
2961            url: None,
2962            call: None,
2963            lines: SourceLineRange {
2964                start: start_line,
2965                end: model_line,
2966            },
2967            status: SourceEpistemicStatus::Confirmed,
2968            confidence: 1.0,
2969            warnings: Vec::new(),
2970        });
2971    }
2972}
2973
2974fn python_imported_symbol_paths(tokens: &[Token]) -> BTreeMap<String, String> {
2975    let mut output = BTreeMap::new();
2976    for index in 0..tokens.len() {
2977        if !tokens[index].is_ident("from") {
2978            continue;
2979        }
2980        let import_index = (index + 1..tokens.len())
2981            .take_while(|candidate| tokens[*candidate].line == tokens[index].line)
2982            .find(|candidate| tokens[*candidate].is_ident("import"));
2983        let Some(import_index) = import_index else {
2984            continue;
2985        };
2986        let module = tokens[index + 1..import_index]
2987            .iter()
2988            .filter_map(Token::ident)
2989            .collect::<Vec<_>>()
2990            .join("/");
2991        if module.is_empty() {
2992            continue;
2993        }
2994        let target_path = format!("{module}.py");
2995        let mut cursor = import_index + 1;
2996        while cursor < tokens.len() && tokens[cursor].line == tokens[index].line {
2997            let Some(imported) = tokens[cursor].ident() else {
2998                cursor += 1;
2999                continue;
3000            };
3001            let (local, advance) = if tokens
3002                .get(cursor + 1)
3003                .is_some_and(|token| token.is_ident("as"))
3004            {
3005                (
3006                    tokens
3007                        .get(cursor + 2)
3008                        .and_then(Token::ident)
3009                        .unwrap_or(imported),
3010                    3,
3011                )
3012            } else {
3013                (imported, 1)
3014            };
3015            output.insert(local.to_owned(), target_path.clone());
3016            cursor += advance;
3017        }
3018    }
3019    output
3020}
3021
3022fn parse_python_http_calls(
3023    tokens: &[Token],
3024    functions: &[FunctionSpan],
3025    contexts: &PythonContexts,
3026    scopes: &PythonScopes<'_>,
3027    observations: &mut SourceObservationCollector<'_>,
3028) {
3029    let receivers = contexts.http_receivers();
3030    for index in 0..tokens.len() {
3031        let Some(receiver) = tokens[index].ident() else {
3032            continue;
3033        };
3034        let member = || {
3035            tokens
3036                .get(index + 1)
3037                .is_some_and(|token| token.is_punct('.'))
3038                .then(|| tokens.get(index + 2).and_then(Token::ident))
3039                .flatten()
3040        };
3041        let mut parameter = None;
3042        let (framework, call, open) = if let Some(framework) = receivers.get(receiver).copied() {
3043            let Some(call) = member() else {
3044                continue;
3045            };
3046            (framework, call, index + 3)
3047        } else if let Some((framework, call)) = contexts.direct_calls.get(receiver) {
3048            (*framework, call.as_str(), index + 1)
3049        } else if let Some(call) = member().filter(|call| canonical_method(call).is_some())
3050            && let Some(received) = python_received_client(tokens, index, scopes)
3051        {
3052            parameter = Some(received);
3053            (SourceFramework::TestClient, call, index + 3)
3054        } else {
3055            continue;
3056        };
3057        if !tokens.get(open).is_some_and(|token| token.is_punct('(')) {
3058            continue;
3059        }
3060        let Some(close) = matching(tokens, open, '(', ')') else {
3061            continue;
3062        };
3063        let arguments = top_level_arguments(tokens, open, close);
3064        let (method, path_argument) = if call == "request" {
3065            (
3066                arguments
3067                    .first()
3068                    .and_then(|argument| tokens.get(*argument))
3069                    .and_then(Token::literal)
3070                    .and_then(canonical_method)
3071                    .map(str::to_owned),
3072                arguments.get(1).copied(),
3073            )
3074        } else {
3075            (
3076                canonical_method(call).map(str::to_owned),
3077                arguments.first().copied(),
3078            )
3079        };
3080        if method.is_none() && call != "request" {
3081            continue;
3082        }
3083        let template = path_argument.map(|argument| {
3084            let end = python_argument_end(tokens, argument, close);
3085            let start = keyword_argument(tokens, argument, end)
3086                .filter(|(keyword, _)| keyword == "url")
3087                .map_or(argument, |(_, value)| value);
3088            scopes.template(start, end, index)
3089        });
3090        let literal = template.as_ref().and_then(UrlTemplate::client_literal);
3091        let mut observation = http_from_literal(
3092            SourceLanguage::Python,
3093            framework,
3094            SourceRole::Consumer,
3095            method,
3096            literal.as_deref(),
3097            enclosing_symbol(functions, index),
3098            SourceLineRange {
3099                start: tokens[index].line,
3100                end: tokens[close].end_line,
3101            },
3102            false,
3103        );
3104        observation.url = template.filter(UrlTemplate::has_parameters);
3105        if let Some(received) = parameter {
3106            if !literal.as_deref().is_some_and(|path| path.starts_with('/')) {
3107                continue;
3108            }
3109            observation.router = Some(received);
3110            observation.status = SourceEpistemicStatus::Ambiguous;
3111            observation.confidence = 0.0;
3112        }
3113        if call == "request" && observation.method.is_none() {
3114            observation.status = SourceEpistemicStatus::Incomplete;
3115            observation.confidence = 0.0;
3116            observation.warnings.push(SourceWarning::DynamicMethod);
3117            observation.warnings.sort();
3118            observation.warnings.dedup();
3119        }
3120        observations.push(observation);
3121    }
3122}
3123
3124/// Parameter of the enclosing function through which the call at `index` receives its client.
3125fn python_received_client(
3126    tokens: &[Token],
3127    index: usize,
3128    scopes: &PythonScopes<'_>,
3129) -> Option<SymbolRef> {
3130    if index > 0 && tokens[index - 1].is_punct('.') {
3131        return None;
3132    }
3133    let name = tokens[index].ident()?;
3134    let function = scopes.innermost(index)?;
3135    let position = scopes
3136        .parameters_of(function)
3137        .iter()
3138        .position(|parameter| parameter == name)?;
3139    Some(SymbolRef::Parameter {
3140        name: name.to_owned(),
3141        index: position,
3142    })
3143}
3144
3145fn parse_python_tests(
3146    source: &str,
3147    tokens: &[Token],
3148    observations: &mut SourceObservationCollector<'_>,
3149) {
3150    let unittest_classes = python_unittest_classes(source, tokens);
3151    let python_classes = python_class_ranges(source, tokens);
3152    for index in 0..tokens.len() {
3153        if !tokens[index].is_ident("def") {
3154            continue;
3155        }
3156        let Some(name) = tokens.get(index + 1).and_then(Token::ident) else {
3157            continue;
3158        };
3159        if !name.starts_with("test_") {
3160            continue;
3161        }
3162        let signature_end = (index + 2..tokens.len())
3163            .find(|candidate| tokens[*candidate].is_punct(':'))
3164            .unwrap_or(index + 1);
3165        let line = tokens[index].line;
3166        let is_unittest = unittest_classes
3167            .iter()
3168            .any(|range| range.start <= line && line <= range.end);
3169        let indent = source_indent(source, line);
3170        let is_class_method = python_classes.iter().any(|(range, body_indent)| {
3171            range.start <= line && line <= range.end && indent == *body_indent
3172        });
3173        if !is_unittest && indent != 0 && !is_class_method {
3174            continue;
3175        }
3176        observations.push(confirmed_test(
3177            SourceLanguage::Python,
3178            if is_unittest {
3179                SourceFramework::Unittest
3180            } else if is_class_method {
3181                SourceFramework::PythonTest
3182            } else {
3183                SourceFramework::Pytest
3184            },
3185            name.to_owned(),
3186            line,
3187            tokens[signature_end].end_line,
3188        ));
3189    }
3190}
3191
3192fn python_class_ranges(source: &str, tokens: &[Token]) -> Vec<(SourceLineRange, usize)> {
3193    let fallback = saturating_u32(source.lines().count().max(1));
3194    let mut classes = Vec::new();
3195    for token in tokens.iter().filter(|token| token.is_ident("class")) {
3196        let class_indent = source_indent(source, token.line);
3197        let end = python_block_end(source, token.line, class_indent, fallback);
3198        let body_indent = source
3199            .lines()
3200            .enumerate()
3201            .skip(usize::try_from(token.line).unwrap_or(usize::MAX))
3202            .take(usize::try_from(end.saturating_sub(token.line)).unwrap_or(usize::MAX))
3203            .find_map(|(index, line)| {
3204                let trimmed = line.trim();
3205                let line_number = saturating_u32(index + 1);
3206                let indent = source_indent(source, line_number);
3207                (!trimmed.is_empty() && !trimmed.starts_with('#') && indent > class_indent)
3208                    .then_some(indent)
3209            });
3210        if let Some(body_indent) = body_indent {
3211            classes.push((
3212                SourceLineRange {
3213                    start: token.line,
3214                    end,
3215                },
3216                body_indent,
3217            ));
3218        }
3219    }
3220    classes
3221}
3222
3223fn python_unittest_classes(source: &str, tokens: &[Token]) -> Vec<SourceLineRange> {
3224    if !has_ident(tokens, "unittest") {
3225        return Vec::new();
3226    }
3227    let fallback = saturating_u32(source.lines().count().max(1));
3228    let mut classes = Vec::new();
3229    for index in 0..tokens.len() {
3230        if !tokens[index].is_ident("class") {
3231            continue;
3232        }
3233        let signature_end = (index + 1..tokens.len())
3234            .find(|candidate| tokens[*candidate].is_punct(':'))
3235            .unwrap_or(index);
3236        if !contains_ident(tokens, index + 1, signature_end, "TestCase") {
3237            continue;
3238        }
3239        let start = tokens[index].line;
3240        classes.push(SourceLineRange {
3241            start,
3242            end: python_block_end(source, start, source_indent(source, start), fallback),
3243        });
3244    }
3245    classes
3246}
3247
3248fn saturating_u32(value: usize) -> u32 {
3249    u32::try_from(value).unwrap_or(u32::MAX)
3250}
3251
3252fn finish(mut observations: Vec<SourceObservation>) -> Vec<SourceObservation> {
3253    for observation in &mut observations {
3254        observation.warnings.sort();
3255        observation.warnings.dedup();
3256    }
3257    observations.sort_by(compare_observations);
3258    observations.dedup();
3259    observations
3260}
3261
3262fn compare_observations(left: &SourceObservation, right: &SourceObservation) -> Ordering {
3263    (
3264        left.lines,
3265        left.language,
3266        left.framework,
3267        left.role,
3268        &left.method,
3269        &left.path,
3270        &left.symbol_name,
3271        &left.related_symbol,
3272        &left.related_path,
3273        left.status,
3274        &left.warnings,
3275    )
3276        .cmp(&(
3277            right.lines,
3278            right.language,
3279            right.framework,
3280            right.role,
3281            &right.method,
3282            &right.path,
3283            &right.symbol_name,
3284            &right.related_symbol,
3285            &right.related_path,
3286            right.status,
3287            &right.warnings,
3288        ))
3289        .then_with(|| {
3290            (
3291                &left.authority,
3292                &left.router,
3293                &left.mount_parent,
3294                &left.url,
3295                &left.call,
3296            )
3297                .cmp(&(
3298                    &right.authority,
3299                    &right.router,
3300                    &right.mount_parent,
3301                    &right.url,
3302                    &right.call,
3303                ))
3304        })
3305}
3306
3307#[cfg(test)]
3308mod tests {
3309    use super::{
3310        SourceEpistemicStatus, SourceFramework, SourceObservation, SourceRole, SourceWarning, SymbolRef, UrlPart, parse_python_source
3311    };
3312
3313    /// HTTP, route, and test facts without call observations.
3314    fn parse_rust_source(source: &str) -> Vec<SourceObservation> {
3315        super::parse_rust_source(source)
3316            .into_iter()
3317            .filter(|item| item.role != SourceRole::Call)
3318            .collect()
3319    }
3320
3321    #[test]
3322    fn rust_reqwest_urls_should_resolve_constants_format_strings_and_wrapper_parameters() {
3323        let source = r#"
3324use reqwest::Client;
3325const BASE: &str = "http://orders:8080";
3326async fn get_order(client: &Client, id: u64) {
3327    client.get(format!("{BASE}/orders/{id}")).send().await;
3328}
3329async fn post_json(client: &Client, path: &str) {
3330    client.post(format!("{}{}", BASE, path)).send().await;
3331}
3332async fn refund(client: &Client, id: &str) {
3333    post_json(client, &format!("/orders/{id}/refunds")).await;
3334}
3335"#;
3336        let result = super::parse_rust_source(source);
3337        let consumers = result
3338            .iter()
3339            .filter(|item| item.role == SourceRole::Consumer)
3340            .map(|item| {
3341                (
3342                    item.symbol_name.as_deref(),
3343                    item.path.as_deref(),
3344                    item.url.is_some(),
3345                )
3346            })
3347            .collect::<Vec<_>>();
3348        let calls = result
3349            .iter()
3350            .filter_map(|item| item.call.as_ref())
3351            .map(|call| (call.callee.clone(), call.arguments.len()))
3352            .collect::<Vec<_>>();
3353
3354        assert_eq!(
3355            consumers,
3356            [
3357                (Some("get_order"), Some("/orders/{id}"), true),
3358                (Some("post_json"), None, true),
3359            ]
3360        );
3361        assert_eq!(calls, [(SymbolRef::Call("post_json".to_owned()), 2)]);
3362    }
3363
3364    #[test]
3365    fn axum_should_extract_multiline_route_and_handler() {
3366        let source = r#"
3367use axum::{Router, routing::post};
3368fn router() {
3369    Router::new().route(
3370        "/api//orders/",
3371        post(create_order),
3372    );
3373}
3374"#;
3375        let result = parse_rust_source(source);
3376
3377        assert!(matches!(
3378            result.as_slice(),
3379            [item]
3380                if item.framework == SourceFramework::Axum
3381                    && item.role == SourceRole::Provider
3382                    && item.method.as_deref() == Some("POST")
3383                    && item.path.as_deref() == Some("/api/orders")
3384                    && item.symbol_name.as_deref() == Some("create_order")
3385                    && item.lines.start == 4
3386                    && item.lines.end == 7
3387        ));
3388    }
3389
3390    #[test]
3391    fn actix_attributes_should_extract_direct_and_route_methods() {
3392        let source = r#"
3393use actix_web::{get, route};
3394#[get("/health")]
3395async fn health() {}
3396#[route(
3397    "/orders",
3398    method = "POST",
3399)]
3400async fn create() {}
3401"#;
3402        let result = parse_rust_source(source);
3403
3404        assert_eq!(
3405            result
3406                .iter()
3407                .map(|item| (item.method.as_deref(), item.path.as_deref()))
3408                .collect::<Vec<_>>(),
3409            vec![
3410                (Some("GET"), Some("/health")),
3411                (Some("POST"), Some("/orders"))
3412            ]
3413        );
3414    }
3415
3416    #[test]
3417    fn actix_builder_should_require_web_route_evidence() {
3418        let source = r#"
3419use actix_web::{web, App};
3420fn app() {
3421    App::new().route("/users", web::put().to(update_user));
3422    App::new().service(
3423        web::resource("/orders").route(web::post().to(create_order)),
3424    );
3425}
3426"#;
3427        let result = parse_rust_source(source);
3428
3429        assert_eq!(
3430            result
3431                .iter()
3432                .filter(|item| item.role == SourceRole::Provider)
3433                .map(|item| (
3434                    item.framework,
3435                    item.method.as_deref(),
3436                    item.symbol_name.as_deref()
3437                ))
3438                .collect::<Vec<_>>(),
3439            vec![
3440                (SourceFramework::ActixWeb, Some("PUT"), Some("update_user")),
3441                (
3442                    SourceFramework::ActixWeb,
3443                    Some("POST"),
3444                    Some("create_order")
3445                ),
3446            ]
3447        );
3448    }
3449
3450    #[test]
3451    fn utoipa_should_extract_explicit_and_contextual_actix_paths() {
3452        let source = r#"
3453use actix_web::{get, post};
3454
3455#[cfg_attr(feature = "openapi", utoipa::path(post, path = "/api/orders"))]
3456#[post("/orders")]
3457async fn create_order() {}
3458
3459#[cfg_attr(feature = "openapi", utoipa::path(
3460    get,
3461    context_path = "/api/users"
3462))]
3463#[get("/{id}")]
3464async fn get_user() {}
3465"#;
3466        let result = parse_rust_source(source);
3467
3468        assert!(result.iter().any(|item| {
3469            item.framework == SourceFramework::Utoipa
3470                && item.symbol_name.as_deref() == Some("create_order")
3471                && item.method.as_deref() == Some("POST")
3472                && item.path.as_deref() == Some("/api/orders")
3473        }));
3474        assert!(result.iter().any(|item| {
3475            item.framework == SourceFramework::Utoipa
3476                && item.symbol_name.as_deref() == Some("get_user")
3477                && item.method.as_deref() == Some("GET")
3478                && item.path.as_deref() == Some("/api/users/{id}")
3479        }));
3480        assert!(result.iter().any(|item| {
3481            item.framework == SourceFramework::ActixWeb
3482                && item.symbol_name.as_deref() == Some("create_order")
3483                && item.path.as_deref() == Some("/orders")
3484                && (item.confidence - 1.0).abs() < f32::EPSILON
3485        }));
3486        assert!(result.iter().any(|item| {
3487            item.framework == SourceFramework::Utoipa
3488                && item.symbol_name.as_deref() == Some("create_order")
3489                && (item.confidence - 0.75).abs() < f32::EPSILON
3490                && item.warnings.contains(&SourceWarning::AdvisoryDeclaration)
3491        }));
3492    }
3493
3494    #[test]
3495    fn reqwest_should_extract_convenience_client_and_request_calls() {
3496        let source = r#"
3497use reqwest::{Client, Method};
3498async fn send() {
3499    reqwest::get("https://example.test/health?full=1").await;
3500    reqwest::blocking::get("https://example.test/ready");
3501    let client = Client::new();
3502    client.post("/orders").send().await;
3503    client.request(Method::DELETE, "https://example.test/orders/7").send().await;
3504}
3505"#;
3506        let result = parse_rust_source(source);
3507
3508        assert_eq!(
3509            result
3510                .iter()
3511                .map(|item| (item.method.as_deref(), item.path.as_deref()))
3512                .collect::<Vec<_>>(),
3513            vec![
3514                (Some("GET"), Some("/health")),
3515                (Some("GET"), Some("/ready")),
3516                (Some("POST"), Some("/orders")),
3517                (Some("DELETE"), Some("/orders/7")),
3518            ]
3519        );
3520    }
3521
3522    #[test]
3523    fn reqwest_should_recognize_injected_client_parameters() {
3524        let source = r#"
3525use reqwest::Client;
3526async fn synchronize(client: &Client, qualified: &reqwest::Client) {
3527    client.post("https://orders.test/v1/orders").send().await;
3528    qualified.get("https://payments.test/v1/payments").send().await;
3529}
3530"#;
3531        let result = parse_rust_source(source);
3532
3533        assert_eq!(
3534            result
3535                .iter()
3536                .map(|item| (item.method.as_deref(), item.path.as_deref()))
3537                .collect::<Vec<_>>(),
3538            vec![
3539                (Some("POST"), Some("/v1/orders")),
3540                (Some("GET"), Some("/v1/payments")),
3541            ]
3542        );
3543    }
3544
3545    #[test]
3546    fn reqwest_should_preserve_explicit_lifetimes_in_client_parameters() {
3547        let source = r#"
3548use reqwest::Client;
3549async fn synchronize<'request>(client: &'request Client) {
3550    client.post("https://orders.test/v1/orders").send().await;
3551}
3552"#;
3553        let result = parse_rust_source(source);
3554
3555        assert!(result.iter().any(|item| {
3556            item.framework == SourceFramework::Reqwest
3557                && item.method.as_deref() == Some("POST")
3558                && item.path.as_deref() == Some("/v1/orders")
3559        }));
3560    }
3561
3562    #[test]
3563    fn absolute_consumer_url_should_record_its_authority() {
3564        let source = r#"
3565use reqwest::Client;
3566async fn synchronize(client: &Client) {
3567    client.get("https://User@Third-Party.example:8443/health?probe=1").send().await;
3568    client.get("/internal-health").send().await;
3569}
3570"#;
3571        let result = parse_rust_source(source);
3572        let external = result
3573            .iter()
3574            .find(|item| item.path.as_deref() == Some("/health"))
3575            .expect("absolute call");
3576        let internal = result
3577            .iter()
3578            .find(|item| item.path.as_deref() == Some("/internal-health"))
3579            .expect("relative call");
3580
3581        assert_eq!(external.status, SourceEpistemicStatus::Confirmed);
3582        assert_eq!(
3583            external.authority.as_deref(),
3584            Some("third-party.example:8443")
3585        );
3586        assert_eq!(external.warnings, []);
3587        assert_eq!(internal.status, SourceEpistemicStatus::Confirmed);
3588        assert_eq!(internal.authority, None);
3589    }
3590
3591    #[test]
3592    fn reqwest_should_recognize_builder_chains_and_typed_self_fields() {
3593        let source = r#"
3594use reqwest::Client;
3595use std::time::Duration;
3596
3597struct Api {
3598    client: Client,
3599}
3600
3601impl Api {
3602    fn new() -> Self {
3603        let client = Client::builder()
3604            .timeout(Duration::from_secs(5))
3605            .build()
3606            .expect("valid client configuration");
3607        Self { client }
3608    }
3609
3610    async fn synchronize(&self) {
3611        self.client.get("https://inventory.test/v1/inventory").send().await;
3612    }
3613}
3614"#;
3615        let result = parse_rust_source(source);
3616
3617        assert!(matches!(
3618            result.as_slice(),
3619            [observation]
3620                if observation.method.as_deref() == Some("GET")
3621                    && observation.path.as_deref() == Some("/v1/inventory")
3622        ));
3623    }
3624
3625    #[test]
3626    fn unrelated_grouped_import_should_not_promote_client_to_reqwest() {
3627        let source = r#"
3628use my_http::{reqwest, Client};
3629async fn diagnostic() {
3630    let client = Client::new();
3631    client.get("https://inventory.test/v1/diagnostic");
3632}
3633"#;
3634        let result = parse_rust_source(source);
3635
3636        assert_eq!(result.len(), 0);
3637    }
3638
3639    #[test]
3640    fn reqwest_should_not_reuse_receiver_names_across_functions() {
3641        let source = r#"
3642use reqwest::Client;
3643struct FakeClient;
3644impl FakeClient { fn get(&self, _path: &str) {} }
3645fn local_only(client: &FakeClient) {
3646    client.get("https://inventory.test/v1/diagnostic");
3647}
3648async fn remote() {
3649    let client = Client::new();
3650    client.get("https://inventory.test/v1/inventory").send().await;
3651}
3652"#;
3653        let result = parse_rust_source(source);
3654
3655        assert_eq!(result.len(), 1);
3656        assert_eq!(result[0].path.as_deref(), Some("/v1/inventory"));
3657    }
3658
3659    #[test]
3660    fn reqwest_import_should_not_leak_across_inline_modules() {
3661        let source = r#"
3662mod real { use reqwest::Client; }
3663mod fake {
3664    struct Client;
3665    impl Client { fn get(&self, _path: &str) {} }
3666    fn probe(client: &Client) { client.get("/health"); }
3667}
3668"#;
3669
3670        assert_eq!(parse_rust_source(source), []);
3671    }
3672
3673    #[test]
3674    fn top_level_reqwest_import_should_survive_an_inline_test_module() {
3675        let source = r#"
3676use reqwest::Client;
3677async fn probe() {
3678    let client = Client::new();
3679    client.get("/health").send().await;
3680}
3681#[cfg(test)] mod tests { fn smoke() {} }
3682"#;
3683
3684        assert!(parse_rust_source(source).iter().any(|item| {
3685            item.framework == SourceFramework::Reqwest && item.path.as_deref() == Some("/health")
3686        }));
3687    }
3688
3689    #[test]
3690    fn reqwest_import_inside_inline_module_should_remain_visible_locally() {
3691        let source = r#"
3692mod api {
3693    use reqwest::Client as HttpClient;
3694    async fn probe() {
3695        let client = HttpClient::new();
3696        client.get("/health").send().await;
3697    }
3698}
3699"#;
3700
3701        assert!(parse_rust_source(source).iter().any(|item| {
3702            item.framework == SourceFramework::Reqwest && item.path.as_deref() == Some("/health")
3703        }));
3704    }
3705
3706    #[test]
3707    fn reqwest_self_fields_should_not_leak_across_sibling_modules() {
3708        let source = r#"
3709mod real {
3710    use reqwest::Client;
3711    struct Api { client: Client }
3712    impl Api {
3713        async fn probe(&self) { self.client.get("/real").send().await; }
3714    }
3715}
3716mod fake {
3717    struct Client;
3718    impl Client { fn get(&self, _path: &str) {} }
3719    struct Api { client: Client }
3720    impl Api {
3721        fn probe(&self) { self.client.get("/fake"); }
3722    }
3723}
3724"#;
3725
3726        let result = parse_rust_source(source);
3727        assert_eq!(result.len(), 1);
3728        assert_eq!(result[0].path.as_deref(), Some("/real"));
3729    }
3730
3731    #[test]
3732    fn reqwest_should_respect_lexical_shadowing() {
3733        let source = r#"
3734use reqwest::Client;
3735struct FakeClient;
3736impl FakeClient { fn get(&self, _path: &str) {} }
3737async fn synchronize() {
3738    let client = Client::new();
3739    client.get("https://inventory.test/v1/inventory").send().await;
3740    {
3741        let client = FakeClient;
3742        client.get("https://inventory.test/v1/diagnostic");
3743    }
3744    client.get("https://payments.test/v1/payments").send().await;
3745}
3746"#;
3747        let result = parse_rust_source(source);
3748
3749        assert_eq!(
3750            result
3751                .iter()
3752                .map(|item| item.path.as_deref())
3753                .collect::<Vec<_>>(),
3754            vec![Some("/v1/inventory"), Some("/v1/payments")]
3755        );
3756    }
3757
3758    #[test]
3759    fn reqwest_should_not_promote_wrappers_that_consume_a_client() {
3760        let source = r#"
3761use reqwest::Client;
3762struct FakeClient;
3763impl FakeClient {
3764    fn new(_client: Client) -> Self { Self }
3765    fn get(&self, _path: &str) {}
3766}
3767async fn diagnostic() {
3768    let fake = FakeClient::new(Client::new());
3769    fake.get("https://inventory.test/v1/diagnostic");
3770}
3771"#;
3772        let result = parse_rust_source(source);
3773
3774        assert_eq!(result.len(), 0);
3775    }
3776
3777    #[test]
3778    fn reqwest_should_recognize_import_aliases_and_exact_type_annotations() {
3779        let source = r#"
3780use reqwest::Client as HttpClient;
3781async fn synchronize(injected: &HttpClient) {
3782    let constructed: HttpClient = factory();
3783    injected.get("https://inventory.test/v1/inventory").send().await;
3784    constructed.post("https://orders.test/v1/orders").send().await;
3785}
3786"#;
3787        let result = parse_rust_source(source);
3788
3789        assert_eq!(
3790            result
3791                .iter()
3792                .map(|item| (item.method.as_deref(), item.path.as_deref()))
3793                .collect::<Vec<_>>(),
3794            vec![
3795                (Some("GET"), Some("/v1/inventory")),
3796                (Some("POST"), Some("/v1/orders")),
3797            ]
3798        );
3799    }
3800
3801    #[test]
3802    fn reqwest_should_recognize_blocking_clients_and_generic_self_fields() {
3803        let source = r#"
3804use reqwest::blocking::Client as BlockingClient;
3805use reqwest::blocking::{Client as GroupedClient, Response};
3806struct Api<T> { client: BlockingClient, marker: T }
3807impl<T> Api<T> {
3808    fn synchronize(&self) {
3809        self.client.get("https://inventory.test/v1/inventory").send();
3810    }
3811}
3812fn qualified() {
3813    let client = reqwest::blocking::Client::new();
3814    client.post("https://orders.test/v1/orders").send();
3815}
3816fn grouped() {
3817    let client = GroupedClient::new();
3818    client.delete("https://orders.test/v1/obsolete").send();
3819}
3820"#;
3821        let result = parse_rust_source(source);
3822
3823        assert_eq!(result.len(), 3);
3824        assert!(
3825            result
3826                .iter()
3827                .any(|item| item.path.as_deref() == Some("/v1/inventory"))
3828        );
3829        assert!(
3830            result
3831                .iter()
3832                .any(|item| item.path.as_deref() == Some("/v1/orders"))
3833        );
3834        assert!(
3835            result
3836                .iter()
3837                .any(|item| item.path.as_deref() == Some("/v1/obsolete"))
3838        );
3839    }
3840
3841    #[test]
3842    fn reqwest_should_recognize_exact_local_type_aliases() {
3843        let source = r#"
3844use reqwest::Client as HttpClient;
3845type ServiceClient = HttpClient;
3846async fn synchronize(client: &ServiceClient) {
3847    client.get("https://inventory.test/v1/inventory").send().await;
3848}
3849"#;
3850        let result = parse_rust_source(source);
3851
3852        assert!(matches!(
3853            result.as_slice(),
3854            [observation]
3855                if observation.method.as_deref() == Some("GET")
3856                    && observation.path.as_deref() == Some("/v1/inventory")
3857        ));
3858    }
3859
3860    #[test]
3861    fn reqwest_should_track_braced_typed_closure_parameters() {
3862        let source = r#"
3863use reqwest::Client;
3864async fn synchronize() {
3865    let operation = |client: &Client| {
3866        client.get("https://inventory.test/v1/inventory");
3867    };
3868}
3869"#;
3870        let result = parse_rust_source(source);
3871
3872        assert!(matches!(
3873            result.as_slice(),
3874            [observation] if observation.path.as_deref() == Some("/v1/inventory")
3875        ));
3876    }
3877
3878    #[test]
3879    fn reqwest_should_treat_destructuring_as_lexical_shadowing() {
3880        let source = r#"
3881use reqwest::Client;
3882struct FakeClient;
3883impl FakeClient { fn get(&self, _path: &str) {} }
3884async fn synchronize(client: &Client, pair: (FakeClient, usize)) {
3885    let (client, _value) = pair;
3886    client.get("https://inventory.test/v1/diagnostic");
3887}
3888"#;
3889        let result = parse_rust_source(source);
3890
3891        assert_eq!(result.len(), 0);
3892    }
3893
3894    #[test]
3895    fn reqwest_should_conservatively_handle_binding_reassignment() {
3896        let source = r#"
3897use reqwest::Client;
3898async fn synchronize() {
3899    let mut client = Client::new();
3900    client = factory();
3901    client.get("https://inventory.test/v1/unknown");
3902    client = Client::new();
3903    client.get("https://inventory.test/v1/inventory");
3904}
3905"#;
3906        let result = parse_rust_source(source);
3907
3908        assert_eq!(
3909            result
3910                .iter()
3911                .map(|item| item.path.as_deref())
3912                .collect::<Vec<_>>(),
3913            vec![Some("/v1/inventory")]
3914        );
3915    }
3916
3917    #[test]
3918    fn rust_test_attributes_should_cover_builtin_tokio_and_rstest() {
3919        let source = r"
3920#[test]
3921fn plain() {}
3922#[tokio::test]
3923async fn asynchronous() {}
3924#[rstest]
3925#[case(1)]
3926fn parameterized(#[case] value: u8) {}
3927";
3928        let result = parse_rust_source(source);
3929
3930        assert_eq!(
3931            result
3932                .iter()
3933                .map(|item| (item.framework, item.symbol_name.as_deref()))
3934                .collect::<Vec<_>>(),
3935            vec![
3936                (SourceFramework::RustTest, Some("plain")),
3937                (SourceFramework::TokioTest, Some("asynchronous")),
3938                (SourceFramework::Rstest, Some("parameterized")),
3939            ]
3940        );
3941    }
3942
3943    #[test]
3944    fn rust_dynamic_route_should_never_claim_exact_path() {
3945        let source = r"
3946use axum::{Router, routing::get};
3947fn router(path: &str) {
3948    Router::new().route(path, get(handler));
3949}
3950";
3951        let result = parse_rust_source(source);
3952
3953        assert!(matches!(
3954            result.as_slice(),
3955            [item]
3956                if item.path.is_none()
3957                    && item.status == SourceEpistemicStatus::Ambiguous
3958                    && item.warnings == [SourceWarning::DynamicPath]
3959        ));
3960    }
3961
3962    #[test]
3963    fn rust_comments_strings_and_unrelated_route_methods_should_be_ignored() {
3964        let source = r##"
3965// use axum; Router::new().route("/fake", get(fake));
3966const TEXT: &str = r#"reqwest::get("https://example.test/fake")"#;
3967struct Router;
3968impl Router {
3969    fn route(&self, path: &str, handler: usize) {}
3970}
3971fn ordinary() {
3972    Router.route("/fake", handler);
3973}
3974"##;
3975        let result = parse_rust_source(source);
3976
3977        assert_eq!(result, Vec::new());
3978    }
3979
3980    #[test]
3981    fn fastapi_should_extract_method_and_api_route_decorators() {
3982        let source = r#"
3983from fastapi import FastAPI
3984app = FastAPI()
3985@app.get("/users/{user_id}")
3986async def get_user(user_id: str):
3987    pass
3988@app.api_route(
3989    "/orders",
3990    methods=["POST", "PUT"],
3991)
3992def orders():
3993    pass
3994"#;
3995        let result = parse_python_source(source);
3996
3997        assert_eq!(
3998            result
3999                .iter()
4000                .filter(|item| item.role == SourceRole::Provider)
4001                .map(|item| (item.method.as_deref(), item.path.as_deref()))
4002                .collect::<Vec<_>>(),
4003            vec![
4004                (Some("GET"), Some("/users/{user_id}")),
4005                (Some("POST"), Some("/orders")),
4006                (Some("PUT"), Some("/orders")),
4007            ]
4008        );
4009    }
4010
4011    #[test]
4012    fn fastapi_should_compose_static_router_prefixes() {
4013        let source = r#"
4014from fastapi import APIRouter
4015router = APIRouter(prefix="/api/v1/projects")
4016
4017@router.get("/{project_id}")
4018async def get_project(project_id: int):
4019    pass
4020"#;
4021        let result = parse_python_source(source);
4022
4023        assert!(result.iter().any(|item| {
4024            item.framework == SourceFramework::FastApi
4025                && item.method.as_deref() == Some("GET")
4026                && item.path.as_deref() == Some("/api/v1/projects/{project_id}")
4027                && item.symbol_name.as_deref() == Some("get_project")
4028        }));
4029    }
4030
4031    #[test]
4032    fn flask_should_extract_default_and_explicit_methods() {
4033        let source = r#"
4034from flask import Flask
4035app = Flask(__name__)
4036@app.route("/health")
4037def health():
4038    pass
4039@app.route(
4040    "/orders",
4041    methods=["POST", "DELETE"],
4042)
4043def orders():
4044    pass
4045"#;
4046        let result = parse_python_source(source);
4047
4048        assert_eq!(
4049            result
4050                .iter()
4051                .filter(|item| item.role == SourceRole::Provider)
4052                .map(|item| item.method.as_deref())
4053                .collect::<Vec<_>>(),
4054            vec![Some("GET"), Some("DELETE"), Some("POST")]
4055        );
4056    }
4057
4058    #[test]
4059    fn flask_should_resolve_instance_app_and_static_path_concatenation() {
4060        let source = r#"
4061from flask import Flask
4062URL = "/servers/remitee"
4063
4064class Remitee:
4065    def __init__(self):
4066        self.app = Flask(__name__)
4067
4068    def setup_routes(self):
4069        @self.app.route(URL + "/api/Payments/<payment_id>", methods=["GET"])
4070        def payment(payment_id):
4071            pass
4072"#;
4073        let result = parse_python_source(source);
4074
4075        assert!(result.iter().any(|item| {
4076            item.framework == SourceFramework::Flask
4077                && item.role == SourceRole::Provider
4078                && item.method.as_deref() == Some("GET")
4079                && item.path.as_deref() == Some("/servers/remitee/api/Payments/<payment_id>")
4080        }));
4081    }
4082
4083    #[test]
4084    fn python_http_registry_should_flatten_nested_static_operations() {
4085        let source = r#"
4086METHODS = {
4087    "public": ("/api/v1", {
4088        "accounts": ("/accounts", {
4089            "get_accounts": ["GET", ""],
4090            "get_account": ["GET", "/{{accounts_id}}"],
4091        }),
4092    }),
4093}
4094"#;
4095        let result = parse_python_source(source);
4096        let operations = result
4097            .iter()
4098            .filter(|item| item.framework == SourceFramework::PythonHttpRegistry)
4099            .map(|item| (item.method.as_deref(), item.path.as_deref()))
4100            .collect::<Vec<_>>();
4101
4102        assert_eq!(
4103            operations,
4104            vec![
4105                (Some("GET"), Some("/api/v1/accounts")),
4106                (Some("GET"), Some("/api/v1/accounts/{accounts_id}")),
4107            ]
4108        );
4109    }
4110
4111    #[test]
4112    fn factory_boy_should_link_factory_to_imported_model() {
4113        let source = r"
4114import factory
4115from src.clases.Account import Account
4116
4117class AccountFactory(factory.Factory):
4118    class Meta:
4119        model = Account
4120";
4121        let result = parse_python_source(source);
4122
4123        assert!(result.iter().any(|item| {
4124            item.framework == SourceFramework::FactoryBoy
4125                && item.role == SourceRole::Factory
4126                && item.symbol_name.as_deref() == Some("AccountFactory")
4127                && item.related_symbol.as_deref() == Some("Account")
4128                && item.related_path.as_deref() == Some("src/clases/Account.py")
4129                && item.status == SourceEpistemicStatus::Confirmed
4130        }));
4131    }
4132
4133    #[test]
4134    fn requests_should_extract_module_alias_and_session_calls() {
4135        let source = r#"
4136import requests as rq
4137from requests import Session, post as create
4138def send():
4139    rq.get("https://example.test/status")
4140    create("/orders")
4141    session = Session()
4142    session.request("PATCH", "/orders/4")
4143"#;
4144        let result = parse_python_source(source);
4145
4146        assert_eq!(
4147            result
4148                .iter()
4149                .map(|item| (item.framework, item.method.as_deref(), item.path.as_deref()))
4150                .collect::<Vec<_>>(),
4151            vec![
4152                (SourceFramework::Requests, Some("GET"), Some("/status")),
4153                (SourceFramework::Requests, Some("POST"), Some("/orders")),
4154                (SourceFramework::Requests, Some("PATCH"), Some("/orders/4")),
4155            ]
4156        );
4157    }
4158
4159    #[test]
4160    fn aiohttp_should_extract_client_session_context_calls() {
4161        let source = r#"
4162from aiohttp import ClientSession
4163
4164async def load():
4165    async with ClientSession() as session:
4166        await session.get("/accounts")
4167"#;
4168        let result = parse_python_source(source);
4169
4170        assert!(result.iter().any(|item| {
4171            item.framework == SourceFramework::AioHttp
4172                && item.role == SourceRole::Consumer
4173                && item.method.as_deref() == Some("GET")
4174                && item.path.as_deref() == Some("/accounts")
4175        }));
4176    }
4177
4178    #[test]
4179    fn httpx_should_extract_module_sync_and_async_clients() {
4180        let source = r#"
4181import httpx
4182from httpx import AsyncClient, patch as update
4183def direct():
4184    httpx.delete("https://example.test/items/1")
4185    update("/items/1")
4186async def clients():
4187    client = AsyncClient()
4188    client.put("/items/1")
4189"#;
4190        let result = parse_python_source(source);
4191
4192        assert_eq!(
4193            result
4194                .iter()
4195                .map(|item| (item.framework, item.method.as_deref()))
4196                .collect::<Vec<_>>(),
4197            vec![
4198                (SourceFramework::Httpx, Some("DELETE")),
4199                (SourceFramework::Httpx, Some("PATCH")),
4200                (SourceFramework::Httpx, Some("PUT")),
4201            ]
4202        );
4203    }
4204
4205    #[test]
4206    fn python_tests_should_distinguish_pytest_and_unittest() {
4207        let source = r"
4208import unittest
4209def test_pytest_case():
4210    pass
4211class ApiTests(unittest.TestCase):
4212    def test_unittest_case(self):
4213        pass
4214";
4215        let result = parse_python_source(source);
4216
4217        assert_eq!(
4218            result
4219                .iter()
4220                .map(|item| (item.framework, item.symbol_name.as_deref()))
4221                .collect::<Vec<_>>(),
4222            vec![
4223                (SourceFramework::Pytest, Some("test_pytest_case")),
4224                (SourceFramework::Unittest, Some("test_unittest_case")),
4225            ]
4226        );
4227    }
4228
4229    #[test]
4230    fn indirect_python_test_class_should_preserve_generic_test_evidence() {
4231        let source = r#"
4232import requests
4233
4234class PaymentCases(SharedTestBase):
4235    def test_payment(self):
4236        requests.post("/payments")
4237"#;
4238        let result = parse_python_source(source);
4239
4240        assert!(result.iter().any(|item| {
4241            item.framework == SourceFramework::PythonTest
4242                && item.role == SourceRole::Test
4243                && item.symbol_name.as_deref() == Some("test_payment")
4244        }));
4245        assert!(result.iter().any(|item| {
4246            item.framework == SourceFramework::Requests
4247                && item.role == SourceRole::Consumer
4248                && item.symbol_name.as_deref() == Some("test_payment")
4249                && item.path.as_deref() == Some("/payments")
4250        }));
4251    }
4252
4253    #[test]
4254    fn python_dynamic_url_and_method_should_remain_explicitly_incomplete() {
4255        let source = r"
4256import httpx
4257def send(method, base, path):
4258    httpx.request(method, base + path)
4259";
4260        let result = parse_python_source(source);
4261
4262        assert!(matches!(
4263            result.as_slice(),
4264            [item]
4265                if item.method.is_none()
4266                    && item.path.is_none()
4267                    && item.status == SourceEpistemicStatus::Incomplete
4268                    && item.warnings
4269                        == [SourceWarning::DynamicMethod, SourceWarning::DynamicPath]
4270        ));
4271    }
4272
4273    fn consumer_paths(source: &str) -> Vec<(Option<String>, Option<String>, bool)> {
4274        parse_python_source(source)
4275            .into_iter()
4276            .filter(|item| item.role == SourceRole::Consumer)
4277            .map(|item| (item.symbol_name, item.path, item.url.is_some()))
4278            .collect()
4279    }
4280
4281    #[test]
4282    fn python_url_expressions_should_resolve_whole_segment_values_and_scoped_names() {
4283        let source = r#"
4284import requests
4285BASE_URL = "http://orders:8080"
4286API = BASE_URL + "/api"
4287def fetch(user_id):
4288    requests.get(f"https://example.test/users/{user_id}")
4289def report(name):
4290    requests.get(f"/reports/{name}.csv")
4291def scoped(order):
4292    url = f"{API}/orders/{order.id}"
4293    requests.get(url)
4294def formatted(sku):
4295    requests.get("{}/items/{}".format(API, sku))
4296    requests.delete("/items/%s" % sku)
4297"#;
4298
4299        assert_eq!(
4300            consumer_paths(source),
4301            [
4302                (
4303                    Some("fetch".to_owned()),
4304                    Some("/users/{user_id}".to_owned()),
4305                    true
4306                ),
4307                (Some("report".to_owned()), None, true),
4308                (
4309                    Some("scoped".to_owned()),
4310                    Some("/api/orders/{id}".to_owned()),
4311                    false
4312                ),
4313                (
4314                    Some("formatted".to_owned()),
4315                    Some("/api/items/{sku}".to_owned()),
4316                    true
4317                ),
4318                (
4319                    Some("formatted".to_owned()),
4320                    Some("/items/{sku}".to_owned()),
4321                    true
4322                ),
4323            ]
4324        );
4325    }
4326
4327    #[test]
4328    fn python_test_clients_should_be_recognized_and_parameter_clients_left_for_composition() {
4329        let source = r#"
4330import httpx
4331import pytest
4332from fastapi.testclient import TestClient
4333from app import app, flask_app
4334
4335client = TestClient(app)
4336
4337def test_direct():
4338    client.get("/items")
4339
4340class OrdersTest(unittest.TestCase):
4341    def setUp(self):
4342        self.web = flask_app.test_client()
4343
4344    def test_flask(self):
4345        self.web.post("/orders")
4346
4347async def test_async():
4348    async with httpx.AsyncClient(app=app, base_url="http://test") as api:
4349        await api.delete("/orders/1")
4350
4351@pytest.fixture
4352def api_client():
4353    return TestClient(app)
4354
4355def test_injected(api_client):
4356    api_client.put("/orders/2")
4357"#;
4358        let result = parse_python_source(source);
4359        let consumers = result
4360            .iter()
4361            .filter(|item| item.role == SourceRole::Consumer)
4362            .map(|item| {
4363                (
4364                    item.framework,
4365                    item.method.clone().unwrap_or_default(),
4366                    item.path.clone().unwrap_or_default(),
4367                    item.status,
4368                    item.router.clone(),
4369                )
4370            })
4371            .collect::<Vec<_>>();
4372        let clients = result
4373            .iter()
4374            .filter(|item| item.role == SourceRole::Client)
4375            .map(|item| (item.framework, item.symbol_name.clone().unwrap_or_default()))
4376            .collect::<Vec<_>>();
4377
4378        assert_eq!(
4379            consumers,
4380            [
4381                (
4382                    SourceFramework::TestClient,
4383                    "GET".to_owned(),
4384                    "/items".to_owned(),
4385                    SourceEpistemicStatus::Confirmed,
4386                    None
4387                ),
4388                (
4389                    SourceFramework::FlaskTestClient,
4390                    "POST".to_owned(),
4391                    "/orders".to_owned(),
4392                    SourceEpistemicStatus::Confirmed,
4393                    None
4394                ),
4395                (
4396                    SourceFramework::TestClient,
4397                    "DELETE".to_owned(),
4398                    "/orders/1".to_owned(),
4399                    SourceEpistemicStatus::Confirmed,
4400                    None
4401                ),
4402                (
4403                    SourceFramework::TestClient,
4404                    "PUT".to_owned(),
4405                    "/orders/2".to_owned(),
4406                    SourceEpistemicStatus::Ambiguous,
4407                    Some(SymbolRef::Parameter {
4408                        name: "api_client".to_owned(),
4409                        index: 0
4410                    })
4411                ),
4412            ]
4413        );
4414        assert_eq!(
4415            clients,
4416            [(SourceFramework::TestClient, "api_client".to_owned())]
4417        );
4418    }
4419
4420    #[test]
4421    fn python_imperative_routes_should_name_their_handlers() {
4422        let source = r#"
4423from fastapi import APIRouter
4424from flask import Flask
4425from orders import views
4426
4427router = APIRouter()
4428router.add_api_route("/orders", views.list_orders, methods=["GET", "POST"])
4429router.add_api_route(path="/health", endpoint=health)
4430app = Flask(__name__)
4431app.add_url_rule("/legacy/<int:id>", "legacy", views.legacy)
4432"#;
4433        let providers = parse_python_source(source)
4434            .into_iter()
4435            .filter(|item| item.role == SourceRole::Provider)
4436            .map(|item| {
4437                format!(
4438                    "{} {} -> {}",
4439                    item.method.unwrap_or_default(),
4440                    item.path.unwrap_or_default(),
4441                    item.symbol_name.unwrap_or_default()
4442                )
4443            })
4444            .collect::<Vec<_>>();
4445
4446        assert_eq!(
4447            providers,
4448            [
4449                "GET /orders -> views.list_orders",
4450                "POST /orders -> views.list_orders",
4451                "GET /health -> health",
4452                "GET /legacy/<int:id> -> views.legacy",
4453            ]
4454        );
4455    }
4456
4457    #[test]
4458    fn rust_test_requests_should_be_recognized_for_axum_oneshot_and_actix() {
4459        let source = r#"
4460use axum::http::{Method, Request};
4461use tower::ServiceExt;
4462
4463#[tokio::test]
4464async fn creates_order() {
4465    let request = Request::builder()
4466        .method(Method::POST)
4467        .uri("/orders")
4468        .body(Body::empty())
4469        .unwrap();
4470    app().oneshot(request).await.unwrap();
4471}
4472
4473#[actix_web::test]
4474async fn reads_order() {
4475    let id = 42;
4476    let request = test::TestRequest::get().uri(&format!("/orders/{}", id)).to_request();
4477}
4478"#;
4479        let facts = parse_rust_source(source)
4480            .into_iter()
4481            .map(|item| {
4482                format!(
4483                    "{:?} {:?} {} {} {}",
4484                    item.role,
4485                    item.framework,
4486                    item.symbol_name.unwrap_or_default(),
4487                    item.method.unwrap_or_default(),
4488                    item.path.unwrap_or_default()
4489                )
4490            })
4491            .filter(|fact| !fact.starts_with("Call"))
4492            .collect::<Vec<_>>();
4493
4494        assert_eq!(
4495            facts,
4496            [
4497                "Test TokioTest creates_order  ",
4498                "Consumer AxumOneshot creates_order POST /orders",
4499                "Test RustTest reads_order  ",
4500                "Consumer ActixTest reads_order GET /orders/{value}",
4501            ]
4502        );
4503    }
4504
4505    #[test]
4506    fn python_wrappers_calls_and_fixture_requests_should_be_recorded() {
4507        let source = r#"
4508import pytest
4509import requests
4510from tests.helpers import create_order
4511
4512def get_json(path):
4513    return requests.get(BASE + path)
4514
4515@pytest.fixture
4516def order(client):
4517    return create_order(client, "/orders")
4518
4519def test_reads_order(order, api):
4520    api.read_order(order)
4521    get_json("/orders/7")
4522"#;
4523        let result = parse_python_source(source);
4524        let calls = result
4525            .iter()
4526            .filter_map(|item| {
4527                let call = item.call.as_ref()?;
4528                Some((
4529                    item.symbol_name.clone()?,
4530                    call.callee.clone(),
4531                    call.arguments
4532                        .iter()
4533                        .filter_map(|argument| argument.value.as_ref()?.client_literal())
4534                        .collect::<Vec<_>>(),
4535                ))
4536            })
4537            .collect::<Vec<_>>();
4538        let wrapper = result
4539            .iter()
4540            .find(|item| item.role == SourceRole::Consumer)
4541            .and_then(|item| item.url.clone());
4542
4543        assert_eq!(
4544            wrapper.map(|url| url.parts),
4545            Some(vec![
4546                UrlPart::Value(Some("BASE".to_owned())),
4547                UrlPart::Parameter {
4548                    name: "path".to_owned(),
4549                    index: 0
4550                },
4551            ])
4552        );
4553        assert_eq!(
4554            calls,
4555            [
4556                (
4557                    "order".to_owned(),
4558                    SymbolRef::Fixture("client".to_owned()),
4559                    vec![]
4560                ),
4561                (
4562                    "order".to_owned(),
4563                    SymbolRef::Import {
4564                        module: "tests.helpers".to_owned(),
4565                        name: "create_order".to_owned()
4566                    },
4567                    vec!["/orders".to_owned()]
4568                ),
4569                (
4570                    "test_reads_order".to_owned(),
4571                    SymbolRef::Fixture("api".to_owned()),
4572                    vec![]
4573                ),
4574                (
4575                    "test_reads_order".to_owned(),
4576                    SymbolRef::Fixture("order".to_owned()),
4577                    vec![]
4578                ),
4579                (
4580                    "test_reads_order".to_owned(),
4581                    SymbolRef::Call("api.read_order".to_owned()),
4582                    vec![]
4583                ),
4584                (
4585                    "test_reads_order".to_owned(),
4586                    SymbolRef::Local("get_json".to_owned()),
4587                    vec!["/orders/7".to_owned()]
4588                ),
4589            ]
4590        );
4591    }
4592
4593    #[test]
4594    fn python_comments_docstrings_and_unknown_clients_should_be_ignored() {
4595        let source = r#"
4596"""@app.get("/fake")
4597def test_fake(): pass
4598requests.get("https://example.test/fake")
4599"""
4600# import requests
4601# requests.post("/fake")
4602class Client:
4603    def get(self, path):
4604        pass
4605client = Client()
4606client.get("/not-httpx")
4607"#;
4608        let result = parse_python_source(source);
4609
4610        assert_eq!(result, Vec::new());
4611    }
4612
4613    #[test]
4614    fn ordering_should_be_source_stable_and_independent_of_method_list_order() {
4615        let source = r#"
4616from fastapi import FastAPI
4617app = FastAPI()
4618@app.api_route("/z", methods=["PUT", "GET", "POST"])
4619def endpoint():
4620    pass
4621"#;
4622        let first = parse_python_source(source);
4623        let second = parse_python_source(source);
4624
4625        assert_eq!(
4626            (
4627                first
4628                    .iter()
4629                    .map(|item| item.method.as_deref())
4630                    .collect::<Vec<_>>(),
4631                &first
4632            ),
4633            ((vec![Some("GET"), Some("POST"), Some("PUT")]), &second)
4634        );
4635    }
4636}