Implement semantic configuration file comparison utility

.gitignore

@@ -0,0 +1,32 @@
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool
+*.out
+
+# Dependency directories
+vendor/
+
+# Go workspace file
+go.work
+
+# Build output
+go-config-diff
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

CONTRIBUTING.md

@@ -0,0 +1,166 @@
+# Contributing to go-config-diff
+
+Thank you for your interest in contributing to go-config-diff! This document provides guidelines and instructions for contributing.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/go-config-diff.git`
+3. Create a feature branch: `git checkout -b feature/your-feature-name`
+4. Make your changes
+5. Run tests: `make test`
+6. Commit your changes: `git commit -am 'Add some feature'`
+7. Push to the branch: `git push origin feature/your-feature-name`
+8. Create a Pull Request
+
+## Development Setup
+
+### Prerequisites
+
+- Go 1.24 or later
+- Make (optional, for using Makefile targets)
+
+### Building
+
+```bash
+make build
+```
+
+### Running Tests
+
+```bash
+make test
+```
+
+### Running the Tool
+
+```bash
+make run
+```
+
+## Code Style
+
+- Follow standard Go conventions
+- Use `gofmt` to format your code
+- Write meaningful commit messages
+- Add comments for complex logic
+- Keep functions focused and small
+
+## Testing
+
+- Write tests for new features
+- Ensure all tests pass before submitting PR
+- Add test cases for edge cases
+- Update existing tests if behavior changes
+
+### Test Structure
+
+```
+pkg/
+  ast/
+    ast.go
+    ast_test.go      # Tests for AST functionality
+  parser/
+    parser.go
+    parser_test.go   # Tests for parsers
+  diff/
+    diff.go
+    diff_test.go     # Tests for diff logic
+```
+
+## Adding a New Format
+
+To add support for a new configuration format:
+
+1. Add the format constant to `pkg/parser/parser.go`:
+   ```go
+   const FormatXML Format = "xml"
+   ```
+
+2. Update `DetectFormat()` to recognize the file extension
+
+3. Implement a parser function:
+   ```go
+   func parseXML(r io.Reader) (interface{}, error) {
+       // Parse XML and return as interface{}
+   }
+   ```
+
+4. Add the case to `ParseReader()` switch statement
+
+5. Add tests in `pkg/parser/parser_test.go`
+
+6. Add example files in `examples/` directory
+
+7. Update documentation
+
+## Pull Request Guidelines
+
+- **Title**: Use a clear, descriptive title
+- **Description**: Explain what changes you made and why
+- **Tests**: Include tests for new functionality
+- **Documentation**: Update README or other docs if needed
+- **One feature per PR**: Keep PRs focused on a single feature or fix
+
+## Reporting Issues
+
+When reporting issues, please include:
+
+- Go version: `go version`
+- Operating system and version
+- Clear description of the problem
+- Steps to reproduce
+- Expected vs actual behavior
+- Error messages or logs
+- Sample configuration files (if applicable)
+
+## Feature Requests
+
+We welcome feature requests! Please:
+
+- Check if the feature already exists
+- Search existing issues for similar requests
+- Provide a clear use case
+- Explain why the feature would be valuable
+
+## Code Review Process
+
+1. All PRs require review before merging
+2. Address review comments
+3. Keep the discussion constructive and professional
+4. PRs may be updated by maintainers to fix minor issues
+
+## Project Structure
+
+```
+go-config-diff/
+├── cmd/
+│   └── go-config-diff/    # CLI entry point
+├── pkg/
+│   ├── ast/               # Abstract Syntax Tree
+│   ├── parser/            # Format parsers
+│   ├── diff/              # Comparison logic
+│   └── output/            # Output formatters
+├── examples/              # Example config files
+├── Makefile               # Build automation
+└── README.md              # Documentation
+```
+
+## Areas for Contribution
+
+- **New format support**: Add XML, HOCON, or other formats
+- **Output formats**: Add more output options (HTML, Markdown, etc.)
+- **Performance**: Optimize comparison for large files
+- **Documentation**: Improve examples and guides
+- **Tests**: Add more test coverage
+- **Bug fixes**: Fix reported issues
+
+## Questions?
+
+Feel free to open an issue with your question or reach out to the maintainers.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the GPL-3.0 License.
+
+Thank you for contributing to go-config-diff! 🎉

Makefile

@@ -0,0 +1,40 @@
+.PHONY: build test install clean run help
+
+# Binary name
+BINARY_NAME=go-config-diff
+
+# Build the binary
+build:
+	@echo "Building $(BINARY_NAME)..."
+	@go build -o $(BINARY_NAME) ./cmd/go-config-diff
+
+# Run tests
+test:
+	@echo "Running tests..."
+	@go test ./... -v
+
+# Install the binary
+install:
+	@echo "Installing $(BINARY_NAME)..."
+	@go install ./cmd/go-config-diff
+
+# Clean build artifacts
+clean:
+	@echo "Cleaning..."
+	@rm -f $(BINARY_NAME)
+	@go clean
+
+# Run the application with example
+run: build
+	@echo "Running example..."
+	@./$(BINARY_NAME) examples/config1.yaml examples/config2.yaml || true
+
+# Show help
+help:
+	@echo "Available targets:"
+	@echo "  build   - Build the binary"
+	@echo "  test    - Run tests"
+	@echo "  install - Install the binary to GOPATH/bin"
+	@echo "  clean   - Clean build artifacts"
+	@echo "  run     - Build and run with example files"
+	@echo "  help    - Show this help message"

QUICKREF.md

@@ -0,0 +1,127 @@
+# Quick Reference Guide
+
+## Installation
+
+```bash
+go install github.com/BaseMax/go-config-diff/cmd/go-config-diff@latest
+```
+
+## Basic Commands
+
+```bash
+# Compare two config files
+go-config-diff config1.yaml config2.yaml
+
+# Use different output format
+go-config-diff -format=json config1.json config2.json
+go-config-diff -format=plain config1.toml config2.toml
+
+# Show summary of changes
+go-config-diff -summary config1.ini config2.ini
+
+# Show version
+go-config-diff -version
+
+# Show help
+go-config-diff -help
+```
+
+## Output Symbols
+
+- `+` Green: Added field or value
+- `-` Red: Removed field or value  
+- `~` Yellow: Modified field or value
+
+## Exit Codes
+
+- `0`: No differences found
+- `1`: Differences found or error occurred
+
+## Supported Formats
+
+- YAML (`.yaml`, `.yml`)
+- JSON (`.json`)
+- TOML (`.toml`)
+- INI (`.ini`, `.conf`)
+
+## Use Cases
+
+### CI/CD Pipeline
+```bash
+# Exit with error if configs differ
+go-config-diff prod-config.yaml staging-config.yaml
+```
+
+### Generate Machine-Readable Report
+```bash
+# Output JSON for further processing
+go-config-diff -format=json old.json new.json > diff-report.json
+```
+
+### Quick Visual Check
+```bash
+# Colored output with summary
+go-config-diff -summary app-v1.yaml app-v2.yaml
+```
+
+## Features
+
+✅ Semantic comparison (not line-by-line)  
+✅ Ignores key ordering in objects/maps  
+✅ Deep nested structure comparison  
+✅ Type-aware comparison  
+✅ Multiple output formats  
+✅ Colored terminal output  
+✅ Path tracking for changes  
+✅ Summary statistics  
+
+## Common Patterns
+
+### Compare across formats
+```bash
+# Even different formats are compared semantically
+go-config-diff config.yaml config.json
+```
+
+### Integration with Git
+```bash
+# Compare config between branches
+git show main:config.yaml > /tmp/old.yaml
+git show feature:config.yaml > /tmp/new.yaml
+go-config-diff /tmp/old.yaml /tmp/new.yaml
+```
+
+### Automation
+```bash
+# Use in scripts
+if go-config-diff base.yaml custom.yaml; then
+    echo "Configs are identical"
+else
+    echo "Configs differ"
+fi
+```
+
+## Building from Source
+
+```bash
+git clone https://github.com/BaseMax/go-config-diff.git
+cd go-config-diff
+make build
+./go-config-diff -version
+```
+
+## Development
+
+```bash
+# Run tests
+make test
+
+# Build binary
+make build
+
+# Run with examples
+make run
+
+# Clean artifacts
+make clean
+```