Merge pull request #43 from davegarvey:md-fix

Md-fix

Author: davegarvey

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - correct changelog formatting for markdownlint compliance
+
 ## [4.7.0] - 2025-12-16
 
 ### Added

CONTRIBUTING.md

@@ -0,0 +1,222 @@
+# Contributing to Grubble
+
+Thank you for your interest in contributing to Grubble! This document provides guidelines and information for contributors.
+
+## Development Setup
+
+### Prerequisites
+
+- **Rust**: Install the latest stable version from [rustup.rs](https://rustup.rs/)
+- **Node.js** (optional): For markdown linting tests, install from [nodejs.org](https://nodejs.org/)
+
+### Getting Started
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/davegarvey/grubble.git
+   cd grubble
+   ```
+
+2. Run tests:
+
+   ```bash
+   cargo test
+   ```
+
+3. Run linting:
+
+   ```bash
+   cargo clippy
+   ```
+
+## Testing
+
+### Standard Test Suite
+
+Run all tests with:
+
+```bash
+cargo test
+```
+
+### Markdown Linting Tests
+
+Grubble includes optional tests that validate generated changelog files against markdown linting rules. These tests require `markdownlint-cli` and are controlled by the `RUN_MARKDOWN_LINT` environment variable.
+
+#### Why Optional?
+
+- **Dependencies**: Requires Node.js and `markdownlint-cli`
+- **Performance**: External process calls are slower
+- **CI Focus**: Primarily valuable in CI where standards are enforced
+
+#### Running Markdown Linting Tests
+
+**Option 1: Environment Variable (Recommended)**
+
+```bash
+# Set for current session
+export RUN_MARKDOWN_LINT=1
+cargo test
+
+# Or inline
+RUN_MARKDOWN_LINT=1 cargo test
+```
+
+**Option 2: .env File**
+
+```bash
+# Create .env file
+echo 'RUN_MARKDOWN_LINT=1' > .env
+
+# Run tests with environment loaded
+export $(cat .env) && cargo test
+```
+
+**Option 3: Convenience Script**
+
+```bash
+# Use the provided script
+./test-with-markdown.sh
+./test-with-markdown.sh test_markdown_linter_if_available -- --nocapture
+```
+
+#### Test Behavior
+
+- **CI Environment**: Tests run automatically when `CI=true`
+- **Local Development**: Tests skip gracefully unless `RUN_MARKDOWN_LINT=1` is set
+- **Missing Dependencies**: In CI, tests fail if `markdownlint-cli` is unavailable
+
+### Test Coverage
+
+The project maintains comprehensive test coverage including:
+
+- Unit tests for all core functionality
+- Integration tests for changelog generation
+- Markdown compliance tests
+- Cross-platform compatibility tests
+
+## Code Quality
+
+### Linting
+
+Run clippy for code quality checks:
+
+```bash
+cargo clippy --all-targets --all-features -- -D warnings
+```
+
+### Formatting
+
+Format code according to Rust standards:
+
+```bash
+cargo fmt --all
+```
+
+### Pre-commit Hooks
+
+The project uses Husky for pre-commit hooks. Install dependencies and set up hooks:
+
+```bash
+npm install
+```
+
+## Commit Guidelines
+
+Grubble follows [Conventional Commits](https://conventionalcommits.org/) specification:
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Commit Types
+
+- `feat:` - New features (minor version bump)
+- `fix:` - Bug fixes (patch version bump)
+- `docs:` - Documentation changes
+- `test:` - Testing related changes
+- `refactor:` - Code refactoring
+- `style:` - Code style changes
+- `chore:` - Maintenance tasks
+- `ci:` - CI/CD changes
+- `build:` - Build system changes
+- `perf:` - Performance improvements
+
+### Breaking Changes
+
+Mark breaking changes with `!` after the type/scope or include `BREAKING CHANGE:` in the footer.
+
+### Examples
+
+```bash
+feat: add support for custom commit types
+fix: resolve changelog spacing issue
+test: improve markdown linter test behavior
+docs: update installation instructions
+refactor!: simplify version parsing logic
+```
+
+## Pull Request Process
+
+1. **Fork** the repository
+2. **Create** a feature branch from `main`
+3. **Make** your changes following the guidelines above
+4. **Test** thoroughly (including markdown linting if applicable)
+5. **Commit** with conventional commit messages
+6. **Push** to your fork
+7. **Create** a Pull Request with a clear description
+
+### PR Requirements
+
+- All tests pass
+- Code is formatted (`cargo fmt`)
+- No clippy warnings (`cargo clippy`)
+- Conventional commit messages
+- Clear description of changes
+
+## Release Process
+
+Grubble uses automated releases based on conventional commits:
+
+- `feat:` commits → Minor version bump
+- `fix:` commits → Patch version bump
+- Breaking changes → Major version bump
+
+Releases are automatically created via GitHub Actions when changes are merged to `main`.
+
+## Project Structure
+
+```
+src/
+├── main.rs          # CLI entry point
+├── analyser.rs      # Commit analysis logic
+├── versioner.rs     # Version bump calculations
+├── changelog.rs     # CHANGELOG.md generation
+├── config.rs        # Configuration handling
+├── git.rs           # Git operations
+├── strategy/        # Version strategy implementations
+│   ├── git.rs
+│   └── node.rs
+└── error.rs         # Error types
+```
+
+## Configuration Files
+
+- `.versionrc.json` - Version bump configuration
+- `.markdownlint.json` - Markdown linting rules
+- `.github/workflows/` - CI/CD pipelines
+
+## Getting Help
+
+- **Issues**: [GitHub Issues](https://github.com/davegarvey/grubble/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/davegarvey/grubble/discussions)
+- **Documentation**: See README.md for detailed usage instructions
+
+## License
+
+By contributing to Grubble, you agree that your contributions will be licensed under the same MIT License that covers the project.

src/changelog.rs

@@ -133,7 +133,6 @@ fn generate_changelog_entry_at_path(
         }
         entry.push_str(&format!("- {}\n", change.description));
     }
-    // Don't add extra blank line after final list - the header already provides spacing
 
     // Read existing changelog or create header
     let mut content = if changelog_path.exists() {
@@ -144,6 +143,8 @@ fn generate_changelog_entry_at_path(
 
     // Find where to insert the new entry (after the header, before existing entries)
     let insertion_point = if let Some(pos) = content.find("\n## [") {
+        // Add blank line after the new entry if there are existing entries
+        entry.push('\n');
         pos + 1
     } else {
         content.len()
@@ -219,6 +220,63 @@ mod tests {
         assert!(content.contains("- add new feature"));
         assert!(content.contains("### Fixed"));
         assert!(content.contains("- resolve bug"));
+
+        // Verify no double blank lines (triple newlines) in the file
+        assert!(
+            !content.contains("\n\n\n"),
+            "New changelog should not have double blank lines"
+        );
+
+        // The file should end with a single newline, not multiple blank lines
+        assert!(
+            !content.ends_with("\n\n\n"),
+            "New changelog should not end with double blank lines"
+        );
+        assert!(
+            !content.ends_with("\n\n"),
+            "New changelog should not end with a blank line (should end with single newline after last list item)"
+        );
+    }
+
+    #[test]
+    fn test_new_changelog_file_has_no_double_blank_lines_at_end() {
+        let temp_dir = TempDir::new().unwrap();
+        let changelog_path = temp_dir.path().join("CHANGELOG.md");
+
+        let version = Version::parse("1.0.0").unwrap();
+        let commits = vec!["feat: first feature".to_string()];
+
+        generate_changelog_entry_at_path(&version, &commits, &changelog_path).unwrap();
+
+        let content = fs::read_to_string(&changelog_path).unwrap();
+
+        // For a new file with just one entry, the structure should be:
+        // - Header (ending with \n\n)
+        // - Version header: "## [1.0.0] - date\n\n"
+        // - Category header: "### Added\n\n"
+        // - List item: "- first feature\n"
+        // - End of file (no extra newlines)
+
+        // Verify the ending structure
+        assert!(
+            content.ends_with("- first feature\n"),
+            "New changelog should end with list item + single newline, but got: {:?}",
+            &content[content.len().saturating_sub(30)..]
+        );
+
+        // Verify no triple newlines anywhere (which would be double blank lines)
+        assert!(
+            !content.contains("\n\n\n"),
+            "New changelog should not contain double blank lines"
+        );
+
+        // Count the total newlines at the end - should be exactly 1
+        let trailing_newlines = content.chars().rev().take_while(|&c| c == '\n').count();
+        assert_eq!(
+            trailing_newlines, 1,
+            "New changelog should end with exactly 1 newline, found {}",
+            trailing_newlines
+        );
     }
 
     #[test]
@@ -446,10 +504,64 @@ mod tests {
     }
 
     #[test]
-    #[ignore] // Run with: cargo test -- --ignored --nocapture (automatically run in CI)
+    fn test_generate_changelog_entry_proper_spacing_between_releases() {
+        let temp_dir = TempDir::new().unwrap();
+        let changelog_path = temp_dir.path().join("CHANGELOG.md");
+
+        // Create first release
+        let version1 = Version::parse("1.0.0").unwrap();
+        let commits1 = vec!["feat: initial feature".to_string()];
+        generate_changelog_entry_at_path(&version1, &commits1, &changelog_path).unwrap();
+
+        // Create second release
+        let version2 = Version::parse("1.1.0").unwrap();
+        let commits2 = vec!["fix: bug fix".to_string()];
+        generate_changelog_entry_at_path(&version2, &commits2, &changelog_path).unwrap();
+
+        // Create third release
+        let version3 = Version::parse("1.2.0").unwrap();
+        let commits3 = vec!["feat: another feature".to_string()];
+        generate_changelog_entry_at_path(&version3, &commits3, &changelog_path).unwrap();
+
+        let content = fs::read_to_string(&changelog_path).unwrap();
+
+        // Verify proper spacing: should have exactly one blank line between release entries
+        // Pattern should be: "- item\n\n## [version]" (list item, blank line, next header)
+        assert!(
+            content.contains("- another feature\n\n## [1.1.0]"),
+            "Missing blank line between [1.2.0] and [1.1.0]"
+        );
+        assert!(
+            content.contains("- bug fix\n\n## [1.0.0]"),
+            "Missing blank line between [1.1.0] and [1.0.0]"
+        );
+
+        // Should NOT have double blank lines (triple newlines)
+        assert!(
+            !content.contains("\n\n\n"),
+            "Found double blank line (triple newlines) in changelog"
+        );
+
+        // Verify all versions are present and in correct order
+        let v3_pos = content.find("## [1.2.0]").unwrap();
+        let v2_pos = content.find("## [1.1.0]").unwrap();
+        let v1_pos = content.find("## [1.0.0]").unwrap();
+        assert!(
+            v3_pos < v2_pos && v2_pos < v1_pos,
+            "Versions not in descending order"
+        );
+    }
+
+    #[test]
     fn test_markdown_linter_if_available() {
         use std::process::Command;
 
+        // Only run this test in CI or when explicitly requested
+        if std::env::var("CI").is_err() && std::env::var("RUN_MARKDOWN_LINT").is_err() {
+            println!("⚠ Skipping markdown linter test (run with RUN_MARKDOWN_LINT=1 to enable)");
+            return;
+        }
+
         let temp_dir = TempDir::new().unwrap();
         let changelog_path = temp_dir.path().join("CHANGELOG.md");
 
@@ -463,7 +575,6 @@ mod tests {
         generate_changelog_entry_at_path(&version, &commits, &changelog_path).unwrap();
 
         // Try to run markdownlint-cli if available
-        // Install with: npm install -g markdownlint-cli
         let result = Command::new("npx")
             .args(["markdownlint-cli", changelog_path.to_str().unwrap()])
             .output();
@@ -482,8 +593,7 @@ mod tests {
                 }
             }
             Err(e) => {
-                println!("⚠ markdownlint not found (optional): {}", e);
-                println!("  To enable this test, install: npm install -g markdownlint-cli");
+                panic!("markdownlint-cli not available but required in CI: {}", e);
             }
         }
     }