mcov

Documentation

Overview

Package mcov is m-cli's coverage runner (spec §3.1/§8). On YottaDB it uses built-in line tracing: `view "TRACE":1:"^ycov":""` makes every executed line increment ^ycov(routine, LABEL, offset) where offset is from the owning label's declaration line. The host enumerates executable lines from the parse tree (the denominator), runs the suites under trace, then joins the ^ycov dump (the numerator) back to absolute lines for LCOV.

(IRIS coverage via ^%MONLBL — absolute lines, no offset reconciliation — is the parity follow-up; this package implements the YDB path.)

Index

• func BuildScript(suiteEntries []string) string
• func LCOV(r Result) string
• type ExecLine
  • func DiscoverExecutables(p *parse.Parser, routinePaths []string) ([]ExecLine, error)
• type FileCov
  • func ByFile(r Result) []FileCov
  • func (f FileCov) Percent() float64
• type LineCov
• type Result
  • func FromMonitor(p *parse.Parser, monText string, routinePaths []string) (Result, error)
  • func ParseLCOV(text string) (Result, error)
  • func Run(ctx context.Context, p *parse.Parser, eng engine.Engine, ...) (Result, error)
  • func (r Result) Covered() int
  • func (r Result) Percent() float64
  • func (r Result) Total() int

Functions

func BuildScript

func BuildScript(suiteEntries []string) string

BuildScript composes the YDB direct-mode trace script: reset ^ycov, enable line tracing, run every suite entry, disable tracing, dump ^ycov, halt.

func LCOV

func LCOV(r Result) string

LCOV renders the result as an LCOV tracefile (one SF block per source file).

Types

type ExecLine

type ExecLine struct {
	Routine string
	Label   string
	Path    string
	Line    int
	Offset  int
}

ExecLine is one executable source line, with the YDB trace offset (the line's distance from its owning label's declaration line).

func DiscoverExecutables

func DiscoverExecutables(p *parse.Parser, routinePaths []string) ([]ExecLine, error)

DiscoverExecutables walks each routine file and returns its executable lines. A line is executable iff its `line` AST node has a `command_sequence` child (comment-only and label-only lines are excluded — YDB's TRACE emits no hits for them, so their absence never means "uncovered"). Each line carries the owning label and its YDB trace offset = lineNumber − labelDeclarationLine.

type FileCov

type FileCov struct {
	Path    string
	Covered int
	Total   int
}

FileCov is one source file's coverage rollup.

func ByFile

func ByFile(r Result) []FileCov

ByFile rolls a Result up per source file in first-seen line order — the shared rollup behind `m coverage`'s per-file report and `m watch --coverage`.

func (FileCov) Percent

func (f FileCov) Percent() float64

Percent is the file's line coverage (0 when it has no executable lines).

type LineCov

type LineCov struct {
	Routine string
	Label   string
	Path    string
	Line    int
	Hits    int
}

LineCov is an executable line plus how many times it ran.

type Result

type Result struct {
	Lines  []LineCov
	Stdout string
}

Result is the aggregate coverage outcome.

func FromMonitor

func FromMonitor(p *parse.Parser, monText string, routinePaths []string) (Result, error)

FromMonitor builds a coverage Result from a raw ##MON block (the MLINE lines the resident harness's IRIS line monitor emits, design §3.2) joined to the executable lines of routinePaths. The executable-line denominator stays host-side (the parse tree) and the monitor data is identical to what the host-orchestrated runIris collects, so resident coverage == file-side coverage by construction (G4). The host owns the parse tree the resident M side lacks.

func ParseLCOV

func ParseLCOV(text string) (Result, error)

ParseLCOV reads an LCOV tracefile into a Result. It is the inverse of LCOV: a coverage payload that arrives as text (the resident harness ##LCOV frame block, §3.2) parses back here so it feeds the same ByFile / Percent / gutter consumers a host-side mcov.Run produces — the parity contract. Only SF: and DA: lines carry data; TN:/LF:/LH:/end_of_record and anything else are ignored (so output of this package's own LCOV, with its TN:/LF:/LH: lines, round-trips and a foreign producer's extra records do not break the parse).

func Run

func Run(ctx context.Context, p *parse.Parser, eng engine.Engine, routinePaths, suiteEntries []string) (Result, error)

Run enumerates executable lines in routinePaths, runs the suites under the engine's line tracer, and joins per-line hits back to those lines. YDB uses view "TRACE" → ^ycov (label-relative offsets); IRIS uses the LineByLine monitor (absolute lines).

func (Result) Covered

func (r Result) Covered() int

Covered is the number of executable lines that ran at least once.

func (Result) Percent

func (r Result) Percent() float64

Percent is line coverage as a percentage (0 when there are no lines).

func (Result) Total

func (r Result) Total() int

Total is the number of executable lines (the denominator).