@glion/lint-profile-required-fields 0.23.0 → 0.24.0

package/README.md

@@ -1,10 +1,10 @@
 # @glion/lint-profile-required-fields
 
-Lint rule to validate required fields per HL7v2 profile.
+Lint rule that reports a required field that is missing or empty.
 
 ## What it does
 
-Flags segments whose required fields (as declared by the HL7v2 profile for the message's version) are missing or empty. The rule reads profile context attached to the file by `@glion/annotate-profile-context` and reports one message per missing required field. Segments without a known profile (for example Z-segments like `ZPD`) are silently skipped.
+Flags a field that the HL7v2 standard for the message's version marks `R` (required) when it is missing or empty. Segments the standard does not define, such as Z-segments, are skipped. It needs the plugin `@glion/annotate-profile-context` to run before it; `@glion/preset-lint-profile-recommended` includes it.
 
 ## Install
 
@@ -16,21 +16,22 @@ npm install @glion/lint-profile-required-fields
 
 ```ts
 import { hl7v2AnnotateProfileContext } from "@glion/annotate-profile-context";
-import { hl7v2Parser } from "@glion/parser";
 import hl7v2LintRequiredFields from "@glion/lint-profile-required-fields";
+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",
-  "PID|1||PATID1234^^^HOSP^MR||DOE^JANE||19800101|F",
+  "PID|1||||DOE^JANE||19800101|F",
 ].join("\r");
 
-const file = await unified()
-  .use(hl7v2Parser)
+const file = new VFile();
+await unified()
   .use(hl7v2AnnotateProfileContext)
   .use(hl7v2LintRequiredFields)
-  .process(message);
+  .run(parseHL7v2(message), file);
 
 console.error(reporter([file]));
 ```
@@ -39,9 +40,7 @@ console.error(reporter([file]));
 
 ### `unified().use(hl7v2LintRequiredFields)`
 
-A `unified` lint rule plugin. Takes no options.
-
-The plugin reads `file.data.profile` (populated by `@glion/annotate-profile-context`). If no profile context is present the rule exits silently. For each segment, it iterates `fieldDef.requiredSequences` and checks that the corresponding field at that 1-based position is present and non-empty.
+A `unified` lint rule plugin. Takes no options. Reports one message for each required field that is missing or empty.
 
 ```ts
 import type { Plugin } from "unified";
@@ -53,11 +52,11 @@ export default hl7v2LintRequiredFields;
 
 ## What it checks
 
-This rule flags fields declared `required: true` in the HL7v2 profile for the message's version when those fields are missing or empty on the corresponding segment.
+Every field marked `R` in the message's version is present and not empty. For example, in v2.5 `PID-3` (Patient Identifier List) and `PID-5` (Patient Name) are required.
 
 ### Valid
 
-`PID-3` (Patient Identifier List) and `PID-5` (Patient Name) are required in v2.5 and both are populated:
+`PID-3` and `PID-5` both have values:
 
 ```hl7
 MSH|^~\&|SENDER|FAC|RECV|RFAC|20250601120000||ADT^A01^ADT_A01|MSG00001|P|2.5
@@ -66,7 +65,7 @@ PID|1||PATID1234^^^HOSP^MR||DOE^JANE||19800101|F
 
 ### Invalid
 
-`PID-3` is empty, which violates the v2.5 profile for the `PID` segment:
+`PID-3` is empty:
 
 ```hl7
 MSH|^~\&|SENDER|FAC|RECV|RFAC|20250601120000||ADT^A01^ADT_A01|MSG00001|P|2.5
@@ -76,10 +75,15 @@ PID|1||||DOE^JANE||19800101|F
 Reported message:
 
 ```
-Required field PID-3 (Patient Identifier List) is missing or empty
+Field `PID-3` (Patient Identifier List) is empty; it is required.
 ```
 
-When the profile attaches a field name, it appears in parentheses after the position. Segments shorter than the highest required sequence produce one message per missing required field.
+A segment that ends before a required field, such as `PID|1`, produces one message per required field it does not reach:
+
+```
+Field `PID-3` (Patient Identifier List) is not present; it is required.
+Field `PID-5` (Patient Name) is not present; it is required.
+```
 
 ## Part of Glion
 

package/dist/index.d.ts

@@ -2,8 +2,9 @@ import type { Root } from "@glion/ast";
 /**
  * Lint rule that validates required fields per HL7v2 profile.
  *
- * For each segment, checks that all fields marked `required: true`
- * in the field definition are present and non-empty.
+ * For each segment, checks that every field whose optionality is `R` is
+ * present and non-empty. Fields whose optionality is `C`, `B`, or `W` are not
+ * checked.
  *
  * Segments without a known profile (e.g., Z-segments) are silently skipped.
  *

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAKvC;;;;;;;;;;;;;;;GAeG;AACH,QAAA,MAAM,uBAAuB,mDAiC5B,CAAC;AAEF,eAAe,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAYvC;;;;;;;;;;;;;;;;GAgBG;AACH,QAAA,MAAM,uBAAuB,mDAyC5B,CAAC;AAEF,eAAe,uBAAuB,CAAC"}

package/dist/index.js

@@ -2,11 +2,16 @@ import { SKIP, visit } from "@glion/util-visit";
 import { isEmptyNode } from "@glion/utils";
 import { lintRule } from "unified-lint-rule";
 //#region src/index.ts
+const messages = {
+	absentField: (field, name) => `Field \`${field}\` (${name}) is not present; it is required.`,
+	emptyField: (field, name) => `Field \`${field}\` (${name}) is empty; it is required.`
+};
 /**
 * Lint rule that validates required fields per HL7v2 profile.
 *
-* For each segment, checks that all fields marked `required: true`
-* in the field definition are present and non-empty.
+* For each segment, checks that every field whose optionality is `R` is
+* present and non-empty. Fields whose optionality is `C`, `B`, or `W` are not
+* checked.
 *
 * Segments without a known profile (e.g., Z-segments) are silently skipped.
 *
@@ -18,26 +23,31 @@ import { lintRule } from "unified-lint-rule";
 *   unified().use(hl7v2AnnotateProfileContext).use(hl7v2LintRequiredFields);
 *   ```;
 */
-const hl7v2LintRequiredFields = lintRule({ origin: "hl7v2-lint:required-fields" }, (tree, file) => {
+const hl7v2LintRequiredFields = lintRule({
+	origin: "hl7v2-lint:required-fields",
+	url: "https://github.com/rethinkhealth/glion/tree/main/packages/lint-profile-required-fields#readme"
+}, (tree, file) => {
 	const ctx = file.data.profile;
 	if (!ctx) return;
-	visit(tree, "segment", (node, parents) => {
-		const fieldDef = ctx.fields.get(node.name);
-		if (!fieldDef) return SKIP;
-		for (const sequence of fieldDef.requiredSequences) {
-			const fieldNode = node.children[sequence - 1];
-			if (!fieldNode || isEmptyNode(fieldNode)) {
-				const profile = fieldDef.bySequence.get(sequence);
-				const name = profile?.name ? ` (${profile.name})` : "";
-				file.message(`Required field ${node.name}-${sequence}${name} is missing or empty`, {
-					ancestors: [
-						...parents,
-						node,
-						...fieldNode ? [fieldNode] : []
-					],
-					place: fieldNode?.position ?? node.position
-				});
-			}
+	visit(tree, "segment", (segment, segmentAncestors) => {
+		const fields = ctx.fields.get(segment.name);
+		if (!fields) return SKIP;
+		for (const sequence of fields.requiredSequences) {
+			const id = `${segment.name}-${sequence}`;
+			const name = fields.bySequence.get(sequence)?.name ?? "";
+			const field = segment.children[sequence - 1];
+			if (!field) file.message(messages.absentField(id, name), {
+				ancestors: [...segmentAncestors, segment],
+				place: segment.position
+			});
+			else if (isEmptyNode(field)) file.message(messages.emptyField(id, name), {
+				ancestors: [
+					...segmentAncestors,
+					segment,
+					field
+				],
+				place: field.position
+			});
 		}
 		return SKIP;
 	});

package/dist/index.js.map

@@ -1 +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\";\nimport type { Root } from \"@glion/ast\";\nimport { SKIP, visit } from \"@glion/util-visit\";\nimport { isEmptyNode } from \"@glion/utils\";\nimport { lintRule } from \"unified-lint-rule\";\n\n/**\n * Lint rule that validates required fields per HL7v2 profile.\n *\n * For each segment, checks that all fields marked `required: true`\n * in the field definition are present and non-empty.\n *\n * Segments without a known profile (e.g., Z-segments) are silently skipped.\n *\n * Requires `@glion/annotate-profile-context` to run first\n * so that `file.data.fields` is populated.\n *\n * @example\n *   ```typescript\n *   unified().use(hl7v2AnnotateProfileContext).use(hl7v2LintRequiredFields);\n *   ```;\n */\nconst hl7v2LintRequiredFields = lintRule<Root>(\n  { origin: \"hl7v2-lint:required-fields\" },\n  (tree, file) => {\n    const ctx = file.data.profile;\n    if (!ctx) {\n      return;\n    }\n\n    visit(tree, \"segment\", (node, parents) => {\n      const fieldDef = ctx.fields.get(node.name);\n      if (!fieldDef) {\n        return SKIP;\n      }\n\n      for (const sequence of fieldDef.requiredSequences) {\n        const fieldNode = node.children[sequence - 1];\n\n        if (!fieldNode || isEmptyNode(fieldNode)) {\n          const profile = fieldDef.bySequence.get(sequence);\n          const name = profile?.name ? ` (${profile.name})` : \"\";\n          file.message(\n            `Required field ${node.name}-${sequence}${name} is missing or empty`,\n            {\n              ancestors: [...parents, node, ...(fieldNode ? [fieldNode] : [])],\n              place: fieldNode?.position ?? node.position,\n            }\n          );\n        }\n      }\n\n      return SKIP;\n    });\n  }\n);\n\nexport default hl7v2LintRequiredFields;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAuBA,MAAM,0BAA0B,SAC9B,EAAE,QAAQ,8BAA8B,GACvC,MAAM,SAAS;CACd,MAAM,MAAM,KAAK,KAAK;AACtB,KAAI,CAAC,IACH;AAGF,OAAM,MAAM,YAAY,MAAM,YAAY;EACxC,MAAM,WAAW,IAAI,OAAO,IAAI,KAAK,KAAK;AAC1C,MAAI,CAAC,SACH,QAAO;AAGT,OAAK,MAAM,YAAY,SAAS,mBAAmB;GACjD,MAAM,YAAY,KAAK,SAAS,WAAW;AAE3C,OAAI,CAAC,aAAa,YAAY,UAAU,EAAE;IACxC,MAAM,UAAU,SAAS,WAAW,IAAI,SAAS;IACjD,MAAM,OAAO,SAAS,OAAO,KAAK,QAAQ,KAAK,KAAK;AACpD,SAAK,QACH,kBAAkB,KAAK,KAAK,GAAG,WAAW,KAAK,uBAC/C;KACE,WAAW;MAAC,GAAG;MAAS;MAAM,GAAI,YAAY,CAAC,UAAU,GAAG,EAAE;MAAE;KAChE,OAAO,WAAW,YAAY,KAAK;KACpC,CACF;;;AAIL,SAAO;GACP;EAEL"}
+{"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\";\nimport type { Root } from \"@glion/ast\";\nimport { SKIP, visit } from \"@glion/util-visit\";\nimport { isEmptyNode } from \"@glion/utils\";\nimport { lintRule } from \"unified-lint-rule\";\n\nconst messages = {\n  absentField: (field: string, name: string) =>\n    `Field \\`${field}\\` (${name}) is not present; it is required.`,\n  emptyField: (field: string, name: string) =>\n    `Field \\`${field}\\` (${name}) is empty; it is required.`,\n} as const;\n\n/**\n * Lint rule that validates required fields per HL7v2 profile.\n *\n * For each segment, checks that every field whose optionality is `R` is\n * present and non-empty. Fields whose optionality is `C`, `B`, or `W` are not\n * checked.\n *\n * Segments without a known profile (e.g., Z-segments) are silently skipped.\n *\n * Requires `@glion/annotate-profile-context` to run first\n * so that `file.data.fields` is populated.\n *\n * @example\n *   ```typescript\n *   unified().use(hl7v2AnnotateProfileContext).use(hl7v2LintRequiredFields);\n *   ```;\n */\nconst hl7v2LintRequiredFields = lintRule<Root>(\n  {\n    origin: \"hl7v2-lint:required-fields\",\n    url: \"https://github.com/rethinkhealth/glion/tree/main/packages/lint-profile-required-fields#readme\",\n  },\n  (tree, file) => {\n    const ctx = file.data.profile;\n    if (!ctx) {\n      return;\n    }\n\n    visit(tree, \"segment\", (segment, segmentAncestors) => {\n      const fields = ctx.fields.get(segment.name);\n      if (!fields) {\n        return SKIP;\n      }\n\n      // Loop over the profile's required fields, not the message's: a field\n      // the segment ends before has no node to visit.\n      for (const sequence of fields.requiredSequences) {\n        const id = `${segment.name}-${sequence}`;\n        const name = fields.bySequence.get(sequence)?.name ?? \"\";\n        const field = segment.children[sequence - 1];\n\n        if (!field) {\n          // Reported on the segment, the closest node the message has.\n          file.message(messages.absentField(id, name), {\n            ancestors: [...segmentAncestors, segment],\n            place: segment.position,\n          });\n        } else if (isEmptyNode(field)) {\n          file.message(messages.emptyField(id, name), {\n            ancestors: [...segmentAncestors, segment, field],\n            place: field.position,\n          });\n        }\n      }\n\n      return SKIP;\n    });\n  }\n);\n\nexport default hl7v2LintRequiredFields;\n"],"mappings":";;;;AAOA,MAAM,WAAW;CACf,cAAc,OAAe,SAC3B,WAAW,MAAM,MAAM,KAAK;CAC9B,aAAa,OAAe,SAC1B,WAAW,MAAM,MAAM,KAAK;CAC/B;;;;;;;;;;;;;;;;;;AAmBD,MAAM,0BAA0B,SAC9B;CACE,QAAQ;CACR,KAAK;CACN,GACA,MAAM,SAAS;CACd,MAAM,MAAM,KAAK,KAAK;AACtB,KAAI,CAAC,IACH;AAGF,OAAM,MAAM,YAAY,SAAS,qBAAqB;EACpD,MAAM,SAAS,IAAI,OAAO,IAAI,QAAQ,KAAK;AAC3C,MAAI,CAAC,OACH,QAAO;AAKT,OAAK,MAAM,YAAY,OAAO,mBAAmB;GAC/C,MAAM,KAAK,GAAG,QAAQ,KAAK,GAAG;GAC9B,MAAM,OAAO,OAAO,WAAW,IAAI,SAAS,EAAE,QAAQ;GACtD,MAAM,QAAQ,QAAQ,SAAS,WAAW;AAE1C,OAAI,CAAC,MAEH,MAAK,QAAQ,SAAS,YAAY,IAAI,KAAK,EAAE;IAC3C,WAAW,CAAC,GAAG,kBAAkB,QAAQ;IACzC,OAAO,QAAQ;IAChB,CAAC;YACO,YAAY,MAAM,CAC3B,MAAK,QAAQ,SAAS,WAAW,IAAI,KAAK,EAAE;IAC1C,WAAW;KAAC,GAAG;KAAkB;KAAS;KAAM;IAChD,OAAO,MAAM;IACd,CAAC;;AAIN,SAAO;GACP;EAEL"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glion/lint-profile-required-fields",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Lint rule to validate required fields per HL7v2 profile",
   "keywords": [
     "health",
@@ -34,9 +34,9 @@
   },
   "dependencies": {
     "unified-lint-rule": "3.0.1",
-    "@glion/ast": "0.23.0",
-    "@glion/util-visit": "0.23.0",
-    "@glion/utils": "0.23.0"
+    "@glion/ast": "0.24.0",
+    "@glion/util-visit": "0.24.0",
+    "@glion/utils": "0.24.0"
   },
   "devDependencies": {
     "@types/node": "25.6.0",
@@ -47,8 +47,8 @@
     "unified": "^11.0.5",
     "vfile": "^6.0.3",
     "vitest": "4.1.11",
-    "@glion/annotate-profile-context": "0.23.0",
-    "@glion/builder": "0.23.0",
+    "@glion/annotate-profile-context": "0.24.0",
+    "@glion/builder": "0.24.0",
     "@glion/check-readme": "0.18.0",
     "@glion/testing": "0.18.0",
     "@glion/tsconfig": "0.18.0"