feat: allow overriding default techdocs preparers

a new extension point `TechdocsPreparerExtensionPoint` allows
registering custom preparers for the techdocs plugin.

closes #21952

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

.changeset/chatty-flies-worry.md

@@ -0,0 +1,6 @@
+---
+'@backstage/plugin-techdocs-backend': patch
+'@backstage/plugin-techdocs-node': patch
+---
+
+Allow overriding default techdocs preparers with new `TechdocsPreparerExtensionPoint`

plugins/techdocs-backend/src/plugin.ts

@@ -15,9 +15,9 @@
  */
 
 import {
+  cacheToPluginCacheManager,
   DockerContainerRunner,
   loggerToWinstonLogger,
-  cacheToPluginCacheManager,
 } from '@backstage/backend-common';
 import {
   coreServices,
@@ -26,12 +26,15 @@ import {
 
 import {
   DocsBuildStrategy,
-  Preparers,
   Generators,
+  PreparerBase,
+  Preparers,
   Publisher,
+  RemoteProtocol,
   techdocsBuildsExtensionPoint,
-  techdocsGeneratorExtensionPoint,
   TechdocsGenerator,
+  techdocsGeneratorExtensionPoint,
+  techdocsPreparerExtensionPoint,
 } from '@backstage/plugin-techdocs-node';
 import Docker from 'dockerode';
 import { createRouter } from '@backstage/plugin-techdocs-backend';
@@ -64,6 +67,18 @@ export const techdocsPlugin = createBackendPlugin({
       },
     });
 
+    const customPreparers = new Map<RemoteProtocol, PreparerBase>();
+    env.registerExtensionPoint(techdocsPreparerExtensionPoint, {
+      registerPreparer(protocol: RemoteProtocol, preparer: PreparerBase) {
+        if (customPreparers.has(protocol)) {
+          throw new Error(
+            `Preparer for protocol ${protocol} is already registered`,
+          );
+        }
+        customPreparers.set(protocol, preparer);
+      },
+    });
+
     env.registerInit({
       deps: {
         config: coreServices.rootConfig,
@@ -91,6 +106,9 @@ export const techdocsPlugin = createBackendPlugin({
           reader: urlReader,
           logger: winstonLogger,
         });
+        for (const [protocol, preparer] of customPreparers.entries()) {
+          preparers.register(protocol, preparer);
+        }
 
         // Docker client (conditionally) used by the generators, based on techdocs.generators config.
         const dockerClient = new Docker();

plugins/techdocs-node/api-report.md

@@ -291,6 +291,15 @@ export type TechDocsMetadata = {
   files?: string[];
 };
 
+// @public
+export interface TechdocsPreparerExtensionPoint {
+  // (undocumented)
+  registerPreparer(protocol: RemoteProtocol, preparer: PreparerBase): void;
+}
+
+// @public
+export const techdocsPreparerExtensionPoint: ExtensionPoint<TechdocsPreparerExtensionPoint>;
+
 // @public
 export const transformDirLocation: (
   entity: Entity,

plugins/techdocs-node/src/extensions.ts

@@ -15,7 +15,7 @@
  */
 import { createExtensionPoint } from '@backstage/backend-plugin-api';
 import { DocsBuildStrategy } from './techdocsTypes';
-import { TechdocsGenerator } from './stages';
+import { PreparerBase, RemoteProtocol, TechdocsGenerator } from './stages';
 
 /**
  * Extension point type for configuring Techdocs builds.
@@ -54,3 +54,22 @@ export const techdocsGeneratorExtensionPoint =
   createExtensionPoint<TechdocsGeneratorExtensionPoint>({
     id: 'techdocs.generator',
   });
+
+/**
+ * Extension point type for configuring a custom Techdocs preparer
+ *
+ * @public
+ */
+export interface TechdocsPreparerExtensionPoint {
+  registerPreparer(protocol: RemoteProtocol, preparer: PreparerBase): void;
+}
+
+/**
+ * Extension point for configuring a custom Techdocs preparer
+ *
+ * @public
+ */
+export const techdocsPreparerExtensionPoint =
+  createExtensionPoint<TechdocsPreparerExtensionPoint>({
+    id: 'techdocs.preparer',
+  });

plugins/techdocs-node/src/index.ts

@@ -26,6 +26,8 @@ export * from './techdocsTypes';
 export {
   techdocsBuildsExtensionPoint,
   techdocsGeneratorExtensionPoint,
+  techdocsPreparerExtensionPoint,
   type TechdocsBuildsExtensionPoint,
   type TechdocsGeneratorExtensionPoint,
+  type TechdocsPreparerExtensionPoint,
 } from './extensions';