file_tree_visualizer 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d9ec7a6ef5ea0597b5efc056da74912985e0ca2f9a784398c13aa83b5e95c5a6
+  data.tar.gz: f3a9a8ee8fb984e8b135fefbe9db34b9e8f5df19ccf787538a754b975b5c9022
+SHA512:
+  metadata.gz: f902440430610f789db16ab282b2890e3569fa354691ee74dd1587539ad299aa2b7db9c66890496fd46429e1369da7b5d84db95b6c1614977559ffbef3b99c68
+  data.tar.gz: 9571ce07d3162b7e5477ae40f1a844c61e2ac476780e1665300778e1d811500b1b288e064b376e86a2f2305e1fad3e54a3a2dbbd80c106459f8638d4d96b835c

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,44 @@
+# file_tree_visualizer
+
+Gema Ruby para escanear árboles de archivos desde terminal y generar un reporte HTML interactivo 100% offline con los elementos que más espacio ocupan.
+
+## Qué hace
+
+- Recorre recursivamente una carpeta.
+- Calcula tamaño acumulado por directorio y tamaño por archivo.
+- Genera un reporte HTML con:
+  - Árbol de archivos expandible/colapsable.
+  - Filtros por texto y tamaño mínimo.
+  - Ranking de archivos más pesados.
+  - Sin dependencias externas (funciona sin internet).
+
+## Uso rápido (sin instalar la gema)
+
+```bash
+ruby bin/file-tree-visualizer /ruta/a/escanear -o reporte.html
+```
+
+## Uso como gema
+
+```bash
+bundle install
+gem build file_tree_visualizer.gemspec
+gem install ./file_tree_visualizer-0.0.3.gem
+file-tree-visualizer /ruta/a/escanear -o reporte.html
+```
+
+## Opciones
+
+```bash
+file-tree-visualizer [ruta] [opciones]
+
+Si no indicas `ruta`, se escanea el directorio actual por defecto.
+
+Durante el escaneo, en terminal interactiva se muestra una barra de progreso con archivos y directorios procesados vs total detectado.
+
+    -o, --output FILE           Archivo HTML de salida (default: file-tree-report.html)
+    -t, --top N                 Cantidad de archivos pesados a guardar en ranking (default: 200)
+        --follow-symlinks       Sigue enlaces simbólicos
+        --no-progress           Desactiva la barra de progreso
+    -h, --help                  Muestra ayuda
+```

data/Rakefile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"

data/bin/file-tree-visualizer

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/file_tree_visualizer"
+
+exit(FileTreeVisualizer::CLI.new(ARGV).run)

data/file_tree_visualizer.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "lib/file_tree_visualizer/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "file_tree_visualizer"
+  spec.version = FileTreeVisualizer::VERSION
+  spec.authors = ["jbidwell1"]
+  spec.email = ["devnull@example.com"]
+
+  spec.summary = "CLI Ruby tool to analyze file sizes and generate an interactive HTML report."
+  spec.description = "Scans a directory recursively, computes file/directory sizes, and generates an HTML report rendered with React."
+  spec.homepage = "https://example.com/file_tree_visualizer"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir[
+      "README.md",
+      "Gemfile",
+      "Rakefile",
+      "bin/*",
+      "lib/**/*.rb",
+      "file_tree_visualizer.gemspec"
+    ]
+  end
+  spec.bindir = "bin"
+  spec.executables = ["file-tree-visualizer"]
+  spec.require_paths = ["lib"]
+end

