veragem 0.1.0 → 0.2.0

data/lib/veragem/project.rb

@@ -1,77 +1,238 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Veragem
   # The gem to generate: the values given, checked, and what follows from them.
   class Project
-    # GitHub's rule for a user or organization name.
-    GITHUB = /\A[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}\z/i
-    # Each choice's SPDX identifiers: the gemspec's licenses, the LICENSE-* files.
-    LICENSES = { "mit" => ["MIT"], "apache" => ["Apache-2.0"], "dual" => ["MIT", "Apache-2.0"] }.freeze
+    # GitHub's rule for a user or organization name: ASCII's letters, which /i would widen to Unicode's
+    # (ſ, the Kelvin sign).
+    GITHUB = /\A[a-zA-Z\d](?:[a-zA-Z\d]|-(?=[a-zA-Z\d])){0,38}\z/
+    # Each value a refusal names otherwise than its key.
+    FIELDS = { github: "GitHub user", license: "license (#{License::CHOICES})", orcid: "ORCID iD" }.freeze
+    # What Markdown would read as markup in a text: a character to escape, but an `_` within a word;
+    # and a URL's `://` or `www.`, which GFM would link, its escapes shown.
+    MARKUP = %r{[\\`*\[\]<~$] | (?<![[:alnum:]])_ | _(?![[:alnum:]]) | &(?=\#?[[:alnum:]]+;) | :(?=//) | (?<=www)\.}x
+    # The values that may be none, and how an option gives none: a question takes "-".
+    OPTIONAL = { email: "--no-email", given_names: "--no-given-names", alias: "--no-alias",
+                 orcid: "leave --orcid out", keywords: "leave --keywords out" }.freeze
+    private_constant :GITHUB, :FIELDS, :MARKUP
+
+    # The gem's name.
+    # @return [String]
+    attr_reader :name
+    # Its author.
+    # @return [String]
+    attr_reader :author
+    # The author's email, none nil.
+    # @return [String, nil]
+    attr_reader :email
+    # The GitHub user or organization.
+    # @return [String]
+    attr_reader :github
+    # Its summary.
+    # @return [String]
+    attr_reader :summary
+    # Its licence's choice: mit, apache or dual.
+    # @return [String]
+    attr_reader :license
+    # Whether it has a command line.
+    # @return [Boolean]
+    attr_reader :exe
+    # Whether it has CITATION.cff.
+    # @return [Boolean]
+    attr_reader :citation
+    # CITATION.cff's given names, none nil.
+    # @return [String, nil]
+    attr_reader :given_names
+    # CITATION.cff's family names, nil without a citation.
+    # @return [String, nil]
+    attr_reader :family_names
+    # CITATION.cff's alias, none nil.
+    # @return [String, nil]
+    attr_reader :alias_name
+    # CITATION.cff's ORCID iD, its URL; none nil.
+    # @return [String, nil]
+    attr_reader :orcid
+    # CITATION.cff's keywords, none nil.
+    # @return [Array<String>, nil]
+    attr_reader :keywords
+
+    # The value +key+ names, as a refusal names it: `GitHub user` :github, `given names` :given_names.
+    # @param key [Symbol] a value's
+    # @return [String]
+    def self.field(key) = FIELDS.fetch(key) { key.name.tr("_", " ") }
+
+    # +text+ without the spaces around it, Unicode's too (String#strip's are ASCII's alone).
+    # @param text [String]
+    # @return [String]
+    def self.strip(text) = text.gsub(/\A[[:space:]]+|[[:space:]]+\z/, "")
 
-    attr_reader :name, :author, :email, :github, :summary, :license, :exe
+    # +value+ as a Ruby string literal, as written whatever the locale (String#inspect escapes
+    # what the locale cannot show): a quote, a backslash and an interpolation escaped.
+    # @param value [String] a value of the gem's, checked
+    # @return [String]
+    def self.quote(value) = %("#{value.gsub(/["\\]|#(?=[{$@])/) { "\\#{it}" }}")
+
+    # The value +key+ takes, an option's or an answer's: checked, or an Error saying why not.
+    # @param key [Symbol] :author, :email, :github, :summary, :license, :given_names, :family_names,
+    #   :alias, :orcid or :keywords
+    # @param value [String, nil] as given; nil, none, is refused as "" is
+    # @return [String] the value kept: a licence its choice (`MIT` mit, `Apache-2.0` apache), an ORCID
+    #   iD its URL, keywords joined by ", "
+    # @raise [Veragem::Error] +key+ cannot take it
+    def self.check(key, value)
+      value = utf8(key, value)
+      return Citation.check(key, value) { |name, text| line(name, text) } if Citation::KEYS.include?(key)
+
+      case key
+      when :github then github(strip(value))
+      when :license then License.check(strip(value))
+      when :summary then Summary.check(text(field(key), value))
+      else text(field(key), value)
+      end
+    end
 
-    # +name+, and +values+: the author, email, github, summary and license (strings), exe (true or
-    # absent), as Options reads them.
+    # +name+, and +values+: the author, email, github, summary, license and a citation's given and
+    # family names, alias, ORCID iD and keywords (strings, but an email, given names or alias false,
+    # --no-email's, --no-given-names', --no-alias', or nil for none), exe and citation (true for a
+    # command line, for CITATION.cff), as Options reads them.
+    # @param name [String] the gem's name, as given
+    # @param values [Hash{Symbol => String, Boolean, nil}] the rest, as given
+    # @return [void]
+    # @raise [Veragem::Error] a value is refused
     def initialize(name, values)
       @name = Name.check(name)
-      @author = text("author", values[:author])
-      @email = values[:email] && text("email", values[:email])
-      @github = valid("GitHub user", values[:github]) { GITHUB.match?(it) }
-      @summary = text("summary", values[:summary])
-      @license = valid("license (mit, apache or dual)", values[:license]) { LICENSES.key?(it) }
-      @exe = values[:exe] == true
+      @author = Project.check(:author, values[:author])
+      @email = optional(:email, values[:email])
+      @github = Project.check(:github, values[:github])
+      @summary = Project.check(:summary, values[:summary])
+      @license = Project.check(:license, values[:license])
+      extras(values)
     end
 
-    # The file the gem requires: `my-gem`'s is my/gem.
-    def path = name.tr("-", "/")
+    # The file the gem requires, lib/'s: `my-gem`'s my/gem.
+    # @return [String]
+    def path = Name.path(name)
 
-    def underscored = name.tr("-", "_")
+    # Its name, its words joined by `_` alone: its test's file name.
+    # @return [String]
+    def underscored = Name.underscored(name)
 
     # Its module, as `bundle gem` names it.
+    # @return [String]
     def constant = modules.join("::")
 
+    # Its modules, outermost first.
+    # @return [Array<String>]
     def modules = Name.modules(name)
 
-    def licenses = LICENSES.fetch(license)
+    # The SPDX identifiers of its licence.
+    # @return [Array<String>]
+    def licenses = License::SPDX.fetch(license)
 
+    # The copyright's year: this one.
+    # @return [Integer]
     def year = Time.now.year
 
-    # +value+ as a Ruby string literal, as written whatever the locale (String#inspect escapes
-    # what the locale cannot show): a quote, a backslash and an interpolation escaped.
-    def quote(value) = %("#{value.gsub(/["\\]|#(?=[{$@])/) { "\\#{it}" }}")
+    # Today in UTC, as CFF writes a date: CITATION.cff's date-released until `rake bump` sets a
+    # release's, UTC's too.
+    # @return [String]
+    def today = Time.now.utc.strftime("%F")
+
+    # +value+ as a YAML double-quoted string: JSON's, which YAML reads alike.
+    # @param value [String] a value of the gem's, checked
+    # @return [String]
+    def yaml(value) = JSON.generate(value)
+
+    # +value+ as Markdown's text, shown as written, as RubyGems shows a summary: its markup escaped,
+    # one space between words, as dprint writes them.
+    # @param value [String] a value of the gem's, checked
+    # @return [String]
+    def markdown(value)
+      escaped = value.squeeze(" ").gsub(MARKUP) { "\\#{it}" }
+      escaped.sub(/\A(?=[#>+-])|\A\d+\K(?=[.)])/) { "\\" }
+    end
 
-    # +body+ inside the gem's modules, each nested and indented, +doc+ a comment on the innermost.
+    # Project.quote, for the templates.
+    # @param value [String] a value of the gem's, checked
+    # @return [String]
+    def quote(value) = Project.quote(value)
+
+    # +body+ inside the gem's modules, each nested and indented, +doc+ a comment on the innermost and
+    # the outer ones each a namespace's: one file documents them, as YARD would have it.
+    # @param body [String] Ruby code
+    # @param doc [String, nil] the comment
+    # @return [String]
     def nest(body, doc: nil)
       *outer, inner = modules
       code = "#{"# #{doc}\n" if doc}module #{inner}\n#{indent(body)}end\n"
-      outer.reverse.reduce(code) { |nested, mod| "module #{mod}\n#{indent(nested)}end\n" }
+      outer.reverse.reduce(code) do |nested, mod|
+        "#{"# The namespace of #{constant}.\n" if doc}module #{mod}\n#{indent(nested)}end\n"
+      end
     end
 
-    private
+    # +value+'s bytes as UTF-8, whatever their encoding (an argument's are binary where the locale's
+    # encoding cannot read them), refused unless valid: every check after it takes valid UTF-8.
+    # None (nil) is "", which each check refuses.
+    private_class_method def self.utf8(key, value)
+      value = value.to_s.dup.force_encoding(Encoding::UTF_8)
+      raise Error, "invalid #{field(key)} #{value.inspect}: not UTF-8" unless value.valid_encoding?
 
-    def indent(code) = code.gsub(/^(?=.)/, "  ")
+      value
+    end
 
-    def valid(field, value)
-      raise Error, "invalid #{field} #{value.inspect}" unless yield value
+    private_class_method def self.github(value)
+      return value if GITHUB.match?(value)
 
-      value
+      raise Error, "invalid #{field(:github)} #{value.inspect}: 1 to 39 ASCII letters, digits and inner single hyphens"
     end
 
-    # A value a file quotes: one line of valid UTF-8, its surrounding spaces stripped (Unicode's too),
-    # short enough for the gemspec's line (RuboCop's 120 columns), which RubyGems does not refuse as
-    # unfinished.
-    def text(field, value)
-      value = value.dup.force_encoding(Encoding::UTF_8)
-      one_line = value.valid_encoding? && !value.match?(/[[:cntrl:]\u2028\u2029]/)
-      line = one_line ? value.gsub(/\A[[:space:]]+|[[:space:]]+\z/, "") : ""
-      raise Error, "invalid #{field} #{value.inspect}: one line of text" if line.empty?
+    # A value the gemspec quotes: short enough for its line (RuboCop's 120 columns), and not one
+    # RubyGems refuses as unfinished.
+    private_class_method def self.text(field, value)
+      line = line(field, value)
       raise Error, "invalid #{field}: too long, its Ruby string at most 100 characters" if quote(line).length > 100
-      if line.match?(/\A(TODO|FIXME)/)
-        raise Error,
-              "invalid #{field} #{line.inspect}: RubyGems refuses one starting TODO or FIXME"
-      end
+      return line unless line.match?(/\A(TODO|FIXME)/)
+
+      raise Error, "invalid #{field} #{line.inspect}: RubyGems refuses one starting TODO or FIXME"
+    end
+
+    # One line, its surrounding spaces stripped (Unicode's too). U+FFFE and U+FFFF are outside YAML's
+    # printable characters: CITATION.cff's.
+    private_class_method def self.line(field, value)
+      line = value.match?(/[[:cntrl:]\u2028\u2029\uFFFE\uFFFF]/) ? "" : strip(value)
+      raise Error, "invalid #{field} #{value.inspect}: one line of text" if line.empty?
 
       line
     end
+
+    private
+
+    # What the gem holds beyond the library: a command line, a citation.
+    def extras(values)
+      @exe = values[:exe] == true
+      @citation = values[:citation] == true
+      Citation.check_values(values, citation)
+      cite(values) if citation
+    end
+
+    # CITATION.cff's author is a person: the family names it needs, the rest it may have.
+    def cite(values)
+      family = values[:family_names]
+      raise Error, "no family names: --family-names, CITATION.cff's author" unless family
+
+      @given_names = optional(:given_names, values[:given_names])
+      @family_names = Project.check(:family_names, family)
+      @alias_name = optional(:alias, values[:alias])
+      @orcid = optional(:orcid, values[:orcid])
+      @keywords = optional(:keywords, values[:keywords])&.split(", ")
+    end
+
+    # A value OPTIONAL names: none, false or nil, is nil.
+    def optional(key, value) = (Project.check(key, value) if value)
+
+    # a blank line left blank, no trailing spaces
+    def indent(code) = code.gsub(/^(?=.)/, "  ")
   end
 end

data/lib/veragem/questions.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Veragem
+  # A terminal's questions for what no option gives: each offers its default, which an empty answer
+  # takes, and is asked again until the answer passes the check the project's value would.
+  class Questions
+    # Each value's question, in the order asked; the name's comes first.
+    QUESTIONS = {
+      exe: "A command line, exe/%<name>s (y/n)",
+      citation: "A citation file, CITATION.cff (y/n)",
+      license: "License (#{License::CHOICES})",
+      summary: "Summary",
+      author: "Author",
+      family_names: "Family names, CITATION.cff's",
+      given_names: "Given names, CITATION.cff's",
+      orcid: "ORCID iD, CITATION.cff's",
+      keywords: "Keywords, comma-separated, CITATION.cff's",
+      email: "Email",
+      github: "GitHub user",
+      alias: "Alias, CITATION.cff's"
+    }.freeze
+    private_constant :QUESTIONS
+
+    # Whether +text+ is "-", an optional question's none, its spaces around it stripped as a value's
+    # are (Project.strip).
+    # @param text [String] an answer or an option's value, its bytes as given
+    # @return [Boolean]
+    def self.none?(text)
+      text = text.dup.force_encoding(Encoding::UTF_8)
+      text.valid_encoding? && Project.strip(text) == "-"
+    end
+
+    # Questions on +output+, answered on +input+, for a gem generated into +dir+.
+    # @param input [#gets, #tty?] where the answers are typed
+    # @param output [#print, #puts] where the questions are shown
+    # @param dir [String] where the gem is to be generated
+    # @param git [Hash{Symbol => String}] each value's git config key, which a refusal of the default
+    #   git gives names
+    # @return [void]
+    def initialize(input, output, dir, git: {})
+      @input = input
+      @output = output
+      @dir = dir
+      @git = git
+    end
+
+    # The name, +given+ or else asked for: checked as far as it, +exe+ and +citation+ decide, before
+    # the rest.
+    # @param given [String, nil] the name the arguments give
+    # @param exe [Boolean] whether --exe is given
+    # @param citation [Boolean] whether --citation, or a citation's value, is given
+    # @return [String]
+    # @raise [Veragem::Error] +given+ is refused, nothing is answered, or the terminal cannot be asked
+    def name(given, exe:, citation:)
+      return check_name(given, exe, citation) if given
+
+      ask("Gem name", check: -> { check_name(it, exe, citation) }) #: String
+    end
+
+    # +given+ (the options) and the answers to the rest, +defaults+ offered; a citation's values asked
+    # only for a citation, the author's words offered for its names, the GitHub user for its alias.
+    # @param name [String] the gem's, checked
+    # @param given [Hash{Symbol => String, Boolean}] the options' values
+    # @param defaults [Hash{Symbol => String}] git's and Options' own
+    # @return [Hash{Symbol => String, Boolean, nil}] a value for each key asked, nil for none
+    # @raise [Veragem::Error] nothing is answered, or the terminal cannot be asked
+    def values(name, given, defaults)
+      values = given.dup #: Hash[Symbol, String | bool | nil]
+      QUESTIONS.except(*given.keys).each do |key, question|
+        next if Citation::KEYS.include?(key) && values[:citation] != true
+
+        check = -> { answer(key, it, name, values) }
+        offer = default(key, defaults, values)
+        values[key] = ask(format(question, name:), offer,
+                          from: source(key), check:, optional: Project::OPTIONAL.key?(key))
+      end
+      values #: Project::values
+    end
+
+    private
+
+    def check_name(name, exe, citation) = Generator.check(name, exe:, citation:, target: File.join(@dir, name))
+
+    def answer(key, text, name, values)
+      case key
+      when :exe then yes?(text).tap { Generator.check_name(name, it) }
+      when :citation
+        yes?(text).tap do |cited|
+          Citation.check_values(values, cited)
+          Citation.check_name(name, cited)
+        end
+      else Project.check(key, text)
+      end
+    end
+
+    # The answer, or the default, through +check+; asked again, saying why, when there is neither, or
+    # the check fails, but an +optional+ one is nil -- and "-" its none, which a default would take
+    # otherwise.
+    def ask(question, default = nil, check:, from: "the default", optional: false)
+      default = offered(question, default, from, check)
+      loop do
+        reply = read(question, default, optional) || default
+        return if optional && (reply.nil? || Questions.none?(reply))
+
+        value = reply.nil? ? unanswered(question) : checked(question, reply, check)
+        return value unless value.nil?
+      end
+    end
+
+    # +default+ if it passes +check+: one refused, said why and where it is from, is not offered.
+    def offered(question, default, from, check)
+      default unless default.nil? || checked(question, default, check, " (#{from}, not offered)").nil?
+    end
+
+    # A line's text, nil when empty: its bytes as UTF-8 (whatever the locale's encoding), or as bytes
+    # where they are no UTF-8, as an argument's; stripped after, as Project strips a value.
+    def read(question, default, optional)
+      line = terminal(question) do
+        @output.print "#{question}#{" (- for none)" if optional}#{" [#{default}]" if default}: "
+        @input.gets.tap { @output.puts unless it }
+      end
+      raise Error, "no answer to #{question}" unless line
+
+      text = line.dup.force_encoding(Encoding::UTF_8)
+      answer = Project.strip(text.valid_encoding? ? text : text.b)
+      answer unless answer.empty?
+    end
+
+    # neither an answer nor a default: said so, and nil, as a refusal is
+    def unanswered(question)
+      terminal(question) { @output.puts "an answer is required" }
+      nil
+    end
+
+    def checked(question, answer, check, note = "")
+      check.call(answer)
+    rescue Error => e
+      terminal(question) { @output.puts "#{e}#{note}" }
+      nil
+    end
+
+    # The block's reading or writing of the terminal: one that fails cannot ask +question+, unlike a
+    # check's own failure.
+    def terminal(question)
+      yield
+    rescue SystemCallError, IOError, EncodingError => e
+      raise Error, "cannot ask #{question}: #{e}"
+    end
+
+    def yes?(answer)
+      case answer.downcase
+      in "y" | "yes" then true
+      in "n" | "no" then false
+      else raise Error, "y or n"
+      end
+    end
+
+    def default(key, defaults, values) = Citation.default(key, values) || { exe: "n", **defaults }[key]
+
+    # where a default is from, as a refusal of it says
+    def source(key) = @git[key] ? "git config #{@git[key]}" : "the default"
+  end
+end

data/lib/veragem/summary.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Veragem
+  # The gem's summary, which is its module's comment too: one the gem's own yard-lint and RuboCop take
+  # as its documentation.
+  module Summary
+    # What YARD reads as a tag first in a comment: its own (`@param`, `(see`), and those yard-lint
+    # (.yard-lint.yml) takes for one written informally.
+    TAG = /\A(?:@|\(see\b|(?:note|important|todo|fixme|see(?:\ also)?|warning|deprecated|author|version|since
+            |returns|raises|example):)/xi
+    # A RuboCop annotation, no documentation, as its AnnotationComment reads one: a keyword first, then
+    # a colon, spaces before it or not, or a space -- but a sentence's capitalized first word, a word
+    # after it (a summary, stripped, has one after a space).
+    ANNOTATION = /\A(todo|fixme|optimize|hack|review|note)\b(\s*:)?(\s+)?/i
+    # A magic comment -- an encoding's anywhere, lower-case (Ruby's rule); Ruby's others first (past
+    # the ' " : ; it skips) or within -*-, in any case, `-` for `_` (a frozen string literal's after
+    # code, a warning: one the tests raise) -- or a RuboCop directive, which would turn its cops off,
+    # or fail them.
+    MAGIC = /\b(?:en)?coding\s*[:=]|(?:\A['":;\s]*|-\*-.*)(?i:(?:frozen[_-]string[_-]literal|warn[_-]indent|
+             shareable[_-]constant[_-]value)\s*:)|(?i:\brubocop\s*:)/x
+    # What yard-lint's Markdown and text checks refuse: a list marker (• ·) or a code block's fence
+    # first, an em or en dash outside code (.yard-lint.yml's TextSubstitution).
+    MARKDOWN = /\A(?:[•·]|```)/
+    DASH = /[—–]/
+    private_constant :TAG, :ANNOTATION, :MAGIC, :MARKDOWN, :DASH
+
+    # +summary+, refused where it holds a tag, an annotation, a magic comment or Markdown yard-lint
+    # refuses, or leaves a backtick or bold open -- a `**` outside code with a non-space beside it, as
+    # yard-lint counts (`x ** 2` is no bold).
+    # @param summary [String] one line of text, as Project.check passes it
+    # @return [String] +summary+
+    # @raise [Veragem::Error] the gem's yard-lint or RuboCop would not take it
+    def self.check(summary)
+      why = refusal(summary)
+      raise Error, "invalid summary #{summary.inspect}: #{why}" if why
+
+      summary
+    end
+
+    private_class_method def self.refusal(summary)
+      return "YARD would read a tag" if summary.match?(TAG)
+      return "RuboCop or Ruby would read an annotation or a directive" if annotation?(summary) || summary.match?(MAGIC)
+      return "yard-lint would refuse its Markdown" if summary.match?(MARKDOWN) || prose(summary).match?(DASH)
+
+      "a backtick or ** left open" if left_open?(summary)
+    end
+
+    private_class_method def self.left_open?(summary)
+      summary.count("`").odd? || prose(summary).scan(/(?<=\S)\*\*|\*\*(?=\S)/).size.odd?
+    end
+
+    # Its code's spans aside, as yard-lint reads the prose.
+    private_class_method def self.prose(summary) = summary.gsub(/`[^`]*`/, "")
+
+    private_class_method def self.annotation?(summary)
+      keyword, colon, space = summary.match(ANNOTATION)&.captures
+      return false unless keyword && (colon || space)
+
+      !(keyword == keyword.capitalize && !colon)
+    end
+  end
+end

data/lib/veragem/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Veragem
-  VERSION = "0.1.0"
+  # The plugin's version.
+  VERSION = "0.2.0"
 end

data/lib/veragem.rb

@@ -3,7 +3,11 @@
 require "bundler"
 require_relative "veragem/version"
 require_relative "veragem/name"
+require_relative "veragem/citation"
+require_relative "veragem/license"
+require_relative "veragem/summary"
 require_relative "veragem/project"
+require_relative "veragem/questions"
 require_relative "veragem/options"
 require_relative "veragem/generator"
 
@@ -12,9 +16,14 @@ module Veragem
   # A refusal: Bundler prints its message alone, and exits with its status.
   class Error < Bundler::PluginError; end
 
-  # Generates the gem +argv+ names into +dir+; returns its directory.
-  def self.run(argv, dir: Dir.pwd)
-    project = Options.parse(argv)
+  # Generates the gem +argv+ names into +dir+, what no option gives asked of +input+ when a terminal.
+  # @param argv [Array<String>] the command's arguments
+  # @param dir [String] where the gem is to be generated
+  # @param input [#gets, #tty?] where the answers are typed
+  # @return [String] the gem's directory
+  # @raise [Veragem::Error] veragem refuses
+  def self.run(argv, dir: Dir.pwd, input: $stdin)
+    project = Options.parse(argv, dir:, input:)
     target = File.join(dir, project.name)
     Generator.generate(project, target)
     puts "Created #{project.name}. Next: cd #{project.name} && bin/setup (CONTRIBUTING.md's first steps)"

data/plugins.rb

@@ -8,6 +8,10 @@ module Veragem
   class Command < Bundler::Plugin::API
     command "veragem"
 
+    # Runs `bundle veragem ARGS`.
+    # @param _command [String] "veragem"
+    # @param args [Array<String>] the command's arguments
+    # @return [String] the gem's directory
     def exec(_command, args)
       Veragem.run(args)
     end