ucode 0.1.1 → 0.2.1

data/TODO.extract-code-chart/07-codechart-cli.md

@@ -0,0 +1,135 @@
+# TODO 07 — CodeChart CLI
+
+## Status
+
+Pending. Depends on TODO 06 (Writer), TODO 04 (Extractor),
+TODO 02 (block name resolver).
+
+## Goal
+
+`ucode code-chart fetch | extract | list` — the REQ (R4) commands.
+Thin Thor wrappers that delegate to the existing `CodeChart::*`
+modules. No orchestration logic in the CLI; every command is a
+single delegation.
+
+## Files
+
+- `lib/ucode/cli.rb` — add the `CodeChartCmd` Thor subcommand class.
+- `spec/ucode/cli_spec.rb` (extend existing) — verify the new
+  subcommand wires up.
+
+## Design
+
+### Subcommand shape
+
+```ruby
+class Cli < Thor
+  # …existing commands…
+
+  class CodeChartCmd < Thor
+    desc "fetch --block BLOCK", "Download the Code Charts PDF for a block"
+    option :block, type: :string, required: true,
+                  desc: "Block identifier (e.g. Sidetic)"
+    def fetch
+      puts JSON.pretty_generate(
+        Commands::FetchCommand.new.fetch_charts(
+          VersionResolver.resolve(nil),
+          block_first_cps: [block_first_cp!(options[:block])],
+        ),
+      )
+    end
+
+    desc "extract --block BLOCK --to DIR", "Extract per-codepoint SVG + provenance sidecars"
+    option :block, type: :string, required: true,
+                  desc: "Block identifier (e.g. Sidetic)"
+    option :to, type: :string, required: true,
+                desc: "Output directory"
+    def extract
+      # ...
+    end
+
+    desc "list", "List blocks that have Code Charts PDFs available locally"
+    def list
+      # ...
+    end
+  end
+
+  desc "code-chart", "Extract per-codepoint SVG glyphs from Unicode Code Charts PDFs"
+  subcommand "code-chart", CodeChartCmd
+end
+```
+
+### `extract` flow
+
+```ruby
+def extract
+  Ucode::Commands::FetchCommand.new.fetch_charts(
+    VersionResolver.resolve(nil),
+    block_first_cps: [block_first_cp!(options[:block])],
+  )
+  blocks_txt = Ucode::Cache.ucd_dir(VersionResolver.resolve(nil)).join("Blocks.txt")
+  block = Parsers::Blocks.find_by_name(blocks_txt, options[:block]) or
+    raise Thor::Error, "Unknown block: #{options[:block].inspect}"
+  pdf = Ucode::Glyphs::PdfFetcher.new(
+    VersionResolver.resolve(nil),
+    monolith_path: nil,
+    blocks: [block],
+  ).fetch(block_first_cp: block.range_first, force: false) or
+    raise Thor::Error, "PDF unavailable for block #{options[:block]}"
+
+  writer = Ucode::CodeChart::Writer.new(
+    output_root: Pathname.new(options[:to]),
+    pdf_path: pdf,
+    blocks_txt: blocks_txt,
+  )
+  summary = writer.write(block)
+  puts JSON.pretty_generate(summary.to_h.compact)
+end
+
+def block_first_cp!(block_id)
+  cache = Ucode::Cache.ucd_dir(VersionResolver.resolve(nil))
+  block = Ucode::Parsers::Blocks.find_by_name(cache.join("Blocks.txt"), block_id)
+  raise Thor::Error, "Unknown block: #{block_id.inspect}" unless block
+  block.range_first
+end
+```
+
+### Why `Ucode::Commands::FetchCommand.new.fetch_charts` for fetch
+
+`fetch_charts` is the existing CLI hook for "download a Code Charts
+PDF for these block first-cps." We just call it with the block's
+first cp. Reuse, don't reimplement.
+
+### Why resolve version once at the top of `extract`
+
+Per Candidate 4 of the architecture review (`refactor/build-context-resolve-version-once`,
+merged): every CLI method resolves the version once and threads it
+through. This CLI method does the same — one call per invocation.
+
+### Why no separate `Commands::CodeChartCommand` class
+
+Following the existing pattern (e.g. `Cli::Audit` calls
+`Commands::Audit::*Command` *only* when the logic is non-trivial).
+The CodeChart commands are trivial delegations — a one-liner each.
+The CLI methods call `CodeChart::Writer` and `CodeChart::Extractor`
+directly. Adding a `Commands::CodeChartCommand` class would be
+indirection without a payoff.
+
+If the extract logic grows (e.g. progress reporting, partial
+extraction), extract it into a Command class at that point.
+
+## Acceptance
+
+- `ucode code-chart fetch --block Sidetic` downloads the PDF.
+- `ucode code-chart extract --block Sidetic --to /tmp/s/` extracts
+  to the given directory.
+- `ucode code-chart list` prints available blocks.
+- Unknown block names produce a clean error, not a stack trace.
+- The CLI matches the REQ's signature exactly.
+
+## Out of scope
+
+- `--version` flag (the REQ doesn't specify, and existing commands
+  default to the configured version).
+- `--format svg|glif` (the REQ specifies SVG; `.glif` output is a
+  future extension).