data/lib/file_tree_visualizer/cli.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module FileTreeVisualizer
+  class CLI
+    DEFAULT_OUTPUT = "file-tree-report.html"
+
+    def initialize(argv)
+      @argv = argv
+    end
+
+    def run
+      options, parser = parse_options(@argv.dup)
+      if options[:help]
+        puts parser
+        return 0
+      end
+
+      scanner = Scanner.new(top_limit: options[:top], follow_symlinks: options[:follow_symlinks])
+      progress = ProgressRenderer.new(enabled: options[:progress])
+      callback = options[:progress] ? progress.method(:render) : nil
+      result = scanner.scan(options[:path], progress: callback)
+      progress.finish
+      report = ReportBuilder.new(result: result, source_path: options[:path]).build
+
+      output_path = File.expand_path(options[:output])
+      File.write(output_path, report)
+
+      puts "Reporte generado en: #{output_path}"
+      puts "Escaneado: #{result.stats[:directories]} directorios, #{result.stats[:files]} archivos, #{result.stats[:skipped]} omitidos."
+      puts "Tamaño total: #{format_bytes(result.stats[:bytes])}"
+      0
+    rescue OptionParser::ParseError, ArgumentError => e
+      warn e.message
+      warn "Usa --help para ver las opciones disponibles."
+      1
+    rescue StandardError => e
+      warn "Error inesperado: #{e.message}"
+      1
+    end
+
+    private
+
+    class ProgressRenderer
+      BAR_WIDTH = 28
+
+      def initialize(io: $stdout, enabled: true)
+        @io = io
+        @enabled = enabled && io.tty?
+        @last_draw_at = nil
+        @has_rendered = false
+        @spinner_index = 0
+      end
+
+      def render(phase:, **data)
+        return unless @enabled
+
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        return if @last_draw_at && now - @last_draw_at < 0.05
+
+        @last_draw_at = now
+
+        if phase == :counting
+          render_counting(data)
+        else
+          render_scanning(data)
+        end
+
+        @has_rendered = true
+        @io.flush
+      end
+
+      def finish
+        return unless @enabled
+
+        @io.print("\n") if @has_rendered
+      end
+
+      private
+
+      def render_counting(data)
+        spinner = %w[| / - \\][@spinner_index % 4]
+        @spinner_index += 1
+        @io.print(format("\rPreparando escaneo %<spinner>s Arch:%<files>d Dir:%<dirs>d",
+                         spinner: spinner,
+                         files: data.fetch(:discovered_files, 0),
+                         dirs: data.fetch(:discovered_directories, 0)))
+      end
+
+      def render_scanning(data)
+        processed_files = data.fetch(:processed_files, 0)
+        total_files = data.fetch(:total_files, 0)
+        processed_directories = data.fetch(:processed_directories, 0)
+        total_directories = data.fetch(:total_directories, 0)
+        total_items = total_files + total_directories
+        processed_items = [processed_files + processed_directories, total_items].min
+
+        safe_total_items = total_items.positive? ? total_items : 1
+        progress_ratio = [processed_items.to_f / safe_total_items, 1.0].min
+        filled = (progress_ratio * BAR_WIDTH).round
+        empty = BAR_WIDTH - filled
+        percent = progress_ratio * 100
+
+        @io.print(format("\rEscaneando [%<bar>s] %<percent>6.2f%% Arch:%<pf>d/%<tf>d Dir:%<pd>d/%<td>d",
+                         bar: ("#" * filled) + ("-" * empty),
+                         percent: percent,
+                         pf: processed_files,
+                         tf: total_files,
+                         pd: processed_directories,
+                         td: total_directories))
+      end
+    end
+
+    def parse_options(argv)
+      options = {
+        path: Dir.pwd,
+        output: DEFAULT_OUTPUT,
+        top: Scanner::DEFAULT_TOP_LIMIT,
+        follow_symlinks: false,
+        progress: true,
+        help: false
+      }
+
+      parser = OptionParser.new do |opts|
+        opts.banner = "Uso: file-tree-visualizer [ruta] [opciones]"
+        opts.separator ""
+        opts.separator "Opciones:"
+
+        opts.on("-o", "--output FILE", "Archivo HTML de salida (default: #{DEFAULT_OUTPUT})") do |value|
+          options[:output] = value
+        end
+
+        opts.on("-t", "--top N", Integer, "Cantidad de archivos pesados en ranking (default: #{Scanner::DEFAULT_TOP_LIMIT})") do |value|
+          options[:top] = value
+        end
+
+        opts.on("--follow-symlinks", "Sigue enlaces simbólicos durante el escaneo") do
+          options[:follow_symlinks] = true
+        end
+
+        opts.on("--no-progress", "Desactiva la barra de progreso") do
+          options[:progress] = false
+        end
+
+        opts.on("-h", "--help", "Muestra esta ayuda") do
+          options[:help] = true
+        end
+      end
+
+      remaining = parser.parse(argv)
+      options[:path] = File.expand_path(remaining.first || options[:path])
+      raise ArgumentError, "--top debe ser mayor que 0" unless options[:top].positive?
+
+      [options, parser]
+    end
+
+    def format_bytes(bytes)
+      return "#{bytes} B" if bytes < 1024
+
+      units = %w[KB MB GB TB PB]
+      value = bytes.to_f / 1024
+      unit_index = 0
+
+      while value >= 1024 && unit_index < units.length - 1
+        value /= 1024
+        unit_index += 1
+      end
+
+      precision = value < 10 ? 2 : 1
+      format("%.#{precision}f %s", value, units[unit_index])
+    end
+  end
+end

