hecks 3.5.0 → 3.6.0

data/lib/hecks/doc/reference/rendering.rb

@@ -0,0 +1,149 @@
+module Hecks
+  module Doc
+    module Reference
+      # Renders the pages themselves: a context's page word by word, and the index. Extended onto
+      # `Reference`.
+      module Rendering
+        # Renders one context's page, grouped by word (not per form) so a
+        # two-form word doesn't repeat its heading and prose.
+        def render_page(context, prose, path)
+          words = keywords.select { |row| row[:context] == context }.group_by { |row| row[:word] }
+          refuse_orphans!(prose, words, context, path)
+          sections = words.map { |word, forms| render_word(forms, prose[word]) }
+          page_markdown(context, prose[PREAMBLE].to_s.strip, sections)
+        end
+
+        # @raise [RuntimeError] when a page carries prose for a word the language does not declare
+        def refuse_orphans!(prose, words, context, path)
+          orphans = prose.keys - words.keys - [PREAMBLE]
+          return if orphans.empty?
+
+          raise "#{path} carries prose for #{orphans.join(", ")}, which the language no longer " \
+                "declares in #{context} — deleting writing is a human's decision, so decide"
+        end
+
+        # @return [String] the page: its heading, generated lede, the hand-written preamble and the
+        #   word sections
+        def page_markdown(context, preamble, sections)
+          <<~PAGE
+            # #{context}
+
+            #{region_begin("page")}
+            #{context_lede(context)}
+
+            *The tables on this page are generated from the language's own
+            aggregate-local syntax tables (`lib/hecks/language/**/*.bluebook`)
+            by `hecks language_run.project_reference` — do not edit inside the markers. The prose
+            between them is hand-written and survives regeneration.*
+            #{GENERATED_END}
+            #{"\n#{preamble}\n" unless preamble.empty?}
+            #{sections.join("\n")}
+          PAGE
+        end
+
+        # The one-line description of where a context's words are typed.
+        def context_lede(context)
+          openers = keywords.select { |row| row[:opens] == context }
+          return "Words available at the top of a file." if context == "File"
+          return "Words available in the type position of an `attribute`." if context == "Type"
+
+          inside = openers.map { |row| "`#{row[:word]} do ... end`" }.uniq.join(" / ")
+          inside.empty? ? "Words available in the #{context} body." : "Words available inside #{inside}."
+        end
+
+        # One section per word, built off forms.first — spelling is the only
+        # column that differs between a word's two forms.
+        def render_word(forms, prose)
+          row = forms.first
+          facts = word_facts(row)
+          spellings = forms.map { |form| "`#{signature(form)}`" }.join(" / ")
+          word_markdown(row, spellings, facts, argument_table(row), prose)
+        end
+
+        # @return [Array<String>] what a word's heading line states beyond its spelling
+        def word_facts(row)
+          [("opens a `#{row[:opens]}` body" unless row[:opens].to_s.empty?),
+           ("fills `#{row[:fills]}`" unless row[:fills].to_s.empty?),
+           ("**status: #{status_of(row)}**" unless status_of(row) == "admitted"),
+           ("was `#{row[:was]}`" unless row[:was].to_s.empty?)].compact
+        end
+
+        # @return [String] one word's section: heading, generated region and prose
+        def word_markdown(row, spellings, facts, table, prose)
+          <<~WORD
+            ## #{row[:word]}
+
+            #{generated_begin(row[:word])}
+            #{spellings}#{" — #{facts.join(", ")}" unless facts.empty?}
+            #{table}#{GENERATED_END}
+
+            #{prose_or_sentinel(prose)}
+          WORD
+        end
+
+        # Falls back to the TODO sentinel when a word has no prose yet.
+        def prose_or_sentinel(prose)
+          text = prose.to_s.strip
+          text.empty? ? TODO_SENTINEL : text
+        end
+
+        # The Argument rows declared for one Keyword row's word, in its context.
+        def word_arguments(row)
+          arguments.select { |arg| arg[:keyword] == row[:word] && arg[:context] == row[:context] }
+        end
+
+        # Builds the call spelling shown for one word: positional arguments
+        # then named ones, with a trailing `do ... end` unless its body is "none".
+        def signature(row)
+          args = word_arguments(row)
+          parts = positional_parts(args) + named_parts(args)
+          base = parts.empty? ? row[:word] : "#{row[:word]} #{parts.join(", ")}"
+          row[:body].to_s == "none" ? base : "#{base} do ... end"
+        end
+
+        # @return [Array<String>] the positional arguments' kinds (or what they fill), in order
+        def positional_parts(args)
+          args.reject { |arg| arg[:at].to_s.empty? }
+              .sort_by { |arg| arg[:at].to_i }
+              .map { |arg| arg[:fills].to_s.empty? ? arg[:kind] : arg[:fills] }
+        end
+
+        # @return [Array<String>] the named arguments, as `name:`
+        def named_parts(args)
+          args.select { |arg| arg[:at].to_s.empty? }.map { |arg| "#{arg[:named]}:" }
+        end
+
+        # Renders one word's arguments as a Markdown table, or "" if it declares none.
+        def argument_table(row)
+          args = word_arguments(row)
+          return "" if args.empty?
+
+          lines = ["", "| argument | kind | required | fills |", "|---|---|---|---|"]
+          args.each do |arg|
+            name = arg[:at].to_s.empty? ? "`#{arg[:named]}:`" : "positional #{arg[:at]}"
+            lines << "| #{name} | #{arg[:kind]} | #{arg[:required]} | #{arg[:fills]} |"
+          end
+          "#{lines.join("\n")}\n"
+        end
+
+        # Renders the reference index page, one linked entry per context.
+        def render_index
+          listed = contexts.map do |context|
+            count = keywords.select { |row| row[:context] == context }.map { |row| row[:word] }.uniq.size
+            "- [#{context}](#{page_name(context)}) — #{count} #{count == 1 ? "word" : "words"}"
+          end
+          <<~INDEX
+            # The DSL reference
+
+            One page per context — the place in a file where a word may be
+            typed. Generated by `hecks language_run.project_reference` from the Syntax chapter;
+            the prose between the generated markers is hand-written and
+            survives regeneration.
+
+            #{listed.join("\n")}
+          INDEX
+        end
+      end
+    end
+  end
+end

