@rethinkhealth/hl7v2-utils 0.2.19 → 0.2.21

package/README.md

@@ -2,12 +2,180 @@
 
 A utility package for working with HL7v2 messages, most commonly used within the `@rethinkhealth/hl7v2` ecosystem — a unist-inspired collection of plugins and utilities designed to parse, transform, validate, and manipulate HL7v2 messages.
 
+This package provides core utilities including:
+- Diagnostic reporting system for linters, validators, and transformers
+- Standard HL7v2 delimiters
+- AST node utility functions
+
 ## Installation
 
 ```bash
 npm install @rethinkhealth/hl7v2-utils
 ```
 
+## API
+
+### `report(file, rule, options?)`
+
+Report a diagnostic to a VFile. This function is the standard way to report issues in the HL7v2 ecosystem.
+
+#### Parameters
+
+- `file` (`VFile | null | undefined`) - The VFile to report to
+- `rule` (`Diagnostic`) - The diagnostic rule definition
+- `options` (`ReportOptions`, optional)
+  - `node` (`Node`, optional) - The AST node related to the diagnostic
+  - `context` (`Record<string, unknown>`, optional) - Context data passed to the diagnostic's message function
+
+#### Example
+
+```typescript
+import { report } from '@rethinkhealth/hl7v2-utils';
+import type { Diagnostic } from '@rethinkhealth/hl7v2-utils';
+import { VFile } from 'vfile';
+
+// Define a diagnostic rule
+const requiredFieldRule: Diagnostic = {
+  type: 'lint',
+  namespace: 'field',
+  code: 'required',
+  title: 'Required Field Missing',
+  description: 'A required field is missing from the segment.',
+  severity: 'error',
+  message: (ctx) => `Field '${ctx.fieldPath}' is required`,
+  helpUrl: 'https://example.com/docs/required-field'
+};
+
+// Report the diagnostic
+const file = new VFile();
+report(file, requiredFieldRule, {
+  context: { fieldPath: 'PID-5' },
+  node: segmentNode
+});
+```
+
+### `Diagnostic`
+
+Type definition for diagnostic rules. Diagnostics are used to report issues about HL7v2 messages.
+
+#### Properties
+
+- `type` (`string`) - Tool/plugin category (e.g., "validator", "lint", "annotator", "transformer", "parser")
+- `namespace` (`string`) - Domain/concern (e.g., "order", "field", "segment", "conformance")
+- `code` (`string`) - Specific issue code (e.g., "transition", "required", "acceptance")
+- `title` (`string`) - Human-readable title
+- `description` (`string`) - Full description of the rule
+- `severity` (`"error" | "warning" | "info" | null | undefined`) - Default severity level
+- `message` (`(context: Record<string, unknown>) => string`) - Message formatter function
+- `helpUrl` (`string`, optional) - URL to documentation
+
+#### Rule ID Format
+
+The rule ID is automatically constructed as `type:namespace:code` (e.g., `lint:field:required`).
+
+#### Example
+
+```typescript
+const invalidTransitionRule: Diagnostic = {
+  type: 'validator',
+  namespace: 'order',
+  code: 'transition',
+  title: 'Invalid Segment Transition',
+  description: 'A segment arrived that is not allowed in this position.',
+  severity: 'error',
+  message: (ctx) => {
+    const expected = Array.isArray(ctx.expected) 
+      ? ctx.expected.join(', ') 
+      : ctx.expected;
+    return `Expected ${expected}, got '${ctx.actual}'`;
+  },
+  helpUrl: 'https://example.com/docs/segment-order'
+};
+```
+
+### `DEFAULT_DELIMITERS`
+
+Standard HL7v2 delimiters as defined in the specification.
+
+```typescript
+export const DEFAULT_DELIMITERS = {
+  field: "|",
+  component: "^",
+  repetition: "~",
+  subcomponent: "&",
+  escape: "\\",
+  segment: "\r",
+};
+```
+
+#### Example
+
+```typescript
+import { DEFAULT_DELIMITERS } from '@rethinkhealth/hl7v2-utils';
+
+const message = segments.join(DEFAULT_DELIMITERS.segment);
+```
+
+### `isEmptyNode(node)`
+
+Check if an AST node is semantically empty. This is useful for validation and transformation logic.
+
+#### Parameters
+
+- `node` (`Nodes | null | undefined`) - The AST node to check
+
+#### Returns
+
+`boolean` - `true` if the node is empty, `false` otherwise
+
+#### Example
+
+```typescript
+import { isEmptyNode } from '@rethinkhealth/hl7v2-utils';
+
+if (isEmptyNode(field)) {
+  report(file, requiredFieldRule, { 
+    context: { fieldPath: 'PID-5' },
+    node: field 
+  });
+}
+```
+
+## Usage
+
+### Creating a Custom Linter
+
+```typescript
+import { visit } from 'unist-util-visit';
+import { report } from '@rethinkhealth/hl7v2-utils';
+import type { Diagnostic } from '@rethinkhealth/hl7v2-utils';
+import type { Root } from '@rethinkhealth/hl7v2-ast';
+import type { VFile } from 'vfile';
+
+const noEmptySegmentRule: Diagnostic = {
+  type: 'lint',
+  namespace: 'segment',
+  code: 'no-empty',
+  title: 'Empty Segment',
+  description: 'Segments should not be empty.',
+  severity: 'warning',
+  message: (ctx) => `Segment '${ctx.segmentId}' is empty`
+};
+
+function lintNoEmptySegment() {
+  return (tree: Root, file: VFile) => {
+    visit(tree, 'segment', (node) => {
+      if (isEmptyNode(node)) {
+        report(file, noEmptySegmentRule, {
+          node,
+          context: { segmentId: node.segmentId }
+        });
+      }
+    });
+  };
+}
+```
+
 ## Contributing
 
 We welcome contributions! Please see our [Contributing Guide][github-contributing] for more details.

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 /** biome-ignore-all lint/performance/noBarrelFile: fine */
+export { report } from "./report";
+export type { Diagnostic } from "./types";
 export { DEFAULT_DELIMITERS, isEmptyNode } from "./utils";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -1,3 +1,35 @@
