okf 1.9.0 → 1.11.0

data/lib/okf/cli/registry.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # The registry umbrella, split by what each verb keys on. `set`/`del`/`list`
+    # act on entries — `set` keys on the bundle's path, so --as means one thing
+    # ("the slug this entry has") whether it adds or renames. `default`/`rename`
+    # act on slugs, the names actually to hand once a bundle is registered. Every
+    # positional stays unambiguous, and `config` is left free for real settings.
+    class Registry < Command
+      # The `registry` umbrella's subcommands — the dispatch, and the words a
+      # flag-first invocation is checked against.
+      SUBCOMMANDS = %w[set del list default rename].freeze
+
+      def self.id
+        :registry
+      end
+
+      def self.group
+        :registry
+      end
+
+      def self.help_rows
+        [
+          [ "registry  list [--json]", "list registered bundles (* marks the default)" ],
+          [ "registry  set <dir|@slug> [--as SLUG] [--default]", "add or update a bundle (a bare `server` serves them)" ],
+          [ "registry  del <dir|@slug>", "remove a bundle from the registry" ],
+          [ "registry  default <@slug>", "move a bundle to the front (the default)" ],
+          [ "registry  rename <@slug> <new>", "rename a registered bundle (<new> is a new name, not a ref)" ]
+        ]
+      end
+
+      def call(argv)
+        require "okf/registry"
+
+        sub = argv.first
+        case sub
+        when "set" then registry_set(argv.drop(1))
+        when "del" then registry_del(argv.drop(1))
+        when "list" then registry_list(argv.drop(1))
+        when "default" then registry_default(argv.drop(1))
+        when "rename" then registry_rename(argv.drop(1))
+        else
+          # A bare word that isn't a known subcommand is a typo (`registry remove x`
+          # must not silently render the list and read as success).
+          return usage_error("unknown registry subcommand '#{sub}' (expected: #{SUBCOMMANDS.join(", ")})") if sub && !sub.start_with?("-")
+
+          # Same rule for a subcommand hiding behind a flag: `registry --json set
+          # dir` would otherwise list an empty registry and exit 0, having written
+          # nothing the user asked for. It cannot just be dispatched from wherever
+          # it turns up — the word may be a flag's value (`registry --as set <dir>`
+          # asks for the slug "set"), and a grammar where that reading depends on
+          # which flag precedes it is a trapdoor. So the subcommand must lead, and
+          # the error says which one was found rather than guessing at the intent.
+          stray = argv.find { |arg| SUBCOMMANDS.include?(arg) }
+          return usage_error("put the subcommand first: okf registry #{stray} … (flags follow it)") if stray
+
+          registry_list(argv)
+        end
+      end
+
+      private
+
+      # Add a bundle to the persistent registry (so a later bare `okf server` finds
+      # it), or update one already there. The entry is keyed by the bundle's path: a
+      # path already registered refreshes its title in place, and --as renames it. A
+      # new path is added, slugged by directory basename unless --as says otherwise.
+      def registry_set(argv)
+        options = { as: nil, default: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf registry set <dir|@slug> [--as SLUG] [--default]"
+          o.on("--as SLUG", "slug to register under (default: directory basename)") { |v| options[:as] = v }
+          o.on("--default", "put it first — the bundle a bare `okf server` opens") { options[:default] = true }
+          help_flag(o)
+        end
+        # No no_extras? here: positional_dir has already refused a trailing
+        # argument. The sibling subcommands need the call because they take their
+        # positional through `positional`, which does not check.
+        dir = positional_dir(parser, argv) or return 2
+
+        reg = OKF::Registry.load
+        # Said before the upsert: after it, an update is indistinguishable from an
+        # add, and "registered" for what was a rename reads as a duplicate entry.
+        known = reg.listing.any? { |row| row[:dir] == File.expand_path(dir) }
+        entry = reg.add(dir, as: options[:as], default: options[:default])
+        # Through report_skipped like every other bundle-reading verb: the reader
+        # tolerates a file it cannot open, so a count taken straight off the graph
+        # reports "0 concepts" for a bundle whose files are simply unreadable.
+        folder = OKF::Bundle::Folder.load(entry.path)
+        report_skipped(folder)
+        count = folder.graph(minimal: true).nodes.size
+        @out.puts "#{known ? "updated" : "registered"} #{entry.slug} → #{entry.path} (#{count} #{pluralize(count, "concept")})"
+        0
+      rescue OKF::Error => e
+        usage_error(e.message)
+      end
+
+      # Remove a bundle from the persistent registry by slug or by its directory.
+      def registry_del(argv)
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf registry del <dir|@slug>"
+          help_flag(o)
+        end
+        slug = positional(parser, argv) or return 2
+        no_extras?(argv) or return 2
+
+        reg = OKF::Registry.load
+        slug = registry_slug(slug, reg) or return 2
+        removed = reg.remove(slug)
+        return usage_error("no such bundle: #{slug}") unless removed
+
+        @out.puts "removed #{removed.slug}"
+        0
+      rescue OKF::Error => e
+        usage_error(e.message)
+      end
+
+      def registry_list(argv)
+        options = { json: false }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf registry list [--json] [--pretty]\n       " \
+                     "okf registry set <dir|@slug> | del <dir|@slug> | default <@slug> | rename <@slug> <new>"
+          json_flags(o, options, "emit the registry as JSON")
+          help_flag(o)
+        end
+        begin
+          parser.parse!(argv)
+        rescue OptionParser::ParseError => e
+          @err.puts e.message
+          return 2
+        end
+        no_extras?(argv) or return 2
+
+        reg = OKF::Registry.load
+        return emit_list_json({ "registry" => reg.path }, "bundles", reg.listing.map { |row| stringify(row) }, options) if options[:json]
+
+        print_registry(reg)
+        0
+      rescue OKF::Error => e
+        usage_error(e.message)
+      end
+
+      # Choose which registered bundle a bare `okf server` opens at `/`, by moving
+      # it to the front of the registry. The listing is ordered and the JSON is
+      # meant to be hand-editable, so the move is stated rather than left to be
+      # discovered from a reordered file.
+      def registry_default(argv)
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf registry default <@slug>\n       " \
+                     "moves it to the front — the first registered bundle is the default until you do"
+          help_flag(o)
+        end
+        slug = positional(parser, argv) or return 2
+        no_extras?(argv) or return 2
+
+        reg = OKF::Registry.load
+        slug = registry_slug(slug, reg) or return 2
+        reg.default = slug
+        @out.puts "default bundle → #{reg.default.slug} (now first)"
+        0
+      rescue OKF::Error => e
+        usage_error(e.message)
+      end
+
+      # The @ref grammar for a verb that takes a *slug*, read by name. These three
+      # must reach an entry whose directory is gone — that is the one worth
+      # deleting or renaming — so they cannot go through resolve_ref, which
+      # insists the directory exist. Without this the refs only appeared to work:
+      # `normalize` strips the `@` off `@slug`, so `default @slug` resolved by
+      # accident while a bare `@` normalized to "" and failed. Returns the slug,
+      # or nil after reporting.
+      def registry_slug(arg, registry)
+        return arg unless arg.start_with?("@")
+
+        asked = arg[1..-1]
+        return asked unless asked.empty?
+
+        default = registry.default
+        return default.slug if default
+
+        @err.puts "error: no bundle is registered, so `@` names nothing (okf registry set <dir>)"
+        nil
+      end
+
+      # Rename a registered bundle's slug — its mount path and switcher name.
+      def registry_rename(argv)
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf registry rename <@slug> <new>"
+          help_flag(o)
+        end
+        parser.parse!(argv)
+        old_slug, new_slug = argv.shift(2)
+        if old_slug.nil? || new_slug.nil?
+          @err.puts parser.banner
+          return 2
+        end
+        no_extras?(argv) or return 2
+
+        reg = OKF::Registry.load
+        # The old name may be a ref; the new one is a name being minted, never one.
+        old_slug = registry_slug(old_slug, reg) or return 2
+        entry = reg.rename(old_slug, new_slug)
+        # The slug it *found*, not the argv that found it: rename normalizes to look
+        # the entry up, so echoing the raw ask names a bundle that never existed.
+        @out.puts "renamed #{OKF::Registry.normalize(old_slug)} → #{entry.slug}"
+        0
+      rescue OptionParser::ParseError => e
+        @err.puts e.message
+        2
+      rescue OKF::Error => e
+        usage_error(e.message)
+      end
+
+      def print_registry(reg)
+        return @out.puts "no bundles registered — okf registry set <dir>" if reg.empty?
+
+        rows = reg.listing
+        width = rows.map { |row| row[:slug].length }.max
+        rows.each do |row|
+          marker = row[:default] ? "*" : " "
+          missing = row[:missing] ? "  (missing)" : ""
+          @out.puts "#{marker} #{row[:slug].ljust(width)}  #{row[:title]}  (#{row[:dir]})#{missing}"
+        end
+      end
+    end
+
+    register(Registry)
+  end
+end

data/lib/okf/cli/render.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module OKF
+  class CLI
+    # The static counterpart to `server`: bake the whole bundle into one
+    # self-contained HTML file (bodies, catalog, index, logs baked in, no server
+    # needed — e.g. hosting on GitHub Pages). Prints to stdout unless -o is given.
+    class Render < Command
+      def self.id
+        :render
+      end
+
+      def self.group
+        :act
+      end
+
+      def self.help_rows
+        [
+          [ "render    <dir|@slug> [-o FILE] [--layout NAME] [...]", "write a static, self-contained HTML graph" ]
+        ]
+      end
+
+      def call(argv)
+        require "okf/render/graph"
+
+        options = { output: nil, title: nil, link: nil, layout: "cose" }
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: okf render <dir|@slug> [-o FILE] [--layout NAME] [-t title] [-l url]"
+          o.on("-o", "--output FILE", "write to FILE instead of stdout") { |v| options[:output] = v }
+          o.on("-t", "--title TITLE", "graph title (default: parent/bundle dir name)") { |v| options[:title] = v }
+          o.on("-l", "--link URL", "source URL shown in the header") { |v| options[:link] = v }
+          o.on("--layout NAME", OKF::Render::Graph::LAYOUTS, "initial layout (#{OKF::Render::Graph::LAYOUTS.join(", ")})") { |v| options[:layout] = v }
+          help_flag(o)
+        end
+        dir = positional_dir(parser, argv) or return 2
+
+        folder = OKF::Bundle::Folder.load(dir)
+        report_skipped(folder)
+        html = OKF::Render::Graph.static(folder, title: options[:title], link: options[:link], layout: options[:layout])
+        if options[:output]
+          # A bad -o path (a missing directory, a permission denial) is a bad
+          # *argument*: exit 2 with the reason, never a backtrace and an exit code
+          # that means "failing bundle".
+          begin
+            File.write(options[:output], html)
+          rescue SystemCallError => e
+            return usage_error("cannot write #{options[:output]}: #{e.message}")
+          end
+          # Off the bundle, not a second graph: Graph.build maps one node per
+          # concept, so the counts are identical — and Folder#graph is not
+          # memoized, so asking for one here would build a whole second graph
+          # (Render::Graph.static already built one) to print one number. Only
+          # the graph, to be exact: the concepts are parsed once at Folder.load
+          # and Graph.build reads them from memory, so this costs no disk.
+          count = folder.bundle.concepts.size
+          @out.puts "wrote #{count} #{pluralize(count, "concept")} to #{options[:output]}"
+        else
+          @out.print html
+        end
+        0
+      end
+    end
+
+    register(Render)
+  end
+end

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] [--dir D] [--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