issue-summoner

README

Issue Summoner

Turn those pesky todo comments into track-able issues that can be reported to your favorite source code hosting platform.


Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

Issue Summoner is a tool designed to streamline the process of managing issues in your codebase. Its primary function is to locate custom defined annotations within your project and use them to improve your issue tracking workflow. Your code can be scanned for these annotations, generate a summary directly in your terminal, and even report the issues to your preferred source code hosting platform.

After reporting an issue, you can use Issue Summoner to check the status of the issues and automatically clean up your code by removing the corresponding comments.

This tool helps keep track of tasks, and concerns to ensure that nothing is overlooked or forgotten in your development process.

Features

Custom Annotations

Define your own annotations to flag issues, tasks, or concerns directly within your code comments. Whether it's a single or multi line comment, you can include a custom annotation followed by a description. This makes it easy to keep track of issues directly in the context where they occur.

Summary

Analyze your codebase to detect and compile a summary of outstanding issues. This provides an overview, including the number of issues, where each issue resides (file name, line number, etc...) and a brief description.

Language Agnostic

Designed to work across different programming languages, each with its own syntax for comments.

Source Code Hosting Platform Adpaters

Integrate with code hosting platforms like GitHub, GitLab, and more. This allows you to publish detected issues from your codebase to your preferred platform.

Self Cleansing

Keep your codebase clean by checking the status of issues, that were reported with the tool. Once an issue has been marked as resolved on the hosting platform, the corresponding comment is automatically removed.

Reduced Context Switching

Minimize disruptions in your workflow by writing a quick note about the issue, or concern directly in the code. At any point during development, you can invoke the scan, or report command to review the newly added issues or publish them to a source code hosting platform, without needing to leave your development environment.

Built With

(back to top)

Getting Started

To get started, follow these steps:

Installation

Install using go. (Ensure you have Go on your system first.)

go install github.com/AntoninoAdornetto/issue-summoner@latest

(back to top)

Usage

Authorize Command

In order to publish issues to a source code hosting platform, we must first authorize the program to allow this. Authorizing will look different for each provider. As of now, I have added support for GitHub. More will be added in the near future.

• -s, --sch The source code hosting platform to authorize. (default is GitHub).

Authorize for GitHub

The device-flow is utilized to create an access token. The only thing you really need to know here is that when you run the command, you will be given a user code in the terminal and your default browser will open to https://github.com/login/device You will then be prompted to enter the user code while the program polls the authorization service for an access token. Once the steps are complete, the program will have all scopes it needs to report issues for you. Note: this does grant the program access to both public and private repositories.

issue-summoner authorize -s github

Scan Command

The scan command provides functionality for managing and reviewing issues that reside in your codebase. It serves as an aid to the report command through two primary modes. scanand purge mode. These modes help you manage and track issues directly within your codebase using custom annotations.

Scan Mode (Default)

In scan mode, the command analyzes your codebase to locate un-reported issues marked by a specific annotation flag (e.g., @TODO, @FIXME, etc). This mode is useful when you want to:

• Identify issues currently residing in your codebase that have not been reported yet
• Generate a summary of each un-reported issue that includes a description, location (file name, line number) of the issue.

Scan Mode usage

# will return a count of all issues that are annotated with @TODO
issue-summoner scan

# will return a count of all issues that are annotated with @FIXME
issue-summoner scan --annotation @FIXME

 # will return a count and detailed summary of each issue that is annotated with @TODO
issue-summoner scan --verbose

Purge Mode

In purge mode, the command analyzes your codebase to locate reported issues marked by a specific annotation flag that has been appended with an issue number (e.g., @TODO(#405)). This mode is useful when you want to:

• Identify issues that have been reported, to a source code hosting platform, but haven't been resolved as of yet.
• Generate a summary of each reported issue that includes a description, location (file name, line number) of the issue.
• Checks the status of all reported issues and will remove the comment entirely if it's been marked as resolved on the hosting platform it was reported to.

note: issue summoner obviously cannot keep track of issues that were reported outside of using the report command.

Purge Mode usage

# checks the status of each reported issue and returns the count of all open issues that are annotated with @TODO
issue-summoner scan --mode purge

# checks the status of each reported issue and return the count of all open issues that are annotated with @FIXME
issue-summoner scan --mode purge --annotation @FIXME

# shorthand flags
# checks the status of each reported issue and returns a detailed summary of each open issue that is annotated with @TODO
issue-summoner scan -m purge -v

Flags

• -a, --annotation string: The annotation to search for. Example: @TODO, @FIXME, etc. (Default is "@TODO").

• -d, --debug Log the stack trace when errors occur

• -h, --help Help for scan

• -m, --mode, string: scan: searches for annotations denoted with the --annotation flag. purge: searches for annotations that have been appended with an issue number and removes comments if issues are resolved.(Default is "scan")

• -p, --path string: the path to your local git directory. (Defaults to your working directory).

• -v, --verbose Log the details about each issue annotation that was located during the scan. Can be used with both scan, and purge modes.

Scan usage

# search for un-reported issues using @TEST_TODO annotation
# and log details about each issue, with verbose flag
issue-summoner scan -a @TEST_TODO -v

# check the status of all reported issues using the annotation @TEST_TODO,
# removes code comments, automatically, for all issues that have a status of resolved and
# print verbose output about all open issues
issue-summoner scan -a @TEST_TODO -m purge -v

Code Example

issues that have not been reported yet:

int main() {
  // @TODO do something useful in the main function
  return 0;
}

/*
* @TODO do something useful with the sum function
* for the love of god
*/
int sum(int a, int b) {
  return a + b;
}

issues that have been reported, using the report command:

int main() {
  // @TODO(#504) do something useful in the main function
  return 0;
}

/*
* @TODO(#505) do something useful with the sum function
* for the love of god
*/
int sum(int a, int b) {
  return a + b;
}

Report Command

Report is similar to the scan command but with added functionality. It allows you to report selected comments to a source code hosting platform. After all selections are uploaded, the issue id is written to the same location that the comment token is located. Meaning, your todo annotation will be transformed so that issue summoner can be used to remove the entire comment once the issue has been marked as resolved.

• -a, --annotation The annotation the program will search for. (default annotation is @TODO)

• -p, --path The path to your local git repository (defaults to your current working directory if a path is not provided)

• -s, --sch The souce code hosting platform you would like to upload issues to. Such as, github, gitlab, or bitbucket (default "github")

Report usage

issue-summoner report

You are then presented with a list of discovered issues that you can select to report.

j - navigate down the list

k - navigate up the list

space - select an item

y - confirm and report the selected issues

After the new issue is published, you will notice that your todo annotation is changed to @ISSUE(issue_id), here is an example of how it may look:

Before Report command

int main() {
  // @TODO do something usefull
  return 0;
}

After Report command

int main() {
  // @ISSUE(1999): do something usefull
  return 0;
}

(back to top)

Roadmap

• Lexical Analysis: Develop the core engine that scans source code for comment tokens.

  • C Lexer: scan & build comment tokens for c like languages
  • Python Lexer: scan & build comment tokens for python
  • Markdown Lexer: scan & build comment tokens for python
    
    

• Authenticate User to submit issues: Verify and Authenticate a user to allow the program to submit issues on the users behalf.

  • GitHub Device Flow
  • GitLab
  • BitBucket
    
    

• Source Code Hosting Adpaters: Implement a basic adapter for issue reporting functionality.

  • GitHub Adapter
  • GitLab Adapater
  • BitBucket Adapater

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Documentation

Overview

Copyright © 2024 Antonino Adornetto