Skip to main content

symforge/domain/
index.rs

1use std::collections::HashMap;
2use std::fmt;
3
4#[derive(
5    Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, serde::Serialize, serde::Deserialize,
6)]
7pub enum LanguageId {
8    Rust,
9    Python,
10    JavaScript,
11    TypeScript,
12    Go,
13    Java,
14    C,
15    Cpp,
16    CSharp,
17    Ruby,
18    Php,
19    Swift,
20    Kotlin,
21    Dart,
22    Perl,
23    Elixir,
24    Json,
25    Toml,
26    Yaml,
27    Markdown,
28    Env,
29    Html,
30    Css,
31    Scss,
32}
33
34impl LanguageId {
35    pub fn from_extension(ext: &str) -> Option<Self> {
36        match ext {
37            "rs" => Some(Self::Rust),
38            "py" => Some(Self::Python),
39            "js" | "jsx" => Some(Self::JavaScript),
40            "ts" | "tsx" => Some(Self::TypeScript),
41            "go" => Some(Self::Go),
42            "java" => Some(Self::Java),
43            "c" | "h" => Some(Self::C),
44            "cpp" | "cxx" | "cc" | "hpp" | "hxx" | "hh" => Some(Self::Cpp),
45            "cs" => Some(Self::CSharp),
46            "rb" => Some(Self::Ruby),
47            "php" => Some(Self::Php),
48            "swift" => Some(Self::Swift),
49            "dart" => Some(Self::Dart),
50            "kt" | "kts" => Some(Self::Kotlin),
51            "pl" | "pm" => Some(Self::Perl),
52            "ex" | "exs" => Some(Self::Elixir),
53            "json" => Some(Self::Json),
54            "toml" => Some(Self::Toml),
55            "yaml" | "yml" => Some(Self::Yaml),
56            "md" => Some(Self::Markdown),
57            "env" => Some(Self::Env),
58            "html" => Some(Self::Html),
59            "css" => Some(Self::Css),
60            "scss" => Some(Self::Scss),
61            _ => None,
62        }
63    }
64
65    /// Returns `true` when `relative_path` is a TSX source file (`.tsx`).
66    ///
67    /// `.tsx` and `.ts` both map to [`LanguageId::TypeScript`], but they require
68    /// different tree-sitter grammars: `.tsx` needs the TSX grammar (JSX-aware,
69    /// rejects legacy `<T>expr` casts) while `.ts` needs the plain TypeScript
70    /// grammar (no JSX, accepts angle-bracket casts). The grammar is therefore
71    /// selected from the file extension, not the [`LanguageId`], so this helper
72    /// threads the TSX flavor to the parse sites.
73    pub fn is_tsx_path(relative_path: &str) -> bool {
74        relative_path
75            .rsplit(['/', '\\'])
76            .next()
77            .and_then(|name| name.rsplit_once('.'))
78            .is_some_and(|(_, ext)| ext.eq_ignore_ascii_case("tsx"))
79    }
80
81    /// Returns `true` when `relative_path` is a `.h` header file.
82    ///
83    /// `.h` maps to [`LanguageId::C`] by extension, but in cross-platform repos
84    /// it routinely holds C++ (`class`/`namespace`/`::`) or Objective-C
85    /// (`@interface`/`@property`) — none of which the C grammar can parse,
86    /// causing total symbol loss (SF-STRESS-005). The grammar for a `.h` file is
87    /// therefore disambiguated from CONTENT at parse time (see
88    /// [`crate::parsing`]), not from the extension alone; this helper flags the
89    /// `.h` extension so the parse site knows to apply that disambiguation.
90    ///
91    /// Unambiguous C++ header extensions (`.hpp`/`.hxx`/`.hh`) already map to
92    /// [`LanguageId::Cpp`] and are NOT `.h`, so they are not flagged here.
93    pub fn is_c_header_path(relative_path: &str) -> bool {
94        relative_path
95            .rsplit(['/', '\\'])
96            .next()
97            .and_then(|name| name.rsplit_once('.'))
98            .is_some_and(|(_, ext)| ext.eq_ignore_ascii_case("h"))
99    }
100
101    pub fn extensions(&self) -> &[&str] {
102        match self {
103            Self::Rust => &["rs"],
104            Self::Python => &["py"],
105            Self::JavaScript => &["js", "jsx"],
106            Self::TypeScript => &["ts", "tsx"],
107            Self::Go => &["go"],
108            Self::Java => &["java"],
109            Self::C => &["c", "h"],
110            Self::Cpp => &["cpp", "cxx", "cc", "hpp", "hxx", "hh"],
111            Self::CSharp => &["cs"],
112            Self::Ruby => &["rb"],
113            Self::Php => &["php"],
114            Self::Swift => &["swift"],
115            Self::Kotlin => &["kt", "kts"],
116            Self::Dart => &["dart"],
117            Self::Perl => &["pl", "pm"],
118            Self::Elixir => &["ex", "exs"],
119            Self::Json => &["json"],
120            Self::Toml => &["toml"],
121            Self::Yaml => &["yaml", "yml"],
122            Self::Markdown => &["md"],
123            Self::Env => &["env"],
124            Self::Html => &["html"],
125            Self::Css => &["css"],
126            Self::Scss => &["scss"],
127        }
128    }
129
130    pub fn support_tier(&self) -> SupportTier {
131        match self {
132            Self::Rust | Self::Python | Self::JavaScript | Self::TypeScript | Self::Go => {
133                SupportTier::QualityFocus
134            }
135            Self::Java
136            | Self::C
137            | Self::Cpp
138            | Self::CSharp
139            | Self::Ruby
140            | Self::Php
141            | Self::Swift
142            | Self::Kotlin
143            | Self::Dart
144            | Self::Perl
145            | Self::Elixir
146            | Self::Json
147            | Self::Toml
148            | Self::Yaml
149            | Self::Markdown
150            | Self::Env
151            | Self::Html
152            | Self::Css
153            | Self::Scss => SupportTier::Broader,
154        }
155    }
156}
157
158impl fmt::Display for LanguageId {
159    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
160        let name = match self {
161            Self::Rust => "Rust",
162            Self::Python => "Python",
163            Self::JavaScript => "JavaScript",
164            Self::TypeScript => "TypeScript",
165            Self::Go => "Go",
166            Self::Java => "Java",
167            Self::C => "C",
168            Self::Cpp => "C++",
169            Self::CSharp => "C#",
170            Self::Ruby => "Ruby",
171            Self::Php => "PHP",
172            Self::Swift => "Swift",
173            Self::Kotlin => "Kotlin",
174            Self::Dart => "Dart",
175            Self::Perl => "Perl",
176            Self::Elixir => "Elixir",
177            Self::Json => "JSON",
178            Self::Toml => "TOML",
179            Self::Yaml => "YAML",
180            Self::Markdown => "Markdown",
181            Self::Env => "Env",
182            Self::Html => "HTML",
183            Self::Css => "CSS",
184            Self::Scss => "SCSS",
185        };
186        write!(f, "{name}")
187    }
188}
189
190#[derive(Clone, Debug, PartialEq, Eq)]
191pub enum SupportTier {
192    QualityFocus,
193    Broader,
194    Unsupported,
195}
196
197#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
198pub enum FileClass {
199    Code,
200    Text,
201    Binary,
202}
203
204/// Canonical path-segment source of truth for noise classification, shared by
205/// [`FileClassification::for_code_path`] (gates search_symbols/search_text) and
206/// `NoiseClass::classify_path` (gates explore/repo_map/search_files) so the two
207/// classifiers cannot diverge (SF-STRESS-011). A segment is a single
208/// `/`-delimited path component, already lowercased.
209///
210/// Vendored / third-party dependency roots. `deps` and `extern`/`externals`
211/// added per SF-STRESS-011 corpus evidence (redis `deps/`, node `deps/`).
212pub const VENDOR_PATH_SEGMENTS: &[&str] = &[
213    "vendor",
214    "third_party",
215    "third-party",
216    "node_modules",
217    ".venv",
218    "venv",
219    "site-packages",
220    "pods",
221    "bower_components",
222    "deps",
223    "extern",
224    "externals",
225];
226
227/// Build-output / machine-generated directory roots. `dist` is shared here so
228/// `FileClassification` agrees with `NoiseClass` (previously `dist` lived only
229/// in `NoiseClass`, causing the laravel `dist/` divergence in SF-STRESS-011).
230pub const GENERATED_PATH_SEGMENTS: &[&str] =
231    &["dist", "generated", "__generated__", "generated-sources"];
232
233/// Test-directory roots. `test_data`/`testdata`/`fixtures`/`__fixtures__`/
234/// `__snapshots__` added per SF-STRESS-011 (rust-analyzer `test_data` fixtures,
235/// snapshot trees) and SF-STRESS-009 (test-fixture bucket).
236pub const TEST_PATH_SEGMENTS: &[&str] = &[
237    "tests",
238    "test",
239    "__tests__",
240    "spec",
241    "test_data",
242    "testdata",
243    "fixtures",
244    "__fixtures__",
245    "__snapshots__",
246];
247
248#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
249pub struct FileClassification {
250    pub class: FileClass,
251    pub is_generated: bool,
252    pub is_test: bool,
253    pub is_vendor: bool,
254    #[serde(default)]
255    pub is_config: bool,
256}
257
258impl FileClassification {
259    pub fn for_code_path(relative_path: &str) -> Self {
260        let lower = relative_path.replace('\\', "/").to_ascii_lowercase();
261        let segments: Vec<&str> = lower
262            .split('/')
263            .filter(|segment| !segment.is_empty())
264            .collect();
265        let basename = segments.last().copied().unwrap_or("");
266        let stem = basename
267            .rsplit_once('.')
268            .map(|(name, _)| name)
269            .unwrap_or(basename);
270
271        let is_test = segments
272            .iter()
273            .any(|segment| TEST_PATH_SEGMENTS.contains(segment))
274            || stem.starts_with("test_")
275            || stem.ends_with("_test")
276            || stem.ends_with(".test")
277            || stem.ends_with("_spec")
278            || stem.ends_with(".spec");
279
280        let is_vendor = segments
281            .iter()
282            .any(|segment| VENDOR_PATH_SEGMENTS.contains(segment));
283
284        let is_generated = segments
285            .iter()
286            .any(|segment| GENERATED_PATH_SEGMENTS.contains(segment))
287            || basename.contains(".generated.")
288            || basename.contains(".gen.")
289            || basename.ends_with(".g.dart")
290            || basename.ends_with(".pb.go")
291            || basename.ends_with(".designer.cs")
292            || basename.ends_with(".min.js")
293            || basename.ends_with(".min.css")
294            || basename.ends_with(".map");
295
296        let ext = basename.rsplit_once('.').map(|(_, e)| e).unwrap_or("");
297        let is_config = matches!(ext, "json" | "toml" | "yaml" | "yml" | "md" | "env");
298
299        Self {
300            class: FileClass::Code,
301            is_generated,
302            is_test,
303            is_vendor,
304            is_config,
305        }
306    }
307
308    pub const fn is_code(&self) -> bool {
309        matches!(self.class, FileClass::Code)
310    }
311
312    pub const fn is_text(&self) -> bool {
313        matches!(self.class, FileClass::Text)
314    }
315
316    pub const fn is_binary(&self) -> bool {
317        matches!(self.class, FileClass::Binary)
318    }
319}
320
321#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
322pub struct ParseDiagnostic {
323    pub parser: String,
324    pub message: String,
325    pub line: Option<u32>,
326    pub column: Option<u32>,
327    pub byte_span: Option<(u32, u32)>,
328    pub fallback_used: bool,
329}
330
331impl ParseDiagnostic {
332    pub fn location_display(&self) -> Option<String> {
333        match (self.line, self.column) {
334            (Some(line), Some(column)) => Some(format!("line {line}, column {column}")),
335            (Some(line), None) => Some(format!("line {line}")),
336            (None, Some(column)) => Some(format!("column {column}")),
337            (None, None) => None,
338        }
339    }
340
341    pub fn summary(&self) -> String {
342        let mut summary = format!("{}: {}", self.parser, self.message);
343        if let Some(location) = self.location_display() {
344            summary.push_str(&format!(" ({location})"));
345        }
346        if self.fallback_used {
347            summary.push_str(" [fallback symbol extraction used]");
348        }
349        summary
350    }
351}
352
353#[derive(Clone, Debug, PartialEq, Eq)]
354pub struct FileProcessingResult {
355    pub relative_path: String,
356    pub language: LanguageId,
357    pub classification: FileClassification,
358    pub outcome: FileOutcome,
359    pub parse_diagnostic: Option<ParseDiagnostic>,
360    pub symbols: Vec<SymbolRecord>,
361    pub byte_len: u64,
362    pub content_hash: String,
363    /// Cross-references extracted by `parsing::xref::extract_references`.
364    /// Empty until Task 2 wires xref extraction into the parse pipeline.
365    pub references: Vec<ReferenceRecord>,
366    /// Import alias map for this file: alias -> original name (e.g. "Map" -> "HashMap").
367    pub alias_map: HashMap<String, String>,
368}
369
370#[derive(Clone, Debug, PartialEq, Eq)]
371pub enum FileOutcome {
372    Processed,
373    PartialParse { warning: String },
374    Failed { error: String },
375}
376
377#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
378pub struct SymbolRecord {
379    pub name: String,
380    pub kind: SymbolKind,
381    pub depth: u32,
382    pub sort_order: u32,
383    pub byte_range: (u32, u32),
384    pub line_range: (u32, u32),
385    pub doc_byte_range: Option<(u32, u32)>,
386    #[serde(default)]
387    pub item_byte_range: Option<(u32, u32)>,
388}
389
390impl SymbolRecord {
391    /// Returns the start byte of the full editable item when available.
392    pub fn item_start(&self) -> u32 {
393        self.item_byte_range.map_or_else(
394            || {
395                self.doc_byte_range
396                    .map_or(self.byte_range.0, |(start, _)| start)
397            },
398            |(start, _)| start,
399        )
400    }
401
402    /// Returns the end byte of the full editable item when available.
403    pub fn item_end(&self) -> u32 {
404        self.item_byte_range
405            .map_or(self.byte_range.1, |(_, end)| end)
406    }
407
408    /// Returns the full editable item range when available.
409    pub fn item_range(&self) -> (u32, u32) {
410        (self.item_start(), self.item_end())
411    }
412
413    /// Returns the parser's core symbol node range.
414    pub fn core_range(&self) -> (u32, u32) {
415        self.byte_range
416    }
417
418    /// Returns the effective start byte, including doc comments if present.
419    pub fn effective_start(&self) -> u32 {
420        self.doc_byte_range
421            .map_or(self.byte_range.0, |(start, _)| start)
422    }
423}
424
425#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
426pub enum SymbolKind {
427    Function,
428    Method,
429    Class,
430    Struct,
431    Enum,
432    Interface,
433    Module,
434    Constant,
435    Variable,
436    Type,
437    Trait,
438    Impl,
439    Other,
440    Key,
441    Section,
442}
443
444impl fmt::Display for SymbolKind {
445    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
446        let prefix = match self {
447            Self::Function => "fn",
448            Self::Method => "fn",
449            Self::Class => "class",
450            Self::Struct => "struct",
451            Self::Enum => "enum",
452            Self::Interface => "interface",
453            Self::Module => "mod",
454            Self::Constant => "const",
455            Self::Variable => "let",
456            Self::Type => "type",
457            Self::Trait => "trait",
458            Self::Impl => "impl",
459            Self::Other => "other",
460            Self::Key => "key",
461            Self::Section => "section",
462        };
463        write!(f, "{prefix}")
464    }
465}
466
467/// A single cross-reference (call site, import, type usage, or macro use) extracted
468/// from a source file. Part of the Phase 4 cross-reference pipeline.
469#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
470pub struct ReferenceRecord {
471    /// Simple name at the reference site (e.g. "new", "process", "HashMap").
472    pub name: String,
473    /// Best-effort qualified name when available (e.g. "Vec::new", "fmt.Println").
474    pub qualified_name: Option<String>,
475    /// What kind of reference this is.
476    pub kind: ReferenceKind,
477    /// Byte range in the source file (start, end).
478    pub byte_range: (u32, u32),
479    /// Line range in the source file (start, end — zero-indexed).
480    pub line_range: (u32, u32),
481    /// Index into the file's symbol list for the innermost containing definition.
482    /// `None` means the reference is at module/top level.
483    pub enclosing_symbol_index: Option<u32>,
484}
485
486/// Discriminates the semantic role of a cross-reference.
487#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
488pub enum ReferenceKind {
489    /// A function or method call site.
490    Call,
491    /// An import/use/require statement.
492    Import,
493    /// A type annotation, generic parameter, or other type usage.
494    TypeUsage,
495    /// A macro invocation.
496    MacroUse,
497    /// A trait/interface implementation relationship.
498    /// `name` holds the trait/interface name, `qualified_name` holds the implementing type.
499    Implements,
500    /// A read of a named `const`/`static` value at a value-expression site
501    /// (e.g. iterated in a `for` loop, used as a receiver, or passed as a bare
502    /// argument). Distinct from `Call` so callee/type analysis stays clean.
503    ValueUse,
504}
505
506impl fmt::Display for ReferenceKind {
507    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
508        let s = match self {
509            Self::Call => "call",
510            Self::Import => "import",
511            Self::TypeUsage => "type_usage",
512            Self::MacroUse => "macro_use",
513            Self::Implements => "implements",
514            Self::ValueUse => "value_use",
515        };
516        write!(f, "{s}")
517    }
518}
519
520/// Returns the index of the innermost `SymbolRecord` whose `line_range` contains
521/// `ref_line`, or `None` if the reference is at module level.
522///
523/// "Innermost" is defined as the symbol with the latest `line_range.0` (start line)
524/// that still contains `ref_line`. This handles nested function definitions correctly.
525pub fn find_enclosing_symbol(symbols: &[SymbolRecord], ref_line: u32) -> Option<u32> {
526    let mut best: Option<(u32, u32)> = None; // (start_line, index)
527    for (idx, sym) in symbols.iter().enumerate() {
528        let (start, end) = sym.line_range;
529        if ref_line >= start && ref_line <= end {
530            match best {
531                None => best = Some((start, idx as u32)),
532                Some((best_start, _)) if start > best_start => best = Some((start, idx as u32)),
533                _ => {}
534            }
535        }
536    }
537    best.map(|(_, idx)| idx)
538}
539
540/// Admission tier — whether a file is eligible for indexing/parsing at all.
541/// Separate from NoiseClass (which is about ranking/filtering signal).
542#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
543pub enum AdmissionTier {
544    /// Tier 1: Fully indexed — parsed, symbols extracted, text searchable.
545    Normal,
546    /// Tier 2: Metadata only — path, size, classification stored. No parsing.
547    MetadataOnly,
548    /// Tier 3: Hard-skipped — counted in health, minimal registration.
549    HardSkip,
550}
551
552/// Reason a file was placed in Tier 2 or Tier 3.
553#[derive(Debug, Clone, Copy, PartialEq, Eq)]
554pub enum SkipReason {
555    SizeCeiling,
556    DenylistedExtension,
557    SizeThreshold,
558    BinaryContent,
559    /// File is a dependency lockfile (e.g. `package-lock.json`, `Cargo.lock`).
560    /// Demoted to Tier-2 metadata-only so its machine-generated content does not
561    /// flood the index with thousands of junk key/value symbols (a single
562    /// `package-lock.json` can mint ~9k JSON-key symbols, dominating symbol counts
563    /// and `conventions` complexity heuristics). The path stays searchable as
564    /// metadata; only symbol extraction is skipped. See `LOCKFILE_BASENAMES`.
565    DependencyLockfile,
566    /// SF-009: file demoted to Tier-2 because it is not git-tracked, under the
567    /// opt-in `SYMFORGE_EXCLUDE_UNTRACKED` policy (default OFF). Only minted when
568    /// that env gate is explicitly enabled; the default admission path never
569    /// produces this reason, so admission defaults are unchanged.
570    Untracked,
571    /// SF-004 / SF-012: file exists on disk and is small/non-binary, but its
572    /// extension maps to no supported tree-sitter grammar (e.g. `.tcl`, `.sh`,
573    /// `.m`, `.eex`, extensionless `LICENSE`/`Makefile`). It cannot be parsed, so
574    /// it is admitted Tier-2 metadata-only instead of being stored with a
575    /// contradictory Tier-1/Normal decision (which made it vanish from tier
576    /// accounting and minted a false "File not found"). The path stays searchable
577    /// as metadata; only symbol extraction is skipped.
578    UnsupportedLanguage,
579}
580
581impl std::fmt::Display for SkipReason {
582    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
583        match self {
584            SkipReason::SizeCeiling => write!(f, ">100MB"),
585            SkipReason::DenylistedExtension => write!(f, "artifact"),
586            SkipReason::SizeThreshold => write!(f, ">1MB"),
587            SkipReason::BinaryContent => write!(f, "binary"),
588            SkipReason::DependencyLockfile => write!(f, "lockfile"),
589            SkipReason::Untracked => write!(f, "untracked"),
590            SkipReason::UnsupportedLanguage => write!(f, "unsupported language"),
591        }
592    }
593}
594
595/// Structured result from the admission gate.
596#[derive(Debug, Clone, Copy, PartialEq, Eq)]
597pub struct AdmissionDecision {
598    pub tier: AdmissionTier,
599    pub reason: Option<SkipReason>,
600}
601
602impl AdmissionDecision {
603    pub fn normal() -> Self {
604        Self {
605            tier: AdmissionTier::Normal,
606            reason: None,
607        }
608    }
609    pub fn skip(tier: AdmissionTier, reason: SkipReason) -> Self {
610        Self {
611            tier,
612            reason: Some(reason),
613        }
614    }
615}
616
617/// Metadata record for a file that was not fully indexed (Tier 2 or Tier 3).
618/// Stores the AdmissionDecision directly — no re-derivation downstream.
619#[derive(Debug, Clone)]
620pub struct SkippedFile {
621    pub path: String,
622    pub size: u64,
623    pub extension: Option<String>,
624    pub decision: AdmissionDecision,
625}
626
627impl SkippedFile {
628    pub fn tier(&self) -> AdmissionTier {
629        self.decision.tier
630    }
631    pub fn reason(&self) -> Option<SkipReason> {
632        self.decision.reason
633    }
634}
635
636pub const HARD_SKIP_BYTES: u64 = 100 * 1024 * 1024;
637pub const METADATA_ONLY_BYTES: u64 = 1024 * 1024;
638pub const BINARY_SNIFF_BYTES: usize = 8192;
639
640const DENYLISTED_EXTENSIONS: &[&str] = &[
641    // ML models
642    "safetensors",
643    "ckpt",
644    "pt",
645    "onnx",
646    "gguf",
647    "pth",
648    // VM/disk images
649    "vmdk",
650    "iso",
651    "img",
652    "qcow2",
653    // Archives
654    "tar",
655    "gz",
656    "zip",
657    "7z",
658    "rar",
659    "bz2",
660    "xz",
661    "zst",
662    // Databases
663    "db",
664    "sqlite",
665    "sqlite3",
666    "mdb",
667    // Media
668    "mp3",
669    "mp4",
670    "wav",
671    "avi",
672    "mov",
673    "mkv",
674    "png",
675    "jpg",
676    "jpeg",
677    "gif",
678    "bmp",
679    "ico",
680    "woff",
681    "woff2",
682    "ttf",
683    "eot",
684    // Binary
685    "bin",
686    // Executables and libraries
687    "exe",
688    "dll",
689    "so",
690    "dylib",
691    "class",
692];
693
694pub fn is_denylisted_extension(ext: &str) -> bool {
695    DENYLISTED_EXTENSIONS.contains(&ext.to_lowercase().as_str())
696}
697
698/// Dependency lockfiles matched by exact basename (case-sensitive, as these
699/// names are conventionally fixed). These are machine-generated manifests whose
700/// content (resolved dependency trees) parses into thousands of structurally
701/// meaningless symbols — e.g. a single `package-lock.json` can mint ~9k JSON-key
702/// symbols, dwarfing real source and skewing `conventions` complexity stats.
703/// Admission demotes them to Tier-2 (metadata only): the path stays searchable,
704/// but no symbols are extracted.
705///
706/// Cross-reference: the search ranker keeps an OVERLAPPING but distinct list,
707/// `CHORE_ANCHOR_FILENAMES` in `src/live_index/rank_signals.rs`, used to suppress
708/// co-change promotion. That list is intentionally NOT shared: it also contains
709/// non-lockfile chore anchors (`CHANGELOG.md`, `.release-please-manifest.json`)
710/// and lives in the `live_index` layer, which `domain` must not depend on. The
711/// two lists answer different questions (admission vs. ranking) and are kept
712/// separate on purpose; update both when the lockfile ecosystem changes.
713const LOCKFILE_BASENAMES: &[&str] = &[
714    "package-lock.json",
715    "npm-shrinkwrap.json",
716    "yarn.lock",
717    "pnpm-lock.yaml",
718    "bun.lock",
719    "Cargo.lock",
720    "composer.lock",
721    "Gemfile.lock",
722    "poetry.lock",
723    "uv.lock",
724    "Pipfile.lock",
725    "flake.lock",
726    "packages.lock.json",
727    "go.sum",
728];
729
730/// Returns `true` when `path`'s file name is an exact (case-sensitive) match for
731/// a known dependency lockfile. See [`LOCKFILE_BASENAMES`].
732pub fn is_dependency_lockfile(path: &std::path::Path) -> bool {
733    path.file_name()
734        .and_then(|n| n.to_str())
735        .is_some_and(|name| LOCKFILE_BASENAMES.contains(&name))
736}
737
738/// Maximum number of NUL byte offsets [`scan_nul_bytes`] enumerates explicitly.
739/// Beyond this we report only the count plus the first few offsets — the warning
740/// exists to alert, not to exhaustively map every NUL.
741pub const NUL_OFFSET_SAMPLE_LIMIT: usize = 5;
742
743/// Result of scanning a byte slice for literal NUL (`0x00`) bytes.
744///
745/// A NUL is valid UTF-8, so it survives `String::from_utf8_lossy` intact and is
746/// then rendered invisibly (most terminals show nothing or a space). Source code
747/// that smuggles a NUL into a string/template literal (legal for Node, Python,
748/// etc.) therefore reads back as text that does NOT byte-match the file — an
749/// agent copying that rendered text for an edit produces a mismatch. This scan
750/// powers an honest warning at the content-rendering boundary.
751#[derive(Clone, Debug, Default, PartialEq, Eq)]
752pub struct NulScan {
753    /// Total count of NUL bytes in the scanned slice.
754    pub count: usize,
755    /// Byte offsets (relative to the scanned slice) of the first
756    /// [`NUL_OFFSET_SAMPLE_LIMIT`] NUL bytes, in ascending order.
757    pub first_offsets: Vec<usize>,
758}
759
760impl NulScan {
761    /// `true` when the scanned slice contained at least one NUL byte.
762    pub fn has_nul(&self) -> bool {
763        self.count > 0
764    }
765}
766
767/// Scan `content` for literal NUL (`0x00`) bytes, returning a count and the
768/// first [`NUL_OFFSET_SAMPLE_LIMIT`] offsets. Pure; scans the WHOLE slice it is
769/// given (callers pass the exact bytes whose rendering they are warning about).
770pub fn scan_nul_bytes(content: &[u8]) -> NulScan {
771    let mut count = 0usize;
772    let mut first_offsets = Vec::new();
773    for (offset, &byte) in content.iter().enumerate() {
774        if byte == 0 {
775            count += 1;
776            if first_offsets.len() < NUL_OFFSET_SAMPLE_LIMIT {
777                first_offsets.push(offset);
778            }
779        }
780    }
781    NulScan {
782        count,
783        first_offsets,
784    }
785}
786
787/// Render a single-line warning describing NUL bytes found by [`scan_nul_bytes`],
788/// or `None` when the slice is clean. The message is deliberately blunt: copied
789/// rendered text will not byte-match the file, so edits must use byte-exact tools.
790pub fn nul_byte_warning_line(scan: &NulScan) -> Option<String> {
791    if !scan.has_nul() {
792        return None;
793    }
794    let offsets = scan
795        .first_offsets
796        .iter()
797        .map(|o| o.to_string())
798        .collect::<Vec<_>>()
799        .join(", ");
800    let plural = if scan.count == 1 { "" } else { "s" };
801    let offset_suffix = if scan.count > scan.first_offsets.len() {
802        format!("{offsets}, ...")
803    } else {
804        offsets
805    };
806    Some(format!(
807        "WARNING: this file contains {} NUL byte{plural} (0x00) at byte offset(s) {offset_suffix}. \
808         They are rendered invisibly above; copied text will NOT byte-match the file. \
809         Edit this file with byte-exact tools, not rendered text.",
810        scan.count
811    ))
812}
813
814#[cfg(test)]
815mod tests {
816    use super::*;
817
818    #[test]
819    fn test_symbol_kind_display_function() {
820        assert_eq!(SymbolKind::Function.to_string(), "fn");
821    }
822
823    #[test]
824    fn test_is_c_header_path() {
825        // `.h` headers (any case, any directory separator) are flagged.
826        assert!(LanguageId::is_c_header_path("foo.h"));
827        assert!(LanguageId::is_c_header_path("src/runner/flutter_window.h"));
828        assert!(LanguageId::is_c_header_path("windows\\runner\\utils.h"));
829        assert!(LanguageId::is_c_header_path("API.H"));
830        // C++ header extensions map to Cpp directly and are NOT `.h`.
831        assert!(!LanguageId::is_c_header_path("foo.hpp"));
832        assert!(!LanguageId::is_c_header_path("foo.hxx"));
833        assert!(!LanguageId::is_c_header_path("foo.hh"));
834        // Non-headers.
835        assert!(!LanguageId::is_c_header_path("foo.c"));
836        assert!(!LanguageId::is_c_header_path("foo.cpp"));
837        assert!(!LanguageId::is_c_header_path("README"));
838        // A `.h` in the directory name, not the file, must not match.
839        assert!(!LanguageId::is_c_header_path("foo.h/bar.c"));
840    }
841
842    #[test]
843    fn test_symbol_kind_display_method() {
844        assert_eq!(SymbolKind::Method.to_string(), "fn");
845    }
846
847    #[test]
848    fn test_symbol_kind_display_class() {
849        assert_eq!(SymbolKind::Class.to_string(), "class");
850    }
851
852    #[test]
853    fn test_symbol_kind_display_struct() {
854        assert_eq!(SymbolKind::Struct.to_string(), "struct");
855    }
856
857    #[test]
858    fn test_symbol_kind_display_enum() {
859        assert_eq!(SymbolKind::Enum.to_string(), "enum");
860    }
861
862    #[test]
863    fn test_symbol_kind_display_interface() {
864        assert_eq!(SymbolKind::Interface.to_string(), "interface");
865    }
866
867    #[test]
868    fn test_symbol_kind_display_module() {
869        assert_eq!(SymbolKind::Module.to_string(), "mod");
870    }
871
872    #[test]
873    fn test_symbol_kind_display_constant() {
874        assert_eq!(SymbolKind::Constant.to_string(), "const");
875    }
876
877    #[test]
878    fn test_symbol_kind_display_variable() {
879        assert_eq!(SymbolKind::Variable.to_string(), "let");
880    }
881
882    #[test]
883    fn test_symbol_kind_display_type() {
884        assert_eq!(SymbolKind::Type.to_string(), "type");
885    }
886
887    #[test]
888    fn test_symbol_kind_display_trait() {
889        assert_eq!(SymbolKind::Trait.to_string(), "trait");
890    }
891
892    #[test]
893    fn test_symbol_kind_display_impl() {
894        assert_eq!(SymbolKind::Impl.to_string(), "impl");
895    }
896
897    #[test]
898    fn test_symbol_kind_display_other() {
899        assert_eq!(SymbolKind::Other.to_string(), "other");
900    }
901
902    // --- ReferenceRecord and ReferenceKind ---
903
904    #[test]
905    fn test_reference_kind_all_variants_constructible() {
906        let _call = ReferenceKind::Call;
907        let _import = ReferenceKind::Import;
908        let _type_usage = ReferenceKind::TypeUsage;
909        let _macro_use = ReferenceKind::MacroUse;
910    }
911
912    #[test]
913    fn test_reference_kind_display_call() {
914        assert_eq!(ReferenceKind::Call.to_string(), "call");
915    }
916
917    #[test]
918    fn test_reference_kind_display_import() {
919        assert_eq!(ReferenceKind::Import.to_string(), "import");
920    }
921
922    #[test]
923    fn test_reference_kind_display_type_usage() {
924        assert_eq!(ReferenceKind::TypeUsage.to_string(), "type_usage");
925    }
926
927    #[test]
928    fn test_reference_kind_display_macro_use() {
929        assert_eq!(ReferenceKind::MacroUse.to_string(), "macro_use");
930    }
931
932    #[test]
933    fn test_reference_record_construction_with_all_fields() {
934        let r = ReferenceRecord {
935            name: "foo".to_string(),
936            qualified_name: Some("Bar::foo".to_string()),
937            kind: ReferenceKind::Call,
938            byte_range: (10, 20),
939            line_range: (1, 1),
940            enclosing_symbol_index: Some(0),
941        };
942        assert_eq!(r.name, "foo");
943        assert_eq!(r.qualified_name.as_deref(), Some("Bar::foo"));
944        assert_eq!(r.kind, ReferenceKind::Call);
945        assert_eq!(r.byte_range, (10, 20));
946        assert_eq!(r.line_range, (1, 1));
947        assert_eq!(r.enclosing_symbol_index, Some(0));
948    }
949
950    #[test]
951    fn test_reference_record_without_optional_fields() {
952        let r = ReferenceRecord {
953            name: "baz".to_string(),
954            qualified_name: None,
955            kind: ReferenceKind::Import,
956            byte_range: (0, 5),
957            line_range: (0, 0),
958            enclosing_symbol_index: None,
959        };
960        assert!(r.qualified_name.is_none());
961        assert!(r.enclosing_symbol_index.is_none());
962    }
963
964    #[test]
965    fn test_file_processing_result_backward_compat_with_empty_refs() {
966        use std::collections::HashMap;
967        let result = FileProcessingResult {
968            relative_path: "test.rs".to_string(),
969            language: LanguageId::Rust,
970            classification: FileClassification::for_code_path("test.rs"),
971            outcome: FileOutcome::Processed,
972            parse_diagnostic: None,
973            symbols: vec![],
974            byte_len: 0,
975            content_hash: "abc".to_string(),
976            references: vec![],
977            alias_map: HashMap::new(),
978        };
979        assert!(result.references.is_empty());
980        assert!(result.alias_map.is_empty());
981    }
982
983    #[test]
984    fn test_file_classification_for_code_path_marks_code_only_by_default() {
985        let classification = FileClassification::for_code_path("src/lib.rs");
986
987        assert!(classification.is_code());
988        assert!(!classification.is_text());
989        assert!(!classification.is_binary());
990        assert!(!classification.is_generated);
991        assert!(!classification.is_test);
992        assert!(!classification.is_vendor);
993    }
994
995    #[test]
996    fn test_file_classification_for_code_path_marks_noise_tags_from_path() {
997        let generated = FileClassification::for_code_path("src/generated/client.pb.go");
998        assert!(generated.is_generated);
999
1000        let test_file = FileClassification::for_code_path("tests/parser_spec.rs");
1001        assert!(test_file.is_test);
1002
1003        let vendor_file = FileClassification::for_code_path("node_modules/pkg/index.js");
1004        assert!(vendor_file.is_vendor);
1005    }
1006
1007    #[test]
1008    fn test_find_enclosing_symbol_innermost_for_nested() {
1009        // outer: line 0..10, inner: line 3..6
1010        let symbols = vec![
1011            SymbolRecord {
1012                name: "outer".to_string(),
1013                kind: SymbolKind::Function,
1014                depth: 0,
1015                sort_order: 0,
1016                byte_range: (0, 100),
1017                line_range: (0, 10),
1018                doc_byte_range: None,
1019                item_byte_range: None,
1020            },
1021            SymbolRecord {
1022                name: "inner".to_string(),
1023                kind: SymbolKind::Function,
1024                depth: 1,
1025                sort_order: 1,
1026                byte_range: (30, 60),
1027                line_range: (3, 6),
1028                doc_byte_range: None,
1029                item_byte_range: None,
1030            },
1031        ];
1032        // Reference at line 4 is inside both - should return inner (index 1)
1033        let idx = find_enclosing_symbol(&symbols, 4);
1034        assert_eq!(idx, Some(1), "should return innermost enclosing symbol");
1035    }
1036
1037    #[test]
1038    fn test_find_enclosing_symbol_none_at_module_level() {
1039        let symbols = vec![SymbolRecord {
1040            name: "foo".to_string(),
1041            kind: SymbolKind::Function,
1042            depth: 0,
1043            sort_order: 0,
1044            byte_range: (50, 100),
1045            line_range: (5, 10),
1046            doc_byte_range: None,
1047            item_byte_range: None,
1048        }];
1049        // Reference at line 0 is not inside any symbol
1050        let idx = find_enclosing_symbol(&symbols, 0);
1051        assert_eq!(idx, None, "should return None when not inside any symbol");
1052    }
1053
1054    #[test]
1055    fn test_symbol_record_item_helpers_fall_back_to_doc_range() {
1056        let symbol = SymbolRecord {
1057            name: "target".to_string(),
1058            kind: SymbolKind::Function,
1059            depth: 0,
1060            sort_order: 0,
1061            byte_range: (20, 40),
1062            line_range: (1, 3),
1063            doc_byte_range: Some((10, 20)),
1064            item_byte_range: None,
1065        };
1066
1067        assert_eq!(symbol.item_start(), 10);
1068        assert_eq!(symbol.item_end(), 40);
1069        assert_eq!(symbol.item_range(), (10, 40));
1070        assert_eq!(symbol.core_range(), (20, 40));
1071    }
1072
1073    #[test]
1074    fn test_symbol_record_item_helpers_prefer_item_range() {
1075        let symbol = SymbolRecord {
1076            name: "target".to_string(),
1077            kind: SymbolKind::Function,
1078            depth: 0,
1079            sort_order: 0,
1080            byte_range: (20, 40),
1081            line_range: (1, 3),
1082            doc_byte_range: Some((10, 20)),
1083            item_byte_range: Some((5, 44)),
1084        };
1085
1086        assert_eq!(symbol.item_start(), 5);
1087        assert_eq!(symbol.item_end(), 44);
1088        assert_eq!(symbol.item_range(), (5, 44));
1089        assert_eq!(symbol.core_range(), (20, 40));
1090    }
1091
1092    #[test]
1093    fn test_admission_tier_variants() {
1094        let t1 = AdmissionTier::Normal;
1095        let t2 = AdmissionTier::MetadataOnly;
1096        let t3 = AdmissionTier::HardSkip;
1097        assert_ne!(t1, t2);
1098        assert_ne!(t2, t3);
1099        assert_ne!(t1, t3);
1100    }
1101
1102    #[test]
1103    fn test_extension_is_denylisted() {
1104        assert!(is_denylisted_extension("safetensors"));
1105        assert!(is_denylisted_extension("ckpt"));
1106        assert!(is_denylisted_extension("zip"));
1107        assert!(is_denylisted_extension("mp4"));
1108        assert!(is_denylisted_extension("woff2"));
1109        assert!(is_denylisted_extension("png"));
1110        assert!(is_denylisted_extension("bin"));
1111    }
1112
1113    #[test]
1114    fn test_extension_not_denylisted() {
1115        assert!(!is_denylisted_extension("rs"));
1116        assert!(!is_denylisted_extension("ts"));
1117        assert!(!is_denylisted_extension("json"));
1118        assert!(!is_denylisted_extension("svg")); // SVG intentionally NOT denylisted
1119        assert!(!is_denylisted_extension("md"));
1120        assert!(!is_denylisted_extension("toml"));
1121    }
1122
1123    #[test]
1124    fn test_new_executable_extensions_denylisted() {
1125        assert!(is_denylisted_extension("exe"));
1126        assert!(is_denylisted_extension("dll"));
1127        assert!(is_denylisted_extension("so"));
1128        assert!(is_denylisted_extension("dylib"));
1129        assert!(is_denylisted_extension("class"));
1130    }
1131
1132    #[test]
1133    fn test_denylist_case_insensitive() {
1134        assert!(is_denylisted_extension("DLL"));
1135        assert!(is_denylisted_extension("So"));
1136        assert!(is_denylisted_extension("EXE"));
1137        assert!(is_denylisted_extension("Dylib"));
1138        assert!(is_denylisted_extension("CLASS"));
1139    }
1140
1141    #[test]
1142    fn test_skipped_file_creation() {
1143        let decision =
1144            AdmissionDecision::skip(AdmissionTier::MetadataOnly, SkipReason::DenylistedExtension);
1145        let sf = SkippedFile {
1146            path: "model.safetensors".into(),
1147            size: 4_200_000_000,
1148            extension: Some("safetensors".into()),
1149            decision,
1150        };
1151        assert_eq!(sf.tier(), AdmissionTier::MetadataOnly);
1152        assert_eq!(sf.reason(), Some(SkipReason::DenylistedExtension));
1153    }
1154
1155    #[test]
1156    fn test_scan_nul_bytes_clean_slice_reports_none() {
1157        let scan = scan_nul_bytes(b"fn main() {}\n");
1158        assert!(!scan.has_nul());
1159        assert_eq!(scan.count, 0);
1160        assert!(scan.first_offsets.is_empty());
1161        assert_eq!(nul_byte_warning_line(&scan), None);
1162    }
1163
1164    #[test]
1165    fn test_scan_nul_bytes_empty_slice_reports_none() {
1166        let scan = scan_nul_bytes(b"");
1167        assert!(!scan.has_nul());
1168        assert_eq!(nul_byte_warning_line(&scan), None);
1169    }
1170
1171    #[test]
1172    fn test_scan_nul_bytes_single_offset_and_singular_warning() {
1173        let scan = scan_nul_bytes(b"ab\0cd");
1174        assert_eq!(scan.count, 1);
1175        assert_eq!(scan.first_offsets, vec![2]);
1176        let warning = nul_byte_warning_line(&scan).expect("NUL present");
1177        assert!(warning.contains("1 NUL byte (0x00)"), "warning: {warning}");
1178        assert!(
1179            warning.contains("byte offset(s) 2."),
1180            "single offset, no ellipsis: {warning}"
1181        );
1182        assert!(warning.contains("byte-exact tools"));
1183    }
1184
1185    #[test]
1186    fn test_scan_nul_bytes_plural_warning() {
1187        let scan = scan_nul_bytes(b"\0a\0b");
1188        assert_eq!(scan.count, 2);
1189        assert_eq!(scan.first_offsets, vec![0, 2]);
1190        let warning = nul_byte_warning_line(&scan).expect("NUL present");
1191        assert!(warning.contains("2 NUL bytes (0x00)"), "warning: {warning}");
1192        assert!(
1193            warning.contains("byte offset(s) 0, 2."),
1194            "warning: {warning}"
1195        );
1196    }
1197
1198    #[test]
1199    fn test_scan_nul_bytes_caps_offsets_and_adds_ellipsis() {
1200        // 7 NUL bytes; only the first NUL_OFFSET_SAMPLE_LIMIT (5) are enumerated.
1201        let scan = scan_nul_bytes(b"\0\0\0\0\0\0\0");
1202        assert_eq!(scan.count, 7);
1203        assert_eq!(scan.first_offsets.len(), NUL_OFFSET_SAMPLE_LIMIT);
1204        assert_eq!(scan.first_offsets, vec![0, 1, 2, 3, 4]);
1205        let warning = nul_byte_warning_line(&scan).expect("NUL present");
1206        assert!(warning.contains("7 NUL bytes"), "warning: {warning}");
1207        assert!(
1208            warning.contains("0, 1, 2, 3, 4, ..."),
1209            "more NULs than sampled => ellipsis: {warning}"
1210        );
1211    }
1212}