refactor: rename CLI to Cli and add proper error handling

.github/workflows/release.yml

@@ -24,6 +24,7 @@ jobs:
     uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
     with:
       next_version: ${{ github.event.inputs.next_version }}
+      submodules: true
     secrets:
       rubygems-api-key: ${{ secrets.UNITSML_CI_RUBYGEMS_API_KEY }}
       pat_token: ${{ secrets.UNITSML_CI_PAT_TOKEN }}

.gitmodules

@@ -1,3 +1,4 @@
-[submodule "spec/fixtures/unitsdb"]
-	path = spec/fixtures/unitsdb
-	url = https://github.com/unitsml/unitsdb/
+[submodule "data"]
+	path = data
+	url = https://github.com/unitsml/unitsdb.git
+	branch = refs/tags/v2.0.0

.rubocop.yml

@@ -12,4 +12,4 @@ AllCops:
   NewCops: enable
   Exclude:
     - 'vendor/**/*'
-    - 'spec/fixtures/unitsdb/**/*'
+    - 'data/**/*'

.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-03-27 10:55:21 UTC using RuboCop version 1.86.0.
+# on 2026-04-03 22:15:03 UTC using RuboCop version 1.86.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -11,21 +11,92 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'unitsdb.gemspec'
 
-# Offense count: 1
+# Offense count: 9
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_argument, with_fixed_indentation
+Layout/ArgumentAlignment:
+  Exclude:
+    - 'lib/unitsdb/commands/get.rb'
+    - 'lib/unitsdb/commands/release.rb'
+    - 'lib/unitsdb/commands/search.rb'
+    - 'lib/unitsdb/commands/validate/identifiers.rb'
+    - 'lib/unitsdb/commands/validate/qudt_references.rb'
+    - 'lib/unitsdb/commands/validate/references.rb'
+    - 'lib/unitsdb/commands/validate/si_references.rb'
+    - 'lib/unitsdb/commands/validate/ucum_references.rb'
+    - 'spec/unitsdb/commands/normalize_spec.rb'
+
+# Offense count: 6
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyleAlignWith.
 # SupportedStylesAlignWith: either, start_of_block, start_of_line
 Layout/BlockAlignment:
   Exclude:
     - 'spec/unitsdb/commands/normalize_spec.rb'
+    - 'spec/unitsdb/commands/qudt/update_spec.rb'
+    - 'spec/unitsdb/commands/search_spec.rb'
+    - 'spec/unitsdb/commands/validate/qudt_references_spec.rb'
+    - 'spec/unitsdb/commands/validate/ucum_references_spec.rb'
+
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+Layout/BlockEndNewline:
+  Exclude:
+    - 'spec/unitsdb/commands/normalize_spec.rb'
+    - 'spec/unitsdb/commands/qudt/update_spec.rb'
+    - 'spec/unitsdb/commands/search_spec.rb'
+    - 'spec/unitsdb/commands/validate/qudt_references_spec.rb'
+    - 'spec/unitsdb/commands/validate/ucum_references_spec.rb'
+
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/HashAlignment:
+  Exclude:
+    - 'lib/unitsdb/cli.rb'
+    - 'lib/unitsdb/commands/_modify.rb'
+    - 'lib/unitsdb/commands/qudt.rb'
+    - 'lib/unitsdb/commands/ucum.rb'
+    - 'lib/unitsdb/commands/validate.rb'
+
+# Offense count: 10
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
+# SupportedStylesAlignWith: start_of_line, relative_to_receiver
+Layout/IndentationWidth:
+  Exclude:
+    - 'spec/unitsdb/commands/normalize_spec.rb'
+    - 'spec/unitsdb/commands/qudt/update_spec.rb'
+    - 'spec/unitsdb/commands/search_spec.rb'
+    - 'spec/unitsdb/commands/validate/qudt_references_spec.rb'
+    - 'spec/unitsdb/commands/validate/ucum_references_spec.rb'
 
-# Offense count: 373
+# Offense count: 393
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
+# Offense count: 9
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'lib/unitsdb/commands/get.rb'
+    - 'lib/unitsdb/commands/release.rb'
+    - 'lib/unitsdb/commands/search.rb'
+    - 'lib/unitsdb/commands/validate/identifiers.rb'
+    - 'lib/unitsdb/commands/validate/qudt_references.rb'
+    - 'lib/unitsdb/commands/validate/references.rb'
+    - 'lib/unitsdb/commands/validate/si_references.rb'
+    - 'lib/unitsdb/commands/validate/ucum_references.rb'
+    - 'spec/unitsdb/commands/normalize_spec.rb'
+
 # Offense count: 9
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
@@ -35,7 +106,7 @@ Lint/DuplicateBranch:
     - 'lib/unitsdb/commands/ucum/matcher.rb'
     - 'lib/unitsdb/database.rb'
 
-# Offense count: 83
+# Offense count: 82
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -110,12 +181,12 @@ RSpec/DescribeClass:
     - 'spec/exe/unitsdb_spec.rb'
     - 'spec/unitsdb/version_compatibility_spec.rb'
 
-# Offense count: 30
+# Offense count: 43
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 30
 
-# Offense count: 26
+# Offense count: 22
 RSpec/ExpectOutput:
   Exclude:
     - 'spec/unitsdb/commands/check_si_command_spec.rb'
