ucode 0.1.0 → 0.2.0

data/lib/ucode/cli.rb

@@ -3,6 +3,7 @@
 require "thor"
 
 require "ucode/commands"
+require "ucode/version_resolver"
 
 module Ucode
   # Top-level CLI entry.
@@ -10,6 +11,12 @@ module Ucode
   # **Thin Thor**: every method delegates to a `Commands::*Command`
   # class and only formats the result. The Command classes are pure
   # and testable in-process — Thor never holds business logic.
+  #
+  # **Version resolution lives here** — each top-level command resolves
+  # the user-supplied intent (nil / :default / :latest / explicit string)
+  # exactly once via `VersionResolver.resolve` and threads the resolved
+  # string into the dispatched Command. Sub-commands never re-resolve.
+  # See Candidate 4 of the 2026-06-29 architecture review.
   class Cli < Thor
     package_name "ucode"
 
@@ -28,13 +35,17 @@ module Ucode
       desc "ucd [VERSION]", "Download UCD.zip"
       option :force, type: :boolean, default: false, desc: "Re-download even if cached"
       def ucd(version = nil)
-        puts format_result Commands::FetchCommand.new.fetch_ucd(version, force: options[:force])
+        puts format_result Commands::FetchCommand.new.fetch_ucd(
+          VersionResolver.resolve(version), force: options[:force],
+        )
       end
 
       desc "unihan [VERSION]", "Download Unihan.zip"
       option :force, type: :boolean, default: false
       def unihan(version = nil)
-        puts format_result Commands::FetchCommand.new.fetch_unihan(version, force: options[:force])
+        puts format_result Commands::FetchCommand.new.fetch_unihan(
+          VersionResolver.resolve(version), force: options[:force],
+        )
       end
 
       desc "charts [VERSION]", "Download per-block Code Charts PDFs"
@@ -43,7 +54,26 @@ module Ucode
       def charts(version = nil)
         cps = options[:block]&.map { |id| block_id_to_first_cp(id) }&.compact
         puts format_result Commands::FetchCommand.new
-          .fetch_charts(version, block_first_cps: cps, force: options[:force])
+          .fetch_charts(VersionResolver.resolve(version),
+                        block_first_cps: cps, force: options[:force])
+      end
+
+      desc "fonts", "Download specialist Tier 1 fonts (config/specialist_fonts.yml)"
+      option :manifest, type: :string,
+                        desc: "Override manifest path (default config/specialist_fonts.yml)"
+      option :label, type: :string, desc: "Fetch only this font by label"
+      option :allow_proprietary, type: :boolean, default: false,
+                                 desc: "Permit non-OFL licensed fonts"
+      option :dry_run, type: :boolean, default: false,
+                       desc: "Plan only; no network or disk writes"
+      def fonts
+        result = Commands::FetchCommand.new.fetch_fonts(
+          manifest_path: options[:manifest],
+          only_label: options[:label],
+          allow_proprietary: options[:allow_proprietary],
+          dry_run: options[:dry_run],
+        )
+        puts format_fonts_result(result)
       end
 
       private
@@ -58,6 +88,11 @@ module Ucode
       def format_result(result)
         JSON.pretty_generate(result)
       end
+
+      def format_fonts_result(result)
+        clean = result.merge(results: result[:results].map { |r| r.to_h.compact })
+        JSON.pretty_generate(clean)
+      end
     end
 
     desc "fetch", "Download UCD sources"
@@ -67,7 +102,9 @@ module Ucode
     desc "parse [VERSION]", "Stream UCD → output/"
     option :to, type: :string, default: "./output", desc: "Output directory"
     def parse(version = nil)
-      result = Commands::ParseCommand.new.call(version, output_root: options[:to])
+      result = Commands::ParseCommand.new.call(
+        VersionResolver.resolve(version), output_root: options[:to],
+      )
       puts JSON.pretty_generate(result)
     end
 
