@flakiness/sdk 0.148.0 → 0.149.0

package/lib/flakinessProjectConfig.js

@@ -2,26 +2,102 @@
 import fs from "fs";
 import path from "path";
 
-// src/git.ts
+// src/gitWorktree.ts
 import assert from "assert";
-
-// src/pathutils.ts
+import { exec } from "child_process";
+import debug from "debug";
 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;
-}
+import { promisify } from "util";
 
-// src/utils.ts
+// src/_internalUtils.ts
 import { spawnSync } from "child_process";
+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 resolve;
+    let reject;
+    const responseDataPromise = new Promise((a, b) => {
+      resolve = 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)
+          resolve(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 });
@@ -35,14 +111,204 @@ function shell(command, args, options) {
   }
 }
 
-// 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/gitWorktree.ts
+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
@@ -62,8 +328,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());
   }
@@ -73,33 +339,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));