@glion/lint-profile-backward-compatible 0.0.0-stage → 0.24.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Rethink Health
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# @glion/lint-profile-backward-compatible
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lint rule that reports a value in an element HL7v2 keeps only for backward compatibility.
+
+## What it does
+
+Flags a field, component, or subcomponent that has a value although the HL7v2 standard for the message's version marks it `B` (backward compatible). HL7v2 keeps such an element so older systems can still send it, and another element now carries its data. A value is still allowed, so `@glion/preset-lint-profile-recommended` reports it as a warning. It needs the plugins `@glion/annotate-profile-context`, `@glion/annotate-profile-fields` and `@glion/annotate-profile-datatypes` to run before it; `@glion/preset-lint-profile-recommended` includes them.
+
+## Install
+
+```bash
+npm install @glion/lint-profile-backward-compatible
+```
+
+## Use
+
+```ts
+import { hl7v2AnnotateProfileContext } from "@glion/annotate-profile-context";
+import { hl7v2AnnotateProfileDatatypes } from "@glion/annotate-profile-datatypes";
+import { hl7v2AnnotateProfileFields } from "@glion/annotate-profile-fields";
+import hl7v2LintBackwardCompatible from "@glion/lint-profile-backward-compatible";
+import { parseHL7v2 } from "@glion/parser";
+import { unified } from "unified";
+import { VFile } from "vfile";
+import { reporter } from "vfile-reporter";
+
+const message = [
+  "MSH|^~\\&|SENDER|FAC|RECV|RFAC|20250601120000||ADT^A01^ADT_A01|MSG00001|P|2.5.1",
+  "DG1|1|I9|250.00|DIABETES",
+].join("\r");
+
+const file = new VFile();
+await unified()
+  .use(hl7v2AnnotateProfileContext)
+  .use(hl7v2AnnotateProfileFields)
+  .use(hl7v2AnnotateProfileDatatypes)
+  .use(hl7v2LintBackwardCompatible)
+  .run(parseHL7v2(message), file);
+
+console.error(reporter([file]));
+```
+
+## API
+
+### `unified().use(hl7v2LintBackwardCompatible)`
+
+A `unified` lint rule plugin. Takes no options. Reports one message for each backward-compatible element that has a value.
+
+```ts
+import type { Plugin } from "unified";
+import type { Root } from "@glion/ast";
+
+declare const hl7v2LintBackwardCompatible: Plugin<[], Root>;
+export default hl7v2LintBackwardCompatible;
+```
+
+## What it checks
+
+An element whose optionality is `B` in the message's version should be empty. The explicit null `""` is accepted. For example, in v2.5.1 the field `DG1-4` (Diagnosis Description) is backward compatible, and `DG1-3` (Diagnosis Code) carries the diagnosis.
+
+### Valid
+
+`DG1-4` is empty in a v2.5.1 message:
+
+```hl7
+MSH|^~\&|SENDER|FAC|RECV|RFAC|20250601120000||ADT^A01^ADT_A01|MSG00001|P|2.5.1
+DG1|1|I9|250.00
+```
+
+### Invalid
+
+`DG1-4` has a value in a v2.5.1 message:
+
+```hl7
+MSH|^~\&|SENDER|FAC|RECV|RFAC|20250601120000||ADT^A01^ADT_A01|MSG00001|P|2.5.1
+DG1|1|I9|250.00|DIABETES
+```
+
+Reported message:
+
+```
+`DG1-4` (Diagnosis Description) has a value; v2.5.1 keeps it only for backward compatibility.
+```
+
+A field is reported once, whichever of its repetitions has a value. A component is reported in each repetition that gives it a value.
+
+## Part of Glion
+
+`@glion/lint-profile-backward-compatible` is part of **[Glion]**, the application framework for HL7v2. See the [Glion README] for the full package catalog and architecture.
+
+[Glion]: https://github.com/rethinkhealth/glion#readme
+[Glion README]: https://github.com/rethinkhealth/glion#readme

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import type { Root } from "@glion/ast";
+/**
+ * Lint rule that reports a value in any element whose optionality is `B`
+ * (backward compatible): a field, a component, or a subcomponent.
+ *
+ * Reads `optionality` from `node.data`, which the profile annotators write, so
+ * `@glion/annotate-profile-fields` and `@glion/annotate-profile-datatypes`
+ * MUST run before it. An empty element and the explicit null `""` are
+ * accepted.
+ *
+ * @example
+ *   ```typescript
+ *   unified()
+ *     .use(hl7v2AnnotateProfileContext)
+ *     .use(hl7v2AnnotateProfileFields)
+ *     .use(hl7v2AnnotateProfileDatatypes)
+ *     .use(hl7v2LintBackwardCompatible);
+ *   ```;
+ */
+declare const hl7v2LintBackwardCompatible: import("unified-lint-rule").Plugin<Root, unknown>;
+export default hl7v2LintBackwardCompatible;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAevC;;;;;;;;;;;;;;;;;GAiBG;AACH,QAAA,MAAM,2BAA2B,mDA8ChC,CAAC;AAEF,eAAe,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,52 @@
+import { toHl7v2 } from "@glion/to-hl7v2";
+import { delimiters } from "@glion/util-query";
+import { SKIP, visit } from "@glion/util-visit";
+import { Optionality, isEmptyNode } from "@glion/utils";
+import { lintRule } from "unified-lint-rule";
+//#region src/index.ts
+/** HL7v2 explicit null: the receiver deletes the element's value. */
+const EXPLICIT_NULL = "\"\"";
+const messages = { backwardCompatible: (id, name, version) => `\`${id}\` (${name}) has a value; v${version} keeps it only for backward compatibility.` };
+/**
+* Lint rule that reports a value in any element whose optionality is `B`
+* (backward compatible): a field, a component, or a subcomponent.
+*
+* Reads `optionality` from `node.data`, which the profile annotators write, so
+* `@glion/annotate-profile-fields` and `@glion/annotate-profile-datatypes`
+* MUST run before it. An empty element and the explicit null `""` are
+* accepted.
+*
+* @example
+*   ```typescript
+*   unified()
+*     .use(hl7v2AnnotateProfileContext)
+*     .use(hl7v2AnnotateProfileFields)
+*     .use(hl7v2AnnotateProfileDatatypes)
+*     .use(hl7v2LintBackwardCompatible);
+*   ```;
+*/
+const hl7v2LintBackwardCompatible = lintRule({
+	origin: "hl7v2-lint:backward-compatible",
+	url: "https://github.com/rethinkhealth/glion/tree/main/packages/lint-profile-backward-compatible#readme"
+}, (tree, file) => {
+	const version = file.data.profile?.version;
+	if (version === void 0) return;
+	visit(tree, (node, ancestors) => {
+		if (node.type !== "field" && node.type !== "component" && node.type !== "subcomponent") return;
+		const id = node.data?.id;
+		if (id === void 0 || node.data?.optionality !== Optionality.BackwardCompatible || isEmptyNode(node)) return;
+		const value = toHl7v2(node, delimiters(tree));
+		if (value === EXPLICIT_NULL) return SKIP;
+		const message = file.message(messages.backwardCompatible(id, node.data?.name ?? "", version), {
+			ancestors: [...ancestors, node],
+			place: node.position
+		});
+		message.actual = value;
+		message.expected = ["", EXPLICIT_NULL];
+		return SKIP;
+	});
+});
+//#endregion
+export { hl7v2LintBackwardCompatible as default };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["// oxlint-disable-next-line no-unused-vars -- triggers VFile DataMap augmentation\nimport type { ProfileContext } from \"@glion/annotate-profile-context\";\n// oxlint-disable-next-line no-unused-vars -- triggers ComponentData and SubcomponentData augmentation\nimport type { hl7v2AnnotateProfileDatatypes } from \"@glion/annotate-profile-datatypes\";\n// oxlint-disable-next-line no-unused-vars -- triggers FieldData augmentation\nimport type { hl7v2AnnotateProfileFields } from \"@glion/annotate-profile-fields\";\nimport type { Root } from \"@glion/ast\";\nimport { toHl7v2 } from \"@glion/to-hl7v2\";\nimport { delimiters } from \"@glion/util-query\";\nimport { SKIP, visit } from \"@glion/util-visit\";\nimport { isEmptyNode, Optionality } from \"@glion/utils\";\nimport { lintRule } from \"unified-lint-rule\";\n\n/** HL7v2 explicit null: the receiver deletes the element's value. */\nconst EXPLICIT_NULL = '\"\"';\n\nconst messages = {\n  backwardCompatible: (id: string, name: string, version: string) =>\n    `\\`${id}\\` (${name}) has a value; v${version} keeps it only for backward compatibility.`,\n} as const;\n\n/**\n * Lint rule that reports a value in any element whose optionality is `B`\n * (backward compatible): a field, a component, or a subcomponent.\n *\n * Reads `optionality` from `node.data`, which the profile annotators write, so\n * `@glion/annotate-profile-fields` and `@glion/annotate-profile-datatypes`\n * MUST run before it. An empty element and the explicit null `\"\"` are\n * accepted.\n *\n * @example\n *   ```typescript\n *   unified()\n *     .use(hl7v2AnnotateProfileContext)\n *     .use(hl7v2AnnotateProfileFields)\n *     .use(hl7v2AnnotateProfileDatatypes)\n *     .use(hl7v2LintBackwardCompatible);\n *   ```;\n */\nconst hl7v2LintBackwardCompatible = lintRule<Root>(\n  {\n    origin: \"hl7v2-lint:backward-compatible\",\n    url: \"https://github.com/rethinkhealth/glion/tree/main/packages/lint-profile-backward-compatible#readme\",\n  },\n  (tree, file) => {\n    const version = file.data.profile?.version;\n    if (version === undefined) {\n      return;\n    }\n\n    visit(tree, (node, ancestors) => {\n      // Fields, components and subcomponents carry an optionality.\n      if (\n        node.type !== \"field\" &&\n        node.type !== \"component\" &&\n        node.type !== \"subcomponent\"\n      ) {\n        return;\n      }\n\n      // An element that is not reported may still have components that are.\n      const id = node.data?.id;\n      if (\n        id === undefined ||\n        node.data?.optionality !== Optionality.BackwardCompatible ||\n        isEmptyNode(node)\n      ) {\n        return;\n      }\n\n      const value = toHl7v2(node, delimiters(tree));\n      if (value === EXPLICIT_NULL) {\n        return SKIP;\n      }\n\n      const message = file.message(\n        messages.backwardCompatible(id, node.data?.name ?? \"\", version),\n        { ancestors: [...ancestors, node], place: node.position }\n      );\n      message.actual = value;\n      message.expected = [\"\", EXPLICIT_NULL];\n      // The element is reported; its components need no report of their own.\n      return SKIP;\n    });\n  }\n);\n\nexport default hl7v2LintBackwardCompatible;\n"],"mappings":";;;;;;;AAcA,MAAM,gBAAgB;AAEtB,MAAM,WAAW,EACf,qBAAqB,IAAY,MAAc,YAC7C,KAAK,GAAG,MAAM,KAAK,kBAAkB,QAAQ,6CAChD;;;;;;;;;;;;;;;;;;;AAoBD,MAAM,8BAA8B,SAClC;CACE,QAAQ;CACR,KAAK;CACN,GACA,MAAM,SAAS;CACd,MAAM,UAAU,KAAK,KAAK,SAAS;AACnC,KAAI,YAAY,KAAA,EACd;AAGF,OAAM,OAAO,MAAM,cAAc;AAE/B,MACE,KAAK,SAAS,WACd,KAAK,SAAS,eACd,KAAK,SAAS,eAEd;EAIF,MAAM,KAAK,KAAK,MAAM;AACtB,MACE,OAAO,KAAA,KACP,KAAK,MAAM,gBAAgB,YAAY,sBACvC,YAAY,KAAK,CAEjB;EAGF,MAAM,QAAQ,QAAQ,MAAM,WAAW,KAAK,CAAC;AAC7C,MAAI,UAAU,cACZ,QAAO;EAGT,MAAM,UAAU,KAAK,QACnB,SAAS,mBAAmB,IAAI,KAAK,MAAM,QAAQ,IAAI,QAAQ,EAC/D;GAAE,WAAW,CAAC,GAAG,WAAW,KAAK;GAAE,OAAO,KAAK;GAAU,CAC1D;AACD,UAAQ,SAAS;AACjB,UAAQ,WAAW,CAAC,IAAI,cAAc;AAEtC,SAAO;GACP;EAEL"}

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@glion/lint-profile-backward-compatible",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.24.0",
+  "description": "Lint rule that reports a value in an element HL7v2 keeps only for backward compatibility",
+  "keywords": [
+    "health",
+    "healthcare",
+    "hl7",
+    "hl7v2",
+    "nodejs",
+    "typescript"
+  ],
+  "homepage": "https://glion.dev",
+  "license": "MIT",
+  "author": {
+    "name": "Melek Somai",
+    "email": "melek@rethinkhealth.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rethinkhealth/glion.git",
+    "directory": "packages/lint-profile-backward-compatible"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "unified-lint-rule": "3.0.1",
+    "@glion/annotate-profile-datatypes": "0.24.0",
+    "@glion/annotate-profile-fields": "0.24.0",
+    "@glion/ast": "0.24.0",
+    "@glion/to-hl7v2": "0.24.0",
+    "@glion/util-query": "0.24.0",
+    "@glion/util-visit": "0.24.0",
+    "@glion/utils": "0.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "25.6.0",
+    "@vitest/coverage-v8": "4.1.11",
+    "publint": "0.3.18",
+    "tsdown": "0.21.10",
+    "typescript": "6.0.3",
+    "unified": "^11.0.5",
+    "vfile": "^6.0.3",
+    "vitest": "4.1.11",
+    "@glion/annotate-profile-context": "0.24.0",
+    "@glion/builder": "0.24.0",
+    "@glion/check-readme": "0.18.0",
+    "@glion/parser": "0.24.0",
+    "@glion/testing": "0.18.0",
+    "@glion/tsconfig": "0.18.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown && tsc --emitDeclarationOnly",
+    "check-types": "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json",
+    "check:readme": "glion-check-readme",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "publint": "publint --strict"
+  }
 }