countless 1.0.0

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'countless'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/countless.gemspec

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'countless/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'countless'
+  spec.version       = Countless::VERSION
+  spec.authors       = ['Hermann Mayer']
+  spec.email         = ['hermann.mayer@hausgold.de']
+
+  spec.summary       = 'Code statistics/annotations helpers'
+  spec.description   = 'This gem includes reusable code statistics / ' \
+                       'annotations helpers / Rake tasks.'
+
+  spec.homepage      = 'https://github.com/hausgold/countless'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end + ['bin/cloc']
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 2.5'
+
+  spec.add_runtime_dependency 'activesupport', '>= 5.2.0'
+  spec.add_runtime_dependency 'zeitwerk', '~> 2.4'
+
+  spec.add_development_dependency 'appraisal'
+  spec.add_development_dependency 'benchmark-ips', '~> 2.10'
+  spec.add_development_dependency 'bundler', '>= 1.16', '< 3'
+  spec.add_development_dependency 'guard-rspec', '~> 4.7'
+  spec.add_development_dependency 'irb', '~> 1.2'
+  spec.add_development_dependency 'rspec', '~> 3.9'
+  spec.add_development_dependency 'rubocop', '~> 1.25'
+  spec.add_development_dependency 'rubocop-rails', '~> 2.14'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.10'
+  spec.add_development_dependency 'simplecov', '< 0.18'
+  spec.add_development_dependency 'yard', '~> 0.9.18'
+  spec.add_development_dependency 'yard-activesupport-concern', '~> 0.0.1'
+end

data/doc/assets/project.svg

