@rethinkhealth/hl7v2-lint-required-message-header 0.2.8

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

@@ -0,0 +1,136 @@
+# @rethinkhealth/hl7v2-lint-required-message-header
+
+A [`unified`][github-unified] lint rule for HL7v2 that warns when the message header segment (`MSH`) is missing or not the first segment in a message. This helps ensure all HL7v2 messages begin with the required header, improving interoperability and data quality.
+
+HL7v2 messages must always begin with a message header segment, known as `MSH`. This rule checks that the first segment in a message is `MSH` and warns if it is missing or replaced by another segment.
+
+## What is this?
+
+This package validates the **segment header** in HL7v2 syntax trees produced by parsers like [`@rethinkhealth/hl7v2-parser`][github-hl7v2-parser].  
+
+It reports a message when the first segment of an HL7v2 message is not a segment header (MSH).
+
+## When should I use this?
+
+Use this rule to enforce canonical HL7v2 segment identifiers across messages, catch typos (e.g., `PID1`, `Obx`, `MS`), and improve downstream processing reliability.
+
+## Presets
+
+This plugin is included in the following presets:
+
+| Preset | Options |
+| - | - |
+| `@rethinkhealth/hl7v2-lint-recommended` | |
+
+## Install
+
+This package is **ESM only**. In Node.js (v16+), install with npm:
+
+```sh
+npm install @rethinkhealth/hl7v2-lint-required-message-header
+````
+
+
+## Use
+
+On the API:
+
+```js
+import { unified } from 'unified'
+import { hl7v2Parse } from '@rethinkhealth/hl7v2-parser'
+import hl7v2LintRequiredMessageHeader from '@rethinkhealth/hl7v2-lint-required-message-header'
+import { reporter } from 'vfile-reporter'
+
+const msg = `MSH|^~\\&|...`
+const file = await unified()
+  .use(hl7v2Parse)
+  .use(hl7v2LintRequiredMessageHeader)
+  .process(msg)
+
+console.error(reporter([file]))
+```
+
+
+## API
+
+### `unified().use(hl7v2LintSegmentHeaderLength[, options])`
+
+Warn when a segment header is not a three-letter uppercase code.
+
+###### Returns
+
+A `unified` Transformer that adds messages to the file.
+
+## Recommendation
+
+This helps ensure that HL7v2 messages are well-formed and can be reliably parsed and processed by downstream systems. If the message does not start with `MSH`, a warning is reported indicating which segment was found instead.
+
+**Why is this important?**
+
+- The `MSH` segment contains metadata required for routing and interpreting the message.
+- Missing or misplaced `MSH` segments can cause interoperability issues and data loss.
+
+**When to disable:**  
+
+You should only disable this rule if you are intentionally working with non-standard HL7v2 messages that do not require a message header segment, which is rare in practice.
+
+
+It’s recommended to enable this rule in most pipelines.
+
+## Examples
+
+##### `ok.hl7`
+
+###### In
+
+```hl7
+MSH|^~\&|... 
+PID|1||12345^^^HOSP^MR||DOE^JANE||...
+OBX|1|TX|...
+```
+
+###### Out
+
+No messages.
+
+##### `not-ok.hl7`
+
+###### In
+
+```hl7
+PID|1||12345||DOE^JANE||...
+```
+
+###### Out
+
+```text
+Message header (MSH) segment is required. Received PID instead.
+```
+
+## Security
+
+This plugin only transforms AST nodes and does not execute code. Ensure you trust the source of HL7v2 messages before processing.
+
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for more details.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Code of Conduct
+
+To ensure a welcoming and positive environment, we have a [Code of Conduct](../../CODE_OF_CONDUCT.md) that all contributors and participants are expected to adhere to.
+
+## License
+
+Copyright 2025 Rethink Health, SUARL. All rights reserved.
+
+This program is licensed to you under the terms of the [MIT License](https://opensource.org/licenses/MIT). This program is distributed WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the [LICENSE](../../LICENSE) file for details.
+
+[github-unified]: https://github.com/unifiedjs/unified
+[github-hl7v2-parser]: https://github.com/rethinkhealth/hl7v2/tree/main/packages/hl7v2-parser

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { Node } from '@rethinkhealth/hl7v2-ast';
+/**
+ * hl7v2-lint rule to warn when message header segment (MSH) is missing.
+ *
+ * This rule is useful for ensuring that all messages start with a message
+ * header segment.
+ */
+declare const hl7v2LintSegmentRequiredMessageHeader: import("unified-lint-rule").Plugin<Node, undefined>;
+export default hl7v2LintSegmentRequiredMessageHeader;
+//# 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":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAiB,MAAM,0BAA0B,CAAC;AAIpE;;;;;GAKG;AACH,QAAA,MAAM,qCAAqC,qDA2B1C,CAAC;AAEF,eAAe,qCAAqC,CAAC"}

package/dist/index.js

@@ -0,0 +1,35 @@
+// src/index.ts
+import { lintRule } from "unified-lint-rule";
+import { SKIP, visitParents } from "unist-util-visit-parents";
+var hl7v2LintSegmentRequiredMessageHeader = lintRule(
+  {
+    origin: "hl7v2-lint:segment-required-message-header",
+    url: "https://github.com/rethinkhealth/hl7v2/tree/main/packages/hl7v2-lint-segment-required-message-header#readme"
+  },
+  (tree, file) => {
+    visitParents(tree, (node, parents) => {
+      if (node.type === "root") {
+        const firstSegment = node.children[0];
+        if (firstSegment?.type === "segment") {
+          const header = firstSegment.children?.[0]?.children?.[0]?.children?.[0]?.children?.[0]?.value;
+          if (header !== "MSH") {
+            file.message(
+              `Message header (MSH) segment is required. Received ${header} instead.`,
+              {
+                ancestors: [...parents, node, firstSegment],
+                place: firstSegment.position
+              }
+            );
+          }
+        }
+      } else {
+        return SKIP;
+      }
+    });
+  }
+);
+var src_default = hl7v2LintSegmentRequiredMessageHeader;
+export {
+  src_default as default
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Node, Root, Segment } from '@rethinkhealth/hl7v2-ast';\nimport { lintRule } from 'unified-lint-rule';\nimport { SKIP, visitParents } from 'unist-util-visit-parents';\n\n/**\n * hl7v2-lint rule to warn when message header segment (MSH) is missing.\n *\n * This rule is useful for ensuring that all messages start with a message\n * header segment.\n */\nconst hl7v2LintSegmentRequiredMessageHeader = lintRule<Node, undefined>(\n  {\n    origin: 'hl7v2-lint:segment-required-message-header',\n    url: 'https://github.com/rethinkhealth/hl7v2/tree/main/packages/hl7v2-lint-segment-required-message-header#readme',\n  },\n  (tree, file) => {\n    visitParents(tree, (node, parents) => {\n      if (node.type === 'root') {\n        const firstSegment = (node as Root).children[0];\n        if (firstSegment?.type === 'segment') {\n          const header = (firstSegment as Segment).children?.[0]?.children?.[0]\n            ?.children?.[0]?.children?.[0]?.value;\n          if (header !== 'MSH') {\n            file.message(\n              `Message header (MSH) segment is required. Received ${header} instead.`,\n              {\n                ancestors: [...parents, node, firstSegment],\n                place: firstSegment.position,\n              }\n            );\n          }\n        }\n      } else {\n        return SKIP;\n      }\n    });\n  }\n);\n\nexport default hl7v2LintSegmentRequiredMessageHeader;\n"],"mappings":";AACA,SAAS,gBAAgB;AACzB,SAAS,MAAM,oBAAoB;AAQnC,IAAM,wCAAwC;AAAA,EAC5C;AAAA,IACE,QAAQ;AAAA,IACR,KAAK;AAAA,EACP;AAAA,EACA,CAAC,MAAM,SAAS;AACd,iBAAa,MAAM,CAAC,MAAM,YAAY;AACpC,UAAI,KAAK,SAAS,QAAQ;AACxB,cAAM,eAAgB,KAAc,SAAS,CAAC;AAC9C,YAAI,cAAc,SAAS,WAAW;AACpC,gBAAM,SAAU,aAAyB,WAAW,CAAC,GAAG,WAAW,CAAC,GAChE,WAAW,CAAC,GAAG,WAAW,CAAC,GAAG;AAClC,cAAI,WAAW,OAAO;AACpB,iBAAK;AAAA,cACH,sDAAsD,MAAM;AAAA,cAC5D;AAAA,gBACE,WAAW,CAAC,GAAG,SAAS,MAAM,YAAY;AAAA,gBAC1C,OAAO,aAAa;AAAA,cACtB;AAAA,YACF;AAAA,UACF;AAAA,QACF;AAAA,MACF,OAAO;AACL,eAAO;AAAA,MACT;AAAA,IACF,CAAC;AAAA,EACH;AACF;AAEA,IAAO,cAAQ;","names":[]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@rethinkhealth/hl7v2-lint-required-message-header",
+  "description": "hl7v2-lint rule to warn when message header segment is missing",
+  "version": "0.2.8",
+  "license": "MIT",
+  "author": {
+    "name": "Melek Somai",
+    "email": "melek@rethinkhealth.io"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "unified": "11.0.1",
+    "unified-lint-rule": "^3.0.0",
+    "unist-util-visit-parents": "^6.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.15.31",
+    "@types/unist": "^3.0.3",
+    "@vitest/coverage-c8": "^0.33.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "tsup": "8.5.0",
+    "typescript": "^5.8.3",
+    "vfile-reporter": "^8.1.1",
+    "vitest": "^3.2.4",
+    "@rethinkhealth/hl7v2": "0.2.8",
+    "@rethinkhealth/testing": "0.0.0",
+    "@rethinkhealth/hl7v2-ast": "0.2.8",
+    "@rethinkhealth/tsconfig": "0.0.0"
+  },
+  "repository": "rethinkhealth/hl7v2.git",
+  "homepage": "https://www.rethinkhealth.io/hl7v2/docs",
+  "keywords": [
+    "hl7",
+    "hl7v2",
+    "nodejs",
+    "typescript",
+    "definition",
+    "lint",
+    "hl7v2-lint",
+    "hl7v2-lint-rule",
+    "rule"
+  ],
+  "packageManager": "pnpm@10.12.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  }
+}