@code-pushup/utils 0.1.0

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@code-pushup/utils",
+  "version": "0.1.0",
+  "dependencies": {
+    "@code-pushup/models": "*",
+    "bundle-require": "^4.0.1",
+    "chalk": "^5.3.0",
+    "@isaacs/cliui": "^8.0.2",
+    "simple-git": "^3.20.0",
+    "multi-progress-bars": "^5.0.3",
+    "cli-table3": "^0.6.3"
+  },
+  "type": "module",
+  "main": "./index.js",
+  "types": "./src/index.d.ts"
+}

package/src/index.d.ts

@@ -0,0 +1,14 @@
+export { CliArgsObject, ProcessConfig, ProcessError, ProcessObserver, ProcessResult, executeProcess, objectToCliArgs, } from './lib/execute-process';
+export { getLatestCommit, git } from './lib/git';
+export { ProgressBar, getProgressBar } from './lib/progress';
+export { CODE_PUSHUP_DOMAIN, FOOTER_PREFIX, README_LINK, calcDuration, compareIssueSeverity, loadReport, } from './lib/report';
+export { reportToMd } from './lib/report-to-md';
+export { reportToStdout } from './lib/report-to-stdout';
+export { ScoredReport, scoreReport } from './lib/scoring';
+export { readJsonFile, readTextFile, toUnixPath, ensureDirectoryExists, FileResult, MultipleFileResults, logMultipleFileResults, importEsmModule, pluginWorkDir, crawlFileSystem, findLineNumberInText, } from './lib/file-system';
+export { verboseUtils } from './lib/verbose-utils';
+export { toArray, objectToKeys, objectToEntries, countOccurrences, distinct, } from './lib/transformation';
+export { slugify, pluralize, pluralizeToken, formatBytes, formatDuration, } from './lib/formatting';
+export { NEW_LINE } from './lib/md';
+export { logMultipleResults } from './lib/log-results';
+export { isPromiseFulfilledResult, isPromiseRejectedResult, } from './lib/guards';

package/src/lib/execute-process.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Represents the process result.
+ * @category Types
+ * @public
+ * @property {string} stdout - The stdout of the process.
+ * @property {string} stderr - The stderr of the process.
+ * @property {number | null} code - The exit code of the process.
+ */
+export type ProcessResult = {
+    stdout: string;
+    stderr: string;
+    code: number | null;
+    date: string;
+    duration: number;
+};
+/**
+ * Error class for process errors.
+ * Contains additional information about the process result.
+ * @category Error
+ * @public
+ * @class
+ * @extends Error
+ * @example
+ * const result = await executeProcess({})
+ * .catch((error) => {
+ *   if (error instanceof ProcessError) {
+ *   console.error(error.code);
+ *   console.error(error.stderr);
+ *   console.error(error.stdout);
+ *   }
+ * });
+ *
+ */
+export declare class ProcessError extends Error {
+    code: number | null;
+    stderr: string;
+    stdout: string;
+    constructor(result: ProcessResult);
+}
+/**
+ * Process config object. Contains the command, args and observer.
+ * @param cfg - process config object with command, args and observer (optional)
+ * @category Types
+ * @public
+ * @property {string} command - The command to execute.
+ * @property {string[]} args - The arguments for the command.
+ * @property {ProcessObserver} observer - The observer for the process.
+ *
+ * @example
+ *
+ * // bash command
+ * const cfg = {
+ *   command: 'bash',
+ *   args: ['-c', 'echo "hello world"']
+ * };
+ *
+ * // node command
+ * const cfg = {
+ * command: 'node',
+ * args: ['--version']
+ * };
+ *
+ * // npx command
+ * const cfg = {
+ * command: 'npx',
+ * args: ['--version']
+ *
+ */
+export type ProcessConfig = {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    observer?: ProcessObserver;
+};
+/**
+ * Process observer object. Contains the onStdout, error and complete function.
+ * @category Types
+ * @public
+ * @property {function} onStdout - The onStdout function of the observer (optional).
+ * @property {function} onError - The error function of the observer (optional).
+ * @property {function} onComplete - The complete function of the observer (optional).
+ *
+ * @example
+ * const observer = {
+ *  onStdout: (stdout) => console.info(stdout)
+ *  }
+ */
+export type ProcessObserver = {
+    onStdout?: (stdout: string) => void;
+    onError?: (error: ProcessError) => void;
+    onComplete?: () => void;
+};
+/**
+ * Executes a process and returns a promise with the result as `ProcessResult`.
+ *
+ * @example
+ *
+ * // sync process execution
+ * const result = await executeProcess({
+ *  command: 'node',
+ *  args: ['--version']
+ * });
+ *
+ * console.info(result);
+ *
+ * // async process execution
+ * const result = await executeProcess({
+ *    command: 'node',
+ *    args: ['download-data.js'],
+ *    observer: {
+ *      onStdout: updateProgress,
+ *      error: handleError,
+ *      complete: cleanLogs,
+ *    }
+ * });
+ *
+ * console.info(result);
+ *
+ * @param cfg - see {@link ProcessConfig}
+ */
+export declare function executeProcess(cfg: ProcessConfig): Promise<ProcessResult>;
+type ArgumentValue = number | string | boolean | string[];
+export type CliArgsObject<T extends object = Record<string, ArgumentValue>> = T extends never ? Record<string, ArgumentValue | undefined> | {
+    _: string;
+} : T;
+/**
+ * Converts an object with different types of values into an array of command-line arguments.
+ *
+ * @example
+ * const args = objectToProcessArgs({
+ *   _: ['node', 'index.js'], // node index.js
+ *   name: 'Juanita', // --name=Juanita
+ *   formats: ['json', 'md'] // --format=json --format=md
+ * });
+ */
+export declare function objectToCliArgs<T extends object = Record<string, ArgumentValue>>(params?: CliArgsObject<T>): string[];
+export {};

