@cqse/commons 0.1.0-beta.8 → 1.0.0-beta.4

package/lib/CollectorConfig.d.ts

@@ -0,0 +1,61 @@
+import { ConfigurationParameters } from './ConfigParser';
+export type PredefinableOptions = {
+    keepCoverageFiles: boolean;
+    dumpAfterMins: number;
+    artifactoryServerUrl?: string;
+    artifactoryUser?: string;
+    artifactoryPassword?: string;
+    artifactoryAccessToken?: string;
+    artifactoryPathSuffix?: string;
+};
+/**
+ * Options that cannot be reconfigured during runtime.
+ * These settings are fixed after initial configuration.
+ */
+export type StaticCollectorOptions = PredefinableOptions & {
+    port: number;
+    dumpFolder: string;
+    httpProxy?: string;
+    logLevel: string;
+    logToFile: string;
+    jsonLog: boolean;
+    enableControlPort?: number;
+    teamscaleServerUrl?: string;
+    teamscaleUser?: string;
+    teamscaleAccessToken?: string;
+};
+/**
+ * Options that can be modified during runtime.
+ * These settings control various aspects of the collector's behavior.
+ *
+ * See the other code in the present file for a list of all available
+ * options and their descriptions and default values.
+ */
+export type ReconfigurableCollectorOptions = PredefinableOptions & {
+    teamscaleProject?: string;
+    teamscalePartition?: string;
+    teamscaleRepository?: string;
+    teamscaleMessage?: string;
+    dumpToFolder?: string;
+};
+/**
+ * Complete collection of collector configuration options.
+ * Combines both fixed and reconfigurable options into a single type.
+ */
+export type CollectorOptions = StaticCollectorOptions & ReconfigurableCollectorOptions;
+/**
+ * Build the collector parameters that can be overwritten by instrumented apps.
+ */
+export declare function buildPredefinableParameters(): ConfigurationParameters;
+/**
+ * Builds and returns the configuration parameters for the collector.
+ * This includes all available command line arguments and their default values.
+ *
+ * @returns {ConfigurationParameters} Configuration parameters instance with all defined options
+ */
+export declare function buildStaticCollectorParameters(): ConfigurationParameters;
+/**
+ * Builds and returns the during run-time reconfigurable configuration parameters for the collector.
+ */
+export declare function buildReconfigurableCollectorParameters(): ConfigurationParameters;
+//# sourceMappingURL=CollectorConfig.d.ts.map

package/lib/CollectorConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CollectorConfig.d.ts","sourceRoot":"","sources":["../src/CollectorConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,uBAAuB,EACvB,MAAM,gBAAgB,CAAC;AAGxB,MAAM,MAAM,mBAAmB,GAAG;IACjC,iBAAiB,EAAE,OAAO,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,mBAAmB,GAAG;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,8BAA8B,GAAG,mBAAmB,GAAG;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,sBAAsB,GAAG,8BAA8B,CAAC;AAsCvF;;GAEG;AACH,wBAAgB,2BAA2B,IAAI,uBAAuB,CA0CrE;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,IAAI,uBAAuB,CAkDxE;AAED;;GAEG;AACH,wBAAgB,sCAAsC,IAAI,uBAAuB,CAuChF"}

