iriq 0.30.2 → 0.35.0

data/completions/_iriq

@@ -27,6 +27,8 @@ _iriq() {
         '--no-scheme-less[skip schemeless URL extraction]' \
         '--scheme-less[enable schemeless URL extraction]' \
         '--corpus[load/create a JSON or SQLite corpus]:corpus path:_files -g "*.(json|db|sqlite|sqlite3)"' \
+        '(-C --no-corpus)'{-C,--no-corpus}'[disable corpus persistence for this invocation]' \
+        '--reset[delete the corpus database and exit]' \
         '--host[host-keying strategy for clustering]:strategy:(full registrable reg none)' \
         '--stats[print rolling aggregates]' \
         '--reinfer[replay the source-IRI log]' \

data/completions/iriq.bash

@@ -44,7 +44,7 @@ _iriq() {
     if [[ "$cur" == -* ]]; then
         local flags="-h --help -V --version -p --parse -n --normalize -c --canonical -e --explain
                      -j --json -J --ndjson -N --no-hints --hints --no-scheme-less
-                     --scheme-less --corpus --host --stats --reinfer
+                     --scheme-less --corpus -C --no-corpus --reset --host --stats --reinfer
                      --propose-recognizers --activate-above --cross-host-shapes
                      --min-observations --min-coverage --min-hosts"
         COMPREPLY=( $(compgen -W "$flags" -- "$cur") )

data/iriq.gemspec

@@ -5,7 +5,7 @@ Gem::Specification.new do |s|
   s.version     = Iriq::VERSION
   s.authors     = ["Daniel Pepper"]
   s.description = "IRI extraction, normalization, and clustering."
-  s.files       = `git ls-files * ':!:spec' ':!:script' ':!:bin' ':!:rust' ':!:go'`.split("\n")
+  s.files       = `git ls-files lib exe completions README.md LICENSE.txt CHANGELOG.md iriq.gemspec`.split("\n")
   s.bindir      = "exe"
   s.executables = ["iriq"]
   s.homepage    = "https://github.com/dpep/iriq"

data/lib/iriq/cli.rb

@@ -1,3 +1,4 @@
+require "fileutils"
 require "json"
 require "optparse"
 require "stringio"
@@ -24,8 +25,8 @@ module Iriq
              iriq [options] < text
              iriq cluster [options] [file]
 
-      <input> may be an IRI, a file path (extracted automatically), or piped
-      text via stdin.
+      <input> may be an IRI, a file to extract IRIs from (an existing file wins
+      unless the argument contains ://), or piped text via stdin.
 
       Sections (combine freely):
         -n, --normalize       Shape — variable parts become placeholders
@@ -33,32 +34,43 @@ module Iriq
         -p, --parse           Parsed fields
         -e, --explain         Annotated trace — per-segment notes about why
                               each placeholder / canonical value was chosen
+                              (mechanical rules only, even with a corpus)
 
       Corpus + stats:
-            --corpus PATH     Load/create a JSON corpus; observe and save atomically.
-                              -n becomes corpus-informed once it has data.
+            --corpus PATH     Use a specific corpus file (overrides the default).
+                              Extension picks the backend: .db/.sqlite/.sqlite3
+                              are SQLite; anything else is JSON.
+        -C, --no-corpus       Disable corpus persistence for this invocation.
+                              Same as IRIQ_NO_CORPUS=1 in the environment.
+            --reset           Delete the corpus (default path or the one
+                              resolved via --corpus / IRIQ_CORPUS), its SQLite
+                              sidecars and JSON temp files, and exit.
             --host MODE       Host-keying strategy for clustering:
                               full (default), registrable (or reg) strips
-                              subdomains, none ignores host entirely.
+                              subdomains, none ignores host entirely. Keys
+                              IRIs as they're observed (-C included) and on
+                              --reinfer; existing clusters keep their keys.
             --stats           Print rolling aggregates
             --reinfer         Replay the source-IRI log through the current
                               classifier + reducers; rebuilds materialized
-                              views from scratch. Requires --corpus.
+                              views from scratch.
             --propose-recognizers
                               Scan observed values for shape patterns that
                               recur enough to suggest a new Recognizer.
                               Combine with --json for structured output.
-                              Requires --corpus.
             --cross-host-shapes
                               List route shapes that recur across
                               multiple hosts. Combine with --min-hosts.
-                              Requires --corpus.
             --activate-above F  With --propose-recognizers, promote every
                               proposal at or above CONFIDENCE F into a
                               live Recognizer on the corpus, then
                               reinfer. Confidence integrates coverage
                               and cross-host corroboration.
 
+      Environment:
+            IRIQ_CORPUS=PATH    Set the corpus path (overrides the default).
+            IRIQ_NO_CORPUS=1    Disable the default corpus (equivalent to -C).
+
       Thresholds (apply to --propose-recognizers / --cross-host-shapes):
             --min-observations N  proposal noise floor (default 20)
             --min-coverage F      proposal coverage floor (default 0.7)
@@ -70,18 +82,23 @@ module Iriq
         -h, --help            Show this message
         -j, --json            Emit JSON instead of human-readable output
         -J, --ndjson          Newline-delimited JSON (one object per line). Implies --json.
+                              Streams per IRI only with -n/-p/-c/-e; alone, it
+                              prints the URL list or clusters at end of input.
         -N, --no-hints        Use {integer} placeholders instead of {user_id}
             --no-scheme-less  Skip foo.com/path extraction (explicit-scheme only)
         -V, --version         Print version
 
       Subcommands:
-        cluster [file]        Force cluster view (default for ≥10 IRIs anyway)
+        cluster [file]        Observe file (or stdin), then show every cluster
+                              in the corpus (default view for ≥10 IRIs anyway)
+        completion <shell>    Print shell completion script (bash | zsh)
 
       Examples:
         iriq foo.com/users/456
         iriq -n https://foo.com/users/123
-        iriq ./access.log                     # auto-detect file → extract URLs
+        iriq access.log                       # extract URLs (request paths have no host)
         cat README.md | iriq -n               # one normalized URL per line
+        tail -f app.log | iriq -nJ            # live stream → NDJSON per IRI
         cat README.md | iriq --corpus c.json
     TXT
 
@@ -114,18 +131,30 @@ module Iriq
       explicit_cluster = (args.first == "cluster")
       args.shift if explicit_cluster
 
-      # Auto-detect: a positional argument that isn't parseable as an IRI
-      # but IS an existing file gets treated as a file to extract from. This
-      # is what makes `iriq ./access.log` and `iriq /var/log/foo.log` Just
-      # Work without a separate --extract flag.
-      positional_is_file = args.first && File.file?(args.first) && !parseable_iri?(args.first)
+      # A positional that names an existing file is read as a file, so
+      # `iriq access.log` works without ./ (it also parses as a host). An
+      # argument containing "://" is always an IRI.
+      positional_is_file = args.first && !args.first.include?("://") && File.file?(args.first)
 
       batch_mode = explicit_cluster || positional_is_file ||
                    (args.empty? && piped_stdin?)
 
+      # --reset short-circuits: delete the resolved corpus file (+ sidecars)
+      # and exit. Resolves through the same precedence chain as the normal
+      # path so `--reset --corpus other.db` and `IRIQ_CORPUS=… --reset` Just Work.
+      if opts[:reset]
+        return cmd_reset(opts)
+      end
+
+      # Before any corpus is opened, so a typo doesn't create one.
+      if (missing = missing_input_file(args.first, explicit_cluster))
+        raise InputError.new("file_not_found", "no such file: #{missing}")
+      end
+
       return print_usage(stdout, 0) if args.empty? && !batch_mode && !opts[:reinfer] && !opts[:propose] && !opts[:cross_host_shapes]
 
-      corpus = opts[:corpus] ? load_corpus(opts[:corpus], host_strategy: opts[:host_strategy]) : nil
+      corpus_path = resolve_corpus_path(opts)
+      corpus = corpus_path ? load_corpus(corpus_path, host_strategy: opts[:host_strategy], announce_create: true) : nil
 
       code = if opts[:reinfer]
         cmd_reinfer(corpus, opts)
@@ -141,12 +170,26 @@ module Iriq
         cmd_summary(args, opts, corpus)
       end
 
-      corpus.save(opts[:corpus]) if corpus && opts[:corpus]
+      corpus.save(corpus_path) if corpus && corpus_path
       code
     rescue Iriq::ParseError => e
       emit_error("parse_error", e.message, 2, human: "iriq: parse error: #{e.message}")
     rescue OptionParser::ParseError => e
       emit_error("option_error", e.message, 1)
+    rescue InputError => e
+      emit_error(e.code, e.message, 1)
+    rescue Iriq::CorpusError => e
+      emit_error("corpus_error", e.message, 1)
+    end
+
+    # Input iriq can't read. `code` is the JSON error envelope's code.
+    class InputError < Iriq::Error
+      attr_reader :code
+
+      def initialize(code, message)
+        super(message)
+        @code = code
+      end
     end
 
     def parseable_iri?(input)
@@ -158,6 +201,15 @@ module Iriq
 
     private
 
+    # The argument iriq would have read as a file but can't find: anything
+    # after `cluster`, or a /, ./, ../ path that isn't an IRI.
+    def missing_input_file(arg, explicit_cluster)
+      return nil if arg.nil? || arg == "-" || File.file?(arg)
+      return arg if explicit_cluster
+
+      arg if arg.start_with?("/", "./", "../") && !parseable_iri?(arg)
+    end
+
     def parse_options(argv)
       opts = {
         json:        false,
@@ -167,6 +219,8 @@ module Iriq
         hints:       true,
         sections:    [],
         corpus:        nil,
+        no_corpus:     false,
+        reset:         false,
         stats:         false,
         reinfer:       false,
         propose:       false,
@@ -191,6 +245,8 @@ module Iriq
         o.on("--[no-]hints")         { |v| opts[:hints] = v }
         o.on("-N")                   { opts[:hints] = false }
         o.on("--corpus PATH")        { |v| opts[:corpus] = v }
+        o.on("-C", "--no-corpus")    { opts[:no_corpus] = true }
+        o.on("--reset")              { opts[:reset] = true }
         o.on("--host MODE")          { |v| opts[:host_strategy] = host_strategy_arg(v) }
         o.on("--stats")              { opts[:stats]   = true }
         o.on("--reinfer")            { opts[:reinfer] = true }
@@ -220,8 +276,95 @@ module Iriq
       end
     end
 
-    def load_corpus(path, host_strategy: :full)
-      Corpus.open(path, host_strategy: host_strategy)
+    def load_corpus(path, host_strategy: :full, announce_create: false)
+      creating = announce_create && !File.exist?(path)
+      if creating
+        begin
+          FileUtils.mkdir_p(File.dirname(path))
+        rescue SystemCallError => e
+          raise CorpusError, "corpus #{path}: #{Iriq.os_error_message(e)}"
+        end
+      end
+      corpus = Corpus.open(path, host_strategy: host_strategy)
+      # Only announce once the corpus actually exists — mkdir_p can succeed
+      # (e.g. the dir is there but read-only) while the open still fails.
+      stderr.puts "iriq: created corpus at #{path} (disable with --no-corpus or IRIQ_NO_CORPUS=1)" if creating
+      corpus
+    end
+
+    # Resolve the corpus file the CLI should use. Precedence:
+    #   1. --corpus PATH       — explicit always wins (you asked for it)
+    #   2. --no-corpus / IRIQ_NO_CORPUS=1 — opt out of the default
+    #   3. IRIQ_CORPUS=PATH    — env override of the default location
+    #   4. default_corpus_path — platform-aware location
+    def resolve_corpus_path(opts)
+      return opts[:corpus] if opts[:corpus]
+      return nil if opts[:no_corpus] || env_corpus_disabled?
+
+      env_path = ENV["IRIQ_CORPUS"].to_s
+      return env_path unless env_path.empty?
+
+      default_corpus_path
+    end
+
+    # Platform-aware default. XDG-honoring on Linux + BSD, Apple-style on
+    # macOS, %LOCALAPPDATA% on Windows. Same logic in Rust so both
+    # runtimes share the same default.db.
+    def default_corpus_path
+      base = if (xdg = ENV["XDG_DATA_HOME"].to_s) && !xdg.empty?
+        File.join(xdg, "iriq")
+      elsif RUBY_PLATFORM =~ /darwin/
+        File.expand_path("~/Library/Application Support/iriq")
+      elsif RUBY_PLATFORM =~ /mingw|mswin|cygwin/
+        File.join(ENV["LOCALAPPDATA"].to_s.empty? ? File.expand_path("~/AppData/Local") : ENV["LOCALAPPDATA"], "iriq")
+      else
+        File.expand_path("~/.local/share/iriq")
+      end
+      File.join(base, "default.db")
+    end
+
+    def env_corpus_disabled?
+      v = ENV["IRIQ_NO_CORPUS"].to_s.downcase
+      !v.empty? && v != "0" && v != "false" && v != "no"
+    end
+
+    def cmd_reset(opts)
+      path = resolve_reset_path(opts)
+      unless path
+        return emit_error("missing_argument", "no corpus path to reset (use --corpus PATH or unset --no-corpus)", 1)
+      end
+      removed = []
+      [path, "#{path}-wal", "#{path}-shm", "#{path}.tmp", *json_temp_files(path)].each do |p|
+        if File.exist?(p)
+          File.delete(p)
+          removed << p
+        end
+      end
+      if removed.empty?
+        stderr.puts "iriq: no corpus to reset at #{path}"
+      else
+        stderr.puts "iriq: reset corpus at #{path}"
+      end
+      0
+    end
+
+    # The JSON writer's per-save temp files, PATH.<pid>.<n>.tmp
+    # (Storage.write_atomically); a save killed before its rename leaves one.
+    def json_temp_files(path)
+      dir = File.dirname(path)
+      return [] unless Dir.exist?(dir)
+
+      pattern = /\A#{Regexp.escape(File.basename(path))}\.\d+\.\d+\.tmp\z/
+      Dir.children(dir).grep(pattern).map { |name| File.join(dir, name) }
+    end
+
+    # --reset honors --corpus / IRIQ_CORPUS even when --no-corpus is set —
+    # the user is explicitly addressing a stored file, not the runtime state.
+    def resolve_reset_path(opts)
+      return opts[:corpus] if opts[:corpus]
+      env_path = ENV["IRIQ_CORPUS"].to_s
+      return env_path unless env_path.empty?
+      default_corpus_path
     end
 
     # Accept `--host=reg` as a short alias for the `registrable` mode.
@@ -231,7 +374,9 @@ module Iriq
 
     def host_strategy_arg(value)
       mode = HOST_STRATEGY_ALIASES[value.to_s.downcase]
-      raise OptionParser::InvalidArgument, "--host: expected full|registrable|reg|none, got #{value.inspect}" unless mode
+      # OptionParser prefixes the switch itself ("--host bogus" / "--host=bogus"),
+      # so the message carries only the accepted modes.
+      raise OptionParser::InvalidArgument.new(value, "(expected full|registrable|reg|none)") unless mode
 
       mode
     end
@@ -255,9 +400,7 @@ module Iriq
       data = {}
       data[:parse]     = identifier_hash(iri) if sections.include?(:parse)
       data[:canonical] = iri.canonical         if sections.include?(:canonical)
-      if sections.include?(:normalize)
-        data[:normalize] = corpus ? corpus.normalize(iri) : Normalizer.normalize_identifier(iri, hints: opts[:hints])
-      end
+      data[:normalize] = normalize_section(iri, opts, corpus) if sections.include?(:normalize)
       if sections.include?(:explain)
         data[:explain] = Trace.for(iri, hints: opts[:hints])
       end
@@ -276,20 +419,20 @@ module Iriq
     # of URLs (one per line) and a file of prose with URLs both work. The
     # corpus is ephemeral unless --corpus was given.
     def cmd_batch(args, opts, corpus, explicit_cluster: false)
-      corpus ||= Corpus.new
-
-      # Per-IRI sections (-n/-p/-c/-e) are independent line to line, so we
-      # stream: read input lazily, extract per line, and emit each IRI as it
-      # arrives (flushed for live `tail -f | iriq -n` pipelines). The aggregate
-      # views below — stats, clusters, the deduped URL list — need the whole
-      # input, so they slurp.
+      # Per-IRI sections (-n/-p/-c/-e) stream: read input lazily, extract per
+      # line, and emit each IRI as it arrives (flushed for live
+      # `tail -f | iriq -n` pipelines). Each IRI renders as single-input would,
+      # so with -C there is no corpus, not a throwaway one. The aggregate views
+      # below — stats, clusters, the deduped URL list — need the whole input,
+      # so they slurp.
       if opts[:sections].any?
         emit_per_iri_sections(lazy_iris(args.first, opts), opts, corpus)
         return 0
       end
 
-      iris = extract_text(read_text(args.first), opts)
-      corpus.batch { iris.each { |iri| corpus.observe(iri) } }
+      corpus ||= Corpus.new(host_strategy: opts[:host_strategy])
+      iris = extract_text(utf8!(read_text(args.first)), opts)
+      corpus.observe_all(iris)
 
       if opts[:stats]
         emit_stats(corpus, opts)
@@ -309,19 +452,42 @@ module Iriq
     # (URL_CHAR_CLASS excludes whitespace) and `extract` does not dedup.
     def lazy_iris(path, opts)
       extractor = Extractor.new(scheme_less: opts[:scheme_less])
-      input_lines(path).lazy.flat_map { |line| extractor.extract(line) }
+      input_lines(path).lazy.flat_map { |line| extractor.extract(utf8!(line)) }
     end
 
+    # Yields input lines as they arrive. Only the reads are guarded, so a
+    # failure in the caller's block isn't mistaken for a read error.
     def input_lines(path)
-      if path.nil? || path == "-"
-        stdin.each_line
-      else
-        File.foreach(path)
+      return enum_for(:input_lines, path) unless block_given?
+
+      io = path.nil? || path == "-" ? stdin : read_guard { File.open(path) }
+      while (line = read_guard { io.gets })
+        yield line
       end
+    ensure
+      io.close if io && !io.equal?(stdin)
     end
 
-    # Emit the requested sections (parse/normalize/explain) for each extracted
-    # IRI, observing each into `corpus` as it passes. `iris` may be a lazy
+    # Input iriq can't read is the OS error in the Rust CLI's words,
+    # `iriq: Permission denied (os error 13)`, code read_error.
+    def read_guard
+      yield
+    rescue SystemCallError => e
+      raise InputError.new("read_error", Iriq.os_error_message(e))
+    end
+
+    # Input is UTF-8 regardless of locale; anything else is an error, not a
+    # backtrace. Message matches the Rust CLI's io::Error text.
+    def utf8!(text)
+      text = text.dup.force_encoding(Encoding::UTF_8)
+      raise InputError.new("invalid_utf8", "stream did not contain valid UTF-8") unless text.valid_encoding?
+
+      text
+    end
+
+    # Emit the requested sections (parse/canonical/normalize/explain) for each
+    # extracted IRI, observing each into `corpus` (when there is one) and then
+    # rendering it from the corpus as it now stands. `iris` may be a lazy
     # enumerator; human and NDJSON output stream (flushed per IRI) while a single
     # JSON array must be materialized. -n alone is the cleanest case: one line
     # per URL.
@@ -331,14 +497,14 @@ module Iriq
       # A wrapping JSON array can't be emitted incrementally — collect it
       # (force the lazy enumerator to a real Array so emit_json sees an array).
       if opts[:json] && !opts[:ndjson]
-        payloads = iris.map { |iri| corpus.observe(iri); section_payload(iri, sections, opts) }.to_a
+        payloads = iris.map { |iri| corpus&.observe(iri); section_payload(iri, sections, opts, corpus) }.to_a
         out = sections.size == 1 ? payloads.map(&:values).flatten(1) : payloads
         return emit_json(out, opts)
       end
 
       iris.each_with_index do |iri, i|
-        corpus.observe(iri)
-        p = section_payload(iri, sections, opts)
+        corpus&.observe(iri)
+        p = section_payload(iri, sections, opts, corpus)
         if opts[:ndjson]
           items = sections.size == 1 ? p.values : [p]
           items.each { |item| stdout.puts JSON.generate(item) }
@@ -354,6 +520,7 @@ module Iriq
             when :parse     then emit_parse_human(p[:parse])
             when :canonical then stdout.puts p[:canonical]
             when :normalize then stdout.puts p[:normalize]
+            when :explain   then emit_explain_human(p[:explain])
             end
           end
         end
@@ -361,14 +528,21 @@ module Iriq
       end
     end
 
-    def section_payload(iri, sections, opts)
+    # Key order is fixed (parse, canonical, normalize, explain) whatever the
+    # flag order, matching cmd_summary's multi-section JSON.
+    def section_payload(iri, sections, opts, corpus)
       data = {}
-      data[:parse]     = identifier_hash(iri)                                       if sections.include?(:parse)
-      data[:canonical] = iri.canonical                                              if sections.include?(:canonical)
-      data[:normalize] = Normalizer.normalize_identifier(iri, hints: opts[:hints])  if sections.include?(:normalize)
+      data[:parse]     = identifier_hash(iri)                  if sections.include?(:parse)
+      data[:canonical] = iri.canonical                         if sections.include?(:canonical)
+      data[:normalize] = normalize_section(iri, opts, corpus)  if sections.include?(:normalize)
+      data[:explain]   = Trace.for(iri, hints: opts[:hints])   if sections.include?(:explain)
       data
     end
 
+    def normalize_section(iri, opts, corpus)
+      corpus ? corpus.normalize(iri, hints: opts[:hints]) : Normalizer.normalize_identifier(iri, hints: opts[:hints])
+    end
+
     def extract_text(text, opts)
       Extractor.new(scheme_less: opts[:scheme_less]).extract(text)
     end
@@ -406,7 +580,7 @@ module Iriq
     # --propose-recognizers: scan observed values for prefix patterns
     # that recur enough to suggest a new Recognizer. Prints one block
     # per proposal in human mode, or a JSON array under --json. With
-    # --activate-above F, every proposal at or above coverage F is
+    # --activate-above F, every proposal at or above confidence F is
     # promoted to a live Recognizer on the corpus's classifier and the
     # corpus reinfers to apply the new classifier to existing
     # observations.
@@ -421,7 +595,7 @@ module Iriq
       if opts[:activate_above]
         activated = corpus.activate_proposals_above(opts[:activate_above], **kwargs)
         if activated.empty?
-          stdout.puts "no proposals at or above coverage #{opts[:activate_above]}"
+          stdout.puts "no proposals at or above confidence #{opts[:activate_above]}"
         else
           activated.each do |r|
             stdout.puts "activated: #{r.type} (#{r.prefix})"
@@ -473,9 +647,10 @@ module Iriq
     end
 
     # `completion <shell>` — emit the bundled shell-completion script.
-    # Scripts live in completions/{iriq.bash,_iriq} alongside the gem;
-    # Homebrew installs them automatically, but the user can also do
-    # `source <(iriq completion bash)` in their shell rc.
+    # Scripts live in completions/{iriq.bash,_iriq} alongside the
+    # gem; Homebrew installs them automatically, but the user can also do
+    # `source <(iriq completion bash)` in their shell rc. The Rust CLI
+    # inlines the same scripts — keep them byte-identical (parity-tested).
     COMPLETIONS_DIR = File.expand_path("../../completions", __dir__).freeze
     COMPLETION_FILES = {
       "bash" => File.join(COMPLETIONS_DIR, "iriq.bash"),
@@ -551,20 +726,8 @@ module Iriq
       exit_code
     end
 
-    def read_input(path)
-      if path.nil? || path == "-"
-        stdin.read.lines
-      else
-        File.readlines(path)
-      end
-    end
-
     def read_text(path)
-      if path.nil? || path == "-"
-        stdin.read
-      else
-        File.read(path)
-      end
+      read_guard { path.nil? || path == "-" ? stdin.read : File.read(path) }
     end
 
     # Compact identifier hash for parse output (both JSON and human). Drops
@@ -653,7 +816,10 @@ module Iriq
     end
 
     def emit_clusters(clusters, opts)
-      sorted = clusters.sort_by { |c| -c.count }
+      # Stable sort: equal-count clusters keep first-seen order. Ruby's
+      # sort_by is unstable, so ties need the explicit index tie-break to
+      # match the Rust CLI's (stable) sort.
+      sorted = clusters.sort_by.with_index { |c, i| [-c.count, i] }
 
       if opts[:json]
         emit_json(sorted.map(&:to_h), opts)
@@ -672,8 +838,8 @@ module Iriq
       end
     end
 
-    # One line per param: type, range (numeric), cardinality, presence.
-    # `page  integer  1..100  avg 50.5  (10 distinct, 100%)`
+    # One line per param: type, confidence, range (numeric), cardinality,
+    # presence. `page  integer  conf 0.87  1..100  avg 50.5  (10 distinct, 100%)`
     def emit_param_summary(cluster)
       rows = cluster.param_summary
       return if rows.empty?
@@ -681,6 +847,7 @@ module Iriq
       width = rows.map { |r| r[:name].length }.max
       rows.each do |r|
         bits = ["#{r[:type]}"]
+        bits << "conf #{format_conf(r[:confidence])}" if r[:confidence]
         if r[:min] && r[:max]
           bits << format_range(r[:min], r[:max])
           bits << "avg #{format_num(r[:avg])}" if r[:avg]
@@ -690,6 +857,11 @@ module Iriq
       end
     end
 
+    # Two-decimal confidence, e.g. 0.87. Matches the Rust CLI formatting.
+    def format_conf(conf)
+      format("%.2f", conf)
+    end
+
     def format_range(lo, hi)
       "#{format_num(lo)}..#{format_num(hi)}"
     end
@@ -737,9 +909,8 @@ module Iriq
     end
 
     def top(hash)
-      # Lex tie-break on equal counts — Ruby Hash insertion order would
-      # otherwise diverge from Go's map iteration (which has no insertion
-      # order). Keeps Ruby ↔ Go --stats parity stable.
+      # Lex tie-break on equal counts — keeps --stats output deterministic
+      # and Ruby ↔ Rust parity stable regardless of insertion order.
       hash.sort_by { |k, n| [-n, k] }.first(TOP_N_STATS).to_h
     end
   end