documented 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5026a405923100cfe8ea3f484fe324b3588a3481369fd954b7d5645537227672
-  data.tar.gz: b9d86b71d1a7dfc1018edc79922a54fd2013245d95c17eb9d902d5dd8160f100
+  metadata.gz: eed131baa88c812dcc5e2d7539e11a422b40903854ab07f20ee594979537e87b
+  data.tar.gz: 4222dd37097a675c37304d4a539bfe3d92c563e3aeb97732ce47246d6bc0f7e3
 SHA512:
-  metadata.gz: 55480519881df342fcbff4d0b7ea3b7aef9a6ca96805c3eb18283faf3f43b3e83d8e3df00219310e75293123fd801993848630a7c446626407812b745ae6c896
-  data.tar.gz: 994c10ccf460e023790c8caaa4198f5bf63f06b41b6ebebefc604b1752af27f1d4610d3f62297f08f0e124f62d7a1786af8ad16e2e9e8e5e31d1bb86db269df4
+  metadata.gz: da326d596f66a75475b00be099299b04f997fa88077811f361b3b1e2228b9c0ec79a51f7f7df25f66282fa6cd6d21b466845a29c80c30c86831b1b3a5e4e10aa
+  data.tar.gz: 16fe5d6fc344069bf61423b569472332ec4eef9e81374688630887480423321afac84832b3daa6981827b15d177a5eca6a24ef9248b8eaecf165b60d912a1f04

data/bin/documented

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+require lib_path = File.expand_path('../lib/documented')
+require '../lib/rewriter'
+
+################################################################################
+# Usage:
+#   documented <file_path>
+#
+# Example:
+#   documented spec/example_spec.rb
+################################################################################
+
+file_path = File.join(Dir.pwd, ARGV.first)
+
+rewriter = Documented::Rewriter.new(file_path)
+rewriter.require_library(lib_path)
+rewriter.replace_comments
+rewriter.write
+rewriter.execute
+rewriter.delete

data/lib/config.rb

@@ -2,12 +2,14 @@ module Documented
   class Config
     attr_accessor :blocklist
     attr_accessor :duplicates
-    attr_accessor :project_path
+    attr_accessor :app_path
+    attr_accessor :gem_path
     attr_accessor :output_directory
 
     def initialize()
       @blocklist = [
         '#<Class:Bundler',
+        '#<Class:Documented>',
         '#<Class:#<Class',
         '#<Class:0x0000',
         '#<Class:Cucumber',
@@ -22,6 +24,7 @@ module Documented
         'Bundler',
         'Cucumber',
         'Datadog',
+        'Documented',
         'Float',
         'Helpers',
         'Integer',
@@ -36,10 +39,11 @@ module Documented
         'URI::Generic',
       ]
 
-      # An absolute path to the project root directory. Defaults to current execution path.
-      @project_path = Dir.pwd
+      @duplicates = false
+
+      @app_path = Dir.pwd
+      @gem_path = File.dirname(File.realpath(__FILE__))
 
-      # Name of output directory.
       @output_directory = "documented"
     end
   end

data/lib/documented.rb

@@ -1,82 +1,49 @@
-require 'set'
-require 'erb'
-
-require_relative 'accessor'
-require_relative 'config'
-require_relative 'renderer'
+require_relative './config'
+require_relative './tracer'
+require_relative './renderer'
 
 module Documented
-  def documented
-    events = []
-    calls = ['Start']
-  
-    trace = TracePoint.new(:call, :return) do |tp|
-      # file = File.open("#{__dir__}/../../doc/diagrams/input.mmd")
-      # file.write("sequenceDiagram\n")
-  
-      # file.close
-      caller = calls.last.to_s
-      callee = tp.defined_class.to_s
-      event = tp.event
-  
-      unless blocklist.any? { |e| callee.to_s.start_with? e }
-        unless calls.last == callee
-          if event == :return
-            calls.pop
-          elsif calls.last != callee
-            calls << callee
-          end
-        end
-  
-        unless callee == caller
-          caller = caller.gsub('::','.')
-          callee = callee.gsub('::','.')
-          p "#{caller}->>#{callee}: #{tp.method_id}"
-        end
-      end
+  class << self
+    def setup(file_path)
+      @@file_path = file_path
+      @@config = Config.new
+      @@tracer = Tracer.new(@@config.blocklist)
+
+      output_path = File.join(@@config.app_path, @@config.output_directory)
+      Dir.mkdir(output_path) unless Dir.exist? output_path
+      @@renderer = Renderer.new(@@config.gem_path, output_path)
+
+      @@sequences = []
     end
