@decaf-ts/utils 1.2.2 → 1.3.0

package/lib/types/output/common.d.ts

@@ -1,53 +0,0 @@
-import { Logger } from "@decaf-ts/logging";
-/**
- * @description Prints a styled banner to the console.
- * @summary Generates and prints a colorful ASCII art banner with a random slogan.
- * @param {Logger} [logger] - Optional logger for verbose output.
- * @memberOf module:utils
- * @function printBanner
- * @mermaid
- * sequenceDiagram
- *   participant printBanner
- *   participant getSlogan
- *   participant padEnd
- *   participant console
- *   printBanner->>getSlogan: Call getSlogan()
- *   getSlogan-->>printBanner: Return random slogan
- *   printBanner->>printBanner: Create banner ASCII art
- *   printBanner->>printBanner: Split banner into lines
- *   printBanner->>printBanner: Calculate max line length
- *   printBanner->>padEnd: Call padEnd with slogan
- *   padEnd-->>printBanner: Return padded slogan line
- *   loop For each banner line
- *     printBanner->>style: Call style(line)
- *     style-->>printBanner: Return styled line
- *     printBanner->>console: Log styled line
- *   end
- */
-export declare function printBanner(logger?: Logger): void;
-/**
- * @description Retrieves a slogan from the predefined list.
- * @summary Fetches a random slogan or a specific one by index from the slogans list.
- * @param {number} [i] - Optional index to retrieve a specific slogan.
- * @return {string} The selected slogan.
- * @function getSlogan
- * @memberOf module:utils
- * @mermaid
- * sequenceDiagram
- *   participant getSlogan
- *   participant Math.random
- *   participant slogans
- *   alt i is undefined
- *     getSlogan->>Math.random: Generate random index
- *     Math.random-->>getSlogan: Return random index
- *   else i is defined
- *     Note over getSlogan: Use provided index
- *   end
- *   getSlogan->>slogans: Access slogan at index
- *   slogans-->>getSlogan: Return slogan
- *   alt Error occurs
- *     getSlogan->>getSlogan: Throw error
- *   end
- *   getSlogan-->>Caller: Return slogan
- */
-export declare function getSlogan(i?: number): string;

package/lib/types/output/index.d.ts

@@ -1 +0,0 @@
-export * from "./common";

package/lib/types/release-chain/index.d.ts

@@ -1,43 +0,0 @@
-export interface ReleaseChainOptions {
-    metaRepoUrl: string;
-    branch: string;
-    currentRepo?: string;
-    packageName: string;
-    workspace?: string;
-    token?: string;
-    submoduleFile?: string;
-    submodulePath?: string;
-    targetBaseBranch?: string;
-}
-export interface ReleaseChainDispatchOptions {
-    metaRepoUrl: string;
-    branch: string;
-    workflowFile?: string;
-    repoSlug?: string;
-    currentRepo?: string;
-    token?: string;
-    ref?: string;
-    targetBaseBranch?: string;
-}
-export declare class ReleaseChainRunner {
-    private readonly options;
-    private readonly workspace;
-    private readonly clonesRoot;
-    private readonly token?;
-    private readonly metaRepoSlug;
-    private readonly currentRepo?;
-    constructor(options: ReleaseChainOptions);
-    run(): Promise<void>;
-    private evaluateModule;
-    private cloneRepository;
-    private checkoutTargetBranch;
-    private loadSubmodules;
-    private runCommand;
-    private githubRequest;
-    private findExistingPr;
-    private acceptPullRequest;
-    private createPullRequest;
-    private getDefaultBranch;
-}
-export declare function runReleaseChain(options: ReleaseChainOptions): Promise<void>;
-export declare function dispatchReleaseChainWorkflow(options: ReleaseChainDispatchOptions): Promise<void>;

package/lib/types/tests/Consumer.d.ts

