update readme and .gitignore to exclude ide config

Author: T0MASD

.gitignore

@@ -102,3 +102,6 @@ dist
 
 # TernJS port file
 .tern-port
+
+# ide config
+.vscode

README.md

@@ -1,13 +1,26 @@
 # ukko
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
- ### apply gmail labels using google script
+**manage your gmail using google apps script**
 
-[Ukko](https://en.wikipedia.org/wiki/Ukko) is a code name for a [google script](https://developers.google.com/apps-script) tool accessing gmail inbox threads, looping over them and assigning labels based on the email metadata. It's intended be setup via google drive and have time driven trigger.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) ![node workflow](https://github.com/T0MASD/ukko/actions/workflows/node.js.yml/badge.svg)
+
+
+- [ukko](#ukko)
+- [Using on google drive](#using-on-google-drive)
+- [Setting up scheduled execution](#setting-up-scheduled-execution)
+- [Developing and testing locally](#developing-and-testing-locally)
+  - [Install javascript dependencies](#install-javascript-dependencies)
+  - [Run tests](#run-tests)
+  - [Run lint](#run-lint)
+  - [Run Ukko](#run-ukko)
+  - [Extending label rules](#extending-label-rules)
+  - [Contributions](#contributions)
+
+[Ukko](https://en.wikipedia.org/wiki/Ukko) is a code name for a [google apps script](https://developers.google.com/apps-script) runs on google servers. It can get emails in your inbox or use search, looping over email threads and assigning labels based on the email metadata. It's intended be setup via google drive and have time driven trigger.
 
 # Using on google drive
 1. Access your [google drive](https://en.wikipedia.org/wiki/Ukko), click **New** and select ["Google Apps Script"](https://script.google.com/create).
-2. Name the project "Ukko" and paste the contents of ukko.js, exclude `import` and `export` statements those are used for testing Ukko locally.
+2. Name the project "Ukko" and paste the contents of [modules/ukko.js](https://github.com/T0MASD/ukko/blob/main/modules/ukko.js) , exclude `import` and `export` statements those are used for testing Ukko locally.
 3. Click "Run" icon at the top of the editor, you will be prompted to grant access to your gmail.
 4. If there are any messages in your inbox that have header "List-Id" it will create and assign labels.
 
@@ -21,12 +34,12 @@
   - "lists/my-list/company" 
 - Labelled threads are shown at all nesting levels.
 
-**NOTE**: To automatically "archive" the thread after labels are applied, uncomment following line in ukko.js:
-```
+**NOTE**: To automatically "archive" the thread after labels are applied, uncomment following line in [modules/ukko.js](https://github.com/T0MASD/ukko/blob/main/modules/ukko.js) :
+```javascript
 if (labels.length) { inboxThread.moveToArchive() }
 ```
-Expect similar output:
-```
+Expect similar output when executing the script in google apps script "execution log":
+```shell
 from:[email protected] labels:lists/planet-list
 from:[email protected] labels:lists/announce-list
 from:nothandled@domain labels:
@@ -38,11 +51,11 @@ from:nothandled@domain labels:
 3. Make sure "runUkko" is selected along with "Interval" at which Ukko runs.
 4. Click save and enjoy!
 
-# Testing locally
-To try locally you will need [nodejs](https://nodejs.org/en/) and [npm](https://www.npmjs.com/) installed on your machine.
-## Install dependencies
-Pull dependencies (see package.json) locally to `node_modules` dir (feel free to delete it and run `npm install` any time):
-```
+# Developing and testing locally
+To try [ukko](https://github.com/T0MASD/ukko) locally you will need [nodejs](https://nodejs.org/en/) and [npm](https://www.npmjs.com/) installed on your machine.
+## Install javascript dependencies
+To pull javascirpt dependencies (see package.json) locally run `npm install`:
+```shell
 [tomas@dev ukko]$ npm install
 npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected] (node_modules/fsevents):
 npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for [email protected]: wanted {"os":"darwin","arch":"any"} (current: {"os":"linux","arch":"x64"})
@@ -57,73 +70,90 @@ found 0 vulnerabilities
 
 ## Run tests
 Mocha is used for testing, if you have installed [mocha](https://www.npmjs.com/package/mocha) globally  you can call it directly with `mocha`, *OR* via `npm test`:
-```
-[tomas@dev ukko]$ npm test
+```shell
+[tomas@dev ukko]$ npm run test
 
-> [email protected] test /home/tomas/ukko
+> [email protected] test /ukko
 > mocha
 
+from:[email protected] labels:lists/announce-list/example
+from:[email protected] labels:lists/planet-list/example
 
 
-  email filter tests
-    get labels tests
-      ✓ should return list of labels for header named List-Id
-      ✓ should return list of labels for emails from @github.com
-    run filter tests
-from:[email protected] labels:lists/planet-list
-from:[email protected] labels:lists/announce-list
-      ✓ output list of processed emails with labels applied
+email filter tests
+ get regex tests
+   ✓ should return domain
+   ✓ should return username
+   ✓ should return jira project
+   ✓ should return email
+   ✓ should return list id
+ get labels tests
+   ✓ should return list of labels for header named List-Id
+   ✓ should return list of labels for emails from @github.com
+   ✓ should return list of labels for emails from [email protected]
+   ✓ should return list of labels for emails from team
+   ✓ should return list of labels for emails from [email protected]
+   ✓ should return list of labels for emails for jira
+   ✓ should return list of labels for emails for jira project
+ should return list of assigned labels
+   ✓ output list of processed emails with labels applied
+ run filter tests
+from:[email protected] labels:lists/announce-list/example
+from:[email protected] labels:lists/planet-list/example
+   ✓ output list of processed emails with labels applied
 
 
-  3 passing (17ms)
+14 passing (20ms)
 ```
 
 ## Run lint
 Eslint is used for linting all js code, if you have installed [eslint](https://eslint.org/) globally you can call it directly with `eslint .` *OR* via `npm lint`:
-```
+```shell
 [tomas@dev ukko]$ npm run lint
 
-> [email protected] lint /home/tomas/ukko
+> [email protected] lint /ukko
 > eslint .
 ```
 
 ## Run Ukko
 To Ukko locally with mock data call `node .` or `npm start`
-```
+```shell
 [tomas@dev ukko]$ npm start
 
-> [email protected] start /home/tomas/ukko
+> [email protected] start /ukko
 > node .
 
 from:[email protected] labels:lists/planet-list
 from:[email protected] labels:lists/announce-list
 ```
 
 ## Extending label rules
-Modify `getLabels` function of `modules/ukko.js` to add your own logic for setting up labels.
+Modify `getLabels` function of [modules/ukko.js](https://github.com/T0MASD/ukko/blob/main/modules/ukko.js) to add your own logic for setting up labels. Few example rules are included with ukko, feel free to change to suit your needs.
 
 Create "catch all" filters for given domain:
-```
+```javascript
 // process @github.com
-if (message.getFrom().includes('@github.com')) {
+if (messageFrom.includes('@github.com')) {
  labels.push('github')
 }
 ```
 Here's an sample to extract GitLab project name from header named `X-GitLab-Project` and assign label `gitlab/projectname`:
-```
+```javascript
 // process gitlab notifications
 if (message.getHeader('X-GitLab-Project')) {
- const listLabel = 'gitlab/' + message.getHeader('X-GitLab-Project')
- labels.push(listLabel)
+ labels.push(`gitlab/${message.getHeader('X-GitLab-Project')}`)
 }
 ```
-Here's a sample to assign label from the value of `List-Id` header:
-```
+Here's a sample to assign label from the value of `List-Id` header, in this example extra label is added where sender domain doesn't match `mydomain`:
+```javascript
 // process mailing lists
 if (message.getHeader('List-Id')) {
  // extract my-list from 'My List <my-list.example.com>'
- const listIDshort = message.getHeader('List-Id').match(/<([^.]+).+>/).pop()
- const listLabel = 'lists/' + listIDshort
+ const listIDshort = getReMatch('listid', message.getHeader('List-Id'))
+ let listLabel = 'lists/' + listIDshort
+ if (messageFromDomain !== 'mydomain') {
+   listLabel += `/${messageFromDomain}`
+ }
  labels.push(listLabel)
 }
 ```

test/ukko.test.js

@@ -14,9 +14,9 @@ describe('email filter tests', () => {
       expect(result).to.eql(expectResult)
     })
     it('should return username', () => {
-      const from = 'Github <noreply@github.com>'
+      const from = 'First Last <flast@example.com>'
       const result = getReMatch('username', from)
-      const expectResult = 'noreply'
+      const expectResult = 'flast'
       expect(result).to.eql(expectResult)
     })
     it('should return jira project', () => {
@@ -57,9 +57,9 @@ describe('email filter tests', () => {
       const expectResult = ['github']
       expect(result).to.eql(expectResult)
     })
-    it('should return list of labels for emails from errata@redhat.com', () => {
+    it('should return list of labels for emails from errata@security.com', () => {
       const headers = {
-        From: 'Red Hat Errata Notifications <errata@redhat.com>'
+        From: 'Errata <errata@security.com>'
       }
       const message = new GmailMessage(headers)
       const result = getLabels(message)
@@ -68,17 +68,17 @@ describe('email filter tests', () => {
     })
     it('should return list of labels for emails from team', () => {
       const headers = {
-        From: 'First Last <flast@redhat.com>'
+        From: 'First Last <flast@example.com>'
       }
       const message = new GmailMessage(headers)
       const result = getLabels(message)
       const expectResult = ['team/flast']
       expect(result).to.eql(expectResult)
     })
-    it('should return list of labels for emails from some@434324325214.amazon.com', () => {
+    it('should return list of labels for emails from some@subdomain.domain.com', () => {
       const headers = {
         From: '[email protected]',
-        'List-Id': '<some.subdomain.amazon.com>'
+        'List-Id': '<some.subdomain.domain.com>'
       }
       const message = new GmailMessage(headers)
       const result = getLabels(message)
@@ -87,8 +87,7 @@ describe('email filter tests', () => {
     })
     it('should return list of labels for emails for jira', () => {
       const headers = {
-        From: '[email protected]',
-        Subject: '[Red Hat JIRA] Subscription: Filter for KC-STI'
+        From: '[email protected]'
       }
       const message = new GmailMessage(headers)
       const result = getLabels(message)
@@ -97,8 +96,8 @@ describe('email filter tests', () => {
     })
     it('should return list of labels for emails for jira project', () => {
       const headers = {
-        From: 'issues@jboss.org',
-        Subject: '[Red Hat JIRA] (proj-123)'
+        From: 'issues@example.come',
+        Subject: '[JIRA] (proj-123)'
       }
       const message = new GmailMessage(headers)
       const result = getLabels(message)