okf 1.9.0 → 1.11.0

data/lib/okf/bundle/folder.rb

@@ -46,6 +46,10 @@ module OKF
         @bundle.catalog
       end
 
+      def hubs
+        @bundle.hubs
+      end
+
       def directory_index
         @bundle.directory_index
       end
@@ -60,13 +64,28 @@ module OKF
         end
       end
 
-      # Human-readable "parent/dir" name — the default HTML title.
-      # The bundle's display label, "parent/dir" — path arithmetic, no disk. It
-      # is a class method so a caller that only wants the label (the registry
-      # naming an entry) can have it without a Reader.read of every file.
+      # The bundle's display label — path arithmetic, no disk. It is a class
+      # method so a caller that only wants the label (the registry naming an
+      # entry) can have it without a Reader.read of every file.
+      #
+      # "parent/dir", because a bundle directory's own name is rarely unique
+      # enough to name it by — except when that name is `.okf`, the conventional
+      # container, and then the parent carries the whole answer on its own. A
+      # registry of eight projects is eight rows reading `…/.okf`, which is the
+      # one word that tells none of them apart; `repo/.okf` is read as "repo" by
+      # anyone looking at it anyway.
+      #
+      # A directory with no parent to borrow (`/.okf`) keeps its own name: the
+      # parent is `/`, which names nothing. That case used to compose into
+      # `//.okf`.
       def self.label(root)
         pathname = Pathname.new(root)
-        "#{pathname.parent.basename}/#{pathname.basename}"
+        parent = pathname.parent.basename.to_s
+        base = pathname.basename.to_s
+        return base if [ "/", "." ].include?(parent)
+        return parent if base == ".okf"
+
+        "#{parent}/#{base}"
       end
 
       def name

data/lib/okf/bundle/linter.rb

@@ -324,7 +324,7 @@ module OKF
       end
 
       def concepts_in(dir)
-        @concepts.select { |concept| File.dirname("#{concept.id}.md") == dir }
+        @concepts.select { |concept| OKF.dir_of(concept.id) == dir }
       end
 
       def index_path_for(dir)

data/lib/okf/bundle/search/index.rb

@@ -12,8 +12,9 @@ module OKF
       #
       # Matching is by *token*: a term matches a whole word or a word it prefixes
       # ("dedup" reaches "deduplication"), and `fuzzy:` opts into typo tolerance.
-      # The index is built per call — see .okf/capabilities/search.md for why that
-      # ceiling stands and what lifts it.
+      # The index builds per call unless the caller holds a Search::Corpus, which
+      # builds it once through .prepare and reuses it — the server does, the
+      # one-shot CLI cannot. See .okf/capabilities/search.md.
       module Index
         CAPABILITIES = %i[fuzzy prefix].freeze
 
@@ -37,9 +38,18 @@ module OKF
           # can neither match nor be credited. The hit's `terms` are MiniFTS's
           # matched *document* terms — already lowercased, and present in the text
           # verbatim even when the query only prefixed them.
-          def call(documents, terms, fields:, fuzzy: false, **_options)
+          # The expensive half, separated so a long-lived caller can hold it. A
+          # Corpus calls this once; a one-shot call still goes through #call and
+          # builds inline, which is why this is an addition and not a new
+          # requirement on the engine contract.
+          def prepare(documents)
             index = MiniFTS.new(fields: FIELDS, id_field: "key")
             index.add_all(documents)
+            index
+          end
+
+          def call(documents, terms, fields:, fuzzy: false, prepared: nil, **_options)
+            index = prepared || prepare(documents)
 
             options = { combine_with: "AND", prefix: true, boost: WEIGHTS, fields: fields }
             options[:fuzzy] = FUZZY_DISTANCE if fuzzy

data/lib/okf/bundle/search.rb

@@ -186,12 +186,89 @@ module OKF
         new(bundles, terms, fields: fields, regexp: regexp, fuzzy: fuzzy, engine: engine, engines: engines).results
       end
 
