decode 0.20.2 → 0.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 133b0261b7fc97e74472573ccfe28b7526409627b7ebf60ee9674ff62348b0bc
-  data.tar.gz: 79572a96b6c043d76093db8fac0835b6aeae69885f10d687e6ee18313a179e6d
+  metadata.gz: 6b8fbab2f6bbd8c5008a6a6de78b05846e7e102ae913c222a7c89410155c8585
+  data.tar.gz: ee07d9267e3d9ad7d84e0a72015e263465f1575fb8cb37942b4329e185ea54f8
 SHA512:
-  metadata.gz: ad5a07fac459587b2a7c2630e4a368797ab8d7c6290134640a561b4b6acd9d1cc15fc310e752fd5895718c0b4f46c04e37facc457519d9a16f3f40d5cdd122fc
-  data.tar.gz: a76d74f0eeb86f787dd6df5f859ce5235367a3e9ee2ab54aea1f22e2b5b980fac64f5620c239119406ee45492f5ed177959ccb49ade5ef58bf1ad0d676bb2bde
+  metadata.gz: 31004fbf090c9766bbec2b47c92a475a41b26e72641d040cf03e01c82ca038d9ed22daba05b9db9ac9ab484cca786f3f6adc727ba7cfcb62a710460a0ef9980a
+  data.tar.gz: ac3d6de5594d11b875c6c6befe2f01b2eea5a1dfa36e74e416697618a63f1c7b09ed6096e8981a4cfdbca6180aaa1b6d8ee75560bb3b7383272bd78bf1b99e8e

data/bake/decode/index.rb

@@ -8,26 +8,51 @@
 def coverage(root)
 	require 'build/files/glob'
 	require 'decode/index'
+	require 'set'
 	
 	paths = Build::Files::Path.expand(root).glob("**/*")
 	
 	index = Decode::Index.new
 	index.update(paths)
 	
-	total = 0
-	documented = 0
+	documented = Set.new
+	missing = Set.new
 	
-	index.definitions.each do |name, definition|
-		total += 1
+	index.trie.traverse do |path, node, descend|
+		public_definition = node.values.nil?
+		
+		node.values&.each do |definition|
+			if definition.public?
+				level = path.size
+				
+				if definition.comments.nil?
+					missing << definition.qualified_name
+				else
+					documented << definition.qualified_name
+				end
+				
+				public_definition = true
+			end
+		end
 		
-		if comments = definition.comments
-			documented += 1
-		else
-			$stderr.puts "#{name}"
+		# Don't descend into non-public definitions:
+		if public_definition
+			descend.call
 		end
 	end
 	
-	$stderr.puts "#{documented}/#{total} definitions have documentation."
+	documented_count = documented.size
+	public_count = documented_count + missing.size
+	$stderr.puts "#{documented_count} definitions have documentation, out of #{public_count} public definitions."
+	
+	if documented_count < public_count
+		$stderr.puts nil, "Missing documentation for:"
+		missing.each do |name|
+			$stderr.puts "- #{name}"
+		end
+		
+		raise RuntimeError, "Insufficient documentation!"
+	end
 end
 
 # Process the given source root and report on symbols.

data/lib/decode/definition.rb

@@ -48,6 +48,15 @@ module Decode
 		# @attribute [Array(String)]
 		attr :comments
 		
+		# Whether the definition is considered part of the public interface.
+		#
+		# This is used to determine whether the definition should be documented for coverage purposes.
+		#
+		# @returns [Boolean]
+		def public?
+			true
+		end
+		
 		# The qualified name is an absolute name which includes any and all namespacing.
 		# @returns [String]
 		def qualified_name

data/lib/decode/index.rb

@@ -37,7 +37,7 @@ module Decode
 		attr :sources
 		
 		# All definitions which have been parsed.
-		# @attribute [Array(Symbol)]
+		# @attribute [Hash(String, Definition)]
 		attr :definitions
 		
 		# A (prefix) trie of lexically scoped definitions.

data/lib/decode/language/ruby/definition.rb

@@ -11,19 +11,27 @@ module Decode
 			# A Ruby-specific definition.
 			class Definition < Decode::Definition
 				# Initialize the definition from the syntax tree node.
-				def initialize(node, *arguments, **options)
+				def initialize(node, *arguments, visibility: nil, **options)
 					super(*arguments, **options)
 					
 					@node = node
+					@visibility = visibility
 				end
 				
 				def nested_name
 					"\##{@name}"
 				end
 				
