r3bl_build_infra/lib.rs
1// Copyright (c) 2025 R3BL LLC. Licensed under Apache License, Version 2.0.
2
3#![cfg_attr(not(test), deny(clippy::unwrap_in_result))]
4
5//! # R3BL Build Infrastructure
6//!
7//! Build tools and utilities designed for R3BL projects, but usable in any Rust project.
8//!
9//! ## cargo-rustdoc-fmt
10//!
11//! A cargo subcommand that formats markdown tables and converts inline links to
12//! reference-style links within Rust documentation comments (`///` and `//!`).
13//!
14//! ### Features
15//!
16//! - **Table Formatting**: Aligns markdown table columns for readability
17//! - **Link Conversion**: Converts inline markdown links to reference-style links,
18//! keeping documentation cleaner
19//! - **Workspace Support**: Process entire Rust workspaces or specific files
20//! - **Check Mode**: Verify formatting without modifying files (useful for CI)
21//! - **Selective Formatting**: Choose to format only tables, only links, or both
22//! - **Git Integration**: Auto-detects changed files in git working tree
23//!
24//! ### Installation
25//!
26//! From [crates.io](https://crates.io/crates/r3bl-build-infra):
27//!
28//! ```bash
29//! cargo install r3bl-build-infra
30//! ```
31//!
32//! Or from source (in a workspace containing this crate):
33//!
34//! ```bash
35//! cargo install --path build-infra
36//! ```
37//!
38//! ### Usage Examples
39//!
40//! **Format git-changed files** (default - auto-detects staged/unstaged changes):
41//! ```bash
42//! cargo rustdoc-fmt
43//! ```
44//!
45//! **Format entire workspace**:
46//! ```bash
47//! cargo rustdoc-fmt --workspace
48//! ```
49//!
50//! **Format specific files**:
51//! ```bash
52//! cargo rustdoc-fmt src/lib.rs src/main.rs
53//! ```
54//!
55//! **Format a directory**:
56//! ```bash
57//! cargo rustdoc-fmt src/
58//! ```
59//!
60//! **Check formatting without modifying** (useful for CI):
61//! ```bash
62//! cargo rustdoc-fmt --check
63//! ```
64//!
65//! **Only format tables** (skip link conversion):
66//! ```bash
67//! cargo rustdoc-fmt --tables-only
68//! ```
69//!
70//! **Only convert links** (skip table formatting):
71//! ```bash
72//! cargo rustdoc-fmt --links-only
73//! ```
74//!
75//! **Verbose output**:
76//! ```bash
77//! cargo rustdoc-fmt --verbose
78//! ```
79//!
80//! **Combine options**:
81//! ```bash
82//! cargo rustdoc-fmt --check --verbose src/
83//! ```
84//!
85//! ### What It Does
86//!
87//! #### Table Formatting
88//!
89//! Markdown tables in rustdoc comments are reformatted with consistent column widths.
90//!
91//! **Before:**
92//! ```rust
93//! //! | A | B |
94//! //! |---|---|
95//! //! | Short | Very Long Text |
96//! ```
97//!
98//! **After:**
99//! ```rust
100//! //! | A | B |
101//! //! |-------|----------------|
102//! //! | Short | Very Long Text |
103//! ```
104//!
105//! #### Link Conversion
106//!
107//! Inline markdown links are converted to reference-style links using the link text
108//! as the reference identifier, reducing visual clutter in documentation.
109//!
110//! **Before:**
111//! ```rust
112//! //! See [docs](https://example.com) and [Rust](https://rust-lang.org).
113//! ```
114//!
115//! **After:**
116//! ```rust
117//! //! See [docs] and [Rust].
118//! //!
119//! //! [docs]: https://example.com
120//! //! [Rust]: https://rust-lang.org
121//! ```
122//!
123//! ### Git Integration
124//!
125//! When run without arguments, `cargo-rustdoc-fmt` intelligently determines which files
126//! to format:
127//!
128//! 1. **If there are staged/unstaged changes**: Formats only those changed files
129//! 2. **If working tree is clean**: Formats files from the most recent commit
130//! 3. **If not in a git repository**: Formats the entire workspace
131//!
132//! This makes it perfect for pre-commit hooks and development workflows.
133//!
134//! ### CI Integration
135//!
136//! Add to your continuous integration pipeline to enforce formatting standards:
137//!
138//! ```bash
139//! cargo rustdoc-fmt --check
140//! ```
141//!
142//! Exits with code 1 if formatting is needed, allowing CI to fail the build.
143//!
144//! **Example GitHub Actions step**:
145//!
146//! ```yaml
147//! - name: Check rustdoc formatting
148//! run: cargo rustdoc-fmt --check --verbose
149//! ```
150//!
151//! ### Architecture
152//!
153//! The project follows a multi-tool design pattern (similar to the `cmdr/` crate).
154//! Currently implements `cargo-rustdoc-fmt`, with support for adding additional
155//! build tools in the future without refactoring.
156//!
157//! **Module structure:**
158//! - `src/lib.rs` - Library root
159//! - `src/bin/cargo-rustdoc-fmt.rs` - Binary entry point
160//! - `src/cargo_rustdoc_fmt/` - Tool implementation
161//! - `cli_arg.rs` - CLI argument parsing
162//! - `extractor.rs` - Extract rustdoc blocks from source
163//! - `table_formatter.rs` - Format markdown tables
164//! - `link_converter.rs` - Convert inline to reference-style links
165//! - `processor.rs` - Orchestrate file processing
166//! - `ir_event_types` - Type definitions
167//! - `ui_str.rs` - User-facing messages
168//! - `src/common/` - Shared utilities
169//! - `git_utils.rs` - Git integration
170//! - `workspace_utils.rs` - Workspace discovery and file finding
171//!
172//! ### Implementation Notes
173//!
174//! Currently uses `pulldown-cmark` for markdown parsing. This will be migrated to
175//! `r3bl_tui::md_parser` once table support is added to that parser, achieving full
176//! R3BL infrastructure dogfooding.
177
178// Attach all modules.
179pub mod cargo_rustdoc_fmt;
180pub mod common;
181
182// Re-export commonly used items.
183pub use common::*;