monkrb 0.19.0 → 0.21.0

data/lib/monk/generator/definition.rb

@@ -0,0 +1,153 @@
+module Monk
+  module Generator
+    # One module's generator, as `Monk::Generator.define(:jobs) { ... }`
+    # declares it. Only declarations: Run decides what they mean for a given
+    # app, and writes nothing until it has checked every file.
+    class Definition
+      Copy = Data.define(:path, :from, :role, :executable, :condition)
+      Migration = Data.define(:name)
+      Env = Data.define(:file, :key, :value, :commented)
+      Option = Data.define(:name, :values, :infer_from, :describe, :default)
+      Service = Data.define(:name, :check, :setup)
+      Step = Data.define(:text, :note, :needs_service, :condition)
+      Example = Data.define(:tag, :todo)
+      Production = Data.define(:key, :note, :placeholder)
+
+      # What a role means when the file already exists with other content:
+      # a wiring file stops the whole command, anything else is skipped
+      # (docs/history/plan-scaffold.md decision 26).
+      ROLES = %i[wiring example test view demo].freeze
+
+      # Which .env file each env group appends to.
+      ENV_FILES = { development: ".env", test: ".env.test", example: ".env.example" }.freeze
+
+      attr_reader :name, :copies, :migrations, :gems, :envs, :ignores, :options, :services, :steps,
+        :examples, :productions, :sections
+
+      def initialize(name)
+        @name = name.to_sym
+        @summary = ""
+        @dependencies = []
+        @option_dependencies = []
+        @installed_if = "config/#{name}.rb"
+        @copies = []
+        @migrations = []
+        @gems = []
+        @envs = []
+        @ignores = []
+        @options = []
+        @services = []
+        @steps = []
+        @examples = []
+        @productions = []
+        @sections = {}
+        @closing = nil
+      end
+
+      def summary(text = nil)
+        return @summary if text.nil?
+
+        @summary = text
+      end
+
+      # Modules this one needs, added first when they're missing.
+      def depends_on(*names)
+        @dependencies.concat(names.map(&:to_sym))
+      end
+
+      # A choice the user makes (websocket's transport). It's inferred when
+      # exactly one of `infer_from` is installed or being added, and the
+      # chosen value is a dependency when `dependency: true`. An option with
+      # a `default:` (live's demo) is never inferred.
+      def option(name, values:, infer_from: values, dependency: false, describe: {}, default: nil)
+        @options << Option.new(name: name.to_sym, values: values.map(&:to_s), infer_from: infer_from.map(&:to_s),
+          describe: describe.transform_keys(&:to_s), default: default&.to_s,)
+        @option_dependencies << name.to_sym if dependency
+      end
+
+      # The file whose existence means this module is installed.
+      def installed_if(path = nil)
+        return @installed_if if path.nil?
+
+        @installed_if = path
+      end
+
+      # A file copied verbatim from templates/<module>/<path>, or from
+      # `from:`, a template path or a block taking the options. `if:`, a
+      # block taking the options, decides whether it's copied at all.
+      def copy(*paths, role:, from: nil, executable: false, if: nil)
+        raise ArgumentError, "unknown role #{role.inspect}, one of #{ROLES.inspect}" unless ROLES.include?(role)
+        raise ArgumentError, "from: needs a single path" if from && paths.size > 1
+
+        condition = binding.local_variable_get(:if)
+        paths.each do |path|
+          @copies << Copy.new(path: path, from: from, role: role, executable: executable, condition: condition)
+        end
+      end
+
+      # db/migrate/<timestamp>_<name>.{up,down}.sql, from the template
+      # migration named *_<name>.{up,down}.sql.
+      def migration(name)
+        @migrations << Migration.new(name: name)
+      end
+
+      # A line appended to the Gemfile unless that gem is already there.
+      def gem(line)
+        @gems << line
+      end
+
+      # A KEY=value line appended to one of the .env files unless KEY is
+      # already there (the app's own value wins). The value may be a block
+      # taking the app's name.
+      def env(file, values, commented: false)
+        raise ArgumentError, "unknown env file #{file.inspect}" unless ENV_FILES.key?(file)
+
+        values.each { |key, value| @envs << Env.new(file: file, key: key.to_s, value: value, commented: commented) }
+      end
+
+      # A line appended to .gitignore and .dockerignore unless it's there.
+      def ignore(line)
+        @ignores << line
+      end
+
+      def service(name, check:, setup:)
+        @services << Service.new(name: name.to_s, check: check, setup: setup)
+      end
+
+      # This module's section of SETUP.md or AGENTS.md: a template path.
+      def setup_section(path) = @sections[:setup] = path
+      def agents_section(path) = @sections[:agents] = path
+
+      def set_before_production(key, note, placeholder: false)
+        @productions << Production.new(key: key, note: note, placeholder: placeholder)
+      end
+
+      # A command (`bin/jobs`) or something to do; `note:` says what for.
+      def next_step(text, note: nil, needs_service: nil, if: nil)
+        @steps << Step.new(text: text, note: note, needs_service: needs_service&.to_s,
+          condition: binding.local_variable_get(:if),)
+      end
+
+      # What to do with an example block (`# monk:example <tag>`). `todo`
+      # may be a block taking the names of the installed modules.
+      def example(tag, todo:)
+        @examples << Example.new(tag: tag, todo: todo)
+      end
+
+      # The one thing that matters most after adding this module: a String,
+      # or a block taking the options.
+      def closing(text = nil)
+        return @closing if text.nil?
+
+        @closing = text
+      end
+
+      # The options whose value is a module to depend on (websocket's transport).
+      def dependency_options = @option_dependencies
+
+      def dependencies(options = {})
+        @dependencies + @option_dependencies.filter_map { |option| options[option]&.to_sym }
+      end
+    end
+  end
+end