data/TODO.extract-code-chart/08-specs.md

@@ -0,0 +1,87 @@
+# TODO 08 — CodeChart specs
+
+## Status
+
+Pending. Depends on TODOs 01–07.
+
+## Goal
+
+Comprehensive spec coverage for every new module. Per the project
+rules: real model instances (no doubles), tight focused tests,
+behavior assertions (not interaction counts).
+
+## Files
+
+Already enumerated per TODO. Final spec coverage:
+
+- `spec/ucode/fetch/code_charts_spec.rb` — happy path + HTTP 4xx +
+  wrong content-type + non-PDF body. (TODO 01)
+- `spec/ucode/parsers/blocks_spec.rb` (extend) — `find_by_name`
+  happy path + nil on miss. (TODO 02)
+- `spec/ucode/code_chart/extractor_spec.rb` — constructor invariants,
+  Resolver wiring, integration test against fixture PDF. (TODO 04)
+- `spec/ucode/code_chart/provenance_spec.rb` — value object
+  construction + `to_h` schema. (TODO 05)
+- `spec/ucode/code_chart/sidecar_spec.rb` — write sidecar, idempotent
+  re-write. (TODO 05)
+- `spec/ucode/code_chart/writer_spec.rb` — full lifecycle:
+  extract → write → summary. Idempotent re-run produces byte-identical
+  files. (TODO 06)
+- `spec/ucode/cli_spec.rb` (extend) — verify `ucode code-chart fetch`,
+  `extract`, `list` wire up. (TODO 07)
+
+## Design
+
+### Fixture strategy
+
+The existing `spec/fixtures/pdfs/basic_latin.pdf` is the only PDF
+fixture in the repo. It's tiny and validates the integration path.
+The Sidetic + Egyptian Ext-B PDFs are large (whole-block) and would
+inflate the repo. The integration spec uses `basic_latin.pdf` to
+exercise the full pipeline; per-codepoint assertions cover
+representative cases.
+
+If Sidetic-specific behavior must be tested, a smaller fixture PDF
+cropped to ~5 codepoints would be the right tool — out of scope for
+this TODO.
+
+### No doubles policy
+
+The project's `~/.claude/CLAUDE.md` rule: no doubles. All specs use
+real instances:
+- `Ucode::Models::Block.new(...)` for test blocks.
+- A temp directory + real `Blocks.txt` text for parser specs.
+- The real `Ucode::Glyphs::Resolver` for extractor specs.
+
+### Idempotency assertion pattern
+
+`Writer#write` idempotency is asserted via byte-equality:
+
+```ruby
+first_run  = writer.write(block)
+first_size = File.stat(svg_path).size
+sleep 0.01  # ensure mtime changes would be detectable
+second_run = writer.write(block)
+second_size = File.stat(svg_path).size
+expect(second_size).to eq(first_size)
+expect(File.read(svg_path)).to eq(expected_svg_bytes)
+```
+
+This is the existing pattern from `spec/ucode/repo/aggregate_writer_spec.rb`
+(idiempotency spec there). Reuse.
+
+## Acceptance
+
+- `bundle exec rspec spec/ucode/code_chart/ spec/ucode/fetch/code_charts_spec.rb spec/ucode/parsers/blocks_spec.rb`
+  passes 100%.
+- Coverage for the new files is ≥ 95% (per the project's per-file
+  floor of 30% + the overall 80% minimum).
+- No doubles are introduced (verify with `grep -r "double(" spec/ucode/code_chart/`).
+- The integration spec exercises both the Extractor and Writer
+  together end-to-end.
+
+## Out of scope
+
+- Performance benchmarks — separate concern.
+- Sidetic-specific fixtures — requires PDF curation beyond the
+  scope of this feature.

