context_spook 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acac1bb23044efca6b50d929dfeda70b409cb95fc81f2a18f269d67ca2fb857d
-  data.tar.gz: 80c69f95ab2f595daf33eb5646d0cc0133c0752ea74ac73b4737eb0b2f57cd32
+  metadata.gz: e70334ee77b21283268eaabfc74ea73593a375119003d74be68442188f4dbf5b
+  data.tar.gz: cc7ca13e3a403a97f16c897a797d0b2a4a92bba1b8e3da99adb199f807169b1c
 SHA512:
-  metadata.gz: c68f160740a7b1af14ce1f6260fd08430745e7f338e4151c88a46da708d8635572471400600ad119fcfdd9c33d7f9944ec9fe5ca8710778d61f919403de8c38d
-  data.tar.gz: 20a6c25fc8097d67d6b4111b4d6fd6c15b5ad12512e05b93e68d27f32ca8adb58d9f20255a30b9dfcb679b2c4e89a4108eaaa37fc2388153243ae6812f33b4f7
+  metadata.gz: db73acce9ba9aa696619be04671adde77a115d63b2e2c48d559848cc3d02c608579982a29da2bba7bd70bda7a5fae5654828c6ad1f763e2b04094e47820c98e0
+  data.tar.gz: f95575da363d9c70d5f9303ce66bc13d8c2bb2e4c70c7c6074fe3c61f1bf35554dbfc68f286bf2eac2d4080fe39291ad4b1f2ce9ca0910560e2a4b86f5eb6154

data/.contexts/project.rb

@@ -5,6 +5,12 @@ context do
     command "tree", tags: %w[ project_structure ]
   end
 
+  namespace "bin" do
+    Dir['bin/**/*'].each do |filename|
+      file filename, tags: 'bin'
+    end
+  end
+
   namespace "lib" do
     Dir['lib/**/*.rb'].each do |filename|
       file filename, tags: 'lib'
@@ -39,5 +45,9 @@ context do
 
   meta nixda_json: json('nixda_json.json')
 
+  meta hey_world: yaml('hey_world.yaml')
+
+  meta nixda_yaml: yaml('nixda_yaml.yaml')
+
   meta code_coverage: json('coverage/coverage_context.json')
 end

data/README.md

@@ -12,6 +12,10 @@ information. The `.contexts/project.rb` example below demonstrates how to
 describe a Ruby project, but the same principles apply across many different
 domains.
 
