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::{ExtractionLimitExceeded, ExtractionTracker};
14
15mod rust_bindings;
16
17const HTTP_METHODS: [&str; 8] = [
18    "DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT", "TRACE",
19];
20
21/// Source language understood by the focused parsers.
22#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
23#[serde(rename_all = "snake_case")]
24pub enum SourceLanguage {
25    /// JavaScript source.
26    JavaScript,
27    /// TypeScript source.
28    TypeScript,
29    /// Rust source.
30    Rust,
31    /// Python source.
32    Python,
33    /// Go source.
34    Go,
35    /// Java source.
36    Java,
37}
38
39/// Framework whose syntax supplied the direct evidence.
40#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
41#[serde(rename_all = "snake_case")]
42pub enum SourceFramework {
43    /// Browser or runtime Fetch API calls.
44    Fetch,
45    /// Axios HTTP client calls.
46    Axios,
47    /// Express route declarations.
48    Express,
49    /// Fastify route declarations.
50    Fastify,
51    /// `NestJS` controller declarations.
52    NestJs,
53    /// Next.js App Router file-route declarations.
54    NextJs,
55    /// Axum router declarations.
56    Axum,
57    /// Actix Web route declarations and route attributes.
58    ActixWeb,
59    /// Utoipa operation declarations, including Actix routes wrapped by `cfg_attr`.
60    Utoipa,
61    /// Reqwest client calls.
62    Reqwest,
63    /// Rust built-in `#[test]` functions.
64    RustTest,
65    /// Tokio `#[tokio::test]` functions.
66    TokioTest,
67    /// Rstest `#[rstest]` functions.
68    Rstest,
69    /// `FastAPI` route decorators.
70    FastApi,
71    /// Flask route decorators.
72    Flask,
73    /// Python requests calls.
74    Requests,
75    /// Python HTTPX calls.
76    Httpx,
77    /// Python aiohttp client-session calls.
78    AioHttp,
79    /// Statically declared Python HTTP method/path registries.
80    PythonHttpRegistry,
81    /// Factory Boy model and sub-factory declarations.
82    FactoryBoy,
83    /// Pytest test functions.
84    Pytest,
85    /// unittest `TestCase` methods.
86    Unittest,
87    /// Canonical `test_` methods in a Python class whose runner inheritance is resolved elsewhere.
88    PythonTest,
89    /// Go standard-library `net/http`.
90    GoNetHttp,
91    /// Gin route declarations.
92    Gin,
93    /// Chi route declarations.
94    Chi,
95    /// Spring MVC route declarations.
96    SpringMvc,
97    /// Spring `WebClient` calls.
98    WebClient,
99    /// Feign client declarations.
100    Feign,
101}
102
103/// Repository-boundary role represented by an observation.
104#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
105#[serde(rename_all = "snake_case")]
106pub enum SourceRole {
107    /// An HTTP operation served by the repository.
108    Provider,
109    /// An HTTP operation invoked by the repository.
110    Consumer,
111    /// A declared test case.
112    Test,
113    /// A data factory with one statically declared model target.
114    Factory,
115}
116
117/// Epistemic state of a source observation.
118#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
119#[serde(rename_all = "snake_case")]
120pub enum SourceEpistemicStatus {
121    /// Method and path, when applicable, are supported by exact literal syntax.
122    Confirmed,
123    /// A relevant framework operation was found, but a dynamic expression prevents exact identity.
124    Ambiguous,
125    /// Required method, path, or symbol evidence was absent.
126    Incomplete,
127}
128
129/// Inclusive one-based source range supporting an observation.
130#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
131pub struct SourceLineRange {
132    /// First line containing direct evidence.
133    pub start: u32,
134    /// Last line containing direct evidence.
135    pub end: u32,
136}
137
138/// Machine-readable limitation attached to an observation.
139#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
140#[serde(rename_all = "snake_case")]
141pub enum SourceWarning {
142    /// The HTTP method is computed rather than represented by a supported literal or method name.
143    DynamicMethod,
144    /// The URL or route path is computed rather than represented by one literal.
145    DynamicPath,
146    /// A literal URL is not an absolute URL or root-relative path.
147    UnsupportedLiteralPath,
148    /// An absolute consumer URL names an authority with no explicit workspace mapping.
149    UnmappedAuthority,
150    /// The framework declaration did not expose an implementation symbol.
151    MissingSymbol,
152    /// Tree-sitter recovered from at least one syntax error in the source artifact.
153    SyntaxErrorRecovery,
154    /// A documentation-oriented declaration may drift from executable framework registration.
155    AdvisoryDeclaration,
156}
157
158/// Conversion-ready source evidence for an HTTP boundary, implementation, or test case.
159///
160/// Confirmed provider observations have enough method, path, and symbol evidence to construct an
161/// HTTP provider plus an implementation anchor. Confirmed consumers have exact method/path
162/// evidence. Test observations intentionally omit method/path; downstream correlation can join
163/// them to consumer observations with the same `symbol_name`.
164#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
165pub struct SourceObservation {
166    /// Language in which the evidence was found.
167    pub language: SourceLanguage,
168    /// Framework whose syntax was recognized.
169    pub framework: SourceFramework,
170    /// Provider, consumer, or test role.
171    pub role: SourceRole,
172    /// Canonical upper-case HTTP method when exactly known.
173    pub method: Option<String>,
174    /// Canonical normalized HTTP path when exactly known.
175    pub path: Option<String>,
176    /// Enclosing implementation symbol or test name when known.
177    pub symbol_name: Option<String>,
178    /// Related model symbol for declarations such as Factory Boy `Meta.model`.
179    pub related_symbol: Option<String>,
180    /// Repository-relative module path that declares `related_symbol`, when statically imported.
181    pub related_path: Option<String>,
182    /// Inclusive source range containing the direct evidence.
183    pub lines: SourceLineRange,
184    /// Epistemic state of this observation.
185    pub status: SourceEpistemicStatus,
186    /// Normalized confidence in the inclusive range from zero to one.
187    pub confidence: f32,
188    /// Deterministically ordered extraction limitations.
189    pub warnings: Vec<SourceWarning>,
190}
191
192pub(crate) struct SourceObservationCollector<'a> {
193    observations: Vec<SourceObservation>,
194    tracker: Option<&'a mut ExtractionTracker>,
195    error: Option<ExtractionLimitExceeded>,
196}
197
198impl<'a> SourceObservationCollector<'a> {
199    pub(crate) fn unbounded() -> Self {
200        Self {
201            observations: Vec::new(),
202            tracker: None,
203            error: None,
204        }
205    }
206
207    pub(crate) fn bounded(tracker: &'a mut ExtractionTracker) -> Self {
208        Self {
209            observations: Vec::new(),
210            tracker: Some(tracker),
211            error: None,
212        }
213    }
214
215    pub(crate) fn push(&mut self, observation: SourceObservation) {
216        if self.error.is_some() {
217            return;
218        }
219        if let Some(tracker) = self.tracker.as_deref_mut()
220            && let Err(error) = tracker
221                .charge_observation(1)
222                .and_then(|()| charge_source_observation_values(&observation, tracker))
223        {
224            self.error = Some(error);
225            return;
226        }
227        self.observations.push(observation);
228    }
229
230    pub(crate) fn into_result(self) -> Result<Vec<SourceObservation>, ExtractionLimitExceeded> {
231        match self.error {
232            Some(error) => Err(error),
233            None => Ok(self.observations),
234        }
235    }
236
237    pub(crate) fn into_unbounded(self) -> Vec<SourceObservation> {
238        self.observations
239    }
240}
241
242pub(crate) fn charge_source_observation_values(
243    observation: &SourceObservation,
244    tracker: &mut ExtractionTracker,
245) -> Result<(), ExtractionLimitExceeded> {
246    if let Some(method) = &observation.method {
247        tracker.charge_identifier(method)?;
248    }
249    if let Some(path) = &observation.path {
250        tracker.charge_portable_path(path)?;
251    }
252    for symbol in [
253        observation.symbol_name.as_deref(),
254        observation.related_symbol.as_deref(),
255    ]
256    .into_iter()
257    .flatten()
258    {
259        tracker.charge_identifier(symbol)?;
260    }
261    if let Some(path) = &observation.related_path {
262        tracker.charge_portable_path(path)?;
263    }
264    Ok(())
265}
266
267/// Parses the mandatory focused Rust framework matrix.
268///
269/// Supported syntax comprises Axum `route` declarations, Actix Web route attributes and builder
270/// routes, Reqwest convenience/request calls, and built-in, Tokio, and rstest test attributes.
271/// The returned vector is sorted and deduplicated deterministically.
272#[must_use]
273pub fn parse_rust_source(source: &str) -> Vec<SourceObservation> {
274    let collector = collect_rust_source(source, SourceObservationCollector::unbounded());
275    finish(collector.into_unbounded())
276}
277
278fn collect_rust_source<'a>(
279    source: &str,
280    mut observations: SourceObservationCollector<'a>,
281) -> SourceObservationCollector<'a> {
282    let tokens = lex_rust(source);
283    let functions = rust_functions(&tokens);
284    parse_rust_attributes(&tokens, &mut observations);
285    if has_ident(&tokens, "axum") {
286        parse_axum_routes(&tokens, &mut observations);
287    }
288    if has_ident(&tokens, "actix_web") {
289        parse_actix_builder_routes(&tokens, &mut observations);
290    }
291    if has_ident(&tokens, "reqwest") {
292        parse_reqwest_calls(&tokens, &functions, &mut observations);
293    }
294    observations
295}
296
297/// Parses focused Rust facts while charging each attempted observation before retention.
298///
299/// # Errors
300///
301/// Returns [`ExtractionLimitExceeded`] before an observation or one of its values exceeds the
302/// effective per-artifact budget.
303pub fn parse_rust_source_with_tracker(
304    source: &str,
305    tracker: &mut ExtractionTracker,
306) -> Result<Vec<SourceObservation>, ExtractionLimitExceeded> {
307    let observations = collect_rust_source(source, SourceObservationCollector::bounded(tracker));
308    Ok(finish(observations.into_result()?))
309}
310
311/// Parses the mandatory focused Python framework matrix.
312///
313/// Supported syntax comprises `FastAPI` and Flask decorators, requests, HTTPX and aiohttp
314/// convenience/client calls, static HTTP registries, Factory Boy model declarations, pytest
315/// functions, unittest `TestCase` methods, and canonical class-level `test_` methods whose
316/// indirect runner inheritance cannot be proven in one file. Comments and string contents are
317/// lexically excluded from recognition. The returned vector is sorted and deduplicated.
318#[must_use]
319pub fn parse_python_source(source: &str) -> Vec<SourceObservation> {
320    let collector = collect_python_source(source, SourceObservationCollector::unbounded());
321    finish(collector.into_unbounded())
322}
323
324fn collect_python_source<'a>(
325    source: &str,
326    mut observations: SourceObservationCollector<'a>,
327) -> SourceObservationCollector<'a> {
328    let tokens = lex_python(source);
329    let functions = python_functions(source, &tokens);
330    let contexts = PythonContexts::discover(&tokens);
331    parse_python_routes(&tokens, &contexts, &mut observations);
332    parse_python_http_registries(&tokens, &mut observations);
333    parse_python_http_calls(&tokens, &functions, &contexts, &mut observations);
334    parse_python_factories(source, &tokens, &mut observations);
335    parse_python_tests(source, &tokens, &mut observations);
336    observations
337}
338
339/// Parses focused Python facts while charging each attempted observation before retention.
340///
341/// # Errors
342///
343/// Returns [`ExtractionLimitExceeded`] before an observation or one of its values exceeds the
344/// effective per-artifact budget.
345pub fn parse_python_source_with_tracker(
346    source: &str,
347    tracker: &mut ExtractionTracker,
348) -> Result<Vec<SourceObservation>, ExtractionLimitExceeded> {
349    let observations = collect_python_source(source, SourceObservationCollector::bounded(tracker));
350    Ok(finish(observations.into_result()?))
351}
352
353/// Normalizes a literal path using the same slash and trailing-separator rules as HTTP contracts.
354///
355/// Query strings and fragments must be removed by the caller before invoking this function.
356#[must_use]
357pub fn normalize_source_http_path(path: &str) -> String {
358    let trimmed = path.trim();
359    if trimmed.is_empty() || trimmed == "/" {
360        return "/".to_owned();
361    }
362    let mut normalized = String::with_capacity(trimmed.len() + 1);
363    if !trimmed.starts_with('/') {
364        normalized.push('/');
365    }
366    let mut previous_slash = false;
367    for character in trimmed.chars() {
368        if character == '/' {
369            if !previous_slash {
370                normalized.push('/');
371            }
372            previous_slash = true;
373        } else {
374            normalized.push(character);
375            previous_slash = false;
376        }
377    }
378    while normalized.len() > 1 && normalized.ends_with('/') {
379        normalized.pop();
380    }
381    normalized
382}
383
384#[derive(Debug, Clone, PartialEq, Eq)]
385enum TokenKind {
386    Ident(String),
387    Literal(Option<String>),
388    Punct(char),
389}
390
391#[derive(Debug, Clone, PartialEq, Eq)]
392struct Token {
393    kind: TokenKind,
394    line: u32,
395    end_line: u32,
396}
397
398impl Token {
399    fn is_ident(&self, expected: &str) -> bool {
400        matches!(&self.kind, TokenKind::Ident(value) if value == expected)
401    }
402
403    fn is_punct(&self, expected: char) -> bool {
404        self.kind == TokenKind::Punct(expected)
405    }
406
407    fn literal(&self) -> Option<&str> {
408        match &self.kind {
409            TokenKind::Literal(Some(value)) => Some(value),
410            _ => None,
411        }
412    }
413
414    fn ident(&self) -> Option<&str> {
415        match &self.kind {
416            TokenKind::Ident(value) => Some(value),
417            _ => None,
418        }
419    }
420}
421
422#[derive(Debug, Clone)]
423struct FunctionSpan {
424    name: String,
425    start_token: usize,
426    body_start_token: usize,
427    end_token: usize,
428}
429
430fn has_ident(tokens: &[Token], name: &str) -> bool {
431    tokens.iter().any(|token| token.is_ident(name))
432}
433
434fn lex_rust(source: &str) -> Vec<Token> {
435    let characters = source.chars().collect::<Vec<_>>();
436    let mut tokens = Vec::new();
437    let mut index = 0;
438    let mut line = 1_u32;
439    while index < characters.len() {
440        match characters[index] {
441            '\n' => {
442                line += 1;
443                index += 1;
444            }
445            character if character.is_whitespace() => index += 1,
446            '/' if characters.get(index + 1) == Some(&'/') => {
447                index += 2;
448                while index < characters.len() && characters[index] != '\n' {
449                    index += 1;
450                }
451            }
452            '/' if characters.get(index + 1) == Some(&'*') => {
453                index += 2;
454                let mut depth = 1_u32;
455                while index < characters.len() && depth > 0 {
456                    if characters[index] == '\n' {
457                        line += 1;
458                        index += 1;
459                    } else if characters[index] == '/' && characters.get(index + 1) == Some(&'*') {
460                        depth += 1;
461                        index += 2;
462                    } else if characters[index] == '*' && characters.get(index + 1) == Some(&'/') {
463                        depth -= 1;
464                        index += 2;
465                    } else {
466                        index += 1;
467                    }
468                }
469            }
470            'r' if rust_raw_string_start(&characters, index).is_some() => {
471                let start_line = line;
472                let (next, value) = consume_rust_raw_string(&characters, index, &mut line);
473                tokens.push(Token {
474                    kind: TokenKind::Literal(value),
475                    line: start_line,
476                    end_line: line,
477                });
478                index = next;
479            }
480            '"' => {
481                let start_line = line;
482                let (next, value) = consume_quoted(&characters, index, '"', false, &mut line);
483                tokens.push(Token {
484                    kind: TokenKind::Literal(value),
485                    line: start_line,
486                    end_line: line,
487                });
488                index = next;
489            }
490            '\'' if rust_char_literal_end(&characters, index).is_some() => {
491                let (next, _) = consume_quoted(&characters, index, '\'', false, &mut line);
492                index = next;
493            }
494            character if is_ident_start(character) => {
495                let start = index;
496                index += 1;
497                while index < characters.len() && is_ident_continue(characters[index]) {
498                    index += 1;
499                }
500                tokens.push(Token {
501                    kind: TokenKind::Ident(characters[start..index].iter().collect()),
502                    line,
503                    end_line: line,
504                });
505            }
506            character => {
507                tokens.push(Token {
508                    kind: TokenKind::Punct(character),
509                    line,
510                    end_line: line,
511                });
512                index += 1;
513            }
514        }
515    }
516    tokens
517}
518
519fn rust_char_literal_end(characters: &[char], index: usize) -> Option<usize> {
520    let value = index.checked_add(1)?;
521    let closing = if characters.get(value) == Some(&'\\') {
522        match characters.get(value + 1)? {
523            'u' if characters.get(value + 2) == Some(&'{') => {
524                (value + 3..characters.len()).find(|cursor| characters[*cursor] == '}')? + 1
525            }
526            'x' => value.checked_add(4)?,
527            _ => value.checked_add(2)?,
528        }
529    } else {
530        value.checked_add(1)?
531    };
532    (characters.get(closing) == Some(&'\'')).then_some(closing + 1)
533}
534
535fn rust_raw_string_start(characters: &[char], index: usize) -> Option<usize> {
536    let mut cursor = index + 1;
537    while characters.get(cursor) == Some(&'#') {
538        cursor += 1;
539    }
540    (characters.get(cursor) == Some(&'"')).then_some(cursor - index - 1)
541}
542
543fn consume_rust_raw_string(
544    characters: &[char],
545    index: usize,
546    line: &mut u32,
547) -> (usize, Option<String>) {
548    let hashes = rust_raw_string_start(characters, index).unwrap_or_default();
549    let content_start = index + hashes + 2;
550    let mut cursor = content_start;
551    while cursor < characters.len() {
552        if characters[cursor] == '\n' {
553            *line += 1;
554        }
555        if characters[cursor] == '"'
556            && (0..hashes).all(|offset| characters.get(cursor + 1 + offset) == Some(&'#'))
557        {
558            return (
559                cursor + hashes + 1,
560                Some(characters[content_start..cursor].iter().collect()),
561            );
562        }
563        cursor += 1;
564    }
565    (cursor, None)
566}
567
568fn lex_python(source: &str) -> Vec<Token> {
569    let characters = source.chars().collect::<Vec<_>>();
570    let mut tokens = Vec::new();
571    let mut index = 0;
572    let mut line = 1_u32;
573    while index < characters.len() {
574        match characters[index] {
575            '\n' => {
576                line += 1;
577                index += 1;
578            }
579            character if character.is_whitespace() => index += 1,
580            '#' => {
581                while index < characters.len() && characters[index] != '\n' {
582                    index += 1;
583                }
584            }
585            prefix @ ('r' | 'R' | 'u' | 'U')
586                if matches!(characters.get(index + 1), Some('"' | '\'')) =>
587            {
588                let start_line = line;
589                let quote = characters[index + 1];
590                let triple = characters.get(index + 2) == Some(&quote)
591                    && characters.get(index + 3) == Some(&quote);
592                let (next, value) =
593                    consume_quoted(&characters, index + 1, quote, triple, &mut line);
594                let _ = prefix;
595                tokens.push(Token {
596                    kind: TokenKind::Literal(value),
597                    line: start_line,
598                    end_line: line,
599                });
600                index = next;
601            }
602            quote @ ('"' | '\'') => {
603                let start_line = line;
604                let triple = characters.get(index + 1) == Some(&quote)
605                    && characters.get(index + 2) == Some(&quote);
606                let (next, value) = consume_quoted(&characters, index, quote, triple, &mut line);
607                tokens.push(Token {
608                    kind: TokenKind::Literal(value),
609                    line: start_line,
610                    end_line: line,
611                });
612                index = next;
613            }
614            character if is_ident_start(character) => {
615                let start = index;
616                index += 1;
617                while index < characters.len() && is_ident_continue(characters[index]) {
618                    index += 1;
619                }
620                tokens.push(Token {
621                    kind: TokenKind::Ident(characters[start..index].iter().collect()),
622                    line,
623                    end_line: line,
624                });
625            }
626            character => {
627                tokens.push(Token {
628                    kind: TokenKind::Punct(character),
629                    line,
630                    end_line: line,
631                });
632                index += 1;
633            }
634        }
635    }
636    tokens
637}
638
639fn consume_quoted(
640    characters: &[char],
641    index: usize,
642    quote: char,
643    triple: bool,
644    line: &mut u32,
645) -> (usize, Option<String>) {
646    let delimiter_width = if triple { 3 } else { 1 };
647    let mut cursor = index + delimiter_width;
648    let mut value = String::new();
649    let mut valid = true;
650    while cursor < characters.len() {
651        if characters[cursor] == '\n' {
652            *line += 1;
653            if !triple {
654                valid = false;
655            }
656        }
657        let closes = if triple {
658            characters.get(cursor) == Some(&quote)
659                && characters.get(cursor + 1) == Some(&quote)
660                && characters.get(cursor + 2) == Some(&quote)
661        } else {
662            characters.get(cursor) == Some(&quote)
663        };
664        if closes {
665            return (
666                cursor + delimiter_width,
667                if valid { Some(value) } else { None },
668            );
669        }
670        if characters[cursor] == '\\' && !triple {
671            let Some(escaped) = characters.get(cursor + 1).copied() else {
672                return (characters.len(), None);
673            };
674            match escaped {
675                '\\' => value.push('\\'),
676                '"' => value.push('"'),
677                '\'' => value.push('\''),
678                'n' => value.push('\n'),
679                'r' => value.push('\r'),
680                't' => value.push('\t'),
681                _ => valid = false,
682            }
683            cursor += 2;
684        } else {
685            value.push(characters[cursor]);
686            cursor += 1;
687        }
688    }
689    (cursor, None)
690}
691
692fn is_ident_start(character: char) -> bool {
693    character == '_' || character.is_alphabetic()
694}
695
696fn is_ident_continue(character: char) -> bool {
697    character == '_' || character.is_alphanumeric()
698}
699
700fn matching(tokens: &[Token], open: usize, left: char, right: char) -> Option<usize> {
701    if !tokens.get(open).is_some_and(|token| token.is_punct(left)) {
702        return None;
703    }
704    let mut depth = 0_u32;
705    for (index, token) in tokens.iter().enumerate().skip(open) {
706        if token.is_punct(left) {
707            depth += 1;
708        } else if token.is_punct(right) {
709            depth -= 1;
710            if depth == 0 {
711                return Some(index);
712            }
713        }
714    }
715    None
716}
717
718fn rust_functions(tokens: &[Token]) -> Vec<FunctionSpan> {
719    let mut functions = Vec::new();
720    for (index, token) in tokens.iter().enumerate() {
721        if !token.is_ident("fn") {
722            continue;
723        }
724        let Some(name) = tokens.get(index + 1).and_then(Token::ident) else {
725            continue;
726        };
727        let Some(open) = (index + 2..tokens.len())
728            .find(|candidate| tokens[*candidate].is_punct('{') || tokens[*candidate].is_punct(';'))
729        else {
730            continue;
731        };
732        if tokens[open].is_punct(';') {
733            continue;
734        }
735        let end = matching(tokens, open, '{', '}').unwrap_or(tokens.len().saturating_sub(1));
736        functions.push(FunctionSpan {
737            name: name.to_owned(),
738            start_token: index,
739            body_start_token: open,
740            end_token: end,
741        });
742    }
743    functions
744}
745
746fn enclosing_symbol(functions: &[FunctionSpan], token_index: usize) -> Option<String> {
747    functions
748        .iter()
749        .filter(|function| function.start_token <= token_index && token_index <= function.end_token)
750        .min_by_key(|function| function.end_token - function.start_token)
751        .map(|function| function.name.clone())
752}
753
754fn parse_rust_attributes(tokens: &[Token], observations: &mut SourceObservationCollector<'_>) {
755    let mut index = 0;
756    while index + 2 < tokens.len() {
757        if !tokens[index].is_punct('#') || !tokens[index + 1].is_punct('[') {
758            index += 1;
759            continue;
760        }
761        let Some(close) = matching(tokens, index + 1, '[', ']') else {
762            break;
763        };
764        let Some((function_index, name, signature_end)) = rust_function_after(tokens, close) else {
765            index = close + 1;
766            continue;
767        };
768        let path = attribute_path(tokens, index + 2, close);
769        let framework = match path.as_slice() {
770            [name] if name == "test" => Some(SourceFramework::RustTest),
771            [first, second] if first == "tokio" && second == "test" => {
772                Some(SourceFramework::TokioTest)
773            }
774            [name] if name == "rstest" => Some(SourceFramework::Rstest),
775            _ => None,
776        };
777        if let Some(framework) = framework {
778            observations.push(confirmed_test(
779                SourceLanguage::Rust,
780                framework,
781                name.clone(),
782                tokens[index].line,
783                tokens[signature_end].end_line,
784            ));
785        }
786        parse_utoipa_attribute(
787            tokens,
788            index,
789            close,
790            function_index,
791            signature_end,
792            &name,
793            observations,
794        );
795        if has_ident(tokens, "actix_web") {
796            parse_actix_attribute(
797                tokens,
798                index,
799                close,
800                function_index,
801                signature_end,
802                name,
803                &path,
804                observations,
805            );
806        }
807        index = close + 1;
808    }
809}
810
811fn parse_utoipa_attribute(
812    tokens: &[Token],
813    start: usize,
814    close: usize,
815    function_index: usize,
816    signature_end: usize,
817    symbol: &str,
818    observations: &mut SourceObservationCollector<'_>,
819) {
820    let Some(utoipa_index) = (start..close).find(|index| tokens[*index].is_ident("utoipa")) else {
821        return;
822    };
823    if !tokens[utoipa_index + 1..close]
824        .iter()
825        .any(|token| token.is_ident("path"))
826    {
827        return;
828    }
829    let method = tokens[utoipa_index..close]
830        .iter()
831        .filter_map(Token::ident)
832        .find_map(canonical_method)
833        .map(str::to_owned);
834    let explicit_path = parse_keyword_string_values(tokens, utoipa_index, close, "path")
835        .into_iter()
836        .next();
837    let context_path = parse_keyword_string_values(tokens, utoipa_index, close, "context_path")
838        .into_iter()
839        .next();
840    let actix = rust_actix_route_between(tokens, close.saturating_add(1), function_index);
841    let method = method.or_else(|| actix.as_ref().and_then(|(method, _)| method.clone()));
842    let path = explicit_path.or_else(|| {
843        let (context, (_, route)) = (context_path?, actix?);
844        Some(normalize_source_http_path(&format!("{context}{route}")))
845    });
846    let lines = SourceLineRange {
847        start: tokens[start].line,
848        end: tokens[signature_end].end_line,
849    };
850    let mut observation = http_from_literal(
851        SourceLanguage::Rust,
852        SourceFramework::Utoipa,
853        SourceRole::Provider,
854        method,
855        path.as_deref(),
856        Some(symbol.to_owned()),
857        lines,
858        true,
859    );
860    if observation.status == SourceEpistemicStatus::Confirmed {
861        observation.confidence = 0.75;
862        observation
863            .warnings
864            .push(SourceWarning::AdvisoryDeclaration);
865    }
866    observations.push(observation);
867}
868
869fn rust_actix_route_between(
870    tokens: &[Token],
871    start: usize,
872    end: usize,
873) -> Option<(Option<String>, String)> {
874    let mut index = start;
875    while index + 3 < end {
876        if !tokens[index].is_punct('#') || !tokens[index + 1].is_punct('[') {
877            index += 1;
878            continue;
879        }
880        let close = matching(tokens, index + 1, '[', ']')?;
881        if close > end {
882            return None;
883        }
884        let method = tokens
885            .get(index + 2)
886            .and_then(Token::ident)
887            .and_then(canonical_method)
888            .map(str::to_owned);
889        let open = (index + 2..close).find(|candidate| tokens[*candidate].is_punct('('));
890        let path = open
891            .and_then(|open| first_argument(open, close))
892            .and_then(|argument| tokens.get(argument))
893            .and_then(Token::literal)
894            .and_then(route_literal_path)?;
895        return Some((method, path));
896    }
897    None
898}
899
900fn rust_function_after(tokens: &[Token], close: usize) -> Option<(usize, String, usize)> {
901    let mut index = close + 1;
902    while index < tokens.len() && index <= close + 24 {
903        if tokens[index].is_punct('#') {
904            if tokens
905                .get(index + 1)
906                .is_some_and(|token| token.is_punct('['))
907            {
908                index = matching(tokens, index + 1, '[', ']')? + 1;
909                continue;
910            }
911            return None;
912        }
913        if tokens[index].is_ident("fn") {
914            let name = tokens.get(index + 1)?.ident()?.to_owned();
915            let end = (index + 2..tokens.len())
916                .find(|candidate| {
917                    tokens[*candidate].is_punct('{') || tokens[*candidate].is_punct(';')
918                })
919                .unwrap_or(index + 1);
920            return Some((index, name, end));
921        }
922        index += 1;
923    }
924    None
925}
926
927fn attribute_path(tokens: &[Token], start: usize, end: usize) -> Vec<String> {
928    let mut path = Vec::new();
929    let mut index = start;
930    while index < end && !tokens[index].is_punct('(') {
931        if let Some(name) = tokens[index].ident() {
932            path.push(name.to_owned());
933        }
934        index += 1;
935    }
936    path
937}
938
939#[expect(
940    clippy::too_many_arguments,
941    reason = "Attribute evidence is passed without allocation"
942)]
943fn parse_actix_attribute(
944    tokens: &[Token],
945    start: usize,
946    close: usize,
947    _function_index: usize,
948    signature_end: usize,
949    symbol: String,
950    path: &[String],
951    observations: &mut SourceObservationCollector<'_>,
952) {
953    let direct_method = match path {
954        [name] => canonical_method(name),
955        _ => None,
956    };
957    if direct_method.is_none() && path != ["route"] {
958        return;
959    }
960    let open = (start + 2..close).find(|index| tokens[*index].is_punct('('));
961    let literal = open
962        .and_then(|open| first_argument(open, close))
963        .and_then(|argument| tokens.get(argument))
964        .and_then(Token::literal);
965    let methods = direct_method
966        .into_iter()
967        .map(str::to_owned)
968        .chain(
969            parse_keyword_string_values(tokens, start, close, "method")
970                .into_iter()
971                .filter_map(|method| canonical_method(&method).map(str::to_owned)),
972        )
973        .collect::<BTreeSet<_>>();
974    if methods.is_empty() {
975        observations.push(inexact_http(
976            SourceLanguage::Rust,
977            SourceFramework::ActixWeb,
978            SourceRole::Provider,
979            None,
980            literal.and_then(route_literal_path),
981            Some(symbol),
982            SourceLineRange {
983                start: tokens[start].line,
984                end: tokens[signature_end].end_line,
985            },
986            SourceWarning::DynamicMethod,
987        ));
988        return;
989    }
990    for method in methods {
991        observations.push(http_from_literal(
992            SourceLanguage::Rust,
993            SourceFramework::ActixWeb,
994            SourceRole::Provider,
995            Some(method),
996            literal,
997            Some(symbol.clone()),
998            SourceLineRange {
999                start: tokens[start].line,
1000                end: tokens[signature_end].end_line,
1001            },
1002            true,
1003        ));
1004    }
1005}
1006
1007fn parse_axum_routes(tokens: &[Token], observations: &mut SourceObservationCollector<'_>) {
1008    for (index, token) in tokens.iter().enumerate() {
1009        if !token.is_ident("route")
1010            || !tokens
1011                .get(index.wrapping_sub(1))
1012                .is_some_and(|token| token.is_punct('.'))
1013            || !tokens
1014                .get(index + 1)
1015                .is_some_and(|token| token.is_punct('('))
1016        {
1017            continue;
1018        }
1019        let Some(close) = matching(tokens, index + 1, '(', ')') else {
1020            continue;
1021        };
1022        let arguments = top_level_arguments(tokens, index + 1, close);
1023        if arguments.len() < 2 {
1024            continue;
1025        }
1026        let literal = tokens.get(arguments[0]).and_then(Token::literal);
1027        let methods = method_calls(tokens, arguments[1], close);
1028        for (method, handler) in methods {
1029            observations.push(http_from_literal(
1030                SourceLanguage::Rust,
1031                SourceFramework::Axum,
1032                SourceRole::Provider,
1033                Some(method),
1034                literal,
1035                handler,
1036                SourceLineRange {
1037                    start: token.line,
1038                    end: tokens[close].end_line,
1039                },
1040                true,
1041            ));
1042        }
1043    }
1044}
1045
1046fn parse_actix_builder_routes(tokens: &[Token], observations: &mut SourceObservationCollector<'_>) {
1047    for (index, token) in tokens.iter().enumerate() {
1048        if !token.is_ident("route")
1049            || !tokens
1050                .get(index + 1)
1051                .is_some_and(|token| token.is_punct('('))
1052        {
1053            continue;
1054        }
1055        let Some(close) = matching(tokens, index + 1, '(', ')') else {
1056            continue;
1057        };
1058        let arguments = top_level_arguments(tokens, index + 1, close);
1059        if arguments.len() < 2 || !contains_ident(tokens, arguments[1], close, "web") {
1060            continue;
1061        }
1062        let literal = tokens.get(arguments[0]).and_then(Token::literal);
1063        for (method, handler) in method_calls(tokens, arguments[1], close) {
1064            observations.push(http_from_literal(
1065                SourceLanguage::Rust,
1066                SourceFramework::ActixWeb,
1067                SourceRole::Provider,
1068                Some(method),
1069                literal,
1070                handler,
1071                SourceLineRange {
1072                    start: token.line,
1073                    end: tokens[close].end_line,
1074                },
1075                true,
1076            ));
1077        }
1078    }
1079    for (index, token) in tokens.iter().enumerate() {
1080        if !token.is_ident("resource")
1081            || !tokens
1082                .get(index.wrapping_sub(1))
1083                .is_some_and(|token| token.is_punct(':'))
1084            || !tokens
1085                .get(index + 1)
1086                .is_some_and(|token| token.is_punct('('))
1087        {
1088            continue;
1089        }
1090        let Some(resource_close) = matching(tokens, index + 1, '(', ')') else {
1091            continue;
1092        };
1093        let end = (resource_close + 1..tokens.len())
1094            .find(|candidate| tokens[*candidate].is_punct(';'))
1095            .unwrap_or(resource_close);
1096        if !contains_ident(tokens, resource_close + 1, end, "route") {
1097            continue;
1098        }
1099        let literal = tokens.get(index + 2).and_then(Token::literal);
1100        for (method, handler) in method_calls(tokens, resource_close + 1, end) {
1101            observations.push(http_from_literal(
1102                SourceLanguage::Rust,
1103                SourceFramework::ActixWeb,
1104                SourceRole::Provider,
1105                Some(method),
1106                literal,
1107                handler,
1108                SourceLineRange {
1109                    start: token.line,
1110                    end: tokens[end].end_line,
1111                },
1112                true,
1113            ));
1114        }
1115    }
1116}
1117
1118fn parse_reqwest_calls(
1119    tokens: &[Token],
1120    functions: &[FunctionSpan],
1121    observations: &mut SourceObservationCollector<'_>,
1122) {
1123    let reqwest_receivers = rust_bindings::reqwest_receiver_tokens(tokens, functions);
1124    for index in 0..tokens.len() {
1125        let explicit = tokens[index].is_ident("reqwest")
1126            && tokens
1127                .get(index + 1)
1128                .is_some_and(|token| token.is_punct(':'))
1129            && tokens
1130                .get(index + 2)
1131                .is_some_and(|token| token.is_punct(':'));
1132        let (receiver, method_index) = if explicit {
1133            let direct = index + 3;
1134            let method_index = if tokens
1135                .get(direct)
1136                .is_some_and(|token| token.is_ident("blocking"))
1137                && tokens
1138                    .get(direct + 1)
1139                    .is_some_and(|token| token.is_punct(':'))
1140                && tokens
1141                    .get(direct + 2)
1142                    .is_some_and(|token| token.is_punct(':'))
1143            {
1144                direct + 3
1145            } else {
1146                direct
1147            };
1148            ("reqwest", method_index)
1149        } else if let Some(receiver) = tokens[index].ident() {
1150            if reqwest_receivers.contains(&index)
1151                && tokens
1152                    .get(index + 1)
1153                    .is_some_and(|token| token.is_punct('.'))
1154            {
1155                (receiver, index + 2)
1156            } else {
1157                continue;
1158            }
1159        } else {
1160            continue;
1161        };
1162        let Some(method_name) = tokens.get(method_index).and_then(Token::ident) else {
1163            continue;
1164        };
1165        if !tokens
1166            .get(method_index + 1)
1167            .is_some_and(|token| token.is_punct('('))
1168        {
1169            continue;
1170        }
1171        let Some(close) = matching(tokens, method_index + 1, '(', ')') else {
1172            continue;
1173        };
1174        let arguments = top_level_arguments(tokens, method_index + 1, close);
1175        let (method, path_argument) = if method_name == "request" {
1176            (
1177                arguments.first().and_then(|argument| {
1178                    let method_end = arguments
1179                        .get(1)
1180                        .map_or(close, |second| second.saturating_sub(1));
1181                    rust_method_expression(tokens, *argument, method_end)
1182                }),
1183                arguments.get(1).copied(),
1184            )
1185        } else {
1186            (
1187                canonical_method(method_name).map(str::to_owned),
1188                arguments.first().copied(),
1189            )
1190        };
1191        if method.is_none() && method_name != "request" {
1192            continue;
1193        }
1194        let literal = path_argument
1195            .and_then(|argument| tokens.get(argument))
1196            .and_then(Token::literal);
1197        let mut observation = http_from_literal(
1198            SourceLanguage::Rust,
1199            SourceFramework::Reqwest,
1200            SourceRole::Consumer,
1201            method,
1202            literal,
1203            enclosing_symbol(functions, index),
1204            SourceLineRange {
1205                start: tokens[index].line,
1206                end: tokens[close].end_line,
1207            },
1208            false,
1209        );
1210        if method_name == "request" && observation.method.is_none() {
1211            observation.status = SourceEpistemicStatus::Incomplete;
1212            observation.confidence = 0.0;
1213            observation.warnings.push(SourceWarning::DynamicMethod);
1214            observation.warnings.sort();
1215            observation.warnings.dedup();
1216        }
1217        let _ = receiver;
1218        observations.push(observation);
1219    }
1220}
1221
1222fn rust_method_expression(tokens: &[Token], start: usize, end: usize) -> Option<String> {
1223    if let Some(literal) = tokens.get(start).and_then(Token::literal) {
1224        return canonical_method(literal).map(str::to_owned);
1225    }
1226    (start..end)
1227        .filter_map(|index| tokens[index].ident())
1228        .find_map(|name| canonical_method(name).map(str::to_owned))
1229}
1230
1231fn method_calls(tokens: &[Token], start: usize, end: usize) -> Vec<(String, Option<String>)> {
1232    let mut methods = Vec::new();
1233    for index in start..end {
1234        let Some(name) = tokens[index].ident() else {
1235            continue;
1236        };
1237        let Some(method) = canonical_method(name) else {
1238            continue;
1239        };
1240        if !tokens
1241            .get(index + 1)
1242            .is_some_and(|token| token.is_punct('('))
1243        {
1244            continue;
1245        }
1246        let direct_handler = tokens
1247            .get(index + 2)
1248            .and_then(Token::ident)
1249            .map(str::to_owned);
1250        let actix_handler = (index + 2..end)
1251            .find(|candidate| {
1252                tokens[*candidate].is_ident("to")
1253                    && tokens
1254                        .get(*candidate + 1)
1255                        .is_some_and(|token| token.is_punct('('))
1256            })
1257            .and_then(|to| tokens.get(to + 2))
1258            .and_then(Token::ident)
1259            .map(str::to_owned);
1260        let handler = direct_handler.or(actix_handler);
1261        methods.push((method.to_owned(), handler));
1262    }
1263    methods
1264}
1265
1266fn contains_ident(tokens: &[Token], start: usize, end: usize, name: &str) -> bool {
1267    tokens
1268        .get(start..end)
1269        .is_some_and(|slice| slice.iter().any(|token| token.is_ident(name)))
1270}
1271
1272fn first_argument(open: usize, close: usize) -> Option<usize> {
1273    (open + 1 < close).then_some(open + 1)
1274}
1275
1276fn top_level_arguments(tokens: &[Token], open: usize, close: usize) -> Vec<usize> {
1277    if open + 1 >= close {
1278        return Vec::new();
1279    }
1280    let mut arguments = vec![open + 1];
1281    let mut round = 0_i32;
1282    let mut square = 0_i32;
1283    let mut curly = 0_i32;
1284    for (index, token) in tokens.iter().enumerate().take(close).skip(open + 1) {
1285        match token.kind {
1286            TokenKind::Punct('(') => round += 1,
1287            TokenKind::Punct(')') => round -= 1,
1288            TokenKind::Punct('[') => square += 1,
1289            TokenKind::Punct(']') => square -= 1,
1290            TokenKind::Punct('{') => curly += 1,
1291            TokenKind::Punct('}') => curly -= 1,
1292            TokenKind::Punct(',')
1293                if round == 0 && square == 0 && curly == 0 && index + 1 < close =>
1294            {
1295                arguments.push(index + 1);
1296            }
1297            _ => {}
1298        }
1299    }
1300    arguments
1301}
1302
1303fn parse_keyword_string_values(
1304    tokens: &[Token],
1305    start: usize,
1306    end: usize,
1307    keyword: &str,
1308) -> Vec<String> {
1309    let mut values = Vec::new();
1310    for index in start..end {
1311        if !tokens[index].is_ident(keyword)
1312            || !tokens
1313                .get(index + 1)
1314                .is_some_and(|token| token.is_punct('='))
1315        {
1316            continue;
1317        }
1318        let value_start = index + 2;
1319        if let Some(value) = tokens.get(value_start).and_then(Token::literal) {
1320            values.push(value.to_owned());
1321        } else if tokens
1322            .get(value_start)
1323            .is_some_and(|token| token.is_punct('['))
1324        {
1325            let close = matching(tokens, value_start, '[', ']').unwrap_or(end);
1326            values.extend(
1327                tokens[value_start + 1..close]
1328                    .iter()
1329                    .filter_map(Token::literal)
1330                    .map(str::to_owned),
1331            );
1332        }
1333    }
1334    values
1335}
1336
1337fn canonical_method(name: &str) -> Option<&'static str> {
1338    HTTP_METHODS
1339        .iter()
1340        .copied()
1341        .find(|method| method.eq_ignore_ascii_case(name))
1342}
1343
1344fn confirmed_test(
1345    language: SourceLanguage,
1346    framework: SourceFramework,
1347    name: String,
1348    start: u32,
1349    end: u32,
1350) -> SourceObservation {
1351    SourceObservation {
1352        language,
1353        framework,
1354        role: SourceRole::Test,
1355        method: None,
1356        path: None,
1357        symbol_name: Some(name),
1358        related_symbol: None,
1359        related_path: None,
1360        lines: SourceLineRange { start, end },
1361        status: SourceEpistemicStatus::Confirmed,
1362        confidence: 1.0,
1363        warnings: Vec::new(),
1364    }
1365}
1366
1367#[expect(
1368    clippy::too_many_arguments,
1369    reason = "Observation fields remain explicit at evidence sites"
1370)]
1371fn http_from_literal(
1372    language: SourceLanguage,
1373    framework: SourceFramework,
1374    role: SourceRole,
1375    method: Option<String>,
1376    literal: Option<&str>,
1377    symbol_name: Option<String>,
1378    lines: SourceLineRange,
1379    route: bool,
1380) -> SourceObservation {
1381    let (path, authority) = literal.map_or((None, None), |value| {
1382        if route {
1383            (route_literal_path(value), None)
1384        } else {
1385            client_literal_identity(value)
1386        }
1387    });
1388    let warning = if authority.is_some() {
1389        Some(SourceWarning::UnmappedAuthority)
1390    } else if literal.is_none() {
1391        Some(SourceWarning::DynamicPath)
1392    } else if path.is_none() {
1393        Some(SourceWarning::UnsupportedLiteralPath)
1394    } else {
1395        None
1396    };
1397    let status = if path.is_some() && method.is_some() && authority.is_none() {
1398        SourceEpistemicStatus::Confirmed
1399    } else {
1400        SourceEpistemicStatus::Ambiguous
1401    };
1402    let mut observation = SourceObservation {
1403        language,
1404        framework,
1405        role,
1406        method,
1407        path,
1408        symbol_name,
1409        related_symbol: None,
1410        related_path: None,
1411        lines,
1412        status,
1413        confidence: if status == SourceEpistemicStatus::Confirmed {
1414            1.0
1415        } else {
1416            0.0
1417        },
1418        warnings: warning.into_iter().collect(),
1419    };
1420    if role == SourceRole::Provider && observation.symbol_name.is_none() {
1421        observation.status = SourceEpistemicStatus::Incomplete;
1422        observation.confidence = 0.0;
1423        observation.warnings.push(SourceWarning::MissingSymbol);
1424    }
1425    observation
1426}
1427
1428#[expect(
1429    clippy::too_many_arguments,
1430    reason = "Observation fields remain explicit at evidence sites"
1431)]
1432fn inexact_http(
1433    language: SourceLanguage,
1434    framework: SourceFramework,
1435    role: SourceRole,
1436    method: Option<String>,
1437    path: Option<String>,
1438    symbol_name: Option<String>,
1439    lines: SourceLineRange,
1440    warning: SourceWarning,
1441) -> SourceObservation {
1442    SourceObservation {
1443        language,
1444        framework,
1445        role,
1446        method,
1447        path,
1448        symbol_name,
1449        related_symbol: None,
1450        related_path: None,
1451        lines,
1452        status: SourceEpistemicStatus::Incomplete,
1453        confidence: 0.0,
1454        warnings: vec![warning],
1455    }
1456}
1457
1458fn route_literal_path(value: &str) -> Option<String> {
1459    (value.starts_with('/') && !value.contains(['?', '#']))
1460        .then(|| normalize_source_http_path(value))
1461}
1462
1463fn client_literal_identity(value: &str) -> (Option<String>, Option<String>) {
1464    if value.starts_with('/') {
1465        return (
1466            Some(normalize_source_http_path(
1467                value.split(['?', '#']).next().unwrap_or(value),
1468            )),
1469            None,
1470        );
1471    }
1472    let after_authority = value
1473        .strip_prefix("http://")
1474        .or_else(|| value.strip_prefix("https://"));
1475    let Some(after_authority) = after_authority else {
1476        return (None, None);
1477    };
1478    if after_authority.is_empty() || after_authority.starts_with('/') {
1479        return (None, None);
1480    }
1481    let separator = after_authority.find('/');
1482    let authority = separator.map_or(after_authority, |index| &after_authority[..index]);
1483    let path = separator.map_or("/", |index| &after_authority[index..]);
1484    (
1485        Some(normalize_source_http_path(
1486            path.split(['?', '#']).next().unwrap_or(path),
1487        )),
1488        Some(authority.to_ascii_lowercase()),
1489    )
1490}
1491
1492#[derive(Debug, Default)]
1493struct PythonContexts {
1494    fastapi_apps: BTreeSet<String>,
1495    route_prefixes: BTreeMap<String, String>,
1496    flask_apps: BTreeSet<String>,
1497    request_modules: BTreeSet<String>,
1498    httpx_modules: BTreeSet<String>,
1499    aiohttp_modules: BTreeSet<String>,
1500    request_clients: BTreeSet<String>,
1501    httpx_clients: BTreeSet<String>,
1502    aiohttp_clients: BTreeSet<String>,
1503    direct_calls: BTreeMap<String, (SourceFramework, String)>,
1504    string_constants: BTreeMap<String, String>,
1505}
1506
1507impl PythonContexts {
1508    fn discover(tokens: &[Token]) -> Self {
1509        let mut contexts = Self::default();
1510        contexts.request_modules.insert("requests".to_owned());
1511        contexts.httpx_modules.insert("httpx".to_owned());
1512        contexts.aiohttp_modules.insert("aiohttp".to_owned());
1513        discover_python_import_aliases(tokens, "requests", &mut contexts.request_modules);
1514        discover_python_import_aliases(tokens, "httpx", &mut contexts.httpx_modules);
1515        discover_python_import_aliases(tokens, "aiohttp", &mut contexts.aiohttp_modules);
1516        discover_python_direct_calls(
1517            tokens,
1518            "requests",
1519            SourceFramework::Requests,
1520            &mut contexts.direct_calls,
1521        );
1522        discover_python_direct_calls(
1523            tokens,
1524            "httpx",
1525            SourceFramework::Httpx,
1526            &mut contexts.direct_calls,
1527        );
1528        let request_session_imported = python_imports_item(tokens, "requests", "Session");
1529        let httpx_client_imported = python_imports_item(tokens, "httpx", "Client")
1530            || python_imports_item(tokens, "httpx", "AsyncClient");
1531        let aiohttp_client_imported = python_imports_item(tokens, "aiohttp", "ClientSession");
1532        for index in 0..tokens.len() {
1533            let Some(name) = tokens[index].ident() else {
1534                continue;
1535            };
1536            if !tokens
1537                .get(index + 1)
1538                .is_some_and(|token| token.is_punct('='))
1539            {
1540                continue;
1541            }
1542            let end = python_expression_end(tokens, index + 2);
1543            if let Some(value) =
1544                python_static_string_expression(tokens, index + 2, end, &contexts.string_constants)
1545            {
1546                contexts.string_constants.insert(name.to_owned(), value);
1547            }
1548            if contains_ident(tokens, index + 2, end, "FastAPI")
1549                || contains_ident(tokens, index + 2, end, "APIRouter")
1550            {
1551                contexts.fastapi_apps.insert(name.to_owned());
1552                if contains_ident(tokens, index + 2, end, "APIRouter")
1553                    && let Some(open) =
1554                        (index + 2..end).find(|candidate| tokens[*candidate].is_punct('('))
1555                    && let Some(close) = matching(tokens, open, '(', ')')
1556                    && let Some(prefix) = parse_keyword_string_values(tokens, open, close, "prefix")
1557                        .into_iter()
1558                        .next()
1559                {
1560                    contexts
1561                        .route_prefixes
1562                        .insert(name.to_owned(), normalize_source_http_path(&prefix));
1563                }
1564            }
1565            if contains_ident(tokens, index + 2, end, "Flask")
1566                || contains_ident(tokens, index + 2, end, "Blueprint")
1567            {
1568                contexts.flask_apps.insert(name.to_owned());
1569            }
1570            if contains_ident(tokens, index + 2, end, "Session")
1571                && (contains_any(tokens, index + 2, end, &contexts.request_modules)
1572                    || request_session_imported)
1573            {
1574                contexts.request_clients.insert(name.to_owned());
1575            }
1576            if (contains_ident(tokens, index + 2, end, "Client")
1577                || contains_ident(tokens, index + 2, end, "AsyncClient"))
1578                && (contains_any(tokens, index + 2, end, &contexts.httpx_modules)
1579                    || httpx_client_imported)
1580            {
1581                contexts.httpx_clients.insert(name.to_owned());
1582            }
1583            if contains_ident(tokens, index + 2, end, "ClientSession")
1584                && (contains_any(tokens, index + 2, end, &contexts.aiohttp_modules)
1585                    || aiohttp_client_imported)
1586            {
1587                contexts.aiohttp_clients.insert(name.to_owned());
1588            }
1589        }
1590        if aiohttp_client_imported {
1591            for index in 0..tokens.len() {
1592                if !tokens[index].is_ident("as") {
1593                    continue;
1594                }
1595                let Some(name) = tokens.get(index + 1).and_then(Token::ident) else {
1596                    continue;
1597                };
1598                let start = index.saturating_sub(32);
1599                if tokens[start..index]
1600                    .iter()
1601                    .any(|token| token.is_ident("ClientSession"))
1602                {
1603                    contexts.aiohttp_clients.insert(name.to_owned());
1604                }
1605            }
1606        }
1607        contexts
1608    }
1609}
1610
1611fn python_imports_item(tokens: &[Token], module: &str, item: &str) -> bool {
1612    tokens.iter().enumerate().any(|(index, token)| {
1613        token.is_ident("from")
1614            && tokens
1615                .get(index + 1)
1616                .is_some_and(|token| token.is_ident(module))
1617            && tokens
1618                .get(index + 2)
1619                .is_some_and(|token| token.is_ident("import"))
1620            && (index + 3..tokens.len())
1621                .take_while(|candidate| tokens[*candidate].line == token.line)
1622                .any(|candidate| tokens[candidate].is_ident(item))
1623    })
1624}
1625
1626fn discover_python_direct_calls(
1627    tokens: &[Token],
1628    module: &str,
1629    framework: SourceFramework,
1630    calls: &mut BTreeMap<String, (SourceFramework, String)>,
1631) {
1632    for index in 0..tokens.len() {
1633        if !tokens[index].is_ident("from")
1634            || !tokens
1635                .get(index + 1)
1636                .is_some_and(|token| token.is_ident(module))
1637            || !tokens
1638                .get(index + 2)
1639                .is_some_and(|token| token.is_ident("import"))
1640        {
1641            continue;
1642        }
1643        let mut cursor = index + 3;
1644        while cursor < tokens.len() && tokens[cursor].line == tokens[index].line {
1645            let Some(imported) = tokens[cursor].ident() else {
1646                cursor += 1;
1647                continue;
1648            };
1649            if canonical_method(imported).is_none() && imported != "request" {
1650                cursor += 1;
1651                continue;
1652            }
1653            let (local, advance) = if tokens
1654                .get(cursor + 1)
1655                .is_some_and(|token| token.is_ident("as"))
1656            {
1657                (
1658                    tokens
1659                        .get(cursor + 2)
1660                        .and_then(Token::ident)
1661                        .unwrap_or(imported),
1662                    3,
1663                )
1664            } else {
1665                (imported, 1)
1666            };
1667            calls.insert(local.to_owned(), (framework, imported.to_owned()));
1668            cursor += advance;
1669        }
1670    }
1671}
1672
1673fn python_expression_end(tokens: &[Token], start: usize) -> usize {
1674    let mut round = 0_i32;
1675    let mut square = 0_i32;
1676    let mut curly = 0_i32;
1677    let mut previous_line = tokens.get(start).map_or(0, |token| token.line);
1678    for (index, token) in tokens.iter().enumerate().skip(start) {
1679        if index > start && token.line > previous_line && round == 0 && square == 0 && curly == 0 {
1680            return index;
1681        }
1682        if token.is_punct(';') && round == 0 && square == 0 && curly == 0 {
1683            return index;
1684        }
1685        match token.kind {
1686            TokenKind::Punct('(') => round += 1,
1687            TokenKind::Punct(')') => round -= 1,
1688            TokenKind::Punct('[') => square += 1,
1689            TokenKind::Punct(']') => square -= 1,
1690            TokenKind::Punct('{') => curly += 1,
1691            TokenKind::Punct('}') => curly -= 1,
1692            _ => {}
1693        }
1694        previous_line = token.line;
1695    }
1696    tokens.len()
1697}
1698
1699fn discover_python_import_aliases(tokens: &[Token], module: &str, aliases: &mut BTreeSet<String>) {
1700    for index in 0..tokens.len() {
1701        if !tokens[index].is_ident("import")
1702            || !tokens
1703                .get(index + 1)
1704                .is_some_and(|token| token.is_ident(module))
1705        {
1706            continue;
1707        }
1708        if tokens
1709            .get(index + 2)
1710            .is_some_and(|token| token.is_ident("as"))
1711            && let Some(alias) = tokens.get(index + 3).and_then(Token::ident)
1712        {
1713            aliases.insert(alias.to_owned());
1714        }
1715    }
1716}
1717
1718fn contains_any(tokens: &[Token], start: usize, end: usize, names: &BTreeSet<String>) -> bool {
1719    tokens.get(start..end).is_some_and(|slice| {
1720        slice
1721            .iter()
1722            .filter_map(Token::ident)
1723            .any(|name| names.contains(name))
1724    })
1725}
1726
1727fn python_static_string_expression(
1728    tokens: &[Token],
1729    start: usize,
1730    end: usize,
1731    constants: &BTreeMap<String, String>,
1732) -> Option<String> {
1733    let mut output = String::new();
1734    let mut found = false;
1735    for token in tokens.get(start..end)? {
1736        if let Some(value) = token.literal() {
1737            output.push_str(value);
1738            found = true;
1739        } else if let Some(name) = token.ident() {
1740            output.push_str(constants.get(name)?);
1741            found = true;
1742        } else if !matches!(token.kind, TokenKind::Punct('+' | '(' | ')' | '[' | ']')) {
1743            return None;
1744        }
1745    }
1746    found.then_some(output)
1747}
1748
1749fn python_functions(source: &str, tokens: &[Token]) -> Vec<FunctionSpan> {
1750    let line_count = saturating_u32(source.lines().count().max(1));
1751    let mut functions = Vec::new();
1752    for index in 0..tokens.len() {
1753        if !tokens[index].is_ident("def") {
1754            continue;
1755        }
1756        let Some(name) = tokens.get(index + 1).and_then(Token::ident) else {
1757            continue;
1758        };
1759        let indent = source_indent(source, tokens[index].line);
1760        let end_line = python_block_end(source, tokens[index].line, indent, line_count);
1761        let end_token = (index + 1..tokens.len())
1762            .find(|candidate| tokens[*candidate].line > end_line)
1763            .unwrap_or(tokens.len())
1764            .saturating_sub(1);
1765        functions.push(FunctionSpan {
1766            name: name.to_owned(),
1767            start_token: index,
1768            body_start_token: index,
1769            end_token,
1770        });
1771    }
1772    functions
1773}
1774
1775fn source_indent(source: &str, line: u32) -> usize {
1776    source
1777        .lines()
1778        .nth(line.saturating_sub(1) as usize)
1779        .map_or(0, |value| {
1780            value
1781                .chars()
1782                .take_while(|character| character.is_whitespace())
1783                .count()
1784        })
1785}
1786
1787fn python_block_end(source: &str, start: u32, indent: usize, fallback: u32) -> u32 {
1788    for (offset, line) in source.lines().enumerate().skip(start as usize) {
1789        let trimmed = line.trim();
1790        if trimmed.is_empty() || trimmed.starts_with('#') {
1791            continue;
1792        }
1793        let candidate_indent = line
1794            .chars()
1795            .take_while(|character| character.is_whitespace())
1796            .count();
1797        if candidate_indent <= indent {
1798            return saturating_u32(offset);
1799        }
1800    }
1801    fallback
1802}
1803
1804fn parse_python_routes(
1805    tokens: &[Token],
1806    contexts: &PythonContexts,
1807    observations: &mut SourceObservationCollector<'_>,
1808) {
1809    for index in 0..tokens.len() {
1810        if !tokens[index].is_punct('@') {
1811            continue;
1812        }
1813        let Some((receiver, decorator, open)) = python_decorator_call(tokens, index) else {
1814            continue;
1815        };
1816        let Some(close) = matching(tokens, open, '(', ')') else {
1817            continue;
1818        };
1819        let Some((name, signature_end)) = python_function_after(tokens, close) else {
1820            continue;
1821        };
1822        let framework = if contexts.fastapi_apps.contains(receiver) {
1823            SourceFramework::FastApi
1824        } else if contexts.flask_apps.contains(receiver) {
1825            SourceFramework::Flask
1826        } else {
1827            continue;
1828        };
1829        let path_start = top_level_arguments(tokens, open, close).first().copied();
1830        let resolved_path = path_start.and_then(|start| {
1831            python_static_string_expression(
1832                tokens,
1833                start,
1834                python_argument_end(tokens, start, close),
1835                &contexts.string_constants,
1836            )
1837        });
1838        let raw_path = resolved_path.or_else(|| {
1839            tokens
1840                .get(open + 1)
1841                .and_then(Token::literal)
1842                .map(str::to_owned)
1843        });
1844        let prefixed_path = raw_path.as_ref().map(|path| {
1845            contexts.route_prefixes.get(receiver).map_or_else(
1846                || path.clone(),
1847                |prefix| normalize_source_http_path(&format!("{prefix}{path}")),
1848            )
1849        });
1850        let literal = prefixed_path.as_deref();
1851        let methods = python_route_methods(tokens, open, close, decorator, framework);
1852        if methods.is_empty() {
1853            observations.push(inexact_http(
1854                SourceLanguage::Python,
1855                framework,
1856                SourceRole::Provider,
1857                None,
1858                literal.and_then(route_literal_path),
1859                Some(name),
1860                SourceLineRange {
1861                    start: tokens[index].line,
1862                    end: tokens[signature_end].end_line,
1863                },
1864                SourceWarning::DynamicMethod,
1865            ));
1866        } else {
1867            for method in methods {
1868                observations.push(http_from_literal(
1869                    SourceLanguage::Python,
1870                    framework,
1871                    SourceRole::Provider,
1872                    Some(method),
1873                    literal,
1874                    Some(name.clone()),
1875                    SourceLineRange {
1876                        start: tokens[index].line,
1877                        end: tokens[signature_end].end_line,
1878                    },
1879                    true,
1880                ));
1881            }
1882        }
1883    }
1884}
1885
1886fn python_decorator_call(tokens: &[Token], at: usize) -> Option<(&str, &str, usize)> {
1887    let mut names = Vec::new();
1888    let mut cursor = at.saturating_add(1);
1889    loop {
1890        names.push(tokens.get(cursor)?.ident()?);
1891        if tokens
1892            .get(cursor + 1)
1893            .is_some_and(|token| token.is_punct('.'))
1894        {
1895            cursor = cursor.saturating_add(2);
1896            continue;
1897        }
1898        break;
1899    }
1900    let open = cursor.saturating_add(1);
1901    if names.len() < 2 || !tokens.get(open).is_some_and(|token| token.is_punct('(')) {
1902        return None;
1903    }
1904    Some((names[names.len() - 2], names[names.len() - 1], open))
1905}
1906
1907fn python_argument_end(tokens: &[Token], start: usize, close: usize) -> usize {
1908    let mut round = 0_i32;
1909    let mut square = 0_i32;
1910    let mut curly = 0_i32;
1911    for (index, token) in tokens.iter().enumerate().take(close).skip(start) {
1912        match token.kind {
1913            TokenKind::Punct('(') => round += 1,
1914            TokenKind::Punct(')') => round -= 1,
1915            TokenKind::Punct('[') => square += 1,
1916            TokenKind::Punct(']') => square -= 1,
1917            TokenKind::Punct('{') => curly += 1,
1918            TokenKind::Punct('}') => curly -= 1,
1919            TokenKind::Punct(',') if round == 0 && square == 0 && curly == 0 => return index,
1920            _ => {}
1921        }
1922    }
1923    close
1924}
1925
1926fn python_function_after(tokens: &[Token], close: usize) -> Option<(String, usize)> {
1927    let mut index = close + 1;
1928    while index < tokens.len() && tokens[index].line <= tokens[close].line.saturating_add(12) {
1929        if tokens[index].is_ident("async") {
1930            index += 1;
1931            continue;
1932        }
1933        if tokens[index].is_ident("def") {
1934            let name = tokens.get(index + 1)?.ident()?.to_owned();
1935            let end = (index + 2..tokens.len())
1936                .find(|candidate| tokens[*candidate].is_punct(':'))
1937                .unwrap_or(index + 1);
1938            return Some((name, end));
1939        }
1940        if tokens[index].is_punct('@') {
1941            return None;
1942        }
1943        index += 1;
1944    }
1945    None
1946}
1947
1948fn python_route_methods(
1949    tokens: &[Token],
1950    open: usize,
1951    close: usize,
1952    decorator: &str,
1953    framework: SourceFramework,
1954) -> BTreeSet<String> {
1955    if let Some(method) = canonical_method(decorator) {
1956        return BTreeSet::from([method.to_owned()]);
1957    }
1958    let mut methods = parse_keyword_string_values(tokens, open, close, "methods")
1959        .into_iter()
1960        .filter_map(|method| canonical_method(&method).map(str::to_owned))
1961        .collect::<BTreeSet<_>>();
1962    if framework == SourceFramework::Flask && decorator == "route" && methods.is_empty() {
1963        methods.insert("GET".to_owned());
1964    }
1965    methods
1966}
1967
1968fn parse_python_http_registries(
1969    tokens: &[Token],
1970    observations: &mut SourceObservationCollector<'_>,
1971) {
1972    for index in 0..tokens.len() {
1973        let Some(name) = tokens[index].ident() else {
1974            continue;
1975        };
1976        if !name
1977            .chars()
1978            .all(|character| character.is_ascii_uppercase() || character == '_')
1979            || !tokens
1980                .get(index + 1)
1981                .is_some_and(|token| token.is_punct('='))
1982            || !tokens
1983                .get(index + 2)
1984                .is_some_and(|token| token.is_punct('{'))
1985        {
1986            continue;
1987        }
1988        let open = index + 2;
1989        let Some(close) = matching(tokens, open, '{', '}') else {
1990            continue;
1991        };
1992        parse_python_http_registry_dict(tokens, open, close, "", observations, 0);
1993    }
1994}
1995
1996fn parse_python_http_registry_dict(
1997    tokens: &[Token],
1998    open: usize,
1999    close: usize,
2000    prefix: &str,
2001    observations: &mut SourceObservationCollector<'_>,
2002    depth: usize,
2003) {
2004    if depth >= 32 {
2005        return;
2006    }
2007    let mut cursor = open.saturating_add(1);
2008    while cursor < close {
2009        while cursor < close && tokens[cursor].is_punct(',') {
2010            cursor += 1;
2011        }
2012        let Some(key) = tokens.get(cursor).and_then(Token::literal) else {
2013            cursor += 1;
2014            continue;
2015        };
2016        if !tokens
2017            .get(cursor + 1)
2018            .is_some_and(|token| token.is_punct(':'))
2019        {
2020            cursor += 1;
2021            continue;
2022        }
2023        let value_start = cursor + 2;
2024        let value_end = python_argument_end(tokens, value_start, close);
2025        parse_python_http_registry_value(
2026            tokens,
2027            value_start,
2028            value_end,
2029            prefix,
2030            key,
2031            observations,
2032            depth,
2033        );
2034        cursor = value_end.saturating_add(1);
2035    }
2036}
2037
2038fn parse_python_http_registry_value(
2039    tokens: &[Token],
2040    start: usize,
2041    end: usize,
2042    prefix: &str,
2043    key: &str,
2044    observations: &mut SourceObservationCollector<'_>,
2045    depth: usize,
2046) {
2047    if tokens.get(start).is_some_and(|token| token.is_punct('[')) {
2048        let Some(close) = matching(tokens, start, '[', ']').filter(|close| *close <= end) else {
2049            return;
2050        };
2051        let arguments = top_level_arguments(tokens, start, close);
2052        let Some(method) = arguments
2053            .first()
2054            .and_then(|argument| tokens.get(*argument))
2055            .and_then(Token::literal)
2056            .and_then(canonical_method)
2057        else {
2058            return;
2059        };
2060        let Some(path) = arguments
2061            .get(1)
2062            .and_then(|argument| tokens.get(*argument))
2063            .and_then(Token::literal)
2064        else {
2065            return;
2066        };
2067        let combined = canonical_python_registry_path(prefix, path);
2068        observations.push(http_from_literal(
2069            SourceLanguage::Python,
2070            SourceFramework::PythonHttpRegistry,
2071            SourceRole::Consumer,
2072            Some(method.to_owned()),
2073            Some(&combined),
2074            Some(key.to_owned()),
2075            SourceLineRange {
2076                start: tokens[start].line,
2077                end: tokens[close].end_line,
2078            },
2079            false,
2080        ));
2081        return;
2082    }
2083    if !tokens.get(start).is_some_and(|token| token.is_punct('(')) {
2084        return;
2085    }
2086    let Some(close) = matching(tokens, start, '(', ')').filter(|close| *close <= end) else {
2087        return;
2088    };
2089    let arguments = top_level_arguments(tokens, start, close);
2090    let Some(segment) = arguments
2091        .first()
2092        .and_then(|argument| tokens.get(*argument))
2093        .and_then(Token::literal)
2094    else {
2095        return;
2096    };
2097    let Some(dictionary) = arguments.get(1).copied().filter(|argument| {
2098        tokens
2099            .get(*argument)
2100            .is_some_and(|token| token.is_punct('{'))
2101    }) else {
2102        return;
2103    };
2104    let Some(dictionary_close) = matching(tokens, dictionary, '{', '}') else {
2105        return;
2106    };
2107    let nested_prefix = canonical_python_registry_path(prefix, segment);
2108    parse_python_http_registry_dict(
2109        tokens,
2110        dictionary,
2111        dictionary_close,
2112        &nested_prefix,
2113        observations,
2114        depth.saturating_add(1),
2115    );
2116}
2117
2118fn canonical_python_registry_path(prefix: &str, segment: &str) -> String {
2119    let joined = format!("{prefix}{segment}")
2120        .replace("{{", "{")
2121        .replace("}}", "}");
2122    normalize_source_http_path(&joined)
2123}
2124
2125fn parse_python_factories(
2126    source: &str,
2127    tokens: &[Token],
2128    observations: &mut SourceObservationCollector<'_>,
2129) {
2130    let imported_paths = python_imported_symbol_paths(tokens);
2131    let fallback = saturating_u32(source.lines().count().max(1));
2132    for index in 0..tokens.len() {
2133        if !tokens[index].is_ident("class") {
2134            continue;
2135        }
2136        let Some(factory_name) = tokens.get(index + 1).and_then(Token::ident) else {
2137            continue;
2138        };
2139        let signature_end = (index + 2..tokens.len())
2140            .find(|candidate| tokens[*candidate].is_punct(':'))
2141            .unwrap_or(index + 1);
2142        if !tokens
2143            .get(index + 2..signature_end)
2144            .is_some_and(|signature| {
2145                signature
2146                    .iter()
2147                    .filter_map(Token::ident)
2148                    .any(|base| base == "Factory" || base.ends_with("Factory"))
2149            })
2150        {
2151            continue;
2152        }
2153        let start_line = tokens[index].line;
2154        let end_line = python_block_end(
2155            source,
2156            start_line,
2157            source_indent(source, start_line),
2158            fallback,
2159        );
2160        let model_assignment = (signature_end + 1..tokens.len())
2161            .take_while(|candidate| tokens[*candidate].line <= end_line)
2162            .find_map(|candidate| {
2163                if tokens[candidate].is_ident("model")
2164                    && tokens
2165                        .get(candidate + 1)
2166                        .is_some_and(|token| token.is_punct('='))
2167                {
2168                    Some((
2169                        tokens.get(candidate + 2).and_then(Token::ident)?,
2170                        tokens[candidate].line,
2171                    ))
2172                } else {
2173                    None
2174                }
2175            });
2176        let Some((model_name, model_line)) = model_assignment else {
2177            continue;
2178        };
2179        observations.push(SourceObservation {
2180            language: SourceLanguage::Python,
2181            framework: SourceFramework::FactoryBoy,
2182            role: SourceRole::Factory,
2183            method: None,
2184            path: None,
2185            symbol_name: Some(factory_name.to_owned()),
2186            related_symbol: Some(model_name.to_owned()),
2187            related_path: imported_paths.get(model_name).cloned(),
2188            lines: SourceLineRange {
2189                start: start_line,
2190                end: model_line,
2191            },
2192            status: SourceEpistemicStatus::Confirmed,
2193            confidence: 1.0,
2194            warnings: Vec::new(),
2195        });
2196    }
2197}
2198
2199fn python_imported_symbol_paths(tokens: &[Token]) -> BTreeMap<String, String> {
2200    let mut output = BTreeMap::new();
2201    for index in 0..tokens.len() {
2202        if !tokens[index].is_ident("from") {
2203            continue;
2204        }
2205        let import_index = (index + 1..tokens.len())
2206            .take_while(|candidate| tokens[*candidate].line == tokens[index].line)
2207            .find(|candidate| tokens[*candidate].is_ident("import"));
2208        let Some(import_index) = import_index else {
2209            continue;
2210        };
2211        let module = tokens[index + 1..import_index]
2212            .iter()
2213            .filter_map(Token::ident)
2214            .collect::<Vec<_>>()
2215            .join("/");
2216        if module.is_empty() {
2217            continue;
2218        }
2219        let target_path = format!("{module}.py");
2220        let mut cursor = import_index + 1;
2221        while cursor < tokens.len() && tokens[cursor].line == tokens[index].line {
2222            let Some(imported) = tokens[cursor].ident() else {
2223                cursor += 1;
2224                continue;
2225            };
2226            let (local, advance) = if tokens
2227                .get(cursor + 1)
2228                .is_some_and(|token| token.is_ident("as"))
2229            {
2230                (
2231                    tokens
2232                        .get(cursor + 2)
2233                        .and_then(Token::ident)
2234                        .unwrap_or(imported),
2235                    3,
2236                )
2237            } else {
2238                (imported, 1)
2239            };
2240            output.insert(local.to_owned(), target_path.clone());
2241            cursor += advance;
2242        }
2243    }
2244    output
2245}
2246
2247fn parse_python_http_calls(
2248    tokens: &[Token],
2249    functions: &[FunctionSpan],
2250    contexts: &PythonContexts,
2251    observations: &mut SourceObservationCollector<'_>,
2252) {
2253    let receivers = contexts
2254        .request_modules
2255        .iter()
2256        .chain(&contexts.request_clients)
2257        .map(|name| (name.as_str(), SourceFramework::Requests))
2258        .chain(
2259            contexts
2260                .httpx_modules
2261                .iter()
2262                .chain(&contexts.httpx_clients)
2263                .map(|name| (name.as_str(), SourceFramework::Httpx)),
2264        )
2265        .chain(
2266            contexts
2267                .aiohttp_clients
2268                .iter()
2269                .map(|name| (name.as_str(), SourceFramework::AioHttp)),
2270        )
2271        .collect::<BTreeMap<_, _>>();
2272    for index in 0..tokens.len() {
2273        let Some(receiver) = tokens[index].ident() else {
2274            continue;
2275        };
2276        let (framework, call, open) = if let Some(framework) = receivers.get(receiver).copied() {
2277            if !tokens
2278                .get(index + 1)
2279                .is_some_and(|token| token.is_punct('.'))
2280            {
2281                continue;
2282            }
2283            let Some(call) = tokens.get(index + 2).and_then(Token::ident) else {
2284                continue;
2285            };
2286            (framework, call, index + 3)
2287        } else if let Some((framework, call)) = contexts.direct_calls.get(receiver) {
2288            (*framework, call.as_str(), index + 1)
2289        } else {
2290            continue;
2291        };
2292        if !tokens.get(open).is_some_and(|token| token.is_punct('(')) {
2293            continue;
2294        }
2295        let Some(close) = matching(tokens, open, '(', ')') else {
2296            continue;
2297        };
2298        let arguments = top_level_arguments(tokens, open, close);
2299        let (method, path_argument) = if call == "request" {
2300            (
2301                arguments
2302                    .first()
2303                    .and_then(|argument| tokens.get(*argument))
2304                    .and_then(Token::literal)
2305                    .and_then(canonical_method)
2306                    .map(str::to_owned),
2307                arguments.get(1).copied(),
2308            )
2309        } else {
2310            (
2311                canonical_method(call).map(str::to_owned),
2312                arguments.first().copied(),
2313            )
2314        };
2315        if method.is_none() && call != "request" {
2316            continue;
2317        }
2318        let resolved_path = path_argument.and_then(|argument| {
2319            python_static_string_expression(
2320                tokens,
2321                argument,
2322                python_argument_end(tokens, argument, close),
2323                &contexts.string_constants,
2324            )
2325        });
2326        let literal = resolved_path.as_deref().or_else(|| {
2327            path_argument
2328                .and_then(|argument| tokens.get(argument))
2329                .and_then(Token::literal)
2330        });
2331        let mut observation = http_from_literal(
2332            SourceLanguage::Python,
2333            framework,
2334            SourceRole::Consumer,
2335            method,
2336            literal,
2337            enclosing_symbol(functions, index),
2338            SourceLineRange {
2339                start: tokens[index].line,
2340                end: tokens[close].end_line,
2341            },
2342            false,
2343        );
2344        if call == "request" && observation.method.is_none() {
2345            observation.status = SourceEpistemicStatus::Incomplete;
2346            observation.confidence = 0.0;
2347            observation.warnings.push(SourceWarning::DynamicMethod);
2348            observation.warnings.sort();
2349            observation.warnings.dedup();
2350        }
2351        observations.push(observation);
2352    }
2353}
2354
2355fn parse_python_tests(
2356    source: &str,
2357    tokens: &[Token],
2358    observations: &mut SourceObservationCollector<'_>,
2359) {
2360    let unittest_classes = python_unittest_classes(source, tokens);
2361    let python_classes = python_class_ranges(source, tokens);
2362    for index in 0..tokens.len() {
2363        if !tokens[index].is_ident("def") {
2364            continue;
2365        }
2366        let Some(name) = tokens.get(index + 1).and_then(Token::ident) else {
2367            continue;
2368        };
2369        if !name.starts_with("test_") {
2370            continue;
2371        }
2372        let signature_end = (index + 2..tokens.len())
2373            .find(|candidate| tokens[*candidate].is_punct(':'))
2374            .unwrap_or(index + 1);
2375        let line = tokens[index].line;
2376        let is_unittest = unittest_classes
2377            .iter()
2378            .any(|range| range.start <= line && line <= range.end);
2379        let indent = source_indent(source, line);
2380        let is_class_method = python_classes.iter().any(|(range, body_indent)| {
2381            range.start <= line && line <= range.end && indent == *body_indent
2382        });
2383        if !is_unittest && indent != 0 && !is_class_method {
2384            continue;
2385        }
2386        observations.push(confirmed_test(
2387            SourceLanguage::Python,
2388            if is_unittest {
2389                SourceFramework::Unittest
2390            } else if is_class_method {
2391                SourceFramework::PythonTest
2392            } else {
2393                SourceFramework::Pytest
2394            },
2395            name.to_owned(),
2396            line,
2397            tokens[signature_end].end_line,
2398        ));
2399    }
2400}
2401
2402fn python_class_ranges(source: &str, tokens: &[Token]) -> Vec<(SourceLineRange, usize)> {
2403    let fallback = saturating_u32(source.lines().count().max(1));
2404    let mut classes = Vec::new();
2405    for token in tokens.iter().filter(|token| token.is_ident("class")) {
2406        let class_indent = source_indent(source, token.line);
2407        let end = python_block_end(source, token.line, class_indent, fallback);
2408        let body_indent = source
2409            .lines()
2410            .enumerate()
2411            .skip(usize::try_from(token.line).unwrap_or(usize::MAX))
2412            .take(usize::try_from(end.saturating_sub(token.line)).unwrap_or(usize::MAX))
2413            .find_map(|(index, line)| {
2414                let trimmed = line.trim();
2415                let line_number = saturating_u32(index + 1);
2416                let indent = source_indent(source, line_number);
2417                (!trimmed.is_empty() && !trimmed.starts_with('#') && indent > class_indent)
2418                    .then_some(indent)
2419            });
2420        if let Some(body_indent) = body_indent {
2421            classes.push((
2422                SourceLineRange {
2423                    start: token.line,
2424                    end,
2425                },
2426                body_indent,
2427            ));
2428        }
2429    }
2430    classes
2431}
2432
2433fn python_unittest_classes(source: &str, tokens: &[Token]) -> Vec<SourceLineRange> {
2434    if !has_ident(tokens, "unittest") {
2435        return Vec::new();
2436    }
2437    let fallback = saturating_u32(source.lines().count().max(1));
2438    let mut classes = Vec::new();
2439    for index in 0..tokens.len() {
2440        if !tokens[index].is_ident("class") {
2441            continue;
2442        }
2443        let signature_end = (index + 1..tokens.len())
2444            .find(|candidate| tokens[*candidate].is_punct(':'))
2445            .unwrap_or(index);
2446        if !contains_ident(tokens, index + 1, signature_end, "TestCase") {
2447            continue;
2448        }
2449        let start = tokens[index].line;
2450        classes.push(SourceLineRange {
2451            start,
2452            end: python_block_end(source, start, source_indent(source, start), fallback),
2453        });
2454    }
2455    classes
2456}
2457
2458fn saturating_u32(value: usize) -> u32 {
2459    u32::try_from(value).unwrap_or(u32::MAX)
2460}
2461
2462fn finish(mut observations: Vec<SourceObservation>) -> Vec<SourceObservation> {
2463    for observation in &mut observations {
2464        observation.warnings.sort();
2465        observation.warnings.dedup();
2466    }
2467    observations.sort_by(compare_observations);
2468    observations.dedup();
2469    observations
2470}
2471
2472fn compare_observations(left: &SourceObservation, right: &SourceObservation) -> Ordering {
2473    (
2474        left.lines,
2475        left.language,
2476        left.framework,
2477        left.role,
2478        &left.method,
2479        &left.path,
2480        &left.symbol_name,
2481        &left.related_symbol,
2482        &left.related_path,
2483        left.status,
2484        &left.warnings,
2485    )
2486        .cmp(&(
2487            right.lines,
2488            right.language,
2489            right.framework,
2490            right.role,
2491            &right.method,
2492            &right.path,
2493            &right.symbol_name,
2494            &right.related_symbol,
2495            &right.related_path,
2496            right.status,
2497            &right.warnings,
2498        ))
2499}
2500
2501#[cfg(test)]
2502mod tests {
2503    use super::{
2504        SourceEpistemicStatus, SourceFramework, SourceRole, SourceWarning, parse_python_source, parse_rust_source
2505    };
2506
2507    #[test]
2508    fn axum_should_extract_multiline_route_and_handler() {
2509        let source = r#"
2510use axum::{Router, routing::post};
2511fn router() {
2512    Router::new().route(
2513        "/api//orders/",
2514        post(create_order),
2515    );
2516}
2517"#;
2518        let result = parse_rust_source(source);
2519
2520        assert!(matches!(
2521            result.as_slice(),
2522            [item]
2523                if item.framework == SourceFramework::Axum
2524                    && item.role == SourceRole::Provider
2525                    && item.method.as_deref() == Some("POST")
2526                    && item.path.as_deref() == Some("/api/orders")
2527                    && item.symbol_name.as_deref() == Some("create_order")
2528                    && item.lines.start == 4
2529                    && item.lines.end == 7
2530        ));
2531    }
2532
2533    #[test]
2534    fn actix_attributes_should_extract_direct_and_route_methods() {
2535        let source = r#"
2536use actix_web::{get, route};
2537#[get("/health")]
2538async fn health() {}
2539#[route(
2540    "/orders",
2541    method = "POST",
2542)]
2543async fn create() {}
2544"#;
2545        let result = parse_rust_source(source);
2546
2547        assert_eq!(
2548            result
2549                .iter()
2550                .map(|item| (item.method.as_deref(), item.path.as_deref()))
2551                .collect::<Vec<_>>(),
2552            vec![
2553                (Some("GET"), Some("/health")),
2554                (Some("POST"), Some("/orders"))
2555            ]
2556        );
2557    }
2558
2559    #[test]
2560    fn actix_builder_should_require_web_route_evidence() {
2561        let source = r#"
2562use actix_web::{web, App};
2563fn app() {
2564    App::new().route("/users", web::put().to(update_user));
2565    App::new().service(
2566        web::resource("/orders").route(web::post().to(create_order)),
2567    );
2568}
2569"#;
2570        let result = parse_rust_source(source);
2571
2572        assert_eq!(
2573            result
2574                .iter()
2575                .map(|item| (
2576                    item.framework,
2577                    item.method.as_deref(),
2578                    item.symbol_name.as_deref()
2579                ))
2580                .collect::<Vec<_>>(),
2581            vec![
2582                (SourceFramework::ActixWeb, Some("PUT"), Some("update_user")),
2583                (
2584                    SourceFramework::ActixWeb,
2585                    Some("POST"),
2586                    Some("create_order")
2587                ),
2588            ]
2589        );
2590    }
2591
2592    #[test]
2593    fn utoipa_should_extract_explicit_and_contextual_actix_paths() {
2594        let source = r#"
2595use actix_web::{get, post};
2596
2597#[cfg_attr(feature = "openapi", utoipa::path(post, path = "/api/orders"))]
2598#[post("/orders")]
2599async fn create_order() {}
2600
2601#[cfg_attr(feature = "openapi", utoipa::path(
2602    get,
2603    context_path = "/api/users"
2604))]
2605#[get("/{id}")]
2606async fn get_user() {}
2607"#;
2608        let result = parse_rust_source(source);
2609
2610        assert!(result.iter().any(|item| {
2611            item.framework == SourceFramework::Utoipa
2612                && item.symbol_name.as_deref() == Some("create_order")
2613                && item.method.as_deref() == Some("POST")
2614                && item.path.as_deref() == Some("/api/orders")
2615        }));
2616        assert!(result.iter().any(|item| {
2617            item.framework == SourceFramework::Utoipa
2618                && item.symbol_name.as_deref() == Some("get_user")
2619                && item.method.as_deref() == Some("GET")
2620                && item.path.as_deref() == Some("/api/users/{id}")
2621        }));
2622        assert!(result.iter().any(|item| {
2623            item.framework == SourceFramework::ActixWeb
2624                && item.symbol_name.as_deref() == Some("create_order")
2625                && item.path.as_deref() == Some("/orders")
2626                && (item.confidence - 1.0).abs() < f32::EPSILON
2627        }));
2628        assert!(result.iter().any(|item| {
2629            item.framework == SourceFramework::Utoipa
2630                && item.symbol_name.as_deref() == Some("create_order")
2631                && (item.confidence - 0.75).abs() < f32::EPSILON
2632                && item.warnings.contains(&SourceWarning::AdvisoryDeclaration)
2633        }));
2634    }
2635
2636    #[test]
2637    fn reqwest_should_extract_convenience_client_and_request_calls() {
2638        let source = r#"
2639use reqwest::{Client, Method};
2640async fn send() {
2641    reqwest::get("https://example.test/health?full=1").await;
2642    reqwest::blocking::get("https://example.test/ready");
2643    let client = Client::new();
2644    client.post("/orders").send().await;
2645    client.request(Method::DELETE, "https://example.test/orders/7").send().await;
2646}
2647"#;
2648        let result = parse_rust_source(source);
2649
2650        assert_eq!(
2651            result
2652                .iter()
2653                .map(|item| (item.method.as_deref(), item.path.as_deref()))
2654                .collect::<Vec<_>>(),
2655            vec![
2656                (Some("GET"), Some("/health")),
2657                (Some("GET"), Some("/ready")),
2658                (Some("POST"), Some("/orders")),
2659                (Some("DELETE"), Some("/orders/7")),
2660            ]
2661        );
2662    }
2663
2664    #[test]
2665    fn reqwest_should_recognize_injected_client_parameters() {
2666        let source = r#"
2667use reqwest::Client;
2668async fn synchronize(client: &Client, qualified: &reqwest::Client) {
2669    client.post("https://orders.test/v1/orders").send().await;
2670    qualified.get("https://payments.test/v1/payments").send().await;
2671}
2672"#;
2673        let result = parse_rust_source(source);
2674
2675        assert_eq!(
2676            result
2677                .iter()
2678                .map(|item| (item.method.as_deref(), item.path.as_deref()))
2679                .collect::<Vec<_>>(),
2680            vec![
2681                (Some("POST"), Some("/v1/orders")),
2682                (Some("GET"), Some("/v1/payments")),
2683            ]
2684        );
2685    }
2686
2687    #[test]
2688    fn reqwest_should_preserve_explicit_lifetimes_in_client_parameters() {
2689        let source = r#"
2690use reqwest::Client;
2691async fn synchronize<'request>(client: &'request Client) {
2692    client.post("https://orders.test/v1/orders").send().await;
2693}
2694"#;
2695        let result = parse_rust_source(source);
2696
2697        assert!(result.iter().any(|item| {
2698            item.framework == SourceFramework::Reqwest
2699                && item.method.as_deref() == Some("POST")
2700                && item.path.as_deref() == Some("/v1/orders")
2701        }));
2702    }
2703
2704    #[test]
2705    fn absolute_consumer_url_should_require_an_explicit_authority_mapping() {
2706        let source = r#"
2707use reqwest::Client;
2708async fn synchronize(client: &Client) {
2709    client.get("https://third-party.example/health").send().await;
2710    client.get("/internal-health").send().await;
2711}
2712"#;
2713        let result = parse_rust_source(source);
2714        let external = result
2715            .iter()
2716            .find(|item| item.path.as_deref() == Some("/health"))
2717            .expect("absolute call");
2718        let internal = result
2719            .iter()
2720            .find(|item| item.path.as_deref() == Some("/internal-health"))
2721            .expect("relative call");
2722
2723        assert_eq!(external.status, SourceEpistemicStatus::Ambiguous);
2724        assert_eq!(external.warnings, [SourceWarning::UnmappedAuthority]);
2725        assert_eq!(internal.status, SourceEpistemicStatus::Confirmed);
2726    }
2727
2728    #[test]
2729    fn reqwest_should_recognize_builder_chains_and_typed_self_fields() {
2730        let source = r#"
2731use reqwest::Client;
2732use std::time::Duration;
2733
2734struct Api {
2735    client: Client,
2736}
2737
2738impl Api {
2739    fn new() -> Self {
2740        let client = Client::builder()
2741            .timeout(Duration::from_secs(5))
2742            .build()
2743            .expect("valid client configuration");
2744        Self { client }
2745    }
2746
2747    async fn synchronize(&self) {
2748        self.client.get("https://inventory.test/v1/inventory").send().await;
2749    }
2750}
2751"#;
2752        let result = parse_rust_source(source);
2753
2754        assert!(matches!(
2755            result.as_slice(),
2756            [observation]
2757                if observation.method.as_deref() == Some("GET")
2758                    && observation.path.as_deref() == Some("/v1/inventory")
2759        ));
2760    }
2761
2762    #[test]
2763    fn unrelated_grouped_import_should_not_promote_client_to_reqwest() {
2764        let source = r#"
2765use my_http::{reqwest, Client};
2766async fn diagnostic() {
2767    let client = Client::new();
2768    client.get("https://inventory.test/v1/diagnostic");
2769}
2770"#;
2771        let result = parse_rust_source(source);
2772
2773        assert_eq!(result.len(), 0);
2774    }
2775
2776    #[test]
2777    fn reqwest_should_not_reuse_receiver_names_across_functions() {
2778        let source = r#"
2779use reqwest::Client;
2780struct FakeClient;
2781impl FakeClient { fn get(&self, _path: &str) {} }
2782fn local_only(client: &FakeClient) {
2783    client.get("https://inventory.test/v1/diagnostic");
2784}
2785async fn remote() {
2786    let client = Client::new();
2787    client.get("https://inventory.test/v1/inventory").send().await;
2788}
2789"#;
2790        let result = parse_rust_source(source);
2791
2792        assert_eq!(result.len(), 1);
2793        assert_eq!(result[0].path.as_deref(), Some("/v1/inventory"));
2794    }
2795
2796    #[test]
2797    fn reqwest_import_should_not_leak_across_inline_modules() {
2798        let source = r#"
2799mod real { use reqwest::Client; }
2800mod fake {
2801    struct Client;
2802    impl Client { fn get(&self, _path: &str) {} }
2803    fn probe(client: &Client) { client.get("/health"); }
2804}
2805"#;
2806
2807        assert_eq!(parse_rust_source(source), []);
2808    }
2809
2810    #[test]
2811    fn top_level_reqwest_import_should_survive_an_inline_test_module() {
2812        let source = r#"
2813use reqwest::Client;
2814async fn probe() {
2815    let client = Client::new();
2816    client.get("/health").send().await;
2817}
2818#[cfg(test)] mod tests { fn smoke() {} }
2819"#;
2820
2821        assert!(parse_rust_source(source).iter().any(|item| {
2822            item.framework == SourceFramework::Reqwest && item.path.as_deref() == Some("/health")
2823        }));
2824    }
2825
2826    #[test]
2827    fn reqwest_import_inside_inline_module_should_remain_visible_locally() {
2828        let source = r#"
2829mod api {
2830    use reqwest::Client as HttpClient;
2831    async fn probe() {
2832        let client = HttpClient::new();
2833        client.get("/health").send().await;
2834    }
2835}
2836"#;
2837
2838        assert!(parse_rust_source(source).iter().any(|item| {
2839            item.framework == SourceFramework::Reqwest && item.path.as_deref() == Some("/health")
2840        }));
2841    }
2842
2843    #[test]
2844    fn reqwest_self_fields_should_not_leak_across_sibling_modules() {
2845        let source = r#"
2846mod real {
2847    use reqwest::Client;
2848    struct Api { client: Client }
2849    impl Api {
2850        async fn probe(&self) { self.client.get("/real").send().await; }
2851    }
2852}
2853mod fake {
2854    struct Client;
2855    impl Client { fn get(&self, _path: &str) {} }
2856    struct Api { client: Client }
2857    impl Api {
2858        fn probe(&self) { self.client.get("/fake"); }
2859    }
2860}
2861"#;
2862
2863        let result = parse_rust_source(source);
2864        assert_eq!(result.len(), 1);
2865        assert_eq!(result[0].path.as_deref(), Some("/real"));
2866    }
2867
2868    #[test]
2869    fn reqwest_should_respect_lexical_shadowing() {
2870        let source = r#"
2871use reqwest::Client;
2872struct FakeClient;
2873impl FakeClient { fn get(&self, _path: &str) {} }
2874async fn synchronize() {
2875    let client = Client::new();
2876    client.get("https://inventory.test/v1/inventory").send().await;
2877    {
2878        let client = FakeClient;
2879        client.get("https://inventory.test/v1/diagnostic");
2880    }
2881    client.get("https://payments.test/v1/payments").send().await;
2882}
2883"#;
2884        let result = parse_rust_source(source);
2885
2886        assert_eq!(
2887            result
2888                .iter()
2889                .map(|item| item.path.as_deref())
2890                .collect::<Vec<_>>(),
2891            vec![Some("/v1/inventory"), Some("/v1/payments")]
2892        );
2893    }
2894
2895    #[test]
2896    fn reqwest_should_not_promote_wrappers_that_consume_a_client() {
2897        let source = r#"
2898use reqwest::Client;
2899struct FakeClient;
2900impl FakeClient {
2901    fn new(_client: Client) -> Self { Self }
2902    fn get(&self, _path: &str) {}
2903}
2904async fn diagnostic() {
2905    let fake = FakeClient::new(Client::new());
2906    fake.get("https://inventory.test/v1/diagnostic");
2907}
2908"#;
2909        let result = parse_rust_source(source);
2910
2911        assert_eq!(result.len(), 0);
2912    }
2913
2914    #[test]
2915    fn reqwest_should_recognize_import_aliases_and_exact_type_annotations() {
2916        let source = r#"
2917use reqwest::Client as HttpClient;
2918async fn synchronize(injected: &HttpClient) {
2919    let constructed: HttpClient = factory();
2920    injected.get("https://inventory.test/v1/inventory").send().await;
2921    constructed.post("https://orders.test/v1/orders").send().await;
2922}
2923"#;
2924        let result = parse_rust_source(source);
2925
2926        assert_eq!(
2927            result
2928                .iter()
2929                .map(|item| (item.method.as_deref(), item.path.as_deref()))
2930                .collect::<Vec<_>>(),
2931            vec![
2932                (Some("GET"), Some("/v1/inventory")),
2933                (Some("POST"), Some("/v1/orders")),
2934            ]
2935        );
2936    }
2937
2938    #[test]
2939    fn reqwest_should_recognize_blocking_clients_and_generic_self_fields() {
2940        let source = r#"
2941use reqwest::blocking::Client as BlockingClient;
2942use reqwest::blocking::{Client as GroupedClient, Response};
2943struct Api<T> { client: BlockingClient, marker: T }
2944impl<T> Api<T> {
2945    fn synchronize(&self) {
2946        self.client.get("https://inventory.test/v1/inventory").send();
2947    }
2948}
2949fn qualified() {
2950    let client = reqwest::blocking::Client::new();
2951    client.post("https://orders.test/v1/orders").send();
2952}
2953fn grouped() {
2954    let client = GroupedClient::new();
2955    client.delete("https://orders.test/v1/obsolete").send();
2956}
2957"#;
2958        let result = parse_rust_source(source);
2959
2960        assert_eq!(result.len(), 3);
2961        assert!(
2962            result
2963                .iter()
2964                .any(|item| item.path.as_deref() == Some("/v1/inventory"))
2965        );
2966        assert!(
2967            result
2968                .iter()
2969                .any(|item| item.path.as_deref() == Some("/v1/orders"))
2970        );
2971        assert!(
2972            result
2973                .iter()
2974                .any(|item| item.path.as_deref() == Some("/v1/obsolete"))
2975        );
2976    }
2977
2978    #[test]
2979    fn reqwest_should_recognize_exact_local_type_aliases() {
2980        let source = r#"
2981use reqwest::Client as HttpClient;
2982type ServiceClient = HttpClient;
2983async fn synchronize(client: &ServiceClient) {
2984    client.get("https://inventory.test/v1/inventory").send().await;
2985}
2986"#;
2987        let result = parse_rust_source(source);
2988
2989        assert!(matches!(
2990            result.as_slice(),
2991            [observation]
2992                if observation.method.as_deref() == Some("GET")
2993                    && observation.path.as_deref() == Some("/v1/inventory")
2994        ));
2995    }
2996
2997    #[test]
2998    fn reqwest_should_track_braced_typed_closure_parameters() {
2999        let source = r#"
3000use reqwest::Client;
3001async fn synchronize() {
3002    let operation = |client: &Client| {
3003        client.get("https://inventory.test/v1/inventory");
3004    };
3005}
3006"#;
3007        let result = parse_rust_source(source);
3008
3009        assert!(matches!(
3010            result.as_slice(),
3011            [observation] if observation.path.as_deref() == Some("/v1/inventory")
3012        ));
3013    }
3014
3015    #[test]
3016    fn reqwest_should_treat_destructuring_as_lexical_shadowing() {
3017        let source = r#"
3018use reqwest::Client;
3019struct FakeClient;
3020impl FakeClient { fn get(&self, _path: &str) {} }
3021async fn synchronize(client: &Client, pair: (FakeClient, usize)) {
3022    let (client, _value) = pair;
3023    client.get("https://inventory.test/v1/diagnostic");
3024}
3025"#;
3026        let result = parse_rust_source(source);
3027
3028        assert_eq!(result.len(), 0);
3029    }
3030
3031    #[test]
3032    fn reqwest_should_conservatively_handle_binding_reassignment() {
3033        let source = r#"
3034use reqwest::Client;
3035async fn synchronize() {
3036    let mut client = Client::new();
3037    client = factory();
3038    client.get("https://inventory.test/v1/unknown");
3039    client = Client::new();
3040    client.get("https://inventory.test/v1/inventory");
3041}
3042"#;
3043        let result = parse_rust_source(source);
3044
3045        assert_eq!(
3046            result
3047                .iter()
3048                .map(|item| item.path.as_deref())
3049                .collect::<Vec<_>>(),
3050            vec![Some("/v1/inventory")]
3051        );
3052    }
3053
3054    #[test]
3055    fn rust_test_attributes_should_cover_builtin_tokio_and_rstest() {
3056        let source = r"
3057#[test]
3058fn plain() {}
3059#[tokio::test]
3060async fn asynchronous() {}
3061#[rstest]
3062#[case(1)]
3063fn parameterized(#[case] value: u8) {}
3064";
3065        let result = parse_rust_source(source);
3066
3067        assert_eq!(
3068            result
3069                .iter()
3070                .map(|item| (item.framework, item.symbol_name.as_deref()))
3071                .collect::<Vec<_>>(),
3072            vec![
3073                (SourceFramework::RustTest, Some("plain")),
3074                (SourceFramework::TokioTest, Some("asynchronous")),
3075                (SourceFramework::Rstest, Some("parameterized")),
3076            ]
3077        );
3078    }
3079
3080    #[test]
3081    fn rust_dynamic_route_should_never_claim_exact_path() {
3082        let source = r"
3083use axum::{Router, routing::get};
3084fn router(path: &str) {
3085    Router::new().route(path, get(handler));
3086}
3087";
3088        let result = parse_rust_source(source);
3089
3090        assert!(matches!(
3091            result.as_slice(),
3092            [item]
3093                if item.path.is_none()
3094                    && item.status == SourceEpistemicStatus::Ambiguous
3095                    && item.warnings == [SourceWarning::DynamicPath]
3096        ));
3097    }
3098
3099    #[test]
3100    fn rust_comments_strings_and_unrelated_route_methods_should_be_ignored() {
3101        let source = r##"
3102// use axum; Router::new().route("/fake", get(fake));
3103const TEXT: &str = r#"reqwest::get("https://example.test/fake")"#;
3104struct Router;
3105impl Router {
3106    fn route(&self, path: &str, handler: usize) {}
3107}
3108fn ordinary() {
3109    Router.route("/fake", handler);
3110}
3111"##;
3112        let result = parse_rust_source(source);
3113
3114        assert_eq!(result, Vec::new());
3115    }
3116
3117    #[test]
3118    fn fastapi_should_extract_method_and_api_route_decorators() {
3119        let source = r#"
3120from fastapi import FastAPI
3121app = FastAPI()
3122@app.get("/users/{user_id}")
3123async def get_user(user_id: str):
3124    pass
3125@app.api_route(
3126    "/orders",
3127    methods=["POST", "PUT"],
3128)
3129def orders():
3130    pass
3131"#;
3132        let result = parse_python_source(source);
3133
3134        assert_eq!(
3135            result
3136                .iter()
3137                .filter(|item| item.role == SourceRole::Provider)
3138                .map(|item| (item.method.as_deref(), item.path.as_deref()))
3139                .collect::<Vec<_>>(),
3140            vec![
3141                (Some("GET"), Some("/users/{user_id}")),
3142                (Some("POST"), Some("/orders")),
3143                (Some("PUT"), Some("/orders")),
3144            ]
3145        );
3146    }
3147
3148    #[test]
3149    fn fastapi_should_compose_static_router_prefixes() {
3150        let source = r#"
3151from fastapi import APIRouter
3152router = APIRouter(prefix="/api/v1/projects")
3153
3154@router.get("/{project_id}")
3155async def get_project(project_id: int):
3156    pass
3157"#;
3158        let result = parse_python_source(source);
3159
3160        assert!(result.iter().any(|item| {
3161            item.framework == SourceFramework::FastApi
3162                && item.method.as_deref() == Some("GET")
3163                && item.path.as_deref() == Some("/api/v1/projects/{project_id}")
3164                && item.symbol_name.as_deref() == Some("get_project")
3165        }));
3166    }
3167
3168    #[test]
3169    fn flask_should_extract_default_and_explicit_methods() {
3170        let source = r#"
3171from flask import Flask
3172app = Flask(__name__)
3173@app.route("/health")
3174def health():
3175    pass
3176@app.route(
3177    "/orders",
3178    methods=["POST", "DELETE"],
3179)
3180def orders():
3181    pass
3182"#;
3183        let result = parse_python_source(source);
3184
3185        assert_eq!(
3186            result
3187                .iter()
3188                .filter(|item| item.role == SourceRole::Provider)
3189                .map(|item| item.method.as_deref())
3190                .collect::<Vec<_>>(),
3191            vec![Some("GET"), Some("DELETE"), Some("POST")]
3192        );
3193    }
3194
3195    #[test]
3196    fn flask_should_resolve_instance_app_and_static_path_concatenation() {
3197        let source = r#"
3198from flask import Flask
3199URL = "/servers/remitee"
3200
3201class Remitee:
3202    def __init__(self):
3203        self.app = Flask(__name__)
3204
3205    def setup_routes(self):
3206        @self.app.route(URL + "/api/Payments/<payment_id>", methods=["GET"])
3207        def payment(payment_id):
3208            pass
3209"#;
3210        let result = parse_python_source(source);
3211
3212        assert!(result.iter().any(|item| {
3213            item.framework == SourceFramework::Flask
3214                && item.role == SourceRole::Provider
3215                && item.method.as_deref() == Some("GET")
3216                && item.path.as_deref() == Some("/servers/remitee/api/Payments/<payment_id>")
3217        }));
3218    }
3219
3220    #[test]
3221    fn python_http_registry_should_flatten_nested_static_operations() {
3222        let source = r#"
3223METHODS = {
3224    "public": ("/api/v1", {
3225        "accounts": ("/accounts", {
3226            "get_accounts": ["GET", ""],
3227            "get_account": ["GET", "/{{accounts_id}}"],
3228        }),
3229    }),
3230}
3231"#;
3232        let result = parse_python_source(source);
3233        let operations = result
3234            .iter()
3235            .filter(|item| item.framework == SourceFramework::PythonHttpRegistry)
3236            .map(|item| (item.method.as_deref(), item.path.as_deref()))
3237            .collect::<Vec<_>>();
3238
3239        assert_eq!(
3240            operations,
3241            vec![
3242                (Some("GET"), Some("/api/v1/accounts")),
3243                (Some("GET"), Some("/api/v1/accounts/{accounts_id}")),
3244            ]
3245        );
3246    }
3247
3248    #[test]
3249    fn factory_boy_should_link_factory_to_imported_model() {
3250        let source = r"
3251import factory
3252from src.clases.Account import Account
3253
3254class AccountFactory(factory.Factory):
3255    class Meta:
3256        model = Account
3257";
3258        let result = parse_python_source(source);
3259
3260        assert!(result.iter().any(|item| {
3261            item.framework == SourceFramework::FactoryBoy
3262                && item.role == SourceRole::Factory
3263                && item.symbol_name.as_deref() == Some("AccountFactory")
3264                && item.related_symbol.as_deref() == Some("Account")
3265                && item.related_path.as_deref() == Some("src/clases/Account.py")
3266                && item.status == SourceEpistemicStatus::Confirmed
3267        }));
3268    }
3269
3270    #[test]
3271    fn requests_should_extract_module_alias_and_session_calls() {
3272        let source = r#"
3273import requests as rq
3274from requests import Session, post as create
3275def send():
3276    rq.get("https://example.test/status")
3277    create("/orders")
3278    session = Session()
3279    session.request("PATCH", "/orders/4")
3280"#;
3281        let result = parse_python_source(source);
3282
3283        assert_eq!(
3284            result
3285                .iter()
3286                .map(|item| (item.framework, item.method.as_deref(), item.path.as_deref()))
3287                .collect::<Vec<_>>(),
3288            vec![
3289                (SourceFramework::Requests, Some("GET"), Some("/status")),
3290                (SourceFramework::Requests, Some("POST"), Some("/orders")),
3291                (SourceFramework::Requests, Some("PATCH"), Some("/orders/4")),
3292            ]
3293        );
3294    }
3295
3296    #[test]
3297    fn aiohttp_should_extract_client_session_context_calls() {
3298        let source = r#"
3299from aiohttp import ClientSession
3300
3301async def load():
3302    async with ClientSession() as session:
3303        await session.get("/accounts")
3304"#;
3305        let result = parse_python_source(source);
3306
3307        assert!(result.iter().any(|item| {
3308            item.framework == SourceFramework::AioHttp
3309                && item.role == SourceRole::Consumer
3310                && item.method.as_deref() == Some("GET")
3311                && item.path.as_deref() == Some("/accounts")
3312        }));
3313    }
3314
3315    #[test]
3316    fn httpx_should_extract_module_sync_and_async_clients() {
3317        let source = r#"
3318import httpx
3319from httpx import AsyncClient, patch as update
3320def direct():
3321    httpx.delete("https://example.test/items/1")
3322    update("/items/1")
3323async def clients():
3324    client = AsyncClient()
3325    client.put("/items/1")
3326"#;
3327        let result = parse_python_source(source);
3328
3329        assert_eq!(
3330            result
3331                .iter()
3332                .map(|item| (item.framework, item.method.as_deref()))
3333                .collect::<Vec<_>>(),
3334            vec![
3335                (SourceFramework::Httpx, Some("DELETE")),
3336                (SourceFramework::Httpx, Some("PATCH")),
3337                (SourceFramework::Httpx, Some("PUT")),
3338            ]
3339        );
3340    }
3341
3342    #[test]
3343    fn python_tests_should_distinguish_pytest_and_unittest() {
3344        let source = r"
3345import unittest
3346def test_pytest_case():
3347    pass
3348class ApiTests(unittest.TestCase):
3349    def test_unittest_case(self):
3350        pass
3351";
3352        let result = parse_python_source(source);
3353
3354        assert_eq!(
3355            result
3356                .iter()
3357                .map(|item| (item.framework, item.symbol_name.as_deref()))
3358                .collect::<Vec<_>>(),
3359            vec![
3360                (SourceFramework::Pytest, Some("test_pytest_case")),
3361                (SourceFramework::Unittest, Some("test_unittest_case")),
3362            ]
3363        );
3364    }
3365
3366    #[test]
3367    fn indirect_python_test_class_should_preserve_generic_test_evidence() {
3368        let source = r#"
3369import requests
3370
3371class PaymentCases(SharedTestBase):
3372    def test_payment(self):
3373        requests.post("/payments")
3374"#;
3375        let result = parse_python_source(source);
3376
3377        assert!(result.iter().any(|item| {
3378            item.framework == SourceFramework::PythonTest
3379                && item.role == SourceRole::Test
3380                && item.symbol_name.as_deref() == Some("test_payment")
3381        }));
3382        assert!(result.iter().any(|item| {
3383            item.framework == SourceFramework::Requests
3384                && item.role == SourceRole::Consumer
3385                && item.symbol_name.as_deref() == Some("test_payment")
3386                && item.path.as_deref() == Some("/payments")
3387        }));
3388    }
3389
3390    #[test]
3391    fn python_dynamic_url_and_method_should_remain_explicitly_incomplete() {
3392        let source = r"
3393import httpx
3394def send(method, base, path):
3395    httpx.request(method, base + path)
3396";
3397        let result = parse_python_source(source);
3398
3399        assert!(matches!(
3400            result.as_slice(),
3401            [item]
3402                if item.method.is_none()
3403                    && item.path.is_none()
3404                    && item.status == SourceEpistemicStatus::Incomplete
3405                    && item.warnings
3406                        == [SourceWarning::DynamicMethod, SourceWarning::DynamicPath]
3407        ));
3408    }
3409
3410    #[test]
3411    fn python_f_strings_should_be_dynamic_not_exact() {
3412        let source = r#"
3413import requests
3414def fetch(user_id):
3415    requests.get(f"https://example.test/users/{user_id}")
3416"#;
3417        let result = parse_python_source(source);
3418
3419        assert!(matches!(
3420            result.as_slice(),
3421            [item]
3422                if item.path.is_none()
3423                    && item.status == SourceEpistemicStatus::Ambiguous
3424                    && item.warnings == [SourceWarning::DynamicPath]
3425        ));
3426    }
3427
3428    #[test]
3429    fn python_comments_docstrings_and_unknown_clients_should_be_ignored() {
3430        let source = r#"
3431"""@app.get("/fake")
3432def test_fake(): pass
3433requests.get("https://example.test/fake")
3434"""
3435# import requests
3436# requests.post("/fake")
3437class Client:
3438    def get(self, path):
3439        pass
3440client = Client()
3441client.get("/not-httpx")
3442"#;
3443        let result = parse_python_source(source);
3444
3445        assert_eq!(result, Vec::new());
3446    }
3447
3448    #[test]
3449    fn ordering_should_be_source_stable_and_independent_of_method_list_order() {
3450        let source = r#"
3451from fastapi import FastAPI
3452app = FastAPI()
3453@app.api_route("/z", methods=["PUT", "GET", "POST"])
3454def endpoint():
3455    pass
3456"#;
3457        let first = parse_python_source(source);
3458        let second = parse_python_source(source);
3459
3460        assert_eq!(
3461            (
3462                first
3463                    .iter()
3464                    .map(|item| item.method.as_deref())
3465                    .collect::<Vec<_>>(),
3466                &first
3467            ),
3468            ((vec![Some("GET"), Some("POST"), Some("PUT")]), &second)
3469        );
3470    }
3471}