okf 1.11.0 → 1.12.0

data/lib/okf/bundle/skeleton.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module OKF
+  class Bundle
+    # The graph reduced to what a reader can hold in their head. Pure — built from
+    # an OKF::Bundle::Graph's nodes and edges, does no I/O, and decides nothing
+    # about how any of it is drawn.
+    #
+    # A dense bundle is not dense in the way a hub-and-spoke picture is. Measured
+    # on a 47-concept bundle with 227 links: the top hub takes 13 inbound and the
+    # median takes 4, so there is no 80/20 to exploit — dropping two thirds of the
+    # concepts still leaves 53 edges. The density lives *between directories*:
+    # 173 of those 227 links (76%) cross a directory boundary, and they collapse
+    # into 50 directory-to-directory arcs of which the top ten carry half the mass.
+    # That is the reduction worth drawing, and it is why #arcs exists at all.
+    #
+    # ── the two things it produces, and who reads them ──
+    #
+    #   dirs + arcs   the reduction, as counts: one row per directory, one
+    #                 weighted arc per ordered pair. Printed by
+    #                 `okf graph --traffic`, with cohesion derived from them.
+    #   edges         every link with the cut it survives (`keep_at`). Nothing
+    #                 prints these — they are what lets the graph page lay a
+    #                 large bundle out on its strongest links first.
+    #
+    # Both are emitted *unthresholded*, and #suggested_cut names where to cut
+    # rather than cutting, so a caller narrows the picture without this class
+    # having to know what a picture is.
+    #
+    # Directories come off the concept *id* (OKF.dir_of), not the file path, so
+    # this agrees with #catalog, #hubs and the `--dir` filter. Bundle#directory_index
+    # groups by path instead — deliberately, since an index.md is a physical
+    # listing — so the two disagree for a concept whose frontmatter `id` moves it.
+    # This side follows the id because the edges do.
+    class Skeleton
+      attr_reader :dirs, :arcs, :edges
+
+      def self.build(bundle)
+        graph = bundle.graph(minimal: true)
+        ids = graph.nodes.map { |node| node[:id] }
+        pairs = graph.edges.map { |edge| [ edge[:source], edge[:target] ] }
+        dir_by_id = ids.map { |id| [ id, OKF.dir_of(id) ] }.to_h
+
+        new(
+          dirs: dirs_for(dir_by_id, pairs),
+          arcs: arcs_for(dir_by_id, pairs),
+          edges: edges_for(pairs, neighbours_for(ids, pairs))
+        )
+      end
+
+      # ── the cuts (see above) ──
+
+      def self.arcs_above(arcs, weight)
+        arcs.select { |arc| arc[:weight] >= weight }
+      end
+
+      def self.edges_within(edges, keep_at)
+        edges.select { |edge| edge[:keep_at] <= keep_at }
+      end
+
+      # ── the directories ──
+
+      # One row per directory that holds a concept, plus every ancestor up to the
+      # root, so the tree stays connected through a directory that holds nothing
+      # directly. `count` is direct and `subtree` is at-or-below — the same pair
+      # `okf dirs` prints, and for the same reason: a direct count alone cannot
+      # say where the mass is once the listing is cut off at a depth.
+      def self.dirs_for(dir_by_id, pairs)
+        direct = Hash.new(0)
+        dir_by_id.each_value { |dir| direct[dir] += 1 }
+        internal = Hash.new(0)
+        pairs.each do |source, target|
+          from = dir_by_id[source]
+          internal[from] += 1 if from == dir_by_id[target]
+        end
+
+        every_dir(direct.keys).map do |dir|
+          { dir: dir, parent: parent_of(dir), count: direct[dir],
+            subtree: direct.reduce(0) { |sum, (other, n)| under?(other, dir) ? sum + n : sum },
+            internal: internal[dir] }
+        end
+      end
+
+      # The cross-directory link mass, aggregated. Directed and never a self-arc:
+      # a directory's internal links are carried on its own row (`internal`),
+      # because an arc from a box to itself is a loop the eye has to untangle to
+      # learn a number the box could simply have carried.
+      def self.arcs_for(dir_by_id, pairs)
+        weights = Hash.new(0)
+        pairs.each do |source, target|
+          from = dir_by_id[source]
+          to = dir_by_id[target]
+          weights[[ from, to ]] += 1 unless from == to
+        end
+
+        weights.map { |(from, to), weight| { source: from, target: to, weight: weight } }
+               .sort_by { |arc| [ -arc[:weight], arc[:source], arc[:target] ] }
+      end
+
+      # ── where to cut ──
+
+      # The arc cut that leaves a readable picture, chosen from the *shape* of
+      # the bundle rather than fixed. A fixed cut cannot work: measured at
+      # weight 3 across ten bundles it left 2 arcs on one and 136 on another —
+      # too tight to be a picture at one end, no reduction at all at the other.
+      #
+      # What stays constant when a bundle grows is not the arc count but the
+      # arcs *per box*: a node-link diagram reads at roughly one to two edges
+      # per node regardless of size. So the target is 1.5 arcs per directory,
+      # and the cut is whatever weight delivers it — 22 arcs over 13 directories
+      # on one bundle, 191 over 95 on another, both about the same density.
+      #
+      # The floor of 8 is for the small end, where 1.5-per-box would cut a
+      # ten-arc bundle down to something that no longer shows how it is joined
+      # up. Ties are kept rather than broken, so the result is *at least* the
+      # target — the alternative is dropping one of two arcs that weigh the
+      # same, which is an arbitrary choice presented as a threshold.
+      def self.suggested_cut(arcs, dir_count)
+        target = [ (dir_count * 1.5).ceil, 8 ].max
+        return 1 if arcs.empty? || arcs.size <= target
+
+        arcs[target - 1][:weight]
+      end
+
+      # ── the edges, each with the cut it survives ──
+
+      # The local-degree sparsifier (Lindner et al.): every concept keeps its own
+      # most-connected neighbours, and an edge survives if *either* end kept it.
+      # The union is the point — it is what stops a sparsifier from stranding the
+      # quiet half of the bundle, which a global "drop the weakest edges" rule
+      # does immediately.
+      #
+      # Not the disparity filter, the usual name in this territory: that one reads
+      # an edge's weight against its endpoint's total, and every link here weighs
+      # exactly 1, which makes every proportion identical and the filter a coin
+      # toss. Weighted-graph tools do not transfer to an unweighted graph just
+      # because both are graphs.
+      #
+      # `keep_at` is the smallest cut (0–100) at which the edge appears, so the
+      # consumer's whole job is `keep_at <= n`. An edge to a node's single most
+      # connected neighbour keeps at 0 and is therefore never cut away: the
+      # skeleton always spans every linked concept.
+      def self.edges_for(pairs, neighbours)
+        order = ordered_neighbours(neighbours)
+        pairs.map do |source, target|
+          { source: source, target: target,
+            keep_at: [ keep_at(order, neighbours, source, target),
+                       keep_at(order, neighbours, target, source) ].min }
+        end
+      end
+
+      # Where `other` sits in `id`'s neighbours (1 = most connected), turned into
+      # the smallest cut that reaches it. Position 1 needs no budget at all; past
+      # that, a cut of n keeps ceil(degree ** n/100) neighbours, so the answer is
+      # the least n satisfying that — solved directly rather than searched, and
+      # pinned against the definition it came from in the unit test.
+      def self.keep_at(order, neighbours, id, other)
+        position = order[id].index(other) + 1
+        return 0 if position == 1
+
+        degree = neighbours[id].size
+        (100 * Math.log(position - 1) / Math.log(degree)).floor + 1
+      end
+
+      def self.ordered_neighbours(neighbours)
+        neighbours.each_with_object({}) do |(id, set), out|
+          out[id] = set.sort_by { |other| [ -neighbours[other].size, other ] }
+        end
+      end
+
+      # Undirected neighbour sets. A link is structure regardless of which end
+      # authored it, and a concept every page cites but that cites nothing back
+      # is as central as one that does the citing.
+      def self.neighbours_for(ids, pairs)
+        sets = ids.map { |id| [ id, Set.new ] }.to_h
+        pairs.each do |source, target|
+          sets[source] << target if sets.key?(source) && sets.key?(target)
+          sets[target] << source if sets.key?(source) && sets.key?(target)
+        end
+        sets
+      end
+
+      # ── path arithmetic (pure; the bundle root is ".") ──
+
+      def self.every_dir(dirs)
+        seen = {}
+        dirs.each do |dir|
+          current = dir
+          loop do
+            seen[current] = true
+            break if current == "."
+
+            current = parent_of(current)
+          end
+        end
+        seen.keys.sort_by { |dir| dir == "." ? "" : dir }
+      end
+
+      def self.parent_of(dir)
+        return nil if dir == "."
+
+        File.dirname(dir)
+      end
+
+      # At or below — the same rule `--dir` is answered against, so a row's
+      # `subtree` and what `--dir <that row>` returns can never disagree.
+      def self.under?(dir, ancestor)
+        return true if ancestor == "."
+
+        dir == ancestor || dir.start_with?("#{ancestor}/")
+      end
+
+      def initialize(dirs:, arcs:, edges:)
+        @dirs = dirs
+        @arcs = arcs
+        @edges = edges
+      end
+
+      def suggested_cut
+        @suggested_cut ||= self.class.suggested_cut(arcs, dirs.size)
+      end
+
+      # The `keep_at` of each edge in +edges+, in *its* order — so a caller
+      # holding an OKF::Bundle::Graph can line the two up. Matched on the pair
+      # rather than by index: both lists derive from the same graph and so are
+      # already parallel today, and an index-aligned read would go wrong in
+      # silence on the day one of them stops being built that way.
+      def cuts_for(graph_edges)
+        by_pair = edges.each_with_object({}) { |edge, out| out[[ edge[:source], edge[:target] ]] = edge[:keep_at] }
+        graph_edges.map { |edge| by_pair[[ edge[:source], edge[:target] ]] || 0 }
+      end
+
+      # What the drawn views read. `edges` stays out: it is per-link data whose
+      # only consumer needs it at boot, before any fetch could answer — so it
+      # rides inline with the graph instead (see OKF::Render::Graph#edge_cuts_json).
+      def to_h
+        { dirs: dirs, arcs: arcs, suggested_cut: suggested_cut }
+      end
+    end
+  end
+end