package/lib/CollectorConfig.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPredefinableParameters = buildPredefinableParameters;
+exports.buildStaticCollectorParameters = buildStaticCollectorParameters;
+exports.buildReconfigurableCollectorParameters = buildReconfigurableCollectorParameters;
+const ConfigParser_1 = require("./ConfigParser");
+const CONFIG_GROUP_COLLECTOR_CONNECTIVITY = {
+    order: 1,
+    title: 'Collector Connectivity'
+};
+const CONFIG_GROUP_TEAMSCALE_SERVER = {
+    order: 1,
+    title: 'Teamscale Server'
+};
+const CONFIG_GROUP_TEAMSCALE_UPLOAD = {
+    order: 2,
+    title: 'Upload to Teamscale'
+};
+const CONFIG_GROUP_COVERAGE_DUMP = {
+    order: 3,
+    title: 'Coverage Dumping'
+};
+const CONFIG_GROUP_ARTIFACTORY_UPLOAD = {
+    order: 4,
+    title: 'Upload to Artifactory'
+};
+const CONFIG_GROUP_LOGGING = {
+    order: 5,
+    title: 'Logging Behavior'
+};
+/**
+ * Build the collector parameters that can be overwritten by instrumented apps.
+ */
+function buildPredefinableParameters() {
+    const parameters = new ConfigParser_1.ConfigurationParameters();
+    function add(shortParameter, longParameter, type, options) {
+        parameters.addParameter(shortParameter, longParameter, type, options);
+    }
+    add('-k', '--keep-coverage-files', 'bool', {
+        help: 'Whether to keep the coverage files on disk after a successful upload to Teamscale.',
+        default: false,
+        group: CONFIG_GROUP_COVERAGE_DUMP
+    });
+    add('-t', '--dump-after-mins', 'int', {
+        help: 'Dump the coverage information every N minutes.',
+        default: 120,
+        group: CONFIG_GROUP_COVERAGE_DUMP
+    });
+    // Artifactory upload
+    add(undefined, '--artifactory-server-url', 'string', {
+        help: 'Upload the coverage to the given Artifactory server URL. The URL may include a subpath on the artifactory server, e.g. https://artifactory.acme.com/my-repo/my/subpath',
+        group: CONFIG_GROUP_ARTIFACTORY_UPLOAD
+    });
+    add(undefined, '--artifactory-user', 'string', {
+        help: 'The user for uploading coverage to Artifactory. Only needed when not using the --artifactory-access-token option',
+        group: CONFIG_GROUP_ARTIFACTORY_UPLOAD
+    });
+    add(undefined, '--artifactory-password', 'string', {
+        help: 'The password for uploading coverage to Artifactory. Only needed when not using the --artifactory-access-token option',
+        group: CONFIG_GROUP_ARTIFACTORY_UPLOAD
+    });
+    add(undefined, '--artifactory-access-token', 'string', {
+        help: 'The access_token for uploading coverage to Artifactory.',
+        group: CONFIG_GROUP_ARTIFACTORY_UPLOAD
+    });
+    add(undefined, '--artifactory-path-suffix', 'string', {
+        help: '(optional): The path within the storage location between the default path and the uploaded artifact.',
+        group: CONFIG_GROUP_ARTIFACTORY_UPLOAD
+    });
+    return parameters;
+}
+/**
+ * Builds and returns the configuration parameters for the collector.
+ * This includes all available command line arguments and their default values.
+ *
+ * @returns {ConfigurationParameters} Configuration parameters instance with all defined options
+ */
+function buildStaticCollectorParameters() {
+    const parameters = buildPredefinableParameters();
+    function add(shortParameter, longParameter, type, options) {
+        parameters.addParameter(shortParameter, longParameter, type, options);
+    }
+    add('-p', '--port', 'int', { help: 'The port to receive coverage information on.',
+        default: 54678, group: CONFIG_GROUP_COLLECTOR_CONNECTIVITY, disableEnvironmentVariableOverride: true });
+    add('-l', '--log-to-file', 'string', { help: 'Log file', default: 'logs/collector-combined.log', group: CONFIG_GROUP_LOGGING,
+        disableEnvironmentVariableOverride: true });
+    add('-e', '--log-level', 'string', { help: 'Log level',
+        default: 'info', group: CONFIG_GROUP_LOGGING, disableEnvironmentVariableOverride: true });
+    add('-j', '--json-log', 'bool', { help: 'Additional JSON-like log file format.',
+        group: CONFIG_GROUP_LOGGING, disableEnvironmentVariableOverride: true });
+    add('-c', '--enable-control-port', 'int', {
+        help: 'Enables the remote control API on the specified port (<=0 means "disabled").',
+        default: 0, group: CONFIG_GROUP_COLLECTOR_CONNECTIVITY
+    });
+    add('-s', '--teamscale-server-url', 'string', {
+        help: 'Upload the coverage to the given Teamscale server URL, for example, https://teamscale.dev.example.com:8080/production.',
+        group: CONFIG_GROUP_TEAMSCALE_SERVER
+    });
+    add('-u', '--teamscale-user', 'string', {
+        help: 'The user for uploading coverage to Teamscale.',
+        group: CONFIG_GROUP_TEAMSCALE_SERVER
+    });
+    add('-a', '--teamscale-access-token', 'string', {
+        help: 'The API key to use for uploading to Teamscale.',
+        group: CONFIG_GROUP_TEAMSCALE_SERVER
+    });
+    add(undefined, '--http-proxy', 'string', {
+        help: '(optional): The HTTP/HTTPS proxy address that should be used in the format: http://host:port/ or http://username:password@host:port/.',
+        group: CONFIG_GROUP_COLLECTOR_CONNECTIVITY,
+    });
+    add('-f', '--dump-folder', 'string', {
+        help: 'Target folder for coverage files.',
+        default: './coverage',
+        group: CONFIG_GROUP_COVERAGE_DUMP
+    });
+    parameters.addArgumentCheck((options) => {
+        if (options.teamscaleServerUrl) {
+            if (!options.teamscaleUser || !options.teamscaleAccessToken) {
+                return 'The Teamscale user name and access token must be given if the Teamscale server URL is given.';
+            }
+        }
+    });
+    return parameters;
+}
+/**
+ * Builds and returns the during run-time reconfigurable configuration parameters for the collector.
+ */
+function buildReconfigurableCollectorParameters() {
+    const parameters = buildPredefinableParameters();
+    function addShort(shortParameter, longParameter, type, options) {
+        parameters.addParameter(shortParameter, longParameter, type, options);
+    }
+    function add(longArgument, type, options) {
+        addShort(undefined, longArgument, type, options);
+    }
+    // Coverage dumping
+    add('--dump-to-folder', 'string', {
+        help: 'Coverage should be dumped to a folder on the server that the collector is running on.\n' +
+            'Specifies the name of the subfolder within the collector\'s dump folder (--dump-folder of the collector) where coverage files should be placed.',
+        group: CONFIG_GROUP_COVERAGE_DUMP
+    });
+    // Upload to Teamscale
+    add('--teamscale-project', 'string', {
+        help: 'The project ID to upload coverage to.',
+        group: CONFIG_GROUP_TEAMSCALE_UPLOAD
+    });
+    add('--teamscale-partition', 'string', {
+        help: 'The partition to upload coverage to.',
+        group: CONFIG_GROUP_TEAMSCALE_UPLOAD
+    });
+    add('--teamscale-repository', 'string', {
+        help: 'The repository to upload coverage for. Optional: Only needed when uploading via revision to a project that has more than one connector.',
+        group: CONFIG_GROUP_TEAMSCALE_UPLOAD
+    });
+    add('--teamscale-message', 'string', {
+        help: 'The commit message shown within Teamscale for the coverage upload.',
+        default: 'JavaScript coverage upload',
+        group: CONFIG_GROUP_TEAMSCALE_UPLOAD
+    });
+    return parameters;
+}
+//# sourceMappingURL=CollectorConfig.js.map

