veragem 0.1.0 → 0.2.0

data/lib/veragem/license.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Veragem
+  # The gem's licence: one of three choices, each its SPDX identifiers.
+  module License
+    # Each choice's SPDX identifiers: the gemspec's licenses, the LICENSE-* files.
+    SPDX = { "mit" => ["MIT"], "apache" => ["Apache-2.0"], "dual" => ["MIT", "Apache-2.0"] }.freeze
+    # The choices, as --help, the question and a refusal name them.
+    CHOICES = "mit, apache or dual"
+
+    # The choice +value+ names: a choice, its SPDX expression (its ORs in either order) or the start
+    # of one choice alone, in any case (`Apache-2.0`, `apache-2.0 or mit`, `a`).
+    # @param value [String] valid UTF-8, the spaces around it stripped, as Project.check passes it
+    # @return [String] the choice
+    # @raise [Veragem::Error] it names none
+    def self.check(value)
+      given = value.downcase
+      spdx = SPDX.find { |_, ids| ids.map(&:downcase).sort == given.split(" or ").sort }&.first
+      return spdx if spdx
+
+      case SPDX.keys.select { it.start_with?(given) }
+      in [choice] then choice
+      else raise Error, "invalid license (#{CHOICES}) #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/veragem/name.rb

@@ -8,11 +8,29 @@ module Veragem
     # `bundle gem`'s names, lower-case: words of letters and digits joined by `_` (one constant,
     # `my_gem` is MyGem) or `-` (a namespace, `my-gem` is My::Gem), each constant a letter first.
     PATTERN = /\A[a-z][a-z0-9]*(?:_[a-z0-9]+)*(?:-[a-z][a-z0-9]*(?:_[a-z0-9]+)*)*\z/
+    # Windows' devices, whose names no file there takes: a path's word, of its dashes
+    RESERVED = /\A(?:con|prn|aux|nul|com\d|lpt\d)\z/
 
     # Its modules, as `bundle gem` names them: `my-gem_tools`' My, GemTools.
+    # @param name [String] one PATTERN matches
+    # @return [Array<String>] outermost first
     def self.modules(name) = name.split("-").map { |word| word.split("_").map(&:capitalize).join }
 
-    # +name+, or an Error saying why a gem cannot have it.
+    # The file the gem requires: `my-gem`'s is my/gem.
+    # @param name [String] one PATTERN matches
+    # @return [String]
+    def self.path(name) = name.tr("-", "/")
+
+    # Its words joined by `_` alone: `my-gem`'s my_gem, its test's file name.
+    # @param name [String] one PATTERN matches
+    # @return [String]
+    def self.underscored(name) = name.tr("-", "_")
+
+    # +name+, or an Error saying why a gem cannot have it, as written: Generator.check adds what its
+    # modules and its kind decide.
+    # @param name [String] a gem's name, as typed
+    # @return [String] +name+
+    # @raise [Veragem::Error] a gem cannot have it
     def self.check(name)
       unless PATTERN.match?(name)
         raise Error, "invalid gem name #{name.inspect}: lower-case words of letters and digits, each a " \
@@ -22,90 +40,134 @@ module Veragem
       if name.length > 40 || name.count("-") > 3
         raise Error, "invalid gem name #{name}: at most 40 characters and 4 modules deep"
       end
-      # lib/test_helper.rb would shadow the tests' own (Minitest's -Ilib:test)
-      raise Error, "invalid gem name #{name}: its lib/test_helper.rb would shadow the tests'" if name == "test_helper"
 
-      check_modules(name)
+      check_paths(name)
       name
     end
 
-    # The gem writes lib/<path>.rb, `module` for each of its modules, and tests that name the first.
+    # The gem writes lib/<path>.rb, `module` for each of its modules, and tests that name the first:
+    # none may meet what its tools load.
+    # @param name [String] one Name.check takes
+    # @return [void]
+    # @raise [Veragem::Error] a module or its file would meet another, or they could not be checked
     def self.check_modules(name)
       nestings = nestings_of(name)
