feat(tech-insights): support registry and persistence at plugin

Support `FactRetrieverRegistry` and `PersistenceContext` at the `techInsightsPlugin`
using extension points.

Additionally, move `FactRetrieverRegistry` and `PersistenceContext`
to `@backstage/plugin-tech-insights-node`.
Original exports are marked as deprecated and re-export the moved types.

Signed-off-by: Patrick Jungermann <Patrick.Jungermann@gmail.com>

.changeset/orange-gorillas-clean.md

@@ -0,0 +1,26 @@
+---
+'@backstage/plugin-tech-insights-backend': patch
+'@backstage/plugin-tech-insights-node': patch
+---
+
+Move `FactRetrieverRegistry` and `PersistenceContext` to `@backstage/plugin-tech-insights-node`.
+
+Original exports are marked as deprecated and re-export the moved types.
+
+Please replace uses like
+
+```ts
+import {
+  FactRetrieverRegistry,
+  PersistenceContext,
+} from '@backstage/plugin-tech-insights-backend';
+```
+
+with
+
+```ts
+import {
+  FactRetrieverRegistry,
+  PersistenceContext,
+} from '@backstage/plugin-tech-insights-node';
+```

plugins/tech-insights-backend/api-report.md

@@ -13,14 +13,14 @@ import { FactCheckerFactory } from '@backstage/plugin-tech-insights-node';
 import { FactLifecycle } from '@backstage/plugin-tech-insights-node';
 import { FactRetriever } from '@backstage/plugin-tech-insights-node';
 import { FactRetrieverRegistration } from '@backstage/plugin-tech-insights-node';
-import { FactSchema } from '@backstage/plugin-tech-insights-common';
+import { FactRetrieverRegistry as FactRetrieverRegistry_2 } from '@backstage/plugin-tech-insights-node';
 import { HumanDuration } from '@backstage/types';
 import { Logger } from 'winston';
+import { PersistenceContext as PersistenceContext_2 } from '@backstage/plugin-tech-insights-node';
 import { PluginDatabaseManager } from '@backstage/backend-common';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
 import { PluginTaskScheduler } from '@backstage/backend-tasks';
 import { TechInsightCheck } from '@backstage/plugin-tech-insights-node';
-import { TechInsightsStore } from '@backstage/plugin-tech-insights-node';
 import { TokenManager } from '@backstage/backend-common';
 
 // @public
@@ -64,30 +64,17 @@ export type FactRetrieverRegistrationOptions = {
   initialDelay?: Duration | HumanDuration;
 };
 
-// @public (undocumented)
-export interface FactRetrieverRegistry {
-  // (undocumented)
-  get(retrieverReference: string): Promise<FactRetrieverRegistration>;
-  // (undocumented)
-  getSchemas(): Promise<FactSchema[]>;
-  // (undocumented)
-  listRegistrations(): Promise<FactRetrieverRegistration[]>;
-  // (undocumented)
-  listRetrievers(): Promise<FactRetriever[]>;
-  // (undocumented)
-  register(registration: FactRetrieverRegistration): Promise<void>;
-}
+// @public @deprecated (undocumented)
+export type FactRetrieverRegistry = FactRetrieverRegistry_2;
 
 // @public
 export const initializePersistenceContext: (
   database: PluginDatabaseManager,
   options?: PersistenceContextOptions,
-) => Promise<PersistenceContext>;
+) => Promise<PersistenceContext_2>;
 
-// @public
-export type PersistenceContext = {
-  techInsightsStore: TechInsightsStore;
-};
+// @public @deprecated (undocumented)
+export type PersistenceContext = PersistenceContext_2;
 
 // @public
 export type PersistenceContextOptions = {
@@ -102,7 +89,7 @@ export interface RouterOptions<
   config: Config;
   factChecker?: FactChecker<CheckType, CheckResultType>;
   logger: Logger;
-  persistenceContext: PersistenceContext;
+  persistenceContext: PersistenceContext_2;
 }
 
 // @public