data/lib/okf/bundle.rb

@@ -95,6 +95,10 @@ module OKF
       Graph.build(self, minimal: minimal, body: body)
     end
 
+    def skeleton
+      Skeleton.build(self)
+    end
+
     # Rich per-concept metadata the catalog / files / stats consumers want but the
     # lean graph omits — the descriptive frontmatter fields plus in/out link degree
     # taken from the graph edges. Pure: derived from the concepts and their links,
@@ -119,28 +123,28 @@ module OKF
           status: concept.frontmatter["status"]&.to_s,
           backlog_ref: concept.frontmatter["backlog_ref"]&.to_s,
           dir: OKF.dir_of(id),
-          area: area_of(id),
+          top_dir: top_dir_of(id),
           links_out: out_degree[id],
           links_in: in_degree[id]
         }
       end.sort_by { |entry| entry[:id] }
     end
 
-    # Concepts ranked by inbound link degree, each with the areas its inbound
-    # links come from — the evidence for "is this hub well-homed?": a hub whose
-    # inbound majority is foreign to its own area is a move candidate, one with
-    # a single dominant foreign area already names its better home. Only
-    # concepts with at least one inbound link appear. Pure: derived from the
-    # graph edges. Shared by the `okf graph --hubs` view.
+    # Concepts ranked by inbound link degree, each with the top-level dirs its
+    # inbound links come from — the evidence for "is this hub well-homed?": a hub
+    # whose inbound majority is foreign to its own top-level dir is a move
+    # candidate, one with a single dominant foreign dir already names its better
+    # home. Only concepts with at least one inbound link appear. Pure: derived
+    # from the graph edges. Shared by the `okf graph --hubs` view.
     def hubs
       inbound = {}
       graph(minimal: true).edges.each do |edge|
