feat(fmt,cli-common): add fgumi-fmt and fgumi-cli-common leaf crates

[nh13]

First in a crate-by-crate series landing the runall / unified-pipeline work onto main-runall. Each PR targets main-runall, which is kept rebased on main; main itself is untouched until the whole series lands.

What

Adds the two dependency-free leaf crates, wired into the workspace as members:

• fgumi-fmt (102 lines, 2 public items) — human-readable count and duration formatting. No workspace dependencies at all.
• fgumi-cli-common (817 lines, 21 public items) — shared CLI types and helpers. Depends only on fgumi-fmt.

Nothing calls into either crate yet. This is purely additive: no existing file changes behaviour, and both crates are unreachable from any command until later PRs wire them up.

Why these two first

They are the only two of the six incoming crates that are already clean under cargo ci-lint (-D warnings -W clippy::pedantic). The remaining four need a let-chain lint sweep first — the source branch targets MSRV 1.87, this workspace is on 1.93 with let-chains adopted, so clippy::collapsible_if fires on code written against the older toolchain. Per the repo's guidance those get rewritten as let-chains rather than suppressed, and keeping that work out of this PR keeps both halves reviewable.

Starting small is also deliberate: this PR is really about agreeing the conventions — workspace wiring, dependency handling, lockfile discipline — that the rest of the series will repeat.

Dependency centralization

Both crates arrived with per-crate version pins. I converted them to { workspace = true } to match this workspace's existing centralization, which required promoting three dependencies into [workspace.dependencies]:

dep	reason
enum_dispatch	now shared by two members
num_cpus	now shared by two members
sysinfo	shared by two members and MSRV-constrained

sysinfo is the one that matters: it is held at 0.38 because >= 0.39 requires rustc 1.95, above our pinned 1.93. A per-crate pin could drift onto 0.39 and silently raise the effective MSRV — precisely the failure the centralization rule exists to prevent. Its explanatory comment moved to the workspace entry.

Verification

gate	result
cargo ci-fmt	pass
cargo ci-lint	pass
cargo ci-test	pass — 6936 run, 6936 passed, 27 skipped
cargo ci-doctest	pass
cargo ci-doc with RUSTDOCFLAGS="-D warnings"	pass
cargo nextest run -p fgumi-fmt -p fgumi-cli-common	46 run, 46 passed

Cargo.lock is regenerated in the same commit — three CI aliases run --locked, so a stale lockfile would fail on this commit specifically.

A test-inventory check (name-keyed, so module moves are not miscounted as loss) confirms no test present on main is absent here: 5964 before, 6005 after, 0 lost. Raw #[case], #[values] and #[ignore] counts are also non-decreasing, since those are invisible to a name-keyed comparison.

For review

1. Is promoting enum_dispatch / num_cpus / sysinfo into [workspace.dependencies] the right call to make here, or would you rather this PR stay minimal and centralization land separately?
2. Both crates are dead code until a later PR consumes them. Is that acceptable for the series, or would you prefer each crate arrive alongside its first consumer?
3. Branch naming: I used nh/runall-NN-<topic> so the series is orderable. Say if you want the <issue>/<user>/<type>-<desc> form instead.

---

Update (force-pushed): the first push failed codecov/patch at 74.9 % against the repo's 90 % gate, with all 13 other checks green.

Cause: fgumi-cli-common arrived from the source branch at 73.1 % line coverage on the changed lines. Its own tests cover the parsing happy paths, but the OperationTimer, validate_file_exists, several parse_memory_size error arms, parse_memory / parse_memory_reserve, the binary-unit Display impls, and two branches of the memory-budget resolver arrived untested. fgumi-fmt was already at 100 %.

Rather than pad for the metric, I added tests for each of those paths — as #[rstest] case tables with descriptive labels, matching the repo convention. fgumi-cli-common goes from 33 to 63 tests; patch coverage is now 95.9 %.

The 15 lines still uncovered are all log::info! / warn! / debug! macro arguments, which are never evaluated because the test binary initializes no logger, plus one defensively-unreachable checked_mul arm in parse_memory_size (its input is already bounded to ≤ 1,000,000 a few lines earlier). Both seemed like the wrong things to chase.

Amended into the original commit rather than stacked as a fixup, so the PR stays a single logical change. tempfile is added as a dev-dependency for the validate_file_exists tests.

Summary by CodeRabbit

• New Features

  • Added consistent formatting for counts, durations, and processing rates.
  • Improved command-line handling for memory limits, reservations, compression settings, and boolean values.
  • Added clearer validation and error reporting for files and memory sizes.
  • Added system-aware CPU and memory detection for resource budgeting.
  • Added operation progress and completion reporting.

• Bug Fixes

  • Compression now defaults consistently to level 1.
  • Large memory-size suggestions now use accurate binary GiB units.
  • Improved resource-budget handling on platforms with smaller integer limits.

[coderabbitai]

Note

Reviews paused

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

The PR centralizes workspace dependencies, adds fgumi-fmt and fgumi-cli-common, introduces shared CLI parsing, system, timing, error, memory, and compression utilities, and aligns existing compression defaults and memory diagnostics with those implementations.

Changes

Shared CLI foundation