data/lib/hecks/doc/reference.rb

@@ -1,11 +1,19 @@
+require "fileutils"
 require_relative "../bluebook/meta_validator"
 require_relative "../naming"
+require_relative "reference/harvester"
+require_relative "reference/readme"
+require_relative "reference/coverage"
+require_relative "reference/rendering"
 
 module Hecks
   module Doc
     # The DSL reference, projected from the language's own Syntax chapter so
     # its tables can never drift from the live builders. Regenerate with
     # `hecks language_run.project_reference`.
+    #
+    # README's regions are in `Readme` and the coverage gates in `Coverage`, both extended onto
+    # this module; `Harvester` reads committed prose back.
     module Reference
       GENERATED_END = "<!-- generated:end -->".freeze
       TODO_SENTINEL = "<!-- TODO: document this word -->".freeze
@@ -14,6 +22,10 @@ module Hecks
       # collide with a word (words are always Strings off the Syntax chapter).
       PREAMBLE = :preamble
 
+      extend Readme
+      extend Coverage
+      extend Rendering
+
       module_function
 
       # The marker opening one word's generated region.
@@ -65,153 +77,9 @@ module Hecks
         end.merge("index.md" => render_index)
       end
 
-      # Renders one context's page, grouped by word (not per form) so a
-      # two-form word doesn't repeat its heading and prose.
-      def render_page(context, prose, path)
-        words = keywords.select { |row| row[:context] == context }.group_by { |row| row[:word] }
-        orphans = prose.keys - words.keys - [PREAMBLE]
-        unless orphans.empty?
-          raise "#{path} carries prose for #{orphans.join(', ')}, which the language no longer " \
-                "declares in #{context} — deleting writing is a human's decision, so decide"
-        end
-
-        sections = words.map { |word, forms| render_word(forms, prose[word]) }
-        preamble = prose[PREAMBLE].to_s.strip
-        <<~PAGE
-          # #{context}
-
-          #{region_begin('page')}
-          #{context_lede(context)}
-
-          *The tables on this page are generated from the language's own
-          aggregate-local syntax tables (`lib/hecks/language/**/*.bluebook`)
-          by `hecks language_run.project_reference` — do not edit inside the markers. The prose
-          between them is hand-written and survives regeneration.*
-          #{GENERATED_END}
-          #{"\n#{preamble}\n" unless preamble.empty?}
-          #{sections.join("\n")}
-        PAGE
-      end
-
-      # The one-line description of where a context's words are typed.
-      def context_lede(context)
-        openers = keywords.select { |row| row[:opens] == context }
-        return "Words available at the top of a file." if context == "File"
-        return "Words available in the type position of an `attribute`." if context == "Type"
-
-        inside = openers.map { |row| "`#{row[:word]} do ... end`" }.uniq.join(" / ")
-        inside.empty? ? "Words available in the #{context} body." : "Words available inside #{inside}."
-      end
-
-      # One section per word, built off forms.first — spelling is the only
-      # column that differs between a word's two forms.
-      def render_word(forms, prose)
-        row = forms.first
-        table = argument_table(row)
-        facts = []
-        facts << "opens a `#{row[:opens]}` body" unless row[:opens].to_s.empty?
-        facts << "fills `#{row[:fills]}`" unless row[:fills].to_s.empty?
-        facts << "**status: #{status_of(row)}**" unless status_of(row) == "admitted"
-        facts << "was `#{row[:was]}`" unless row[:was].to_s.empty?
-        spellings = forms.map { |form| "`#{signature(form)}`" }.join(" / ")
-
-        <<~WORD
-          ## #{row[:word]}
-
-          #{generated_begin(row[:word])}
-          #{spellings}#{" — #{facts.join(', ')}" unless facts.empty?}
-          #{table}#{GENERATED_END}
-
-          #{prose_or_sentinel(prose)}
-        WORD
-      end
-
-      # Falls back to the TODO sentinel when a word has no prose yet.
-      def prose_or_sentinel(prose)
-        text = prose.to_s.strip
-        text.empty? ? TODO_SENTINEL : text
-      end
-
-      # The Argument rows declared for one Keyword row's word, in its context.
-      def word_arguments(row)
-        arguments.select { |arg| arg[:keyword] == row[:word] && arg[:context] == row[:context] }
-      end
-
-      # Builds the call spelling shown for one word: positional arguments
-      # then named ones, with a trailing `do ... end` unless its body is "none".
-      def signature(row)
-        positional = word_arguments(row).reject { |arg| arg[:at].to_s.empty? }
-                                        .sort_by { |arg| arg[:at].to_i }
-                                        .map { |arg| arg[:fills].to_s.empty? ? arg[:kind] : arg[:fills] }
-        named = word_arguments(row).select { |arg| arg[:at].to_s.empty? }
-                                   .map { |arg| "#{arg[:named]}:" }
-        parts = positional + named
-        base = parts.empty? ? row[:word] : "#{row[:word]} #{parts.join(', ')}"
-        row[:body].to_s == "none" ? base : "#{base} do ... end"
-      end
-
-      # Renders one word's arguments as a Markdown table, or "" if it declares none.
-      def argument_table(row)
-        args = word_arguments(row)
-        return "" if args.empty?
-
-        lines = ["", "| argument | kind | required | fills |", "|---|---|---|---|"]
-        args.each do |arg|
-          name = arg[:at].to_s.empty? ? "`#{arg[:named]}:`" : "positional #{arg[:at]}"
-          lines << "| #{name} | #{arg[:kind]} | #{arg[:required]} | #{arg[:fills]} |"
-        end
-        "#{lines.join("\n")}\n"
-      end
-
-      # Renders the reference index page, one linked entry per context.
-      def render_index
-        listed = contexts.map do |context|
-          count = keywords.select { |row| row[:context] == context }.map { |row| row[:word] }.uniq.size
-          "- [#{context}](#{page_name(context)}) — #{count} #{count == 1 ? 'word' : 'words'}"
-        end
-        <<~INDEX
-          # The DSL reference
-
-          One page per context — the place in a file where a word may be
-          typed. Generated by `hecks language_run.project_reference` from the Syntax chapter;
-          the prose between the generated markers is hand-written and
-          survives regeneration.
-
-          #{listed.join("\n")}
-        INDEX
-      end
-
       # Prose keyed by word: everything between a section's generated region
