okf 1.11.0 → 1.13.0

data/lib/okf/cli/command.rb

@@ -190,22 +190,52 @@ module OKF
         parser.on("--tag TAG", "only concepts carrying this tag") { |v| options[:tag] = v } if keys.include?(:tag)
       end
 
-      def filter_entries(entries, options)
+      # The argument is resolved once per view, not once per entry: the `root`
+      # alias below has to consult the bundle's own directories, and that is a
+      # question about the whole set rather than about the row in hand.
+      #
+      # +dirs+ is that set, and every in-tree caller passes it (see #dir_scope)
+      # rather than deriving it from +entries+ — the catalog knows only
+      # directories that hold *concepts*, so a `root/` carrying an index.md and
+      # nothing else was invisible here while `dirs` and `index` (which read
+      # Bundle#directories) saw it. Two answers to one question about one
+      # bundle is how the alias survived its own fix.
+      #
+      # The default is a compatibility promise, not a shortcut: this base is
+      # what every plugin verb inherits, and 1.12.0 shipped the two-argument
+      # shape. An out-of-tree caller that never learned the third argument gets
+      # exactly the resolution it was written against — the alias folds with no
+      # directory set consulted — no better and no worse.
+      def filter_entries(entries, options, dirs = nil)
+        area = options[:area] && fold_area(options[:area], dirs)
+        base = options[:dir] && fold_dir(options[:dir], dirs)
         entries.select do |entry|
           (options[:type].nil? || fold(entry[:type]) == fold(options[:type])) &&
-            (options[:area].nil? || fold(entry[:area]) == fold_area(options[:area])) &&
-            (options[:dir].nil? || under_dir?(entry[:dir], options[:dir])) &&
+            (area.nil? || fold(entry[:top_dir]) == area) &&
+            (base.nil? || under_dir?(entry[:dir], base)) &&
             (options[:tag].nil? || entry[:tags].any? { |tag| fold(tag) == fold(options[:tag]) })
         end
       end
 
+      # The directory set only when a flag is going to consult it. Deriving it
+      # walks every path up to the root, and #filter_entries reads it solely to
+      # resolve the `root`/`--area` aliases — a plain listing, or a type/tag
+      # narrowing, never needs the walk.
+      def dir_scope(folder, options)
+        options[:dir] || options[:area] ? folder.directories : nil
+      end
+
       # The one rule --dir is built on: a dir names itself and everything beneath
       # it. `--dir foo` reaches foo/bar, `--dir foo/bar` narrows, and `--dir .`
       # needs no special case at all — nothing starts with "./", so the root
       # selects only what lives directly in it.
-      def under_dir?(entry_dir, wanted)
+      #
+      # +path+ arrives already folded, through #fold_dir for a user's argument
+      # and #fold for a stored one. A stored dir is never an alias — that is the
+      # distinction the old signature could not make, and it is what had a row
+      # named `root` counting the bundle root's subtree instead of its own.
+      def under_dir?(entry_dir, path)
         entry = fold(entry_dir)
-        path = fold_dir(wanted)
         entry == path || entry.start_with?("#{path}/")
       end
 
@@ -213,16 +243,34 @@ module OKF
         value.to_s.downcase
       end
 
-      def fold_area(value)
+      def fold_area(value, known = nil)
         folded = trim_slash(fold(value))
-        folded == "root" ? "(root)" : folded
+        folded == "root" && !names_dir?(known, "root") ? "(root)" : folded
       end
 
       # `.` is the stored spelling of the root everywhere; `root` is the one a
       # shell needs no quoting for, and the only reason the two exist.
-      def fold_dir(value)
+      #
+      # A bundle that really has a `root/` directory owns the word, and +known+
+      # — the directories that bundle actually holds — is what decides. The
+      # alias is a convenience; being able to name a directory at all is not, so
+      # the convenience yields. Without this, `--dir root` answered for the
+      # bundle root in such a bundle: the wrong concepts, exit 0, nothing said.
+      def fold_dir(value, known = nil)
         folded = trim_slash(fold(value))
