Merge pull request #25 from Aeliot-Tm/inline_config

Implement inline config EXTRAS

README.md

@@ -1,112 +1,81 @@
 # TODO Registrar
 
 [![GitHub Release](https://img.shields.io/github/v/release/Aeliot-Tm/todo-registrar?label=Release&labelColor=black)](https://packagist.org/packages/aeliot/todo-registrar)
-[![GitHub License](https://img.shields.io/github/license/Aeliot-Tm/todo-registrar?label=License&labelColor=black)](LICENSE)
 [![WFS](https://github.com/Aeliot-Tm/todo-registrar/actions/workflows/automated_testing.yml/badge.svg?branch=main)](https://github.com/Aeliot-Tm/todo-registrar/actions)
 [![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/Aeliot-Tm/todo-registrar?labelColor=black&label=Issues)](https://github.com/Aeliot-Tm/todo-registrar/issues)
+[![GitHub License](https://img.shields.io/github/license/Aeliot-Tm/todo-registrar?label=License&labelColor=black)](LICENSE)
+
+It takes TODO/FIXME and other comments from your php-code and register them as issues in Issue Trackers like
+JIRA. With all necessary labels, linked issues and so on.
+
+## Motivation
+
+Time to time developers left notes in code to not forget to do something. And they forget to do it. One of the most reason is that it is difficult to manage them.
+
+Why do developers left comment in code instead of registering of isdues? It is convenient. You don't need to deal with UI of Issue Tracker and to fill lots of field. And lots of times to register each issue. It takes time. The second reason, comment in code permit to mark exact place which have to be modified. And many other reasons. No matter why they do it. They do it and leave this comments for years.
+
+Somebody have to manage it.
 
-Package responsible for registration of issues in Issue Trackers.
+So, we need in tool which will be responsible for registering of issues and save time of developers. After that you may use all power of management to plan solving of lacks of your code.
+
+This script do it for you. It registers issues with all necessary params. Then injects IDs/Keys of created issues into comment in code. This prevents creating of issues twice and injected marks helps to find proper places in code quickly.
 
 ## Installation
 
 1. Require package via Composer:
    ```shell
    composer require --dev aeliot/todo-registrar
    ```
-2. Create configuration file. It expects ".todo-registrar.php" or ".todo-registrar.dist.php" at the root of the project.
+2. Create [configuration file](docs/config.md). It expects ".todo-registrar.php" or ".todo-registrar.dist.php" at the root of the project.
 
 ## Using
 
 1. Call script:
    ```shell
    vendor/bin/todo-registrar
    ```
-   You may pass option with it `--config=/custom/path/to/config`. Otherwise, it tries to use one of default files. 
+   You may pass option with path to config `--config=/custom/path/to/config`.
+   Otherwise, it tries to use one of default paths to [config file](docs/config.md).
 2. Commit updated files. You may config your pipeline/job on CI which commits updates.
 
 ## Configuration file
 
-Config file is php-file which returns instance of class `\Aeliot\TodoRegistrar\Config`. See [example](.todo-registrar.dist.php).
+It expects that file `.todo-registrar.php` or `.todo-registrar.dist.php` added in the root directory of project.
+It may be put in any other place, but you have to define path to it with option `--config=/custom/path/to/cofig`
+while call the script. Config file is php-file which returns instance of class `\Aeliot\TodoRegistrar\Config`.
+
+[See full documentation about config](docs/config.md)
+
+## Inline Configuration
+
+Script supports inline configuration of each TODO-comment. It helps flexibly configure different aspects of created issues.
+Like relations to other issues, labels, components and so on. So, it becomes very powerful instrument. 😊
+
+[See documentation about inline config](docs/inline_config.md)
+
+## Supported todo-tags
 
-It has setters:
-1. `setFinder` - accepts instance of configured finder of php-files.
-2. `setRegistrar` - responsible for configuration of registrar factory. It accepts as type of registrar with its config
-   as instance of custom registrar factory.
-3. `setTags` - array of detected tags. It supports "todo" and "fixme" by default. 
-   You don't need to configure it when you want to use only this tags. Nevertheless, you have to set them 
-   when you want to use them together with your custom tags.
+It detects `TODO` and `FIXME` by default. But you may config your custom set of tags in config file.
+Whey will be detected case insensitively.
 
-### Supported patters of comments (examples):
+## Supported formats of comments:
 
 It detects TODO-tags in single-line comments started with both `//` and `#` symbols
 and multiple-line comments `/* ... */` and phpDoc `/** ... **/`.
 
-1. Tag and comment separated by colon
-   ```php
-   // TODO: comment summary
-   ```
-2. Tag and comment does not separated by colon
-   ```php
-   // TODO comment summary
-   ```
-3. Tag with assignee and comment separated by colon
-   ```php
-   // TODO@assigne: comment summary
-   ```
-4. Tag with assignee and comment does not separated by colon
-   ```php
-   // TODO@assigne comment summary
-   ```
-5. Multiline comment with complex description. All lines after the first one with tag MUST have indentation
-   same to the text of the first line. So, all af them will be detected af part of description of TODO.
-   Multiple line comments may have assignee and colon same as single-line comments/.
-   ```php
-   /**
-    * TODO: comment summary
-    *       and some complex description
-    *       which must have indentation same as end of one presented:
-    *       - colon
-    *       - assignee
-    *       - tag
-    *       So, all this text will be passed to registrar as description
-    *       without not meaning indentations (" *      " in this case).
-    * This line (and all after) will not be detected as part (description) of "TODO"
-    * case they don't have expected indentation.
-    */
-   ```
-
-As a result of processing of such comments, ID of ISSUE will be injected before comment summary
-and after colon and assignee when they are presented. For example:
-1. Tag and comment separated by colon
-   ```php
-   // TODO: XX-001 comment summary
-   ```
-2. Tag and comment does not separated by colon
-   ```php
-   // TODO XX-001 comment summary
-   ```
-3. Tag with assignee and comment separated by colon
-   ```php
-   // TODO@assigne: XX-001 comment summary
-   ```
-4. Tag with assignee and comment does not separated by colon
-   ```php
-   // TODO@assigne XX-001 comment summary
-   ```
-5. Multiline comment with complex description. All lines after the first one with tag MUST have indentation
-   same to the text of the first line. So, all af them will be detected af part of description of TODO.
-   Multiple line comments may have assignee and colon same as single-line comments/.
-   ```php
-   /**
-    * TODO: XX-001 comment summary
-    *       and some complex description
-    */
-   ```
+Comments can be formatted differently:
+```php
+// TODO: comment summary
+// TODO comment summary
+// TODO@assigne: comment summary
 
-### Assignee-part
+/**
+ * TODO: XX-001 comment summary
+ *       with some complex description
+ */
+```
 
-It is some "username" which separated of tag by symbol "@". It sticks to pattern `/[a-z0-9._-]+/i`.
-System pass it in payload to registrar with aim to be used as "identifier" of assignee in issue tracker.
+And others. [See all supported formats](docs/supported_patters_of_comments.md).
 
 ## Supported Issue Trackers
 
@@ -115,3 +84,4 @@ Currently, todo-registrar supports the following issue trackers:
 | Issue Tracker                                   | Description                                                                                 |
 |-------------------------------------------------|---------------------------------------------------------------------------------------------|
 | [Jira](https://www.atlassian.com/software/jira) | Supported via API tokens. See [description of configuration](docs/registrar/jira/config.md) |
+

composer.json

@@ -26,6 +26,7 @@
     },
     "require": {
         "php": "^8.2",
+        "ext-mbstring": "*",
         "ext-tokenizer": "*",
         "lesstif/php-jira-rest-client": "^5.8",
         "symfony/finder": "^5.4|^6.0|^7.0"

docker-compose.yml

@@ -4,5 +4,13 @@ services:
             context: ./
             dockerfile: .docker/php/Dockerfile
         entrypoint: [ '/app/docker-entrypoint.sh' ]
+        environment:
+            PHP_IDE_CONFIG: serverName=todo-registrar.local
+            XDEBUG_CONFIG: "client_host=host.docker.internal"
+            XDEBUG_ENABLE: 1
+        expose:
+            - '9003'
+        extra_hosts:
+            - "host.docker.internal:host-gateway"
         volumes:
             - .:/app

docs/config.md

@@ -0,0 +1,56 @@
+# Configuration file
+
+It expects that file `.todo-registrar.php` or `.todo-registrar.dist.php` added in the root directory of project.
+It may be put in any other place, but you have to define path to it when call the script with option `--config=/path/to/cofig`.
+
+Config file is php-file which returns instance of class `\Aeliot\TodoRegistrar\Config`. See [example](../.todo-registrar.dist.php).
+
+## Methods
+
+| Method                 | Is Required |
+|------------------------|-------------|
+| setFinder              | yes         |
+| setInlineConfigFactory | no          |
+| setInlineConfigReader  | no          |
+| setRegistrar           | yes         |
+| setTags                | no          |
+
+
+### setFinder
+
+Accepts instance of configured finder (`\Aeliot\TodoRegistrar\Service\File\Finder`) responsible for finding of php-files.
+Very similar to configuration of Finder for "PHP CS Fixer".
+
+### setInlineConfigFactory
+
+Accepts instance of `\Aeliot\TodoRegistrar\InlineConfigFactoryInterface`
+
+You can implement and expects instance of your custom inline config in your registrar.
+This method permits to provide factory for it.
+
+### setInlineConfigReader
+
+Accepts instance of `\Aeliot\TodoRegistrar\InlineConfigReaderInterface`. 
+
+So, you can use your own reader of inline config which support your preferred format or relay on build-in.  
+
+### setRegistrar
+
+Responsible for configuration of registrar factory. 
+
+It accepts two arguments:
+1. First one is registrar type (`\Aeliot\TodoRegistrar\Enum\RegistrarType`)
+   or instance of registrar factory (`\Aeliot\TodoRegistrar\Service\Registrar\RegistrarFactoryInterface`).
+2. Second one is array of config for registrar. See [example for JIRA](registrar/jira/config.md).
+
+So, you can use build-in registrar or pass your own.
+
+### setTags
+
+Permit to define array of tags to be detected. 
+
+Script supports `TODO` and `FIXME` by default.
+You don't need to configure it when you want to use only this tags. Nevertheless, you have to set them
+when you want to use them together with your custom tags.
+
+Don't wary about case of tags. They will be found in case-insensitive mode. 

docs/inline_config.md

@@ -0,0 +1,54 @@
+## Inline Configuration
+
+Script supports inline configuration of each TODO-comment. It helps flexibly configure different aspects of created issues.
+Like relations to other issues, labels, components and so on.
+
+Very flexible tool. A format similar to js objects or JSON, only without quotes.
+It is so-called "EXTRAS" case they started with `{EXTRAS: ...`. It should be a part of multi-line commit
+and indented a description ([see supported formats](supported_patters_of_comments.md)).
+The system expects no more than one inline config per TODO. And it would be nice to keep them as last part of TODO-commit.
+
+It may be split to multiple lines. But don't forget about indents of each line.
+
+```php
+/**
+ * [email protected]: summary of issue (title)
+ *                   And some complex description on second line and below.
+ *                   Fell you free to add any complex description as you wish.
+ *                        But don't forget to start each line on same column as summary (title) or later.
+ *                   And suit same rule for EXTRAS, which can be split to multiple lines with any spaces. 
+ *                   See below.
+ *                   {EXTRAS: {
+ *                      someKey: [value1, value2],
+ *                      moreComplexData: {key1: [v3], key2: {
+ *                            neverMindHowManyLevels: [v4]
+ *                      }}
+ *                   }}        
+ */
+```
+
+### Example
+
+Below are examples of settings supported by the implemented JIRA-registrar.
+
+1. Do you need to provide a related ticket? Easily.
+   ```
+   {EXTRAS: {linkedIssues: XX-123}}
+   ```
+2. Do you need to link multiple tickets? So:
+   ```
+   {EXTRAS: {linkedIssues: [XX-123, XX-234]}}
+   ```
+3. Do you need to link tickets with different link types? Easily.
+   ```
+   {EXTRAS: {linkedIssues: {child_of: XX-123, is_blocked_by: [XX-234, YY-567]}}}
+   ```
+4. Labels and components can be provided in the same way.
+   ```
+   {EXTRAS: {labels: [label-a, label-b], components: [component-a, component-b]}}
+   ```
+
+## The order of applying of configs
+1. `@assignee` joined to TODO-tag.
+2. `EXTRAS`
+3. Then the [general config](config.md) of the JIRA registrar.

docs/supported_patters_of_comments.md

@@ -0,0 +1,78 @@
+# Supported formats and patterns of comments
+
+It detects TODO-tags in single-line comments started with both `//` and `#` symbols
+and multiple-line comments `/* ... */` and phpDoc `/** ... **/`.
+
+1. Tag and comment separated by colon
+   ```php
+   // TODO: comment summary
+   ```
+2. Tag and comment does not separated by colon
+   ```php
+   // TODO comment summary
+   ```
+3. Tag with assignee and comment separated by colon
+   ```php
+   // TODO@assigne: comment summary
+   ```
+4. Tag with assignee and comment does not separated by colon
+   ```php
+   // TODO@assigne comment summary
+   ```
+5. Multiline comment with complex description. All lines after the first one with tag MUST have indentation
+   same to the text of the first line. So, all af them will be detected af part of description of TODO.
+   Multiple line comments may have assignee and colon same as single-line comments/.
+   ```php
+   /**
+    * TODO: comment summary
+    *       and some complex description
+    *       which must have indentation same as end of one presented:
+    *       - colon
+    *       - assignee
+    *       - tag
+    *       So, all this text will be passed to registrar as description
+    *       without not meaning indentations (" *      " in this case).
+    * This line (and all after) will not be detected as part (description) of "TODO"
+    * case they don't have expected indentation.
+    */
+   ```
+
+As a result of processing of such comments, ID of ISSUE will be injected before comment summary
+and after colon and assignee when they are presented. For example:
+1. Tag and comment separated by colon
+   ```php
+   // TODO: XX-001 comment summary
+   ```
+2. Tag and comment does not separated by colon
+   ```php
+   // TODO XX-001 comment summary
+   ```
+3. Tag with assignee and comment separated by colon
+   ```php
+   // TODO@assigne: XX-001 comment summary
+   ```
+4. Tag with assignee and comment does not separated by colon
+   ```php
+   // TODO@assigne XX-001 comment summary
+   ```
+5. Multiline comment with complex description. All lines after the first one with tag MUST have indentation
+   same to the text of the first line. So, all af them will be detected af part of description of TODO.
+   Multiple line comments may have assignee and colon same as single-line comments/.
+   ```php
+   /**
+    * TODO: XX-001 comment summary
+    *       and some complex description
+    */
+   ```
+
+### Assignee-part
+
+It is some "username" which separated of tag by symbol "@". It sticks to pattern `/[a-z0-9._-]+/i`.
+System pass it in payload to registrar with aim to be used as "identifier" of assignee in issue tracker.
+
+## Compatibility
+
+Script implemented to support formats of "comments with expiration" provided by [staabm/phpstan-todo-by](https://github.com/staabm/phpstan-todo-by).
+On my point of view, it is cool feature which I'd like to use in my projects.
+
+So, script ignores comments which already have mark of "expiration".