feat(techdocs): add extension for setting build strategy

Signed-off-by: Phil Kuang <pkuang@factset.com>

plugins/techdocs-node/api-report.md

@@ -10,6 +10,7 @@ import { Config } from '@backstage/config';
 import { ContainerRunner } from '@backstage/backend-common';
 import { Entity } from '@backstage/catalog-model';
 import express from 'express';
+import { ExtensionPoint } from '@backstage/backend-plugin-api';
 import { IndexableDocument } from '@backstage/plugin-search-common';
 import { Logger } from 'winston';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
@@ -24,6 +25,12 @@ export class DirectoryPreparer implements PreparerBase {
   shouldCleanPreparedDirectory(): boolean;
 }
 
+// @public
+export interface DocsBuildStrategy {
+  // (undocumented)
+  shouldBuild(params: ShouldBuildParameters): Promise<boolean>;
+}
+
 // @public
 export type ETag = string;
 
@@ -226,9 +233,23 @@ export type ReadinessResponse = {
 // @public
 export type RemoteProtocol = 'url' | 'dir';
 
+// @public
+export type ShouldBuildParameters = {
+  entity: Entity;
+};
+
 // @public
 export type SupportedGeneratorKey = 'techdocs' | string;
 
+// @public
+export interface TechdocsBuildStrategyExtensionPoint {
+  // (undocumented)
+  setBuildStrategy(buildStrategy: DocsBuildStrategy): void;
+}
+
+// @public
+export const techdocsBuildStrategyExtensionPoint: ExtensionPoint<TechdocsBuildStrategyExtensionPoint>;
+
 // @public
 export interface TechDocsDocument extends IndexableDocument {
   kind: string;

plugins/techdocs-node/package.json

@@ -47,6 +47,7 @@
     "@azure/identity": "^3.2.1",
     "@azure/storage-blob": "^12.5.0",
     "@backstage/backend-common": "workspace:^",
+    "@backstage/backend-plugin-api": "workspace:^",
     "@backstage/catalog-model": "workspace:^",
     "@backstage/config": "workspace:^",
     "@backstage/errors": "workspace:^",

plugins/techdocs-node/src/extensions.ts

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2023 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.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { createExtensionPoint } from '@backstage/backend-plugin-api';
+import { DocsBuildStrategy } from './techdocsTypes';
+
+/**
+ * Extension point type for setting a custom build strategy.
+ *
+ * @public
+ */
+export interface TechdocsBuildStrategyExtensionPoint {
+  setBuildStrategy(buildStrategy: DocsBuildStrategy): void;
+}
+
+/**
+ * Extension point for setting a custom build strategy.
+ *
+ * @public
+ */
+export const techdocsBuildStrategyExtensionPoint =
+  createExtensionPoint<TechdocsBuildStrategyExtensionPoint>({
+    id: 'techdocs.buildStrategy',
+  });

plugins/techdocs-node/src/index.ts

@@ -23,3 +23,7 @@
 export * from './stages';
 export * from './helpers';
 export * from './techdocsTypes';
+export {
+  techdocsBuildStrategyExtensionPoint,
+  type TechdocsBuildStrategyExtensionPoint,
+} from './extensions';

plugins/techdocs-node/src/techdocsTypes.ts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import { Entity } from '@backstage/catalog-model';
 import { IndexableDocument } from '@backstage/plugin-search-common';
 
 /**
@@ -46,3 +47,21 @@ export interface TechDocsDocument extends IndexableDocument {
    */
   path: string;
 }
+
+/**
+ * Parameters passed to the shouldBuild method on the DocsBuildStrategy interface
+ *
+ * @public
+ */
+export type ShouldBuildParameters = {
+  entity: Entity;
+};
+
+/**
+ * A strategy for when to build TechDocs locally, and when to skip building TechDocs (allowing for an external build)
+ *
+ * @public
+ */
+export interface DocsBuildStrategy {
+  shouldBuild(params: ShouldBuildParameters): Promise<boolean>;
+}