package/src/lib/file-system.d.ts

@@ -0,0 +1,21 @@
+import { type Options } from 'bundle-require';
+export declare function toUnixPath(path: string, options?: {
+    toRelative?: boolean;
+}): string;
+export declare function ensureDirectoryExists(baseDir: string): Promise<void>;
+export declare function readTextFile(path: string): Promise<string>;
+export declare function readJsonFile<T = unknown>(path: string): Promise<T>;
+export type FileResult = readonly [string] | readonly [string, number];
+export type MultipleFileResults = PromiseSettledResult<FileResult>[];
+export declare function logMultipleFileResults(fileResults: MultipleFileResults, messagePrefix: string): void;
+export declare class NoExportError extends Error {
+    constructor(filepath: string);
+}
+export declare function importEsmModule<T = unknown>(options: Options, parse?: (d: unknown) => T): Promise<T>;
+export declare function pluginWorkDir(slug: string): string;
+export declare function crawlFileSystem<T = string>(options: {
+    directory: string;
+    pattern?: string | RegExp;
+    fileTransform?: (filePath: string) => Promise<T> | T;
+}): Promise<T[]>;
+export declare function findLineNumberInText(content: string, pattern: string): number | null;

package/src/lib/formatting.d.ts

@@ -0,0 +1,5 @@
+export declare function slugify(text: string): string;
+export declare function pluralize(text: string): string;
+export declare function formatBytes(bytes: number, decimals?: number): string;
+export declare function pluralizeToken(token: string, times?: number): string;
+export declare function formatDuration(duration: number): string;

package/src/lib/git.d.ts

@@ -0,0 +1,13 @@
+export type CommitData = {
+    hash: string;
+    message: string;
+    author: string;
+    date: string;
+};
+export declare const git: import("simple-git").SimpleGit;
+export declare function getLatestCommit(): Promise<({
+    hash: string;
+    message: string;
+    author: string;
+    date: string;
+} & import("simple-git").ListLogLine) | null>;

package/src/lib/guards.d.ts

@@ -0,0 +1,2 @@
+export declare function isPromiseFulfilledResult<T>(result: PromiseSettledResult<T>): result is PromiseFulfilledResult<T>;
+export declare function isPromiseRejectedResult(result: PromiseSettledResult<unknown>): result is PromiseRejectedResult;

package/src/lib/log-results.d.ts

@@ -0,0 +1,2 @@
+export declare function logMultipleResults<T>(results: PromiseSettledResult<T>[], messagePrefix: string, succeededCallback?: (result: PromiseFulfilledResult<T>) => void, failedCallback?: (result: PromiseRejectedResult) => void): void;
+export declare function logPromiseResults<T extends PromiseFulfilledResult<unknown> | PromiseRejectedResult>(results: T[], logMessage: string, callback: (result: T) => void): void;