@@ -1,151 +0,0 @@
-import { LoggedClass } from "@decaf-ts/logging";
-import { TestReporter } from "./TestReporter";
-/**
- * @description Store for logs indexed by identifier.
- * @summary A record where keys are identifiers and values are arrays of log strings.
- * @typedef {Record<number, string[]>} LogStore
- * @memberOf module:utils
- */
-type LogStore = Record<number, string[]>;
-/**
- * @description Structure of a parsed log entry.
- * @summary Contains timestamp, child identifier, and action.
- * @interface ParsedLog
- * @property {number} timestamp - The timestamp of the log.
- * @property {string} child - The child identifier.
- * @property {string} action - The action performed.
- * @memberOf module:utils
- */
-export interface ParsedLog {
-    timestamp: number;
-    child: string;
-    action: string;
-}
-/**
- * @description Result of a comparison between consumer and producer logs.
- * @summary Contains arrays of parsed logs for both consumer and producer.
- * @interface ComparerResult
- * @property {ParsedLog[]} consumer - The parsed consumer logs.
- * @property {ParsedLog[]} producer - The parsed producer logs.
- * @memberOf module:utils
- */
-export interface ComparerResult {
-    consumer: ParsedLog[];
-    producer: ParsedLog[];
-}
-/**
- * @description Function type for comparing consumer and producer data.
- * @summary Compares two LogStores and returns a Promise resolving to ComparerResult.
- * @typedef {function(LogStore, LogStore): Promise<ComparerResult>} Comparer
- * @memberOf module:utils
- */
-type Comparer = (consumerData: LogStore, producerData: LogStore) => Promise<ComparerResult>;
-/**
- * @description Function type for handling consumer actions.
- * @summary A function that takes an identifier and optional arguments, returning a result.
- * @typedef {function(number, ...unknown[]): unknown | Promise<unknown>} ConsumerHandler
- * @memberOf module:utils
- */
-type ConsumerHandler = (identifier: number, ...args: unknown[]) => unknown | Promise<unknown>;
-/**
- * @description Default comparer function for consumer and producer logs.
- * @summary Sorts and compares consumer and producer logs to ensure they match.
- * @param {LogStore} consumerData - The consumer logs.
- * @param {LogStore} producerData - The producer logs.
- * @return {Promise<ComparerResult>} The comparison result.
- * @function defaultComparer
- * @memberOf module:utils
- */
-export declare const defaultComparer: Comparer;
-/**
- * @description Options for the reporting comparer.
- * @summary Configuration options for the reportingComparer function.
- * @interface ReportingComparerOptions
- * @property {TestReporter} [reporter] - The test reporter instance.
- * @property {string} [testCase] - The test case name.
- * @property {string} [referencePrefix] - The prefix for report references.
- * @memberOf module:utils
- */
-export interface ReportingComparerOptions {
-    reporter?: TestReporter;
-    testCase?: string;
-    referencePrefix?: string;
-}
-/**
- * @description Comparer function that reports results using TestReporter.
- * @summary Compares logs and generates a report with tables and messages.
- * @param {LogStore} consumerData - The consumer logs.
- * @param {LogStore} producerData - The producer logs.
- * @param {ReportingComparerOptions} [options] - Options for reporting.
- * @return {Promise<ComparerResult>} The comparison result.
- * @function reportingComparer
- * @memberOf module:utils
- */
-export declare const reportingComparer: (consumerData: LogStore, producerData: LogStore, options?: ReportingComparerOptions) => Promise<ComparerResult>;
-/**
- * @class ConsumerRunner
- * @description Runs a consumer process and manages producer child processes.
- * @summary Orchestrates the execution of consumer and producer processes, collects logs, and compares results.
- * @param {string} action - The action name.
- * @param {ConsumerHandler} consumerHandler - The handler function for the consumer.
- * @param {Comparer} [compareHandler] - Optional custom comparer function.
- * @memberOf module:utils
- */
-export declare class ConsumerRunner extends LoggedClass {
-    private readonly action;
-    private readonly handler;
-    private readonly comparerHandle;
-    private forkedCache;
-    private consumerResults;
-    private producerResults;
-    private childExitPromises;
-    private completionTriggered;
-    private producerCompletion;
-    private consumerCompletion;
-    private expectedIterations;
-    private activeHandlers;
-    constructor(action: string, consumerHandler: ConsumerHandler, compareHandler?: Comparer);
-    private reset;
-    private waitForChildExit;
-    private store;
-    private recordConsumer;
-    private isProducerComplete;
-    private isConsumerComplete;
-    private terminateChildren;
-    /**
-     * @description Runs the consumer and producer processes.
-     * @summary Starts the producer child processes and the consumer handler, then waits for completion and compares results.
-     * @param {number} count - The number of producers.
-     * @param {number} [timeout] - The timeout for producers.
-     * @param {number} times - The number of times to repeat.
-     * @param {boolean} [random] - Whether to use random timeouts.
-     * @return {Promise<ComparerResult>} The comparison result.
-     * @mermaid
-     * sequenceDiagram
-     *   participant Runner as ConsumerRunner
-     *   participant Child as ProducerChild
-     *   participant Handler as ConsumerHandler
-     *   participant Comparer as Comparer
-     *   Runner->>Runner: reset()
-     *   loop For each count
-     *     Runner->>Child: fork()
-     *     Runner->>Runner: Store child process
-     *   end
-     *   Runner->>Child: send(start message)
-     *   loop For each message from Child
-     *     Child->>Runner: message(action)
-     *     Runner->>Runner: store producer log
-     *     Runner->>Handler: call handler
-     *     Handler-->>Runner: return
-     *     Runner->>Runner: record consumer log
-     *     Runner->>Runner: finalizeIfComplete()
-     *   end
-     *   alt Complete
-     *     Runner->>Comparer: compare logs
-     *     Comparer-->>Runner: return result
-     *     Runner-->>Caller: resolve(result)
-     *   end
-     */
-    run(count: number, timeout: number | undefined, times: number, random: boolean | undefined): Promise<ComparerResult>;
-}
-export {};

