stormlog.report

The stormlog.report v1 verdict envelope.

A report is the machine-readable summary a command leaves behind for CI jobs and agents: the verdict paired with the process exit code, findings with evidence pointers, flat metrics, and pointers to the versioned artifacts the command wrote. Tool-specific detail goes in payload and is versioned by the producing command, so this envelope stays small and strict.

The published schema is docs/schemas/stormlog_report_v1.schema.json. validate_report applies the same rules without a JSON Schema dependency.

Functions

build_report(*, report_kind, tool_name, ...)	Assemble a v1 report dict whose verdict matches exit_code.
load_report(path)	Read and validate a report file.
validate_report(report)	Check report against the v1 contract.
write_report(path, report)	Validate report and write it as indented JSON.

Classes

Artifact(kind, path[, format, schema_version])	A file the command wrote or relied on.
Evidence(kind[, path, pointer, session_id, ...])	Pointer to the data behind a finding.
Finding(id, kind, severity, title[, ...])	One detected condition with its severity and evidence.

class stormlog.report.Artifact(kind, path, format=None, schema_version=None)

Bases: object

A file the command wrote or relied on.

Parameters:

• kind (str)

• path (str)

• format (str | None)

• schema_version (int | None)

kind: str

path: str

format: str | None = None

schema_version: int | None = None

as_dict()

Return type:

dict[str, Any]

class stormlog.report.Evidence(kind, path=None, pointer=None, session_id=None, record_id=None, start_ns=None, end_ns=None, description=None)

Bases: object

Pointer to the data behind a finding.

path resolves against the directory holding the report; pointer is a JSON pointer inside that file.

Parameters:

• kind (str)

• path (str | None)

• pointer (str | None)

• session_id (str | None)

• record_id (str | None)

• start_ns (int | None)

• end_ns (int | None)

• description (str | None)

kind: str

path: str | None = None

pointer: str | None = None

session_id: str | None = None

record_id: str | None = None

start_ns: int | None = None

end_ns: int | None = None

description: str | None = None

as_dict()

Return type:

dict[str, Any]

class stormlog.report.Finding(id, kind, severity, title, message=None, metrics=None, evidence=<factory>)

Bases: object

One detected condition with its severity and evidence.

Parameters:

• id (str)

• kind (str)

• severity (str)

• title (str)

• message (str | None)

• metrics (Mapping[str, float | int | None] | None)

• evidence (Sequence[Evidence])

id: str

kind: str

severity: str

title: str

message: str | None = None

metrics: Mapping[str, float | int | None] | None = None

evidence: Sequence[Evidence]

as_dict()

Return type:

dict[str, Any]

stormlog.report.build_report(*, report_kind, tool_name, command, exit_code, summary, findings=(), metrics=None, artifacts=(), recommendations=(), session_id=None, run_id=None, payload=None, argv=None, tool_version=None, generated_at_utc=None)

Assemble a v1 report dict whose verdict matches exit_code.

Raises:

ValueError – if exit_code is not in the contract.

Parameters:

• report_kind (str)

• tool_name (str)

• command (str)

• exit_code (int)

• summary (str)

• findings (Sequence[Finding])

• metrics (Mapping[str, float | int | None] | None)

• artifacts (Sequence[Artifact])

• recommendations (Sequence[str])

• session_id (str | None)

• run_id (str | None)

• payload (Mapping[str, Any] | None)

• argv (Sequence[str] | None)

• tool_version (str | None)

• generated_at_utc (str | None)

Return type:

dict[str, Any]

stormlog.report.load_report(path)

Read and validate a report file.

Raises:

ValueError – if the file is not a valid v1 report.

Parameters:

path (Path)

Return type:

dict[str, Any]

stormlog.report.validate_report(report)

Check report against the v1 contract.

Raises:

ValueError – naming the first rule the report breaks.

Parameters:

report (Mapping[str, Any])

Return type:

None

stormlog.report.write_report(path, report)

Validate report and write it as indented JSON.

The file is written next to path and renamed into place, so a reader that arrives after a crash sees either the previous report or the new one, never a truncated file.

Parameters:

• path (Path)

• report (Mapping[str, Any])

Return type:

None