automatic 14.12.2 → 26.09

data/lib/automatic/recipe.rb

@@ -1,37 +1,120 @@
 # -*- coding: utf-8 -*-
-# Name::      Automatic::Recipe
-# Author::    ainame
-#             774 <http://id774.net>
-# Created::   Feb 18, 2012
-# Updated::   Jun 14, 2012
-# Copyright:: Copyright (c) 2012-2013 Automatic Ruby Developers.
-# License::   Licensed under the GNU GENERAL PUBLIC LICENSE, Version 3.0.
+# Name::        Automatic::Recipe
+# Author:       ainame
+# Source Code:: https://github.com/id774/automaticruby
+# License::     The GPL version 3, or LGPL version 3 (Dual License).
+# Contact::     idnanashi@gmail.com
+# Created::     Feb 18, 2012
+# Updated::     Sep  6, 2026
+# Copyright::   Copyright (c) 2012-2026 Automatic Ruby Developers.
+#
+# Turns a Recipe file into something the pipeline can iterate. The format is
+# specified in doc/PLUGINS.md section 2.
+#
+# Each plugin entry's documented shape -- a mapping naming a module, with an
+# optional config mapping -- is validated here, at load time, rather than
+# left to surface as whatever internal exception a malformed entry happens to
+# raise once the pipeline reaches it.
 
+require 'date'
 require 'hashie'
 require 'yaml'
 
 module Automatic
   class Recipe
+    # A Recipe is trusted local configuration, but it is still loaded safely:
+    # the document may name none of its own Ruby classes to instantiate. That
+    # costs nothing, since no Recipe needs it. It is a second line of defence
+    # and not the trust boundary; see doc/REQUIREMENTS.md section 17.
+    PERMITTED_CLASSES = [Date, Time, Symbol].freeze
+
     attr_reader :procedure
 
-    def initialize(path = "")
+    def initialize(path = '')
       load_recipe(path)
     end
 
     def load_recipe(path)
-      dir = File.join((File.expand_path('~/.automatic/config/')), path)
-      path = dir if File.exist?(dir)
-      @procedure = Hashie::Mash.new(YAML.load(File.read(path)))
-      log_level = @procedure.global && @procedure.global.log && @procedure.global.log.level
-      Automatic::Log.level(log_level)
-      Automatic::Log.puts("info", "Loading Recipe: #{path}")
+      resolved = resolve_path(path)
+      document = parse(resolved)
+
+      unless document.is_a?(Hash)
+        raise InvalidRecipeError,
+              "recipe #{resolved} is not a mapping"
+      end
+
+      @procedure = Hashie::Mash.new(document)
+
+      unless @procedure.plugins.is_a?(Array)
+        raise InvalidRecipeError,
+              "recipe #{resolved} has no plugins sequence"
+      end
+
+      validate_plugins(resolved)
+
+      Automatic::Log.level(@procedure.global&.log&.level)
+      Automatic::Log.puts('info', "Loading Recipe: #{resolved}")
       @procedure
     end
 
     def each_plugin
-      @procedure.plugins.each {|plugin|
-        yield plugin
-      }
+      return enum_for(:each_plugin) unless block_given?
+
+      @procedure.plugins.each { |plugin| yield plugin }
+    end
+
+    private
+
+    # A bare filename is looked for in the user's config directory first;
+    # anything not found there is used as a path exactly as given.
+    def resolve_path(path)
+      in_user_dir = File.join(Automatic.user_config_dir, path.to_s)
+      File.exist?(in_user_dir) ? in_user_dir : path.to_s
+    end
+
+    def parse(path)
+      YAML.safe_load(
+        File.read(path),
+        permitted_classes: PERMITTED_CLASSES,
+        aliases: true
+      )
+    end
+
+    # Only the shape doc/PLUGINS.md documents is checked here: a mapping
+    # naming a module, with an optional config mapping. What a plugin does
+    # with its own config is that plugin's concern, not this one's.
+    def validate_plugins(resolved)
+      @procedure.plugins.each_with_index do |plugin, index|
+        validate_plugin_entry(resolved, plugin, index)
+      end
+    end
+
+    def validate_plugin_entry(resolved, plugin, index)
+      unless plugin.is_a?(Hash)
+        raise InvalidRecipeError,
+              "recipe #{resolved} plugins[#{index}] is not a mapping"
+      end
+
+      validate_module_name(resolved, plugin, index)
+      validate_plugin_config(resolved, plugin, index)
+    end
+
+    def validate_module_name(resolved, plugin, index)
+      name = plugin['module']
+
+      return if name.is_a?(String) && !name.strip.empty?
+
+      raise InvalidRecipeError,
+            "recipe #{resolved} plugins[#{index}] has no module name"
+    end
+
+    def validate_plugin_config(resolved, plugin, index)
+      config = plugin['config']
+
+      return if config.nil? || config.is_a?(Hash)
+
+      raise InvalidRecipeError,
+            "recipe #{resolved} plugins[#{index}] has a config that is not a mapping"
     end
   end
 end