package/lib/types/tests/ProducerChildProcess.d.ts

@@ -1,18 +0,0 @@
-type ParentMessage = {
-    identifier: number;
-    action: string;
-    timeout?: number;
-    times: number;
-    random?: boolean;
-    terminate?: boolean;
-};
-type ProducerResponse = {
-    identifier: number;
-    action: string;
-    timeout?: number;
-    times: number;
-    random?: boolean;
-    result?: string[];
-};
-declare let shuttingDown: boolean;
-declare const completeAndExit: (logMessage?: string) => void;

package/lib/types/tests/TestReporter.d.ts

@@ -1,245 +0,0 @@
-import { MdTableDefinition } from "../utils/md";
-/**
- * @interface AddAttachParams
- * @description Parameters for adding an attachment to a report
- * @summary Interface for attachment parameters
- * @memberOf module:utils
- */
-export interface AddAttachParams {
-    attach: string | Buffer;
-    description: string | object;
-    context?: any;
-    bufferFormat?: string;
-}
-/**
- * @interface AddMsgParams
- * @description Parameters for adding a message to a report
- * @summary Interface for message parameters
- * @memberOf module:utils
- */
-export interface AddMsgParams {
-    message: string | object;
-    context?: any;
-}
-/**
- * @typedef {("json"|"image"|"text"|"md")} PayloadType
- * @description Types of payloads that can be handled
- * @summary Union type for payload types
- * @memberOf module:utils
- */
-export type PayloadType = "json" | "image" | "text" | "md";
-export type EvidenceData = {
-    name: string;
-    content: string | Buffer;
-    path: string;
-};
-/**
- * @description Environment variable key for Jest HTML reporters temporary directory path
- * @summary Constant defining the environment variable key for Jest HTML reporters
- * @const JestReportersTempPathEnvKey
- * @memberOf module:utils
- */
-export declare const JestReportersTempPathEnvKey = "JEST_HTML_REPORTERS_TEMP_DIR_PATH";
-/**
- * @description Environment variable key to enable file-based evidence storage
- * @summary Constant defining the environment variable key for storage enablement
- * @const TestReporterStorageEnabledEnvKey
- * @memberOf module:utils
- */
-export declare const TestReporterStorageEnabledEnvKey = "TEST_REPORTER_STORAGE_ENABLED";
-/**
- * @description Environment variable key for the base path of evidence storage
- * @summary Constant defining the environment variable key for storage path
- * @const TestReporterStoragePathEnvKey
- * @memberOf module:utils
- */
-export declare const TestReporterStoragePathEnvKey = "TEST_REPORTER_STORAGE_PATH";
-/**
- * @description Test reporting utility class for managing test results and evidence
- * @summary A comprehensive test reporter that handles various types of test artifacts including messages,
- * attachments, data, images, tables, and graphs. It provides methods to report and store test evidence
- * in different formats and manages dependencies for reporting functionality.
- *
- * @template T - Type of data being reported
- * @param {string} [testCase="tests"] - Name of the test case
- * @param {string} [basePath] - Base path for storing test reports
- * @class
- *
- * @example
- * ```typescript
- * const reporter = new TestReporter('login-test');
- *
- * // Report test messages
- * await reporter.reportMessage('Test Started', 'Login flow initiated');
- *
- * // Report test data
- * await reporter.reportData('user-credentials', { username: 'test' }, 'json');
- *
- * // Report test results table
- * await reporter.reportTable('test-results', {
- *   headers: ['Step', 'Status'],
- *   rows: [
- *     { Step: 'Login', Status: 'Pass' },
- *     { Step: 'Validation', Status: 'Pass' }
- *   ]
- * });
- *
- * // Report test evidence
- * await reporter.reportAttachment('Screenshot', screenshotBuffer);
- * ```
- *
- * @mermaid
- * sequenceDiagram
- *   participant Client
- *   participant TestReporter
- *   participant FileSystem
- *   participant Dependencies
- *
- *   Client->>TestReporter: new TestReporter(testCase, basePath)
- *   TestReporter->>FileSystem: Create report directory
- *
- *   alt Report Message
- *     Client->>TestReporter: reportMessage(title, message)
- *     TestReporter->>Dependencies: Import helpers
- *     TestReporter->>FileSystem: Store message
- *   else Report Data
- *     Client->>TestReporter: reportData(reference, data, type)
- *     TestReporter->>Dependencies: Process data
- *     TestReporter->>FileSystem: Store formatted data
- *   else Report Table
- *     Client->>TestReporter: reportTable(reference, tableDef)
- *     TestReporter->>Dependencies: Convert to MD format
- *     TestReporter->>FileSystem: Store table
- *   end
- */
-export declare class TestReporter {
-    protected testCase: string;
-    protected basePath: string;
-    /**
-     * @description Function for adding messages to the test report
-     * @summary Static handler for processing and storing test messages
-     * @type {function(AddMsgParams): Promise<void>}
-     */
-    protected static addMsgFunction: (params: AddMsgParams) => Promise<void>;
-    /**
-     * @description Function for adding attachments to the test report
-     * @summary Static handler for processing and storing test attachments
-     * @type {function(AddAttachParams): Promise<void>}
-     */
-    protected static addAttachFunction: (params: AddAttachParams) => Promise<void>;
-    /**
-     * @description Map of dependencies required by the reporter
-     * @summary Stores the current state of dependencies
-     * @type {SimpleDependencyMap}
-     */
-    private deps?;
-    /**
-     * @description Checks if storage is enabled via environment variables
-     * @summary Static getter for storage enablement status
-     * @type {boolean}
-     */
-    static get storageEnabled(): boolean;
-    /**
-     * @description Gets the base path for evidence storage from environment variables or default
-     * @summary Static getter for evidence storage base path
-     * @type {string}
-     */
-    static get storagePath(): string;
-    constructor(testCase?: string, basePath?: string);
-    /**
-     * @description Retrieves all evidences for a given describe and it name
-     * @summary Searches the storage directory for matching evidences using string inclusion
-     * @param {string} describeName - Name of the describe block to match
-     * @param {string} itName - Name of the it block to match
-     * @return {EvidenceData[]} Array of matching evidences
-     */
-    static getEvidencesOf(describeName: string, itName: string): EvidenceData[];
-    /**
-     * @description Imports required helper functions
-     * @summary Ensures all necessary dependencies are available and imports helper functions
-     * @return {Promise<void>} Promise that resolves when helpers are imported
-     */
-    private importHelpers;
-    private getJestHtmlReportersTempDir;
-    private ensureJestHtmlReportersTempDirs;
-    private overrideJestHtmlReportersTempPaths;
-    /**
-     * @description Reports a message to the test report
-     * @summary Adds a formatted message to the test report with an optional title
-     * @param {string} title - Title of the message
-     * @param {string | object} message - Content of the message
-     * @return {Promise<void>} Promise that resolves when the message is reported
-     */
-    reportMessage(title: string, message: string | object): Promise<void>;
-    /**
-     * @description Reports an attachment to the test report
-     * @summary Adds a formatted message to the test report with an optional title
-     * @param {string} title - Title of the message
-     * @param {string | Buffer} attachment - Content of the message
-     * @return {Promise<void>} Promise that resolves when the message is reported
-     */
-    reportAttachment(title: string, attachment: string | Buffer): Promise<void>;
-    /**
-     * @description Reports data with specified type
-     * @summary Processes and stores data in the test report with formatting
-     * @param {string} reference - Reference identifier for the data
-     * @param {string | number | object} data - Data to be reported
-     * @param {PayloadType} type - Type of the payload
-     * @param {boolean} [trim=false] - Whether to trim the data
-     * @return {Promise<void>} Promise that resolves when data is reported
-     */
-    protected report(reference: string, data: string | number | object | Buffer, type: PayloadType, trim?: boolean): Promise<void>;
-    /**
-     * @description Stores evidence to a file in the specified directory structure
-     * @summary Internal method to handle file-based storage of test artifacts
-     * @param {string} reference - Reference identifier for the data
-     * @param {any} data - Data to be stored
-     * @param {PayloadType} type - Type of the payload
-     * @param {string} extension - File extension to use
-     * @return {Promise<void>}
-     */
-    private storeEvidence;
-    /**
-     * @description Reports data with a specified type
-     * @summary Wrapper method for reporting various types of data
-     * @param {string} reference - Reference identifier for the data
-     * @param {string | number | object} data - Data to be reported
-     * @param {PayloadType} [type="json"] - Type of the payload
-     * @param {boolean} [trim=false] - Whether to trim the data
-     * @return {Promise<void>} Promise that resolves when data is reported
-     */
-    reportData(reference: string, data: string | number | object, type?: PayloadType, trim?: boolean): Promise<void>;
-    /**
-     * @description Reports a JSON object
-     * @summary Convenience method for reporting JSON objects
-     * @param {string} reference - Reference identifier for the object
-     * @param {object} json - JSON object to be reported
-     * @param {boolean} [trim=false] - Whether to trim the object
-     * @return {Promise<void>} Promise that resolves when object is reported
-     */
-    reportObject(reference: string, json: object, trim?: boolean): Promise<void>;
-    /**
-     * @description Reports a table in markdown format
-     * @summary Converts and stores a table definition in markdown format
-     * @param {string} reference - Reference identifier for the table
-     * @param {MdTableDefinition} tableDef - Table definition object
-     * @return {Promise<void>} Promise that resolves when table is reported
-     */
-    reportTable(reference: string, tableDef: MdTableDefinition): Promise<void>;
-    /**
-     * @description Reports a graph using Chart.js
-     * @summary Generates and stores a graph visualization
-     * @param {string} reference - Reference identifier for the graph
-     * @param {any} config - Chart.js configuration object
-     * @return {Promise<void>} Promise that resolves when graph is reported
-     */
-    reportGraph(reference: string, config: any, width?: number, height?: number): Promise<Buffer>;
-    /**
-     * @description Reports an image to the test report
-     * @summary Stores an image buffer in the test report
-     * @param {string} reference - Reference identifier for the image
-     * @param {Buffer} buffer - Image data buffer
-     * @return {Promise<void>} Promise that resolves when image is reported
-     */
-    reportImage(reference: string, buffer: Buffer): Promise<void>;
-}

