spreen-wiki 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae1421288cd76d1d43326a72cdfd2c2c2dd9bb617becd061468e7a2789f80b31
-  data.tar.gz: 3ab8bc5f1d779379fe2137cd0869071150c06fc74ce4566cda84c57a03a6d5af
+  metadata.gz: 4e9507fb9c2097bc8c1221f21934eebeef6eac80a6e85ec217afed7a031a2db9
+  data.tar.gz: 5ce2f2ca5db1a5c9244b475d3866ca32d7463b4deb5beb4cfca270c869b1051a
 SHA512:
-  metadata.gz: d2658be24738c7ad2a5a9738f45dcb5505b8fa1c4054554e9c8384e5782df2c01027e5aff529ae59715123343f472ec4dab0e1cac36008a66be0128401311090
-  data.tar.gz: 56454356e70d3d8d6a7c3013084d5c3babf65d9e4042ce1f8f55a306b90169ff9184753d65e20ff058a6f4bdf7e1f6f74b64d2c28f0d73f5a994082f43e65211
+  metadata.gz: f27d7c79f9e9e3fd7185471eca0b83c08ccbf441c2e03ec37ea578a944b5d1ac459bdde7af863e4332b072e090bda90698bf01b39de37b21ff2f301fce2f12c5
+  data.tar.gz: 2ce2882fb724ca7066026b5b2fbb6468f43c81d617c9cc9af4c8d56d8636b7850c39899018bc3a4ca3a1f0ea3f6d10bcf6595f3100f3d185de905f95ec9d6545

data/README.md

@@ -35,12 +35,12 @@ Persistent settings, custom labels and additional languages go into a [`.spreen.
 ## 3. Library Usage
 
 ```ruby
-require 'spreen/wiki'
+require 'spreen_wiki'
 
-Spreen::Wiki::Home.run(base_path: '.', organisation: 'your-org', repository: 'your-repo')
-Spreen::Wiki::Sidebar.run(base_path: '.', organisation: 'your-org', repository: 'your-repo')
-Spreen::Wiki::UnknownWikiCountListExporter.run(base_path: '.', output: 'report.txt')
-Spreen::Wiki::UnknownWikiListExporterForLLM.run(base_path: '.', group_by: 'Category', language: 'Japanese')
+SpreenWiki::Home.run(base_path: '.', organisation: 'your-org', repository: 'your-repo')
+SpreenWiki::Sidebar.run(base_path: '.', organisation: 'your-org', repository: 'your-repo')
+SpreenWiki::UnknownWikiCountListExporter.run(base_path: '.', output: 'report.txt')
+SpreenWiki::UnknownWikiListExporterForLLM.run(base_path: '.', group_by: 'Category', language: 'Japanese')
 ```
 
 All classes accept `base_path:`, `group_by:`, `language:`, `home_overflow:` plus the configuration keywords `organisation:`, `repository:`, `wiki_url:`, `owner_base_url:`, `template_dir:`, `excluded_dirs:`, `config_path:` (and `output:` on the exporters).
@@ -49,8 +49,9 @@ All classes accept `base_path:`, `group_by:`, `language:`, `home_overflow:` plus
 
 ### 4-1. Environment
 
-- Ruby 4.0.5
-- Bundler 4.0.x
+- Ruby 4.0.6
+- Gemfile 4.0.16
+- Bundler 4.0.16
 
 ```command
 $ bundle install

data/exe/spreen

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'spreen/wiki'
+require 'spreen_wiki'
 
-exit Spreen::Wiki::CLI.start
+exit SpreenWiki::CLI.start

data/lib/spreen-wiki.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 # Convenience shim so that both `require 'spreen-wiki'` (the gem name) and
-# `require 'spreen/wiki'` (the conventional path) work.
-require_relative 'spreen/wiki'
+# `require 'spreen_wiki'` (the conventional path) work.
+require_relative 'spreen_wiki'

data/lib/spreen_wiki/application.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'configuration'
+
+module SpreenWiki
+  # Base class for the wiki-organising commands. Loads the wiki tree under
+  # base_path, groups it by Owner or Category in either English or Japanese,
+  # and exposes the resulting maps to its subclasses. Grouping criteria,
+  # languages and labels are resolved through Configuration and can be
+  # extended via a `.spreen.yml` file.
+  class Application
+    class NotImplementedError < StandardError; end
+
+    # @rbs base_path: String
+    # @rbs group_by: String
+    # @rbs language: String
+    # @rbs home_overflow: (bool | String)
+    # @rbs **options: untyped
+    # @rbs return: untyped
+    def self.run(base_path: Dir.pwd, group_by: 'Owner', language: 'English', home_overflow: 'false', **)
+      instance = new(base_path:, group_by:, language:, home_overflow:, **)
+      instance.validate!
+      instance.run
+    end
+
+    # @rbs base_path: String
+    # @rbs group_by: String
+    # @rbs language: String
+    # @rbs home_overflow: (bool | String)
+    # @rbs config: Configuration?
+    # @rbs **options: untyped
+    # @rbs return: void
+    def initialize(base_path: Dir.pwd, group_by: 'Owner', language: 'English', home_overflow: 'false',
+                   config: nil, **)
+      @base_path       = base_path
+      @group_by        = group_by
+      @language        = language
+      @home_overflow   = parse_home_overflow(home_overflow)
+      @config          = config || Configuration.new(base_path:, **)
+      @path_to_home    = File.join(base_path, 'Home.md')
+      @path_to_sidebar = File.join(base_path, '_Sidebar.md')
+      @paths_to_wikis  = Dir[File.join(base_path, '**', '*.md')]
+      @excluded_paths  = @config.excluded_dirs.flat_map { |dir| Dir[File.join(base_path, dir, '**', '*.md')] }
+    end
+
+    # @rbs return: void
+    def validate!
+      raise ArgumentError, "Invalid group_by: `#{group_by}`" unless config.group_bys.include?(group_by)
+      raise ArgumentError, "Invalid language: `#{language}`" unless config.languages(group_by).include?(language)
+
+      validate_home_overflow!
+    end
+
+    # @rbs return: untyped
+    def run
+      raise NotImplementedError, 'This method must be implemented in each subclass.'
+    end
+
+    private
+
+    attr_reader :base_path,
+                :group_by,
+                :language,
+                :home_overflow,
+                :config,
+                :path_to_home,
+                :path_to_sidebar,
+                :paths_to_wikis,
+                :excluded_paths
+
+    # @rbs return: void
+    def validate_home_overflow!
+      return if [true, false].include?(home_overflow)
+
+      raise ArgumentError, "Invalid home_overflow: `#{home_overflow}` must be boolean"
+    end
+
+    # @rbs raw: (bool | String)
+    # @rbs return: (bool | String)
+    def parse_home_overflow(raw)
+      case raw
+      when 'true'  then true
+      when 'false' then false
+      else raw
+      end
+    end
+
+    # @rbs return: Array[String]
+    def target_paths
+      @target_paths ||= paths_to_wikis.reject do |path_to_wiki|
+        path_to_wiki == path_to_home ||
+          path_to_wiki == path_to_sidebar ||
+          excluded_paths.include?(path_to_wiki)
+      end
+    end
+
+    # @rbs return: Regexp
+    def target_regexp
+      @target_regexp ||= config.target_regexp(group_by)
+    end
+
+    # @rbs return: String
+    def no_declaration
+      @no_declaration ||= config.no_declaration(group_by, language)
+    end
+
+    # @rbs return: Hash[String, Array[String]]
+    def wiki_maps_with_namespace
+      @wiki_maps_with_namespace ||= begin
+        named      = Hash.new { |hash, namespace| hash[namespace] = [] } #: Hash[String, Array[String]]
+        undeclared = Hash.new { |hash, namespace| hash[namespace] = [] } #: Hash[String, Array[String]]
+        target_paths.each { |target_path| populate_namespace(target_path, named, undeclared) }
+        named.sort.to_h.merge(undeclared)
+      end
+    end
+
+    # @rbs target_path: String
+    # @rbs named: Hash[String, Array[String]]
+    # @rbs undeclared: Hash[String, Array[String]]
+    # @rbs return: void
+    def populate_namespace(target_path, named, undeclared)
+      return unless File.exist?(target_path)
+
+      namespace = namespace_for(target_path)
+      bucket    = namespace == no_declaration ? undeclared : named
+      bucket[namespace] << File.basename(target_path)
+    end
+
+    # @rbs target_path: String
+    # @rbs return: String
+    def namespace_for(target_path)
+      declaration = File.open(target_path, &:gets)
+      return no_declaration unless declaration&.start_with?(target_regexp)
+
+      declaration.chomp.gsub(target_regexp, '')
+    end
+
+    # @rbs return: Hash[String, Array[String]]
+    def owned_wiki_maps
+      @owned_wiki_maps ||= wiki_maps_with_namespace.select { |namespace, _| namespace.include?('@') }
+    end
+
+    # @rbs return: Hash[String, Array[String]]
+    def plain_wiki_maps
+      @plain_wiki_maps ||= wiki_maps_with_namespace.reject { |namespace, _| namespace.include?('@') }
+    end
+  end
+end

data/lib/spreen_wiki/cli.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'optparse'
+require_relative 'version'
+require_relative 'home'
+require_relative 'sidebar'
+require_relative 'unknown_wiki_count_list_exporter'
+require_relative 'unknown_wiki_list_exporter_for_llm'
+
+module SpreenWiki
+  # Command line interface behind the `spreen` executable:
+  # `spreen <update|count-report|llm-export> [options]`.
+  class CLI
+    HELP = <<~HELP
+      Usage: spreen <command> [options]
+
+      Commands:
+        update        Regenerate Home.md and _Sidebar.md from the wiki tree
+        count-report  Export a count report of the unknown-namespace wikis
+        llm-export    Export the unknown-namespace wiki list for an LLM
+        version       Print the version
+
+      Run `spreen <command> --help` to list the command's options.
+    HELP
+
+    # Flags shared by every command, mapped to the keyword arguments of the
+    # underlying classes. --exclude and the per-command flags are wired up
+    # separately because they need a type or a fixed value.
+    COMMON_OPTIONS = {
+      '--path PATH' => [:base_path, 'Path to the wiki clone (default: current directory)'],
+      '--group-by GROUP_BY' => [:group_by, 'Grouping criteria (default: Owner)'],
+      '--language LANGUAGE' => [:language, 'Language of the labels (default: English)'],
+      '--org ORGANISATION' => [:organisation, 'GitHub organisation/user hosting the wiki'],
+      '--repo REPOSITORY' => [:repository, 'GitHub repository whose wiki is organised'],
+      '--wiki-url URL' => [:wiki_url, 'Wiki URL (overrides the one derived from --org/--repo)'],
+      '--template-dir DIR' => [:template_dir, 'Directory of <group_by>/<language>.md Home templates'],
+      '--config FILE' => [:config_path, 'Config file path (default: <path>/.spreen.yml)']
+    }.freeze
+
+    # @rbs argv: Array[String]
+    # @rbs return: Integer
+    def self.start(argv = ARGV)
+      new(argv).run
+    end
+
+    # @rbs argv: Array[String]
+    # @rbs return: void
+    def initialize(argv)
+      @argv    = argv.dup
+      @options = { base_path: Dir.pwd, group_by: 'Owner', language: 'English', home_overflow: 'false' }
+    end
+
+    # @rbs return: Integer
+    def run
+      command = argv.shift
+      case command
+      when 'update', 'count-report', 'llm-export' then execute(command)
+      when 'version', '--version', '-v'           then print_version
+      when nil, 'help', '--help', '-h'            then print_help(command)
+      else unknown_command(command)
+      end
+    end
+
+    private
+
+    attr_reader :argv, :options
+
+    # @rbs command: String
+    # @rbs return: Integer
+    def execute(command)
+      parser(command).parse!(argv)
+      __send__(command.tr('-', '_'))
+      0
+    rescue ArgumentError, OptionParser::ParseError => e
+      warn e.message
+      1
+    end
+
+    # @rbs return: Integer
+    def print_version
+      puts VERSION
+      0
+    end
+
+    # @rbs command: String?
+    # @rbs return: Integer
+    def print_help(command)
+      puts HELP
+      command.nil? ? 1 : 0
+    end
+
+    # @rbs command: String
+    # @rbs return: Integer
+    def unknown_command(command)
+      warn "Unknown command: `#{command}`"
+      warn HELP
+      1
+    end
+
+    # @rbs return: void
+    def update
+      wiki_url = Home.run(**options)
+      Sidebar.run(**options)
+      puts 'Updated Home.md and _Sidebar.md.'
+      puts "Check them out at '#{wiki_url}' !!" if wiki_url
+    end
+
+    # @rbs return: void
+    def count_report
+      count_list_by_namespace, path_to_export = UnknownWikiCountListExporter.run(**options)
+      puts count_list_by_namespace
+      puts "Exported the unknown wiki count report to '#{path_to_export}'."
+    end
+
+    # @rbs return: void
+    def llm_export
+      path_to_export = UnknownWikiListExporterForLLM.run(**options)
+      puts "Exported the unknown wiki list for LLM to '#{path_to_export}'."
+    end
+
+    # @rbs command: String
+    # @rbs return: OptionParser
+    def parser(command)
+      OptionParser.new("Usage: spreen #{command} [options]") do |opt|
+        add_common_options(opt)
+        add_command_options(opt, command)
+      end
+    end
+
+    # @rbs opt: OptionParser
+    # @rbs return: void
+    def add_common_options(opt)
+      COMMON_OPTIONS.each do |flag, (key, description)|
+        opt.on(flag, description) { |value| options[key] = value }
+      end
+      opt.on('--exclude DIR1,DIR2', Array, 'Directories to skip while scanning') do |dirs|
+        options[:excluded_dirs] = dirs
+      end
+    end
+
+    # @rbs opt: OptionParser
+    # @rbs command: String
+    # @rbs return: void
+    def add_command_options(opt, command)
+      if command == 'update'
+        opt.on('--overflow', 'Split Home into per-namespace pages under wikis-by-owner/') do
+          options[:home_overflow] = 'true'
+        end
+      else
+        opt.on('--output FILENAME', 'Export filename (relative to --path unless absolute)') do |filename|
+          options[:output] = filename
+        end
+      end
+    end
+  end
+end

data/lib/spreen_wiki/configuration.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'yaml'
+
+module SpreenWiki
+  # Resolves the runtime configuration for a wiki checkout. Every value is
+  # looked up with the same precedence: explicit keyword argument, then the
+  # `.spreen.yml` file under base_path (or config_path), then the
+  # ORGANISATION_NAME environment variable (organisation only), then the
+  # built-in defaults.
+  class Configuration
+    CONFIG_FILENAME = '.spreen.yml'
+    EMPTY_HASH = {}.freeze #: Hash[String, untyped]
+    DEFAULT_TEMPLATE_DIR = File.expand_path(File.join(__dir__.to_s, 'templates'))
+    DEFAULT_EXCLUDED_DIRS = %w[spreen-wiki wikis-by-owner].freeze
+
+    # Built-in labels: how the first line of a wiki page is parsed (regexp),
+    # which namespace collects pages without a declaration (no_declaration),
+    # which namespaces the count report covers (unknown_namespaces) and which
+    # namespace the LLM export targets (llm_target_namespace). A config file
+    # can override any of these, add languages or add group_by criteria.
+    DEFAULT_LABELS = {
+      'Owner' => {
+        'regexp' => '[Oo]wner:\s?',
+        'languages' => {
+          'English' => {
+            'no_declaration' => 'Unowned',
+            'unknown_namespaces' => ['Unknown Owner nor Necessity', 'Unowned but Necessary', 'Unowned'],
+            'llm_target_namespace' => 'Unknown Owner nor Necessity'
+          },
+          'Japanese' => {
+            'no_declaration' => 'Owner記名なし',
+            'unknown_namespaces' => [
+              'Ownerチームが不明だが必要なページ群',
+              'Ownerチーム・要or不要が不明なページ群',
+              'Owner記名なし'
+            ],
+            'llm_target_namespace' => 'Ownerチーム・要or不要が不明なページ群'
+          }
+        }
+      },
+      'Category' => {
+        'regexp' => '[Cc]ategory:\s?',
+        'languages' => {
+          'English' => {
+            'no_declaration' => 'Uncategorised',
+            'unknown_namespaces' => ['Uncategorised'],
+            'llm_target_namespace' => 'Uncategorised'
+          },
+          'Japanese' => {
+            'no_declaration' => 'Category記載なし',
+            'unknown_namespaces' => ['Category記載なし'],
+            'llm_target_namespace' => 'Category記載なし'
+          }
+        }
+      }
+    }.freeze
+
+    attr_reader :organisation, :repository, :wiki_url, :owner_base_url, :excluded_dirs, :template_dir
+
+    # @rbs!
+    #   @organisation: String?
+    #   @repository: String?
+    #   @wiki_url: String?
+    #   @owner_base_url: String?
+    #   @excluded_dirs: Array[String]
+    #   @template_dir: String
+    #   @file: Hash[String, untyped]
+    #   @labels: Hash[String, untyped]
+
+    # @rbs base_path: String
+    # @rbs config_path: String?
+    # @rbs organisation: String?
+    # @rbs repository: String?
+    # @rbs wiki_url: String?
+    # @rbs owner_base_url: String?
+    # @rbs excluded_dirs: Array[String]?
+    # @rbs template_dir: String?
+    # @rbs return: void
+    def initialize(base_path:, config_path: nil, organisation: nil, repository: nil, wiki_url: nil,
+                   owner_base_url: nil, excluded_dirs: nil, template_dir: nil)
+      @file           = load_file(config_path || File.join(base_path, CONFIG_FILENAME))
+      @organisation   = resolve_organisation(organisation)
+      @repository     = resolve(repository, 'repository')
+      @wiki_url       = resolve_wiki_url(wiki_url)
+      @owner_base_url = resolve_owner_base_url(owner_base_url)
+      @excluded_dirs  = excluded_dirs || file.fetch('exclude', DEFAULT_EXCLUDED_DIRS)
+      @template_dir   = template_dir || file.fetch('template_dir', DEFAULT_TEMPLATE_DIR)
+      @labels         = deep_merge(DEFAULT_LABELS, file.fetch('labels', EMPTY_HASH))
+    end
+
+    # @rbs return: Array[String]
+    def group_bys
+      labels.keys
+    end
+
+    # @rbs group_by: String
+    # @rbs return: Array[String]
+    def languages(group_by)
+      label_for(group_by).fetch('languages', EMPTY_HASH).keys
+    end
+
+    # @rbs group_by: String
+    # @rbs return: Regexp
+    def target_regexp(group_by)
+      Regexp.new(label_for(group_by).fetch('regexp', ''))
+    end
+
+    # @rbs group_by: String
+    # @rbs language: String
+    # @rbs return: String
+    def no_declaration(group_by, language)
+      language_labels(group_by, language).fetch('no_declaration', '')
+    end
+
+    # @rbs group_by: String
+    # @rbs language: String
+    # @rbs return: Array[String]
+    def unknown_namespaces(group_by, language)
+      language_labels(group_by, language).fetch('unknown_namespaces', [])
+    end
+
+    # @rbs group_by: String
+    # @rbs language: String
+    # @rbs return: String
+    def llm_target_namespace(group_by, language)
+      language_labels(group_by, language).fetch('llm_target_namespace', '')
+    end
+
+    # @rbs group_by: String
+    # @rbs language: String
+    # @rbs return: String
+    def path_to_template(group_by, language)
+      File.join(template_dir, group_by.downcase, "#{language.downcase}.md")
+    end
+
+    private
+
+    attr_reader :file, :labels
+
+    # Treats empty strings the same as nil so that callers can pass values
+    # straight from optional environment variables or CLI flags.
+    # @rbs value: String?
+    # @rbs return: String?
+    def presence(value)
+      value unless value.nil? || value.empty?
+    end
+
+    # @rbs explicit: String?
+    # @rbs key: String
+    # @rbs return: String?
+    def resolve(explicit, key)
+      presence(explicit) || presence(file[key])
+    end
+
+    # @rbs explicit: String?
+    # @rbs return: String?
+    def resolve_organisation(explicit)
+      resolve(explicit, 'organisation') || presence(ENV.fetch('ORGANISATION_NAME', nil))
+    end
+
+    # @rbs explicit: String?
+    # @rbs return: String?
+    def resolve_wiki_url(explicit)
+      resolve(explicit, 'wiki_url') || default_wiki_url
+    end
+
+    # @rbs explicit: String?
+    # @rbs return: String?
+    def resolve_owner_base_url(explicit)
+      resolve(explicit, 'owner_base_url') || default_owner_base_url
+    end
+
+    # @rbs path: String
+    # @rbs return: Hash[String, untyped]
+    def load_file(path)
+      return {} unless File.exist?(path)
+
+      YAML.safe_load_file(path) || {}
+    end
+
+    # @rbs group_by: String
+    # @rbs return: Hash[String, untyped]
+    def label_for(group_by)
+      labels.fetch(group_by, EMPTY_HASH)
+    end
+
+    # @rbs group_by: String
+    # @rbs language: String
+    # @rbs return: Hash[String, untyped]
+    def language_labels(group_by, language)
+      label_for(group_by).fetch('languages', EMPTY_HASH).fetch(language, EMPTY_HASH)
+    end
+
+    # @rbs return: String?
+    def default_wiki_url
+      "https://github.com/#{organisation}/#{repository}/wiki" if organisation && repository
+    end
+
+    # @rbs return: String?
+    def default_owner_base_url
+      "https://github.com/orgs/#{organisation}/teams/" if organisation
+    end
+
+    # @rbs base: Hash[String, untyped]
+    # @rbs override: Hash[String, untyped]
+    # @rbs return: Hash[String, untyped]
+    def deep_merge(base, override)
+      base.merge(override) do |_key, old_value, new_value|
+        old_value.is_a?(Hash) && new_value.is_a?(Hash) ? deep_merge(old_value, new_value) : new_value
+      end
+    end
+  end
+end

data/lib/spreen_wiki/home.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'fileutils'
+require_relative 'application'
+
+module SpreenWiki
+  # Generates the wiki Home page, optionally splitting per-owner content out
+  # into `wikis-by-owner/<owner>.md` when home_overflow is enabled. Returns
+  # the configured wiki URL (if any) so callers can point at the result.
+  class Home < Application
+    # @rbs return: String?
+    def run
+      home_overflow ? write_concise_home_passage : write_home_passage
+      config.wiki_url
+    end
+
+    private
+
+    # @rbs return: String
+    def path_to_wikis_by_owner
+      @path_to_wikis_by_owner ||= File.join(base_path, 'wikis-by-owner')
+    end
+
+    # @rbs return: String
+    def path_to_home_template
+      path = config.path_to_template(group_by, language)
+      unless File.exist?(path)
+        raise ArgumentError, "Missing Home template: `#{path}`. Ship one there or configure template_dir."
+      end
+
+      path
+    end
+
+    # @rbs return: Array[String]
+    def home_passage
+      @home_passage ||= File.readlines(path_to_home_template).append("\n")
+    end
+
+    # @rbs return: void
+    def write_home_passage
+      FileUtils.rm_rf(path_to_wikis_by_owner)
+      owned_wiki_maps.each { |namespace, wikis| append_block(home_passage, namespace, wikis, owned: true) }
+      plain_wiki_maps.each { |namespace, wikis| append_block(home_passage, namespace, wikis, owned: false) }
+      File.write(path_to_home, home_passage.join.chomp)
+    end
+
+    # @rbs return: void
+    def write_concise_home_passage
+      FileUtils.mkdir_p(path_to_wikis_by_owner)
+      write_per_namespace_files
+      write_home_table_of_contents
+    end
+
+    # @rbs return: void
+    def write_per_namespace_files
+      owned_wiki_maps.each { |namespace, wikis| write_overflow_block(namespace, wikis, owned: true) }
+      plain_wiki_maps.each { |namespace, wikis| write_overflow_block(namespace, wikis, owned: false) }
+    end
+
+    # @rbs return: void
+    def write_home_table_of_contents
+      (owned_wiki_maps.keys + plain_wiki_maps.keys).each { |namespace| home_passage << "- [[#{namespace}]]\n" }
+      home_passage << "\n"
+      File.write(path_to_home, home_passage.join.chomp)
+    end
+
+    # @rbs passage: Array[String]
+    # @rbs namespace: String
+    # @rbs wikis: Array[String]
+    # @rbs owned: bool
+    # @rbs return: void
+    def append_block(passage, namespace, wikis, owned:)
+      passage << "#{heading_for(namespace, owned:)}\n"
+      passage << "\n"
+      wikis.each { |wiki| passage << "- [[#{wiki.gsub('.md', '')}]]\n" }
+      passage << "\n"
+    end
+
+    # @rbs namespace: String
+    # @rbs wikis: Array[String]
+    # @rbs owned: bool
+    # @rbs return: void
+    def write_overflow_block(namespace, wikis, owned:)
+      scratch = [] #: Array[String]
+      append_block(scratch, namespace, wikis, owned:)
+      File.write(File.join(path_to_wikis_by_owner, "#{namespace}.md"), scratch.join.chomp)
+    end
+
+    # @rbs namespace: String
+    # @rbs owned: bool
+    # @rbs return: String
+    def heading_for(namespace, owned:)
+      owner_base_url = config.owner_base_url
+      return "## #{namespace}" unless owned && owner_base_url
+
+      "## [#{namespace}](#{owner_base_url + namespace.delete('@')})"
+    end
+  end
+end