Modifications after PR review
* Change entity filter to be an actual entity filter instead of a list of kinds or types * Modify/simplify types a little bit * Split common type libs to one for node and one isomorphic * Remove unnecessary items from FactChecker interface to simplify execution loop. Needs still matching README.md changes. Signed-off-by: Jussi Hallila <jussi@hallila.com>
This commit is contained in:
Jussi Hallila
@@ -0,0 +1,153 @@
|
||||
/*
|
||||
* Copyright 2021 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 { TechInsightsStore } from './persistence';
|
||||
import { CheckResult } from '@backstage/plugin-tech-insights-common';
|
||||
|
||||
/**
|
||||
* A factory wrapper to construct FactChecker implementations.
|
||||
*
|
||||
* @public
|
||||
* @typeParam CheckType - Implementation specific Check. Can extend TechInsightCheck with additional information
|
||||
* @typeParam CheckResultType - Implementation specific result of a check. Can extend CheckResult with additional information
|
||||
*/
|
||||
export interface FactCheckerFactory<
|
||||
CheckType extends TechInsightCheck,
|
||||
CheckResultType extends CheckResult,
|
||||
> {
|
||||
/**
|
||||
* @param repository - TechInsightsStore
|
||||
* @returns an implementation of a FactChecker for generic types defined in the factory
|
||||
*/
|
||||
construct(
|
||||
repository: TechInsightsStore,
|
||||
): FactChecker<CheckType, CheckResultType>;
|
||||
}
|
||||
|
||||
/**
|
||||
* FactChecker interface
|
||||
*
|
||||
* A generic interface that can be implemented to create checkers for specific check and check return types.
|
||||
* This is used especially when creating Scorecards and displaying results of rules when run against facts.
|
||||
*
|
||||
* @public
|
||||
* @typeParam CheckType - Implementation specific Check. Can extend TechInsightCheck with additional information
|
||||
* @typeParam CheckResultType - Implementation specific result of a check. Can extend CheckResult with additional information
|
||||
*/
|
||||
export interface FactChecker<
|
||||
CheckType extends TechInsightCheck,
|
||||
CheckResultType extends CheckResult,
|
||||
> {
|
||||
/**
|
||||
* Runs checks against an entity.
|
||||
*
|
||||
* @param entity - A reference to an entity to run checks against. In a format namespace/kind/name
|
||||
* @param checks - A collection of checks to run against provided entity
|
||||
* @returns - A collection containing check/fact information and the actual results of the check
|
||||
*/
|
||||
runChecks(entity: string, checks?: string[]): Promise<CheckResultType[]>;
|
||||
|
||||
/**
|
||||
* Retrieves all available checks that can be used to run checks against.
|
||||
* The implementation can be just a piping through to CheckRegistry implementation if such is in use.
|
||||
*
|
||||
* @returns - A collection of checks
|
||||
*/
|
||||
getChecks(): Promise<CheckType[]>;
|
||||
|
||||
/**
|
||||
* Validates if check is valid and can be run with the current implementation
|
||||
*
|
||||
* @param check - The check to be validated
|
||||
* @returns - Validation result
|
||||
*/
|
||||
validate(check: CheckType): Promise<CheckValidationResponse>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Registry containing checks for tech insights.
|
||||
*
|
||||
* @public
|
||||
* @typeParam CheckType - Implementation specific Check. Can extend TechInsightCheck with additional information
|
||||
*
|
||||
*/
|
||||
export interface TechInsightCheckRegistry<CheckType extends TechInsightCheck> {
|
||||
register(check: CheckType): Promise<CheckType>;
|
||||
get(checkId: string): Promise<CheckType>;
|
||||
getAll(checks: string[]): Promise<CheckType[]>;
|
||||
list(): Promise<CheckType[]>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generic definition of a check for Tech Insights
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export interface TechInsightCheck {
|
||||
/**
|
||||
* Unique identifier of the check
|
||||
*
|
||||
* Used to identify which checks to use when running checks.
|
||||
*/
|
||||
id: string;
|
||||
|
||||
/**
|
||||
* Type identifier for the check.
|
||||
* Can be used to determine storage options, logical routing to correct FactChecker implementation
|
||||
* or to help frontend render correct component types based on this
|
||||
*/
|
||||
type: string;
|
||||
|
||||
/**
|
||||
* Human readable name of the check, may be displayed in the UI
|
||||
*/
|
||||
name: string;
|
||||
|
||||
/**
|
||||
* Human readable description of the check, may be displayed in the UI
|
||||
*/
|
||||
description: string;
|
||||
|
||||
/**
|
||||
* A collection of string referencing fact rows that a check will be run against.
|
||||
*
|
||||
* References the fact container, aka fact retriever itself which may or may not contain multiple individual facts and values
|
||||
*/
|
||||
factIds: string[];
|
||||
|
||||
/**
|
||||
* Metadata to be returned in case a check has been successfully evaluated
|
||||
* Can contain links, description texts or other actionable items
|
||||
*/
|
||||
successMetadata?: Record<string, any>;
|
||||
|
||||
/**
|
||||
* Metadata to be returned in case a check evaluation has ended in failure
|
||||
* Can contain links, description texts or other actionable items
|
||||
*/
|
||||
failureMetadata?: Record<string, any>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Validation response from CheckValidator
|
||||
*
|
||||
* May contain additional data for display purposes
|
||||
* @public
|
||||
*/
|
||||
export type CheckValidationResponse = {
|
||||
valid: boolean;
|
||||
message?: string;
|
||||
errors?: unknown[];
|
||||
};
|
||||
@@ -0,0 +1,210 @@
|
||||
/*
|
||||
* Copyright 2021 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 { DateTime } from 'luxon';
|
||||
import { Config } from '@backstage/config';
|
||||
import { PluginEndpointDiscovery } from '@backstage/backend-common';
|
||||
import { Logger } from 'winston';
|
||||
|
||||
/**
|
||||
* A container for facts. The shape of the fact records needs to correspond to the FactSchema with same `ref` value.
|
||||
* Each container contains a reference to an entity which can be a Backstage entity or a generic construct
|
||||
* outside of backstage with same shape.
|
||||
*
|
||||
* Container may contain multiple individual facts and their values
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export type TechInsightFact = {
|
||||
/**
|
||||
* Entity reference that this fact relates to
|
||||
*/
|
||||
entity: {
|
||||
namespace: string;
|
||||
kind: string;
|
||||
name: string;
|
||||
};
|
||||
|
||||
/**
|
||||
* A collection of fact values as key value pairs.
|
||||
*
|
||||
* Key indicates fact name as it is defined in FactSchema
|
||||
*/
|
||||
facts: Record<
|
||||
string,
|
||||
| number
|
||||
| string
|
||||
| boolean
|
||||
| DateTime
|
||||
| number[]
|
||||
| string[]
|
||||
| boolean[]
|
||||
| DateTime[]
|
||||
>;
|
||||
|
||||
/**
|
||||
* Optional timestamp value which can be used to override retrieval time of the fact row.
|
||||
* Otherwise when stored into data storage, defaults to current time
|
||||
*/
|
||||
timestamp?: DateTime;
|
||||
};
|
||||
|
||||
/**
|
||||
|
||||
* Response type used when returning from database and API.
|
||||
* Adds a field for ref for easier usage
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export type FlatTechInsightFact = TechInsightFact & {
|
||||
/**
|
||||
* Reference and unique identifier of the fact row
|
||||
*/
|
||||
id: string;
|
||||
};
|
||||
|
||||
/**
|
||||
* @public
|
||||
*
|
||||
* A record type to specify individual fact shapes
|
||||
*
|
||||
* Used as part of a schema to validate, identify and generically construct usage implementations
|
||||
* of individual fact values in the system.
|
||||
*/
|
||||
export type FactSchema = {
|
||||
/**
|
||||
* Name of the fact
|
||||
*/
|
||||
[name: string]: {
|
||||
/**
|
||||
* Type of the individual fact value
|
||||
*
|
||||
* Numbers are split into integers and floating point values.
|
||||
* `set` indicates a collection of values
|
||||
*/
|
||||
type: 'integer' | 'float' | 'string' | 'boolean' | 'datetime' | 'set';
|
||||
|
||||
/**
|
||||
* A description of this individual fact value
|
||||
*/
|
||||
description: string;
|
||||
|
||||
/**
|
||||
* Optional semver string to indicate when this specific fact definition was added to the schema
|
||||
*/
|
||||
since?: string;
|
||||
|
||||
/**
|
||||
* Metadata related to an individual fact.
|
||||
* Can contain links, additional description texts and other actionable data.
|
||||
*
|
||||
* Currently loosely typed, but in the future when patterns emerge, key shapes can be defined
|
||||
*
|
||||
* examples:
|
||||
* ```
|
||||
* \{
|
||||
* link: 'https://sonarqube.mycompany.com/fix-these-issues',
|
||||
* suggestion: 'To affect this value, you can do x, y, z',
|
||||
* minValue: 0
|
||||
* \}
|
||||
* ```
|
||||
*/
|
||||
metadata?: Record<string, any>;
|
||||
};
|
||||
};
|
||||
|
||||
/**
|
||||
* @public
|
||||
*
|
||||
* FactRetrieverContext injected into individual handler methods of FactRetriever implementations.
|
||||
* The context can be used to construct logic to retrieve entities, contact integration points
|
||||
* and fetch and calculate fact values from external sources.
|
||||
*/
|
||||
export type FactRetrieverContext = {
|
||||
config: Config;
|
||||
discovery: PluginEndpointDiscovery;
|
||||
logger: Logger;
|
||||
};
|
||||
|
||||
/**
|
||||
* @public
|
||||
*
|
||||
* FactRetriever interface
|
||||
*
|
||||
* A component specifying
|
||||
*/
|
||||
export interface FactRetriever {
|
||||
/**
|
||||
* A unique identifier of the retriever.
|
||||
* Used to identify and store individual facts returned from this retriever
|
||||
* and schemas defined by this retriever.
|
||||
*/
|
||||
id: string;
|
||||
|
||||
/**
|
||||
* Semver string indicating the version of this fact retriever
|
||||
* This version is used to determine if the schema this fact retriever matches the data this fact retriever provides.
|
||||
*
|
||||
* Should be incremented on changes to returned data from the handler or if the schema changes.
|
||||
*/
|
||||
version: string;
|
||||
|
||||
/**
|
||||
* Handler function that needs to be implemented to retrieve fact values for entities.
|
||||
*
|
||||
* @param ctx - FactRetrieverContext which can be used to retrieve config and contact integrations
|
||||
* @returns - A collection of TechInsightFacts grouped by entities.
|
||||
*/
|
||||
handler: (ctx: FactRetrieverContext) => Promise<TechInsightFact[]>;
|
||||
|
||||
/**
|
||||
* A fact schema defining the shape of data returned from the handler method for each entity
|
||||
*/
|
||||
schema: FactSchema;
|
||||
|
||||
/**
|
||||
* An optional object/array of objects of entity filters to indicate if this fact retriever is valid for an entity type.
|
||||
* If omitted, the retriever should apply to all entities.
|
||||
*
|
||||
* Should be defined for example:
|
||||
* { field: 'kind', values: ['component'] }
|
||||
* { field: 'metadata.name', values: ['component-1', 'component-2'] }
|
||||
*/
|
||||
entityFilter?:
|
||||
| Record<string, string | symbol | (string | symbol)[]>[]
|
||||
| Record<string, string | symbol | (string | symbol)[]>;
|
||||
}
|
||||
|
||||
export type FactSchemaDefinition = Omit<FactRetriever, 'handler'>;
|
||||
|
||||
/**
|
||||
* @public
|
||||
*
|
||||
* Registration of a fact retriever
|
||||
* Used to add and schedule individual fact retrievers to the fact retriever engine.
|
||||
*/
|
||||
export type FactRetrieverRegistration = {
|
||||
/**
|
||||
* Actual FactRetriever implementation
|
||||
*/
|
||||
factRetriever: FactRetriever;
|
||||
|
||||
/**
|
||||
* Cron expression to indicate when the retriever should be triggered.
|
||||
* Defaults to a random point in time every 24h
|
||||
*
|
||||
*/
|
||||
cadence?: string;
|
||||
};
|
||||
@@ -0,0 +1,24 @@
|
||||
/*
|
||||
* Copyright 2021 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 * as anything from './';
|
||||
|
||||
describe('tech-insights-node', () => {
|
||||
// Types only
|
||||
it('should exist', () => {
|
||||
expect(anything).toBeTruthy();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,19 @@
|
||||
/*
|
||||
* Copyright 2021 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.
|
||||
*/
|
||||
|
||||
export * from './checks';
|
||||
export * from './facts';
|
||||
export * from './persistence';
|
||||
@@ -0,0 +1,83 @@
|
||||
/*
|
||||
* Copyright 2021 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 {
|
||||
FactSchema,
|
||||
TechInsightFact,
|
||||
FlatTechInsightFact,
|
||||
FactSchemaDefinition,
|
||||
} from './facts';
|
||||
import { DateTime } from 'luxon';
|
||||
|
||||
/**
|
||||
* TechInsights Database
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export interface TechInsightsStore {
|
||||
/**
|
||||
* Stores fact containers as rows into data store.
|
||||
* Individual items in array correspond to a fact schema based on reference and entity based on entity identifier.
|
||||
*
|
||||
* Each row may contain multiple individual facts and values
|
||||
*
|
||||
* @param id - Unique identifier of the fact retriever these facts relate to
|
||||
* @param facts - A collection of TechInsightFacts
|
||||
*/
|
||||
insertFacts(id: string, facts: TechInsightFact[]): Promise<void>;
|
||||
|
||||
/**
|
||||
* @param ids - A collection of fact row identifiers
|
||||
* @param entity - A string identifying an entity. In a format namespace/kind/name
|
||||
*
|
||||
* @returns - An object keyed by a fact reference and containing an individual TechInsightFact
|
||||
*/
|
||||
getLatestFactsByIds(
|
||||
ids: string[],
|
||||
entity: string,
|
||||
): Promise<{ [factRef: string]: FlatTechInsightFact }>;
|
||||
|
||||
/**
|
||||
* Retrieves fact values identified by fact row references for an individual entity.
|
||||
*
|
||||
* @param ids - A collection of fact row identifiers
|
||||
* @param entity - A string identifying an entity. In a format namespace/kind/name
|
||||
* @param startDateTime - DateTime object indicating start of the time frame
|
||||
* @param endDateTime - DateTime object indicating start of the time frame
|
||||
*
|
||||
* @returns - An object keyed by a fact reference and containing a collection of TechInsightFacts matching the time frame
|
||||
*/
|
||||
getFactsBetweenTimestampsByIds(
|
||||
ids: string[],
|
||||
entity: string,
|
||||
startDateTime: DateTime,
|
||||
endDateTime: DateTime,
|
||||
): Promise<{ [factRef: string]: FlatTechInsightFact[] }>;
|
||||
|
||||
/**
|
||||
* Stores versioned fact schemas into data store
|
||||
*
|
||||
* @param schemaDefinition - FactSchemaDefinition containing id, version, schema and entityTypes.
|
||||
*/
|
||||
insertFactSchema(schemaDefinition: FactSchemaDefinition): Promise<void>;
|
||||
|
||||
/**
|
||||
* Retrieves latest versions (as defined by semver) of fact schemas from the data store.
|
||||
*
|
||||
* @param ids - Collection of ids to return. If omitted, all Schemas should be returned.
|
||||
* @returns - A collection of schemas
|
||||
*/
|
||||
getLatestSchemas(ids?: string[]): Promise<FactSchema[]>;
|
||||
}
|
||||
@@ -0,0 +1,17 @@
|
||||
/*
|
||||
* Copyright 2021 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.
|
||||
*/
|
||||
|
||||
export {};
|
||||
Reference in New Issue
Block a user