automatic 14.12.2 → 26.08

data/lib/automatic/http.rb

@@ -0,0 +1,107 @@
+# -*- coding: utf-8 -*-
+# Name::        Automatic::Http
+# Author:       id774 (More info: http://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::     Aug 15, 2026
+# Updated::     Aug 21, 2026
+# Copyright::   Copyright (c) 2012-2026 Automatic Ruby Developers.
+#
+# One way in for everything the plugins fetch over HTTP.
+#
+# This exists because seven plugins were each calling `URI.open` on a string,
+# and the four decisions that call implies -- which schemes are allowed, how
+# long to wait, how many redirects to follow, what to send as a User-Agent --
+# were being made seven times, mostly by omission. They are made once here.
+# It is a helper, not a client framework: one method fetches, one builds a URI,
+# and a plugin that wants something else still calls Ruby directly.
+# See doc/POLICY.md section 9.2 and doc/PLUGINS.md section 3.8.
+
+require 'open-uri'
+require 'uri'
+require 'automatic/version'
+
+module Automatic
+  module Http
+    # A link in a pipeline item comes from a feed, which is to say from
+    # outside. `URI.open` on such a string will happily read `file:///etc/passwd`
+    # or run an FTP session; a plugin fetching an article body wants neither.
+    SCHEMES = %w[http https].freeze
+
+    OPEN_TIMEOUT = 10
+    READ_TIMEOUT = 30
+
+    # open-uri follows redirects itself and refuses an HTTPS-to-HTTP downgrade.
+    # This bounds the chain so that a redirect loop ends as an error rather
+    # than as an unattended run that never returns.
+    REDIRECT_LIMIT = 5
+
+    USER_AGENT = "Automatic Ruby/#{Automatic::VERSION} " \
+                 '(+https://github.com/id774/automaticruby)'
+
+    # The RFC 2396 parser is named directly: `URI.escape` was removed in Ruby
+    # 3.0, and `URI::Parser` became the RFC 3986 parser in 3.4, which reports
+    # #escape as obsolete. This spelling means the same thing on every
+    # supported Ruby.
+    ESCAPER = URI::RFC2396_Parser.new
+
+    class << self
+      # Fetch a URL and return its body as a string. Raises rather than
+      # returning nil: a plugin's retry handling is built around an exception,
+      # and a body that could not be fetched is not an empty body.
+      def read(url)
+        open(url, &:read)
+      end
+
+      # Fetch a URL and yield the IO, for a caller that would rather stream
+      # than hold the whole body.
+      def open(url, &block)
+        uri(url).open(
+          'User-Agent' => USER_AGENT,
+          open_timeout: OPEN_TIMEOUT,
+          read_timeout: READ_TIMEOUT,
+          redirect: true,
+          max_redirects: REDIRECT_LIMIT,
+          &block
+        )
+      end
+
+      # Parse a URL into a URI this framework will fetch, or raise. A string
+      # carrying characters a URI may not (a space, a Japanese query term) is
+      # escaped and parsed again, which is what the plugins used to do for
+      # themselves before every call.
+      def uri(url)
+        string = url.to_s.strip
+        raise ArgumentError, 'no URL to fetch' if string.empty?
+
+        parsed = parse(string)
+        unless SCHEMES.include?(parsed.scheme)
+          raise ArgumentError, "not an HTTP or HTTPS URL: #{string}"
+        end
+        unless parsed.host
+          raise ArgumentError, "HTTP or HTTPS URL has no host: #{string}"
+        end
+
+        parsed.normalize
+      end
+
+      # Whether a string is a URL this framework will fetch. For a plugin that
+      # skips an item rather than failing the run on one.
+      def fetchable?(url)
+        uri(url)
+        true
+      rescue ArgumentError, URI::InvalidURIError
+        false
+      end
+
+      private
+
+      def parse(string)
+        URI.parse(string)
+      rescue URI::InvalidURIError
+        URI.parse(ESCAPER.escape(string))
+      end
+    end
+  end
+end

