@backstage-community/plugin-tech-insights-backend 0.6.2 → 0.6.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @backstage-community/plugin-tech-insights-backend
 
+## 0.6.3
+
+### Patch Changes
+
+- Updated dependencies [1d33996]
+  - @backstage-community/plugin-tech-insights-common@0.2.18
+  - @backstage-community/plugin-tech-insights-node@0.6.7
+
 ## 0.6.2
 
 ### Patch Changes

package/README.md

@@ -1,8 +1,10 @@
 # Tech Insights Backend
 
-This is the backend for the default Backstage Tech Insights feature.
-This provides the API for the frontend tech insights, scorecards and fact visualization functionality,
-as well as a framework to run fact retrievers and store fact values in to a data store.
+The backend plugin for Tech Insights.
+
+It provides the API for the frontend tech insights, scorecards and fact visualization functionality, as well as a framework to run fact retrievers and store fact values in to a data store.
+
+Looking for the old backend installation docs? Visit [here](./docs/old-backend-system.md).
 
 ## Installation
 
@@ -13,133 +15,104 @@ as well as a framework to run fact retrievers and store fact values in to a data
 yarn --cwd packages/backend add @backstage-community/plugin-tech-insights-backend
 ```
 
-### Adding the plugin to your `packages/backend`
+### Add the plugin to your backend
 
 ```ts title="packages/backend/src/index.ts"
+// Add the following to `packages/backend/src/index.ts`
 backend.add(import('@backstage-community/plugin-tech-insights-backend'));
 ```
 
-You can use the extension points [@backstage-community/plugin-tech-insights-node](../tech-insights-node)
-to add your `FactRetriever` or set a `FactCheckerFactory`.
+## Built-in Defaults
+
+### Included FactRetrievers
 
-The built-in `FactRetrievers`:
+`FactRetrievers` are only registered if configured in the `app-config.yaml`. Meaning that while you have the tech insights backend installed, you will not have any fact retrievers present in your application.
 
-- `entityMetadataFactRetriever`
-- `entityOwnershipFactRetriever`
-- `techdocsFactRetriever`
+There are three built-in FactRetrievers that come with Tech Insights:
 
-`FactRetrievers` only get registered if they get configured:
+- `entityMetadataFactRetriever`: Generates facts which indicate the completeness of entity metadata
+- `entityOwnershipFactRetriever`: Generates facts which indicate the quality of data in the `spec.owner` field
+- `techdocsFactRetriever`: Generates facts related to the completeness of techdocs configuration for entities
+
+#### Registering the built-in FactRetrievers
+
+The following example registers the built-in fact retrievers to run every 6 hours, while retaining the latest two weeks of fact data.
 
 ```yaml title="app-config.yaml"
 techInsights:
   factRetrievers:
+    entityMetadataFactRetriever:
+      # How often the fact retriever should run
+      cadence: '*/15 * * * *'
+      # How long to keep the fact data
+      lifecycle: { timeToLive: { weeks: 2 } }
     entityOwnershipFactRetriever:
       cadence: '*/15 * * * *'
       lifecycle: { timeToLive: { weeks: 2 } }
+    techdocsFactRetriever:
+      cadence: '*/15 * * * *'
+      lifecycle: { timeToLive: { weeks: 2 } }
 ```
 
-### Adding the plugin to your `packages/backend` (old)
-
-You'll need to add the plugin to the router in your `backend` package. You can
-do this by creating a file called `packages/backend/src/plugins/techInsights.ts`. An example content for `techInsights.ts` could be something like this.
-
-```ts
-import {
-  createRouter,
-  buildTechInsightsContext,
-} from '@backstage-community/plugin-tech-insights-backend';
-import { Router } from 'express';
-import { PluginEnvironment } from '../types';
-
-export default async function createPlugin(
-  env: PluginEnvironment,
-): Promise<Router> {
-  const builder = buildTechInsightsContext({
-    logger: env.logger,
-    config: env.config,
-    database: env.database,
-    discovery: env.discovery,
-    scheduler: env.scheduler,
-    tokenManager: env.tokenManager,
-    factRetrievers: [], // Fact retrievers registrations you want tech insights to use
-  });
-
-  return await createRouter({
-    ...(await builder),
-    logger: env.logger,
-    config: env.config,
-  });
-}
-```
-
-With the `techInsights.ts` router setup in place, add the router to
-`packages/backend/src/index.ts`:
+The optional `lifecycle` configuration value limits the lifetime of fact data. The value can be either `maxItems` or TTL (time to live). Valid options are either a number for `maxItems` or a Luxon duration-like object for TTL.
 
-```diff
-+import techInsights from './plugins/techInsights';
+```yaml
+# Lifecycle configuration examples
+lifecycle: { timeToLive: { weeks: 2 } }
 
- async function main() {
-   ...
-   const createEnv = makeCreateEnv(config);
+# Deletes all but 7 latest facts for each id/entity pair
+lifecycle: { maxItems: 7 };
 
-   const catalogEnv = useHotMemoize(module, () => createEnv('catalog'));
-+  const techInsightsEnv = useHotMemoize(module, () => createEnv('tech_insights'));
-
-   const apiRouter = Router();
-+  apiRouter.use('/tech-insights', await techInsights(techInsightsEnv));
-   ...
-   apiRouter.use(notFoundHandler());
- }
+# Deletes all facts older than 2 weeks (TTL)
+lifecycle: { timeToLive: 1209600000 } # Luxon duration like object
+lifecycle: { timeToLive: { weeks: 2 } }; # Human readable value
 ```
 