@@ -88,7 +125,7 @@ module Ucode
                             desc: "Opt into the experimental v0.1 pipeline"
     def glyphs(version = nil)
       result = Commands::GlyphsCommand.new.call(
-        version,
+        VersionResolver.resolve(version),
         output_root: options[:to],
         block_filter: options[:block],
         force: options[:force],
@@ -127,7 +164,9 @@ module Ucode
       def block(codepoint)
         cp = parse_cp(codepoint)
         with_db_handling do
-          result = Commands::LookupCommand.new.lookup_block(options[:version], codepoint: cp)
+          result = Commands::LookupCommand.new.lookup_block(
+            VersionResolver.resolve(options[:version]), codepoint: cp,
+          )
           puts "#{format("U+%04X", cp)} → #{result.block || "(unassigned)"}"
         end
       end
@@ -137,7 +176,9 @@ module Ucode
       def script(codepoint)
         cp = parse_cp(codepoint)
         with_db_handling do
-          result = Commands::LookupCommand.new.lookup_script(options[:version], codepoint: cp)
+          result = Commands::LookupCommand.new.lookup_script(
+            VersionResolver.resolve(options[:version]), codepoint: cp,
+          )
           puts "#{format("U+%04X", cp)} → #{result.script || "(none)"}"
         end
       end
@@ -149,7 +190,8 @@ module Ucode
         cp = parse_cp(codepoint)
         with_db_handling do
           result = Commands::LookupCommand.new
-            .lookup_char(options[:version], codepoint: cp, output_root: options[:from])
+            .lookup_char(VersionResolver.resolve(options[:version]),
+                         codepoint: cp, output_root: options[:from])
           puts "#{format("U+%04X", cp)} block=#{result.block_id} glyph=#{result.glyph_path}"
         end
       end
@@ -222,50 +264,333 @@ module Ucode
       puts JSON.pretty_generate(result)
     end
 
-    # ─────────────── font-coverage ───────────────
-    desc "font-coverage FONT [FONT...]", "Audit Unicode 17 block coverage for one or more fonts"
-    long_desc <<~LONG
-      Each FONT argument is either a fontist formula name (resolved via
-      `Fontist::Font.find` then `install`) or `label=/path/to/font.ttf`
-      (uses the local file directly). For every font, walks the cmap via
-      fontisan and emits per-Unicode-17-block coverage to
-      `<to>/font_coverage/<label>.json`.
+    # ─────────────── audit ───────────────
+    class Audit < Thor
+      desc "font PATH", "Audit a single font (or fontist formula name)"
+      option :label,       type: :string, default: nil,
+                           desc: "Output directory name (default: postscript_name)"
+      option :unicode_version, type: :string, default: nil
+      option :output,      type: :string,  default: "./output"
+      option :verbose,     type: :boolean, default: false,
+                           desc: "Emit per-codepoint detail chunks"
+      option :with_glyphs, type: :boolean, default: false,
+                           desc: "Emit per-codepoint SVG chunks (no-op until TODO 20)"
+      option :brief,       type: :boolean, default: false,
+                           desc: "Cheap-extractor-only mode"
+      option :browse,      type: :boolean, default: false,
+                           desc: "Also write the self-contained HTML browser"
+      option :no_install,  type: :boolean, default: false,
+                           desc: "Don't auto-install missing fonts via fontist"
+      option :reference_universal_set, type: :string, default: nil,
+                                       desc: "Path to universal-set manifest (or 'none'); " \
+                                 "default: output/universal_glyph_set/manifest.json " \
+                                 "if present, else UCD-only"
+      option :universal_set_root, type: :string, default: nil,
+                                  desc: "Path to universal-set build root (e.g. " \
+                                       "output/universal_glyph_set). Required for " \
+                                       "--with-missing-glyph-pages."
+      option :with_missing_glyph_pages, type: :boolean, default: false,
+                                        desc: "Emit per-block missing-glyph galleries " \
+                                              "(requires --browse + --universal-set-root)"
+      def font(path)
+        reference = Ucode::Audit::ReferenceFactory.build_from_cli(
+          flag: options[:reference_universal_set],
+          version: options[:unicode_version],
+        )
+        result = Commands::Audit::FontCommand.new.call(
+          path,
+          label: options[:label],
+          unicode_version: options[:unicode_version],
+          verbose: options[:verbose],
+          with_glyphs: options[:with_glyphs],
+          brief: options[:brief],
+          output_root: options[:output],
+          browse: options[:browse],
+          install: !options[:no_install],
+          reference: reference,
+          universal_set_root: options[:universal_set_root],
+          with_missing_glyph_pages: options[:with_missing_glyph_pages],
+        )
+        puts JSON.pretty_generate(result_to_h(result))
+      end
+
+      desc "collection PATH", "Audit a TTC/OTC/dfong collection"
+      option :font_index,  type: :numeric, default: nil,
+                           desc: "Audit only face N (single-face output)"
+      option :label,       type: :string,  default: nil
+      option :unicode_version, type: :string, default: nil
+      option :output,      type: :string,  default: "./output"
+      option :verbose,     type: :boolean, default: false
+      option :with_glyphs, type: :boolean, default: false
+      option :brief,       type: :boolean, default: false
+      option :browse,      type: :boolean, default: false
+      option :reference_universal_set, type: :string, default: nil,
+                                       desc: "Path to universal-set manifest (or 'none')"
+      option :universal_set_root, type: :string, default: nil,
+                                  desc: "Path to universal-set build root"
+      option :with_missing_glyph_pages, type: :boolean, default: false,
+                                        desc: "Emit per-block missing-glyph galleries"
+      def collection(path)
+        reference = Ucode::Audit::ReferenceFactory.build_from_cli(
+          flag: options[:reference_universal_set],
+          version: options[:unicode_version],
+        )
+        result = Commands::Audit::CollectionCommand.new.call(
+          path,
+          font_index: options[:font_index],
+          label: options[:label],
+          unicode_version: options[:unicode_version],
+          verbose: options[:verbose],
+          with_glyphs: options[:with_glyphs],
+          brief: options[:brief],
+          output_root: options[:output],
+          browse: options[:browse],
+          reference: reference,
+          universal_set_root: options[:universal_set_root],
+          with_missing_glyph_pages: options[:with_missing_glyph_pages],
+        )
+        puts JSON.pretty_generate(result_to_h(result))
+      end
+
+      desc "library DIR", "Walk a directory of fonts and audit each"
+      option :recursive, type: :boolean, default: false
+      option :unicode_version, type: :string, default: nil
+      option :output,      type: :string,  default: "./output"
+      option :verbose,     type: :boolean, default: false
+      option :with_glyphs, type: :boolean, default: false
+      option :brief,       type: :boolean, default: false
+      option :browse,      type: :boolean, default: false,
+                           desc: "Also write the library + face HTML browsers"
+      option :reference_universal_set, type: :string, default: nil,
+                                       desc: "Path to universal-set manifest (or 'none')"
+      option :universal_set_root, type: :string, default: nil,
+                                  desc: "Path to universal-set build root"
+      option :with_missing_glyph_pages, type: :boolean, default: false,
+                                        desc: "Emit per-block missing-glyph galleries"
+      def library(dir)
+        reference = Ucode::Audit::ReferenceFactory.build_from_cli(
+          flag: options[:reference_universal_set],
+          version: options[:unicode_version],
+        )
+        result = Commands::Audit::LibraryCommand.new.call(
+          dir,
+          recursive: options[:recursive],
+          unicode_version: options[:unicode_version],
+          verbose: options[:verbose],
+          with_glyphs: options[:with_glyphs],
+          brief: options[:brief],
+          output_root: options[:output],
+          browse: options[:browse],
+          reference: reference,
+          universal_set_root: options[:universal_set_root],
+          with_missing_glyph_pages: options[:with_missing_glyph_pages],
+        )
+        puts JSON.pretty_generate(result_to_h(result))
+      end
+
+      desc "compare LEFT RIGHT", "Diff two audits"
+      option :unicode_version, type: :string, default: nil
+      option :output,      type: :string, default: nil,
+                           desc: "Write text diff to file (default: stdout)"
+      def compare(left, right)
+        result = Commands::Audit::CompareCommand.new.call(
+          left, right,
+          unicode_version: options[:unicode_version],
+          output_file: options[:output],
+        )
+        if result.error
+          warn "compare failed: #{result.error}"
+          exit 1
+        elsif options[:output].nil?
+          puts result.text
+        else
+          puts "wrote #{options[:output]}"
+        end
+      end
+
+      desc "browser", "Regenerate HTML browsers from existing JSON audits"
+      option :input,       type: :string,  default: "./output/font_audit"
+      option :faces_only,  type: :boolean, default: false
+      option :library_only, type: :boolean, default: false
+      def browser
+        result = Commands::Audit::BrowserCommand.new.call(
+          input: options[:input],
+          faces_only: options[:faces_only],
+          library_only: options[:library_only],
+        )
+        puts JSON.pretty_generate(result_to_h(result))
+      end
 
-      Examples:
+      private
+
+      def result_to_h(result)
+        return { error: result.error } if result.error
+
+        result.to_h.compact.transform_values do |v|
+          v.is_a?(Struct) ? v.to_h : v
+        end
+      end
+    end
+
+    desc "audit", "Audit font coverage against the Unicode baseline"
+    subcommand "audit", Audit
+
+    # ─────────────── universal-set ───────────────
+    class UniversalSetCmd < Thor
+      desc "build [VERSION]", "Materialize the universal glyph set (one SVG per assigned codepoint)"
+      option :to, type: :string, default: "./output/universal_glyph_set",
+                  desc: "Output directory"
+      option :source_config, type: :string, default: nil,
+                             desc: "Path to a Tier 1 source config YAML " \
+                                   "(default: config/unicode17_universal_glyph_set.yml)"
+      option :block, type: :string, default: nil,
+                     desc: "Limit the build to one block (canonical underscore form)"
+      option :parallel, type: :numeric, default: nil,
+                        desc: "Worker pool size (default: Ucode.configuration.parallel_workers)"
+      def build(version = nil)
+        result = Commands::UniversalSet::BuildCommand.new.call(
+          VersionResolver.resolve(version),
+          output_root: options[:to],
+          source_config_path: options[:source_config],
+          block_filter: options[:block],
+          parallel_workers: options[:parallel] || Ucode.configuration.parallel_workers,
+        )
+        puts JSON.pretty_generate(result)
+      rescue Ucode::UniversalSetPreBuildError => e
+        warn "pre-build validation failed:"
+        warn JSON.pretty_generate(e.context)
+        exit 1
+      end
+
+      desc "pre-check [VERSION]", "Validate source config + fonts + coverage assertion before a build"
+      option :source_config, type: :string, default: nil,
+                             desc: "Path to a Tier 1 source config YAML"
+      def pre_check(version = nil)
+        report = Commands::UniversalSet::PreCheckCommand.new.call(
+          VersionResolver.resolve(version),
+          source_config_path: options[:source_config],
+        )
+        puts JSON.pretty_generate(report.to_h)
+      rescue Ucode::UniversalSetPreBuildError => e
+        warn "pre-build validation failed:"
+        warn JSON.pretty_generate(e.context)
+        exit 1
+      end
+
+      desc "report [VERSION]", "Emit per-tier / per-block / gaps reports from an existing manifest"
+      option :from, type: :string, default: "./output/universal_glyph_set",
+                    desc: "Output directory holding manifest.json"
+      def report(version = nil)
+        result = Commands::UniversalSet::ReportCommand.new.call(
+          VersionResolver.resolve(version),
+          output_root: options[:from],
+        )
+        puts JSON.pretty_generate(result)
+      end
 
-        ucode font-coverage Lentariso=/tmp/lentariso/TTFs/Lentariso-Re.ttf \\
-                             Kedebideri=/tmp/kedebideri/Kedebideri-3.001/Kedebideri-Regular.ttf
+      desc "validate [OUTPUT_ROOT]", "Run post-build structural validation on a manifest + glyphs dir"
+      option :version, type: :string, default: nil,
+                       desc: "Unicode version (stamps the report; defaults to manifest)"
+      def validate(output_root = "./output/universal_glyph_set")
+        result = Commands::UniversalSet::ValidateCommand.new.call(
+          output_root,
+          version: options[:version] && VersionResolver.resolve(options[:version]),
+        )
+        puts JSON.pretty_generate(result)
+        exit 1 unless result[:passed]
+      end
+    end
+
+    desc "universal-set", "Build and inspect the universal glyph set reference"
+    subcommand "universal-set", UniversalSetCmd
 
-        ucode font-coverage Kedebideri  # resolves + installs via fontist
+    # ─────────────── release ───────────────
+    desc "release", "Assemble the fontist.org release tree from per-formula audits"
+    long_desc <<~LONG
+      Walks a directory of per-formula font subdirectories and produces
+      the fontist.org-consumable release tree at
+      `<output>/font_audit_release/`. The release tree contains:
+
+        audit/<slug>/<postscript_name>/  — per-face audit subtrees
+        universal_glyph_set/             — pre-staged universal set
+        library.json                     — formula + face card index
+        manifest.json                    — versions, sha256s, totals
+
+      The universal-set directory is NOT copied by this command; the
+      CI collector is expected to pre-stage it under
+      `<output>/font_audit_release/universal_glyph_set/`.
     LONG
-    option :to, type: :string, default: "./output"
-    option :no_install, type: :boolean, default: false,
-                        desc: "Don't auto-install missing fonts via fontist"
-    def font_coverage(*fonts)
-      raise Thor::Error, "Provide at least one font" if fonts.empty?
+    option :from, type: :string, required: true,
+                  desc: "Directory of per-formula font subdirectories"
+    option :output, type: :string, default: "./output",
+                    desc: "Parent of the release root"
+    option :universal_set, type: :string, default: nil,
+                           desc: "Path to the universal_glyph_set directory " \
+                                 "(default: <release_root>/universal_glyph_set)"
+    option :unicode_version, type: :string, default: nil
+    option :brief, type: :boolean, default: false
+    option :browse, type: :boolean, default: true,
+                    desc: "Also write per-face HTML browsers + missing-glyph pages"
+    option :source_config_sha256, type: :string, default: nil,
+                                  desc: "sha256 of the Tier 1 source-config YAML"
+    option :reference_universal_set, type: :string, default: nil,
+                                     desc: "Path to universal-set manifest (or 'none') " \
+                                           "for the per-face coverage reference"
+    def release
+      reference = Ucode::Audit::ReferenceFactory.build_from_cli(
+        flag: options[:reference_universal_set],
+        version: options[:unicode_version],
+      )
+      result = Commands::ReleaseCommand.new.call(
+        from: options[:from],
+        output_root: options[:output],
+        universal_set_root: options[:universal_set],
+        unicode_version: options[:unicode_version],
+        brief: options[:brief],
+        browse: options[:browse],
+        source_config_sha256: options[:source_config_sha256],
+        reference: reference,
+      )
+      puts JSON.pretty_generate(result_to_h(result))
+    end
 
-      results = Commands::FontCoverageCommand.new.call(
-        fonts,
-        output_root: options[:to],
-        install: !options[:no_install],
+    # ─────────────── block-feed ───────────────
+    desc "block-feed", "Emit per-block Unicode data feed from ucode output"
+    long_desc <<~LONG
+      Translates ucode's canonical output tree into a compact per-block
+      Unicode data feed:
+
+        <target>/unicode-blocks.json
+        <target>/unicode-version.json
+        <target>/unicode/blocks/<slug>.json
+
+      Each per-block file contains the codepoints in that block with
+      their compact metadata (name, general category, script, combining
+      class, bidi class, mirrored flag). Block slugs are derived from
+      the block name via the standard slug algorithm.
+    LONG
+    option :ucode_output, type: :string, default: "./output",
+                          desc: "ucode's output/ directory"
+    option :target, type: :string, default: "./output/block-feed",
+                    desc: "Target directory for emitted files"
+    option :unicode_version, type: :string, default: nil,
+                             desc: "UCD version stamp (default: from manifest)"
+    def block_feed
+      result = Commands::BlockFeedCommand.new.call(
+        ucode_output_root: options[:ucode_output],
+        block_feed_output_root: options[:target],
+        unicode_version: options[:unicode_version],
       )
-      puts JSON.pretty_generate(results.map { |r| result_to_h(r) })
+      puts JSON.pretty_generate(result.to_h)
     end
 
     private
 
     def result_to_h(result)
-      if result.error
-        { spec: result.spec, error: result.error }
-      else
-        {
-          spec: result.spec,
-          label: result.located.name,
-          source: result.located.path.to_s,
-          via: result.located.via,
-          output_path: result.output_path.to_s,
-          complete_blocks: result.complete_blocks,
-        }
+      return { error: result.error } if result.error
+
+      result.to_h.compact.transform_values do |v|
+        v.is_a?(Struct) ? v.to_h : v
       end
     end
   end

data/lib/ucode/commands/audit/browser_command.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "json"
+
+require "ucode/audit"
+require "ucode/audit/browser"
+require "ucode/audit/emitter/paths"
+
+module Ucode
+  module Commands
+    module Audit
+      # `ucode audit browser` — regenerate HTML browsers from existing
+      # JSON audits, without re-running extractors.
+      #
+      # Walks the audit root and rewrites only `.html` files. Useful
+      # when the audit ran without `--browse`, or after a CSS/JS
+      # template tweak. No JSON is rewritten.
+      #
+      # Scopes:
+      #   - default: regenerate both library-level + all face pages.
+      #   - `faces_only: true` — only per-face pages.
+      #   - `library_only: true` — only the library-level page.
+      class BrowserCommand
+        FaceRegen = Struct.new(:label, :path, :written, keyword_init: true)
+
+        Result = Struct.new(:input, :library_html, :faces, :error,
+                            keyword_init: true)
+
+        # @param input [String, Pathname] audit root path. Must be a
+        #   directory containing either `<input>/index.json` (library
+        #   root) or per-face subdirectories each with their own
+        #   `index.json` (face root). Either way the root is treated
+        #   as the library root.
+        # @param faces_only [Boolean]
+        # @param library_only [Boolean]
+        # @return [Result]
+        def call(input:, faces_only: false, library_only: false)
+          audit_root = Pathname.new(input)
+
+          library_html =
+            library_only || !faces_only ? write_library(audit_root) : nil
+          faces =
+            faces_only || !library_only ? write_faces(audit_root) : []
+
+          Result.new(input: audit_root.to_s, library_html: library_html&.to_s,
+                     faces: faces)
+        rescue StandardError => e
+          Result.new(input: input.to_s, error: "#{e.class}: #{e.message}")
+        end
+
+        private
+
+        # The library index.json sits at `<audit_root>/index.json`;
+        # the library index.html is written to the same directory.
+        # {Browser::LibraryPage#write} takes the output_root (one
+        # level up) so we pass `audit_root.parent`.
+        def write_library(audit_root)
+          index_json = audit_root.join("index.json")
+          return nil unless index_json.exist?
+
+          Ucode::Audit::Browser::LibraryPage.new(library_json: index_json.read)
+            .write(audit_root.parent)
+          Ucode::Audit::Emitter::Paths.library_html_path(audit_root.parent)
+        end
+
+        def write_faces(audit_root)
+          audit_root.children.select(&:directory?).filter_map do |face_dir|
+            json = face_dir.join("index.json")
+            next unless json.exist?
+
+            written = Ucode::Audit::Browser::FacePage.new(overview_json: json.read)
+              .write(face_dir)
+            FaceRegen.new(label: face_dir.basename.to_s,
+                          path: face_dir.join("index.html").to_s,
+                          written: written)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ucode/commands/audit/collection_command.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "fontisan"
+
+require "ucode/commands/audit/font_command"
+require "ucode/audit/face_auditor"
+
+module Ucode
+  module Commands
+    module Audit
+      # `ucode audit collection PATH` — explicit collection audit.
+      # Wraps {FontCommand} with two collection-specific behaviors:
+      #
+      #   - Validates the source is actually a collection
+      #     (TTC/OTC/dfong). Errors out otherwise.
+      #   - Supports `font_index:` to audit only one face of the
+      #     collection, producing a single-face tree.
+      #
+      # For unspecified collection options, delegates to FontCommand.
+      class CollectionCommand
+        # @param font_path [String, Pathname] must be a collection source.
+        # @param font_index [Integer, nil] if set, audit only this face.
+        # @param kwargs [Hash] forwarded to {FontCommand#call}.
+        # @return [FontCommand::Result] when auditing all faces, or a
+        #   single-face variant when `font_index:` is set.
+        def call(font_path, font_index: nil, **kwargs)
+          raise CollectionRequiredError, font_path unless collection?(font_path)
+          return audit_single_face(font_path, font_index, kwargs) if font_index
+
+          font_command.call(font_path, **kwargs)
+        end
+
+        private
+
+        def collection?(path)
+          Fontisan::FontLoader.collection?(path.to_s)
+        end
+
+        def audit_single_face(font_path, index, kwargs)
+          output_root = kwargs.fetch(:output_root)
+          options = build_options(kwargs)
+          report = Ucode::Audit::FaceAuditor.new(font_path.to_s, options: options,
+                                                                 mode: mode_from(kwargs),
+                                                                 font_index: index,
+                                                                 reference: kwargs[:reference]).call
+
+          directory = Ucode::Audit::Emitter::FaceDirectory.new(
+            output_root: output_root,
+            verbose: kwargs.fetch(:verbose, false),
+            with_glyphs: kwargs.fetch(:with_glyphs, false),
+            emit_browser: kwargs.fetch(:browse, false),
+            universal_set_root: kwargs[:universal_set_root],
+            with_missing_glyph_pages: kwargs.fetch(:with_missing_glyph_pages, false),
+          )
+
+          label = sanitize(kwargs[:label] || report.postscript_name || "face-#{index}")
+          face_dir = directory.emit_face(label: label, report: report)
+
+          FontCommand::Result.new(
+            spec: font_path.to_s,
+            label: label,
+            output_dir: face_dir.to_s,
+            faces: [FontCommand::FaceOutcome.new(
+              label: label,
+              postscript_name: report.postscript_name,
+              output_dir: face_dir.to_s,
+            )],
+          )
+        end
+
+        def build_options(kwargs)
+          opts = {}
+          opts[:ucd_version] = kwargs[:unicode_version] if kwargs[:unicode_version]
+          opts[:audit_brief] = true if kwargs[:brief]
+          opts
+        end
+
+        def mode_from(kwargs)
+          kwargs[:brief] ? :brief : :full
+        end
+
+        def sanitize(name)
+          (name || "face").to_s.gsub(/[^A-Za-z0-9._-]/, "_")
+        end
+
+        def font_command
+          @font_command ||= FontCommand.new
+        end
+      end
+
+      # Raised by {CollectionCommand} when the input is not a
+      # collection source.
+      class CollectionRequiredError < StandardError
+        # @param path [String, Pathname]
+        def initialize(path)
+          super("#{path} is not a collection (TTC/OTC/dfong) source")
+        end
+      end
+    end
+  end
+end