okf 1.8.0 → 1.10.0

data/lib/okf/cli/search.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # Ranked text retrieval — the browser page's search brought to the CLI on the
+    # same engine (a MiniFTS index) and extended to bodies. Terms after the
+    # directory are ANDed tokens, matched whole or by prefix (Ruby regexps with
+    # --regexp, typo tolerance with --fuzzy); rows rank by BM25+ weighted toward
+    # where they hit (title > id > tags > type/description > body) and carry one
+    # bounded context snippet, so "which concept covers X?" costs a few rows, not
+    # a body read. Advisory read: exit 0 even with no matches. Exact by default —
+    # the consuming agent is the fuzzy layer, until it asks not to be.
+    class Search < Command
+      # The core raises `:regexp`; a user typed `--regexp`. Translating here keeps
+      # the flag vocabulary in the shell, where it belongs, and lets the message end
+      # with the fix rather than only the complaint: an engine that *can* do what was
+      # asked is named, so the next command is obvious.
+      CAPABILITY_FLAGS = { regexp: "--regexp", fuzzy: "--fuzzy" }.freeze
+
+      def self.id
+        :search
+      end
+
+      def self.group
+        :read
+      end
+
+      def self.help_rows
+        [
+          [ "search    <dir|@slug…|@all> <term…> [--regexp|--fuzzy]", "find concepts by text or regexp, ranked (@all: every bundle)" ]
+        ]
+      end
+
+      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]"
+          search_engine_note(o)
+          json_flags(o, options, "emit the matches as JSON")
+          projection_flags(o, options)
+          o.on("-e", "--regexp", "read each term as a Ruby regular expression rather",
+            "than literal text — case-insensitive (scan engine)") { options[:regexp] = true }
+          o.on("--fuzzy",
+            "tolerate typos, edit distance #{OKF::Bundle::Search::FUZZY_DISTANCE} × term length (index engine)") { options[:fuzzy] = true }
+          o.on("--engine NAME", "match with this engine instead of the default",
+            "(#{engine_names}) — index is BM25+ ranked, token-based") { |v| options[:engine] = v }
+          o.on("--in LIST", Array, "search only these fields (#{OKF::Bundle::Search::FIELDS.join(", ")})") { |v| options[:in] = v.map(&:downcase) }
+          filter_flags(o, options, :type, :area, :tag)
+          help_flag(o)
+        end
+        begin
+          parser.parse!(argv)
+        rescue OptionParser::ParseError => e
+          @err.puts e.message
+          return 2
+        end
+
+        # Registry mode — leading @refs, @all among them — searches several bundles
+        # and labels every match; a plain dir keeps the classic single-bundle output.
+        if argv.first&.start_with?("@")
+          pairs = ref_targets(argv) or return 2
+          dir = nil
+        else
+          dir = argv.shift
+          if dir.nil?
+            @err.puts parser.banner
+            return 2
+          end
+          dir = resolve_ref(dir) or return 2
+        end
+
+        terms = argv
+        if terms.empty?
+          @err.puts parser.banner
+          return 2
+        end
+
+        # A non-leading @arg is a literal term by the grammar — say so, since the
+        # user may have meant a ref (refs must lead) and would otherwise see only
+        # a silent zero-match.
+        stray = terms.find { |term| term.start_with?("@") }
+        @err.puts "note: '#{stray}' searches as a literal term — an @slug or @all must lead" if stray
+
+        unknown = Array(options[:in]) - OKF::Bundle::Search::FIELDS
+        return usage_error("unknown field(s): #{unknown.join(", ")} (searchable: #{OKF::Bundle::Search::FIELDS.join(", ")})") unless unknown.empty?
+
+        # Two query languages, not two dials on one: a regexp is matched against raw
+        # text, --fuzzy is an edit distance over indexed tokens. Silently honouring
+        # one and dropping the other would answer a question nobody asked.
+        if options[:regexp] && options[:fuzzy]
+          return usage_error("--regexp and --fuzzy are mutually exclusive (a pattern is matched literally, not by edit distance)")
+        end
+
+        return multi_search(pairs, terms, options) if pairs
+
+        folder = OKF::Bundle::Folder.load(dir)
+        report_skipped(folder)
+        rows = OKF::Bundle::Search.call(folder.bundle, terms, fields: options[:in], regexp: options[:regexp],
+          fuzzy: options[:fuzzy], engine: options[:engine])
+        keep = filter_ids(folder, options)
+        rows = rows.select { |row| keep.include?(row[:id]) } unless keep.nil?
+        return print_search_json(dir, terms, rows, options) if options[:json]
+
+        print_search(dir, terms, rows, folder.bundle.concepts.size)
+        0
+      rescue RegexpError => e
+        usage_error("invalid pattern: #{e.message}")
+      rescue OKF::Bundle::Search::UnknownEngine => e
+        usage_error(e.message)
+      rescue OKF::Bundle::Search::UnsupportedQuery => e
+        usage_error(unsupported_query_message(e))
+      end
+
+      private
+
+      # Every registered bundle, as [slug, dir] pairs — what @all expands to.
+      # Asking for everything tolerates gaps: a registered directory that has since
+      # vanished is skipped with a note, the same forgiveness the hub shows a stale
+      # entry. Naming one bundle demands it, so a plain @slug still fails hard.
+      def all_targets
+        registry = load_registry
+        return nil unless registry
+
+        if registry.empty?
+          @err.puts "error: no bundles registered (okf registry set <dir>)"
+          return nil
+        end
+        pairs = []
+        registry.each do |entry|
+          if File.directory?(entry.path)
+            pairs << [ entry.slug, entry.path ]
+          else
+            skip_registered(entry)
+          end
+        end
+        if pairs.empty?
+          @err.puts "error: every registered bundle is missing on disk (okf registry list)"
+          return nil
+        end
+        pairs
+      end
+
+      # Dedupe by resolved path, not ref spelling — `@ @one` is one bundle when
+      # "one" is the default, and must be searched once. `@all @one` is the same
+      # story with a wider first ref: all ⊇ one, so the result is right and the
+      # duplicate simply drops. No error branch, because there is no wrong answer
+      # to warn about.
+      def ref_targets(argv)
+        refs = []
+        refs << argv.shift while argv.first&.start_with?("@")
+        pairs = []
+        refs.each do |ref|
+          found = all_ref?(ref) ? all_targets : ref_pair(ref)
+          return nil unless found
+
+          found.each { |slug, path| pairs << [ slug, path ] unless pairs.any? { |_, seen| seen == path } }
+        end
+        pairs
+      end
+
+      # One @ref as a single-element [[slug, dir]], or nil after reporting.
+      def ref_pair(ref)
+        path = resolve_registered(ref)
+        unless path
+          # Only an unknown slug is plausibly a mistyped term — a broken registry
+          # or a gone directory has nothing to do with the grammar.
+          @err.puts "note: searching for a literal @-term? put a non-@ term first, or use -e '\\@term'" if @ref_failure == :unknown
+          return nil
+        end
+        [ [ ref_slugs[path], path ] ]
+      end
+
+      # Search every bundle at once and merge the rankings, each row labeled with
+      # its bundle's slug. The bundles go in as *one* corpus rather than one search
+      # each: BM25 weighs a term by how rare it is, so ranking each bundle on its own
+      # statistics and then interleaving the lists would let the same match score
+      # differently for no reason a reader could see. One index, one ranking.
+      #
+      # Filters stay per-bundle — they are per-folder questions — so they apply to
+      # the merged rows by (slug, id) afterwards.
+      def multi_search(pairs, terms, options)
+        bundles = []
+        keeps = {}
+        total = 0
+        pairs.each do |slug, dir|
+          folder = OKF::Bundle::Folder.load(dir)
+          report_skipped(folder)
+          total += folder.bundle.concepts.size
+          bundles << [ slug, folder.bundle ]
+          keep = filter_ids(folder, options)
+          keeps[slug] = keep unless keep.nil?
+        end
+        rows = OKF::Bundle::Search.across(bundles, terms, fields: options[:in], regexp: options[:regexp],
+          fuzzy: options[:fuzzy], engine: options[:engine])
+        rows = rows.select { |row| !keeps.key?(row[:slug]) || keeps[row[:slug]].include?(row[:id]) }
+        return print_multi_search_json(pairs, terms, rows, options) if options[:json]
+
+        print_multi_search(pairs, terms, rows, total)
+        0
+      end
+
+      def print_search(dir, terms, rows, total)
+        @out.puts "Search — #{bundle_label(dir)} · #{terms.join(" ")} (#{counted(rows.size, total, "concept")})"
+        if rows.empty?
+          @out.puts "  no matches — fewer or broader terms, or scan `okf tags #{dir}` for the vocabulary"
+          return
+        end
+
+        width = rows.map { |row| row[:id].length }.max
+        rows.each do |row|
+          @out.puts
+          @out.puts "  #{row[:id].ljust(width)}  #{row[:title]}  ·  #{row[:type]}  ·  #{row[:matched].join("+")}"
+          @out.puts "    #{truncate(row[:snippet], 100)}" unless row[:snippet].empty?
+        end
+      end
+
+      def print_search_json(dir, terms, rows, options)
+        emit_list_json(dir, "matches", rows.map { |row| stringify(row) }, options, "query" => terms)
+      end
+
+      def print_multi_search(pairs, terms, rows, total)
+        @out.puts "Search — #{pairs.map { |slug, _| "@#{slug}" }.join(" ")} · #{terms.join(" ")} (#{counted(rows.size, total, "concept")})"
+        if rows.empty?
+          @out.puts "  no matches — fewer or broader terms, or scan `okf tags @<slug>` for a bundle's vocabulary"
+          return
+        end
+
+        slug_width = rows.map { |row| row[:slug].length }.max + 1
+        width = rows.map { |row| row[:id].length }.max
+        rows.each do |row|
+          @out.puts
+          @out.puts "  #{"@#{row[:slug]}".ljust(slug_width)}  #{row[:id].ljust(width)}  #{row[:title]}  ·  #{row[:type]}  ·  #{row[:matched].join("+")}"
+          @out.puts "    #{truncate(row[:snippet], 100)}" unless row[:snippet].empty?
+        end
+      end
+
+      # The head maps every searched slug to its directory once, so a row's
+      # `slug` resolves to `<dir>/<id>.md` without a second lookup — and without
+      # repeating a long path on every row.
+      def print_multi_search_json(pairs, terms, rows, options)
+        head = { "bundles" => pairs.map { |slug, dir| { "slug" => slug, "dir" => dir } } }
+        emit_list_json(head, "matches", rows.map { |row| stringify(row) }, options, { "query" => terms }, "matches_by_ref")
+      end
+
+      def unsupported_query_message(error)
+        wanted = error.missing.map { |name| CAPABILITY_FLAGS.fetch(name, ":#{name}") }.join(", ")
+        return "no available search engine offers #{wanted}" if error.engine.nil?
+
+        able = OKF::Bundle::Search.engines.select { |engine| (error.missing - engine.capabilities).empty? }
+        message = "--engine #{error.engine} does not support #{wanted}"
+        message += " (try --engine #{able.map(&:id).join(" or ")})" unless able.empty?
+        message
+      end
+
+      # The engine story, told once, in the only place there is to tell it. `search`
+      # routes on what the query needs — a pattern needs the scan, --fuzzy needs the
+      # index — and says nothing about it at runtime: no note on stderr, nothing in
+      # the header, and deliberately no --engine flag. So this is where a user learns
+      # that the exactness a token index gives up is still reachable, and that -e is
+      # how. Without it that capability is present but undiscoverable.
+      #
+      # It leads rather than trails because #help_flag registers -h with `on_tail`,
+      # which OptionParser renders after every separator: a closing paragraph would
+      # print *above* the -h line and split the option list in half. Stating the
+      # matching model before the flags reads better anyway.
+      def search_engine_note(parser)
+        parser.separator ""
+        parser.separator "Terms match raw text, so a phrase (\"dedup key\"), a dotted identifier (7.2.0,"
+        parser.separator "customer_id) and a word inside `backticks` all match literally — the scan engine."
+        parser.separator "--engine index matches whole tokens and the tokens they prefix, ranked by BM25+:"
+        parser.separator "better ranking and the engine the browser page runs, at the cost of that"
+        parser.separator "exactness. --fuzzy implies it. Add -e to read the terms as regular expressions."
+        parser.separator ""
+      end
+
+      # The registered engines, read at parse time so an addon that registers one
+      # shows up in `--help` without the CLI knowing it exists.
+      def engine_names
+        OKF::Bundle::Search.engines.map(&:id).join(" | ")
+      end
+    end
+
+    register(Search)
+  end
+end