@@ -114,7 +101,7 @@ export type TechInsightsContext<
   CheckResultType extends CheckResult,
 > = {
   factChecker?: FactChecker<CheckType, CheckResultType>;
-  persistenceContext: PersistenceContext;
+  persistenceContext: PersistenceContext_2;
   factRetrieverEngine: FactRetrieverEngine;
 };
 
@@ -130,11 +117,11 @@ export interface TechInsightsOptions<
   // (undocumented)
   discovery: PluginEndpointDiscovery;
   factCheckerFactory?: FactCheckerFactory<CheckType, CheckResultType>;
-  factRetrieverRegistry?: FactRetrieverRegistry;
+  factRetrieverRegistry?: FactRetrieverRegistry_2;
   factRetrievers?: FactRetrieverRegistration[];
   // (undocumented)
   logger: Logger;
-  persistenceContext?: PersistenceContext;
+  persistenceContext?: PersistenceContext_2;
   // (undocumented)
   scheduler: PluginTaskScheduler;
   // (undocumented)

plugins/tech-insights-backend/src/deprecated.ts

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2024 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 {
+  FactRetrieverRegistry as FactRetrieverRegistry_,
+  PersistenceContext as PersistenceContext_,
+} from '@backstage/plugin-tech-insights-node';
+
+/**
+ * @public
+ * @deprecated Use FactRetrieverRegistry from `@backstage/plugin-tech-insights-node` instead.
+ */
+export type FactRetrieverRegistry = FactRetrieverRegistry_;
+
+/**
+ * @public
+ * @deprecated Use PersistenceContext from `@backstage/plugin-tech-insights-node` instead.
+ */
+export type PersistenceContext = PersistenceContext_;

plugins/tech-insights-backend/src/index.ts

@@ -15,4 +15,5 @@
  */
 
 export { techInsightsPlugin as default } from './plugin';
+export * from './deprecated';
 export * from './service';

plugins/tech-insights-backend/src/plugin/plugin.ts

@@ -24,9 +24,13 @@ import {
   FactCheckerFactory,
   FactRetriever,
   FactRetrieverRegistration,
+  FactRetrieverRegistry,
+  PersistenceContext,
   TechInsightCheck,
   techInsightsFactCheckerFactoryExtensionPoint,
+  techInsightsFactRetrieverRegistryExtensionPoint,
   techInsightsFactRetrieversExtensionPoint,
+  techInsightsPersistenceContextExtensionPoint,
 } from '@backstage/plugin-tech-insights-node';
 import {
   buildTechInsightsContext,
@@ -57,6 +61,16 @@ export const techInsightsPlugin = createBackendPlugin({
       },
     });
 
+    let factRetrieverRegistry: FactRetrieverRegistry | undefined = undefined;
+    env.registerExtensionPoint(
+      techInsightsFactRetrieverRegistryExtensionPoint,
+      {
+        setFactRetrieverRegistry(registry: FactRetrieverRegistry): void {
+          factRetrieverRegistry = registry;
+        },
+      },
+    );
+
     // initialized with built-in fact retrievers
     // only added as registration if there is config for them
     const addedFactRetrievers: Record<string, FactRetriever> = {
@@ -72,6 +86,13 @@ export const techInsightsPlugin = createBackendPlugin({
       },
     });
 