+      # The searchable text of one concept, by field. Here rather than on an
+      # instance because a Corpus builds documents with no query in hand.
+      def self.field_texts(concept)
+        {
+          "id" => concept.id,
+          "title" => concept.title.to_s,
+          "type" => concept.type.to_s,
+          "description" => concept.description.to_s,
+          "tags" => Array(concept.tags).join(" "),
+          "body" => concept.body
+        }
+      end
+
+      # A corpus prepared once and queried many times: the documents, the key →
+      # concept map, and each engine's built index.
+      #
+      # This is the asymmetry the engine choice was always argued from. A CLI
+      # process loads a bundle, asks one question and exits, so an index build has
+      # exactly one query to amortize over and the scan wins. A server is the
+      # other case — the build is ~95% of the index path's cost, and paying it per
+      # request made every search re-read the whole corpus. Held once, it is paid
+      # once.
+      #
+      # Pure: it holds concepts, never disk. Which is also the cost — the corpus
+      # is a snapshot, so a body edited after it was built is searchable only
+      # after the holder drops it. That matches the graph, which is memoized the
+      # same way and for the same reason.
+      class Corpus
+        attr_reader :bundles, :documents, :sources
+
+        def initialize(bundles)
+          @bundles = bundles
+          @documents = []
+          @sources = {}
+          @indexes = {}
+          bundles.each do |slug, bundle|
+            bundle.concepts.each do |concept|
+              key = "#{slug}#{KEY_SEPARATOR}#{concept.id}"
+              @sources[key] = [ slug, concept ]
+              @documents << Search.field_texts(concept).merge("key" => key)
+            end
+          end
+        end
+
+        # nil for an engine with nothing to prebuild — the scan reads raw text and
+        # has no index to hold — so the option only ever reaches one that declared
+        # it can. Memoized per engine id: two engines over one corpus is legal.
+        def index_for(engine)
+          return nil unless engine.respond_to?(:prepare)
+
+          @indexes[engine.id] ||= engine.prepare(@documents)
+        end
+      end
+
+      # Prepare a corpus for a long-lived caller. Hand the result back to .with
+      # for every query.
+      #
+      # `engine:` builds that engine's index *now* rather than on the first query.
+      # Without it the corpus holds only the documents, and the expensive half —
+      # the index — is still built lazily, which puts the whole cost on whoever
+      # searches first. A server knows its engine at boot, so it can pay there.
+      def self.prepare(bundles, engine: nil, engines: nil)
+        corpus = Corpus.new(bundles)
+        return corpus if OKF.blank?(engine)
+
+        corpus.index_for(engine_for([], engines: engines || self.engines, name: engine))
+        corpus
+      end
+
+      # Query a prepared corpus. Same rows as .across, without rebuilding what the
+      # corpus already holds.
+      def self.with(corpus, terms, fields: nil, regexp: false, fuzzy: false, engine: nil, engines: nil)
+        new(corpus.bundles, terms, fields: fields, regexp: regexp, fuzzy: fuzzy,
+          engine: engine, engines: engines, corpus: corpus).results
+      end
+
       # Raises RegexpError on an invalid pattern with `regexp: true`, and
       # UnsupportedQuery when no engine can answer — the caller owns turning
       # either into a usage error. `engines:` overrides the registry, which is how
       # the "nothing qualifies" path stays reachable without an addon installed.
-      def initialize(bundles, terms, fields: nil, regexp: false, fuzzy: false, engine: nil, engines: nil)
+      def initialize(bundles, terms, fields: nil, regexp: false, fuzzy: false, engine: nil, engines: nil, corpus: nil)
         @bundles = bundles
+        @corpus = corpus
         @terms = Array(terms).reject { |term| OKF.blank?(term) }.map(&:to_s)
         @fields = fields.nil? || fields.empty? ? FIELDS : fields
         @regexp = regexp
@@ -202,7 +279,7 @@ module OKF
       end
 
       # Ranked match rows, catalog-style identity plus where the terms hit:
-      # [{ slug:, id:, title:, type:, area:, tags:, matched: [field, …], score:, snippet: }, …]
+      # [{ slug:, id:, title:, type:, dir:, area:, tags:, matched: [field, …], score:, snippet: }, …]
       # ordered by score descending, then slug, then id. `slug` is present only
       # when searching across bundles. No terms means no matches.
       def results
@@ -242,6 +319,7 @@ module OKF
       # what it can act on, so there is nothing left for it to ignore.
       def engine_options(chosen)
         options = { fields: @fields }
+        options[:prepared] = @corpus.index_for(chosen) if @corpus
         ROUTABLE.each do |capability|
           options[capability] = requested[capability] if chosen.capabilities.include?(capability)
         end
@@ -255,6 +333,13 @@ module OKF
       # Every concept as an indexable document, keyed uniquely across bundles.
       # @sources keeps the way back, so the index stores no fields of its own.
       def documents
