🚀 LDG - Linux Dependency Guide

🇮🇹 Leggi questo README in Italiano (Read in Italian)

LDG (Linux Dependency Guide) is a powerful, offline-first diagnostic utility that inventories installed software on your Linux machine and generates an interactive, high-fidelity visual dependency graph.

It maps native system packages (APT, DNF, Pacman, Zypper, Portage, APK), universal packages (Flatpak, Snap, AppImage), and OCI container engines (Docker, Podman, Distrobox) into a unified, interactive HTML visualizer.

---

🌟 Key Features

• 🔍 Multi-Engine Local Auditing: Direct, high-performance querying of native system package managers (Debian/Ubuntu APT, Arch Pacman, Fedora RPM/DNF, openSUSE Zypper, Gentoo Portage, Alpine APK) alongside modern app sandboxes (Flatpak, Snap, AppImage) and container infrastructures (Docker, Podman, Distrobox).
• 🎨 Dynamic Physical Graph: Render relationships using an offline-first 2D Physics Canvas engine. Nodes represent packages/repositories and dynamically repel or attract. Drag, zoom, pan, and double-click to navigate complex dependency paths. Styled with the Okabe-Ito high-contrast color palette.
• 🔄 Deep Configuration Differentials: Compare two different exports (e.g., migrating from an old PC to a new one). It identifies common, removed, or newly added packages, and instantly provides custom, distro-aware shell commands to align both systems.
• ⚡ Custom Update Manual & Failsafe OCI Operations: Based on the specific inventory detected on the host, LDG compiles a dynamic update guide. Offers a 4-step failsafe workflow for Docker/Podman container upgrades (Arrest, Backup-rename, Re-create, Clean up) with high-visibility amber security alerts to prevent operations disruption.
• 🌓 Auto-detecting Themes & Bilingual Support: Instantly toggles between stunning dark (default) and light themes with full browser scheme detection. Complete translation engine for English (en) and Italian (it) embedded directly in the single-page application.
• 🌈 Colorized Multi-Language CLI Help: Built-in --help with ANSI escape color highlighting over a solid black background. Recognizes system language (Euro5: it, en, es, fr, de) to render custom localized help screens and lists all script dependencies.

---

🚀 Getting Started

1. Generate the Export

Run the lightweight extraction script in your terminal. It will inventory your system packages and compile the standalone visualizer:

chmod +x ldg.sh
./ldg.sh

• This will create a compressed file named ldg-export-<machinename>-YYYY-MM-DD.json.gz containing the system state.
• It also generates ldg-viewer.html, a self-contained, 100% offline-friendly interactive dashboard.

2. Launch the Visualizer

Simply open ldg-viewer.html in any modern web browser.

• Drag and drop the generated ldg-export-*.json.gz file directly into the dropzone.
• Explore package stats, search/filter items, track recursive dependency pathways, and examine the interactive relationship graph!

---

🛠️ Command Line Interface

Usage:
  ./ldg.sh [OUTDIR]      Generate export and viewer HTML in target directory (defaults to current dir)
  ./ldg.sh --help        Display colorized multi-language command help
  ./ldg.sh --version     Display active version string (v1.0.0)

---

🔬 How It Works (Under The Hood)

1. Low-Level Extraction: The Bash script uses highly-optimized, distro-specific native queries (e.g. /var/db/pkg parsing for Portage, direct RPM database mapping for Fedora/RHEL to bypass DNF overhead, origin APT headers parsing for Debian) to collect accurate inventories in seconds, even in offline or containerized environments.
2. Universal Runtimes Parsing: Scans active Flatpak installations, local Snap indexes, and running OCI docker/podman daemon states to locate containers and translate original images.
3. Self-Healing HTML Template: Slices out the visualizer dynamically. If no packages are explicitly set as roots, the HTML self-heals by treating all detected items as root packages, preventing rendering errors.

---

📄 License & Usage Terms

This project is licensed under the Personal and Educational Free License (PEF License / PEFL) Version 1.0.

Terms at a Glance:

• 🟢 Personal & Educational Use: 100% Free. Anyone is allowed to use, copy, modify, and redistribute the Software free of charge for personal, domestic, academic, and non-profit/third-sector usage.
• 🔴 Corporate, Business & Enterprise Use: STRICTLY PROHIBITED without written authorization and payment of the corresponding usage fee agreed upon with the author. This includes use on corporate-owned machines, servers, or work environments, as well as places of worship and religious organizations.

Please read the full LICENSE and NOTICE files for details.

Author's Contact Details:

For licensing requests, commercial use authorizations, or inquiries, contact:

• Email: rubens@rainelli.it
• GitHub: https://github.com/RubensRainelli/
• Phone: (+39) 342 811 5882