data/lib/okf/cli/server.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # Boot the graph server. One verb covers three intentions and the argument
+    # count is the whole interface: one dir serves it at /, several serve them
+    # behind a hub, none serves the registry. Passing dirs never registers them.
+    class Server < Command
+      def self.id
+        :server
+      end
+
+      def self.group
+        :act
+      end
+
+      def self.help_rows
+        [
+          [ "server    [DIR|@slug…] [-p PORT] [--bind ADDR] [...]", "serve one bundle, or many behind a hub" ]
+        ]
+      end
+
+      def call(argv)
+        require "okf/server/app"
+        require "rack/deflater"
+
+        options = { port: 8808, bind: "127.0.0.1", title: nil, link: nil, layout: "cose", read_only: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf server [DIR|@slug…] [-p PORT] [--bind ADDR] [--layout NAME] [-t title] [-l url]"
+          o.on("-p", "--port PORT", Integer, "port to serve on (default #{options[:port]})") { |v| options[:port] = v }
+          o.on("--bind ADDR", "address to bind (default #{options[:bind]})") { |v| options[:bind] = v }
+          o.on("-t", "--title TITLE", "graph title, single bundle only (default: parent/bundle dir name)") { |v| options[:title] = v }
+          o.on("-l", "--link URL", "source URL shown in the header, single bundle only") { |v| options[:link] = v }
+          o.on("--layout NAME", OKF::Render::Graph::LAYOUTS, "initial layout (#{OKF::Render::Graph::LAYOUTS.join(", ")})") { |v| options[:layout] = v }
+          o.on("--read-only", "serve the bundles list without its registry controls") { options[:read_only] = true }
+          help_flag(o)
+        end
+        dirs = positional_dirs(parser, argv) or return 2
+
+        # A flag that will have no effect in this mode gets a note, not silence.
+        @err.puts "note: --title/--link apply to a single-bundle server; ignored" if dirs.size != 1 && (options[:title] || options[:link])
+
+        # One dir keeps the historical single-bundle server at `/`; zero (the
+        # persistent registry) or many (ephemeral) fan out behind a hub.
+        if dirs.size == 1
+          folder = OKF::Bundle::Folder.load(dirs.first)
+          report_skipped(folder)
+          run_server(folder, options)
+        else
+          run_hub(dirs, options)
+        end
+        0
+      rescue OKF::Error => e
+        usage_error(e.message)
+      end
+
+      private
+
+      # 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])
+        # 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.
+        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)
+      end
+
+      # Build the multi-bundle hub and hand it to the runner. With dirs it serves
+      # those ephemerally; with none it serves the persistent registry. Either way
+      # the first bundle is the one `/` opens — for the registry that is its own
+      # order, and a first entry whose directory has vanished drops out here, so
+      # `/` lands on the next one that is actually there.
+      def run_hub(dirs, options)
+        require "okf/server/hub"
+        require "okf/registry"
+        reg = nil
+        if dirs.empty?
+          # A malformed registry raises OKF::Error, which `server` rescues into a
+          # usage error — no guarded load needed on this path.
+          reg = OKF::Registry.load
+          # The hub's own loader, so the set it rebuilds after a browser-side
+          # write is built exactly the way this one was.
+          bundles = OKF::Server::Hub.bundles_for(reg) { |entry| skip_registered(entry) }
+          bundles.each { |bundle| report_skipped(bundle.folder) }
+        else
+          bundles = ephemeral_bundles(dirs)
+        end
+        # The hub keeps the registry so its /b/ manager can report on entries it
+        # 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))
+        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)"
+        print_mounts(hub)
+        serve(hub, options)
+      end
+
+      # The one boot seam every served app passes through, so a hub gzips exactly
+      # like a single bundle — the wrap belongs to booting a server, not to either
+      # mode, and a mode added later gets it for free. Deliberately not inside the
+      # runner: an embedding app mounting OKF::Server::App brings its own middleware.
+      def serve(app, options)
+        # gzip responses when the client accepts it — transparent, no new dependency
+        @runner.call(Rack::Deflater.new(app), options[:bind], options[:port])
+      end
+
+      # The mount table — which dir landed on which /b/<slug>/ and where `/` goes.
+      # Mirrors the Hub's own default resolution (explicit slug, else first).
+      # Ask the hub which bundle it chose rather than re-deriving the
+      # explicit-else-first rule, and mount at its own prefix: two copies of a
+      # rule is two answers waiting to disagree.
+      def print_mounts(hub)
+        hub.bundles.each do |bundle|
+          marker = bundle.equal?(hub.default) ? "*" : " "
+          @out.puts "  #{marker} #{OKF::Server::Hub::MOUNT}/#{bundle.slug}/  #{bundle.title}"
+        end
+      end
+
+      # Load the given directories as unregistered bundles, slugged by basename and
+      # deduped within the run. The same directory listed twice mounts once — two
+      # windows on one bundle would just burn a slug on a URL that vanishes next run.
+      def ephemeral_bundles(dirs)
+        roots = []
+        dirs.each do |dir|
+          root = File.expand_path(dir)
+          roots << root unless roots.include?(root)
+        end
+
+        # A registered slug owns its mount outright: reserve every ref's slug
+        # before any basename is deduped. Otherwise argv order decides, and
+        # `server ./two @two` mounts the *unregistered* ./two at /b/two/ while
+        # pushing the ref — the bundle whose slug that is — to /b/two-2/, so a
+        # bookmark from a bundle-less run silently opens the wrong graph.
+        taken = roots.map { |root| ref_slugs[root] }.compact
+        roots.each_with_object([]) do |root, bundles|
+          folder = OKF::Bundle::Folder.load(root)
+          report_skipped(folder)
+          slug = ref_slugs[root]
+          unless slug
+            slug = OKF::Registry.dedupe(File.basename(root), taken)
+            taken << slug
+          end
+          bundles << OKF::Server::Hub::Bundle.new(slug, folder, folder.name)
+        end
+      end
+
+      # May the browser change the registry? On a loopback bind, yes: the server
+      # is reachable only from this machine, and the audience this was built for
+      # should not need a flag to use the page they were pointed at. Anywhere
+      # else, no — and there is no flag that says otherwise, because the registry
+      # is a per-user file and the machine that owns it is the machine that
+      # manages it. `--bind 0.0.0.0` is how a personal tool becomes a public one,
+      # and 0.0.0.0 is *not* loopback: it is every interface, which is the exact
+      # case this guards.
+      #
+      # So the only flag is the way *out*. It was `--allow-manage`, an opt-in
+      # that read as the on switch and was not one — the loopback default had
+      # already turned management on, and the flag only widened it to a bind
+      # nobody should widen it to. Naming the exception instead means the flag
+      # cannot be misread as permission: `--read-only` is the word the hub's own
+      # refusal already uses, and this server never writes a reader's markdown
+      # anyway, so in context it can only mean the registry.
+      def writable?(options)
+        !options[:read_only] && loopback?(options[:bind])
+      end
+
+      def loopback?(bind)
+        address = bind.to_s
+        address == "localhost" || address == "::1" || address.start_with?("127.")
+      end
+    end
+
+    register(Server)
+  end
+end

