metanorma-release 0.2.1

data/lib/metanorma/release/cache_store.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Metanorma
+  module Release
+    module CacheStore
+      def get(key)
+        raise NotImplementedError, "#{self.class} must implement #get"
+      end
+
+      def set(key, value)
+        raise NotImplementedError, "#{self.class} must implement #set"
+      end
+
+      def delete(key)
+        raise NotImplementedError, "#{self.class} must implement #delete"
+      end
+
+      def clear
+        raise NotImplementedError, "#{self.class} must implement #clear"
+      end
+
+      def keys
+        raise NotImplementedError, "#{self.class} must implement #keys"
+      end
+    end
+
+    class FileCacheStore
+      include CacheStore
+
+      def initialize(directory)
+        @directory = directory
+      end
+
+      def get(key)
+        path = file_path(key)
+        return nil unless File.exist?(path)
+
+        File.read(path)
+      end
+
+      def set(key, value)
+        FileUtils.mkdir_p(@directory)
+        File.write(file_path(key), value)
+      end
+
+      def delete(key)
+        path = file_path(key)
+        File.delete(path) if File.exist?(path)
+      end
+
+      def clear
+        return unless Dir.exist?(@directory)
+
+        Dir.glob(File.join(@directory, '*')).each do |f|
+          File.delete(f) if File.file?(f)
+        end
+      end
+
+      def keys
+        return [] unless Dir.exist?(@directory)
+
+        Dir.glob(File.join(@directory, '*')).select { |f| File.file?(f) }
+                                            .map { |f| File.basename(f) }
+      end
+
+      private
+
+      def file_path(key)
+        sanitized = key.gsub(/[^a-zA-Z0-9._-]/, '_')
+        File.join(@directory, sanitized)
+      end
+    end
+
+    class NullCacheStore
+      include CacheStore
+
+      def get(_key) = nil
+      def set(_key, _value) = nil
+      def delete(_key) = nil
+      def clear = nil
+      def keys = []
+    end
+  end
+end

data/lib/metanorma/release/change_detector.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Release
+    class ContentHashChangeDetector
+      include ChangeDetector
+
+      def initialize(previous_releases:)
+        @previous_releases = previous_releases
+      end
+
+      def detect(metadata, tag, force: false)
+        current = ContentHash.of_directory(metadata.output_dir, base: metadata.file_base_name)
+        previous = @previous_releases[tag.to_s]
+        changed = force || previous.nil? || !current.eql?(previous)
+        ChangeResult.new(changed?: changed, current_hash: current, previous_hash: previous)
+      end
+    end
+  end
+end

data/lib/metanorma/release/channel.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Release
+    class Channel
+      def self.parse(channel_string)
+        parts = channel_string.to_s.strip.split('/', 2)
+        if ChannelAudience.values.include?(parts[0])
+          new(audience: parts[0], category: parts[1] || 'default')
+        else
+          new(audience: ChannelAudience::PUBLIC, category: parts[0])
+        end
+      end
+
+      def self.parse_list(strings)
+        (strings || []).map { |s| parse(s) }
+      end
+
+      def self.public(category)
+        new(audience: ChannelAudience::PUBLIC, category: category)
+      end
+
+      def self.members(category)
+        new(audience: ChannelAudience::MEMBERS, category: category)
+      end
+
+      def self.internal(category)
+        new(audience: ChannelAudience::INTERNAL, category: category)
+      end
+
+      attr_reader :audience, :category
+
+      def initialize(audience:, category:)
+        @audience = audience
+        @category = category
+        freeze
+      end
+
+      def to_s
+        "#{audience}/#{category}"
+      end
+
+      def public?
+        audience == ChannelAudience::PUBLIC
+      end
+
+      def members?
+        audience == ChannelAudience::MEMBERS
+      end
+
+      def matches?(filter_channels)
+        filter_channels.any? { |c| eql?(Channel.parse(c)) }
+      end
+
+      def eql?(other)
+        other.is_a?(self.class) && audience == other.audience && category == other.category
+      end
+
+      def hash
+        [audience, category].hash
+      end
+    end
+  end
+end