data/lib/automatic/version.rb

@@ -1,3 +1,16 @@
+# -*- coding: utf-8 -*-
+# Name::        Automatic::VERSION
+# Author:       id774 (More info: https://id774.net)
+# Source Code:: https://github.com/id774/automaticruby
+# License::     The GPL version 3, or LGPL version 3 (Dual License).
+# Contact::     idnanashi@gmail.com
+# Created::     Feb 18, 2012
+# Updated::     Aug 25, 2026
+# Copyright::   Copyright (c) 2012-2026 Automatic Ruby Developers.
+
 module Automatic
-  VERSION = "14.12.2"
+  # The release version. The VERSION file at the repository root carries the
+  # same number and the gemspec reads it from there; a spec asserts that the
+  # two agree. See doc/POLICY.md section 10.
+  VERSION = '26.09'
 end

data/lib/automatic.rb

@@ -1,54 +1,127 @@
 # -*- coding: utf-8 -*-
-# Name::      Automatic::Ruby
-# Author::    774 <http://id774.net>
-# Created::   Feb 18, 2012
-# Updated::   Feb 21, 2014
-# Copyright:: Copyright (c) 2012-2014 Automatic Ruby Developers.
-# License::   Licensed under the GNU GENERAL PUBLIC LICENSE, Version 3.0.
+# Name::        Automatic::Ruby
+# Author:       id774 (More info: https://id774.net)
+# Source Code:: https://github.com/id774/automaticruby
+# License::     The GPL version 3, or LGPL version 3 (Dual License).
+# Contact::     idnanashi@gmail.com
+# Created::     Feb 18, 2012
+# Updated::     Sep  6, 2026
+# Copyright::   Copyright (c) 2012-2026 Automatic Ruby Developers.
+#
+# The framework module: the two directories everything else resolves paths
+# against, and the one method that runs a Recipe. See doc/BASIC_DESIGN.md
+# section 4.3.
 
 module Automatic
   require 'automatic/environment'
+  require 'automatic/log'
   require 'automatic/recipe'
   require 'automatic/pipeline'
-  require 'automatic/log'
+  require 'automatic/http'
   require 'automatic/feed_parser'
   require 'automatic/feed_maker'
   require 'automatic/version'
 
-  USER_DIR = "/.automatic"
+  # The user directory, relative to the home directory.
+  USER_DIR = '/.automatic'
+
+  # Base class for every failure the framework raises itself, so that a caller
+  # can rescue these without rescuing everything.
+  class Error < StandardError; end
+
+  # Pipeline.run was given no Recipe.
+  class NoRecipeError < Error; end
+
+  # A Recipe named a module for which no plugin file could be found.
+  class NoPluginError < Error; end
+
+  # A Recipe parsed, but is not a document this framework can run.
+  class InvalidRecipeError < Error; end
+
+  # Raised by require_optional when, and only when, the exact feature it was
+  # asked to require could not be found. A LoadError subtype rather than an
+  # Error subtype, so that a caller already rescuing LoadError still catches
+  # it; distinct from plain LoadError so that a caller can tell "the optional
+  # gem itself is missing" apart from a LoadError raised from inside that
+  # gem's own load. See doc/POLICY.md section 9.1.
+  class OptionalDependencyError < LoadError; end
 
   class << self
     attr_accessor :root_dir
 
