decode 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ee41a6017a7689ecfe8e5d45060f099389f42adef8881dbcc83c379ea0283a0
-  data.tar.gz: 381f84c1f1ae15d9486c07ac9f58f694169157200ad44c34e3ba5e2006de32d5
+  metadata.gz: a6e020e7ce8808abe27ac191ff49baa00f384634d9277c94b6c2cde64a5751c2
+  data.tar.gz: f0d8aa8a53d32c81be30df5d23eaa6acc97018c07cab16e82bf44f2f0d9990fd
 SHA512:
-  metadata.gz: c1b8322f13b93c5e0e6a64772b57e4dfb2eb6d8682404c69edfb233dc76bdaa795d3b9dfde2567f3240409041116e284790645583e32c9fecf6b0a9a5ea17d18
-  data.tar.gz: b4c8ab5a9b990107069fb618cc4bc2e64267372c639dc8d42c3de48f5ddb0543b5451e86b58ad016f649298ae84977518a77a7b9c008dc1e0a5974cf70bf4043
+  metadata.gz: 9dd39e23835a40d32280c75d3f28ebdc3d944224399d7c0844255ac0b46de31a89c151502361c0852becae448a8cb8b9b9b1f3a1a56489e1c0bbba73a01c774e
+  data.tar.gz: cb017f4cc34c7ee444432ba5746d97bbd4fc3791130e0bdbe3ef7eb8dc0a5b26126b1356d007910daae85c6f2f86e3da3d74ff1e9d9c91ee365b313fba834ba0

data/README.md

@@ -2,6 +2,10 @@
 
 A Ruby code analysis tool and documentation generator.
 
+## Usage
+
+Please see the documentation wiki.
+
 ## Contributing
 
 1. Fork it

data/decode.gemspec

@@ -22,10 +22,10 @@ Gem::Specification.new do |spec|
 	spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
 	spec.require_paths = ["lib"]
 	
-	spec.add_dependency 'build-files'
+	spec.add_dependency "parser"
 	
+	spec.add_development_dependency 'build-files'
 	spec.add_development_dependency 'bake-bundler'
-	
 	spec.add_development_dependency 'utopia-wiki'
 	spec.add_development_dependency 'covered'
 	spec.add_development_dependency 'bundler'

data/gems.locked

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    decode (0.1.0)
-      build-files
+    decode (0.2.0)
+      parser
 
 GEM
   remote: https://rubygems.org/
@@ -159,6 +159,7 @@ PLATFORMS
 
 DEPENDENCIES
   bake-bundler
+  build-files
   bundler
   covered
   decode!

data/lib/decode/documentation.rb

@@ -0,0 +1,77 @@
+# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+module Decode
+	class Documentation
+		def initialize(comments)
+			@comments = comments
+		end
+		
+		DESCRIPTION = /\A\s*([^@\s].*)?\z/
+		
+		def description
+			return to_enum(:description) unless block_given?
+			
+			# We track empty lines and only yield a single empty line when there is another line of text:
+			gap = false
+			
+			@comments.each do |comment|
+				if match = comment.match(DESCRIPTION)
+					if match[1]
+						if gap
+							yield ""
+							gap = false
+						end
+						
+						yield match[1]
+					else
+						gap = true
+					end
+				else
+					break
+				end
+			end
+		end
+		
+		ATTRIBUTE = /\A\s*@(?<name>.*?)\s+(?<value>.*?)\z/
+		
+		def attributes
+			return to_enum(:attributes) unless block_given?
+			
+			@comments.each do |comment|
+				if match = comment.match(ATTRIBUTE)
+					yield match
+				end
+			end
+		end
+		
+		PARAMETER = /\A\s*@param\s+(?<name>.*?)\s+\[(?<type>.*?)\]\s+(?<details>.*?)\z/
+		
+		def parameters
+			return to_enum(:parameters) unless block_given?
+			
+			@comments.each do |comment|
+				if match = comment.match(PARAMETER)
+					yield match
+				end
+			end
+		end
+	end
+end

data/lib/decode/index.rb

@@ -18,7 +18,66 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
+require_relative 'source'
+require_relative 'trie'
+
 module Decode
 	class Index
+		def initialize(paths)
+			@paths = paths
+			@sources = {}
+			@symbols = {}
+			
+			# This is essentially a prefix tree:
+			@trie = Trie.new
+		end
+		
+		attr :paths
+		attr :sources
+		attr :symbols
+		
+		attr :trie
+		
+		def update!
+			@paths.each do |path|
+				source = Source.new(path)
+				@sources[path.relative_path] = Source.new(path)
+				
+				source.parse do |definition|
+					@symbols[definition.qualified_name] = definition
+					
+					@trie.insert(definition.lexical_path, definition)
+				end
+			end
+		end
+		
+		def lookup(reference, relative_to: nil)
+			if reference.absolute? || relative_to.nil?
+				lexical_path = []
+			else
+				lexical_path = relative_to.lexical_path
+			end
+			
+			path = reference.path
+			
+			while true
+				node = @trie.match(lexical_path)
+				
+				if node.children[path.first]
+					if target = node.lookup(path)
+						if reference.kind
+							return target.values.select{|symbol| symbol.kind == reference.kind}
+						else
+							return target.values
+						end
+					else
+						return nil
+					end
+				end
+				
+				break if lexical_path.empty?
+				lexical_path.pop
+			end
+		end
 	end
 end

