feat: Added a test tab in awards to test the matching
This commit is contained in:
+171
-12
@@ -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
|
||||
}
|
||||
|
||||
@@ -384,6 +384,65 @@ func TestComputeOrFallbackAfterUnlistedPrimary(t *testing.T) {
|
||||
t.Errorf("BG not worked; refs = %v", refCodes(r))
|
||||
}
|
||||
|
||||
// Explain must account for the WAIP case exactly: the primary rule produces a
|
||||
// candidate that is NOT a province, says so, and the QTH fallback then finds BG.
|
||||
func TestExplainAccountsForEveryRule(t *testing.T) {
|
||||
def := Def{
|
||||
Code: "WAIP", Valid: true, Type: TypeReference,
|
||||
Field: "address", MatchBy: "code", ExactMatch: true,
|
||||
OrRules: []OrRule{{Field: "qth", MatchBy: "code"}},
|
||||
Confirm: []string{"lotw"},
|
||||
}
|
||||
metas := []RefMeta{{Code: "BG", Name: "Bergamo", Valid: true}}
|
||||
q := &qso.QSO{Callsign: "I2IFT", Band: "30m", QTH: "SERIATE (BG)", Address: "Seriate (Bg) 24068 Italy"}
|
||||
|
||||
ex := Explain(def, metas, q)
|
||||
if !ex.InScope || len(ex.Steps) != 2 {
|
||||
t.Fatalf("in scope=%v, %d steps, want in scope with 2 (primary + OR 1): %+v", ex.InScope, len(ex.Steps), ex)
|
||||
}
|
||||
// The primary rule LOOKS like it found something. Saying only "no match" here is
|
||||
// what cost hours: the trace has to show the candidate and why it lost.
|
||||
p := ex.Steps[0]
|
||||
if len(p.Candidates) == 0 {
|
||||
t.Error("primary produced no candidate; the whole point is that it produces a bogus one")
|
||||
}
|
||||
if len(p.Kept) != 0 || len(p.Rejected) == 0 {
|
||||
t.Fatalf("primary kept=%v rejected=%v, want nothing kept and a stated reason", p.Kept, p.Rejected)
|
||||
}
|
||||
if !strings.Contains(p.Rejected[0].Reason, "not in the award's reference list") {
|
||||
t.Errorf("reason = %q, want it to name the real cause", p.Rejected[0].Reason)
|
||||
}
|
||||
if or1 := ex.Steps[1]; or1.Skipped || len(or1.Kept) != 1 || or1.Kept[0] != "BG" {
|
||||
t.Errorf("OR 1 = %+v, want it to run and find BG", or1)
|
||||
}
|
||||
if len(ex.Result) != 1 || ex.Result[0] != "BG" {
|
||||
t.Errorf("result = %v, want [BG]", ex.Result)
|
||||
}
|
||||
|
||||
// A trace that disagrees with the matcher is worse than none: it is believed.
|
||||
if got := MatchQSO(def, metas, q); strings.Join(got, ",") != strings.Join(ex.Result, ",") {
|
||||
t.Errorf("Explain says %v but MatchQSO says %v — the trace does not describe the code", ex.Result, got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestExplainOutOfScopeSaysWhy(t *testing.T) {
|
||||
def := Def{Code: "FFMA", Valid: true, Field: "grid4", MatchBy: "code", ExactMatch: true,
|
||||
ValidBands: []string{"6m"}, ValidFrom: "1983-01-01", Confirm: []string{"lotw"}}
|
||||
q := &qso.QSO{Callsign: "K1ABC", Band: "2m", Grid: "EM00AA",
|
||||
QSODate: time.Date(1990, 1, 1, 0, 0, 0, 0, time.UTC)}
|
||||
|
||||
ex := Explain(def, []RefMeta{{Code: "EM00", Valid: true}}, q)
|
||||
if ex.InScope {
|
||||
t.Fatal("a 2 m QSO is not in scope for a 6 m-only award")
|
||||
}
|
||||
if !strings.Contains(ex.ScopeError, "2m") {
|
||||
t.Errorf("scope error = %q, want it to name the band that fails", ex.ScopeError)
|
||||
}
|
||||
if len(ex.Steps) != 0 {
|
||||
t.Errorf("%d steps ran on an out-of-scope QSO; none should", len(ex.Steps))
|
||||
}
|
||||
}
|
||||
|
||||
func refCodes(r Result) []string {
|
||||
out := make([]string, 0, len(r.Refs))
|
||||
for _, rf := range r.Refs {
|
||||
|
||||
Reference in New Issue
Block a user