context_spook 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a00a3e36535b351b630e539a1dfae938bb2325c2f639e3d0b318f1cac0e8c14f
-  data.tar.gz: 3c7976d1672dd67d6b0b07d64350e3baf211d6e8752b83631de9f5a17ae642f3
+  metadata.gz: 5cca218e18443bf3698be556f93b822253a9f0dd4c93322d1ee9c826d1a26dc3
+  data.tar.gz: d8c48e20203cbc5c1c0741e93805480aa7fbe9987821fe2b9839447902879149
 SHA512:
-  metadata.gz: 82bf0afffa28eab0b379ec94c9a7a7cd34406ca82ccf4a7e78d26103082b8610ce3461a06a26772381fe59d6cfa401516eed532d33c6742cff980d08dea5508d
-  data.tar.gz: f969059b0b7ca9490ceb6560c5735da343c4ee5ee5ff856bae919da5ab66f02886e55a7096ad33b91241a147d78f5b5a82ec652ce25800658d46e4dc6a87bbc2
+  metadata.gz: a7f1fb4f2b26f9c59dc6a48be8db0a2ffc4381250334a401c6ad2944fe398cb18bcc0154df6111d26ceac1a9bcad7ac4386626aeb681bbe20f1286310fbe58f0
+  data.tar.gz: 990b7df25449551007c8e986ec479bdf5656195e47ef6d7243603849179a5fac6edaa6e245bbfaa99768115b3b46eeffc5baf6f37e542c8a4b729dc443ba8b13

data/Rakefile

@@ -38,7 +38,7 @@ GemHadar do
   dependency 'mime-types',     '~> 3.0'
   dependency 'yaml',           '~> 0.4'
   dependency 'pathname',       '~> 0.4'
-  dependency 'ruby-json-toon', '~> 1.0'
+  dependency 'toon-ruby',      '>= 0.1'
   development_dependency 'all_images', '~> 0.6'
   development_dependency 'rspec',      '~> 3.2'
   development_dependency 'debug'

data/context_spook.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: context_spook 1.3.0 ruby lib
+# stub: context_spook 1.5.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "context_spook".freeze
-  s.version = "1.3.0".freeze
+  s.version = "1.5.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -13,7 +13,7 @@ Gem::Specification.new do |s|
   s.email = "flori@ping.de".freeze
   s.executables = ["context_spook".freeze]
   s.extra_rdoc_files = ["README.md".freeze, "lib/context_spook.rb".freeze, "lib/context_spook/generator.rb".freeze, "lib/context_spook/output_context.rb".freeze, "lib/context_spook/toon.rb".freeze, "lib/context_spook/utils.rb".freeze, "lib/context_spook/verbose_puts.rb".freeze, "lib/context_spook/version.rb".freeze]
-  s.files = [".contexts/project.rb".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "bin/context_spook".freeze, "context_spook.gemspec".freeze, "hello_world.json".freeze, "hey_world.yaml".freeze, "lib/context_spook.rb".freeze, "lib/context_spook/generator.rb".freeze, "lib/context_spook/output_context.rb".freeze, "lib/context_spook/toon.rb".freeze, "lib/context_spook/utils.rb".freeze, "lib/context_spook/verbose_puts.rb".freeze, "lib/context_spook/version.rb".freeze, "spec/context_spook/generator_spec.rb".freeze, "spec/context_spook/toon_spec.rb".freeze, "spec/spec_helper.rb".freeze]
+  s.files = [".contexts/project.rb".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "bin/context_spook".freeze, "context_spook.gemspec".freeze, "hello_world.json".freeze, "hey_world.yaml".freeze, "lib/context_spook.rb".freeze, "lib/context_spook/generator.rb".freeze, "lib/context_spook/output_context.rb".freeze, "lib/context_spook/toon.rb".freeze, "lib/context_spook/toon/example.md".freeze, "lib/context_spook/utils.rb".freeze, "lib/context_spook/verbose_puts.rb".freeze, "lib/context_spook/version.rb".freeze, "spec/context_spook/generator_spec.rb".freeze, "spec/context_spook/toon_spec.rb".freeze, "spec/spec_helper.rb".freeze]
   s.homepage = "https://github.com/flori/context_spook".freeze
   s.licenses = ["MIT".freeze]
   s.rdoc_options = ["--title".freeze, "ContextSpook - context_spook collects project context for AI".freeze, "--main".freeze, "README.md".freeze]
@@ -36,5 +36,5 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency(%q<mime-types>.freeze, ["~> 3.0".freeze])
   s.add_runtime_dependency(%q<yaml>.freeze, ["~> 0.4".freeze])
   s.add_runtime_dependency(%q<pathname>.freeze, ["~> 0.4".freeze])
