@flakiness/sdk 2.3.1 → 2.5.0

package/README.md

@@ -10,7 +10,7 @@ The Flakiness SDK provides a comprehensive set of tools for creating and managin
 npm i @flakiness/sdk @flakiness/flakiness-report
 ```
 
-Requires Node.js 22+.
+Requires Node.js ^20.17.0 or >=22.9.0.
 
 ## Quick Start
 
@@ -34,6 +34,7 @@ const env = ReportUtils.createEnvironment({ name: 'CI' });
 const report: FlakinessReport.Report = {
   category: 'testreport',
   commitId: worktree.headCommitId(),
+  title: CIUtils.runTitle(),
   url: CIUtils.runUrl(),
   environments: [env],
   suites: [{
@@ -82,7 +83,7 @@ Use this entry point when you need to process or manipulate reports in browser-b
 ## Top-Level Exports
 
 ### Building Reports
-- **`CIUtils`** - Utilities to extract CI/CD information (run URLs, environment detection)
+- **`CIUtils`** - Utilities to extract CI/CD information (run URLs, run titles, environment detection)
 - **`GithubOIDC`** - GitHub Actions OIDC integration for passwordless Flakiness.io authentication
 - **`GitWorktree`** - Git repository utilities for path conversion and commit information
 - **`ReportUtils`** - Namespace with utilities for report creation and manipulation:

package/lib/browser.js

@@ -13,162 +13,8 @@ __export(reportUtilsBrowser_exports, {
   visitTests: () => visitTests
 });
 
-// node_modules/.pnpm/@flakiness+flakiness-report@0.28.0_zod@4.3.5/node_modules/@flakiness/flakiness-report/lib/flakinessReport.js
-var FlakinessReport;
-((FlakinessReport22) => {
-  FlakinessReport22.CATEGORY_PLAYWRIGHT = "playwright";
-  FlakinessReport22.CATEGORY_PYTEST = "pytest";
-  FlakinessReport22.CATEGORY_JUNIT = "junit";
-  FlakinessReport22.STREAM_STDOUT = 1;
-  FlakinessReport22.STREAM_STDERR = 2;
-})(FlakinessReport || (FlakinessReport = {}));
-
-// node_modules/.pnpm/@flakiness+flakiness-report@0.28.0_zod@4.3.5/node_modules/@flakiness/flakiness-report/lib/schema.js
-import z from "zod/v4";
-var Schema;
-((Schema2) => {
-  Schema2.CommitId = z.string().min(40).max(40);
-  Schema2.AttachmentId = z.string().min(1).max(1024);
-  Schema2.UnixTimestampMS = z.number().min(0);
-  Schema2.DurationMS = z.number().min(0);
-  Schema2.Number1Based = z.number();
-  Schema2.GitFilePath = z.string().min(0);
-  Schema2.Location = z.object({
-    file: Schema2.GitFilePath,
-    line: Schema2.Number1Based,
-    // Note: Locations for file suites are (0, 0).
-    column: Schema2.Number1Based
-  });
-  Schema2.TestStatus = z.enum(["passed", "failed", "timedOut", "skipped", "interrupted"]);
-  Schema2.Environment = z.object({
-    name: z.string().min(1).max(512),
-    systemData: z.object({
-      osName: z.string().optional(),
-      osVersion: z.string().optional(),
-      osArch: z.string().optional()
-    }).optional(),
-    metadata: z.any().optional(),
-    userSuppliedData: z.any().optional()
-  });
-  Schema2.STDIOEntry = z.union([
-    z.object({ text: z.string() }),
-    z.object({ buffer: z.string() })
-  ]);
-  Schema2.STREAM_STDOUT = z.literal(FlakinessReport.STREAM_STDOUT);
-  Schema2.STREAM_STDERR = z.literal(FlakinessReport.STREAM_STDERR);
-  Schema2.TimedSTDIOEntry = z.object({
-    stream: z.union([Schema2.STREAM_STDOUT, Schema2.STREAM_STDERR]).optional(),
-    dts: Schema2.DurationMS
-  }).and(z.union([
-    z.object({ text: z.string() }),
-    z.object({ buffer: z.string() })
-  ]));
-  Schema2.ReportError = z.object({
-    location: Schema2.Location.optional(),
-    message: z.string().optional(),
-    stack: z.string().optional(),
-    snippet: z.string().optional(),
-    value: z.string().optional()
-  });
-  Schema2.SuiteType = z.enum(["file", "anonymous suite", "suite"]);
-  Schema2.TestStep = z.object({
-    title: z.string(),
-    duration: Schema2.DurationMS.optional(),
-    location: Schema2.Location.optional(),
-    snippet: z.string().optional(),
-    error: Schema2.ReportError.optional(),
-    get steps() {
-      return z.array(Schema2.TestStep).optional();
-    }
-  });
-  Schema2.Attachment = z.object({
-    name: z.string(),
-    contentType: z.string(),
-    id: Schema2.AttachmentId
-  });
-  Schema2.Annotation = z.object({
-    type: z.string(),
-    description: z.string().optional(),
-    location: Schema2.Location.optional()
-  });
-  Schema2.RunAttempt = z.object({
-    // Index of the environment in the environments array (must be >= 0).
-    environmentIdx: z.number().min(0).optional(),
-    expectedStatus: Schema2.TestStatus.optional(),
-    status: Schema2.TestStatus.optional(),
-    startTimestamp: Schema2.UnixTimestampMS,
-    duration: Schema2.DurationMS.optional(),
-    timeout: Schema2.DurationMS.optional(),
-    annotations: z.array(Schema2.Annotation).optional(),
-    errors: z.array(Schema2.ReportError).optional(),
-    parallelIndex: z.number().optional(),
-    steps: z.array(Schema2.TestStep).optional(),
-    stdio: z.array(Schema2.TimedSTDIOEntry).optional(),
-    stdout: z.array(Schema2.STDIOEntry).optional(),
-    stderr: z.array(Schema2.STDIOEntry).optional(),
-    attachments: z.array(Schema2.Attachment).optional()
-  });
-  Schema2.Suite = z.object({
-    type: Schema2.SuiteType,
-    title: z.string(),
-    location: Schema2.Location.optional(),
-    get suites() {
-      return z.array(Schema2.Suite).optional();
-    },
-    get tests() {
-      return z.array(Schema2.Test).optional();
-    }
-  });
-  Schema2.Test = z.object({
-    title: z.string(),
-    location: Schema2.Location.optional(),
-    tags: z.array(z.string()).optional(),
-    attempts: z.array(Schema2.RunAttempt)
-  });
-  Schema2.SystemUtilizationSample = z.object({
-    dts: Schema2.DurationMS,
-    // Must be between 0 and 100 (inclusive). Can be a rational number.
-    cpuUtilization: z.number().min(0).max(100),
-    // Must be between 0 and 100 (inclusive). Can be a rational number.
-    memoryUtilization: z.number().min(0).max(100)
-  });
-  Schema2.SystemUtilization = z.object({
-    totalMemoryBytes: z.number().min(0),
-    startTimestamp: Schema2.UnixTimestampMS,
-    samples: z.array(Schema2.SystemUtilizationSample)
-  });
-  Schema2.UtilizationTelemetry = z.tuple([Schema2.DurationMS, z.number().min(0).max(100)]);
-  Schema2.Source = z.object({
-    filePath: Schema2.GitFilePath,
-    text: z.string(),
-    lineOffset: z.number().optional(),
-    contentType: z.string().optional()
-  });
-  Schema2.FlakinessProject = z.string();
-  Schema2.Report = z.object({
-    sources: z.array(Schema2.Source).optional(),
-    flakinessProject: Schema2.FlakinessProject.optional(),
-    category: z.string().min(1).max(100),
-    commitId: Schema2.CommitId,
-    relatedCommitIds: z.array(Schema2.CommitId).optional(),
-    configPath: Schema2.GitFilePath.optional(),
-    url: z.string().optional(),
-    environments: z.array(Schema2.Environment).min(1),
-    suites: z.array(Schema2.Suite).optional(),
-    tests: z.array(Schema2.Test).optional(),
-    unattributedErrors: z.array(Schema2.ReportError).optional(),
-    startTimestamp: Schema2.UnixTimestampMS,
-    duration: Schema2.DurationMS,
-    systemUtilization: z.optional(Schema2.SystemUtilization),
-    cpuCount: z.number().min(0).optional(),
-    cpuAvg: z.array(Schema2.UtilizationTelemetry).optional(),
-    cpuMax: z.array(Schema2.UtilizationTelemetry).optional(),
-    ram: z.array(Schema2.UtilizationTelemetry).optional(),
-    ramBytes: z.number().min(0).optional()
-  });
-})(Schema || (Schema = {}));
-
 // src/normalizeReport.ts
+import { FlakinessReport } from "@flakiness/flakiness-report";
 import stableObjectHash from "stable-hash";
 var Multimap = class {
   _map = /* @__PURE__ */ new Map();
@@ -327,7 +173,8 @@ function computeTestId(test, suiteId) {
 }
 
 // src/validateReport.ts
-import z2 from "zod/v4";
+import { Schema } from "@flakiness/flakiness-report";
+import z from "zod/v4";
 function validateReport(report) {
   const validation = Schema.Report.safeParse(report);
   if (!validation.success) {
@@ -335,7 +182,7 @@ function validateReport(report) {
     const allIssues = validation.error.issues;
     const shownIssues = allIssues.slice(0, MAX_ISSUES);
     const remaining = allIssues.length - shownIssues.length;
-    const base = [z2.prettifyError(new z2.ZodError(shownIssues))];
+    const base = [z.prettifyError(new z.ZodError(shownIssues))];
     if (remaining > 0)
       base.push(`... and ${remaining} more issue${remaining === 1 ? "" : "s"} ...`);
     return base.join("\n");

package/lib/index.js

@@ -7,11 +7,19 @@ var __export = (target, all) => {
 // src/ciUtils.ts
 var CIUtils;
 ((CIUtils2) => {
+  function runTitle() {
+    return githubActionsTitle();
+  }
+  CIUtils2.runTitle = runTitle;
   function runUrl() {
     return githubActions() ?? azure() ?? process.env.CI_JOB_URL ?? process.env.BUILD_URL;
   }
   CIUtils2.runUrl = runUrl;
 })(CIUtils || (CIUtils = {}));
+function githubActionsTitle() {
+  const title = process.env.GITHUB_WORKFLOW?.trim();
+  return title || void 0;
+}
 function githubActions() {
   const serverUrl = process.env.GITHUB_SERVER_URL || "https://github.com";
   const repo = process.env.GITHUB_REPOSITORY;
@@ -679,162 +687,8 @@ function createEnvironment(options) {
   };
 }
 
-// node_modules/.pnpm/@flakiness+flakiness-report@0.28.0_zod@4.3.5/node_modules/@flakiness/flakiness-report/lib/flakinessReport.js
-var FlakinessReport;
-((FlakinessReport22) => {
-  FlakinessReport22.CATEGORY_PLAYWRIGHT = "playwright";
-  FlakinessReport22.CATEGORY_PYTEST = "pytest";
-  FlakinessReport22.CATEGORY_JUNIT = "junit";
-  FlakinessReport22.STREAM_STDOUT = 1;
-  FlakinessReport22.STREAM_STDERR = 2;
-})(FlakinessReport || (FlakinessReport = {}));
-
-// node_modules/.pnpm/@flakiness+flakiness-report@0.28.0_zod@4.3.5/node_modules/@flakiness/flakiness-report/lib/schema.js
-import z from "zod/v4";
-var Schema;
-((Schema2) => {
-  Schema2.CommitId = z.string().min(40).max(40);
-  Schema2.AttachmentId = z.string().min(1).max(1024);
-  Schema2.UnixTimestampMS = z.number().min(0);
-  Schema2.DurationMS = z.number().min(0);
-  Schema2.Number1Based = z.number();
-  Schema2.GitFilePath = z.string().min(0);
-  Schema2.Location = z.object({
-    file: Schema2.GitFilePath,
-    line: Schema2.Number1Based,
-    // Note: Locations for file suites are (0, 0).
-    column: Schema2.Number1Based
-  });
-  Schema2.TestStatus = z.enum(["passed", "failed", "timedOut", "skipped", "interrupted"]);
-  Schema2.Environment = z.object({
-    name: z.string().min(1).max(512),
-    systemData: z.object({
-      osName: z.string().optional(),
-      osVersion: z.string().optional(),
-      osArch: z.string().optional()
-    }).optional(),
-    metadata: z.any().optional(),
-    userSuppliedData: z.any().optional()
-  });
-  Schema2.STDIOEntry = z.union([
-    z.object({ text: z.string() }),
-    z.object({ buffer: z.string() })
-  ]);
-  Schema2.STREAM_STDOUT = z.literal(FlakinessReport.STREAM_STDOUT);
-  Schema2.STREAM_STDERR = z.literal(FlakinessReport.STREAM_STDERR);
-  Schema2.TimedSTDIOEntry = z.object({
-    stream: z.union([Schema2.STREAM_STDOUT, Schema2.STREAM_STDERR]).optional(),
-    dts: Schema2.DurationMS
-  }).and(z.union([
-    z.object({ text: z.string() }),
-    z.object({ buffer: z.string() })
-  ]));
-  Schema2.ReportError = z.object({
-    location: Schema2.Location.optional(),
-    message: z.string().optional(),
-    stack: z.string().optional(),
-    snippet: z.string().optional(),
-    value: z.string().optional()
-  });
-  Schema2.SuiteType = z.enum(["file", "anonymous suite", "suite"]);
-  Schema2.TestStep = z.object({
-    title: z.string(),
-    duration: Schema2.DurationMS.optional(),
-    location: Schema2.Location.optional(),
-    snippet: z.string().optional(),
-    error: Schema2.ReportError.optional(),
-    get steps() {
-      return z.array(Schema2.TestStep).optional();
-    }
-  });
-  Schema2.Attachment = z.object({
-    name: z.string(),
-    contentType: z.string(),
-    id: Schema2.AttachmentId
-  });
-  Schema2.Annotation = z.object({
-    type: z.string(),
-    description: z.string().optional(),
-    location: Schema2.Location.optional()
-  });
-  Schema2.RunAttempt = z.object({
-    // Index of the environment in the environments array (must be >= 0).
-    environmentIdx: z.number().min(0).optional(),
-    expectedStatus: Schema2.TestStatus.optional(),
-    status: Schema2.TestStatus.optional(),
-    startTimestamp: Schema2.UnixTimestampMS,
-    duration: Schema2.DurationMS.optional(),
-    timeout: Schema2.DurationMS.optional(),
-    annotations: z.array(Schema2.Annotation).optional(),
-    errors: z.array(Schema2.ReportError).optional(),
-    parallelIndex: z.number().optional(),
-    steps: z.array(Schema2.TestStep).optional(),
-    stdio: z.array(Schema2.TimedSTDIOEntry).optional(),
-    stdout: z.array(Schema2.STDIOEntry).optional(),
-    stderr: z.array(Schema2.STDIOEntry).optional(),
-    attachments: z.array(Schema2.Attachment).optional()
-  });
-  Schema2.Suite = z.object({
-    type: Schema2.SuiteType,
-    title: z.string(),
-    location: Schema2.Location.optional(),
-    get suites() {
-      return z.array(Schema2.Suite).optional();
-    },
-    get tests() {
-      return z.array(Schema2.Test).optional();
-    }
-  });
-  Schema2.Test = z.object({
-    title: z.string(),
-    location: Schema2.Location.optional(),
-    tags: z.array(z.string()).optional(),
-    attempts: z.array(Schema2.RunAttempt)
-  });
-  Schema2.SystemUtilizationSample = z.object({
-    dts: Schema2.DurationMS,
-    // Must be between 0 and 100 (inclusive). Can be a rational number.
-    cpuUtilization: z.number().min(0).max(100),
-    // Must be between 0 and 100 (inclusive). Can be a rational number.
-    memoryUtilization: z.number().min(0).max(100)
-  });
-  Schema2.SystemUtilization = z.object({
-    totalMemoryBytes: z.number().min(0),
-    startTimestamp: Schema2.UnixTimestampMS,
-    samples: z.array(Schema2.SystemUtilizationSample)
-  });
-  Schema2.UtilizationTelemetry = z.tuple([Schema2.DurationMS, z.number().min(0).max(100)]);
-  Schema2.Source = z.object({
-    filePath: Schema2.GitFilePath,
-    text: z.string(),
-    lineOffset: z.number().optional(),
-    contentType: z.string().optional()
-  });
-  Schema2.FlakinessProject = z.string();
-  Schema2.Report = z.object({
-    sources: z.array(Schema2.Source).optional(),
-    flakinessProject: Schema2.FlakinessProject.optional(),
-    category: z.string().min(1).max(100),
-    commitId: Schema2.CommitId,
-    relatedCommitIds: z.array(Schema2.CommitId).optional(),
-    configPath: Schema2.GitFilePath.optional(),
-    url: z.string().optional(),
-    environments: z.array(Schema2.Environment).min(1),
-    suites: z.array(Schema2.Suite).optional(),
-    tests: z.array(Schema2.Test).optional(),
-    unattributedErrors: z.array(Schema2.ReportError).optional(),
-    startTimestamp: Schema2.UnixTimestampMS,
-    duration: Schema2.DurationMS,
-    systemUtilization: z.optional(Schema2.SystemUtilization),
-    cpuCount: z.number().min(0).optional(),
-    cpuAvg: z.array(Schema2.UtilizationTelemetry).optional(),
-    cpuMax: z.array(Schema2.UtilizationTelemetry).optional(),
-    ram: z.array(Schema2.UtilizationTelemetry).optional(),
-    ramBytes: z.number().min(0).optional()
-  });
-})(Schema || (Schema = {}));
-
 // src/normalizeReport.ts
+import { FlakinessReport } from "@flakiness/flakiness-report";
 import stableObjectHash from "stable-hash";
 var Multimap = class {
   _map = /* @__PURE__ */ new Map();
@@ -993,7 +847,8 @@ function computeTestId(test, suiteId) {
 }
 
 // src/validateReport.ts
-import z2 from "zod/v4";
+import { Schema } from "@flakiness/flakiness-report";
+import z from "zod/v4";
 function validateReport(report) {
   const validation = Schema.Report.safeParse(report);
   if (!validation.success) {
@@ -1001,7 +856,7 @@ function validateReport(report) {
     const allIssues = validation.error.issues;
     const shownIssues = allIssues.slice(0, MAX_ISSUES);
     const remaining = allIssues.length - shownIssues.length;
-    const base = [z2.prettifyError(new z2.ZodError(shownIssues))];
+    const base = [z.prettifyError(new z.ZodError(shownIssues))];
     if (remaining > 0)
       base.push(`... and ${remaining} more issue${remaining === 1 ? "" : "s"} ...`);
     return base.join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flakiness/sdk",
-  "version": "2.3.1",
+  "version": "2.5.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
   "author": "Degu Labs, Inc",
   "license": "MIT",
   "engines": {
-    "node": ">=22"
+    "node": "^20.17.0 || >=22.9.0"
   },
   "devDependencies": {
     "@flakiness/flakiness-report": "^0.28.0",

package/types/src/ciUtils.d.ts

@@ -5,6 +5,27 @@
  * from various CI/CD environments, including GitHub Actions, Azure DevOps, Jenkins, and others.
  */
 export declare namespace CIUtils {
+    /**
+     * Automatically extracts a human-readable CI run title when available.
+     *
+     * This function attempts to detect the current CI environment and return a
+     * stable title that identifies the workflow or pipeline generating the report.
+     *
+     * Supported CI providers (checked in order):
+     * - GitHub Actions (via `GITHUB_WORKFLOW`)
+     *
+     * @returns {string | undefined} The CI run title, or `undefined` if no supported
+     *   CI environment exposes a stable human-readable title.
+     *
+     * @example
+     * ```typescript
+     * const report: FlakinessReport.Report = {
+     *   // ... other report properties
+     *   title: CIUtils.runTitle(),
+     * };
+     * ```
+     */
+    function runTitle(): string | undefined;
     /**
      * Automatically extracts the run URL for common continuous integration providers.
      *

package/types/src/ciUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ciUtils.d.ts","sourceRoot":"","sources":["../../src/ciUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,yBAAiB,OAAO,CAAC;IACvB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,SAAgB,MAAM,IAAI,MAAM,GAAG,SAAS,CAE3C;CACF"}
+{"version":3,"file":"ciUtils.d.ts","sourceRoot":"","sources":["../../src/ciUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,yBAAiB,OAAO,CAAC;IACvB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAgB,QAAQ,IAAI,MAAM,GAAG,SAAS,CAE7C;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,SAAgB,MAAM,IAAI,MAAM,GAAG,SAAS,CAE3C;CACF"}

package/types/src/stripAnsi.d.ts

@@ -11,9 +11,7 @@
  *
  * @example
  * ```typescript
- * import { styleText } from 'node:util';
- *
- * const clean = stripAnsi(styleText('red', 'Error: test failed'));
+ * const clean = stripAnsi('\u001B[31mError: test failed\u001B[39m');
  * // Returns: 'Error: test failed' (without color codes)
  * ```
  */

package/types/src/stripAnsi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stripAnsi.d.ts","sourceRoot":"","sources":["../../src/stripAnsi.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C"}
+{"version":3,"file":"stripAnsi.d.ts","sourceRoot":"","sources":["../../src/stripAnsi.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C"}