issue

Documentation

Overview

THIS FILE IS RESPONSIBLE FOR LOCATING, REPORTING AND MANAGING ISSUES THAT RESIDE WITHIN SOURCE CODE COMMENTS.

ISSUE ANNOTATIONS ARE LOCATED BY WALKING [Walk] THE WORKING TREE AND SCANNING/TOKENIZING [Scan] SOURCE CODE COMMENTS. SEE THE LEXER PACKAGE FOR DETAILS ON THE LEXICAL TOKENIZATION PROCESS.

ISSUES CAN BE REPORTED TO VARIOUS PLATFORMS, SUCH AS GITHUB, GITLAB, BITBUCKET, ECT... ONCE REPORTED TO AN SCH, THE ID'S ASSOCIATED WITH THE ISSUE AND PLATFORM THEY WERE PUBLISHED ON ARE APPENDED AND WRITTEN TO THE ISSUE ANNOTATION. THIS ALLOWS ISSUE-SUMMONER TO CHECK THE STATUS OF ISSUES AND REMOVE THE COMMENT/ISSUE ENTIRELY, ONCE IT IS MARKED AS RESOLVED.

EXAMPLE PRIOR TO REPORTING THE ISSUE: // @MY_ISSUE_ANNOTATION resolve bug....

EXAMPLE AFTER REPORTING THE ISSUE TO AN SCH: // @MY_ISSUE_ANNOTATION(#45323) resolve bug....

SUPPORTED MODES

- `SCAN`: LOCATES ALL SRC CODE COMMENTS THAT CONTAIN AN ISSUE [Annotation] AND STORES THE RESULTS IN THE [Issues] SLICE.

- `REPORT`: PRODUCES THE SAME LIST OF ISSUES FROM `SCAN` MODE, AND CREATES A MAP THAT GROUPS ISSUES TOGETHER BY FILE PATH. THE MAP IS USED AFTER ALL SELECTED [Issues] HAVE BEEN REPORTED TO A SOURCE CODE HOSTING PLATFORM, I.E. GITHUB, GITLAB ECT..., AND WRITES THE ISSUE ID BACK TO THE SOURCE FILE. THE ISSUE ID IS OBTAINED FROM PUBLISHING AN ISSUE, SEE GIT PACKAGE FOR MORE DETAILS. THE GROUPING, FROM THE MAP, HELPS WITH EXECUTING 1 WRITE CALL PER FILEPATH. MEANING, IF THERE ARE 10 ISSUES BEING REPORTED AND THEY RESIDE IN 2 SOURCE CODE FILES, THERE WOULD ONLY BE 2 WRITE FILE CALLS BECAUSE THE ISSUES ARE GROUPED BY FILE PATH AND BATCHED TOGETHER TO AVOID MULTIPLE WRITES. @SEE [WriteIssues] FUNC.

- `PURGE`: CHECK THE STATUS OF ISSUES THAT WERE REPORTED USING ISSUE SUMMONER AND ATTEMPTS TO REMOVE THE COMMENTS. COMMENTS ARE REMOVED IF THE ISSUE WAS REPORTED USING <issue-summoner report> COMMAND AND THE ISSUE ID WAS WRITTEN BACK TO THE SOURCE FILE. THE ID IS USED TO CHECK THE STATUS AND IF RESOLVED, THE COMMENT IS REMOVED. @SEE [Purge] FUNC.

THE TEMPLATE IN THIS FILE IS USED WHEN EXECUTING THE 'REPORT' COMMAND. FOR EACH CODE ISSUE THAT IS SELECTED, THE BELOW TEMPLATE IS EXECUTED AGAINST THE GIVEN ISSUE. THE RESULT IS A FORMATTED MARKDOWN ISSUE THAT IS PUBLISHED TO THE SOURCE CODE MANAGMENET PLATFORM FLAG THAT IS PASSED INTO THE REPORT COMMAND.

Index

• type Issue
• type IssueManager
  • func NewIssueManager(annotation []byte, mode IssueMode) (*IssueManager, error)
  • func (mngr *IssueManager) Group(index, id int) error
  • func (mngr *IssueManager) Purge(pathKey string) error
  • func (mngr *IssueManager) Results(pathKey, sch string, failed bool) ([]string, error)
  • func (mngr *IssueManager) Scan(path string) error
  • func (mngr *IssueManager) Walk(root string) error
  • func (mngr *IssueManager) WriteIssues(pathKey string) error
• type IssueMapEntry
• type IssueMode

Types

type Issue

type Issue struct {
	ID          string // Used as a key for the multi select tui component for issue selection <issue summoner report> cmd
	Title       string // Title of the issue
	Description string // Description of the issue
	Body        string // Contains the issue body/description to use for the issue filing. Is a markdown template
	FileName    string // base
	FilePath    string // relative to the working tree dir
	LineNumber  int    // Line number of where the comment resides
	OS          string // Used for env section of the issue markdown template
	Index       int    // index of the issue in [IssueManager.Issues]
	Comment     *lexer.Comment
}

type IssueManager

type IssueManager struct {
	Issues     []Issue
	IssueMap   map[string][]IssueMapEntry
	Annotation []byte
	// contains filtered or unexported fields
}

func NewIssueManager

func NewIssueManager(annotation []byte, mode IssueMode) (*IssueManager, error)

NewIssueManager accepts an annotation as input, which is used to locate issues/action items that are contained within comments, and a [mode] that is used to determine the functionality/behavior of both the issue & lexer packages. @See top comment in this file for a description on the supported modes and their responsibilities.

func (*IssueManager) Group

func (mngr *IssueManager) Group(index, id int) error

Groups [Issues] together by file path so that when we are writting issue ids back to where the issue [Annotation] is located, we can do so with fewer sys calls.

func (*IssueManager) Purge

func (mngr *IssueManager) Purge(pathKey string) error

func (*IssueManager) Results

func (mngr *IssueManager) Results(pathKey, sch string, failed bool) ([]string, error)

returns the results of reporting issues to a source code hosting platform and writing the ids obtained from the source code hosting platform back to the src code files

func (*IssueManager) Scan

func (mngr *IssueManager) Scan(path string) error

func (*IssueManager) Walk

func (mngr *IssueManager) Walk(root string) error

func (*IssueManager) WriteIssues

func (mngr *IssueManager) WriteIssues(pathKey string) error

type IssueMapEntry

type IssueMapEntry struct {
	Index      int // index of the issue in [IssueManager.Issues]
	ReportedID int // issue identifier after calling [git.Report] func
}

type IssueMode

type IssueMode = string

const (
	IssueModePurge  IssueMode = "purge"
	IssueModeReport IssueMode = "report"
	IssueModeScan   IssueMode = "scan"
)