+## Documentation
+
+Complete API documentation is available at: [GitHub.io](https://flori.github.io/context_spook/)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -128,13 +132,35 @@ Generate context and save to file:
 
 Or pipe directly to another tool:
 
-```
+```bash
 ./bin/context_spook .contexts/project.rb | ollama_chat_send
 ```
 
-You will see two orange warning messages, that demonstrates how errors like
+
+The CLI tool also supports verbose output:
+
+```bash
+# Generate context with verbose output
+./bin/context_spook .contexts/project.rb -v
+```
+
+Now you can see two orange warning messages, that demonstrates how errors like
 missing files or commands with failing exit codes are handled.
 
+The CLI tool also supports file redirection:
+
+```bash
+# Generate context and save to file
+./bin/context_spook .contexts/project.rb -o context.json
+```
+
+This is how you can show the usage message:
+
+```
+# Show help
+./bin/context_spook -h
+```
+
 ## What Gets Collected
 
 The DSL collects various types of project information:

data/Rakefile

@@ -9,7 +9,6 @@ GemHadar do
   email       'flori@ping.de'
   homepage    "https://github.com/flori/context_spook"
   summary     "#{name} collects project context for AI"
-  executables 'context_spook'
 
   description <<~EOT
     #{name} is a library that collects and organizes project
@@ -24,6 +23,12 @@ GemHadar do
      '.rspec', '.github'
   readme      'README.md'
 
+  executables 'context_spook'
+
+  github_workflows(
+    'static.yml' => {}
+  )
+
   required_ruby_version  '~> 3.1'
 
   dependency 'tins',           '~>1.39'
@@ -31,6 +36,7 @@ GemHadar do
   dependency 'term-ansicolor', '~> 1.11'
   dependency 'mize',           '~> 0.6'
   dependency 'mime-types',     '~> 3.0'
+  dependency 'yaml',           '~> 0.4'
   development_dependency 'all_images', '~> 0.6'
   development_dependency 'rspec',      '~> 3.2'
   development_dependency 'debug'

data/bin/context_spook

@@ -1,7 +1,57 @@
 #!/usr/bin/env ruby
 
 require 'context_spook'
+require 'tins/go'
+include Tins::GO
+require 'json'
 
-filename = ARGV.shift or fail 'require context definition file as first argument'
-context_json = ContextSpook.generate_context(filename).to_json
-puts context_json
+# The usage method displays the command-line interface help text and example
+# usage patterns for the ContextSpook tool.
+#
+# This method outputs a formatted help message that includes the tool's usage
+# syntax, available options, and practical examples.
+#
+# @see ContextSpook::generate_context
+# @see ContextSpook::Generator
+# @see ContextSpook::Generator::Context
+def usage
+  puts <<~EOT
+
+  Usage: #{File.basename($0)} [options] <context_definition_file>
+
+  Options:
+    -o FILE    Write output to FILE instead of stdout
+    -v         Verbose output
+    -h         Show this help message
+
+  Examples:
+    # Generate context and output to stdout
+    #{File.basename($0)} .contexts/project.rb
+
+    # Generate context and save to file
+    #{File.basename($0)} .contexts/project.rb -o context.json
+
+    # Generate context with verbose output
+    #{File.basename($0)} .contexts/project.rb -v
+
+    # Generate context and pipe to another tool
+    #{File.basename($0)} .contexts/project.rb | ollama_chat_send
+
+  EOT
+  exit 0
+end
+
+opts     = go 'o:pvh'
+opts[?h] and usage
+filename = ARGV.shift or fail 'require context definition file as an argument'
+output   = nil
+context  = ContextSpook.generate_context(filename, verbose: opts[?v])
+if output_filename = opts[?o]
+  if File.exist?(output_filename)
+    fail "Filename #{output_filename.inspect} already exists!"
+  end
+  output = File.new output_filename, ?w
+else
+  output = STDOUT
+end
+JSON.dump(context.as_json, output)

data/context_spook.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: context_spook 0.4.0 ruby lib
+# stub: context_spook 0.6.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "context_spook".freeze
-  s.version = "0.4.0".freeze
+  s.version = "0.6.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -13,18 +13,18 @@ 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 = [".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, "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 = [".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/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]
   s.required_ruby_version = Gem::Requirement.new("~> 3.1".freeze)
-  s.rubygems_version = "3.6.9".freeze
+  s.rubygems_version = "3.7.2".freeze
   s.summary = "context_spook collects project context for AI".freeze
   s.test_files = ["spec/context_spook/generator_spec.rb".freeze, "spec/spec_helper.rb".freeze]
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 2.2".freeze])
+  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 2.8".freeze])
   s.add_development_dependency(%q<all_images>.freeze, ["~> 0.6".freeze])
   s.add_development_dependency(%q<rspec>.freeze, ["~> 3.2".freeze])
   s.add_development_dependency(%q<debug>.freeze, [">= 0".freeze])
@@ -34,4 +34,5 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency(%q<term-ansicolor>.freeze, ["~> 1.11".freeze])
   s.add_runtime_dependency(%q<mize>.freeze, ["~> 0.6".freeze])
   s.add_runtime_dependency(%q<mime-types>.freeze, ["~> 3.0".freeze])
+  s.add_runtime_dependency(%q<yaml>.freeze, ["~> 0.4".freeze])
 end

data/hey_world.yaml

@@ -0,0 +1,2 @@
+---
+hey: world

data/lib/context_spook/generator.rb

@@ -3,30 +3,66 @@ require 'term/ansicolor'
 require 'json'
 require 'mize'
 require 'mime-types'
+require 'yaml'
 
 # The ContextSpook module serves as a namespace container for collecting and
 # organizing project information for AI assistance.
 module ContextSpook
   include DSLKit::Interpreter
 
-  # The generate_context method processes a context definition file and returns
-  # the resulting context object.
+  # The VerbosePuts module provides a conditional output mechanism for
+  # displaying status or debug messages.
   #
-  # This method reads the content of a specified file, parses it using the
-  # generator's parsing mechanism, and extracts the configured context from the
-  # parsed result.
+  # This module includes a method that outputs messages to standard error only
+  # when a verbose flag is enabled. It is designed to be included in classes
+  # that need to conditionally emit verbose logging information during
+  # processing.
+  module VerbosePuts
+    # The verbose_puts method outputs the given arguments to standard error
+    # only if verbose mode is enabled.
+    #
+    # This method serves as a conditional output mechanism, allowing debug or
+    # status messages to be displayed based on the verbosity setting of the
+    # object.
+    #
+    # @param a [ Array ] the arguments to be printed to standard error
+    #
+    # @return [ nil ] always returns nil after attempting to output
+    def verbose_puts(*a)
+      @verbose and return
+      STDERR.puts(a)
+    end
+  end
+
+  # The generate_context method processes a context definition file or block
+  # and returns the resulting context object.
   #
-  # @param filename [ String ] the path to the context definition file to be processed
+  # 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.
+  #
+  # @param filename [ String, nil ] the path to the context definition file to
+  #   be processed
+  # @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
   #
   # @return [ ContextSpook::Generator::Context ] the context object generated
-  # from the file contents
-  def self.generate_context(filename = nil, &block)
+  #   from the file contents or block
+  #
+  # @raise [ ArgumentError ] if neither a filename nor a block is provided
+  # @raise [ ArgumentError ] if both a filename and a block are provided
+  def self.generate_context(filename = nil, verbose: false, &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))
+                Generator.send(:new, verbose:).send(:parse, File.read(filename))
                 else
-                  Generator.send(:new, &block)
+                  Generator.send(:new, verbose:, &block)
                 end
     generator.output_context_size
     generator.context
@@ -37,13 +73,19 @@ module ContextSpook
   # project metadata, file contents, command outputs, and variables for AI
   # assistance.
   class Generator
+    include VerbosePuts
+
     private_class_method :new
 
-    # The initialize method sets up the object by evaluating the provided block in the object's context.
+    # The initialize method sets up the object by evaluating the provided block
+    # in the object's context.
     #
-    # @param block [ Proc ] A block of code to be evaluated within the object's context.
+    # @param verbose [ TrueClass, FalseClass ] flag to enable verbose
+    #   output during processing, defaults to lfalse.
+    # @param block [ Proc ] a block of code to be evaluated within the object's context
     #                       If no block is given, the method does nothing.
-    def initialize(&block)
+    def initialize(verbose: false, &block)
+      @verbose = !!verbose
       block and instance_eval(&block)
     end
 
@@ -55,7 +97,7 @@ module ContextSpook
     def context(&block)
       if block
         @context and raise ArgumentError, "only one context allowed"
-        @context = Context.new(&block)
+        @context = Context.new(verbose: @verbose, &block)
       else
         @context
       end
@@ -72,22 +114,27 @@ module ContextSpook
       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."
+      verbose_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.
     class Context
+      include VerbosePuts
       include Tins::Scope
       include Tins::DSLAccessor
       include Term::ANSIColor
 
-      # The initialize method sets up the object by evaluating a block in the
-      # object's context.
+      # The initialize method sets up the object by evaluating the provided block
+      # in the object's context.
       #
-      # @param block [ Proc ] A block to be evaluated within the object's context.
-      def initialize(&block)
+      # @param verbose [ TrueClass, FalseClass ] flag to enable verbose output
+      #   during processing, defaults to false.
+      # @param block [ Proc ] a block of code to be evaluated within the object's context
+      #                       If no block is given, the method does nothing.
+      def initialize(verbose: false, &block)
+        @verbose = !!verbose
         block and instance_eval(&block)
       end
 
@@ -156,10 +203,34 @@ module ContextSpook
         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
+        verbose_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}" }
+      rescue Errno::ENOENT, JSON::ParserError => e
+        verbose_puts color(208) { "Reading #{filename.inspect} as JSON caused #{e.class}: #{e}" }
+        nil
+      end
+
+      # The yaml method reads and parses a YAML file, returning the resulting
+      # data structure.
+      #
+      # This method attempts to load a YAML 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 or YAML syntax errors, it outputs a colored warning
+      # message to standard error and returns nil.
+      #
+      # @param filename [ String ] the path to the YAML file to be read and parsed
+      #
+      # @return [ Object, nil ] the parsed YAML data structure or nil if the
+      #   file cannot be read
+      def yaml(filename)
+        file_size = Tins::Unit.format(
+          File.size(filename), format: '%.2f %U', unit: ?b, prefix: 1024
+        )
+        verbose_puts "Read #{filename.inspect} as YAML (%s) for context." % file_size
+        YAML.load_file(filename)
+      rescue Errno::ENOENT, Psych::SyntaxError => e
+        verbose_puts color(208) { "Reading #{filename.inspect} as YAML caused #{e.class}: #{e}" }
         nil
       end
 
@@ -193,10 +264,10 @@ module ContextSpook
         file_size = Tins::Unit.format(
           content.size, format: '%.2f %U', unit: ?b, prefix: 1024
         )
-        STDERR.puts "Read #{filename.inspect} (%s) for context." % file_size
+        verbose_puts "Read #{filename.inspect} (%s) for context." % file_size
         nil
       rescue Errno::ENOENT => e
-        STDERR.puts color(208) { "Reading #{filename.inspect} caused #{e.class}: #{e}" }
+        verbose_puts color(208) { "Reading #{filename.inspect} caused #{e.class}: #{e}" }
       end
 
       # The commands method sets up a DSL accessor for provided command outputs.
@@ -219,7 +290,9 @@ module ContextSpook
         output = `#{shell_command}`
         exit_code = $?&.exitstatus.to_i
         if exit_code != 0
-          STDERR.puts color(208) { "Executing #{shell_command.inspect} resulted in exit code #{exit_code}." }
+          verbose_puts color(208) {
+            "Executing #{shell_command.inspect} resulted in exit code #{exit_code}."
+          }
         end
         commands[shell_command] = {
           namespace: scope_top,
@@ -231,7 +304,7 @@ module ContextSpook
         output_size = Tins::Unit.format(
           output.size, format: '%.2f %U', unit: ?b, prefix: 1024
         )
-        STDERR.puts "Executed #{shell_command.inspect} with output (%s) for context." % output_size
+        verbose_puts "Executed #{shell_command.inspect} with output (%s) for context." % output_size
         nil
       end
 

data/lib/context_spook/version.rb

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

@@ -2,7 +2,7 @@ require 'spec_helper'
 
 describe ContextSpook::Generator do
   let :context do
-    ContextSpook.generate_context('.contexts/project.rb')
+    ContextSpook.generate_context('.contexts/project.rb', verbose: true)
   end
 
   it 'context can be generated from block' do
@@ -64,7 +64,7 @@ describe ContextSpook::Generator do
       command = context.commands['tree']
       expect(command).to be_present
       expect(command[:working_directory]).to eq Dir.pwd
-      expect(command[:exit_code]).to be_present
+      expect(command[:exit_code]).not_to be_nil
       if command[:exit_code] == 0
         expect(command[:output]).to be_present
       else
@@ -76,5 +76,37 @@ describe ContextSpook::Generator do
     it 'can have metada' do
       expect(context.metadata[:ruby]).to eq RUBY_DESCRIPTION
     end
+
+    it 'can have json metadata' do
+      expect(context.metadata[:hello_world]).to eq("hello" => "world")
+    end
+
+    it 'can have yaml metadata' do
+      expect(context.metadata[:hey_world]).to eq("hey" => "world")
+    end
+
+    it 'handles missing json files gracefully' do
+      expect(context.json('nixda.json')).to be_nil
+    end
+
+    it 'handles invalid json content gracefully' do
+      Tempfile.create('invalid.json') do |f|
+        f.write('{ invalid json }')
+        f.close
+        expect(context.json(f.path)).to be_nil
+      end
+    end
+
+    it 'handles missing yaml files gracefully' do
+      expect(context.yaml('nixda.yaml')).to be_nil
+    end
+
+    it 'handles invalid yaml content gracefully' do
+      Tempfile.create('invalid.yaml') do |f|
+        f.write('invalid: [yaml')
+        f.close
+        expect(context.yaml(f.path)).to be_nil
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: context_spook
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Florian Frank
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: '2.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: '2.8'
 - !ruby/object:Gem::Dependency
   name: all_images
   requirement: !ruby/object:Gem::Requirement
@@ -149,6 +149,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yaml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
 description: |
   context_spook is a library that collects and organizes project
   information to help AI assistants understand codebases better.
@@ -170,6 +184,7 @@ files:
 - bin/context_spook
 - context_spook.gemspec
 - hello_world.json
+- hey_world.yaml
 - lib/context_spook.rb
 - lib/context_spook/generator.rb
 - lib/context_spook/version.rb
@@ -197,7 +212,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: context_spook collects project context for AI
 test_files: