hecks 3.4.2 → 3.6.0

data/lib/hecks/deploy/bluebook/deploy.hecksagon

@@ -46,11 +46,68 @@ Hecks.hecksagon "Deploy" do
   Deploy::SmokeRun.port "DeployToolchain" do
     asks "Smoke", to: SmokeRun do
       attribute :run, RunKey
+      attribute :after, Origin, default: { value: "alone" }
       answers "SmokeAnswered"
       refuses "SmokeRefused"
     end
   end
 
+  Deploy::ServiceRoll.port "DeployToolchain" do
+    asks "RollService", to: ServiceRoll do
+      attribute :run, RunKey
+      answers "ServiceRollAnswered"
+      refuses "ServiceRollRefused"
+    end
+  end
+
+  Deploy::BoxRoll.port "DeployToolchain" do
+    asks "RollBox", to: BoxRoll do
+      attribute :run, RunKey
+      answers "BoxRollAnswered"
+      refuses "BoxRollRefused"
+    end
+  end
+
+  Deploy::DataCopy.port "DeployToolchain" do
+    asks "CopyData", to: DataCopy do
+      attribute :run, RunKey
+      answers "DataCopyAnswered"
+      refuses "DataCopyRefused"
+    end
+  end
+
+  Deploy::CopyVerification.port "DeployToolchain" do
+    asks "CompareCopy", to: CopyVerification do
+      attribute :run, RunKey
+      answers "CopyVerificationAnswered"
+      refuses "CopyVerificationRefused"
+    end
+  end
+
+  Deploy::BluebookDiff.port "DeployToolchain" do
+    asks "CompareBluebooks", to: BluebookDiff do
+      attribute :run, RunKey
+      answers "BluebookDiffAnswered"
+      refuses "BluebookDiffRefused"
+    end
+  end
+
+  Deploy::PreviewRun.port "DeployToolchain" do
+    asks "RunPreview", to: PreviewRun do
+      attribute :run, RunKey
+      answers "PreviewRunAnswered"
+      refuses "PreviewRunRefused"
+    end
+  end
+
+  Deploy::CompanionRoll.port "DeployToolchain" do
+    asks "RollCompanion", to: CompanionRoll do
+      attribute :run, RunKey
+      answers "CompanionRollAnswered"
+      refuses "CompanionRollRefused"
+    end
+  end
+
   Deploy::TemplateComparison.port "DeployToolchain" do
     asks "Compare", to: TemplateComparison do
       attribute :run, RunKey

data/lib/hecks/deploy/oidc.json

@@ -1,11 +1,101 @@
 {
   "audience": "Deploy",
   "scopes": [
+    {
+      "scope": "deploy:bluebook_diff.differ",
+      "verb": "Deploy::BluebookDiff.Differ",
+      "role": null
+    },
+    {
+      "scope": "deploy:bluebook_diff.flag",
+      "verb": "Deploy::BluebookDiff.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:bluebook_diff.match",
+      "verb": "Deploy::BluebookDiff.Match",
+      "role": null
+    },
+    {
+      "scope": "deploy:bluebook_diff.run",
+      "verb": "Deploy::BluebookDiff.Run",
+      "role": null
+    },
+    {
+      "scope": "deploy:bluebook_diff.withhold",
+      "verb": "Deploy::BluebookDiff.Withhold",
+      "role": null
+    },
+    {
+      "scope": "deploy:box_roll.complete",
+      "verb": "Deploy::BoxRoll.Complete",
+      "role": null
+    },
+    {
+      "scope": "deploy:box_roll.flag",
+      "verb": "Deploy::BoxRoll.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:box_roll.flag_smoke",
+      "verb": "Deploy::BoxRoll.FlagSmoke",
+      "role": null
+    },
+    {
+      "scope": "deploy:box_roll.run",
+      "verb": "Deploy::BoxRoll.Run",
+      "role": null
+    },
+    {
+      "scope": "deploy:box_roll.verify",
+      "verb": "Deploy::BoxRoll.Verify",
+      "role": null
+    },
     {
       "scope": "deploy:box_target.declare",
       "verb": "Deploy::BoxTarget.Declare",
       "role": null
     },
+    {
+      "scope": "deploy:companion_roll.complete",
+      "verb": "Deploy::CompanionRoll.Complete",
+      "role": null
+    },
+    {
+      "scope": "deploy:companion_roll.flag",
+      "verb": "Deploy::CompanionRoll.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:companion_roll.plan",
+      "verb": "Deploy::CompanionRoll.Plan",
+      "role": null
+    },
+    {
+      "scope": "deploy:companion_roll.run",
+      "verb": "Deploy::CompanionRoll.Run",
+      "role": null
+    },
+    {
+      "scope": "deploy:copy_verification.differ",
+      "verb": "Deploy::CopyVerification.Differ",
+      "role": null
+    },
+    {
+      "scope": "deploy:copy_verification.flag",
+      "verb": "Deploy::CopyVerification.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:copy_verification.match",
+      "verb": "Deploy::CopyVerification.Match",
+      "role": null
+    },
+    {
+      "scope": "deploy:copy_verification.run",
+      "verb": "Deploy::CopyVerification.Run",
+      "role": null
+    },
     {
       "scope": "deploy:cost_check.check",
       "verb": "Deploy::CostCheck.Check",
@@ -21,6 +111,46 @@
       "verb": "Deploy::CostCheck.Pass",
       "role": null
     },
+    {
+      "scope": "deploy:data_copy.complete",
+      "verb": "Deploy::DataCopy.Complete",
+      "role": null
+    },
+    {
+      "scope": "deploy:data_copy.confirm",
+      "verb": "Deploy::DataCopy.Confirm",
+      "role": null
+    },
+    {
+      "scope": "deploy:data_copy.drift",
+      "verb": "Deploy::DataCopy.Drift",
+      "role": null
+    },
+    {
+      "scope": "deploy:data_copy.flag",
+      "verb": "Deploy::DataCopy.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:data_copy.flag_verification",
+      "verb": "Deploy::DataCopy.FlagVerification",
+      "role": null
+    },
+    {
+      "scope": "deploy:data_copy.plan",
+      "verb": "Deploy::DataCopy.Plan",
+      "role": null
+    },
+    {
+      "scope": "deploy:data_copy.restore",
+      "verb": "Deploy::DataCopy.Restore",
+      "role": null
+    },
+    {
+      "scope": "deploy:data_copy.verify",
+      "verb": "Deploy::DataCopy.Verify",
+      "role": null
+    },
     {
       "scope": "deploy:fargate_target.declare",
       "verb": "Deploy::FargateTarget.Declare",
@@ -61,6 +191,76 @@
       "verb": "Deploy::OidcManifest.ProjectOidc",
       "role": null
     },
+    {
+      "scope": "deploy:preview_run.deploy",
+      "verb": "Deploy::PreviewRun.Deploy",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.destroy",
+      "verb": "Deploy::PreviewRun.Destroy",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.flag",
+      "verb": "Deploy::PreviewRun.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.list",
+      "verb": "Deploy::PreviewRun.List",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.login",
+      "verb": "Deploy::PreviewRun.Login",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.name",
+      "verb": "Deploy::PreviewRun.Name",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.plan",
+      "verb": "Deploy::PreviewRun.Plan",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.record_deploy",
+      "verb": "Deploy::PreviewRun.RecordDeploy",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.record_destroy",
+      "verb": "Deploy::PreviewRun.RecordDestroy",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.record_list",
+      "verb": "Deploy::PreviewRun.RecordList",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.record_login",
+      "verb": "Deploy::PreviewRun.RecordLogin",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.record_name",
+      "verb": "Deploy::PreviewRun.RecordName",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.record_url",
+      "verb": "Deploy::PreviewRun.RecordUrl",
+      "role": null
+    },
+    {
+      "scope": "deploy:preview_run.url",
+      "verb": "Deploy::PreviewRun.Url",
+      "role": null
+    },
     {
       "scope": "deploy:recipe.complete",
       "verb": "Deploy::Recipe.Complete",
@@ -76,6 +276,31 @@
       "verb": "Deploy::Recipe.Project",
       "role": null
     },
+    {
+      "scope": "deploy:service_roll.complete",
+      "verb": "Deploy::ServiceRoll.Complete",
+      "role": null
+    },
+    {
+      "scope": "deploy:service_roll.flag",
+      "verb": "Deploy::ServiceRoll.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:service_roll.flag_smoke",
+      "verb": "Deploy::ServiceRoll.FlagSmoke",
+      "role": null
+    },
+    {
+      "scope": "deploy:service_roll.run",
+      "verb": "Deploy::ServiceRoll.Run",
+      "role": null
+    },
+    {
+      "scope": "deploy:service_roll.verify",
+      "verb": "Deploy::ServiceRoll.Verify",
+      "role": null
+    },
     {
       "scope": "deploy:smoke_run.flag",
       "verb": "Deploy::SmokeRun.Flag",

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

@@ -0,0 +1,70 @@
+module Hecks
+  module Doc
+    module Reference
+      # The two coverage gates over a reference's prose: every live word is written about, and
+      # every one has a runnable example. Extended onto `Reference`.
+      module Coverage
+        # 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|
+            prose = page_prose(directory, context)
+            keywords.select { |row| row[:context] == context && live?(row) }
+                    .map { |row| [row[:word], context, prose[row[:word]]] }
+          end
+          rows.uniq { |word, context, _| [word, context] }
+        end
+
+        # @return [Hash{String, Symbol => String}] the prose committed in a context's page, or
+        #   none when the page does not exist yet
+        def page_prose(directory, context)
+          path = File.join(directory, page_name(context))
+          File.exist?(path) ? harvest(File.read(path)) : {}
+        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 { |words, owed| gap_section(words, owed) }
+          return [true, "every live word carries prose and a running example."] if sections.empty?
+
+          [false, sections.join]
+        end
+
+        # @return [String] the heading and list of the words that owe one kind of coverage
+        def gap_section(words, owed)
+          head = "#{words.size} live #{words.size == 1 ? "word carries" : "words carry"} #{owed}:\n"
+          "#{head}#{words.map { |word| "  #{word}\n" }.join}\n"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+module Hecks
+  module Doc
+    module Reference
+      # Reads the hand-written prose back out of a committed reference page: everything between a
+      # section's generated region and the next `## ` heading, keyed by word.
+      #
+      # Starts collecting under `PREAMBLE` (not nil) so a page written before that region existed
+      # still parses unchanged. A `## ` line inside a fence is not a heading: it is a comment in
+      # the runnable example, not a section break.
+      class Harvester
+        def initialize
+          @prose = {}
+          @current = PREAMBLE
+          @collecting = false
+          @buffer = []
+          @in_fence = false
+        end
+
+        # @param text [String] a reference page
+        # @return [Hash{String, Symbol => String}] each word's prose (the preamble under
+        #   `PREAMBLE`), leaving out a word with none or only the TODO sentinel
+        def call(text)
+          text.each_line { |line| consume(line) }
+          flush
+          @prose.reject { |_word, body| body.empty? || body == TODO_SENTINEL }
+        end
+
+        private
+
+        def consume(line)
+          @in_fence = !@in_fence if line.start_with?("```")
+          heading = line.match(/\A## (\S+)\s*\z/) unless @in_fence
+          if heading
+            start_section(heading[1])
+          elsif line.include?(GENERATED_END)
+            @collecting = true
+          elsif @collecting
+            @buffer << line
+          end
+        end
+
+        def start_section(word)
+          flush
+          @current = word
+          @collecting = false
+          @buffer = []
+        end
+
+        def flush
+          @prose[@current] = @buffer.join.strip if @current && @collecting
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+module Hecks
+  module Doc
+    module Reference
+      # README's own generated regions, keyed by region id instead of a word. Extended onto
+      # `Reference`.
+      module Readme
+        # 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)
+          Dir.glob(File.join(root, "examples/*/")).filter_map { |dir| roster_line(dir) }.join("\n")
+        end
+
+        # @return [String, nil] the example's name and vision as a list item; nil without a bluebook
+        def roster_line(dir)
+          bluebooks = example_bluebooks(dir)
+          return if bluebooks.empty?
+
+          vision = bluebooks.filter_map { |bluebook| File.read(bluebook)[/vision\s+"([^"]*)"/, 1] }.first
+          "- **#{File.basename(dir.chomp("/"))}** — #{vision}"
+        end
+
+        # @return [Array<String>] the example's bluebooks, under `bluebook/` or else beside it
+        def example_bluebooks(dir)
+          bluebooks = Dir.glob(File.join(dir, "bluebook/*.bluebook"))
+          bluebooks.empty? ? Dir.glob(File.join(dir, "*.bluebook")) : bluebooks
+        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
+      end
+    end
+  end
+end

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