# Codebase Improvements and Future Work

## Quick Wins (Already Fixed in this session)
- ✅ Fixed all compiler warnings (unused imports, variables, fields)
- ✅ Cleaned up MD041, MD043, MD049, MD058 rule implementations
- ✅ Added `#[allow(dead_code)]` to functions reserved for future phases

## Phase 6: Auto-Fix Implementation (Next Priority)

### Core Fix Infrastructure
- [ ] Implement fix application engine in `src/fix/fixer.rs`
- [ ] Add fix validation and conflict detection
- [ ] Handle multiple fixes per file safely
- [ ] Preserve file encoding and line endings (LF vs CRLF)
- [ ] Add dry-run mode for previewing fixes

### Fixable Rules (20 rules to implement)
- [ ] MD009: Remove trailing spaces
- [ ] MD010: Replace tabs with spaces
- [ ] MD012: Remove excess blank lines
- [ ] MD014: Remove dollar signs from shell commands
- [ ] MD018: Add space after hash
- [ ] MD019: Remove extra spaces after hash
- [ ] MD022: Add blank lines around headings
- [ ] MD023: Move heading to start of line
- [ ] MD027: Remove extra spaces in blockquote
- [ ] MD030: Fix spaces after list markers
- [ ] MD031: Add blank lines around code blocks
- [ ] MD034: Convert bare URLs to links
- [ ] MD037: Remove spaces inside emphasis markers
- [ ] MD038: Remove spaces inside code spans
- [ ] MD039: Remove spaces inside link text
- [ ] MD047: Add trailing newline
- [ ] MD048: Convert code fence style (backtick/tilde)
- [ ] MD049: Convert emphasis style (asterisk/underscore)
- [ ] MD050: Convert strong style (asterisk/underscore)
- [ ] MD054: Convert link style (inline/reference)

## Phase 7: Output Formatters

### Formatter Implementations
- [ ] Complete `src/format/default.rs` - Human-readable with colors
- [ ] Complete `src/format/json.rs` - JSON output (use `_pretty` field)
- [ ] Complete `src/format/junit.rs` - JUnit XML for CI
- [ ] Complete `src/format/sarif.rs` - SARIF for security tools
- [ ] Add GitHub Actions formatter (::error:: annotations)
- [ ] Add Codacy formatter

### Formatter Features
- [ ] Color support using `termcolor` or `anstream`
- [ ] Summary statistics (files checked, errors found)
- [ ] File grouping and sorting
- [ ] Configurable verbosity levels

## Phase 8: CLI Interface

### Command-Line Arguments (using clap)
- [ ] Positional glob patterns (multiple allowed)
- [ ] `--config <path>`: Custom config file
- [ ] `--fix`: Enable auto-fixing
- [ ] `--no-globs`: Ignore globs from config
- [ ] `--verbose` / `--quiet`: Verbosity control
- [ ] `--output-format`: Select formatter
- [ ] `--help` and `--version`: Auto-generated by clap

### CLI Features
- [ ] Progress indicator for large file sets
- [ ] Respect `noBanner` and `noProgress` config
- [ ] Detect TTY for appropriate output
- [ ] Exit codes (0=success, 1=errors found, 2=runtime error)

### Inline Configuration
- [ ] Parse HTML comments: `<!-- markdownlint-disable MD001 -->`
- [ ] Parse enable directives: `<!-- markdownlint-enable MD001 -->`
- [ ] Parse next-line disable: `<!-- markdownlint-disable-next-line -->`
- [ ] Parse file-level config: `<!-- markdownlint-configure-file {...} -->`
- [ ] Respect `noInlineConfig` option

## Phase 9: Testing Improvements

### Test Coverage
- [ ] Add integration tests beyond unit tests
- [ ] Test complete workflows (discovery → lint → format)
- [ ] Test with various configuration combinations
- [ ] Test auto-fix workflows
- [ ] Aim for >90% code coverage

### Compatibility Testing
- [ ] Run Docker-based compatibility tests in CI
- [ ] Document expected differences from markdownlint-cli2
- [ ] Add regression tests for fixed bugs
- [ ] Test against markdownlint's official test suite

### Property-Based Testing
- [ ] Use `proptest` for fuzzing rules
- [ ] Generate random valid markdown
- [ ] Generate random invalid markdown
- [ ] Ensure no panics or crashes

## Phase 10: Performance & Advanced Features

### Performance Optimizations
- [ ] Parallel file processing using `rayon`
- [ ] Memory-mapped file I/O for large files
- [ ] Incremental linting (cache results)
- [ ] Profile and optimize hot paths
- [ ] Benchmark against markdownlint-cli2 (informational)

### Advanced Features
- [ ] Custom rule plugin system
- [ ] Watch mode using `notify` crate
- [ ] Language server protocol (LSP) support
- [ ] Editor integrations (VS Code, Neovim, etc.)