-				# The parser syntax tree node.
+				# @attribute [Parser::AST::Node] The parser syntax tree node.
 				attr :node
 				
+				# @attribute [Symbol] The visibility of the definition.
+				attr_accessor :visibility
+				
+				def public?
+					@visibility == :public
+				end
+				
 				def multiline?
 					@node.location.line != @node.location.last_line
 				end

data/lib/decode/language/ruby/parser.rb

@@ -25,6 +25,17 @@ module Decode
 			class Parser
 				def initialize(language)
 					@language = language
+					
+					@visibility = :public
+					@definitions = Hash.new.compare_by_identity
+				end
+				
+				private def assign_definition(parent, definition)
+					(@definitions[parent] ||= {})[definition.name] = definition
+				end
+				
+				private def lookup_definition(parent, name)
+					(@definitions[parent] ||= {})[name]
 				end
 				
 				# Parse the given source object, can be a string or a Source instance.
@@ -71,6 +82,14 @@ module Decode
 					end
 				end
 				
+				def with_visibility(visibility = :public, &block)
+					saved_visibility = @visibility
+					@visibility = visibility
+					yield
+				ensure
+					@visibility = saved_visibility
+				end
+				
 				# Walk over the syntax tree and extract relevant definitions with their associated comments.
 				def walk_definitions(node, comments, parent = nil, &block)
 					case node.type
@@ -79,32 +98,40 @@ module Decode
 							node, nested_name_for(node.children[0]),
 							comments: extract_comments_for(node, comments),
 							parent: parent,
-							language: @language
+							language: @language, visibility: :public
 						)
 						
+						assign_definition(parent, definition)
+						
 						yield definition
 						
 						if children = node.children[1]
-							walk_definitions(children, comments, definition, &block)
+							with_visibility do
+								walk_definitions(children, comments, definition, &block)
+							end
 						end
 					when :class
 						definition = Class.new(
 							node, nested_name_for(node.children[0]),
 							comments: extract_comments_for(node, comments),
-							parent: parent, language: @language
+							parent: parent, language: @language, visibility: :public
 						)
 						
+						assign_definition(parent, definition)
+						
 						yield definition
 						
 						if children = node.children[2]
-							walk_definitions(children, comments, definition, &block)
+							with_visibility do
+								walk_definitions(children, comments, definition, &block)
+							end
 						end
 					when :sclass
 						if name = singleton_name_for(node.children[0])
 							definition = Singleton.new(
 								node, name,
 								comments: extract_comments_for(node, comments),
-								parent: parent, language: @language
+								parent: parent, language: @language, visibility: :public
 							)
 							
 							yield definition
@@ -117,7 +144,7 @@ module Decode
 						definition = Method.new(
 							node, node.children[0],
 							comments: extract_comments_for(node, comments),
-							parent: parent, language: @language
+							parent: parent, language: @language, visibility: @visibility
 						)
 						
 						yield definition
@@ -128,7 +155,7 @@ module Decode
 							node, node.children[1],
 							comments: extracted_comments,
 							parent: scope_for(extracted_comments, parent, &block),
-							language: @language
+							language: @language, visibility: @visibility
 						)
 						
 						yield definition
@@ -144,6 +171,14 @@ module Decode
 						name = node.children[1]
 						
 						case name
+						when :public, :protected, :private
+							@visibility = name
+						when :private_constant
+							constant_names_for(node.children[2..]) do |name|
+								if definition = lookup_definition(parent, name)
+									definition.visibility = :private
+								end
+							end
 						when :attr, :attr_reader, :attr_writer, :attr_accessor
 							definition = Attribute.new(
 								node, name_for(node.children[2]),
@@ -263,6 +298,14 @@ module Decode
 					return parent
 				end
 				
+				def constant_names_for(children)
+					children.each do |node|
+						if node.type == :sym
+							yield node.children[0]
+						end
+					end
+				end
+				
 				# Extract segments from the given input file.
 				def segments_for(source, &block)
 					top, comments = self.parse_source(source)

data/lib/decode/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2020-2022, by Samuel Williams.
 
 module Decode
-	VERSION = "0.20.2"
+	VERSION = "0.21.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: decode
 version: !ruby/object:Gem::Version
-  version: 0.20.2
+  version: 0.21.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -37,7 +37,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2023-12-04 00:00:00.000000000 Z
+date: 2024-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parser
@@ -125,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.22
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: Code analysis for documentation generation.