blueprint-html2slim 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcd9f4a5d346b4edee89ff58f86e84501a642530ce563be68daca7ccaa4747e4
-  data.tar.gz: b8d50860a181f7b4077be2aba82c520a5c3c0e498fed7b3c069e6e40077447ee
+  metadata.gz: d27f4f166468ae3be90116e4ff94d8c9901eb72a033ef69b14822d6ed8ce8273
+  data.tar.gz: c7916bc01602176018608dc723e49816670d6e6688d890aedde2ec09b4901a4a
 SHA512:
-  metadata.gz: f53a93b08cb863037eadc43536bbdf5a551a58586d495254cfbfff181d2e0db1512f8a2533453a4c60b914b78ef5e7adfa3ce9fe3780c8ff3bd76c07ad0f388d
-  data.tar.gz: d0206ced006d3113f391387223c77b96e958d1e6f6b5bafb44882badbd93eba8f75d786ba5a03d60787b873bb8bcb36ef05bf932f2b6c8c7a804d21e1f670382
+  metadata.gz: d019b9a611db510f8bd3ed39187c651c40dbd1dab414e7012cbb97d8e4cf06222034d45a1d06db44bf7709a3b822a12021af205fccf5b3482c325b9ca3377f89
+  data.tar.gz: 21da628071a957513c4faa67aedb8fe63ee76274efc3c9f08f6c0aeeae353b89017e7785b7fb144a8378718aaf297b9cebf1ba61ad9a623e79de411aad045dc1

data/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.3.0] - 2025-01-16
+
+### Added
+- **SlimExtractor enhancements**:
+  - Extract outline up to specified depth (`--outline N`) for high-level structure analysis
+  - Extract fragments by CSS selector (`--selector`) supporting #id, .class, element, and combinations
+- **Comprehensive documentation**:
+  - Complete README with detailed examples for all commands
+  - All command options now have descriptive help text
+  - Added workflow examples and use cases
+  - Table of contents for easy navigation
+
+### Changed
+- Improved command-line help system with detailed option descriptions
+- Fixed extraction logic bug where keep/remove functionality wasn't working correctly
+- Enhanced help output with categorized examples
+
+### Fixed
+- SlimExtractor now correctly handles keep/remove section logic
+- Thor deprecation warnings resolved with `exit_on_failure?` method
+- RuboCop style violations corrected
+
+## [1.2.0] - 2025-01-16
+
+### Added
+- New `slimtool` command-line utility for comprehensive Slim template manipulation
+- **SlimFixer**: Automatically fixes common Slim syntax issues
+  - Fixes text starting with "/" that would be interpreted as comments (converts to pipe notation)
+  - Fixes multiline text blocks using proper pipe notation
+  - Supports backup and dry-run modes
+- **SlimExtractor**: Extract or remove specific sections from Slim templates
+  - Remove unwanted sections (doctype, head, nav, footer, script, etc.)
+  - Keep only specified sections (main, article, or any element/class/id)
+  - Remove outer wrapper elements
+  - Extract outline up to specified depth (high-level structure only)
+  - Extract fragments by CSS selector (#id, .class, element, element.class#id)
+  - Custom output file support
+- **SlimValidator**: Validate Slim syntax and check for potential issues
+  - Detects syntax errors (invalid indentation, unclosed brackets, empty Ruby markers)
+  - Strict mode: checks for tabs, inline styles, long lines
+  - Rails mode: checks for hardcoded URLs, static assets, missing CSRF tokens
+  - Comprehensive error and warning reporting
+- **SlimRailsifier**: Convert static templates to Rails conventions
+  - Configurable link mappings via JSON/YAML files (no automatic guessing)
+  - Convert CDN assets to Rails asset pipeline helpers
+  - Add CSRF protection meta tags to forms
+  - Supports dry-run and backup modes
+- **LinkExtractor**: Extract and analyze hardcoded links from templates
+  - Find all static HTML links, forms, assets, and images
+  - Categorize link types and suggest Rails helper conversions
+  - Multiple output formats (JSON, YAML, text)
+  - Batch processing of multiple files
+- Comprehensive test suite for all new SlimTool features
+
+### Changed
+- Updated gem to include both `html2slim` and `slimtool` executables
+- Rails link conversions now require explicit mappings (removed automatic fallback guessing)
+- Improved command-line help with detailed examples and option descriptions
+
 ## [1.1.0] - 2025-01-16
 
 ### Added
@@ -23,10 +82,16 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 - Initial release of blueprint-html2slim
-- HTML to Slim conversion
-- ERB template support
-- Smart file naming conventions
+- HTML to Slim conversion with full HTML5 support
+- ERB template support with proper Ruby code handling
+- Smart file naming conventions (.html → .html.slim, .erb → .slim)
 - Backup option for source files
 - Recursive directory processing
-- Dry-run mode
-- Custom output path support
+- Dry-run mode for previewing conversions
+- Custom output path support
+- Force overwrite option
+- Delete source files after conversion
+- Target directory support with structure preservation
+- Custom indentation size support
+- Comprehensive test suite with RSpec
+- RuboCop integration for code quality

data/README.md

@@ -1,9 +1,19 @@
 # Blueprint HTML2Slim
 
-A Ruby gem providing a command-line tool to convert HTML and ERB files to Slim format.
+A comprehensive Ruby gem providing tools to convert HTML/ERB files to Slim format and manipulate Slim templates.
 
 **Online Converter**: Try the web-based version at [https://railsblueprint.com/html2slim](https://railsblueprint.com/html2slim)
 
+## Table of Contents
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Tools Included](#tools-included)
+- [HTML2Slim Converter](#html2slim-converter)
+- [SlimTool - Template Manipulation](#slimtool---template-manipulation)
+- [Features Overview](#features-overview)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Requirements
 
 - Ruby 2.7 - 3.4 (compatible with latest Ruby versions)
@@ -28,7 +38,13 @@ Or install it yourself as:
 gem install blueprint-html2slim
 ```
 
-## Usage
+## Tools Included
+
+This gem provides two command-line tools:
+1. **html2slim** - Convert HTML/ERB files to Slim format
+2. **slimtool** - Manipulate and fix existing Slim files
+
+## HTML2Slim Converter
 
 ### Programmatic Usage (Ruby)
 
@@ -62,77 +78,386 @@ converter = Blueprint::Html2Slim::Converter.new(indent_size: 4)
 
 ### Command Line Usage
 
-Convert a single file:
+#### Basic Conversion
+
 ```bash
+# Convert a single file
 html2slim index.html
 # Creates: index.html.slim
-```
 
-Convert with custom output:
-```bash
+# Convert with custom output
 html2slim -o custom.slim index.html
-```
 
-Convert multiple files:
-```bash
+# Convert multiple files
 html2slim file1.html file2.erb file3.html.erb
 ```
 
-Convert and backup original files:
+#### File Management Options
+
 ```bash
+# Create backup of original files
 html2slim -b index.html
 # Creates: index.html.slim
 # Renames: index.html -> index.html.bak
+
+# Delete source files after conversion
+html2slim -d old_templates/*.erb
+# Converts and deletes the original .erb files
+
+# Force overwrite without prompting
+html2slim -f existing.html
 ```
 
-Convert files in a directory recursively:
+#### Directory Processing
+
 ```bash
+# Convert files in a directory recursively
 html2slim -r ./views
-```
 
-Convert to target directory (preserves structure):
-```bash
+# Convert to target directory (preserves structure)
 html2slim -t dist/ -r src/
 # Converts src/views/index.html to dist/views/index.html.slim
 ```
 
-Delete source files after conversion:
-```bash
-html2slim -d old_templates/*.erb
-# Converts and deletes the original .erb files
-```
+#### Preview and Testing
 
-Dry run (preview what would be converted):
 ```bash
+# Dry run (preview what would be converted)
 html2slim -n file.html
+
+# Custom indentation (default: 2 spaces)
+html2slim -i 4 template.html
 ```
 
-## Naming Convention
+### Naming Conventions
 
 - `file.html` → `file.html.slim`
 - `file.html.erb` → `file.html.slim`
 - `file.erb` → `file.slim`
 
-## Options
+### All HTML2Slim Options
 
-- `-o, --output FILE` - Output file path (only for single file conversion)
+- `-o, --output FILE` - Output file path (single file only)
 - `-r, --recursive` - Process directories recursively
-- `-n, --dry-run` - Show what would be converted without actually converting
+- `-n, --dry-run` - Preview conversions without modifying files
 - `-d, --delete` - Delete source files after successful conversion
-- `-t, --target-dir DIR` - Target directory for converted files (preserves directory structure)
+- `-t, --target-dir DIR` - Target directory for converted files
 - `-f, --force` - Overwrite existing files without prompting
-- `-b, --backup` - Backup source files with .bak extension
+- `-b, --backup` - Create .bak backup of source files
 - `-i, --indent SIZE` - Indentation size in spaces (default: 2)
 - `-h, --help` - Show help message
 - `-v, --version` - Show version
 
-## Features
+## SlimTool - Template Manipulation
+
+The `slimtool` command provides advanced manipulation capabilities for Slim files.
+
+### 1. Fix Common Syntax Issues
+
+Automatically fix common Slim syntax problems:
+
+```bash
+# Fix text starting with forward slash (e.g., span /month)
+slimtool fix pricing.slim
+
+# Fix with backup
+slimtool fix template.slim --backup
+
+# Preview fixes without modifying
+slimtool fix template.slim --dry-run
+
+# Fix multiple files
+slimtool fix views/*.slim
+```
+
+**Options:**
+- `--fix-slashes` - Fix forward slashes in text (default: true)
+- `--fix-multiline` - Fix multiline text blocks (default: true)
+- `-b, --backup` - Create .bak backup before fixing
+- `-n, --dry-run` - Preview changes without modifying files
+
+**What it fixes:**
+- Text starting with `/` that would be interpreted as comments
+- Multiline text that should use pipe notation
+- Common indentation issues
+
+### 2. Extract Content Sections
+
+Extract or remove specific sections from Slim templates:
+
+```bash
+# Remove unwanted sections
+slimtool extract page.slim --remove head,nav,footer
+
+# Keep only specific sections
+slimtool extract page.slim --keep main,article
+
+# Remove outer wrapper div
+slimtool extract page.slim --remove-wrapper
+
+# Extract outline (high-level structure only)
+slimtool extract page.slim --outline 2
+# Extracts only elements at depth 0 and 1
+
+# Extract by CSS selector
+slimtool extract page.slim --selector "#content"
+slimtool extract page.slim --selector ".main-section"
+slimtool extract page.slim --selector "article.featured"
+
+# Custom output file
+slimtool extract page.slim --output clean.slim
+```
+
+**Options:**
+- `--keep SECTIONS` - Keep only specified sections
+- `--remove SECTIONS` - Remove specified sections
+- `-o, --output FILE` - Output file path
+- `--remove-wrapper` - Remove single outer wrapper
+- `--outline N` - Extract outline up to depth N
+- `--selector CSS` - Extract fragment by CSS selector
+
+**Supported CSS Selectors:**
+- Element: `article`, `main`, `div`
+- ID: `#content`, `#sidebar`
+- Class: `.container`, `.main-section`
+- Combined: `article.featured`, `div#main.container`
+
+### 3. Validate Slim Syntax
+
+Check for syntax errors and potential issues:
+
+```bash
+# Basic validation
+slimtool validate template.slim
+
+# Validate multiple files
+slimtool validate views/**/*.slim
+
+# Strict validation (style checks)
+slimtool validate template.slim --strict
+
+# Check Rails conventions
+slimtool validate app.slim --check-rails
+
+# Combined strict + Rails checks
+slimtool validate *.slim --strict --check-rails
+```
+
+**Options:**
+- `--strict` - Enable strict mode checks
+- `--check-rails` - Check Rails best practices
+
+**What it checks:**
+
+**Basic validation:**
+- Invalid indentation
+- Unclosed brackets
+- Empty Ruby code markers (`=` or `-` with no code)
+- Text starting with `/` (would be interpreted as comment)
+
+**Strict mode (`--strict`):**
+- Tabs in indentation (enforces spaces only)
+- Inline styles (suggests using CSS classes)
+- Lines exceeding 120 characters
+- Deprecated Slim syntax
+
+**Rails checks (`--check-rails`):**
+- Static asset links (suggests asset pipeline helpers)
+- Hardcoded URLs (suggests Rails path helpers)
+- Forms without Rails helpers
+- Missing CSRF tokens in forms
+- CDN assets that could use asset pipeline
+
+### 4. Convert to Rails Conventions
+
+Transform static Slim templates to use Rails helpers:
+
+```bash
+# Create a mappings file for URL conversions
+cat > mappings.json << 'EOF'
+{
+  "/": "root_path",
+  "/about": "about_path",
+  "/users": "users_path",
+  "/login": "new_session_path",
+  "/products": "products_path"
+}
+EOF
+
+# Convert using mappings
+slimtool railsify template.slim --mappings mappings.json
+
+# Add CSRF protection to forms
+slimtool railsify form.slim --add-csrf --mappings mappings.json
+
+# Convert CDN assets to Rails asset pipeline
+slimtool railsify layout.slim --use-assets
+
+# Preview changes
+slimtool railsify template.slim --mappings mappings.json --dry-run
+
+# Process multiple files with backup
+slimtool railsify views/*.slim --mappings mappings.json --backup
+```
+
+**Options:**
+- `--mappings FILE` - JSON/YAML file with URL-to-helper mappings
+- `--add-helpers` - Convert links to Rails helpers (default: true)
+- `--use-assets` - Convert CDN assets to asset pipeline (default: true)
+- `--add-csrf` - Add CSRF meta tags to head section
+- `-b, --backup` - Create .bak backup before converting
+- `-n, --dry-run` - Preview changes without modifying
+
+**What it converts:**
+- Static links to Rails path helpers (using your mappings)
+- CDN stylesheets to `stylesheet_link_tag`
+- CDN scripts to `javascript_include_tag`
+- Static forms to include CSRF tokens
+- Image paths to use `image_tag` helper
+
+**Note:** Link conversions require explicit mappings - no automatic guessing.
+
+### 5. Extract Hardcoded Links
+
+Find and report all hardcoded links in templates:
+
+```bash
+# Display found links
+slimtool extract-links template.slim
+
+# Process multiple files
+slimtool extract-links views/**/*.slim
+
+# Save results to JSON
+slimtool extract-links *.slim -o links.json
+
+# Save in different formats
+slimtool extract-links *.slim -o links.yaml --format yaml
+slimtool extract-links *.slim -o links.txt --format text
+
+# Find links in entire project
+slimtool extract-links app/views/**/*.slim -o project_links.json
+```
+
+**Options:**
+- `-o, --output FILE` - Save results to file
+- `--format FORMAT` - Output format: json, yaml, or text (default: json)
+
+**What it finds:**
+- HTML anchor links (`a[href]`)
+- Form action URLs
+- Asset links (stylesheets, scripts)
+- Image sources
+- Any hardcoded paths that could use Rails helpers
+
+**Output includes:**
+- File location
+- Line number
+- Link type (anchor, form, asset, image)
+- Original URL
+- Suggested Rails helper (when applicable)
+
+## Features Overview
+
+### HTML2Slim Converter Features
+- ✅ Full HTML5 support
+- ✅ ERB template conversion
+- ✅ Preserves all attributes and structure
+- ✅ Smart ID/class shortcuts (`div#id.class`)
+- ✅ Handles void elements correctly
+- ✅ Preserves comments
+- ✅ Unicode/UTF-8 support
+- ✅ Multiline ERB code blocks
+- ✅ Custom indentation
+- ✅ Batch processing
+- ✅ Directory recursion
+
+### SlimTool Features
+- ✅ **Syntax Fixing**
+  - Text starting with `/` (pipe notation)
+  - Multiline text blocks
+  - Common indentation issues
+  
+- ✅ **Content Extraction**
+  - Remove unwanted sections
+  - Keep specific sections
+  - Extract by CSS selector
+  - Extract outline by depth
+  - Remove wrapper elements
+  
+- ✅ **Validation**
+  - Syntax error detection
+  - Style checking (strict mode)
+  - Rails convention checking
+  - Comprehensive error reporting
+  
+- ✅ **Rails Integration**
+  - Convert links to helpers
+  - Asset pipeline integration
+  - CSRF token support
+  - Form helper suggestions
+  
+- ✅ **Link Analysis**
+  - Find all hardcoded URLs
+  - Categorize link types
+  - Suggest Rails helpers
+  - Multiple output formats
+
+## Examples
+
+### Complete Workflow Example
+
+```bash
+# 1. Convert HTML/ERB files to Slim
+html2slim -r ./app/views_old -t ./app/views
+
+# 2. Fix any syntax issues
+slimtool fix app/views/**/*.slim --backup
+
+# 3. Validate the converted files
+slimtool validate app/views/**/*.slim --strict --check-rails
+
+# 4. Extract hardcoded links for analysis
+slimtool extract-links app/views/**/*.slim -o links.json
+
+# 5. Create mappings based on found links
+cat > url_mappings.json << 'EOF'
+{
+  "/": "root_path",
+  "/dashboard": "dashboard_path",
+  "/users": "users_path",
+  "/login": "new_session_path"
+}
+EOF
+
+# 6. Convert to Rails conventions
+slimtool railsify app/views/**/*.slim --mappings url_mappings.json --add-csrf
+
+# 7. Final validation
+slimtool validate app/views/**/*.slim --check-rails
+```
+
+### Cleaning Up Templates
+
+```bash
+# Remove all navigation and footer from templates
+slimtool extract views/*.slim --remove head,nav,footer,script
+
+# Extract only the main content area
+slimtool extract page.slim --selector "#main-content" -o clean.slim
+
+# Get high-level structure for documentation
+slimtool extract complex_page.slim --outline 2 -o structure.slim
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
 
-- Converts HTML tags to Slim syntax
-- Handles HTML attributes, IDs, and classes
-- Preserves ERB tags (<%= %> and <% %>)
-- Supports nested elements
-- Handles void elements correctly
-- Preserves comments
-- Smart output file naming
-- Optional source file backup
+This gem is available as open source under the terms of the [MIT License](LICENSE).