@flakiness/sdk 0.148.0 → 0.149.0

package/lib/showReport.js

@@ -1,32 +1,97 @@
 // src/showReport.ts
-import { randomUUIDBase62 } from "@flakiness/shared/node/nodeutils.js";
 import chalk from "chalk";
 import open from "open";
 
-// src/flakinessProjectConfig.ts
-import fs from "fs";
-import path from "path";
-
-// src/git.ts
-import assert from "assert";
-
-// src/pathutils.ts
-import { posix as posixPath, win32 as win32Path } from "path";
-var IS_WIN32_PATH = new RegExp("^[a-zA-Z]:\\\\", "i");
-var IS_ALMOST_POSIX_PATH = new RegExp("^[a-zA-Z]:/", "i");
-function normalizePath(aPath) {
-  if (IS_WIN32_PATH.test(aPath)) {
-    aPath = aPath.split(win32Path.sep).join(posixPath.sep);
-  }
-  if (IS_ALMOST_POSIX_PATH.test(aPath))
-    return "/" + aPath[0] + aPath.substring(2);
-  return aPath;
-}
-
-// src/utils.ts
+// src/_internalUtils.ts
 import { spawnSync } from "child_process";
+import crypto from "crypto";
+import http from "http";
+import https from "https";
+import util from "util";
+import zlib from "zlib";
+var asyncBrotliCompress = util.promisify(zlib.brotliCompress);
 var FLAKINESS_DBG = !!process.env.FLAKINESS_DBG;