-        (inbound[edge[:target]] ||= Hash.new(0))[area_of(edge[:source])] += 1
+        (inbound[edge[:target]] ||= Hash.new(0))[top_dir_of(edge[:source])] += 1
       end
 
       inbound.map do |id, sources|
-        by_area = sources.sort_by { |area, count| [ -count, area ] }.to_h
-        { id: id, area: area_of(id), inbound: by_area.values.reduce(0, :+), by_area: by_area }
+        by_top_dir = sources.sort_by { |top_dir, count| [ -count, top_dir ] }.to_h
+        { id: id, top_dir: top_dir_of(id), inbound: by_top_dir.values.reduce(0, :+), by_top_dir: by_top_dir }
       end.sort_by { |row| [ -row[:inbound], row[:id] ] }
     end
 
@@ -189,9 +193,10 @@ module OKF
 
     private
 
-    # A concept's top-level area, derived from its id — the same derivation the
-    # catalog exposes, so every grouped view labels the bundle root "(root)".
-    def area_of(id)
+    # A concept's top-level dir, derived from its id — the first path segment, the
+    # same derivation the catalog exposes, so every grouped view labels the bundle
+    # root "(root)". OKF.dir_of keeps the levels this one rolls up.
+    def top_dir_of(id)
       id.include?("/") ? id.split("/").first : "(root)"
     end
 