-  
-    trace.enable
-  
-    yield
-  
-    trace.disable
-  
-    ap events
-  end
 
-  def self.configure
-    documented_setup_class()
+    def enable
+      @@tracer.enable 
+    end
 
-    yield(@@documented.config)
-  end
+    def disable
+      @@tracer.disable
+      @@renderer.render(@@file_path)
+    end
 
-  def self.included(base)
-    documented_setup_class()
-  end
+    def sequences
+      @@sequences
+    end
 
-  private
+    def add_sequence(sequence)
+      @@sequences << sequence
+    end
 
-  ##
-  # Setup class.
-  #
-  # @paths
-  #   - package_path [String] Absolute path to the library itself.
-  #   - project_path [String] Absolute path to the project root.
-  #   - output_path [String] Absolute path to the documented directory.
-  ##
-  def self.documented_setup_class()
-    @@documented = Accessor.new()
-    @@documented.config = Config.new()
+    def config
+      @@config
+    end
 
-    # Setup paths.
-    @@documented.package_path = File.dirname(File.realpath(__FILE__))
-    @@documented.project_path = @@documented.config.project_path
-    @@documented.output_path = File.join(@@documented.project_path, @@documented.config.output_directory)
-    unless Dir.exist? @@documented.output_path
-      Dir.mkdir(@@documented.output_path)
+    def tracer
+      @@tracer
     end
 
-    @@documented.renderer = Renderer.new(@@documented.package_path, @@documented.output_path)
+    # Allow end-user to override config.
+    def configure
+      yield(@@config)
+    end
   end
 end

data/lib/renderer.rb

@@ -1,26 +1,33 @@
 module Documented
   class Renderer
-    def initialize(package_path, output_path)
-      @package_path = package_path
+    def initialize(gem_path, output_path)
+      @gem_path = gem_path
       @output_path = output_path
     end
 
-    # Place files in output path.
-    def render()
-      filenames = [
-        "README.md",
-      ]
+    def render(file_path)
+      # file_names = [
+      #   "README.md",
+      # ]
+      # file_names.each do |file_name|
+      #   file = File.read(File.join(@gem_path, "output", file_name))
+      #   File.open(File.join(@output_path, file_name), 'w+') do |f|
+      #     f.write file
+      #   end
+      # end
 
