@code-pushup/utils 0.50.0 → 0.51.0

package/index.js

@@ -155,9 +155,27 @@ function hasNonZeroWeightedRef(refs) {
   return refs.reduce((acc, { weight }) => weight + acc, 0) !== 0;
 }
 
-// packages/models/src/lib/audit.ts
+// packages/models/src/lib/source.ts
 import { z as z2 } from "zod";
-var auditSchema = z2.object({
+var sourceFileLocationSchema = z2.object(
+  {
+    file: filePathSchema.describe("Relative path to source file in Git repo"),
+    position: z2.object(
+      {
+        startLine: positiveIntSchema.describe("Start line"),
+        startColumn: positiveIntSchema.describe("Start column").optional(),
+        endLine: positiveIntSchema.describe("End line").optional(),
+        endColumn: positiveIntSchema.describe("End column").optional()
+      },
+      { description: "Location in file" }
+    ).optional()
+  },
+  { description: "Source file location" }
+);
+
+// packages/models/src/lib/audit.ts
+import { z as z3 } from "zod";
+var auditSchema = z3.object({
   slug: slugSchema.describe("ID (unique within plugin)")
 }).merge(
   metaSchema({
@@ -167,7 +185,7 @@ var auditSchema = z2.object({
     description: "List of scorable metrics for the given plugin"
   })
 );
-var pluginAuditsSchema = z2.array(auditSchema, {
+var pluginAuditsSchema = z3.array(auditSchema, {
   description: "List of audits maintained in a plugin"
 }).min(1).refine(
   (auditMetadata) => !getDuplicateSlugsInAudits(auditMetadata),
@@ -186,31 +204,16 @@ function getDuplicateSlugsInAudits(audits) {
 }
 
 // packages/models/src/lib/audit-output.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 
 // packages/models/src/lib/issue.ts
-import { z as z3 } from "zod";
-var sourceFileLocationSchema = z3.object(
-  {
-    file: filePathSchema.describe("Relative path to source file in Git repo"),
-    position: z3.object(
-      {
-        startLine: positiveIntSchema.describe("Start line"),
-        startColumn: positiveIntSchema.describe("Start column").optional(),
-        endLine: positiveIntSchema.describe("End line").optional(),
-        endColumn: positiveIntSchema.describe("End column").optional()
-      },
-      { description: "Location in file" }
-    ).optional()
-  },
-  { description: "Source file location" }
-);
-var issueSeveritySchema = z3.enum(["info", "warning", "error"], {
+import { z as z4 } from "zod";
+var issueSeveritySchema = z4.enum(["info", "warning", "error"], {
   description: "Severity level"
 });
-var issueSchema = z3.object(
+var issueSchema = z4.object(
   {
-    message: z3.string({ description: "Descriptive error message" }).max(MAX_ISSUE_MESSAGE_LENGTH),
+    message: z4.string({ description: "Descriptive error message" }).max(MAX_ISSUE_MESSAGE_LENGTH),
     severity: issueSeveritySchema,
     source: sourceFileLocationSchema.optional()
   },
@@ -218,60 +221,60 @@ var issueSchema = z3.object(
 );
 
 // packages/models/src/lib/table.ts
-import { z as z4 } from "zod";
-var tableAlignmentSchema = z4.enum(["left", "center", "right"], {
+import { z as z5 } from "zod";
+var tableAlignmentSchema = z5.enum(["left", "center", "right"], {
   description: "Cell alignment"
 });
-var tableColumnObjectSchema = z4.object({
-  key: z4.string(),
-  label: z4.string().optional(),
+var tableColumnObjectSchema = z5.object({
+  key: z5.string(),
+  label: z5.string().optional(),
   align: tableAlignmentSchema.optional()
 });
-var tableRowObjectSchema = z4.record(tableCellValueSchema, {
+var tableRowObjectSchema = z5.record(tableCellValueSchema, {
   description: "Object row"
 });
-var tableRowPrimitiveSchema = z4.array(tableCellValueSchema, {
+var tableRowPrimitiveSchema = z5.array(tableCellValueSchema, {
   description: "Primitive row"
 });
-var tableSharedSchema = z4.object({
-  title: z4.string().optional().describe("Display title for table")
+var tableSharedSchema = z5.object({
+  title: z5.string().optional().describe("Display title for table")
 });
 var tablePrimitiveSchema = tableSharedSchema.merge(
-  z4.object(
+  z5.object(
     {
-      columns: z4.array(tableAlignmentSchema).optional(),
-      rows: z4.array(tableRowPrimitiveSchema)
+      columns: z5.array(tableAlignmentSchema).optional(),
+      rows: z5.array(tableRowPrimitiveSchema)
     },
     { description: "Table with primitive rows and optional alignment columns" }
   )
 );
 var tableObjectSchema = tableSharedSchema.merge(
-  z4.object(
+  z5.object(
     {
-      columns: z4.union([
-        z4.array(tableAlignmentSchema),
-        z4.array(tableColumnObjectSchema)
+      columns: z5.union([
+        z5.array(tableAlignmentSchema),
+        z5.array(tableColumnObjectSchema)
       ]).optional(),
-      rows: z4.array(tableRowObjectSchema)
+      rows: z5.array(tableRowObjectSchema)
     },
     {
       description: "Table with object rows and optional alignment or object columns"
     }
   )
 );
-var tableSchema = (description = "Table information") => z4.union([tablePrimitiveSchema, tableObjectSchema], { description });
+var tableSchema = (description = "Table information") => z5.union([tablePrimitiveSchema, tableObjectSchema], { description });
 
 // packages/models/src/lib/audit-output.ts
 var auditValueSchema = nonnegativeNumberSchema.describe("Raw numeric value");
-var auditDisplayValueSchema = z5.string({ description: "Formatted value (e.g. '0.9 s', '2.1 MB')" }).optional();
-var auditDetailsSchema = z5.object(
+var auditDisplayValueSchema = z6.string({ description: "Formatted value (e.g. '0.9 s', '2.1 MB')" }).optional();
+var auditDetailsSchema = z6.object(
   {
-    issues: z5.array(issueSchema, { description: "List of findings" }).optional(),
+    issues: z6.array(issueSchema, { description: "List of findings" }).optional(),
     table: tableSchema("Table of related findings").optional()
   },
   { description: "Detailed information" }
 );
-var auditOutputSchema = z5.object(
+var auditOutputSchema = z6.object(
   {
     slug: slugSchema.describe("Reference to audit"),
     displayValue: auditDisplayValueSchema,
@@ -281,7 +284,7 @@ var auditOutputSchema = z5.object(
   },
   { description: "Audit information" }
 );
-var auditOutputsSchema = z5.array(auditOutputSchema, {
+var auditOutputsSchema = z6.array(auditOutputSchema, {
   description: "List of JSON formatted audit output emitted by the runner process of a plugin"
 }).refine(
   (audits) => !getDuplicateSlugsInAudits2(audits),
@@ -298,13 +301,13 @@ function getDuplicateSlugsInAudits2(audits) {
 }
 
 // packages/models/src/lib/category-config.ts
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 var categoryRefSchema = weightedRefSchema(
   "Weighted references to audits and/or groups for the category",
   "Slug of an audit or group (depending on `type`)"
 ).merge(
-  z6.object({
-    type: z6.enum(["audit", "group"], {
+  z7.object({
+    type: z7.enum(["audit", "group"], {
       description: "Discriminant for reference kind, affects where `slug` is looked up"
     }),
     plugin: slugSchema.describe(
@@ -325,8 +328,8 @@ var categoryConfigSchema = scorableSchema(
     description: "Meta info for category"
   })
 ).merge(
-  z6.object({
-    isBinary: z6.boolean({
+  z7.object({
+    isBinary: z7.boolean({
       description: 'Is this a binary category (i.e. only a perfect score considered a "pass")?'
     }).optional()
   })
@@ -342,7 +345,7 @@ function getDuplicateRefsInCategoryMetrics(metrics) {
     metrics.map(({ slug, type, plugin }) => `${type} :: ${plugin} / ${slug}`)
   );
 }
-var categoriesSchema = z6.array(categoryConfigSchema, {
+var categoriesSchema = z7.array(categoryConfigSchema, {
   description: "Categorization of individual audits"
 }).refine(
   (categoryCfg) => !getDuplicateSlugCategories(categoryCfg),
@@ -361,18 +364,18 @@ function getDuplicateSlugCategories(categories) {
 }
 
 // packages/models/src/lib/commit.ts
-import { z as z7 } from "zod";
-var commitSchema = z7.object(
+import { z as z8 } from "zod";
+var commitSchema = z8.object(
   {
-    hash: z7.string({ description: "Commit SHA (full)" }).regex(
+    hash: z8.string({ description: "Commit SHA (full)" }).regex(
       /^[\da-f]{40}$/,
       "Commit SHA should be a 40-character hexadecimal string"
     ),
-    message: z7.string({ description: "Commit message" }),
-    date: z7.coerce.date({
+    message: z8.string({ description: "Commit message" }),
+    date: z8.coerce.date({
       description: "Date and time when commit was authored"
     }),
-    author: z7.string({
+    author: z8.string({
       description: "Commit author name"
     }).trim()
   },
@@ -380,22 +383,22 @@ var commitSchema = z7.object(
 );
 
 // packages/models/src/lib/core-config.ts
-import { z as z13 } from "zod";
+import { z as z14 } from "zod";
 
 // packages/models/src/lib/persist-config.ts
-import { z as z8 } from "zod";
-var formatSchema = z8.enum(["json", "md"]);
-var persistConfigSchema = z8.object({
+import { z as z9 } from "zod";
+var formatSchema = z9.enum(["json", "md"]);
+var persistConfigSchema = z9.object({
   outputDir: filePathSchema.describe("Artifacts folder").optional(),
   filename: fileNameSchema.describe("Artifacts file name (without extension)").optional(),
-  format: z8.array(formatSchema).optional()
+  format: z9.array(formatSchema).optional()
 });
 
 // packages/models/src/lib/plugin-config.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 
 // packages/models/src/lib/group.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 var groupRefSchema = weightedRefSchema(
   "Weighted reference to a group",
   "Reference slug to a group within this plugin (e.g. 'max-lines')"
@@ -412,7 +415,7 @@ var groupSchema = scorableSchema(
   getDuplicateRefsInGroups,
   duplicateRefsInGroupsErrorMsg
 ).merge(groupMetaSchema);
-var groupsSchema = z9.array(groupSchema, {
+var groupsSchema = z10.array(groupSchema, {
   description: "List of groups"
 }).optional().refine(
   (groups) => !getDuplicateSlugsInGroups(groups),
@@ -440,14 +443,14 @@ function getDuplicateSlugsInGroups(groups) {
 }
 
 // packages/models/src/lib/runner-config.ts
-import { z as z10 } from "zod";
-var outputTransformSchema = z10.function().args(z10.unknown()).returns(z10.union([auditOutputsSchema, z10.promise(auditOutputsSchema)]));
-var runnerConfigSchema = z10.object(
+import { z as z11 } from "zod";
+var outputTransformSchema = z11.function().args(z11.unknown()).returns(z11.union([auditOutputsSchema, z11.promise(auditOutputsSchema)]));
+var runnerConfigSchema = z11.object(
   {
-    command: z10.string({
+    command: z11.string({
       description: "Shell command to execute"
     }),
-    args: z10.array(z10.string({ description: "Command arguments" })).optional(),
+    args: z11.array(z11.string({ description: "Command arguments" })).optional(),
     outputFile: filePathSchema.describe("Output path"),
     outputTransform: outputTransformSchema.optional()
   },
@@ -455,8 +458,8 @@ var runnerConfigSchema = z10.object(
     description: "How to execute runner"
   }
 );
-var onProgressSchema = z10.function().args(z10.unknown()).returns(z10.void());
-var runnerFunctionSchema = z10.function().args(onProgressSchema.optional()).returns(z10.union([auditOutputsSchema, z10.promise(auditOutputsSchema)]));
+var onProgressSchema = z11.function().args(z11.unknown()).returns(z11.void());
+var runnerFunctionSchema = z11.function().args(onProgressSchema.optional()).returns(z11.union([auditOutputsSchema, z11.promise(auditOutputsSchema)]));
 
 // packages/models/src/lib/plugin-config.ts
 var pluginMetaSchema = packageVersionSchema().merge(
@@ -467,13 +470,13 @@ var pluginMetaSchema = packageVersionSchema().merge(
     description: "Plugin metadata"
   })
 ).merge(
-  z11.object({
+  z12.object({
     slug: slugSchema.describe("Unique plugin slug within core config"),
     icon: materialIconSchema
   })
 );
-var pluginDataSchema = z11.object({
-  runner: z11.union([runnerConfigSchema, runnerFunctionSchema]),
+var pluginDataSchema = z12.object({
+  runner: z12.union([runnerConfigSchema, runnerFunctionSchema]),
   audits: pluginAuditsSchema,
   groups: groupsSchema
 });
@@ -499,22 +502,22 @@ function getMissingRefsFromGroups(pluginCfg) {
 }
 
 // packages/models/src/lib/upload-config.ts
-import { z as z12 } from "zod";
-var uploadConfigSchema = z12.object({
+import { z as z13 } from "zod";
+var uploadConfigSchema = z13.object({
   server: urlSchema.describe("URL of deployed portal API"),
-  apiKey: z12.string({
+  apiKey: z13.string({
     description: "API key with write access to portal (use `process.env` for security)"
   }),
   organization: slugSchema.describe(
     "Organization slug from Code PushUp portal"
   ),
   project: slugSchema.describe("Project slug from Code PushUp portal"),
-  timeout: z12.number({ description: "Request timeout in minutes (default is 5)" }).positive().int().optional()
+  timeout: z13.number({ description: "Request timeout in minutes (default is 5)" }).positive().int().optional()
 });
 
 // packages/models/src/lib/core-config.ts
-var unrefinedCoreConfigSchema = z13.object({
-  plugins: z13.array(pluginConfigSchema, {
+var unrefinedCoreConfigSchema = z14.object({
+  plugins: z14.array(pluginConfigSchema, {
     description: "List of plugins to be used (official, community-provided, or custom)"
   }).min(1),
   /** portal configuration for persisting results */
@@ -537,7 +540,7 @@ function refineCoreConfig(schema) {
 }
 
 // packages/models/src/lib/report.ts
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 var auditReportSchema = auditSchema.merge(auditOutputSchema);
 var pluginReportSchema = pluginMetaSchema.merge(
   executionMetaSchema({
@@ -545,9 +548,9 @@ var pluginReportSchema = pluginMetaSchema.merge(
     descriptionDuration: "Duration of the plugin run in ms"
   })
 ).merge(
-  z14.object({
-    audits: z14.array(auditReportSchema).min(1),
-    groups: z14.array(groupSchema).optional()
+  z15.object({
+    audits: z15.array(auditReportSchema).min(1),
+    groups: z15.array(groupSchema).optional()
   })
 ).refine(
   (pluginReport) => !getMissingRefsFromGroups2(pluginReport.audits, pluginReport.groups ?? []),
@@ -581,10 +584,10 @@ var reportSchema = packageVersionSchema({
     descriptionDuration: "Duration of the collect run in ms"
   })
 ).merge(
-  z14.object(
+  z15.object(
     {
-      categories: z14.array(categoryConfigSchema),
-      plugins: z14.array(pluginReportSchema).min(1),
+      categories: z15.array(categoryConfigSchema),
+      plugins: z15.array(pluginReportSchema).min(1),
       commit: commitSchema.describe("Git commit for which report was collected").nullable()
     },
     { description: "Collect output data" }
@@ -600,40 +603,40 @@ var reportSchema = packageVersionSchema({
 );
 
 // packages/models/src/lib/reports-diff.ts
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 function makeComparisonSchema(schema) {
   const sharedDescription = schema.description || "Result";
-  return z15.object({
+  return z16.object({
     before: schema.describe(`${sharedDescription} (source commit)`),
     after: schema.describe(`${sharedDescription} (target commit)`)
   });
 }
 function makeArraysComparisonSchema(diffSchema, resultSchema, description) {
-  return z15.object(
+  return z16.object(
     {
-      changed: z15.array(diffSchema),
-      unchanged: z15.array(resultSchema),
-      added: z15.array(resultSchema),
-      removed: z15.array(resultSchema)
+      changed: z16.array(diffSchema),
+      unchanged: z16.array(resultSchema),
+      added: z16.array(resultSchema),
+      removed: z16.array(resultSchema)
     },
     { description }
   );
 }
-var scorableMetaSchema = z15.object({
+var scorableMetaSchema = z16.object({
   slug: slugSchema,
   title: titleSchema,
   docsUrl: docsUrlSchema
 });
 var scorableWithPluginMetaSchema = scorableMetaSchema.merge(
-  z15.object({
+  z16.object({
     plugin: pluginMetaSchema.pick({ slug: true, title: true, docsUrl: true }).describe("Plugin which defines it")
   })
 );
 var scorableDiffSchema = scorableMetaSchema.merge(
-  z15.object({
+  z16.object({
     scores: makeComparisonSchema(scoreSchema).merge(
-      z15.object({
-        diff: z15.number().min(-1).max(1).describe("Score change (`scores.after - scores.before`)")
+      z16.object({
+        diff: z16.number().min(-1).max(1).describe("Score change (`scores.after - scores.before`)")
       })
     ).describe("Score comparison")
   })
@@ -644,10 +647,10 @@ var scorableWithPluginDiffSchema = scorableDiffSchema.merge(
 var categoryDiffSchema = scorableDiffSchema;
 var groupDiffSchema = scorableWithPluginDiffSchema;
 var auditDiffSchema = scorableWithPluginDiffSchema.merge(
-  z15.object({
+  z16.object({
     values: makeComparisonSchema(auditValueSchema).merge(
-      z15.object({
-        diff: z15.number().int().describe("Value change (`values.after - values.before`)")
+      z16.object({
+        diff: z16.number().int().describe("Value change (`values.after - values.before`)")
       })
     ).describe("Audit `value` comparison"),
     displayValues: makeComparisonSchema(auditDisplayValueSchema).describe(
@@ -656,18 +659,18 @@ var auditDiffSchema = scorableWithPluginDiffSchema.merge(
   })
 );
 var categoryResultSchema = scorableMetaSchema.merge(
-  z15.object({ score: scoreSchema })
+  z16.object({ score: scoreSchema })
 );
 var groupResultSchema = scorableWithPluginMetaSchema.merge(
-  z15.object({ score: scoreSchema })
+  z16.object({ score: scoreSchema })
 );
 var auditResultSchema = scorableWithPluginMetaSchema.merge(
   auditOutputSchema.pick({ score: true, value: true, displayValue: true })
 );
-var reportsDiffSchema = z15.object({
+var reportsDiffSchema = z16.object({
   commits: makeComparisonSchema(commitSchema).nullable().describe("Commits identifying compared reports"),
   portalUrl: urlSchema.optional().describe("Link to comparison page in Code PushUp portal"),
-  label: z15.string().optional().describe("Label (e.g. project name)"),
+  label: z16.string().optional().describe("Label (e.g. project name)"),
   categories: makeArraysComparisonSchema(
     categoryDiffSchema,
     categoryResultSchema,
@@ -770,6 +773,7 @@ var FOOTER_PREFIX = "Made with \u2764 by";
 var CODE_PUSHUP_DOMAIN = "code-pushup.dev";
 var README_LINK = "https://github.com/code-pushup/cli#readme";
 var REPORT_HEADLINE_TEXT = "Code PushUp Report";
+var CODE_PUSHUP_UNICODE_LOGO = "<\u2713>";
 var REPORT_RAW_OVERVIEW_TABLE_HEADERS = [
   "Category",
   "Score",
@@ -840,9 +844,17 @@ function severityMarker(severity) {
   }
   return "\u2139\uFE0F";
 }
+var MIN_NON_ZERO_RESULT = 0.1;
+function roundValue(value) {
+  const roundedValue = Math.round(value * 10) / 10;
+  if (roundedValue === 0 && value !== 0) {
+    return MIN_NON_ZERO_RESULT * Math.sign(value);
+  }
+  return roundedValue;
+}
 function formatScoreChange(diff) {
   const marker = getDiffMarker(diff);
-  const text = formatDiffNumber(Math.round(diff * 1e3) / 10);
+  const text = formatDiffNumber(roundValue(diff * 100));
   return colorByScoreDiff(`${marker} ${text}`, diff);
 }
 function formatValueChange({
@@ -850,7 +862,7 @@ function formatValueChange({
   scores
 }) {
   const marker = getDiffMarker(values.diff);
-  const percentage = values.before === 0 ? values.diff > 0 ? Number.POSITIVE_INFINITY : Number.NEGATIVE_INFINITY : Math.round(100 * values.diff / values.before);
+  const percentage = values.before === 0 ? values.diff > 0 ? Number.POSITIVE_INFINITY : Number.NEGATIVE_INFINITY : roundValue(values.diff / values.before * 100);
   const text = `${formatDiffNumber(percentage)}\u2009%`;
   return colorByScoreDiff(`${marker} ${text}`, scores.diff);
 }
@@ -1907,6 +1919,29 @@ import {
   MarkdownDocument,
   md as md2
 } from "build-md";
+import { posix as pathPosix } from "node:path";
+
+// packages/utils/src/lib/reports/ide-environment.ts
+function getEnvironmentType() {
+  if (isVSCode()) {
+    return "vscode";
+  }
+  if (isGitHub()) {
+    return "github";
+  }
+  return "other";
+}
+function isVSCode() {
+  return process.env["TERM_PROGRAM"] === "vscode";
+}
+function isGitHub() {
+  return process.env["GITHUB_ACTIONS"] === "true";
+}
+function getGitHubBaseUrl() {
+  return `${process.env["GITHUB_SERVER_URL"]}/${process.env["GITHUB_REPOSITORY"]}/blob/${process.env["GITHUB_SHA"]}`;
+}
+
+// packages/utils/src/lib/reports/formatting.ts
 function tableSection(tableData, options) {
   if (tableData.rows.length === 0) {
     return null;
@@ -1944,6 +1979,44 @@ function metaDescription(audit) {
   }
   return "";
 }
+function linkToLocalSourceForIde(source, options) {
+  const { file, position } = source;
+  const { outputDir } = options ?? {};
+  if (!outputDir) {
+    return md2.code(file);
+  }
+  return md2.link(formatFileLink(file, position, outputDir), md2.code(file));
+}
+function formatSourceLine(position) {
+  if (!position) {
+    return "";
+  }
+  const { startLine, endLine } = position;
+  return endLine && startLine !== endLine ? `${startLine}-${endLine}` : `${startLine}`;
+}
+function formatGitHubLink(file, position) {
+  const baseUrl = getGitHubBaseUrl();
+  if (!position) {
+    return `${baseUrl}/${file}`;
+  }
+  const { startLine, endLine, startColumn, endColumn } = position;
+  const start = startColumn ? `L${startLine}C${startColumn}` : `L${startLine}`;
+  const end = endLine ? endColumn ? `L${endLine}C${endColumn}` : `L${endLine}` : "";
+  const lineRange = end && start !== end ? `${start}-${end}` : start;
+  return `${baseUrl}/${file}#${lineRange}`;
+}
+function formatFileLink(file, position, outputDir) {
+  const relativePath = pathPosix.relative(outputDir, file);
+  const env = getEnvironmentType();
+  switch (env) {
+    case "vscode":
+      return position ? `${relativePath}#L${position.startLine}` : relativePath;
+    case "github":
+      return formatGitHubLink(file, position);
+    default:
+      return relativePath;
+  }
+}
 
 // packages/utils/src/lib/reports/generate-md-report-categoy-section.ts
 import { MarkdownDocument as MarkdownDocument2, md as md3 } from "build-md";
@@ -2145,16 +2218,16 @@ function auditDetailsAuditValue({
     String(displayValue ?? value)
   )} (score: ${formatReportScore(score)})`;
 }
-function generateMdReport(report) {
+function generateMdReport(report, options) {
   return new MarkdownDocument3().heading(HIERARCHY.level_1, REPORT_HEADLINE_TEXT).$if(
     report.categories.length > 0,
     (doc) => doc.$concat(
       categoriesOverviewSection(report),
       categoriesDetailsSection(report)
     )
-  ).$concat(auditsSection(report), aboutSection(report)).rule().paragraph(md4`${FOOTER_PREFIX} ${md4.link(README_LINK, "Code PushUp")}`).toString();
+  ).$concat(auditsSection(report, options), aboutSection(report)).rule().paragraph(md4`${FOOTER_PREFIX} ${md4.link(README_LINK, "Code PushUp")}`).toString();
 }
-function auditDetailsIssues(issues = []) {
+function auditDetailsIssues(issues = [], options) {
   if (issues.length === 0) {
     return null;
   }
@@ -2170,39 +2243,36 @@ function auditDetailsIssues(issues = []) {
       if (!source) {
         return [severity, message];
       }
-      const file = md4.code(source.file);
+      const file = linkToLocalSourceForIde(source, options);
       if (!source.position) {
         return [severity, message, file];
       }
-      const { startLine, endLine } = source.position;
-      const line = `${startLine || ""}${endLine && startLine !== endLine ? `-${endLine}` : ""}`;
+      const line = formatSourceLine(source.position);
       return [severity, message, file, line];
     })
   );
 }
-function auditDetails(audit) {
+function auditDetails(audit, options) {
   const { table: table2, issues = [] } = audit.details ?? {};
   const detailsValue = auditDetailsAuditValue(audit);
   if (issues.length === 0 && !table2?.rows.length) {
     return new MarkdownDocument3().paragraph(detailsValue);
   }
   const tableSectionContent = table2 && tableSection(table2);
-  const issuesSectionContent = issues.length > 0 && auditDetailsIssues(issues);
+  const issuesSectionContent = issues.length > 0 && auditDetailsIssues(issues, options);
   return new MarkdownDocument3().details(
     detailsValue,
     new MarkdownDocument3().$concat(tableSectionContent, issuesSectionContent)
   );
 }
-function auditsSection({
-  plugins
-}) {
+function auditsSection({ plugins }, options) {
   return new MarkdownDocument3().heading(HIERARCHY.level_2, "\u{1F6E1}\uFE0F Audits").$foreach(
     plugins.flatMap(
       (plugin) => plugin.audits.map((audit) => ({ ...audit, plugin }))
     ),
     (doc, { plugin, ...audit }) => {
       const auditTitle = `${audit.title} (${plugin.title})`;
-      const detailsContent = auditDetails(audit);
+      const detailsContent = auditDetails(audit, options);
       const descriptionContent = metaDescription(audit);
       return doc.heading(HIERARCHY.level_3, auditTitle).$concat(detailsContent).paragraph(descriptionContent);
     }
@@ -2464,15 +2534,6 @@ function createDiffCategoriesSection(diff, options) {
 function createCategoriesTable(diff, options) {
   const { changed, unchanged, added } = diff.categories;
   const { hasChanges, skipUnchanged } = options;
-  const columns = [
-    { heading: "\u{1F3F7}\uFE0F Category", alignment: "left" },
-    {
-      heading: hasChanges ? "\u2B50 Previous score" : "\u2B50 Score",
-      alignment: "center"
-    },
-    { heading: "\u2B50 Current score", alignment: "center" },
-    { heading: "\u{1F504} Score change", alignment: "center" }
-  ];
   const rows = [
     ...sortChanges(changed).map((category) => [
       formatTitle(category),
@@ -2495,6 +2556,18 @@ function createCategoriesTable(diff, options) {
       "\u2013"
     ])
   ];
+  if (rows.length === 0) {
+    return [[], []];
+  }
+  const columns = [
+    { heading: "\u{1F3F7}\uFE0F Category", alignment: "left" },
+    {
+      heading: hasChanges ? "\u2B50 Previous score" : "\u2B50 Score",
+      alignment: "center"
+    },
+    { heading: "\u2B50 Current score", alignment: "center" },
+    { heading: "\u{1F504} Score change", alignment: "center" }
+  ];
   return [
     hasChanges ? columns : columns.slice(0, 2),
     rows.map((row) => hasChanges ? row : row.slice(0, 2))
@@ -2774,6 +2847,7 @@ var verboseUtils = (verbose = false) => ({
 });
 export {
   CODE_PUSHUP_DOMAIN,
+  CODE_PUSHUP_UNICODE_LOGO,
   FOOTER_PREFIX,
   HIERARCHY,
   NEW_LINE,

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@code-pushup/utils",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "description": "Low-level utilities (helper functions, etc.) used by Code PushUp CLI",
   "dependencies": {
-    "@code-pushup/models": "0.50.0",
+    "@code-pushup/models": "0.51.0",
     "@isaacs/cliui": "^8.0.2",
     "@poppinss/cliui": "^6.4.0",
     "ansis": "^3.3.0",

package/src/index.d.ts

@@ -1,19 +1,19 @@
 export { exists } from '@code-pushup/models';
-export { type Diff, comparePairs, matchArrayItemsByKey } from './lib/diff';
+export { comparePairs, matchArrayItemsByKey, type Diff } from './lib/diff';
 export { stringifyError } from './lib/errors';
-export { type ProcessConfig, ProcessError, type ProcessObserver, type ProcessResult, executeProcess, } from './lib/execute-process';
-export { type CrawlFileSystemOptions, type FileResult, type MultipleFileResults, crawlFileSystem, directoryExists, ensureDirectoryExists, fileExists, filePathToCliArg, findLineNumberInText, importModule, logMultipleFileResults, pluginWorkDir, readJsonFile, readTextFile, removeDirectoryIfExists, } from './lib/file-system';
+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 { type 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 { type CliUi, type Column, link, ui } from './lib/logging';
+export { link, ui, type CliUi, type Column } from './lib/logging';
 export { mergeConfigs } from './lib/merge-configs';
-export { type 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, generateMdReportsDiffForMonorepo, } from './lib/reports/generate-md-reports-diff';
@@ -25,6 +25,6 @@ export type { ScoredCategoryConfig, ScoredGroup, ScoredReport, } from './lib/rep
 export { calcDuration, compareIssueSeverity, formatReportScore, } from './lib/reports/utils';
 export { isSemver, normalizeSemver, sortSemvers } from './lib/semver';
 export * from './lib/text-formats';
-export { type CliArgsObject, capitalize, countOccurrences, distinct, factorOf, fromJsonLines, objectFromEntries, objectToCliArgs, objectToEntries, objectToKeys, toArray, toJsonLines, toNumberPrecision, toOrdinal, toUnixNewlines, toUnixPath, } from './lib/transform';
+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/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/formatting.d.ts

@@ -1,6 +1,19 @@
 import { type HeadingLevel, type InlineText, MarkdownDocument } from 'build-md';
-import type { AuditReport, Table } from '@code-pushup/models';
+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.d.ts

@@ -1,11 +1,11 @@
 import { type InlineText, MarkdownDocument } from 'build-md';
 import type { AuditReport, Issue, Report } from '@code-pushup/models';
-import type { ScoredReport } from './types';
+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/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/types.d.ts

@@ -1,4 +1,4 @@
-import type { 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

@@ -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;