cargo-memlense 0.2.0-beta.1

Static analysis tool for memkit - detect memory issues before runtime
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

<div align="center">

# ◈ CARGO MEMLENSE ◈


### `[ STATIC ANALYSIS & SEMANTIC LINTING SUITE ]`


[![Crates.io](https://img.shields.io/badge/crates.io-v0.2.0--beta.1-00ff9f?style=for-the-badge&labelColor=0d1117)](https://crates.io/crates/cargo-memlense)
[![License](https://img.shields.io/badge/license-MPL--2.0-ff6b35?style=for-the-badge&labelColor=0d1117)](../LICENSE.md)

---

```
 ██████╗ █████╗ ██████╗  ██████╗  ██████╗ 
██╔════╝██╔══██╗██╔══██╗██╔════╝ ██╔═══██╗
██║     ███████║██████╔╝██║  ███╗██║   ██║
██║     ██╔══██║██╔══██╗██║   ██║██║   ██║
╚██████╗██║  ██║██║  ██║╚██████╔╝╚██████╔╝
 ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝  ╚═════╝ 
```

> *"Detecting what the compiler accepts, but the system forbids."*

**The official static analysis tool for the Memkit ecosystem. Ensures your memory patterns adhere to deterministic constraints and task-local safety rules.**

[`◈ INSTALLATION`](#◈-installation) • [`◈ CATEGORIES`](#◈-diagnostic-categories) • [`◈ ARCHITECTURE`](#◈-architecture)

</div>

---

## ◈ THE MEMLENSE ADVANTAGE


| Feature | `cargo check` | `cargo memlense` | Results |
|:--------|:-------------:|:----------------:|:--------|
| **Arena Safety** | Ignored | **Scope Validation** | No escapes |
| **Async Leaks** | Runtime | **Compile-time** | Fast feedback |
| **Perf Hints** | Basic | **Cache-Locality** | Latency wins |
| **Patterns** | General | **Specialized** | Intent-driven |

---

## ◈ FEATURES


```
┌─────────────────────────────────────────────────────────────────────────┐
│  ◆ SCOPE GUARD │  Detects when frame allocations leak across boundaries  │
│                │  of `begin_frame` and `end_frame`.                      │
├─────────────────────────────────────────────────────────────────────────┤
│  ◆ ASYNC AUDIT │  Identifies allocations held across `.await` points,    │
│                │  preventing dangerous task-migration leaks.             │
├─────────────────────────────────────────────────────────────────────────┤
│  ◆ EXPLAIN     │  Rich diagnostic explainers for every rule. Simply run  │
│                │  `cargo memlense explain <CODE>`.                        │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## ◈ INSTALLATION


```bash
# Install the linter binary

cargo install cargo-memlense
```

---

## ◈ QUICK START


```bash
# Analyze your entire workspace

cargo memlense check

# Check a specific module for async violations

cargo memlense check src/network.rs --rules ML6

# Detailed explanation of a diagnostic

cargo memlense explain ML602
```

---

## ◈ DIAGNOSTIC CATEGORIES


| Code | Category | Purpose |
|:-----|:---------|:--------|
| **`ML1xx`** | Frame Lifecycle | Lifetime mismatches |
| **`ML2xx`** | Threading | Cross-thread ownership hazards |
| **`ML3xx`** | GPU Sync | Device/Staging coordination errors |
| **`ML4xx`** | Performance | Cache locality & alignment tips |
| **`ML6xx`** | Async Safety | Task-local boundary checks |

---

## ◈ ARCHITECTURE


```mermaid
graph TD
    Source([Source Code]) --> Parser[memlense Parser]
    Parser --> Engine{Semantic Rules}
    Engine -->|Console| UI[Rich Diagnostic TUI]
    Engine -->|JSON| CI[CI/CD Artifacts]
```

---

## ◈ LICENSE


Licensed under the **Mozilla Public License 2.0**.

---

<div align="center">

**[ Part of the ◈ MEMKIT ◈ Ecosystem ]**

</div>