lutaml-jsonschema 0.1.22 → 0.1.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9249e848f66c41b3894e4051e14e53bf7ddfa45201fa058621003aa6c4eef9c
-  data.tar.gz: 79fbafbb8fee29c7672181288992e9983a98fc8745978a2a40e0eeb5bfa0e10b
+  metadata.gz: 229f1667cd05ad90ee3f424ebc68ae1720ec3219eeec3584a1f65d76f09cf90c
+  data.tar.gz: 224e628bec6fe5d06986a0dbdee00cb5946b8d39b00e1baa4c3777503db4fbb2
 SHA512:
-  metadata.gz: 84ac86a22b2ba9a854a309d708a1ee9cce58128dc6dbd5cc467031363a10f69be49ff550bc12bae9c90f4571c56f05c60b10d92f867911826187d3c6b21adbb5
-  data.tar.gz: b9a35d6e0b71a3d4e8feb8229e963d3a185829643cbf9d5eaf8b248e30221d88332c7a120dd8ddc1ff41fdc1f84a44c7250fb76732cc315b5bc691b2925159c2
+  metadata.gz: 2602ab20233317d4d1ae319739dbc98b86a92598d5decb13a6f5e4e5c3bd0398b69c53698d16c35426599ccd029b565c7a3ceda8546b837d6030d471bcae2c13
+  data.tar.gz: f647240a0ce3da5e729da26cbe79e71e02ae3a17bd16b58c71e80bff88711cb8e34d81787caad00522c6494c2ca90c0c0b59966c252f6d96e56e550be6cf355b

data/CLAUDE.md

@@ -0,0 +1,59 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`lutaml-jsonschema` parses JSON Schema documents into lutaml-model objects and generates a single-file SPA documentation site from them. It has two halves that must stay in sync:
+
+1. **Ruby gem** (`lib/lutaml/jsonschema/`) — the JSON Schema model and documentation generator.
+2. **Vue 3 frontend** (`frontend/`) — the SPA itself. The built bundle (`frontend/dist/app.iife.js` + `style.css`) gets inlined into a standalone `index.html`.
+
+## Commands
+
+```sh
+bundle exec rspec                          # full suite
+bundle exec rspec spec/lutaml/cli_spec.rb  # one file
+bundle exec rspec spec/lutaml/cli_spec.rb:76  # one example
+bundle exec rubocop                        # lint (-a to autofix; .rubocop_todo.yml holds baselined offenses)
+bundle exec rake                           # spec + rubocop (what CI runs)
+
+bundle exec rake frontend:build            # npm install + vite build → frontend/dist
+cd frontend && npm test                    # vitest (frontend unit tests)
+
+bundle exec exe/lutaml-jsonschema spa SCHEMA_FILES... [--diff BASELINE...]
+bundle exec exe/lutaml-jsonschema combine|validate SCHEMA_FILES...
+bundle exec exe/lutaml-jsonschema export SCHEMA_FILES... -f cddl|openapi|xsd|adoc
+bundle exec exe/lutaml-jsonschema diff OLD NEW [--format json]
+```
+
+`frontend/dist/` and `Gemfile.lock` are gitignored. `frontend/dist/` must exist (run `rake frontend:build`) for the `spa` command and for packaging — the gemspec ships it via `Dir.glob("frontend/dist/*")`.
+
+## Architecture
+
+Data flow: schema files → `SchemaSet.load_from_files` → `Spa::SpaBuilder` → `Spa::SpaDocument` → `to_json` → `Spa::VueInlinedStrategy` (embeds `window.SCHEMA_DATA` + inlined JS/CSS into `index.html`).
+
+- **`Base`** — everything inherits from `Lutaml::Model::Serializable`. `Base` also forward-declares `Schema` to break the circular `Schema ↔ PropertyEntry ↔ Link` references.
+- **`Schema`** — the central model of a JSON Schema document. Every `$`-prefixed keyword is a `dollar_`-prefixed attribute (`$schema` → `dollar_schema`) via json mappings. `Schema.from_json` / `to_json` are lutaml-model serialization.
+- **`SchemaSet`** — in-memory named collection of schemas plus `$ref` resolution (local `#/...` pointers and relative `./file.json` refs through `ReferenceResolver`) and validation.
+- **`SchemaStore`** — `SchemaSet` subclass that adds on-disk persistence through **lutaml-store** (`PackageStore`, package shape from `LjrPackageDefinition`).
+- **`Combiner`** — compatibility facade; bundling lives in `SchemaSet#bundle` (hoists definitions, adds a top-level `$ref` property per source schema, rewrites `#/definitions/` → `#/$defs/`).
+- **`Spa::*`** — `SpaBuilder` flattens a `SchemaSet` into a `SpaDocument` (metadata, `SpaSchema` list, flat `search_index` for FlexSearch). `Spa::Generator` renders through an `OutputStrategy`; `VueInlinedStrategy` is the only implementation.
+- **`Configuration`** — YAML config for the SPA (title, theme, appearance…), loaded by `Cli#spa -c`.
+- **`Cli`** — Thor commands: `spa` (generate docs; `--diff` embeds a classified change set), `combine` (merge schemas), `export` (cddl/openapi/xsd/adoc), `diff` (exits 1 on breaking changes), `validate` (meta-schema checks), `version`.
+- **`TupleItem`** — schema-or-boolean wrapper used by `items`/`prefixItems` arrays and composition collections; models that accept `true`/`false` store booleans in companion `*_boolean` attributes and expose `*_value` helpers.
+
+## JSON engine: yeptris
+
+Two distinct paths, both engine-backed:
+
+- **Direct parsing** in this gem (`Cli#combine`, `Cli#validate`, `Schema.serialize_additional_properties`) uses `Yeptris::JSON.load` — strict RFC 8259, exact-`JSON.parse` semantics, raises `Yeptris::JSON::ParseError`. JSON **generation** stays on the stdlib `json` gem (`JSON.pretty_generate`); yeptris's JSON surface is load-only.
+- **Model serialization** (`Schema.from_json`/`to_json`, `Configuration.from_yaml`, lutaml-store I/O) goes through lutaml-model, whose `AdapterResolver` auto-detects yeptris from the bundle and routes both `:json` and `:yaml` to its `YeptrisAdapter`. That adapter re-raises parse failures as `JSON::ParserError`, so error handling must cover **both** exception types — see the rescue in `Cli#validate`.
+- Raw-parse speed depends on the resolved yeptris build shipping a **native materializer for the running Ruby version**; without one it falls back to a pure-Ruby tape engine that is several times slower than `JSON.parse` on large documents (yeptris-ruby#278). Check with `defined?(Yeptris::Native)` (0.6.28.x shipped only Ruby 3.3; 3.4-native starts at 0.6.29.1).
+- The GC-pressure SIGSEGV in the native JSON materializer (yeptris-ruby#279) is fixed in the yeptris **0.6.34 line** (staged pairs made GC-visible); the gemspec floors at `~> 0.6.34`, excluding the crashy 0.6.29.x–0.6.33.x native builds. Env-gated canary: yeptris-ruby#280.
+
+## Repo notes
+
+- `README.md` is unreplaced gem-template boilerplate — don't treat it as documentation.
+- `TODO.redoc/`, `TODO.refactor/`, `TODO.store/` are untracked, numbered working notes (known gaps and planned refactors), not code. `TODO.sota/` holds the SOTA program (purpose, per-area tasks with done-when criteria, and the goal prompt).
+- CI is metanorma/ci's `generic-rake` workflow; releases run through `.github/workflows/release.yml`.

data/Rakefile

@@ -9,7 +9,17 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+task default: %i[spec rubocop perf]
+
+namespace :perf do
+  desc "Pipeline performance harness with regression caps (TODO.sota/08)"
+  task :profile do
+    ruby "benchmark/pipeline_profile.rb"
+  end
+end
+
+desc "Run the pipeline performance regression gate"
+task perf: "perf:profile"
 
 namespace :frontend do
   desc "Build the Vue frontend"
@@ -19,6 +29,11 @@ namespace :frontend do
       sh "npm run build"
     end
   end
+
+  desc "axe-core accessibility audit of the generated SPA (needs Chrome)"
+  task :audit do
+    ruby "script/axe_audit"
+  end
 end
 
 task :build_frontend do

data/benchmark/pipeline_profile.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# Pipeline performance harness (TODO.sota/08).
+#
+# Measures the two budgeted paths on the real-world heroku.json fixture:
+#   - Schema.from_json (model construction)
+#   - end-to-end SPA generation (SchemaSet + SpaBuilder + inlined HTML)
+#
+# Metrics are reported both absolutely and as a ratio to a stdlib
+# JSON.parse of the same document. The ratio is the machine-independent
+# signal: CI runners vary wildly in absolute speed, but the C parser is
+# a stable per-machine yardstick. Regression caps apply to the ratio.
+#
+# Usage: bundle exec ruby benchmark/pipeline_profile.rb [runs]
+
+require "benchmark"
+require "json"
+require "lutaml/jsonschema"
+require "tmpdir"
+
+FIXTURES = Dir[File.expand_path("../spec/fixtures/*.json", __dir__)]
+HEROKU = File.expand_path("../spec/fixtures/heroku.json", __dir__)
+DATA = File.read(HEROKU)
+RUNS = (ARGV[0] || 3).to_i
+
+# Regression caps, calibrated per environment: the ratio looked
+# machine-independent but is not — CI runners (2 vCPU, shared) inflate the
+# Ruby-vs-C balance ~2x versus a local M-series machine (first real CI run:
+# from_json 5901x, e2e 7853x, suite itself green). Caps catch real
+# regressions (1.3x+ of the environment's own baseline) without flaking.
+# Aspirational budgets are printed separately.
+IN_CI = ["true", "1"].include?(ENV.fetch("CI", nil))
+CAP_FROM_JSON_RATIO, CAP_E2E_RATIO =
+  if IN_CI
+    [7_500, 10_000]
+  else
+    [2_600, 5_000]
+  end
+
+def median(values)
+  values.sort[values.length / 2]
+end
+
+def measure(runs, &)
+  Array.new(runs) { Benchmark.realtime(&) }
+end
+
+Schema = Lutaml::Jsonschema::Schema
+
+# Warmup
+Schema.from_json(DATA)
+JSON.parse(DATA)
+
+parse_times = measure(RUNS) { JSON.parse(DATA) }
+from_json_times = measure(RUNS) { Schema.from_json(DATA) }
+
+tmp = Dir.mktmpdir
+frontend_built = File.exist?(
+  File.join(Lutaml::Jsonschema::Spa::VueInlinedStrategy::FRONTEND_DIST,
+            "app.iife.js"),
+)
+generate = lambda do
+  set = Lutaml::Jsonschema::SchemaSet.load_from_files(*FIXTURES)
+  Lutaml::Jsonschema::Spa::Generator.new(set, tmp).generate
+end
+if frontend_built
+  generate.call
+  e2e_times = measure(RUNS) { generate.call }
+else
+  e2e_times = nil
+end
+
+parse_ms = median(parse_times) * 1000
+from_json_ms = median(from_json_times) * 1000
+e2e_ms = e2e_times && (median(e2e_times) * 1000)
+
+from_json_ratio = from_json_ms / parse_ms
+e2e_ratio = e2e_ms && (e2e_ms / parse_ms)
+
+per_100kb = from_json_ms / (DATA.bytesize / 100_000.0)
+html_bytes = if e2e_ms
+               File.size(File.join(tmp, "index.html"))
+             end
+
+puts "heroku.json: #{DATA.bytesize} bytes, #{FIXTURES.length} fixtures, " \
+     "runs=#{RUNS}"
+puts format("JSON.parse (reference):   %<ms>10.3f ms", ms: parse_ms)
+puts format("Schema.from_json:         %<ms>10.3f ms  " \
+            "(%<per>0f ms/100KB, %<ref>0fx ref)",
+            ms: from_json_ms, per: per_100kb, ref: from_json_ratio)
+if e2e_ms
+  puts format("e2e spa generate:         %<ms>10.3f ms  (%<ref>0fx ref)",
+              ms: e2e_ms, ref: e2e_ratio)
+  puts format("index.html:               %<bytes>10d bytes " \
+              "(%<ratio>0.2fx input)",
+              bytes: html_bytes, ratio: html_bytes.to_f / DATA.bytesize)
+else
+  puts "e2e spa generate:         skipped (frontend/dist not built)"
+end
+puts
+puts "environment: #{IN_CI ? 'CI' : 'local'}"
+puts "budgets (aspirational): from_json <= #{DATA.bytesize / 1000} ms " \
+     "(100 ms/100KB), e2e <= 1 s/MB"
+puts "regression caps:        from_json ratio <= #{CAP_FROM_JSON_RATIO}, " \
+     "e2e ratio <= #{CAP_E2E_RATIO}"
+
+failures = []
+failures << "from_json ratio #{from_json_ratio.round} > #{CAP_FROM_JSON_RATIO}" \
+  if from_json_ratio > CAP_FROM_JSON_RATIO
+failures << "e2e ratio #{e2e_ratio.round} > #{CAP_E2E_RATIO}" \
+  if e2e_ratio && e2e_ratio > CAP_E2E_RATIO
+
+if failures.empty?
+  puts "PERF OK"
+else
+  warn "PERF REGRESSION: #{failures.join('; ')}"
+  exit 1
+end