Merge pull request #19876 from backstage/mob/backend-system-finalizations

Moved `ScaffolderEntitiesProcessor` and `catalogModuleTemplateKind` to a dedicated module

.changeset/twenty-worms-enjoy.md

@@ -0,0 +1,7 @@
+---
+'@backstage/plugin-scaffolder-backend': minor
+---
+
+**DEPRECATION**: Deprecated `ScaffolderEntitiesProcessor`, which should now instead be imported from `@backstage/plugin-catalog-backend-module-scaffolder-entity-model`.
+
+`catalogModuleTemplateKind` was also moved to that package and renamed to `catalogModuleScaffolderEntityModel`, without any deprecation since it was an alpha export.

.changeset/wet-donuts-fry.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend-module-scaffolder-entity-model': minor
+---
+
+Added a dedicated module to collect the `ScaffolderEntitiesProcessor` and `catalogModuleTemplateKind`.

docs/features/software-catalog/extending-the-model.md

@@ -467,7 +467,7 @@ The next step is to create a custom processor for your new entity kind. This
 will be used within the catalog to make sure that it's able to ingest and
 validate entities of our new kind. Just like with the definition package, you
 can find inspiration in for example the existing
-[ScaffolderEntitiesProcessor](https://github.com/backstage/backstage/tree/master/plugins/scaffolder-backend/src/processor/ScaffolderEntitiesProcessor.ts).
+[ScaffolderEntitiesProcessor](https://github.com/backstage/backstage/tree/master/plugins/catalog-backend-module-scaffolder-entity-model/src/processor/ScaffolderEntitiesProcessor.ts).
 We also provide a high-level example of what a catalog process for a custom
 entity might look like:
 

packages/backend-next/package.json

@@ -34,6 +34,7 @@
     "@backstage/plugin-azure-devops-backend": "workspace:^",
     "@backstage/plugin-badges-backend": "workspace:^",
     "@backstage/plugin-catalog-backend": "workspace:^",
+    "@backstage/plugin-catalog-backend-module-scaffolder-entity-model": "workspace:^",
     "@backstage/plugin-catalog-backend-module-unprocessed": "workspace:^",
     "@backstage/plugin-devtools-backend": "workspace:^",
     "@backstage/plugin-entity-feedback-backend": "workspace:^",

packages/backend-next/src/index.ts

@@ -23,6 +23,9 @@ backend.add(import('@backstage/plugin-app-backend/alpha'));
 backend.add(import('@backstage/plugin-azure-devops-backend'));
 backend.add(import('@backstage/plugin-badges-backend'));
 backend.add(import('@backstage/plugin-catalog-backend-module-unprocessed'));
+backend.add(
+  import('@backstage/plugin-catalog-backend-module-scaffolder-entity-model'),
+);
 backend.add(import('@backstage/plugin-catalog-backend/alpha'));
 backend.add(import('@backstage/plugin-devtools-backend'));
 backend.add(import('@backstage/plugin-entity-feedback-backend'));

packages/backend/package.json

@@ -40,6 +40,7 @@
     "@backstage/plugin-azure-sites-backend": "workspace:^",
     "@backstage/plugin-badges-backend": "workspace:^",
     "@backstage/plugin-catalog-backend": "workspace:^",
+    "@backstage/plugin-catalog-backend-module-scaffolder-entity-model": "workspace:^",
     "@backstage/plugin-catalog-backend-module-unprocessed": "workspace:^",
     "@backstage/plugin-catalog-node": "workspace:^",
     "@backstage/plugin-code-coverage-backend": "workspace:^",

packages/backend/src/plugins/catalog.ts

@@ -15,11 +15,11 @@
  */
 
 import { CatalogBuilder } from '@backstage/plugin-catalog-backend';
-import { ScaffolderEntitiesProcessor } from '@backstage/plugin-scaffolder-backend';
+import { ScaffolderEntitiesProcessor } from '@backstage/plugin-catalog-backend-module-scaffolder-entity-model';
+import { UnprocessedEntitiesModule } from '@backstage/plugin-catalog-backend-module-unprocessed';
 import { Router } from 'express';
 import { PluginEnvironment } from '../types';
 import { DemoEventBasedEntityProvider } from './DemoEventBasedEntityProvider';
-import { UnprocessedEntitiesModule } from '@backstage/plugin-catalog-backend-module-unprocessed';
 
 export default async function createPlugin(
   env: PluginEnvironment,

plugins/catalog-backend-module-scaffolder-entity-model/.eslintrc.js

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

plugins/catalog-backend-module-scaffolder-entity-model/README.md

@@ -0,0 +1,3 @@
+# @backstage/plugin-catalog-backend-module-scaffolder-entity-model
+
+Adds support for the scaffolder specific entity model (e.g. the Template kind) to the catalog backend plugin.

plugins/catalog-backend-module-scaffolder-entity-model/api-report.md

@@ -0,0 +1,29 @@
+## API Report File for "@backstage/plugin-catalog-backend-module-scaffolder-entity-model"
+
+> 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';
+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
+const catalogModuleScaffolderEntityModel: () => BackendFeature;
+export default catalogModuleScaffolderEntityModel;
+
+// @public
+export class ScaffolderEntitiesProcessor implements CatalogProcessor {
+  // (undocumented)
+  getProcessorName(): string;
+  // (undocumented)
+  postProcessEntity(
+    entity: Entity,
+    _location: LocationSpec,
+    emit: CatalogProcessorEmit,
+  ): Promise<Entity>;
+  // (undocumented)
+  validateEntityKind(entity: Entity): Promise<boolean>;
+}
+```

plugins/catalog-backend-module-scaffolder-entity-model/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@backstage/plugin-catalog-backend-module-scaffolder-entity-model",
+  "description": "Adds support for the scaffolder specific entity model (e.g. the Template kind) to the catalog backend plugin.",
+  "version": "0.0.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "package.json": [
+        "package.json"
+      ]
+    }
+  },
+  "backstage": {
+    "role": "backend-plugin-module"
+  },
+  "scripts": {
+    "start": "backstage-cli package start",
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "dependencies": {
+    "@backstage/backend-common": "workspace:^",
+    "@backstage/backend-plugin-api": "workspace:^",
+    "@backstage/catalog-model": "workspace:^",
+    "@backstage/plugin-catalog-common": "workspace:^",
+    "@backstage/plugin-catalog-node": "workspace:^",
+    "@backstage/plugin-scaffolder-common": "workspace:^"
+  },
+  "devDependencies": {
+    "@backstage/backend-test-utils": "workspace:^",
+    "@backstage/cli": "workspace:^"
+  },
+  "files": [
+    "dist"
+  ]
+}

plugins/catalog-backend-module-scaffolder-entity-model/src/index.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 The Backstage Authors
+ * Copyright 2020 The Backstage Authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -14,4 +14,11 @@
  * limitations under the License.
  */
 
-export { catalogModuleTemplateKind } from './catalogModuleTemplateKind';
+/**
+ * Adds support for the scaffolder specific entity model (e.g. the Template kind) to the catalog backend plugin.
+ *
+ * @packageDocumentation
+ */
+
+export * from './processor';
+export { catalogModuleScaffolderEntityModel as default } from './module';

plugins/catalog-backend-module-scaffolder-entity-model/src/module.test.ts

@@ -15,16 +15,16 @@
  */
 
 import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node/alpha';
-import { ScaffolderEntitiesProcessor } from '../processor';
-import { catalogModuleTemplateKind } from './catalogModuleTemplateKind';
+import { ScaffolderEntitiesProcessor } from './processor';
+import { catalogModuleScaffolderEntityModel } from './module';
 import { startTestBackend } from '@backstage/backend-test-utils';
 
-describe('catalogModuleTemplateKind', () => {
+describe('catalogModuleScaffolderEntityModel', () => {
   it('should register the extension point', async () => {
     const extensionPoint = { addProcessor: jest.fn() };
     await startTestBackend({
       extensionPoints: [[catalogProcessingExtensionPoint, extensionPoint]],
-      features: [catalogModuleTemplateKind()],
+      features: [catalogModuleScaffolderEntityModel()],
     });
 
     expect(extensionPoint.addProcessor).toHaveBeenCalledWith(

plugins/catalog-backend-module-scaffolder-entity-model/src/module.ts

@@ -16,16 +16,17 @@
 
 import { createBackendModule } from '@backstage/backend-plugin-api';
 import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node/alpha';
-import { ScaffolderEntitiesProcessor } from '../processor';
+import { ScaffolderEntitiesProcessor } from '@backstage/plugin-catalog-backend-module-scaffolder-entity-model';
 
 /**
- * Registers support for the Template kind to the catalog backend plugin.
+ * Registers support for the scaffolder specific entity model (e.g. the Template
+ * kind) to the catalog backend plugin.
  *
- * @alpha
+ * @public
  */
-export const catalogModuleTemplateKind = createBackendModule({
-  moduleId: 'templateKind',
+export const catalogModuleScaffolderEntityModel = createBackendModule({
   pluginId: 'catalog',
+  moduleId: 'scaffolderEntityModel',
   register(env) {
     env.registerInit({
       deps: {

plugins/catalog-backend-module-scaffolder-entity-model/src/processor/ScaffolderEntitiesProcessor.ts

@@ -32,7 +32,11 @@ import {
   templateEntityV1beta3Validator,
 } from '@backstage/plugin-scaffolder-common';
 
-/** @public */
+/**
+ * Adds support for scaffolder specific entity kinds to the catalog.
+ *
+ * @public
+ */
 export class ScaffolderEntitiesProcessor implements CatalogProcessor {
   getProcessorName(): string {
     return 'ScaffolderEntitiesProcessor';

plugins/scaffolder-backend/alpha-api-report.md

@@ -15,9 +15,6 @@ import { ResourcePermission } from '@backstage/plugin-permission-common';
 import { TemplateEntityStepV1beta3 } from '@backstage/plugin-scaffolder-common';
 import { TemplateParametersV1beta3 } from '@backstage/plugin-scaffolder-common';
 
-// @alpha
-export const catalogModuleTemplateKind: () => BackendFeature;
-
 // @alpha (undocumented)
 export const createScaffolderActionConditionalDecision: (
   permission: ResourcePermission<'scaffolder-action'>,

plugins/scaffolder-backend/api-report.md

@@ -5,12 +5,9 @@
 ```ts
 import { ActionContext as ActionContext_2 } from '@backstage/plugin-scaffolder-node';
 import { CatalogApi } from '@backstage/catalog-client';
-import { CatalogProcessor } from '@backstage/plugin-catalog-node';
-import { CatalogProcessorEmit } from '@backstage/plugin-catalog-node';
 import { Config } from '@backstage/config';
 import { createPullRequest } from 'octokit-plugin-create-pull-request';
 import { Duration } from 'luxon';
-import { Entity } from '@backstage/catalog-model';
 import { executeShellCommand as executeShellCommand_2 } from '@backstage/plugin-scaffolder-node';
 import { ExecuteShellCommandOptions } from '@backstage/plugin-scaffolder-node';
 import express from 'express';
@@ -20,7 +17,6 @@ import { HumanDuration } from '@backstage/types';
 import { IdentityApi } from '@backstage/plugin-auth-node';
 import { JsonObject } from '@backstage/types';
 import { Knex } from 'knex';
-import { LocationSpec } from '@backstage/plugin-catalog-common';
 import { Logger } from 'winston';
 import { Octokit } from 'octokit';
 import { PermissionEvaluator } from '@backstage/plugin-permission-common';
@@ -30,6 +26,7 @@ import { PluginDatabaseManager } from '@backstage/backend-common';
 import { PluginTaskScheduler } from '@backstage/backend-tasks';
 import { RESOURCE_TYPE_SCAFFOLDER_ACTION } from '@backstage/plugin-scaffolder-common/alpha';
 import { RESOURCE_TYPE_SCAFFOLDER_TEMPLATE } from '@backstage/plugin-scaffolder-common/alpha';
+import { ScaffolderEntitiesProcessor as ScaffolderEntitiesProcessor_2 } from '@backstage/plugin-catalog-backend-module-scaffolder-entity-model';
 import { Schema } from 'jsonschema';
 import { ScmIntegrationRegistry } from '@backstage/integration';
 import { ScmIntegrations } from '@backstage/integration';
@@ -881,19 +878,8 @@ export interface RouterOptions {
 // @public @deprecated
 export type RunCommandOptions = ExecuteShellCommandOptions;
 
-// @public (undocumented)
-export class ScaffolderEntitiesProcessor implements CatalogProcessor {
-  // (undocumented)
-  getProcessorName(): string;
-  // (undocumented)
-  postProcessEntity(
-    entity: Entity,
-    _location: LocationSpec,
-    emit: CatalogProcessorEmit,
-  ): Promise<Entity>;
-  // (undocumented)
-  validateEntityKind(entity: Entity): Promise<boolean>;
-}
+// @public @deprecated
+export const ScaffolderEntitiesProcessor: typeof ScaffolderEntitiesProcessor_2;
 
 // @public @deprecated
 export type SerializedTask = SerializedTask_2;

plugins/scaffolder-backend/package.json

@@ -56,6 +56,7 @@
     "@backstage/integration": "workspace:^",
     "@backstage/plugin-auth-node": "workspace:^",
     "@backstage/plugin-catalog-backend": "workspace:^",
+    "@backstage/plugin-catalog-backend-module-scaffolder-entity-model": "workspace:^",
     "@backstage/plugin-catalog-common": "workspace:^",
     "@backstage/plugin-catalog-node": "workspace:^",
     "@backstage/plugin-permission-common": "workspace:^",

plugins/scaffolder-backend/src/alpha.ts

@@ -14,6 +14,5 @@
  * limitations under the License.
  */
 
-export * from './modules';
 export * from './service';
 export { scaffolderPlugin as default } from './ScaffolderPlugin';

plugins/scaffolder-backend/src/deprecated.ts

@@ -24,6 +24,7 @@ import {
   fetchContents as fetchContentsNode,
 } from '@backstage/plugin-scaffolder-node';
 import { JsonObject } from '@backstage/types';
+import { ScaffolderEntitiesProcessor as ScaffolderEntitiesProcessorModule } from '@backstage/plugin-catalog-backend-module-scaffolder-entity-model';
 
 /**
  * @public
@@ -75,3 +76,11 @@ export const executeShellCommand = executeShellCommandNode;
  * @deprecated Use `fetchContents` from `@backstage/plugin-scaffolder-node` instead
  */
 export const fetchContents = fetchContentsNode;
+
+/**
+ * Adds support for scaffolder specific entity kinds to the catalog.
+ *
+ * @public
+ * @deprecated Import from `@backstage/plugin-catalog-backend-module-scaffolder-entity-model` instead
+ */
+export const ScaffolderEntitiesProcessor = ScaffolderEntitiesProcessorModule;

plugins/scaffolder-backend/src/index.ts

@@ -23,6 +23,5 @@
 export * from './scaffolder';
 export * from './service/router';
 export * from './lib';
-export * from './processor';
 
 export * from './deprecated';

yarn.lock

@@ -5667,6 +5667,21 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@backstage/plugin-catalog-backend-module-scaffolder-entity-model@workspace:^, @backstage/plugin-catalog-backend-module-scaffolder-entity-model@workspace:plugins/catalog-backend-module-scaffolder-entity-model":
+  version: 0.0.0-use.local
+  resolution: "@backstage/plugin-catalog-backend-module-scaffolder-entity-model@workspace:plugins/catalog-backend-module-scaffolder-entity-model"
+  dependencies:
+    "@backstage/backend-common": "workspace:^"
+    "@backstage/backend-plugin-api": "workspace:^"
+    "@backstage/backend-test-utils": "workspace:^"
+    "@backstage/catalog-model": "workspace:^"
+    "@backstage/cli": "workspace:^"
+    "@backstage/plugin-catalog-common": "workspace:^"
+    "@backstage/plugin-catalog-node": "workspace:^"
+    "@backstage/plugin-scaffolder-common": "workspace:^"
+  languageName: unknown
+  linkType: soft
+
 "@backstage/plugin-catalog-backend-module-unprocessed@workspace:^, @backstage/plugin-catalog-backend-module-unprocessed@workspace:plugins/catalog-backend-module-unprocessed":
   version: 0.0.0-use.local
   resolution: "@backstage/plugin-catalog-backend-module-unprocessed@workspace:plugins/catalog-backend-module-unprocessed"
@@ -8637,6 +8652,7 @@ __metadata:
     "@backstage/integration": "workspace:^"
     "@backstage/plugin-auth-node": "workspace:^"
     "@backstage/plugin-catalog-backend": "workspace:^"
+    "@backstage/plugin-catalog-backend-module-scaffolder-entity-model": "workspace:^"
     "@backstage/plugin-catalog-common": "workspace:^"
     "@backstage/plugin-catalog-node": "workspace:^"
     "@backstage/plugin-permission-common": "workspace:^"
@@ -25868,6 +25884,7 @@ __metadata:
     "@backstage/plugin-azure-devops-backend": "workspace:^"
     "@backstage/plugin-badges-backend": "workspace:^"
     "@backstage/plugin-catalog-backend": "workspace:^"
+    "@backstage/plugin-catalog-backend-module-scaffolder-entity-model": "workspace:^"
     "@backstage/plugin-catalog-backend-module-unprocessed": "workspace:^"
     "@backstage/plugin-devtools-backend": "workspace:^"
     "@backstage/plugin-entity-feedback-backend": "workspace:^"
@@ -25909,6 +25926,7 @@ __metadata:
     "@backstage/plugin-azure-sites-backend": "workspace:^"
     "@backstage/plugin-badges-backend": "workspace:^"
     "@backstage/plugin-catalog-backend": "workspace:^"
+    "@backstage/plugin-catalog-backend-module-scaffolder-entity-model": "workspace:^"
     "@backstage/plugin-catalog-backend-module-unprocessed": "workspace:^"
     "@backstage/plugin-catalog-node": "workspace:^"
     "@backstage/plugin-code-coverage-backend": "workspace:^"