@@ -137,13 +208,13 @@ RSpec/LeakyLocalVariable:
     - 'spec/unitsdb/unit_systems_spec.rb'
     - 'spec/unitsdb/units_spec.rb'
 
-# Offense count: 7
+# Offense count: 6
 # Configuration parameters: .
 # SupportedStyles: have_received, receive
 RSpec/MessageSpies:
   EnforcedStyle: receive
 
-# Offense count: 45
+# Offense count: 52
 RSpec/MultipleExpectations:
   Max: 15
 
@@ -157,6 +228,19 @@ RSpec/MultipleMemoizedHelpers:
 RSpec/NestedGroups:
   Max: 4
 
+# Offense count: 2
+RSpec/RepeatedExample:
+  Exclude:
+    - 'spec/exe/unitsdb_spec.rb'
+
+# Offense count: 1
+# Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
+# SupportedInflectors: default, active_support
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - '**/spec/routing/**/*'
+    - 'spec/unitsdb/bundled_data_spec.rb'
+
 # Offense count: 17
 # Configuration parameters: IgnoreNameless, IgnoreSymbolicNames.
 RSpec/VerifiedDoubles:
@@ -165,6 +249,21 @@ RSpec/VerifiedDoubles:
     - 'spec/unitsdb/commands/validate/references_spec.rb'
     - 'spec/unitsdb/commands/validate/ucum_references_spec.rb'
 
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# AllowedMethods: lambda, proc, it
+Style/BlockDelimiters:
+  Exclude:
+    - 'spec/unitsdb/commands/normalize_spec.rb'
+    - 'spec/unitsdb/commands/qudt/update_spec.rb'
+    - 'spec/unitsdb/commands/search_spec.rb'
+    - 'spec/unitsdb/commands/validate/qudt_references_spec.rb'
+    - 'spec/unitsdb/commands/validate/ucum_references_spec.rb'
+
 # Offense count: 1
 # This cop supports unsafe autocorrection (--autocorrect-all).
 Style/CombinableLoops:
@@ -177,6 +276,15 @@ Style/IdenticalConditionalBranches:
   Exclude:
     - 'lib/unitsdb/commands/check_si/si_formatter.rb'
 
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: EnforcedStyle, AllowedMethods, AllowedPatterns.
+# SupportedStyles: predicate, comparison
+Style/NumericPredicate:
+  Exclude:
+    - 'spec/**/*'
+    - 'exe/unitsdb'
+
 # Offense count: 14
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: respond_to_missing?

CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+```bash
+bundle install          # Install dependencies
+bundle exec rake        # Run full default task (rspec + rubocop)
+bundle exec rspec       # Run all tests
+bundle exec rspec spec/path/to/file_spec.rb  # Run single spec
+bundle exec rubocop     # Lint all files
+bundle exec rake build  # Build the gem
+```
+
+## Architecture
+
+### Bundled Data
+
+The gem ships UnitsDB YAML data files in `data/` (a git submodule at https://github.com/unitsml/unitsdb). These are included in the published gem via `spec.files += Dir.glob("data/**/*.yaml")` in the gemspec.
+
+Two entry points for the bundled data:
+- `Unitsdb.data_dir` — path to the `data/` directory inside the gem
+- `Unitsdb.database` — pre-loaded `Database.from_db(data_dir)` instance (cached)
+
+The correspondence between gem version and data version is tracked via
+`Unitsdb::UNITS_DATA_VERSION` (e.g. `"2.0.0"`). **The UnitsDB data must be
+released (tagged) before the gem can be released with updated data.** When
+releasing with new data: tag the data in `unitsml/unitsdb`, then update
+`.gitmodules` (`branch = refs/tags/new-data-tag`) and bump both `VERSION` and
+`UNITS_DATA_VERSION` in `lib/unitsdb/version.rb`.
+
+### Core Classes
+
+- **`Unitsdb::Database`** — Loads all YAML files, provides `search`, `get_by_id`, `find_by_type`, `find_by_symbol`, `match_entities`, `validate_uniqueness`, `validate_references`
+- **`Unitsdb::Cli`** (Thor-based) — Command-line interface with subcommands: `validate`, `search`, `get`, `check_si`, `ucum`, `qudt`, `_modify`, `release`
+- **`lib/unitsdb/commands/base.rb`** — Base class for commands; provides `load_database` and `@options[:database]`
+
+### Model Pattern
+
+Entity types (Unit, Prefix, Dimension, Quantity, UnitSystem, etc.) are Lutaml::Model-serializable classes. They are loaded from YAML via `Database.from_db`, which validates `schema_version: "2.0.0"` across all files and merges them into a single object.
+
+### Workflow Files
+
+Workflows in `.github/workflows/` are auto-generated by **Cimas** (metanorma/cimas) and delegate to shared reusable workflows in `metanorma/ci`:
+- `rake.yml` → `generic-rake.yml@main` — runs tests/lint on push/PR
+- `release.yml` → `rubygems-release.yml@main` — builds and publishes gem
+- `dependent-gems.yml` → `dependent-rake.yml@main` — tests downstream consumers
+
+### Git Submodule
+
+`data/` is a git submodule pinned to a specific tag in https://github.com/unitsml/unitsdb
+(e.g. `branch = refs/tags/v2.0.0` in `.gitmodules`). The CI `rake.yml` uses
+`submodules: 'recursive'` so tests have the data available. The release workflow
+uses `submodules: true` to initialize the submodule during checkout.