file_tree_visualizer 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 487ea44c103965a0bf633fc0d618c50fb4a0c7d8ddbbee53b61f4d99a959d3f9
-  data.tar.gz: 89a961a923ab5ae1a9f83ada18f1951905e5ccde53219de8ba83fe5bd34b14f1
+  metadata.gz: b43d301f84619b7a620a0cbcef1d135d4906073efaecf03b737b43572ebd6d89
+  data.tar.gz: 65de782e8d5094d981f0bedd23e6307d1b6cd4eedebd6b8bbb412a9b303e330e
 SHA512:
-  metadata.gz: fd1eddbd5b1ae2b077e521f8ddd09dad953c12679aac80da81253cb18673a2f300d5146f86e244da85888b4872e59e823174c7a35e47f58aaa76cfa859e23cea
-  data.tar.gz: 7e91afaea1510c5c3ea03695666a1edac1390bd1be55c15c5bd9a6092bdc10a35f981bce7289f0a9a1e05ef5f0823c84a4da54161929a42868150dda92d90729
+  metadata.gz: f6a58da21e94d26fd62fa5a05bc5d0946a16525c187f021e7184b010515051f346b2c8786067879c278c34ca3abfbe61dc416f1a2bd170201654c71d477bffd0
+  data.tar.gz: ba3cb73876856ee460c66f1b34a61f1965cb6deda2021f52dba5904a8500b995e8cd4c28fd91bb1f388462a88c2d62e381024e94d1430dfaf591555344c674a8

data/README.md

@@ -1,5 +1,8 @@
 # file_tree_visualizer
 
