lite-utils-md_code 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d4f6dae34cdd94c22ab7eec0c7f639b844a5c665c3ceee865117609a65024602
+  data.tar.gz: 0350753f46a05fa6ac07d0c5a0a4d29bbfccc13fe0be3d282e571536f5560c29
+SHA512:
+  metadata.gz: d5680075287f717edd30aac0e2ea468d40269330ccd9d0e914d9c720a80ec6dd10f52438b08e2ca2f72cdf7a75e23c92381869fbe386a298a50e430e571d31d5
+  data.tar.gz: 3f9fa8897dd8e3ff95985b83979cbb3785eca986237bc75a8da563237565e12786ac4f269056cd58a10b7d55c7b38aad8d87b19f5ca08d37852297cbf293220a

data/.rubocop.yml

@@ -0,0 +1,88 @@
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: start_of_line
+
+Layout/LineLength:
+  Exclude:
+    - spec/**/*.rb
+
+Lint/BooleanSymbol:
+  Enabled: false
+
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - spec/**/*.rb
+
+Lint/ShadowingOuterLocalVariable:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*.rb
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/ModuleLength:
+  Max: 200
+
+Naming/BinaryOperatorParameterName:
+  Enabled: false
+
+Naming/BlockForwarding:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/VariableNumber:
+  Exclude:
+    - spec/**/*.rb
+
+RSpec/ExampleLength:
+  Max: 10
+
+RSpec/IndexedLet:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+Style/ArgumentsForwarding:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/DocumentDynamicEvalDefinition:
+  Enabled: false
+
+Style/EachWithObject:
+  Enabled: false
+
+Style/HashConversion:
+  Enabled: false
+
+Style/HashSyntax:
+  Enabled: false
+
+Style/MethodCallWithoutArgsParentheses:
+  Enabled: false
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Style/RedundantArrayConstructor:
+  Enabled: false
+
+Style/RedundantSelfAssignment:
+  Enabled: false
+
+Style/TrailingUnderscoreVariable:
+  Enabled: false
+

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  gem 'byebug', '~> 11'
+  gem 'rspec', '~> 3'
+  gem 'rubocop'
+  gem 'rubocop-rspec'
+  gem 'simplecov'
+end

data/README.md

