report()

Structured reporting middleware. Decorates ctx.report with methods for writing checks, findings, and summaries.

Import from maltty/report.

report(options?)

Create the report middleware.

OptionTypeDefaultDescription
outputNodeJS.WritableStreamprocess.stderrOutput stream for report output
reportReport--Custom Report implementation (useful for testing)

createReport(options?)

Create a standalone Report instance outside the middleware pipeline.

OptionTypeDefaultDescription
outputNodeJS.WritableStreamprocess.stderrOutput stream for report output

Report

The ctx.report interface:

MethodSignatureDescription
check(input: CheckInput) => voidWrite a pass/fail/warn/skip/fix row
finding(input: FindingInput) => voidWrite a finding with optional code frame
summary(input: SummaryInput) => voidWrite a summary block or inline stats

CheckInput

FieldTypeRequiredDescription
status'pass' | 'fail' | 'warn' | 'skip' | 'fix'yesCheck status
namestringyesDisplay name (e.g. file path, test name)
detailstringnoDetail text shown after the name
durationnumbernoDuration in milliseconds
hintstringnoHint shown at the end

FindingInput

FieldTypeRequiredDescription
severity'error' | 'warning' | 'hint'yesFinding severity
rulestringyesRule identifier (e.g. no-unused-vars)
messagestringyesFinding message
categorystringnoCategory (e.g. correctness, style)
helpstringnoHelp text with suggested fix
frameCodeFrameInputnoSource code frame with annotation

CodeFrameInput

FieldTypeDescription
filePathstringFile path displayed above the frame
linesreadonly string[]Source lines to display
startLinenumber1-based line number of the first line
annotationCodeFrameAnnotationAnnotation to render below the target line

CodeFrameAnnotation

FieldTypeDescription
linenumber1-based line number to annotate
columnnumber1-based column where annotation starts
lengthnumberLength of the annotated span
messagestringMessage shown on the annotation line

SummaryInput

Discriminated union on style:

Block style ('tally')

FieldTypeDescription
style'tally'Aligned multi-row summary block
statsreadonly SummaryStat[]Labeled stat rows

Inline style

FieldTypeDescription
style'inline'Pipe-separated one-liner
statsreadonly string[]Pre-formatted stat segments

SummaryStat

FieldTypeDescription
labelstringRow label (e.g. Tests, Duration)
valuestringRow value (can contain pre-colored text)

ReportEnv

Middleware environment descriptor. Declares that ctx.report will be available after this middleware runs.

Module augmentation

import type { Report } from 'maltty/report'

declare module 'maltty' {
  interface CommandContext {
    readonly report: Report
  }
}

References