-### Adding fact retrievers
+#### Running fact retrievers in a multi-instance installation
 
-At this point the Tech Insights backend is installed in your backend package, but
-you will not have any fact retrievers present in your application. To have the implemented FactRetrieverEngine within this package to be able to retrieve and store fact data into the database, you need to add these.
+The Tech Insights plugin utilizes `PluginTaskScheduler` to schedule and coordinate task invocation across instances. See [the PluginTaskScheduler documentation](https://backstage.io/docs/reference/backend-tasks.plugintaskscheduler) for more information.
 
-To create factRetrieverRegistration you need to implement `FactRetriever` interface defined in `@backstage-community/plugin-tech-insights-node` package (see [Creating fact retrievers](#creating-fact-retrievers) for details). After you have implemented this interface you can wrap that into a registration object like follows:
+### Included FactChecker
 
-```ts
-import { createFactRetrieverRegistration } from '@backstage-community/plugin-tech-insights-backend';
+**NOTE**: You need a Fact Checker configured to get access to the backend routes that will allow the facts to be checked. If you don't have one configured, you will see 404s and potentially other errors.
 
-const myFactRetriever = {
-  /**
-   * snip
-   */
-};
+There is a default FactChecker implementation provided in the [@backstage-community/plugin-tech-insights-backend-module-jsonfc](../tech-insights-backend-module-jsonfc/README.md) module. This implementation uses `json-rules-engine` as the underlying functionality to run checks.
 
-const myFactRetrieverRegistration = createFactRetrieverRegistration({
-  cadence: '1 * 2 * * ', // On the first minute of the second day of the month
-  factRetriever: myFactRetriever,
-});
-```
+You must install the module into your backend system to use the fact checker.
 
-FactRetrieverRegistration also accepts an optional `lifecycle` configuration value. This can be either MaxItems or TTL (time to live). Valid options for this value are either a number for MaxItems or a Luxon duration like object for TTL. For example:
+```bash
+# From your Backstage root directory
+yarn --cwd packages/backend add @backstage-community/plugin-tech-insights-backend-module-jsonfc
+```
 
-```ts
-const maxItems = { maxItems: 7 }; // Deletes all but 7 latest facts for each id/entity pair
-const ttl = { timeToLive: 1209600000 }; // (2 weeks) Deletes items older than 2 weeks
-const ttlWithAHumanReadableValue = { timeToLive: { weeks: 2 } }; // Deletes items older than 2 weeks
+```diff title="packages/backend/src/index.ts"
+// Add the following to `packages/backend/src/index.ts`
+backend.add(import('@backstage-community/plugin-tech-insights-backend'));
++backend.add(import('@backstage-community/plugin-tech-insights-backend-module-jsonfc'));
 ```
 
-To register these fact retrievers to your application you can modify the example `techInsights.ts` file shown above like this:
+Then, configure the checks in the `app-config.yaml` file. The following example configures a _check_ to verify a group has been set as the `spec.owner` for an entity. The check uses the `entityOwnershipFactRetriever` fact retriever to get the data.
 
-```diff
-const builder = buildTechInsightsContext({
-  logger: env.logger,
-  config: env.config,
-  database: env.database,
-  discovery: env.discovery,
-  tokenManager: env.tokenManager,
-  scheduler: env.scheduler,
-- factRetrievers: [],
-+ factRetrievers: [myFactRetrieverRegistration],
-});
+```yaml title="app-config.yaml"
+techInsights:
+  factRetrievers: ...
+  factChecker:
+    checks:
+      groupOwnerCheck:
+        type: json-rules-engine
+        name: Group Owner Check
+        description: Verifies that a group has been set as the spec.owner for this entity
+        factIds:
+          - entityOwnershipFactRetriever
+        rule:
+          conditions:
+            all:
+              - fact: hasGroupOwner
+                operator: equal
+                value: true
 ```
 
-#### Running fact retrievers in a multi-instance installation
-
-The Tech Insights plugin utilizes the `PluginTaskScheduler` for scheduling tasks and coordinating the task invocation across instances. See [the PluginTaskScheduler documentation](https://backstage.io/docs/reference/backend-tasks.plugintaskscheduler) for more information.
+## Creating custom implementations of FactRetrievers
 
 ### Creating Fact Retrievers
 
@@ -156,7 +129,7 @@ An example implementation of a FactRetriever could for example be as follows:
 ```ts
 import { FactRetriever } from '@backstage-community/plugin-tech-insights-node';
 
-const myFactRetriever: FactRetriever = {
+export const myFactRetriever: FactRetriever = {
   id: 'documentation-number-factretriever', // unique identifier of the fact retriever
   version: '0.1.1', // SemVer version number of this fact retriever schema. This should be incremented if the implementation changes
   entityFilter: [{ kind: 'component' }], // EntityFilter to be used in the future (creating checks, graphs etc.) to figure out which entities this fact retrieves data for.
@@ -195,7 +168,7 @@ const myFactRetriever: FactRetriever = {
 
         // All facts that this retriever returns
         facts: {
-          examplenumberfact: 2, //
+          examplenumberfact: 2,
         },
         // (optional) timestamp to use as a Luxon DateTime object
       };
@@ -204,43 +177,33 @@ const myFactRetriever: FactRetriever = {
 };
 ```
 
-### Adding a fact checker
-
-This module comes with a possibility to additionally add a fact checker and expose fact checking endpoints from the API. To be able to enable this feature you need to add a FactCheckerFactory implementation to be part of the `DefaultTechInsightsBuilder` constructor call.
-
-There is a default FactChecker implementation provided in module `@backstage-community/plugin-tech-insights-backend-module-jsonfc`. This implementation uses `json-rules-engine` as the underlying functionality to run checks. If you want to implement your own FactChecker, for example to be able to handle other than `boolean` result types, you can do so by implementing `FactCheckerFactory` and `FactChecker` interfaces from `@backstage-community/plugin-tech-insights-common` package.
-
-To add the default FactChecker into your Tech Insights you need to install the module into your backend application:
-
-```bash
-# From your Backstage root directory
-yarn --cwd packages/backend add @backstage-community/plugin-tech-insights-backend-module-jsonfc
-```
+Additional FactRetrievers are added to the Tech Insights backend by creating a new backend module and registering the FactRetriever with the `techInsightsFactRetrieversExtensionPoint` extension point. This, along with other extension points, are available in the [@backstage-community/plugin-tech-insights-node](../tech-insights-node/README.md) library.
 
-and modify the `techInsights.ts` file to contain a reference to the FactChecker implementation.
+```ts title="plugins/tech-insights-backend-module-my-fact-retriever/src/module.ts"
+import { techInsightsFactRetrieversExtensionPoint } from '@backstage-community/plugin-tech-insights-node';
+import { myFactRetriever } from './myFactRetriever';
 
-```diff
-+import { JsonRulesEngineFactCheckerFactory } from '@backstage-community/plugin-tech-insights-backend-module-jsonfc';
-
-+const myFactCheckerFactory = new JsonRulesEngineFactCheckerFactory({
-+   checks: [],
-+   logger: env.logger,
-+}),
-
- const builder = new DefaultTechInsightsBuilder({
-   logger: env.logger,
-   config: env.config,
-   database: env.database,
-   discovery: env.discovery,
-   tokenManager: env.tokenManager,
-   factRetrievers: [myFactRetrieverRegistration],
-+  factCheckerFactory: myFactCheckerFactory
- });
+export const techInsightsModuleMyFactRetriever = createBackendModule({
+  pluginId: 'tech-insights',
+  moduleId: 'my-fact-retriever',
+  register(reg) {
+    reg.registerInit({
+      deps: {
+        providers: techInsightsFactRetrieversExtensionPoint,
+      },
+      async init({ providers }) {
+        providers.addFactRetrievers({
+          myFactRetriever,
+        });
+      },
+    });
+  },
+});
 ```
 
-NOTE: You need a Fact Checker Factory to get access to the backend routes that will allow the facts to be checked. If you don't have a Fact Checker Factory you will see 404s and potentially other errors.
+### Adding a fact checker
 
-To be able to run checks, you need to additionally add individual checks into your FactChecker implementation. For examples how to add these, you can check the documentation of the individual implementation of the FactChecker
+If you want to implement your own FactChecker, for example to be able to handle other than `boolean` result types, you can do so by implementing `FactCheckerFactory` and `FactChecker` interfaces from `@backstage-community/plugin-tech-insights-common` package.
 
 #### Modifying check persistence
 
@@ -255,132 +218,3 @@ const myFactCheckerFactory = new JsonRulesEngineFactCheckerFactory({
 }),
 
 ```
-
-## Included FactRetrievers
-
-There are three FactRetrievers that come out of the box with Tech Insights:
-
-- `entityMetadataFactRetriever`: Generates facts which indicate the completeness of entity metadata
-- `entityOwnershipFactRetriever`: Generates facts which indicate the quality of data in the spec.owner field
-- `techdocsFactRetriever`: Generates facts related to the completeness of techdocs configuration for entities
-
-## Backend Example
-
-Here's an example backend setup that will use the three included fact retrievers so you can get an idea of how this all works. This will be the entire contents of your `techInsights.ts` file found at `\packages\backend\src\plugins` as per [Adding the plugin to your `packages/backend`](#adding-the-plugin-to-your-packagesbackend)
-
-```ts
-import {
-  createRouter,
-  buildTechInsightsContext,
-  createFactRetrieverRegistration,
-  entityOwnershipFactRetriever,
-  entityMetadataFactRetriever,
-  techdocsFactRetriever,
-} from '@backstage-community/plugin-tech-insights-backend';
-import { Router } from 'express';
-import { PluginEnvironment } from '../types';
-import {
-  JsonRulesEngineFactCheckerFactory,
-  JSON_RULE_ENGINE_CHECK_TYPE,
-} from '@backstage-community/plugin-tech-insights-backend-module-jsonfc';
-
-const ttlTwoWeeks = { timeToLive: { weeks: 2 } };
-
-export default async function createPlugin(
-  env: PluginEnvironment,
-): Promise<Router> {
-  const techInsightsContext = await buildTechInsightsContext({
-    logger: env.logger,
-    config: env.config,
-    database: env.database,
-    discovery: env.discovery,
-    tokenManager: env.tokenManager,
-    scheduler: env.scheduler,
-    factRetrievers: [
-      createFactRetrieverRegistration({
-        cadence: '0 */6 * * *', // Run every 6 hours - https://crontab.guru/#0_*/6_*_*_*
-        factRetriever: entityOwnershipFactRetriever,
-        lifecycle: ttlTwoWeeks,
-      }),
-      createFactRetrieverRegistration({
-        cadence: '0 */6 * * *',
-        factRetriever: entityMetadataFactRetriever,
-        lifecycle: ttlTwoWeeks,
-      }),
-      createFactRetrieverRegistration({
-        cadence: '0 */6 * * *',
-        factRetriever: techdocsFactRetriever,
-        lifecycle: ttlTwoWeeks,
-      }),
-    ],
-    factCheckerFactory: new JsonRulesEngineFactCheckerFactory({
-      logger: env.logger,
-      checks: [
-        {
-          id: 'groupOwnerCheck',
-          type: JSON_RULE_ENGINE_CHECK_TYPE,
-          name: 'Group Owner Check',
-          description:
-            'Verifies that a Group has been set as the owner for this entity',
-          factIds: ['entityOwnershipFactRetriever'],
-          rule: {
-            conditions: {
-              all: [
-                {
-                  fact: 'hasGroupOwner',
-                  operator: 'equal',
-                  value: true,
-                },
-              ],
-            },
-          },
-        },
-        {
-          id: 'titleCheck',
-          type: JSON_RULE_ENGINE_CHECK_TYPE,
-          name: 'Title Check',
-          description:
-            'Verifies that a Title, used to improve readability, has been set for this entity',
-          factIds: ['entityMetadataFactRetriever'],
-          rule: {
-            conditions: {
-              all: [
-                {
-                  fact: 'hasTitle',
-                  operator: 'equal',
-                  value: true,
-                },
-              ],
-            },
-          },
-        },
-        {
-          id: 'techDocsCheck',
-          type: JSON_RULE_ENGINE_CHECK_TYPE,
-          name: 'TechDocs Check',
-          description:
-            'Verifies that TechDocs has been enabled for this entity',
-          factIds: ['techdocsFactRetriever'],
-          rule: {
-            conditions: {
-              all: [
-                {
-                  fact: 'hasAnnotationBackstageIoTechdocsRef',
-                  operator: 'equal',
-                  value: true,
-                },
-              ],
-            },
-          },
-        },
-      ],
-    }),
-  });
-
-  return await createRouter({
-    ...techInsightsContext,
-    logger: env.logger,
-    config: env.config,
-  });
-}
-```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage-community/plugin-tech-insights-backend",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "backstage": {
     "role": "backend-plugin",
     "pluginId": "tech-insights",
@@ -45,8 +45,8 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage-community/plugin-tech-insights-common": "^0.2.17",
-    "@backstage-community/plugin-tech-insights-node": "^0.6.6",
+    "@backstage-community/plugin-tech-insights-common": "^0.2.18",
+    "@backstage-community/plugin-tech-insights-node": "^0.6.7",
     "@backstage/backend-common": "^0.24.0",
     "@backstage/backend-defaults": "^0.4.3",
     "@backstage/backend-plugin-api": "^0.8.0",