@code-pushup/utils 0.49.0 → 0.51.0

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@code-pushup/utils",
-  "version": "0.49.0",
+  "version": "0.51.0",
+  "description": "Low-level utilities (helper functions, etc.) used by Code PushUp CLI",
   "dependencies": {
-    "@code-pushup/models": "0.49.0",
+    "@code-pushup/models": "0.51.0",
     "@isaacs/cliui": "^8.0.2",
     "@poppinss/cliui": "^6.4.0",
     "ansis": "^3.3.0",
-    "build-md": "^0.4.1",
+    "build-md": "^0.4.2",
     "bundle-require": "^4.0.1",
     "esbuild": "^0.19.2",
     "multi-progress-bars": "^5.0.3",
@@ -14,7 +15,7 @@
     "simple-git": "^3.20.0"
   },
   "license": "MIT",
-  "homepage": "https://github.com/code-pushup/cli#readme",
+  "homepage": "https://github.com/code-pushup/cli/tree/main/packages/utils#readme",
   "bugs": {
     "url": "https://github.com/code-pushup/cli/issues"
   },
@@ -23,33 +24,6 @@
     "url": "git+https://github.com/code-pushup/cli.git",
     "directory": "packages/utils"
   },
-  "contributors": [
-    {
-      "name": "Igor Katsuba",
-      "email": "igor@katsuba.dev",
-      "url": "https://katsuba.dev"
-    },
-    {
-      "name": "Kateřina Pilátová",
-      "email": "katerina.pilatova@flowup.cz",
-      "url": "https://github.com/Tlacenka"
-    },
-    {
-      "name": "Matěj Chalk",
-      "email": "matej.chalk@flowup.cz",
-      "url": "https://github.com/matejchalk"
-    },
-    {
-      "name": "Michael Hladky",
-      "email": "michael.hladky@push-based.io",
-      "url": "https://push-based.io"
-    },
-    {
-      "name": "Michael Seredenko",
-      "email": "misha.seredenko@push-based.io",
-      "url": "https://github.com/MishaSeredenkoPushBased"
-    }
-  ],
   "type": "module",
   "main": "./index.js",
   "types": "./src/index.d.ts"

package/src/index.d.ts

@@ -1,29 +1,30 @@
 export { exists } from '@code-pushup/models';
-export { Diff, comparePairs, matchArrayItemsByKey } from './lib/diff';
-export { ProcessConfig, ProcessError, ProcessObserver, ProcessResult, executeProcess, } from './lib/execute-process';
-export { CrawlFileSystemOptions, FileResult, MultipleFileResults, crawlFileSystem, directoryExists, ensureDirectoryExists, fileExists, filePathToCliArg, findLineNumberInText, importModule, logMultipleFileResults, pluginWorkDir, readJsonFile, readTextFile, removeDirectoryIfExists, } from './lib/file-system';
+export { comparePairs, matchArrayItemsByKey, type Diff } from './lib/diff';
+export { stringifyError } from './lib/errors';
+export { ProcessError, executeProcess, type ProcessConfig, type ProcessObserver, type ProcessResult, } from './lib/execute-process';
+export { crawlFileSystem, directoryExists, ensureDirectoryExists, fileExists, filePathToCliArg, findLineNumberInText, importModule, logMultipleFileResults, pluginWorkDir, readJsonFile, readTextFile, removeDirectoryIfExists, type CrawlFileSystemOptions, type FileResult, type MultipleFileResults, } from './lib/file-system';
 export { filterItemRefsBy } from './lib/filter';
 export { formatBytes, formatDuration, pluralize, pluralizeToken, slugify, truncateDescription, truncateIssueMessage, truncateText, truncateTitle, } from './lib/formatting';
 export { formatGitPath, getGitRoot, guardAgainstLocalChanges, safeCheckout, toGitPath, } from './lib/git/git';
