openehr-rails 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49c5536ccdf6abee6fb03aea4a4ed6002fc6402e6551d6f234b0e6a1a7b9200c
-  data.tar.gz: c36b2b1b58f60d22c2cbbbcb5754108bb3235f12737bd573103d2a3463a70618
+  metadata.gz: 065a9ba44f893adaea9e6c0ccf6f3c5f8a0af8c8c3897379cd008e5642e99a7a
+  data.tar.gz: 98f81ad0baf2b086e2193102c25804b3affcd2fa1ffb4c0730952d6a916e3a58
 SHA512:
-  metadata.gz: 0651aa4386933ccff02d230ab06d1eda996ca102da9b99ba2ebf09d3fde233ce7f08cea00b26644b744b92b647f917fe0e80dd6169fa158d9af19759c7db7f1b
-  data.tar.gz: 4358f499a80546004d5ca80b1ec542f2fe2d977a674461be36ee1afb288322717b71507978a50b1f7560edf1248835783f29e60b0bc874f164d8c4141bcc06a8
+  metadata.gz: 42353942db8a02b901e3727a85446fe1995f3c953fd33f3da2dfea68d7018b533de95b97494db856593df77ccbacd8d57f0f4bb4cdcedee086da6c4e44035a04
+  data.tar.gz: 4fd7e793d2d77230e585dcf06204147926d3b36a86a576525614d19395930f80b4fe38bc0b534de5a0f6b26e98e0859d5c8275ce865a1efedf3aa942dc1d272e

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -16,6 +16,9 @@ assignees: ''
 - `openehr` version: <!-- e.g. ~> 2.3 -->
 - Rails version: <!-- e.g. 8.1 -->
 - Ruby version: <!-- e.g. 3.3, 3.4, 4.0 -->
+- If the report involves an OPT/ADL file: the generating tool and its
+  version (e.g. Better Archetype Designer / Ocean Template Designer 2.6 /
+  ADL Workbench / LinkEHR / HMC).
 
 ## Reproduction
 

data/CHANGELOG.md

