From 4368196fba0d145fdb7bb478301fb5f8e92a89b0 Mon Sep 17 00:00:00 2001
From: Nikolas Skoufis <nskoufis@seek.com.au>
Date: Wed, 2 Mar 2022 10:06:23 +1100
Subject: [PATCH] Accept object in shouldBuild for future extensibility

Signed-off-by: Nikolas Skoufis <nskoufis@seek.com.au>
---
 plugins/techdocs-backend/api-report.md              |  7 ++++++-
 plugins/techdocs-backend/src/index.ts               |  1 +
 .../src/service/DocsBuildStrategy.test.ts           |  4 ++--
 .../src/service/DocsBuildStrategy.ts                | 13 +++++++++++--
 plugins/techdocs-backend/src/service/index.ts       |  5 ++++-
 plugins/techdocs-backend/src/service/router.ts      |  2 +-
 6 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/plugins/techdocs-backend/api-report.md b/plugins/techdocs-backend/api-report.md
index 3ce3a2504b..2bf4664f77 100644
--- a/plugins/techdocs-backend/api-report.md
+++ b/plugins/techdocs-backend/api-report.md
@@ -45,7 +45,7 @@ export class DefaultTechDocsCollator implements DocumentCollator {
 // @public
 export interface DocsBuildStrategy {
   // (undocumented)
-  shouldBuild(entity: Entity): Promise<boolean>;
+  shouldBuild(params: ShouldBuildParameters): Promise<boolean>;
 }
 
 // @public
@@ -76,6 +76,11 @@ export type RouterOptions =
   | RecommendedDeploymentOptions
   | OutOfTheBoxDeploymentOptions;
 
+// @public
+export type ShouldBuildParameters = {
+  entity: Entity;
+};
+
 // @public
 export type TechDocsCollatorOptions = {
   discovery: PluginEndpointDiscovery;
diff --git a/plugins/techdocs-backend/src/index.ts b/plugins/techdocs-backend/src/index.ts
index 2a17bf2736..01acbea2cc 100644
--- a/plugins/techdocs-backend/src/index.ts
+++ b/plugins/techdocs-backend/src/index.ts
@@ -26,6 +26,7 @@ export type {
   RecommendedDeploymentOptions,
   OutOfTheBoxDeploymentOptions,
   DocsBuildStrategy,
+  ShouldBuildParameters,
 } from './service';
 
 export { DefaultTechDocsCollator } from './search';
diff --git a/plugins/techdocs-backend/src/service/DocsBuildStrategy.test.ts b/plugins/techdocs-backend/src/service/DocsBuildStrategy.test.ts
index 76b70e67e9..84bd960f8f 100644
--- a/plugins/techdocs-backend/src/service/DocsBuildStrategy.test.ts
+++ b/plugins/techdocs-backend/src/service/DocsBuildStrategy.test.ts
@@ -46,7 +46,7 @@ describe('DefaultDocsBuildStrategy', () => {
 
       MockedConfigReader.prototype.getString.mockReturnValue('local');
 
-      const result = await defaultDocsBuildStrategy.shouldBuild(entity);
+      const result = await defaultDocsBuildStrategy.shouldBuild({ entity });
 
       expect(result).toBe(true);
     });
@@ -57,7 +57,7 @@ describe('DefaultDocsBuildStrategy', () => {
 
       MockedConfigReader.prototype.getString.mockReturnValue('external');
 
-      const result = await defaultDocsBuildStrategy.shouldBuild(entity);
+      const result = await defaultDocsBuildStrategy.shouldBuild({ entity });
 
       expect(result).toBe(false);
     });
diff --git a/plugins/techdocs-backend/src/service/DocsBuildStrategy.ts b/plugins/techdocs-backend/src/service/DocsBuildStrategy.ts
index e0220d7a32..42a16234f9 100644
--- a/plugins/techdocs-backend/src/service/DocsBuildStrategy.ts
+++ b/plugins/techdocs-backend/src/service/DocsBuildStrategy.ts
@@ -16,13 +16,22 @@
 import { Entity } from '@backstage/catalog-model';
 import { Config } from '@backstage/config';
 
+/**
+ * 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(entity: Entity): Promise<boolean>;
+  shouldBuild(params: ShouldBuildParameters): Promise<boolean>;
 }
 
 export class DefaultDocsBuildStrategy {
@@ -36,7 +45,7 @@ export class DefaultDocsBuildStrategy {
     return new DefaultDocsBuildStrategy(config);
   }
 
-  async shouldBuild(_: Entity): Promise<boolean> {
+  async shouldBuild(_: ShouldBuildParameters): Promise<boolean> {
     return this.config.getString('techdocs.builder') === 'local';
   }
 }
diff --git a/plugins/techdocs-backend/src/service/index.ts b/plugins/techdocs-backend/src/service/index.ts
index 29db2d2038..7355a34e32 100644
--- a/plugins/techdocs-backend/src/service/index.ts
+++ b/plugins/techdocs-backend/src/service/index.ts
@@ -20,4 +20,7 @@ export type {
   RecommendedDeploymentOptions,
   OutOfTheBoxDeploymentOptions,
 } from './router';
-export type { DocsBuildStrategy } from './DocsBuildStrategy';
+export type {
+  DocsBuildStrategy,
+  ShouldBuildParameters,
+} from './DocsBuildStrategy';
diff --git a/plugins/techdocs-backend/src/service/router.ts b/plugins/techdocs-backend/src/service/router.ts
index 4d51ebd485..abe83b3d47 100644
--- a/plugins/techdocs-backend/src/service/router.ts
+++ b/plugins/techdocs-backend/src/service/router.ts
@@ -221,7 +221,7 @@ export async function createRouter(
     // techdocs-backend will only try to build documentation for an entity if techdocs.builder is set to 'local'
     // If set to 'external', it will assume that an external process (e.g. CI/CD pipeline
     // of the repository) is responsible for building and publishing documentation to the storage provider
-    const shouldBuild = await docsBuildStrategy.shouldBuild(entity);
+    const shouldBuild = await docsBuildStrategy.shouldBuild({ entity });
     if (!shouldBuild) {
       // However, if caching is enabled, take the opportunity to check and
       // invalidate stale cache entries.