data/lib/metanorma/release/channel_audience.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Release
+    module ChannelAudience
+      PUBLIC = 'public'
+      MEMBERS = 'members'
+      INTERNAL = 'internal'
+
+      ALL = [PUBLIC, MEMBERS, INTERNAL].freeze
+
+      def self.values
+        ALL
+      end
+
+      def self.from_string(raw)
+        normalized = raw.to_s.downcase.strip
+        return normalized if ALL.include?(normalized)
+
+        raise ArgumentError, "Unknown audience: #{raw.inspect}. Expected one of: #{ALL.join(', ')}"
+      end
+    end
+  end
+end

data/lib/metanorma/release/channel_config.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Metanorma
+  module Release
+    class ChannelConfig
+      def self.from_yaml(yaml_string)
+        data = YAML.safe_load(yaml_string, permitted_classes: [Symbol])
+        raise ArgumentError, 'Invalid channel config YAML' unless data.is_a?(Hash)
+
+        registry = ChannelRegistry.from_yaml(yaml_string)
+        defaults = data['defaults'] || {}
+        default_visibility = defaults['visibility'] || 'public'
+        default_channels = parse_channels(defaults['channels'])
+
+        new(registry: registry, default_visibility: default_visibility,
+            default_channels: default_channels)
+      end
+
+      def self.from_file(path)
+        if File.directory?(path)
+          channels_yml = File.join(path, 'channels.yml')
+          raise ArgumentError, "Channel config file not found: #{path}" unless File.exist?(channels_yml)
+
+          return from_file(channels_yml)
+        end
+
+        raise ArgumentError, "Channel config file not found: #{path}" unless File.exist?(path)
+
+        from_yaml(File.read(path))
+      end
+
+      def self.empty
+        new(registry: ChannelRegistry.all_allowed,
+            default_visibility: 'public', default_channels: [])
+      end
+
+      def initialize(registry:, default_visibility:, default_channels:)
+        @registry = registry
+        @default_visibility = default_visibility
+        @default_channels = default_channels.freeze
+        freeze
+      end
+
+      attr_reader :registry, :default_visibility, :default_channels
+
+      def self.parse_channels(list)
+        return [] unless list
+
+        list.map { |c| Channel.parse(c.to_s) }
+      end
+    end
+  end
+end

data/lib/metanorma/release/channel_filter.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Release
+    class ChannelFilter
+      def initialize(channels)
+        @channels = channels.map { |c| Channel.parse(c) }
+        @all = @channels.empty?
+      end
+
+      def matches?(release_metadata)
+        return true if @all
+
+        release_channels = (release_metadata['channels'] || []).map { |c| Channel.parse(c) }
+        release_channels.any? { |rc| @channels.any? { |fc| fc.eql?(rc) } }
+      end
+
+      def overlaps?(manifest_channels)
+        return true if @all
+
+        parsed = manifest_channels.map { |c| Channel.parse(c) }
+        parsed.any? { |mc| @channels.any? { |fc| fc.eql?(mc) } }
+      end
+    end
+  end
+end