@@ -7,6 +7,97 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-10
+
+> **Upgrade note.** Regenerate `app/fhir/profiles/*.json`. `Condition.component`
+> slices are gone; anything reading them must move to the mapped elements
+> (`category` slice `ckm`, `code`, `onsetDateTime`, `recordedDate`,
+> `abatementDateTime`, `verificationStatus`), and an entry with no mapping onto
+> a non-`Observation` resource now appears in the generator's `#skipped` list
+> instead of producing a profile.
+
+### Changed
+- **Breaking for consumers of generated FHIR profiles.** `EVALUATION` entries no
+  longer produce `Condition.component` slices, which FHIR R5 `Condition` does not
+  have. Each leaf now maps onto the real `Condition` element that means the same
+  thing — `code` (bound to the leaf's value set), `onsetDateTime`,
+  `recordedDate`, `abatementDateTime`, `verificationStatus` — and the archetype
+  anchor moves from `Condition.code` to a `Condition.category` slice (`ckm`,
+  `1..1`, pattern-discriminated on `$this`, so an instance keeps room for its
+  other categories), since `code` is now the diagnosis itself. `recordedDate`
+  carries an `ElementDefinition.comment` stating that it approximates at0003
+  (date/time clinically recognised). `ProfileGenerator` (JSON) and
+  `FshGenerator` generate from one table in `TypeMap`, so the two outputs cannot
+  disagree. Generated FSH for `problem_list.opt` goes from 29 Sushi errors to 0.
+  Host apps must regenerate cached `app/fhir/profiles/*.json`; anything reading
+  the old `Condition.component` slices must be updated (#33). Currently mapped:
+  `openEHR-EHR-EVALUATION.problem_diagnosis.v1`. A multi-leaf entry mapped to
+  `ServiceRequest`/`Procedure`/`Encounter` without a mapping-table row is now
+  skipped and reported (see Added) instead of producing `component` constraints
+  those resources do not have; its mapping table remains reserved as #35.
+- Value-set canonicals on mapped leaves no longer carry OPT's `terminology:`
+  prefix, in either output.
+
+### Added
+- `ProfileGenerator#skipped` and `FshGenerator#skipped`: the entries left out of
+  `#profiles` / `#to_fsh_files`, each as an
+  `OpenehrRails::Fhir::UnsupportedProfileError` (`archetype_id`,
+  `resource_type`, `leaf_count`) in template order. An entry is skipped when it
+  has more than one leaf, maps to a resource without `component`, and has no row
+  in `TypeMap::ENTRY_ELEMENT_MAPS`; the rest of the template still generates.
+  `rails g openehr:fhir_profile` and `openehr:scaffold --fhir` print each skip
+  (#33).
+
+### Removed
+- `TypeMap.value_element`, dead since it was added — its ternary returned the
+  same string on both branches and nothing called it. Its intended
+  resource-type branch is now the mapping table (#33).
+
+### Fixed
+- `templates/openehr_template.rb` pins `json < 3` in the generated app's
+  `Gemfile`. `json` 3.0 (2026-09-08) changed `JSON.parse`'s arity and
+  `ActiveSupport::JSON.decode` as of activesupport 8.1.3.1 still passes options
+  positionally, so a freshly generated host app failed at `db:seed` on its first
+  json-column write (`ArgumentError: wrong number of arguments (given 2, expected
+  1)`). Temporary: remove once a Rails patch release carries the fix. This
+  repo's own `Gemfile` and `script/build_demo.sh` carry the same dev-only pin.
+- `release:check` now fails when a tag matching the gemspec version exists and
+  `HEAD` is not that tag's commit. `gem.files` comes from `git ls-files`, so a
+  gem built at a later commit ships different bytes under the same version
+  number — the defect that let 0.6.0 be published as a `master`-HEAD build
+  (#34). The check stays silent when the version has no tag yet, so ordinary
+  pre-release development is unaffected.
+
+## [0.6.0] - 2026-08-26
+
+> **Published artifact note.** The gem published to RubyGems for this version
+> was built from `master` HEAD rather than the `v0.6.0` tag, so it contains the
+> tagged tree plus two documentation files added after the tag
+> (`docs/design/multi-leaf-non-observation-plan.md`, and this project's
+> `docs/reports/fsh-generator-log.md` carrying its R6 entry). `lib/` is
+> byte-identical to the tag artifact and version, runtime dependencies and
+> `required_ruby_version` are unchanged, so the published gem is functionally
+> identical to what CI built and verified at the tag; it was accepted rather
+> than yanked. Published sha256
+> `223e3b3897f85c38eaffe7ea39bd7c2acf4c5de9cab7d50fe38f754ff9d65db6`; tag-build
+> sha256 `08cdd14ab1f3890b0c6b5f0ae0d5ca55615f0b4874ed5efb0cd4d7bda9e573ca`.
+> Full measurements: `docs/reports/fsh-generator-log.md` R8. Prevention:
+> `skoba/openehr-rails#34`.
+
+### Added
+- `OpenehrRails::Fhir::FshGenerator` renders one FHIR Shorthand profile per
+  openEHR entry, including metadata, archetype codes, value constraints,
+  component slicing, quantity units, fixed terminology codes, and required
+  external value-set bindings. Observation-mapped output is Sushi-verified;
+  multi-leaf non-Observation entries have a known structural gap tracked as #33.
+
+### Changed
+- `FshGenerator` no longer depends on `active_support/core_ext/string`; the
+  three String helpers it used are now small plain-Ruby private methods,
+  verified byte-identical output. Restores the Rails-independence this class
+  was designed for (see `anlage`'s `docs/design/fsh-plan.md`), so it can move
+  wholesale to a future satellite gem without a Rails dependency riding along.
+
 ## [0.5.0] - 2026-08-25
 
 ### Added

data/CLAUDE.md

@@ -46,6 +46,37 @@ Before tagging, make the final semver determination from the actual content of
 `[Unreleased]`, not from a pre-assigned version number. If the instructed version number
 contradicts the actual content, stop instead of tagging and ask for re-arbitration.
 
+**Publish only the CI artifact itself.** `gem push` takes the `.gem` downloaded
+from the tag's Release run (`gh run download <run-id> -n gem`), after its sha256
+has been compared against the value recorded for that run - never a locally built
+`pkg/*.gem`. `gem.files` comes from `git ls-files`, so a build made at any commit
+other than the tag ships different bytes under the same version number, and a
+stale `pkg/` artifact from unrelated local work is indistinguishable by filename
+from a release build.
+
+(Added 2026-08-27, from the 0.6.0 publish: the gem that reached RubyGems was a
+`master`-HEAD build left in `pkg/` by an unrelated verification run, not the
+CI-verified `v0.6.0` artifact. Accepted rather than yanked - the delta was two
+documentation files and `lib/` was byte-identical - but nothing in the release
+path caught it. Measurements in `docs/reports/fsh-generator-log.md` R8; the
+matching `release:check` guard is `skoba/openehr-rails#34`.)
+
+**Confirm publication by checksum, not by version number.** RubyGems publishes
+the sha256 it recorded at push time (`/api/v1/gems/openehr-rails.json` `sha`, and
+the `checksum:` field in `https://index.rubygems.org/info/openehr-rails`). The
+post-push confirmation compares that value against the sha256 the tag's Release
+run recorded for its artifact - the same value already compared before the push.
+Seeing the version number appear is not the check; it only shows that *a* gem
+landed under that number. (Ported 2026-09-10 from openehr-ruby's 2.4.3 release,
+where CI run, downloaded artifact and published gem all agreed on one sha256.)
+
+**RubyGems API propagation lag.** `/api/v1/versions/openehr-rails.json` can lag
+the push by minutes; do not read the new version's absence there as a failed
+publish, and do not re-push. Confirm with
+`/api/v1/versions/openehr-rails/latest.json`, `/api/v1/gems/openehr-rails.json`,
+or the compact index `https://index.rubygems.org/info/openehr-rails`, which
+updated first in that same 2.4.3 run.
+
 ## Verification
 
 - **Verify against the repo before recording a fact in it**, even when a prompt or an
@@ -102,6 +133,26 @@ lasting effect, but the near-miss is what prompted this generalization. See
 logging the underlying structural fix under consideration - one
 worktree/session per repo instead of per-command vigilance.)
 
+## Cross-repository implementation work needs its own authorization gate
+
+The moment it becomes clear that the actual implementation target for a piece of
+work is a repository other than this one, stop before starting that work and insert
+a gate report confirming the implementation target, rather than sliding from
+read-only cross-repo reference (already permitted for design/evidence-gathering)
+into cross-repo write work on the strength of that same permission. Correctly
+targeting a command once you've decided to cross the boundary (the previous
+section's `cd`/`-C`/`-R` discipline) is a different concern from being authorized to
+cross it at all - following the operational convention precisely does not retroactively
+authorize the crossing.
+
+(Added 2026-08-26, alongside the `#32`/`#33` FSH-generator work continuation, to
+name explicitly a distinction that the existing repository-context rule left
+implicit: it governs *how* to target a cross-repo command correctly, not *whether*
+crossing into implementation work on another repository has actually been
+authorized for the task at hand. A matching line is planned for `anlage`'s own
+`CLAUDE.md` in a later batch - not yet added there as of this entry. Update
+2026-09-04: added there as 絶対規律 item 9.)
+
 ## Project Overview
 
 This is `openehr-rails`, a Rails engine gem that turns an openEHR Operational Template (`.opt`, ADL2/XML) into a working Rails resource in one command: `rails generate openehr:scaffold path/to/template.opt --fhir` emits a model, migration, controller, views, i18n locale, and (with `--fhir`) HL7 FHIR R5 `StructureDefinition` profiles. Generated models persist both as typed columns (for forms/search) and as full openEHR RM data (canonical JSON + a typed node graph with immutable-append versioning), and are queryable via a growing AQL surface. A mountable admin engine (`/openehr`) provides template upload/management, runtime scaffolding, and a FHIR R5 facade. Legacy ADL-archetype-only generators (model/controller/migration/helper/assets/i18n/template/template_model, based on `Openehr::Generators::ArchetypedBase`) have been removed — OPT is the only supported input format for scaffolding.
@@ -181,4 +232,4 @@ This is `openehr-rails`, a Rails engine gem that turns an openEHR Operational Te
 - Guard setup available for TDD workflow
 - RuboCop Rails linting configured
 - SimpleCov for test coverage
-- `openehr` gem dependency; see the gem's own README/CHANGELOG for OPT-parser and AQL-engine capabilities and known gaps before relying on either.
+- `openehr` gem dependency; see the gem's own README/CHANGELOG for OPT-parser and AQL-engine capabilities and known gaps before relying on either.

data/Gemfile

@@ -1,3 +1,10 @@
 source 'https://rubygems.org'
 
 gemspec
+
+# json 3.0 (released 2026-09-09) changed JSON.parse's arity; ActiveSupport::JSON.decode
+# as of activesupport 8.1.3.1 still passes its options positionally, so reading any
+# json column raises ArgumentError (wrong number of arguments (given 2, expected 1)).
+# Dev/test-only pin -- the gemspec is untouched, host apps resolve their own json.
+# Drop once a Rails patch release carries the fix (docs/backlog.md, "Dependencies").
+gem 'json', '< 3'

data/docs/backlog.md

@@ -34,6 +34,23 @@ actually running, not just present:
   push will reproduce the same red run. See "Release automation" below.
 - Most recent `master` push at the time of this record (`4055ec3`): CI run
   `32569774700`, success.
+- **Tag `v0.5.0` (2026-08-25, #30): `release.yml` run
+  [32831263811](https://github.com/skoba/openehr-rails/actions/runs/32831263811) --
+  overall conclusion **success**, all 12 jobs green (9 reused `ci.yml` spec-matrix
+  jobs, `demo smoke`, `application template smoke test`, `Build gem artifact`).**
+  First fully-green tag-push run on record -- confirms the "Release automation fix
+  landed (2026-08-23, PR #28)" note below actually fixed the structural red
+  described above, not just that the workflow file changed (`v0.4.1`/`v0.4.0`/`v0.3.0`
+  were all red at the now-removed RubyGems-publish step; `v0.5.0` has no such step to
+  fail at). Downloaded the run's `gem` artifact and independently built
+  `pkg/openehr-rails-0.5.0.gem` locally at the same tagged commit (`69db63f`): both
+  197632 bytes, identical sha256
+  `e07815bd1c86736403cbb558fec869fbe04666f695e6cc12a41dad9be77230e6`. RubyGems
+  publish (human `gem push`, per "Release automation" below) confirmed complete via
+  `https://rubygems.org/api/v1/versions/openehr-rails.json`: version `0.5.0`,
+  `created_at: 2026-08-25T09:26:15.342Z`, published `sha` field matches the same
+  sha256 above exactly -- local build, CI artifact, and the published gem are all
+  byte-identical.
 
 Recorded here after this file previously claimed "this repo currently has no CI
 workflow gating pull requests" — wrong on both existence and execution. This file is
@@ -73,6 +90,13 @@ status entry above for verification details.
   docs-only pass — implementing the workflow change goes through an Issue (once
   ticket-driven work applies to it) plus the normal explore → plan → approval gate,
   not a direct docs commit.
+  - A point in Trusted Publishing's favour, measured 2026-08-27: the gem build is
+    byte-identical across machines and Ruby installs for a given commit — `4080053`
+    (the `v0.6.0` tag) produced sha256 `08cdd14a…` from CI, from the old machine
+    (R5), and from a rebuild on the replacement machine under local ruby 4.0.6 vs
+    CI's `ruby/setup-ruby@v1` ruby 4.0. So a CI- or Trusted-Publishing-published
+    artifact stays independently verifiable against a local rebuild
+    (`docs/reports/fsh-generator-log.md` R8).
 
 ## From #25 / PR #26 (FieldExtractor terminology scope fix, 2026-08-22)
 
@@ -138,3 +162,18 @@ status entry above for verification details.
   duplicate-method inventory being produced first.
 - **#2** (constraint -> HTML attribute mapping extraction): gated on a generality decision
   after Anlage Slice 4; whether to even start is undecided.
+
+## Dependencies
+
+- **Remove the `json < 3` pins once Rails ships the fix.** Added 2026-09-10 in
+  three places: `Gemfile` (dev/test), `script/build_demo.sh` (the demo app's
+  Gemfile), `templates/openehr_template.rb` (the generated host app's Gemfile).
+  Cause: `json` 3.0 (3.0.1 on 2026-09-08, 3.0.2 on 2026-09-09) changed
+  `JSON.parse`'s arity and `ActiveSupport::JSON.decode` as of activesupport
+  8.1.3.1 still passes options positionally, so every json-column read raises
+  `ArgumentError: wrong number of arguments (given 2, expected 1)`. Measured on
+  PR #39's CI run `34423912397` (62 failures, all RM-graph/AQL specs) and
+  reproduced locally with `bundle update` on `master`; with the pin and a fresh
+  resolve, 295 examples / 0 failures. Removal condition: an activesupport release
+  whose `JSON.decode` accepts json 3 (check the Rails CHANGELOG), then delete the
+  three pins in one docs+tooling commit and let CI resolve fresh.

data/docs/design/fsh-generator-plan.md

@@ -0,0 +1,113 @@
+# Enhancement: FshGenerator (FSH output alongside ProfileGenerator)
+
+- Status: draft, approved-by-citation (design decisions made upstream in
+  `skoba/anlage#17`, not re-litigated here)
+- Target: `openehr-rails` (this repo)
+- Issue: [#32](https://github.com/skoba/openehr-rails/issues/32)
+- Log: `docs/reports/fsh-generator-log.md`
+- Design authority: `skoba/anlage`'s `docs/design/fsh-plan.md` (2026-08-26
+  ruling, all 4 judgments approved) and `docs/reports/fsh-log.md` R1-R4.
+  This doc translates that already-approved plan into this repo's
+  file:line reality; it does not re-decide source/scope/output-form.
+
+## 1. Summary
+
+Add `OpenehrRails::Fhir::FshGenerator`, a sibling to
+`OpenehrRails::Fhir::ProfileGenerator` that renders FSH (FHIR Shorthand)
+text instead of a JSON StructureDefinition Hash, from the exact same
+input: `OpenehrRails::Opt::FieldExtractor#entries`. No independent OPT
+walk — this is the "share the intermediate representation" design
+anlage's plan settled on (rejecting a pathcards-based or
+independently-walking alternative as violating the no-double-derivation
+constraint).
+
+## 2. Input contract (already shipped, `skoba/openehr-rails#30` / 0.5.0)
+
+`FieldExtractor#entries[].fields[]` now always carries (verified live
+in `field_extractor.rb:160-177`, doc comment `field_extractor.rb:1-23`):
+
+- `value_set_uri`: `C_CODE_REFERENCE#reference_set_uri`, else `nil`
+- `code_bindings`: `[{system_uri:, code:}]`, else `[]` — not limited to
+  `DV_CODED_TEXT` (BMI's LOINC binding sits on a `DV_QUANTITY` element,
+  `CHANGELOG.md` [0.5.0] Added note)
+
+No further gem work is a prerequisite for this Issue.
+
+## 3. v1 scope (per the approved anlage plan, §"v1サブセットの範囲確定")
+
+Mirror exactly what `ProfileGenerator` already emits, in FSH syntax,
+plus binding writes (now unblocked):
+
+| JSON (`profile_generator.rb`) | FSH form |
+|---|---|
+| `build_profile` metadata (`:33-50`) | `Profile:`/`Parent:`/`Id:`/`Title:` header lines |
+| `code_element` (`:62-69`) | `* code.coding.system = ...` / `* code.coding.code = ...` (or a `patternCodeableConcept`-equivalent assignment — pick whichever Sushi compiles identically to the JSON shape; verify by comparing compiled output, not by assumption) |
+| `value_elements` (`:71-80`) | `* value[x] <min>..<max>` + `* value[x] only <Type>` |
+| `component_elements`/`component_slice` (`:82-113`) | slicing declaration (`^slicing.discriminator...`) + `* component contains <slice> <card>` + per-slice `code`/`value[x]` assignment (see anlage's `docs/reports/fsh-log.md` R1 for a working Sushi-verified example of this exact shape) |
+| `DV_QUANTITY` unit (`apply_value_constraints`, `:117-124`) | `* value[x].unit = "..."` (or equivalent fixed-value rule) |
+| `DV_CODED_TEXT` binding (`:125-131`, now includes `valueSet`) | `field[:value_set_uri]` present → `* value[x] from <uri> (required)`. `field[:code_bindings]` present (any rm_type) → fixed `patternCodeableConcept`-equivalent assignment per binding entry |
+
+Explicitly out of scope for v1 (matches the JSON facade's own gaps, not
+new ones introduced here): `magnitude_range` (extracted but never
+emitted by `ProfileGenerator` either — a separate, pre-existing gap).
+`mml_referral`-scale templates are out of v1's verification scope per
+the approved plan (size cap); this Issue's fixtures stay to the 3 small
+ones listed below.
+
+## 4. Fixtures (no new SNOMED literal budget — reuse what's already here)
+
+- `spec/generators/templates/bmi_calculation.opt` — single-leaf,
+  `DV_QUANTITY`, real SNOMED-CT (`60621009`) + LOINC `code_binding` on
+  `at0004` (`spec/templates/bmi_calculation_without_uid.opt:1683-1697`
+  for the byte-identical sibling with visible XML)
+- `spec/templates/problem_list.opt` — `C_CODE_REFERENCE`/ICD-11
+  `value_set_binding` on `at0002`, local `code_list` contrast on
+  `at0073` (byte-identical copy of anlage's `ProblemList.opt`,
+  provenance comment already in the file per `0bbbc47`)
+
+Both are already indexed by existing specs
+(`spec/openehr_rails/fhir/profile_generator_spec.rb`,
+`spec/openehr_rails/opt/field_extractor_binding_spec.rb`) — reuse the
+same `template` `let` pattern.
+
+## 5. TDD (t-wada, per this repo's CLAUDE.md)
+
+1. Red/Green: `FshGenerator` non-binding v1 subset against
+   `bmi_calculation.opt` — metadata, single-leaf `value[x]`, unit. Fix
+   the exact FSH text with a golden spec (string equality or a small
+   set of `include` assertions on stable substrings — match whichever
+   style `profile_generator_spec.rb` already uses for the JSON side)
+2. Red/Green: `code_binding` write against `bmi_calculation.opt`'s
+   `at0004` (SNOMED-CT `60621009` and/or the LOINC binding — pick
+   whichever demonstrates the fixed-value FSH form most clearly)
+3. Red/Green: `value_set_binding` write against `problem_list.opt`'s
+   `at0002` (ICD-11) — fix the `from <uri> (required)` line
+4. Red/Green: multi-leaf `component` slicing — `bmi_calculation.opt`'s
+   `openEHR-EHR-OBSERVATION.body_mass_index.v2` entry already has 2 leaf
+   fields (verified: `bundle exec ruby` with `FieldExtractor#entries`,
+   2026-08-26), and `at0004`'s SNOMED/LOINC `code_binding` sits inside
+   this same multi-leaf entry — one fixture covers both slicing and
+   binding for this case. No new fixture needed (`problem_list.opt` also
+   has 5 leaf fields, `lab_result_report_reduced.opt` has 3, for
+   reference)
+5. Manual verification (not part of this Issue's automated suite,
+   done once locally before closing): pipe generated FSH through
+   `fsh-sushi` and confirm 0 Errors, matching the shapes anlage already
+   verified by hand (`docs/reports/fsh-log.md` R1 in `skoba/anlage`)
+
+## 6. Structural note
+
+`FshGenerator` takes only `FieldExtractor#entries` (or a `template` it
+extracts from, same as `ProfileGenerator.new(template)`) — no
+`ActiveRecord::Base`/`Rails` dependency. This keeps it relocatable if a
+future `openehr-fhirbridge` satellite gem is split out (anlage
+`docs/backlog.md` item 5, not a decision made in this Issue).
+
+## 7. Out of scope here
+
+- CI wiring for Sushi verification (anlage-side decision, ruled out for
+  v1 — `docs/design/fsh-plan.md`'s 判断3 in `skoba/anlage`)
+- The `rake fsh:export` output path (anlage-side, `skoba/anlage`'s own
+  Issue #17 scope)
+- Any RubyGems release/publish step (human-gated per this repo's
+  `docs/backlog.md` "Release automation" / `skoba/openehr-rails#27`)