data/lib/decode/language/ruby.rb

@@ -20,17 +20,70 @@
 
 require_relative '../symbol'
 
+require 'parser/current'
+
 module Decode
 	module Language
 		class Ruby
-			def initialize
-			end
-			
+			# The symbol which is used to separate the specified definition from the parent scope.
 			PREFIX = {
 				class: '::',
 				module: '::',
-				def: '-',
-			}
+				def: ':',
+				constant: '::',
+				defs: '.',
+			}.freeze
+			
+			KIND =  {
+				':' => :def,
+				'.' => :defs,
+			}.freeze
+			
+			class Reference
+				def initialize(value)
+					@value = value
+					
+					@path = nil
+					@kind = nil
+				end
+				
+				def absolute?
+					@value.start_with?('::')
+				end
+				
+				METHOD = /\A(?<scope>.*?)?(?<kind>:|\.)(?<name>.+?)\z/
+				
+				def path
+					if @path.nil?
+						@path = @value.split(/::/)
+						
+						if last = @path.pop
+							if match = last.match(METHOD)
+								@kind = KIND[match[:kind]]
+								
+								if scope = match[:scope]
+									@path << scope
+								end
+								
+								@path << match[:name]
+							else
+								@path << last
+							end
+						end
+						
+						@path = @path.map(&:to_sym)
+						@path.freeze
+					end
+					
+					return @path
+				end
+				
+				def kind
+					self.path
+					
+					return @kind
+				end
+			end
 			
 			def join(symbols, absolute = true)
 				buffer = String.new
@@ -42,37 +95,105 @@ module Decode
 						buffer << PREFIX[symbol.kind]
 					end
 					
-					buffer << symbol.name
+					buffer << symbol.name.to_s
 				end
+				
+				return buffer
 			end
 			
-			COMMENT = /\A\s*\#\s?(.*?)\Z/
-			DECLARATION = /\A(?<indentation>\s*)(?<text>(?<kind>module|class|def|attr)\s+(?<name>[\w\.\:]+).*)\Z/
+			def parse(input, &block)
+				parser = ::Parser::CurrentRuby.new
+				
+				buffer = ::Parser::Source::Buffer.new('(input)')
+				buffer.source = input.read
+				
+				top, comments = parser.parse_with_comments(buffer)
+				
+				walk(top, comments, &block)
+			end
 			
-			def parse(input)
-				first = true
-				comments = []
-				nesting = []
+			def extract_comments_for(node, comments)
+				prefix = []
 				
-				input.each_line do |line|
-					line.chomp!
+				while comment = comments.first
+					break if comment.location.line >= node.location.line
 					
-					if match = line.match(COMMENT)
-						comments << match[1]
-					elsif match = line.match(DECLARATION)
-						level = match[:indentation].size
-						parent = nesting[level-1]
-						
-						declaration = Declaration.new(match[:kind].to_sym, match[:name], match[:text], comments, parent: parent, language: self)
-						
-						nesting[level] = declaration
-						
-						yield declaration
-						
-						comments = []
-					else
-						comments.clear
+					if last_comment = prefix.last
+						if last_comment.location.line != (comment.location.line - 1)
+							prefix.clear
+						end
 					end
+					
+					prefix << comments.shift
+				end
+				
+				# The last comment must butt up against the node:
+				if comment = prefix.last
+					if comment.location.line == (node.location.line - 1)
+						return prefix.map(&:text)
+					end
+				end
+			end
+			
+			# Walk over the syntax tree and extract relevant definitions with their associated comments.
+			def walk(node, comments, parent = nil, &block)
+				case node.type
+				when :begin
+					node.children.each do |child|
+						walk(child, comments, parent, &block)
+					end
+				when :class
+					definition = Definition.new(
+						:class, node.children[0].children[1],
+						node, extract_comments_for(node, comments),
+						parent: parent, language: self
+					)
+					
+					yield definition
+					
+					walk(node.children[2], comments, definition, &block)
+				when :module
+					definition = Definition.new(
+						:module, node.children[0].children[1],
+						node, extract_comments_for(node, comments),
+						parent: parent, language: self
+					)
+					
+					yield definition
+					
+					walk(node.children[1], comments, definition, &block)
+				when :def
+					definition = Definition.new(
+						:def, node.children[0],
+						node, extract_comments_for(node, comments),
+						parent: parent, language: self
+					)
+					
+					yield definition
+					
+					# if body = node.children[2]
+					# 	walk(body, comments, definition, &block)
+					# end
+				when :defs
+					definition = Definition.new(
+						:defs, node.children[1],
+						node, extract_comments_for(node, comments),
+						parent: parent, language: self
+					)
+					
+					yield definition
+					
+					# if body = node.children[2]
+					# 	walk(body, comments, definition, &block)
+					# end
+				when :casgn
+					definition = Definition.new(
+						:constant, node.children[1],
+						node, extract_comments_for(node, comments),
+						parent: parent, language: self
+					)
+					
+					yield definition
 				end
 			end
 		end