data/lib/file_tree_visualizer/report_builder.rb

@@ -0,0 +1,443 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module FileTreeVisualizer
+  class ReportBuilder
+    def initialize(result:, source_path:, generated_at: Time.now.utc)
+      @result = result
+      @source_path = File.expand_path(source_path.to_s)
+      @generated_at = generated_at
+    end
+
+    def build
+      payload_json = JSON.generate(payload).gsub("</", "<\\/")
+      <<~HTML
+        <!doctype html>
+        <html lang="es">
+          <head>
+            <meta charset="utf-8" />
+            <meta name="viewport" content="width=device-width, initial-scale=1" />
+            <title>Reporte de archivos</title>
+            <style>
+              :root {
+                color-scheme: dark;
+                --bg: #0f172a;
+                --panel: #111827;
+                --panel-soft: #1f2937;
+                --text: #e5e7eb;
+                --muted: #94a3b8;
+                --accent: #38bdf8;
+                --ok: #34d399;
+                --border: #334155;
+              }
+              * {
+                box-sizing: border-box;
+              }
+              body {
+                margin: 0;
+                font-family: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+                background: var(--bg);
+                color: var(--text);
+              }
+              .container {
+                max-width: 1400px;
+                margin: 0 auto;
+                padding: 1rem;
+                display: flex;
+                flex-direction: column;
+                gap: 1rem;
+              }
+              .header {
+                display: flex;
+                flex-wrap: wrap;
+                justify-content: space-between;
+                align-items: center;
+                gap: 1rem;
+                border: 1px solid var(--border);
+                background: var(--panel);
+                border-radius: 12px;
+                padding: 1rem;
+              }
+              .header h1 {
+                margin: 0;
+                font-size: 1.2rem;
+              }
+              .meta {
+                color: var(--muted);
+                font-size: 0.9rem;
+              }
+              .stats {
+                display: grid;
+                grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+                gap: 0.6rem;
+              }
+              .stat {
+                border: 1px solid var(--border);
+                background: var(--panel);
+                border-radius: 10px;
+                padding: 0.7rem;
+              }
+              .stat-label {
+                color: var(--muted);
+                font-size: 0.82rem;
+              }
+              .stat-value {
+                font-size: 1rem;
+                margin-top: 0.2rem;
+              }
+              .filters {
+                border: 1px solid var(--border);
+                background: var(--panel);
+                border-radius: 10px;
+                padding: 0.8rem;
+                display: grid;
+                gap: 0.7rem;
+                grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+              }
+              .filters label {
+                display: flex;
+                flex-direction: column;
+                gap: 0.3rem;
+                font-size: 0.85rem;
+                color: var(--muted);
+              }
+              .filters input {
+                background: #0b1220;
+                border: 1px solid var(--border);
+                color: var(--text);
+                border-radius: 6px;
+                padding: 0.45rem 0.55rem;
+              }
+              .layout {
+                display: grid;
+                grid-template-columns: 2fr 1fr;
+                gap: 1rem;
+              }
+              .panel {
+                border: 1px solid var(--border);
+                background: var(--panel);
+                border-radius: 12px;
+                min-height: 400px;
+                overflow: hidden;
+                display: flex;
+                flex-direction: column;
+              }
+              .panel h2 {
+                margin: 0;
+                padding: 0.85rem 1rem;
+                border-bottom: 1px solid var(--border);
+                font-size: 1rem;
+              }
+              .panel-body {
+                padding: 0.75rem;
+                overflow: auto;
+              }
+              .node-row {
+                display: flex;
+                align-items: center;
+                gap: 0.4rem;
+                padding: 0.2rem 0;
+              }
+              .toggle-btn {
+                width: 1.2rem;
+                height: 1.2rem;
+                border: 1px solid var(--border);
+                background: var(--panel-soft);
+                color: var(--text);
+                border-radius: 4px;
+                cursor: pointer;
+                line-height: 1;
+                font-size: 0.8rem;
+              }
+              .file-dot {
+                width: 1.2rem;
+                text-align: center;
+                color: var(--muted);
+              }
+              .node-name {
+                flex: 1;
+                overflow: hidden;
+                text-overflow: ellipsis;
+                white-space: nowrap;
+              }
+              .node-size {
+                font-variant-numeric: tabular-nums;
+                color: var(--ok);
+                margin-left: auto;
+              }
+              table {
+                width: 100%;
+                border-collapse: collapse;
+              }
+              th,
+              td {
+                text-align: left;
+                padding: 0.45rem;
+                border-bottom: 1px solid var(--border);
+                font-size: 0.85rem;
+                vertical-align: top;
+              }
+              th {
+                color: var(--muted);
+                position: sticky;
+                top: 0;
+                background: var(--panel);
+              }
+              a {
+                color: var(--accent);
+                text-decoration: none;
+              }
+              a:hover {
+                text-decoration: underline;
+              }
+              .hint {
+                font-size: 0.8rem;
+                color: var(--muted);
+                margin-top: 0.2rem;
+              }
+              .empty-state {
+                color: var(--muted);
+                font-size: 0.9rem;
+                padding: 0.5rem 0.25rem;
+              }
+              @media (max-width: 1080px) {
+                .layout {
+                  grid-template-columns: 1fr;
+                }
+              }
+            </style>
+          </head>
+          <body>
+            <div id="app"></div>
+            <script id="scan-data" type="application/json">#{payload_json}</script>
+            <script>
+              (function () {
+                const data = JSON.parse(document.getElementById("scan-data").textContent);
+                const app = document.getElementById("app");
+
+                const state = {
+                  query: "",
+                  minSizeMb: 0,
+                  expanded: new Set([data.root.path])
+                };
+
+                const formatBytes = (bytes) => {
+                  if (bytes < 1024) return bytes + " B";
+                  const units = ["KB", "MB", "GB", "TB", "PB"];
+                  let value = bytes / 1024;
+                  let unitIndex = 0;
+                  while (value >= 1024 && unitIndex < units.length - 1) {
+                    value /= 1024;
+                    unitIndex += 1;
+                  }
+                  return value.toFixed(value < 10 ? 2 : 1) + " " + units[unitIndex];
+                };
+
+                const nodeMatches = (node, query, minBytes) => {
+                  const pathText = (node.name + " " + node.path).toLowerCase();
+                  const queryMatch = !query || pathText.includes(query);
+                  const sizeMatch = node.size >= minBytes;
+
+                  if (node.type === "file") return queryMatch && sizeMatch;
+                  if (queryMatch && sizeMatch) return true;
+                  return (node.children || []).some((child) => nodeMatches(child, query, minBytes));
+                };
+
+                const filters = () => ({
+                  query: state.query.trim().toLowerCase(),
+                  minBytes: Math.max(0, Number(state.minSizeMb || 0)) * 1024 * 1024
+                });
+
+                const formatNumber = (value) => Number(value || 0).toLocaleString();
+
+                app.innerHTML = [
+                  '<div class="container">',
+                  '  <header class="header">',
+                  '    <div>',
+                  '      <h1>Reporte de espacio en disco</h1>',
+                  '      <div class="meta" id="meta-source"></div>',
+                  '      <div class="meta" id="meta-generated"></div>',
+                  '    </div>',
+                  '  </header>',
+                  '  <section class="stats">',
+                  '    <div class="stat"><div class="stat-label">Tamaño total</div><div class="stat-value" id="stat-bytes"></div></div>',
+                  '    <div class="stat"><div class="stat-label">Archivos</div><div class="stat-value" id="stat-files"></div></div>',
+                  '    <div class="stat"><div class="stat-label">Directorios</div><div class="stat-value" id="stat-directories"></div></div>',
+                  '    <div class="stat"><div class="stat-label">Entradas omitidas</div><div class="stat-value" id="stat-skipped"></div></div>',
+                  '  </section>',
+                  '  <section class="filters">',
+                  '    <label>Buscar por nombre/ruta<input id="query-input" type="text" placeholder="ej: node_modules, .mp4, backup" /></label>',
+                  '    <label>Tamaño mínimo (MB)<input id="min-size-input" type="number" min="0" value="0" /><span class="hint">Filtra nodos y ranking por tamaño mínimo.</span></label>',
+                  '  </section>',
+                  '  <section class="layout">',
+                  '    <article class="panel">',
+                  '      <h2>Árbol de archivos</h2>',
+                  '      <div class="panel-body" id="tree-panel"></div>',
+                  '    </article>',
+                  '    <article class="panel">',
+                  '      <h2>Top archivos más pesados</h2>',
+                  '      <div class="panel-body">',
+                  '        <table>',
+                  '          <thead><tr><th>#</th><th>Tamaño</th><th>Ruta</th></tr></thead>',
+                  '          <tbody id="top-files-body"></tbody>',
+                  '        </table>',
+                  '      </div>',
+                  '    </article>',
+                  '  </section>',
+                  '</div>'
+                ].join("");
+
+                const queryInput = document.getElementById("query-input");
+                const minSizeInput = document.getElementById("min-size-input");
+                const treePanel = document.getElementById("tree-panel");
+                const topFilesBody = document.getElementById("top-files-body");
+
+                document.getElementById("meta-source").textContent = "Origen: " + data.source_path;
+                document.getElementById("meta-generated").textContent = "Generado: " + data.generated_at;
+                document.getElementById("stat-bytes").textContent = formatBytes(data.stats.bytes);
+                document.getElementById("stat-files").textContent = formatNumber(data.stats.files);
+                document.getElementById("stat-directories").textContent = formatNumber(data.stats.directories);
+                document.getElementById("stat-skipped").textContent = formatNumber(data.stats.skipped);
+
+                queryInput.addEventListener("input", (event) => {
+                  state.query = event.target.value || "";
+                  render();
+                });
+
+                minSizeInput.addEventListener("input", (event) => {
+                  state.minSizeMb = event.target.value;
+                  render();
+                });
+
+                const appendTreeNode = (node, depth, parent, activeFilters) => {
+                  if (!nodeMatches(node, activeFilters.query, activeFilters.minBytes)) return;
+
+                  const row = document.createElement("div");
+                  row.className = "node-row";
+                  row.style.paddingLeft = (depth * 14) + "px";
+
+                  if (node.type === "directory") {
+                    const button = document.createElement("button");
+                    button.className = "toggle-btn";
+                    button.textContent = state.expanded.has(node.path) ? "▾" : "▸";
+                    button.addEventListener("click", () => {
+                      if (state.expanded.has(node.path)) {
+                        state.expanded.delete(node.path);
+                      } else {
+                        state.expanded.add(node.path);
+                      }
+                      renderTree(activeFilters);
+                    });
+                    row.appendChild(button);
+                  } else {
+                    const dot = document.createElement("span");
+                    dot.className = "file-dot";
+                    dot.textContent = "•";
+                    row.appendChild(dot);
+                  }
+
+                  const name = document.createElement("span");
+                  name.className = "node-name";
+                  name.title = node.path;
+                  name.textContent = node.name;
+                  row.appendChild(name);
+
+                  const size = document.createElement("span");
+                  size.className = "node-size";
+                  size.textContent = formatBytes(node.size);
+                  row.appendChild(size);
+
+                  parent.appendChild(row);
+
+                  if (node.type === "directory" && state.expanded.has(node.path)) {
+                    const childrenWrap = document.createElement("div");
+                    parent.appendChild(childrenWrap);
+                    (node.children || []).forEach((child) => {
+                      appendTreeNode(child, depth + 1, childrenWrap, activeFilters);
+                    });
+                  }
+                };
+
+                const renderTree = (activeFilters) => {
+                  treePanel.innerHTML = "";
+                  if (!nodeMatches(data.root, activeFilters.query, activeFilters.minBytes)) {
+                    const empty = document.createElement("div");
+                    empty.className = "empty-state";
+                    empty.textContent = "Sin resultados con los filtros actuales.";
+                    treePanel.appendChild(empty);
+                    return;
+                  }
+                  appendTreeNode(data.root, 0, treePanel, activeFilters);
+                };
+
+                const renderTopFiles = (activeFilters) => {
+                  topFilesBody.innerHTML = "";
+                  const filtered = (data.top_files || []).filter((item) => {
+                    const pathMatch = !activeFilters.query || item.path.toLowerCase().includes(activeFilters.query);
+                    return pathMatch && item.size >= activeFilters.minBytes;
+                  });
+
+                  if (!filtered.length) {
+                    const emptyRow = document.createElement("tr");
+                    const cell = document.createElement("td");
+                    cell.colSpan = 3;
+                    cell.className = "empty-state";
+                    cell.textContent = "Sin archivos para mostrar con los filtros actuales.";
+                    emptyRow.appendChild(cell);
+                    topFilesBody.appendChild(emptyRow);
+                    return;
+                  }
+
+                  filtered.forEach((item, index) => {
+                    const row = document.createElement("tr");
+
+                    const indexCell = document.createElement("td");
+                    indexCell.textContent = String(index + 1);
+                    row.appendChild(indexCell);
+
+                    const sizeCell = document.createElement("td");
+                    sizeCell.textContent = formatBytes(item.size);
+                    row.appendChild(sizeCell);
+
+                    const pathCell = document.createElement("td");
+                    const link = document.createElement("a");
+                    link.href = "file://" + encodeURI(item.path);
+                    link.target = "_blank";
+                    link.rel = "noreferrer";
+                    link.textContent = item.path;
+                    pathCell.appendChild(link);
+                    row.appendChild(pathCell);
+
+                    topFilesBody.appendChild(row);
+                  });
+                };
+
+                const render = () => {
+                  const activeFilters = filters();
+                  renderTree(activeFilters);
+                  renderTopFiles(activeFilters);
+                };
+
+                render();
+              })();
+            </script>
+          </body>
+        </html>
+      HTML
+    end
+
+    private
+
+    def payload
+      {
+        source_path: @source_path,
+        generated_at: @generated_at.iso8601,
+        stats: @result.stats,
+        root: @result.root,
+        top_files: @result.top_files
+      }
+    end
+  end
+end

