@code-pushup/utils 0.35.0 → 0.42.0

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@code-pushup/utils",
-  "version": "0.35.0",
+  "version": "0.42.0",
   "dependencies": {
-    "@code-pushup/models": "0.35.0",
+    "@code-pushup/models": "0.42.0",
     "bundle-require": "^4.0.1",
+    "esbuild": "^0.19.2",
     "chalk": "^5.3.0",
     "@isaacs/cliui": "^8.0.2",
     "simple-git": "^3.20.0",
     "multi-progress-bars": "^5.0.3",
-    "@poppinss/cliui": "^6.4.0"
+    "@poppinss/cliui": "^6.4.0",
+    "semver": "^7.6.0"
   },
   "license": "MIT",
   "homepage": "https://github.com/code-pushup/cli#readme",
@@ -17,7 +19,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/code-pushup/cli.git",
+    "url": "git+https://github.com/code-pushup/cli.git",
     "directory": "packages/utils"
   },
   "contributors": [

package/src/index.d.ts

@@ -1,10 +1,13 @@
+export * from './lib/text-formats';
+export { ExcludeNullFromPropertyTypes } from './lib/types';
 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, findLineNumberInText, importEsmModule, logMultipleFileResults, pluginWorkDir, readJsonFile, readTextFile, removeDirectoryIfExists, } from './lib/file-system';
 export { filterItemRefsBy } from './lib/filter';
 export { formatBytes, formatDuration, pluralize, pluralizeToken, slugify, truncateDescription, truncateIssueMessage, truncateText, truncateTitle, } from './lib/formatting';
-export { formatGitPath, getCurrentBranchOrTag, getGitRoot, getLatestCommit, safeCheckout, toGitPath, } from './lib/git';
+export { formatGitPath, guardAgainstLocalChanges, getGitRoot, safeCheckout, toGitPath, } from './lib/git/git';
+export { getSemverTags, LogResult, getHashes, getHashFromTag, getCurrentBranchOrTag, getLatestCommit, } 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';
@@ -21,3 +24,4 @@ export { ScoredCategoryConfig, ScoredGroup, ScoredReport, } from './lib/reports/
 export { calcDuration, compareIssueSeverity, loadReport, } from './lib/reports/utils';
 export { CliArgsObject, apostrophize, capitalize, countOccurrences, distinct, factorOf, fromJsonLines, objectFromEntries, objectToCliArgs, objectToEntries, objectToKeys, toArray, toJsonLines, toNumberPrecision, toOrdinal, toUnixNewlines, toUnixPath, } from './lib/transform';
 export { verboseUtils } from './lib/verbose-utils';
+export { isSemver, normalizeSemver, sortSemvers } from './lib/semver';

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

