MODGEN
Rust Module Surface Manager

https://github.com/neuxdotdev/modgen

modgen is a command-line tool that recursively scans Rust source
directories and generates or updates mod.rs files. It automatically adds
pub mod statements for every .rs file (except mod.rs itself) and,
optionally, pub use re-exports.

The tool is designed to be deterministic, idempotent, and friendly to both
developers and CI pipelines.

FEATURES

- Recursive directory walk across the entire source tree
- Ignores common directories (target, .git, node_modules), configurable
- Generates mod.rs with sorted, case-insensitive module lists
- Optional pub use re-exports for flat public APIs
- Idempotent behavior using content hashing
- Marker-based updates that preserve manual code outside markers
- Dry-run mode to preview changes
- Check mode for CI validation
- Verbose logging levels
- Configuration via modgen.toml (TOML format)
- Hash algorithms: Simple (default) or Blake3
- Pure Rust, fast, portable

INSTALLATION

Install directly from the Git repository using Cargo:

cargo install --git https://github.com/neuxdotdev/modgen

The binary will be installed into ~/.cargo/bin. Ensure this directory is in your PATH.

USAGE

Basic usage:

modgen [OPTIONS] [PATH]

If PATH is omitted, it defaults to src.

Options:

--config <FILE> Path to TOML configuration file
--dry-run Show planned changes without writing files
--no-reexport Disable pub use generation (overrides config)
--check Exit with code 1 if any mod.rs would change
-v, --verbose Increase logging verbosity (repeatable)

Run modgen --help for complete option details.

CONFIGURATION

Create a modgen.toml file in your project root or specify one with --config.

Example configuration:

ignore = ["target", ".git", "tests", "benches"]
reexport = true
marker_start = "// modgen:start"
marker_end = "// modgen:end"
hash_algo = "Blake3"

All fields are optional.

Default values:

ignore = ["target", ".git", "node_modules"]
reexport = true
marker_start = "// modgen:start"
marker_end = "// modgen:end"
hash_algo = "Simple"

EXISTING MOD.RS BEHAVIOR

If mod.rs contains markers:

// modgen:start
// modgen:end

Only the content between those markers will be replaced.
Content outside markers remains untouched.

If markers are not found, the entire file will be overwritten with a
fresh auto-generated block.

EXAMPLES

Generate mod.rs for src:

modgen src

Dry run with verbose logging:

modgen --dry-run -v src

Check mode for CI:

modgen --check src

Use a custom configuration file:

modgen --config myconfig.toml lib/src

Disable re-exports:

modgen --no-reexport src

OUTPUT EXAMPLE

For a directory authentication containing password.rs and pin.rs,
the generated authentication/mod.rs will contain:

// Auto-generated by modgen. Do not edit manually.
// modgen:start
pub mod password;
pub mod pin;

pub use password::_;
pub use pin::_;
// modgen:end

LICENSE

This project is licensed under the MIT License.
See the LICENSE file for details.