data/lib/file_tree_visualizer/scanner.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module FileTreeVisualizer
+  class Scanner
+    DEFAULT_TOP_LIMIT = 200
+    Result = Struct.new(:root, :top_files, :stats, keyword_init: true)
+
+    def initialize(top_limit: DEFAULT_TOP_LIMIT, follow_symlinks: false)
+      @top_limit = top_limit
+      @follow_symlinks = follow_symlinks
+      reset!
+    end
+
+    def scan(path, progress: nil)
+      reset!
+      expanded_path = File.expand_path(path.to_s)
+      raise ArgumentError, "La ruta no es un directorio: #{expanded_path}" unless File.directory?(expanded_path)
+
+      @progress_callback = progress
+      notify_counting_progress(force: true)
+      totals = count_totals(expanded_path)
+      notify_counting_progress(force: true)
+      @total_files = totals[:files]
+      @total_directories = totals[:directories]
+      @processed_files = 0
+      @processed_directories = 0
+      notify_progress
+
+      root = scan_directory(expanded_path)
+      @processed_files = @total_files if @processed_files < @total_files
+      @processed_directories = @total_directories if @processed_directories < @total_directories
+      notify_progress
+      top_files = @top_files.sort_by { |item| -item[:size] }
+      Result.new(
+        root: root,
+        top_files: top_files,
+        stats: {
+          bytes: root[:size],
+          files: @files_count,
+          directories: @directories_count,
+          skipped: @skipped_count
+        }
+      )
+    end
+
+    private
+
+    def reset!
+      @top_files = []
+      @files_count = 0
+      @directories_count = 0
+      @skipped_count = 0
+      @progress_callback = nil
+      @total_files = 0
+      @processed_files = 0
+      @total_directories = 0
+      @processed_directories = 0
+      @counted_files = 0
+      @counted_directories = 0
+    end
+
+    def scan_directory(path)
+      directory_name = File.basename(path)
+      directory_name = path if directory_name.nil? || directory_name.empty?
+
+      node = {
+        name: directory_name,
+        path: path,
+        type: "directory",
+        size: 0,
+        children: []
+      }
+
+      @directories_count += 1
+      @processed_directories += 1
+      notify_progress
+
+      entries = Dir.children(path)
+      entries.each do |entry_name|
+        child_path = File.join(path, entry_name)
+        process_child_node(child_path, entry_name, node)
+      rescue StandardError
+        @skipped_count += 1
+      end
+
+      node[:children].sort_by! { |child| [-child[:size], child[:name].downcase] }
+      node
+    rescue SystemCallError
+      @skipped_count += 1
+      node[:error] = true
+      node
+    end
+
+    def process_child_node(child_path, entry_name, parent_node)
+      if File.symlink?(child_path) && !@follow_symlinks
+        @skipped_count += 1
+        return
+      end
+
+      if File.directory?(child_path)
+        child_node = scan_directory(child_path)
+        parent_node[:children] << child_node
+        parent_node[:size] += child_node[:size]
+      elsif File.file?(child_path)
+        file_size = File.size(child_path)
+        file_node = {
+          name: entry_name,
+          path: child_path,
+          type: "file",
+          size: file_size
+        }
+        parent_node[:children] << file_node
+        parent_node[:size] += file_size
+        @files_count += 1
+        @processed_files += 1
+        notify_progress
+        remember_top_file(file_node)
+      else
+        @skipped_count += 1
+      end
+    rescue SystemCallError
+      @skipped_count += 1
+    end
+
+    def remember_top_file(file_node)
+      @top_files << {
+        name: file_node[:name],
+        path: file_node[:path],
+        size: file_node[:size]
+      }
+      return unless @top_files.length > @top_limit
+
+      @top_files.sort_by! { |item| item[:size] }
+      overflow = @top_files.length - @top_limit
+      @top_files.shift(overflow)
+    end
+
+    def count_totals(path)
+      totals = { files: 0, directories: 1 }
+      @counted_directories += 1
+      notify_counting_progress
+      entries = Dir.children(path)
+      entries.each do |entry_name|
+        child_path = File.join(path, entry_name)
+
+        begin
+          if File.symlink?(child_path) && !@follow_symlinks
+            next
+          elsif File.directory?(child_path)
+            child_totals = count_totals(child_path)
+            totals[:files] += child_totals[:files]
+            totals[:directories] += child_totals[:directories]
+          elsif File.file?(child_path)
+            totals[:files] += 1
+            @counted_files += 1
+            notify_counting_progress
+          end
+        rescue SystemCallError
+          next
+        end
+      end
+
+      totals
+    rescue SystemCallError
+      totals
+    end
+
+    def notify_progress
+      return unless @progress_callback
+
+      @progress_callback.call(
+        phase: :scanning,
+        processed_files: @processed_files,
+        total_files: @total_files,
+        processed_directories: @processed_directories,
+        total_directories: @total_directories
+      )
+    end
+
+    def notify_counting_progress(force: false)
+      return unless @progress_callback
+      return unless force || ((@counted_files + @counted_directories) % 200).zero?
+
+      @progress_callback.call(
+        phase: :counting,
+        discovered_files: @counted_files,
+        discovered_directories: @counted_directories
+      )
+    end
+  end
+end

