okf 1.9.0 → 1.10.0

data/lib/okf/cli/tags.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # The tag index: which tags exist, how often, and on what. --by regroups them
+    # per concept dimension, which is the view for curating a vocabulary rather
+    # than reading one.
+    class Tags < Command
+      def self.id
+        :tags
+      end
+
+      def self.group
+        :read
+      end
+
+      def self.help_rows
+        [
+          [ "tags      <dir|@slug> [--json] [--by DIM] [filters]", "list tags with their concepts, by count" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false, by: nil }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf tags <dir|@slug> [--by type|area] [--type T] [--area A] [--json]"
+          json_flags(o, options, "emit the tag index as JSON")
+          o.on("--by DIM", %w[type area], "group the tags by a concept dimension (type | area)") { |v| options[:by] = v.to_sym }
+          filter_flags(o, options, :type, :area)
+          help_flag(o)
+        end
+        dir = positional_dir(parser, argv) or return 2
+
+        return grouped_tags(dir, options) if options[:by]
+
+        print_inverted_index(dir, "Tags", :tag, "tags", options)
+      end
+
+      private
+
+      # `tags --by type|area`: the tag index re-cut per concept type or top-level
+      # area, with within-group counts — the curation view. A tag confined to one
+      # group at count 1 is scattered; one recurring across groups is connective.
+      # The --type/--area filters narrow the concepts first, then the grouping cuts.
+      def grouped_tags(dir, options)
+        folder = OKF::Bundle::Folder.load(dir)
+        report_skipped(folder)
+        graph = folder.graph(minimal: true)
+        titles = graph.nodes.map { |node| [ node[:id], node[:title] ] }.to_h
+        groups = tag_groups(graph.tag_index, folder, options)
+        options[:json] ? print_grouped_tags_json(dir, options[:by], groups) : print_grouped_tags(dir, options[:by], groups, titles)
+        0
+      end
+
+      # [ [ group, rows ], … ] — groups sorted by name, rows shaped like index_rows'
+      # plus each tag's total across the narrowed set. A tag carried in several
+      # groups appears in each, counted per group; count/total per row is what
+      # makes a tag's spread — local to one group, or cutting across several —
+      # readable without cross-referencing the groups by hand.
+      def tag_groups(tag_index, folder, options)
+        by_id = filter_entries(folder.catalog, options).map { |entry| [ entry[:id], entry ] }.to_h
+        groups = {}
+        totals = Hash.new(0)
+        tag_index.each do |tag, ids|
+          ids.each do |id|
+            entry = by_id[id]
+            next if entry.nil?
+
+            key = options[:by] == :type ? entry_type(entry) : entry[:area]
+            ((groups[key] ||= {})[tag] ||= []) << id
+            totals[tag] += 1
+          end
+        end
+        groups.map do |key, tags|
+          rows = tags.map { |tag, ids| { tag: tag, count: ids.length, total: totals[tag], concepts: ids } }
+                     .sort_by { |row| [ -row[:count], row[:tag] ] }
+          [ key, rows ]
+        end.sort_by(&:first)
+      end
+
+      # A catalog entry's type for display — "Untyped" when blank, matching the graph.
+      def entry_type(entry)
+        OKF.blank?(entry[:type]) ? "Untyped" : entry[:type]
+      end
+
+      def print_grouped_tags(dir, dim, groups, titles)
+        @out.puts "Tags — #{bundle_label(dir)} (#{distinct_tags(groups)} distinct, by #{dim})"
+        groups.each do |key, rows|
+          label = dim == :area && key != "(root)" ? "#{key}/" : key
+          @out.puts
+          @out.puts "  #{label} (#{rows.size} #{pluralize(rows.size, "tag")})"
+          width = rows.map { |row| row[:tag].length }.max || 0
+          cwidth = [ 3, *rows.map { |row| count_cell(row).length } ].max
+          rows.each do |row|
+            names = row[:concepts].map { |id| titles[id] || id }.join(", ")
+            @out.puts "    #{row[:tag].ljust(width)}  #{count_cell(row).rjust(cwidth)}   #{truncate(names, 76)}"
+          end
+        end
+      end
+
+      # "2/3" when the tag spreads beyond this group, the plain count when it is
+      # local — so equality (locality 1.0) reads by absence.
+      def count_cell(row)
+        row[:count] == row[:total] ? row[:count].to_s : "#{row[:count]}/#{row[:total]}"
+      end
+
+      def print_grouped_tags_json(dir, dim, groups)
+        groups_json = groups.map do |key, rows|
+          rows_json = rows.map { |row| { "tag" => row[:tag], "count" => row[:count], "total" => row[:total], "concepts" => row[:concepts] } }
+          { dim.to_s => key, "count" => rows.size, "tags" => rows_json }
+        end
+        emit_json(bundle_head(dir).merge("count" => distinct_tags(groups), "by" => dim.to_s, "groups" => groups_json))
+      end
+
+      def distinct_tags(groups)
+        groups.flat_map { |_, rows| rows.map { |row| row[:tag] } }.uniq.size
+      end
+    end
+
+    register(Tags)
+  end
+end

data/lib/okf/cli/types.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # The type index: which types exist, how often, and on what.
+    class Types < Command
+      def self.id
+        :types
+      end
+
+      def self.group
+        :read
+      end
+
+      def self.help_rows
+        [
+          [ "types     <dir|@slug> [--json] [filters]", "list types with their concepts, by count" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf types <dir|@slug> [--area A] [--tag T] [--json]"
+          json_flags(o, options, "emit the type index as JSON")
+          filter_flags(o, options, :area, :tag)
+          help_flag(o)
+        end
+        dir = positional_dir(parser, argv) or return 2
+
+        print_inverted_index(dir, "Types", :type, "types", options)
+      end
+    end
+
+    register(Types)
+  end
+end

data/lib/okf/cli/validate.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # The §9 conformance judge: is this legal OKF? Binary and tolerant — it is
+    # forbidden from failing a bundle over a broken link or a missing optional
+    # field, which is lint's job. Exit 1 when non-conformant.
+    class Validate < Command
+      def self.id
+        :validate
+      end
+
+      def self.group
+        :judge
+      end
+
+      def self.help_rows
+        [
+          [ "validate  <dir|@slug> [--json]", "check OKF v0.1 conformance" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf validate <dir|@slug> [--json]"
+          json_flags(o, options, "emit a JSON report")
+          help_flag(o)
+        end
+        dir = positional_dir(parser, argv) or return 2
+
+        result = OKF::Bundle::Folder.load(dir).validate
+        options[:json] ? print_validation_json(dir, result) : print_validation(dir, result)
+        result.valid? ? 0 : 1
+      end
+
+      private
+
+      def print_validation(dir, result)
+        counts = result.counts
+        @out.puts "OKF v0.1 conformance — #{bundle_label(dir)}"
+        @out.puts "  concepts: #{counts[:concepts]}   index.md: #{counts[:indexes]}   log.md: #{counts[:logs]}"
+        result.errors.each { |e| @out.puts "  #{paint("✗ ERROR", 31)}  #{e[:path]}: #{e[:message]}" }
+        result.warnings.each { |w| @out.puts "  #{paint("! warn", 33)}  #{w[:path]}: #{w[:message]}" }
+        if result.valid? && result.warnings.empty?
+          @out.puts "  #{paint("✓ conformant — no issues", 32)}"
+        elsif result.valid?
+          @out.puts "  #{paint("✓ conformant", 32)} (#{result.warnings.size} warning(s))"
+        else
+          @out.puts "  #{paint("✗ non-conformant", 31)} (#{result.errors.size} error(s))"
+        end
+      end
+
+      def print_validation_json(dir, result)
+        emit_json(bundle_head(dir).merge(
+          "conformant" => result.valid?,
+          "counts" => result.counts,
+          "errors" => result.errors,
+          "warnings" => result.warnings
+        ))
+      end
+    end
+
+    register(Validate)
+  end
+end