data/lib/metanorma/release/channel_manifest.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Metanorma
+  module Release
+    class DocumentReleasePolicy
+      def self.from_defaults(visibility, channels)
+        ch = build_channels(visibility, channels)
+        is_released = visibility != 'private' || !ch.empty?
+        new(release: is_released, channels: ch, stage_allow_list: nil)
+      end
+
+      def self.from_entry(entry)
+        ch = build_channels(entry.visibility, entry.channels)
+        new(release: true, channels: ch, stage_allow_list: entry.stages_set)
+      end
+
+      def self.not_released
+        new(release: false, channels: [].freeze, stage_allow_list: nil)
+      end
+
+      def initialize(release:, channels:, stage_allow_list:)
+        @release = release
+        @channels = channels.freeze
+        @stage_allow_list = stage_allow_list
+        freeze
+      end
+
+      def release?
+        @release
+      end
+
+      attr_reader :channels, :stage_allow_list
+
+      def self.build_channels(visibility, explicit_channels)
+        return explicit_channels if explicit_channels && !explicit_channels.empty?
+
+        case visibility
+        when 'public'  then [Channel.public('default')]
+        when 'members' then [Channel.members('default')]
+        else [].freeze
+        end
+      end
+    end
+
+    class ManifestEntry
+      attr_reader :source, :pattern, :visibility, :channels, :stages
+
+      def initialize(source:, pattern:, visibility:, channels:, stages:)
+        @source = source
+        @pattern = pattern
+        @visibility = visibility
+        @channels = channels
+        @stages = stages
+        freeze
+      end
+
+      def match_priority
+        return 100 if source
+        return 50 + pattern.to_s.length if pattern
+
+        0
+      end
+
+      def stages_set
+        return nil if stages.nil? || stages.empty?
+
+        Set.new(stages.map(&:downcase))
+      end
+    end
+
+    class ChannelManifest
+      def self.parse(yaml_hash)
+        defaults = yaml_hash['defaults'] || {}
+        default_visibility = defaults['visibility'] || 'public'
+        default_channels = parse_channels(defaults['channels'])
+        entries = parse_entries(yaml_hash['documents'] || [])
+        config_source = yaml_hash['config']
+
+        new(entries: entries, default_visibility: default_visibility,
+            default_channels: default_channels, explicit: true, config_source: config_source)
+      end
+
+      def self.from_yaml(yaml_string)
+        yaml = YAML.safe_load(yaml_string, permitted_classes: [Symbol])
+        raise ArgumentError, 'Manifest YAML is empty' unless yaml.is_a?(Hash)
+
+        parse(yaml)
+      end
+
+      def self.from_file(path)
+        raise ArgumentError, "Manifest file not found: #{path}" unless File.exist?(path)
+
+        from_yaml(File.read(path))
+      end
+
+      def self.all_public
+        new(entries: [], default_visibility: 'public',
+            default_channels: [Channel.public('default')], explicit: false, config_source: nil)
+      end
+
+      def self.all_private
+        new(entries: [], default_visibility: 'private',
+            default_channels: [], explicit: false, config_source: nil)
+      end
+
+      def initialize(entries:, default_visibility:, default_channels:, explicit:, config_source: nil)
+        @entries = entries
+        @default_visibility = default_visibility
+        @default_channels = default_channels.freeze
+        @explicit = explicit
+        @config_source = config_source
+        freeze
+      end
+
+      def resolve(document)
+        return default_policy unless @explicit
+
+        entry = find_best_match(document)
+        return DocumentReleasePolicy.from_defaults(@default_visibility, @default_channels) unless entry
+
+        DocumentReleasePolicy.from_entry(entry)
+      end
+
+      def list_all
+        @entries
+      end
+
+      def all_channels
+        (@default_channels + @entries.flat_map(&:channels)).uniq
+      end
+
+      def explicit?
+        @explicit
+      end
+
+      attr_reader :config_source
+
+      private
+
+      def default_policy
+        DocumentReleasePolicy.from_defaults(@default_visibility, @default_channels)
+      end
+
+      def find_best_match(document)
+        source = extract_source(document)
+        matches = @entries.select { |e| entry_matches?(e, source) }
+        return nil if matches.empty?
+
+        matches.max_by(&:match_priority)
+      end
+
+      def entry_matches?(entry, source)
+        return false unless source
+        return true if entry.source && entry.source == source
+        return true if entry.pattern && File.fnmatch?(entry.pattern, source)
+
+        false
+      end
+
+      def extract_source(document)
+        document['source_path']
+      end
+
+      def self.parse_channels(channel_list)
+        return [] unless channel_list
+
+        channel_list.map { |c| Channel.parse(c.to_s) }
+      end
+
+      def self.parse_entries(documents)
+        documents.map do |doc|
+          validate_entry!(doc)
+          ManifestEntry.new(
+            source: doc['source'],
+            pattern: doc['pattern'],
+            visibility: doc['visibility'],
+            channels: parse_channels(doc['channels']),
+            stages: doc['stages']
+          )
+        end
+      end
+
+      def self.validate_entry!(doc)
+        return unless doc['source']&.include?('..')
+
+        raise ArgumentError, "Path traversal detected in manifest source: #{doc['source']}"
+      end
+    end
+  end
+end