+        # The corpus already walked every concept and kept the map that turns a
+        # hit back into a row; taking its sources is what makes that reuse whole.
+        if @corpus
+          @sources = @corpus.sources
+          return @corpus.documents
+        end
+
         docs = []
         @bundles.each do |slug, bundle|
           bundle.concepts.each do |concept|
@@ -269,14 +354,7 @@ module OKF
       # { field => original-case text } for every searchable field. The index reads
       # all of them; `fields:` narrows the search, not the document.
       def field_texts(concept)
-        {
-          "id" => concept.id,
-          "title" => concept.title.to_s,
-          "type" => concept.type.to_s,
-          "description" => concept.description.to_s,
-          "tags" => Array(concept.tags).join(" "),
-          "body" => concept.body
-        }
+        Search.field_texts(concept)
       end
 
       # `slug` leads the row so a merged result reads bundle-first, and drops
@@ -288,6 +366,7 @@ module OKF
           id: concept.id,
           title: (concept.title || concept.id).to_s,
           type: concept.type.to_s,
+          dir: OKF.dir_of(concept.id),
           area: area_of(concept.id),
           tags: Array(concept.tags).map(&:to_s),
           matched: matched,
@@ -342,7 +421,8 @@ module OKF
         end
       end
 
-      # A concept's top-level area, mirroring the catalog's definition.
+      # A concept's top-level area, mirroring the catalog's definition. Deprecated
+      # in favour of OKF.dir_of, which keeps the levels this one throws away.
       def area_of(id)
         id.include?("/") ? id.split("/").first : "(root)"
       end

data/lib/okf/bundle.rb

@@ -118,14 +118,32 @@ module OKF
           timestamp: concept.timestamp&.to_s,
           status: concept.frontmatter["status"]&.to_s,
           backlog_ref: concept.frontmatter["backlog_ref"]&.to_s,
-          dir: File.dirname("#{id}.md"),
-          area: id.include?("/") ? id.split("/").first : "(root)",
+          dir: OKF.dir_of(id),
+          area: area_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.
+    def hubs
+      inbound = {}
+      graph(minimal: true).edges.each do |edge|
+        (inbound[edge[:target]] ||= Hash.new(0))[area_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 }
+      end.sort_by { |row| [ -row[:inbound], row[:id] ] }
+    end
+
     # The progressive-disclosure map (spec §6): one entry per directory that holds
     # concepts or carries an index.md, sorted with the root (".") first. Each entry
     # gives the authored index body (frontmatter stripped) when an index.md is
@@ -171,6 +189,12 @@ 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)
+      id.include?("/") ? id.split("/").first : "(root)"
+    end
+
     # Every directory to show: those holding concepts or an index.md, plus each of
     # their ancestors up to the root, so the subdir tree stays connected even when
     # an intermediate directory holds nothing directly. Sorted with "." first.

data/lib/okf/cli/catalog.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+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.
+    class Catalog < Command
+      def self.id
+        :catalog
+      end
+
+      def self.group
+        :read
+      end
+
+      def self.help_rows
+        [
+          [ "catalog   <dir|@slug> [--json] [filters]", "list concepts with metadata, by area" ]
+        ]
+      end
+
+      def call(argv)
+        options = { json: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf catalog <dir|@slug> [--type T] [--dir D] [--tag T] [--json]"
+          json_flags(o, options, "emit the catalog as JSON")
+          projection_flags(o, options)
+          filter_flags(o, options, :type, :area, :tag)
+          help_flag(o)
+        end
+        dir = positional_dir(parser, argv) or return 2
+
+        folder = OKF::Bundle::Folder.load(dir)
+        report_skipped(folder)
+        entries = folder.catalog
+        selected = filter_entries(entries, options)
+        return print_catalog_json(dir, selected, options) if options[:json]
+
+        print_catalog(dir, selected, entries.size)
+        0
+      end
+
+      private
+
+      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|
+          @out.puts
+          @out.puts "  #{area == "(root)" ? "(root)" : "#{area}/"} (#{group.size})"
+          group.each do |entry|
+            links = entry[:links_out] + entry[:links_in]
+            meta = [ entry[:type], (links.positive? ? "↳#{links}" : nil), entry[:status] ].compact.join("  ·  ")
+            @out.puts "    #{entry[:title]}  ·  #{meta}"
+            @out.puts "      #{truncate(entry[:description], 92)}" unless entry[:description].empty?
+          end
+        end
+      end
+
+      def print_catalog_json(dir, entries, options)
+        emit_list_json(dir, "concepts", entries.map { |entry| stringify(entry) }, options)
+      end
+    end
+
+    register(Catalog)
+  end
+end