wake.detectors.api module

DetectorConfidence class

Bases: StrEnum

The confidence of a DetectorResult.

Source code in wake/detectors/api.py

@total_ordering
class DetectorConfidence(StrEnum):
    """
    The confidence of a [DetectorResult][wake.detectors.api.DetectorResult].
    """

    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"

    def __lt__(self, other: Any) -> bool:
        if not isinstance(other, DetectorConfidence):
            return NotImplemented
        prio = ["low", "medium", "high"]
        return prio.index(self.value) < prio.index(other.value)

LOW = 'low' class-attribute instance-attribute

MEDIUM = 'medium' class-attribute instance-attribute

HIGH = 'high' class-attribute instance-attribute

DetectorImpact class

Bases: StrEnum

The impact of a DetectorResult.

Source code in wake/detectors/api.py

@total_ordering
class DetectorImpact(StrEnum):
    """
    The impact of a [DetectorResult][wake.detectors.api.DetectorResult].
    """

    INFO = "info"
    WARNING = "warning"
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"

    def __lt__(self, other: Any) -> bool:
        if not isinstance(other, DetectorImpact):
            return NotImplemented
        prio = ["info", "warning", "low", "medium", "high"]
        return prio.index(self.value) < prio.index(other.value)

INFO = 'info' class-attribute instance-attribute

WARNING = 'warning' class-attribute instance-attribute

LOW = 'low' class-attribute instance-attribute

MEDIUM = 'medium' class-attribute instance-attribute

HIGH = 'high' class-attribute instance-attribute

Detection class

A single detection bound to a location in the source code through an IR node. May contain any number of subdetections.

Attributes:

Name	Type	Description
ir_node	IrAbc	IR node representing the detection.
message	str	User-friendly message describing the detection.
subdetections	Tuple[Detection, ...]	Subdetections of this detection.
lsp_range	Optional[Tuple[int, int]]	Byte offsets (start, end) of the detection used for highlighting in LSP diagnostics and in SARIF export.
subdetections_mandatory	bool	Whether the detection requires at least one subdetection to be valid, or if the subdetections are not mandatory for the existence of the detection. This attribute determines whether the detection should be filtered out if all subdetections are filtered out based on the detectors ignore_paths configuration.

Source code in wake/detectors/api.py

@dataclass(eq=True, frozen=True)
class Detection:
    """
    A single detection bound to a location in the source code through an IR node. May contain any number of subdetections.

    Attributes:
        ir_node: IR node representing the detection.
        message: User-friendly message describing the detection.
        subdetections: Subdetections of this detection.
        lsp_range: Byte offsets (start, end) of the detection used for highlighting in LSP diagnostics and in SARIF export.
        subdetections_mandatory: Whether the detection requires at least one subdetection to be valid,
            or if the subdetections are not mandatory for the existence of the detection.
            This attribute determines whether the detection should be filtered out if all subdetections are filtered out based on the detectors [ignore_paths][wake.config.data_model.DetectorsConfig.ignore_paths] configuration.
    """

    ir_node: IrAbc
    message: str
    subdetections: Tuple[Detection, ...] = field(default_factory=tuple)
    lsp_range: Optional[Tuple[int, int]] = field(default=None)
    subdetections_mandatory: bool = field(default=True)

DetectorResult class

A single result reported by a Detector.

Attributes:

Name	Type	Description
detection	Detection	Detection describing the location in the source code and the message.
impact	DetectorImpact	Impact of the detection.
confidence	DetectorConfidence	Confidence of the detection.
uri	Optional[str]	Optional URI to a page describing the detection.

Source code in wake/detectors/api.py

@dataclass(eq=True, frozen=True)
class DetectorResult:
    """
    A single result reported by a [Detector][wake.detectors.api.Detector].

    Attributes:
        detection: Detection describing the location in the source code and the message.
        impact: Impact of the detection.
        confidence: Confidence of the detection.
        uri: Optional URI to a page describing the detection.
    """

    detection: Detection
    impact: DetectorImpact
    confidence: DetectorConfidence
    uri: Optional[str] = field(default=None)

    def __post_init__(self):
        if self.impact not in DetectorImpact.__members__.values():
            raise ValueError(f"Invalid impact: {self.impact}")
        if self.confidence not in DetectorConfidence.__members__.values():
            raise ValueError(f"Invalid confidence: {self.confidence}")

Detector class

Bases: Visitor

Base class for detectors.

Attributes:

Name	Type	Description
paths	List[Path]	Paths the detector should operate on. May be empty if a user did not specify any paths, e.g. when running wake detect all. In this case, the detector should operate on all paths. May be ignored unless visit_mode is all.
extra	Dict[Any, Any]	Extra data shared between all detectors in a single run. May contain additional data set by the execution engine.

Source code in wake/detectors/api.py

class Detector(Visitor, metaclass=ABCMeta):
    """
    Base class for detectors.

    Attributes:
        paths: Paths the detector should operate on. May be empty if a user did not specify any paths, e.g. when running `wake detect all`.
            In this case, the detector should operate on all paths. May be ignored unless [visit_mode][wake.detectors.api.Detector.visit_mode] is `all`.
        extra: Extra data shared between all detectors in a single run. May contain additional data set by the execution engine.
    """

    paths: List[Path]
    extra: Dict[Any, Any]
    lsp_provider: Optional[LspProvider]
    execution_mode: Literal["cli", "lsp", "both"] = "both"  # TODO is this needed?

    @property
    def visit_mode(self) -> Literal["paths", "all"]:
        """
        Configurable visit mode of the detector. If set to `paths`, the detector `visit_` methods will be called only for the paths specified by the user.
        If set to `all`, the detector `visit_` methods will be called for all paths, leaving the filtering of detections to the detector implementation.
        In this case, the detector should use the `paths` attribute to determine which paths to operate on.

        Returns:
            Visit mode of the detector.
        """
        return "paths"

    @abstractmethod
    def detect(self) -> List[DetectorResult]:
        """
        Abstract method that must be implemented in a detector to return the discovered detections.

        Returns:
            List of detector results.
        """
        ...

visit_mode: Literal['paths', 'all'] property

Configurable visit mode of the detector. If set to paths, the detector visit_ methods will be called only for the paths specified by the user. If set to all, the detector visit_ methods will be called for all paths, leaving the filtering of detections to the detector implementation. In this case, the detector should use the paths attribute to determine which paths to operate on.

Returns:

Type	Description
Literal['paths', 'all']	Visit mode of the detector.

detect() abstractmethod

Abstract method that must be implemented in a detector to return the discovered detections.

Returns:

Type	Description
List[DetectorResult]	List of detector results.

Source code in wake/detectors/api.py

@abstractmethod
def detect(self) -> List[DetectorResult]:
    """
    Abstract method that must be implemented in a detector to return the discovered detections.

    Returns:
        List of detector results.
    """
    ...