package/src/lib/md/constants.d.ts

@@ -0,0 +1 @@
+export declare const NEW_LINE = "\n";

package/src/lib/md/details.d.ts

@@ -0,0 +1,9 @@
+/**
+ * <details {open}>
+ *   <summary>{title}</summary>
+ *   {content}
+ * <details>
+ */
+export declare function details(title: string, content: string, cfg?: {
+    open: boolean;
+}): string;

package/src/lib/md/font-style.d.ts

@@ -0,0 +1,16 @@
+declare const stylesMap: {
+    readonly i: "_";
+    readonly b: "**";
+    readonly s: "~";
+    readonly c: "`";
+};
+export type FontStyle = keyof typeof stylesMap;
+/**
+ * **{text}** // default is bold
+ *
+ * _{text}_ // italic - styles set to `['i']`
+ *
+ * ~**{text}**~ // bold & stroke-through - styles set to `['b','s']`
+ */
+export declare function style(text: string, styles?: FontStyle[]): string;
+export {};

package/src/lib/md/headline.d.ts

@@ -0,0 +1,13 @@
+export type Hierarchy = 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * \# {text} // hierarchy set to 1
+ *
+ * \## {text} // hierarchy set to 2
+ */
+export declare function headline(text: string, hierarchy?: Hierarchy): string;
+export declare function h(text: string, hierarchy?: Hierarchy): string;
+export declare function h2(text: string): string;
+export declare function h3(text: string): string;
+export declare function h4(text: string): string;
+export declare function h5(text: string): string;
+export declare function h6(text: string): string;

package/src/lib/md/index.d.ts

@@ -0,0 +1,7 @@
+export * from './details';
+export * from './headline';
+export * from './table';
+export * from './constants';
+export * from './font-style';
+export * from './link';
+export * from './list';

package/src/lib/md/link.d.ts

@@ -0,0 +1,6 @@
+/**
+ * \# {text} // hierarchy set to 1
+ *
+ * \## {text} // hierarchy set to 2
+ */
+export declare function link(href: string, text?: string): string;

package/src/lib/md/list.d.ts

@@ -0,0 +1,5 @@
+export type Order = 'unordered' | 'checkbox';
+/**
+ * - {text}
+ */
+export declare function li(text: string, order?: Order): string;

package/src/lib/md/table.d.ts

@@ -0,0 +1,10 @@
+export type Alignment = 'l' | 'c' | 'r';
+/**
+ * | Table Header 1  | Table Header 2 |
+ * | --------------- | -------------- |
+ * |  String 1       |  1             |
+ * |  String 1       |  2             |
+ * |  String 1       |  3             |
+ */
+export declare function tableMd(data: (string | number)[][], align?: Alignment[]): string;
+export declare function tableHtml(data: (string | number)[][]): string;

package/src/lib/progress.d.ts

@@ -0,0 +1,13 @@
+import { CtorOptions, MultiProgressBars } from 'multi-progress-bars';
+type BarStyles = 'active' | 'done' | 'idle';
+type StatusStyles = Record<BarStyles, (s: string) => string>;
+export declare const barStyles: StatusStyles;
+export declare const messageStyles: StatusStyles;
+export type ProgressBar = {
+    incrementInSteps: (numSteps: number) => void;
+    updateTitle: (title: string) => void;
+    endProgress: (message?: string) => void;
+};
+export declare function getSingletonProgressBars(options?: Partial<CtorOptions>): MultiProgressBars;
+export declare function getProgressBar(taskName: string): ProgressBar;
+export {};

package/src/lib/report-to-md.d.ts

@@ -0,0 +1,3 @@
+import { CommitData } from './git';
+import { ScoredReport } from './scoring';
+export declare function reportToMd(report: ScoredReport, commitData: CommitData | null): string;

package/src/lib/report-to-stdout.d.ts

@@ -0,0 +1,2 @@
+import { ScoredReport } from './scoring';
+export declare function reportToStdout(report: ScoredReport): string;

package/src/lib/report.d.ts