@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   version="1.1"
+   id="Ebene_1"
+   x="0px"
+   y="0px"
+   viewBox="0 0 800 200"
+   xml:space="preserve"
+   width="800"
+   height="200"><metadata
+   id="metadata33"><rdf:RDF><cc:Work
+       rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type
+         rdf:resource="http://purl.org/dc/dcmitype/StillImage" /><dc:title></dc:title></cc:Work></rdf:RDF></metadata><defs
+   id="defs31" />
+<style
+   type="text/css"
+   id="style2">
+    .st0{fill-rule:evenodd;clip-rule:evenodd;fill:#E73E11;}
+    .st1{fill-rule:evenodd;clip-rule:evenodd;fill:#0371B9;}
+    .st2{fill:#132E48;}
+    .st3{font-family:'OpenSans-Bold';}
+    .st4{font-size:29.5168px;}
+    .st5{fill-rule:evenodd;clip-rule:evenodd;fill:none;}
+    .st6{opacity:0.5;fill:#132E48;}
+    .st7{font-family:'OpenSans';}
+    .st8{font-size:12px;}
+</style>
+<g
+   transform="translate(0,1.53584)"
+   id="g828"><g
+   transform="translate(35.93985,35.66416)"
+   id="g8">
+    <path
+   style="clip-rule:evenodd;fill:#e73e11;fill-rule:evenodd"
+   id="path4"
+   d="m -0.1,124.4 c 0,0 33.7,-123.2 66.7,-123.2 12.8,0 26.9,21.9 38.8,47.2 -23.6,27.9 -66.6,59.7 -94,76 -7.1,0 -11.5,0 -11.5,0 z"
+   class="st0" />
+    <path
+   style="clip-rule:evenodd;fill:#0371b9;fill-rule:evenodd"
+   id="path6"
+   d="m 88.1,101.8 c 13.5,-10.4 18.4,-16.2 27.1,-25.4 10,25.7 16.7,48 16.7,48 0,0 -41.4,0 -78,0 14.6,-7.9 18.7,-10.7 34.2,-22.6 z"
+   class="st1" />
+</g><text
+   y="106.40316"
+   x="192.43155"
+   style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:29.51733398px;font-family:'Open Sans', sans-serif;-inkscape-font-specification:'OpenSans-Bold, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#132e48"
+   id="text10"
+   class="st2 st3 st4">Countless</text>
+<rect
+   style="clip-rule:evenodd;fill:none;fill-rule:evenodd"
+   id="rect12"
+   height="24"
+   width="314.5"
+   class="st5"
+   y="118.06416"
+   x="194.23985" /><text
+   y="127.22146"
+   x="194.21715"
+   style="font-size:12px;font-family:'Open Sans', sans-serif;opacity:0.5;fill:#132e48;-inkscape-font-specification:'Open Sans, sans-serif, Normal';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;text-anchor:start;text-align:start;writing-mode:lr;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;"
+   id="text14"
+   class="st6 st7 st8">Code statistics/annotations helpers</text>
+</g>
+</svg>

data/docker-compose.yml

@@ -0,0 +1,8 @@
+version: "3"
+services:
+  test:
+    image: ruby:2.7
+    network_mode: bridge
+    working_dir: /app
+    volumes:
+      - .:/app

data/gemfiles/rails_5.2.gemfile

@@ -0,0 +1,9 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activejob", "5.2.0"
+gem "activerecord", "5.2.0"
+gem "activesupport", "5.2.0"
+
+gemspec path: "../"

data/gemfiles/rails_6.0.gemfile

@@ -0,0 +1,9 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activejob", "6.0.0"
+gem "activerecord", "6.0.0"
+gem "activesupport", "6.0.0"
+
+gemspec path: "../"

data/gemfiles/rails_6.1.gemfile

@@ -0,0 +1,9 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activejob", "6.1.0"
+gem "activerecord", "6.1.0"
+gem "activesupport", "6.1.0"
+
+gemspec path: "../"

data/gemfiles/rails_7.0.gemfile

@@ -0,0 +1,9 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "activejob", "7.0.0"
+gem "activerecord", "7.0.0"
+gem "activesupport", "7.0.0"
+
+gemspec path: "../"

data/lib/countless/annotations.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module Countless
+  # Annotation objects are triplets +:line+, +:tag+, +:text+ that represent the
+  # line where the annotation lives, its tag, and its text. Note the filename
+  # is not stored.
+  #
+  # Annotations are looked for in comments and modulus whitespace they have to
+  # start with the tag optionally followed by a colon. Everything up to the end
+  # of the line (or closing ERB comment tag) is considered to be their text.
+  #
+  # Heavily stolen from: https://bit.ly/3nBS0aj
+  #
+  # rubocop:disable Metrics/ClassLength because of the nested Annotation class
+  class Annotations
+    attr_reader :tag, :options, :dirs, :files, :annotations
+
+    # Setup a new instance of the source annotation extractor.
+    #
+    # If +tag+ is +nil+, annotations with either default or registered tags are
+    # printed.  Specific directories can be explicitly set using the +:dirs+
+    # key in +options+.
+    #
+    #   Countless::SourceAnnotationExtractor.enumerate(
+    #     'TODO|FIXME', dirs: %w(app lib), tag: true
+    #   )
+    #
+    # If +options+ has a +:tag+ flag, it will be passed to each annotation's
+    # +to_s+. See +#find_in+ for a list of file extensions that will be taken
+    # into account.
+    #
+    # @param tag [String, nil] the annotation tags to use
+    # @param options [Hash{Symbol => Mixed}] additional options
+    # @return [Countless::SourceAnnotationExtractor] the new instance
+    def initialize(tag = nil, options = {})
+      @tag = tag || Annotation.tags.join('|')
+      @dirs = options.delete(:dirs) || Annotation.directories
+      @files = options.delete(:files) || Annotation.files
+      @options = options
+      @annotations = find(dirs: dirs, files: files)
+    end
+
+    # Returns a hash that maps filenames under +dirs+ (recursively) to arrays
+    # with their annotations.
+    #
+    # @param files [Array<String>] the files to use
+    # @param dirs [Array<String>] the directories to use
+    # @return [Hash{String => Array<Annotation>}] the found annotations per file
+    def find(files: [], dirs: [])
+      results = {}
+      files.inject(results) { |memo, file| memo.update(annotations_in(file)) }
+      dirs.inject(results) { |memo, dir| memo.update(find_in(dir)) }
+      results
+    end
+
+    # Returns a hash that maps filenames under +dir+ (recursively) to arrays
+    # with their annotations. Files with extensions registered in
+    # +Countless::SourceAnnotationExtractor::Annotation.extensions+ are
+    # taken into account. Only files with annotations are included.
+    #
+    # @param dir [String] the directory to use
+    # @return [Hash{String => Array<Annotation>}] the found annotations per file
+    def find_in(dir)
+      results = {}
+
+      Dir.glob("#{dir}/*") do |item|
+        next if File.basename(item)[0] == '.'
+
+        if File.directory?(item)
+          results.update(find_in(item))
+        else
+          results.update(annotations_in(item))
+        end
+      end
+
+      results
+    end
+
+    # Returns a hash that maps filenames under +file+ (de-glob-bed) to arrays
+    # with their annotations. Files with extensions registered in
+    # +Countless::SourceAnnotationExtractor::Annotation.extensions+ are
+    # taken into account. Only files with annotations are included.
+    #
+    # @param file [String] the file to use
+    # @return [Hash{String => Array<Annotation>}] the found annotations per file
+    def annotations_in(file)
+      results = {}
+
+      Dir.glob(file) do |item|
+        extension = \
+          Annotation.extensions.detect { |regexp, _block| regexp.match(item) }
+
+        if extension
+          pattern = extension.last.call(tag)
+          results.update(extract_annotations_from(item, pattern)) if pattern
+        end
+      end
+
+      results
+    end
+
+    # If +file+ is the filename of a file that contains annotations this method
+    # returns a hash with a single entry that maps +file+ to an array of its
+    # annotations. Otherwise it returns an empty hash.
+    #
+    # @param file [String] the file path to extract annotations from
+    # @param pattern [RegExp] the matching pattern to use
+    # @return [Hash{String => Annotation}] the found annotation of the file
+    def extract_annotations_from(file, pattern)
+      lineno = 0
+      result = File.readlines(
+        file, encoding: Encoding::BINARY
+      ).inject([]) do |list, line|
+        lineno += 1
+        next list unless line =~ pattern
+
+        list << Annotation.new(lineno, Regexp.last_match(1),
+                               Regexp.last_match(2))
+      end
+      result.empty? ? {} : { file => result }
+    end
+
+    # Formats the found annotations.
+    #
+    # @return [String] the formatted annotations
+    #
+    # rubocop:disable Metrics/AbcSize because of the indentation logic
+    def to_s
+      buf = []
+      options[:indent] = annotations.flat_map do |_f, a|
+        a.map(&:line)
+      end.max.to_s.size
+      annotations.keys.sort.each do |file|
+        buf << "#{file}:"
+        annotations[file].each { |note| buf << "  * #{note.to_s(options)}" }
+        buf << ''
+      end
+      buf.join("\n")
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # A single annotation representation.
+    Annotation = Struct.new(:line, :tag, :text) do
+      # Returns the currently configured files.
+      #
+      # @return [Array<String>] the configured files
+      def self.files
+        @files ||= \
+          Countless.configuration.annotations_files.deep_dup
+      end
+
+      # Registers additional files to be included.
+      #
+      # @param dirs [Array<String>] the additional files to include
+      def self.register_files(*dirs)
+        files.push(*dirs)
+      end
+
+      # Returns the currently configured directories.
+      #
+      # @return [Array<String>] the configured directories
+      def self.directories
+        @directories ||= \
+          Countless.configuration.annotations_directories.deep_dup
+      end
+
+      # Registers additional directories to be included.
+      #
+      # @param dirs [Array<String>] the additional directories to include
+      def self.register_directories(*dirs)
+        directories.push(*dirs)
+      end
+
+      # Returns the currently configured tags.
+      #
+      # @return [Array<String>] the configured tags
+      def self.tags
+        @tags ||= Countless.configuration.annotation_tags.deep_dup.map do |tag|
+          "@?#{tag}"
+        end
+      end
+
+      # Registers additional tags.
+      #
+      # @param additional_tags [Array<String>] the additional tags to include
+      def self.register_tags(*additional_tags)
+        tags.push(*additional_tags)
+      end
+
+      # Returns the currently configured file extension handlers.
+      #
+      # @return [Hash<RegExp => Proc>] the configured file extension handlers
+      def self.extensions
+        @extensions ||= begin
+          patterns = Countless.configuration.annotation_patterns.values
+          patterns.map do |conf|
+            [
+              extensions_regexp(conf[:extensions], conf[:files] || []),
+              conf[:regex]
+            ]
+          end.to_h
+        end
+      end
+
+      # Registers new annotations file extension handlers.
+      #
+      # @param exts [Array<String>] the file extensions to match
+      # @param block [Proc] the line/comment/annotation matching block
+      def self.register_extensions(*exts, &block)
+        extensions[extensions_regexp(exts)] = block
+      end
+
+      # Build a new extension regexp of the given extensions.
+      #
+      # @param exts [Array<String>] the file extensions to join
+      # @param files [Array<String>] a list of dedicated files
+      # @return [RegExp] the extensions matching regexp
+      def self.extensions_regexp(exts, files = [])
+        exts = /\.(#{exts.join('|')})$/
+        return exts if files.empty?
+
+        Regexp.union(/^#{files.join('|')}$/, exts)
+      end
+
+      # Returns a representation of the annotation that looks like this:
+      #
+      #   [126] [TODO] This algorithm is nice and simple, make it faster.
+      #
+      # If +options+ has a flag +:tag+ the tag is shown as in the example
+      # above.  Otherwise the string contains just line and text.  When
+      # +options+ has a value for +:indent+ the line number block will be
+      # right-justified.
+      #
+      # @param options [Hash{Symbol => Mixed}] the additional options
+      def to_s(options = {})
+        s = +"[#{line.to_s.rjust(options[:indent])}] "
+        s << "[#{tag}] " if options[:tag]
+        s << text
+      end
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/countless/cloc.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Countless
+  # A simple wrapper around the CLOC utility.
+  class Cloc
+    class << self
+      # Extract code statistics from the given files with CLOC. Each key of the
+      # resulting hash is the file path which was inspected. Each value of the
+      # resulting hash contains the raw statistic numbers (blank, comment,
+      # code, total).
+      #
+      # Example:
+      #
+      #   {
+      #     "/app/lib/countless/configuration.rb" => {
+      #       :blank=>24, :comment=>43, :code=>141, :total=>208
+      #     }
+      #   }
+      #
+      # @return [Hash{String => Hash{Symbol => Integer}}] the
+      #   re-structured CLOC statistics
+      def stats(*paths)
+        raw_stats(*paths).except('SUM', 'header').transform_values do |obj|
+          obj.symbolize_keys.except(:language).tap do |stats|
+            stats[:total] = stats.values.sum
+          end
+        end
+      end
+
+      # Fetch the raw statistics via CLOC for the given paths.
+      #
+      # @param paths [Array<String, Pathname>] the paths (files or
+      #   directories) to fetch the statistics for
+      # @return [Hash{String => Hash{String => Mixed}] the raw CLOC
+      #   YAML output
+      #
+      # rubocop:disable Metrics/MethodLength because of the system
+      #   command preparation
+      def raw_stats(*paths)
+        cmd = [
+          Countless.cloc_path,
+          '--quiet',
+          '--by-file',
+          '--yaml',
+          '--list-file -',
+          '2>/dev/null'
+        ].join(' ')
+
+        # We pipe in the file list via stdin to cloc, this allows us to
+        # pass large file lists down (ARGV is size limited)
+        stdout = IO.popen(cmd, File::RDWR) do |io|
+          paths.each { |path| io.puts(path) }
+          io.close_write
+          io.read
+        end
+
+        # When the system command was not successful,
+        # we return an fallback result
+        return {} unless $CHILD_STATUS.success?
+
+        # Otherwise we use the CLOC produced YAML and parse it
+        YAML.safe_load(stdout) || {}
+      end
+      # rubocop:enable Metrics/MethodLength
+    end
+  end
+end