@@ -0,0 +1,94 @@
+# lite-utils-md_code
+Extracts runnable code inside MD fences, 
+tagged with an identifier, so you can `eval` 
+them from your test suite. The main use case: 
+keeping documentation examples honest by actually 
+running them as specs.
+
+## Writing the documentation
+Write runnable code in the MD file and mark it
+with a tag and a unique identifier. The
+fenced block looks somewhat like this in raw MD:
+````ruby test rspec_example
+```ruby test rspec_example
+expect(true).to be(true)
+```
+````
+
+The info string after the opening triple-backtick follows a fixed
+grammar: `<language> <tag> <key>`, space-separated.
+
+- `language` – the language identifier used for syntax highlighting
+(e.g. `ruby`). Not interpreted by this library.
+- `tag` – groups snippets so they can be filtered together. Matches
+the `tag:` keyword passed to `MdCode.instance`.
+- `key` – an identifier for this specific snippet, used later
+to reference it via `SPECS.snippet!(:key)`. Must be unique
+in a tag.
+
+So ` ```ruby test unique_identifier ` declares a Ruby snippet, tagged
+`test`, retrievable under the key `unique_identifier`.
+
+## Writing the tests
+Load the snippets somewhere in your specs. The positional
+argument is the path to the file containing code snippets,
+optional `tag` keyword specifies the tag used to filter
+them – defaults to `:test`. Another 
+optional keyword is `dir`, which can be used to pass over 
+`__dir__` from the caller's location.
+```ruby test extract_snippets
+SPECS = MdCode.instance('../../../README.md', dir: __dir__)
+```
+
+Configure RSpec so that it ensures all snippets have been consumed
+```ruby test rspec_config
+RSpec.configure do |config|
+  config.add_setting :readme_spec, default: false
+  
+  config.define_derived_metadata(file_path: %r{spec/utils/md_code}) do |meta|
+    config.readme_spec = true
+  end
+  
+  config.after(:suite) do
+    next unless config.readme_spec
+    
+    SPECS.ensure_consumed!
+  end
+end
+```
+
+You may need a more complex configuration depending on 
+how you structure your specs; however, the setup shown 
+above works even with complex readme specs spreading 
+across multiple files.
+
+Eval the snippets inside your specs – either as a part of the context
+or inside your examples. Note the bang at the end of the method name – 
+this method tracks usage of individual keys and raises if it was 
+called twice with the same key. This makes it easier to avoid mistakes
+where your test evals some key by mistake and omits another,
+making sure your whole documentation is tested as intended.
+```ruby test rspec_eval
+it 'is true' do 
+  eval(SPECS.snippet!(:rspec_example))
+end
+```
+
+Obviously the bang variant is meant for snippets that run 
+exactly once across the whole suite. When the snippet 
+represents shared setup – like a memoized helper body –
+it must be allowed to evaluate repeatedly. In such 
+case use `SPECS.snippet` without the bang. It still tracks 
+usage but doesn't raise when the key is accessed multiple times.
+
+**A note on `eval`**: This library works by evaluating snippet contents 
+as Ruby source. That's inherent to the pattern – the whole point is 
+to run your documentation's example code.
+
+Snippets only ever come from files that already live in your own 
+repository, and they're only evaluated inside your own test suite. 
+You're not pulling snippets from user input, a network request, 
+or any other untrusted source – just from docs you wrote yourself.
+
+## License
+This library is published under the MIT license

data/lib/lite/utils/md_code/error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Lite
+  module Utils
+    module MdCode
+      class Error < StandardError; end
+    end
+  end
+end

data/lib/lite/utils/md_code/extraction.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'markly'
+
+require_relative 'error'
+
+module Lite
+  module Utils
+    module MdCode
+      module Extraction
+        def self.extract(path, dir, tag)
+          extract_each(Markly.parse(read(path, dir)), tag)
+        end
+
+        def self.extract_each(doc, tag)
+          specs = {}
+          regex = Regexp.new("^\\S+\\s+#{tag}\\s+(\\S+)$")
+
+          doc.walk do |node|
+            next unless node.type == :code_block
+            next unless (match = regex.match(node.fence_info))
+
+            key = match[1].to_sym
+            raise Error, "Duplicate #{tag} key: #{key}" if specs.key?(key)
+
+            specs.store(key, node.string_content.freeze)
+          end
+
+          specs.freeze
+        end
+
+        def self.read(path, dir)
+          full_path(path, dir).read
+        end
+
+        def self.full_path(path, dir)
+          dir ? Pathname.new(dir).join(path) : Pathname.new(path)
+        end
+      end
+    end
+  end
+end

data/lib/lite/utils/md_code/instance.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'lite/data'
+
+require_relative 'error'
+
+module Lite
+  module Utils
+    module MdCode
+      class Instance
+        Lite::Data.define(self, args: %i[snippets usage])
+
+        def self.instance(snippets)
+          new snippets, {}
+        end
+
+        def initialize(snippets, usage)
+          super(snippets.freeze, usage)
+        end
+
+        def snippet!(key)
+          consume key, true
+        end
+
+        def snippet(key)
+          consume key, false
+        end
+
+        def consume(key, deplete)
+          raise Error, "Snippet not defined: #{key}" unless snippets.key?(key)
+          raise Error, "Key already used: #{key}" if usage[key] == :depleted
+
+          case usage[key]
+          when nil, :consumed then usage[key] = deplete ? :depleted : :consumed
+          end
+          snippets[key]
+        end
+
+        def ensure_consumed!
+          unconsumed = snippets.keys - usage.keys
+
+          raise Error, "Some snippets haven't been consumed: #{unconsumed.join(', ')}" unless unconsumed.empty?
+        end
+      end
+    end
+  end
+end

data/lib/lite/utils/md_code/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Lite
+  module Utils
+    module MdCode
+      VERSION = '0.0.1'
+    end
+  end
+end

data/lib/lite/utils/md_code.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'md_code/version'
+require_relative 'md_code/extraction'
+require_relative 'md_code/instance'
+
+module Lite
+  module Utils
+    module MdCode
+      def self.instance(path, dir: nil, tag: :test)
+        snippets = Extraction.extract(path, dir, tag)
+        Instance.instance snippets
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: lite-utils-md_code
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Tomas Milsimer
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lite-data
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: markly
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  Extracts runnable code inside MD fences, tagged with an identifier,
+  so you can `eval` them from your test suite.
+email:
+- tomas.milsimer@protonmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- Gemfile
+- README.md
+- lib/lite/utils/md_code.rb
+- lib/lite/utils/md_code/error.rb
+- lib/lite/utils/md_code/extraction.rb
+- lib/lite/utils/md_code/instance.rb
+- lib/lite/utils/md_code/version.rb
+homepage: https://github.com/lame-impala/lite-utils-md_code
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Connects a MD file to your code through MD fencing
+test_files: []