Merge branch 'master' into moore-techradar

CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to cortex-plugins
+
+Thank you for your interest in contributing to cortex-plugins! We welcome contributions from the community.
+
+## Adding a plugin
+
+To add a new plugin, please follow these steps:
+
+1. For the easiest setup, create a new Scaffolder template similar to the built-in for creating a Cortex plugin, but with a few different configurations to allow targeting a subdirectory of this repo. The template should be:
+
+- Pointed at the repo https://github.com/cortexapps/cookiecutter-cortex-plugin
+- "Requires a new service" should be enabled
+- "Requires a new pull request" should be enabled
+- (Optional) Add the tag "plugin" to ensure it can easily be found in the Scaffolder UI
+
+2. Use this Scaffolder template to create a new plugin inside the `plugins` directory. Point it at this repo with the subdirectory `plugins/{plugin-name}` (replace "{plugin-name}" with the name of your plugin).
+3. Update the `tsconfig.json` file `typeRoots` property to include types at the root of the repo, i.e.
+   ```js
+   "typeRoots": ["../../node_modules/@types", "./node_modules/@types"],
+   ```
+4. Update the jest.config.js module name mappings for @cortexapps/plugin-core to point at the root of the repo, i.e.
+   ```js
+   "@cortexapps/plugin-core/components":
+    "<rootDir>/../../node_modules/@cortexapps/plugin-core/dist/components.cjs.js",
+   "@cortexapps/plugin-core":
+    "<rootDir>/../../node_modules/@cortexapps/plugin-core/dist/index.cjs.js",
+   ```
+5. Mark the PR as a draft until you're ready for a review
+6. Code away at your plugin!
+7. Ensure that the README.md for your plugin specifies any proxy setup expected for it to function properly.
+8. When your plugin is ready for review, remove the draft status from the PR -- the Cortex team will automatically be notified to review.
+
+## Updating a plugin
+
+To update an existing plugin, please follow these steps:
+
+1. Fork the repository and create a new branch for your changes.
+1. Make your changes to the plugin.
+1. Write tests for your changes.
+1. Ensure that all tests pass.
+1. Ensure that setup instructions are updated, if necessary. In particular, please note any changes in the proxy setup required for the plugin to function properly.
+1. Submit a pull request with your changes -- the Cortex team will automatically be notified to review.
+
+## Reporting issues
+
+If you encounter any issues with cortex-plugins, please report them on the [issue tracker](https://github.com/cortexapps/plugin-core/issues).
+
+Thank you for your contributions!
+
+## FAQ
+
+### What are expectations around testing?
+
+All _major_ conditions should be tested using the existing testing tools ([Jest](https://jestjs.io/) + [testing-library](https://testing-library.com/docs/react-testing-library/intro/)). For instance, if your plugin pulls in data about an entity from a third party, at minimum the following test cases should be covered:
+
+- There is no valid mapping between the entity in Cortex and the entity in the third party system
+- There is a valid mapping between the entity in Cortex and the entity in the third party system, but the third party system does not have data for the entity
+- There is a valid mapping between the entity in Cortex and the entity in the third party system and there is data for the entity in the third party system
+
+### What does the `build` command do?
+
+The `build` command uses [webpack](https://webpack.js.org/) to compile your plugin into a single html file (in `dist/ui.html`) that can be uploaded to Cortex for use.

README.md

@@ -1,18 +1,13 @@
 # cortex-plugins
 
-This is a monorepo housing Cortex-maintained plugins for Cortex.
+This is a monorepo housing Cortex-maintained plugins for Cortex. All available plugins live inside of the `plugins` directory, plus an example [Scaffolded](https://www.cortex.io/products/scaffolder) plugin. Each plugin is a separate package that can be built and deployed independently.
 
-### Adding a plugin
+## Using a plugin
 
-1. Use Scaffolder to create a new plugin inside the `plugins` directory. **IMPORTANT**: use the "Plugin in cortex-plugins" template on tenant `cortex` in prod and point it at this repo with the subdirectory `plugins/{plugin-name}` (replace "{plugin-name}" with the name of your plugin).
-2. Update the `tsconfig.json` file `typeRoots` property to include types at the root of the repo, 1.e.
-   ```js
-   "typeRoots": ["../../node_modules/@types", "./node_modules/@types"],
-   ```
-3. Update the `jest.config.js` module name mappings for `@cortexapps/plugin-core` to point at the root of the repo, i.e.
-   ```js
-   "@cortexapps/plugin-core/components":
-      "<rootDir>/../../node_modules/@cortexapps/plugin-core/dist/components.cjs.js",
-   "@cortexapps/plugin-core":
-      "<rootDir>/../../node_modules/@cortexapps/plugin-core/dist/index.cjs.js",
-   ```
+To use one or multiple of these plugins, we recommend first forking this repository. Then, in the desired plugin subdirectory, run `yarn build` to generate the plugin code that will be executed by Cortex. Finally, in Cortex, register a new plugin and upload the generated `dist/ui.html` file to serve as the plugin code.
+
+Be sure to follow any additional setup instructions in the plugin's README.md file, particularly for proxy configuration setup.
+
+## Adding or updating a plugin
+
+For information on adding or updating a plugin, see [CONTRIBUTING.md](./CONTRIBUTING.md).

plugins/gitlab-issues/.eslintignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

plugins/gitlab-issues/.eslintrc.js

@@ -0,0 +1,30 @@
+module.exports = {
+  env: {
+    browser: true,
+    es2021: true,
+  },
+  extends: [
+    "plugin:react/jsx-runtime",
+    "plugin:react-hooks/recommended",
+    "standard-with-typescript",
+    "prettier",
+  ],
+  overrides: [],
+  parserOptions: {
+    ecmaVersion: "latest",
+    project: "tsconfig.json",
+    sourceType: "module",
+    tsconfigRootDir: __dirname,
+  },
+  plugins: ["react"],
+  rules: {
+    // conflicts with no-extra-boolean-cast
+    "@typescript-eslint/strict-boolean-expressions": "off",
+    "no-console": ["error", { allow: ["warn", "error"] }],
+  },
+  settings: {
+    react: {
+      version: "detect",
+    },
+  },
+};

plugins/gitlab-issues/.gitignore

@@ -0,0 +1,12 @@
+# OSX
+*.DS_Store
+
+# IDEs
+.idea
+*.iml
+.vscode
+
+# This project
+node_modules/
+dist/
+yarn-error.log

plugins/gitlab-issues/.prettierignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

plugins/gitlab-issues/README.md

@@ -0,0 +1,67 @@
+# GitLab Issues Cortex Plugin
+
+View GitLab issues associated with your services!
+
+<div align="center"><img src="img/gl-issues-cortex.png" width="650" /></div>
+
+The GitLab Issues plugin shows open GitLab issues associated with the GitLab repository specified in the entity's `cortex.yaml`. If the `cortex.yaml` has a `basepath` defined in its `x-cortex-git` configuration, it will query for issues filtering by a label that matches the tag of the entity.
+
+## Setup
+
+This plugin requires a proxy to GitLab. The API that the plugin uses is documented [here](https://docs.gitlab.com/ee/api/issues.html), which details the type of headers you need defined.
+
+- Define a secret that contains your GitLab Access Token. To determine which type of token to use, check the [docs](https://docs.gitlab.com/ee/api/rest/index.html#authentication).
+- Define a proxy that is pointed to your GitLab instance with the headers mentioned in the docs. Here is a screenshot of what your proxy may look like:
+<div align="center"><img src="img/gl-proxy.png" width="600" /></div>
+
+- Register the plugin.
+  - This plugin will not work on the Global context.
+  - Select an entity context (and, optionally, filter) that will have the GitLab repo in its `cortex.yaml`
+
+## Connecting to a self-hosted instance
+
+This plugin will connect to GitLab's cloud instance out of the box. If you are self-hosting GitLab and need to direct the plugin to a different API endpoint, update the following section of the [Issues.tsx](src/components/Issues.tsx) file:
+
+```ts
+// Set your GitLab url. Cloud is https://gitlab.com
+const glURL = `https://gitlab.com/`;
+```
+
+## Troubleshooting
+
+### Getting a message that "This service does not have a GitLab Repo defined"
+
+If you get the following message:
+
+<div align="center"><img src="img/gl-no-repo-defined.png" width="640" /></div>
+
+This means that the plugin did not find a GitLab repository defined as described [here](https://docs.cortex.io/docs/reference/integrations/gitlab#catalog-descriptor).
+
+# Developing this plugin
+
+GitLab Issues Plugin is a [Cortex](https://www.cortex.io/) plugin. To see how to run the plugin inside of Cortex, see [our docs](https://docs.cortex.io/docs/plugins).
+
+### Prerequisites
+
+Developing and building this plugin requires either [yarn](https://classic.yarnpkg.com/lang/en/docs/install/) or [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
+
+## Getting started
+
+1. Run `yarn` or `npm install` to download all dependencies
+2. Run `yarn build` or `npm run build` to compile the plugin code into `./dist/ui.html`
+3. Upload `ui.html` into Cortex on a create or edit plugin page
+4. Add or update the code and repeat steps 2-3 as necessary
+
+### Notable scripts
+
+The following commands come pre-configured in this repository. You can see all available commands in the `scripts` section of [package.json](./package.json). They can be run with npm via `npm run {script_name}` or with yarn via `yarn {script_name}`, depending on your package manager preference. For instance, the `build` command can be run with `npm run build` or `yarn build`.
+
+- `build` - compiles the plugin. The compiled code root is `./src/index.tsx` (or as defined by [webpack.config.js](webpack.config.js)) and the output is generated into `dist/ui.html`.
+- `test` - runs all tests defined in the repository using [jest](https://jestjs.io/)
+- `lint` - runs lint and format checking on the repository using [prettier](https://prettier.io/) and [eslint](https://eslint.org/)
+- `lintfix` - runs eslint in fix mode to fix any linting errors that can be fixed automatically
+- `formatfix` - runs Prettier in fix mode to fix any formatting errors that can be fixed automatically
+
+### Available React components
+
+See available UI components via our [Storybook](https://cortexapps.github.io/plugin-core/).

plugins/gitlab-issues/__mocks__/fileMock.js

@@ -0,0 +1 @@
+module.exports = "test-file-stub";

plugins/gitlab-issues/__mocks__/styleMock.js

@@ -0,0 +1 @@
+module.exports = {};

plugins/gitlab-issues/babel.config.js

@@ -0,0 +1,8 @@
+module.exports = {
+  plugins: ["@babel/plugin-syntax-jsx"],
+  presets: [
+    ["@babel/preset-env", { targets: { node: "current" } }],
+    "@babel/preset-typescript",
+    ["@babel/preset-react", { runtime: "automatic" }],
+  ],
+};

plugins/gitlab-issues/jest.config.js

@@ -0,0 +1,18 @@
+module.exports = {
+  moduleNameMapper: {
+    // map static asset imports to a stub file under the assumption they are not important to our tests
+    "\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$":
+      "<rootDir>/__mocks__/fileMock.js",
+    // map style asset imports to a stub file under the assumption they are not important to our tests
+    "\\.(css|less)$": "<rootDir>/__mocks__/styleMock.js",
+    "@cortexapps/plugin-core/components":
+      "<rootDir>/../../node_modules/@cortexapps/plugin-core/dist/components.cjs.js",
+    "@cortexapps/plugin-core":
+      "<rootDir>/../../node_modules/@cortexapps/plugin-core/dist/index.cjs.js",
+  },
+  setupFilesAfterEnv: ["<rootDir>/setupTests.ts"],
+  testEnvironment: "jsdom",
+  transform: {
+    "^.+\\.tsx?$": "babel-jest",
+  },
+};

plugins/gitlab-issues/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "GitLabIssuesPlugin",
+  "version": "0.1.0",
+  "license": "MIT",
+  "dependencies": {
+    "@cortexapps/plugin-core": "^2.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.21.3",
+    "@babel/plugin-syntax-jsx": "^7.18.6",
+    "@babel/preset-env": "^7.20.2",
+    "@babel/preset-react": "^7.18.6",
+    "@babel/preset-typescript": "^7.21.0",
+    "@popperjs/core": "^2.11.8",
+    "@testing-library/jest-dom": "^5.16.5",
+    "@testing-library/react": "^14.0.0",
+    "@types/react": "^18.0.28",
+    "@types/react-dom": "^18.0.11",
+    "@typescript-eslint/eslint-plugin": "^5.0.0",
+    "@typescript-eslint/parser": "^5.55.0",
+    "babel-jest": "^29.5.0",
+    "css-loader": "^6.7.3",
+    "eslint": "^8.0.1",
+    "eslint-config-prettier": "^8.7.0",
+    "eslint-config-standard-with-typescript": "^34.0.0",
+    "eslint-plugin-import": "^2.25.2",
+    "eslint-plugin-n": "^15.6.1",
+    "eslint-plugin-promise": "^6.0.0",
+    "eslint-plugin-react": "^7.32.2",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "html-webpack-plugin": "^5.5.0",
+    "jest": "^29.5.0",
+    "jest-environment-jsdom": "^29.5.0",
+    "jest-fetch-mock": "^3.0.3",
+    "npm-run-all": "^4.1.5",
+    "prettier": "^2.8.4",
+    "prop-types": "^15.8.1",
+    "react-dev-utils": "^12.0.1",
+    "style-loader": "^3.3.1",
+    "terser-webpack-plugin": "^5.3.7",
+    "ts-loader": "^9.4.2",
+    "typescript": "^4.9.5",
+    "url-loader": "^4.1.1",
+    "webpack": "^5.76.1",
+    "webpack-cli": "^5.0.1",
+    "webpack-dev-server": "^4.15.0"
+  },
+  "scripts": {
+    "build": "webpack --mode=production",
+    "clean": "rm -r ./dist",
+    "dev": "webpack serve --mode=development",
+    "fix": "run-p formatfix lintfix",
+    "formatfix": "yarn prettier . --write",
+    "formatcheck": "yarn prettier . --check",
+    "lint": "run-p formatcheck lintcheck",
+    "lintcheck": "yarn eslint src",
+    "lintfix": "yarn lintcheck --fix",
+    "test": "jest"
+  }
+}

plugins/gitlab-issues/setupTests.ts

@@ -0,0 +1,60 @@
+import "@testing-library/jest-dom/extend-expect";
+import fetchMock from "jest-fetch-mock";
+
+fetchMock.enableMocks();
+
+const mockContext = {
+  apiBaseUrl: "https://api.getcortexapp.com",
+  entity: {
+    definition: null,
+    description: null,
+    groups: null,
+    name: "Inventory planner",
+    ownership: {
+      emails: [
+        {
+          description: null,
+          email: "[email protected]",
+          inheritance: null,
+          id: 1,
+        },
+      ],
+    },
+    tag: "inventory-planner",
+    type: "service",
+  },
+  location: "ENTITY",
+  user: {
+    email: "[email protected]",
+    name: "Ganesh Datta",
+    role: "ADMIN",
+  },
+};
+
+jest.mock("@cortexapps/plugin-core/components", () => {
+  const originalModule = jest.requireActual(
+    "@cortexapps/plugin-core/components"
+  );
+  return {
+    ...originalModule,
+    usePluginContext: () => {
+      return mockContext;
+    },
+    PluginProvider: ({ children }) => {
+      return children;
+    },
+  };
+});
+
+jest.mock("@cortexapps/plugin-core", () => {
+  const originalModule = jest.requireActual("@cortexapps/plugin-core");
+  return {
+    ...originalModule,
+    CortexApi: {
+      ...originalModule.CortexApi,
+      getContext: () => {
+        return mockContext;
+      },
+    },
+  };
+});