fdu-core

The engine behind fdu: hierarchical tallies (sizes, counts, recency, file types) over large directory trees, with a persistent cache and an optional OS-native watch layer.

This crate is the library. If you want the command-line tool, install fdu — it carries the command line and re-exports this whole API, so cargo add fdu gives a library caller everything here under one name.

Full documentation, design notes, and the tool survey this is built from live in the repository: https://github.com/jlevy/fdu

Status: 0.x. A new minor release may change the API; the release process states the compatibility rules. The revision-arbitrated observation/commit contract, bounded parallel walker, applying reconciler, checksummed snapshot and content sidecars, cache lifecycle, and opt-in content analyzers are tested end to end.

cargo add fdu-core

Published requirements are caret ranges of the reviewed minimum (libc, pulldown-cmark). Cargo.lock still pins the exact versions this workspace builds; cargo install --locked fdu is what reproduces them. An exact pin in a published library would make any downstream that needs a newer compatible release unresolvable.

The crate has no default features. The watch capability is strictly additive; without it, scan, index, and snapshot remain fully functional. The fdu command and Python package enable it explicitly, while embedding consumers can leave it out along with its dependency tree. .gitignore handling is always compiled in, because it has no dependency to shed. Whether a request reads .gitignore files is decided at runtime by its ScanConfig::read_controls, which is on by default; a request that turns it off is a separate snapshot scope.

Content inspection is optional and disabled by default. Basis::content enables bounded streaming line, prose, and common-language SLOC metrics; sparse type, family, and language summaries; and independently versioned sidecar reuse without changing the metadata snapshot format or cost model for metadata-only consumers. code-sloc-v1 covers Rust, Python, JavaScript, TypeScript, Go, Java, C, C++, C#, Ruby, PHP, Swift, Kotlin, shell, and SQL without adding a parser dependency. text-logical-v1 adds normalized words, paragraphs, and aggregate-derived pages; markdown-prose-v1 adds a reader-visible CommonMark projection that excludes code and destinations. Exact names and extensions stay path-only, while unresolved and ambiguous paths may use bounded shebang, modeline, literal, or signature probes whose source and confidence are retained in reports and sidecars.

use fdu_core::content::AnalysisSet;
use fdu_core::{CachePolicy, open};
use fdu_core::query::{Basis, Delivery, Scope};
use std::path::Path;

let basis = Basis { root: Path::new(".").into(), scope: Scope::default(), content: AnalysisSet::ALL };
let delivery = Delivery::new(CachePolicy::Auto, None);
let (index, report) = open(&basis, &delivery)?;
let lines = index
    .content_rollup(Path::new(""))
    .map_or(0, |root| root.total.lines.metrics.physical_lines);
println!("{} lines", lines);
assert!(report.analysis.is_some());
# Ok::<(), fdu_core::Error>(())

License: MIT.

fdu-core 0.2.0

fdu-core