data/lib/ucode/audit/reference_factory.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Ucode
+  module Audit
+    # Translates CLI flags into a {Ucode::Audit::CoverageReference}.
+    #
+    # The audit CLI exposes the universal-set reference via a
+    # `--reference-universal-set=<path>` flag (and a default lookup
+    # at `output/universal_glyph_set/manifest.json`). This factory
+    # resolves the flag value into a concrete reference instance
+    # backed by a freshly-opened {Ucode::Database}, so the command
+    # classes don't repeat the same branching.
+    #
+    # Behavior:
+    #
+    # - flag = "none"          → nil (force UCD-only even if a default manifest exists)
+    # - flag = path to .json   → {Ucode::Audit::UniversalSetReference}
+    # - flag = nil             → look at DEFAULT_MANIFEST_PATH; use it if present,
+    #                             else nil (UCD-only)
+    #
+    # Lives in the {Ucode::Audit} namespace (not {Ucode::Commands::Audit})
+    # so the Audit module owns its own entry point — programmatic callers
+    # don't need to round-trip through the CLI to obtain a reference.
+    module ReferenceFactory
+      DEFAULT_MANIFEST_PATH = Pathname.new("output/universal_glyph_set/manifest.json")
+
+      module_function
+
+      # @param flag [String, nil] value of the
+      #   `--reference-universal-set` CLI option.
+      # @param version [String, nil] UCD version for the database
+      #   that backs the reference. When nil, the default UCD
+      #   version is resolved.
+      # @return [Ucode::Audit::CoverageReference, nil]
+      def build_from_cli(flag:, version: nil)
+        return nil if flag == "none"
+
+        path = resolve_manifest_path(flag)
+        return nil unless path && File.exist?(path)
+
+        database = open_database(version)
+        return nil unless database
+
+        Ucode::Audit::UniversalSetReference.new(
+          manifest: path, database: database,
+        )
+      end
+
+      def resolve_manifest_path(flag)
+        return Pathname.new(flag) if flag && flag != "none"
+        return DEFAULT_MANIFEST_PATH if DEFAULT_MANIFEST_PATH.exist?
+
+        nil
+      end
+
+      def open_database(version)
+        resolved = version || Ucode::VersionResolver.resolve(nil)
+        Ucode::Database.open(resolved)
+      rescue Ucode::UnknownVersionError, Ucode::DatabaseMissingError
+        nil
+      end
+    end
+  end
+end

data/lib/ucode/audit.rb

@@ -32,6 +32,7 @@ module Ucode
     autoload :CoverageReference, "ucode/audit/coverage_reference"
     autoload :UcdOnlyReference, "ucode/audit/ucd_only_reference"
     autoload :UniversalSetReference, "ucode/audit/universal_set_reference"
+    autoload :ReferenceFactory, "ucode/audit/reference_factory"
 
     # Per-face orchestrator (TODO 11) — shared by LibraryAuditor and
     # the future CLI AuditCommand.

data/lib/ucode/cli.rb

@@ -3,6 +3,8 @@
 require "thor"
 
 require "ucode/commands"
