spreen-wiki 0.1.0 → 0.2.0

data/lib/spreen_wiki/sidebar.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'application'
+
+module SpreenWiki
+  # 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

data/lib/spreen_wiki/unknown_wiki_count_list_exporter.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'application'
+
+module SpreenWiki
+  # 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

data/lib/spreen_wiki/unknown_wiki_list_exporter_for_llm.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'application'
+
+module SpreenWiki
+  # 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

data/lib/{spreen/wiki → spreen_wiki}/version.rb

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

data/lib/spreen_wiki.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative 'spreen_wiki/version'
+require_relative 'spreen_wiki/configuration'
+require_relative 'spreen_wiki/application'
+require_relative 'spreen_wiki/home'
+require_relative 'spreen_wiki/sidebar'
+require_relative 'spreen_wiki/unknown_wiki_count_list_exporter'
+require_relative 'spreen_wiki/unknown_wiki_list_exporter_for_llm'
+require_relative 'spreen_wiki/cli'
+
+# 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 SpreenWiki
+end

data/sig/generated/spreen_wiki/application.rbs

@@ -0,0 +1,91 @@
+# Generated from lib/spreen_wiki/application.rb with RBS::Inline
+
+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: 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

data/sig/generated/spreen_wiki/cli.rbs

@@ -0,0 +1,68 @@
+# Generated from lib/spreen_wiki/cli.rb with RBS::Inline
+
+module SpreenWiki
+  # 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

data/sig/generated/spreen_wiki/configuration.rbs

@@ -0,0 +1,148 @@
+# Generated from lib/spreen_wiki/configuration.rb with RBS::Inline
+
+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: ::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

data/sig/generated/spreen_wiki/home.rbs

@@ -0,0 +1,52 @@
+# Generated from lib/spreen_wiki/home.rb with RBS::Inline
+
+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: () -> String?
+
+    private
+
+    # @rbs return: String
+    def path_to_wikis_by_owner: () -> String
+
+    # @rbs return: String
+    def path_to_home_template: () -> String
+
+    # @rbs return: Array[String]
+    def home_passage: () -> Array[String]
+
+    # @rbs return: void
+    def write_home_passage: () -> void
+
+    # @rbs return: void
+    def write_concise_home_passage: () -> void
+
+    # @rbs return: void
+    def write_per_namespace_files: () -> void
+
+    # @rbs return: void
+    def write_home_table_of_contents: () -> void
+
+    # @rbs passage: Array[String]
+    # @rbs namespace: String
+    # @rbs wikis: Array[String]
+    # @rbs owned: bool
+    # @rbs return: void
+    def append_block: (Array[String] passage, String namespace, Array[String] wikis, owned: bool) -> void
+
+    # @rbs namespace: String
+    # @rbs wikis: Array[String]
+    # @rbs owned: bool
+    # @rbs return: void
+    def write_overflow_block: (String namespace, Array[String] wikis, owned: bool) -> void
+
+    # @rbs namespace: String
+    # @rbs owned: bool
+    # @rbs return: String
+    def heading_for: (String namespace, owned: bool) -> String
+  end
+end

data/sig/generated/spreen_wiki/sidebar.rbs

@@ -0,0 +1,29 @@
+# Generated from lib/spreen_wiki/sidebar.rb with RBS::Inline
+
+module SpreenWiki
+  # Generates the wiki _Sidebar.md as a nested list of owners/categories and
+  # their wiki pages.
+  class Sidebar < Application
+    # @rbs return: void
+    def run: () -> void
+
+    private
+
+    # @rbs return: Array[String]
+    def wiki_list: () -> Array[String]
+
+    # @rbs return: void
+    def update_wiki_list: () -> void
+
+    # @rbs namespace: String
+    # @rbs wikis: Array[String]
+    # @rbs owned: bool
+    # @rbs return: void
+    def append_section: (String namespace, Array[String] wikis, owned: bool) -> void
+
+    # @rbs namespace: String
+    # @rbs owned: bool
+    # @rbs return: String
+    def section_heading: (String namespace, owned: bool) -> String
+  end
+end

data/sig/generated/spreen_wiki/unknown_wiki_count_list_exporter.rbs

@@ -0,0 +1,38 @@
+# Generated from lib/spreen_wiki/unknown_wiki_count_list_exporter.rb with RBS::Inline
+
+module SpreenWiki
+  # 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: ::String
+
+    # @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: String, ?group_by: String, ?language: String, ?home_overflow: bool | String, ?output: String?, **untyped) -> void
+
+    # @rbs return: [Array[String], String]
+    def run: () -> [ Array[String], String ]
+
+    private
+
+    attr_reader path_to_export: String
+
+    # @rbs filename: String
+    # @rbs return: String
+    def resolve_output_path: (String filename) -> String
+
+    # @rbs return: Array[String]
+    def namespace_list: () -> Array[String]
+
+    # @rbs return: Array[String]
+    def missing_count_list_by_namespace: () -> Array[String]
+
+    # @rbs return: Array[String]
+    def count_list_by_namespace: () -> Array[String]
+  end
+end

data/sig/generated/spreen_wiki/unknown_wiki_list_exporter_for_llm.rbs

@@ -0,0 +1,35 @@
+# Generated from lib/spreen_wiki/unknown_wiki_list_exporter_for_llm.rb with RBS::Inline
+
+module SpreenWiki
+  # 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: ::String
+
+    # @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: String, ?group_by: String, ?language: String, ?home_overflow: bool | String, ?output: String?, **untyped) -> void
+
+    # @rbs return: String
+    def run: () -> String
+
+    private
+
+    attr_reader path_to_export: String
+
+    # @rbs filename: String
+    # @rbs return: String
+    def resolve_output_path: (String filename) -> String
+
+    # @rbs return: String
+    def target_namespace: () -> String
+
+    # @rbs return: Array[String]
+    def unknown_wiki_list_for_llm: () -> Array[String]
+  end
+end

data/sig/generated/spreen_wiki/version.rbs

@@ -0,0 +1,5 @@
+# Generated from lib/spreen_wiki/version.rb with RBS::Inline
+
+module SpreenWiki
+  VERSION: ::String
+end

data/sig/generated/spreen_wiki.rbs

@@ -0,0 +1,8 @@
+# Generated from lib/spreen_wiki.rb with RBS::Inline
+
+# 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 SpreenWiki
+end