nu_config/lib.rs
1//! Nushell configuration infrastructure.
2//!
3//! This crate owns **all** XDG-aware path resolution for Nushell configuration
4//! files and directories. It is the single source of truth for *where* config
5//! lives. It does **not** evaluate or parse config files — that is the job of
6//! `nu-cli` / the `nu` binary.
7//!
8//! # Architecture
9//!
10//! ```text
11//! CLI flags + process env + platform dirs
12//! │
13//! ▼
14//! resolve_paths() ← one-shot at startup
15//! │
16//! ▼
17//! NushellConfigDirs ← stored on EngineState.config_dirs
18//! │
19//! ┌────────┼────────┬──────────────┐
20//! ▼ ▼ ▼ ▼
21//! $nu.* loaders history plugins
22//! ```
23//!
24//! After startup, **do not** re-read `XDG_*` env vars or call free path helpers.
25//! Always read from [`NushellConfigDirs`].
26//!
27//! # Resolution priority
28//!
29//! For every path:
30//!
31//! 1. CLI override ([`CliOverrides`] — e.g. `--config-home`, `--config`)
32//! 2. XDG environment variable (e.g. `$XDG_CONFIG_HOME`)
33//! 3. Platform default via the [`EnvAccess`] seam
34//!
35//! # Testing
36//!
37//! Use [`TestEnv`] to inject env vars and platform directories without touching
38//! the host process. Prefer unit tests in this crate over spawning `nu` for pure
39//! path-resolution logic.
40
41mod config_file;
42mod env_access;
43mod errors;
44mod overrides;
45mod paths;
46mod resolve;
47
48// Convenience re-exports so callers don't need to dig into sub-modules.
49pub use config_file::ConfigFileKind;
50pub use env_access::{EnvAccess, SystemEnv, TestEnv};
51pub use errors::{ConfigError, ConfigWarning};
52pub use overrides::CliOverrides;
53pub use paths::{ConfigPath, NushellConfigDirs};
54pub use resolve::resolve_paths;
55
56#[cfg(test)]
57#[macro_use]
58extern crate nu_test_support;
59
60#[cfg(test)]
61use nu_test_support::harness::main;