From a686c2c63f16f9ce214739257723d283efafd8ba Mon Sep 17 00:00:00 2001 From: Samsie Date: Mon, 15 Jun 2026 22:42:35 +0530 Subject: [PATCH 1/3] docs: Add Quick Start section to README --- README.md | 38 ++++++++++++++++++++++++++++++++++---- 1 file changed, 34 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 95af5b3..5260514 100644 --- a/README.md +++ b/README.md @@ -16,13 +16,43 @@ Our design philosophy is built around simplicity and accessibility because **We **"One command. All platforms. No configuration hell."** -## Status -Early but functional. Core scanning and leak detection work on both platforms. See the roadmap below for what's coming. +--- + +## 🚀 Quick Start -### New TUI +### 1. Installation +The fastest way to get started is downloading a pre-built binary from the [Releases](https://github.com/SickleFire/m-vis/releases) page. +If you have Rust installed, you can build from source: +```bash +git clone https://github.com/SickleFire/m-vis +cd mvis +cargo build --release +# Your binary is at target/release/mvis +``` + +### 2. Enter the TUI +Experience the interactive memory dashboard immediately: +```bash +mvis tui +``` Screenshot 2026-06-05 173344 -Screenshot 2026-06-05 173607 +### 3. Basic CLI Commands +```bash +# Find a target process +mvis list + +# Scan process memory maps (replace 'notepad' with your target) +mvis scan notepad -a + +# Monitor a process for memory leaks (10 second interval) +mvis leak notepad 10 +``` + +--- + +## Status +Early but functional. Core scanning and leak detection work on all platforms. See the roadmap below for what's coming. --- From e38ea68ee8d755f1cad2c82642cbffd6a3cceb41 Mon Sep 17 00:00:00 2001 From: Samsie Date: Mon, 15 Jun 2026 22:46:48 +0530 Subject: [PATCH 2/3] docs: revamp README with Mermaid diagrams and improved structure --- README.md | 133 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 87 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 5260514..078e766 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,47 @@ -# mvis +# m-vis: Memory Debugging Made Simple 🧠 [![Tests](https://github.com/SickleFire/m-vis/actions/workflows/tests.yml/badge.svg)](https://github.com/SickleFire/m-vis/actions/workflows/tests.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -mvis: Memory debugging for developers who just want answers. -Simple. Fast. Works everywhere. +Welcome to **m-vis**. Memory debugging for developers who just want answers. Simple. Fast. Works everywhere. -## Why mvis? +Existing tools are either platform-specific (Valgrind, WinDbg) or too complex for quick diagnostics. m-vis gives you deep memory insights with a single command across any platform. -Existing tools are either platform-specific (Valgrind, WinDbg) or -too complex for quick diagnostics. mvis gives you memory insights -with a single command on any platform. - -Our design philosophy is built around simplicity and accessibility because **We believe memory debugging should be accessible, not a PhD requirement.** +Our design philosophy is built around simplicity and accessibility because **we believe memory debugging should be accessible, not a PhD requirement.** **"One command. All platforms. No configuration hell."** --- +## 🏗 High-Level System Architecture + +m-vis is built in Rust to provide native, blazing-fast performance without overhead. It abstracts away the complex OS-level memory APIs into a unified, cross-platform scanning engine. + +```mermaid +graph TD + subgraph UI [User Interfaces] + CLI[Command Line Interface] + TUI[Terminal User Interface] + end + + subgraph Core [m-vis Core Engine] + Scan[Memory Scanner] + Leak[Leak Detector] + Stack[Stack Tracer] + end + + subgraph OS [Operating System APIs] + Win[Windows API / VirtualQueryEx] + Lin[Linux / procfs / ptrace] + Mac[macOS / Mach VM API] + end + + UI --> Core + Core --> OS +``` + +--- + ## 🚀 Quick Start ### 1. Installation @@ -51,20 +75,45 @@ mvis leak notepad 10 --- -## Status -Early but functional. Core scanning and leak detection work on all platforms. See the roadmap below for what's coming. +## 🎨 Features & Capabilities + +- **Process Scanning**: Inspect memory allocations, mapped regions, and permissions of active processes. +- **Heap-Level Analysis**: Dive deeply into heap structures and allocations for detailed debugging. +- **DLL Tracking**: Monitor and list all dynamic libraries (DLLs/SOs/Dylibs) loaded by a target. +- **Real-time Memory Leak Detection**: Identify and monitor processes with growing, unreleased memory allocations. +- **Leak Delta Chart**: m-vis includes a real-time leak delta chart that visualizes memory allocation trends over time directly in the TUI. +- **Universal OS Support**: 100% native support for Windows, Linux, and macOS. --- -## Features -- **Process Scanning**: Inspect memory allocations of active processes. -- **Heap-Level Analysis**: Dive into heap structures for detailed debugging. -- **DLL Tracking**: Monitor and list all DLLs loaded by a target. -- **Memory Leak Detection**: Identify and monitor processes with growing, unreleased allocations. -- **Leak Delta Chart**: mvis includes a real-time leak delta chart that visualizes memory allocation trends over time directly in the TUI. -- **Supported OS**: Windows, Linux, macOS +## 🔄 Core Workflows: How Leak Detection Works + +The leak detector doesn't just watch total RAM usage; it takes deep topological snapshots of the process heap and computes exact block-level deltas to find silent unreleased memory. + +```mermaid +sequenceDiagram + participant User + participant mvis as m-vis Engine + participant OS as Target Process OS API + + User->>mvis: Run `mvis leak 10` + + loop Every 10 Seconds + mvis->>OS: Capture Deep Memory Snapshot + OS-->>mvis: Memory Regions & Heap Blocks + mvis->>mvis: Compute Delta (Diff with previous snapshot) + + alt New allocations found + mvis-->>User: Report Exact Growth & Block Count + else Stable Memory + mvis-->>User: Report "No Leaks Detected" + end + end +``` + +--- -## macOS Code Signing +## 🔐 macOS Security & Code Signing On macOS, `mvis` requires the `com.apple.security.cs.debugger` entitlement to inspect other processes due to Hardened Runtime restrictions. Even with `sudo`, inspecting third-party apps requires this entitlement. @@ -78,7 +127,11 @@ make run-scan PROCESS=language_server_macos_arm MODE=-a ``` *Note: Apple platform apps (Safari, Finder) and some Hardened Runtime apps (WhatsApp) will remain protected by System Integrity Protection (SIP) even with this entitlement.* -## Usage +--- + +## 💻 Detailed Usage & Examples + +### Available Commands ```powershell # visualize memory map mvis scan notepad.exe -a @@ -95,45 +148,31 @@ mvis leak-m notepad.exe 10 3 # list processes mvis list -#open mvis tui +# open mvis tui mvis tui ``` -### Examples + +### Visual Examples + +**Detecting Leaks:** ```powershell mvis leak leaking_app.exe 10 ``` Output:
Screenshot 2026-05-01 181525
+**Scanning Process Maps:** ```powershell mvis scan myapp.exe -a ``` -
Output:
Screenshot 2026-05-01 182001 -.
-.
-.
+
Screenshot 2026-05-01 181929 --- -## Installation - -### From GitHub Releases (Recommended) -Download pre-built binaries from [Releases](https://github.com/SickleFire/m-vis/releases): -- **Windows:** `mvis-windows-x86_64.exe` -- **Linux:** `mvis-linux-x86_64` - - -### From source -```bash -git clone https://github.com/SickleFire/m-vis -cd mvis -cargo build --release -``` - -## Testing +## 🛠 Developer Commands & Testing The project includes comprehensive unit and integration tests to ensure reliability across platforms. @@ -147,7 +186,7 @@ cargo test cargo test --test integration_tests ``` -### Run integration tests with admin privileges (advanced) +### Run integration tests with elevated privileges ```bash # On Linux with sudo sudo cargo test --test integration_tests -- --include-ignored @@ -155,10 +194,12 @@ sudo cargo test --test integration_tests -- --include-ignored # On Windows (run terminal as Administrator) cargo test --test integration_tests -- --include-ignored ``` + --- -### Roadmap -See [Roadmap](https://github.com/SickleFire/m-vis/issues/24) -## License +## 📅 Status & Roadmap +Early but highly functional. Core scanning and leak detection work on all supported platforms. +See the [Roadmap](https://github.com/SickleFire/m-vis/issues/24) for what's coming next. +## 📄 License MIT — see [LICENSE](LICENSE.md) From f0bfc7fb2edca8095a279edc5ebcb60f99299c3d Mon Sep 17 00:00:00 2001 From: Samsie Date: Mon, 15 Jun 2026 22:52:50 +0530 Subject: [PATCH 3/3] docs: standardize hyphenation by removing unnecessary hyphens from README documentation --- README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 078e766..9c99ea7 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Welcome to **m-vis**. Memory debugging for developers who just want answers. Simple. Fast. Works everywhere. -Existing tools are either platform-specific (Valgrind, WinDbg) or too complex for quick diagnostics. m-vis gives you deep memory insights with a single command across any platform. +Existing tools are either platform specific (Valgrind, WinDbg) or too complex for quick diagnostics. m-vis gives you deep memory insights with a single command across any platform. Our design philosophy is built around simplicity and accessibility because **we believe memory debugging should be accessible, not a PhD requirement.** @@ -13,9 +13,9 @@ Our design philosophy is built around simplicity and accessibility because **we --- -## 🏗 High-Level System Architecture +## 🏗 System Architecture -m-vis is built in Rust to provide native, blazing-fast performance without overhead. It abstracts away the complex OS-level memory APIs into a unified, cross-platform scanning engine. +m-vis is built in Rust to provide native, blazing fast performance without overhead. It abstracts away the complex OS level memory APIs into a unified, cross platform scanning engine. ```mermaid graph TD @@ -45,7 +45,7 @@ graph TD ## 🚀 Quick Start ### 1. Installation -The fastest way to get started is downloading a pre-built binary from the [Releases](https://github.com/SickleFire/m-vis/releases) page. +The fastest way to get started is downloading a pre built binary from the [Releases](https://github.com/SickleFire/m-vis/releases) page. If you have Rust installed, you can build from source: ```bash git clone https://github.com/SickleFire/m-vis @@ -78,17 +78,17 @@ mvis leak notepad 10 ## 🎨 Features & Capabilities - **Process Scanning**: Inspect memory allocations, mapped regions, and permissions of active processes. -- **Heap-Level Analysis**: Dive deeply into heap structures and allocations for detailed debugging. +- **Heap Level Analysis**: Dive deeply into heap structures and allocations for detailed debugging. - **DLL Tracking**: Monitor and list all dynamic libraries (DLLs/SOs/Dylibs) loaded by a target. -- **Real-time Memory Leak Detection**: Identify and monitor processes with growing, unreleased memory allocations. -- **Leak Delta Chart**: m-vis includes a real-time leak delta chart that visualizes memory allocation trends over time directly in the TUI. +- **Real time Memory Leak Detection**: Identify and monitor processes with growing, unreleased memory allocations. +- **Leak Delta Chart**: m-vis includes a real time leak delta chart that visualizes memory allocation trends over time directly in the TUI. - **Universal OS Support**: 100% native support for Windows, Linux, and macOS. --- ## 🔄 Core Workflows: How Leak Detection Works -The leak detector doesn't just watch total RAM usage; it takes deep topological snapshots of the process heap and computes exact block-level deltas to find silent unreleased memory. +The leak detector doesn't just watch total RAM usage; it takes deep topological snapshots of the process heap and computes exact block level deltas to find silent unreleased memory. ```mermaid sequenceDiagram @@ -115,7 +115,7 @@ sequenceDiagram ## 🔐 macOS Security & Code Signing -On macOS, `mvis` requires the `com.apple.security.cs.debugger` entitlement to inspect other processes due to Hardened Runtime restrictions. Even with `sudo`, inspecting third-party apps requires this entitlement. +On macOS, `mvis` requires the `com.apple.security.cs.debugger` entitlement to inspect other processes due to Hardened Runtime restrictions. Even with `sudo`, inspecting third party apps requires this entitlement. To build and run `mvis` on macOS: ```bash @@ -142,7 +142,7 @@ mvis scan notepad.exe -h # detect leaks mvis leak notepad.exe 10 -# multi-sample leak detection +# multi sample leak detection mvis leak-m notepad.exe 10 3 # list processes