Add more breaking changes.

Update API reports.

Signed-off-by: Jussi Hallila <jussi@hallila.com>

.changeset/six-coins-admire.md

@@ -6,7 +6,7 @@
 BREAKING CHANGES:
 
 - The helper function to create a fact retriever registration is now expecting an object of configuration items instead of individual arguments.
-  Modify your techInsights.ts plugin configuration in `packages/backend/src/plugins/techInsights.ts` (or equivalent) the following way:
+  Modify your `techInsights.ts` plugin configuration in `packages/backend/src/plugins/techInsights.ts` (or equivalent) the following way:
 
 ```diff
 -createFactRetrieverRegistration(
@@ -20,6 +20,17 @@ BREAKING CHANGES:
 
 ```
 
+- `TechInsightsStore` interface has changed its signature of `insertFacts` method. If you have created your own implementation of either `TechInsightsDatabase` or `FactRetrieverEngine` you need to modify the implementation/call to this method to accept/pass-in an object instead if individual arguments. The interface now accepts an additional `lifecycle` argument which is optional (defined below). An example modification to fact retriever engine:
+
+```diff
+-await this.repository.insertFacts(factRetriever.id, facts);
++await this.repository.insertFacts({
++ id: factRetriever.id,
++ facts,
++ lifecycle,
++});
+```
+
 Adds a configuration option to fact retrievers to define lifecycle for facts the retriever persists. Possible values are either 'max items' or 'time-to-live'. The former will keep only n number of items in the database for each fact per entity. The latter will remove all facts that are older than the TTL value.
 
 Possible values:

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

@@ -26,11 +26,11 @@ export const buildTechInsightsContext: <
 ) => Promise<TechInsightsContext<CheckType, CheckResultType>>;
 
 // @public
-export function createFactRetrieverRegistration(
-  cadence: string,
-  factRetriever: FactRetriever,
-  lifecycle?: FactLifecycle,
-): FactRetrieverRegistration;
+export function createFactRetrieverRegistration({
+  cadence,
+  factRetriever,
+  lifecycle,
+}: FactRetrieverRegistrationOptions): FactRetrieverRegistration;
 
 // @public
 export function createRouter<
@@ -44,6 +44,13 @@ export const entityMetadataFactRetriever: FactRetriever;
 // @public
 export const entityOwnershipFactRetriever: FactRetriever;
 