+[![CI](https://github.com/JohnBidwellB/file-tree-visualizer/actions/workflows/release.yml/badge.svg)](https://github.com/JohnBidwellB/file-tree-visualizer/actions/workflows/release.yml)
+[![RubyGems](https://badge.fury.io/rb/file_tree_visualizer.svg)](https://rubygems.org/gems/file_tree_visualizer)
+
 Ruby gem to scan file trees from the terminal and generate a fully offline interactive HTML report with the items that consume the most disk space.
 
 ## What it does
@@ -30,7 +33,7 @@ file-tree-visualizer /path/to/scan -o report.html
 Install a specific version:
 
 ```bash
-gem install file_tree_visualizer -v 0.1.0
+gem install file_tree_visualizer -v 0.2.0
 ```
 
 ## Local development install
@@ -38,7 +41,7 @@ gem install file_tree_visualizer -v 0.1.0
 ```bash
 bundle install
 gem build file_tree_visualizer.gemspec
-gem install ./file_tree_visualizer-0.1.0.gem
+gem install ./file_tree_visualizer-0.2.0.gem
 file-tree-visualizer /path/to/scan -o report.html
 ```
 
@@ -55,6 +58,10 @@ During scanning, an interactive terminal shows a progress bar with processed fil
     -t, --top N                 Number of largest files to keep in ranking (default: 200)
         --follow-symlinks       Follow symbolic links
         --no-progress           Disable progress bar
+        --exclude PATTERNS      Exclude patterns (comma-separated or repeated)
+        --summary               Print summary to terminal
+        --json FILE             Export full result as JSON
+        --csv FILE              Export top files as CSV
         --lang LANG             Language for CLI and report (en|es)
     -h, --help                  Show help
 
@@ -64,12 +71,62 @@ Language resolution priority:
 - fallback to English (`en`)
 ```
 
+## Common workflows
+
+Summary only (no HTML file generated unless `--output` is explicitly provided):
+
+```bash
+file-tree-visualizer --summary
+```
+
+Summary + HTML report:
+
+```bash
+file-tree-visualizer . --summary --output report.html
+```
+
+Exclude directories and files by pattern:
+
+```bash
+file-tree-visualizer . --exclude "node_modules,.git,*.log" --exclude "tmp/**"
+```
+
+Export JSON and CSV in one run:
+
+```bash
+file-tree-visualizer . --summary --json scan.json --csv top-files.csv
+```
+
+## Contributing
+
+1. Create a feature branch from `main`.
+2. Implement your change and run tests locally.
+3. Push your branch and open a Pull Request.
+4. Wait for CI to pass and at least one approval.
+
+```bash
+git checkout -b feat/short-description
+bundle exec rake test
+git push origin feat/short-description
+```
+
+Branch policy:
+- For collaborators, `main` is protected and requires PR + CI + approval.
+- Repository admins can bypass these rules when needed.
+
 ## Automatic release to RubyGems
 
-- This repository publishes the gem automatically when pushing a tag with format `v*` (for example `v0.0.4`).
+- This repository publishes the gem automatically when pushing a tag with format `v*` (for example `v0.2.0`).
 - Before using it, configure the `RUBYGEMS_API_KEY` secret in GitHub Actions.
+- You can also trigger the workflow manually from GitHub Actions (`workflow_dispatch`).
+
+```bash
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+Reusable release notes template:
 
 ```bash
-git tag v0.0.4
-git push origin v0.0.4
+gh release create v0.2.0 --title "v0.2.0" --notes-file .github/release-template.md
 ```

data/file_tree_visualizer.gemspec

@@ -5,8 +5,8 @@ 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.authors = ['John Bidwell']
+  spec.email = ['johnbidwellb@gmail.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.'
@@ -14,7 +14,8 @@ Gem::Specification.new do |spec|
   spec.license = 'MIT'
   spec.required_ruby_version = '>= 2.7'
 
-  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = "#{spec.homepage}/tree/main"
+  spec.metadata['bug_tracker_uri'] = "#{spec.homepage}/issues"
   spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
 
   spec.files = Dir.chdir(__dir__) do
@@ -30,4 +31,5 @@ Gem::Specification.new do |spec|
   spec.bindir = 'bin'
   spec.executables = ['file-tree-visualizer']
   spec.require_paths = ['lib']
+  spec.add_dependency 'csv', '~> 3.3'
 end

data/lib/file_tree_visualizer/cli.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'optparse'
+require 'csv'
+require 'json'
 
 module FileTreeVisualizer
   class CLI
@@ -24,22 +26,30 @@ module FileTreeVisualizer
               t(locale, 'cli.errors.invalid_directory', path: expanded_path)
       end
 
-      scanner = Scanner.new(top_limit: options[:top], follow_symlinks: options[:follow_symlinks])
+      scanner = Scanner.new(
+        top_limit: options[:top],
+        follow_symlinks: options[:follow_symlinks],
+        excludes: options[:exclude_patterns]
+      )
       progress = ProgressRenderer.new(enabled: options[:progress], locale: locale)
       callback = options[:progress] ? progress.method(:render) : nil
       result = scanner.scan(expanded_path, progress: callback)
       progress.finish
-      report = ReportBuilder.new(result: result, source_path: expanded_path, locale: locale).build
-
-      output_path = File.expand_path(options[:output])
-      File.write(output_path, report)
-
-      puts t(locale, 'cli.messages.report_generated', path: output_path)
-      puts t(locale, 'cli.messages.scanned',
-             directories: result.stats[:directories],
-             files: result.stats[:files],
-             skipped: result.stats[:skipped])
-      puts t(locale, 'cli.messages.total_size', size: format_bytes(result.stats[:bytes]))
+      generated_at = Time.now.utc
+      output_path = maybe_write_report(options, expanded_path, result, locale, generated_at)
+      json_path = write_json_export(options[:json_output], expanded_path, result, locale, generated_at)
+      csv_path = write_csv_export(options[:csv_output], result)
+      print_summary(expanded_path, result, locale) if options[:summary]
+      puts t(locale, 'cli.messages.report_generated', path: output_path) if output_path
+      puts t(locale, 'cli.messages.json_generated', path: json_path) if json_path
+      puts t(locale, 'cli.messages.csv_generated', path: csv_path) if csv_path
+      unless options[:summary]
+        puts t(locale, 'cli.messages.scanned',
+               directories: result.stats[:directories],
+               files: result.stats[:files],
+               skipped: result.stats[:skipped])
+      end
+      puts t(locale, 'cli.messages.total_size', size: format_bytes(result.stats[:bytes])) unless options[:summary]
       0
     rescue OptionParser::ParseError, ArgumentError => e
       locale = error_locale
@@ -133,6 +143,11 @@ module FileTreeVisualizer
         top: Scanner::DEFAULT_TOP_LIMIT,
         follow_symlinks: false,
         progress: true,
+        summary: false,
+        output_given: false,
+        json_output: nil,
+        csv_output: nil,
+        exclude_patterns: [],
         lang: nil,
         help: false
       }
@@ -164,6 +179,7 @@ module FileTreeVisualizer
 
         opts.on('-o', '--output FILE', t(locale, 'cli.output_option', default: DEFAULT_OUTPUT)) do |value|
           options[:output] = value
+          options[:output_given] = true
         end
 
         opts.on('-t', '--top N', Integer, t(locale, 'cli.top_option', default: Scanner::DEFAULT_TOP_LIMIT)) do |value|
@@ -178,6 +194,22 @@ module FileTreeVisualizer
           options[:progress] = false
         end
 
+        opts.on('--exclude PATTERNS', t(locale, 'cli.exclude_option')) do |value|
+          options[:exclude_patterns].concat(split_patterns(value))
+        end
+
+        opts.on('--summary', t(locale, 'cli.summary_option')) do
+          options[:summary] = true
+        end
+
+        opts.on('--json FILE', t(locale, 'cli.json_option')) do |value|
+          options[:json_output] = value
+        end
+
+        opts.on('--csv FILE', t(locale, 'cli.csv_option')) do |value|
+          options[:csv_output] = value
+        end
+
         opts.on('--lang LANG', t(locale, 'cli.lang_option')) do |value|
           options[:lang] = value
         end
@@ -198,6 +230,10 @@ module FileTreeVisualizer
       nil
     end
 
+    def split_patterns(value)
+      value.to_s.split(',').map(&:strip).reject(&:empty?)
+    end
+
     def t(locale, key, **vars)
       I18n.t(locale, key, **vars)
     end
@@ -221,5 +257,72 @@ module FileTreeVisualizer
       precision = value < 10 ? 2 : 1
       format("%.#{precision}f %s", value, units[unit_index])
     end
+
+    def maybe_write_report(options, source_path, result, locale, generated_at)
+      should_write = !options[:summary] || options[:output_given]
+      return nil unless should_write
+
+      report = ReportBuilder.new(
+        result: result,
+        source_path: source_path,
+        locale: locale,
+        generated_at: generated_at
+      ).build
+      output_path = File.expand_path(options[:output])
+      File.write(output_path, report)
+      output_path
+    end
+
+    def write_json_export(target_path, source_path, result, locale, generated_at)
+      return nil unless target_path
+
+      output_path = File.expand_path(target_path)
+      payload = {
+        source_path: source_path,
+        generated_at: generated_at.iso8601,
+        locale: locale,
+        version: FileTreeVisualizer::VERSION,
+        stats: result.stats,
+        root: result.root,
+        top_files: result.top_files
+      }
+      File.write(output_path, JSON.pretty_generate(payload))
+      output_path
+    end
+
+    def write_csv_export(target_path, result)
+      return nil unless target_path
+
+      output_path = File.expand_path(target_path)
+      CSV.open(output_path, 'w') do |csv|
+        csv << %w[rank path name size_bytes size_human]
+        result.top_files.each_with_index do |item, index|
+          csv << [index + 1, item[:path], item[:name], item[:size], format_bytes(item[:size])]
+        end
+      end
+      output_path
+    end
+
+    def print_summary(source_path, result, locale)
+      puts t(locale, 'cli.summary.heading')
+      puts t(locale, 'cli.summary.source', path: source_path)
+      puts t(locale, 'cli.summary.total_size', size: format_bytes(result.stats[:bytes]))
+      puts t(locale, 'cli.summary.files', count: result.stats[:files])
+      puts t(locale, 'cli.summary.directories', count: result.stats[:directories])
+      puts t(locale, 'cli.summary.skipped', count: result.stats[:skipped])
+      puts t(locale, 'cli.summary.top_files')
+
+      if result.top_files.empty?
+        puts "  #{t(locale, 'cli.summary.none')}"
+        return
+      end
+
+      result.top_files.each_with_index do |item, index|
+        puts format('  %<rank>d. %<size>s  %<path>s',
+                    rank: index + 1,
+                    size: format_bytes(item[:size]),
+                    path: item[:path])
+      end
+    end
   end
 end

data/lib/file_tree_visualizer/i18n.rb

@@ -13,10 +13,16 @@ module FileTreeVisualizer
           'top_option' => 'Number of largest files in ranking (default: %<default>s)',
           'follow_symlinks_option' => 'Follow symbolic links during scan',
           'no_progress_option' => 'Disable progress bar',
+          'exclude_option' => 'Exclude patterns (comma-separated or repeated)',
+          'summary_option' => 'Print terminal summary',
+          'json_option' => 'Export scan result as JSON',
+          'csv_option' => 'Export top files as CSV',
           'lang_option' => 'Language for CLI and report (en|es)',
           'help_option' => 'Show this help',
           'messages' => {
             'report_generated' => 'Report generated at: %<path>s',
+            'json_generated' => 'JSON exported at: %<path>s',
+            'csv_generated' => 'CSV exported at: %<path>s',
             'scanned' => 'Scanned: %<directories>s directories, %<files>s files, %<skipped>s skipped.',
             'total_size' => 'Total size: %<size>s'
           },
@@ -30,6 +36,16 @@ module FileTreeVisualizer
           'progress' => {
             'preparing' => 'Preparing scan %<spinner>s Files:%<files>s Dirs:%<dirs>s',
             'scanning' => 'Scanning [%<bar>s] %<percent>s%% Files:%<pf>s/%<tf>s Dirs:%<pd>s/%<td>s'
+          },
+          'summary' => {
+            'heading' => 'Summary',
+            'source' => 'Source: %<path>s',
+            'total_size' => 'Total size: %<size>s',
+            'files' => 'Files: %<count>s',
+            'directories' => 'Directories: %<count>s',
+            'skipped' => 'Skipped entries: %<count>s',
+            'top_files' => 'Top files:',
+            'none' => '(none)'
           }
         },
         'report' => {
@@ -72,10 +88,16 @@ module FileTreeVisualizer
           'top_option' => 'Cantidad de archivos pesados en ranking (default: %<default>s)',
           'follow_symlinks_option' => 'Sigue enlaces simbólicos durante el escaneo',
           'no_progress_option' => 'Desactiva la barra de progreso',
+          'exclude_option' => 'Excluye patrones (separados por coma o repetidos)',
+          'summary_option' => 'Imprime resumen en terminal',
+          'json_option' => 'Exporta resultado del escaneo como JSON',
+          'csv_option' => 'Exporta top de archivos como CSV',
           'lang_option' => 'Idioma para CLI y reporte (en|es)',
           'help_option' => 'Muestra esta ayuda',
           'messages' => {
             'report_generated' => 'Reporte generado en: %<path>s',
+            'json_generated' => 'JSON exportado en: %<path>s',
+            'csv_generated' => 'CSV exportado en: %<path>s',
             'scanned' => 'Escaneado: %<directories>s directorios, %<files>s archivos, %<skipped>s omitidos.',
             'total_size' => 'Tamano total: %<size>s'
           },
@@ -89,6 +111,16 @@ module FileTreeVisualizer
           'progress' => {
             'preparing' => 'Preparando escaneo %<spinner>s Arch:%<files>s Dir:%<dirs>s',
             'scanning' => 'Escaneando [%<bar>s] %<percent>s%% Arch:%<pf>s/%<tf>s Dir:%<pd>s/%<td>s'
+          },
+          'summary' => {
+            'heading' => 'Resumen',
+            'source' => 'Origen: %<path>s',
+            'total_size' => 'Tamano total: %<size>s',
+            'files' => 'Archivos: %<count>s',
+            'directories' => 'Directorios: %<count>s',
+            'skipped' => 'Entradas omitidas: %<count>s',
+            'top_files' => 'Top archivos:',
+            'none' => '(ninguno)'
           }
         },
         'report' => {

data/lib/file_tree_visualizer/scanner.rb

@@ -5,9 +5,10 @@ module FileTreeVisualizer
     DEFAULT_TOP_LIMIT = 200
     Result = Struct.new(:root, :top_files, :stats, keyword_init: true)
 
-    def initialize(top_limit: DEFAULT_TOP_LIMIT, follow_symlinks: false)
+    def initialize(top_limit: DEFAULT_TOP_LIMIT, follow_symlinks: false, excludes: [])
       @top_limit = top_limit
       @follow_symlinks = follow_symlinks
+      @excludes = Array(excludes).map(&:to_s).reject(&:empty?)
       reset!
     end
 
@@ -16,6 +17,8 @@ module FileTreeVisualizer
       expanded_path = File.expand_path(path.to_s)
       raise ArgumentError, "Path is not a directory: #{expanded_path}" unless File.directory?(expanded_path)
 
+      @root_path = expanded_path
+
       @progress_callback = progress
       notify_counting_progress(force: true)
       totals = count_totals(expanded_path)
@@ -57,6 +60,7 @@ module FileTreeVisualizer
       @processed_directories = 0
       @counted_files = 0
       @counted_directories = 0
+      @root_path = nil
     end
 
     def scan_directory(path)
@@ -78,6 +82,11 @@ module FileTreeVisualizer
       entries = Dir.children(path)
       entries.each do |entry_name|
         child_path = File.join(path, entry_name)
+        if excluded_path?(child_path)
+          @skipped_count += 1
+          next
+        end
+
         process_child_node(child_path, entry_name, node)
       rescue StandardError
         @skipped_count += 1
@@ -142,6 +151,7 @@ module FileTreeVisualizer
       entries = Dir.children(path)
       entries.each do |entry_name|
         child_path = File.join(path, entry_name)
+        next if excluded_path?(child_path)
 
         begin
           if File.symlink?(child_path) && !@follow_symlinks
@@ -165,6 +175,22 @@ module FileTreeVisualizer
       totals
     end
 
+    def excluded_path?(path)
+      return false if @excludes.empty?
+
+      basename = File.basename(path)
+      relative = relative_path(path)
+      flags = File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB
+
+      @excludes.any? do |pattern|
+        File.fnmatch?(pattern, basename, flags) || File.fnmatch?(pattern, relative, flags)
+      end
+    end
+
+    def relative_path(path)
+      path.delete_prefix("#{@root_path}/")
+    end
+
     def notify_progress
       return unless @progress_callback
 

data/lib/file_tree_visualizer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FileTreeVisualizer
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,19 +1,33 @@
 --- !ruby/object:Gem::Specification
 name: file_tree_visualizer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
-- jbidwell1
+- John Bidwell
 autorequire:
 bindir: bin
 cert_chain: []
 date: 2026-04-04 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
 description: Scans a directory recursively, computes file/directory sizes, and generates
   an HTML report rendered with React.
 email:
-- devnull@example.com
+- johnbidwellb@gmail.com
 executables:
 - file-tree-visualizer
 extensions: []
@@ -34,7 +48,8 @@ homepage: https://github.com/JohnBidwellB/file-tree-visualizer
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/JohnBidwellB/file-tree-visualizer
+  source_code_uri: https://github.com/JohnBidwellB/file-tree-visualizer/tree/main
+  bug_tracker_uri: https://github.com/JohnBidwellB/file-tree-visualizer/issues
   changelog_uri: https://github.com/JohnBidwellB/file-tree-visualizer/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []