validate.go

// Copyright 2026 Joshua Jones <joshua.jones.software@gmail.com>
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package hl7

import "strconv"

// Severity indicates the severity of a validation issue.
type Severity int

const (
	SeverityError Severity = iota
	SeverityWarning
)

func (s Severity) String() string {
	switch s {
	case SeverityError:
		return "error"
	case SeverityWarning:
		return "warning"
	default:
		return "unknown"
	}
}

// Issue codes for machine-readable categorization of validation findings.
const (
	CodeUnknownStructure   = "UNKNOWN_STRUCTURE"
	CodeRequiredSegment    = "REQUIRED_SEGMENT"
	CodeUnexpectedSegment  = "UNEXPECTED_SEGMENT"
	CodeSegmentCardinality = "SEGMENT_CARDINALITY"
	CodeRequiredField      = "REQUIRED_FIELD"
	CodeFieldLength        = "FIELD_LENGTH"
	CodeFieldCardinality   = "FIELD_CARDINALITY"
	CodeRequiredComponent  = "REQUIRED_COMPONENT"
	CodeComponentLength    = "COMPONENT_LENGTH"
	CodeInvalidFormat      = "INVALID_FORMAT"
	CodeInvalidTableValue  = "INVALID_TABLE_VALUE"
	CodeInvalidValue       = "INVALID_VALUE"
)

// Issue represents a single validation finding.
type Issue struct {
	Severity    Severity
	Location    string // terser-style location, e.g., "PID-3.1" or segment type
	Code        string // machine-readable code, e.g., CodeRequiredField
	Description string // human-readable description
}

func (i Issue) String() string {
	return "[" + i.Severity.String() + "] " + i.Location + ": " + i.Description + " (" + i.Code + ")"
}

// ValidationResult holds the outcome of message validation.
type ValidationResult struct {
	Valid  bool
	Issues []Issue
}

// Validate checks a parsed message against a schema and returns all findings.
//
// Validation runs in three phases:
//  1. Structure — checks segment presence, order, and cardinality against the
//     MessageDef looked up from MSH-9.
//  2. Content — checks field presence, length, cardinality, data type format,
//     and coded table values against SegmentDef, DataTypeDef, and TableDef.
//     Also runs FieldCheckFunc and SegmentCheckFunc validators if defined.
//  3. Custom checks — runs MessageCheckFunc validators from schema.Checks for
//     cross-segment business rules.
//
// Each phase runs only if the relevant definitions exist in the schema.
// A nil receiver or nil schema returns a valid result with no issues.
func (m *Message) Validate(schema *Schema) *ValidationResult {
	if m == nil || schema == nil {
		return &ValidationResult{Valid: true}
	}
	v := &validator{msg: m, schema: schema}
	v.validateStructure()
	v.validateFields()
	v.validateChecks()
	return &ValidationResult{
		Valid:  !v.hasErr,
		Issues: v.issues,
	}
}

type validator struct {
	msg    *Message
	schema *Schema
	issues []Issue
	hasErr bool
}

func (v *validator) addIssue(sev Severity, loc, code, desc string) {
	v.issues = append(v.issues, Issue{
		Severity:    sev,
		Location:    loc,
		Code:        code,
		Description: desc,
	})
	if sev == SeverityError {
		v.hasErr = true
	}
}

func (v *validator) appendIssues(issues []Issue) {
	for i := range issues {
		v.issues = append(v.issues, issues[i])
		if issues[i].Severity == SeverityError {
			v.hasErr = true
		}
	}
}

// --- Phase 3: Custom Message Checks ---

func (v *validator) validateChecks() {
	for _, fn := range v.schema.Checks {
		v.appendIssues(fn(v.msg))
	}
}

// --- Phase 1: Structure Validation ---

func (v *validator) validateStructure() {
	msgDef := v.lookupMessageDef()
	if msgDef == nil {
		return
	}
	segments := v.msg.Segments()
	pos := v.matchElements(msgDef.Elements, segments, 0)
	for i := pos; i < len(segments); i++ {
		typ := segments[i].Type()
		v.addIssue(SeverityError, typ, CodeUnexpectedSegment,
			"Unexpected segment "+typ)
	}
}

func (v *validator) lookupMessageDef() *MessageDef {
	if v.schema.Messages == nil {
		return nil
	}
	structID := v.msg.Get("MSH-9.3").String()
	if structID == "" {
		code := v.msg.Get("MSH-9.1").String()
		event := v.msg.Get("MSH-9.2").String()
		if code != "" && event != "" {
			structID = code + "_" + event
		}
	}
	if structID == "" {
		return nil
	}
	def, ok := v.schema.Messages[structID]
	if !ok {
		v.addIssue(SeverityError, "MSH-9", CodeUnknownStructure,
			"No message definition found for "+structID)
		return nil
	}
	return def
}

// matchElements walks a list of element definitions and tries to consume
// matching segments starting at pos. Returns the new position after matching.
func (v *validator) matchElements(elems []Element, segs []Segment, pos int) int {
	for _, elem := range elems {
		if elem.Segment != "" {
			pos = v.matchSegmentElem(elem, segs, pos)
		} else if len(elem.Elements) > 0 {
			pos = v.matchGroupElem(elem, segs, pos)
		}
	}
	return pos
}

func (v *validator) matchSegmentElem(elem Element, segs []Segment, pos int) int {
	count := 0
	max := elem.Max
	for pos < len(segs) && segs[pos].Type() == elem.Segment {
		count++
		pos++
		if max > 0 && count >= max {
			break
		}
	}
	if count < elem.Min {
		v.addIssue(SeverityError, elem.Segment, CodeRequiredSegment,
			"Required segment "+elem.Segment+" is missing")
	}
	// Check for additional occurrences beyond max.
	if max > 0 {
		extra := 0
		for pos < len(segs) && segs[pos].Type() == elem.Segment {
			extra++
			pos++
		}
		if extra > 0 {
			v.addIssue(SeverityError, elem.Segment, CodeSegmentCardinality,
				"Segment "+elem.Segment+" appears "+strconv.Itoa(count+extra)+" times, max is "+strconv.Itoa(max))
		}
	}
	return pos
}

func (v *validator) matchGroupElem(elem Element, segs []Segment, pos int) int {
	count := 0
	max := elem.Max
	for {
		start := pos
		// Snapshot before probing so we can roll back spurious errors
		// if the group doesn't consume any segments this iteration.
		snap := v.snapshotIssues()
		newPos := v.matchElements(elem.Elements, segs, pos)
		if newPos == start {
			v.restoreIssues(snap)
			break
		}
		count++
		pos = newPos
		if max > 0 && count >= max {
			break
		}
	}
	if count < elem.Min {
		name := elem.Group
		if name == "" {
			name = "unnamed"
		}
		v.addIssue(SeverityError, "", CodeRequiredSegment,
			"Required group "+name+" is missing")
	}
	return pos
}

type issueSnapshot struct {
	count  int
	hasErr bool
}

func (v *validator) snapshotIssues() issueSnapshot {
	return issueSnapshot{count: len(v.issues), hasErr: v.hasErr}
}

func (v *validator) restoreIssues(s issueSnapshot) {
	v.issues = v.issues[:s.count]
	v.hasErr = s.hasErr
}

// --- Phase 2: Content Validation (fields, data types, tables) ---

func (v *validator) validateFields() {
	if v.schema.Segments == nil {
		return
	}
	segments := v.msg.Segments()
	counts := make(map[string]int)
	for i := range segments {
		seg := &segments[i]
		typ := seg.Type()
		idx := counts[typ]
		counts[typ]++
		segDef, ok := v.schema.Segments[typ]
		if !ok {
			continue
		}
		segLoc := formatSegLoc(typ, idx)
		v.validateSegmentFields(seg, segDef, segLoc)
	}
}

func (v *validator) validateSegmentFields(seg *Segment, def *SegmentDef, segLoc string) {
	for _, fd := range def.Fields {
		field := seg.Field(fd.Index)

		if fd.Required && !field.HasValue() {
			loc := segLoc + "-" + strconv.Itoa(fd.Index)
			desc := "Required field " + loc + " is missing"
			if fd.Name != "" {
				desc = "Required field " + loc + " (" + fd.Name + ") is missing"
			}
			v.addIssue(SeverityError, loc, CodeRequiredField, desc)
		}

		if field.IsEmpty() || field.IsNull() {
			continue
		}

		repCount := field.RepetitionCount()
		if !fd.Repeating && repCount > 1 {
			loc := segLoc + "-" + strconv.Itoa(fd.Index)
			v.addIssue(SeverityError, loc, CodeFieldCardinality,
				"Field "+loc+" repeats "+strconv.Itoa(repCount)+" times but is not repeating")
		}

		for ri := range repCount {
			rep := field.Rep(ri)
			v.validateRep(rep, fd, segLoc, ri, repCount)
		}

		if fd.Check != nil {
			v.appendIssues(fd.Check(field))
		}
	}

	if def.Check != nil {
		v.appendIssues(def.Check(seg))
	}
}

func (v *validator) validateRep(rep Repetition, fd FieldDef, segLoc string, repIdx, repCount int) {
	raw := rep.Raw()

	if fd.Value != "" && string(raw) != fd.Value {
		loc := buildFieldLoc(segLoc, fd.Index, repIdx, repCount)
		v.addIssue(SeverityError, loc, CodeInvalidValue,
			"Field "+loc+" has value "+strconv.Quote(string(raw))+", expected "+strconv.Quote(fd.Value))
		return
	}

	if fd.MaxLength > 0 && len(raw) > fd.MaxLength {
		loc := buildFieldLoc(segLoc, fd.Index, repIdx, repCount)
		v.addIssue(SeverityError, loc, CodeFieldLength,
			"Field "+loc+" exceeds max length "+strconv.Itoa(fd.MaxLength)+" (got "+strconv.Itoa(len(raw))+")")
	}

	var dtDef *DataTypeDef
	if fd.DataType != "" && v.schema.DataTypes != nil {
		dtDef = v.schema.DataTypes[fd.DataType]
	}

	if dtDef != nil && len(dtDef.Components) > 0 {
		v.validateComposite(rep, dtDef, segLoc, fd.Index, repIdx, repCount)
	} else {
		if fd.DataType != "" && !isValidPrimitiveFormat(raw, fd.DataType) {
			loc := buildFieldLoc(segLoc, fd.Index, repIdx, repCount)
			v.addIssue(SeverityError, loc, CodeInvalidFormat,
				"Value "+strconv.Quote(string(raw))+" at "+loc+" is not a valid "+fd.DataType)
		}
		if fd.Table != "" && !v.isInTable(raw, fd.Table) {
			loc := buildFieldLoc(segLoc, fd.Index, repIdx, repCount)
			v.addIssue(SeverityError, loc, CodeInvalidTableValue,
				"Value "+strconv.Quote(string(raw))+" at "+loc+" is not in table "+fd.Table)
		}
	}
}

func (v *validator) validateComposite(rep Repetition, dtDef *DataTypeDef, segLoc string, fieldIdx, repIdx, repCount int) {
	for _, cd := range dtDef.Components {
		comp := rep.Component(cd.Index)

		if cd.Required && comp.IsEmpty() {
			loc := buildCompLoc(segLoc, fieldIdx, repIdx, repCount, cd.Index)
			desc := "Required component " + loc + " is missing"
			if cd.Name != "" {
				desc = "Required component " + loc + " (" + cd.Name + ") is missing"
			}
			v.addIssue(SeverityError, loc, CodeRequiredComponent, desc)
			continue
		}
		if comp.IsEmpty() {
			continue
		}
		raw := comp.Raw()
		if cd.Value != "" && string(raw) != cd.Value {
			loc := buildCompLoc(segLoc, fieldIdx, repIdx, repCount, cd.Index)
			v.addIssue(SeverityError, loc, CodeInvalidValue,
				"Component "+loc+" has value "+strconv.Quote(string(raw))+", expected "+strconv.Quote(cd.Value))
			continue
		}
		if cd.MaxLength > 0 && len(raw) > cd.MaxLength {
			loc := buildCompLoc(segLoc, fieldIdx, repIdx, repCount, cd.Index)
			v.addIssue(SeverityError, loc, CodeComponentLength,
				"Component "+loc+" exceeds max length "+strconv.Itoa(cd.MaxLength)+" (got "+strconv.Itoa(len(raw))+")")
		}
		if cd.DataType != "" && !isValidPrimitiveFormat(raw, cd.DataType) {
			loc := buildCompLoc(segLoc, fieldIdx, repIdx, repCount, cd.Index)
			v.addIssue(SeverityError, loc, CodeInvalidFormat,
				"Value "+strconv.Quote(string(raw))+" at "+loc+" is not a valid "+cd.DataType)
		}
		if cd.Table != "" && !v.isInTable(raw, cd.Table) {
			loc := buildCompLoc(segLoc, fieldIdx, repIdx, repCount, cd.Index)
			v.addIssue(SeverityError, loc, CodeInvalidTableValue,
				"Value "+strconv.Quote(string(raw))+" at "+loc+" is not in table "+cd.Table)
		}
	}
}

// --- Location builders (only called on error paths) ---

func buildFieldLoc(segLoc string, field, repIdx, repCount int) string {
	loc := segLoc + "-" + strconv.Itoa(field)
	if repCount > 1 {
		loc += "[" + strconv.Itoa(repIdx) + "]"
	}
	return loc
}

func buildCompLoc(segLoc string, field, repIdx, repCount, comp int) string {
	return buildFieldLoc(segLoc, field, repIdx, repCount) + "." + strconv.Itoa(comp)
}

func formatSegLoc(typ string, idx int) string {
	if idx == 0 {
		return typ
	}
	return typ + "(" + strconv.Itoa(idx) + ")"
}

// --- Primitive Format Validation ---
//
// Format validators operate on raw bytes to avoid Unescape allocations.
// Escape sequences in date, numeric, or coded value fields are pathological
// and would correctly fail format validation on the raw representation.

func isValidPrimitiveFormat(raw []byte, dataType string) bool {
	switch dataType {
	case "DT":
		return isValidDT(raw)
	case "TM":
		return isValidTM(raw)
	case "DTM", "TS":
		return isValidDTM(raw)
	case "NM":
		return isValidNM(raw)
	case "SI":
		return isValidSI(raw)
	default:
		return true
	}
}

// isValidDT validates the HL7 DT (date) format: YYYY[MM[DD]].
func isValidDT(b []byte) bool {
	n := len(b)
	if n != 4 && n != 6 && n != 8 {
		return false
	}
	if !allDigitsB(b) {
		return false
	}
	if n >= 6 {
		month := parseTwoDigitsB(b[4:6])
		if month < 1 || month > 12 {
			return false
		}
	}
	if n == 8 {
		day := parseTwoDigitsB(b[6:8])
		if day < 1 || day > 31 {
			return false
		}
	}
	return true
}

// isValidTM validates the HL7 TM (time) format: HH[MM[SS[.S[S[S[S]]]]]]]][+/-ZZZZ].
func isValidTM(b []byte) bool {
	if len(b) < 2 {
		return false
	}
	base, _ := stripTimezoneB(b)
	base, ok := stripFractionalB(base)
	if !ok {
		return false
	}
	n := len(base)
	if n != 2 && n != 4 && n != 6 {
		return false
	}
	if !allDigitsB(base) {
		return false
	}
	return validateTimeDigitsB(base)
}

// isValidDTM validates the HL7 DTM/TS (datetime) format:
// YYYY[MM[DD[HH[MM[SS[.S[S[S[S]]]]]]]]]]][+/-ZZZZ].
func isValidDTM(b []byte) bool {
	if len(b) < 4 {
		return false
	}
	base, _ := stripTimezoneB(b)
	base, ok := stripFractionalB(base)
	if !ok {
		return false
	}
	n := len(base)
	if n < 4 || n > 14 || n%2 != 0 {
		return false
	}
	if !allDigitsB(base) {
		return false
	}
	if n >= 6 {
		month := parseTwoDigitsB(base[4:6])
		if month < 1 || month > 12 {
			return false
		}
	}
	if n >= 8 {
		day := parseTwoDigitsB(base[6:8])
		if day < 1 || day > 31 {
			return false
		}
	}
	if n >= 10 {
		return validateTimeDigitsB(base[8:])
	}
	return true
}

// isValidNM validates the HL7 NM (numeric) format: [+/-]digits[.digits].
func isValidNM(b []byte) bool {
	if len(b) == 0 {
		return false
	}
	i := 0
	if b[0] == '+' || b[0] == '-' {
		i++
	}
	if i >= len(b) {
		return false
	}
	hasDigit := false
	hasDot := false
	for ; i < len(b); i++ {
		if b[i] >= '0' && b[i] <= '9' {
			hasDigit = true
		} else if b[i] == '.' && !hasDot {
			hasDot = true
		} else {
			return false
		}
	}
	return hasDigit
}

// isValidSI validates the HL7 SI (sequence ID) format: non-negative integer.
func isValidSI(b []byte) bool {
	if len(b) == 0 {
		return false
	}
	return allDigitsB(b)
}

// --- Format validation helpers ---

func allDigitsB(b []byte) bool {
	for _, c := range b {
		if c < '0' || c > '9' {
			return false
		}
	}
	return true
}

func parseTwoDigitsB(b []byte) int {
	return int(b[0]-'0')*10 + int(b[1]-'0')
}

func stripTimezoneB(b []byte) ([]byte, bool) {
	n := len(b)
	if n >= 5 {
		if c := b[n-5]; c == '+' || c == '-' {
			if allDigitsB(b[n-4:]) {
				return b[:n-5], true
			}
		}
	}
	return b, false
}

func stripFractionalB(b []byte) ([]byte, bool) {
	for i, c := range b {
		if c == '.' {
			frac := b[i+1:]
			if len(frac) < 1 || len(frac) > 4 || !allDigitsB(frac) {
				return b, false
			}
			return b[:i], true
		}
	}
	return b, true
}

func validateTimeDigitsB(b []byte) bool {
	n := len(b)
	if n >= 2 {
		if parseTwoDigitsB(b[0:2]) > 23 {
			return false
		}
	}
	if n >= 4 {
		if parseTwoDigitsB(b[2:4]) > 59 {
			return false
		}
	}
	if n >= 6 {
		if parseTwoDigitsB(b[4:6]) > 59 {
			return false
		}
	}
	return true
}

// --- Table Validation ---

func (v *validator) isInTable(raw []byte, tableID string) bool {
	if v.schema.Tables == nil {
		return true
	}
	td, ok := v.schema.Tables[tableID]
	if !ok {
		return true
	}
	// string(raw) in a map index expression is optimized by the compiler
	// to avoid allocation (mapaccess optimization).
	_, valid := td.Values[string(raw)]
	return valid
}