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.
|
required |
severity
|
Severity
|
See :class: |
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 |
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 |
as_dict(*, exclude_hidden=True)
Convert this dataclass instance to a plain dict.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
exclude_hidden
|
bool
|
When |
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 |
dict[str, Any]
|
metadata at every level. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If the subclass was not decorated with
|
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 |
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 |
TypeError
|
If the subclass was not decorated with
|
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: |
None
|
**kwargs
|
Any
|
Additional keyword arguments forwarded to
:func: |
{}
|
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: |
{}
|
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.