Skip to content

Findings

rn_forge.commons.findings

Structured findings: the result shape every checker and doctor reports in.

A checker returns a list of :class:Finding values for a CLI to render as a table or JSON.

code is the stable identifier, dotted and lowercase (artifact.drift, docs.broken-link). It is what a suppression list, a CI annotation or a release note refers to, so it must outlive rewording of message.

Finding(code, severity, message, path=None, line=None, details=dict[str, JsonValue]()) dataclass

Bases: LenientDataclassMixin

One structured result from a check.

Parameters:

Name Type Description Default
code str

Stable dotted identifier for the rule that produced this, e.g. "artifact.drift".

required
severity Severity

See :class:Severity.

required
message str

Human-readable, one line, specific to this occurrence.

required
path str | None

The path the finding is about, when there is one — relative to the repository for a repository check, absolute for a check of a workstation install.

None
line int | None

1-indexed line within path, when the rule is line-precise.

None
details dict[str, JsonValue]

Rule-specific structured data for --json consumers — expected and actual hashes, a resolved link target, and so on. Never load-bearing for rendering.

dict[str, JsonValue]()

Type checking is disabled because dacite cannot validate the recursive :data:~rn_forge.commons.lang.types.JsonValue alias used by details.

is_error property

Whether this finding should fail the command that collected it.

__repr__()

Return an unambiguous ClassName(field=value, ...) representation.

Excluded fields (metadata={"exclude": True}) are omitted. Falls back to :func:object.__repr__ when the class is not a dataclass.

Returns:

Type Description
str

A string of the form ClassName(field1=value1, field2=value2).

as_dict(*, exclude_hidden=True)

Convert this dataclass instance to a plain dict.

Parameters:

Name Type Description Default
exclude_hidden bool

When True (default), fields decorated with metadata={"exclude": True} are omitted from the result, recursively throughout nested dataclasses. Pass False to include every field.

True

Returns:

Type Description
dict[str, Any]

A dict mapping field names to their current values. Nested

dict[str, Any]

dataclasses are recursively converted, respecting exclude

dict[str, Any]

metadata at every level.

Raises:

Type Description
TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_dict(data) classmethod

Create an instance from a dict, recursively rebuilding nested dataclasses.

Only keys that match declared dataclass field names are passed to the constructor. This makes from_dict tolerant of extra data (e.g. when loading from a config file that has fields added in a newer schema version). Nested dataclass-typed fields are reconstructed recursively for common container annotations, via :mod:dacite.

Note a nested dataclass field's own overridden from_dict (if any) is not called — dacite structures nested dataclasses itself.

Parameters:

Name Type Description Default
data dict[str, Any]

A dict whose keys correspond to dataclass field names. Unrecognised keys are silently ignored, or rejected when the class's __dacite_config__ sets strict.

required

Returns:

Type Description
Self

A new instance of this class populated with matching field values.

Raises:

Type Description
AppException

A value does not match its field's declared type, a required field is absent, or an enum-typed field names a member the enum does not define. Under strict, also a key that names no field, at any nesting level; the message lists every such key by its dotted path (repository.archtype).

TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_json(text) classmethod

Create an instance from a JSON string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A JSON string representing a dict of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed JSON.

Raises:

Type Description
JSONDecodeError

If text is not valid JSON.

from_yaml(text) classmethod

Create an instance from a YAML string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A YAML string representing a mapping of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed YAML.

Raises:

Type Description
YAMLError

If text is not valid YAML.

to_json(*, indent=None, **kwargs)

Serialise this instance to a JSON string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
indent str | int | None

Indentation level passed to :func:json.dumps. None produces compact output.

None
**kwargs Any

Additional keyword arguments forwarded to :func:json.dumps.

{}

Returns:

Type Description
str

A JSON string representation of this instance.

to_yaml(**kwargs)

Serialise this instance to a YAML string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
**kwargs Any

Additional keyword arguments forwarded to :meth:~rn_forge.commons.fs.documents.YamlUtils.serialize (e.g. sort_keys, default_flow_style).

{}

Returns:

Type Description
str

A YAML string representation of this instance.

Severity

Bases: StrEnum

How a finding should be treated by the command that collected it.

ERROR = 'error' class-attribute instance-attribute

The check failed; the command exits non-zero.

INFO = 'info' class-attribute instance-attribute

Context for the reader; never affects an exit code.

WARNING = 'warning' class-attribute instance-attribute

Worth reporting, but not a failure on its own.