Merge pull request #151 from Start-Out/dev/feature/cli-enhancements

CLI Enhancements

.github/workflows/todoon-issues.yml

@@ -2,6 +2,16 @@ name: Generate issues with TODO-or-not
 
 on:
   workflow_dispatch:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - reopened
+    branches:
+      - dev/staging
+  push:
+    branches:
+      - dev/staging
 jobs:
   run_todoon:
     runs-on: ubuntu-latest
@@ -27,4 +37,4 @@ jobs:
           GH_TOKEN: ${{ steps.generate-token.outputs.token }}
         run: |
           echo "Generate GitHub issues for each problem found, but don't fail the workflow"
-          todoon --mode issue --silent
+          todoon --mode waitforstableissue --silent

.todo-ignore

@@ -1,14 +1,17 @@
+
 .git/
 .github/
 .idea/
 .pytest_cache/
+.venv/
 tests/
 scripts/
 
 dist/
 node_modules/
 
 .gitignore
+example.todo-ignore
 
 package-lock.json
 package.json
@@ -23,4 +26,3 @@ LICENSE
 todo_or_not/__pycache__/
 todo_or_not/__init__.py/
 todo_or_not/localize.py
-todo_or_not/todo_check.py

README.md

@@ -9,7 +9,7 @@
 
 > TODO or not to do, that is the question
 
-TODO Or Not (#todoon) is, in essence, a simple tool that checks your project for TODO's and FIXME's. You can also integrate this tool into your GitHub workflow via actions, and automate generating issues from the discovered TODO's and FIXME's.
+TODO Or Not (todoon) is, in essence, a simple tool that checks your project for TODO's and FIXME's. You can also integrate this tool into your GitHub workflow via actions, and automate generating issues from the discovered TODO's and FIXME's.
 
 [Get the GitHub App](https://github.com/apps/todo-or-not)
 
@@ -26,6 +26,11 @@ pip install todo-or-not
 - [Examples](#examples)
 - [Usage](#usage)
    * [CLI](#cli)
+      + [Usage](#usage-1)
+         - [Arguments](#arguments)
+         - [Options](#options)
+         - [Feedback](#feedback)
+   * [Examples](#examples-1)
    * [Environment Variables](#environment-variables)
    * [.todo-ignore](#todo-ignore)
    * [Issues](#issues)
@@ -40,7 +45,7 @@ Check out [this example code](https://github.com/Start-Out/todo-or-not/blob/main
 
 ```py
 ##########################
-# Example usage of #todoon
+# Example usage of todoon
 ##########################
 
 def an_unfinished_function():
@@ -69,8 +74,8 @@ def a_broken_function():
 
 
 def a_skipping_example():
-    # Since the line below has #todoon in it, the checker will give it a pass even though it has the magic words!
-    print("Sometimes you really have to write TODO or FIXME, like this!")  # #todoon
+    # Since the line below has `# todoon` in it, the checker will give it a pass even though it has the magic words!
+    print("Sometimes you really have to write TODO or FIXME, like this!")  # todoon
 
 
 def a_very_pretty_example():
@@ -82,22 +87,35 @@ def a_very_pretty_example():
 
 ### CLI
 
+#### Usage
+
 [[Generated by Typer, thanks Typer!](https://github.com/tiangolo/typer)]
 
 ```
-Usage: todo_check.py [OPTIONS]                                              
-                                                                            
-Options:                                                                    
-  --mode TEXT             [default: print]                                  
-  --silent / --no-silent  [default: no-silent]                              
-  --force / --no-force    [default: no-force]                               
-  --ni TEXT               Copy the contents of other files into a new .todo-
-                          ignore                                            
-  --xi TEXT               Copy the contents of other files into an existing 
-                          .todo-ignore                                      
-  --help                  Show this message and exit.       
+Usage: todoon [OPTIONS] [FILES]...
+
+Arguments:
+  [FILES]...
+
+Options:
+  --mode TEXT               [default: print]
+  --silent / --no-silent    [default: no-silent]
+  --force / --no-force      [default: no-force]
+  --verbose / --no-verbose  [default: no-verbose]
+  --ni TEXT                 Copy the contents of another file into a new .todo-
+                            ignore
+  --xi TEXT                 Copy the contents of another file into an existing
+                            .todo-ignore
+  --help                    Show this message and exit.  
 ```
 
+##### Arguments
+
+[FILES]
+: This optional argument allows you to specify which files todoon should scan. When left blank, todoon will scan every file in the working directory that is not filtered out by the .todo-ignore
+
+##### Options
+
 --mode PRINT
 : The default configuration, will print the discovered issues to stderr
 
@@ -110,6 +128,9 @@ Options:
 --force
 : Run todo_check without a .todo-ignore. NOT RECOMMENDED! There could be a lot of files in there.
 
+--verbose
+: Print everything while running todoon, this will print each encoding error and which file it concerns.
+
 --ni FILENAME
 : Copy the contents of other files into a **N**EW [.todo-ignore](#todo-ignore), this option must be specified for each. e.g. `--ni .gitignore --ni .prettierignore`
 
@@ -119,6 +140,46 @@ Options:
 If a file discovered by `todoon` is not of a supported encoding [see [SUPPORTED_ENCODINGS_TODO_CHECK](todo_or_not/localize.py) for most up-to-date list] it will be skipped.
 The number of skipped files is summarized at the end of the run.
 
+##### Feedback
+
+todoon will summarize the run in stderr when it completes, it will also update a number of environment variables during and after the run:
+
+- `$TODOON_STATUS`
+  - `starting`
+  - `parsing-todo-ignore` (if applicable)
+  - `collecting-targets` (if no targets specified)
+  - `collecting-issues` (if mode is "issue")
+  - `scanning-files`
+- `$TODOON_PROGRESS`
+  - starting at status `scanning-files`, this variable is updated to a percentage (e.g. '18.7') which reflects the number of targets scanned of all targets found
+- `$TODOON_FILES_SCANNED`
+- `$TODOON_TODOS_FOUND`
+- `$TODOON_FIXMES_FOUND`
+- `$TODOON_ENCODING_ERRORS`
+- `$TODOON_ISSUES_GENERATED`
+- `$TODOON_DUPLICATE_ISSUES_AVOIDED`
+
+### Examples
+
+> Find ALL issues in the current working directory (including any hidden folders/files) and exit non-zero if any are found
+> 
+> ```bash
+> todoon --force
+> ```
+
+> Show the issues the files "a.txt", "b.txt", and all the files that are under the directory "c/" without failing
+> 
+> ```bash
+> todoon --silent a.txt b.txt c/
+> ```
+
+> Generate all the issues found in the project that haven't already been generated (assumes [issues environment](#issues) is set up correctly and a .todo-ignore is in place)
+> 
+> ```bash
+> gh auth login 
+> todoon --silent --mode issue 
+> ```
+
 ### Environment Variables
 
 MAXIMUM_ISSUES_GENERATED
@@ -155,7 +216,7 @@ Issue generation is best supported from GitHub actions, the YAML included in thi
 
 ### Localization
 
-Try out your #todoon in your language! In the environment that you're running `todoon` in, set the environment variable "REGION" to your ISO code (see below). For example, on Windows (PowerShell): `$env:REGION="ko_kr"`
+Try out your todoon in your language! In the environment that you're running `todoon` in, set the environment variable "REGION" to your ISO code (see below). For example, on Windows (PowerShell): `$env:REGION="ko_kr"`
 
 Currently supported: