okf 1.10.0 → 1.12.0

data/lib/okf/cli/stats.rb

@@ -2,7 +2,7 @@
 
 module OKF
   class CLI
-    # Bundle rollups — concepts, types, areas, links, tags — in one screen.
+    # Bundle rollups — concepts, dirs, types, links, tags — in one screen.
     class Stats < Command
       def self.id
         :stats
@@ -14,7 +14,7 @@ module OKF
 
       def self.help_rows
         [
-          [ "stats     <dir|@slug> [--json]", "bundle rollups (concepts, types, areas, links, tags)" ]
+          [ "stats     <dir|@slug> [--json]", "bundle rollups (concepts, dirs, types, links, tags)" ]
         ]
       end
 
@@ -41,44 +41,69 @@ module OKF
         graph = folder.graph(minimal: true)
         entries = folder.catalog
         by_type = graph.type_index.transform_values(&:size).sort_by { |_, n| -n }.to_h
-        by_area = entries.group_by { |entry| entry[:area] }.transform_values(&:size).sort_by { |_, n| -n }.to_h
+        by_top_dir = entries.group_by { |entry| entry[:top_dir] }.transform_values(&:size).sort_by { |_, n| -n }.to_h
+        by_dir = directory_counts(folder)
         {
           concepts: entries.size,
-          areas: by_area.size,
+          dirs: by_dir.size,
+          top_dirs: by_top_dir.size,
           types: by_type.size,
           cross_links: graph.edges.size,
           tags: graph.tag_index.size,
           by_type: by_type,
-          by_area: by_area
+          by_dir: by_dir,
+          by_top_dir: by_top_dir
         }
       end
 
+      # Every directory the bundle has, with the concepts that live *directly* in
+      # it. Read off Bundle#directory_index — the same map `okf dirs` lists and
+      # `--dir` is answered against — rather than off the catalog, which knows
+      # only the directories that happen to hold a concept. Grouping the catalog
+      # made `stats` and `dirs` report different totals for one bundle, and left
+      # an addressable directory out of by_dir entirely: `--dir deeply` answers,
+      # but nothing in `stats` said `deeply` was there to ask about.
+      #
+      # A directory holding nothing directly therefore appears at 0. That is the
+      # honest reading — it is the same zero `okf dirs` prints in its Concepts
+      # column — and it keeps `dirs` equal to `by_dir.size`. Ties break by path so
+      # the order is total, not whatever the sort happened to leave.
+      def directory_counts(folder)
+        folder.directory_index
+              .map { |entry| [ entry[:dir], entry[:count] ] }
+              .sort_by { |dir, count| [ -count, dir ] }.to_h
+      end
+
       def print_stats(dir, stats)
         @out.puts "Stats — #{bundle_label(dir)}"
         @out.puts
         @out.puts "  concepts       #{stats[:concepts]}"
-        @out.puts "  areas          #{stats[:areas]}"
+        @out.puts "  dirs           #{stats[:dirs]}"
         @out.puts "  concept types  #{stats[:types]}"
         @out.puts "  cross-links    #{stats[:cross_links]}"
         @out.puts "  distinct tags  #{stats[:tags]}"
         print_stat_breakdown("By type", stats[:by_type])
-        print_stat_breakdown("By area", stats[:by_area])
+        # One grouping word in the human view: `by_top_dir` stays in --json (the
+        # first-segment rollup) but a screen that printed both it and `by_dir`
+        # would double up on one idea, so the human view shows the full-path cut.
+        print_stat_breakdown("By dir", stats[:by_dir]) { |label| dir_label(label) }
       end
 
       def print_stat_breakdown(title, counts)
         return if counts.empty?
 
-        width = counts.keys.map(&:length).max
+        labels = counts.keys.map { |key| block_given? ? yield(key) : key }
+        width = labels.map(&:length).max
         @out.puts
         @out.puts "  #{title}"
-        counts.each { |label, count| @out.puts "    #{label.ljust(width)}  #{count}" }
+        counts.each_with_index { |(_, count), i| @out.puts "    #{labels[i].ljust(width)}  #{count}" }
       end
 
       def print_stats_json(dir, stats)
         emit_json(bundle_head(dir).merge(
-          "concepts" => stats[:concepts], "areas" => stats[:areas],
+          "concepts" => stats[:concepts], "dirs" => stats[:dirs], "top_dirs" => stats[:top_dirs],
           "concept_types" => stats[:types], "cross_links" => stats[:cross_links], "distinct_tags" => stats[:tags],
-          "by_type" => stats[:by_type], "by_area" => stats[:by_area]
+          "by_type" => stats[:by_type], "by_dir" => stats[:by_dir], "by_top_dir" => stats[:by_top_dir]
         ))
       end
     end

data/lib/okf/cli/tags.rb

@@ -23,9 +23,12 @@ module OKF
       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]"
