build(project): set up and configure tsoa

.eslintrc.js

@@ -1,17 +1,31 @@
 module.exports = {
   root: true,
-  parser: "@typescript-eslint/parser",
+  parser: '@typescript-eslint/parser',
   parserOptions: {
     tsconfigRootDir: __dirname,
-    project: ["./tsconfig.json"],
+    project: ['./tsconfig.json'],
   },
 
-  plugins: ["@typescript-eslint", "prettier"],
+  plugins: ['@typescript-eslint', 'prettier'],
   extends: [
-    "eslint:all",
-    "plugin:@typescript-eslint/recommended",
-    "plugin:@typescript-eslint/recommended-requiring-type-checking",
-    "prettier",
-    "prettier/@typescript-eslint",
+    'eslint:all',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:@typescript-eslint/recommended-requiring-type-checking',
+    'prettier',
+    'prettier/@typescript-eslint',
   ],
+  rules: {
+    'new-cap': ['error', { capIsNew: false }],
+    'max-lines-per-function': 'off',
+    '@typescript-eslint/require-await': 'off',
+    'class-methods-use-this': 'off',
+    'sort-keys': 'off',
+    'multiline-comment-style': 'off',
+    'max-lines': 'off',
+    'max-statements': 'off',
+    'func-style': 'off',
+    'one-var': 'off',
+    'capitalized-comments': 'off',
+    'no-undefined': 'off',
+  },
 };

.gitignore

@@ -102,3 +102,6 @@ dist
 
 # TernJS port file
 .tern-port
+
+# tsoa generated stuff
+src/api/tsoa-routes.generated.ts

.prettierignore

@@ -0,0 +1 @@
+*.generated.ts

.prettierrc

@@ -1,3 +1,4 @@
 {
+    "singleQuote": true,
     "printWidth": 100
 }

docs/swagger.yaml

