@teamscale/coverage-collector 0.1.0-beta.8 → 1.0.0-beta.4

package/dist/src/storage/DataStorage.d.ts

@@ -1,3 +1,4 @@
+import { CollectorOptions, ConfigurationParameters } from '@cqse/commons';
 import Logger from 'bunyan';
 /**
  * Lines covered for the specified file.
@@ -8,79 +9,62 @@ export type FileCoverage = {
     /** Lines covered */
     coveredLines: Set<number>;
 };
-/**
- * Storage interface for reading information.
- */
-export interface IReadableStorage {
+/** Specifier of a coverage target bucket */
+export type CoverageBucketSpecifier = {
     /**
-     * The list of projects the collector received coverage information for.
+     * The unique ID of the application the coverage is collected for.
      */
-    getProjects(): string[];
+    appId: string;
     /**
-     * Retrieve the projects' coverage by source file.
+     * The configuration that shall be used along with this application.
      */
-    getCoverageBySourceFile(project: string): IterableIterator<FileCoverage> | undefined;
+    configId?: string;
     /**
-     * Write the coverage to the specified file. A timestamp will be appended to the provided file path.
-     *
-     * @param coverageFolder - Full path of the file to write the coverage to.
-     * @param date - Date to use for the appended timestamp
-     *
-     * @return The number of lines written
+     * Concrete configuration option values to set.
      */
-    dumpToSimpleCoverageFile(coverageFolder: string, date: Date): [string, number];
-}
+    configOptions?: string;
+    /** The project's commit to contribute coverage for. Either a revision or a
+     * commit in the sense of branch+timestamp.
+     */
+    commit: string;
+};
 /**
- * Storage interface for writing information.
+ * Summary of the coverage dump that has been performed.
  */
-export interface IWriteableStorage {
-    /**
-     * Add coverage information to the storage.
-     *
-     * @param project - The project to add the information to.
-     * @param sourceFilePath - The file for that lines are covered.
-     * @param coveredOriginalLines - The covered lines.
-     */
-    putCoverage(project: string, sourceFilePath: string, coveredOriginalLines: number[]): void;
-    /**
-     * Signals that we have received coverage information
-     * for that no mapping based on sourcemaps was possible.
-     *
-     * @param project - The project to add the information to.
-     */
-    signalUnmappedCoverage(project: string): void;
-    /**
-     * Discard the coverage information that has been collected up to this point.
-     */
-    discardCollectedCoverage(): void;
-}
+export type DumpSummary = {
+    hadCoverageToDump: boolean;
+    details: CoverageDumpDetails[];
+};
 /**
- * Union of write and read interface.
+ * Details of a single dump (for a single application and commit).
  */
-export interface IDataStorage extends IReadableStorage, IWriteableStorage {
-}
+export type CoverageDumpDetails = {
+    appId: string;
+    commit: string;
+    simpleCoverageFileLines: number;
+    simpleCoverageFile: string;
+};
 /**
- * The coverage information received for one particular project.
+ * The coverage information received for one particular project/revision/application.
  */