+          o.banner = "Usage: okf tags <dir|@slug> [--by type|dir] [--type T] [--dir D] [--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 }
+          o.on("--by DIM", %w[type dir area], "group the tags by a concept dimension (type | dir)") do |v|
+            options[:by] = v.to_sym
+            deprecated("--by area", "--by dir") if options[:by] == :area
+          end
           filter_flags(o, options, :type, :area)
           help_flag(o)
         end
@@ -38,10 +41,10 @@ module OKF
 
       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
+      # `tags --by type|dir`: the tag index re-cut per concept type or directory,
+      # 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.
+      # The --type/--dir filters narrow the concepts first, then the grouping cuts.
       def grouped_tags(dir, options)
         folder = OKF::Bundle::Folder.load(dir)
         report_skipped(folder)
@@ -66,7 +69,7 @@ module OKF
             entry = by_id[id]
             next if entry.nil?
 
-            key = options[:by] == :type ? entry_type(entry) : entry[:area]
+            key = group_key(entry, options[:by])
             ((groups[key] ||= {})[tag] ||= []) << id
             totals[tag] += 1
           end
@@ -83,10 +86,29 @@ module OKF
         OKF.blank?(entry[:type]) ? "Untyped" : entry[:type]
       end
 
+      # The group a concept falls in, in its *stored* spelling — `.` for the root
+      # under --by dir, never "(root)". The human label is applied at print time,
+      # so the JSON and the table cannot disagree about which one is the data.
+      def group_key(entry, dim)
+        case dim
+        when :type then entry_type(entry)
+        when :dir then entry[:dir]
+        else entry[:top_dir]
+        end
+      end
+
+      # `.` prints "(root)" bare; every other dir carries the trailing slash that
+      # says it is one. The deprecated --by area already stores "(root)" itself.
+      def group_label(key, dim)
+        return key if dim == :type
+
+        dir_label(key, slash: true)
+      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
+          label = group_label(key, dim)
           @out.puts
           @out.puts "  #{label} (#{rows.size} #{pluralize(rows.size, "tag")})"
           width = rows.map { |row| row[:tag].length }.max || 0

data/lib/okf/cli/types.rb

@@ -21,7 +21,7 @@ module OKF
       def call(argv)
         options = { json: false }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf types <dir|@slug> [--area A] [--tag T] [--json]"
+          o.banner = "Usage: okf types <dir|@slug> [--dir D] [--tag T] [--json]"
           json_flags(o, options, "emit the type index as JSON")
           filter_flags(o, options, :area, :tag)
           help_flag(o)

data/lib/okf/cli.rb

@@ -32,16 +32,17 @@ module OKF
     # Declared in emission order, so the "available:" list a typo prints reads
     # the same as the rows themselves.
     ROW_FIELDS = {
-      "matches" => %w[id title type area tags matched score snippet],
+      "matches" => %w[id title type dir top_dir tags matched score snippet],
       # Registry mode labels every row with the bundle it came from; a plain-dir
       # search has one bundle and no slug to carry. Two shapes, because the typo
       # guard checks against the *declared* one — a single shape covering both
       # would let `--fields slug` pass on a search whose rows have none, and hand
       # back an empty object per match under a count that says otherwise.
-      "matches_by_ref" => %w[slug id title type area tags matched score snippet],
-      "concepts" => %w[id title type description tags timestamp status backlog_ref dir area links_out links_in],
+      "matches_by_ref" => %w[slug id title type dir top_dir tags matched score snippet],
+      "concepts" => %w[id title type description tags timestamp status backlog_ref dir top_dir links_out links_in],
       "files" => %w[path id dir type title description],
-      "directories" => %w[dir index_path present synthesized count types tags subdirs body listing],
+      "directories" => %w[dir ancestor index_path present synthesized count types tags subdirs body listing],
+      "dirs" => %w[dir ancestor count subtree subdirs],
       "bundles" => %w[slug title dir mount default missing]
     }.freeze
 
@@ -103,9 +104,11 @@ module OKF
       search spans bundles: several leading @slugs, or @all for every registered one
       (@all skips a bundle whose directory is gone; a named @slug insists on it).
 
-      [filters] narrow a view to matching concepts: --type TYPE, --area AREA, --tag TAG
+      [filters] narrow a view to matching concepts: --type TYPE, --dir PATH, --tag TAG
       (each view takes the ones orthogonal to it; matching is case-insensitive).
-      tags --by DIM regroups the tags per concept dimension — type or area — with
+      --dir takes a directory and everything below it; `root` (or `.`) is the bundle
+      root. It replaces --area, which still works, warns, and matches one segment.
+      tags --by DIM regroups the tags per concept dimension — type or dir — with
       within-group counts, the view for curating a tag vocabulary.
       --json emits compact JSON (the machine substrate); add --pretty to indent it.
       --fields / --except project the JSON to the properties you want (search/index/catalog/files).
@@ -497,6 +500,7 @@ require "okf/cli/loose"
 require "okf/cli/validate"
 require "okf/cli/search"
 require "okf/cli/index"
+require "okf/cli/dirs"
 require "okf/cli/stats"
 require "okf/cli/types"
 require "okf/cli/tags"