+    let persistenceContext: PersistenceContext | undefined = undefined;
+    env.registerExtensionPoint(techInsightsPersistenceContextExtensionPoint, {
+      setPersistenceContext(context: PersistenceContext): void {
+        persistenceContext = context;
+      },
+    });
+
     env.registerInit({
       deps: {
         config: coreServices.rootConfig,
@@ -109,8 +130,10 @@ export const techInsightsPlugin = createBackendPlugin({
           database,
           discovery,
           factCheckerFactory,
+          factRetrieverRegistry,
           factRetrievers,
           logger: winstonLogger,
+          persistenceContext,
           scheduler,
           tokenManager,
         });

plugins/tech-insights-backend/src/service/fact/FactRetrieverEngine.test.ts

@@ -17,11 +17,11 @@
 import {
   FactRetriever,
   FactRetrieverRegistration,
+  FactRetrieverRegistry,
   FactSchemaDefinition,
   TechInsightFact,
   TechInsightsStore,
 } from '@backstage/plugin-tech-insights-node';
-import { FactRetrieverRegistry } from './FactRetrieverRegistry';
 import {
   DefaultFactRetrieverEngine,
   FactRetrieverEngine,

plugins/tech-insights-backend/src/service/fact/FactRetrieverEngine.ts

@@ -18,10 +18,10 @@ import {
   FactRetriever,
   FactRetrieverContext,
   FactRetrieverRegistration,
+  FactRetrieverRegistry,
   TechInsightFact,
   TechInsightsStore,
 } from '@backstage/plugin-tech-insights-node';
-import { FactRetrieverRegistry } from './FactRetrieverRegistry';
 import { Logger } from 'winston';
 import { PluginTaskScheduler } from '@backstage/backend-tasks';
 import { Duration } from 'luxon';

plugins/tech-insights-backend/src/service/fact/FactRetrieverRegistry.ts

@@ -17,22 +17,11 @@
 import {
   FactRetriever,
   FactRetrieverRegistration,
+  FactRetrieverRegistry,
 } from '@backstage/plugin-tech-insights-node';
 import { FactSchema } from '@backstage/plugin-tech-insights-common';
 import { ConflictError, NotFoundError } from '@backstage/errors';
 
-/**
- * @public
- *
- */
-export interface FactRetrieverRegistry {
-  register(registration: FactRetrieverRegistration): Promise<void>;
-  get(retrieverReference: string): Promise<FactRetrieverRegistration>;
-  listRetrievers(): Promise<FactRetriever[]>;
-  listRegistrations(): Promise<FactRetrieverRegistration[]>;
-  getSchemas(): Promise<FactSchema[]>;
-}
-
 /**
  * A basic in memory fact retriever registry.
  *

plugins/tech-insights-backend/src/service/fact/index.ts

@@ -17,5 +17,4 @@
 export { createFactRetrieverRegistration } from './createFactRetriever';
 export type { FactRetrieverRegistrationOptions } from './createFactRetriever';
 export type { FactRetrieverEngine } from './FactRetrieverEngine';
-export type { FactRetrieverRegistry } from './FactRetrieverRegistry';
 export * from './factRetrievers';

plugins/tech-insights-backend/src/service/persistence/index.ts

@@ -15,7 +15,4 @@
  */
 
 export { initializePersistenceContext } from './persistenceContext';
-export type {
-  PersistenceContext,
-  PersistenceContextOptions,
-} from './persistenceContext';
+export type { PersistenceContextOptions } from './persistenceContext';

plugins/tech-insights-backend/src/service/persistence/persistenceContext.ts

@@ -20,22 +20,13 @@ import {
 } from '@backstage/backend-common';
 import { Logger } from 'winston';
 import { TechInsightsDatabase } from './TechInsightsDatabase';
-import { TechInsightsStore } from '@backstage/plugin-tech-insights-node';
+import { PersistenceContext } from '@backstage/plugin-tech-insights-node';
 
 const migrationsDir = resolvePackagePath(
   '@backstage/plugin-tech-insights-backend',
   'migrations',
 );
 
-/**
- * A Container for persistence related components in TechInsights
- *
- * @public
- */
-export type PersistenceContext = {
-  techInsightsStore: TechInsightsStore;
-};
-
 /**
  * A Container for persistence context initialization options
  *

plugins/tech-insights-backend/src/service/router.test.ts

@@ -24,8 +24,10 @@ import {
 import { ConfigReader } from '@backstage/config';
 import request from 'supertest';
 import express from 'express';
-import { PersistenceContext } from './persistence/persistenceContext';
-import { TechInsightsStore } from '@backstage/plugin-tech-insights-node';
+import {
+  PersistenceContext,
+  TechInsightsStore,
+} from '@backstage/plugin-tech-insights-node';
 import { DateTime } from 'luxon';
 import { Knex } from 'knex';
 import { TaskScheduler } from '@backstage/backend-tasks';

plugins/tech-insights-backend/src/service/router.ts

@@ -19,13 +19,13 @@ import Router from 'express-promise-router';
 import { Config } from '@backstage/config';
 import {
   FactChecker,
+  PersistenceContext,
   TechInsightCheck,
 } from '@backstage/plugin-tech-insights-node';
 
 import { CheckResult } from '@backstage/plugin-tech-insights-common';
 import { Logger } from 'winston';
 import { DateTime } from 'luxon';
-import { PersistenceContext } from './persistence/persistenceContext';
 import {
   CompoundEntityRef,
   parseEntityRef,

plugins/tech-insights-backend/src/service/techInsightsContextBuilder.ts

@@ -19,10 +19,7 @@ import {
   FactRetrieverEngine,
 } from './fact/FactRetrieverEngine';
 import { Logger } from 'winston';
-import {
-  DefaultFactRetrieverRegistry,
-  FactRetrieverRegistry,
-} from './fact/FactRetrieverRegistry';
+import { DefaultFactRetrieverRegistry } from './fact/FactRetrieverRegistry';
 import { Config } from '@backstage/config';
 import {
   PluginDatabaseManager,
@@ -33,12 +30,11 @@ import {
   FactChecker,
   FactCheckerFactory,
   FactRetrieverRegistration,
+  FactRetrieverRegistry,
+  PersistenceContext,
   TechInsightCheck,
 } from '@backstage/plugin-tech-insights-node';
-import {
-  initializePersistenceContext,
-  PersistenceContext,
-} from './persistence/persistenceContext';
+import { initializePersistenceContext } from './persistence';
 import { CheckResult } from '@backstage/plugin-tech-insights-common';
 import { PluginTaskScheduler } from '@backstage/backend-tasks';
 

plugins/tech-insights-node/api-report.md

@@ -80,6 +80,20 @@ export type FactRetrieverRegistration = {
   initialDelay?: Duration | HumanDuration;
 };
 
+// @public (undocumented)
+export interface FactRetrieverRegistry {
+  // (undocumented)
+  get(retrieverReference: string): Promise<FactRetrieverRegistration>;
+  // (undocumented)
+  getSchemas(): Promise<FactSchema[]>;
+  // (undocumented)
+  listRegistrations(): Promise<FactRetrieverRegistration[]>;
+  // (undocumented)
+  listRetrievers(): Promise<FactRetriever[]>;
+  // (undocumented)
+  register(registration: FactRetrieverRegistration): Promise<void>;
+}
+
 // @public
 export type FactSchemaDefinition = Omit<FactRetriever, 'handler'>;
 
@@ -93,6 +107,11 @@ export type MaxItems = {
   maxItems: number;
 };
 
+// @public
+export type PersistenceContext = {
+  techInsightsStore: TechInsightsStore;
+};
+
 // @public
 export interface TechInsightCheck {
   description: string;
@@ -152,6 +171,15 @@ export interface TechInsightsFactCheckerFactoryExtensionPoint {
 // @public
 export const techInsightsFactCheckerFactoryExtensionPoint: ExtensionPoint<TechInsightsFactCheckerFactoryExtensionPoint>;
 
+// @public (undocumented)
+export interface TechInsightsFactRetrieverRegistryExtensionPoint {
+  // (undocumented)
+  setFactRetrieverRegistry(registry: FactRetrieverRegistry): void;
+}
+
+// @public
+export const techInsightsFactRetrieverRegistryExtensionPoint: ExtensionPoint<TechInsightsFactRetrieverRegistryExtensionPoint>;
+
 // @public (undocumented)
 export interface TechInsightsFactRetrieversExtensionPoint {
   // (undocumented)
@@ -161,6 +189,15 @@ export interface TechInsightsFactRetrieversExtensionPoint {
 // @public
 export const techInsightsFactRetrieversExtensionPoint: ExtensionPoint<TechInsightsFactRetrieversExtensionPoint>;
 
+// @public (undocumented)
+export interface TechInsightsPersistenceContextExtensionPoint {
+  // (undocumented)
+  setPersistenceContext(context: PersistenceContext): void;
+}
+
+// @public
+export const techInsightsPersistenceContextExtensionPoint: ExtensionPoint<TechInsightsPersistenceContextExtensionPoint>;
+
 // @public
 export interface TechInsightsStore {
   getFactsBetweenTimestampsByIds(

plugins/tech-insights-node/src/extensionPoints.ts

@@ -16,8 +16,9 @@
 
 import { createExtensionPoint } from '@backstage/backend-plugin-api';
 import { CheckResult } from '@backstage/plugin-tech-insights-common';
-import { FactRetriever } from './facts';
 import { FactCheckerFactory, TechInsightCheck } from './checks';
+import { FactRetriever, FactRetrieverRegistry } from './facts';
+import { PersistenceContext } from './persistence';
 
 /**
  * @public
@@ -57,3 +58,37 @@ export const techInsightsFactCheckerFactoryExtensionPoint =
   createExtensionPoint<TechInsightsFactCheckerFactoryExtensionPoint>({
     id: 'tech-insights.fact-checker-factory',
   });
+
+/**
+ * @public
+ */
+export interface TechInsightsFactRetrieverRegistryExtensionPoint {
+  setFactRetrieverRegistry(registry: FactRetrieverRegistry): void;
+}
+
+/**
+ * An extension point that allows other plugins or modules to set a custom FactRetrieverRegistry.
+ *
+ * @public
+ */
+export const techInsightsFactRetrieverRegistryExtensionPoint =
+  createExtensionPoint<TechInsightsFactRetrieverRegistryExtensionPoint>({
+    id: 'tech-insights.fact-retriever-registry',
+  });
+
+/**
+ * @public
+ */
+export interface TechInsightsPersistenceContextExtensionPoint {
+  setPersistenceContext(context: PersistenceContext): void;
+}
+
+/**
+ * An extension point that allows other plugins or modules to set a custom PersistenceContext.
+ *
+ * @public
+ */
+export const techInsightsPersistenceContextExtensionPoint =
+  createExtensionPoint<TechInsightsPersistenceContextExtensionPoint>({
+    id: 'tech-insights.persistence-context',
+  });

plugins/tech-insights-node/src/facts.ts

@@ -230,3 +230,14 @@ export type FactRetrieverRegistration = {
    */
   initialDelay?: Duration | HumanDuration;
 };
+
+/**
+ * @public
+ */
+export interface FactRetrieverRegistry {
+  register(registration: FactRetrieverRegistration): Promise<void>;
+  get(retrieverReference: string): Promise<FactRetrieverRegistration>;
+  listRetrievers(): Promise<FactRetriever[]>;
+  listRegistrations(): Promise<FactRetrieverRegistration[]>;
+  getSchemas(): Promise<FactSchema[]>;
+}

plugins/tech-insights-node/src/persistence.ts

@@ -22,6 +22,15 @@ import {
 import { DateTime } from 'luxon';
 import { FactSchema } from '@backstage/plugin-tech-insights-common';
 
+/**
+ * A Container for persistence related components in TechInsights
+ *
+ * @public
+ */
+export type PersistenceContext = {
+  techInsightsStore: TechInsightsStore;
+};
+
 /**
  * TechInsights Database
  *