context_spook 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46a28bdfcceb8928f53b232ce6d2e69d64632ff171eb6493edfa8c4471ffff43
-  data.tar.gz: 0ea5102521b157be1198bf9e440e28530f023565a4d2ae3c5988ddd685f00912
+  metadata.gz: 4088e8a4f8de00062dcea1b56b696dd1190731c0c30944a95c60a14cad995fa9
+  data.tar.gz: 996fb30d8a2542a387451416ece827dd1b8062344317ef798db803c216d39e17
 SHA512:
-  metadata.gz: 8d351e068d6a174857d3dd9d5d413e71a4cb6d84fe271595076bd72870e2e10e539e90475556f1d0381048e092360061ee81d8585ce60935431d8c049af0d24a
-  data.tar.gz: f3a2f224075862ed04c87bd5ca695a410510b42a4974fd061edeb99025712de4fff2691f7401da1e6e1f977041f9fb9b5a6ad25b641e441746fff367206c6f09
+  metadata.gz: df6ce1080b5b98a1e279f945cb0e5934592ea586c15abc24234b1c44aaa0d5aac55308227c2966a1e2e9912f620f4d13a5bda0940726028f589aa0ee522dc3fd
+  data.tar.gz: 2b787ae025a227d47f7d6ab53d850bc0c2084a6872e16bb2b60d122965d3dcdb17531fc4118371de82da0edcdd29b7a4ebe143b55019d3116bb424117edb85f4

data/README.md

@@ -32,8 +32,46 @@ $ gem install context_spook
 
 ## Usage
 
-Create a `contexts/project.rb` file that describes your project context using
-the DSL in a context definition file:
+### Programmatic Usage
+
+#### Directly in Ruby
+
+Now you can generate context from a block directly in Ruby using the DSL:
+
+```ruby
+context = ContextSpook::generate_context do
+  context do
+    variable branch: `git rev-parse --abbrev-ref HEAD`.chomp
+    
+    namespace "structure" do
+      command "tree", tags: %w[ project_structure ]
+    end
+    
+    namespace "lib" do
+      Dir['lib/**/*.rb'].each do |filename|
+        file filename, tags: 'lib'
+      end
+    end
+    
+    # ... rest of your context definition, see below for full example
+  end
+end
+```
+
+This approach can be used to dynamically generate a context when it is not
+configurable via a user context definition file, or as a fallback when users
+have not yet created such files.
+
+Afterwards you can store the context as JSON in Ruby or send it to another
+application.
+
+```ruby
+File.write 'context.json', context.to_json
+```
+
+#### From a context definition file
+
+Alternatively store the block's content above to a file `contexts/project.rb`:
 
 ```ruby
 # contexts/project.rb
@@ -41,7 +79,7 @@ context do
   variable branch: `git rev-parse --abbrev-ref HEAD`.chomp
 
   namespace "structure" do
-    command "tree lib", tags: %w[ project_structure ]
+    command "tree", tags: %w[ project_structure ]
   end
 
   namespace "lib" do
@@ -68,13 +106,12 @@ context do
 
   meta ruby: RUBY_DESCRIPTION
 
-  meta code_coverage: JSON.load_file('coverage/coverage_context.json') rescue nil
+  meta code_coverage: json('coverage/coverage_context.json')
 end
 ```
 