-      shadowed, found, *kinds = probe(library_of(name), name.tr("-", "/"), nestings)
-      check_shadowing(name, shadowed.to_s, found.to_s)
-      check_defined(name, nestings.zip(kinds).take_while { |_, kind| !kind.to_s.empty? }, nestings.last)
-    end
-
-    # Its lib/<path>.rb, first on the load path, must not shadow a library its tools require
-    # (lib/json.rb, JSON's); its tests' classes, Minitest::Test's, and its gemspec, which `gem build`
-    # evaluates in Gem::Specification, must find its module, not one of theirs (`lifecycle_hooks`:
-    # Minitest::Test::LifecycleHooks).
-    def self.check_shadowing(name, shadowed, found)
-      unless shadowed.empty?
-        raise Error, "invalid gem name #{name}: its lib/#{name.tr("-", "/")}.rb would shadow #{shadowed}"
-      end
-      raise Error, "invalid gem name #{name}: #{found} for its module" unless found.empty?
+      answers = probe(library_of(name), path(name), nestings)
+      check_shadowing(name, answers.fetch(0), answers.fetch(1))
+      check_defined(name, nestings.zip(answers.drop(2)).take_while { |_, kind| !kind.to_s.empty? }, nestings.last)
     end
 
-    # The +defined+ nestings, outermost first, each with its class: the gem's own module, +innermost+,
-    # one defined already (Comparable) would reopen; an outer one that is a class (Set, Logger), it
-    # could not open.
-    def self.check_defined(name, defined, innermost)
-      raise Error, "invalid gem name #{name}: #{innermost} is already defined" if defined.last&.first == innermost
+    # What the gem's tools load with its code, where installed: Bundler's CLI, which reads its gemspec
+    # (bin/setup's `bundle install`); the Rakefile's libraries and its tasks' (RuboCop's, Steep's,
+    # YARD's ERB); bin/console's IRB; its tests' (SimpleCov, Pbt).
+    LIBRARIES = %w[bundler bundler/cli rake bundler/audit/task csv json minitest/test_task rubocop/rake_task
+                   steep/rake_task yard rubocop steep erb irb simplecov minitest/autorun pbt].freeze
+    # Its files' paths: lib/test_helper.rb would shadow the tests' own (Minitest's -Ilib:test); a
+    # device's name, whatever its extension, is no file of Windows' (lib/con.rb), nor git's there.
+    private_class_method def self.check_paths(name)
+      raise Error, "invalid gem name #{name}: its lib/test_helper.rb would shadow the tests'" if name == "test_helper"
 
-      outer = defined.find { |_, kind| kind != "Module" }
-      raise Error, "invalid gem name #{name}: #{outer[0]} is a #{outer[1]}, not a module" if outer
+      reserved = name.split("-").grep(RESERVED).first
+      raise Error, "invalid gem name #{name}: Windows reserves #{reserved} as a file's name" if reserved
     end
 
-    # The gem's top-level library: `date-holidays`' date
-    def self.library_of(name) = name.split("-").fetch(0)
-
-    # My, My::Gem
-    def self.nestings_of(name) = modules(name).then { |modules| (1..modules.size).map { modules.first(it).join("::") } }
-
     # The child: no stdin, a scratch directory, its arguments cleared before the libraries load, their
-    # own output kept from the answers, no exit hooks.
-    PROBE = <<~RUBY
+    # own output kept from the answers, no exit hooks (minitest/autorun's). A file shadowed in any
+    # case: a file system may ignore it (macOS', Windows').
+    PROBE = <<~RUBY.freeze
       library, path, *nestings = ARGV
       first = nestings.fetch(0)
       ARGV.clear
       answers = $stdout.dup
       $stdout.reopen($stderr)