+// src/report.ts
+function report(file, rule, options) {
+  if (!file) {
+    return;
+  }
+  const ruleId = `${rule.type}:${rule.namespace}:${rule.code}`;
+  const context = options?.context ?? {};
+  const message = rule.message(context);
+  const vfileMessage = file.message(message, options?.node);
+  vfileMessage.ruleId = ruleId;
+  vfileMessage.url = rule.helpUrl;
+  vfileMessage.note = rule.description;
+  vfileMessage.source = rule.namespace;
+  switch (rule.severity) {
+    case "error":
+      vfileMessage.fatal = true;
+      break;
+    case "warning":
+      vfileMessage.fatal = false;
+      break;
+    case "info":
+      vfileMessage.fatal = null;
+      break;
+    case null:
+      vfileMessage.fatal = null;
+      break;
+    default:
+      vfileMessage.fatal = void 0;
+      break;
+  }
+}
+
 // src/utils.ts
 var DEFAULT_DELIMITERS = {
   field: "|",
@@ -27,6 +59,7 @@ function isEmptyNode(node) {
 }
 export {
   DEFAULT_DELIMITERS,
-  isEmptyNode
+  isEmptyNode,
+  report
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/utils.ts"],"sourcesContent":["import type { Nodes } from \"@rethinkhealth/hl7v2-ast\";\n\n// -------------\n// Delimiters\n// -------------\n\nexport const DEFAULT_DELIMITERS = {\n  field: \"|\",\n  component: \"^\",\n  repetition: \"~\",\n  subcomponent: \"&\",\n  escape: \"\\\\\",\n  segment: \"\\r\",\n};\n\n// -------------\n// General\n// -------------\n\n/**\n * Utility: check if a node is semantically empty\n */\nexport function isEmptyNode(node: Nodes | null | undefined): boolean {\n  if (!node) {\n    return true;\n  }\n\n  // If node has a \"value\" property (Subcomponent, maybe Component)\n  if (\"value\" in node) {\n    return !node.value || node.value.trim() === \"\";\n  }\n\n  // If node has children (Field, Component, Repetition, Segment, Root, etc.)\n  if (\"children\" in node) {\n    if (!node.children || node.children.length === 0) {\n      return true;\n    }\n\n    // If node has more than one child, then it is considered non-empty\n    if (node.children.length > 1) {\n      return false;\n    }\n\n    // If node has only one child, then it is considered empty if the child is also empty\n    return isEmptyNode(node.children[0]);\n  }\n\n  // Fallback: consider unknown node as non-empty\n  return false;\n}\n"],"mappings":";AAMO,IAAM,qBAAqB;AAAA,EAChC,OAAO;AAAA,EACP,WAAW;AAAA,EACX,YAAY;AAAA,EACZ,cAAc;AAAA,EACd,QAAQ;AAAA,EACR,SAAS;AACX;AASO,SAAS,YAAY,MAAyC;AACnE,MAAI,CAAC,MAAM;AACT,WAAO;AAAA,EACT;AAGA,MAAI,WAAW,MAAM;AACnB,WAAO,CAAC,KAAK,SAAS,KAAK,MAAM,KAAK,MAAM;AAAA,EAC9C;AAGA,MAAI,cAAc,MAAM;AACtB,QAAI,CAAC,KAAK,YAAY,KAAK,SAAS,WAAW,GAAG;AAChD,aAAO;AAAA,IACT;AAGA,QAAI,KAAK,SAAS,SAAS,GAAG;AAC5B,aAAO;AAAA,IACT;AAGA,WAAO,YAAY,KAAK,SAAS,CAAC,CAAC;AAAA,EACrC;AAGA,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/report.ts","../src/utils.ts"],"sourcesContent":["import type { Node } from \"@rethinkhealth/hl7v2-ast\";\nimport type { VFile } from \"vfile\";\nimport type { Diagnostic } from \"./types\";\n\nexport type ReportOptions = {\n  node?: Node;\n  context?: Record<string, unknown>;\n};\n\n/**\n * Report a diagnostic to a vfile.\n *\n * Calls the diagnostic's message function with context and wires to vfile.\n *\n * @param file - The VFile to report to\n * @param rule - The diagnostic rule definition\n * @param options - Position and context data\n */\nexport function report(\n  file: VFile | null | undefined,\n  rule: Diagnostic,\n  options?: ReportOptions\n): void {\n  if (!file) {\n    return;\n  }\n\n  // Construct the rule ID from type, namespace, and code\n  const ruleId = `${rule.type}:${rule.namespace}:${rule.code}`;\n\n  const context = options?.context ?? {};\n  const message = rule.message(context);\n\n  // Create the vfile message\n  const vfileMessage = file.message(message, options?.node);\n\n  // Set the ruleId explicitly\n  vfileMessage.ruleId = ruleId;\n\n  // Set the help URL if provided\n  vfileMessage.url = rule.helpUrl;\n\n  // Set the description\n  vfileMessage.note = rule.description;\n\n  // Set source to the namespace (middle part of ruleId)\n  vfileMessage.source = rule.namespace;\n\n  // Map severity to fatal flag\n  switch (rule.severity) {\n    case \"error\":\n      vfileMessage.fatal = true;\n      break;\n    case \"warning\":\n      vfileMessage.fatal = false;\n      break;\n    case \"info\":\n      vfileMessage.fatal = null;\n      break;\n    case null:\n      vfileMessage.fatal = null;\n      break;\n    default:\n      vfileMessage.fatal = undefined;\n      break;\n  }\n}\n","import type { Nodes } from \"@rethinkhealth/hl7v2-ast\";\n\n// -------------\n// Delimiters\n// -------------\n\nexport const DEFAULT_DELIMITERS = {\n  field: \"|\",\n  component: \"^\",\n  repetition: \"~\",\n  subcomponent: \"&\",\n  escape: \"\\\\\",\n  segment: \"\\r\",\n};\n\n// -------------\n// General\n// -------------\n\n/**\n * Utility: check if a node is semantically empty\n */\nexport function isEmptyNode(node: Nodes | null | undefined): boolean {\n  if (!node) {\n    return true;\n  }\n\n  // If node has a \"value\" property (Subcomponent, maybe Component)\n  if (\"value\" in node) {\n    return !node.value || node.value.trim() === \"\";\n  }\n\n  // If node has children (Field, Component, Repetition, Segment, Root, etc.)\n  if (\"children\" in node) {\n    if (!node.children || node.children.length === 0) {\n      return true;\n    }\n\n    // If node has more than one child, then it is considered non-empty\n    if (node.children.length > 1) {\n      return false;\n    }\n\n    // If node has only one child, then it is considered empty if the child is also empty\n    return isEmptyNode(node.children[0]);\n  }\n\n  // Fallback: consider unknown node as non-empty\n  return false;\n}\n"],"mappings":";AAkBO,SAAS,OACd,MACA,MACA,SACM;AACN,MAAI,CAAC,MAAM;AACT;AAAA,EACF;AAGA,QAAM,SAAS,GAAG,KAAK,IAAI,IAAI,KAAK,SAAS,IAAI,KAAK,IAAI;AAE1D,QAAM,UAAU,SAAS,WAAW,CAAC;AACrC,QAAM,UAAU,KAAK,QAAQ,OAAO;AAGpC,QAAM,eAAe,KAAK,QAAQ,SAAS,SAAS,IAAI;AAGxD,eAAa,SAAS;AAGtB,eAAa,MAAM,KAAK;AAGxB,eAAa,OAAO,KAAK;AAGzB,eAAa,SAAS,KAAK;AAG3B,UAAQ,KAAK,UAAU;AAAA,IACrB,KAAK;AACH,mBAAa,QAAQ;AACrB;AAAA,IACF,KAAK;AACH,mBAAa,QAAQ;AACrB;AAAA,IACF,KAAK;AACH,mBAAa,QAAQ;AACrB;AAAA,IACF,KAAK;AACH,mBAAa,QAAQ;AACrB;AAAA,IACF;AACE,mBAAa,QAAQ;AACrB;AAAA,EACJ;AACF;;;AC5DO,IAAM,qBAAqB;AAAA,EAChC,OAAO;AAAA,EACP,WAAW;AAAA,EACX,YAAY;AAAA,EACZ,cAAc;AAAA,EACd,QAAQ;AAAA,EACR,SAAS;AACX;AASO,SAAS,YAAY,MAAyC;AACnE,MAAI,CAAC,MAAM;AACT,WAAO;AAAA,EACT;AAGA,MAAI,WAAW,MAAM;AACnB,WAAO,CAAC,KAAK,SAAS,KAAK,MAAM,KAAK,MAAM;AAAA,EAC9C;AAGA,MAAI,cAAc,MAAM;AACtB,QAAI,CAAC,KAAK,YAAY,KAAK,SAAS,WAAW,GAAG;AAChD,aAAO;AAAA,IACT;AAGA,QAAI,KAAK,SAAS,SAAS,GAAG;AAC5B,aAAO;AAAA,IACT;AAGA,WAAO,YAAY,KAAK,SAAS,CAAC,CAAC;AAAA,EACrC;AAGA,SAAO;AACT;","names":[]}

package/dist/report.d.ts

@@ -0,0 +1,18 @@
+import type { Node } from "@rethinkhealth/hl7v2-ast";
+import type { VFile } from "vfile";
+import type { Diagnostic } from "./types";
+export type ReportOptions = {
+    node?: Node;
+    context?: Record<string, unknown>;
+};
+/**
+ * Report a diagnostic to a vfile.
+ *
+ * Calls the diagnostic's message function with context and wires to vfile.
+ *
+ * @param file - The VFile to report to
+ * @param rule - The diagnostic rule definition
+ * @param options - Position and context data
+ */
+export declare function report(file: VFile | null | undefined, rule: Diagnostic, options?: ReportOptions): void;
+//# sourceMappingURL=report.d.ts.map

package/dist/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CACpB,IAAI,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,EAC9B,IAAI,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,aAAa,GACtB,IAAI,CA4CN"}

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Diagnostic definition.
+ *
+ * A diagnostic is a message about a problem in the HL7v2 message. It is used to report issues to the user.
+ *
+ * Diagnostics are defined per-package with type, namespace, and code that compose the `ruleId`.
+ *
+ * Diagnostics are used in conjunction with the `report()` function to report issues to the user.
+ */
+export type Diagnostic = Readonly<{
+    /**
+     * Tool/plugin category
+     */
+    type: "validator" | "lint" | "annotator" | "transformer" | "parser" | string;
+    /**
+     * Domain/concern (order, field, conformance, segment, group, datatype, etc.)
+     */
+    namespace: string;
+    /**
+     * Specific issue code (transition, required, acceptance, mismatch, etc.)
+     */
+    code: string;
+    /**
+     * Full description of the rule
+     */
+    description?: string;
+    /**
+     * Default severity
+     *
+     * @defaultValue 'info'
+     */
+    severity?: "error" | "warning" | "info" | null | undefined;
+    /**
+     * Message formatter function.
+     * Takes context and returns the formatted message.
+     * The function signature is self-documenting: it shows what context is required.
+     */
+    message: (context: Record<string, unknown>) => string;
+    /**
+     * Optional URL to documentation
+     */
+    helpUrl?: string;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC;IAChC;;OAEG;IACH,IAAI,EAAE,WAAW,GAAG,MAAM,GAAG,WAAW,GAAG,aAAa,GAAG,QAAQ,GAAG,MAAM,CAAC;IAE7E;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAE3D;;;;OAIG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;IAEtD;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rethinkhealth/hl7v2-utils",
   "description": "hl7v2 utilities",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "license": "MIT",
   "author": {
     "name": "Melek Somai",
@@ -22,8 +22,9 @@
     "tsup": "8.5.0",
     "typescript": "^5.8.3",
     "unist-builder": "^4.0.0",
+    "vfile": "^6.0.3",
     "vitest": "^3.2.4",
-    "@rethinkhealth/hl7v2-ast": "0.2.19",
+    "@rethinkhealth/hl7v2-ast": "0.2.21",
     "@rethinkhealth/testing": "0.0.1",
     "@rethinkhealth/tsconfig": "0.0.1"
   },