data/lib/monk/generator/result.rb

@@ -0,0 +1,279 @@
+require "json"
+
+module Monk
+  module Generator
+    # What one `monk add` did, or would do: printed as text for a person
+    # (decision 25), as one JSON object with --json (decision 27), and
+    # turned into the exit code (decision 28) -- all from the same data.
+    class Result
+      EXIT_CODES = { ok: 0, usage_error: 1, missing_choice: 2, conflict: 3 }.freeze
+
+      # The text form's widest path column.
+      COLUMN = 30
+      # The text form's numbered steps; JSON keeps them all.
+      MAX_STEPS = 3
+
+      attr_reader :status, :written, :dry_run, :requested, :modules, :files, :skipped, :env, :examples, :services,
+        :next_steps, :docs, :closing, :message, :suggestion, :choice, :conflicts, :command
+
+      def initialize(status:, written:, dry_run: false, requested: [], modules: [], files: [], skipped: [], env: [],
+                     examples: [], services: [], next_steps: [], docs: [], closing: nil, message: nil, suggestion: nil,
+                     choice: nil, conflicts: [], command: nil)
+        @status = status
+        @written = written
+        @dry_run = dry_run
+        @requested = requested
+        @modules = modules
+        @files = files
+        @skipped = skipped
+        @env = env
+        @examples = examples
+        @services = services
+        @next_steps = next_steps
+        @docs = docs
+        @closing = closing
+        @message = message
+        @suggestion = suggestion
+        @choice = choice
+        @conflicts = conflicts
+        @command = command
+      end
+
+      def ok? = status == :ok
+      def exit_code = EXIT_CODES.fetch(status)
+
+      def to_h
+        hash = { status: status.to_s, written: written, requested: requested.map(&:to_s) }
+        if ok?
+          hash.merge!(
+            modules: modules.map { |entry| stringify(entry) },
+            files: files.map { |entry| file_json(entry) },
+            skipped: skipped.map { |entry| stringify(entry) },
+            env: env.map { |entry| stringify(entry.except(:module)) },
+            examples: examples.map { |entry| stringify(entry.except(:module)) },
+            services: services.map { |entry| stringify(entry) },
+            next: next_steps.map { |entry| stringify(entry) },
+            docs: docs,
+          )
+          hash[:dry_run] = true if dry_run
+        else
+          hash[:message] = message
+          hash[:suggestion] = suggestion if suggestion
+          hash[:choice] = stringify(choice.except(:describe, :command)) if choice
+          hash[:conflicts] = conflicts.map { |entry| stringify(entry) } unless conflicts.empty?
+        end
+        stringify(hash)
+      end
+
+      def to_json(*) = JSON.pretty_generate(to_h)
+
+      def to_text
+        case status
+        when :ok then ok_text
+        when :missing_choice then missing_choice_text
+        when :conflict then conflict_text
+        else "#{message}#{"\n  #{suggestion}" if suggestion}\n\nNothing was written.\n"
+        end
+      end
+
+      # `monk new`'s text: the app created, its base files by directory, then
+      # each module added on top of it, as `monk add` shows them.
+      def new_text(app)
+        return to_text unless ok?
+
+        added = modules.select { |entry| entry[:action] == :added && entry[:name] != :base }
+        lines = [new_header(app, added), "", *base_summary]
+        added.each { |entry| lines.push("", entry[:name].to_s, *module_lines(entry[:name])) }
+        lines.concat(production_text)
+        lines.push("", "Next:", "  cd #{app}", *step_lines)
+        lines << "  then: monk add --list   the modules you can add" if added.empty?
+        lines.push("", closing) if closing && !dry_run
+        "#{lines.join("\n")}\n"
+      end
+
+      private
+
+      def new_header(app, added)
+        verb = dry_run ? "Would create" : "Created"
+        return "#{verb} #{app}/ (bare Monk app)#{" — nothing written" if dry_run}." if added.empty?
+
+        requested_added = added.reject { |entry| entry[:reason] }.map { |entry| entry[:name] }
+        dependencies = added.select { |entry| entry[:reason] }.map { |entry| entry[:name] }
+        line = "#{verb} #{app}/ with #{names(requested_added)}"
+        if dependencies.any?
+          line += ", and #{names(dependencies)}, which #{requested_added.size > 1 ? "they need" : "it needs"}"
+        end
+        "#{line}#{" — nothing written" if dry_run}."
+      end
+
+      # The base app's files, one line per top-level directory.
+      def base_summary
+        base = files.select { |entry| entry[:module] == :base && entry[:action] == :created }
+        paths = base.map { |entry| entry[:path] }
+        top, nested = paths.partition { |path| !path.include?("/") }
+        lines = top.empty? ? [] : ["  + #{top.join(", ")}"]
+        nested.group_by { |path| path.split("/").first }.each do |dir, inside|
+          children = inside.map { |path| path.split("/")[1] + (path.count("/") > 1 ? "/" : "") }.uniq
+          lines << "  + #{"#{dir}/".ljust(9)}#{children.join(", ")}"
+        end
+        sections = files.select { |entry| entry[:sections] }.map { |entry| entry[:path] }
+        lines << "  + #{sections.join(", ")}" unless sections.empty?
+        lines
+      end
+
+      def ok_text
+        added = modules.select { |entry| entry[:action] == :added }
+        if added.empty?
+          return "#{names(requested)} #{requested.size > 1 ? "are" : "is"} already installed — nothing to do.\n"
+        end
+
+        lines = [header(added), ""]
+        added.each do |entry|
+          body = module_lines(entry[:name])
+          lines << entry[:name].to_s if added.size > 1
+          lines.concat(body)
+          lines << "" if added.size > 1
+        end
+        lines.pop if lines.last == "" && added.size == 1
+        sections = files.select { |entry| entry[:sections] }
+        if sections.any?
+          names = sections.flat_map { |entry| entry[:items] }.uniq
+          label = names.size > 1 ? "sections" : "section"
+          lines << row("~", sections.map { |entry| entry[:path] }.join(", "), "#{label}: #{names.join(", ")}")
+        elsif lines.last == ""
+          lines.pop
+        end
+        lines.concat(production_text, next_text)
+        lines.push("", closing) if closing && !dry_run
+        "#{lines.join("\n")}\n"
+      end
+
+      def header(added)
+        to_add = added.reject { |entry| entry[:reason] }.map { |entry| entry[:name] }
+        dependencies = added.select { |entry| entry[:reason] }.map { |entry| entry[:name] }
+        installed = modules.select { |entry| entry[:action] == :already_installed }.map { |entry| entry[:name] }
+        verb = dry_run ? "Would add" : "Adding"
+        line = "#{verb} #{names(to_add)}"
+        if dependencies.any?
+          line += ", which #{to_add.size > 1 ? "need" : "needs"} #{names(dependencies)} — adding " \
+                  "#{dependencies.size > 1 ? "those" : "it"} first"
+        end
+        already = "#{names(installed)} already installed" if installed.any? && dependencies.empty?
+        return "#{line} (#{["nothing written", already].compact.join("; ")}):" if dry_run
+
+        already ? "#{line} (#{already})." : "#{line}."
+      end
+
+      def module_lines(name)
+        own = files.select { |entry| entry[:module] == name }
+        created = own.select { |entry| entry[:action] == :created }
+        lines = migrations_grouped(created).map { |entry| row("+", entry[:path], created_note(entry)) }
+        lines += skipped.select { |entry| entry[:module] == name }.map do |entry|
+          row("!", entry[:path], "exists and differs — left as is")
+        end
+        lines + appended_grouped(own.select { |entry| entry[:action] == :appended && !entry[:sections] })
+      end
+
+      def created_note(entry)
+        return "example: #{entry[:examples].map(&:first).uniq.join(", ")} (commented)" if entry[:examples]&.any?
+
+        "demo, development only" if entry[:role] == :demo
+      end
+
+      # db/migrate/..._name.up.sql and .down.sql as one line.
+      def migrations_grouped(created)
+        created.each_with_object([]) do |entry, rows|
+          if entry[:path].end_with?(".down.sql") && rows.last && rows.last[:path] == entry[:path].sub(/\.down\.sql\z/,
+            ".up.sql",)
+            rows[-1] = rows.last.merge(path: entry[:path].sub(/\.down\.sql\z/, ".{up,down}.sql"))
+          else
+            rows << entry
+          end
+        end
+      end
+
+      # The files that got the same lines (the .env files, say), as one line.
+      def appended_grouped(appended)
+        appended.group_by { |entry| compact_keys(entry[:items]) }.map do |items, entries|
+          row("~", entries.map { |entry| entry[:path] }.join(", "), items)
+        end
+      end
+
+      # DB_HOST, DB_NAME... as DB_*.
+      def compact_keys(items)
+        prefix = items.first.to_s[/\A[A-Z]+_/]
+        return "#{prefix}*" if prefix && items.size > 1 && items.all? { |item| item.start_with?(prefix) }
+
+        items.join(", ")
+      end
+
+      def production_text
+        return [] if env.empty?
+
+        width = env.map { |entry| entry[:key].size }.max
+        ["", "Set before production:", *env.map { |entry| "  #{entry[:key].ljust(width)}  #{entry[:note]}" }]
+      end
+
+      def next_text = ["", "Next:", *step_lines]
+
+      # At most three numbered steps, in the order they're done. Past three,
+      # bin/setup_db joins the tests' line, the first two and that line are
+      # numbered, and what's left is named on one more line each, with the
+      # SETUP.md section that explains it.
+      def step_lines
+        steps = next_steps.dup
+        if steps.size > MAX_STEPS && (migrate = steps.find { |step| step[:run] == "bin/setup_db" })
+          steps.delete(migrate)
+          steps[-1] = steps.last.merge(run: "bin/setup_db && #{steps.last[:run]}")
+        end
+        rest = []
+        if steps.size > MAX_STEPS
+          rest = steps[(MAX_STEPS - 1)...-1]
+          steps = steps.first(MAX_STEPS - 1) + [steps.last]
+        end
+        lines = steps.each_with_index.map { |step, index| "  #{index + 1}. #{step_text(step)}" }
+        lines + rest.map { |step| "  … also: #{step_text(step)}#{" (SETUP.md › #{step[:module]})" if step[:module]}" }
+      end
+
+      def step_text(step)
+        [step[:run] || step[:do], step[:note]].compact.join("   ")
+      end
+
+      def missing_choice_text
+        lines = ["#{command}: #{message} Pass one:", ""]
+        width = choice[:values].map(&:size).max
+        choice[:values].each do |value|
+          described = choice[:describe]&.fetch(value, nil)
+          lines << "  #{command} --#{choice[:option]}=#{value.ljust(width)}#{"   #{described}" if described}"
+        end
+        "#{lines.join("\n")}\n\nNothing was written.\n"
+      end
+
+      def conflict_text
+        lines = [message]
+        conflicts.each { |entry| lines << "  Monk's version of #{entry[:path]}: #{entry[:show]}" }
+        "#{lines.join("\n")}\n\nNothing was written.\n"
+      end
+
+      def row(mark, path, note = nil)
+        note ? "  #{mark} #{path.ljust(COLUMN)} #{note}" : "  #{mark} #{path}"
+      end
+
+      def names(list)
+        list = list.map(&:to_s)
+        list.size <= 1 ? list.join : "#{list[0..-2].join(", ")} and #{list.last}"
+      end
+
+      def file_json(entry)
+        json = entry.slice(:path, :module, :role, :action, :items)
+        json[:examples] = entry[:examples].map(&:first).uniq if entry[:examples]&.any?
+        json[:module] = nil if entry[:sections]
+        stringify(json.compact)
+      end
+
+      def stringify(hash)
+        hash.to_h { |key, value| [key.to_s, value.is_a?(Symbol) ? value.to_s : value] }
+      end
+    end
+  end
+end