data/lib/automatic/log.rb

@@ -1,31 +1,62 @@
 # -*- coding: utf-8 -*-
-# Name::      Automatic::Log
-# Author::    774 <http://id774.net>
-# Created::   Feb 20, 2012
-# Updated::   Oct 09, 2014
-# Copyright:: Copyright (c) 2012-2014 Automatic Ruby Developers.
-# License::   Licensed under the GNU GENERAL PUBLIC LICENSE, Version 3.0.
+# Name::        Automatic::Log
+# Author:       id774 (More info: http://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 20, 2012
+# Updated::     Aug 14, 2026
+# Copyright::   Copyright (c) 2012-2026 Automatic Ruby Developers.
+#
+# One log, to standard output, behind a level filter set per Recipe by
+# global.log.level. See doc/BASIC_DESIGN.md section 4.7.
 
 require 'logger'
 
 module Automatic
   module Log
-    LOG_LEVELS = ['info', 'warn', 'error', 'none']
+    # In increasing order of severity. 'none' is the threshold that admits
+    # nothing; it is never used as the level of a message.
+    LOG_LEVELS = %w[info warn error none].freeze
 
-    def self.level(level)
-      @level = level
-    end
+    DEFAULT_LEVEL = 'info'
 
-    def self.logger
-      @logger ||= Logger.new(STDOUT)
-    end
+    class << self
+      # Set the threshold. An unrecognised name, including nil, means the
+      # default: an unattended run should not be silenced by a typo in a
+      # Recipe, nor should it raise in the middle of a job.
+      def level(level = nil)
+        @level = normalize(level, DEFAULT_LEVEL)
+      end
 
-    def self.puts(level = :info, message)
-      if LOG_LEVELS.index(@level).to_i > LOG_LEVELS.index(level).to_i
-        return
+      def logger
+        @logger ||= Logger.new($stdout)
       end
-      logger.send(level, message)
-    end
 
+      # Replace the logger. Used by the specs; a plugin has no business
+      # calling this.
+      attr_writer :logger
+
+      # Emit a message at the given level, if the threshold admits it.
+      # Both 'info' and :info are accepted, because plugins pass both.
+      def puts(level, message)
+        name = normalize(level, DEFAULT_LEVEL)
+        return if name == 'none'
+        return if LOG_LEVELS.index(name) < LOG_LEVELS.index(current_level)
+
+        logger.public_send(name, message)
+      end
+
+      private
+
+      def current_level
+        @level ||= DEFAULT_LEVEL
+      end
+
+      def normalize(level, fallback)
+        name = level.to_s
+        LOG_LEVELS.include?(name) ? name : fallback
+      end
+    end
   end
 end

data/lib/automatic/opml.rb

@@ -220,7 +220,9 @@ module Automatic
       end # each_outline
 
       def read_text
-        text = ""
+        # +'' rather than "": this string is appended to below, and a literal
+        # is on its way to being frozen.
+        text = +''
         while event = @p.pull
           case event.event_type
           when :end_element

data/lib/automatic/pipeline.rb

@@ -1,43 +1,74 @@
 # -*- coding: utf-8 -*-
-# Name::      Automatic::Pipeline
-# Author::    774 <http://id774.net>
-# Created::   Feb 22, 2012
-# Updated::   Mar 16, 2014
-# Copyright:: Copyright (c) 2012-2014 Automatic Ruby Developers.
-# License::   Licensed under the GNU GENERAL PUBLIC LICENSE, Version 3.0.
+# Name::        Automatic::Pipeline
+# Author:       id774 (More info: http://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 22, 2012
+# Updated::     Aug 14, 2026
+# Copyright::   Copyright (c) 2012-2026 Automatic Ruby Developers.
+#
+# The core: resolve a plugin's class name to a file, then run the Recipe's
+# plugins in order, each receiving the previous one's output. See
+# doc/BASIC_DESIGN.md section 4.6 and doc/PLUGINS.md section 3.
 
