file_identify/classify.rs
1//! Path classification: identify's `tags_from_path`, split into a pure
2//! planning step ([`classify()`]) and at most one bounded read.
3
4use std::fs::{self, File};
5use std::io::{self, Read};
6use std::path::Path;
7
8use crate::error::{IdentifyError, Result};
9use crate::filename::{tags_from_filename, tags_from_interpreter};
10use crate::meta::{ExecPolicy, FileKind, Meta};
11use crate::shebang::{Source, parse_shebang_buf};
12use crate::tags::{Tag, TagSet};
13use crate::text::{TEXT_PROBE_LEN, is_text, is_text_bytes, read_full};
14
15/// Outcome of [`classify()`].
16#[derive(Clone, Copy, Debug, PartialEq, Eq)]
17pub enum Classification {
18 /// The tags are final; the file does not need to be read.
19 Done(TagSet),
20 /// The file's leading bytes are needed; finish with [`Pending`].
21 NeedsContent(Pending),
22}
23
24/// A classification waiting for file content (see [`classify()`]).
25///
26/// Content is needed when the name gives no `text`/`binary` tag (unknown
27/// names and [`EXTENSIONS_NEED_BINARY_CHECK`](crate::extensions::EXTENSIONS_NEED_BINARY_CHECK)
28/// entries) and, for executable files with an unknown name, to read the
29/// shebang.
30#[derive(Clone, Copy, Debug, PartialEq, Eq)]
31pub struct Pending {
32 tags: TagSet,
33 shebang: bool,
34}
35
36impl Pending {
37 /// The tags known so far (type, mode and name tags).
38 #[must_use]
39 pub const fn tags(&self) -> TagSet {
40 self.tags
41 }
42
43 /// Whether the shebang must be parsed (an executable file whose name
44 /// gave no tags).
45 #[must_use]
46 pub const fn needs_shebang(&self) -> bool {
47 self.shebang
48 }
49
50 /// Whether `text`/`binary` must be decided from the content (always
51 /// true when [`needs_shebang`](Pending::needs_shebang) is).
52 #[must_use]
53 pub const fn needs_encoding(&self) -> bool {
54 !self.tags.has_encoding()
55 }
56
57 /// Finish from the file's content read from its start.
58 ///
59 /// Reads [`TEXT_PROBE_LEN`] bytes (fewer at end of input); only a shebang
60 /// line longer than that reads further, bounded by
61 /// [`MAX_SHEBANG_BYTES`](crate::MAX_SHEBANG_BYTES).
62 ///
63 /// # Errors
64 ///
65 /// Propagates read errors.
66 pub fn finish<R: Read>(self, mut reader: R) -> io::Result<TagSet> {
67 let mut head = [0u8; TEXT_PROBE_LEN];
68 let n = read_full(&mut reader, &mut head)?;
69 self.finish_with_head(head.get(..n).unwrap_or_default(), reader)
70 }
71
72 /// Finish from in-memory content (the whole file or at least its first
73 /// [`TEXT_PROBE_LEN`] bytes plus the shebang line).
74 ///
75 /// ```
76 /// use file_identify::{Classification, Meta, classify};
77 ///
78 /// let Classification::NeedsContent(pending) = classify(Meta::regular(true), "bin/tool") else {
79 /// unreachable!()
80 /// };
81 /// let tags = pending.finish_bytes(b"#!/usr/bin/env python3\nprint('hi')\n");
82 /// assert_eq!(tags.to_string(), "executable, file, python, python3, text");
83 /// ```
84 #[must_use]
85 pub fn finish_bytes(self, content: &[u8]) -> TagSet {
86 let head = content.get(..TEXT_PROBE_LEN).unwrap_or(content);
87 let rest = content.get(head.len()..).unwrap_or_default();
88 self.finish_with_head(head, rest).unwrap_or(self.tags)
89 }
90
91 /// `head` is the first `min(len, TEXT_PROBE_LEN)` bytes; `rest` continues
92 /// right after it.
93 fn finish_with_head<R: Read>(self, head: &[u8], rest: R) -> io::Result<TagSet> {
94 let mut tags = self.tags;
95 if self.shebang {
96 let cmd = parse_shebang_buf(&mut Source::new(head, rest))?;
97 if let Some(interpreter) = cmd.first() {
98 tags = tags.union(tags_from_interpreter(interpreter));
99 }
100 }
101 if !tags.has_encoding() {
102 tags.insert(if is_text_bytes(head) {
103 Tag::TEXT
104 } else {
105 Tag::BINARY
106 });
107 }
108 Ok(tags)
109 }
110}
111
112/// The I/O-free part of `identify.tags_from_path`: everything that follows
113/// from the entry's [`Meta`] and name.
114///
115/// `path` may include directories (only the base name is used); see
116/// [`tags_from_filename`] for the name rules. Directories, symlinks and
117/// sockets are [`Done`](Classification::Done) with a single type tag. A
118/// regular file gets `file`, `executable`/`non-executable` and its name tags;
119/// it needs content only if that leaves no `text`/`binary` tag.
120///
121/// [`FileKind::Other`] (FIFOs, devices) is never read: it is classified like
122/// a regular file whose content is unavailable and tagged `binary` when the
123/// name does not decide the encoding. (identify would open it, which blocks
124/// forever on a FIFO.)
125///
126/// ```
127/// use file_identify::{Classification, Meta, classify};
128///
129/// // Known extension: no I/O needed at all.
130/// let Classification::Done(tags) = classify(Meta::regular(false), "src/lib.rs") else {
131/// unreachable!()
132/// };
133/// assert_eq!(tags.to_string(), "file, non-executable, rust, text");
134///
135/// // Unknown name: the first bytes decide text vs binary.
136/// let Classification::NeedsContent(pending) = classify(Meta::regular(false), "data.bin2") else {
137/// unreachable!()
138/// };
139/// assert!(pending.needs_encoding() && !pending.needs_shebang());
140/// assert_eq!(pending.finish_bytes(b"\0\x01").to_string(), "binary, file, non-executable");
141/// ```
142#[must_use]
143pub fn classify(meta: Meta, path: impl AsRef<[u8]>) -> Classification {
144 let kind = meta.kind();
145 let tags = match kind {
146 FileKind::Directory => return Classification::Done(TagSet::from_tag(Tag::DIRECTORY)),
147 FileKind::Symlink => return Classification::Done(TagSet::from_tag(Tag::SYMLINK)),
148 FileKind::Socket => return Classification::Done(TagSet::from_tag(Tag::SOCKET)),
149 FileKind::Regular | FileKind::Other => {
150 TagSet::from_tag(Tag::FILE).with(if meta.is_executable() {
151 Tag::EXECUTABLE
152 } else {
153 Tag::NON_EXECUTABLE
154 })
155 }
156 };
157 let name_tags = tags_from_filename(path);
158 let shebang = name_tags.is_empty() && meta.is_executable();
159 let mut tags = tags.union(name_tags);
160 if kind == FileKind::Other {
161 if !tags.has_encoding() {
162 tags.insert(Tag::BINARY);
163 }
164 return Classification::Done(tags);
165 }
166 if !shebang && tags.has_encoding() {
167 Classification::Done(tags)
168 } else {
169 Classification::NeedsContent(Pending { tags, shebang })
170 }
171}
172
173/// The bytes of a path as Python sees them (raw bytes on Unix, WTF-8 on
174/// Windows).
175fn path_bytes(path: &Path) -> &[u8] {
176 path.as_os_str().as_encoded_bytes()
177}
178
179/// Open for reading without blocking on FIFOs (defence in depth: callers
180/// only open entries believed to be regular files).
181fn open_for_read(path: &Path) -> io::Result<File> {
182 #[cfg(unix)]
183 {
184 use std::os::unix::fs::OpenOptionsExt;
185 let nonblock = i32::try_from(rustix::fs::OFlags::NONBLOCK.bits()).unwrap_or(0);
186 fs::OpenOptions::new()
187 .read(true)
188 .custom_flags(nonblock)
189 .open(path)
190 }
191 #[cfg(not(unix))]
192 {
193 File::open(path)
194 }
195}
196
197/// Run the content step for `path`, opening it once.
198fn finish_from_file(path: &Path, pending: Pending, len_hint: Option<u64>) -> Result<TagSet> {
199 let file = open_for_read(path).map_err(|e| {
200 if e.kind() == io::ErrorKind::NotFound {
201 // identify re-checks `os.path.lexists` right before opening.
202 IdentifyError::not_found(path, e)
203 } else {
204 IdentifyError::from(e)
205 }
206 })?;
207 Ok(finish_sized(pending, file, len_hint)?)
208}
209
210/// [`Pending::finish`] for a file believed to be `len_hint` bytes long: a
211/// file smaller than [`TEXT_PROBE_LEN`] is read with a single `read` (no
212/// extra `read` just to observe the end of the file). Without a hint, or for
213/// an empty file (whose size may be unknown, as in `/proc`), up to
214/// [`TEXT_PROBE_LEN`] bytes are requested.
215fn finish_sized<R: Read>(
216 pending: Pending,
217 mut file: R,
218 len_hint: Option<u64>,
219) -> io::Result<TagSet> {
220 let want = match len_hint {
221 Some(len) if len > 0 => {
222 usize::try_from(len).map_or(TEXT_PROBE_LEN, |l| l.min(TEXT_PROBE_LEN))
223 }
224 _ => TEXT_PROBE_LEN,
225 };
226 let mut head = [0u8; TEXT_PROBE_LEN];
227 let n = read_full(&mut file, head.get_mut(..want).unwrap_or_default())?;
228 pending.finish_with_head(head.get(..n).unwrap_or_default(), file)
229}
230
231/// Identify a path, exactly like `identify.tags_from_path`, with
232/// [`ExecPolicy::PythonCompat`].
233///
234/// Cost: one `lstat`; the file is opened at most once and only when its name
235/// does not determine `text`/`binary` (or it is an executable with an
236/// unknown name, whose shebang is then read from the same buffer). At most
237/// 1 KiB is read, plus the rest of an unusually long shebang line.
238///
239/// Differences from identify, all deliberate: FIFOs and devices are never
240/// opened (see [`classify()`]); shebang lines longer than
241/// [`MAX_SHEBANG_BYTES`](crate::MAX_SHEBANG_BYTES) are ignored.
242///
243/// # Errors
244///
245/// * [`IdentifyError::PathNotFound`] (`"{path} does not exist."`) if `lstat`
246/// fails, or the file vanishes before it is opened;
247/// * [`IdentifyError::IoError`] if opening or reading the file fails.
248///
249/// ```
250/// # let dir = tempfile::tempdir()?;
251/// # let path = dir.path().join("setup.py");
252/// # std::fs::write(&path, "print('hello')\n")?;
253/// use file_identify::{Tag, tags_from_path};
254///
255/// let tags = tags_from_path(&path)?;
256/// // "file, non-executable, python, text" (on Windows identify reports
257/// // every file as executable)
258/// assert!(tags.contains(Tag::FILE) && tags.contains("python") && tags.contains(Tag::TEXT));
259/// # Ok::<(), Box<dyn std::error::Error>>(())
260/// ```
261pub fn tags_from_path(path: impl AsRef<Path>) -> Result<TagSet> {
262 tags_from_path_with(path, ExecPolicy::PythonCompat)
263}
264
265/// [`tags_from_path`] with an explicit [`ExecPolicy`].
266///
267/// # Errors
268///
269/// As for [`tags_from_path`].
270pub fn tags_from_path_with(path: impl AsRef<Path>, policy: ExecPolicy) -> Result<TagSet> {
271 let path = path.as_ref();
272 let md = fs::symlink_metadata(path).map_err(|e| IdentifyError::not_found(path, e))?;
273 tags_from_metadata(path, &md, policy)
274}
275
276/// Identify a path whose `lstat` metadata ([`fs::symlink_metadata`]) the
277/// caller already holds, e.g. from an existence check (pre-commit filters
278/// files with `os.path.lexists` before identifying them).
279///
280/// This is [`tags_from_path_with`] without its `lstat`: the result is the
281/// same, and the file size from `metadata` lets a small file be read with a
282/// single `read` (open, read, close) instead of a second `read` to observe
283/// the end of the file. Pass metadata that does not follow symlinks;
284/// metadata from [`fs::metadata`] describes the link target instead.
285///
286/// # Errors
287///
288/// [`IdentifyError::PathNotFound`] if the file has to be opened but no
289/// longer exists; [`IdentifyError::IoError`] for other open or read
290/// failures.
291///
292/// ```
293/// # let dir = tempfile::tempdir()?;
294/// # let path = dir.path().join("notes.unknownext");
295/// # std::fs::write(&path, "hello\n")?;
296/// use file_identify::{ExecPolicy, tags_from_metadata, tags_from_path};
297///
298/// // The caller's own existence check ...
299/// let md = std::fs::symlink_metadata(&path)?;
300/// // ... is reused for identification: no second lstat.
301/// let tags = tags_from_metadata(&path, &md, ExecPolicy::PythonCompat)?;
302/// assert_eq!(tags, tags_from_path(&path)?);
303/// # Ok::<(), Box<dyn std::error::Error>>(())
304/// ```
305pub fn tags_from_metadata(
306 path: impl AsRef<Path>,
307 metadata: &fs::Metadata,
308 policy: ExecPolicy,
309) -> Result<TagSet> {
310 let path = path.as_ref();
311 let meta = Meta::from_metadata(metadata, policy);
312 match classify(meta, path_bytes(path)) {
313 Classification::Done(tags) => Ok(tags),
314 Classification::NeedsContent(pending) => {
315 finish_from_file(path, pending, Some(metadata.len()))
316 }
317 }
318}
319
320/// Identify a path whose [`Meta`] is already known (e.g. from
321/// [`Meta::from_git_mode`]), without `lstat`.
322///
323/// No system call is made when the name decides everything; otherwise the
324/// file is opened once, as in [`tags_from_path`]. The meta is trusted: a
325/// path that does not exist is only reported when it has to be opened.
326///
327/// A [`Meta`] carries no file size, so a file that has to be read costs one
328/// more `read` (to observe its end) than with [`tags_from_metadata`]; use
329/// that when you hold `lstat` metadata.
330///
331/// A meta from [`Meta::from_git_mode`] describes the index; the result
332/// matches identify only where the work tree agrees. A `120000` entry
333/// yields `symlink`, but with `core.symlinks=false` (usual on Windows) the
334/// work tree has a regular file there: on Windows, or whenever
335/// `core.symlinks` is false, identify such entries with [`tags_from_path`].
336///
337/// # Errors
338///
339/// [`IdentifyError::PathNotFound`] if the file has to be opened but does not
340/// exist; [`IdentifyError::IoError`] for other open or read failures.
341///
342/// ```
343/// use file_identify::{Meta, tags_from_meta};
344///
345/// // 100644 from `git ls-files -s`: no file access needed for a .py file.
346/// let meta = Meta::from_git_mode(0o100644).expect("regular file");
347/// let tags = tags_from_meta("does/not/even/exist.py", meta)?;
348/// assert_eq!(tags.to_string(), "file, non-executable, python, text");
349/// # Ok::<(), file_identify::IdentifyError>(())
350/// ```
351pub fn tags_from_meta(path: impl AsRef<Path>, meta: Meta) -> Result<TagSet> {
352 let path = path.as_ref();
353 match classify(meta, path_bytes(path)) {
354 Classification::Done(tags) => Ok(tags),
355 Classification::NeedsContent(pending) => finish_from_file(path, pending, None),
356 }
357}
358
359/// Whether the file at `path` looks like text, like `identify.file_is_text`
360/// (reads at most [`TEXT_PROBE_LEN`] bytes).
361///
362/// Symlinks are followed for reading, as in Python. FIFOs and devices are
363/// never opened and report `false` (binary).
364///
365/// # Errors
366///
367/// [`IdentifyError::PathNotFound`] if the path does not exist (`lstat`
368/// fails); [`IdentifyError::IoError`] if opening or reading fails (e.g. a
369/// dangling symlink or a directory).
370pub fn file_is_text(path: impl AsRef<Path>) -> Result<bool> {
371 let path = path.as_ref();
372 let md = fs::symlink_metadata(path).map_err(|e| IdentifyError::not_found(path, e))?;
373 let file_type = if md.file_type().is_symlink() {
374 fs::metadata(path)?.file_type()
375 } else {
376 md.file_type()
377 };
378 if FileKind::from_file_type(file_type) == FileKind::Other {
379 return Ok(false);
380 }
381 Ok(is_text(open_for_read(path)?)?)
382}
383
384/// Parse the shebang of the file at `path`, like
385/// `identify.parse_shebang_from_file`: empty unless the file is executable
386/// ([`ExecPolicy::PythonCompat`]: always on Windows), otherwise
387/// [`parse_shebang`](crate::parse_shebang) on its content.
388///
389/// The result is the full command (interpreter and arguments), as used by
390/// pre-commit to build the argv of hook scripts.
391///
392/// # Errors
393///
394/// [`IdentifyError::PathNotFound`] if the path does not exist;
395/// [`IdentifyError::IoError`] if opening or reading fails, except for an
396/// error Python reports as `EINVAL`, which yields an empty result as in
397/// identify (on Windows that is every error the C runtime does not map to
398/// another `errno`, e.g. `ERROR_INVALID_NAME` or `ERROR_CANT_ACCESS_FILE`).
399/// FIFOs and devices are never opened (empty result).
400///
401/// ```
402/// # let dir = tempfile::tempdir()?;
403/// # let path = dir.path().join("tool");
404/// # std::fs::write(&path, "#!/usr/bin/env -S python3 -u\n")?;
405/// # #[cfg(unix)] {
406/// # use std::os::unix::fs::PermissionsExt;
407/// # std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755))?;
408/// # }
409/// use file_identify::parse_shebang_from_file;
410///
411/// assert_eq!(parse_shebang_from_file(&path)?, ["python3", "-u"]);
412/// # Ok::<(), Box<dyn std::error::Error>>(())
413/// ```
414pub fn parse_shebang_from_file(path: impl AsRef<Path>) -> Result<Vec<String>> {
415 parse_shebang_from_file_with(path, ExecPolicy::PythonCompat)
416}
417
418/// [`parse_shebang_from_file`] with an explicit [`ExecPolicy`] deciding
419/// whether the file is executable (and therefore read at all).
420///
421/// With [`ExecPolicy::ModeBits`] only files with the owner `x` bit are read,
422/// on every platform (so on Windows the result is always empty), which
423/// agrees with [`tags_from_path_with`] and with a git index mode.
424///
425/// # Errors
426///
427/// As for [`parse_shebang_from_file`].
428///
429/// ```
430/// # let dir = tempfile::tempdir()?;
431/// # let path = dir.path().join("tool");
432/// # std::fs::write(&path, "#!/bin/sh\n")?;
433/// use file_identify::{ExecPolicy, parse_shebang_from_file_with};
434///
435/// # #[cfg(unix)] {
436/// # use std::os::unix::fs::PermissionsExt;
437/// // Owner x bit set: the shebang is read under both policies.
438/// std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o744))?;
439/// assert_eq!(parse_shebang_from_file_with(&path, ExecPolicy::ModeBits)?, ["/bin/sh"]);
440/// // Group and other x bits only: git stages 100644, so ModeBits says no.
441/// std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o655))?;
442/// assert!(parse_shebang_from_file_with(&path, ExecPolicy::ModeBits)?.is_empty());
443/// # }
444/// # Ok::<(), Box<dyn std::error::Error>>(())
445/// ```
446pub fn parse_shebang_from_file_with(
447 path: impl AsRef<Path>,
448 policy: ExecPolicy,
449) -> Result<Vec<String>> {
450 let path = path.as_ref();
451 let md = fs::symlink_metadata(path).map_err(|e| IdentifyError::not_found(path, e))?;
452 let md = if md.file_type().is_symlink() {
453 match fs::metadata(path) {
454 Ok(target) => target,
455 // os.access() is False for a dangling symlink.
456 Err(_) => return Ok(Vec::new()),
457 }
458 } else {
459 md
460 };
461 if !policy.is_executable(&md) || FileKind::from_file_type(md.file_type()) == FileKind::Other {
462 return Ok(Vec::new());
463 }
464 shebang_unless_einval(open_for_read(path))
465}
466
467/// The body of identify's
468/// `try: with open(path, 'rb') as f: return parse_shebang(f)` /
469/// `except OSError as e: if e.errno == errno.EINVAL: return ()`: an `EINVAL`
470/// from opening *or reading* gives an empty command.
471fn shebang_unless_einval<R: Read>(file: io::Result<R>) -> Result<Vec<String>> {
472 match file.and_then(|file| parse_shebang_buf(&mut Source::new(&[], file))) {
473 Ok(cmd) => Ok(cmd),
474 Err(e) if is_python_einval(&e) => Ok(Vec::new()),
475 Err(e) => Err(e.into()),
476 }
477}
478
479/// Whether Python would raise `err` as an `OSError` with `errno == EINVAL`.
480#[cfg(unix)]
481fn is_python_einval(err: &io::Error) -> bool {
482 err.raw_os_error() == Some(rustix::io::Errno::INVAL.raw_os_error())
483}
484
485/// Whether Python would raise `err` as an `OSError` with `errno == EINVAL`.
486///
487/// `open` and `read` go through the C runtime there (`_wopen`, `_read`),
488/// which maps the Win32 error code to `errno`.
489#[cfg(windows)]
490fn is_python_einval(err: &io::Error) -> bool {
491 err.raw_os_error()
492 .and_then(|code| u32::try_from(code).ok())
493 .is_some_and(crt_errno_is_einval)
494}
495
496/// Whether Python would raise `err` as an `OSError` with `errno == EINVAL`.
497#[cfg(not(any(unix, windows)))]
498fn is_python_einval(err: &io::Error) -> bool {
499 err.raw_os_error().is_some() && err.kind() == io::ErrorKind::InvalidInput
500}
501
502/// Whether the Microsoft C runtime maps the Win32 error `code` to `EINVAL`
503/// (`__acrt_errno_from_os_error`): every code that is neither in its table
504/// of other `errno` values nor in its `EACCES` (19..=36) or `ENOEXEC`
505/// (188..=202) ranges.
506#[cfg(any(windows, test))]
507const fn crt_errno_is_einval(code: u32) -> bool {
508 !matches!(
509 code,
510 2..=11
511 | 15..=36
512 | 53
513 | 65
514 | 67
515 | 80
516 | 82
517 | 83
518 | 89
519 | 108
520 | 109
521 | 112
522 | 114
523 | 128..=130
524 | 132
525 | 145
526 | 158
527 | 161
528 | 164
529 | 167
530 | 183
531 | 188..=202
532 | 206
533 | 215
534 | 1816
535 )
536}
537
538/// Pre-loaded file information for I/O-free identification (kept for
539/// compatibility; [`classify()`] + [`Pending::finish_bytes`] is the more
540/// flexible equivalent).
541#[derive(Clone, Copy, Debug)]
542pub struct FileInfo<'a> {
543 /// The file name (directories are ignored).
544 pub filename: &'a str,
545 /// The kind of file-system entry.
546 pub file_kind: FileKind,
547 /// Whether the file is executable.
548 pub is_executable: bool,
549 /// The file content (at least the first [`TEXT_PROBE_LEN`] bytes), or
550 /// `None` if unavailable — then the result may lack a `text`/`binary`
551 /// tag.
552 pub content: Option<&'a [u8]>,
553}
554
555/// Identify a file from [`FileInfo`] without any I/O.
556///
557/// ```
558/// use file_identify::{FileInfo, FileKind, tags_from_info};
559///
560/// let info = FileInfo {
561/// filename: "script",
562/// file_kind: FileKind::Regular,
563/// is_executable: true,
564/// content: Some(b"#!/bin/bash\necho hi\n"),
565/// };
566/// assert_eq!(tags_from_info(&info).to_string(), "bash, executable, file, shell, text");
567/// ```
568#[must_use]
569pub fn tags_from_info(info: &FileInfo<'_>) -> TagSet {
570 match classify(Meta::new(info.file_kind, info.is_executable), info.filename) {
571 Classification::Done(tags) => tags,
572 Classification::NeedsContent(pending) => match info.content {
573 Some(content) => pending.finish_bytes(content),
574 None => pending.tags(),
575 },
576 }
577}
578
579#[cfg(test)]
580mod tests {
581 use super::*;
582
583 fn done(meta: Meta, name: &str) -> Option<String> {
584 match classify(meta, name) {
585 Classification::Done(tags) => Some(tags.to_string()),
586 Classification::NeedsContent(_) => None,
587 }
588 }
589
590 #[test]
591 fn classify_kinds() {
592 assert_eq!(
593 done(Meta::new(FileKind::Directory, true), "x.py").as_deref(),
594 Some("directory")
595 );
596 assert_eq!(
597 done(Meta::new(FileKind::Symlink, false), "x.py").as_deref(),
598 Some("symlink")
599 );
600 assert_eq!(
601 done(Meta::new(FileKind::Socket, false), "x").as_deref(),
602 Some("socket")
603 );
604 assert_eq!(
605 done(Meta::new(FileKind::Other, true), "fifo").as_deref(),
606 Some("binary, executable, file")
607 );
608 assert_eq!(
609 done(Meta::new(FileKind::Other, false), "x.txt").as_deref(),
610 Some("file, non-executable, plain-text, text")
611 );
612 assert_eq!(
613 done(Meta::regular(true), "x.py").as_deref(),
614 Some("executable, file, python, text")
615 );
616 // Name tags present: the shebang is not consulted even if executable.
617 assert_eq!(
618 done(Meta::regular(true), "x.sh").as_deref(),
619 Some("executable, file, shell, text")
620 );
621 }
622
623 #[test]
624 fn pending_rules() {
625 let Classification::NeedsContent(p) = classify(Meta::regular(false), "f.plist") else {
626 panic!("plist needs a binary check");
627 };
628 assert!(!p.needs_shebang() && p.needs_encoding());
629 assert_eq!(
630 p.finish_bytes(b"bplist00\xd1\x01").to_string(),
631 "binary, file, non-executable, plist"
632 );
633 assert_eq!(
634 p.finish_bytes(b"<?xml").to_string(),
635 "file, non-executable, plist, text"
636 );
637
638 let Classification::NeedsContent(p) = classify(Meta::regular(true), "run") else {
639 panic!("unknown executable needs content");
640 };
641 assert!(p.needs_shebang() && p.needs_encoding());
642 assert_eq!(
643 p.finish_bytes(b"#! \n").to_string(),
644 "executable, file, text"
645 );
646 assert_eq!(
647 p.finish_bytes(b"\x7fELF\x02").to_string(),
648 "binary, executable, file"
649 );
650 assert_eq!(
651 p.finish(&b"#!/bin/zsh\n"[..])
652 .map(|t| t.to_string())
653 .ok()
654 .as_deref(),
655 Some("executable, file, shell, text, zsh")
656 );
657
658 // A shebang line longer than the head is still read from the rest.
659 let mut long = b"#!/usr/bin/env ".to_vec();
660 long.extend(std::iter::repeat_n(b' ', 2000));
661 long.extend_from_slice(b"python3\n\0");
662 assert_eq!(
663 p.finish_bytes(&long).to_string(),
664 "executable, file, python, python3, text"
665 );
666 assert_eq!(
667 p.finish(&long[..]).map(|t| t.to_string()).ok().as_deref(),
668 Some("executable, file, python, python3, text")
669 );
670 }
671
672 /// A reader that serves `data` in one chunk per call, then fails with
673 /// `error` (if any) instead of reporting the end of input; counts calls.
674 struct Scripted {
675 data: &'static [u8],
676 error: Option<fn() -> io::Error>,
677 reads: usize,
678 }
679
680 impl Read for Scripted {
681 fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
682 self.reads += 1;
683 if self.data.is_empty() {
684 return self.error.map_or(Ok(0), |error| Err(error()));
685 }
686 let n = buf.len().min(self.data.len());
687 let (now, later) = self.data.split_at(n);
688 buf[..n].copy_from_slice(now);
689 self.data = later;
690 Ok(n)
691 }
692 }
693
694 fn scripted(data: &'static [u8], error: Option<fn() -> io::Error>) -> Scripted {
695 Scripted {
696 data,
697 error,
698 reads: 0,
699 }
700 }
701
702 #[cfg(unix)]
703 fn einval() -> io::Error {
704 io::Error::from_raw_os_error(rustix::io::Errno::INVAL.raw_os_error())
705 }
706 #[cfg(unix)]
707 fn eio() -> io::Error {
708 io::Error::from_raw_os_error(rustix::io::Errno::IO.raw_os_error())
709 }
710 #[cfg(windows)]
711 fn einval() -> io::Error {
712 io::Error::from_raw_os_error(1920) // ERROR_CANT_ACCESS_FILE
713 }
714 #[cfg(windows)]
715 fn eio() -> io::Error {
716 io::Error::from_raw_os_error(5) // ERROR_ACCESS_DENIED: EACCES
717 }
718
719 /// identify returns `()` for an `OSError` with `EINVAL` raised by
720 /// `open()` *or* while `parse_shebang` reads the file.
721 #[cfg(any(unix, windows))]
722 #[test]
723 fn shebang_einval_is_empty_on_open_and_on_read() {
724 assert_eq!(
725 shebang_unless_einval(Ok(scripted(b"#!/bin/sh\n", None))).ok(),
726 Some(vec!["/bin/sh".to_owned()])
727 );
728 // EINVAL from open().
729 assert_eq!(
730 shebang_unless_einval::<Scripted>(Err(einval())).ok(),
731 Some(vec![])
732 );
733 // EINVAL from the first read, and after `#!` was read.
734 assert_eq!(
735 shebang_unless_einval(Ok(scripted(b"", Some(einval)))).ok(),
736 Some(vec![])
737 );
738 assert_eq!(
739 shebang_unless_einval(Ok(scripted(b"#!/bin/", Some(einval)))).ok(),
740 Some(vec![])
741 );
742 // Any other OS error propagates, from open() or from read().
743 for result in [
744 shebang_unless_einval::<Scripted>(Err(eio())),
745 shebang_unless_einval(Ok(scripted(b"#!/bin/", Some(eio)))),
746 ] {
747 let Err(IdentifyError::IoError { source }) = result else {
748 panic!("expected an I/O error, got {result:?}");
749 };
750 assert_eq!(source.raw_os_error(), eio().raw_os_error());
751 }
752 // A non-OS error has no errno, so it is never EINVAL.
753 let custom = shebang_unless_einval(Ok(scripted(
754 b"",
755 Some(|| io::Error::new(io::ErrorKind::InvalidInput, "synthetic")),
756 )));
757 assert!(custom.is_err());
758 }
759
760 #[test]
761 fn crt_errno_mapping() {
762 // Explicitly EINVAL in the C runtime's table, or not in it at all.
763 for code in [1, 12, 13, 14, 87, 123, 131, 362, 1920, 4390, 0xffff_ffff] {
764 assert!(crt_errno_is_einval(code), "{code}");
765 }
766 // Mapped to another errno (ENOENT, EACCES, EBADF, ENOEXEC, ...).
767 for code in [
768 2, 3, 4, 5, 6, 8, 11, 15, 18, 19, 32, 33, 36, 53, 67, 80, 112, 145, 161, 183, 188, 202,
769 206, 1816,
770 ] {
771 assert!(!crt_errno_is_einval(code), "{code}");
772 }
773 }
774
775 /// A small file whose size is known is read with one `read` call; without
776 /// the size a second `read` observes the end of the file.
777 #[test]
778 fn size_hint_saves_the_eof_read() {
779 let Classification::NeedsContent(p) = classify(Meta::regular(false), "x.unknownext") else {
780 panic!("unknown name needs content");
781 };
782 let mut file = scripted(b"hello\n", None);
783 let tags = finish_sized(p, &mut file, Some(6)).ok();
784 assert_eq!(
785 tags.map(|t| t.to_string()).as_deref(),
786 Some("file, non-executable, text")
787 );
788 assert_eq!(file.reads, 1);
789
790 let mut file = scripted(b"hello\n", None);
791 assert!(finish_sized(p, &mut file, None).is_ok());
792 assert_eq!(file.reads, 2);
793
794 // A size of zero may be a lie (procfs): read normally.
795 let mut file = scripted(b"\0", None);
796 let tags = finish_sized(p, &mut file, Some(0)).ok();
797 assert_eq!(
798 tags.map(|t| t.to_string()).as_deref(),
799 Some("binary, file, non-executable")
800 );
801 assert_eq!(file.reads, 2);
802
803 // An unterminated shebang still reads past the hinted size.
804 let Classification::NeedsContent(p) = classify(Meta::regular(true), "tool") else {
805 panic!("unknown executable needs content");
806 };
807 let mut file = scripted(b"#!/bin/zsh", None);
808 let tags = finish_sized(p, &mut file, Some(10)).ok();
809 assert_eq!(
810 tags.map(|t| t.to_string()).as_deref(),
811 Some("executable, file, shell, text, zsh")
812 );
813 }
814
815 #[test]
816 fn file_info_compat() {
817 let info = FileInfo {
818 filename: "noext",
819 file_kind: FileKind::Regular,
820 is_executable: false,
821 content: None,
822 };
823 assert_eq!(tags_from_info(&info).to_string(), "file, non-executable");
824 let info = FileInfo {
825 content: Some(b"text"),
826 ..info
827 };
828 assert_eq!(
829 tags_from_info(&info).to_string(),
830 "file, non-executable, text"
831 );
832 }
833
834 #[test]
835 fn send_sync() {
836 fn assert_send_sync<T: Send + Sync>() {}
837 assert_send_sync::<Classification>();
838 assert_send_sync::<Pending>();
839 assert_send_sync::<Meta>();
840 assert_send_sync::<FileInfo<'static>>();
841 assert_send_sync::<IdentifyError>();
842 assert_send_sync::<crate::TagTable>();
843 }
844}