plugin(scaffolder-relation-processor): add the scaffolder relation ca…

…talog processor (#506)

Signed-off-by: Frank Kong <[email protected]>

workspaces/scaffolder-relation-processor/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

workspaces/scaffolder-relation-processor/.changeset/config.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch"
+}

workspaces/scaffolder-relation-processor/.changeset/shaggy-eggs-joke.md

@@ -0,0 +1,5 @@
+---
+'@backstage-community/plugin-catalog-backend-module-scaffolder-relation-processor': minor
+---
+
+Initial release of the scaffolder relation catalog processor for backstage

workspaces/scaffolder-relation-processor/.dockerignore

@@ -0,0 +1,8 @@
+.git
+.yarn/cache
+.yarn/install-state.gz
+node_modules
+packages/*/src
+packages/*/node_modules
+plugins
+*.local.yaml

workspaces/scaffolder-relation-processor/.eslintignore

@@ -0,0 +1 @@
+playwright.config.ts

workspaces/scaffolder-relation-processor/.eslintrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  root: true,
+};

workspaces/scaffolder-relation-processor/.gitignore

@@ -0,0 +1,57 @@
+# macOS
+.DS_Store
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Coverage directory generated when running tests with coverage
+coverage
+
+# Dependencies
+node_modules/
+
+# Yarn 3 files
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+# Node version directives
+.nvmrc
+
+# dotenv environment variables file
+.env
+.env.test
+
+# Build output
+dist
+dist-types
+/plugins/*/dist-dynamic/*
+!/plugins/*/dist-dynamic/package.json
+!/plugins/*/dist-dynamic/yarn.lock
+
+# Temporary change files created by Vim
+*.swp
+
+# MkDocs build output
+site
+
+# Local configuration files
+*.local.yaml
+
+# Sensitive credentials
+*-credentials.yaml
+
+# vscode database functionality support files
+*.session.sql
+
+# E2E test reports
+e2e-test-report/

workspaces/scaffolder-relation-processor/.prettierignore

@@ -0,0 +1,5 @@
+dist
+dist-types
+coverage
+.vscode
+.eslintrc.js

workspaces/scaffolder-relation-processor/README.md

@@ -0,0 +1,10 @@
+# [Backstage](https://backstage.io)
+
+This is your newly scaffolded Backstage App, Good Luck!
+
+To start the app, run:
+
+```sh
+yarn install
+yarn dev
+```

workspaces/scaffolder-relation-processor/backstage.json

@@ -0,0 +1,3 @@
+{
+  "version": "1.27.0"
+}

workspaces/scaffolder-relation-processor/catalog-info.yaml

@@ -0,0 +1,13 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: scaffolder-relation-processor
+  description: An example of a Backstage application.
+  # Example for optional annotations
+  # annotations:
+  #   github.com/project-slug: backstage/backstage
+  #   backstage.io/techdocs-ref: dir:.
+spec:
+  type: website
+  owner: [email protected]
+  lifecycle: experimental

workspaces/scaffolder-relation-processor/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@internal/scaffolder-relation-processor",
+  "version": "1.0.0",
+  "private": true,
+  "engines": {
+    "node": "18 || 20"
+  },
+  "scripts": {
+    "tsc": "tsc",
+    "tsc:full": "tsc --skipLibCheck false --incremental false",
+    "build:all": "backstage-cli repo build --all",
+    "build:api-reports": "yarn build:api-reports:only --tsc",
+    "build:api-reports:only": "backstage-repo-tools api-reports -o ae-wrong-input-file-type --validate-release-tags",
+    "clean": "backstage-cli repo clean",
+    "test": "backstage-cli repo test",
+    "test:all": "backstage-cli repo test --coverage",
+    "fix": "backstage-cli repo fix",
+    "lint": "backstage-cli repo lint --since origin/main",
+    "lint:all": "backstage-cli repo lint",
+    "prettier:check": "prettier --check .",
+    "new": "backstage-cli new --scope @backstage-community"
+  },
+  "workspaces": {
+    "packages": [
+      "packages/*",
+      "plugins/*"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/community-plugins",
+    "directory": "workspaces/scaffolder-relation-processor"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.26.5",
+    "@backstage/e2e-test-utils": "^0.1.1",
+    "@backstage/repo-tools": "^0.9.0",
+    "@changesets/cli": "^2.27.1",
+    "@material-ui/core": "^4.12.4",
+    "@spotify/prettier-config": "^12.0.0",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.2.19",
+    "node-gyp": "^9.0.0",
+    "prettier": "^2.3.2",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "typescript": "~5.3.0"
+  },
+  "resolutions": {
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
+    "@microsoft/api-extractor": "7.36.4"
+  },
+  "prettier": "@spotify/prettier-config",
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx,mjs,cjs}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md}": [
+      "prettier --write"
+    ]
+  }
+}

workspaces/scaffolder-relation-processor/plugins/README.md

@@ -0,0 +1,9 @@
+# The Plugins Folder
+
+This is where your own plugins and their associated modules live, each in a
+separate folder of its own.
+
+If you want to create a new plugin here, go to your project root directory, run
+the command `yarn new`, and follow the on-screen instructions.
+
+You can also check out existing plugins on [the plugin marketplace](https://backstage.io/plugins)!

workspaces/scaffolder-relation-processor/plugins/catalog-backend-module-scaffolder-relation-processor/.eslintrc.js

@@ -0,0 +1 @@
+module.exports = require('@backstage/cli/config/eslint-factory')(__dirname);

workspaces/scaffolder-relation-processor/plugins/catalog-backend-module-scaffolder-relation-processor/README.md

@@ -0,0 +1,74 @@
+# Catalog Backend Module for Scaffolder Relation Catalog Processor
+
+This is an extension module to the catalog-backend plugin, providing an additional catalog entity processor that adds a new relation that depends on the `spec.scaffoldedFrom` field to link scaffolder templates and the catalog entities they generated.
+
+## Getting Started
+
+1. Install the scaffolder relation catalog processor module using the following command:
+
+   ```console
+   yarn workspace backend add @backstage-community/backstage-plugin-catalog-backend-module-scaffolder-relation-processor
+   ```
+
+### Installing on the new backend system
+
+To install this module into the [new backend system](https://backstage.io/docs/backend-system/), add the following into the `packages/backend/src/index.ts` file:
+
+```ts title="packages/backend/src/index.ts
+const backend = createBackend();
+
+// highlight-add-start
+backend.add(
+  import(
+    '@backstage-community/backstage-plugin-catalog-backend-module-scaffolder-relation-processor/alpha'
+  ),
+);
+// highlight-add-end
+
+backend.start();
+```
+
+### Installing on the legacy backend system
+
+To install this module into the legacy backend system, add the following to the `packages/backend/src/plugins/catalog.ts` file:
+
+```ts title=packages/backend/src/plugins/catalog.ts
+// highlight-add-start
+import { ScaffolderRelationEntityProcessor } from '@backstage-community/backstage-plugin-catalog-backend-module-scaffolder-relation-processor';
+
+// highlight-add-end
+
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
+  const builder = await CatalogBuilder.create(env);
+
+  /* ... other processors and/or providers ... */
+  // highlight-add-start
+  builder.addProcessor(new ScaffolderRelationEntityProcessor());
+  // highlight-add-end
+
+  const { processingEngine, router } = await builder.build();
+  await processingEngine.start();
+
+  return router;
+}
+```
+
+### Usage
+
+Catalog entities containing the `spec.scaffoldedFrom` field will have a relation link be formed between it and the `template` corresponding to the entity ref in the `spec.scaffoldedFrom` field.
+
+This link can be viewed in the `relations` field of the Raw YAML view of a catalog entity when inspecting an entity. In the entity with the `spec.scaffoldedFrom` field, the relation type is `scaffoldedFrom` with a target pointing to the value of the `spec.scaffoldedFrom` field. Conversely, for the target template, it will have a relation type of `ScaffolderOf` with a target pointing to the entity with the `spec.scaffoldedFrom` field.
+
+These relations should also appear on the `EntityCatalogGraphView` component from the `@backstage/plugin-catalog-graph` package (only if the entity corresponding to the entity ref exists in the catalog).
+
+#### Example graph view
+
+![scaffoldedFrom Relation Graph View](./docs/example-images/scaffoldedFromGraphView.png)
+![scaffolderOf Relation Graph View](./docs/example-images/scaffolderOfGraphView.png)
+
+#### Example Raw YAML view
+
+![scaffoldedFrom Relation YAML View](./docs/example-images/scaffoldedFromYAMLView.png)
+![scaffoldedOf Relation YAML View](./docs/example-images/scaffolderOfYAMLView.png)

workspaces/scaffolder-relation-processor/plugins/catalog-backend-module-scaffolder-relation-processor/api-report-alpha.md

@@ -0,0 +1,13 @@
+## API Report File for "@backstage-community/plugin-catalog-backend-module-scaffolder-relation-processor"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { BackendFeature } from '@backstage/backend-plugin-api';
+
+// @public
+const catalogModuleScaffolderRelationProcessor: () => BackendFeature;
+export default catalogModuleScaffolderRelationProcessor;
+
+// (No @packageDocumentation comment for this package)
+```