-  s.add_runtime_dependency(%q<ruby-json-toon>.freeze, ["~> 1.0".freeze])
+  s.add_runtime_dependency(%q<toon-ruby>.freeze, [">= 0.1".freeze])
 end

data/lib/context_spook/generator.rb

@@ -13,28 +13,30 @@ require 'context_spook/output_context'
 module ContextSpook
   include DSLKit::Interpreter
 
-  # The generate_context method processes a context definition file or block
-  # and returns the resulting context object.
+  # The generate_context method creates a context object by either evaluating a
+  # block or parsing a file
   #
-  # This method serves as the primary entry point for generating project
-  # context data. It accepts either a filename pointing to a context definition
-  # file or a block containing the context definition, but not both.
-  # When a filename is provided, it reads and parses the file content. When a
-  # block is provided, it evaluates the block within the generator's context.
-  # The method ensures that only one context definition mechanism is used.
+  # This method serves as the primary entry point for generating context data.
+  # It accepts either a filename pointing to a context definition file or a
+  # block containing the context definition. The method handles the creation of
+  # a generator instance, processes the context definition, and returns the
+  # resulting context object.
   #
-  # @param filename [ String, nil ] the path to the context definition file to
-  #   be processed
+  # @param filename [ String, nil ] the path to a context definition file, or
+  #   nil if using a block
   # @param verbose [ TrueClass, FalseClass ] flag to enable verbose output
-  #   during processing, defaults to false.
-  # @param block [ Proc ] a block containing the context definition to be
-  #   evaluated
+  #   during processing
+  # @param format [ String, nil ] the output format for the context, either
+  #   'JSON' or 'TOON'
+  # @param block [ Proc ] a block containing the context definition, used if
+  #   filename is nil
   #
-  # @return [ ContextSpook::Generator::Context ] the context object generated
-  #   from the file contents or block
+  # @return [ ContextSpook::Generator::Context ] the generated context object containing
+  #   project metadata, file contents, command outputs, and variables
   #
   # @raise [ ArgumentError ] if neither a filename nor a block is provided
-  # @raise [ ArgumentError ] if both a filename and a block are provided
+  # @raise [ ArgumentError ] if an invalid format is specified
+  # @raise [ ArgumentError ] if the context definition file cannot be read or parsed
   def self.generate_context(filename = nil, verbose: false, format: nil, &block)
     verbose = !!verbose
     filename.present? ^ block or
@@ -56,8 +58,18 @@ module ContextSpook
     include VerbosePuts
     include OutputContext
 
+    # The verbose method returns the verbose flag indicating whether verbose
+    # output is enabled.
+    #
+    # @return [ TrueClass, FalseClass ] true if verbose output is enabled,
+    #   false otherwise
     attr_reader :verbose
 
+    # The format method returns the format identifier for the context output.
+    #
+    # @return [ String ] the format identifier, either 'JSON' or 'TOON'
+    attr_reader :format
+
     private_class_method :new
 
     # The initialize method sets up the object by evaluating the provided block
@@ -70,6 +82,9 @@ module ContextSpook
     def initialize(verbose: false, format: nil, &block)
       @verbose = !!verbose
       @format  = (format || 'JSON').upcase
+      %w[ TOON JSON ].include?(@format) or
+        raise ArgumentError,
+          "format needs to be either JSON or TOON, was #{@format.inspect}"
       block and instance_eval(&block)
     end
 
@@ -107,8 +122,17 @@ module ContextSpook
       def initialize(generator:, &block)
         @generator = generator
         block and instance_eval(&block)
+        meta(format: generator.format)
+        if generator.format == 'TOON'
+          meta(toon_example: toon_example)
+        end
       end
 
+      # The generator method returns the generator object associated with this
+      # context.
+      #
+      # @return [ ContextSpook::Generator ] the generator instance that created
+      #   this context
       attr_reader :generator
 
       delegate :verbose, to: :generator

data/lib/context_spook/toon/example.md

