Merge pull request #2 from medvertical/claude/validation-engine-extensions

Extend structural validation: schema, references, slices, orchestrator

Author: sheydin

.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "source": "./plugins/records",
       "description": "FHIR validation and data-quality workflows with Records.",
       "category": "development",
-      "version": "0.4.0",
+      "version": "0.5.0",
       "author": {
         "name": "MedVertical"
       },

README.md

@@ -9,7 +9,7 @@
 # Records for Claude Code
 
 [![Plugin CI](https://github.com/medvertical/claude-records/actions/workflows/plugin-ci.yml/badge.svg)](https://github.com/medvertical/claude-records/actions/workflows/plugin-ci.yml)
-![Version](https://img.shields.io/badge/version-0.4.0-blue)
+![Version](https://img.shields.io/badge/version-0.5.0-blue)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
 FHIR validation and data-quality workflow skills for Claude Code.
@@ -63,6 +63,7 @@ Example prompts:
 The plugin includes focused commands that route into the `fhir-validation` workflow:
 
 - `/records:doctor` - diagnose FHIR/IG project structure, runtimes, and privacy boundaries.
+- `/records:validate` - run end-to-end local structural validation (detect, validate, explain, map).
 - `/records:init-ci` - generate or update Records FHIR validation CI.
 - `/records:explain-outcome` - explain FHIR `OperationOutcome` issues and safe fixability.
 - `/records:derive-quality-rules` - derive reviewable project quality rules from local evidence.
@@ -92,7 +93,7 @@ The FHIR validation skill guides Claude through five validation paths:
 
 The local CLI fallback uses Records' packaged FHIR R4 structural schema for resource types, required fields, unknown fields, cardinality, primitive types, choice fields, and simple backbone children. It does not replace profile, terminology, invariant, reference, metadata, advisor-rule, anomaly, or evidence-report validation.
 
-Executable helper scripts support deterministic project detection (including FHIR package-cache and dependency resolution), local structural fallback validation, StructureDefinition snapshot/slicing analysis, generated FSH source mapping, OperationOutcome explanation, PHI-minimizing summaries, quality-rule derivation, CI YAML generation, and FHIR expression to JSON Pointer mapping.
+Executable helper scripts support deterministic project detection (including FHIR package-cache and dependency resolution), local structural fallback validation (multi-resource schema, primitive datatype formats, required choices, and contained/intra-Bundle reference integrity), an end-to-end validation orchestrator, StructureDefinition snapshot/slicing analysis and instance-based slice matching, generated FSH source mapping, OperationOutcome explanation, PHI-minimizing summaries, quality-rule derivation, CI YAML generation, and FHIR expression to JSON Pointer mapping.
 
 ## Repository Scope
 
@@ -137,7 +138,7 @@ Canonical installation is via `medvertical/claude-records`. The ClaudeRegistry s
 
 ## Release Notes
 
-See [plugins/records/eval-results/v0.4.0.md](./plugins/records/eval-results/v0.4.0.md) for the current release checks and scope.
+See [plugins/records/eval-results/v0.5.0.md](./plugins/records/eval-results/v0.5.0.md) for the current release checks and scope.
 
 ## Development
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-records",
   "private": true,
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "scripts": {
     "test": "node plugins/records/scripts/smoke-test.mjs && node plugins/records/scripts/eval-fixtures.mjs",

plugins/records/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "records",
   "description": "FHIR validation and data-quality workflow skills for Claude Code.",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "author": {
     "name": "MedVertical"
   },

plugins/records/commands/validate.md

@@ -0,0 +1,34 @@
+---
+description: Run end-to-end local structural FHIR validation (detect, validate, explain, map) with the Records fhir-validation skill.
+argument-hint: "[file-or-directory]"
+---
+
+# Records FHIR Validate
+
+Use `/records:fhir-validation` behavior for this validation task. Prefer a
+profile-aware runtime (Records CLI/MCP/API, IG Publisher, HAPI, Firely) when
+one is configured; this command runs the local **structural fallback** and must
+be labeled as such.
+
+Target: `$ARGUMENTS` or the current working directory.
+
+Run the orchestrator, which detects project context for directories, validates
+each resource, and enriches every issue with fixability guidance and a JSON
+Pointer:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/skills/fhir-validation/scripts/validate.mjs" "$ARGUMENTS"
+```
+
+If no argument was provided, use `.`. Summarize:
+
+1. Mode and privacy boundary (structural fallback; not profile/terminology/
+   invariant/cross-document-reference aware).
+2. Totals: resources scanned, errors, warnings, information.
+3. Errors first, grouped by file and path, with the JSON Pointer and whether
+   the fix is mechanical, domain input, or setup/package repair.
+4. For directories, surface the detector's recommended order and any missing
+   package dependencies.
+
+Do not edit files unless the user explicitly asks for fixes, and do not claim
+profile conformance from this structural run.

plugins/records/eval-results/v0.5.0.md

@@ -0,0 +1,37 @@
+# Records Claude Plugin Eval Results v0.5.0
+
+## Scope
+
+Validation-engine extensions release, deepening the local structural fallback
+toward what the OSS validators (HL7 reference validator, HAPI, Firely) do:
+
+- Expand the embedded R4 structural schema to Condition, Encounter, Procedure,
+  MedicationRequest, and DiagnosticReport, plus primitive datatype format checks
+  (`date`, `dateTime`, `instant`, `time`, `boolean`, `integer`, `uri`) and
+  required `choice[x]` elements (`r4-primitives.mjs`).
+- Add reference integrity checks: contained (`#id`) references must resolve, and
+  inside a Bundle relative (`Type/id`) and `urn:` references are resolved against
+  entry `fullUrl`s and resource ids.
+- Add instance-based slice matching (`match-slices.mjs`) that evaluates value and
+  pattern discriminators against an instance to attribute array entries to named
+  slices.
+- Add an end-to-end orchestrator (`validate.mjs`) and a `/records:validate`
+  command that detect project context, validate each resource, and enrich every
+  issue with fixability guidance and a JSON Pointer. The FHIRPath-to-pointer
+  logic is now a shared library (`lib/fhirpath-pointer.mjs`).
+- Broaden smoke and fixture eval coverage across all of the above.
+
+## Automated Checks
+
+- `npm test`
+- `npm run release:check`
+- `npx --yes @anthropic-ai/claude-code plugin validate .`
+- `npx --yes @anthropic-ai/claude-code plugin validate plugins/records`
+- `node plugins/records/skills/fhir-validation/scripts/validate.mjs plugins/records/fixtures/mini-ig`
+- `node plugins/records/skills/fhir-validation/scripts/validate-structural.mjs plugins/records/fixtures/condition-missing-subject.json`
+- `node plugins/records/skills/fhir-validation/scripts/match-slices.mjs plugins/records/fixtures/structuredefinition-sliced.json plugins/records/fixtures/observation-sliced-instance.json`
+
+## Release Decision
+
+Ship v0.5.0 as the validation-engine extensions release for
+`records@medvertical`.

plugins/records/fixtures/condition-missing-subject.json

@@ -0,0 +1,13 @@
+{
+  "resourceType": "Condition",
+  "id": "condition-missing-subject",
+  "clinicalStatus": {
+    "coding": [
+      {
+        "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
+        "code": "active"
+      }
+    ]
+  },
+  "recordedDate": "2026-13-02"
+}

plugins/records/fixtures/observation-sliced-instance.json

@@ -0,0 +1,39 @@
+{
+  "resourceType": "Observation",
+  "id": "observation-sliced-instance",
+  "status": "final",
+  "code": {
+    "coding": [
+      {
+        "system": "http://loinc.org",
+        "code": "85354-9"
+      }
+    ]
+  },
+  "category": [
+    {
+      "coding": [
+        {
+          "system": "http://terminology.hl7.org/CodeSystem/observation-category",
+          "code": "vital-signs"
+        }
+      ]
+    },
+    {
+      "coding": [
+        {
+          "system": "http://terminology.hl7.org/CodeSystem/observation-category",
+          "code": "laboratory"
+        }
+      ]
+    },
+    {
+      "coding": [
+        {
+          "system": "http://terminology.hl7.org/CodeSystem/observation-category",
+          "code": "social-history"
+        }
+      ]
+    }
+  ]
+}

plugins/records/fixtures/structuredefinition-sliced.json

@@ -31,12 +31,22 @@
         "min": 1,
         "max": "1"
       },
+      {
+        "id": "Observation.category:vital.coding.code",
+        "path": "Observation.category.coding.code",
+        "patternCode": "vital-signs"
+      },
       {
         "id": "Observation.category:lab",
         "path": "Observation.category",
         "sliceName": "lab",
         "min": 0,
         "max": "1"
+      },
+      {
+        "id": "Observation.category:lab.coding.code",
+        "path": "Observation.category.coding.code",
+        "patternCode": "laboratory"
       }
     ]
   }

plugins/records/scripts/smoke-test.mjs

@@ -92,7 +92,11 @@ const required = [
   "plugins/records/skills/fhir-validation/references/structural-validation.md",
   "plugins/records/skills/fhir-validation/scripts/lib/operationoutcome-issues.mjs",
   "plugins/records/skills/fhir-validation/scripts/lib/r4-structural-schema.mjs",
+  "plugins/records/skills/fhir-validation/scripts/lib/r4-primitives.mjs",
+  "plugins/records/skills/fhir-validation/scripts/lib/fhirpath-pointer.mjs",
   "plugins/records/skills/fhir-validation/scripts/validate-structural.mjs",
+  "plugins/records/skills/fhir-validation/scripts/validate.mjs",
+  "plugins/records/skills/fhir-validation/scripts/match-slices.mjs",
   "plugins/records/skills/fhir-validation/scripts/generate-issue-map-doc.mjs",
   "plugins/records/skills/fhir-validation/scripts/analyze-structuredefinition.mjs",
   "plugins/records/skills/fhir-validation/scripts/detect-fhir-project.mjs",
@@ -106,6 +110,7 @@ const required = [
   "plugins/records/commands/init-ci.md",
   "plugins/records/commands/explain-outcome.md",
   "plugins/records/commands/derive-quality-rules.md",
+  "plugins/records/commands/validate.md",
   "plugins/records/agents/fhir-validation-reviewer.md",
   "plugins/records/fixtures/invalid-observation.json",
   "plugins/records/fixtures/operationoutcome-required.json",
@@ -168,10 +173,14 @@ for (const script of [
   "plugins/records/skills/fhir-validation/scripts/generate-ci.mjs",
   "plugins/records/skills/fhir-validation/scripts/map-fhir-expression.mjs",
   "plugins/records/skills/fhir-validation/scripts/validate-structural.mjs",
+  "plugins/records/skills/fhir-validation/scripts/validate.mjs",
+  "plugins/records/skills/fhir-validation/scripts/match-slices.mjs",
   "plugins/records/skills/fhir-validation/scripts/generate-issue-map-doc.mjs",
   "plugins/records/skills/fhir-validation/scripts/analyze-structuredefinition.mjs",
   "plugins/records/skills/fhir-validation/scripts/lib/operationoutcome-issues.mjs",
   "plugins/records/skills/fhir-validation/scripts/lib/r4-structural-schema.mjs",
+  "plugins/records/skills/fhir-validation/scripts/lib/r4-primitives.mjs",
+  "plugins/records/skills/fhir-validation/scripts/lib/fhirpath-pointer.mjs",
 ]) {
   const scriptStat = await stat(path.join(repo, script));
   if (!scriptStat.isFile()) errors.push(`Script is not a file: ${script}`);
@@ -281,6 +290,18 @@ function runJsonInput(script, input) {
   }
 }
 
+// Run an arbitrary JSON-emitting script with file args and return status+parsed.
+function runValidatorScript(script, args) {
+  const result = spawnSync(process.execPath, [script, ...args], { cwd: repo, encoding: "utf8" });
+  let parsed = null;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch {
+    errors.push(`${rel(script)} did not output JSON: ${result.stderr || result.stdout}`);
+  }
+  return { status: result.status, parsed };
+}
+
 const invalidObs = runValidator([path.join(plugin, "fixtures/invalid-observation.json")]);
 if (invalidObs.parsed) {
   if (invalidObs.status !== 1) errors.push("Structural validator should exit 1 for the invalid Observation.");
@@ -403,6 +424,46 @@ if (!sushiCi.includes("sushi .")) errors.push("CI generator --sushi should inclu
 const uploadCi = spawnSync(process.execPath, [ciGen, "--upload-artifact"], { cwd: repo, encoding: "utf8" }).stdout;
 if (!uploadCi.includes("upload-artifact")) errors.push("CI generator --upload-artifact should add an artifact upload step.");
 
+// --- v0.5.0: expanded schema, primitives, required choice, references ---
+const condition = validatorCodes([path.join(plugin, "fixtures/condition-missing-subject.json")]);
+if (!condition.codes?.includes("required:Condition.subject")) errors.push("Validator should require Condition.subject.");
+if (!condition.codes?.some((entry) => entry.startsWith("value:Condition.recordedDate"))) errors.push("Validator should flag the malformed Condition.recordedDate primitive.");
+
+const badPrimitive = validatorCodes([], '{"resourceType":"Patient","id":"x","birthDate":"2020-13-01","active":"yes"}');
+if (!badPrimitive.codes?.some((entry) => entry.startsWith("value:Patient.birthDate"))) errors.push("Validator should flag an invalid date primitive.");
+if (!badPrimitive.codes?.some((entry) => entry.startsWith("value:Patient.active"))) errors.push("Validator should flag a non-boolean primitive.");
+
+const reqChoiceMissing = validatorCodes([], '{"resourceType":"MedicationRequest","id":"m","status":"active","intent":"order","subject":{"reference":"Patient/p"}}');
+if (!reqChoiceMissing.codes?.some((entry) => entry.includes("required:MedicationRequest.medication[x]"))) errors.push("Validator should require a medication[x] choice.");
+const reqChoicePresent = validatorCodes([], '{"resourceType":"MedicationRequest","id":"m","status":"active","intent":"order","subject":{"reference":"Patient/p"},"medicationCodeableConcept":{}}');
+if (reqChoicePresent.codes?.some((entry) => entry.includes("MedicationRequest.medication[x]"))) errors.push("Validator should accept a satisfied medication[x] choice.");
+
+const containedMissing = runValidator([], '{"resourceType":"Observation","status":"final","code":{},"subject":{"reference":"#p1"}}');
+if (containedMissing.parsed?.summary.error !== 1 || !containedMissing.parsed?.operationOutcome.issue.some((entry) => entry.severity === "error" && entry.code === "not-found")) {
+  errors.push("Validator should flag an unresolved contained reference as an error.");
+}
+const bundleUnresolved = runValidator([], '{"resourceType":"Bundle","type":"collection","entry":[{"resource":{"resourceType":"Observation","status":"final","code":{},"subject":{"reference":"Patient/missing"}}}]}');
+if (bundleUnresolved.parsed?.summary.warning !== 1 || bundleUnresolved.status !== 0) errors.push("Validator should warn (not error) on an unresolved intra-Bundle reference.");
+const bundleResolved = runValidator([], '{"resourceType":"Bundle","type":"collection","entry":[{"resource":{"resourceType":"Patient","id":"p"}},{"resource":{"resourceType":"Observation","status":"final","code":{},"subject":{"reference":"Patient/p"}}}]}');
+if (bundleResolved.parsed?.summary.warning !== 0 || bundleResolved.parsed?.summary.error !== 0) errors.push("Validator should resolve an intra-Bundle reference cleanly.");
+
+// --- v0.5.0: instance-based slice matching ---
+const matcher = path.join(plugin, "skills/fhir-validation/scripts/match-slices.mjs");
+const slice = runJson(matcher, [path.join(plugin, "fixtures/structuredefinition-sliced.json"), path.join(plugin, "fixtures/observation-sliced-instance.json")]);
+const sliceElement = slice?.slicedElements?.[0];
+if (!sliceElement || JSON.stringify(sliceElement.slices) !== JSON.stringify({ vital: [0], lab: [1] })) errors.push("Slice matcher should attribute entries 0 and 1 to the vital and lab slices.");
+if (!sliceElement?.unmatched?.includes(2)) errors.push("Slice matcher should report the unmatched social-history entry.");
+
+// --- v0.5.0: orchestrator ---
+const orchestrator = path.join(plugin, "skills/fhir-validation/scripts/validate.mjs");
+const orchFile = runValidatorScript(orchestrator, [path.join(plugin, "fixtures/invalid-observation.json")]);
+if (orchFile.status !== 1 || orchFile.parsed?.totals.error !== 2) errors.push("Orchestrator should report 2 errors and exit 1 for the invalid Observation.");
+const firstIssue = orchFile.parsed?.results?.[0]?.issues?.[0];
+if (!firstIssue?.jsonPointer || !firstIssue?.safeFixability) errors.push("Orchestrator should enrich issues with a JSON Pointer and fixability guidance.");
+const orchDir = runValidatorScript(orchestrator, [miniIg]);
+if (orchDir.parsed?.detector?.projectType !== "fsh-ig") errors.push("Orchestrator should include detector context for a directory target.");
+if (!(orchDir.parsed?.totals.resources >= 2)) errors.push("Orchestrator should validate every resource in a directory.");
+
 if (errors.length) {
   console.error(errors.map((error) => `- ${error}`).join("\n"));
   process.exit(1);