spreen-wiki 0.1.0 → 0.3.0

data/lib/spreen/wiki/configuration.rb

@@ -1,217 +0,0 @@
-# frozen_string_literal: true
-# rbs_inline: enabled
-
-require 'yaml'
-
-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 = '.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
-end

data/lib/spreen/wiki/home.rb

@@ -1,102 +0,0 @@
-# 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

@@ -1,50 +0,0 @@
-# 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/unknown_wiki_count_list_exporter.rb

@@ -1,61 +0,0 @@
-# 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

@@ -1,53 +0,0 @@
-# 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.rb

@@ -1,20 +0,0 @@
-# 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/sig/generated/spreen/wiki/application.rbs

@@ -1,93 +0,0 @@
-# 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

@@ -1,70 +0,0 @@
-# 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