@@ -0,0 +1,69 @@
+# TOON (Token-Oriented Object Notation)
+
+It is a compact, human-readable serialization format that reduces JSON token
+count by 30-40% while maintaining lossless data fidelity. It uses CSV-style
+tabular arrays for uniform data structures and YAML-like indentation for nested
+objects, making it ideal for LLM input where token efficiency and parsing
+reliability matter.
+
+Key benefit: Same data, fewer tokens, better LLM understanding.
+
+**Original JSON:**
+```json
+{
+  "database": {
+    "name": "user_management",
+    "tables": [
+      {
+        "name": "users",
+        "columns": [
+          {
+            "name": "id",
+            "type": "integer",
+            "primary_key": true
+          },
+          {
+            "name": "email",
+            "type": "string",
+            "unique": true
+          }
+        ],
+        "row_count": 1000
+      },
+      {
+        "name": "orders",
+        "columns": [
+          {
+            "name": "id",
+            "type": "integer",
+            "primary_key": true
+          },
+          {
+            "name": "user_id",
+            "type": "integer"
+          }
+        ],
+        "row_count": 5000
+      }
+    ]
+  }
+}
+```
+
+**TOON equivalent:**
+```
+database:
+  name: user_management
+  tables[2]{name,row_count}:
+    users,1000
+    orders,5000
+  tables[2]{name,columns}:
+    users:
+      columns[2]{name,type,primary_key}:
+        id,integer,true
+        email,string,true
+    orders:
+      columns[2]{name,type}:
+        id,integer,true
+        user_id,integer,false
+```

data/lib/context_spook/toon.rb

@@ -1,4 +1,4 @@
-require 'ruby_json_toon'
+require 'toon'
 
 # The ContextSpook::TOON module provides TOON (Token-Oriented Object Notation)
 # serialization functionality for context objects.
@@ -7,7 +7,7 @@ module ContextSpook::TOON
   #
   # @return [String] the TOON-encoded representation of the context
   def to_toon
-    RubyJsonToon.encode(as_json)
+    ::Toon.encode(as_json)
   end
   memoize method: :to_toon
 
@@ -17,4 +17,17 @@ module ContextSpook::TOON
   def toon_size
     to_toon.size
   end
+
+  # The toon_example method reads and returns the content of an example
+  # Markdown file that demonstrates the TOON (Token-Oriented Object Notation)
+  # format.
+  #
+  # This method is used to provide a sample representation of how context data
+  # can be formatted in TOON, which is an alternative serialization format
+  # supported by the ContextSpook library.
+  #
+  # @return [ String ] the content of the TOON example Markdown file
+  def toon_example
+    File.read(Pathname.new(__dir__) + 'toon/example.md')
+  end
 end

data/lib/context_spook/version.rb

@@ -1,6 +1,6 @@
 module ContextSpook
   # ContextSpook version
-  VERSION         = '1.3.0'
+  VERSION         = '1.5.0'
   VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
   VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
   VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:

data/spec/context_spook/generator_spec.rb

@@ -33,6 +33,21 @@ describe ContextSpook::Generator do
       described_class.send(:new).output_context_size
     end
 
+    context 'can handle formats' do
+      it 'raises exceptions for invalid formats' do
+        generator = described_class.send(:new, format: 'TOON')
+        expect(generator.format).to eq 'TOON'
+      end
+
+      it 'raises exceptions for invalid formats' do
+        expect {
+          described_class.send(:new, format: 'YAML')
+        }.to raise_error(
+          ArgumentError, /format needs to be either JSON or TOON, was "YAML"/
+        )
+      end
+    end
+
     it 'cannot do from block and filename' do
       expect {
         ContextSpook.generate_context('.contexts/project.rb') { }

data/spec/context_spook/toon_spec.rb

@@ -20,8 +20,22 @@ describe ContextSpook::TOON do
 
     it 'produces valid TOON output' do
       toon_output = context.to_toon
-      # TOON should be a valid string representation
-      expect { RubyJsonToon.decode(toon_output) }.not_to raise_error
+      expect(toon_output).to match(
+        %r{
+          \Afiles:\n
+          ^[ ]{2}"lib/context_spook\.rb":\n
+          ^[ ]{4}content:[ ]"[^"]+"\n
+          ^[ ]{4}size:[ ]120\n
+          ^[ ]{4}lines:[ ]5\n
+          ^[ ]{4}content_types\[2\]:[ ]application/x-ruby,text/x-ruby\n
+          ^commands:\n
+          ^metadata:\n
+          ^[ ]{2}version:[ ]"1\.0"\n
+          ^[ ]{2}format:[ ]JSON\n
+          ^variables:\n
+          ^[ ]{2}foo:[ ]bar\z
+        }x
+      )
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: context_spook
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Florian Frank
@@ -178,19 +178,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.4'
 - !ruby/object:Gem::Dependency
-  name: ruby-json-toon
+  name: toon-ruby
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '0.1'
 description: |
   context_spook is a library that collects and organizes project
   information to help AI assistants understand codebases better.
@@ -221,6 +221,7 @@ files:
 - lib/context_spook/generator.rb
 - lib/context_spook/output_context.rb
 - lib/context_spook/toon.rb
+- lib/context_spook/toon/example.md
 - lib/context_spook/utils.rb
 - lib/context_spook/verbose_puts.rb
 - lib/context_spook/version.rb