-require 'active_support'
-require 'active_support/core_ext'
-require 'active_support/deprecation'
+require 'active_support/core_ext/string/inflections'
 
 module Automatic
-  module Plugin end
-  class NoPluginError < StandardError; end
-  class NoRecipeError < StandardError; end
+  # The namespace every plugin class lives in. Plugin files are registered
+  # here with autoload, so a file is read when its constant is first used.
+  module Plugin; end
 
   module Pipeline
-    def self.load_plugin(module_name)
-      Dir[Automatic.user_plugins_dir + "/*",
-          Automatic.plugins_dir + "/*"].each {|dir|
-        subdir = File.basename dir
-        if /#{subdir}_(.*)$/ =~ module_name.underscore
-          path = dir + "/#{$1}.rb"
-          return Automatic::Plugin.autoload module_name.to_sym,
-            path.to_s if File.exists? path
+    class << self
+      # Resolve a module name such as SubscriptionFeed to
+      # <search root>/subscription/feed.rb and register it for autoloading.
+      #
+      # The user directory is searched before the installation, so a plugin in
+      # ~/.automatic/plugins shadows a shipped plugin of the same name.
+      def load_plugin(module_name)
+        underscored = module_name.underscore
+
+        search_roots.each do |dir|
+          category = File.basename(dir)
+          next unless /\A#{Regexp.escape(category)}_(.*)\z/ =~ underscored
+
+          path = File.join(dir, "#{Regexp.last_match(1)}.rb")
+          next unless File.exist?(path)
+
+          return Automatic::Plugin.autoload(module_name.to_sym, path)
         end
-      }
-      raise NoPluginError, "unknown plugin named #{module_name}"
-    end
 
-    def self.run(recipe)
-      raise NoRecipeError if recipe.nil?
-      pipeline = []
-      recipe.each_plugin {|plugin|
-        mod = plugin.module
-        load_plugin(mod)
-        klass = Automatic::Plugin.const_get(mod)
-        pipeline = klass.new(plugin.config, pipeline).run
-      }
+        raise NoPluginError, "unknown plugin named #{module_name}"
+      end
+
+      # Run a Recipe: each plugin's return value is the next plugin's input.
+      #
+      # Nothing here rescues a plugin's exception. A Recipe is a sequence in
+      # which each step consumes the previous one's output, so continuing past
+      # a failed step would run the rest on a value their author never
+      # intended. See doc/REQUIREMENTS.md section 12.
+      def run(recipe)
+        raise NoRecipeError, 'no recipe given' if recipe.nil?
+
+        pipeline = []
+        recipe.each_plugin do |plugin|
+          mod = plugin.module
+          load_plugin(mod)
+          klass = Automatic::Plugin.const_get(mod)
+          pipeline = klass.new(plugin.config, pipeline).run
+        end
+        pipeline
+      end
+
+      private
+
+      def search_roots
+        Dir[File.join(Automatic.user_plugins_dir, '*'),
+            File.join(Automatic.plugins_dir, '*')].select { |path|
+          File.directory?(path)
+        }
+      end
     end
   end
 end

data/lib/automatic/recipe.rb

@@ -1,37 +1,76 @@
 # -*- 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::     Aug 14, 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.
 
+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
+
+      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
   end
 end

data/lib/automatic/version.rb

@@ -1,3 +1,16 @@
+# -*- coding: utf-8 -*-
+# Name::        Automatic::VERSION
+# Author:       id774 (More info: http://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 14, 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.08'
 end

data/lib/automatic.rb

@@ -1,54 +1,112 @@
 # -*- 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: http://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 14, 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
 
   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
+      raise LoadError,
+            "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
+
+    # Where a Recipe named by a bare filename is looked for.
+    def user_config_dir
+      File.join(user_dir.to_s, 'config')
     end
-  end
 
+    private
+
+    def default_user_dir
+      File.expand_path('~') + USER_DIR
+    end
+  end
 end