data/lib/okf/cli/skill.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # Install this gem's companion agent skill into a destination directory. The
+    # destination is required (no magic default) so the user always decides where
+    # their agent picks the skill up. By default the skill lands in a skills/okf/
+    # folder under it — point at a project or skills dir (.claude, .agents/skills)
+    # and it settles in its own folder, never loose among the others — so the
+    # resolved path is echoed back. --here installs straight into <dest-dir>.
+    class Skill < Command
+      def self.id
+        :skill
+      end
+
+      def self.group
+        :act
+      end
+
+      def self.help_rows
+        [
+          [ "skill     <dest> [--here] [--force]", "install the companion agent skill" ]
+        ]
+      end
+
+      def call(argv)
+        options = { force: false, nest: true }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf skill <dest-dir> [--here] [--force]"
+          o.on("--here", "install straight into <dest-dir>, wherever it is (no skills/okf nesting)") { options[:nest] = false }
+          o.on("--force", "overwrite a non-empty destination") { options[:force] = true }
+          help_flag(o)
+        end
+        # Through the shared pair like every other verb that takes one positional:
+        # `positional` for the value, `no_extras?` for what must not follow it.
+        # Hand-rolling the shift is how this one came to accept a second
+        # destination, install into the first and exit 0 — the silent-wrong-answer
+        # shape the <dir> verbs are guarded against, on the one verb whose
+        # positional is not a <dir>.
+        dest = positional(parser, argv) or return 2
+        no_extras?(argv) or return 2
+
+        skill = OKF::Skill.new(dest, force: options[:force], nest: options[:nest])
+        files = skill.install
+        @out.puts "installed the okf skill (#{files.size} files) -> #{skill.dest}"
+        files.each { |f| @out.puts "  #{f}" }
+        @out.puts "your agent picks it up from #{skill.dest} (needs the `okf` CLI, which you already have)."
+        0
+      rescue OKF::Skill::Error => e
+        @err.puts "error: #{e.message}"
+        2
+      end
+    end
+
+    register(Skill)
+  end
+end