-    def run(args = { })
+    # Require a gem that only one plugin, or one optional path, needs, and turn
+    # its absence into a message naming the gem, what wanted it and how to get
+    # it. Nothing here resolves, installs or tracks a dependency: the `require`
+    # is the plugin's own, made where the plugin makes it, and this only
+    # replaces `cannot load such file -- dalli` with a sentence an operator can
+    # act on. See doc/POLICY.md section 9.1 and doc/PLUGINS.md section 3.8.
+    #
+    #   Automatic.require_optional('sanitize', needed_by: 'FilterSanitize')
+    #
+    # `gem_name` is given where it differs from the path required, as
+    # `active_record` does from the `activerecord` gem.
+    def require_optional(feature, needed_by:, gem_name: feature)
+      require feature
+    rescue LoadError => e
+      # e.path is the argument require failed to find. When it matches
+      # feature, this require itself is what failed, and the gem naming this
+      # feature is what is missing. When it does not, the failure happened
+      # somewhere inside feature's own load -- a different missing file -- and
+      # is not this gem's absence; it is re-raised unconverted.
+      raise e unless e.path == feature
+
+      raise OptionalDependencyError,
+            "The `#{gem_name}` gem is not installed. It is needed by #{needed_by}. " \
+            "Install it with `gem install #{gem_name}`, or in a source checkout add " \
+            'its group to the bundle; see the optional plugin dependencies in ' \
+            "doc/DEPLOYMENT.md. (#{e.message})"
+    end
+
+    # Run one Recipe. root_dir is the installation root; user_dir is honoured
+    # only under AUTOMATIC_RUBY_ENV=test, which is how the specs point the
+    # plugin loader at a fixture directory.
+    def run(args = {})
       self.root_dir = args[:root_dir]
       self.user_dir = args[:user_dir]
       Automatic::Pipeline.run(args[:recipe])
     end
 
     def plugins_dir
-      File.join(@root_dir, "plugins")
+      File.join(@root_dir.to_s, 'plugins')
     end
 
     def config_dir
-      File.join(@root_dir, "config")
+      File.join(@root_dir.to_s, 'config')
     end
 
+    # Defaults to ~/.automatic when nothing has set it, so that a caller which
+    # never went through .run still resolves the user directory.
     def user_dir
-      @user_dir
+      @user_dir ||= default_user_dir
     end
 
-    def user_dir=(_user_dir)
-      if ENV["AUTOMATIC_RUBY_ENV"] == "test" && !(_user_dir.nil?)
-        @user_dir = _user_dir
-      else
-        @user_dir = File.expand_path("~/") + USER_DIR
-      end
+    def user_dir=(dir)
+      @user_dir =
+        if ENV['AUTOMATIC_RUBY_ENV'] == 'test' && !dir.nil?
+          dir
+        else
+          default_user_dir
+        end
     end
 
     def user_plugins_dir
-      File.join(@user_dir, "plugins")
+      File.join(user_dir.to_s, 'plugins')
     end
-  end
 
+    # Where a Recipe named by a bare filename is looked for.
+    def user_config_dir
+      File.join(user_dir.to_s, 'config')
+    end
+
+    private
+
+    def default_user_dir
+      File.expand_path('~') + USER_DIR
+    end
+  end
 end

data/plugins/custom_feed/svn_log.rb

@@ -1,55 +1,96 @@
 # -*- coding: utf-8 -*-
-# Name::      Automatic::Plugin::CustomFeed::SVNLog
-# Author::    kzgs
-# Created::   Feb 29, 2012
-# Updated::   Mar  3, 2012
-# Copyright:: Copyright (c) 2012-2013 Automatic Ruby Developers.
-# License::   Licensed under the GNU GENERAL PUBLIC LICENSE, Version 3.0.
+# Name::        Automatic::Plugin::CustomFeed::SVNLog
+# Author:       kzgs
+# Source Code:: https://github.com/id774/automaticruby
+# License::     The GPL version 3, or LGPL version 3 (Dual License).
+# Contact::     idnanashi@gmail.com
+# Created::     Feb 29, 2012
+# Updated::     Aug 15, 2026
+# Copyright::   Copyright (c) 2012-2026 Automatic Ruby Developers.
 