@@ -0,0 +1,57 @@
+import { LogOptions as SimpleGitLogOptions } from 'simple-git';
+import { 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 = {
+    hash: string;
+    message: string;
+};
+export declare function filterLogs(allTags: string[], opt?: Pick<LogOptions, 'from' | 'to' | 'maxCount'>): string[];
+export declare function getHashFromTag(tag: string, git?: import("simple-git").SimpleGit): Promise<LogResult>;
+export type LogOptions = {
+    targetBranch?: string;
+    from?: string;
+    to?: string;
+    maxCount?: number;
+};
+export declare function getSemverTags(opt?: LogOptions, git?: import("simple-git").SimpleGit): Promise<LogResult[]>;
+/**
+ * `getHashes` returns a list of commit hashes. Internally it uses `git.log()` to determine the commits within a range.
+ * The amount can be limited to a maximum number of commits specified by `maxCount`.
+ * With `from` and `to`, you can specify a range of commits.
+ *
+ * **NOTE:**
+ * In Git, specifying a range with two dots (`from..to`) selects commits that are reachable from `to` but not from `from`.
+ * Essentially, it shows the commits that are in `to` but not in `from`, excluding the commits unique to `from`.
+ *
+ * Example:
+ *
+ * Let's consider the following commit history:
+ *
+ *   A---B---C---D---E (main)
+ *
+ * Using `git log B..D`, you would get the commits C and D:
+ *
+ *   C---D
+ *
+ * This is because these commits are reachable from D but not from B.
+ *
+ * ASCII Representation:
+ *
+ *   Main Branch:    A---B---C---D---E
+ *                       \       \
+ *                        \       +--- Commits included in `git log B..D`
+ *                         \
+ *                          +--- Excluded by the `from` parameter
+ *
+ * With `simple-git`, when you specify a `from` and `to` range like this:
+ *
+ *   git.log({ from: 'B', to: 'D' });
+ *
+ * It interprets it similarly, selecting commits between B and D, inclusive of D but exclusive of B.
+ * For `git.log({ from: 'B', to: 'D' })` or `git log B..D`, commits C and D are selected.
+ *
+ * @param options Object containing `from`, `to`, and optionally `maxCount` to specify the commit range and limit.
+ * @param git The `simple-git` instance used to execute Git commands.
+ */
+export declare function getHashes(options?: SimpleGitLogOptions & Pick<LogOptions, 'targetBranch'>, git?: import("simple-git").SimpleGit): Promise<LogResult[]>;

package/src/lib/{git.d.ts → git/git.d.ts}

@@ -1,8 +1,13 @@
-import { Commit } from '@code-pushup/models';
-export declare function getLatestCommit(git?: import("simple-git").SimpleGit): Promise<Commit | null>;
+import { 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>;
+export declare class GitStatusError extends Error {
+    static ignoredProps: Set<string>;
+    static getReducedStatus(status: StatusResult): {
+        [k: string]: any;
+    };
+    constructor(status: StatusResult);
+}
 export declare function guardAgainstLocalChanges(git?: import("simple-git").SimpleGit): Promise<void>;
-export declare function getCurrentBranchOrTag(git?: import("simple-git").SimpleGit): Promise<string>;
 export declare function safeCheckout(branchOrHash: string, forceCleanStatus?: boolean, git?: import("simple-git").SimpleGit): Promise<void>;

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

@@ -1,15 +1,35 @@
 export declare const TERMINAL_WIDTH = 80;
-export declare const NEW_LINE = "\n";
 export declare const SCORE_COLOR_RANGE: {
     GREEN_MIN: number;
     YELLOW_MIN: number;
 };
+export declare const CATEGORIES_TITLE = "\uD83C\uDFF7 Categories";
 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 README_LINK = "https://github.com/code-pushup/cli#readme";
 export declare const reportHeadlineText = "Code PushUp Report";
-export declare const reportOverviewTableHeaders: string[];
+export declare const reportOverviewTableHeaders: [{
+    readonly key: "category";
+    readonly label: "🏷 Category";
+    readonly align: "left";
+}, {
+    readonly key: "score";
+    readonly label: "⭐ Score";
+}, {
+    readonly key: "audits";
+    readonly label: "🛡 Audits";
+}];
 export declare const reportRawOverviewTableHeaders: string[];
-export declare const reportMetaTableHeaders: string[];
-export declare const pluginMetaTableHeaders: string[];
-export declare const detailsTableHeaders: string[];
+export declare const issuesTableHeadings: [{
+    readonly key: "severity";
+    readonly label: "Severity";
+}, {
+    readonly key: "message";
+    readonly label: "Message";
+}, {
+    readonly key: "file";
+    readonly label: "Source file";
+}, {
+    readonly key: "line";
+    readonly label: "Line(s)";
+}];

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

@@ -0,0 +1,6 @@
+import { AuditReport, Table } from '@code-pushup/models';
+import { Hierarchy } from '../text-formats';
+export declare function tableSection(tableData: Table, options?: {
+    level?: Hierarchy | 0;
+}): string;
+export declare function metaDescription({ docsUrl, description, }: Pick<AuditReport, 'docsUrl' | 'description'>): string;

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

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

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

@@ -1,2 +1,10 @@
+import { AuditReport, Issue, Report, Table } from '@code-pushup/models';
 import { ScoredReport } from './types';
+export declare function auditDetailsAuditValue({ score, value, displayValue, }: AuditReport): string;
 export declare function generateMdReport(report: ScoredReport): string;
+export declare function auditDetailsIssues(issues?: Issue[]): string;
+export declare function auditDetails(audit: AuditReport): string;
+export declare function auditsSection({ plugins, }: Pick<ScoredReport, 'plugins'>): string;
+export declare function aboutSection(report: Omit<ScoredReport, 'packageName'>): string;
+export declare function reportPluginMeta({ plugins }: Pick<Report, 'plugins'>): Table;
+export declare function reportMetaData({ commit, version, duration, plugins, categories, }: Pick<ScoredReport, 'date' | 'duration' | 'version' | 'commit' | 'plugins' | 'categories'>): Table;

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

@@ -4,13 +4,15 @@ export declare function formatReportScore(score: number): string;
 export declare function formatScoreWithColor(score: number, options?: {
     skipBold?: boolean;
 }): string;
-export declare function getRoundScoreMarker(score: number): string;
-export declare function getSquaredScoreMarker(score: number): string;
+export type MarkerShape = 'circle' | 'square';
+export type ScoreColors = 'red' | 'yellow' | 'green';
+export declare const MARKERS: Record<MarkerShape, Record<ScoreColors, string>>;
+export declare function scoreMarker(score: number, markerType?: MarkerShape): string;
 export declare function getDiffMarker(diff: number): string;
 export declare function colorByScoreDiff(text: string, diff: number): string;
 export declare function shieldsBadge(text: string, color: string): string;
 export declare function formatDiffNumber(diff: number): string;
-export declare function getSeverityIcon(severity: 'info' | 'warning' | 'error'): string;
+export declare function severityMarker(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;

package/src/lib/semver.d.ts

@@ -0,0 +1,3 @@
+export declare function normalizeSemver(semverString: string): string;
+export declare function isSemver(semverString?: string): boolean;
+export declare function sortSemvers(semverStrings: string[]): string[];

package/src/lib/table.d.ts

@@ -0,0 +1,6 @@
+import { Table, TableAlignment, TableColumnObject, TableColumnPrimitive } from '@code-pushup/models';
+export declare function rowToStringArray({ rows, columns }: Table): string[][];
+export declare function columnsToStringArray({ rows, columns }: Table): string[];
+export declare function getColumnAlignmentForKeyAndIndex(targetKey: string, targetIdx: number, columns?: TableColumnObject[]): TableAlignment;
+export declare function getColumnAlignmentForIndex(targetIdx: number, columns?: TableColumnPrimitive[]): TableAlignment;
+export declare function getColumnAlignments({ rows, columns, }: Table): TableAlignment[];

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

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

package/src/lib/{reports/md → text-formats/html}/details.d.ts

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

package/src/lib/text-formats/html/font-style.d.ts

@@ -0,0 +1,3 @@
+export declare function bold(text: string): string;
+export declare function italic(text: string): string;
+export declare function code(text: string): string;

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

@@ -0,0 +1 @@
+export declare function link(href: string, text?: string): string;

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

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

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

@@ -0,0 +1,44 @@
+import { details } from './html/details';
+import { bold as boldHtml, code as codeHtml, italic as italicHtml } from './html/font-style';
+import { link as linkHtml } from './html/link';
+import { table as tableHtml } from './html/table';
+import { bold as boldMd, code as codeMd, italic as italicMd, strikeThrough as strikeThroughMd } from './md/font-style';
+import { h, h1, h2, h3, h4, h5, h6, headline } from './md/headline';
+import { image } from './md/image';
+import { link as linkMd } from './md/link';
+import { indentation, li } from './md/list';
+import { paragraphs } from './md/paragraphs';
+import { lines, section } from './md/section';
+import { table as tableMd } from './md/table';
+export { NEW_LINE, SPACE, TAB } from './constants';
+export { Hierarchy } from './types';
+export declare const md: {
+    bold: typeof boldMd;
+    italic: typeof italicMd;
+    strikeThrough: typeof strikeThroughMd;
+    code: typeof codeMd;
+    link: typeof linkMd;
+    image: typeof image;
+    headline: typeof headline;
+    h: typeof h;
+    h1: typeof h1;
+    h2: typeof h2;
+    h3: typeof h3;
+    h4: typeof h4;
+    h5: typeof h5;
+    h6: typeof h6;
+    indentation: typeof indentation;
+    lines: typeof lines;
+    li: typeof li;
+    section: typeof section;
+    paragraphs: typeof paragraphs;
+    table: typeof tableMd;
+};
+export declare const html: {
+    bold: typeof boldHtml;
+    italic: typeof italicHtml;
+    code: typeof codeHtml;
+    link: typeof linkHtml;
+    details: typeof details;
+    table: typeof tableHtml;
+};

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

@@ -0,0 +1,4 @@
+export declare function bold(text: string): string;
+export declare function italic(text: string): string;
+export declare function strikeThrough(text: string): string;
+export declare function code(text: string): string;

package/src/lib/{reports → text-formats}/md/headline.d.ts

@@ -1,4 +1,4 @@
-export type Hierarchy = 1 | 2 | 3 | 4 | 5 | 6;
+import { Hierarchy } from '../types';
 /**
  * \# {text} // hierarchy set to 1
  *

package/src/lib/text-formats/md/link.d.ts

@@ -0,0 +1 @@
+export declare function link(href: string, text?: string): string;

package/src/lib/{reports → text-formats}/md/list.d.ts

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

package/src/lib/text-formats/md/section.d.ts

@@ -0,0 +1,2 @@
+export declare function section(...contents: (string | undefined | boolean)[]): string;
+export declare function lines(...contents: (string | undefined | boolean)[]): string;

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

@@ -0,0 +1,9 @@
+import { Table } from '@code-pushup/models';
+/**
+ * | Table Header 1  | Table Header 2 |
+ * | :-------------- | -------------: |
+ * |  String 1       |  1             |
+ * |  String 1       |  2             |
+ * |  String 1       |  3             |
+ */
+export declare function table(data: Table): string;

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

@@ -0,0 +1,6 @@
+import { Table, TableAlignment, TableColumnObject, TableColumnPrimitive } from '@code-pushup/models';
+export declare function rowToStringArray({ rows, columns }: Table): string[][];
+export declare function columnsToStringArray({ rows, columns }: Table): string[];
+export declare function getColumnAlignmentForKeyAndIndex(targetKey: string, targetIdx: number, columns?: TableColumnObject[]): TableAlignment;
+export declare function getColumnAlignmentForIndex(targetIdx: number, columns?: TableColumnPrimitive[]): TableAlignment;
+export declare function getColumnAlignments({ rows, columns, }: Table): TableAlignment[];

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

@@ -0,0 +1 @@
+export type Hierarchy = 1 | 2 | 3 | 4 | 5 | 6;

package/src/lib/types.d.ts

@@ -0,0 +1,3 @@
+export type ExcludeNullFromPropertyTypes<T> = {
+    [P in keyof T]: Exclude<T[P], null>;
+};

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

@@ -1,16 +0,0 @@
-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/reports/md/index.d.ts

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

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

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

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

@@ -1,10 +0,0 @@
-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;