v0.2.0: Canonical block synchronization and source skimming features

This merge combines all feature development from the dev/0.2 branch into a single canonical update for v0.2.0.
Highlights include the new `Sourcerer::Sync` engine, the `Sourcerer::SourceSkim` document inspection API,
and utilities for inferring paths from strings and for runtime amendment of `Array<String>` lists.

- **Sourcerer::Sync**: A new engine for synchronizing content blocks between template sources and target files
   using configurable tag markers. Includes:
  - `BlockParser`: Format-agnostic tagged-region parser supporting AsciiDoc, Ruby, Shell, and HTML comments.
  - `Cast`: Operations for initializing new files from Liquid templates or updating existing blocks.
  - Support for "canonical prefixes" (e.g., `universal-`) to distinguish managed content.

- **Sourcerer::SourceSkim**: A machine-oriented document inspection API that produces structured representations of AsciiDoc source files.
  - Extracts section hierarchies (tree or flat), attributes, images, includes, tables, and blocks.
  - Includes an `Asciidoctor::TreeProcessor` extension for integration into generic conversion pipelines.
  - SChema and sample file added to help tools infer skim output structure:
    - `specs/data/asciidoc-source-skim-model.yaml` (representative structure w/ comments)
    - `specs/data/asciidoc-source-skim.schema.json` (JSON Schema definition of full skim output)

- **Two Example Scripts**: New CLI utilities (`scripts/mark_down_grade.rb` and `scripts/skim_asciidoc.rb`).

- `Sourcerer::Util::Pathifier`: Unified path resolution supporting files, directories (with recursive search), and glob patterns.
- `Sourcerer::Util::ListAmend`: Implements a +/- amendment syntax for merging user-supplied lists into library defaults.
- `Sourcerer::AttributesFilter`: Shared utility for partitioning builtin vs. user-defined Asciidoctor attributes.

- Version bumped 0.1.0 -> 0.2.0.
- Added `AsciiSourcerer::Sync` alias for namespace parity.
- Updated main `Sourcerer` facade with new autoloads and logic.
- Comprehensive test suite expansion (approx. 150+ new RSpec examples).
  - 17-example `block_parser_spec.rb` and 23-example `cast_spec.rb` added.
  - 5 fixture files added under `specs/tests/fixtures/sync/`.
  - `ascii_sourcerer_alias_spec.rb` version assertion updated to `0.2.0`.
- RuboCop baseline updated for new modules.
- README.adoc updated with new documentation for all features.
- Existing Bash scripts updated with proper shebang statments.

Author: briandominick

.config/rubocop.yml

@@ -17,16 +17,32 @@ Metrics/ModuleLength:
     - lib/sourcerer/asciidoc.rb
     - lib/sourcerer/mark_down_grade.rb
     - lib/sourcerer/rendering.rb
+    - lib/sourcerer/sync/block_parser.rb # intentionally full; barely over
 
 Metrics/ClassLength:
   Exclude:
     - lib/sourcerer/mark_down_grade.rb
+    - lib/sourcerer/source_skim/skimmer.rb
+    - lib/sourcerer/sync/cast.rb # no advantage to splitting
 
 Metrics/MethodLength:
   Exclude:
     - lib/sourcerer/asciidoc.rb
     - lib/sourcerer/jekyll/monkeypatches.rb
     - lib/sourcerer/mark_down_grade.rb
+    - lib/sourcerer/source_skim/skimmer.rb
+    # BlockParser.parse is a single-pass parser; extracting sub-steps into private
+    # helpers would obscure the algorithm without reducing real complexity.
+    - lib/sourcerer/sync/block_parser.rb # abstraction would obscure algorithm
+    - lib/sourcerer/sync/cast.rb # splitting adds indirection w/out clarity gains.
+
+Metrics/ParameterLists:
+  Exclude:
+    # BlockParser.parse + Cast.sync/Cast.initialize options are independently 
+    #  documented public API params; grouping into options hash would reduce 
+    #  discoverability.
+    - lib/sourcerer/sync/block_parser.rb
+    - lib/sourcerer/sync/cast.rb
 
 RSpec/SpecFilePathFormat:
   CustomTransform:
@@ -35,8 +51,16 @@ RSpec/SpecFilePathFormat:
     AsciiDoc: asciidoc
     PlainTextConverter: plaintext_converter
 
-# Integration test of alias mechanism requires coupled assertions
-# to verify both namespaces work identically as a complete feature
 RSpec/MultipleExpectations:
+  # Sync specs test stateful operations (file writes, parse results) where
+  #  grouping 2-4 closely related assertions per example aids readability.
+  Max: 4
   Exclude:
+    # Integration test of alias mechanism requires coupled assertions
+    #  to verify both namespaces work identically as a complete feature
     - specs/tests/rspec/ascii_sourcerer_alias_spec.rb
+
+RSpec/ExampleLength:
+  # Sync integration examples require inline heredoc fixtures plus the assertions
+  #  that exercise them; extracting to let blocks rarely improves clarity here.
+  Max: 15

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    asciisourcerer (0.1.0)
+    asciisourcerer (0.2.0)
       asciidoctor (~> 2.0)
       asciidoctor-html5s (~> 0.5)
       jekyll (~> 4.4)