context_spook 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f52806b7e9dbd38070ca282415d5e05df58824be37f36389e6d7d820030e864c
-  data.tar.gz: 91a2f4016d0affe3d5e0105cbd456dcc73b6a23c580b85909cfcc2190cb195ff
+  metadata.gz: bf46500652e697db299ccdfe21d5dd4c02953b699ca528b21810f87348eddceb
+  data.tar.gz: ad41e6c9f6141ba5303c845aaf26c2d141125201d82575834a62efc05c2ae7b8
 SHA512:
-  metadata.gz: 1b2facc2b87f0e3a880b45eeee25e0155baf713f461531343ce4906ce5e6f51a153789def95c4b1741b11f468db7c7d6a7698c8e6dda858f14811e6fd85255f7
-  data.tar.gz: ae47a38687a3911af559d39229ee48abaed1970abd124401d20f3bf8392c7790a765793d9ec5e25ab0c5460e7c41f1ac52f1377827e3414baf5815688fb18fb6
+  metadata.gz: edab814b82519dc36f9bb01c4e59dfb372aad6c2e1fa0d8ef7f487a288281ad6bf9bf1474d09a7ff7b818c1a6140ef08c0ba464b986e9bf56a34bd2720f9e778
+  data.tar.gz: 052e05ca7fc2825a75b43e1b9a8585344f9d4e8a6a805e3a5d826680d81bfed723d4359db7083d6451ce4afa6e35e82688a979dae0fcd0dcde401784d373b2de

data/{contexts → .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'

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'

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.3.0 ruby lib
+# stub: context_spook 0.5.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "context_spook".freeze
-  s.version = "0.3.0".freeze
+  s.version = "0.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,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 = ["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.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.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.1".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])

data/lib/context_spook/generator.rb

@@ -9,24 +9,35 @@ require 'mime-types'
 module ContextSpook
   include DSLKit::Interpreter
 
-  # The generate_context method processes a context definition file and returns
-  # the resulting context object.
+  # The generate_context method processes a context definition file or block
+  # and returns the resulting context object.
   #
-  # 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 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 ] the path to the context definition file to be processed
+  # @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
@@ -39,11 +50,15 @@ module ContextSpook
   class Generator
     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
 
@@ -72,7 +87,9 @@ 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."
+      if @verbose
+        STDERR.puts "Built #{json_content_size} of JSON context in total."
+      end
     end
 
     # The Context class represents and manages project context data, providing
@@ -156,10 +173,14 @@ 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
+        if @verbose
+          STDERR.puts "Read #{filename.inspect} as JSON (%s) for context." % file_size
+        end
         JSON.load_file(filename)
       rescue Errno::ENOENT => e
-        STDERR.puts color(208) { "Reading #{filename.inspect} as JSON caused #{e.class}: #{e}" }
+        if @verbose
+          STDERR.puts color(208) { "Reading #{filename.inspect} as JSON caused #{e.class}: #{e}" }
+        end
         nil
       end
 
@@ -193,10 +214,14 @@ 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
+        if @verbose
+          STDERR.puts "Read #{filename.inspect} (%s) for context." % file_size
+        end
         nil
       rescue Errno::ENOENT => e
-        STDERR.puts color(208) { "Reading #{filename.inspect} caused #{e.class}: #{e}" }
+        if @verbose
+          STDERR.puts color(208) { "Reading #{filename.inspect} caused #{e.class}: #{e}" }
+        end
       end
 
       # The commands method sets up a DSL accessor for provided command outputs.
@@ -219,7 +244,11 @@ 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}." }
+          if @verbose
+            STDERR.puts color(208) {
+              "Executing #{shell_command.inspect} resulted in exit code #{exit_code}."
+            }
+          end
         end
         commands[shell_command] = {
           namespace: scope_top,
@@ -231,23 +260,28 @@ 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
+        if @verbose
+          STDERR.puts "Executed #{shell_command.inspect} with output (%s) for context." % output_size
+        end
         nil
       end
 
       # 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.
+      #
+      # @param args [ Array ] pass-through arguments
       memoize method:
-      def to_json(*)
-        as_json.to_json(*)
+      def to_json(*args)
+        as_json.to_json(*args)
       end
 
       # The as_json method converts the context's files, commands, and metadata
       # into a hash representation.
       #
+      # @param ignored [ Array ] ignored arguments
       # @return [ Hash ] a hash containing the files, commands, and metadata
-      def as_json(*)
+      def as_json(*ignored)
         {
           files:,
           commands:,

data/lib/context_spook/version.rb

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

@@ -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')
   end
 
   it 'context can be generated from block' do
@@ -34,7 +34,7 @@ describe ContextSpook::Generator do
 
   it 'cannot do from block and filename' do
     expect {
-      ContextSpook.generate_context('contexts/project.rb') { }
+      ContextSpook.generate_context('.contexts/project.rb') { }
     }.to raise_error(ArgumentError, /need either a filename or a &block/)
   end
 
@@ -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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: context_spook
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Florian Frank
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.8'
 - !ruby/object:Gem::Dependency
   name: all_images
   requirement: !ruby/object:Gem::Requirement
@@ -162,13 +162,13 @@ extra_rdoc_files:
 - lib/context_spook/generator.rb
 - lib/context_spook/version.rb
 files:
+- ".contexts/project.rb"
 - Gemfile
 - LICENSE
 - README.md
 - Rakefile
 - bin/context_spook
 - context_spook.gemspec
-- contexts/project.rb
 - hello_world.json
 - lib/context_spook.rb
 - lib/context_spook/generator.rb
@@ -197,7 +197,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: