spreen-wiki 0.1.0

data/lib/spreen/wiki/home.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require 'fileutils'
+require_relative 'application'
+
+module Spreen
+  module Wiki
+    # 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
+end

data/lib/spreen/wiki/sidebar.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'application'
+
+module Spreen
+  module Wiki
+    # Generates the wiki _Sidebar.md as a nested list of owners/categories and
+    # their wiki pages.
+    class Sidebar < Application
+      # @rbs return: void
+      def run
+        update_wiki_list
+        File.write(path_to_sidebar, wiki_list.join)
+      end
+
+      private
+
+      # @rbs return: Array[String]
+      def wiki_list
+        @wiki_list ||= []
+      end
+
+      # @rbs return: void
+      def update_wiki_list
+        owned_wiki_maps.each { |namespace, wikis| append_section(namespace, wikis, owned: true) }
+        plain_wiki_maps.each { |namespace, wikis| append_section(namespace, wikis, owned: false) }
+      end
+
+      # @rbs namespace: String
+      # @rbs wikis: Array[String]
+      # @rbs owned: bool
+      # @rbs return: void
+      def append_section(namespace, wikis, owned:)
+        wiki_list << "#{section_heading(namespace, owned:)}\n"
+        wikis.each { |wiki| wiki_list << "  - [[#{wiki.gsub('.md', '')}]]\n" }
+      end
+
+      # @rbs namespace: String
+      # @rbs owned: bool
+      # @rbs return: String
+      def section_heading(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
+end

data/lib/spreen/wiki/templates/category/english.md

@@ -0,0 +1,8 @@
+## How to Manage Wiki Pages
+
+This Home page manage wikis by category group.
+
+Absence of category declaration worsens maintainability and searchability.  
+Kindly make sure to articulate `Category: CATEGORY_NAME` of the top of each of your wiki page to avoid it.
+
+Also, please keep in mind that you do not have to edit Home and Sidebar by yourself, which are automatically updated by a GitHub Actions cron job.

data/lib/spreen/wiki/templates/category/japanese.md

@@ -0,0 +1,8 @@
+## Wiki ページの運用ルール
+
+このページは Category ごとに Wiki をグルーピングして一覧化しています。
+
+Category が不明だと、保守性と検索性の悪化が発生します。  
+治安維持のため、各ページの冒頭に `Category: カテゴリー名` を明記して頂きますようよろしくお願いします。
+
+なお、Home・Sidebar は専用の定期実行ジョブで自動更新しますので編集は不要です。

data/lib/spreen/wiki/templates/owner/english.md

@@ -0,0 +1,8 @@
+## How to Manage Wiki Pages
+
+This Home page manage wikis by owner group.
+
+Absence of ownership declaration worsens maintainability and searchability because it makes ambiguous which team the responsibility belongs to.  
+Kindly make sure to articulate `Owner: @OWNER_TEAM` of the top of each of your wiki page to avoid it.
+
+Also, please keep in mind that you do not have to edit Home and Sidebar by yourself, which are automatically updated by a GitHub Actions cron job.

data/lib/spreen/wiki/templates/owner/japanese.md

@@ -0,0 +1,8 @@
+## Wiki ページの運用ルール
+
+このページは Owner チームごとに Wiki をグルーピングして一覧化しています。
+
+Ownership をどのチームが持つのかが不明だと、責任の所在が不明瞭になり、保守性の悪化に伴うノイズの増加と検索性の悪化が発生します。  
+治安維持のため、各ページの冒頭に `Owner: @オーナーチーム` を明記して頂きますようよろしくお願いします。
+
+なお、Home・Sidebar は専用の定期実行ジョブで自動更新しますので編集は不要です。

data/lib/spreen/wiki/unknown_wiki_count_list_exporter.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'application'
+
+module Spreen
+  module Wiki
+    # Writes a sorted text report of how many wikis exist under each of the
+    # configured "unknown owner/category" namespaces.
+    class UnknownWikiCountListExporter < Application
+      DEFAULT_OUTPUT_FILENAME = 'unknown_wiki_count_list_by_namespace.txt'
+
+      # @rbs base_path: String
+      # @rbs group_by: String
+      # @rbs language: String
+      # @rbs home_overflow: (bool | String)
+      # @rbs output: String?
+      # @rbs **options: untyped
+      # @rbs return: void
+      def initialize(base_path: Dir.pwd, group_by: 'Owner', language: 'English', home_overflow: 'false',
+                     output: nil, **)
+        super(base_path:, group_by:, language:, home_overflow:, **)
+        @path_to_export = resolve_output_path(output || DEFAULT_OUTPUT_FILENAME)
+      end
+
+      # @rbs return: [Array[String], String]
+      def run
+        File.open(path_to_export, 'wb') { |f| f.puts(count_list_by_namespace) }
+        [count_list_by_namespace, path_to_export]
+      end
+
+      private
+
+      attr_reader :path_to_export #: String
+
+      # @rbs filename: String
+      # @rbs return: String
+      def resolve_output_path(filename)
+        File.absolute_path?(filename) ? filename : File.join(base_path, filename)
+      end
+
+      # @rbs return: Array[String]
+      def namespace_list
+        config.unknown_namespaces(group_by, language)
+      end
+
+      # @rbs return: Array[String]
+      def missing_count_list_by_namespace
+        (namespace_list - plain_wiki_maps.keys).map { |namespace| "#{namespace}: 0" }
+      end
+
+      # @rbs return: Array[String]
+      def count_list_by_namespace
+        @count_list_by_namespace ||= begin
+          counts = plain_wiki_maps.slice(*namespace_list).map { |namespace, wikis| "#{namespace}: #{wikis.length}" }
+          (counts + missing_count_list_by_namespace).sort
+        end
+      end
+    end
+  end
+end

data/lib/spreen/wiki/unknown_wiki_list_exporter_for_llm.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'application'
+
+module Spreen
+  module Wiki
+    # Writes a flat list of the wikis under the configured "unknown
+    # owner/category" namespace in a form suitable for feeding to an LLM.
+    class UnknownWikiListExporterForLLM < Application
+      DEFAULT_OUTPUT_FILENAME = 'unknown_wiki_list_for_llm.txt'
+
+      # @rbs base_path: String
+      # @rbs group_by: String
+      # @rbs language: String
+      # @rbs home_overflow: (bool | String)
+      # @rbs output: String?
+      # @rbs **options: untyped
+      # @rbs return: void
+      def initialize(base_path: Dir.pwd, group_by: 'Owner', language: 'English', home_overflow: 'false',
+                     output: nil, **)
+        super(base_path:, group_by:, language:, home_overflow:, **)
+        @path_to_export = resolve_output_path(output || DEFAULT_OUTPUT_FILENAME)
+      end
+
+      # @rbs return: String
+      def run
+        File.open(path_to_export, 'wb') { |f| f.puts(unknown_wiki_list_for_llm) }
+        path_to_export
+      end
+
+      private
+
+      attr_reader :path_to_export #: String
+
+      # @rbs filename: String
+      # @rbs return: String
+      def resolve_output_path(filename)
+        File.absolute_path?(filename) ? filename : File.join(base_path, filename)
+      end
+
+      # @rbs return: String
+      def target_namespace
+        config.llm_target_namespace(group_by, language)
+      end
+
+      # @rbs return: Array[String]
+      def unknown_wiki_list_for_llm
+        @unknown_wiki_list_for_llm ||= plain_wiki_maps.slice(target_namespace).values.flatten
+      end
+    end
+  end
+end

data/lib/spreen/wiki/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Spreen
+  module Wiki
+    VERSION = '0.1.0'
+  end
+end

data/lib/spreen/wiki.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'wiki/version'
+require_relative 'wiki/configuration'
+require_relative 'wiki/application'
+require_relative 'wiki/home'
+require_relative 'wiki/sidebar'
+require_relative 'wiki/unknown_wiki_count_list_exporter'
+require_relative 'wiki/unknown_wiki_list_exporter_for_llm'
+require_relative 'wiki/cli'
+
+module Spreen
+  # Spreens a GitHub wiki — the falcon's stoop, then the preen: generates
+  # Home.md and _Sidebar.md grouped by the Owner/Category declared on the
+  # first line of each page, and exports reports of the pages whose owner
+  # or category is unknown.
+  module Wiki
+  end
+end

data/lib/spreen-wiki.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+# 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'

data/sig/generated/spreen/wiki/application.rbs

@@ -0,0 +1,93 @@
+# Generated from lib/spreen/wiki/application.rb with RBS::Inline
+
+module Spreen
+  module Wiki
+    # 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: String, ?group_by: String, ?language: String, ?home_overflow: bool | String, **untyped) -> untyped
+
+      # @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: String, ?group_by: String, ?language: String, ?home_overflow: bool | String, ?config: Configuration?, **untyped) -> void
+
+      # @rbs return: void
+      def validate!: () -> void
+
+      # @rbs return: untyped
+      def run: () -> untyped
+
+      private
+
+      attr_reader base_path: untyped
+
+      attr_reader group_by: untyped
+
+      attr_reader language: untyped
+
+      attr_reader home_overflow: untyped
+
+      attr_reader config: untyped
+
+      attr_reader path_to_home: untyped
+
+      attr_reader path_to_sidebar: untyped
+
+      attr_reader paths_to_wikis: untyped
+
+      attr_reader excluded_paths: untyped
+
+      # @rbs return: void
+      def validate_home_overflow!: () -> void
+
+      # @rbs raw: (bool | String)
+      # @rbs return: (bool | String)
+      def parse_home_overflow: (bool | String raw) -> (bool | String)
+
+      # @rbs return: Array[String]
+      def target_paths: () -> Array[String]
+
+      # @rbs return: Regexp
+      def target_regexp: () -> Regexp
+
+      # @rbs return: String
+      def no_declaration: () -> String
+
+      # @rbs return: Hash[String, Array[String]]
+      def wiki_maps_with_namespace: () -> Hash[String, Array[String]]
+
+      # @rbs target_path: String
+      # @rbs named: Hash[String, Array[String]]
+      # @rbs undeclared: Hash[String, Array[String]]
+      # @rbs return: void
+      def populate_namespace: (String target_path, Hash[String, Array[String]] named, Hash[String, Array[String]] undeclared) -> void
+
+      # @rbs target_path: String
+      # @rbs return: String
+      def namespace_for: (String target_path) -> String
+
+      # @rbs return: Hash[String, Array[String]]
+      def owned_wiki_maps: () -> Hash[String, Array[String]]
+
+      # @rbs return: Hash[String, Array[String]]
+      def plain_wiki_maps: () -> Hash[String, Array[String]]
+    end
+  end
+end

data/sig/generated/spreen/wiki/cli.rbs

@@ -0,0 +1,70 @@
+# Generated from lib/spreen/wiki/cli.rb with RBS::Inline
+
+module Spreen
+  module Wiki
+    # Command line interface behind the `spreen` executable:
+    # `spreen <update|count-report|llm-export> [options]`.
+    class CLI
+      HELP: ::String
+
+      # 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: untyped
+
+      # @rbs argv: Array[String]
+      # @rbs return: Integer
+      def self.start: (?Array[String] argv) -> Integer
+
+      # @rbs argv: Array[String]
+      # @rbs return: void
+      def initialize: (Array[String] argv) -> void
+
+      # @rbs return: Integer
+      def run: () -> Integer
+
+      private
+
+      attr_reader argv: untyped
+
+      attr_reader options: untyped
+
+      # @rbs command: String
+      # @rbs return: Integer
+      def execute: (String command) -> Integer
+
+      # @rbs return: Integer
+      def print_version: () -> Integer
+
+      # @rbs command: String?
+      # @rbs return: Integer
+      def print_help: (String? command) -> Integer
+
+      # @rbs command: String
+      # @rbs return: Integer
+      def unknown_command: (String command) -> Integer
+
+      # @rbs return: void
+      def update: () -> void
+
+      # @rbs return: void
+      def count_report: () -> void
+
+      # @rbs return: void
+      def llm_export: () -> void
+
+      # @rbs command: String
+      # @rbs return: OptionParser
+      def parser: (String command) -> OptionParser
+
+      # @rbs opt: OptionParser
+      # @rbs return: void
+      def add_common_options: (OptionParser opt) -> void
+
+      # @rbs opt: OptionParser
+      # @rbs command: String
+      # @rbs return: void
+      def add_command_options: (OptionParser opt, String command) -> void
+    end
+  end
+end

data/sig/generated/spreen/wiki/configuration.rbs

@@ -0,0 +1,150 @@
+# Generated from lib/spreen/wiki/configuration.rb with RBS::Inline
+
+module Spreen
+  module Wiki
+    # 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: ::String
+
+      EMPTY_HASH: Hash[String, untyped]
+
+      DEFAULT_TEMPLATE_DIR: untyped
+
+      DEFAULT_EXCLUDED_DIRS: untyped
+
+      # 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: untyped
+
+      attr_reader organisation: untyped
+
+      attr_reader repository: untyped
+
+      attr_reader wiki_url: untyped
+
+      attr_reader owner_base_url: untyped
+
+      attr_reader excluded_dirs: untyped
+
+      attr_reader template_dir: untyped
+
+      @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: String, ?config_path: String?, ?organisation: String?, ?repository: String?, ?wiki_url: String?, ?owner_base_url: String?, ?excluded_dirs: Array[String]?, ?template_dir: String?) -> void
+
+      # @rbs return: Array[String]
+      def group_bys: () -> Array[String]
+
+      # @rbs group_by: String
+      # @rbs return: Array[String]
+      def languages: (String group_by) -> Array[String]
+
+      # @rbs group_by: String
+      # @rbs return: Regexp
+      def target_regexp: (String group_by) -> Regexp
+
+      # @rbs group_by: String
+      # @rbs language: String
+      # @rbs return: String
+      def no_declaration: (String group_by, String language) -> String
+
+      # @rbs group_by: String
+      # @rbs language: String
+      # @rbs return: Array[String]
+      def unknown_namespaces: (String group_by, String language) -> Array[String]
+
+      # @rbs group_by: String
+      # @rbs language: String
+      # @rbs return: String
+      def llm_target_namespace: (String group_by, String language) -> String
+
+      # @rbs group_by: String
+      # @rbs language: String
+      # @rbs return: String
+      def path_to_template: (String group_by, String language) -> String
+
+      private
+
+      attr_reader file: untyped
+
+      attr_reader labels: untyped
+
+      # 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: (String? value) -> String?
+
+      # @rbs explicit: String?
+      # @rbs key: String
+      # @rbs return: String?
+      def resolve: (String? explicit, String key) -> String?
+
+      # @rbs explicit: String?
+      # @rbs return: String?
+      def resolve_organisation: (String? explicit) -> String?
+
+      # @rbs explicit: String?
+      # @rbs return: String?
+      def resolve_wiki_url: (String? explicit) -> String?
+
+      # @rbs explicit: String?
+      # @rbs return: String?
+      def resolve_owner_base_url: (String? explicit) -> String?
+
+      # @rbs path: String
+      # @rbs return: Hash[String, untyped]
+      def load_file: (String path) -> Hash[String, untyped]
+
+      # @rbs group_by: String
+      # @rbs return: Hash[String, untyped]
+      def label_for: (String group_by) -> Hash[String, untyped]
+
+      # @rbs group_by: String
+      # @rbs language: String
+      # @rbs return: Hash[String, untyped]
+      def language_labels: (String group_by, String language) -> Hash[String, untyped]
+
+      # @rbs return: String?
+      def default_wiki_url: () -> String?
+
+      # @rbs return: String?
+      def default_owner_base_url: () -> String?
+
+      # @rbs base: Hash[String, untyped]
+      # @rbs override: Hash[String, untyped]
+      # @rbs return: Hash[String, untyped]
+      def deep_merge: (Hash[String, untyped] base, Hash[String, untyped] override) -> Hash[String, untyped]
+    end
+  end
+end