trace_viz 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dad6986e31d5fab4d42a7e6820086bd39ad16d3dd7461b483425d06122533d56
-  data.tar.gz: ca9411d76b1134ad5e676264771e7046a6e52fbe250040f61c5b3294071d2578
+  metadata.gz: 33ae44f03b5cb5a5e546e27adf7d71e4100adb014659122b51ead6c185203b48
+  data.tar.gz: 712c78b3b7cd93f7512fa7f25a1bcf0a3424b45819ec52ae80c4a9b480385282
 SHA512:
-  metadata.gz: c66ab56494adc950558f5e9f21f8630178a262443440d70799ee43284ad03b0615e1031df8f24d495b9970b054c841c057d1858e629e5216c05c35a7485071b6
-  data.tar.gz: c30a273a89fa59c417e3974056916f135083ad50320dbb18c063b3db0c365231bb09118611770e1a158435997733101e9a917026245936ece186c73a7e9fcf71
+  metadata.gz: 178cd46ddd00503c6a7783d8697d7d90dfccb15980e3af6b0f8cdb39999809f4e5f0d541bb9809414149c1c0984ebaff485aa634b42b47aee2f2b1615b2d9cef
+  data.tar.gz: d61a9e82387c176eb31e06651c894ff3113924bcee1eaef10d23d47355f3eca3363165a6d63cb222c57aa0db908f4557c56e24c295496088c1213113fae14857

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

@@ -6,7 +6,15 @@
 [![Maintainability](https://api.codeclimate.com/v1/badges/e97579abe66f3477e71d/maintainability)](https://codeclimate.com/github/patrick204nqh/trace_viz/maintainability)
 ![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/pKjqLFNPxQFQWucTzcGMpt6QE.svg)](https://asciinema.org/a/pKjqLFNPxQFQWucTzcGMpt6QE)
 
 ## Installation
 
@@ -32,24 +40,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 +116,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>
+  <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 +175,50 @@ 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.                                 |
+|                   | `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` or other supported formats).        |
+|                   | `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`.
 
 ## Development
 
@@ -152,7 +248,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 +257,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!