okf 1.10.0 → 1.11.0

data/lib/okf/cli/index.rb

@@ -5,9 +5,15 @@ module OKF
     # The progressive-disclosure map (spec §6): every directory that holds concepts
     # or carries an index.md, with its authored index body, a type/tag rollup, its
     # child directories, and — for a directory with no index.md — the listing
-    # synthesized from the concepts there. The "orient before you read" view. `--area`
-    # is repeatable (one or many directories; `root` is the bundle root); `--no-body`
-    # drops the prose to a skeleton; advisory, exit 0.
+    # synthesized from the concepts there. The "orient before you read" view. `--dir`
+    # is repeatable and selects a directory *and its subtree* (`root` is the bundle
+    # root), `--depth N` bounds how far below the starting point that goes, and
+    # `--no-body` drops the prose to a skeleton; advisory, exit 0.
+    #
+    # The two narrowings are what make the map usable on a deep bundle: every
+    # directory is a section, so a few hundred concepts is a map nobody reads at
+    # once. `--depth 1` is the top of the tree, `--dir X --depth 1` is one branch
+    # of it, and the pair walks down a level at a time.
     class Index < Command
       def self.id
         :index
@@ -19,26 +25,47 @@ module OKF
 
       def self.help_rows
         [
-          [ "index     <dir|@slug> [--json] [--area A] [--no-body]", "the index map: dirs, their listings and rollups" ]
+          [ "index     <dir|@slug> [--dir D] [--depth N] [--no-body]", "the index map: dirs, their listings and rollups" ]
         ]
       end
 
       def call(argv)
-        options = { json: false, body: true, areas: nil }
+        options = { json: false, body: true, dirs: nil, areas: nil, depth: nil, ancestors: true }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf index <dir|@slug> [--area AREA] [--no-body] [--json]"
+          o.banner = "Usage: okf index <dir|@slug> [--dir PATH] [--depth N] [--no-body] [--json]"
           json_flags(o, options, "emit the index map as JSON")
           projection_flags(o, options)
-          o.on("--area AREA", "only this directory/area (repeatable; `root` for the bundle root)") { |v| (options[:areas] ||= []) << v }
+          o.on("--dir PATH", "only this directory and the ones below it",
+            "(repeatable; `root` for the bundle root)") { |v| (options[:dirs] ||= []) << v }
+          depth_flag(o, options)
+          ancestors_flag(o, options)
+          o.on("--area AREA", "deprecated: use --dir (this directory exactly)") do |v|
+            (options[:areas] ||= []) << v
+            deprecated("--area", "--dir")
+          end
           o.on("--[no-]body", "include each index's prose body (default: yes)") { |v| options[:body] = v }
           help_flag(o)
         end
         dir = positional_dir(parser, argv) or return 2
+        bad_depth = depth_error(options)
+        return bad_depth if bad_depth
+        # --area is exact and names no starting point, so --depth has nothing to
+        # be relative *to*: the pair used to union the area with every directory
+        # at that depth from the root. Refusing beats answering with more.
+        #
+        # --dir is refused for the same reason and not a weaker one: one flag is
+        # exact and the other a prefix, so the pair came back with the area *and*
+        # the subtree — an answer to neither question, from a combination only
+        # someone mid-migration would type. A deprecated flag that quietly widens
+        # is worse than one that is merely old.
+        if options[:areas] && (options[:depth] || options[:dirs])
+          return usage_error("--area and #{options[:dirs] ? "--dir" : "--depth"} do not combine: use --dir")
+        end
 
         folder = OKF::Bundle::Folder.load(dir)
         report_skipped(folder)
         entries = folder.directory_index
-        selected = select_directories(entries, options[:areas])
+        selected, chain = select_directories(entries, options)
         if options[:json]
           # --no-body is shorthand for --except body, so asking for the body by
           # name in the same breath is a contradiction. Letting --fields quietly
@@ -48,30 +75,44 @@ module OKF
           end
 
           options[:except] = Array(options[:except]) + [ "body" ] unless options[:body] || options[:fields]
-          return print_index_map_json(dir, selected, options)
+          return print_index_map_json(dir, selected, chain, options)
         end