-export { LogResult, getCurrentBranchOrTag, getHashFromTag, getHashes, getLatestCommit, getSemverTags, } from './lib/git/git.commits-and-tags';
+export { getCurrentBranchOrTag, getHashFromTag, getHashes, getLatestCommit, getSemverTags, type LogResult, } from './lib/git/git.commits-and-tags';
 export { groupByStatus } from './lib/group-by-status';
 export { isPromiseFulfilledResult, isPromiseRejectedResult, } from './lib/guards';
 export { logMultipleResults } from './lib/log-results';
-export { CliUi, Column, link, ui } from './lib/logging';
+export { link, ui, type CliUi, type Column } from './lib/logging';
 export { mergeConfigs } from './lib/merge-configs';
-export { ProgressBar, getProgressBar } from './lib/progress';
-export { CODE_PUSHUP_DOMAIN, FOOTER_PREFIX, README_LINK, TERMINAL_WIDTH, } from './lib/reports/constants';
+export { getProgressBar, type ProgressBar } from './lib/progress';
+export { CODE_PUSHUP_DOMAIN, CODE_PUSHUP_UNICODE_LOGO, FOOTER_PREFIX, README_LINK, TERMINAL_WIDTH, } from './lib/reports/constants';
 export { listAuditsFromAllPlugins, listGroupsFromAllPlugins, } from './lib/reports/flatten-plugins';
 export { generateMdReport } from './lib/reports/generate-md-report';
-export { generateMdReportsDiff } from './lib/reports/generate-md-reports-diff';
+export { generateMdReportsDiff, generateMdReportsDiffForMonorepo, } from './lib/reports/generate-md-reports-diff';
 export { loadReport } from './lib/reports/load-report';
 export { logStdoutSummary } from './lib/reports/log-stdout-summary';
 export { scoreReport } from './lib/reports/scoring';
 export { sortReport } from './lib/reports/sorting';
-export { ScoredCategoryConfig, ScoredGroup, ScoredReport, } from './lib/reports/types';
-export { calcDuration, compareIssueSeverity } from './lib/reports/utils';
+export type { ScoredCategoryConfig, ScoredGroup, ScoredReport, } from './lib/reports/types';
+export { calcDuration, compareIssueSeverity, formatReportScore, } from './lib/reports/utils';
 export { isSemver, normalizeSemver, sortSemvers } from './lib/semver';
 export * from './lib/text-formats';
-export { CliArgsObject, capitalize, countOccurrences, distinct, factorOf, fromJsonLines, objectFromEntries, objectToCliArgs, objectToEntries, objectToKeys, toArray, toJsonLines, toNumberPrecision, toOrdinal, toUnixNewlines, toUnixPath, } from './lib/transform';
-export { ExcludeNullFromPropertyTypes } from './lib/types';
+export { capitalize, countOccurrences, distinct, factorOf, fromJsonLines, objectFromEntries, objectToCliArgs, objectToEntries, objectToKeys, toArray, toJsonLines, toNumberPrecision, toOrdinal, toUnixNewlines, toUnixPath, type CliArgsObject, } from './lib/transform';
+export type { ExcludeNullFromPropertyTypes, ExtractArray, ExtractArrays, ItemOrArray, Prettify, WithRequired, } from './lib/types';
 export { verboseUtils } from './lib/verbose-utils';

package/src/lib/errors.d.ts

@@ -0,0 +1 @@
+export declare function stringifyError(error: unknown): string;

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

@@ -1,3 +1,5 @@
+/// <reference types="node" />
+import { type ChildProcess, type SpawnOptionsWithStdioTuple, type StdioPipe } from 'node:child_process';
 /**
  * Represents the process result.
  * @category Types
@@ -66,10 +68,9 @@ export declare class ProcessError extends Error {
  * args: ['--version']
  *
  */
