# undocumented-unsafe

Require a safety rationale for every unsafe declaration and expression

Unsafe callables impose obligations on their callers, while unsafe implementations and local regions rely on invariants the checker cannot verify.
Instead, you SHOULD document caller obligations under `# Safety` and justify implementations and local regions with an immediately preceding `SAFETY:` comment or a nonempty `@unsafe` reason.

- Category: security
- Level: warning
- Fix: none
- Scope: module

## Reported

```ds title="main.ds"
function execute(): void {
    @unsafe
    {}
}
```

## Accepted

```ds title="main.ds"
function execute(): void {
    // SAFETY: no unsafe operation escapes this region
    @unsafe
    {}
}
```

## Prior art

- [Clippy · missing_safety_doc](https://rust-lang.github.io/rust-clippy/master/index.html#missing_safety_doc)
- [Clippy · undocumented_unsafe_blocks](https://rust-lang.github.io/rust-clippy/master/index.html#undocumented_unsafe_blocks)

[language/linter/src/rules/security/undocumented_unsafe.rs:7](https://github.com/destack-sh/destack/blob/main/language/linter/src/rules/security/undocumented_unsafe.rs#L7)