@@ -0,0 +1,30 @@
+import { CategoryRef, IssueSeverity as CliIssueSeverity, Format, PersistConfig, Report } from '@code-pushup/models';
+import { EnrichedAuditReport, EnrichedScoredAuditGroupWithAudits, ScoredReport, WeighedAuditReport } from './scoring';
+export declare const FOOTER_PREFIX = "Made with \u2764 by";
+export declare const CODE_PUSHUP_DOMAIN = "code-pushup.dev";
+export declare const README_LINK = "https://github.com/flowup/quality-metrics-cli#readme";
+export declare const reportHeadlineText = "Code PushUp Report";
+export declare const reportOverviewTableHeaders: string[];
+export declare const reportRawOverviewTableHeaders: string[];
+export declare const reportMetaTableHeaders: string[];
+export declare const pluginMetaTableHeaders: string[];
+export declare const detailsTableHeaders: string[];
+export declare function formatReportScore(score: number): string;
+export declare function getRoundScoreMarker(score: number): string;
+export declare function getSquaredScoreMarker(score: number): string;
+export declare function getSeverityIcon(severity: 'info' | 'warning' | 'error'): string;
+export declare function calcDuration(start: number, stop?: number): number;
+export declare function countWeightedRefs(refs: CategoryRef[]): number;
+export declare function countCategoryAudits(refs: CategoryRef[], plugins: ScoredReport['plugins']): number;
+export declare function getAuditByRef({ slug, weight, plugin }: CategoryRef, plugins: ScoredReport['plugins']): WeighedAuditReport;
+export declare function getGroupWithAudits(refSlug: string, refPlugin: string, plugins: ScoredReport['plugins']): EnrichedScoredAuditGroupWithAudits;
+export declare function sortCategoryAudits(a: WeighedAuditReport, b: WeighedAuditReport): number;
+export declare function sortAudits(a: EnrichedAuditReport, b: EnrichedAuditReport): number;
+export declare function compareIssueSeverity(severity1: CliIssueSeverity, severity2: CliIssueSeverity): number;
+type LoadedReportFormat<T extends Format> = T extends 'json' ? Report : string;
+export declare function loadReport<T extends Format>(options: Required<Pick<PersistConfig, 'outputDir' | 'filename'>> & {
+    format: T;
+}): Promise<LoadedReportFormat<T>>;
+export declare function throwIsNotPresentError(itemName: string, presentPlace: string): never;
+export declare function getPluginNameFromSlug(slug: string, plugins: ScoredReport['plugins']): string;
+export {};

package/src/lib/scoring.d.ts

@@ -0,0 +1,29 @@
+import { AuditGroup, AuditReport, CategoryConfig, PluginReport, Report } from '@code-pushup/models';
+export type EnrichedAuditReport = AuditReport & {
+    plugin: string;
+};
+export type WeighedAuditReport = EnrichedAuditReport & {
+    weight: number;
+};
+export type EnrichedScoredAuditGroupWithAudits = EnrichedScoredAuditGroup & {
+    audits: AuditReport[];
+};
+type ScoredCategoryConfig = CategoryConfig & {
+    score: number;
+};
+export type EnrichedScoredAuditGroup = AuditGroup & {
+    plugin: string;
+    score: number;
+};
+export type ScoredReport = Omit<Report, 'plugins' | 'categories'> & {
+    plugins: (Omit<PluginReport, 'audits' | 'groups'> & {
+        audits: EnrichedAuditReport[];
+        groups: EnrichedScoredAuditGroup[];
+    })[];
+    categories: ScoredCategoryConfig[];
+};
+export declare function calculateScore<T extends {
+    weight: number;
+}>(refs: T[], scoreFn: (ref: T) => number): number;
+export declare function scoreReport(report: Report): ScoredReport;
+export {};

package/src/lib/transformation.d.ts

@@ -0,0 +1,7 @@
+export declare function toArray<T>(val: T | T[]): T[];
+export declare function objectToKeys<T extends object>(obj: T): (keyof T)[];
+export declare function objectToEntries<T extends object>(obj: T): [keyof T, T[keyof T]][];
+export declare function countOccurrences<T extends PropertyKey>(values: T[]): Partial<Record<T, number>>;
+export declare function distinct<T extends string | number | boolean>(array: T[]): T[];
+export declare function deepClone<T>(obj: T): T;
+export declare function factorOf<T>(items: T[], filterFn: (i: T) => boolean): number;

package/src/lib/verbose-utils.d.ts

@@ -0,0 +1,4 @@
+export declare const verboseUtils: (verbose: boolean) => {
+    log: (...args: unknown[]) => void;
+    exec: (fn: () => unknown) => void;
+};