+// @public (undocumented)
+export type FactRetrieverRegistrationOptions = {
+  cadence: string;
+  factRetriever: FactRetriever;
+  lifecycle?: FactLifecycle;
+};
+
 // @public
 export type PersistenceContext = {
   techInsightsStore: TechInsightsStore;

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

@@ -25,4 +25,5 @@ export type {
 
 export type { PersistenceContext } from './service/persistence/persistenceContext';
 export { createFactRetrieverRegistration } from './service/fact/createFactRetriever';
+export type { FactRetrieverRegistrationOptions } from './service/fact/createFactRetriever';
 export * from './service/fact/factRetrievers';

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

@@ -125,7 +125,11 @@ export class FactRetrieverEngine {
       }
 
       try {
-        await this.repository.insertFacts(factRetriever.id, facts, lifecycle);
+        await this.repository.insertFacts({
+          id: factRetriever.id,
+          facts,
+          lifecycle,
+        });
         this.logger.info(
           `Stored ${facts.length} facts for fact retriever ${
             factRetriever.id

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

@@ -19,6 +19,14 @@ import {
   FactRetrieverRegistration,
 } from '@backstage/plugin-tech-insights-node';
 
+/**
+ * @public
+ *
+ * @param cadence - cron expression to indicate when the fact retriever should be triggered
+ * @param factRetriever - Implementation of fact retriever consisting of at least id, version, schema and handler
+ * @param lifecycle - Optional lifecycle definition indicating the cleanup logic of facts when this retriever is run
+ *
+ */
 export type FactRetrieverRegistrationOptions = {
   cadence: string;
   factRetriever: FactRetriever;
@@ -50,7 +58,7 @@ export type FactRetrieverRegistrationOptions = {
  *
  * Valid lifecycle values:
  * \{ ttl: \{ weeks: 2 \} \} -- This fact retriever will remove items that are older than 2 weeks when it is run
- * \{ itl: 7 \} -- This fact retriever will leave 7 newest items in the database when it is run
+ * \{ maxItems: 7 \} -- This fact retriever will leave 7 newest items in the database when it is run
  *
  */
 export function createFactRetrieverRegistration({

plugins/tech-insights-backend/src/service/persistence/TechInsightsDatabase.test.ts

@@ -290,7 +290,11 @@ describe('Tech Insights database', () => {
       },
     };
     const maxItems = 2;
-    await store.insertFacts('test-fact', [factToBeInserted], { maxItems });
+    await store.insertFacts({
+      id: 'test-fact',
+      facts: [factToBeInserted],
+      lifecycle: { maxItems },
+    });
 
     const afterInsertionFacts = await testDbClient('facts').select();
     expect(afterInsertionFacts).toHaveLength(maxItems);
@@ -334,8 +338,10 @@ describe('Tech Insights database', () => {
         testNumberFact: 555,
       },
     };
-    await store.insertFacts('test-fact', [factToBeInserted], {
-      timeToLive: { weeks: 2 },
+    await store.insertFacts({
+      id: 'test-fact',
+      facts: [factToBeInserted],
+      lifecycle: { timeToLive: { weeks: 2 } },
     });
 
     const afterInsertionFacts = await testDbClient('facts')

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

@@ -87,11 +87,15 @@ export class TechInsightsDatabase implements TechInsightsStore {
     }
   }
 
-  async insertFacts(
-    id: string,
-    facts: TechInsightFact[],
-    lifecycle?: FactLifecycle,
-  ): Promise<void> {
+  async insertFacts({
+    id,
+    facts,
+    lifecycle,
+  }: {
+    id: string;
+    facts: TechInsightFact[];
+    lifecycle?: FactLifecycle;
+  }): Promise<void> {
     if (facts.length === 0) return;
     const currentSchema = await this.getLatestSchema(id);
     const factRows = facts.map(it => {

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

@@ -39,7 +39,7 @@ export interface FactCheckerFactory<
 }
 
 // @public
-export type FactLifecycle = TTL | ITL;
+export type FactLifecycle = TTL | MaxItems;
 
 // @public
 export interface FactRetriever {
@@ -88,8 +88,8 @@ export type FlatTechInsightFact = TechInsightFact & {
 };
 
 // @public
-export type ITL = {
-  itl: number;
+export type MaxItems = {
+  maxItems: number;
 };
 
 // @public
@@ -154,17 +154,21 @@ export interface TechInsightsStore {
     [factRef: string]: FlatTechInsightFact;
   }>;
   getLatestSchemas(ids?: string[]): Promise<FactSchema[]>;
-  insertFacts(
-    id: string,
-    facts: TechInsightFact[],
-    lifecycle?: FactLifecycle,
-  ): Promise<void>;
+  insertFacts({
+    id,
+    facts,
+    lifecycle,
+  }: {
+    id: string;
+    facts: TechInsightFact[];
+    lifecycle?: FactLifecycle;
+  }): Promise<void>;
   insertFactSchema(schemaDefinition: FactSchemaDefinition): Promise<void>;
 }
 
 // @public
 export type TTL = {
-  ttl: DurationLike;
+  timeToLive: DurationLike;
 };
 
 // (No @packageDocumentation comment for this package)

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

@@ -38,11 +38,15 @@ export interface TechInsightsStore {
    * @param facts - A collection of TechInsightFacts
    * @param lifecycle - (Optional) Fact lifecycle object indicating the expiration logic for these items
    */
-  insertFacts(
-    id: string,
-    facts: TechInsightFact[],
-    lifecycle?: FactLifecycle,
-  ): Promise<void>;
+  insertFacts({
+    id,
+    facts,
+    lifecycle,
+  }: {
+    id: string;
+    facts: TechInsightFact[];
+    lifecycle?: FactLifecycle;
+  }): Promise<void>;
 
   /**
    * @param ids - A collection of fact row identifiers