+require "ucode/code_chart"
+require "ucode/version_resolver"
 
 module Ucode
   # Top-level CLI entry.
@@ -10,6 +12,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 +36,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 +55,8 @@ 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)"
@@ -90,7 +103,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
 
@@ -111,7 +126,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],
@@ -143,6 +158,104 @@ module Ucode
     desc "site", "Generate the Vitepress site"
     subcommand "site", Site
 
+    # ─────────────── code-chart ───────────────
+    # Extract per-codepoint SVG glyphs from a Unicode Code Charts PDF.
+    # One folder per block under --to, with <U+XXXX>.svg + .json pairs.
+    class CodeChartCmd < Thor
+      desc "fetch --block BLOCK [VERSION]", "Download the Code Charts PDF for a block"
+      option :block, type: :string, required: true,
+                    desc: "Block identifier (e.g. Sidetic, Basic_Latin)"
+      def fetch(version = nil)
+        with_codechart_errors do
+          block_first_cp = resolve_block_first_cp!(options[:block], version)
+          result = Commands::FetchCommand.new.fetch_charts(
+            VersionResolver.resolve(version),
+            block_first_cps: [block_first_cp],
+          )
+          puts JSON.pretty_generate(result)
+        end
+      end
+
+      desc "extract --block BLOCK --to DIR [VERSION]",
+           "Extract per-codepoint SVG + provenance sidecars from a Code Charts PDF"
+      option :block, type: :string, required: true,
+                    desc: "Block identifier (e.g. Sidetic)"
+      option :to, type: :string, required: true,
+                  desc: "Output directory (will contain <block_id>/<U+XXXX>.svg + .json)"
+      def extract(version = nil)
+        with_codechart_errors do
+          version_str = VersionResolver.resolve(version)
+          block = resolve_block!(options[:block], version_str)
+          block_first_cp = block.range_first
+
+          # Download (idempotent — re-runs skip when the PDF is cached).
+          Commands::FetchCommand.new.fetch_charts(version_str, block_first_cps: [block_first_cp])
+
+          pdf = Ucode::Glyphs::PdfFetcher.new(version_str)
+            .fetch(block_first_cp: block_first_cp)
+          raise Ucode::CodeChartNotFoundError.new(
+            "Code Charts PDF unavailable for block #{block.id.inspect}",
+            context: { block_id: block.id, version: version_str },
+          ) unless pdf
+
+          writer = Ucode::CodeChart::Writer.new(
+            output_root: Pathname.new(options[:to]),
+            pdf_path: pdf,
+            ucd_version: version_str,
+          )
+          summary = writer.write(block)
+          puts JSON.pretty_generate(summary.to_h.compact)
+        end
+      end
+
+      desc "list", "List cached Code Charts PDFs under the version's cache"
+      def list
+        version = VersionResolver.resolve(nil)
+        pdfs_dir = Ucode::Cache.pdfs_dir(version)
+        files = pdfs_dir.exist? ? pdfs_dir.children.sort : []
+        if files.empty?
+          puts "(no cached Code Charts PDFs)"
+          return
+        end
+        files.each do |f|
+          puts f.basename.to_s
+        end
+      end
+
+      private
+
+      # Resolve a block name to its first codepoint via the cached
+      # Blocks.txt. Raises {Ucode::UnknownBlockError} on miss.
+      def resolve_block!(block_id, version)
+        blocks_txt = Ucode::Cache.ucd_dir(VersionResolver.resolve(version)).join("Blocks.txt")
+        Ucode::Parsers::Blocks.find_by_id!(blocks_txt, block_id)
+      end
+
+      def resolve_block_first_cp!(block_id, version)
+        resolve_block!(block_id, version).range_first
+      end
+
+      # Convert semantic Ucode errors into Thor errors so Thor's
+      # dispatch prints the message cleanly instead of a stack trace.
+      # Thor's `start` rescues only `Thor::Error`; without this bridge,
+      # any `Ucode::Error` subclass propagates as an uncaught exception.
+      def with_codechart_errors
+        yield
+      rescue Ucode::Error => e
+        raise Thor::Error, e.message
+      end
+    end
+
+    # Register the subcommand under the underscored method name
+    # (`code_chart`). Thor's `normalize_command_name` converts the
+    # user's hyphenated form (`code-chart`) to the underscored form
+    # before lookup, so `ucode code-chart <cmd>` dispatches correctly.
+    # `desc` first registers the method as a Thor command so the
+    # dispatch table has an entry; `subcommand` then attaches the
+    # CodeChartCmd class to it.
+    desc "code_chart <command>", "Extract SVG glyphs from Unicode Code Charts PDFs"
+    subcommand "code_chart", CodeChartCmd
+
     # ─────────────── lookup ───────────────
     class Lookup < Thor
       desc "block CODEPOINT", "Block name covering CODEPOINT (integer or 0xNNNN)"
