okf 1.12.0 → 2.0.0

data/lib/okf/bundle/validator.rb

@@ -2,21 +2,36 @@
 
 module OKF
   class Bundle
-    # Checks an OKF::Bundle against the OKF v0.1 conformance rules (§9), which has
+    # Checks an OKF::Bundle against the OKF conformance rules (§11), which has
     # three conditions — all hard errors:
     #
-    #   §9.1  every non-reserved file has a parseable YAML frontmatter block;
-    #   §9.2  every such block has a non-empty `type`;
-    #   §9.3  every index.md/log.md present follows the §6/§7 structure — a nested
-    #         index.md has no frontmatter, a root index.md carries only okf_version,
-    #         and log.md date headings are ISO `YYYY-MM-DD`.
+    #   §11 c1  every non-reserved file has a parseable YAML frontmatter block;
+    #   §11 c2  every such block has a non-empty `type`;
+    #   §11 c3  every index.md/log.md present follows the §8/§9 structure — a nested
+    #          index.md has no frontmatter, a root index.md carries only okf_version,
+    #          and log.md date headings are ISO `YYYY-MM-DD`.
     #
     # Everything the spec marks as soft guidance is a warning and never makes a
     # bundle non-conformant: missing recommended fields, non-list tags, an
-    # unparseable timestamp, and broken cross-links (§5.3), which consumers MUST
-    # tolerate. Pure — it reads nothing from disk; it works entirely on the
-    # in-memory bundle.
+    # unparseable timestamp, broken cross-links (§6.1), and every v0.2 family
+    # shape (§5, §10). Pure — it reads nothing from disk; it works entirely on
+    # the in-memory bundle.
+    #
+    # Warnings are machine-readable: each carries a `check:` id and a `source:`
+    # naming who states the rule — `:spec` for the SPEC's own words,
+    # `:convention` for a shape this gem asks for beyond them. Errors keep their
+    # exact two-key shape; consumers already read it.
     class Validator
+      # The warnings that state a gem convention rather than a SPEC rule. §5.1
+      # gives `usage_count` no type and §10.2 marks only `runtime` REQUIRED;
+      # `verified[].by` is REQUIRED-within by analogy with `generated.by`, not
+      # by the SPEC's own words. A consumer that wants only the spec-normative
+      # warnings filters on `source:` instead of string-matching messages.
+      CONVENTION_CHECKS = %i[
+        verified_entry_by source_usage_count source_usage_window_shape
+        parameter_name executor_resource attester_resource
+      ].freeze
+
       def self.call(bundle)
         new(bundle).call
       end
@@ -36,20 +51,203 @@ module OKF
 
       private
 
-      # §9.2 (non-empty type) is the only hard error here; the missing recommended
-      # fields, non-list tags, and bad timestamp are soft warnings (never
-      # non-conformant). A parsed concept is valid UTF-8 by construction.
+      # Every warning goes through here so the check id and its source cannot
+      # drift apart: the id is the API, the source is derived from one constant.
+      #
+      # Not `warn`: that name shadows Kernel#warn for every method in the class,
+      # so a later `warn "…"` meant for stderr would raise ArgumentError at
+      # runtime — a collision neither RuboCop nor the call site can show you.
+      def record_warning(path, check, message)
+        @result.add_warning(path, message,
+          check: check,
+          source: CONVENTION_CHECKS.include?(check) ? :convention : :spec)
+      end
+
+      # §11.2 (non-empty type) is the only hard error here; the missing
+      # recommended fields, non-list tags, and bad timestamp are soft warnings
+      # (never non-conformant). A parsed concept is valid UTF-8 by construction.
       def validate_concept(concept)
         @result.count(:concepts)
         @result.add_error(concept.path, "frontmatter must include a non-empty type") if OKF.blank?(concept.type)
-        @result.add_warning(concept.path, "frontmatter should include title") if OKF.blank?(concept.title)
-        @result.add_warning(concept.path, "frontmatter should include description") if OKF.blank?(concept.description)
-        @result.add_warning(concept.path, "tags should be a list") if concept.frontmatter.key?("tags") && !concept.tags.is_a?(Array)
-        validate_timestamp(concept.path, concept.timestamp) if concept.frontmatter.key?("timestamp")
+        record_warning(concept.path, :recommended_title, "frontmatter should include title") if OKF.blank?(concept.title)
+        record_warning(concept.path, :recommended_description, "frontmatter should include description") if OKF.blank?(concept.description)
+        record_warning(concept.path, :tags_shape, "tags should be a list") if concept.frontmatter.key?("tags") && !concept.tags.is_a?(Array)
+        validate_iso8601(concept.path, :timestamp_format, "timestamp", concept.timestamp) if concept.frontmatter.key?("timestamp")
+        validate_families(concept)
         check_links(concept.path, concept.body)
       end
 