data/lib/decode/symbol.rb

@@ -18,13 +18,28 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
+require_relative 'documentation'
+
 module Decode
+	Key = Struct.new(:kind, :name)
+	
 	class Symbol
 		def initialize(kind, name, parent: nil, language: parent.language)
 			@kind = kind
 			@name = name
 			@parent = parent
 			@language = language
+			
+			@path = nil
+			@qualified_name = nil
+		end
+		
+		def key
+			Key.new(@kind, @name)
+		end
+		
+		def inspect
+			"\#<#{self.class} #{@kind} #{qualified_name}>"
 		end
 		
 		attr :kind
@@ -32,26 +47,44 @@ module Decode
 		attr :parent
 		attr :language
 		
-		def full_name(parts = [])
-			if @parent
-				@parent.full_name(parts)
+		def qualified_name
+			@qualified_name ||= @language.join(self.path).freeze
+		end
+		
+		def path
+			if @path
+				@path
+			elsif @parent
+				@path = [*@parent.path, self.key]
+			else
+				@path = [self.key]
 			end
-			
-			parts << self
-			
-			@language.join(parts)
+		end
+		
+		def lexical_path
+			self.path.map(&:name)
 		end
 	end
 	
-	class Declaration < Symbol
-		def initialize(kind, name, text, comments, **options)
+	class Definition < Symbol
+		def initialize(kind, name, node, comments, **options)
 			super(kind, name, **options)
 			
-			@text = text
+			@node = node
 			@comments = comments
+			@documentation = nil
+		end
+		
+		def text
+			@node.location.expression.source
 		end
 		
-		attr :text
 		attr :comments
+		
+		def documentation
+			if @comments.any?
+				@documentation ||= Documentation.new(@comments)
+			end
+		end
 	end
 end

data/lib/decode/trie.rb

@@ -0,0 +1,87 @@
+# Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'source'
+
+module Decode
+	class Trie
+		class Node
+			def initialize
+				@values = nil
+				@children = Hash.new
+			end
+			
+			attr_accessor :values
+			attr :children
+			
+			def lookup(path, index = 0)
+				if index < path.size
+					if child = @children[path[index]]
+						return child.lookup(path, index+1)
+					end
+				else
+					return self
+				end
+			end
+			
+			def traverse(path = [], &block)
+				yield path, values if values
+				
+				@children.each do |name, node|
+					node.traverse([*path, name], &block)
+				end
+			end
+		end
+		
+		attr_accessor :value
+		
+		def initialize
+			@root = Node.new
+		end
+		
+		attr :root
+		
+		def insert(path, value)
+			node = @root
+			
+			path.each do |key|
+				node = (node.children[key] ||= Node.new)
+			end
+			
+			(node.values ||= []) << value
+		end
+		
+		def lookup(path)
+			@root.lookup(path).values
+		end
+		
+		# Given a base path, enumerate all paths under that.
+		# @yield (path, values) pairs
+		def each(path, &block)
+			if node = @root.lookup(path)
+				node.traverse(&block)
+			end
+		end
+		
+		def match(path, &block)
+			@root.lookup(path)
+		end
+	end
+end

data/lib/decode/version.rb

@@ -19,5 +19,5 @@
 # THE SOFTWARE.
 
 module Decode
-	VERSION = "0.1.0"
+	VERSION = "0.2.0"
 end

data/lib/decode.rb

@@ -19,3 +19,4 @@
 # THE SOFTWARE.
 
 require_relative "decode/version"
+require_relative "decode/index"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: decode
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -11,7 +11,7 @@ cert_chain: []
 date: 2020-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: build-files
+  name: parser
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: build-files
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bake-bundler
   requirement: !ruby/object:Gem::Requirement
@@ -109,11 +123,13 @@ files:
 - gems.locked
 - gems.rb
 - lib/decode.rb
+- lib/decode/documentation.rb
 - lib/decode/index.rb
 - lib/decode/language.rb
 - lib/decode/language/ruby.rb
 - lib/decode/source.rb
 - lib/decode/symbol.rb
+- lib/decode/trie.rb
 - lib/decode/version.rb
 homepage: https://github.com/ioquatix/decode
 licenses: