Package: verify

CTRF report shape. Only the fields reqmd needs are decoded; the per-testextra extension point carries the reqmd binding fields (id, case,verifies, description). results is kept as raw JSON at first so thetop-level shape can be validated without decoding the (potentially verylarge) test list more than once.

Reference: https://ctrf.io/docs/full-schema

loadCTRFFile parses one CTRF JSON file into Results.

loadCTRFData parses CTRF JSON bytes into Results. The path isused only for error messages and evidence attribution.

Binding (extra.x-reqmd):id present → the result binds directly to that requirement ID (patterns A/C); an explicit case is recorded on the result.no id but verifies present → a test case is synthesized under the case key (explicit case, else normalized (suite, name)) with trace edges to each verifies ref (patterns D/E).x-reqmd present but nothing bindable → an "unbound-result" warning.no x-reqmd block → skipped silently.

xreqmdFields holds the reqmd binding fields from a CTRF test'sextra.x-reqmd block. present is true when the block exists.

extractXReqmd reads the reqmd binding fields from a CTRF test's extraobject. Returns present=false when there is no x-reqmd block.

implicitCaseKey derives a stable case key from the report suite and testname for verifies-only bindings (pattern E): suite + "/" + name, or thebare name when the report has no suite.

ctrfStatusToOutcome maps CTRF status to reqmd outcome. A flaky test isinconclusive regardless of its (passing) final status.

msEpochToTime converts a CTRF millisecond epoch to time.Time, fallingback to start when stop is 0, then to the zero value.

isCTRFFileData is a cheap shape check on already-read bytes.Used by the dir walker to distinguish CTRF .json from other.json (coverage reports, etc.) without reading the file twice.

looksLikeCTRF reports whether the JSON bytes decode to an object with atop-level results object. The probe decodes only the top-level key andkeeps results as raw bytes — the potentially huge test list is NOTdecoded into Go values here (that happens once, in loadCTRFData).

isCTRFResultsObject reports whether the raw results value is a non-emptyobject (CTRF's results is an object containing tests[], never an array).This is a byte-level check — no JSON decode of the contents.

Outcome is the reqmd verdict axis derived from a verification result.

Verification result outcomes.

Verification result outcomes.

Verification result outcomes.

Verification result outcomes.

Verdict is the outcome + source for a single measure, ready forconsumption by exporters and reporters. It's the transport typebetween verify (which loads results) and exporter (which rendersthem), avoiding a direct dependency from exporter on verify.

Result is one verification result, already mapped to a measure ID (and,for case-keyed runs, to a test-case identity). Multiple results for thesame measure are merged by VerifiedAt (latest wins) before synthesis.

The identity fields (Name, CaseKey, Verifies, Description) back therequirement → test-case → result chain model. Today only MeasureID ispopulated and Name is captured from CTRF; CaseKey/Verifies/Descriptionare the v2 fields parsed in the binding phase that introduces synthesizedtest cases.

ResultKey identifies a merged verification slot: the binding target(an authored requirement ID, or a synthesized test-case ID "TC:")plus the test-case key. Case is empty for the degenerate single-resultmodel (patterns A/B/F); two results sharing a key collapse into one vialatest-wins merging.

resultKeyFor computes the merge key for a result.

MergeLatest returns, for each (target, case) key, the result with thelatest VerifiedAt. Ties are broken by lexical order of Source fordeterminism. The ~N pin is stripped from the key so results pinned todifferent versions of the same measure collapse to one entry (the pin ispreserved on the synthesized trace edge, not the result identity).

LoadMerged is a convenience wrapper that loads results from thegiven paths and merges them by (target, case) key (latest verdict wins).Returns the merged map, any warnings, and an error. When pathsis empty/nil, returns (nil, nil, nil) — callers should check fornil before calling Synthesize.

LoadVerdicts loads results, merges by (target, case) key, and convertsto a per-target Verdict map for exporters that render per-measure badgesbefore roll-up semantics land. For targets with several cases the verdictis the latest result across those cases (by VerifiedAt); rolled-up verdictcomputation is a graph concern in the evidence-set phase. This is theshared results-loading path for check, serve, and export csv/html/graph.Returns all nil when paths is empty.

LoadResults walks the given paths and loads verification results fromeach. A path may be:a directory: walked; .ctrf.json and CTRF-shaped .json files are parsed as CTRF, directories containing schema.yaml are loaded as manual results via parser.Discover, other files are skipped.a file: parsed as CTRF if .ctrf.json or CTRF-shaped .json.

Returns the merged set of results and any warnings (e.g. unmapped CTRFtests). Warnings are returned as CheckResult-shaped messages via thereturned warning slice; errors abort loading.

readInRoot reads one file from the walked results tree through the walkroot, refusing paths that escape it.

loadDir walks a results directory. CTRF files (.ctrf.json orCTRF-shaped .json) are parsed directly. Subdirectories with aschema.yaml are loaded as manual-results document dirs viaparser.Discover. Non-CTRF files (coverage.json, junit.xml, etc.) areskipped silently.

Each .json file is read once: the bytes are used for the CTRFshape check and, if it passes, for the full parse. This avoidsthe double-read that occurred when isCTRFFile and loadCTRFFileeach opened the file independently.

CTRF files pending load: (path, data) pairs. The data isalready read during the walk for the shape check, so we passit to loadCTRFData to avoid a second read.

loadManualDir parses a manual-results document dir via the standardparser pipeline and extracts result attrs from each requirement.

resultFromReq builds a Result from a parsed manual-results requirement.Returns ok=false if the requirement has no x-reqmd.outcome attr (not aresult). Result attributes are tool-owned and namespaced under x-reqmd.*.

resultDocLevel is the x-reqmd level assigned to synthesizedverification-result documents. The graph uses levels to infer V-modelboundaries; results are the bottom of the V (leaves), so they must notbe treated as roots.

testCasePrefix prefixes the ID of a synthesized test-case node("TC:"). Case-keyed CTRF entries (patterns D/E) synthesize onesuch node per case; it carries the verifies trace edges to therequirements it exercises and the Markdown description body.

Synthesize builds one model.Document (marked Synthetic) holding thepseudo-requirements derived from merged results:One result node per merged (target, case) key: ID RESULT:[#], trace: [], plus outcome / status:approved / verifier / evidence / verified-at.One test-case node per synthesized case target (ID TC:) whose ID starts with testCasePrefix: trace: [verifies...] (pins allowed), Body = the Markdown description of the winning run, Title = the test name.

The returned Document is appended to the spec docs before graph.New soall existing graph machinery (broken-ref, circular, version-pin) works onresult→measure and case→requirement edges with no new traversal code.

synthesizeTestCase builds the synthesized test-case node for acase-keyed CTRF result. Its trace edges go to the requirements itexercises (extra.x-reqmd.verifies, pins allowed); its body is theMarkdown description taken from the winning run.

synthesizeResult builds a single pseudo-requirement node from a mergedresult. The binding target (with its ~N pin preserved for id-boundresults) becomes the trace target; a case-keyed result gets a distinctnode ID so several cases can attach to the same authored measure.

resultNodeID is the synthetic ID of a result node:RESULT: for the single-result model, RESULT:# whenthe run is case-keyed.

outcomeTitle returns a short human-readable title for the pseudo-req.

toAny converts a []string into a []any for attribute maps.

IsResultNode reports whether a requirement ID belongs to a synthesizedverification-result pseudo-requirement (i.e. produced by Synthesize).Used by graph checks to distinguish result nodes from authored ones.

IsTestCaseNode reports whether a requirement ID belongs to a synthesizedtest case ("TC:..."). Used to recognize case nodes independently of theRESULT prefix.

ResultOutcome extracts the outcome attribute from a synthesized resultnode's requirement attrs. Returns "" if not present.