feat: Added a test tab in awards to test the matching

2026-07-14 16:32:49 +02:00
parent 4fe0405432
commit 0c6f8e2d68
8 changed files with 574 additions and 13 deletions
@@ -16,6 +16,7 @@ import (
 	"embed"
 	"encoding/json"
 	"errors"
+	"fmt"
 	"regexp"
 	"sort"
 	"strconv"
@@ -715,9 +716,113 @@ func searchOne(field, matchBy string, re *regexp.Regexp, exact bool, leading, tr
 	return found
 }

+// ── Explain: why did (or didn't) this QSO count for this award? ──────────────
+//
+// An award that silently matches nothing is the hardest kind of bug to see: the
+// UI shows an empty column and the operator has no way to tell whether the QSO is
+// out of scope, the field is empty, the rule looked in the wrong place, or the
+// reference simply isn't on the list. Explain replays the matcher on ONE QSO and
+// reports every step it took.
+
+// Rejected is a candidate a rule produced that did not survive.
+type Rejected struct {
+	Candidate string `json:"candidate"`
+	Reason    string `json:"reason"`
+}
+
+// Step is one matching rule as it actually ran.
+type Step struct {
+	Rule       string     `json:"rule"`                  // "primary", "OR 1", …
+	Field      string     `json:"field"`                 // the QSO field it scanned
+	MatchBy    string     `json:"match_by,omitempty"`    // code | description | pattern
+	Exact      bool       `json:"exact,omitempty"`       // whole field IS the reference
+	Pattern    string     `json:"pattern,omitempty"`     // the rule's regex, if any
+	FieldValue string     `json:"field_value,omitempty"` // what the field actually held
+	Candidates []string   `json:"candidates,omitempty"`  // what the rule produced, before validation
+	Kept       []string   `json:"kept,omitempty"`        // what survived the reference list
+	Rejected   []Rejected `json:"rejected,omitempty"`    // and what didn't, with the reason
+	Skipped    bool       `json:"skipped,omitempty"`     // never ran: an earlier rule already matched
+	Error      string     `json:"error,omitempty"`       // e.g. a bad regex, which SKIPS the rule
+}
+
+// Explanation is the full account of one QSO against one award.
+type Explanation struct {
+	Code       string   `json:"code"`
+	InScope    bool     `json:"in_scope"`
+	ScopeError string   `json:"scope_error,omitempty"` // why the QSO is out of scope
+	Predefined bool     `json:"predefined"`            // matches are validated against a reference list
+	RefCount   int      `json:"ref_count"`             // size of that list
+	Steps      []Step   `json:"steps"`
+	Manual     []string `json:"manual,omitempty"` // references the operator assigned by hand
+	Result     []string `json:"result"`           // what the QSO finally counts for
+}
+
+// Explain runs the matcher on a single QSO and reports what it did. It goes
+// through the SAME code path as Compute — not a re-implementation — so what it
+// shows is what actually happens.
+func Explain(d Def, metas []RefMeta, q *qso.QSO) Explanation {
+	ex := Explanation{Code: d.Code, Steps: []Step{}, Result: []string{}}
+	rl := NewRefList(metas)
+	ex.Predefined = len(metas) > 0 && !d.Dynamic
+	ex.RefCount = len(metas)
+
+	var why string
+	if !inScopeWhy(&d, q, &why) {
+		ex.ScopeError = why
+		return ex // out of scope: no rule ever runs, and saying so IS the answer
+	}
+	ex.InScope = true
+
+	var re *regexp.Regexp
+	if p := strings.TrimSpace(d.Pattern); p != "" {
+		c, err := compileAwardRE(p)
+		if err != nil {
+			ex.Steps = append(ex.Steps, Step{Rule: "primary", Field: d.Field, Pattern: d.Pattern,
+				Error: "bad regex: " + err.Error()})
+			return ex
+		}
+		re = c
+	}
+	candidatesTrace(&d, re, q, rl, len(metas) > 0, &ex)
+	return ex
+}
+
 func candidates(d *Def, re *regexp.Regexp, q *qso.QSO, rl refList, hasList bool) []string {
+	return candidatesTrace(d, re, q, rl, hasList, nil)
+}
+
+// candidatesTrace is the matcher. ex is optional: when non-nil (only Explain
+// passes it) each rule records what it scanned, what it produced and what was
+// rejected. The tracing MUST live inside the real matcher rather than in a
+// parallel "explain" implementation — a trace that can drift from the code it
+// describes is worse than no trace, because it is believed.
+func candidatesTrace(d *Def, re *regexp.Regexp, q *qso.QSO, rl refList, hasList bool, ex *Explanation) []string {
 	predefined := hasList && !d.Dynamic

+	// run executes one rule and, when tracing, records it.
+	run := func(label, field, matchBy, pattern string, rex *regexp.Regexp, exact bool, leading, trailing, prefix string) []string {
+		raw := searchOne(field, matchBy, rex, exact, leading, trailing, prefix, q, rl, predefined)
+		kept := keepRefs(predefined, rl, raw)
+		if ex != nil {
+			s := Step{Rule: label, Field: field, MatchBy: matchBy, Exact: exact, Pattern: pattern,
+				FieldValue: strings.TrimSpace(stripAffix(fieldRaw(field, q), leading, trailing)),
+				Candidates: raw, Kept: kept}
+			keptSet := map[string]struct{}{}
+			for _, k := range kept {
+				keptSet[k] = struct{}{}
+			}
+			for _, c := range raw {
+				n := normalizeRef(c)
+				if _, ok := keptSet[n]; ok {
+					continue
+				}
+				s.Rejected = append(s.Rejected, rejection(predefined, rl, n))
+			}
+			ex.Steps = append(ex.Steps, s)
+		}
+		return kept
+	}
+
 	// Primary search first; the OR rules are ordered FALLBACKS — try the next
 	// only while nothing has matched yet, and stop at the first that yields a
 	// reference (short-circuit). So a province already found by NAME isn't also
@@ -730,18 +835,30 @@ func candidates(d *Def, re *regexp.Regexp, q *qso.QSO, rl refList, hasList bool)
 	// Testing the raw candidate would call that a hit, skip every fallback, and
 	// only then drop it as unlisted — leaving the QSO unmatched even though the
 	// next rule ("find the code inside the QTH") would have found BG.
-	found := keepRefs(predefined, rl, searchOne(d.Field, d.MatchBy, re, d.ExactMatch, d.LeadingStr, d.TrailingStr, "", q, rl, predefined))
-	for i := 0; len(found) == 0 && i < len(d.OrRules); i++ {
+	found := run("primary", d.Field, d.MatchBy, d.Pattern, re, d.ExactMatch, d.LeadingStr, d.TrailingStr, "")
+	for i := range d.OrRules {
 		r := &d.OrRules[i]
+		label := fmt.Sprintf("OR %d", i+1)
+		if len(found) > 0 {
+			if ex != nil {
+				ex.Steps = append(ex.Steps, Step{Rule: label, Field: r.Field, MatchBy: r.MatchBy, Exact: r.ExactMatch,
+					Pattern: r.Pattern, Skipped: true})
+			}
+			continue // an earlier rule already matched — fallbacks short-circuit
+		}
 		var rre *regexp.Regexp
 		if p := strings.TrimSpace(r.Pattern); p != "" {
 			c, err := compileAwardRE(p)
 			if err != nil {
+				if ex != nil {
+					ex.Steps = append(ex.Steps, Step{Rule: label, Field: r.Field, MatchBy: r.MatchBy, Pattern: r.Pattern,
+						Error: "bad regex: " + err.Error()})
+				}
 				continue // skip a rule with a bad regex rather than failing the award
 			}
 			rre = c
 		}
-		found = keepRefs(predefined, rl, searchOne(r.Field, r.MatchBy, rre, r.ExactMatch, r.LeadingStr, r.TrailingStr, r.Prefix, q, rl, predefined))
+		found = run(label, r.Field, r.MatchBy, r.Pattern, rre, r.ExactMatch, r.LeadingStr, r.TrailingStr, r.Prefix)
 	}

 	// Merge operator-assigned references (manual override, ManualRefsKey). Lets
@@ -751,8 +868,37 @@ func candidates(d *Def, re *regexp.Regexp, q *qso.QSO, rl refList, hasList bool)
 	// hand. Applied HERE (not just in MatchQSO) so Compute — which powers the
 	// awards panel and the per-QSO refs editor — honours overrides too. For a
 	// predefined award the ref is still validated against the list below.
-	found = append(found, keepRefs(predefined, rl, manualRefs(q, d.Code))...)
-	return dedupe(found)
+	manual := keepRefs(predefined, rl, manualRefs(q, d.Code))
+	if ex != nil {
+		ex.Manual = manual
+	}
+	found = append(found, manual...)
+	out := dedupe(found)
+	if ex != nil {
+		ex.Result = out
+	}
+	return out
+}
+
+// rejection explains why a candidate the operator can SEE in the trace did not
+// become a reference. "Nothing matched" is the least useful thing a matcher can
+// say; every one of this week's award bugs was a rejection with a plain reason
+// that nothing was printing.
+func rejection(predefined bool, rl refList, code string) Rejected {
+	switch {
+	case code == "":
+		return Rejected{Candidate: code, Reason: "empty"}
+	case !predefined:
+		return Rejected{Candidate: code, Reason: "duplicate"}
+	}
+	m, ok := rl.byCode[code]
+	if !ok {
+		return Rejected{Candidate: code, Reason: "not in the award's reference list"}
+	}
+	if !m.Valid {
+		return Rejected{Candidate: code, Reason: "listed but disabled"}
+	}
+	return Rejected{Candidate: code, Reason: "duplicate"}
 }

 // keepRefs reduces a rule's raw candidates to the references that actually count.
@@ -911,24 +1057,37 @@ func natLess(a, b string) bool {

 // inScope reports whether a QSO falls within an award's scope (DXCC entity,
 // bands, modes, emission category, validity dates).
-func inScope(d *Def, q *qso.QSO) bool {
-	if len(d.DXCCFilter) > 0 && !dxccAllowed(q.DXCC, d.DXCCFilter) {
+func inScope(d *Def, q *qso.QSO) bool { return inScopeWhy(d, q, nil) }
+
+// inScopeWhy is inScope with an optional explanation. why is filled ONLY when the
+// QSO is out of scope AND a caller asked for the reason (Explain does; Compute,
+// which runs this for every QSO × every award, passes nil and pays nothing).
+// Keeping both behind one function is the point: a scope check that disagrees with
+// the scope check it explains would be worse than no explanation at all.
+func inScopeWhy(d *Def, q *qso.QSO, why *string) bool {
+	fail := func(format string, args ...any) bool {
+		if why != nil {
+			*why = fmt.Sprintf(format, args...)
+		}
 		return false
 	}
+	if len(d.DXCCFilter) > 0 && !dxccAllowed(q.DXCC, d.DXCCFilter) {
+		return fail("DXCC %d is not in the award's filter %v", q.DXCC, d.DXCCFilter)
+	}
 	if len(d.ValidBands) > 0 && !containsFold(d.ValidBands, q.Band) {
-		return false
+		return fail("band %q is not among the valid bands %v", q.Band, d.ValidBands)
 	}
 	if len(d.ValidModes) > 0 && !containsFold(d.ValidModes, q.Mode) {
-		return false
+		return fail("mode %q is not among the valid modes %v", q.Mode, d.ValidModes)
 	}
 	if len(d.Emission) > 0 && !containsFold(d.Emission, emissionOf(q.Mode)) {
-		return false
+		return fail("mode %q is %s emission; the award accepts %v", q.Mode, emissionOf(q.Mode), d.Emission)
 	}
 	if d.ValidFrom != "" && q.QSODate.Format("2006-01-02") < d.ValidFrom {
-		return false
+		return fail("QSO of %s predates the award's start date (%s)", q.QSODate.Format("2006-01-02"), d.ValidFrom)
 	}
 	if d.ValidTo != "" && q.QSODate.Format("2006-01-02") > d.ValidTo {
-		return false
+		return fail("QSO of %s is after the award's end date (%s)", q.QSODate.Format("2006-01-02"), d.ValidTo)
 	}
 	return true
 }