## Code Quality Improvements

### Architecture
- [ ] Complete `src/lint/engine.rs` implementation (use `_config` and `_registry`)
- [ ] Add trait for rule categories (heading rules, list rules, etc.)
- [ ] Consider splitting large rules (MD013) into sub-checks
- [ ] Add builder pattern for complex configuration

### Documentation
- [ ] Add module-level documentation to all files
- [ ] Document all public APIs with examples
- [ ] Create architecture diagram
- [ ] Add decision records for major choices (why pulldown-cmark, etc.)

### Error Handling
- [ ] Implement detailed error types in `src/error.rs`
- [ ] Add context to errors (file path, line number)
- [ ] Improve error messages for common issues
- [ ] Add suggestions for fixing configuration errors

### Code Organization
- [ ] Consider grouping rules by category in subdirectories:
  - `src/lint/rules/headings/`
  - `src/lint/rules/lists/`
  - `src/lint/rules/code/`
  - `src/lint/rules/links/`
  - `src/lint/rules/tables/`
- [ ] Extract common utilities to helper modules
- [ ] Consider macro for repetitive rule boilerplate

## Rule-Specific Improvements

### Enhancement Opportunities
- [ ] MD051: Support custom heading ID schemes (not just GitHub-style)
- [ ] MD052/MD053: Support collapsed/shortcut reference links `[text]` and `[text][]`
- [ ] MD044: Support regex patterns for proper names, not just strings
- [ ] MD056: Better handling of escaped pipes in tables
- [ ] MD060: Support more alignment types (justified, etc.)

### Bug Risks to Test
- [ ] MD037/MD038: Handle escaped markers `\*` and `` \` ``
- [ ] MD049/MD050: Handle nested emphasis `*foo **bar** baz*`
- [ ] MD051: Handle URL-encoded fragments `#my%20heading`
- [ ] MD055: Handle tables in code blocks (should be ignored)

## Build & Distribution (Phase 12)

### Build Optimization
- [ ] Enable LTO in release profile
- [ ] Set appropriate `opt-level` and `codegen-units`
- [ ] Strip debug symbols in release builds
- [ ] Profile-guided optimization (PGO)

### Cross-Platform
- [ ] CI testing on Linux, macOS, Windows
- [ ] Handle platform path separators correctly
- [ ] Test with different line endings (LF/CRLF)
- [ ] Build static binaries (musl on Linux)

### Distribution
- [ ] Publish to crates.io
- [ ] Create GitHub releases with binaries
- [ ] Homebrew formula
- [ ] Debian/Ubuntu package
- [ ] Docker image
- [ ] npm wrapper for Node.js compatibility

### CI/CD
- [ ] GitHub Actions for testing all platforms
- [ ] Clippy and rustfmt checks
- [ ] Automated binary builds on tags
- [ ] Automated crates.io publishing
- [ ] Security audit with `cargo audit`

## Documentation (Phase 11)

### User Documentation
- [ ] Comprehensive README with examples
- [ ] Installation guide for all platforms
- [ ] Configuration guide with all options
- [ ] Migration guide from markdownlint-cli2
- [ ] Rule reference (with examples and configs)
- [ ] Troubleshooting guide

### Developer Documentation
- [ ] CONTRIBUTING.md with development setup
- [ ] Architecture overview and diagrams
- [ ] Guide for adding new rules
- [ ] Guide for adding new formatters
- [ ] Release process documentation
- [ ] API documentation for rule authors

## Long-Term Enhancements

### Features
- [ ] Configuration file generation wizard
- [ ] Interactive mode for fixing violations
- [ ] Diff mode (only lint changed lines)
- [ ] Pre-commit hook integration
- [ ] Git hook support (pre-commit, pre-push)

### Ecosystem
- [ ] Share rules with markdownlint community
- [ ] Contribute improvements back to pulldown-cmark
- [ ] Create ecosystem of third-party rules
- [ ] IDE extensions and plugins

---

## Priority Order

1. **Phase 6** - Auto-fix (highest user value)
2. **Phase 7** - Formatters (essential for usability)
3. **Phase 8** - CLI (make it actually usable)
4. **Code Quality** - Documentation and error handling
5. **Phase 9** - More tests (increase confidence)
6. **Phase 10** - Performance and advanced features
7. **Phase 12** - Distribution (make it accessible)
8. **Long-term** - Ecosystem and community

## Estimated Effort

- Quick wins: ✅ Done
- Phase 6 (Auto-fix): 2-3 days
- Phase 7 (Formatters): 1-2 days
- Phase 8 (CLI): 2-3 days
- Code quality improvements: Ongoing
- Phases 9-12: 1-2 weeks total

**Total to production-ready: 1-2 weeks of focused development**
