feat(catalog): processor priority

This change enables the ordering of catalog processors by their priority,
allowing for more control over the catalog processing sequence.
The default priority is set to 20, and processors can be assigned a custom
priority to influence their execution order. Lower number indicates higher priority.
The priority can be set by implementing the `getPriority` method in the processor class
or by adding a `catalog.processors.<processorName>.priority` configuration
in the `app-config.yaml` file. The configuration takes precedence over the method.

closes #30963

Signed-off-by: Hellgren Heikki <heikki.hellgren@op.fi>

.changeset/curvy-terms-jam.md

@@ -0,0 +1,14 @@
+---
+'@backstage/plugin-catalog-backend': patch
+'@backstage/plugin-catalog-node': patch
+---
+
+Order catalog processors by priority.
+
+This change enables the ordering of catalog processors by their priority,
+allowing for more control over the catalog processing sequence.
+The default priority is set to 20, and processors can be assigned a custom
+priority to influence their execution order. Lower number indicates higher priority.
+The priority can be set by implementing the `getPriority` method in the processor class
+or by adding a `catalog.processors.<processorName>.priority` configuration
+in the `app-config.yaml` file. The configuration takes precedence over the method.

docs/features/software-catalog/life-of-an-entity.md

@@ -132,6 +132,10 @@ in the registration order, but this does not apply over multiple catalog modules
 the order of registration depends on the order in which the modules are loaded
 by the framework.
 
+It's possible to customize the order of the processors by modifying the
+`catalog.processors.<processorName>.priority` configuration option.
+The default priority is `20`, and lower value means that the processor runs earlier.
+
 :::
 
 Each step has the opportunity to optionally modify the entity, and to optionally

plugins/catalog-backend/config.d.ts

@@ -251,6 +251,12 @@ export interface Config {
          * Whether the processor is enabled or not. Defaults to true.
          */
         enabled?: boolean;
+        /**
+         * The priority of the processor, which is used to determine the order in which
+         * processors are run. The default priority is 20, and lower value means
+         * that the processor runs earlier.
+         */
+        priority?: number;
       };
     };
   };

plugins/catalog-backend/src/service/CatalogBuilder.ts

@@ -727,7 +727,32 @@ export class CatalogBuilder {
 
     this.checkMissingExternalProcessors(processors);
 
-    return this.filterProcessors(processors);
+    const filteredProcessors = this.filterProcessors(processors);
+
+    // Lastly sort the processors by priority. Config can override the
+    // priority of a processor to allow control of 3rd party processors.
+    filteredProcessors.sort((a, b) => {
+      const getProcessorPriority = (processor: CatalogProcessor) => {
+        try {
+          return (
+            config.getOptionalNumber(
+              `catalog.processors.${processor.getProcessorName()}.priority`,
+            ) ??
+            processor.getPriority?.() ??
+            20
+          );
+        } catch (_) {
+          // In case the processor config is not an object, just return default priority
+          return 20;
+        }
+      };
+
+      const aPriority = getProcessorPriority(a);
+      const bPriority = getProcessorPriority(b);
+      return aPriority - bPriority;
+    });
+
+    return filteredProcessors;
   }
 
   private filterProcessors(processors: CatalogProcessor[]) {

plugins/catalog-node/report.api.md

@@ -60,6 +60,7 @@ export type CatalogProcessor = {
     emit: CatalogProcessorEmit,
     cache: CatalogProcessorCache,
   ): Promise<Entity>;
+  getPriority?(): number;
 };
 
 // @public

plugins/catalog-node/src/api/processor.ts

@@ -100,6 +100,14 @@ export type CatalogProcessor = {
     emit: CatalogProcessorEmit,
     cache: CatalogProcessorCache,
   ): Promise<Entity>;
+
+  /**
+   * Returns a processor priority, which is used to determine the order in which
+   * processors are run. The default priority is 20, and lower value means
+   * that the processor runs earlier.
+   * @returns A number representing the priority of the processor.
+   */
+  getPriority?(): number;
 };
 
 /**