Plot FS Tree (cargo plot-fs-tree / plot-fs-tree.ps1)

Narzędzie do wizualizacji struktury plików w terminalu. Skanuje katalogi na podstawie zaawansowanych wzorców (włączeń/wykluczeń) i generuje kolorowe drzewo ASCII z ikonami plików.

Dostępne są dwie implementacje o identycznej logice działania:

1. Rust (Cargo) - szybka, kompilowana, z interaktywnym menu (TUI) i obsługą argumentów CLI.
2. PowerShell - skryptowa, łatwa do uruchomienia na systemach Windows bez kompilacji.

💾 Pobieranie

• 💾 cargo-plot-fs-tree.exe
• git clone https://github.com/mod-by-cis/plot-path-tree-by-pattern.git

📦 Instalacja

Wersja Rust

Wymaga zainstalowanego Rust i Cargo.

# Instalacja lokalna z katalogu projektu
cargo install --path .

# Po instalacji narzędzie dostępne jest jako wtyczka cargo:
cargo plot-fs-tree

Można również używać skompilowanego pliku .exe bezpośrednio z katalogu target/release/.

Można też zrobić tak

cargo install --git https://github.com/mod-by-cis/plot-path-tree-by-pattern

Lub aby pobrać aktyualizacje

cargo install --git https://github.com/mod-by-cis/plot-path-tree-by-pattern --force

Wersja PowerShell

Nie wymaga instalacji. Wystarczy uruchomić skrypt:

.\ps1\plot-fs-tree.ps1

---

🚀 Użycie

Obie wersje generują ten sam wynik wizualny. Wersja Rust oferuje dodatkowo tryb interaktywny.

1. Tryb Interaktywny (Tylko Rust)

Uruchomienie bez argumentów włącza menu tekstowe, które prowadzi krok po kroku:

cargo plot-fs-tree

Pozwala to na:

• Wybór ustawień domyślnych.
• Dynamiczną zmianę lokalizacji i wzorców.
• Konfigurację sortowania.

2. Tryb CLI (Rust i PowerShell)

Narzędzia przyjmują parametry sterujące skanowaniem.

Rust (cargo plot-fs-tree lub cargo-plot-fs-tree.exe)

cargo plot-fs-tree -h

Flaga krótka	Flaga długa	Opis	Przykład
-l	--location	Ścieżka początkowa (domyślnie .)	-l "C:/Projekty"
-p	--patterns	Wzorce oddzielone przecinkami	-p "**/*.rs, !target/"
-s	--strategy	Sortowanie: name, ext-name, deep-ext	-s ext-name
	--dir-first	Wyświetl foldery przed plikami	--dir-first
	--ext-depth	Głębokość analizy rozszerzeń (dla deep-ext)	--ext-depth 2

Przykład:

cargo plot-fs-tree -l "." -p "**/*.rs, !target/" --dir-first

PowerShell (plot-fs-tree.ps1)

Parametr	Typ	Opis
-pathLocation	string	Ścieżka początkowa.
-pathPatterns	string[]	Tablica wzorców.
-sortStrategy	string	A (nazwa), B (rozszerzenie), C (deep).
-sortDirFirst	switch	Przełącznik: foldery najpierw.

Przykład:

.\ps1\plot-fs-tree.ps1 -pathLocation "." -pathPatterns "**/*.rs", "!target/" -sortDirFirst

---

⚙️ Zasady Działania i Logika

Oba narzędzia implementują ten sam autorski silnik skanujący, który różni się od standardowego .gitignore. Kluczową cechą jest obsługa tzw. Tunelowania (Tunneling).

1. Wzorce (Patterns)

Wzorce są konwertowane z formatu GLOB na wyrażenia regularne (Regex) z flagą ignorowania wielkości liter (Case Insensitive).

• **/* - Dopasuj wszystko (rekurencyjnie).
• !folder/ - Wyklucz folder (i jego zawartość).
• folder/plik.txt - Włącz konkretny plik.

2. Priorytety Filtrowania

Podczas odwiedzania każdego pliku/folderu, decyzja o jego wyświetleniu podejmowana jest w następującej kolejności:

1. Wykluczenia (Excludes): Jeśli ścieżka pasuje do wzorca zaczynającego się od !, jest oznaczana jako "w strefie zastrzeżonej".
2. Specyficzne Włączenia (Specific Includes): Jeśli ścieżka pasuje do konkretnego wzorca włączenia (np. target/debug/*.exe), jest przywracana nawet jeśli znajduje się w wykluczonym folderze.
3. Ogólne Włączenia (Generic Includes): Jeśli nie ma zakazu, a pasuje do **/*, jest włączana.

3. Mechanizm Tunelowania (Tunneling)

To najważniejsza logika pozwalająca na wyświetlanie plików wewnątrz wykluczonych folderów (np. .exe wewnątrz target/, mimo że target/ jest wykluczony).

Algorytm: Jeśli folder jest wykluczony (np. target/), skaner sprawdza, czy istnieje jakakolwiek reguła "Specyficznego Włączenia", która zaczyna się od ścieżki tego folderu (np. reguła target/debug/*.exe zaczyna się od target/).

• TAK: Folder jest traktowany jako "tunel" -> jest dodawany do drzewa, a skaner wchodzi do środka.
• NIE: Folder i jego zawartość są całkowicie ignorowane.

4. Sortowanie

• Priorytety: Pliki takie jak Cargo.toml, package.json są zawsze na górze (konfigurowalne w kodzie).
• Strategie:
• Name (A): Alfabetycznie.
• ExtName (B): Według rozszerzenia, potem nazwy.
• DeepExt (C): Analiza wieloczłonowych rozszerzeń (np. .tar.gz) do określonej głębokości.

---

🧩 Struktura Kodu (Porównanie Wersji)

Obie wersje posiadają analogiczne struktury danych i funkcje.

Funkcjonalność	Wersja Rust (main.rs)	Wersja PowerShell (plot-fs-tree.ps1)
Konfiguracja	struct Config, struct Args (Clap)	Parametry skryptu param(...)
Pojedyncza reguła	struct Rule (przechowuje Regex)	PSCustomObject (Regex + Metadata)
Konwersja Glob->Regex	fn glob_to_regex	function ConvertTo-Regex
Kontekst skanowania	struct ScanContext	function Initialize-ScanContext
Główna pętla (Silnik)	fn recursive_scan	function Scan-Dir
Rysowanie drzewa	fn print_tree_recursive	function Write-FileTree
Sortowanie	fn sort_items	function Get-SortKey
Ikony i kolory	fn get_icon	function Get-FileStyle / Get-DirStyle
Interfejs	inquire (Menu) + clap (CLI)	Parametry standardowe PowerShell

Kluczowe Biblioteki (Rust)

• clap - Parsowanie argumentów wiersza poleceń.
• inquire - Interaktywne menu tekstowe.
• regex - Obsługa wyrażeń regularnych (serce silnika filtrowania).
• colored - Kolorowanie wyjścia w terminalu.

---

📝 Przykładowe Konfiguracje Wzorców

Domyślna (Rust/Dev): Pokazuje strukturę projektu, pomija git i target, ale pokazuje pliki wykonywalne w target.

"**/*", "!.git/", "!target/", "target/debug/*.exe", "target/release/*.exe"

Tylko źródła:

"src/**/*", "Cargo.toml"

Frontend (Node/JS):

"**/*", "!node_modules/", "!.git/", "!dist/"

---