-      ["bundler", "bundler/cli", "rake", "minitest", library].each do |feature|
+      [*#{LIBRARIES.inspect}, library].each do |feature|
         require feature
       rescue StandardError, ScriptError
         nil
       end
-      answers.puts($LOAD_PATH.resolve_feature_path(path)&.last)
+      files = "\#{path.gsub(/[a-z]/) { "[\#{it}\#{it.upcase}]" }}.{rb,\#{RbConfig::CONFIG["DLEXT"]}}"
+      shadowed = $LOAD_PATH.resolve_feature_path(path)&.last ||
+                 $LOAD_PATH.lazy.flat_map { |dir| Dir.glob(files, base: dir).map { File.join(dir, it) } }
+                           .first
+      answers.puts(shadowed)
       readers = { "its tests" => defined?(Minitest::Test) && Minitest::Test, "gem build" => Gem::Specification }
       found = readers.filter_map do |reader, context|
         owner = context && (context.ancestors - Object.ancestors).find { it.const_defined?(first, false) }
         "\#{reader} would find \#{owner}::\#{first}" if owner
       end
       answers.puts(found.first)
-      nestings.each { answers.puts(Object.const_defined?(it, false) ? Object.const_get(it, false).class : "") }
+      nestings.each do |nesting|
+        answers.puts(Object.const_defined?(nesting, false) ? Object.const_get(nesting, false).class : "")
+      rescue TypeError # an outer one no module (`Noisy = 1`): nothing within it
+        answers.puts("")
+      end
       answers.flush
       exit!(0)
     RUBY
-    private_constant :PROBE
+    private_constant :RESERVED, :LIBRARIES, :PROBE
+    # Each probe's answers: a question asked once a process
+    @probed = {} #: Hash[[String, String, Array[String]], Array[String]]
 
     # The file +path+ already requires, what a Minitest::Test or Gem::Specification finds for the
-    # first of +nestings+, then each nesting's class -- Module, Class... --, each "" when none, where
-    # the gem meets them: in Bundler's CLI, which reads its gemspec (bin/setup's `bundle install`),
-    # in Rake and Minitest, and with its top-level +library+ (`date-holidays`: date), which its tools
-    # may require. Asked of a Ruby of its own, so the answer is the same however this one was
-    # started. Its answers come only once the libraries are loaded, then the child exits: one fewer
-    # is a failure.
+    # first of +nestings+, then each nesting's class (Module, Class...), each "" when none, where the
+    # gem meets them: with what its tools load (LIBRARIES), and its top-level +library+
+    # (`date-holidays`: date), which they may require. Asked of a Ruby of its own, the same however
+    # this one was started (RUBYOPT's options would print before the answers), and once a process:
+    # the answer cannot change. The child answers once the libraries are loaded, then exits: fewer
+    # answers are a failure.
+    # @param library [String] the gem's top-level library
+    # @param path [String] the file the gem requires, lib/'s
+    # @param nestings [Array<String>] its modules' full names, outermost first
+    # @return [Array<String>] the shadowed file, what is found, then each nesting's class
+    # @raise [Veragem::Error] the child did not answer them all, or could not be run
     def self.probe(library, path, nestings)
+      @probed[[library, path, nestings]] ||= answers(library, path, nestings)
+    end
+
+    private_class_method def self.answers(library, path, nestings)
       command = [RbConfig.ruby, "-e", PROBE, library, path, *nestings]
+      env = Bundler.unbundled_env.except("RUBYOPT")
       answers = Dir.mktmpdir do |dir|
-        IO.popen(Bundler.unbundled_env, command, unsetenv_others: true, in: File::NULL, err: File::NULL, chdir: dir,
-                 &:readlines)
+        IO.popen(env, command, unsetenv_others: true, in: File::NULL, err: File::NULL, chdir: dir, &:readlines)
       end
-      raise Error, "could not check #{library}'s modules" unless answers.size == nestings.size + 2
+      return answers.map(&:chomp).freeze if answers.size == nestings.size + 2
+
+      # rubocop:disable-next Style/SpecialGlobalVars -- RBS types $?, and has no English for $CHILD_STATUS
+      unchecked(nestings, "their Ruby ended: #{$?}")
+    rescue SystemCallError => e
+      # a refusal, not a raw Errno, which Bundler would report as its own bug
+      unchecked(nestings, e.message)
+    end
+
+    private_class_method def self.unchecked(nestings, why)
+      raise Error, "could not check #{nestings.last} against its tools: #{why}"
+    end
+
+    # Its lib/<path>.rb, first on the load path, must not shadow a library its tools may require:
+    # this Ruby's (lib/json.rb, JSON's), a gem's they load too; its tests' classes, Minitest::Test's,
+    # and its gemspec, which `gem build` evaluates in Gem::Specification, must find its module, not
+    # one of theirs (`lifecycle_hooks`: Minitest::Test::LifecycleHooks).
+    private_class_method def self.check_shadowing(name, shadowed, found)
+      raise Error, "invalid gem name #{name}: its lib/#{path(name)}.rb would shadow #{shadowed}" unless shadowed.empty?
+      raise Error, "invalid gem name #{name}: #{found} for its module" unless found.empty?
+    end
+
+    # The +defined+ nestings, outermost first, each with its class: the gem's own module, +innermost+,
+    # one defined already (Comparable) would reopen; an outer one that is a class (Set, Logger), it
+    # could not open.
+    private_class_method def self.check_defined(name, defined, innermost)
+      raise Error, "invalid gem name #{name}: #{innermost} is already defined" if defined.last&.first == innermost
+
+      outer = defined.find { |_, kind| kind != "Module" }
+      raise Error, "invalid gem name #{name}: #{outer[0]} is a #{outer[1]}, not a module" if outer
+    end
+
+    # The gem's top-level library: `date-holidays`' date
+    private_class_method def self.library_of(name) = name.split("-").fetch(0)
 
-      answers.map(&:chomp)
+    # Each of its modules' full names, outermost first: `my-gem`'s My, My::Gem.
+    private_class_method def self.nestings_of(name)
+      modules(name).then { |modules| (1..modules.size).map { modules.first(it).join("::") } }
     end
   end
 end

data/lib/veragem/options.rb

@@ -1,53 +1,139 @@
 # frozen_string_literal: true
 
+require "open3"
 require "optparse"
 
 module Veragem
   # The command line, read into a Project; git's config gives the author, the email and the GitHub
-  # user, as `bundle gem` reads them.
+  # user, as `bundle gem` reads them. With a terminal for input, what no option gives is asked for.
   module Options
+    # The values git's config gives, and their keys there.
     GIT_CONFIG = { author: "user.name", email: "user.email", github: "github.user" }.freeze
+    # The values no option and no git config need give.
+    DEFAULTS = { summary: "A Ruby gem.", license: "dual" }.freeze
+    # --help's first lines.
+    BANNER = "Usage: bundle veragem NAME [options]\n" \
+             "With a terminal for input, what no option gives (the name too) is asked for."
+    # Each option and its --help, in --help's order.
+    OPTIONS = [
+      ["--[no-]exe", "Add a command line, exe/NAME (default: --no-exe, a library alone)"],
+      ["--license=LICENSE", "#{License::CHOICES} (MIT OR Apache-2.0, the default)"],
+      ["--author=NAME", "The author (default: git config user.name, else required)"],
+      ["--[no-]email=EMAIL", "The author's email (default: git config user.email; --no-email, none)"],
+      ["--github=USER", "The GitHub user or organization (default: git config github.user, else required)"],
+      ["--summary=TEXT", "The gem's summary (default: A Ruby gem.)"],
+      ["--[no-]citation", "Add CITATION.cff, the citation GitHub and Zenodo read (default: --no-citation)"],
+      ["--family-names=NAMES", "With --citation: the author's family names (required)"],
+      ["--[no-]given-names=NAMES", "With --citation: the author's given names (--no-given-names: none, unasked)"],
+      ["--[no-]alias=ALIAS", "With --citation: the author's alias, as a handle (--no-alias: none, unasked)"],
+      ["--orcid=ID", "With --citation: the author's ORCID iD"],
+      ["--keywords=LIST", "With --citation: keywords, comma-separated"]
+    ].freeze #: Array[[String, String]]
+    private_constant :GIT_CONFIG, :DEFAULTS, :BANNER, :OPTIONS
 
-    def self.parse(argv, config: ->(key) { git_config(key) })
-      values = GIT_CONFIG.transform_values { config.call(it) }
-      # an argument of invalid UTF-8 as bytes, as git's values are: OptionParser's matching raises on
-      # it, Project refuses it
-      names = parser.permute(argv.map { it.valid_encoding? ? it : it.b }, into: values)
-      raise Error, "one gem name, not #{names.size} (bundle veragem --help)" unless names.size == 1
-
+    # The Project +argv+ gives, what it does not asked of +input+ when a terminal, the questions on
+    # +output+ (stderr, as a prompt is): at a terminal the name checked for +dir+ before any question,
+    # the generation's check otherwise.
+    # @param argv [Array<String>] the command's arguments
+    # @param dir [String] where the gem is to be generated
+    # @param config [#call] a git config key's value, nil when unset
+    # @param input [#gets, #tty?] where the answers are typed; asked only when a terminal
+    # @param output [#print, #puts] where the questions are shown
+    # @return [Veragem::Project]
+    # @raise [Veragem::Error] an argument or a value is refused, or a question has no answer
+    def self.parse(argv, dir: Dir.pwd, config: ->(key) { git_config(key) }, input: $stdin, output: $stderr)
+      names, given = arguments(argv)
+      defaults = { **DEFAULTS, **GIT_CONFIG.transform_values(&config).compact }
       # rubocop:disable-next Lint/NameTypo -- the project index lacks Class#new, and takes Project#nest for it
-      Project.new(names.fetch(0), { summary: "A Ruby gem.", license: "dual", **given(values) })
+      return Project.new(name_of(names), required(defaults, given)) unless input.tty?
+
+      ask(names, given, defaults, Questions.new(input, output, dir, git: GIT_CONFIG))
     rescue OptionParser::ParseError => e
-      raise Error, "#{e.message} (bundle veragem --help)"
+      raise Error, "#{e} (bundle veragem --help)"
+    end
+
+    # The names and the options given, each value checked as Project checks it: before the name, and
+    # any question.
+    private_class_method def self.arguments(argv)
+      given = {} #: Hash[Symbol, String | bool]
+      # an argument of invalid UTF-8 as bytes: OptionParser's matching raises on it, Project refuses it
+      names = parser.permute(argv.map { it.valid_encoding? ? it : it.b }, into: given)
+      # OptionParser keys --given-names as :"given-names"; Project's are :given_names
+      given.transform_keys! { it.name.tr("-", "_").to_sym }
+      # each value as Project checks it (a text's UTF-8 and stripped): the questions compare them with
+      # their answers
+      checked = given.to_h { |key, value| [key, value.is_a?(String) ? checked(key, value) : value] }
+      Citation.check_values(checked, checked[:citation] == true) if checked.key?(:citation)
+      [names, checked]
+    end
+
+    # +value+ as Project checks it; but "-", a question's none, is no option's value, as no answer
+    # can give it.
+    private_class_method def self.checked(key, value)
+      none = Project::OPTIONAL[key]
+      if none && Questions.none?(value)
+        raise Error, %(invalid #{Project.field(key)} "-": a question's none; for none, #{none})
+      end
+
+      Project.check(key, value)
     end
 
-    # The values set, the author and the GitHub user required.
-    def self.given(values)
-      %i[author github].each { raise Error, "no #{it}: --#{it}, or git config #{GIT_CONFIG[it]}" unless values[it] }
-      values.compact
+    # From a terminal: the names counted, as without one, then the name checked before any question.
+    private_class_method def self.ask(names, given, defaults, questions)
+      # a citation's values given, the citation's question takes y alone: the name is checked for one
+      citation = given[:citation] == true || Citation.cited?(given)
+      name = questions.name((name_of(names) unless names.empty?), exe: given[:exe] == true, citation:)
+      # rubocop:disable-next Lint/NameTypo -- the project index lacks Class#new, and takes Project#nest for it
+      Project.new(name, questions.values(name, given, defaults))
     end
 
-    def self.parser
-      OptionParser.new("Usage: bundle veragem NAME [options]") do |opts|
+    private_class_method def self.name_of(names)
+      return names.fetch(0) if names.size == 1
+      raise Error, "no gem name (bundle veragem --help)" if names.empty?
+
+      raise Error, "one gem name, not #{names.size} (bundle veragem --help)"
+    end
+
+    # The options' values, and git's where none is given: one of git's refused says so, and which
+    # options replace it, as a missing author or GitHub user does.
+    private_class_method def self.required(defaults, given)
+      GIT_CONFIG.except(*given.keys).each do |key, name|
+        value = defaults[key] or next
+        Project.check(key, value)
+      rescue Error => e
+        replaced = ["--#{key}", Project::OPTIONAL[key]].compact.join(" or ")
+        raise Error, "#{e} (git config #{name}; #{replaced} replaces it)"
+      end
+      values = defaults.merge(given) #: Hash[Symbol, String | bool | nil]
+      check_present(values)
+      values #: Project::values
+    end
+
+    # The author and the GitHub user, which nothing but git defaults.
+    private_class_method def self.check_present(values)
+      %i[author github].each do |key|
+        raise Error, "no #{Project.field(key)}: --#{key}, or git config #{GIT_CONFIG[key]}" unless values[key]
+      end
+    end
+
+    private_class_method def self.parser
+      OptionParser.new(BANNER) do |opts|
         opts.program_name = "bundle veragem"
         opts.version = VERSION
-        opts.on("--exe", "Add a command line, exe/NAME")
-        opts.on("--license=LICENSE", Project::LICENSES.keys, "mit, apache or dual (MIT OR Apache-2.0, the default)")
-        opts.on("--author=NAME", "The author (default: git config user.name)")
-        opts.on("--email=EMAIL", "The author's email (default: git config user.email)")
-        opts.on("--github=USER", "The GitHub user or organization (default: git config github.user)")
-        opts.on("--summary=TEXT", "The gem's summary (default: A Ruby gem.)")
+        OPTIONS.each { |switch, help| opts.on(switch, help) }
       end
     end
 
-    # A git config value, nil when unset or git is missing: its bytes, which Project reads as UTF-8
-    # whatever the locale.
-    def self.git_config(key)
-      command = ["git", "config", "--get", key]
-      value = IO.popen(command, err: File::NULL, external_encoding: Encoding::BINARY, &:read).strip
-      value unless value.empty?
-    rescue SystemCallError
-      nil
+    # A git config value, nil when unset (status 1): its bytes as UTF-8, whatever the locale, which
+    # Project refuses unless valid. A git that cannot run, or cannot read its config, is refused here,
+    # with git's reason, before a missing value would be blamed on the config.
+    private_class_method def self.git_config(key)
+      value, error, status = Open3.capture3("git", "config", "--get", key, binmode: true)
+      raise Error, "git config --get #{key}: #{error.strip}" unless status.success? || status.exitstatus == 1
+
+      value.strip.force_encoding(Encoding::UTF_8).then { it unless it.empty? }
+    rescue SystemCallError => e
+      raise Error, "cannot run git: #{e}"
     end
   end
 end