Audit CLI Bugfixes and Enhancements

[dacharyc]

Audit CLI: Enhancements and Bug Fixes

This PR includes a collection of improvements and bug fixes for the audit-cli tool, focusing on better usability, enhanced procedure parsing, and improved output clarity.

🎯 Key Features

1. Sub-Procedure Tracking with List Type Detection

• Added support for tracking multiple sub-procedures within procedure steps separately (instead of flattening them)
• Implemented list marker type detection (numbered 1., 2., 3. vs. lettered a., b., c.)
• New SubProcedure type with ListType field to preserve original formatting
• Display output now uses original list markers for better alignment with source files
• Added --show-sub-procedures flag to display detailed sub-procedure information
• Added --show-steps flag to display detailed step information

Example output:

Sub-procedure 2 (3 step(s)):
   a. Use :method:`rs.stepDown()` to step down the member
   b. Use the :method:`db.shutdownServer()` method to shut down
   c. Restart the member

2. Recursive Code Example Extraction

• Added --preserve-dirs flag to maintain directory structure when extracting code examples recursively
• Improved handling of nested directory structures
• Better path resolution for extracted files

3. Enhanced Usage Analysis

• Extended usage analysis to track .yaml step files and extract files
• Added recursive directory processing support
• Improved output formatting with clearer categorization

4. Improved Include Tracking

• Added file paths to disambiguate include files with the same filename
• Improved count accuracy and output clarity
• Better handling of nested includes

🐛 Bug Fixes

Procedure Parsing

• Fixed issue where sub-procedures were being flattened into a single array, losing structure
• Fixed duplicate/incorrect step numbering in hierarchical procedures
• Fixed continuation marker (#.) handling for both numbered and lettered lists
• Improved detection of ordered list types

File Comparison

• Removed unnecessary --product-path flag from compare file-contents command
• Removed redundant hints in direct file comparison mode
• Streamlined version resolution logic

🏗️ Refactoring

Internal Package Reorganization

• Renamed internal/pathresolver to internal/projectinfo to better reflect its broader scope
• Moved version handling logic to internal package for better reusability
• Improved separation of concerns across commands

Verbose Output Enhancement

• Made --verbose flag actually useful by adding meaningful output:
  • Shows parsing progress
  • Displays individual file write operations
  • Provides [DRY RUN] indicators when appropriate
• Previously, verbose flag had minimal effect on output

📚 Documentation

• Updated PROCEDURE_PARSING.md with comprehensive documentation on:
  • Sub-procedure structure and tracking
  • List type detection and display behavior
  • Backward compatibility approach
• Updated README with:
  • Clearer descriptions of tool capabilities
  • Updated output examples matching current behavior
  • Broader use case descriptions

🧪 Testing

• Added comprehensive test coverage for sub-procedure list type tracking
• Added tests for recursive code example extraction with --preserve-dirs
• Added tests for usage analysis with step and extract files
• All existing tests continue to pass

[cbullinger]

nifty

[cbullinger]

do we need backward compat?

[dacharyc]

Bah, no, that was a Claude detail. I've removed SubSteps and cleaned up all related instances. Good catch - thank you!