use std::collections::HashMap;
use std::fmt;
#[derive(
Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, serde::Serialize, serde::Deserialize,
)]
pub enum LanguageId {
Rust,
Python,
JavaScript,
TypeScript,
Go,
Java,
C,
Cpp,
CSharp,
Ruby,
Php,
Swift,
Kotlin,
Dart,
Perl,
Elixir,
Json,
Toml,
Yaml,
Markdown,
Text,
Env,
Html,
Css,
Scss,
}
impl LanguageId {
pub const ALL: [Self; 25] = [
Self::Rust,
Self::Python,
Self::JavaScript,
Self::TypeScript,
Self::Go,
Self::Java,
Self::C,
Self::Cpp,
Self::CSharp,
Self::Ruby,
Self::Php,
Self::Swift,
Self::Kotlin,
Self::Dart,
Self::Perl,
Self::Elixir,
Self::Json,
Self::Toml,
Self::Yaml,
Self::Markdown,
Self::Text,
Self::Env,
Self::Html,
Self::Css,
Self::Scss,
];
pub const fn name(self) -> &'static str {
match self {
Self::Rust => "rust",
Self::Python => "python",
Self::JavaScript => "javascript",
Self::TypeScript => "typescript",
Self::Go => "go",
Self::Java => "java",
Self::C => "c",
Self::Cpp => "cpp",
Self::CSharp => "csharp",
Self::Ruby => "ruby",
Self::Php => "php",
Self::Swift => "swift",
Self::Kotlin => "kotlin",
Self::Dart => "dart",
Self::Perl => "perl",
Self::Elixir => "elixir",
Self::Json => "json",
Self::Toml => "toml",
Self::Yaml => "yaml",
Self::Markdown => "markdown",
Self::Text => "text",
Self::Env => "env",
Self::Html => "html",
Self::Css => "css",
Self::Scss => "scss",
}
}
pub fn from_extension(ext: &str) -> Option<Self> {
match ext.to_ascii_lowercase().as_str() {
"rs" => Some(Self::Rust),
"py" => Some(Self::Python),
"js" | "jsx" => Some(Self::JavaScript),
"ts" | "tsx" => Some(Self::TypeScript),
"go" => Some(Self::Go),
"java" => Some(Self::Java),
"c" | "h" => Some(Self::C),
"cpp" | "cxx" | "cc" | "hpp" | "hxx" | "hh" => Some(Self::Cpp),
"cs" => Some(Self::CSharp),
"rb" => Some(Self::Ruby),
"php" => Some(Self::Php),
"swift" => Some(Self::Swift),
"dart" => Some(Self::Dart),
"kt" | "kts" => Some(Self::Kotlin),
"pl" | "pm" => Some(Self::Perl),
"ex" | "exs" => Some(Self::Elixir),
"json" => Some(Self::Json),
"toml" => Some(Self::Toml),
"yaml" | "yml" => Some(Self::Yaml),
"md" | "mdx" => Some(Self::Markdown),
"txt" | "text" | "rst" | "adoc" | "asciidoc" | "org" | "ini" | "conf"
| "properties" | "xml" | "json5" => Some(Self::Text),
"env" => Some(Self::Env),
"html" => Some(Self::Html),
"css" => Some(Self::Css),
"scss" => Some(Self::Scss),
_ => None,
}
}
pub fn from_path(relative_path: &str) -> Option<Self> {
let basename = relative_path
.rsplit(['/', '\\'])
.next()
.unwrap_or(relative_path)
.to_ascii_lowercase();
if basename == ".env" || basename.starts_with(".env.") {
return Some(Self::Env);
}
if matches!(
basename.as_str(),
"readme"
| "changelog"
| "license"
| "notice"
| "agents"
| "claude"
| "contributing"
| "security"
| "governance"
| ".gitignore"
| ".gitattributes"
| ".editorconfig"
) {
return Some(Self::Text);
}
basename
.rsplit_once('.')
.and_then(|(_, extension)| Self::from_extension(extension))
}
pub fn is_code_language(&self) -> bool {
!matches!(
self,
Self::Json
| Self::Toml
| Self::Yaml
| Self::Markdown
| Self::Text
| Self::Env
| Self::Html
| Self::Css
| Self::Scss
)
}
pub fn is_tsx_path(relative_path: &str) -> bool {
relative_path
.rsplit(['/', '\\'])
.next()
.and_then(|name| name.rsplit_once('.'))
.is_some_and(|(_, ext)| ext.eq_ignore_ascii_case("tsx"))
}
pub fn is_c_header_path(relative_path: &str) -> bool {
relative_path
.rsplit(['/', '\\'])
.next()
.and_then(|name| name.rsplit_once('.'))
.is_some_and(|(_, ext)| ext.eq_ignore_ascii_case("h"))
}
pub fn extensions(&self) -> &[&str] {
match self {
Self::Rust => &["rs"],
Self::Python => &["py"],
Self::JavaScript => &["js", "jsx"],
Self::TypeScript => &["ts", "tsx"],
Self::Go => &["go"],
Self::Java => &["java"],
Self::C => &["c", "h"],
Self::Cpp => &["cpp", "cxx", "cc", "hpp", "hxx", "hh"],
Self::CSharp => &["cs"],
Self::Ruby => &["rb"],
Self::Php => &["php"],
Self::Swift => &["swift"],
Self::Kotlin => &["kt", "kts"],
Self::Dart => &["dart"],
Self::Perl => &["pl", "pm"],
Self::Elixir => &["ex", "exs"],
Self::Json => &["json"],
Self::Toml => &["toml"],
Self::Yaml => &["yaml", "yml"],
Self::Markdown => &["md", "mdx"],
Self::Text => &[
"txt",
"text",
"rst",
"adoc",
"asciidoc",
"org",
"ini",
"conf",
"properties",
"xml",
"json5",
],
Self::Env => &["env"],
Self::Html => &["html"],
Self::Css => &["css"],
Self::Scss => &["scss"],
}
}
pub fn support_tier(&self) -> SupportTier {
match self {
Self::Rust | Self::Python | Self::JavaScript | Self::TypeScript | Self::Go => {
SupportTier::QualityFocus
}
Self::Java
| Self::C
| Self::Cpp
| Self::CSharp
| Self::Ruby
| Self::Php
| Self::Swift
| Self::Kotlin
| Self::Dart
| Self::Perl
| Self::Elixir
| Self::Json
| Self::Toml
| Self::Yaml
| Self::Markdown
| Self::Text
| Self::Env
| Self::Html
| Self::Css
| Self::Scss => SupportTier::Broader,
}
}
}
impl fmt::Display for LanguageId {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let name = match self {
Self::Rust => "Rust",
Self::Python => "Python",
Self::JavaScript => "JavaScript",
Self::TypeScript => "TypeScript",
Self::Go => "Go",
Self::Java => "Java",
Self::C => "C",
Self::Cpp => "C++",
Self::CSharp => "C#",
Self::Ruby => "Ruby",
Self::Php => "PHP",
Self::Swift => "Swift",
Self::Kotlin => "Kotlin",
Self::Dart => "Dart",
Self::Perl => "Perl",
Self::Elixir => "Elixir",
Self::Json => "JSON",
Self::Toml => "TOML",
Self::Yaml => "YAML",
Self::Markdown => "Markdown",
Self::Text => "Text",
Self::Env => "Env",
Self::Html => "HTML",
Self::Css => "CSS",
Self::Scss => "SCSS",
};
write!(f, "{name}")
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum SupportTier {
QualityFocus,
Broader,
Unsupported,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum FileClass {
Code,
Text,
Binary,
}
pub const VENDOR_PATH_SEGMENTS: &[&str] = &[
"vendor",
"third_party",
"third-party",
"node_modules",
".venv",
"venv",
"site-packages",
"pods",
"bower_components",
"deps",
"extern",
"externals",
];
pub const GENERATED_PATH_SEGMENTS: &[&str] =
&["dist", "generated", "__generated__", "generated-sources"];
pub const TEST_PATH_SEGMENTS: &[&str] = &[
"tests",
"test",
"__tests__",
"spec",
"test_data",
"testdata",
"fixtures",
"__fixtures__",
"__snapshots__",
];
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub struct FileClassification {
pub class: FileClass,
pub is_generated: bool,
pub is_test: bool,
pub is_vendor: bool,
#[serde(default)]
pub is_config: bool,
}
impl FileClassification {
pub fn for_code_path(relative_path: &str) -> Self {
let lower = relative_path.replace('\\', "/").to_ascii_lowercase();
let segments: Vec<&str> = lower
.split('/')
.filter(|segment| !segment.is_empty())
.collect();
let basename = segments.last().copied().unwrap_or("");
let stem = basename
.rsplit_once('.')
.map(|(name, _)| name)
.unwrap_or(basename);
let is_test = segments
.iter()
.any(|segment| TEST_PATH_SEGMENTS.contains(segment))
|| matches!(stem, "test" | "tests" | "testutil" | "testutils")
|| stem.starts_with("test_")
|| stem.ends_with("_test")
|| stem.ends_with(".test")
|| stem.ends_with("_spec")
|| stem.ends_with(".spec");
let is_vendor = segments
.iter()
.any(|segment| VENDOR_PATH_SEGMENTS.contains(segment));
let is_generated = segments
.iter()
.any(|segment| GENERATED_PATH_SEGMENTS.contains(segment))
|| basename.contains(".generated.")
|| basename.contains(".gen.")
|| basename.ends_with(".g.dart")
|| basename.ends_with(".pb.go")
|| basename.ends_with(".designer.cs")
|| basename.ends_with(".min.js")
|| basename.ends_with(".min.css")
|| basename.ends_with(".map");
let ext = basename.rsplit_once('.').map(|(_, e)| e).unwrap_or("");
let is_config = matches!(ext, "json" | "toml" | "yaml" | "yml" | "md" | "env");
Self {
class: FileClass::Code,
is_generated,
is_test,
is_vendor,
is_config,
}
}
pub fn for_indexed_path(relative_path: &str, targets: IndexTargets) -> Self {
let mut classification = Self::for_code_path(relative_path);
classification.class = if matches!(targets, IndexTargets::Knowledge) {
FileClass::Text
} else {
FileClass::Code
};
classification.is_config = matches!(targets, IndexTargets::CodeAndKnowledge);
classification
}
pub const fn is_code(&self) -> bool {
matches!(self.class, FileClass::Code)
}
pub const fn is_text(&self) -> bool {
matches!(self.class, FileClass::Text)
}
pub const fn is_binary(&self) -> bool {
matches!(self.class, FileClass::Binary)
}
}
#[derive(Clone, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
#[serde(transparent)]
pub struct ProjectId(pub String);
#[derive(Clone, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
#[serde(transparent)]
pub struct RepositoryId(String);
impl RepositoryId {
pub fn new(value: impl Into<String>) -> Self {
Self(value.into())
}
pub fn as_str(&self) -> &str {
&self.0
}
}
#[derive(
Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, serde::Serialize, serde::Deserialize,
)]
#[serde(transparent)]
pub struct SourceId(String);
impl SourceId {
pub fn new(value: impl Into<String>) -> Self {
Self(value.into())
}
pub fn as_str(&self) -> &str {
&self.0
}
}
#[derive(Clone, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum SourceLocation {
WorkingTree { worktree_id: String },
GitRef { name: String },
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum WorkingTreeState {
Clean,
Dirty,
NotApplicable,
Unknown,
}
#[derive(Clone, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub struct SourceVersion {
pub branch: Option<String>,
pub commit: Option<String>,
pub working_tree: WorkingTreeState,
}
#[derive(Clone, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub struct SourceIdentity {
pub repository_id: RepositoryId,
pub source_id: SourceId,
pub location: SourceLocation,
}
#[derive(Clone, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum RepositoryFingerprint {
Git {
object_format: String,
selected_ref_or_head: String,
tip_object_id: String,
reachable_history_fingerprint: String,
},
NonGit {
catalog_identity_digest: String,
},
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct SnapshotSourceIdentity {
pub project_id: ProjectId,
pub repository_id: RepositoryId,
pub source_id: SourceId,
pub source_version: SourceVersion,
pub repository_fingerprint: RepositoryFingerprint,
pub manifest_digest: String,
pub indexed_content_digest: String,
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct SourceResponseEnvelope {
pub source: SourceIdentity,
pub source_version: SourceVersion,
pub publication_generation: u64,
pub content_generation: u64,
pub freshness: FreshnessStatus,
pub manifest_digest: String,
pub coverage: CoverageStatus,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum RootCandidateSource {
WorkspaceEnvironment,
McpClientRoot,
ClaudeProjectDir,
GitAncestor,
LaunchCwd,
ExplicitIndexFolder,
InitCwd,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum RootRequestMode {
Automatic,
Init,
ExplicitIndexFolder { allow_protected_root: bool },
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum RootClass {
Normal,
Protected,
NeverIndexable,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum RootRefusalReason {
FilesystemOrDriveRoot,
HomeOrProfileRoot,
OsOrSensitiveTree,
BroadContainer,
SymlinkAliasToForbiddenRoot,
MissingOrNotDirectory,
CanonicalizationFailed,
UnsupportedPathEncoding,
DeviceOrSpecialNamespace,
ProtectedRootRequiresExplicitOverride,
CredentialDirectory,
}
impl RootRefusalReason {
pub const fn code(self) -> &'static str {
match self {
Self::FilesystemOrDriveRoot => "filesystem_or_drive_root",
Self::HomeOrProfileRoot => "home_or_profile_root",
Self::OsOrSensitiveTree => "os_or_sensitive_tree",
Self::BroadContainer => "broad_container",
Self::SymlinkAliasToForbiddenRoot => "symlink_alias_to_forbidden_root",
Self::MissingOrNotDirectory => "missing_or_not_directory",
Self::CanonicalizationFailed => "canonicalization_failed",
Self::UnsupportedPathEncoding => "unsupported_path_encoding",
Self::DeviceOrSpecialNamespace => "device_or_special_namespace",
Self::ProtectedRootRequiresExplicitOverride => {
"protected_root_requires_explicit_override"
}
Self::CredentialDirectory => "credential_directory",
}
}
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum UnboundReason {
NoCandidateDeclared,
Refused(RootRefusalReason),
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum SourceAccessMode {
NormalProject,
ExplicitProtected,
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct RootBinding {
pub source: RootCandidateSource,
pub canonical_root: std::path::PathBuf,
pub root_id: ProjectId,
pub access_mode: SourceAccessMode,
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum RootResolution {
Bound(RootBinding),
Unbound {
rejected_source: Option<RootCandidateSource>,
reason: UnboundReason,
safe_path_id: Option<String>,
},
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(transparent)]
pub struct ProjectStateDir(std::path::PathBuf);
impl ProjectStateDir {
#[must_use]
pub fn new(path: std::path::PathBuf) -> Self {
assert!(
path.is_absolute(),
"project state directory must be absolute"
);
Self(path)
}
pub fn as_path(&self) -> &std::path::Path {
&self.0
}
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(transparent)]
pub struct ControlStateDir(std::path::PathBuf);
impl ControlStateDir {
#[must_use]
pub fn new(path: std::path::PathBuf) -> Self {
assert!(
path.is_absolute(),
"control state directory must be absolute"
);
Self(path)
}
pub fn as_path(&self) -> &std::path::Path {
&self.0
}
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum ControlStatePlacement {
UserLocal { directory: ControlStateDir },
ProcessLocal { safe_reason: AccessErrorKind },
}
impl ControlStatePlacement {
#[must_use]
pub fn directory(&self) -> Option<&ControlStateDir> {
match self {
Self::UserLocal { directory } => Some(directory),
Self::ProcessLocal { .. } => None,
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum CapabilityUnavailableReason {
ExplicitProtectedSource,
SourceReadOnly,
PersistentStateUnavailable,
DurableMutationReplayUnavailable,
NonProjectLocalPlacement,
AtomicDurabilityUnavailable,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum CapabilityStatus {
Available,
Unavailable { reason: CapabilityUnavailableReason },
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct ProjectCapabilities {
pub persistent_snapshots: CapabilityStatus,
pub checkpoint: CapabilityStatus,
pub structural_edits: CapabilityStatus,
pub repository_init: CapabilityStatus,
pub repository_curation: CapabilityStatus,
pub team_artifact_export: CapabilityStatus,
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum StatePlacement {
ProjectLocal {
directory: ProjectStateDir,
},
UserLocal {
directory: ProjectStateDir,
root_id: ProjectId,
reason: UserLocalPlacementReason,
},
MemoryOnly {
failures: Vec<StateFailure>,
},
}
impl StatePlacement {
#[must_use]
pub fn directory(&self) -> Option<&ProjectStateDir> {
match self {
Self::ProjectLocal { directory } | Self::UserLocal { directory, .. } => Some(directory),
Self::MemoryOnly { .. } => None,
}
}
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum UserLocalPlacementReason {
ExplicitProtected,
ProjectLocalUnavailable { safe_reason: AccessErrorKind },
HostSelected,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum StateLocationKind {
ProjectLocal,
UserLocal,
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct StateFailure {
pub location: StateLocationKind,
pub safe_reason: AccessErrorKind,
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum GitignoreHygiene {
Effective,
MissingRule,
NoRootGitignore,
Unverifiable { safe_reason: AccessErrorKind },
NotApplicableExplicitProtected,
}
#[derive(
Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, serde::Serialize, serde::Deserialize,
)]
pub struct CatalogPath {
pub public_id: String,
pub normalized_utf8: Option<String>,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum IndexTargets {
Code,
Knowledge,
CodeAndKnowledge,
}
impl IndexTargets {
pub fn for_path(relative_path: &str, language: Option<&LanguageId>) -> Self {
match language {
Some(LanguageId::Markdown) => Self::Knowledge,
Some(LanguageId::Json | LanguageId::Toml | LanguageId::Yaml | LanguageId::Env) => {
Self::CodeAndKnowledge
}
Some(LanguageId::Text) if is_dual_target_text_path(relative_path) => {
Self::CodeAndKnowledge
}
Some(LanguageId::Text) | None => Self::Knowledge,
Some(_) => Self::Code,
}
}
pub const fn includes_code(self) -> bool {
matches!(self, Self::Code | Self::CodeAndKnowledge)
}
pub const fn includes_knowledge(self) -> bool {
matches!(self, Self::Knowledge | Self::CodeAndKnowledge)
}
}
fn is_dual_target_text_path(relative_path: &str) -> bool {
let basename = relative_path
.rsplit(['/', '\\'])
.next()
.unwrap_or(relative_path)
.to_ascii_lowercase();
let extension = basename.rsplit_once('.').map(|(_, ext)| ext);
matches!(
extension,
Some("ini" | "conf" | "properties" | "xml" | "json5")
) || matches!(
basename.as_str(),
".gitignore" | ".gitattributes" | ".editorconfig" | "dockerfile"
)
}
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct PlatformFileId(Vec<u8>);
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct FileStamp {
pub size: u64,
pub created_hint: Option<std::time::SystemTime>,
pub modified_hint: Option<std::time::SystemTime>,
pub platform_id: Option<PlatformFileId>,
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[non_exhaustive]
pub enum MetadataOnlyReason {
Lockfile,
Binary,
OversizedData,
GeneratedOrVendor,
SensitivePath {
rule_id: String,
},
SensitiveContent {
rule_ids: Vec<String>,
finding_count: u32,
},
LfsPointer {
declared_oid: Option<String>,
declared_size: Option<u64>,
},
UnsupportedPathEncoding,
PathMetadataTooLarge,
UnsupportedTextEncoding,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum HardSkipReason {
ArtifactType,
PerFileCeiling,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum AccessStage {
Metadata,
Probe,
FullRead,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum AccessErrorKind {
NotFound,
PermissionDenied,
InvalidData,
ResourceExhausted,
Other,
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum ScoutDecision {
Ingest {
targets: IndexTargets,
},
MetadataOnly {
reason: MetadataOnlyReason,
},
HardSkip {
reason: HardSkipReason,
},
Unavailable {
stage: AccessStage,
kind: AccessErrorKind,
},
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ScoutedEntry {
pub path: CatalogPath,
pub absolute_path: Option<std::path::PathBuf>,
pub stamp: FileStamp,
pub language: Option<LanguageId>,
pub classification: FileClassification,
pub decision: ScoutDecision,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum CoverageStatus {
Complete,
Degraded,
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum FreshnessStatus {
Current,
Verifying,
Degraded {
last_valid_content_generation: u64,
reason_codes: Vec<FreshnessReason>,
},
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum FreshnessReason {
ObservationFailed,
WatcherUnavailable,
ReconciliationPending,
SnapshotVerificationFailed,
DerivedPublicationPending,
CatalogEntryCapacityExceeded,
CatalogMetadataCapacityExceeded,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum HistoryLimit {
Shallow,
WindowLimited,
RenameFollowLimited,
DivergentHistory,
WorkingTreeOnly,
Unavailable,
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct HistoryCoverage {
pub complete_to_root: bool,
pub limitations: Vec<HistoryLimit>,
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum ScoutIssueKind {
DirectoryEntryUnreadable { kind: AccessErrorKind },
ScopeEscape,
UnsupportedSpecialFile,
PathIdentityCollision,
TraversalCircuitBreaker,
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct ScoutIssue {
pub path_id: Option<String>,
pub safe_path: Option<String>,
pub kind: ScoutIssueKind,
pub safe_message: String,
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct ManifestResourceUsage {
pub catalog_entries: u64,
pub catalog_metadata_bytes: u64,
pub admitted_content_bytes: u64,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub enum ParseStatus {
Parsed,
PartialParse,
Failed,
}
impl ParseStatus {
pub fn from_operational_outcome(outcome: &FileOutcome) -> Self {
match outcome {
FileOutcome::Processed => Self::Parsed,
FileOutcome::PartialParse { .. } => Self::PartialParse,
FileOutcome::Failed { .. } => Self::Failed,
}
}
pub fn aggregate_for_targets(
targets: IndexTargets,
code: Option<Self>,
knowledge: Option<Self>,
) -> Self {
let selected = match targets {
IndexTargets::Code => return code.unwrap_or(Self::Failed),
IndexTargets::Knowledge => return knowledge.unwrap_or(Self::Failed),
IndexTargets::CodeAndKnowledge => [
code.unwrap_or(Self::Failed),
knowledge.unwrap_or(Self::Failed),
],
};
if selected.iter().all(|status| *status == Self::Parsed) {
Self::Parsed
} else if selected.iter().all(|status| *status == Self::Failed) {
Self::Failed
} else {
Self::PartialParse
}
}
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum FileDisposition {
Indexed {
targets: IndexTargets,
parse_status: ParseStatus,
},
MetadataOnly {
reason: MetadataOnlyReason,
},
HardSkip {
reason: HardSkipReason,
},
Unreadable {
stage: AccessStage,
kind: AccessErrorKind,
},
UnstableDuringRead,
AbortedCircuitBreaker,
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct CatalogEntry {
pub path: CatalogPath,
pub size: u64,
pub language: Option<LanguageId>,
pub classification: FileClassification,
pub disposition: FileDisposition,
pub content_hash: Option<String>,
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct RepositoryManifest {
pub schema_version: u32,
pub policy_version: u32,
pub secret_policy_version: u32,
pub source: SourceIdentity,
pub source_version: SourceVersion,
pub coverage: CoverageStatus,
pub entries: Vec<CatalogEntry>,
pub issues: Vec<ScoutIssue>,
pub usage: ManifestResourceUsage,
pub digest: String,
}
impl RepositoryManifest {
#[allow(clippy::too_many_arguments)]
pub fn new(
schema_version: u32,
policy_version: u32,
secret_policy_version: u32,
source: SourceIdentity,
source_version: SourceVersion,
coverage: CoverageStatus,
mut entries: Vec<CatalogEntry>,
mut issues: Vec<ScoutIssue>,
usage: ManifestResourceUsage,
) -> Result<Self, serde_json::Error> {
entries.sort_by_cached_key(|entry| match entry.path.normalized_utf8.as_deref() {
Some(path) => (0_u8, path.to_lowercase(), path.to_string()),
None => (1_u8, entry.path.public_id.clone(), String::new()),
});
issues.sort_by_cached_key(|issue| match issue.safe_path.as_deref() {
Some(path) => (0_u8, path.to_lowercase(), path.to_string()),
None => (
1_u8,
issue.path_id.clone().unwrap_or_default(),
String::new(),
),
});
let digest = Self::compute_digest(
schema_version,
policy_version,
secret_policy_version,
&source,
&entries,
)?;
Ok(Self {
schema_version,
policy_version,
secret_policy_version,
source,
source_version,
coverage,
entries,
issues,
usage,
digest,
})
}
fn compute_digest(
schema_version: u32,
policy_version: u32,
secret_policy_version: u32,
source: &SourceIdentity,
entries: &[CatalogEntry],
) -> Result<String, serde_json::Error> {
#[derive(serde::Serialize)]
struct CanonicalManifestDigest<'a> {
schema_version: u32,
policy_version: u32,
secret_policy_version: u32,
source: &'a SourceIdentity,
entries: &'a [CatalogEntry],
}
let canonical = serde_json::to_vec(&CanonicalManifestDigest {
schema_version,
policy_version,
secret_policy_version,
source,
entries,
})?;
Ok(crate::hash::digest_hex(&canonical))
}
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct ParseDiagnostic {
pub parser: String,
pub message: String,
pub line: Option<u32>,
pub column: Option<u32>,
pub byte_span: Option<(u32, u32)>,
pub fallback_used: bool,
}
impl ParseDiagnostic {
pub fn location_display(&self) -> Option<String> {
match (self.line, self.column) {
(Some(line), Some(column)) => Some(format!("line {line}, column {column}")),
(Some(line), None) => Some(format!("line {line}")),
(None, Some(column)) => Some(format!("column {column}")),
(None, None) => None,
}
}
pub fn summary(&self) -> String {
let mut summary = format!("{}: {}", self.parser, self.message);
if let Some(location) = self.location_display() {
summary.push_str(&format!(" ({location})"));
}
if self.fallback_used {
summary.push_str(" [fallback symbol extraction used]");
}
summary
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct FileProcessingResult {
pub relative_path: String,
pub language: LanguageId,
pub classification: FileClassification,
pub outcome: FileOutcome,
pub parse_diagnostic: Option<ParseDiagnostic>,
pub symbols: Vec<SymbolRecord>,
pub byte_len: u64,
pub content_hash: String,
pub references: Vec<ReferenceRecord>,
pub alias_map: HashMap<String, String>,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum FileOutcome {
Processed,
PartialParse { warning: String },
Failed { error: String },
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct SymbolRecord {
pub name: String,
pub kind: SymbolKind,
pub depth: u32,
pub sort_order: u32,
pub byte_range: (u32, u32),
pub line_range: (u32, u32),
pub doc_byte_range: Option<(u32, u32)>,
#[serde(default)]
pub item_byte_range: Option<(u32, u32)>,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum KnowledgeUnitKind {
MarkdownSection,
TextLine,
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct KnowledgeUnit {
pub source: SourceIdentity,
pub path: String,
pub content_hash: String,
pub kind: KnowledgeUnitKind,
pub heading_path: Vec<String>,
pub byte_range: std::ops::Range<u32>,
pub line_range: std::ops::Range<u32>,
pub parent: Option<u32>,
}
impl SymbolRecord {
pub fn item_start(&self) -> u32 {
self.item_byte_range.map_or_else(
|| {
self.doc_byte_range
.map_or(self.byte_range.0, |(start, _)| start)
},
|(start, _)| start,
)
}
pub fn item_end(&self) -> u32 {
self.item_byte_range
.map_or(self.byte_range.1, |(_, end)| end)
}
pub fn item_range(&self) -> (u32, u32) {
(self.item_start(), self.item_end())
}
pub fn core_range(&self) -> (u32, u32) {
self.byte_range
}
pub fn effective_start(&self) -> u32 {
self.doc_byte_range
.map_or(self.byte_range.0, |(start, _)| start)
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum SymbolKind {
Function,
Method,
Class,
Struct,
Enum,
Interface,
Module,
Constant,
Variable,
Type,
Trait,
Impl,
Other,
Key,
Section,
MacroGenerated,
}
impl fmt::Display for SymbolKind {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let prefix = match self {
Self::Function => "fn",
Self::Method => "fn",
Self::Class => "class",
Self::Struct => "struct",
Self::Enum => "enum",
Self::Interface => "interface",
Self::Module => "mod",
Self::Constant => "const",
Self::Variable => "let",
Self::Type => "type",
Self::Trait => "trait",
Self::Impl => "impl",
Self::Other => "other",
Self::Key => "key",
Self::Section => "section",
Self::MacroGenerated => "macro-generated",
};
write!(f, "{prefix}")
}
}
#[derive(Clone, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct ReferenceRecord {
pub name: String,
pub qualified_name: Option<String>,
pub kind: ReferenceKind,
pub byte_range: (u32, u32),
pub line_range: (u32, u32),
pub enclosing_symbol_index: Option<u32>,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum ReferenceKind {
Call,
Import,
TypeUsage,
MacroUse,
Implements,
ValueUse,
}
impl fmt::Display for ReferenceKind {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let s = match self {
Self::Call => "call",
Self::Import => "import",
Self::TypeUsage => "type_usage",
Self::MacroUse => "macro_use",
Self::Implements => "implements",
Self::ValueUse => "value_use",
};
write!(f, "{s}")
}
}
pub fn find_enclosing_symbol(symbols: &[SymbolRecord], ref_line: u32) -> Option<u32> {
let mut best: Option<(u32, u32)> = None; for (idx, sym) in symbols.iter().enumerate() {
let (start, end) = sym.line_range;
if ref_line >= start && ref_line <= end {
match best {
None => best = Some((start, idx as u32)),
Some((best_start, _)) if start > best_start => best = Some((start, idx as u32)),
_ => {}
}
}
}
best.map(|(_, idx)| idx)
}
pub fn find_enclosing_symbols(symbols: &[SymbolRecord], lines: &[u32]) -> Vec<Option<u32>> {
use std::cmp::Reverse;
let mut by_start: Vec<usize> = (0..symbols.len()).collect();
by_start.sort_by_key(|&idx| symbols[idx].line_range.0);
let mut by_line: Vec<usize> = (0..lines.len()).collect();
by_line.sort_by_key(|&at| lines[at]);
let mut started = std::collections::BinaryHeap::new();
let mut next = 0;
let mut enclosing = vec![None; lines.len()];
for at in by_line {
let line = lines[at];
while let Some(&idx) = by_start.get(next)
&& symbols[idx].line_range.0 <= line
{
let (start, end) = symbols[idx].line_range;
started.push((start, Reverse(idx as u32), end));
next += 1;
}
while started.peek().is_some_and(|&(_, _, end)| end < line) {
started.pop();
}
enclosing[at] = started.peek().map(|&(_, Reverse(idx), _)| idx);
}
enclosing
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum AdmissionTier {
Normal,
MetadataOnly,
HardSkip,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum SkipReason {
SizeCeiling,
DenylistedExtension,
SizeThreshold,
BinaryContent,
DependencyLockfile,
Untracked,
UnsupportedLanguage,
GeneratedOutput,
PolicyWithheld,
UnsupportedTextEncoding,
UnsupportedPath,
LfsPointer,
Unreadable,
}
impl std::fmt::Display for SkipReason {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
SkipReason::SizeCeiling => write!(f, ">100MB"),
SkipReason::DenylistedExtension => write!(f, "artifact"),
SkipReason::SizeThreshold => write!(f, "over size threshold (1MB data / 4MB code)"),
SkipReason::BinaryContent => write!(f, "binary"),
SkipReason::DependencyLockfile => write!(f, "lockfile"),
SkipReason::Untracked => write!(f, "untracked"),
SkipReason::UnsupportedLanguage => write!(f, "unsupported language"),
SkipReason::PolicyWithheld => write!(f, "withheld by admission policy"),
SkipReason::UnsupportedTextEncoding => write!(f, "undecodable text encoding"),
SkipReason::UnsupportedPath => write!(f, "unsupported path"),
SkipReason::LfsPointer => write!(f, "git-lfs pointer"),
SkipReason::Unreadable => write!(f, "unreadable"),
SkipReason::GeneratedOutput => write!(
f,
"untracked generated output (SYMFORGE_INDEX_GENERATED_OUTPUT=1 to index)"
),
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AdmissionDecision {
pub tier: AdmissionTier,
pub reason: Option<SkipReason>,
}
impl AdmissionDecision {
pub fn normal() -> Self {
Self {
tier: AdmissionTier::Normal,
reason: None,
}
}
pub fn skip(tier: AdmissionTier, reason: SkipReason) -> Self {
Self {
tier,
reason: Some(reason),
}
}
}
#[derive(Debug, Clone)]
pub struct SkippedFile {
pub path: String,
pub size: u64,
pub extension: Option<String>,
pub decision: AdmissionDecision,
}
impl SkippedFile {
pub fn tier(&self) -> AdmissionTier {
self.decision.tier
}
pub fn reason(&self) -> Option<SkipReason> {
self.decision.reason
}
}
pub const HARD_SKIP_BYTES: u64 = 100 * 1024 * 1024;
pub const METADATA_ONLY_BYTES: u64 = 1024 * 1024;
pub const METADATA_ONLY_CODE_BYTES: u64 = 4 * 1024 * 1024;
pub const BINARY_SNIFF_BYTES: usize = 8192;
const DENYLISTED_EXTENSIONS: &[&str] = &[
"safetensors",
"ckpt",
"pt",
"onnx",
"gguf",
"pth",
"vmdk",
"iso",
"img",
"qcow2",
"tar",
"gz",
"zip",
"7z",
"rar",
"bz2",
"xz",
"zst",
"db",
"sqlite",
"sqlite3",
"mdb",
"mp3",
"mp4",
"wav",
"avi",
"mov",
"mkv",
"png",
"jpg",
"jpeg",
"gif",
"bmp",
"ico",
"woff",
"woff2",
"ttf",
"eot",
"bin",
"exe",
"dll",
"so",
"dylib",
"class",
];
pub fn is_denylisted_extension(ext: &str) -> bool {
DENYLISTED_EXTENSIONS.contains(&ext.to_lowercase().as_str())
}
const LOCKFILE_BASENAMES: &[&str] = &[
"package-lock.json",
"npm-shrinkwrap.json",
"yarn.lock",
"pnpm-lock.yaml",
"bun.lock",
"Cargo.lock",
"composer.lock",
"Gemfile.lock",
"poetry.lock",
"uv.lock",
"Pipfile.lock",
"flake.lock",
"packages.lock.json",
"go.sum",
];
pub fn is_dependency_lockfile(path: &std::path::Path) -> bool {
path.file_name()
.and_then(|n| n.to_str())
.is_some_and(|name| LOCKFILE_BASENAMES.contains(&name))
}
pub const NUL_OFFSET_SAMPLE_LIMIT: usize = 5;
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct NulScan {
pub count: usize,
pub first_offsets: Vec<usize>,
}
impl NulScan {
pub fn has_nul(&self) -> bool {
self.count > 0
}
}
pub fn scan_nul_bytes(content: &[u8]) -> NulScan {
let mut count = 0usize;
let mut first_offsets = Vec::new();
for (offset, &byte) in content.iter().enumerate() {
if byte == 0 {
count += 1;
if first_offsets.len() < NUL_OFFSET_SAMPLE_LIMIT {
first_offsets.push(offset);
}
}
}
NulScan {
count,
first_offsets,
}
}
pub fn nul_byte_warning_line(scan: &NulScan) -> Option<String> {
if !scan.has_nul() {
return None;
}
let offsets = scan
.first_offsets
.iter()
.map(|o| o.to_string())
.collect::<Vec<_>>()
.join(", ");
let plural = if scan.count == 1 { "" } else { "s" };
let offset_suffix = if scan.count > scan.first_offsets.len() {
format!("{offsets}, ...")
} else {
offsets
};
Some(format!(
"WARNING: this file contains {} NUL byte{plural} (0x00) at byte offset(s) {offset_suffix}. \
They are rendered invisibly above; copied text will NOT byte-match the file. \
Edit this file with byte-exact tools, not rendered text.",
scan.count
))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_symbol_kind_display_function() {
assert_eq!(SymbolKind::Function.to_string(), "fn");
}
#[test]
fn test_is_c_header_path() {
assert!(LanguageId::is_c_header_path("foo.h"));
assert!(LanguageId::is_c_header_path("src/runner/flutter_window.h"));
assert!(LanguageId::is_c_header_path("windows\\runner\\utils.h"));
assert!(LanguageId::is_c_header_path("API.H"));
assert!(!LanguageId::is_c_header_path("foo.hpp"));
assert!(!LanguageId::is_c_header_path("foo.hxx"));
assert!(!LanguageId::is_c_header_path("foo.hh"));
assert!(!LanguageId::is_c_header_path("foo.c"));
assert!(!LanguageId::is_c_header_path("foo.cpp"));
assert!(!LanguageId::is_c_header_path("README"));
assert!(!LanguageId::is_c_header_path("foo.h/bar.c"));
}
#[test]
fn test_symbol_kind_display_method() {
assert_eq!(SymbolKind::Method.to_string(), "fn");
}
#[test]
fn test_symbol_kind_display_class() {
assert_eq!(SymbolKind::Class.to_string(), "class");
}
#[test]
fn test_symbol_kind_display_struct() {
assert_eq!(SymbolKind::Struct.to_string(), "struct");
}
#[test]
fn test_symbol_kind_display_enum() {
assert_eq!(SymbolKind::Enum.to_string(), "enum");
}
#[test]
fn test_symbol_kind_display_interface() {
assert_eq!(SymbolKind::Interface.to_string(), "interface");
}
#[test]
fn test_symbol_kind_display_module() {
assert_eq!(SymbolKind::Module.to_string(), "mod");
}
#[test]
fn test_symbol_kind_display_constant() {
assert_eq!(SymbolKind::Constant.to_string(), "const");
}
#[test]
fn test_symbol_kind_display_variable() {
assert_eq!(SymbolKind::Variable.to_string(), "let");
}
#[test]
fn test_symbol_kind_display_type() {
assert_eq!(SymbolKind::Type.to_string(), "type");
}
#[test]
fn test_symbol_kind_display_trait() {
assert_eq!(SymbolKind::Trait.to_string(), "trait");
}
#[test]
fn test_symbol_kind_display_impl() {
assert_eq!(SymbolKind::Impl.to_string(), "impl");
}
#[test]
fn test_symbol_kind_display_other() {
assert_eq!(SymbolKind::Other.to_string(), "other");
}
#[test]
fn test_reference_kind_all_variants_constructible() {
let _call = ReferenceKind::Call;
let _import = ReferenceKind::Import;
let _type_usage = ReferenceKind::TypeUsage;
let _macro_use = ReferenceKind::MacroUse;
}
#[test]
fn test_reference_kind_display_call() {
assert_eq!(ReferenceKind::Call.to_string(), "call");
}
#[test]
fn test_reference_kind_display_import() {
assert_eq!(ReferenceKind::Import.to_string(), "import");
}
#[test]
fn test_reference_kind_display_type_usage() {
assert_eq!(ReferenceKind::TypeUsage.to_string(), "type_usage");
}
#[test]
fn test_reference_kind_display_macro_use() {
assert_eq!(ReferenceKind::MacroUse.to_string(), "macro_use");
}
#[test]
fn test_reference_record_construction_with_all_fields() {
let r = ReferenceRecord {
name: "foo".to_string(),
qualified_name: Some("Bar::foo".to_string()),
kind: ReferenceKind::Call,
byte_range: (10, 20),
line_range: (1, 1),
enclosing_symbol_index: Some(0),
};
assert_eq!(r.name, "foo");
assert_eq!(r.qualified_name.as_deref(), Some("Bar::foo"));
assert_eq!(r.kind, ReferenceKind::Call);
assert_eq!(r.byte_range, (10, 20));
assert_eq!(r.line_range, (1, 1));
assert_eq!(r.enclosing_symbol_index, Some(0));
}
#[test]
fn test_reference_record_without_optional_fields() {
let r = ReferenceRecord {
name: "baz".to_string(),
qualified_name: None,
kind: ReferenceKind::Import,
byte_range: (0, 5),
line_range: (0, 0),
enclosing_symbol_index: None,
};
assert!(r.qualified_name.is_none());
assert!(r.enclosing_symbol_index.is_none());
}
#[test]
fn test_file_processing_result_backward_compat_with_empty_refs() {
use std::collections::HashMap;
let result = FileProcessingResult {
relative_path: "test.rs".to_string(),
language: LanguageId::Rust,
classification: FileClassification::for_code_path("test.rs"),
outcome: FileOutcome::Processed,
parse_diagnostic: None,
symbols: vec![],
byte_len: 0,
content_hash: "abc".to_string(),
references: vec![],
alias_map: HashMap::new(),
};
assert!(result.references.is_empty());
assert!(result.alias_map.is_empty());
}
#[test]
fn test_file_classification_for_code_path_marks_code_only_by_default() {
let classification = FileClassification::for_code_path("src/lib.rs");
assert!(classification.is_code());
assert!(!classification.is_text());
assert!(!classification.is_binary());
assert!(!classification.is_generated);
assert!(!classification.is_test);
assert!(!classification.is_vendor);
}
#[test]
fn test_file_classification_marks_exact_test_stems_and_testutil() {
for path in [
"src/tests.rs",
"src/test.rs",
"src/protocol/tests.rs",
"src/testutil.rs",
"src/testutils.rs",
"lib/testutil.py",
"pkg/tests.go",
] {
assert!(
FileClassification::for_code_path(path).is_test,
"{path} must classify as a test file"
);
}
}
#[test]
fn test_file_classification_keeps_look_alike_stems_as_source() {
for path in [
"src/contest.rs",
"src/latest.rs",
"src/attest.rs",
"src/protest_handler.rs",
"src/testament.rs",
"src/testing_ground.rs",
] {
assert!(
!FileClassification::for_code_path(path).is_test,
"{path} must stay ordinary source"
);
}
}
#[test]
fn test_file_classification_for_code_path_marks_noise_tags_from_path() {
let generated = FileClassification::for_code_path("src/generated/client.pb.go");
assert!(generated.is_generated);
let test_file = FileClassification::for_code_path("tests/parser_spec.rs");
assert!(test_file.is_test);
let vendor_file = FileClassification::for_code_path("node_modules/pkg/index.js");
assert!(vendor_file.is_vendor);
}
#[test]
fn text_format_matrix_routes_mdx_rst_asciidoc_org_extensionless_and_safe_configs() {
let knowledge_only = [
("guide.mdx", LanguageId::Markdown),
("guide.rst", LanguageId::Text),
("guide.adoc", LanguageId::Text),
("guide.asciidoc", LanguageId::Text),
("guide.org", LanguageId::Text),
("README", LanguageId::Text),
("docs/NOTICE", LanguageId::Text),
];
for (path, expected_language) in knowledge_only {
let language = LanguageId::from_path(path).expect("text format must be recognized");
assert_eq!(language, expected_language);
assert_eq!(
IndexTargets::for_path(path, Some(&language)),
IndexTargets::Knowledge
);
assert!(FileClassification::for_indexed_path(path, IndexTargets::Knowledge).is_text());
}
for (path, expected_language) in [
("openapi.yaml", LanguageId::Yaml),
("schema.json", LanguageId::Json),
("config.toml", LanguageId::Toml),
(".env.example", LanguageId::Env),
("config/settings.ini", LanguageId::Text),
(".gitignore", LanguageId::Text),
] {
let language = LanguageId::from_path(path).expect("safe config must be recognized");
assert_eq!(language, expected_language);
assert_eq!(
IndexTargets::for_path(path, Some(&language)),
IndexTargets::CodeAndKnowledge
);
let classification =
FileClassification::for_indexed_path(path, IndexTargets::CodeAndKnowledge);
assert!(classification.is_code());
assert!(classification.is_config);
}
let rust = LanguageId::from_path("src/lib.rs").expect("Rust must stay recognized");
assert_eq!(
IndexTargets::for_path("src/lib.rs", Some(&rust)),
IndexTargets::Code
);
}
#[test]
fn test_find_enclosing_symbol_innermost_for_nested() {
let symbols = vec![
SymbolRecord {
name: "outer".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (0, 100),
line_range: (0, 10),
doc_byte_range: None,
item_byte_range: None,
},
SymbolRecord {
name: "inner".to_string(),
kind: SymbolKind::Function,
depth: 1,
sort_order: 1,
byte_range: (30, 60),
line_range: (3, 6),
doc_byte_range: None,
item_byte_range: None,
},
];
let idx = find_enclosing_symbol(&symbols, 4);
assert_eq!(idx, Some(1), "should return innermost enclosing symbol");
}
#[test]
fn test_find_enclosing_symbol_none_at_module_level() {
let symbols = vec![SymbolRecord {
name: "foo".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (50, 100),
line_range: (5, 10),
doc_byte_range: None,
item_byte_range: None,
}];
let idx = find_enclosing_symbol(&symbols, 0);
assert_eq!(idx, None, "should return None when not inside any symbol");
}
#[test]
fn test_find_enclosing_symbols_matches_single_line_rule() {
let symbols: Vec<SymbolRecord> = [(0, 40), (2, 9), (2, 9), (5, 6), (12, 20), (30, 25)]
.into_iter()
.map(|line_range| SymbolRecord {
name: "s".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (0, 1),
line_range,
doc_byte_range: None,
item_byte_range: None,
})
.collect();
let lines: Vec<u32> = [7, 0, 45, 5, 2, 20, 27, 9, 10, 6, 5].to_vec();
let expected: Vec<Option<u32>> = lines
.iter()
.map(|&line| find_enclosing_symbol(&symbols, line))
.collect();
assert_eq!(find_enclosing_symbols(&symbols, &lines), expected);
assert_eq!(expected[3], Some(3));
assert_eq!(expected[4], Some(1));
}
#[test]
fn test_symbol_record_item_helpers_fall_back_to_doc_range() {
let symbol = SymbolRecord {
name: "target".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (20, 40),
line_range: (1, 3),
doc_byte_range: Some((10, 20)),
item_byte_range: None,
};
assert_eq!(symbol.item_start(), 10);
assert_eq!(symbol.item_end(), 40);
assert_eq!(symbol.item_range(), (10, 40));
assert_eq!(symbol.core_range(), (20, 40));
}
#[test]
fn test_symbol_record_item_helpers_prefer_item_range() {
let symbol = SymbolRecord {
name: "target".to_string(),
kind: SymbolKind::Function,
depth: 0,
sort_order: 0,
byte_range: (20, 40),
line_range: (1, 3),
doc_byte_range: Some((10, 20)),
item_byte_range: Some((5, 44)),
};
assert_eq!(symbol.item_start(), 5);
assert_eq!(symbol.item_end(), 44);
assert_eq!(symbol.item_range(), (5, 44));
assert_eq!(symbol.core_range(), (20, 40));
}
#[test]
fn test_admission_tier_variants() {
let t1 = AdmissionTier::Normal;
let t2 = AdmissionTier::MetadataOnly;
let t3 = AdmissionTier::HardSkip;
assert_ne!(t1, t2);
assert_ne!(t2, t3);
assert_ne!(t1, t3);
}
#[test]
fn test_extension_is_denylisted() {
assert!(is_denylisted_extension("safetensors"));
assert!(is_denylisted_extension("ckpt"));
assert!(is_denylisted_extension("zip"));
assert!(is_denylisted_extension("mp4"));
assert!(is_denylisted_extension("woff2"));
assert!(is_denylisted_extension("png"));
assert!(is_denylisted_extension("bin"));
}
#[test]
fn test_extension_not_denylisted() {
assert!(!is_denylisted_extension("rs"));
assert!(!is_denylisted_extension("ts"));
assert!(!is_denylisted_extension("json"));
assert!(!is_denylisted_extension("svg")); assert!(!is_denylisted_extension("md"));
assert!(!is_denylisted_extension("toml"));
}
#[test]
fn test_new_executable_extensions_denylisted() {
assert!(is_denylisted_extension("exe"));
assert!(is_denylisted_extension("dll"));
assert!(is_denylisted_extension("so"));
assert!(is_denylisted_extension("dylib"));
assert!(is_denylisted_extension("class"));
}
#[test]
fn test_denylist_case_insensitive() {
assert!(is_denylisted_extension("DLL"));
assert!(is_denylisted_extension("So"));
assert!(is_denylisted_extension("EXE"));
assert!(is_denylisted_extension("Dylib"));
assert!(is_denylisted_extension("CLASS"));
}
#[test]
fn test_skipped_file_creation() {
let decision =
AdmissionDecision::skip(AdmissionTier::MetadataOnly, SkipReason::DenylistedExtension);
let sf = SkippedFile {
path: "model.safetensors".into(),
size: 4_200_000_000,
extension: Some("safetensors".into()),
decision,
};
assert_eq!(sf.tier(), AdmissionTier::MetadataOnly);
assert_eq!(sf.reason(), Some(SkipReason::DenylistedExtension));
}
#[test]
fn test_scan_nul_bytes_clean_slice_reports_none() {
let scan = scan_nul_bytes(b"fn main() {}\n");
assert!(!scan.has_nul());
assert_eq!(scan.count, 0);
assert!(scan.first_offsets.is_empty());
assert_eq!(nul_byte_warning_line(&scan), None);
}
#[test]
fn test_scan_nul_bytes_empty_slice_reports_none() {
let scan = scan_nul_bytes(b"");
assert!(!scan.has_nul());
assert_eq!(nul_byte_warning_line(&scan), None);
}
#[test]
fn test_scan_nul_bytes_single_offset_and_singular_warning() {
let scan = scan_nul_bytes(b"ab\0cd");
assert_eq!(scan.count, 1);
assert_eq!(scan.first_offsets, vec![2]);
let warning = nul_byte_warning_line(&scan).expect("NUL present");
assert!(warning.contains("1 NUL byte (0x00)"), "warning: {warning}");
assert!(
warning.contains("byte offset(s) 2."),
"single offset, no ellipsis: {warning}"
);
assert!(warning.contains("byte-exact tools"));
}
#[test]
fn test_scan_nul_bytes_plural_warning() {
let scan = scan_nul_bytes(b"\0a\0b");
assert_eq!(scan.count, 2);
assert_eq!(scan.first_offsets, vec![0, 2]);
let warning = nul_byte_warning_line(&scan).expect("NUL present");
assert!(warning.contains("2 NUL bytes (0x00)"), "warning: {warning}");
assert!(
warning.contains("byte offset(s) 0, 2."),
"warning: {warning}"
);
}
#[test]
fn test_scan_nul_bytes_caps_offsets_and_adds_ellipsis() {
let scan = scan_nul_bytes(b"\0\0\0\0\0\0\0");
assert_eq!(scan.count, 7);
assert_eq!(scan.first_offsets.len(), NUL_OFFSET_SAMPLE_LIMIT);
assert_eq!(scan.first_offsets, vec![0, 1, 2, 3, 4]);
let warning = nul_byte_warning_line(&scan).expect("NUL present");
assert!(warning.contains("7 NUL bytes"), "warning: {warning}");
assert!(
warning.contains("0, 1, 2, 3, 4, ..."),
"more NULs than sampled => ellipsis: {warning}"
);
}
#[test]
fn parse_status_is_bounded_and_digest_stable() {
let old_diagnostic = FileOutcome::PartialParse {
warning: "unexpected token near heading".to_string(),
};
let reworded_diagnostic = FileOutcome::PartialParse {
warning: "heading contains recoverable syntax".to_string(),
};
let old_knowledge_status = ParseStatus::from_operational_outcome(&old_diagnostic);
let reworded_knowledge_status = ParseStatus::from_operational_outcome(&reworded_diagnostic);
assert_eq!(old_knowledge_status, ParseStatus::PartialParse);
assert_eq!(old_knowledge_status, reworded_knowledge_status);
let entry = |knowledge_status| CatalogEntry {
path: CatalogPath {
public_id: "path:README.md".to_string(),
normalized_utf8: Some("README.md".to_string()),
},
size: 42,
language: Some(LanguageId::Markdown),
classification: FileClassification::for_code_path("README.md"),
disposition: FileDisposition::Indexed {
targets: IndexTargets::Knowledge,
parse_status: ParseStatus::aggregate_for_targets(
IndexTargets::Knowledge,
Some(ParseStatus::Failed),
Some(knowledge_status),
),
},
content_hash: Some("stable-content-hash".to_string()),
};
let source = SourceIdentity {
repository_id: RepositoryId::new("repository-fixture"),
source_id: SourceId::new("source-fixture"),
location: SourceLocation::WorkingTree {
worktree_id: "worktree-fixture".to_string(),
},
};
let source_version = SourceVersion {
branch: Some("main".to_string()),
commit: Some("0123456789abcdef".to_string()),
working_tree: WorkingTreeState::Clean,
};
let usage = ManifestResourceUsage {
catalog_entries: 1,
catalog_metadata_bytes: 256,
admitted_content_bytes: 42,
};
let old_manifest = RepositoryManifest::new(
1,
1,
1,
source.clone(),
source_version.clone(),
CoverageStatus::Complete,
vec![entry(old_knowledge_status)],
Vec::new(),
usage,
)
.unwrap();
let reworded_manifest = RepositoryManifest::new(
1,
1,
1,
source,
source_version,
CoverageStatus::Complete,
vec![entry(reworded_knowledge_status)],
Vec::new(),
usage,
)
.unwrap();
assert!(matches!(
old_manifest.entries[0].disposition,
FileDisposition::Indexed {
targets: IndexTargets::Knowledge,
parse_status: ParseStatus::PartialParse,
}
));
assert_eq!(old_manifest.digest, reworded_manifest.digest);
}
#[test]
fn policy_withheld_never_claims_a_language_problem() {
let withheld = SkipReason::PolicyWithheld.to_string();
assert!(
!withheld.contains("language"),
"a policy exclusion must not be reported as a language problem, got: {withheld}"
);
assert!(
!withheld.contains("size") && !withheld.contains("MB"),
"and must not be reported as a size problem either, got: {withheld}"
);
for leak in ["path", "content", "secret", "detector", "rule"] {
assert!(
!withheld.contains(leak),
"policy refusal must stay neutral; leaked {leak:?} in: {withheld}"
);
}
}
#[test]
fn non_sensitive_skip_reasons_are_distinct_and_honest() {
let encoding = SkipReason::UnsupportedTextEncoding.to_string();
let language = SkipReason::UnsupportedLanguage.to_string();
let path = SkipReason::UnsupportedPath.to_string();
let lfs = SkipReason::LfsPointer.to_string();
let unreadable = SkipReason::Unreadable.to_string();
assert_ne!(encoding, language);
assert!(encoding.contains("encoding"), "got: {encoding}");
assert!(path.contains("path"), "got: {path}");
assert!(lfs.contains("lfs"), "got: {lfs}");
assert!(
!unreadable.contains("language"),
"an unreadable file must not be reported as a language problem, got: {unreadable}"
);
let all = [&encoding, &language, &path, &lfs, &unreadable];
for (i, left) in all.iter().enumerate() {
for right in all.iter().skip(i + 1) {
assert_ne!(left, right, "skip reasons must not share wording");
}
}
}
}