Go Issue Summoner

Turn your comments into trackable issues that are reported to your favorite source code management system.


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

Development Status 🚧

This repo is under active development. I am in the early stages of building out the core features. As such, some parts of the program may be missing and change significantly.

About The Project

Go Issue Summoner is a tool that will streamline the process of creating issues within your code base. It works by scanning source code files for special annotations (that you define and pass into the program via a flag) and automatically creates issues on a source code management platform of your choosing. This process will ensure that no important task or concern is overlooked.

Core Features

• Customizable Annotations: Define your own set of annotations, that you would use in a single or multi line comment to mark tasks, concerns, or areas of code that require attention.

• Language Agnostic: Annotations are scanned and discovered by locating single and multi line comments and then parsing the information surrounding the annotation. This process is language agnostic and uses the current file extension (when walking the directory) to determine the the proper syntax for a single or multi line comment. Note: Additional language support will be added soon

• SCM Adapters: Support multiple source code management platforms. GitHub, GitLab, BitBucket etc...

• Minimized Context Switching: Developers can write a quick note in their source code file about the issue and then run the report command. Those details will be pushed to the source code management platform you selected and will allow the developer to continue on with their original task with minimal context switching.

• Discover Issues for contributing to open source projects: Contributing to open source can be a daunting task. Where does one start? What issue should I tackle first? Well, issue-summoner can be used to locate forgotten issues that may have never been reported and were forgotten about. Simply running issue-summoner scan on your favorite open source project may return hundreds of TODO: annotations that went under the radar. What a great place to start!

(back to top)

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 management system, 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. I will be adding more in the near future.

• -s, --scm The source code management 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

Scans your local git project for comments that are denoted with an annotation. Details about the comment are constructed through lexical analysis. Each programming language uses it's own lexer to gather the comment tokens and parse information about the comment. Scan is a preliminary command that may be used prior to the report command. This will give you an idea of the issue annotations that reside in your project.

• -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)

• -m, --mode The two modes are pending and processed. Meaning, you can scan for annotations that have not been uploaded to a source code management platform, I.E pending, or you can scan for annotations that have been published, I.E processed. Processed annotations will look differently than pending annotations because when issues are reported, the program will update the comment, write to the file at the location of the comment, and append the issue id that is tied to the comment. This is so the comment can be removed after it's been resolved.

• -v, --verbose Logs detailed information about each issue annotation that was located during the scan.

Scan Usage

issue-summoner scan

The command will walk your git project directory and check each source file. It adheres to the rules of your projects .gitignore file and skips entire directories and files when it finds a match. Yes, you do not need to worry about your node_modules folder being scanned! The comment syntax to use for each file is based on the files extension. Most languages are supported and more are to come! Let's take a look at an example that uses a single line comment for a C file:

#include <stdio.h>

// @TODO implement the main function
int main() {
    printf("Hello world\n");
    return 0;
}

Basic usage of the command would result in the following:

We can get a little more information about the annotation by passing the verbose flag -v the result would be:

You may have noticed that there is not a description. This is because single line comments are concise. However, we can be more granular by utilizing a multi line comment:

#include <stdio.h>

int main() {
  /*
   * @TODO implement the main function
   * The main function does nothing useful.
   * Remove the print statement and build something that is useful!
   * */
  printf("Hello world\n");
  return 0;
}

The new result using a multi line comment:

Report Command

Report is similar to the scan command but with added functionality. It allows you to report selected comments to a source code management 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, --scm The souce code management 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
    
    

• 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
    
    

• SCM Adapter: 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)