data/lib/file_tree_visualizer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FileTreeVisualizer
+  VERSION = "0.0.3"
+end

data/lib/file_tree_visualizer.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "file_tree_visualizer/version"
+require_relative "file_tree_visualizer/scanner"
+require_relative "file_tree_visualizer/report_builder"
+require_relative "file_tree_visualizer/cli"
+
+module FileTreeVisualizer
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: file_tree_visualizer
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+platform: ruby
+authors:
+- jbidwell1
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-04 00:00:00.000000000 Z
+dependencies: []
+description: Scans a directory recursively, computes file/directory sizes, and generates
+  an HTML report rendered with React.
+email:
+- devnull@example.com
+executables:
+- file-tree-visualizer
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- Rakefile
+- bin/file-tree-visualizer
+- file_tree_visualizer.gemspec
+- lib/file_tree_visualizer.rb
+- lib/file_tree_visualizer/cli.rb
+- lib/file_tree_visualizer/report_builder.rb
+- lib/file_tree_visualizer/scanner.rb
+- lib/file_tree_visualizer/version.rb
+homepage: https://example.com/file_tree_visualizer
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://example.com/file_tree_visualizer
+  source_code_uri: https://example.com/file_tree_visualizer
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: CLI Ruby tool to analyze file sizes and generate an interactive HTML report.
+test_files: []