+require 'rexml/document'
 require 'rss/maker'
+require 'time'
 
 module Automatic::Plugin
   class CustomFeedSVNLog
-    require 'xmlsimple'
+    DEFAULT_FETCH_ITEMS = 30
 
-    def initialize(config, pipeline=[])
-      @config = config
+    def initialize(config, pipeline = [])
+      @config   = config || {}
       @pipeline = pipeline
     end
 
     def run
-      revisions = XmlSimple.xml_in(`svn log #{svn_log_argument}`)["logentry"]
-      @pipeline << RSS::Maker.make("1.0") {|maker|
-        maker.channel.title = @config["title"] || ""
-        maker.channel.about = ""
-        maker.channel.description = ""
-        maker.channel.link = base_url
-        revisions.each {|rev|
-          item = maker.items.new_item
-          item.title = "#{rev["msg"]} by #{rev["author"]}"
-          item.link = base_url+"/!svn/bc/#{rev["revision"]}"
-          item.date = Time.parse(rev["date"][0])
-        }
-      }
-      return @pipeline
+      entries = revisions
+      if entries.empty?
+        # RSS 1.0 has no representation for a channel with no items, and a
+        # repository with no revisions in the window asked for is an ordinary
+        # answer rather than a failure.
+        Automatic::Log.puts('warn', "No revisions returned by svn log for #{base_url}")
+        return @pipeline
+      end
+
+      @pipeline << feed(entries)
+      @pipeline
     end
 
     private
 
-    def base_url
-      return @config['target'].gsub(/\/$/, "")
+    def feed(revisions)
+      RSS::Maker.make('1.0') do |maker|
+        maker.channel.title       = @config['title'].to_s
+        maker.channel.about       = ''
+        maker.channel.description = ''
+        maker.channel.link        = base_url
+
+        revisions.each do |revision|
+          item       = maker.items.new_item
+          item.title = "#{revision['msg']} by #{revision['author']}"
+          item.link  = "#{base_url}/!svn/bc/#{revision['revision']}"
+          item.date  = Time.parse(revision['date'])
+        end
+      end
+    end
+
+    # `svn log --xml` as REXML sees it. REXML is a runtime dependency of this
+    # framework already -- the OPML parser uses it -- so this plugin needs the
+    # svn command and no gem of its own.
+    def revisions
+      REXML::Document.new(svn_log).elements.to_a('/log/logentry').map do |entry|
+        {
+          'revision' => entry.attributes['revision'].to_s,
+          'author'   => text(entry, 'author'),
+          'msg'      => text(entry, 'msg'),
+          'date'     => text(entry, 'date')
+        }
+      end
     end
 
-    def svn_log_argument
-      return [
-        base_url,
-        "--xml",
-        "--limit=#{limit}"
-      ].join(" ")
+    def text(entry, name)
+      element = entry.elements[name]
+      element.nil? ? '' : element.text.to_s
+    end
+
+    # The command is run as an argument vector rather than through a shell, so
+    # a repository URL cannot become part of a command line. Point `target` at
+    # a repository you control regardless: svn itself will do what the URL
+    # tells it to.
+    def svn_log
+      output = IO.popen(['svn', 'log', base_url, '--xml', "--limit=#{limit}"],
+                        err: File::NULL, &:read)
+      raise "svn log failed for #{base_url}" unless $?.success?
+
+      output
+    end
+
+    def base_url
+      @base_url ||= @config['target'].to_s.sub(%r{/\z}, '')
     end
 
     def limit
-      return @config['fetch_items'] || 30
+      value = @config['fetch_items'].to_i
+      value.positive? ? value : DEFAULT_FETCH_ITEMS
     end
   end
 end