package/lib/CollectorConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CollectorConfig.js","sourceRoot":"","sources":["../src/CollectorConfig.ts"],"names":[],"mappings":"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"}

package/lib/ConfigParser.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Configuration parser module that handles command-line arguments, environment variables,
+ * and configuration files for TypeScript/JavaScript applications.
+ *
+ * @module ConfigParser
+ */
+/** Supported parameter types for configuration options */
+export type ConfigParameterType = 'string' | 'int' | 'bool' | 'string[]';
+/** Possible value types for configuration parameters */
+export type ConfigValueType = string | number | boolean | string[];
+/** Record of parameter names to their values */
+export type Options = Record<string, ConfigValueType>;
+/** Options for printing the version and help information */
+export type VersionAndHelpOptions = {
+    version: boolean;
+    help: boolean;
+};
+/** Result of parsing the configuration containing options and unnamed arguments */
+export type ConfigParsingResult = {
+    options: Options;
+    unnamedArguments: string[];
+};
+/** Describes the application that is going to be configured and run. */
+export type AppInfos = {
+    name: string;
+    version: string;
+    about: string;
+};
+/** Defines a group of configuration parameters. */
+export type ParameterGroup = {
+    /** Number used as the primary criterion for ordering */
+    order: number;
+    /** Title of the group */
+    title: string;
+};
+/** Parameter group for --version and --help */
+export declare const CONFIG_GROUP_APP: ParameterGroup;
+/** Describes a configuration parameter with its properties */
+export type ParameterDescriptor = {
+    /** Internal identifier for the parameter */
+    parameterId: string;
+    /** Short form of the parameter (e.g., -p) */
+    shortParameter?: string;
+    /** Long form of the parameter (e.g., --port) */
+    longParameter: string;
+    /** Environment variable name for this parameter */
+    environmentVariableName: string;
+    /** Disable overwriting the parameter value via an environment variable? */
+    disableEnvironmentVariableOverride?: boolean;
+    /** Parameter's data type */
+    type: ConfigParameterType;
+    /** Default value if parameter is not specified */
+    default?: ConfigValueType;
+    /** Help text describing the parameter */
+    help: string;
+    /**
+     * Is it an internal parameter, not to be visible in the command line by default?
+     * An example is a parameter that is configured via a different mechanism but still
+     * shall be present in the configuration mechanism at hand.
+     */
+    internal: boolean;
+    /** Parameter group it belongs to. */
+    group?: ParameterGroup;
+};
+/**
+ * See `ParameterDescriptor`.
+ */
+export type ParameterDefinitionOptions = Partial<ParameterDescriptor>;
+/**
+ * Converts a parameter name (with dashes) to a camelCase parameter ID.
+ *
+ * @param parameterName - The parameter name to convert (e.g., --my-param)
+ * @returns The camelCase parameter ID (e.g., myParam)
+ */
+export declare function parameterNameToParameterId(parameterName: string): string;
+/**
+ * Converts a long parameter name to an environment variable name.
+ *
+ * @param longParameter - The long parameter name (e.g., --my-param)
+ * @returns The environment variable name (e.g., MY_PARAM)
+ */
+export declare function longParameterToEnvironmentVariableName(longParameter: string): string;
+/**
+ * Manages configuration parameters and their properties.
+ * Provides functionality to add, describe, and parse parameters.
+ */
+export declare class ConfigurationParameters {
+    private readonly parameters;
+    private readonly shortToLongParameterMap;
+    private readonly sequentialParameters;
+    private readonly argumentChecks;
+    constructor();
+    /**
+     * Adds a new parameter to the configuration.
+     *
+     * @param shortParameter - Optional short form of the parameter (e.g., -p)
+     * @param longParameter - Long form of the parameter (e.g., --port)
+     * @param type - Parameter's data type
+     * @param options - Additional parameter options including a help text and default value
+     */
+    addParameter(shortParameter: string | undefined, longParameter: string, type: ConfigParameterType, options?: ParameterDefinitionOptions): void;
+    /**
+     * Adds a new argument check function to the list of checks.
+     *
+     * @param check - A function that takes an options object as input and returns a string containing an
+     * error message if a validation fails, or undefined if the validation passes.
+     */
+    addArgumentCheck(check: (options: Record<string, unknown>) => string | undefined): void;
+    /**
+     * Makes the given parameter mandatory.
+     */
+    addRequiredArgumentFor(parameterId: string): void;
+    /**
+     * Describes a parameter with its complete set of properties.
+     *
+     * @param parameterId - Internal identifier for the parameter
+     * @param descriptor - Complete parameter descriptor
+     * @throws Error if short parameter is invalid or already mapped
+     */
+    describeParameter(parameterId: string, descriptor: ParameterDescriptor): void;
+    /**
+     * Looks up a parameter descriptor by its ID.
+     *
+     * @param parameterId - Parameter identifier to look up
+     * @returns Parameter descriptor if found, undefined otherwise
+     */
+    lookupParameter(parameterId: string): ParameterDescriptor | undefined;
+    /**
+     * Returns all registered parameter descriptors.
+     *
+     * @returns Array of all parameter descriptors
+     */
+    getParameters(): ParameterDescriptor[];
+    /**
+     * Retrieves the collection of functions used for argument validation.
+     */
+    getArgumentChecks(): Array<(options: Record<string, unknown>) => string | undefined>;
+    /**
+     * Returns an array of parameter IDs that are configured as sequential parameters.
+     * That is, parameters that are given without a name but where their mapping
+     * to concrete parameters is defined by their position in the command line.
+     */
+    getSequentialParameters(): string[];
+    /**
+     * @returns A new configuration object with the same parameters as this one.
+     */
+    clone(): ConfigurationParameters;
+    /**
+     * Adds all parameters and checks from the given configuration to this one.
+     */
+    addAllOf(toAdd: ConfigurationParameters): void;
+}
+/**
+ * Parses command line arguments according to parameter definitions.
+ *
+ * @param args - Array of command line arguments to parse
+ * @param parameters - Configuration parameters defining valid options
+ * @returns Parsed options object with parameter values
+ * @throws Error if parameter values are invalid or missing
+ */
+export declare function parseArguments<OptionsType extends Record<string, unknown>>(args: string[], parameters: ConfigurationParameters): Partial<OptionsType>;
+/**
+ * Parses a configuration file content into options and unnamed arguments.
+ *
+ * @param fileContent - Content of the configuration file to parse
+ * @param parameters - Configuration parameters defining valid options
+ * @returns Object containing parsed options and unnamed arguments
+ * @throws Error if the configuration file contains invalid parameters or values
+ */
+export declare function parseConfigFile(fileContent: string, parameters: ConfigurationParameters): ConfigParsingResult;
+/**
+ * Prints help information for all registered parameters.
+ *
+ * @param parameters - Configuration parameters to display help for
+ * @param aboutText - Optional descriptive text to display before parameter help
+ * @param printParamterId - Print the ID of the parameter instead of the command line parameter names?
+ */
+export declare function printHelp(parameters: ConfigurationParameters, aboutText?: string, printParamterId?: boolean): void;
+/**
+ * Runs the config parameter checks for the given options.
+ */
+export declare function checkArguments(configParameters: ConfigurationParameters, options: Options, errorReceiver?: (error: string) => void): boolean;
+/**
+ * Parses the command-line arguments.
+ */
+export declare function processCommandLine<O>(parameters: ConfigurationParameters, appInfos: AppInfos, args?: string[], beforeCheckCallback?: (options: O) => void): O;
+/**
+ * Creates a new configuration object by merging two configuration objects.
+ */
+export declare function parameterUnion(parameters1: ConfigurationParameters, parameters2: ConfigurationParameters): ConfigurationParameters;
+//# sourceMappingURL=ConfigParser.d.ts.map

package/lib/ConfigParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigParser.d.ts","sourceRoot":"","sources":["../src/ConfigParser.ts"],"names":[],"mappings":"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"}