-        folded.empty? || folded == "root" ? "." : folded
+        return "." if folded.empty?
+
+        folded == "root" && !names_dir?(known, "root") ? "." : folded
+      end
+
+      # Does the bundle hold a directory by this name? An ancestor counts: a
+      # bundle whose only concept sits in `root/deep` still has a `root`, and
+      # `--dir root` has to reach it by the prefix rule above.
+      def names_dir?(known, name)
+        Array(known).any? do |dir|
+          folded = fold(dir)
+          folded == name || folded.start_with?("#{name}/")
+        end
       end
 
       # The human views print a directory with the slash that says it is one —
@@ -307,7 +355,7 @@ module OKF
 
         stored = known.each_with_object({}) { |dir, out| out[fold(dir)] = dir }
         Array(options[:dirs]).each_with_object([]) do |path, out|
-          base = fold_dir(path)
+          base = fold_dir(path, known)
           next unless stored.key?(base)
 
           current = dir_parent(base)
@@ -331,7 +379,7 @@ module OKF
       # they do not define one. The ancestor chain is unioned on top by the
       # caller, which is also what tells a row apart from context.
       def select_dirs(dirs, options)
-        bases = Array(options[:dirs]).map { |path| fold_dir(path) }
+        bases = Array(options[:dirs]).map { |path| fold_dir(path, dirs) }
         depth = options[:depth]&.to_i
         return dirs if bases.empty? && depth.nil?
         # No --dir means the whole bundle is the starting point, which is *not*
@@ -373,10 +421,17 @@ module OKF
 
       # The ids the filters select, resolved through the catalog metadata — or nil
       # when no filter is active, meaning keep everything.
-      def filter_ids(folder, options)
+      #
+      # +dirs+ overrides the folder's own directory set, which is what a
+      # multi-bundle run passes: the `root` alias is a fact about a bundle, so
+      # resolving it per folder inside a loop let one `--dir root` mean the
+      # `root/` subtree in one bundle and the bundle root in the next, merged
+      # into a single ranking with nothing saying so. One invocation, one
+      # meaning — see Search#multi_search.
+      def filter_ids(folder, options, dirs = nil)
         return nil if options[:type].nil? && options[:area].nil? && options[:dir].nil? && options[:tag].nil?
 
-        filter_entries(folder.catalog, options).map { |entry| entry[:id] }
+        filter_entries(folder.catalog, options, dirs || dir_scope(folder, options)).map { |entry| entry[:id] }
       end
 
       # §9 best-effort: the graph is built from concepts that parse. Surface any that
@@ -421,15 +476,58 @@ module OKF
       # Parse options, then take zero or more bundle positionals (the multi-bundle
       # server) — directories or @refs. Returns the resolved array (possibly
       # empty), or nil (after reporting) so the caller returns 2.
-      def positional_dirs(parser, argv)
+      def positional_dirs(parser, argv, expand_groups: false)
         parser.parse!(argv)
-        dirs = argv.map { |dir| resolve_ref(dir) }
+        dirs = if expand_groups
+                 argv.flat_map { |arg| resolve_ref_expanding(arg) }
+               else
+                 argv.map { |dir| resolve_ref(dir) }
+               end
         dirs.include?(nil) ? nil : dirs
       rescue OptionParser::ParseError => e
         @err.puts e.message
         nil
       end
 
+      # Like #resolve_ref, but a group @ref fans out to its member directories —
+      # the multi-bundle expansion only `server` wants (single-bundle verbs reject
+      # a group in #resolve_registered). Always returns an array of dirs so the
+      # caller can flat_map, or nil (reported) to fail the run.
+      def resolve_ref_expanding(arg)
+        return [ resolve_ref(arg) ] unless arg.start_with?("@")
+
+        registry = load_registry
+        return [ nil ] unless registry
+
+        slug = OKF::Registry.normalize(arg[1..-1])
+        return [ resolve_ref(arg) ] if slug.empty? || registry.group?(slug).nil?
+
+        group_member_dirs(registry, slug)
+      end
+
+      # A group's member directories, in order, skipping ones whose directory has
+      # vanished with the same note `@all` gives — and populating +ref_slugs+ so the
+      # hub mounts each under its registered slug. nil (reported) when nothing
+      # readable is left, or on a hand-edited cycle.
+      def group_member_dirs(registry, slug)
+        dirs = []
+        registry.expand(slug).each do |entry|
+          if File.directory?(entry.path)
+            ref_slugs[entry.path] = entry.slug
+            dirs << entry.path
+          else
+            skip_registered(entry)
+          end
+        end
+        return dirs unless dirs.empty?
+
+        @err.puts "error: @#{slug} resolves to no readable bundle (okf registry list)"
+        nil
+      rescue OKF::Error => e
+        @err.puts "error: #{e.message}"
+        nil
+      end
+
       # "@slug" — or bare "@", the registry's default — names a registered bundle
       # wherever a <dir> goes; anything else must be a directory on disk. A
       # leading @ always means the registry (a directory literally named that way