-        print_index_map(dir, selected, options[:body])
+        print_index_map(dir, selected, chain, options[:body])
         0
       end
 
       private
 
-      # Narrow the map to the named directories/areas — case-insensitive, `root`
-      # matching the bundle root (".") so no shell quoting is needed. No --area passed
-      # keeps the whole map.
-      def select_directories(entries, areas)
-        return entries if areas.nil? || areas.empty?
-
-        wanted = areas.map { |area| area.downcase == "root" ? "." : area.downcase }
-        entries.select { |entry| wanted.include?(entry[:dir].downcase) }
+      # Narrow the map — case-insensitive, `root` matching the bundle root (".").
+      # --dir takes the named directory *and its subtree* and --depth bounds how
+      # far below the starting point that reaches, both through the shared
+      # select_dirs so the whole CLI answers "which directories?" one way. The
+      # deprecated --area keeps its old exact match beside them, because a
+      # deprecated flag that quietly widens is worse than one that is merely old.
+      # Nothing passed keeps the whole map.
+      def select_directories(entries, options)
+        areas = Array(options[:areas]).map { |area| fold_dir(area) }
+        scoped = !options[:dirs].nil? || !options[:depth].nil?
+        return [ entries, [] ] if areas.empty? && !scoped
+
+        all_dirs = entries.map { |entry| entry[:dir] }
+        wanted = scoped ? select_dirs(all_dirs, options) : []
+        chain = ancestor_dirs(options, all_dirs) - wanted
+        selected = entries.select do |entry|
+          areas.include?(fold(entry[:dir])) || wanted.include?(entry[:dir]) || chain.include?(entry[:dir])
+        end
+        [ selected, chain ]
       end
 
-      def print_index_map(dir, entries, body)
+      def print_index_map(dir, entries, chain, body)
         noun = entries.size == 1 ? "directory" : "directories"
         @out.puts "Index map — #{bundle_label(dir)} (#{entries.size} #{noun})"
         entries.each do |entry|
           @out.puts
-          @out.puts "  #{index_dir_label(entry)}#{index_dir_meta(entry)}"
+          # ↑ marks a row the reader did not ask for: it is here to place the
+          # branch, not to answer about it.
+          up = chain.include?(entry[:dir]) ? "↑ " : ""
+          @out.puts "  #{up}#{index_dir_label(entry)}#{index_dir_meta(entry)}"
           subdirs = entry[:subdirs]
           @out.puts "    → #{subdirs.map { |sub| "#{File.basename(sub)}/" }.join("  ")}" unless subdirs.empty?
           if entry[:present]
@@ -83,7 +124,7 @@ module OKF
       end
 
       def index_dir_label(entry)
-        base = entry[:dir] == "." ? "(root)" : "#{entry[:dir]}/"
+        base = dir_label(entry[:dir], slash: true)
         entry[:present] ? base : "#{base}  (no index.md)"
       end
 
@@ -107,13 +148,14 @@ module OKF
         end
       end
 
-      def print_index_map_json(dir, entries, options)
-        emit_list_json(dir, "directories", entries.map { |entry| index_map_entry_json(entry) }, options)
+      def print_index_map_json(dir, entries, chain, options)
+        rows = entries.map { |entry| index_map_entry_json(entry, chain.include?(entry[:dir])) }
+        emit_list_json(dir, "directories", rows, options)
       end
 
-      def index_map_entry_json(entry)
+      def index_map_entry_json(entry, ancestor)
         {
-          "dir" => entry[:dir], "index_path" => entry[:index_path],
+          "dir" => entry[:dir], "ancestor" => ancestor, "index_path" => entry[:index_path],
           "present" => entry[:present], "synthesized" => entry[:synthesized],
           "count" => entry[:count], "types" => entry[:types], "tags" => entry[:tags],
           "subdirs" => entry[:subdirs], "body" => entry[:body],

data/lib/okf/cli/loose.rb

@@ -44,7 +44,7 @@ module OKF
       def loose_files(graph)
         titles = graph.nodes.map { |node| [ node[:id], node[:title] ] }.to_h
         graph.unlinked_ids
-             .map { |id| { id: id, title: titles[id], dir: File.dirname("#{id}.md") } }
+             .map { |id| { id: id, title: titles[id], dir: OKF.dir_of(id) } }
              .sort_by { |file| file[:id] }
       end
 
@@ -58,7 +58,7 @@ module OKF
         files.group_by { |file| file[:dir] }.sort_by(&:first).each do |folder, group|
           width = group.map { |file| File.basename("#{file[:id]}.md").length }.max
           @out.puts
-          @out.puts "  #{folder == "." ? "(root)" : "#{folder}/"}"
+          @out.puts "  #{dir_label(folder, slash: true)}"
           group.each do |file|
             @out.puts "    #{File.basename("#{file[:id]}.md").ljust(width)}  #{file[:title]}"
           end

data/lib/okf/cli/search.rb

@@ -34,7 +34,7 @@ module OKF
       def call(argv)
         options = { json: false, regexp: false, fuzzy: false, engine: nil }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf search <dir|@slug…|@all> <term…> [--engine NAME] [--regexp|--fuzzy] [--in FIELDS] [--type T] [--area A] [--tag T] [--json]"
+          o.banner = "Usage: okf search <dir|@slug…|@all> <term…> [--engine NAME] [--regexp|--fuzzy] [--in FIELDS] [--type T] [--dir D] [--tag T] [--json]"
           search_engine_note(o)
           json_flags(o, options, "emit the matches as JSON")
           projection_flags(o, options)

data/lib/okf/cli/server.rb

@@ -59,10 +59,16 @@ module OKF
       # Build the single-bundle Rack app and hand it to the runner (WEBrick by
       # default, injected so tests drive this without a socket).
       def run_server(folder, options)
-        app = OKF::Server::App.new(folder, title: options[:title] || folder.name, link: options[:link], layout: options[:layout])
+        # search_endpoint is named here rather than defaulted in App: the page
+        # resolves it against the URL the reader is on, and this is the layer that
+        # knows the app is mounted at the root. An embedding host mounting App
+        # elsewhere passes its own.
+        app = OKF::Server::App.new(folder, title: options[:title] || folder.name, link: options[:link],
+          layout: options[:layout], search_endpoint: "search")
         # minimal: the banner wants a count, not bodies — and Folder#graph is not
         # memoized, so a full build here parses every concept a second time (the
         # App builds its own) purely to print one number.
+        app.warm_search
         count = folder.graph(minimal: true).nodes.size
         @out.puts "serving #{count} #{pluralize(count, "concept")} at http://#{options[:bind]}:#{options[:port]} (Ctrl-C to stop)"
         serve(app, options)
@@ -92,6 +98,7 @@ module OKF
         # could not host — a folder deleted out from under one is the question
         # "where did my bundle go?", and only the registry can answer it.
         hub = OKF::Server::Hub.new(bundles, layout: options[:layout], registry: reg, writable: writable?(options))
+        hub.warm_search
         concepts = bundles.inject(0) { |sum, bundle| sum + bundle.folder.graph(minimal: true).nodes.size }
         @out.puts "serving #{bundles.size} #{pluralize(bundles.size,
           "bundle")}, #{concepts} #{pluralize(concepts, "concept")} at http://#{options[:bind]}:#{options[:port]} (Ctrl-C to stop)"

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
 
@@ -42,43 +42,68 @@ module OKF
         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_dir = directory_counts(folder)
         {
           concepts: entries.size,
+          dirs: by_dir.size,
           areas: by_area.size,
           types: by_type.size,
           cross_links: graph.edges.size,
           tags: graph.tag_index.size,
           by_type: by_type,
+          by_dir: by_dir,
           by_area: by_area
         }
       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_area` stays in --json for the
+        # deprecation window, but a screen that printed both would be teaching the
+        # vocabulary the rest of this change is retiring.
+        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], "areas" => stats[:areas],
           "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_area" => stats[:by_area]
         ))
       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[:area]
+        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 area 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],
+      "matches_by_ref" => %w[slug id title type dir area tags matched score snippet],
       "concepts" => %w[id title type description tags timestamp status backlog_ref dir area 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"