Layer / File(s)	Summary
Workspace crate and dependency setup Cargo.toml, crates/fgumi-cli-common/Cargo.toml, crates/fgumi-fmt/Cargo.toml	Adds both crates to the workspace structure and centralizes their dependency and lint configuration.
Shared formatting utilities crates/fgumi-fmt/src/lib.rs, crates/fgumi-cli-common/src/lib.rs	Adds count, duration, and rate formatting helpers, tests them, and re-exports them through fgumi-cli-common.
CLI contracts and runtime helpers crates/fgumi-cli-common/src/lib.rs	Adds command and error contracts, cgroup-aware memory and CPU detection, operation timing, file validation, and bounded compression options.
Memory parsing and budget resolution crates/fgumi-cli-common/src/lib.rs	Adds strict memory-size parsing, memory/reserve configuration types, reserve and budget resolution, boolean parsing, overflow handling, and extensive tests.
Existing CLI behavior alignment src/lib/commands/common.rs, src/lib/system.rs, src/lib/validation.rs	Makes the compression default explicit, changes memory saturation to preserve downstream overflow checks, and updates oversized-memory suggestions to binary GiB units.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLIArgument
  participant parse_memory
  participant resolve_memory_budget
  CLIArgument->>parse_memory: memory configuration string
  parse_memory->>parse_memory: parse_memory_size
  parse_memory-->>CLIArgument: MemoryLimit or parse error
  CLIArgument->>resolve_memory_budget: limit, reserve, threads, per_thread
  resolve_memory_budget-->>CLIArgument: concrete byte budget or error

Loading

Possibly related PRs

• fulcrumgenomics/fgumi#449: Overlaps in the shared CLI contracts, system-memory fallback, and validation surfaces.
• fulcrumgenomics/fgumi#539: Overlaps in scientific-notation parsing and 32-bit-safe auto-reserve handling.
• fulcrumgenomics/fgumi#561: Directly relates to extracting and re-exporting formatting helpers through fgumi-fmt.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding the fgumi-fmt and fgumi-cli-common leaf crates.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch nh/runall-01-fmt-cli-common

---

_{Comment @coderabbitai help to get the list of available commands.}

[nh13]

@coderabbitai pause

[coderabbitai]

✅ Action performed

Reviews paused.

[codecov]

Codecov Report

❌ Patch coverage is 94.87805% with 21 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.94%. Comparing base (3d27019) to head (8a4d064).

Files with missing lines	Patch %	Lines
crates/fgumi-cli-common/src/lib.rs	94.95%	18 Missing ⚠️
src/lib/commands/common.rs	81.25%	3 Missing ⚠️

Additional details and impacted files

@@               Coverage Diff               @@
##           main-runall     #672      +/-   ##
===============================================
- Coverage        93.94%   93.94%   -0.01%     
===============================================
  Files              178      180       +2     
  Lines           108058   108459     +401     
===============================================
+ Hits            101518   101893     +375     
- Misses            6540     6566      +26     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[nh13]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/fgumi-cli-common/src/lib.rs`:
- Around line 498-505: Update the debug logging around the auto-memory budget
calculation to conditionally describe allocations based on the per_thread mode.
When per_thread is true, retain the per-thread amount and thread-count framing;
when false, log the shared budget without implying it is split into independent
per-thread allocations.
- Around line 24-38: Keep the `Command` trait and its `enum_dispatch`-generated
command enum in the same crate so dispatch implementations are generated
correctly. Update the current `Command` arrangement in `fgumi-cli-common` and
the corresponding enum location, or replace this path with a cross-crate
dispatch mechanism while preserving each command’s `execute` behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: d719e12a-e585-4d03-92c4-62ef31345bff

📥 Commits

Reviewing files that changed from the base of the PR and between 3d27019 and 35a1c82.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock, !**/*.lock

📒 Files selected for processing (8)

• Cargo.toml
• crates/fgumi-cli-common/Cargo.toml
• crates/fgumi-cli-common/src/lib.rs
• crates/fgumi-fmt/Cargo.toml
• crates/fgumi-fmt/src/lib.rs
• src/lib/commands/common.rs
• src/lib/system.rs
• src/lib/validation.rs

[nh13]

Both findings fixed in the amended commit.

enum_dispatch cross-crate limitation — confirmed, and it is broader than the thread describes: #[enum_dispatch] sits on the Command trait in both fgumi-cli-common and src/lib/commands/command.rs, but no enum applies #[enum_dispatch(Command)] anywhere in the repo — src/main.rs:148 hand-writes the dispatch match. So the attribute is already inert today, not merely unable to work after migration.

Removed it from fgumi-cli-common along with the enum_dispatch dependency, and documented on the trait why it is absent. Since fgumi-cli-common was the second member that justified promoting enum_dispatch into [workspace.dependencies], that promotion is reverted too — only the umbrella crate uses it now, so it belongs in the root [dependencies] per the "shared by two or more members" rule stated on that section.

Left the umbrella's own #[enum_dispatch] in place: it is pre-existing, equally inert (the trait is in the lib crate, the enum would be in the bin crate), and removing it touches live dispatch code outside this PR's scope. Worth its own change.

Per-thread debug log — fixed as suggested, and applied to the sibling too: src/lib/commands/common.rs carried the identical unconditional log in the umbrella's copy of resolve_memory_budget. Both now branch on per_thread, matching the framing log_memory_config already used a few lines below.

Verification: ci-fmt, ci-lint, ci-test (6,984 pass), ci-doctest, ci-doc all green; patch coverage 95.0% against the 90% gate.