@@ -452,15 +550,24 @@ module OKF
       # only `server` and the `registry` verbs rescue one. Returns nil after
       # reporting, so every caller returns 2.
       def load_registry
-        require "okf/registry"
-        OKF::Registry.load
+        open_registry
       rescue OKF::Error => e
         @err.puts "error: #{e.message}"
         nil
       end
 
-      # Resolve one @ref through the registry under $OKF_HOME (default ~/.okf).
-      # The slug part is normalized
+      # The registry a verb resolves against — the single seam that opts the CLI
+      # into discovery. `cwd: Dir.pwd` is what makes OKF::Registry.load walk up for
+      # a project-local .okf-registry.json; a library caller passing no cwd stays
+      # global-only. The registry subcommands and `server` open through here too,
+      # so a bare `okf server` inside a repo serves that repo's bundles.
+      def open_registry
+        require "okf/registry"
+        OKF::Registry.load(cwd: Dir.pwd)
+      end
+
+      # Resolve one @ref through the active registry — a discovered project-local
+      # one, else the global $OKF_HOME (default ~/.okf). The slug part is normalized
       # exactly as registration normalized it, so @One finds the bundle
       # registered from dir One — but never through #slugify's mint-a-name
       # placeholder, so "@***" is a bad ref rather than whatever is slugged
@@ -486,6 +593,19 @@ module OKF
 
         asked = ref[1..-1]
         slug = OKF::Registry.normalize(asked)
+
+        # A group is a set, and this verb takes one bundle. Reading its first member
+        # would answer confidently about a bundle the user never singled out — the
+        # silent-wrong-answer shape the second-bundle rule already forbids — so it is
+        # exit 2, with the two verbs that *can* take a group named.
+        group = slug.empty? ? nil : registry.group?(slug)
+        if group
+          count = group.members.size
+          @err.puts "error: @#{slug} names a group of #{count} #{count == 1 ? "member" : "members"}; " \
+                    "only `okf search` and `okf server` take a group"
+          return nil
+        end
+
         entry = if asked.empty?
                   registry.default # bare "@"
                 elsif slug.empty?

data/lib/okf/cli/dirs.rb

@@ -79,7 +79,7 @@ module OKF
       def subtree_counts(entries)
         entries.each_with_object({}) do |entry, out|
           out[entry[:dir]] = entries.reduce(0) do |sum, other|
-            under_dir?(other[:dir], entry[:dir]) ? sum + other[:count] : sum
+            under_dir?(other[:dir], fold(entry[:dir])) ? sum + other[:count] : sum
           end
         end
       end

data/lib/okf/cli/files.rb

@@ -33,7 +33,7 @@ module OKF
         folder = OKF::Bundle::Folder.load(dir)
         report_skipped(folder)
         entries = folder.catalog
-        selected = filter_entries(entries, options)
+        selected = filter_entries(entries, options, dir_scope(folder, options))
         return print_files_json(dir, selected, options) if options[:json]
 
         print_files(dir, selected, entries.size)

data/lib/okf/cli/graph.rb

@@ -15,22 +15,26 @@ module OKF
 
       def self.help_rows
         [
-          [ "graph     <dir|@slug> [--json] [--minimal] [--hubs]", "print the knowledge graph" ]
+          [ "graph     <dir|@slug> [--json] [--minimal] [--hubs]", "print the knowledge graph" ],
+          [ "graph     <dir|@slug> --traffic [--cut N]", "directories and the link traffic between them" ]
         ]
       end
 
       def call(argv)
-        options = { json: false, minimal: false, body: true, hubs: false }
+        options = { json: false, minimal: false, body: true, hubs: false, traffic: false, cut: nil }
         parser = OptionParser.new do |o|