-### Programmatic Usage
-
-Now you can generate the context from the file, and store it as JSON in Ruby.
+Now you can generate the context from the file, and store it as JSON in Ruby or
+send it to another application.
 
 ```ruby
 context = ContextSpook::generate_context('contexts/project.rb')
@@ -129,11 +166,13 @@ assistants understand:
       "content": "...",
       "size": 1234,
       "lines": 56,
-      "tags": ["lib"]
+      "tags": [
+        "lib"
+      ]
     }
   },
   "commands": {
-    "tree lib": {
+    "tree": {
       "namespace": "structure",
       "output": "lib\n├── context_spook\n│   └── generator.rb\n└── context_spook.rb\n\n2 directories, 3 files",
       "exit_code": 0,
@@ -142,7 +181,7 @@ assistants understand:
   },
   "metadata": {
     "ruby": "ruby 3.1.0 ...",
-    "code_coverage": { ... }
+    "code_coverage": {}
   },
   "variables": {
     "branch": "main"

data/Rakefile

@@ -29,6 +29,7 @@ GemHadar do
   dependency 'tins',           '~>1.39'
   dependency 'json',           '~>2.0'
   dependency 'term-ansicolor', '~> 1.11'
+  dependency  'mize',          '~> 0.6'
   development_dependency 'all_images',            '~> 0.6'
   development_dependency 'rspec',                 '~> 3.2'
   development_dependency 'debug'

data/bin/context_spook

@@ -4,8 +4,4 @@ require 'context_spook'
 
 filename = ARGV.shift or fail 'require context definition file as first argument'
 context_json = ContextSpook.generate_context(filename).to_json
-context_json_size = Tins::Unit.format(
-  context_json.size, format: '%.2f %U', unit: ?b, prefix: 1024
-)
-STDERR.puts "Now outputting #{context_json_size} of JSON context in total."
 puts context_json

data/context_spook.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: context_spook 0.0.1 ruby lib
+# stub: context_spook 0.2.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "context_spook".freeze
-  s.version = "0.0.1".freeze
+  s.version = "0.2.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/version.rb".freeze]
-  s.files = ["Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "bin/context_spook".freeze, "context_spook.gemspec".freeze, "contexts/project.rb".freeze, "lib/context_spook.rb".freeze, "lib/context_spook/generator.rb".freeze, "lib/context_spook/version.rb".freeze, "spec/context_spook/generator_spec.rb".freeze, "spec/spec_helper.rb".freeze]
+  s.files = ["Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "bin/context_spook".freeze, "context_spook.gemspec".freeze, "contexts/project.rb".freeze, "hello_world.json".freeze, "lib/context_spook.rb".freeze, "lib/context_spook/generator.rb".freeze, "lib/context_spook/version.rb".freeze, "spec/context_spook/generator_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]
@@ -32,4 +32,5 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency(%q<tins>.freeze, ["~> 1.39".freeze])
   s.add_runtime_dependency(%q<json>.freeze, ["~> 2.0".freeze])
   s.add_runtime_dependency(%q<term-ansicolor>.freeze, ["~> 1.11".freeze])
+  s.add_runtime_dependency(%q<mize>.freeze, ["~> 0.6".freeze])
 end

data/contexts/project.rb

@@ -2,7 +2,7 @@ context do
   variable branch: `git rev-parse --abbrev-ref HEAD`.chomp
 
   namespace "structure" do
-    command "tree lib", tags: %w[ project_structure ]
+    command "tree", tags: %w[ project_structure ]
   end
 
   namespace "lib" do
@@ -35,5 +35,9 @@ context do
 
   meta ruby: RUBY_DESCRIPTION
 
-  meta code_coverage: JSON.load_file('coverage/coverage_context.json') rescue nil
+  meta hello_world: json('hello_world.json')
+
+  meta nixda_json: json('nixda_json.json')
+
+  meta code_coverage: json('coverage/coverage_context.json')
 end

data/hello_world.json

@@ -0,0 +1,3 @@
+{
+  "hello": "world"
+}

data/lib/context_spook/generator.rb

@@ -1,7 +1,7 @@
 require 'tins/xt'
 require 'term/ansicolor'
 require 'json'
-
+require 'mize'
 
 # The ContextSpook module serves as a namespace container for collecting and
 # organizing project information for AI assistance.
@@ -19,8 +19,16 @@ module ContextSpook
   #
   # @return [ ContextSpook::Generator::Context ] the context object generated
   # from the file contents
-  def self.generate_context(filename)
-    Generator.send(:new).send(:parse, File.read(filename)).context
+  def self.generate_context(filename = nil, &block)
+    filename.present? ^ block or
+      raise ArgumentError, 'need either a filename or a &block argument'
+    generator = if filename
+                Generator.send(:new).send(:parse, File.read(filename))
+                else
+                  Generator.send(:new, &block)
+                end
+    generator.output_context_size
+    generator.context
   end
 
   # The Generator class provides a DSL parser that interprets context
@@ -52,6 +60,20 @@ module ContextSpook
       end
     end
 
+    # The output_context_size method prints the total size of the generated
+    # context JSON representation.
+    #
+    # This method calculates the size of the context object when serialized to
+    # JSON, formats it using binary units (KiB, MiB, etc.), and outputs the
+    # result to standard error.
+    def output_context_size
+      context_size = @context&.size.to_i
+      json_content_size = Tins::Unit.format(
+        context_size, format: '%.2f %U', unit: ?b, prefix: 1024
+      )
+      STDERR.puts "Built #{json_content_size} of JSON context in total."
+    end
+
     # The Context class represents and manages project context data, providing
     # structured storage for file contents, command outputs, variables, and
     # metadata that can be serialized to JSON for AI assistance.
@@ -117,6 +139,29 @@ module ContextSpook
         nil
       end
 
+      # The json method reads and parses a JSON file, returning the parsed data
+      # structure.
+      #
+      # This method attempts to load a JSON file from the specified path and
+      # returns the resulting Ruby data structure. It provides verbose output
+      # about the file size when successfully reading the file. In case of file
+      # not found errors, it outputs a colored warning message to standard
+      # error and returns nil.
+      #
+      # @param filename [ String ] the path to the JSON file to be read and parsed
+      #
+      # @return [ Object, nil ] the parsed JSON data structure or nil if the file cannot be read
+      def json(filename)
+        file_size = Tins::Unit.format(
+          File.size(filename), format: '%.2f %U', unit: ?b, prefix: 1024
+        )
+        STDERR.puts "Read #{filename.inspect} as JSON (%s) for context." % file_size
+        JSON.load_file(filename)
+      rescue Errno::ENOENT => e
+        STDERR.puts color(208) { "Reading #{filename.inspect} as JSON caused #{e.class}: #{e}" }
+        nil
+      end
+
       # The files method sets up a DSL accessor for providing files.
       #
       # @param default [ Hash ] the default files hash
@@ -191,6 +236,7 @@ module ContextSpook
       # The to_json method converts the object to a JSON representation by
       # first generating its hash form and then serializing that hash into JSON
       # format.
+      memoize method:
       def to_json(*)
         as_json.to_json(*)
       end
@@ -207,6 +253,19 @@ module ContextSpook
           variables:
         }
       end
+
+      # The size method calculates and returns the byte size of the JSON
+      # representation of the context.
+      #
+      # This method determines the size in bytes of the JSON-serialized version
+      # of the context object, which is useful for understanding the total data
+      # payload being sent to an AI assistant.
+      #
+      # @return [ Integer ] the size in bytes of the JSON representation of the
+      # context
+      def size
+        to_json.size
+      end
     end
 
     private

data/lib/context_spook/version.rb

@@ -1,6 +1,6 @@
 module ContextSpook
   # ContextSpook version
-  VERSION         = '0.0.1'
+  VERSION         = '0.2.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

@@ -5,19 +5,46 @@ describe ContextSpook::Generator do
     ContextSpook.generate_context('contexts/project.rb')
   end
 
-  it 'context can be generated' do
+  it 'context can be generated from block' do
+    expect_any_instance_of(described_class).to\
+      receive(:output_context_size).and_call_original
+    context = ContextSpook.generate_context do
+      context do
+        variable foo: 'bar'
+        metadata version: '1.0'
+      end
+    end
+    expect(context).to be_a described_class::Context
+    expect(context.variables[:foo]).to eq 'bar'
+    expect(context.metadata[:version]).to eq '1.0'
+  end
+
+  it 'context can be generated from filename' do
+    expect_any_instance_of(described_class).to\
+      receive(:output_context_size).and_call_original
     expect(context).to be_a described_class::Context
     expect(context.metadata[:ruby]).to eq RUBY_DESCRIPTION
   end
 
+  it 'could handle premature output_context_size calls' do
+    expect_any_instance_of(described_class).to\
+      receive(:output_context_size).and_call_original
+    described_class.send(:new).output_context_size
+  end
+
+  it 'cannot do from block and filename' do
+    expect {
+      ContextSpook.generate_context('contexts/project.rb') { }
+    }.to raise_error(ArgumentError, /need either a filename or a &block/)
+  end
+
   it 'context be transformed to JSON if loaded' do
     context_as_json = context.to_json
-    expect(context_as_json.size).to be > 1024
+    expect(context.size).to be > 1024
     expect(JSON(context_as_json)).to be_a Hash
   end
 
   describe 'Context' do
-
     it 'can have variables' do
       expect(context.variables[:branch]).to be_present
     end
@@ -33,7 +60,7 @@ describe ContextSpook::Generator do
     end
 
     it 'can have commands' do
-      command = context.commands['tree lib']
+      command = context.commands['tree']
       expect(command).to be_present
       expect(command[:working_directory]).to eq Dir.pwd
       expect(command[:exit_code]).to be_present

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: context_spook
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Florian Frank
@@ -121,6 +121,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: mize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
 description: |
   context_spook is a library that collects and organizes project
   information to help AI assistants understand codebases better.
@@ -141,6 +155,7 @@ files:
 - bin/context_spook
 - context_spook.gemspec
 - contexts/project.rb
+- hello_world.json
 - lib/context_spook.rb
 - lib/context_spook/generator.rb
 - lib/context_spook/version.rb