Crate bug

Crate bug 

Source
Expand description

§bug_rs

A simple Rust library for printing a tracing-style error in the event of a bug and allowing users to easily file a bug report via GitHub issues using bug templates.

§Features

  • Define reusable issue templates with named parameters
  • Load templates from markdown files using include_str! macro
  • Print formatted bug reports to stderr (similar to tracing output)
  • Generate clean GitHub issue URLs with pre-filled templates
  • Support for multiple issue templates per project
  • URL encoding for special characters
  • Optional labels for GitHub issues
  • Parameter validation ensures all placeholders are filled

§Quick Start

use bug_rs::{bug, init, IssueTemplate};

// Initialize with your GitHub repository
init("username", "repository")
    .add_template("crash", IssueTemplate::new(
        "Application Crash: {error_type}",
        "## Description\nThe application crashed with error: {error_type}\n\n## Context\n- Function: {function}\n- Line: {line}"
    ).with_labels(vec!["bug".to_string(), "crash".to_string()]))
    .build()?;

// Later in your code, when a bug occurs:
let url = bug!("crash", {
    error_type = "NullPointerException",
    function = "calculate_sum",
    line = "42"
});
 
println!("Bug report URL: {}", url);

§Advanced Usage

§Using Template Files

Create a markdown template file with placeholders:

templates/crash_report.md:

Application Crash: {error_type}

## Description
The application crashed with error: {error_type}

## Context
- Function: {function}
- Line: {line}
- OS: {os}

Then load it in your Rust code:

use bug_rs::{init, template_file};

init("myorg", "myproject")
    .add_template_file("crash", template_file!("templates/crash_report.md", labels: ["bug", "crash"]))
    .build()?;

§Multiple Templates

use bug_rs::{init, IssueTemplate, template_file};

init("myorg", "myproject")
    .add_template("simple", IssueTemplate::new(
        "Simple Issue: {title}",
        "Description: {description}"
    ))
    .add_template_file("detailed", template_file!("templates/detailed_report.md"))
    .build()?;

§Using the bug! Macro

The bug! macro provides a clean API similar to tracing macros:


// Simple usage without parameters
bug!("error");

// With named parameters
bug!("performance", {
    operation = "database_query",
    expected = 100,
    actual = 1500,
    os = std::env::consts::OS,
    version = env!("CARGO_PKG_VERSION")
});

§Output Format

When bug!() is called, it prints to stderr in a format similar to tracing:

🐛 BUG ENCOUNTERED in src/main.rs:45
   Template: crash
   Parameters:
     error_type: NullPointerException
     function: calculate_sum
     line: 42
   File a bug report: https://github.com/username/repository/issues/new?title=Application%20Crash%3A%20NullPointerException&body=...

Macros§

bug
template_file

Structs§

BugReportConfig
BugReportConfigBuilder
IssueTemplate
TemplateFile

Enums§

HyperlinkMode

Functions§

create_terminal_hyperlink
Creates a terminal hyperlink using ANSI escape sequences Format: \x1b]8;;URL\x1b\TEXT\x1b]8;;\x1b\
generate_github_url
get_hyperlink_mode
Gets the hyperlink mode from configuration
init
supports_hyperlinks
Detects if the terminal supports hyperlinks by checking environment variables