data/lib/okf/cli/catalog.rb

@@ -2,8 +2,8 @@
 
 module OKF
   class CLI
-    # Every concept with its metadata, grouped by area. The widest of the read
-    # views, and the one the others narrow down from.
+    # Every concept with its metadata, grouped by top-level dir. The widest of the
+    # read views, and the one the others narrow down from.
     class Catalog < Command
       def self.id
         :catalog
@@ -15,7 +15,7 @@ module OKF
 
       def self.help_rows
         [
-          [ "catalog   <dir|@slug> [--json] [filters]", "list concepts with metadata, by area" ]
+          [ "catalog   <dir|@slug> [--json] [filters]", "list concepts with metadata, by top-level dir" ]
         ]
       end
 
@@ -44,9 +44,9 @@ module OKF
 
       def print_catalog(dir, entries, total)
         @out.puts "Catalog — #{bundle_label(dir)} (#{counted(entries.size, total, "concept")})"
-        entries.group_by { |entry| entry[:area] }.sort_by(&:first).each do |area, group|
+        entries.group_by { |entry| entry[:top_dir] }.sort_by(&:first).each do |top_dir, group|
           @out.puts
-          @out.puts "  #{area == "(root)" ? "(root)" : "#{area}/"} (#{group.size})"
+          @out.puts "  #{top_dir == "(root)" ? "(root)" : "#{top_dir}/"} (#{group.size})"
           group.each do |entry|
             links = entry[:links_out] + entry[:links_in]
             meta = [ entry[:type], (links.positive? ? "↳#{links}" : nil), entry[:status] ].compact.join("  ·  ")

data/lib/okf/cli/command.rb

@@ -193,7 +193,7 @@ module OKF
       def filter_entries(entries, options)
         entries.select do |entry|
           (options[:type].nil? || fold(entry[:type]) == fold(options[:type])) &&
-            (options[:area].nil? || fold(entry[:area]) == fold_area(options[:area])) &&
+            (options[:area].nil? || fold(entry[:top_dir]) == fold_area(options[:area])) &&
             (options[:dir].nil? || under_dir?(entry[:dir], options[:dir])) &&
             (options[:tag].nil? || entry[:tags].any? { |tag| fold(tag) == fold(options[:tag]) })
         end
@@ -421,15 +421,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 +495,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 +538,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/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