trace_viz 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dad6986e31d5fab4d42a7e6820086bd39ad16d3dd7461b483425d06122533d56
-  data.tar.gz: ca9411d76b1134ad5e676264771e7046a6e52fbe250040f61c5b3294071d2578
+  metadata.gz: 8fffeaf37d8c9d9854f95159dba5ab2c8d9657a4ad63828e04164a79911ba4a3
+  data.tar.gz: 8c868e5bd2e954611c280fcb23a68cbf059f8314a98f7aaba2d3da909197e203
 SHA512:
-  metadata.gz: c66ab56494adc950558f5e9f21f8630178a262443440d70799ee43284ad03b0615e1031df8f24d495b9970b054c841c057d1858e629e5216c05c35a7485071b6
-  data.tar.gz: c30a273a89fa59c417e3974056916f135083ad50320dbb18c063b3db0c365231bb09118611770e1a158435997733101e9a917026245936ece186c73a7e9fcf71
+  metadata.gz: 25fa2eb78c78ad670bc3dd5e2819880154e4119c7260ab4127d35d7f75bcf56a23e237a0eb4cbbd893e2d3f6547a57496b432a214a2145770bdb252385d7dd94
+  data.tar.gz: f267c37003eaa0a4a4427e6faedac0e83827e3e5c6433bc22aee68a32b5b14a07abc51cf6d71bbfaf9aff3bfb0448cd381d1e168bb34e345d95c138478623635

data/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing to TraceViz
+
+Thank you for your interest in improving TraceViz! 🎉
+
+## Development Setup
+
+1. Fork and clone the repository.
+2. Run `bundle install` to install dependencies.
+3. Make your changes.
+4. Run `bin/rspec` to ensure all tests pass.
+5. Submit a Pull Request with a clear description.
+
+## Coding Standards
+
+- Follow the [Ruby Style Guide](https://github.com/rubocop/ruby-style-guide).
+- Write clear and descriptive commit messages.
+
+## Tests
+
+- All new functionality must be covered by tests.
+- Run `bin/rspec` before pushing changes.
+- Ensure 100% passing tests on CI.
+
+## Documentation
+
+- Update `README.md` if your changes affect usage.
+- Consider adding examples or improving existing ones.
+
+## Code of Conduct
+
+- Please be respectful and supportive of others.
+- Refer to [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) for details.
+
+Thank you for making TraceViz better! 🚀

data/README.md

@@ -2,11 +2,20 @@
 
 [![Gem Version](https://badge.fury.io/rb/trace_viz.svg)](https://rubygems.org/gems/trace_viz)
 [![Downloads](https://img.shields.io/gem/dt/trace_viz)](https://rubygems.org/gems/trace_viz)
-[![Build Status](https://github.com/patrick204nqh/trace_viz/actions/workflows/main.yml/badge.svg)](https://github.com/patrick204nqh/trace_viz/actions)
+[![Build Status](https://github.com/patrick204nqh/trace_viz/actions/workflows/ci.yml/badge.svg)](https://github.com/patrick204nqh/trace_viz/actions)
 [![Maintainability](https://api.codeclimate.com/v1/badges/e97579abe66f3477e71d/maintainability)](https://codeclimate.com/github/patrick204nqh/trace_viz/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/e97579abe66f3477e71d/test_coverage)](https://codeclimate.com/github/patrick204nqh/trace_viz/test_coverage)
 ![License](https://img.shields.io/github/license/patrick204nqh/trace_viz)
 
-TraceViz is a Ruby library designed to trace and visualize events executed in a block of code. It is useful for logging, debugging, and generating diagrams to understand code execution and flow. The gem allows you to customize how much detail you want to see, such as method calls, parameters, return values, and execution times.
+TraceViz is a Ruby library designed to trace and visualize events executed in a block of code. It is useful for logging, debugging, and generating diagrams to understand code execution and flow.
+
+> **Note:** The diagram generation feature is currently under development.
+
+The gem allows you to customize how much detail you want to see, such as method calls, parameters, return values, and execution times.
+
+## Demo
+
+[![asciicast](https://asciinema.org/a/lKXPPgx0muZuQbtvMu8GyHaOV.svg)](https://asciinema.org/a/lKXPPgx0muZuQbtvMu8GyHaOV)
 
 ## Installation
 
@@ -32,24 +41,55 @@ gem install trace_viz
 
 Wrap your code inside the TraceViz.trace block to start tracing its execution. The tracing behavior can be customized using various options:
 
+<details>
+  <summary>Configuration Example</summary>
+
 ```ruby
 TraceViz.trace(
-  tab_size: 2,
-  show_indent: true,
-  show_depth: true,
-  max_display_depth: 4, # Recommended to keep this value between 3 and 5
-  show_method_name: true,
-  show_source_location: false,
-  show_params: true,
-  show_return_value: true,
-  show_execution_time: true,
-  show_trace_events: [:call, :return]
+  general: {
+    tab_size: 4,
+    show_indent: true,
+    show_depth: true,
+    max_display_depth: 3,
+    show_method_name: true,
+  },
+  source_location: {
+    show: false,
+    truncate_length: 100,
+  },
+  params: {
+    show: true,
+    mode: :name_and_value,
+    truncate_values: 50,
+  },
+  result: {
+    show: true,
+    truncate_length: 50,
+  },
+  execution: {
+    show_time: true,
+    show_trace_events: [:call, :return],
+  },
+  filters: [
+    :exclude_internal_call,
+    :exclude_default_classes,
+    ...
+  ],
+  export: {
+    enabled: true,
+    path: "tmp",
+    format: :txt,
+    overwrite: false,
+  }
 ) do
   # Your code here
 end
 ```
 
-**Example**
+</details>
+
+<details>
+  <summary>Example Code</summary>
 
 ```ruby
 class Example
@@ -77,27 +117,56 @@ class Example
 end
 
 TraceViz.trace(
+  general: {
     tab_size: 4,
     show_indent: true,
     show_depth: true,
     max_display_depth: 3,
     show_method_name: true,
-    show_source_location: false,
-    show_params: true,
-    show_return_value: true,
-    show_execution_time: true,
-    show_trace_events: [:call, :return]
+  },
+  source_location: {
+    show: false,
+    truncate_length: 100,
+  },
+  params: {
+    show: true,
+    mode: :name_and_value,
+    truncate_values: 50,
+  },
+  result: {
+    show: true,
+    truncate_length: 50,
+  },
+  execution: {
+    show_time: true,
+    show_trace_events: [:call, :return],
+  },
+  filters: [
+    :exclude_internal_call,
+    include_classes: [Example]
+  ],
+  export: {
+    enabled: true,
+    path: "tmp",
+    format: :txt,
+    overwrite: false,
+  }
 ) do
   example = Example.new
   example.perform_task(5, 7)
 end
 ```
 
+</details>
+
 **Output**
 
+<details open>
+  <summary>Sample Output</summary>
+
 ```bash
-🚀   [START]   #depth:0 Example#perform_task (5, 7, nil)
-🚀   [START]       #depth:1 Example#add_numbers (5, 7, nil)
+🚀   [START]   #depth:0 Example#perform_task (5, 7)
+🚀   [START]       #depth:1 Example#add_numbers (5, 7)
 🚀   [START]           #depth:2 Example#multiply_by_factor (12, 2)
 🏁   [FINISH]          #depth:2 Example#multiply_by_factor #=> 24
 🏁   [FINISH]      #depth:1 Example#add_numbers #=> 24
@@ -107,22 +176,52 @@ Final result: 24
 🏁   [FINISH]  #depth:0 Example#perform_task #=> 24
 ```
 
+</details>
+
 ### Configuration Options
 
-| Option                 | Type             | Description                                                                      |
-| ---------------------- | ---------------- | -------------------------------------------------------------------------------- |
-| `tab_size`             | Integer          | Defines the number of spaces used for indentation when `show_indent` is enabled. |
-| `show_indent`          | Boolean          | Whether to visually indent nested calls.                                         |
-| `show_depth`           | Boolean          | Displays the depth level of the method call.                                     |
-| `max_display_depth`    | Integer          | Limits the display to a maximum depth of calls.                                  |
-| `show_method_name`     | Boolean          | Shows the name of the method being called.                                       |
-| `show_source_location` | Boolean          | Logs the source file name and line number where the method is defined.           |
-| `show_params`          | Boolean          | Logs the parameters passed to the method.                                        |
-| `show_return_value`    | Boolean          | Logs the return value of the method.                                             |
-| `show_execution_time`  | Boolean          | Logs the execution time for methods.                                             |
-| `show_trace_events`    | Array of Symbols | Specifies the events to trace. Valid values include:                             |
-|                        |                  | - `:call` - Log method calls.                                                    |
-|                        |                  | - `:return` - Log method returns.                                                |
+TraceViz provides extensive configuration options to customize tracing behavior.
+
+| Group             | Option                     | Type             | Default Value               | Description                                                                |
+| ----------------- | -------------------------- | ---------------- | --------------------------- | -------------------------------------------------------------------------- |
+| `general`         | `tab_size`                 | Integer          | 2                           | Number of spaces for indentation.                                          |
+|                   | `mode`                     | Symbol           | `:summary`                  | Display mode (`:summary` or `:verbose`).                                   |
+|                   | `group_keys`               | Array of Symbols | `[:event, :klass, :action]` | Keys to group similar outputs.                                             |
+|                   | `show_indent`              | Boolean          | true                        | Enables visual indentation for nested calls.                               |
+|                   | `show_depth`               | Boolean          | true                        | Displays the depth level of the method call.                               |
+|                   | `max_display_depth`        | Integer          | 3                           | Maximum depth of calls to display.                                         |
+|                   | `show_method_name`         | Boolean          | true                        | Logs the name of the method being executed.                                |
+| `source_location` | `show`                     | Boolean          | false                       | Logs the source file and line number for methods.                          |
+|                   | `truncate_length`          | Integer          | 100                         | Maximum length of displayed source location information.                   |
+| `params`          | `show`                     | Boolean          | true                        | Logs method parameters.                                                    |
+|                   | `mode`                     | Symbol           | `:name_and_value`           | Parameter display mode (`:name`, `:value`, or `:name_and_value`).          |
+|                   | `truncate_values`          | Integer          | 50                          | Maximum length of parameter values to display.                             |
+| `result`          | `show`                     | Boolean          | true                        | Logs method return values.                                                 |
+|                   | `truncate_length`          | Integer          | 50                          | Maximum length of return value logs.                                       |
+| `execution`       | `show_time`                | Boolean          | true                        | Logs execution time for methods.                                           |
+|                   | `show_trace_events`        | Array of Symbols | `[:call, :return]`          | Specifies the trace events to log (e.g., `:call`, `:return`).              |
+| `filters`         | `:exclude_internal_call`   | Symbol           | N/A                         | Exclude internal Ruby calls.                                               |
+|                   | `:exclude_default_classes` | Symbol           | N/A                         | Skip logging standard library classes.                                     |
+|                   | `:exclude_rails_framework` | Symbol           | N/A                         | Ignore Rails framework classes and methods.                                |
+|                   | `include_classes`          | Hash             | N/A                         | Specify classes to include in tracing.                                     |
+|                   | - `classes`                | Array            | []                          | List of class names to include (e.g., `["ClassName"]`).                    |
+|                   | `exclude_classes`          | Hash             | N/A                         | Specify classes to exclude from tracing.                                   |
+|                   | - `classes`                | Array            | []                          | List of class names to exclude (e.g., `["ClassName"]`).                    |
+|                   | `include_gems`             | Hash             | N/A                         | Include specific gems or runtime application gems.                         |
+|                   | - `app_running`            | Boolean          | true                        | Include the code of the application.                                       |
+|                   | - `app_path`               | String           | `Dir.pwd`                   | Path to the application (e.g., `Dir.pwd`).                                 |
+|                   | - `gems`                   | Array            | []                          | List of gems to include (e.g., `["gem1", "gem2"]`).                        |
+|                   | `exclude_gems`             | Hash             | N/A                         | Exclude specified gems.                                                    |
+|                   | - `gems`                   | Array            | []                          | List of gems to exclude (e.g., `["excluded_gem"]`).                        |
+| `export`          | `enabled`                  | Boolean          | true                        | Enables or disables exporting of trace logs.                               |
+|                   | `path`                     | String           | `"tmp"`                     | Directory for exported trace logs.                                         |
+|                   | `format`                   | Symbol           | `:txt`                      | Format for trace logs (`:txt`). `.json` and `.yaml` are under development. |
+|                   | `overwrite`                | Boolean          | false                       | Prevents overwriting of existing exported files.                           |
+
+### Notes
+
+- **Default Skipped Classes**: The following standard library classes are excluded by default when `:exclude_default_classes` is enabled:
+  - `Object`, `String`, `Array`, `Hash`, `Numeric`, `Integer`, `Float`, `Symbol`, `Kernel`, `Module`, `Class`, `Range`, `Regexp`, `Set`, `Gem`.
 
 ## Development
 
@@ -152,7 +251,7 @@ bundle install
 bin/rspec
 ```
 
-You can use `irb` or `pry` to test the gem locally. Make your changes, add tests, and ensure all tests pass before submitting a pull request.
+You can use `debug` or `pry` to test the gem locally. Make your changes, add tests, and ensure all tests pass before submitting a pull request.
 
 ## Contributing
 
@@ -161,7 +260,3 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/patric
 ## License
 
 TraceViz is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-
-## Acknowledgements
-
-Special thanks to the Ruby community for their continued support and inspiration!

data/Steepfile

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+D = Steep::Diagnostic
+
+target :lib do
+  signature "sig"
+  # ignore_signature "sig/test"
+
+  check "lib" # Directory name
+  # check "path/to/source.rb"         # File name
+  # check "app/models/**/*.rb"        # Glob
+  # ignore "lib/templates/*.rb"
+
+  # library "pathname"              # Standard libraries
+  # library "strong_json"           # Gems
+
+  # configure_code_diagnostics(D::Ruby.default)      # `default` diagnostics setting (applies by default)
+  # configure_code_diagnostics(D::Ruby.strict)       # `strict` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.lenient)      # `lenient` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.silent)       # `silent` diagnostics setting
+  # configure_code_diagnostics do |hash|             # You can setup everything yourself
+  #   hash[D::Ruby::NoMethod] = :information
+  # end
+end
+
+target :test do
+  unreferenced! # Skip type checking the `lib` code when types in `test` target is changed
+  # signature "sig/test"              # Put RBS files for tests under `sig/test`
+  check "test" # Type check Ruby scripts under `test`
+
+  configure_code_diagnostics(D::Ruby.lenient) # Weak type checking for test code
+
+  # library "pathname"              # Standard libraries
+end

data/examples/eu_central_bank.rb

@@ -0,0 +1,69 @@
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require 'eu_central_bank'
+require 'i18n'
+require 'trace_viz'
+
+# Fix the locale issue
+I18n.config.available_locales = [:en]
+I18n.locale = :en
+
+TraceViz.trace(
+  general: {
+    tab_size: 1,
+    mode: :summary,
+    show_indent: true,
+    show_depth: true,
+    max_display_depth: 5,
+    show_method_name: true,
+  },
+  params: {
+    show: true,
+    mode: :name_only,
+    # truncate_length: 10
+  },
+  result: {
+    show: true,
+    truncate_length: 15,
+  },
+  source_location: {
+    show: true,
+    truncate_length: 50,
+  },
+  execution: {
+    show_time: true,
+    show_trace_events: [:call, :return],
+  },
+  log: {
+    runtime: false,
+    post_collection: true,
+    stats: true
+  },
+  filters: [
+    :exclude_internal_call,
+    :exclude_default_classes,
+    # include_classes: {
+    #   classes: [EuCentralBank],
+    # },
+    # exclude_classes: {
+    #   classes: ['Gem']
+    # },
+    exclude_gems: {
+      gems: ['nokogiri', 'money', 'i18n']
+    }
+  ],
+  export: {
+    enabled: true,
+    format: :txt,
+    overwrite: true,
+  }
+) do
+  # Create a new instance of the EuCentralBank
+  bank = EuCentralBank.new
+
+  # Trace the update of exchange rates
+  bank.update_rates
+
+  # Trace conversion of currency
+  result = bank.exchange(50, 'USD', 'EUR')
+  puts "Converted amount: #{result}"
+end