ro 4.2.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50e5d272b2bdbfe25f9ae109ed44568e71637820c4768ea772e757c7436c38cc
-  data.tar.gz: 84372b1f2cc28f316ed1eff63c0ce6ec4333f18a886a0cc38f4c86617baa0c0a
+  metadata.gz: f467beebd987ebb866a7f57a04810ca0c9c4f55396ca07607788c9c614919531
+  data.tar.gz: 73ccfea5d2a5d0d8eac25c1a508c3d16de2d52d44dc6b6d250f2e6e1b5616a2e
 SHA512:
-  metadata.gz: e92b12b8067606b5b5ee11a3db65c926e492298aa3bed178459550d578a6b493762acbc3424fc0e2ac259d84d45cab1a69bc5e07e3550e58cbbdd14b18078c11
-  data.tar.gz: 7a587649abd8cb3a79e667d4767b33005a47a860983725546acdae8f97dfadaafe140f49fda93a12000097171ed4aba7fea5507467bd480b9b83496115aa3352
+  metadata.gz: 4f625e44529a3e41f0d9e1f7ddd324ab439be33e364487bf48a8c9d01611694143f80d5747b0432fea673a2a598692bdbb760306a7a6370f5abb006c3ef23a1b
+  data.tar.gz: be8bf1fdb7ea9e0ba6b66095c767c6ce4d68c3680cab4fbe8c01cf1e5f85aad011542c94c8478bbf35dab2ec431befd0e7c343a06ff53b54386049e7f42fb013

data/Gemfile.lock

@@ -1,13 +1,17 @@
 PATH
   remote: .
   specs:
-    ro (2.0.0)
-      ak47 (~> 0.2)
+    ro (4.4.1)
+      ak47 (~> 0.2.5)
+      front_matter_parser (~> 1.0)
+      image_size (~> 3.4)
       kramdown (~> 2.4, >= 2.4.0)
       kramdown-parser-gfm (~> 1.1, >= 1.1.0)
       map (~> 6.6, >= 6.6.0)
+      nokogiri (~> 1)
+      rinku (~> 2.0)
       rouge (~> 4.1, >= 4.1.1)
-      webrick (~> 1.8.1)
+      webrick (~> 1.9, >= 1.9.1)
 
 GEM
   remote: https://rubygems.org/
@@ -16,28 +20,71 @@ GEM
       guard (~> 0.10.0)
       shell_tools (~> 0.1.0)
       smart_colored
-    ffi (1.16.3)
+    ffi (1.17.2)
+    ffi (1.17.2-aarch64-linux-gnu)
+    ffi (1.17.2-aarch64-linux-musl)
+    ffi (1.17.2-arm-linux-gnu)
+    ffi (1.17.2-arm-linux-musl)
+    ffi (1.17.2-arm64-darwin)
+    ffi (1.17.2-x86-linux-gnu)
+    ffi (1.17.2-x86-linux-musl)
+    ffi (1.17.2-x86_64-darwin)
+    ffi (1.17.2-x86_64-linux-gnu)
+    ffi (1.17.2-x86_64-linux-musl)
+    front_matter_parser (1.0.1)
     guard (0.10.0)
       ffi (>= 0.5.0)
       thor (~> 0.14.6)
+    image_size (3.4.0)
     kramdown (2.4.0)
       rexml
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
     map (6.6.0)
-    rexml (3.2.6)
-    rouge (4.1.1)
+    mini_portile2 (2.8.8)
+    nokogiri (1.18.8)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    nokogiri (1.18.8-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.8-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.8-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.8-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.18.8-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-linux-musl)
+      racc (~> 1.4)
+    racc (1.8.1)
+    rexml (3.3.9)
+    rinku (2.0.6)
+    rouge (4.4.0)
     shell_tools (0.1.2)
     smart_colored (1.1.1)
     thor (0.14.6)
-    webrick (1.8.1)
+    webrick (1.9.1)
 
 PLATFORMS
-  arm64-darwin-21
-  x86_64-linux
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  ruby
+  x86-linux-gnu
+  x86-linux-musl
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
 
 DEPENDENCIES
   ro!
 
 BUNDLED WITH
-   2.4.22
+   2.5.22

data/LICENSE

@@ -1 +1 @@
-Ruby
+Nonstandard