-      # §9.1: a concept-position file whose frontmatter did not parse. The message is
+      # ── the v0.2 families (§5, §10) ──────────────────────────────────────────
+      #
+      # Shape, and only shape: is it a mapping, does the date parse, is the enum
+      # value one the spec names. Whether a field is *missing*, *stale* or
+      # *unattributed* is curation, and the linter owns it — without that line the
+      # two would double-report every family.
+      #
+      # Every check reads the raw frontmatter key, never the fallback-carrying
+      # accessor — otherwise every v0.1 concept would warn about a mapping the
+      # §13.1 fallback synthesized, and "a pure v0.1 bundle validates silently"
+      # would stop being true. And every check is guarded by `frontmatter.key?`,
+      # so absence is never a fault: each family is optional (§5), and a v0.1
+      # concept that adopts none is a valid v0.2 concept. All warnings — §11's
+      # conformance conditions are only three.
+      def validate_families(concept)
+        validate_generated(concept)
+        validate_verified(concept)
+        validate_sources(concept)
+        validate_usage_window(concept)
+        validate_lifecycle(concept)
+        validate_computation(concept)
+      end
+
+      def validate_generated(concept)
+        return unless concept.frontmatter.key?("generated")
+
+        value = concept.frontmatter["generated"]
+        unless value.is_a?(Hash)
+          record_warning(concept.path, :generated_shape, "generated should be a mapping")
+          return
+        end
+
+        generated = Markdown::Frontmatter.stringify_keys(value)
+        record_warning(concept.path, :generated_by, "generated should include by") if OKF.blank?(generated["by"])
+        validate_iso8601(concept.path, :generated_at_format, "generated.at", generated["at"]) if generated.key?("at")
+      end
+
+      # §5.2 permits a list or a single bare mapping; anything else records no
+      # verification at all, which is what the warning is about.
+      def validate_verified(concept)
+        return unless concept.frontmatter.key?("verified")
+
+        value = concept.frontmatter["verified"]
+        return validate_verified_entries(concept, [ value ]) if value.is_a?(Hash)
+        return validate_verified_entries(concept, value) if value.is_a?(Array)
+
+        record_warning(concept.path, :verified_shape, "verified should be a mapping or a list of mappings")
+      end
+
+      def validate_verified_entries(concept, entries)
+        entries.each_with_index do |entry, index|
+          unless entry.is_a?(Hash)
+            record_warning(concept.path, :verified_entry_shape, "verified[#{index}] should be a mapping")
+            next
+          end
+
+          event = Markdown::Frontmatter.stringify_keys(entry)
+          record_warning(concept.path, :verified_entry_by, "verified[#{index}] should include by") if OKF.blank?(event["by"])
+          validate_iso8601(concept.path, :verified_entry_at_format, "verified[#{index}].at", event["at"]) if event.key?("at")
+        end
+      end
+
+      def validate_sources(concept)
+        return unless concept.frontmatter.key?("sources")
+
+        value = concept.frontmatter["sources"]
+        unless value.is_a?(Array)
+          record_warning(concept.path, :sources_shape, "sources should be a list")
+          return
+        end
+
+        value.each_with_index { |entry, index| validate_source(concept, entry, index) }
+      end
+
+      # `resource` is what makes a source addressable, so its absence is the one
+      # that matters most; `last_modified` and `usage_count` are the credibility
+      # signals with a shape to get wrong, and a per-entry `usage_window`
+      # override must be the same mapping the sibling is (§5.1).
+      def validate_source(concept, entry, index)
+        unless entry.is_a?(Hash)
+          record_warning(concept.path, :source_entry_shape, "sources[#{index}] should be a mapping")
+          return
+        end
+
+        source = Markdown::Frontmatter.stringify_keys(entry)
+        record_warning(concept.path, :source_resource, "sources[#{index}] should include resource") if OKF.blank?(source["resource"])
+        validate_date(concept.path, :source_last_modified, "sources[#{index}].last_modified", source["last_modified"]) if source.key?("last_modified")
+        if source.key?("usage_count") && !source["usage_count"].is_a?(Integer)
+          record_warning(concept.path, :source_usage_count, "sources[#{index}].usage_count should be an integer")
+        end
+        return unless source.key?("usage_window") && !source["usage_window"].is_a?(Hash)
+
+        record_warning(concept.path, :source_usage_window_shape, "sources[#{index}].usage_window should be a mapping")
+      end
+
+      def validate_usage_window(concept)
+        return unless concept.frontmatter.key?("usage_window")
+
+        value = concept.frontmatter["usage_window"]
+        unless value.is_a?(Hash)
+          record_warning(concept.path, :usage_window_shape, "usage_window should be a mapping")
+          return
+        end
+
+        window = Markdown::Frontmatter.stringify_keys(value)
+        %w[from to].each { |key| validate_date(concept.path, :usage_window_date, "usage_window.#{key}", window[key]) if window.key?(key) }
+      end
+
+      # §5.4 lets a producer use a status outside the three and requires consumers
+      # to tolerate it (§4.1), so this is a warning about a vocabulary a consumer
+      # keyed to the spec will not understand — never a rejection.
+      def validate_lifecycle(concept)
+        # fold_status, not effective_status: the §5.4 default belongs to a
+        # concept that never declared the key, and applying it here read a
+        # blank `status: ""` as `stable` — so the one value §5.4 names nowhere
+        # was the one value that never warned.
+        if concept.frontmatter.key?("status") && !Concept::STATUSES.include?(Concept.fold_status(concept.declared_status))
+          record_warning(concept.path, :status_vocabulary, "status should be one of #{Concept::STATUSES.join(", ")}")
+        end
+
+        validate_date(concept.path, :stale_after_format, "stale_after", concept.stale_after) if concept.frontmatter.key?("stale_after")
+      end
+
+      # §10.2 makes `runtime` REQUIRED for an Attested Computation — but §11's
+      # conformance conditions are only three, so its absence is a warning here
+      # and the linter owns the rest of the contract (one home per finding:
+      # shape and REQUIRED-within are the validator's side).
+      def validate_computation(concept)
+        if concept.attested_computation? && OKF.blank?(concept.frontmatter["runtime"])
+          record_warning(concept.path, :runtime_required, "runtime is required for an Attested Computation")
+        end
+
+        validate_parameters(concept)
+        validate_contract_mapping(concept, "executor", :executor_shape, :executor_resource)
+        validate_contract_mapping(concept, "attester", :attester_shape, :attester_resource)
+      end
+
+      def validate_parameters(concept)
+        return unless concept.frontmatter.key?("parameters")
+
+        value = concept.frontmatter["parameters"]
+        unless value.is_a?(Array)
+          record_warning(concept.path, :parameters_shape, "parameters should be a list")
+          return
+        end
+
+        value.each_with_index do |entry, index|
+          unless entry.is_a?(Hash)
+            record_warning(concept.path, :parameter_entry_shape, "parameters[#{index}] should be a mapping")
+            next
+          end
+
+          parameter = Markdown::Frontmatter.stringify_keys(entry)
+          record_warning(concept.path, :parameter_name, "parameters[#{index}] should include name") if OKF.blank?(parameter["name"])
+        end
+      end
+
+      def validate_contract_mapping(concept, key, shape_check, resource_check)
+        return unless concept.frontmatter.key?(key)
+
+        value = concept.frontmatter[key]
+        unless value.is_a?(Hash)
+          record_warning(concept.path, shape_check, "#{key} should be a mapping")
+          return
+        end
+
+        contract = Markdown::Frontmatter.stringify_keys(value)
+        record_warning(concept.path, resource_check, "#{key} should include resource") if OKF.blank?(contract["resource"])
+      end
+
+      # §11.1: a concept-position file whose frontmatter did not parse. The message is
       # the ParseError captured at read time.
       def validate_unparseable(entry)
         unless entry.content.valid_encoding?
