@flakiness/sdk 0.149.0 → 0.150.0

package/lib/uploadReport.js

@@ -1,129 +1,7 @@
-// src/uploadReport.ts
 import assert from "assert";
-import fs2 from "fs";
-import { URL } from "url";
-
-// src/_internalUtils.ts
-import crypto from "crypto";
 import fs from "fs";
-import http from "http";
-import https from "https";
-import util from "util";
-import zlib from "zlib";
-var asyncBrotliCompress = util.promisify(zlib.brotliCompress);
-async function compressTextAsync(text) {
-  return asyncBrotliCompress(text, {
-    chunkSize: 32 * 1024,
-    params: {
-      [zlib.constants.BROTLI_PARAM_QUALITY]: 6,
-      [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT
-    }
-  });
-}
-var FLAKINESS_DBG = !!process.env.FLAKINESS_DBG;
-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 sha1Text(data) {
-  const hash = crypto.createHash("sha1");
-  hash.update(data);
-  return hash.digest("hex");
-}
-function sha1File(filePath) {
-  return new Promise((resolve, reject) => {
-    const hash = crypto.createHash("sha1");
-    const stream = fs.createReadStream(filePath);
-    stream.on("data", (chunk) => {
-      hash.update(chunk);
-    });
-    stream.on("end", () => {
-      resolve(hash.digest("hex"));
-    });
-    stream.on("error", (err) => {
-      reject(err);
-    });
-  });
-}
-
-// src/uploadReport.ts
+import { URL } from "url";
+import { compressTextAsync, retryWithBackoff, sha1File, sha1Text } from "./_internalUtils.js";
 async function createFileAttachment(contentType, filePath) {
   return {
     type: "file",
@@ -170,8 +48,8 @@ async function uploadReport(report, attachments, options) {
     return { status: "failed", error: errorMessage };
   }
 }
-var HTTP_BACKOFF = [100, 500, 1e3, 1e3, 1e3, 1e3];
-var ReportUpload = class {
+const HTTP_BACKOFF = [100, 500, 1e3, 1e3, 1e3, 1e3];
+class ReportUpload {
   _report;
   _attachments;
   _options;
@@ -232,14 +110,15 @@ var ReportUpload = class {
       "Content-Encoding": "br"
     };
     await retryWithBackoff(async () => {
-      const { request, responseDataPromise } = httpUtils.createRequest({
-        url: uploadUrl,
+      const response = await fetch(uploadUrl, {
+        method: "PUT",
         headers,
-        method: "put"
+        body: Buffer.from(compressed)
       });
-      request.write(compressed);
-      request.end();
-      await responseDataPromise;
+      if (!response.ok) {
+        throw new Error(`Request to ${uploadUrl} failed with ${response.status}`);
+      }
+      await response.arrayBuffer();
     }, HTTP_BACKOFF);
   }
   async _uploadAttachment(attachment, uploadUrl) {
@@ -247,41 +126,47 @@ var ReportUpload = class {
     const compressable = mimeType.startsWith("text/") || mimeType.endsWith("+json") || mimeType.endsWith("+text") || mimeType.endsWith("+xml");
     if (!compressable && attachment.type === "file") {
       await retryWithBackoff(async () => {
-        const { request, responseDataPromise } = httpUtils.createRequest({
-          url: uploadUrl,
+        const fileBuffer = await fs.promises.readFile(attachment.path);
+        const response = await fetch(uploadUrl, {
+          method: "PUT",
           headers: {
             "Content-Type": attachment.contentType,
-            "Content-Length": (await fs2.promises.stat(attachment.path)).size + ""
+            "Content-Length": fileBuffer.length + ""
           },
-          method: "put"
+          body: new Uint8Array(fileBuffer)
         });
-        fs2.createReadStream(attachment.path).pipe(request);
-        await responseDataPromise;
+        if (!response.ok) {
+          throw new Error(`Request to ${uploadUrl} failed with ${response.status}`);
+        }
+        await response.arrayBuffer();
       }, HTTP_BACKOFF);
       return;
     }
-    let buffer = attachment.type === "buffer" ? attachment.body : await fs2.promises.readFile(attachment.path);
+    let buffer = attachment.type === "buffer" ? attachment.body : await fs.promises.readFile(attachment.path);
     assert(buffer);
     const encoding = compressable ? "br" : void 0;
     if (compressable)
       buffer = await compressTextAsync(buffer);
     const headers = {
       "Content-Type": attachment.contentType,
-      "Content-Length": Buffer.byteLength(buffer) + "",
-      "Content-Encoding": encoding
+      "Content-Length": Buffer.byteLength(buffer) + ""
     };
+    if (encoding) {
+      headers["Content-Encoding"] = encoding;
+    }
     await retryWithBackoff(async () => {
-      const { request, responseDataPromise } = httpUtils.createRequest({
-        url: uploadUrl,
+      const response = await fetch(uploadUrl, {
+        method: "PUT",
         headers,
-        method: "put"
+        body: new Uint8Array(buffer)
       });
-      request.write(buffer);
-      request.end();
-      await responseDataPromise;
+      if (!response.ok) {
+        throw new Error(`Request to ${uploadUrl} failed with ${response.status}`);
+      }
+      await response.arrayBuffer();
     }, HTTP_BACKOFF);
   }
-};
+}
 export {
   createDataAttachment,
   createFileAttachment,

package/lib/visitTests.js

@@ -1,4 +1,3 @@
-// src/visitTests.ts
 function visitTests(report, testVisitor) {
   function visitSuite(suite, parents) {
     parents.push(suite);

package/lib/writeReport.js

@@ -1,4 +1,3 @@
-// src/writeReport.ts
 import fs from "fs";
 import path from "path";
 async function writeReport(report, attachments, outputFolder) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flakiness/sdk",
-  "version": "0.149.0",
+  "version": "0.150.0",
   "private": false,
   "exports": {
     ".": {
@@ -17,18 +17,27 @@
   "type": "module",
   "description": "",
   "types": "./types/index.d.ts",
-  "scripts": {},
+  "scripts": {
+    "minor": "./version.mjs minor",
+    "patch": "./version.mjs patch"
+  },
   "keywords": [],
   "author": "Degu Labs, Inc",
-  "license": "Fair Source 100",
+  "license": "MIT",
   "devDependencies": {
-    "@types/babel__code-frame": "^7.0.6"
+    "@types/babel__code-frame": "^7.0.6",
+    "@types/debug": "^4.1.12",
+    "@types/node": "^25.0.3",
+    "esbuild": "^0.27.0",
+    "kubik": "^0.24.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.2"
   },
   "dependencies": {
     "@babel/code-frame": "^7.26.2",
     "@flakiness/flakiness-report": "^0.16.0",
     "chalk": "^5.6.2",
-    "debug": "^4.3.7",
+    "debug": "^4.4.3",
     "open": "^10.2.0",
     "stable-hash": "^0.0.6"
   }

package/types/src/_internalUtils.d.ts

@@ -0,0 +1,13 @@
+import { SpawnSyncOptionsWithStringEncoding } from 'child_process';
+import crypto from 'crypto';
+export declare function compressTextAsync(text: string | Buffer): Promise<Buffer>;
+export type Brand<T, Brand extends string> = T & {
+    readonly [B in Brand as `__${B}_brand`]: never;
+};
+export declare function errorText(error: Error): string | undefined;
+export declare function retryWithBackoff<T>(job: () => Promise<T>, backoff?: number[]): Promise<T>;
+export declare function shell(command: string, args?: string[], options?: SpawnSyncOptionsWithStringEncoding): string | undefined;
+export declare function sha1Text(data: crypto.BinaryLike): string;
+export declare function sha1File(filePath: string): Promise<string>;
+export declare function randomUUIDBase62(): string;
+//# sourceMappingURL=_internalUtils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"_internalUtils.d.ts","sourceRoot":"","sources":["../../src/_internalUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,kCAAkC,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,MAAM,MAAM,QAAQ,CAAC;AAQ5B,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ5E;AAED,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,KAAK,SAAS,MAAM,IAAI,CAAC,GAAG;IAC/C,QAAQ,EAAE,CAAC,IAAI,KAAK,IAAI,KAAK,CAAC,QAAQ,GAAG,KAAK;CAC/C,CAAC;AAGF,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,sBAErC;AAED,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAenG;AAED,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,kCAAkC,sBAWnG;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,UAAU,UAI/C;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAc1D;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAczC"}

package/types/src/browser.d.ts

@@ -0,0 +1,3 @@
+export { FlakinessReport } from '@flakiness/flakiness-report';
+export * as ReportUtils from './reportUtilsBrowser.js';
+//# sourceMappingURL=browser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC"}

package/types/src/ciUtils.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A collection of utilities to extract information about continuous integration providers.
+ *
+ * This namespace provides functions to automatically detect and extract useful information
+ * from various CI/CD environments, including GitHub Actions, Azure DevOps, Jenkins, and others.
+ */
+export declare namespace CIUtils {
+    /**
+     * Automatically extracts the run URL for common continuous integration providers.
+     *
+     * This function attempts to detect the current CI environment and construct the appropriate
+     * URL that links to the specific build/run where tests are being executed.
+     *
+     * Supported CI providers (checked in order):
+     * - GitHub Actions
+     * - Azure DevOps
+     * - GitLab CI (via `CI_JOB_URL` environment variable)
+     * - Jenkins (via `BUILD_URL` environment variable)
+     *
+     * @returns {string | undefined} The constructed CI run URL, or `undefined` if no supported
+     *   CI environment is detected or required environment variables are missing.
+     *
+     * @example
+     * ```typescript
+     * const report: FlakinessReport.Report = {
+     *   // ... other report properties
+     *   url: CIUtils.runUrl(),
+     * };
+     * ```
+     */
+    function runUrl(): string | undefined;
+}
+//# sourceMappingURL=ciUtils.d.ts.map

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

@@ -0,0 +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"}

package/types/src/createEnvironment.d.ts

@@ -0,0 +1,40 @@
+import { FlakinessReport } from '@flakiness/flakiness-report';
+/**
+ * Creates a Flakiness environment object with system information and user data.
+ *
+ * Automatically detects operating system details (name, architecture, version) and merges
+ * environment variables prefixed with `FK_ENV_` into the user-supplied data. This function
+ * is essential for creating environment metadata that helps identify test execution contexts
+ * in Flakiness reports.
+ *
+ * @param {Object} options - Configuration object for the environment.
+ * @param {string} options.name - Human-readable name for the environment (e.g., 'CI', 'Local Dev', 'Staging').
+ * @param {Record<string, string>} [options.userSuppliedData] - Additional key-value pairs to include
+ *   in the environment data. These are merged with `FK_ENV_*` environment variables.
+ * @param {any} [options.opaqueData] - Optional opaque data object that will be stored with the
+ *   environment but not used for environment deduplication.
+ *
+ * @returns {FlakinessReport.Environment} Environment object containing:
+ *   - `name` - The provided environment name
+ *   - `systemData` - Automatically detected OS information (arch, name, version)
+ *   - `userSuppliedData` - Merged data from `FK_ENV_*` variables and `userSuppliedData` option
+ *   - `opaqueData` - The provided opaque data, if any
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const env = createEnvironment({ name: 'CI' });
+ *
+ * // With custom data
+ * const env = createEnvironment({
+ *   name: 'Staging',
+ *   userSuppliedData: { region: 'us-east-1', instance: 'large' }
+ * });
+ * ```
+ */
+export declare function createEnvironment(options: {
+    name: string;
+    userSuppliedData?: Record<string, string>;
+    opaqueData?: any;
+}): FlakinessReport.Environment;
+//# sourceMappingURL=createEnvironment.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createEnvironment.d.ts","sourceRoot":"","sources":["../../src/createEnvironment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAwD9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,UAAU,CAAC,EAAE,GAAG,CAAC;CAClB,GAAG,eAAe,CAAC,WAAW,CAe9B"}

package/types/src/createTestStepSnippets.d.ts

@@ -0,0 +1,30 @@
+import { FlakinessReport } from '@flakiness/flakiness-report';
+import { GitWorktree } from './gitWorktree.js';
+/**
+ * Generates code snippets for test steps and attaches them to the report in-place.
+ *
+ * This function reads source files from the git worktree and creates highlighted code snippets
+ * for each test step that has a location. The snippets include 3 lines of context (1 before,
+ * the line itself, 1 after) with syntax highlighting and a visual indicator pointing to the
+ * exact column position.
+ *
+ * The snippets are attached directly to the `step.snippet` property of each test step in the
+ * report object. Steps without locations or with invalid file paths are silently skipped.
+ *
+ * @param {GitWorktree} worktree - Git worktree instance used to resolve file paths from
+ *   git-relative paths to absolute paths for reading source files.
+ *
+ * @param {FlakinessReport.Report} report - Flakiness report to process. The report is modified
+ *   in-place by adding `snippet` properties to test steps.
+ *
+ * @returns {void} This function modifies the report in-place and does not return a value.
+ *
+ * @example
+ * ```typescript
+ * const worktree = GitWorktree.create(process.cwd());
+ * createTestStepSnippetsInplace(worktree, report);
+ * // Report steps now have .snippet properties with highlighted code
+ * ```
+ */
+export declare function createTestStepSnippetsInplace(worktree: GitWorktree, report: FlakinessReport.Report): void;
+//# sourceMappingURL=createTestStepSnippets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"createTestStepSnippets.d.ts","sourceRoot":"","sources":["../../src/createTestStepSnippets.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,eAAe,CAAC,MAAM,QA4ClG"}

package/types/src/flakinessProjectConfig.d.ts

@@ -0,0 +1,103 @@
+type JSONConfig = {
+    projectPublicId?: string;
+    customReportViewerUrl?: string;
+};
+/**
+ * Manages Flakiness project configuration stored in `.flakiness/config.json`.
+ *
+ * The configuration file is automatically located by searching upward from the current working
+ * directory for an existing `.flakiness` folder, or by placing it at the git repository root
+ * if no existing config is found.
+ */
+export declare class FlakinessProjectConfig {
+    private _configPath;
+    private _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 load(): Promise<FlakinessProjectConfig>;
+    /**
+     * 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(): FlakinessProjectConfig;
+    constructor(_configPath: string, _config: JSONConfig);
+    /**
+     * Returns the absolute path to the configuration file.
+     *
+     * @returns {string} Absolute path to `.flakiness/config.json`.
+     */
+    path(): string;
+    /**
+     * 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(): string | undefined;
+    /**
+     * 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(): string;
+    /**
+     * 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: string | undefined): void;
+    /**
+     * Sets the project's public ID.
+     *
+     * @param {string | undefined} projectId - Project public ID to set, or `undefined` to clear.
+     */
+    setProjectPublicId(projectId: string | undefined): void;
+    /**
+     * 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();
+     * ```
+     */
+    save(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=flakinessProjectConfig.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flakinessProjectConfig.d.ts","sourceRoot":"","sources":["../../src/flakinessProjectConfig.ts"],"names":[],"mappings":"AAmCA,KAAK,UAAU,GAAG;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAA;AAED;;;;;;GAMG;AACH,qBAAa,sBAAsB;IA4C/B,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,OAAO;IA5CjB;;;;;;;;;;;;;;;OAeG;WACU,IAAI,IAAI,OAAO,CAAC,sBAAsB,CAAC;IAOpD;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,WAAW;gBAKR,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,UAAU;IAG7B;;;;OAIG;IACH,IAAI;IAIJ;;;;;;OAMG;IACH,eAAe;IAIf;;;;;OAKG;IACH,eAAe;IAIf;;;;;OAKG;IACH,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAC,SAAS;IAO9C;;;;OAIG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAC,SAAS;IAI9C;;;;;;;;;;;;;;;;OAgBG;IACG,IAAI;CAIX"}

package/types/src/gitWorktree.d.ts

@@ -0,0 +1,139 @@
+import { FlakinessReport } from '@flakiness/flakiness-report';
+/**
+ * Represents a git commit with its metadata.
+ *
+ * This type is returned by `GitWorktree.listCommits()` and contains all the information
+ * needed to identify and reference a commit in a git repository.
+ */
+export type GitCommit = {
+    /** Full commit hash (SHA-1, 40 characters) */
+    commitId: FlakinessReport.CommitId;
+    /** Commit timestamp in milliseconds since Unix epoch */
+    timestamp: FlakinessReport.UnixTimestampMS;
+    /** Commit message (subject line only) */
+    message: string;
+    /** Author name, if available */
+    author?: string;
+    /** Array of parent commit IDs (empty for initial commit, typically one for normal commits, multiple for merges) */
+    parents: FlakinessReport.CommitId[];
+};
+/**
+ * Utilities for working with git repositories and converting between git-relative paths
+ * and absolute native paths. Essential for creating Flakiness Reports where all paths
+ * must be relative to the git root.
+ */
+export declare class GitWorktree {
+    private _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: string): GitWorktree;
+    private _posixGitRoot;
+    constructor(_gitRoot: string);
+    /**
+     * 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(): string;
+    /**
+     * 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(): FlakinessReport.CommitId;
+    /**
+     * 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: string): FlakinessReport.GitFilePath;
+    /**
+     * 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: FlakinessReport.GitFilePath): string;
+    /**
+     * 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}`);
+     * ```
+     */
+    listCommits(count: number): Promise<GitCommit[]>;
+}
+//# sourceMappingURL=gitWorktree.d.ts.map