@@ -150,7 +263,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
@@ -160,7 +275,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
@@ -172,7 +289,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
@@ -274,7 +392,7 @@ module Ucode
                                         desc: "Emit per-block missing-glyph galleries " \
                                               "(requires --browse + --universal-set-root)"
       def font(path)
-        reference = Commands::Audit::ReferenceBuilder.build(
+        reference = Ucode::Audit::ReferenceFactory.build_from_cli(
           flag: options[:reference_universal_set],
           version: options[:unicode_version],
         )
@@ -312,7 +430,7 @@ module Ucode
       option :with_missing_glyph_pages, type: :boolean, default: false,
                                         desc: "Emit per-block missing-glyph galleries"
       def collection(path)
-        reference = Commands::Audit::ReferenceBuilder.build(
+        reference = Ucode::Audit::ReferenceFactory.build_from_cli(
           flag: options[:reference_universal_set],
           version: options[:unicode_version],
         )
@@ -349,7 +467,7 @@ module Ucode
       option :with_missing_glyph_pages, type: :boolean, default: false,
                                         desc: "Emit per-block missing-glyph galleries"
       def library(dir)
-        reference = Commands::Audit::ReferenceBuilder.build(
+        reference = Ucode::Audit::ReferenceFactory.build_from_cli(
           flag: options[:reference_universal_set],
           version: options[:unicode_version],
         )
@@ -430,7 +548,7 @@ module Ucode
                         desc: "Worker pool size (default: Ucode.configuration.parallel_workers)"
       def build(version = nil)
         result = Commands::UniversalSet::BuildCommand.new.call(
-          version,
+          VersionResolver.resolve(version),
           output_root: options[:to],
           source_config_path: options[:source_config],
           block_filter: options[:block],
@@ -448,7 +566,7 @@ module Ucode
                              desc: "Path to a Tier 1 source config YAML"
       def pre_check(version = nil)
         report = Commands::UniversalSet::PreCheckCommand.new.call(
-          version,
+          VersionResolver.resolve(version),
           source_config_path: options[:source_config],
         )
         puts JSON.pretty_generate(report.to_h)
@@ -463,7 +581,7 @@ module Ucode
                     desc: "Output directory holding manifest.json"
       def report(version = nil)
         result = Commands::UniversalSet::ReportCommand.new.call(
-          version,
+          VersionResolver.resolve(version),
           output_root: options[:from],
         )
         puts JSON.pretty_generate(result)
@@ -475,7 +593,7 @@ module Ucode
       def validate(output_root = "./output/universal_glyph_set")
         result = Commands::UniversalSet::ValidateCommand.new.call(
           output_root,
-          version_intent: options[:version],
+          version: options[:version] && VersionResolver.resolve(options[:version]),
         )
         puts JSON.pretty_generate(result)
         exit 1 unless result[:passed]
@@ -518,7 +636,7 @@ module Ucode
                                      desc: "Path to universal-set manifest (or 'none') " \
                                            "for the per-face coverage reference"
     def release
-      reference = Commands::Audit::ReferenceBuilder.build(
+      reference = Ucode::Audit::ReferenceFactory.build_from_cli(
         flag: options[:reference_universal_set],
         version: options[:unicode_version],
       )