-export type ProcessConfig = {
+export type ProcessConfig = Omit<SpawnOptionsWithStdioTuple<StdioPipe, StdioPipe, StdioPipe>, 'stdio'> & {
     command: string;
     args?: string[];
-    cwd?: string;
     observer?: ProcessObserver;
     ignoreExitCode?: boolean;
 };
@@ -87,7 +88,8 @@ export type ProcessConfig = {
  *  }
  */
 export type ProcessObserver = {
-    onStdout?: (stdout: string) => void;
+    onStdout?: (stdout: string, sourceProcess?: ChildProcess) => void;
+    onStderr?: (stderr: string, sourceProcess?: ChildProcess) => void;
     onError?: (error: ProcessError) => void;
     onComplete?: () => void;
 };

package/src/lib/git/git.commits-and-tags.d.ts

@@ -1,5 +1,5 @@
-import { LogOptions as SimpleGitLogOptions } from 'simple-git';
-import { Commit } from '@code-pushup/models';
+import { type LogOptions as SimpleGitLogOptions } from 'simple-git';
+import { type Commit } from '@code-pushup/models';
 export declare function getLatestCommit(git?: import("simple-git").SimpleGit): Promise<Commit | null>;
 export declare function getCurrentBranchOrTag(git?: import("simple-git").SimpleGit): Promise<string>;
 export type LogResult = {

package/src/lib/git/git.d.ts

@@ -1,4 +1,4 @@
-import { StatusResult } from 'simple-git';
+import { type StatusResult } from 'simple-git';
 export declare function getGitRoot(git?: import("simple-git").SimpleGit): Promise<string>;
 export declare function formatGitPath(path: string, gitRoot: string): string;
 export declare function toGitPath(path: string, git?: import("simple-git").SimpleGit): Promise<string>;

package/src/lib/merge-configs.d.ts

@@ -1,2 +1,2 @@
-import { CoreConfig } from '@code-pushup/models';
+import type { CoreConfig } from '@code-pushup/models';
 export declare function mergeConfigs(config: CoreConfig, ...configs: Partial<CoreConfig>[]): Partial<CoreConfig>;

package/src/lib/progress.d.ts

@@ -1,4 +1,4 @@
-import { CtorOptions, MultiProgressBars } from 'multi-progress-bars';
+import { type CtorOptions, MultiProgressBars } from 'multi-progress-bars';
 type BarStyles = 'active' | 'done' | 'idle';
 type StatusStyles = Record<BarStyles, (s: string) => string>;
 export declare const barStyles: StatusStyles;

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

@@ -7,4 +7,5 @@ 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/code-pushup/cli#readme";
 export declare const REPORT_HEADLINE_TEXT = "Code PushUp Report";
+export declare const CODE_PUSHUP_UNICODE_LOGO = "<\u2713>";
 export declare const REPORT_RAW_OVERVIEW_TABLE_HEADERS: string[];

package/src/lib/reports/flatten-plugins.d.ts

@@ -1,4 +1,4 @@
-import { Report } from '@code-pushup/models';
+import type { Report } from '@code-pushup/models';
 export declare function listGroupsFromAllPlugins<T extends Report>(report: T): {
     plugin: T['plugins'][number];
     group: NonNullable<T['plugins'][number]['groups']>[number];

package/src/lib/reports/formatting.d.ts

@@ -1,6 +1,19 @@
-import { HeadingLevel, InlineText, MarkdownDocument } from 'build-md';
-import { AuditReport, Table } from '@code-pushup/models';
+import { type HeadingLevel, type InlineText, MarkdownDocument } from 'build-md';
+import type { AuditReport, SourceFileLocation, Table } from '@code-pushup/models';
+import type { MdReportOptions } from './types';
 export declare function tableSection(tableData: Table, options?: {
     level?: HeadingLevel;
 }): MarkdownDocument | null;
 export declare function metaDescription(audit: Pick<AuditReport, 'docsUrl' | 'description'>): InlineText;
+/**
+ * Link to local source for IDE
+ * @param source
+ * @param reportLocation
+ *
+ * @example
+ * linkToLocalSourceInIde({ file: 'src/index.ts' }, { outputDir: '.code-pushup' }) // [`src/index.ts`](../src/index.ts)
+ */
+export declare function linkToLocalSourceForIde(source: SourceFileLocation, options?: Pick<MdReportOptions, 'outputDir'>): InlineText;
+export declare function formatSourceLine(position: SourceFileLocation['position']): string;
+export declare function formatGitHubLink(file: string, position: SourceFileLocation['position']): string;
+export declare function formatFileLink(file: string, position: SourceFileLocation['position'], outputDir: string): string;

package/src/lib/reports/generate-md-report-categoy-section.d.ts

@@ -1,6 +1,6 @@
-import { InlineText, MarkdownDocument } from 'build-md';
-import { AuditReport } from '@code-pushup/models';
-import { ScoredGroup, ScoredReport } from './types';
+import { type InlineText, MarkdownDocument } from 'build-md';
+import type { AuditReport } from '@code-pushup/models';
+import type { ScoredGroup, ScoredReport } from './types';
 export declare function categoriesOverviewSection(report: Pick<ScoredReport, 'categories' | 'plugins'>): MarkdownDocument;
 export declare function categoriesDetailsSection(report: Pick<ScoredReport, 'categories' | 'plugins'>): MarkdownDocument;
 export declare function categoryRef({ title, score, value, displayValue }: AuditReport, pluginTitle: string): InlineText;

package/src/lib/reports/generate-md-report.d.ts

@@ -1,11 +1,11 @@
-import { InlineText, MarkdownDocument } from 'build-md';
-import { AuditReport, Issue, Report } from '@code-pushup/models';
-import { ScoredReport } from './types';
+import { type InlineText, MarkdownDocument } from 'build-md';
+import type { AuditReport, Issue, Report } from '@code-pushup/models';
+import type { MdReportOptions, ScoredReport } from './types';
 export declare function auditDetailsAuditValue({ score, value, displayValue, }: AuditReport): InlineText;
-export declare function generateMdReport(report: ScoredReport): string;
-export declare function auditDetailsIssues(issues?: Issue[]): MarkdownDocument | null;
-export declare function auditDetails(audit: AuditReport): MarkdownDocument;
-export declare function auditsSection({ plugins, }: Pick<ScoredReport, 'plugins'>): MarkdownDocument;
+export declare function generateMdReport(report: ScoredReport, options?: MdReportOptions): string;
+export declare function auditDetailsIssues(issues?: Issue[], options?: MdReportOptions): MarkdownDocument | null;
+export declare function auditDetails(audit: AuditReport, options?: MdReportOptions): MarkdownDocument;
+export declare function auditsSection({ plugins }: Pick<ScoredReport, 'plugins'>, options?: MdReportOptions): MarkdownDocument;
 export declare function aboutSection(report: Omit<ScoredReport, 'packageName'>): MarkdownDocument;
 export declare function pluginMetaTable({ plugins, }: Pick<Report, 'plugins'>): Parameters<MarkdownDocument['table']>;
 export declare function reportMetaTable({ commit, version, duration, plugins, categories, }: Pick<ScoredReport, 'date' | 'duration' | 'version' | 'commit' | 'plugins' | 'categories'>): Parameters<MarkdownDocument['table']>;

package/src/lib/reports/generate-md-reports-diff-utils.d.ts

@@ -0,0 +1,29 @@
+import { type InlineText, MarkdownDocument } from 'build-md';
+import type { ReportsDiff } from '@code-pushup/models';
+import type { DiffOutcome } from './types';
+export declare function summarizeUnchanged(token: string, { changed, unchanged }: {
+    changed: unknown[];
+    unchanged: unknown[];
+}): string;
+export declare function summarizeDiffOutcomes(outcomes: DiffOutcome[], token: string): string;
+export declare function createGroupsOrAuditsDetails<T extends 'group' | 'audit'>(token: T, { changed, unchanged }: ReportsDiff[`${T}s`], ...[columns, rows]: Parameters<MarkdownDocument['table']>): MarkdownDocument;
+export declare function formatTitle({ title, docsUrl, }: {
+    title: string;
+    docsUrl?: string;
+}): InlineText;
+export declare function formatPortalLink(portalUrl: string | undefined): InlineText | undefined;
+type Change = {
+    scores: {
+        diff: number;
+    };
+    values?: {
+        diff: number;
+    };
+};
+export declare function sortChanges<T extends Change>(changes: T[]): T[];
+export declare function getDiffChanges(diff: ReportsDiff): Change[];
+export declare function changesToDiffOutcomes(changes: Change[]): DiffOutcome[];
+export declare function mergeDiffOutcomes(outcomes: DiffOutcome[]): DiffOutcome;
+export declare function formatReportOutcome(outcome: DiffOutcome, commits?: ReportsDiff['commits']): InlineText;
+export declare function compareDiffsBy<T extends 'categories' | 'groups' | 'audits'>(type: T, a: ReportsDiff, b: ReportsDiff): number;
+export {};

package/src/lib/reports/generate-md-reports-diff.d.ts

@@ -1,2 +1,5 @@
-import { ReportsDiff } from '@code-pushup/models';
-export declare function generateMdReportsDiff(diff: ReportsDiff, portalUrl?: string): string;
+import type { ReportsDiff } from '@code-pushup/models';
+import type { WithRequired } from '../types';
+export declare function generateMdReportsDiff(diff: ReportsDiff): string;
+export type LabeledDiff = WithRequired<ReportsDiff, 'label'>;
+export declare function generateMdReportsDiffForMonorepo(diffs: LabeledDiff[]): string;

package/src/lib/reports/ide-environment.d.ts

@@ -0,0 +1,3 @@
+import type { IdeEnvironment } from './types';
+export declare function getEnvironmentType(): IdeEnvironment;
+export declare function getGitHubBaseUrl(): string;

package/src/lib/reports/load-report.d.ts

@@ -1,4 +1,4 @@
-import { Format, PersistConfig, Report } from '@code-pushup/models';
+import { type Format, type PersistConfig, type Report } from '@code-pushup/models';
 type LoadedReportFormat<T extends Format> = T extends 'json' ? Report : string;
 export declare function loadReport<T extends Format>(options: Required<Omit<PersistConfig, 'format'>> & {
     format: T;

package/src/lib/reports/log-stdout-summary.d.ts

@@ -1,4 +1,4 @@
-import { ScoredReport } from './types';
+import type { ScoredReport } from './types';
 export declare function logStdoutSummary(report: ScoredReport): void;
 export declare function logCategories({ categories, plugins }: ScoredReport): void;
 export declare function binaryIconPrefix(score: number, isBinary: boolean | undefined): string;

package/src/lib/reports/scoring.d.ts

@@ -1,5 +1,5 @@
-import { Report } from '@code-pushup/models';
-import { ScoredReport } from './types';
+import type { Report } from '@code-pushup/models';
+import type { ScoredReport } from './types';
 export declare class GroupRefInvalidError extends Error {
     constructor(auditSlug: string, pluginSlug: string);
 }

package/src/lib/reports/sorting.d.ts

@@ -1,5 +1,5 @@
-import { CategoryRef, Group } from '@code-pushup/models';
-import { ScoredReport, SortableAuditReport, SortableGroup } from './types';
+import type { CategoryRef, Group } from '@code-pushup/models';
+import type { ScoredReport, SortableAuditReport, SortableGroup } from './types';
 export declare function getSortableAuditByRef({ slug, weight, plugin }: CategoryRef, plugins: ScoredReport['plugins']): SortableAuditReport;
 export declare function getSortedGroupAudits(group: Group, plugin: string, plugins: ScoredReport['plugins']): SortableAuditReport[];
 export declare function getSortableGroupByRef({ plugin, slug, weight }: CategoryRef, plugins: ScoredReport['plugins']): SortableGroup;

package/src/lib/reports/types.d.ts

@@ -1,4 +1,4 @@
-import { AuditReport, CategoryConfig, Group, PluginReport, Report } from '@code-pushup/models';
+import type { AuditReport, CategoryConfig, Group, PersistConfig, PluginReport, Report } from '@code-pushup/models';
 export type ScoredCategoryConfig = CategoryConfig & {
     score: number;
 };
@@ -20,3 +20,5 @@ export type SortableAuditReport = AuditReport & {
     plugin: string;
 };
 export type DiffOutcome = 'positive' | 'negative' | 'mixed' | 'unchanged';
+export type MdReportOptions = Pick<PersistConfig, 'outputDir'>;
+export type IdeEnvironment = 'vscode' | 'github' | 'other';

package/src/lib/reports/utils.d.ts

@@ -1,7 +1,7 @@
-import { Ansis } from 'ansis';
-import { InlineText } from 'build-md';
-import { AuditDiff, AuditReport, CategoryRef, IssueSeverity as CliIssueSeverity, Issue } from '@code-pushup/models';
-import { ScoredReport, SortableAuditReport, SortableGroup } from './types';
+import { type Ansis } from 'ansis';
+import { type InlineText } from 'build-md';
+import type { AuditDiff, AuditReport, CategoryRef, IssueSeverity as CliIssueSeverity, Issue } from '@code-pushup/models';
+import type { ScoredReport, SortableAuditReport, SortableGroup } from './types';
 export declare function formatReportScore(score: number): string;
 export declare function formatScoreWithColor(score: number, options?: {
     skipBold?: boolean;
@@ -15,6 +15,7 @@ export declare function colorByScoreDiff(text: string, diff: number): InlineText
 export declare function shieldsBadge(text: string, color: string): InlineText;
 export declare function formatDiffNumber(diff: number): string;
 export declare function severityMarker(severity: 'info' | 'warning' | 'error'): string;
+export declare function roundValue(value: number): number;
 export declare function formatScoreChange(diff: number): InlineText;
 export declare function formatValueChange({ values, scores, }: Pick<AuditDiff, 'values' | 'scores'>): InlineText;
 export declare function calcDuration(start: number, stop?: number): number;

package/src/lib/text-formats/html/table.d.ts

@@ -1,2 +1,2 @@
-import { Table } from '@code-pushup/models';
+import type { Table } from '@code-pushup/models';
 export declare function table(tableData: Table): string;

package/src/lib/text-formats/table.d.ts

@@ -1,4 +1,4 @@
-import { Table, TableAlignment, TableColumnObject, TableColumnPrimitive } from '@code-pushup/models';
+import type { Table, TableAlignment, TableColumnObject, TableColumnPrimitive } from '@code-pushup/models';
 export declare function rowToStringArray({ rows, columns }: Table): string[][];
 export declare function columnsToStringArray({ rows, columns, }: Pick<Table, 'columns' | 'rows'>): string[];
 export declare function getColumnAlignmentForKeyAndIndex(targetKey: string, targetIdx: number, columns?: TableColumnObject[]): TableAlignment;

package/src/lib/types.d.ts

@@ -1,3 +1,12 @@
 export type ExcludeNullFromPropertyTypes<T> = {
     [P in keyof T]: Exclude<T[P], null>;
 };
+export type ItemOrArray<T> = T | T[];
+export type ExtractArray<T> = T extends Array<unknown> ? T : never;
+export type ExtractArrays<T extends Record<string, unknown>> = {
+    [K in keyof T]: ExtractArray<T[K]>;
+};
+export type WithRequired<T, K extends keyof T> = Prettify<Omit<T, K> & Required<Pick<T, K>>>;
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+};