data/lib/metanorma/release/channel_registry.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Metanorma
+  module Release
+    class ChannelRegistry
+      def self.from_yaml(yaml_string)
+        data = YAML.safe_load(yaml_string, permitted_classes: [Symbol])
+        raise ArgumentError, 'Invalid channel registry YAML' unless data.is_a?(Hash)
+
+        channels = parse_channel_list(data['channels'])
+        new(channels: channels)
+      end
+
+      def self.from_file(path)
+        raise ArgumentError, "Channel registry file not found: #{path}" unless File.exist?(path)
+
+        from_yaml(File.read(path))
+      end
+
+      def self.all_allowed
+        new(channels: [])
+      end
+
+      def initialize(channels:)
+        @channels = channels.freeze
+        @channel_set = channels.to_set
+        freeze
+      end
+
+      def valid?(channel)
+        return true if @channels.empty?
+
+        @channel_set.include?(channel)
+      end
+
+      def include?(channel_or_string)
+        valid?(Channel.parse(channel_or_string.to_s))
+      end
+
+      attr_reader :channels
+
+      def empty?
+        @channels.empty?
+      end
+
+      def self.parse_channel_list(list)
+        return [] unless list
+
+        list.filter_map do |entry|
+          case entry
+          when Hash   then Channel.parse(entry['name'].to_s)
+          when String then Channel.parse(entry)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/release/cli.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Metanorma
+  module Release
+    module CLI
+      module_function
+
+      def run(argv)
+        command = argv.shift
+        case command
+        when 'package'   then run_package(argv)
+        when 'publish'   then run_publish(argv)
+        when 'aggregate' then run_aggregate(argv)
+        when nil
+          warn 'Usage: mn-release <package|publish|aggregate> [options]'
+          exit 2
+        else
+          warn "Unknown command: #{command}"
+          exit 2
+        end
+      end
+
+      def run_package(argv)
+        config = parse_package_args(argv)
+        result = PackageCommand.new(config).call
+        print_package_result(result, config.dest)
+        exit(result.failed.empty? ? 0 : 1)
+      end
+
+      def run_publish(argv)
+        config = parse_publish_args(argv)
+        result = PublishCommand.new(config).call
+        print_publish_result(result)
+        exit(result.failed.empty? ? 0 : 1)
+      end
+
+      def run_aggregate(argv)
+        config = parse_aggregate_args(argv)
+        result = AggregateCommand.new(config).call
+        print_aggregate_result(result)
+        if config.min_documents.positive? && result.documents.length < config.min_documents
+          warn "Error: Found #{result.documents.length} documents, minimum is #{config.min_documents}"
+          exit 1
+        end
+        exit(result.failed_repos.empty? ? 0 : 1)
+      end
+
+      class << self
+        private
+
+        def parse_package_args(argv)
+          options = { output_dir: '_site', dest: 'dist', manifest: 'metanorma.release.yml',
+                      config_source: nil }
+          OptionParser.new do |opts|
+            opts.banner = 'Usage: mn-release package [options]'
+            opts.on('--output-dir DIR', 'Compiled docs directory') { |v| options[:output_dir] = v }
+            opts.on('--dest DIR', 'Destination for packages') { |v| options[:dest] = v }
+            opts.on('--manifest FILE', 'Release manifest file') { |v| options[:manifest] = v }
+            opts.on('--config SOURCE', 'Channel config (file path or platform ref)') { |v| options[:config_source] = v }
+          end.parse!(argv)
+          PackageCommand::Config.new(**options)
+        end
+
+        def parse_publish_args(argv)
+          options = { output_dir: '_site', platform: 'github', manifest: 'metanorma.release.yml',
+                      force: false, force_replace: [], channels: nil, concurrency: 4, token: nil,
+                      config_source: nil }
+          OptionParser.new do |opts|
+            opts.banner = 'Usage: mn-release publish [options]'
+            opts.on('--platform NAME', 'github|local') { |v| options[:platform] = v }
+            opts.on('--output-dir DIR', 'Compiled docs directory') { |v| options[:output_dir] = v }
+            opts.on('--manifest FILE', 'Release manifest file') { |v| options[:manifest] = v }
+            opts.on('--force', 'Force release even if unchanged') { |v| options[:force] = v }
+            opts.on('--force-replace PAT', 'Glob patterns for force-replace') { |v| options[:force_replace] << v }
+            opts.on('--channels CHANS', 'Override channels (comma-separated)') { |v| options[:channels] = v.split(',') }
+            opts.on('--concurrency N', Integer) { |v| options[:concurrency] = v }
+            opts.on('--token TOKEN', 'Platform auth token') { |v| options[:token] = v }
+            opts.on('--config SOURCE', 'Channel config (file path or platform ref)') { |v| options[:config_source] = v }
+          end.parse!(argv)
+          PublishCommand::Config.new(**options)
+        end
+
+        def parse_aggregate_args(argv)
+          options = { source: 'github', organizations: [], topic: 'metanorma-release',
+                      repos: nil, channels: [], stages: [], output_dir: '_site/cc',
+                      file_routing: 'by-document', cache_dir: nil,
+                      include_drafts: false, concurrency: 4, min_documents: 0, token: nil }
+          OptionParser.new do |opts|
+            opts.banner = 'Usage: mn-release aggregate [options]'
+            opts.on('--source SOURCE', 'github|local:PATH') { |v| options[:source] = v }
+            opts.on('--organizations ORGS', 'Comma-separated org list') { |v| options[:organizations] = v.split(',') }
+            opts.on('--topic TOPIC', 'Repository topic') { |v| options[:topic] = v }
+            opts.on('--repos REPOS', 'Explicit repo list (comma-separated)') { |v| options[:repos] = v.split(',') }
+            opts.on('--channels CHANS', 'Filter channels (comma-separated)') { |v| options[:channels] = v.split(',') }
+            opts.on('--stages STAGES', 'Filter stages (comma-separated)') { |v| options[:stages] = v.split(',') }
+            opts.on('--output-dir DIR', 'Output directory') { |v| options[:output_dir] = v }
+            opts.on('--file-routing MODE', 'by-document|flat|by-format') { |v| options[:file_routing] = v }
+            opts.on('--cache-dir DIR', 'Cache directory') { |v| options[:cache_dir] = v }
+            opts.on('--[no-]include-drafts', 'Include draft releases') { |v| options[:include_drafts] = v }
+            opts.on('--concurrency N', Integer) { |v| options[:concurrency] = v }
+            opts.on('--min-documents N', Integer) { |v| options[:min_documents] = v }
+            opts.on('--token TOKEN', 'Platform auth token') { |v| options[:token] = v }
+          end.parse!(argv)
+          AggregateCommand::Config.new(**options)
+        end
+
+        def print_package_result(result, dest)
+          released = result.released
+          puts "Packaged #{released.length} documents → #{dest}/"
+          released.each { |doc| puts "  #{doc.id}" }
+        end
+
+        def print_publish_result(result)
+          puts "Released #{result.released.length}, skipped #{result.skipped.length}, failed #{result.failed.length}"
+          result.released.each { |doc| puts "  RELEASED: #{doc.id} (#{doc.version.tag_component})" }
+          result.skipped.each { |doc| puts "  SKIPPED: #{doc.id} (unchanged)" }
+          result.failed.each { |f| puts "  FAILED: #{f[:document].id} - #{f[:error]}" }
+        end
+
+        def print_aggregate_result(result)
+          puts "Aggregated #{result.documents.length} documents from #{result.repo_count} repos"
+          puts "Index: #{result.channels_found.join(', ')}" unless result.channels_found.empty?
+        end
+      end
+    end
+  end
+end