data/MIGRATION.md

@@ -0,0 +1,320 @@
+# Ro v5.0 Asset Structure Migration Guide
+
+## Overview
+
+Ro v5.0 introduces a simplified asset directory structure that reduces nesting depth and makes assets easier to understand and manage.
+
+### Automatic Warning System
+
+Ro v5.0 automatically detects when you're using old structure data and warns you on stderr:
+
+```
+⚠️  WARNING: Old Ro asset structure detected!
+
+This Ro root contains assets in the OLD structure format:
+  • identifier/attributes.yml
+  • identifier/assets/
+
+Ro v5.0 uses a simplified NEW structure:
+  • identifier.yml
+  • identifier/
+
+Collections will NOT automatically discover old-structure nodes.
+
+To migrate your data, run:
+  ro migrate /path/to/your/data
+```
+
+**This warning does NOT stop your program** - it's informational to help you know you need to migrate. The warning appears once per root directory when `Ro::Root.new` is called.
+
+### Old Structure (v4.x)
+```
+posts/
+  sample-post/
+    attributes.yml       # Metadata file INSIDE node directory
+    assets/             # Assets subdirectory
+      image.jpg
+      document.pdf
+```
+
+### New Structure (v5.0)
+```
+posts/
+  sample-post.yml       # Metadata file at COLLECTION level (moved out)
+  sample-post/          # Node directory (same location)
+    assets/             # Assets subdirectory (SAME location as before!)
+      image.jpg
+      document.pdf
+```
+
+## Benefits
+
+- **Simpler**: One less level of nesting
+- **Clearer**: Metadata file and assets directory are siblings, not parent/child
+- **Faster**: Easier to locate assets by identifier
+- **More Intuitive**: Structure is self-documenting
+
+## Migration Tool
+
+Ro v5.0 includes a migration tool to automate the conversion from old to new structure.
+
+### Basic Usage
+
+```bash
+# Preview migration (dry run)
+./bin/ro migrate --dry-run /path/to/your/ro/root
+
+# Run migration with backup (recommended)
+./bin/ro migrate /path/to/your/ro/root
+
+# Run migration without backup (not recommended)
+./bin/ro migrate --no-backup /path/to/your/ro/root
+```
+
+### Options
+
+- `--dry-run`, `-d`: Preview changes without making them
+- `--backup`, `--no-backup`, `-b`: Create backup before migrating (default: true)
+- `--verbose`, `-v`: Show detailed progress
+- `--force`, `-f`: Force migration even if new structure detected
+- `--help`, `-h`: Show help message
+
+### Migration Process
+
+The migration tool:
+
+1. **Validates** the structure to detect old/new/mixed formats
+2. **Creates a backup** (unless `--no-backup` is specified)
+3. **For each old-structure node directory**:
+   - **If node has attributes file**: Moves `identifier/attributes.yml` → `identifier.yml` (at collection level)
+   - **If node has NO attributes**: Creates empty `identifier.yml` with `{}` content
+   - Assets remain in `identifier/assets/` (no change needed!)
+
+**Important**: The migrator processes ALL node directories, even those without an attributes file. This ensures every node is discoverable in the new structure.
+
+### Safety Features
+
+- **Automatic backups**: Creates timestamped backup before migration
+- **Dry run mode**: Preview changes before applying
+- **Validation**: Detects mixed structures and warns
+- **Rollback support**: Can restore from backup if needed
+
+## Manual Migration
+
+If you prefer to migrate manually:
+
+1. **For each node WITH attributes**:
+   ```bash
+   cd posts
+
+   # Move metadata file out to collection level
+   mv sample-post/attributes.yml sample-post.yml
+
+   # Assets stay in sample-post/assets/
+   ```
+
+2. **For each node WITHOUT attributes** (assets-only):
+   ```bash
+   cd posts
+
+   # Create empty metadata file at collection level
+   echo '{}' > orphan-assets.yml
+
+   # Assets stay in orphan-assets/assets/
+   ```
+
+3. **Update your code** to use Ro v5.0
+
+## Rollback
+
+If you need to rollback after migration:
+
+```ruby
+# Using the Migrator class
+migrator = Ro::Migrator.new('/path/to/ro/root')
+migrator.rollback
+```
+
+This will restore from the most recent backup.
+
+## Migration Checklist
+
+- [ ] Review migration plan with `--dry-run`
+- [ ] Backup your data (migration creates backup automatically)
+- [ ] Run migration: `./bin/ro migrate /path/to/ro/root`
+- [ ] Verify migrated data loads correctly
+- [ ] Test your application with new structure
+- [ ] Update code to Ro v5.0 if needed
+- [ ] Remove old backups once confident
+
+## Breaking Changes
+
+### API Changes
+
+**Node initialization**:
+```ruby
+# Old (v4.x) - still works for backward compatibility
+node = Ro::Node.new(node_directory_path)
+
+# New (v5.0) - preferred for new structure
+node = Ro::Node.new(collection, metadata_file)
+```
+
+**Asset paths**:
+```ruby
+# Both old and new structure
+node.asset_dir  # => identifier/assets/
+
+# The assets/ subdirectory stays the same!
+# Only the metadata file location changes
+```
+
+### What Stays the Same
+
+- **Metadata format**: YAML/JSON/TOML structure unchanged
+- **Asset access**: `node.assets`, `node.asset_paths` work the same
+- **Collection access**: `root['collection']['node']` unchanged
+- **Attribute access**: `node[:title]`, `node.attributes` unchanged
+
+## Testing
+
+Run tests to verify migration:
+
+```bash
+# Unit tests
+ruby test/unit/collection_test.rb
+ruby test/unit/node_test.rb
+ruby test/unit/asset_test.rb
+ruby test/unit/migrator_test.rb
+
+# Integration tests
+ruby test/integration/ro_integration_test.rb
+```
+
+## Troubleshooting
+
+### "Both old and new structures detected"
+
+This indicates a partial migration. Options:
+1. Use `--force` to continue migration
+2. Manually inspect and resolve conflicts
+3. Restore from backup and retry
+
+### "Node directory not found"
+
+Ensure you're running the migration from the correct root directory.
+
+### Assets not loading after migration
+
+Check that:
+1. Metadata files are at collection level (e.g., `posts/sample-post.yml`)
+2. Node directories exist at collection level (e.g., `posts/sample-post/`)
+3. Assets are in the `assets/` subdirectory (e.g., `posts/sample-post/assets/image.jpg`)
+
+## Examples
+
+### Example 1: Single Collection
+
+Before:
+```
+ro_data/
+  posts/
+    welcome/
+      attributes.yml
+      assets/
+        banner.jpg
+```
+
+After:
+```
+ro_data/
+  posts/
+    welcome.yml          ← Metadata moved out
+    welcome/
+      assets/
+        banner.jpg       ← Assets stay in same location
+```
+
+### Example 2: Multiple Collections
+
+Before:
+```
+ro_data/
+  posts/
+    post-1/
+      attributes.yml
+      assets/
+        image.jpg
+  pages/
+    about/
+      attributes.yml
+      assets/
+        photo.png
+```
+
+After:
+```
+ro_data/
+  posts/
+    post-1.yml
+    post-1/
+      assets/
+        image.jpg
+  pages/
+    about.yml
+    about/
+      assets/
+        photo.png
+```
+
+### Example 3: Metadata-Only Node
+
+Before:
+```
+ro_data/
+  posts/
+    text-only/
+      attributes.yml
+```
+
+After:
+```
+ro_data/
+  posts/
+    text-only.yml
+```
+
+### Example 4: Assets-Only Node (No Attributes)
+
+Before:
+```
+ro_data/
+  posts/
+    orphan-assets/     ← Directory with no attributes.yml
+      assets/
+        image.jpg
+```
+
+After:
+```
+ro_data/
+  posts/
+    orphan-assets.yml  ← Empty metadata file created: {}
+    orphan-assets/
+      assets/
+        image.jpg
+```
+
+## Support
+
+For issues or questions:
+- GitHub Issues: https://github.com/ahoward/ro/issues
+- Documentation: See README.md and code comments
+
+## Version Compatibility
+
+- **Ro v4.x**: Old structure only
+- **Ro v5.0**: Both structures (with backward compatibility)
+- **Ro v6.0+**: New structure only (planned)
+
+**Recommendation**: Migrate to new structure before Ro v6.0 release.