-      filenames.each do |filename|
-        file = File.read(File.join(@package_path, "output", filename))
-        File.open(File.join(@output_path, filename), 'w+') do |f|
-          f.write file
-        end
-      end
+      Documented.sequences.each do |sequence|
+        file_name = File.basename(file_path, File.extname(file_path)) + '.md'
+        directory = File.join(@output_path, file_name)
+
+        output = <<~TEXT
+          ```mermaid
+          sequenceDiagram;
+          #{sequence.map { |step| "  #{step}" }.join("\n")}
+          ````
+        TEXT
 
-      file = File.read(File.join(@package_path, "output", "gitignore.txt"))
-      File.open(File.join(@output_path, ".gitignore"), 'w+') do |f|
-        f.write file
+        File.write(directory, output)
       end
     end
   end

data/lib/rewriter.rb

@@ -0,0 +1,63 @@
+require 'rubocop'
+require_relative './config'
+
+module Documented
+  class Rewriter
+    attr_accessor :file_path
+    attr_accessor :source
+    attr_accessor :tree
+
+    def initialize(file_path)
+      @file_path = file_path
+      @source = RuboCop::ProcessedSource.new(File.read(file_path), 3)
+      @tree = Parser::Source::TreeRewriter.new(@source.buffer)
+    end
+
+    def require_library(lib_path)
+      setup = <<-RUBY
+        \n require "#{lib_path}"
+        Documented.setup("#{@file_path}")
+      RUBY
+      @tree.insert_after(@source.ast.children.first.loc.expression, setup)
+    end
+
+    def replace_comments
+      @source.comments.each do |comment|
+        range = comment.location.expression
+      
+        if comment.text.start_with?('# documented:enable')
+          @tree.replace(range, "Documented.enable")
+        elsif comment.text.start_with?('# documented:disable')
+          @tree.replace(range, "Documented.disable")
+        end
+      end
+    end
+
+    def execute
+      system("#{command(file_path)} #{temp_file_path}")
+    end
+
+    def write
+      File.write(temp_file_path, @tree.process)
+    end
+
+    def delete
+      File.delete(temp_file_path)
+    end
+
+    private
+
+    def temp_file_path
+      file_name = 'tmp-' + File.basename(@file_path)
+      directory = File.dirname(file_path)
+      File.join(directory, file_name)
+    end
+
+    def command(file_path)
+      return 'bundle exec rspec' if file_path.end_with?('_spec.rb')
+      return 'bundle exec cucumber' if file_path.end_with?('.feature')
+    
+      'ruby'
+    end
+  end
+end

data/lib/tracer.rb

@@ -0,0 +1,54 @@
+require 'set'
+require 'erb'
+
+require_relative 'config'
+require_relative 'renderer'
+
+module Documented
+  class Tracer
+    attr_reader :sequence
+
+    def initialize(blocklist)
+      @blocklist = blocklist
+      @trace_point = create_trace_point()
+    end
+
+    def enable
+      @sequence = []
+      @trace_point.enable
+    end
+    
+    def disable
+      @trace_point.disable
+      Documented.add_sequence(@sequence)
+    end
+
+    private
+
+    def create_trace_point
+      calls = ['Start']
+
+      return TracePoint.new(:call, :return) do |trace_point|
+        caller = calls.last.to_s
+        callee = trace_point.defined_class.to_s
+        event = trace_point.event
+    
+        unless @blocklist.any? { |e| callee.to_s.start_with? e }
+          unless calls.last == callee
+            if event == :return
+              calls.pop
+            elsif calls.last != callee
+              calls << callee
+            end
+          end
+    
+          unless callee == caller
+            caller = caller.gsub('::','.')
+            callee = callee.gsub('::','.')
+            @sequence << "#{caller}->>#{callee}: #{trace_point.method_id}"
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: documented
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Maedi Prichard
@@ -11,7 +11,7 @@ cert_chain: []
 date: 2023-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: parser
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -26,16 +26,17 @@ dependencies:
         version: '0'
 description: Documentation that's completely automated.
 email: maediprichard@gmail.com
-executables: []
+executables:
+- documented
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/accessor.rb
+- bin/documented
 - lib/config.rb
 - lib/documented.rb
-- lib/output/README.md
-- lib/output/gitignore.txt
 - lib/renderer.rb
+- lib/rewriter.rb
+- lib/tracer.rb
 homepage: https://github.com/greensync/documented
 licenses:
 - MPL-2.0

data/lib/accessor.rb

@@ -1,31 +0,0 @@
-################################################################################
-# Access variables via one object to avoid polluting the caller's scope.
-#
-# @pattern Singleton
-################################################################################
-
-module Documented
-  class Accessor
-    attr_accessor :initialized
-    attr_accessor :error
-
-    attr_accessor :config
-    attr_accessor :renderer
-
-    attr_accessor :package_path
-    attr_accessor :project_path
-    attr_accessor :output_path
-
-    def initialize()
-      @initialized = false
-      @error = nil
-
-      @config = nil
-      @renderer = nil
-
-      @package_path = nil
-      @project_path = nil
-      @output_path = nil
-    end
-  end
-end

data/lib/output/README.md

@@ -1,3 +0,0 @@
-# Documented
-
-As you test the application documentation will be added to `/documented`.

data/lib/output/gitignore.txt

@@ -1,2 +0,0 @@
-.gitignore
-README.md