@@ -85,46 +283,89 @@ module OKF
         frontmatter, = Markdown::Frontmatter.parse(content)
         extra_keys = frontmatter.keys - [ "okf_version" ]
         @result.add_error(path, "root index.md frontmatter may only include okf_version") if extra_keys.any?
+        validate_okf_version(path, frontmatter["okf_version"]) if frontmatter.key?("okf_version")
       rescue Markdown::Frontmatter::ParseError => e
         @result.add_error(path, e.message)
       end
 
+      # §12 asks a consumer to attempt best-effort consumption rather than
+      # refuse, so an unknown version is a warning and the bundle is read
+      # anyway; an absent one is the sanctioned MAY-not-declare case and never
+      # warns. Compared after `to_s.strip`: an unquoted `okf_version: 0.2` is a
+      # Psych Float, and warning on a correctly-declared bundle is the bug.
+      def validate_okf_version(path, declared)
+        return if OKF.blank?(declared) || Concept::KNOWN_SPEC_VERSIONS.include?(declared.to_s.strip)
+
+        record_warning(path, :okf_version_unknown,
+          "okf_version `#{declared}` is not a version this gem knows (read best-effort under §12)")
+      end
+
       def validate_log(path, content)
         content.each_line do |line|
           next unless line.start_with?("## ")
 
           heading = line.sub(/\A## /, "").strip
-          next if heading.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+          next if date_heading?(heading)
 
           @result.add_error(path, "log.md date headings must use YYYY-MM-DD")
         end
       end
 
-      # Broken bundle-internal links are warnings only (§5.3): the spec requires
+      # §9's MUST is ISO 8601, and 2026-02-30 is not a date — the digit shape
+      # alone accepted it, so a bundle could be conformant around a day that
+      # never existed. Same message either way: "must use YYYY-MM-DD" is as
+      # true of a February 30th as of a prose heading.
+      def date_heading?(heading)
+        return false unless heading.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+
+        Date.iso8601(heading)
+        true
+      rescue ArgumentError
+        false
+      end
+
+      # Broken bundle-internal links are warnings only (§6.1): the spec requires
       # consumers to tolerate them, so they never make a bundle non-conformant.
       def check_links(path, content)
         Markdown::Links.extract(content).each do |raw|
           resolved = Markdown::Links.resolve(raw, from: path, bundle: @bundle.root)
           next if resolved.nil? || @existing.include?(resolved)
 
-          @result.add_warning(path, "cross-link target not found: `#{raw}` (tolerated under §5.3)")
+          record_warning(path, :broken_link, "cross-link target not found: `#{raw}` (tolerated under §6.1)")
         end
       end
 
       # A YAML-parsed Date/Time is temporal by construction (YAML already validated
       # the shape); only a String needs checking, and it may be a full ISO 8601
       # datetime (2026-05-28T14:30:00Z) or a date-only value (2026-05-28).
-      def validate_timestamp(path, timestamp)
-        return if timestamp.is_a?(Date) || timestamp.is_a?(Time)
+      #
+      # `field` names what is being checked: one rule about what a moment looks
+      # like serves the legacy `timestamp`, `generated.at` and every
+      # `verified[].at`, reported against whichever field carried it.
+      def validate_iso8601(path, check, field, value)
+        return if value.is_a?(Date) || value.is_a?(Time)
 
-        value = timestamp.to_s
+        string = value.to_s
         begin
-          Time.iso8601(value)
+          Time.iso8601(string)
         rescue ArgumentError
-          Date.iso8601(value)
+          Date.iso8601(string)
         end
       rescue ArgumentError
-        @result.add_warning(path, "timestamp should be ISO 8601 parseable")
+        record_warning(path, check, "#{field} should be ISO 8601 parseable")
+      end
+
+      # §5.1/§5.5 want a calendar day, not a moment: `last_modified`,
+      # `usage_window.from`/`to` and `stale_after` are all YYYY-MM-DD. A YAML Date
+      # is one by construction; a Time is not — the extra precision means the
+      # producer wrote something else.
+      def validate_date(path, check, field, value)
+        return if value.is_a?(Date) && !value.is_a?(DateTime)
+
+        Date.iso8601(value.to_s)
+        record_warning(path, check, "#{field} should be a YYYY-MM-DD date") unless value.to_s.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+      rescue ArgumentError
+        record_warning(path, check, "#{field} should be a YYYY-MM-DD date")
       end
     end
   end

data/lib/okf/bundle/writer.rb

@@ -3,7 +3,7 @@
 module OKF
   class Bundle
     # Atomically writes a bundle to disk: renders concepts to a temp directory,
-    # validates it for §9 conformance (so a malformed bundle is never published),
+    # validates it for §11 conformance (so a malformed bundle is never published),
     # then promotes it into place under a lock. The disk-writing counterpart to
     # Reader.
     class Writer

data/lib/okf/bundle.rb

@@ -66,6 +66,28 @@ module OKF
       entry ? entry.content.to_s : ""
     end
 
+    # The spec version the root index.md declares (§12), as the producer wrote
+    # it, or nil when it declares none — which §12 explicitly permits, so nil is
+    # an answer rather than a fault, and a consumer that must name a version
+    # should say "conformant" rather than guess one.
+    #
+    # Stringified and stripped for the reason the validator compares that way:
+    # an unquoted `okf_version: 0.2` is a Psych Float, and a consumer switching
+    # on it must not be handed 0.2 the number. Public because a version stated
+    # on screen is otherwise a literal — which is how a reader gets told "v0.1"
+    # about a bundle that declares 0.2. Unparseable frontmatter is the
+    # validator's error to report, not this reader's to raise.
+    def okf_version
+      content = reserved_content("index.md")
+      return nil unless content.match?(/\A---[ \t]*\n/)
+
+      frontmatter, = Markdown::Frontmatter.parse(content)
+      declared = frontmatter["okf_version"]
+      OKF.blank?(declared) ? nil : declared.to_s.strip
+    rescue Markdown::Frontmatter::ParseError
+      nil
+    end
+
     # ── id ↔ path (the single source of "which concept an id names") ──
     # A concept's id may be a frontmatter `id`, so it is not derivable from the path
     # alone. These maps let the shell resolve an id back to its file (the server's
@@ -119,8 +141,13 @@ module OKF
           type: concept.type.to_s,
           description: concept.description.to_s,
           tags: Array(concept.tags).map(&:to_s),
-          timestamp: concept.timestamp&.to_s,
-          status: concept.frontmatter["status"]&.to_s,
+          generated_at: iso8601(concept.generated_at),
+          generated_by: concept.generated_by&.to_s,
+          generated: concept.declared_generated?,
+          trust: concept.trust,
+          status: concept.declared_status&.to_s,
+          stale_after: iso8601(concept.stale_after),
+          sources: concept.sources.length,
           backlog_ref: concept.frontmatter["backlog_ref"]&.to_s,
           dir: OKF.dir_of(id),
           top_dir: top_dir_of(id),
@@ -148,18 +175,87 @@ module OKF
       end.sort_by { |row| [ -row[:inbound], row[:id] ] }
     end
 
-    # The progressive-disclosure map (spec §6): one entry per directory that holds
+    # Bundle-level rollups — concepts, dirs, types, links, tags, with the
+    # by_type/by_dir/by_top_dir distributions. One home, shared by `okf stats`
+    # and the MCP stats tool, because the by_dir subtlety already diverged once
+    # when hand-copied: it reads Bundle#directory_index (the map `--dir` is
+    # answered against), so a directory holding nothing directly appears at 0
+    # rather than disappearing, and `dirs` equals `by_dir.size`.
+    # Note the recorded split: by_dir is the disk, by_top_dir rolls up the id.
+    def stats
+      minimal = graph(minimal: true)
+      entries = catalog
+      by_type = minimal.type_index.transform_values(&:size).sort_by { |_, size| -size }.to_h
+      by_top_dir = entries.group_by { |entry| entry[:top_dir] }.transform_values(&:size).sort_by { |_, size| -size }.to_h
+      by_dir = directory_index.map { |entry| [ entry[:dir], entry[:count] ] }
+                              .sort_by { |dir, count| [ -count, dir ] }.to_h
+      {
+        concepts: entries.size,
+        dirs: by_dir.size,
+        top_dirs: by_top_dir.size,
+        types: by_type.size,
+        cross_links: minimal.edges.size,
+        tags: minimal.tag_index.size,
+        by_type: by_type,
+        by_dir: by_dir,
+        by_top_dir: by_top_dir
+      }
+    end
+
+    # The tag index re-cut per concept dimension — the vocabulary-curation
+    # view: [ [ group-key, rows ], … ] with each row carrying `count` (within
+    # the group) beside `total` (across the set), so a tag local to one group
+    # and one cutting across several read differently without cross-referencing
+    # by hand. `by:` is :type (blank folds to "Untyped", matching the graph),
+    # :dir (the stored spelling — `.` for the root), or anything else for the
+    # deprecated first-segment cut. `entries:` narrows the concepts counted —
+    # the CLI passes its filtered catalog; default is everything.
+    def tag_groups(by:, entries: nil)
+      entries ||= catalog
+      by_id = entries.map { |entry| [ entry[:id], entry ] }.to_h
+      groups = {}
+      totals = Hash.new(0)
+      graph(minimal: true).tag_index.each do |tag, ids|
+        ids.each do |id|
+          entry = by_id[id]
+          next if entry.nil?
+
+          key = tag_group_key(entry, by)
+          ((groups[key] ||= {})[tag] ||= []) << id
+          totals[tag] += 1
+        end
+      end
+      groups.map do |key, tags|
+        rows = tags.map { |tag, ids| { tag: tag, count: ids.length, total: totals[tag], concepts: ids } }
+                   .sort_by { |row| [ -row[:count], row[:tag] ] }
+        [ key, rows ]
+      end.sort_by(&:first)
+    end
+
+    # The progressive-disclosure map (spec §8): 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
     # present, a type/tag rollup over the concepts that live *directly* in the
     # directory, its immediate child directories, and the concept listing an
     # index.md there would enumerate. A directory with concepts but no index.md has
     # `present: false` and still carries the listing, so a consumer can synthesize
-    # the map on the fly (§6 permits exactly that). Grouped by the concept's file
+    # the map on the fly (§8 permits exactly that). Grouped by the concept's file
     # path — index files are physical directory listings, so a custom frontmatter
     # `id` must not move a concept out of the directory it lives in. Pure: derived
     # from the concepts and the reserved index text, no disk. Shared by the
     # `okf index` view and the server's Index panel (/index).
+    # Every directory this bundle has — the same set #directory_index enumerates
+    # (concepts, an index.md or a log.md, plus every ancestor), without building
+    # the map. It is the answer to "does this bundle have a directory named X?",
+    # and the CLI needs exactly that to decide whether `--dir root` names a real
+    # directory or the bundle root. Reading it off #catalog instead is the same
+    # question asked of a smaller set, which is how the two views came to
+    # disagree about one bundle. Memoized: the model is immutable once read,
+    # and the resolvers above ask per invocation, not per bundle load.
+    def directories
+      @directories ||= directory_set(concepts.map { |concept| File.dirname(concept.path) }.uniq)
+    end
+
     def directory_index
       by_dir = concepts.group_by { |concept| File.dirname(concept.path) }
       dirs = directory_set(by_dir.keys)
@@ -193,6 +289,12 @@ module OKF
 
     private
 
+    # The one temporal-serialization rule, shared with /node/meta — see
+    # OKF.iso8601.
+    def iso8601(value)
+      OKF.iso8601(value)
+    end
+
     # A concept's top-level dir, derived from its id — the first path segment, the
     # same derivation the catalog exposes, so every grouped view labels the bundle
     # root "(root)". OKF.dir_of keeps the levels this one rolls up.
@@ -200,11 +302,14 @@ module OKF
       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.
+    # Every directory to show: those holding concepts, an index.md or a log.md,
+    # plus each of their ancestors up to the root, so the subdir tree stays
+    # connected even when an intermediate directory holds nothing directly. A
+    # scoped log counts because `okf log` reads it — a directory whose only file
+    # is its history still exists, and leaving it out is how the `root` alias
+    # beat a real `root/` for the second file kind in a row. Sorted "." first.
     def directory_set(concept_dirs)
-      seed = concept_dirs + index_files.map { |path| File.dirname(path) }
+      seed = concept_dirs + (index_files + log_files).map { |path| File.dirname(path) }
       dirs = {}
       seed.each do |dir|
         current = dir
@@ -218,6 +323,17 @@ module OKF
       dirs.keys.sort_by { |dir| dir == "." ? "" : dir }
     end
 
+    # The group a concept falls in, in its *stored* spelling — `.` for the
+    # root under :dir, never "(root)": the human label is applied at print
+    # time, so the JSON and a table cannot disagree about which is the data.
+    def tag_group_key(entry, dim)
+      case dim
+      when :type then OKF.blank?(entry[:type]) ? "Untyped" : entry[:type]
+      when :dir then entry[:dir]
+      else entry[:top_dir]
+      end
+    end
+
     # { value => count }, ordered by count descending then value.
     def tally(values)
       counts = values.each_with_object(Hash.new(0)) { |value, acc| acc[value] += 1 }

data/lib/okf/cli/catalog.rb

@@ -22,7 +22,7 @@ module OKF
       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]"
+          o.banner = "Usage: okf catalog <dir|@slug> [--type T] [--dir D] [--tag T] [--status S] [--trust T] [--json]"
           json_flags(o, options, "emit the catalog as JSON")
           projection_flags(o, options)
           filter_flags(o, options, :type, :area, :tag)
@@ -33,7 +33,7 @@ module OKF
         folder = OKF::Bundle::Folder.load(dir)
         report_skipped(folder)
         entries = folder.catalog
-        selected = filter_entries(entries, options)
+        selected = filter_entries(entries, options, dir_scope(folder, options))
         return print_catalog_json(dir, selected, options) if options[:json]
 
         print_catalog(dir, selected, entries.size)