data/lib/okf/cli/stats.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # Bundle rollups — concepts, types, areas, links, tags — in one screen.
+    class Stats < Command
+      def self.id
+        :stats
+      end
+
+      def self.group
+        :read
+      end
+
+      def self.help_rows
+        [
+          [ "stats     <dir|@slug> [--json]", "bundle rollups (concepts, types, areas, links, tags)" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf stats <dir|@slug> [--json]"
+          json_flags(o, options, "emit the stats as JSON")
+          help_flag(o)
+        end
+        dir = positional_dir(parser, argv) or return 2
+
+        folder = OKF::Bundle::Folder.load(dir)
+        report_skipped(folder)
+        stats = bundle_stats(folder)
+        options[:json] ? print_stats_json(dir, stats) : print_stats(dir, stats)
+        0
+      end
+
+      private
+
+      # Bundle-level rollups derived from the catalog and the graph indexes.
+      def bundle_stats(folder)
+        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
+        {
+          concepts: entries.size,
+          areas: by_area.size,
+          types: by_type.size,
+          cross_links: graph.edges.size,
+          tags: graph.tag_index.size,
+          by_type: by_type,
+          by_area: by_area
+        }
+      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 "  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])
+      end
+
+      def print_stat_breakdown(title, counts)
+        return if counts.empty?
+
+        width = counts.keys.map(&:length).max
+        @out.puts
+        @out.puts "  #{title}"
+        counts.each { |label, count| @out.puts "    #{label.ljust(width)}  #{count}" }
+      end
+
+      def print_stats_json(dir, stats)
+        emit_json(bundle_head(dir).merge(
+          "concepts" => stats[:concepts], "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]
+        ))
+      end
+    end
+
+    register(Stats)
+  end
+end