@@ -0,0 +1,211 @@
+components:
+    examples: {}
+    headers: {}
+    parameters: {}
+    requestBodies: {}
+    responses: {}
+    schemas:
+        User:
+            properties:
+                name:
+                    type: string
+                    description: 'Display name'
+                id:
+                    type: string
+                    description: 'Id should be unique within the server'
+            required:
+                - name
+                - id
+            type: object
+            additionalProperties: false
+        Build:
+            properties:
+                id:
+                    type: string
+                    description: 'Id should be unique within the parent build definition.'
+                name:
+                    type: string
+                status:
+                    type: string
+                    enum:
+                        - Queued
+                        - Running
+                        - Succeeded
+                        - PartiallySucceeded
+                        - Failed
+                        - Canceled
+                    description: 'Build status'
+                startTime:
+                    type: string
+                    format: date-time
+                    description: 'Date and time when this build was started.'
+                finishTime:
+                    type: string
+                    format: date-time
+                    description: 'Should be present for completed builds, but can be absent for running builds.'
+                triggeredByUser:
+                    $ref: '#/components/schemas/User'
+                    description: 'User that requested the build. If the build started automatically after new commit, this should be the user that committed the code.'
+                contributors:
+                    items:
+                        $ref: '#/components/schemas/User'
+                    type: array
+                    description: 'When the build contains changes from multiple user, additional contributors can be placed here.'
+                webUrl:
+                    type: string
+                    description: 'Web page with build details'
+            required:
+                - id
+                - status
+                - startTime
+            type: object
+            additionalProperties: false
+        BuildBranch:
+            properties:
+                id:
+                    type: string
+                    description: "Id should be unique within the parent build definition.\n\nBranch id can be taken from source control. Examples:\n- refs/heads/features/test-feature-branch\n- refs/heads/master\n- refs/pull/2/merge\n- refs/remotes/origin/features/test-feature-branch\n\nCatLight will cleanup branch id and use it as a display name for the branch. For example, \"refs/heads/master\" will be transformed into \"master\".\n\nNote: if you don't see the branch in CatLight app UI, make sure that it has recent builds."
+                builds:
+                    items:
+                        $ref: '#/components/schemas/Build'
+                    type: array
+                    description: 'Sorted array of builds. Last build in the array should be the newest. Return 5-10 builds for each branch.'
+                webUrl:
+                    type: string
+            required:
+                - id
+                - builds
+            type: object
+            additionalProperties: false
+        BuildDefinition:
+            properties:
+                id:
+                    type: string
+                    description: 'Id should be unique in parent space.'
+                name:
+                    type: string
+                    description: 'Display name'
+                branches:
+                    items:
+                        $ref: '#/components/schemas/BuildBranch'
+                    type: array
+                    description: "Branches array should include:\n\nPrimary branches (master, develop, etc.)\nActive feature branches that had builds in the past 30 days.\n\nIf your system cannot separate builds into branches, add a single branch to this array with id = \"~all\""
+                webUrl:
+                    type: string
+                    description: 'Webpage that provides user with detailed information about this build definition.'
+                folder:
+                    type: string
+                    description: 'Path to the build definition, e.g. "my folder/sub-folder".'
+            required:
+                - id
+                - name
+                - branches
+            type: object
+            additionalProperties: false
+        Space:
+            description: "Space is a logical container of build definitions. For most servers, space will map to a project or source control repository.\n\nCatLight apps exchange information about build investigations on space level. If your server has thousands of build definitions, put them into separate spaces to avoid performance problems."
+            properties:
+                id:
+                    type: string
+                    description: 'Space id should be unique on the server.'
+                name:
+                    type: string
+                    description: 'Display name'
+                buildDefinitions:
+                    items:
+                        $ref: '#/components/schemas/BuildDefinition'
+                    type: array
+                webUrl:
+                    type: string
+                    description: 'Url of the space page.'
+            required:
+                - id
+                - name
+                - buildDefinitions
+            type: object
+            additionalProperties: false
+        Server:
+            properties:
+                protocol:
+                    type: string
+                    enum:
+                        - 'https://catlight.io/protocol/v1.0/basic'
+                        - 'https://catlight.io/protocol/v1.0/dynamic'
+                    description: 'Constant string that defines the version and mode of CatLight protocol.'
+                id:
+                    type: string
+                    description: "Globally unique server id.\n\nServer id must be globally unique and should not change.\n\n# How to choose server id?\nFor online services, you can use your domain name, e.g. \"myserver.com\"\nFor installed servers, use your domain or product name + unique installation id. For example, \"myserver.com/3A5126E7-EE74-48E4-9997-1C1DE52BA711\". If your server does not have unique id, you can generate a GUID during installation and save it to configuration file.\n\nTry to keep the id shorter than 100 symbols. If your server has a built-in unique id that is very long, you can use a hash sum of it that should be shorter."
+                name:
+                    type: string
+                    description: 'Display name of the server that is shown to the user.'
+                spaces:
+                    items:
+                        $ref: '#/components/schemas/Space'
+                    type: array
+                webUrl:
+                    type: string
+                    description: 'Url of the main server page.'
+                serverVersion:
+                    type: string
+                currentUser:
+                    $ref: '#/components/schemas/User'
+                    description: 'Currently logged-in user. If it is absent, build investigation feature will not be available.'
+            required:
+                - protocol
+                - id
+                - name
+                - spaces
+            type: object
+            additionalProperties: false
+        BasicBuildInfo:
+            $ref: '#/components/schemas/Server'
+    securitySchemes: {}
+info:
+    title: gha-build-monitor
+    version: 0.0.1
+    description: 'Adapter to give access to GitHub Actions status via the CatLight Protocol'
+    license:
+        name: MIT
+    contact:
+        name: tsimbalar
+openapi: 3.0.0
+paths:
+    /basic:
+        get:
+            operationId: GetBasicBuildInfo
+            responses:
+                '200':
+                    description: Ok
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/BasicBuildInfo'
+            security: []
+            parameters: []
+    /examples/basic/basic:
+        get:
+            operationId: GetBasicExample
+            responses:
+                '200':
+                    description: Ok
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/BasicBuildInfo'
+            security: []
+            parameters: []
+    /examples/basic/multi-space:
+        get:
+            operationId: GetBasicMultispaceExample
+            responses:
+                '200':
+                    description: Ok
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/BasicBuildInfo'
+            security: []
+            parameters: []
+servers:
+    -
+        url: /

nodemon.json

@@ -2,7 +2,10 @@
     "watch": [
         "src"
     ],
+    "exec": "ts-node ./src/index.ts",
     "ext": ".ts,.js",
-    "ignore": [],
-    "exec": "ts-node ./src/index.ts"
+    "ignore": [
+        "*.generated.ts",
+        "*.spec.ts"
+    ]
 }