workspaces/scaffolder-relation-processor/plugins/catalog-backend-module-scaffolder-relation-processor/api-report.md

@@ -0,0 +1,41 @@
+## API Report File for "@backstage-community/plugin-catalog-backend-module-scaffolder-relation-processor"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+import { BackendDynamicPluginInstaller } from '@backstage/backend-dynamic-feature-service';
+import { CatalogProcessor } from '@backstage/plugin-catalog-node';
+import { CatalogProcessorEmit } from '@backstage/plugin-catalog-node';
+import { Entity } from '@backstage/catalog-model';
+import { LocationSpec } from '@backstage/plugin-catalog-common';
+
+// @public (undocumented)
+export const dynamicPluginInstaller: BackendDynamicPluginInstaller;
+
+// @public
+export const RELATION_SCAFFOLDED_FROM = 'scaffoldedFrom';
+
+// @public
+export const RELATION_SCAFFOLDER_OF = 'scaffolderOf';
+
+// @public
+export type ScaffoldedFromSpec = {
+  spec: {
+    scaffoldedFrom: string;
+  };
+};
+
+// @public (undocumented)
+export class ScaffolderRelationEntityProcessor implements CatalogProcessor {
+  // (undocumented)
+  getProcessorName(): string;
+  // (undocumented)
+  postProcessEntity(
+    entity: Entity,
+    _location: LocationSpec,
+    emit: CatalogProcessorEmit,
+  ): Promise<Entity>;
+}
+
+// (No @packageDocumentation comment for this package)
+```

workspaces/scaffolder-relation-processor/plugins/catalog-backend-module-scaffolder-relation-processor/dist-dynamic/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@backstage-community/plugin-catalog-backend-module-scaffolder-relation-processor-dynamic",
+  "description": "The scaffolder-relation-processor backend module for the catalog plugin.",
+  "version": "0.0.0",
+  "main": "dist/index.cjs.js",
+  "types": "dist/index.d.ts",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "backend-plugin-module"
+  },
+  "exports": {
+    ".": {
+      "require": "./dist/index.cjs.js",
+      "default": "./dist/index.cjs.js"
+    },
+    "./alpha": {
+      "require": "./dist/alpha.cjs.js",
+      "default": "./dist/alpha.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "config.d.ts",
+    "app-config.janus-idp.yaml",
+    "alpha"
+  ],
+  "bundleDependencies": true,
+  "peerDependencies": {
+    "@backstage/backend-common": "^0.21.6",
+    "@backstage/backend-dynamic-feature-service": "^0.2.8",
+    "@backstage/backend-plugin-api": "^0.6.16",
+    "@backstage/catalog-model": "^1.4.5",
+    "@backstage/plugin-catalog-common": "^1.0.22",
+    "@backstage/plugin-catalog-node": "^1.11.1"
+  },
+  "overrides": {
+    "@aws-sdk/util-utf8-browser": {
+      "@smithy/util-utf8": "^2.0.0"
+    }
+  },
+  "resolutions": {
+    "@aws-sdk/util-utf8-browser": "npm:@smithy/util-utf8@~2"
+  }
+}