-          o.banner = "Usage: okf graph <dir|@slug> [--json] [--minimal] [--no-body] [--hubs]"
+          o.banner = "Usage: okf graph <dir|@slug> [--json] [--minimal] [--no-body] [--hubs] [--traffic]"
           json_flags(o, options, "emit nodes and edges as JSON")
           o.on("--minimal", "leanest nodes (id + title); adds type/tag indexes") { options[:minimal] = true }
           o.on("--[no-]body", "include each concept's body (default: yes)") { |v| options[:body] = v }
-          o.on("--hubs", "rank concepts by inbound links, with the source areas") { options[:hubs] = true }
+          o.on("--hubs", "rank concepts by inbound links, with the source top-level dirs") { options[:hubs] = true }
+          o.on("--traffic", "collapse concepts into their dirs; count the links between them") { options[:traffic] = true }
+          o.on("--cut N", Integer, "least arc weight to draw (default: fitted to the bundle)") { |v| options[:cut] = v }
           help_flag(o)
         end
         dir = positional_dir(parser, argv) or return 2
 
+        return print_traffic(dir, options) if options[:traffic]
         return print_hubs(dir, options) if options[:hubs]
 
         folder = OKF::Bundle::Folder.load(dir)
@@ -52,16 +56,118 @@ module OKF
 
       private
 
+      # `graph --traffic`: concepts collapse into the directory they live in, and
+      # the links between two directories collapse into one weighted arc. It is
+      # the reduction that pays, and the measurement says why: on a typical
+      # bundle three quarters of all links cross a directory boundary, and those
+      # aggregate roughly ten-to-one — 227 links became 14 arcs on the bundle
+      # this was built for.
+      #
+      # The other half of the view is the cohesion column, which is the reason
+      # `refine` wants this. `--hubs` measures concepts; refine's step-3
+      # judgements ("does this directory prune?", "concern or container?") are
+      # about *directories*, and nothing measured those. Cohesion is a
+      # directory's internal traffic over its total, so it reads directly:
+      # near-zero with heavy inbound is a shared primitive, heavy outbound with
+      # nothing coming back is an index behaving like a container, and high is a
+      # directory that genuinely holds together.
+      def print_traffic(dir, options)
+        folder = OKF::Bundle::Folder.load(dir)
+        skeleton = folder.skeleton
+        cut = options[:cut] || skeleton.suggested_cut
+        return usage_error("--cut must be 1 or more, got #{cut}") if cut < 1
+
+        report_skipped(folder)
+        arcs = OKF::Bundle::Skeleton.arcs_above(skeleton.arcs, cut)
+        rows = dir_traffic(skeleton)
+        if options[:json]
+          emit_json(bundle_head(dir).merge(
+            "cut" => cut, "fitted" => options[:cut].nil?, "dirs" => stringify_rows(rows),
+            "arcs" => stringify_rows(arcs), "total_arcs" => skeleton.arcs.size
+          ))
+        else
+          @out.puts "Traffic — #{bundle_label(dir)} (#{skeleton.dirs.size} #{pluralize(skeleton.dirs.size, "dir")}, " \
+                    "#{counted(arcs.size, skeleton.arcs.size, "arc")} at weight #{cut} or more)"
+          print_dir_rows(rows)
+          print_arc_rows(arcs)
+        end
+        0
+      end
+
+      # Each directory's link traffic, split three ways. Counted over *every*
+      # arc, never the cut ones: the cut decides what is drawn, and a measurement
+      # that moved when the picture was tidied would be worthless as evidence.
+      def dir_traffic(skeleton)
+        out = Hash.new(0)
+        into = Hash.new(0)
+        skeleton.arcs.each do |arc|
+          out[arc[:source]] += arc[:weight]
+          into[arc[:target]] += arc[:weight]
+        end
+
+        skeleton.dirs.map do |row|
+          total = row[:internal] + out[row[:dir]] + into[row[:dir]]
+          row.merge(out: out[row[:dir]], in: into[row[:dir]],
+            cohesion: total.zero? ? nil : (100.0 * row[:internal] / total).round)
+        end
+      end
+
+      # An empty bundle gets no table at all — a column header over nothing is a
+      # heading that promises rows. The arc list is the opposite case and prints
+      # regardless (see print_arc_rows); the difference is that an empty arc list
+      # is a fact about the *cut*, and an empty dir table is a fact about the
+      # bundle the count line has already stated.
+      #
+      # Sorted by cohesion ascending, so the directories with a case to answer
+      # come first — a table that leads with the healthy ones buries its finding
+      # under the rows nobody needed to read. A directory with no traffic at all
+      # has no ratio to report and prints `—` rather than a 0% it did not earn.
+      def print_dir_rows(rows)
+        return if rows.empty?
+
+        ordered = rows.sort_by { |row| [ row[:cohesion] || 999, row[:dir] ] }
+        @out.puts
+        labels = ordered.map { |row| dir_label(row[:dir]) }
+        width = [ 3, *labels.map(&:length) ].max
+        @out.puts "  #{"Dir".ljust(width)}  Concepts  Internal   Out    In  Cohesion"
+        ordered.each_with_index do |row, i|
+          @out.puts "  #{labels[i].ljust(width)}  #{row[:count].to_s.rjust(8)}  #{row[:internal].to_s.rjust(8)}  " \
+                    "#{row[:out].to_s.rjust(4)}  #{row[:in].to_s.rjust(4)}  #{(row[:cohesion] ? "#{row[:cohesion]}%" : "—").rjust(8)}"
+        end
+      end
+
+      # The arc list is the answer this mode exists for, so it prints even when
+      # the cut emptied it — a heading over nothing says "the cut was too tight",
+      # where silence reads as "the bundle has no cross-links".
+      def print_arc_rows(arcs)
+        @out.puts
+        @out.puts "  Arcs"
+        return @out.puts "    (none at this cut)" if arcs.empty?
+
+        width = arcs.map { |arc| dir_label(arc[:source]).length }.max
+        twidth = arcs.map { |arc| dir_label(arc[:target]).length }.max
+        arcs.each do |arc|
+          @out.puts "    #{dir_label(arc[:source]).ljust(width)} → #{dir_label(arc[:target]).ljust(twidth)}  ×#{arc[:weight]}"
+        end
+      end
+
+      # The skeleton is symbol-keyed (it is a pure model, not a payload), and every
+      # other --json view in this CLI answers in strings. Converted at the edge, so
+      # the model stays the model.
+      def stringify_rows(rows)
+        rows.map { |row| stringify(row) }
+      end
+
       # `graph --hubs`: the inbound ranking with each hub's links grouped by
-      # source area — the "is this hub well-homed?" evidence. A hub whose
-      # inbound majority comes from outside its own area is a move candidate;
-      # --minimal/--no-body shape node payloads and change nothing here.
+      # source top-level dir — the "is this hub well-homed?" evidence. A hub whose
+      # inbound majority comes from outside its own top-level dir is a move
+      # candidate; --minimal/--no-body shape node payloads and change nothing here.
       def print_hubs(dir, options)
         folder = OKF::Bundle::Folder.load(dir)
         hubs = folder.hubs
         report_skipped(folder)
         if options[:json]
-          rows = hubs.map { |row| { "id" => row[:id], "area" => row[:area], "inbound" => row[:inbound], "by_area" => row[:by_area] } }
+          rows = hubs.map { |row| { "id" => row[:id], "top_dir" => row[:top_dir], "inbound" => row[:inbound], "by_top_dir" => row[:by_top_dir] } }
           emit_json(bundle_head(dir).merge("count" => hubs.size, "hubs" => rows))
         else
           @out.puts "Hubs — #{bundle_label(dir)} (#{counted(hubs.size, folder.concepts.size, "concept")} with inbound links)"
@@ -69,7 +175,7 @@ module OKF
           width = hubs.map { |row| row[:id].length }.max || 0
           dwidth = hubs.map { |row| row[:inbound].to_s.length }.max || 0
           hubs.each do |row|
-            sources = row[:by_area].map { |area, count| "#{area} #{count}" }.join(", ")
+            sources = row[:by_top_dir].map { |top_dir, count| "#{top_dir} #{count}" }.join(", ")
             @out.puts "  #{row[:id].ljust(width)}  ×#{row[:inbound].to_s.rjust(dwidth)}   #{sources}"
           end
         end

data/lib/okf/cli/index.rb

@@ -91,11 +91,11 @@ module OKF
       # 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) }
+        all_dirs = entries.map { |entry| entry[:dir] }
+        areas = Array(options[:areas]).map { |area| fold_dir(area, all_dirs) }
         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|