-var ansiRegex = new RegExp("[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:[a-zA-Z\\d]*(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)|(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-ntqry=><~]))", "g");
+function errorText(error) {
+  return FLAKINESS_DBG ? error.stack : error.message;
+}
+async function retryWithBackoff(job, backoff = []) {
+  for (const timeout of backoff) {
+    try {
+      return await job();
+    } catch (e) {
+      if (e instanceof AggregateError)
+        console.error(`[flakiness.io err]`, errorText(e.errors[0]));
+      else if (e instanceof Error)
+        console.error(`[flakiness.io err]`, errorText(e));
+      else
+        console.error(`[flakiness.io err]`, e);
+      await new Promise((x) => setTimeout(x, timeout));
+    }
+  }
+  return await job();
+}
+var httpUtils;
+((httpUtils2) => {
+  function createRequest({ url, method = "get", headers = {} }) {
+    let resolve2;
+    let reject;
+    const responseDataPromise = new Promise((a, b) => {
+      resolve2 = a;
+      reject = b;
+    });
+    const protocol = url.startsWith("https") ? https : http;
+    headers = Object.fromEntries(Object.entries(headers).filter(([key, value]) => value !== void 0));
+    const request = protocol.request(url, { method, headers }, (res) => {
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => {
+        if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300)
+          resolve2(Buffer.concat(chunks));
+        else
+          reject(new Error(`Request to ${url} failed with ${res.statusCode}`));
+      });
+      res.on("error", (error) => reject(error));
+    });
+    request.on("error", reject);
+    return { request, responseDataPromise };
+  }
+  httpUtils2.createRequest = createRequest;
+  async function getBuffer(url, backoff) {
+    return await retryWithBackoff(async () => {
+      const { request, responseDataPromise } = createRequest({ url });
+      request.end();
+      return await responseDataPromise;
+    }, backoff);
+  }
+  httpUtils2.getBuffer = getBuffer;
+  async function getText(url, backoff) {
+    const buffer = await getBuffer(url, backoff);
+    return buffer.toString("utf-8");
+  }
+  httpUtils2.getText = getText;
+  async function getJSON(url) {
+    return JSON.parse(await getText(url));
+  }
+  httpUtils2.getJSON = getJSON;
+  async function postText(url, text, backoff) {
+    const headers = {
+      "Content-Type": "application/json",
+      "Content-Length": Buffer.byteLength(text) + ""
+    };
+    return await retryWithBackoff(async () => {
+      const { request, responseDataPromise } = createRequest({ url, headers, method: "post" });
+      request.write(text);
+      request.end();
+      return await responseDataPromise;
+    }, backoff);
+  }
+  httpUtils2.postText = postText;
+  async function postJSON(url, json, backoff) {
+    const buffer = await postText(url, JSON.stringify(json), backoff);
+    return JSON.parse(buffer.toString("utf-8"));
+  }
+  httpUtils2.postJSON = postJSON;
+})(httpUtils || (httpUtils = {}));
 function shell(command, args, options) {
   try {
     const result = spawnSync(command, args, { encoding: "utf-8", ...options });
@@ -39,15 +104,227 @@ function shell(command, args, options) {
     return void 0;
   }
 }
+function randomUUIDBase62() {
+  const BASE62_CHARSET = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+  let num = BigInt("0x" + crypto.randomUUID().replace(/-/g, ""));
+  if (num === 0n)
+    return BASE62_CHARSET[0];
+  const chars = [];
+  while (num > 0n) {
+    const remainder = Number(num % 62n);
+    num /= 62n;
+    chars.push(BASE62_CHARSET[remainder]);
+  }
+  return chars.reverse().join("");
+}
 
-// src/git.ts
-function computeGitRoot(somePathInsideGitRepo) {
-  const root = shell(`git`, ["rev-parse", "--show-toplevel"], {
-    cwd: somePathInsideGitRepo,
-    encoding: "utf-8"
-  });
-  assert(root, `FAILED: git rev-parse --show-toplevel HEAD @ ${somePathInsideGitRepo}`);
-  return normalizePath(root);
+// src/flakinessProjectConfig.ts
+import fs from "fs";
+import path from "path";
+
+// src/gitWorktree.ts
+import assert from "assert";
+import { exec } from "child_process";
+import debug from "debug";
+import { posix as posixPath, win32 as win32Path } from "path";
+import { promisify } from "util";
+var log = debug("fk:git");
+var execAsync = promisify(exec);
+var IS_WIN32_PATH = new RegExp("^[a-zA-Z]:\\\\", "i");
+var IS_ALMOST_POSIX_PATH = new RegExp("^[a-zA-Z]:/", "i");
+function toPosixAbsolutePath(absolutePath) {
+  if (IS_WIN32_PATH.test(absolutePath)) {
+    absolutePath = absolutePath.split(win32Path.sep).join(posixPath.sep);
+  }
+  if (IS_ALMOST_POSIX_PATH.test(absolutePath))
+    return "/" + absolutePath[0] + absolutePath.substring(2);
+  return absolutePath;
+}
+function toNativeAbsolutePath(posix) {
+  if (process.platform !== "win32")
+    return posix;
+  assert(posix.startsWith("/"), "The path must be absolute");
+  const m = posix.match(/^\/([a-zA-Z])(\/.*)?$/);
+  assert(m, `Invalid POSIX path: ${posix}`);
+  const drive = m[1];
+  const rest = (m[2] ?? "").split(posixPath.sep).join(win32Path.sep);
+  return drive.toUpperCase() + ":" + rest;
+}
+var GitWorktree = class _GitWorktree {
+  constructor(_gitRoot) {
+    this._gitRoot = _gitRoot;
+    this._posixGitRoot = toPosixAbsolutePath(this._gitRoot);
+  }
+  /**
+   * Creates a GitWorktree instance from any path inside a git repository.
+   *
+   * @param {string} somePathInsideGitRepo - Any path (file or directory) within a git repository.
+   *   Can be absolute or relative. The function will locate the git root directory.
+   *
+   * @returns {GitWorktree} A new GitWorktree instance bound to the discovered git root.
+   *
+   * @throws {Error} Throws if the path is not inside a git repository or if git commands fail.
+   *
+   * @example
+   * ```typescript
+   * const worktree = GitWorktree.create('./src/my-test.ts');
+   * const gitRoot = worktree.rootPath();
+   * ```
+   */
+  static create(somePathInsideGitRepo) {
+    const root = shell(`git`, ["rev-parse", "--show-toplevel"], {
+      cwd: somePathInsideGitRepo,
+      encoding: "utf-8"
+    });
+    assert(root, `FAILED: git rev-parse --show-toplevel HEAD @ ${somePathInsideGitRepo}`);
+    return new _GitWorktree(root);
+  }
+  _posixGitRoot;
+  /**
+   * Returns the native absolute path of the git repository root directory.
+   *
+   * @returns {string} Native absolute path to the git root. Format matches the current platform
+   *   (Windows or POSIX).
+   *
+   * @example
+   * ```typescript
+   * const root = worktree.rootPath();
+   * // On Windows: 'D:\project'
+   * // On Unix: '/project'
+   * ```
+   */
+  rootPath() {
+    return this._gitRoot;
+  }
+  /**
+   * Returns the commit ID (SHA-1 hash) of the current HEAD commit.
+   *
+   * @returns {FlakinessReport.CommitId} Full 40-character commit hash of the HEAD commit.
+   *
+   * @throws {Error} Throws if git command fails or repository is in an invalid state.
+   *
+   * @example
+   * ```typescript
+   * const commitId = worktree.headCommitId();
+   * // Returns: 'a1b2c3d4e5f6...' (40-character SHA-1)
+   * ```
+   */
+  headCommitId() {
+    const sha = shell(`git`, ["rev-parse", "HEAD"], {
+      cwd: this._gitRoot,
+      encoding: "utf-8"
+    });
+    assert(sha, `FAILED: git rev-parse HEAD @ ${this._gitRoot}`);
+    return sha.trim();
+  }
+  /**
+   * Converts a native absolute path to a git-relative POSIX path.
+   *
+   * Takes any absolute path (Windows or POSIX format) and converts it to a POSIX path
+   * relative to the git repository root. This is essential for Flakiness reports where
+   * all file paths must be git-relative and use POSIX separators.
+   *
+   * @param {string} absolutePath - Native absolute path to convert. Can be in Windows format
+   *   (e.g., `D:\project\src\test.ts`) or POSIX format (e.g., `/project/src/test.ts`).
+   *
+   * @returns {FlakinessReport.GitFilePath} POSIX path relative to git root (e.g., `src/test.ts`).
+   *   Returns an empty string if the path is the git root itself.
+   *
+   * @example
+   * ```typescript
+   * const gitPath = worktree.gitPath('/Users/project/src/test.ts');
+   * // Returns: 'src/test.ts'
+   * ```
+   */
+  gitPath(absolutePath) {
+    return posixPath.relative(this._posixGitRoot, toPosixAbsolutePath(absolutePath));
+  }
+  /**
+   * Converts a git-relative POSIX path to a native absolute path.
+   *
+   * Takes a POSIX path relative to the git root and converts it to the native absolute path
+   * format for the current platform (Windows or POSIX). This is the inverse of `gitPath()`.
+   *
+   * @param {FlakinessReport.GitFilePath} relativePath - POSIX path relative to git root
+   *   (e.g., `src/test.ts`).
+   *
+   * @returns {string} Native absolute path. On Windows, returns Windows format (e.g., `D:\project\src\test.ts`).
+   *   On POSIX systems, returns POSIX format (e.g., `/project/src/test.ts`).
+   *
+   * @example
+   * ```typescript
+   * const absolutePath = worktree.absolutePath('src/test.ts');
+   * // On Windows: 'D:\project\src\test.ts'
+   * // On Unix: '/project/src/test.ts'
+   * ```
+   */
+  absolutePath(relativePath) {
+    return toNativeAbsolutePath(posixPath.join(this._posixGitRoot, relativePath));
+  }
+  /**
+   * Lists recent commits from the repository.
+   *
+   * Retrieves commit information including commit ID, timestamp, author, message, and parent commits.
+   * Note: CI environments often have shallow checkouts with limited history, which may affect
+   * the number of commits returned.
+   *
+   * @param {number} count - Maximum number of commits to retrieve, starting from HEAD.
+   *
+   * @returns {Promise<GitCommit[]>} Promise that resolves to an array of commit objects, ordered
+   *   from most recent to oldest. Each commit includes:
+   *   - `commitId` - Full commit hash
+   *   - `timestamp` - Commit timestamp in milliseconds since Unix epoch
+   *   - `message` - Commit message (subject line)
+   *   - `author` - Author name
+   *   - `parents` - Array of parent commit IDs
+   *
+   * @example
+   * ```typescript
+   * const commits = await worktree.listCommits(10);
+   * console.log(`Latest commit: ${commits[0].message}`);
+   * ```
+   */
+  async listCommits(count) {
+    return await listCommits(this._gitRoot, "HEAD", count);
+  }
+};
+async function listCommits(gitRoot, head, count) {
+  const FIELD_SEPARATOR = "|~|";
+  const RECORD_SEPARATOR = "\0";
+  const prettyFormat = [
+    "%H",
+    // Full commit hash
+    "%ct",
+    // Commit timestamp (Unix seconds)
+    "%an",
+    // Author name
+    "%s",
+    // Subject line
+    "%P"
+    // Parent hashes (space-separated)
+  ].join(FIELD_SEPARATOR);
+  const command = `git log ${head} -n ${count} --pretty=format:"${prettyFormat}" -z`;
+  try {
+    const { stdout } = await execAsync(command, { cwd: gitRoot });
+    if (!stdout) {
+      return [];
+    }
+    return stdout.trim().split(RECORD_SEPARATOR).filter((record) => record).map((record) => {
+      const [commitId, timestampStr, author, message, parentsStr] = record.split(FIELD_SEPARATOR);
+      const parents = parentsStr ? parentsStr.split(" ").filter((p) => p) : [];
+      return {
+        commitId,
+        timestamp: parseInt(timestampStr, 10) * 1e3,
+        author,
+        message,
+        parents,
+        walkIndex: 0
+      };
+    });
+  } catch (error) {
+    log(`Failed to list commits for repository at ${gitRoot}:`, error);
+    return [];
+  }
 }
 
 // src/flakinessProjectConfig.ts
@@ -67,8 +344,8 @@ function computeConfigPath() {
       return configPath;
   }
   try {
-    const gitRoot = computeGitRoot(process.cwd());
-    return createConfigPath(gitRoot);
+    const worktree = GitWorktree.create(process.cwd());
+    return createConfigPath(worktree.rootPath());
   } catch (e) {
     return createConfigPath(process.cwd());
   }
@@ -78,33 +355,110 @@ var FlakinessProjectConfig = class _FlakinessProjectConfig {
     this._configPath = _configPath;
     this._config = _config;
   }
+  /**
+   * Loads the Flakiness project configuration from disk.
+   *
+   * Searches for an existing `.flakiness/config.json` file starting from the current working
+   * directory and walking up the directory tree. If no config exists, it determines the
+   * appropriate location (git root or current directory) for future saves.
+   *
+   * @returns {Promise<FlakinessProjectConfig>} Promise that resolves to a FlakinessProjectConfig
+   *   instance. If no config file exists, returns an instance with default/empty values.
+   *
+   * @example
+   * ```typescript
+   * const config = await FlakinessProjectConfig.load();
+   * const projectId = config.projectPublicId();
+   * ```
+   */
   static async load() {
     const configPath = ensureConfigPath();
     const data = await fs.promises.readFile(configPath, "utf-8").catch((e) => void 0);
     const json = data ? JSON.parse(data) : {};
     return new _FlakinessProjectConfig(configPath, json);
   }
+  /**
+   * Creates a new empty Flakiness project configuration.
+   *
+   * Creates a configuration instance with no values set. Use this when you want to build
+   * a configuration from scratch. Call `save()` to persist it to disk.
+   *
+   * @returns {FlakinessProjectConfig} A new empty configuration instance.
+   *
+   * @example
+   * ```typescript
+   * const config = FlakinessProjectConfig.createEmpty();
+   * config.setProjectPublicId('my-project-id');
+   * await config.save();
+   * ```
+   */
   static createEmpty() {
     return new _FlakinessProjectConfig(ensureConfigPath(), {});
   }
+  /**
+   * Returns the absolute path to the configuration file.
+   *
+   * @returns {string} Absolute path to `.flakiness/config.json`.
+   */
   path() {
     return this._configPath;
   }
+  /**
+   * Returns the project's public ID, if configured.
+   *
+   * The project public ID is used to associate reports with a specific Flakiness.io project.
+   *
+   * @returns {string | undefined} Project public ID, or `undefined` if not set.
+   */
   projectPublicId() {
     return this._config.projectPublicId;
   }
+  /**
+   * Returns the report viewer URL, either custom or default.
+   *
+   * @returns {string} Custom report viewer URL if configured, otherwise the default
+   *   `https://report.flakiness.io`.
+   */
   reportViewerUrl() {
     return this._config.customReportViewerUrl ?? "https://report.flakiness.io";
   }
+  /**
+   * Sets or clears the custom report viewer URL.
+   *
+   * @param {string | undefined} url - Custom report viewer URL to use, or `undefined` to
+   *   clear and use the default URL.
+   */
   setCustomReportViewerUrl(url) {
     if (url)
       this._config.customReportViewerUrl = url;
     else
       delete this._config.customReportViewerUrl;
   }
+  /**
+   * Sets the project's public ID.
+   *
+   * @param {string | undefined} projectId - Project public ID to set, or `undefined` to clear.
+   */
   setProjectPublicId(projectId) {
     this._config.projectPublicId = projectId;
   }
+  /**
+   * Saves the configuration to disk.
+   *
+   * Writes the current configuration values to `.flakiness/config.json`. Creates the
+   * `.flakiness` directory if it doesn't exist.
+   *
+   * @returns {Promise<void>} Promise that resolves when the file has been written.
+   *
+   * @throws {Error} Throws if unable to create directories or write the file.
+   *
+   * @example
+   * ```typescript
+   * const config = await FlakinessProjectConfig.load();
+   * config.setProjectPublicId('my-project');
+   * await config.save();
+   * ```
+   */
   async save() {
     await fs.promises.mkdir(path.dirname(this._configPath), { recursive: true });
     await fs.promises.writeFile(this._configPath, JSON.stringify(this._config, null, 2));
@@ -112,11 +466,11 @@ var FlakinessProjectConfig = class _FlakinessProjectConfig {
 };
 
 // src/staticServer.ts
-import debug from "debug";
+import debug2 from "debug";
 import * as fs2 from "fs";
-import * as http from "http";
+import * as http2 from "http";
 import * as path2 from "path";
-var log = debug("fk:static_server");
+var log2 = debug2("fk:static_server");
 var StaticServer = class {
   _server;
   _absoluteFolderPath;
@@ -138,7 +492,7 @@ var StaticServer = class {
     this._pathPrefix = "/" + pathPrefix.replace(/^\//, "").replace(/\/$/, "");
     this._absoluteFolderPath = path2.resolve(folderPath);
     this._cors = cors;
-    this._server = http.createServer((req, res) => this._handleRequest(req, res));
+    this._server = http2.createServer((req, res) => this._handleRequest(req, res));
   }
   port() {
     const address = this._server.address();
@@ -167,7 +521,7 @@ var StaticServer = class {
     this._server.once("error", errListener);
     this._server.listen(port, host);
     await result;
-    log('Serving "%s" on "%s"', this._absoluteFolderPath, this.address());
+    log2('Serving "%s" on "%s"', this._absoluteFolderPath, this.address());
   }
   async start(port, host = "127.0.0.1") {
     if (port === 0) {
@@ -180,12 +534,12 @@ var StaticServer = class {
         return this.address();
       if (err.code !== "EADDRINUSE")
         throw err;
-      log("Port %d is busy (EADDRINUSE). Trying next port...", port);
+      log2("Port %d is busy (EADDRINUSE). Trying next port...", port);
       port = port + 1;
       if (port > 65535)
         port = 4e3;
     }
-    log("All sequential ports busy. Falling back to random port.");
+    log2("All sequential ports busy. Falling back to random port.");
     await this._startServer(0, host);
     return this.address();
   }
@@ -193,10 +547,10 @@ var StaticServer = class {
     return new Promise((resolve2, reject) => {
       this._server.close((err) => {
         if (err) {
-          log("Error stopping server: %o", err);
+          log2("Error stopping server: %o", err);
           reject(err);
         } else {
-          log("Server stopped.");
+          log2("Server stopped.");
           resolve2();
         }
       });
@@ -205,7 +559,7 @@ var StaticServer = class {
   _errorResponse(req, res, code, text) {
     res.writeHead(code, { "Content-Type": "text/plain" });
     res.end(text);
-    log(`[${code}] ${req.method} ${req.url}`);
+    log2(`[${code}] ${req.method} ${req.url}`);
   }
   _handleRequest(req, res) {
     const { url, method } = req;
@@ -223,9 +577,9 @@ var StaticServer = class {
       this._errorResponse(req, res, 405, "Method Not Allowed");
       return;
     }
-    req.on("aborted", () => log(`ABORTED ${req.method} ${req.url}`));
+    req.on("aborted", () => log2(`ABORTED ${req.method} ${req.url}`));
     res.on("close", () => {
-      if (!res.headersSent) log(`CLOSED BEFORE SEND ${req.method} ${req.url}`);
+      if (!res.headersSent) log2(`CLOSED BEFORE SEND ${req.method} ${req.url}`);
     });
     if (!url || !url.startsWith(this._pathPrefix)) {
       this._errorResponse(req, res, 404, "Not Found");
@@ -246,11 +600,11 @@ var StaticServer = class {
       const ext = path2.extname(filePath).toLowerCase();
       const contentType = this._mimeTypes[ext] || "application/octet-stream";
       res.writeHead(200, { "Content-Type": contentType });
-      log(`[200] ${req.method} ${req.url} -> ${filePath}`);
+      log2(`[200] ${req.method} ${req.url} -> ${filePath}`);
       const readStream = fs2.createReadStream(filePath);
       readStream.pipe(res);
       readStream.on("error", (err2) => {
-        log("Stream error: %o", err2);
+        log2("Stream error: %o", err2);
         res.end();
       });
     });

package/lib/stripAnsi.js

@@ -0,0 +1,9 @@
+// src/stripAnsi.ts
+var ansiRegex = new RegExp("[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:[a-zA-Z\\d]*(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)|(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-ntqry=><~]))", "g");
+function stripAnsi(str) {
+  return str.replace(ansiRegex, "");
+}
+export {
+  stripAnsi
+};
+//# sourceMappingURL=stripAnsi.js.map

package/lib/systemUtilizationSampler.js

@@ -44,9 +44,24 @@ function toFKUtilization(sample, previous) {
   };
 }
 var SystemUtilizationSampler = class {
+  /**
+   * The accumulated system utilization data.
+   *
+   * This object is populated as samples are collected and can be directly included in
+   * Flakiness reports. It contains:
+   * - `samples` - Array of utilization samples with CPU/memory percentages and durations
+   * - `startTimestamp` - Timestamp when sampling began
+   * - `totalMemoryBytes` - Total system memory in bytes
+   */
   result;
   _lastSample = getSystemUtilization();
   _timer;
+  /**
+   * Creates a new SystemUtilizationSampler and starts sampling immediately.
+   *
+   * The first sample is collected after 50ms, and subsequent samples are collected
+   * every 1000ms. Call `dispose()` to stop sampling and clean up resources.
+   */
   constructor() {
     this.result = {
       samples: [],
@@ -61,6 +76,12 @@ var SystemUtilizationSampler = class {
     this._lastSample = sample;
     this._timer = setTimeout(this._addSample.bind(this), 1e3);
   }
+  /**
+   * Stops sampling and cleans up resources.
+   *
+   * Call this method when you're done collecting utilization data to stop the sampling
+   * timer and prevent memory leaks. The `result` object remains accessible after disposal.
+   */
   dispose() {
     clearTimeout(this._timer);
   }