package/lib/types/tests/index.d.ts

@@ -1,4 +0,0 @@
-export * from "./Consumer";
-export * from "./TestReporter";
-export * from "./utils";
-export * from "./jestPerformanceRunner";

package/lib/types/tests/jestPerformanceRunner.d.ts

@@ -1,37 +0,0 @@
-import { PerformanceScenario, PerformanceRunner, PhaseResult } from "../utils/performanceRunner";
-export type JestPerformanceScenario<TContext = Record<string, unknown>> = PerformanceScenario<TContext>;
-export declare class JestPerformanceRunner<TContext = Record<string, unknown>> extends PerformanceRunner<TContext> {
-    protected scenario: JestPerformanceScenario<TContext>;
-    private readonly reporter;
-    constructor(scenario: JestPerformanceScenario<TContext>);
-    /** Disable the base-class text-table canvas; we render a proper bar chart instead. */
-    protected shouldRenderCanvas(): boolean;
-    /** Logs per-phase table to the jest-html-reporters attachment. */
-    private reportPhaseToReporter;
-    /**
-     * After all phases finish: console-log the combined summary (base class),
-     * then report the summary table and a bar chart with the reporter.
-     */
-    protected logSummary(results: PhaseResult<TContext>[]): Promise<void>;
-    private buildTableDef;
-    /**
-     * Builds a Chart.js config: grouped bar columns (Wall/Avg/Min/Max ms)
-     * with a red line overlay for failure counts on a secondary right axis.
-     */
-    private buildPhaseChart;
-    /**
-     * Registers Jest describe/it blocks for the scenario.
-     * Creates one `it` per phase — its never fail, errors are only recorded
-     * in aggregated results. Logs a per-phase console table and reports it
-     * via TestReporter after each `it`; reports combined table + bar chart
-     * in `afterAll`.
-     *
-     * @param hooks Optional lifecycle hooks:
-     *   - `beforeAll`: runs after `scenario.initialize` but before any `it`.
-     *     Use this to populate shared mutable state (e.g. metadata objects)
-     *     that phase configs reference.
-     */
-    describeSuite(hooks?: {
-        beforeAll?: () => Promise<void> | void;
-    }): void;
-}