-      # and the next `## ` heading. Starts collecting under `PREAMBLE` (not nil)
-      # so a page written before that region existed still parses unchanged.
-      # rubocop:disable-next Metrics/PerceivedComplexity
-      def harvest(text)
-        prose = {}
-        current = PREAMBLE
-        collecting = false
-        buffer = []
-
-        # A `## ` line inside a fence is not a heading — it's a comment in
-        # the runnable example, not a section break.
-        in_fence = false
-
-        text.each_line do |line|
-          in_fence = !in_fence if line.start_with?("```")
-
-          if !in_fence && (match = line.match(/\A## (\S+)\s*\z/))
-            prose[current] = buffer.join.strip if current && collecting
-            current = match[1]
-            collecting = false
-            buffer = []
-          elsif line.include?(GENERATED_END)
-            collecting = true
-          elsif collecting
-            buffer << line
-          end
-        end
-        prose[current] = buffer.join.strip if current && collecting
-        prose.reject { |_word, text_| text_.empty? || text_ == TODO_SENTINEL }
-      end
+      # and the next `## ` heading.
+      def harvest(text) = Harvester.new.call(text)
 
       # Renders every reference page and writes each to `directory`.
       def write!(directory)
@@ -220,133 +88,6 @@ module Hecks
           File.write(File.join(directory, name), content)
         end
       end
-
-      # README's own generated regions, keyed by region id instead of a word.
-      def readme_regions(root)
-        {
-          "guides"    => guide_index(root),
-          "reference" => reference_index(root),
-          "corpus"    => corpus_roster(root),
-          "diagrams"  => diagram_showcase(root)
-        }
-      end
-
-      # Lists every committed guide, linked and titled by its own heading.
-      def guide_index(root)
-        paths = Dir.glob(File.join(root, "docs/implemented/guides/*.md"))
-                   .reject { |p| %w[AUTHORING.md].include?(File.basename(p)) }
-        lines = paths.map do |path|
-          heading = File.foreach(path).find { |line| line.start_with?("# ") }
-          title = heading ? heading.sub(/\A#\s*/, "").strip : File.basename(path)
-          "- [#{title}](docs/implemented/guides/#{File.basename(path)})"
-        end
-        lines.join("\n")
-      end
-
-      # Links the reference index, with its context count.
-      def reference_index(_root)
-        count = contexts.size
-        "[The DSL reference](docs/implemented/reference/index.md) — #{count} contexts, generated from " \
-          "the aggregate-local tables under `lib/hecks/language/` and held to them by " \
-          "`spec/reference_golden_spec.rb`."
-      end
-
-      # Quotes the real, committed diagram file rather than re-deriving one,
-      # so this can't drift from `spec/diagrams_spec.rb`'s own check.
-      def diagram_showcase(root)
-        lifecycle = File.read(File.join(root, "docs/generated/diagrams/pizzas/Order_lifecycle.mmd")).strip
-        <<~MARKDOWN.strip
-          `hecks project_diagrams` reads a booted domain's own declaration and draws it as Mermaid — nine kinds so far: `<Name>_lifecycle.mmd`, `relationships.mmd`, `dispatch.mmd`, `roles.mmd`, `ports.mmd`, `read_models.mmd`, `<Name>_surface.mmd` (what a command does, and what it writes), `<Name>_saga.mmd`, and `frameworks.mmd`. Nothing hand-drawn — the same reason a domain is data at all. Order's own lifecycle, straight off the bluebook above:
-
-          ```mermaid
-          #{lifecycle}
-          ```
-
-          The full set for every domain in this checkout — `examples/pizzas`, `examples/banking` — lives in [`docs/generated/diagrams/`](docs/generated/diagrams/), held to the declaration by `spec/diagrams_spec.rb` the same drift-refusing way this page is held to its own source.
-        MARKDOWN
-      end
-
-      # Lists every example domain with a `.bluebook` file, with its own declared vision.
-      def corpus_roster(root)
-        dirs = Dir.glob(File.join(root, "examples/*/"))
-        lines = dirs.filter_map do |dir|
-          name = File.basename(dir.chomp("/"))
-          bluebooks = Dir.glob(File.join(dir, "bluebook/*.bluebook"))
-          bluebooks = Dir.glob(File.join(dir, "*.bluebook")) if bluebooks.empty?
-          next if bluebooks.empty?
-
-          vision = bluebooks.filter_map { |bluebook| File.read(bluebook)[/vision\s+"([^"]*)"/, 1] }.first
-          "- **#{name}** — #{vision}"
-        end
-        lines.join("\n")
-      end
-
-      # Replaces every generated region inside `text` with its freshly rendered
-      # content, leaving the hand-written parts of README untouched.
-      def render_readme(root, text)
-        readme_regions(root).reduce(text) do |current, (id, content)|
-          pattern = /#{Regexp.escape(region_begin(id))}.*?#{Regexp.escape(GENERATED_END)}/m
-          current.sub(pattern) { "#{region_begin(id)}\n#{content}\n#{GENERATED_END}" }
-        end
-      end
-
-      # Regenerates README's generated regions in place.
-      def write_readme!(root)
-        path = File.join(root, "README.md")
-        File.write(path, render_readme(root, File.read(path)))
-      end
-
-      # Matches a runnable `ruby`/`ruby bluebook`/`ruby boot` fenced example;
-      # `ruby skip` and hidden boot blocks are setup, not an example, and don't count.
-      EXAMPLE_FENCE = /^```ruby(?: bluebook| boot)?[ \t]*$/
-
-      # Whether a word's prose carries a runnable example.
-      def exemplified?(prose) = prose.to_s.match?(EXAMPLE_FENCE)
-
-      # Every live word paired with its prose; shared by both coverage gates
-      # so their page-walks can't drift apart.
-      def live_words(directory)
-        rows = contexts.flat_map do |context|
-          path = File.join(directory, page_name(context))
-          prose = File.exist?(path) ? harvest(File.read(path)) : {}
-          keywords.select { |row| row[:context] == context && live?(row) }
-                  .map { |row| [row[:word], context, prose[row[:word]]] }
-        end
-        rows.uniq { |word, context, _| [word, context] }
-      end
-
-      # Disambiguates a word by the context it is declared in.
-      def name_of(word, context) = "#{word} (#{context})"
-
-      # The coverage gate's question: every live word with no prose yet.
-      def undocumented(directory)
-        live_words(directory).reject { |_word, _context, prose| prose }
-                             .map { |word, context, _| name_of(word, context) }
-      end
-
-      # The second coverage gate: prose alone can go stale or describe
-      # unwired behavior; a runnable example is the only doc that can go red.
-      def unexemplified(directory)
-        live_words(directory).reject { |_word, _context, prose| exemplified?(prose) }
-                             .map { |word, context, _| name_of(word, context) }
-      end
-
-      # Both coverage gates, worded for a person: each gap section lists the words that owe it,
-      # and a word missing both kinds is listed twice, one repair each.
-      #
-      # @param directory [String] the reference pages
-      # @return [Array(Boolean, String)] whether every live word is covered, and what to print
-      def coverage_report(directory)
-        gaps = [[undocumented(directory), "no prose — write their sections"],
-                [unexemplified(directory), "no running example — write one in each word's own section"]]
-        sections = gaps.reject { |words, _| words.empty? }.map do |words, owed|
-          head = "#{words.size} live #{words.size == 1 ? 'word carries' : 'words carry'} #{owed}:\n"
-          "#{head}#{words.map { |word| "  #{word}\n" }.join}\n"
-        end
-        return [true, "every live word carries prose and a running example."] if sections.empty?
-
-        [false, sections.join]
-      end
     end
   end
 end

data/lib/hecks/doors/cli_door/nesting.rb

@@ -0,0 +1,34 @@
+module Hecks
+  module Doors
+    module CliDoor
+      # Sets values into the nested argument Hash a dotted path names, creating the intermediate
+      # Hashes on the way.
+      module Nesting
+        module_function
+
+        # Appends one element to a list argument, creating the list on first use.
+        #
+        # Repeats must grow the list (`bury` would silently keep only the last), and a single
+        # element is still a one-item list, since a `list_of` attribute must never see a bare
+        # object. Multi-field elements are left to `JsonDoor`: a flat command line cannot say
+        # which `a.x=` pairs with which `a.y=`.
+        def append(hash, path, value)
+          *branches, leaf = path.map(&:to_sym)
+          holder = branches[0..-2].reduce(hash) { |node, key| node[key] ||= {} }
+          list   = holder[branches.last] ||= []
+
+          list << { leaf => value }
+          hash
+        end
+
+        # Sets one value at a nested path, creating intermediate Hashes and overwriting the leaf.
+        def bury(hash, path, value)
+          *branches, leaf = path.map(&:to_sym)
+          target = branches.reduce(hash) { |node, key| node[key] ||= {} }
+          target[leaf] = value
+          hash
+        end
+      end
+    end
+  end
+end

data/lib/hecks/doors/cli_door/shorthand.rb

@@ -0,0 +1,85 @@
+module Hecks
+  module Doors
+    module CliDoor
+      # Rewrites the shorthand spellings of a command line into plain `name=value` words.
+      module Shorthand
+        module_function
+
+        # Rewrites the short forms into `name=value`: `--name` for a Boolean (a following `yes`,
+        # `no`, `true`, `false`, `on`, `off`, `1` or `0` is that flag's value, not an argument),
+        # `--name=value` as `name=value`, and one bare word as the command's first argument
+        # (`to` for a command on an existing aggregate, the first attribute for one that creates).
+        def normalize(spec, words, options)
+          pairs, bare = collect(words, options)
+          raise Runtime::NotFound, too_many_bare(bare) if bare.length > 1
+
+          pairs.map { |pair| bare.include?(pair) && !pair.include?("=") ? positional(pair, spec) : pair }
+        end
+
+        # Every word as a pair, and the words that were neither a flag nor a pair.
+        def collect(words, options)
+          queue = words.dup
+          pairs = []
+          bare  = []
+          until queue.empty?
+            word = queue.shift
+            pairs << pair_for(word, queue, options)
+            bare << word if bare_word?(word)
+          end
+          [pairs, bare]
+        end
+
+        # A word that is neither a `--flag` nor a `name=value` pair.
+        def bare_word?(word)
+          !word.start_with?("--") && !word.include?("=")
+        end
+
+        # One word as a `name=value` pair; a `--flag` takes the Boolean word that follows it from
+        # `queue`.
+        def pair_for(word, queue, options)
+          return word unless word.start_with?("--")
+          return underscored(word.delete_prefix("--"), options) if word.include?("=")
+
+          path  = flag(word.delete_prefix("--"), options)
+          value = BOOLEAN_WORDS.key?(queue.first.to_s.downcase) ? queue.shift : "true"
+          "#{path}=#{value}"
+        end
+
+        # A `name=value` pair whose name is spelled with dashes (`seed-start=3`), as the argument
+        # spelled with underscores, unless an argument is named with the dashes.
+        def underscored(pair, options)
+          name, value = pair.split("=", 2)
+          options.key?(name) ? pair : "#{name.tr("-", "_")}=#{value}"
+        end
+
+        # A `--name` flag, as the path of the Boolean argument it stands for. A dashed name
+        # (`--gem-only`) is the argument spelled with underscores (`gem_only`).
+        def flag(name, options)
+          name = name.tr("-", "_") unless options.key?(name) || options.keys.any? { |key| key.start_with?("#{name}.") }
+          path = options.key?(name) ? name : CliDoor.expand(name, options)
+          return path if options.dig(path, :type) == "Boolean"
+
+          raise Runtime::NotFound, "--#{name} is a flag, but this command has no Boolean argument #{name.inspect}"
+        end
+
+        # The one bare word, as a pair for the command's first argument the launcher does not mint.
+        def positional(word, spec)
+          first = spec[:arguments].find { |argument| !argument[:minted] }
+          return "#{first[:path]}=#{word}" if first
+
+          if spec[:arguments].any?
+            raise Runtime::NotFound, "#{word.inspect} is not name=value; this command's only argument is its run " \
+                                     "key, which is minted when omitted (run=<key> names one)"
+          end
+
+          raise Runtime::NotFound, "#{word.inspect} is not name=value, and this command takes no arguments"
+        end
+
+        # Words the refusal for more than one unnamed argument.
+        def too_many_bare(bare)
+          "only one argument may go unnamed, not #{bare.map(&:inspect).join(", ")}; name the rest as name=value"
+        end
+      end
+    end
+  end
+end