-export declare class ProjectCoverage {
+export declare class CoverageBucket {
     /**
-     * The identifier of the project.
+     * The identifier of the application.
      */
-    private readonly projectId;
+    readonly appId: string;
     /**
-     * The coverage.
+     * The commit the coverage is reported for.
      */
-    private readonly coveredLinesByFile;
+    readonly commit: string;
     /**
-     * Constructor.
-     *
-     * @param projectId - The identifier of the project to collect the coverage for.
+     * The actual coverage.
      */
-    constructor(projectId: string);
+    private readonly coveredLinesByFile;
+    constructor(appId: string, commit: string);
     /**
      * Put coverage for a single line to the storage.
      *
-     * @param sourceFile - The file in that the line is covered.
+     * @param sourceFile - The file in which the line is covered.
      * @param line - The line number.
      */
     putLine(sourceFile: string, line: number): void;
@@ -88,41 +72,126 @@ export declare class ProjectCoverage {
      * Returns an iterator over the projects' coverage.
      */
     getCoverage(): IterableIterator<FileCoverage>;
+    /**
+     * Clears the coverage of the bucket.
+     */
+    clear(): void;
 }
+type AppId = string;
+type ConfigId = string;
+/**
+ * Callbacks called before a new configuration will take effect, that is,
+ * with the old config still active.
+ */
+export type BeforeConfigUpdateCallback = (appId: string, dataStorage: DataStorage) => Promise<void>;
 /**
  * The data storage which retrieves coverage information.
  */
-export declare class DataStorage implements IDataStorage {
+export declare class DataStorage {
+    /**
+     * The different coverage buckets, identified by a bucket key.
+     */
+    private coverageBuckets;
+    /**
+     * Configuration per application.
+     */
+    private readonly configPerApp;
     /**
-     * Coverage information by project.
+     * Which configurations (their hashes) have already been validated? We store the hash of the validated config on the right.
      */
-    private coverageByProject;
+    private readonly validatedPerApp;
+    /**
+     * Configuration ID per application (key: app id, value: config id).
+     */
+    private readonly configIdPerApp;
     /**
      * Logger to use.
      */
     private readonly logger;
     /**
-     * Times unmapped coverage received.
+     * Base configuration to use.
      */
-    private timesUnmappedCoverage;
+    private readonly baseConfig;
     /**
      * Date format for the timestamp appended to the coverage files
      */
-    readonly DATE_FORMAT = "YYYY-MM-DD-HH-mm-ss.SSS";
+    readonly DATE_FORMAT = "YYYY-MM-DD-HH-mm-ss";
+    /**
+     * The configuration parameters the collector can be configured with.
+     */
+    private readonly reconfigurableParameters;
+    /**
+     * All configuration parameters the collector can be configured with.
+     */
+    private readonly allParameters;
+    /**
+     * Callbacks registered to be invoked before a new configuration will take effect.
+     */
+    private readonly beforeConfigUpdateCallbacks;
     /**
      * Constructs the data storage.
      *
      * @param logger - The logger to use.
+     * @param allParameters - The description of all available configuration parameters.
+     * @param reconfigurableParameters - The description of the reconfigurable configuration parameters.
+     * @param baseConfig - The configuration that has initially been done via the command line.
+     */
+    constructor(logger: Logger, allParameters: ConfigurationParameters, reconfigurableParameters: ConfigurationParameters, baseConfig: CollectorOptions);
+    /**
+     * Create a coverage bucket as specified by the given `bucketSpecifier`; if it already exists,
+     * keep the existing one. Retrieve the configuration from Teamscale if a config ID is supplied with the bucket specifier.
+     */
+    setupCoverageBucket(bucketSpecifier: CoverageBucketSpecifier): Promise<void>;
+    /**
+     * Change the configuration (id) for the given app.
+     * <p>
+     * If the given app ID has not yet assigned a configuration ID
+     * or if it is different, then fetch the configuration from Teamscale and assign it to the application.
+     */
+    changeAppConfiguration(appId: AppId, configId: ConfigId): Promise<void>;
+    /**
+     * For all applications, re-fetch the remote configuration, if set.
+     * The configuration cache in `RemoteProfilerConfig.ts` ensures that we do not make
+     * the fetch repeatedly if the same config id is assigned to different applications.
+     */
+    refreshAllRemoteConfigurations(): Promise<void>;
+    /**
+     * Re-retrieve the configuration from Teamscale for the given application and configuration ID.
      */
-    constructor(logger: Logger);
+    refreshApplicationConfiguration(appId: string, newConfigId?: string): Promise<void>;
+    private getOrCreateAppConfig;
+    private setConfigurationParameter;
+    /**
+     * Check the configuration for its validity. If invalid, report it (if not already
+     * done in this run of the collector).
+     */
+    private validateConfiguration;
+    /**
+     * Returns the collector configuration with overrides for the given app ID.
+     */
+    getAppConfiguration(appId: string): CollectorOptions;
+    /**
+     * Return the bucket which is defined by the given bucket specifier.
+     * Creates a new one if it does not yet exist.
+     */
+    private getBucketFor;
+    /**
+     * For testing: Get the bucket of the given application and commit.
+     */
+    getBucket(appId: string, commit: string): CoverageBucket | undefined;
+    /**
+     * Gets all coverage buckets with the given appId. If now appId is given, all buckets will be returned.
+     */
+    private getAppBuckets;
     /**
      * Put coverage into the storage.
      *
-     * @param project - The project to add it to.
+     * @param appId - The ID of the application to add coverage for.
+     * @param commit - The target commit (or revision) to add coverage for.
      * @param sourceFilePath - The covered file.
      * @param coveredOriginalLines - The lines covered in the file.
      */
-    putCoverage(project: string, sourceFilePath: string, coveredOriginalLines: number[]): void;
+    putCoverage(appId: string, commit: string, sourceFilePath: string, coveredOriginalLines: number[]): void;
     /**
      * Normalize the source file names provided by the Web browsers / from the
      * instrumentation such that they can be matched to the original source code by Teamscale.
@@ -131,39 +200,43 @@ export declare class DataStorage implements IDataStorage {
      */
     private static normalizeSourceFileName;
     /**
-     * {@inheritDoc IWriteableStorage.signalUnmappedCoverage}
+     * Dump coverage to the given coverage folder. Either for a specified application only,
+     * or if not given, for all applications.
      */
-    signalUnmappedCoverage(project: string): void;
+    dumpToSimpleCoverageFile(coverageFolder: string, date: Date, dumpForAppIdOnly?: string): DumpSummary;
     /**
-     * {@inheritDoc IReadableStorage.getCoverageBySourceFile}
+     * Set the collected coverage to 0 for all buckets of the given application.
      */
-    getCoverageBySourceFile(project: string): IterableIterator<FileCoverage> | undefined;
+    private resetCoverage;
     /**
-     * @inheritDoc
+     * Appends the timestamp given with date to the coverageFolder (before the file ending if there is one).
+     *
+     * @param coverageFolder - Path to the coverage file
+     * @param date - Represents the timestamp to be appended with the format {@link DataStorage.DATE_FORMAT}
+     * @param commit - The commit to report coverage for.
+     * @param appId - The id of the application to dump coverage for.
      */
-    dumpToSimpleCoverageFile(coverageFolder: string, date: Date): [string, number];
+    private prepareValidCoverageFileName;
     /**
-     * Set the collected coverage to 0 for all projects
-     * @private
+     * Generate file contents in the Simple Coverage Format for the collected coverage.
+     * The resulting map contains one entry for each commit.
      */
-    private resetCoverage;
+    private toSimpleCoverage;
     /**
-     * Appends the timestamp given with date to the coverageFolder (before the file ending if there is one)
-     * @param coverageFolder Path to the coverage file
-     * @param date Represents the timestamp to be appended with the format {@link DataStorage.DATE_FORMAT}
-     * @private
+     * Returns the applications that are known to us.
      */
-    private initCoverageFile;
+    getApplicationIDs(): Set<AppId>;
     /**
-     * Generate simple coverage format for the collected coverage
+     * Returns all app IDs that are configured with the given config ID.
      */
-    private toSimpleCoverage;
+    getApplicationsWithConfig(configId: string): Set<AppId>;
     /**
-     * {@inheritDoc IReadableStorage.getProjects}
+     * Discard the coverage information that has been collected up to this point.
      */
-    getProjects(): string[];
+    discardCollectedCoverage(appId?: AppId): void;
     /**
-     * {@inheritDoc IWritableStorage.discardCollectedCoverage}
+     * Add a before-config-update callback.
      */
-    discardCollectedCoverage(): void;
+    addBeforeConfigUpdateCallback(callback: BeforeConfigUpdateCallback): void;
 }
+export {};