package/lib/types/tests/utils.d.ts

@@ -1,5 +0,0 @@
-import { SpawnOptionsWithoutStdio } from "child_process";
-import { OutputWriterConstructor, StandardOutputWriter } from "../writers";
-import { CommandResult } from "../utils/types";
-import { TestReporter } from "./TestReporter";
-export declare function runAndReport<R = string>(command: string, opts: SpawnOptionsWithoutStdio | undefined, outputConstructor: OutputWriterConstructor<R, StandardOutputWriter<R>, Error> | undefined, reporter: TestReporter, commandPrefix?: string, ...args: unknown[]): CommandResult<R>;

package/lib/types/utils/constants.d.ts

@@ -1,65 +0,0 @@
-/**
- * @description Default encoding for text operations.
- * @summary The standard UTF-8 encoding used for text processing.
- * @const {string} Encoding
- * @memberOf module:utils
- */
-export declare const Encoding = "utf-8";
-/**
- * @description Regular expression for semantic versioning.
- * @summary A regex pattern to match and parse semantic version strings.
- * @const {RegExp} SemVersionRegex
- * @memberOf module:utils
- */
-export declare const SemVersionRegex: RegExp;
-/**
- * @description Enum for semantic version components.
- * @summary Defines the three levels of semantic versioning: PATCH, MINOR, and MAJOR.
- * @enum {string}
- * @memberOf module:utils
- */
-export declare enum SemVersion {
-    /** Patch version for backwards-compatible bug fixes. */
-    PATCH = "patch",
-    /** Minor version for backwards-compatible new features. */
-    MINOR = "minor",
-    /** Major version for changes that break backwards compatibility. */
-    MAJOR = "major"
-}
-/**
- * @description Flag to indicate non-CI environment.
- * @summary Used to specify that a command should run outside of a Continuous Integration environment.
- * @const {string} NoCIFLag
- * @memberOf module:utils
- */
-export declare const NoCIFLag = "-no-ci";
-/**
- * @description Key for the setup script in package.json.
- * @summary Identifies the script that runs after package installation.
- * @const {string} SetupScriptKey
- * @memberOf module:utils
- */
-export declare const SetupScriptKey = "postinstall";
-/**
- * @description Enum for various authentication tokens.
- * @summary Defines the file names for storing different types of authentication tokens.
- * @enum {string}
- * @memberOf module:utils
- */
-export declare enum Tokens {
-    /** Git authentication token file name. */
-    GIT = ".token",
-    /** NPM authentication token file name. */
-    NPM = ".npmtoken",
-    /** Docker authentication token file name. */
-    DOCKER = ".dockertoken",
-    /** Confluence authentication token file name. */
-    CONFLUENCE = ".confluence-token"
-}
-/**
- * @description Code used to indicate an operation was aborted.
- * @summary Standard message used when a process is manually terminated.
- * @const {string} AbortCode
- * @memberOf module:utils
- */
-export declare const AbortCode = "Aborted";