@flakiness/sdk 2.6.0 → 3.0.0

package/README.md

@@ -27,13 +27,16 @@ import {
 } from '@flakiness/sdk';
 
 // Initialize git worktree and environment
-const worktree = GitWorktree.create(process.cwd());
+const result = GitWorktree.initialize(process.cwd());
+if (!result.ok)
+  throw new Error(result.error);
+const { worktree, commitId } = result;
 const env = ReportUtils.createEnvironment({ name: 'CI' });
 
 // Create a simple test report
 const report: FlakinessReport.Report = {
   category: 'testreport',
-  commitId: worktree.headCommitId(),
+  commitId,
   title: process.env.FLAKINESS_TITLE,
   url: CIUtils.runUrl(),
   environments: [env],

package/lib/browser.js

@@ -33,6 +33,7 @@ function normalizeReport(report) {
     return {
       ...step,
       duration: step.duration === 0 ? void 0 : step.duration,
+      attachments: step.attachments && step.attachments.length ? step.attachments : void 0,
       steps: step.steps && step.steps.length ? step.steps.map(cleanupTestStep) : void 0
     };
   }

package/lib/index.js

@@ -251,29 +251,48 @@ var GitWorktree = class _GitWorktree {
     this._posixGitRoot = toPosixAbsolutePath(this._gitRoot);
   }
   /**
-   * Creates a GitWorktree instance from any path inside a git repository.
+   * Initializes a GitWorktree for any path inside a git repository and resolves the
+   * HEAD commit id in a single call.
    *
-   * @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.
+   * Unlike a constructor, this method never throws — callers check `result.ok` and bail
+   * out early, after which TypeScript narrows `worktree` and `commitId` on the result.
    *
-   * @returns {GitWorktree} A new GitWorktree instance bound to the discovered git root.
+   * @param {string} somePathInsideGitRepo - Any path (file or directory) within a git
+   *   repository. Can be absolute or relative. The function will locate the git root.
    *
-   * @throws {Error} Throws if the path is not inside a git repository or if git commands fail.
+   * @returns {GitWorktreeInitResult} `{ ok: true, worktree, commitId }` on success, or
+   *   `{ ok: false, error }` describing what went wrong.
    *
    * @example
    * ```typescript
-   * const worktree = GitWorktree.create('./src/my-test.ts');
-   * const gitRoot = worktree.rootPath();
+   * const result = GitWorktree.initialize('./src/my-test.ts');
+   * if (!result.ok) {
+   *   console.error(result.error);
+   *   return;
+   * }
+   * // result.worktree and result.commitId are narrowed to non-undefined here.
    * ```
    */
-  static create(somePathInsideGitRepo) {
+  static initialize(somePathInsideGitRepo) {
     const root = shell(`git`, ["rev-parse", "--show-toplevel"], {
       cwd: somePathInsideGitRepo,
       encoding: "utf-8",
       env: GIT_SAFE_ENV
     });
-    assert(root, `FAILED: git rev-parse --show-toplevel HEAD @ ${somePathInsideGitRepo}`);
-    return new _GitWorktree(root);
+    if (!root)
+      return { ok: false, error: `FAILED: git rev-parse --show-toplevel @ ${somePathInsideGitRepo}` };
+    const sha = shell(`git`, ["rev-parse", "HEAD"], {
+      cwd: root,
+      encoding: "utf-8",
+      env: GIT_SAFE_ENV
+    });
+    if (!sha)
+      return { ok: false, error: `FAILED: git rev-parse HEAD @ ${root}` };
+    return {
+      ok: true,
+      worktree: new _GitWorktree(root),
+      commitId: sha.trim()
+    };
   }
   _posixGitRoot;
   /**
@@ -292,28 +311,6 @@ var GitWorktree = class _GitWorktree {
   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",
-      env: GIT_SAFE_ENV
-    });
-    assert(sha, `FAILED: git rev-parse HEAD @ ${this._gitRoot}`);
-    return sha.trim();
-  }
   /**
    * Converts a native absolute path to a git-relative POSIX path.
    *
@@ -703,6 +700,7 @@ function normalizeReport(report) {
     return {
       ...step,
       duration: step.duration === 0 ? void 0 : step.duration,
+      attachments: step.attachments && step.attachments.length ? step.attachments : void 0,
       steps: step.steps && step.steps.length ? step.steps.map(cleanupTestStep) : void 0
     };
   }
@@ -1101,21 +1099,31 @@ async function readReport(reportFolder) {
   const filenameToPath = new Map(attachmentFiles.map((file) => [path.basename(file), file]));
   const attachmentIdToPath = /* @__PURE__ */ new Map();
   const missingAttachments = /* @__PURE__ */ new Map();
+  const visitAttachment = (attachment) => {
+    const attachmentPath = filenameToPath.get(attachment.id);
+    if (!attachmentPath) {
+      missingAttachments.set(attachment.id, attachment);
+    } else {
+      attachmentIdToPath.set(attachment.id, {
+        contentType: attachment.contentType,
+        id: attachment.id,
+        path: attachmentPath,
+        type: "file"
+      });
+    }
+  };
+  const visitStep = (step) => {
+    for (const attachment of step.attachments ?? [])
+      visitAttachment(attachment);
+    for (const childStep of step.steps ?? [])
+      visitStep(childStep);
+  };
   visitTests(report, (test) => {
     for (const attempt of test.attempts) {
-      for (const attachment of attempt.attachments ?? []) {
-        const attachmentPath = filenameToPath.get(attachment.id);
-        if (!attachmentPath) {
-          missingAttachments.set(attachment.id, attachment);
-        } else {
-          attachmentIdToPath.set(attachment.id, {
-            contentType: attachment.contentType,
-            id: attachment.id,
-            path: attachmentPath,
-            type: "file"
-          });
-        }
-      }
+      for (const attachment of attempt.attachments ?? [])
+        visitAttachment(attachment);
+      for (const step of attempt.steps ?? [])
+        visitStep(step);
     }
   });
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flakiness/sdk",
-  "version": "2.6.0",
+  "version": "3.0.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
     "node": "^20.17.0 || >=22.9.0"
   },
   "devDependencies": {
-    "@flakiness/flakiness-report": "^0.28.0",
+    "@flakiness/flakiness-report": "^0.31.0",
     "@flakiness/playwright": "^1.3.3",
     "@playwright/test": "^1.58.2",
     "@types/debug": "^4.1.12",

package/types/src/gitWorktree.d.ts

@@ -17,6 +17,18 @@ export type GitCommit = {
     /** Array of parent commit IDs (empty for initial commit, typically one for normal commits, multiple for merges) */
     parents: FlakinessReport.CommitId[];
 };
+/**
+ * Result of {@link GitWorktree.initialize}. A tagged discriminated union:
+ * check `ok` and TypeScript narrows the rest of the fields.
+ */
+export type GitWorktreeInitResult = {
+    ok: true;
+    worktree: GitWorktree;
+    commitId: FlakinessReport.CommitId;
+} | {
+    ok: false;
+    error: string;
+};
 /**
  * Utilities for working with git repositories and converting between git-relative paths
  * and absolute native paths. Essential for creating Flakiness Reports where all paths
@@ -25,22 +37,29 @@ export type GitCommit = {
 export declare class GitWorktree {
     private _gitRoot;
     /**
-     * Creates a GitWorktree instance from any path inside a git repository.
+     * Initializes a GitWorktree for any path inside a git repository and resolves the
+     * HEAD commit id in a single call.
      *
-     * @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.
+     * Unlike a constructor, this method never throws — callers check `result.ok` and bail
+     * out early, after which TypeScript narrows `worktree` and `commitId` on the result.
      *
-     * @returns {GitWorktree} A new GitWorktree instance bound to the discovered git root.
+     * @param {string} somePathInsideGitRepo - Any path (file or directory) within a git
+     *   repository. Can be absolute or relative. The function will locate the git root.
      *
-     * @throws {Error} Throws if the path is not inside a git repository or if git commands fail.
+     * @returns {GitWorktreeInitResult} `{ ok: true, worktree, commitId }` on success, or
+     *   `{ ok: false, error }` describing what went wrong.
      *
      * @example
      * ```typescript
-     * const worktree = GitWorktree.create('./src/my-test.ts');
-     * const gitRoot = worktree.rootPath();
+     * const result = GitWorktree.initialize('./src/my-test.ts');
+     * if (!result.ok) {
+     *   console.error(result.error);
+     *   return;
+     * }
+     * // result.worktree and result.commitId are narrowed to non-undefined here.
      * ```
      */
-    static create(somePathInsideGitRepo: string): GitWorktree;
+    static initialize(somePathInsideGitRepo: string): GitWorktreeInitResult;
     private _posixGitRoot;
     constructor(_gitRoot: string);
     /**
@@ -57,20 +76,6 @@ export declare class GitWorktree {
      * ```
      */
     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.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"gitWorktree.d.ts","sourceRoot":"","sources":["../../src/gitWorktree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAwB9D;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,8CAA8C;IAC9C,QAAQ,EAAE,eAAe,CAAC,QAAQ,CAAC;IACnC,wDAAwD;IACxD,SAAS,EAAE,eAAe,CAAC,eAAe,CAAC;IAC3C,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mHAAmH;IACnH,OAAO,EAAE,eAAe,CAAC,QAAQ,EAAE,CAAC;CACrC,CAAA;AAyCD;;;;GAIG;AACH,qBAAa,WAAW;IA6BV,OAAO,CAAC,QAAQ;IA5B5B;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,MAAM,CAAC,qBAAqB,EAAE,MAAM;IAU3C,OAAO,CAAC,aAAa,CAAoB;gBAErB,QAAQ,EAAE,MAAM;IAIpC;;;;;;;;;;;;OAYG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;;;;;;;;;;OAYG;IACH,YAAY,IAAI,eAAe,CAAC,QAAQ;IAUxC;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,eAAe,CAAC,WAAW;IAI1D;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,CAAC,YAAY,EAAE,eAAe,CAAC,WAAW,GAAG,MAAM;IAI/D;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;CAGvD"}
+{"version":3,"file":"gitWorktree.d.ts","sourceRoot":"","sources":["../../src/gitWorktree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAwB9D;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,8CAA8C;IAC9C,QAAQ,EAAE,eAAe,CAAC,QAAQ,CAAC;IACnC,wDAAwD;IACxD,SAAS,EAAE,eAAe,CAAC,eAAe,CAAC;IAC3C,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mHAAmH;IACnH,OAAO,EAAE,eAAe,CAAC,QAAQ,EAAE,CAAC;CACrC,CAAA;AAyCD;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,eAAe,CAAC,QAAQ,CAAA;CAAE,GACvE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC;;;;GAIG;AACH,qBAAa,WAAW;IAkDV,OAAO,CAAC,QAAQ;IAjD5B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,UAAU,CAAC,qBAAqB,EAAE,MAAM,GAAG,qBAAqB;IAwBvE,OAAO,CAAC,aAAa,CAAoB;gBAErB,QAAQ,EAAE,MAAM;IAIpC;;;;;;;;;;;;OAYG;IACH,QAAQ,IAAI,MAAM;IAIlB;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,eAAe,CAAC,WAAW;IAI1D;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,CAAC,YAAY,EAAE,eAAe,CAAC,WAAW,GAAG,MAAM;IAI/D;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;CAGvD"}

package/types/src/index.d.ts

@@ -1,6 +1,6 @@
 export { CIUtils } from './ciUtils.js';
 export { CPUUtilization } from './cpuUtilization.js';
-export { GitWorktree } from './gitWorktree.js';
+export { GitWorktree, type GitWorktreeInitResult } from './gitWorktree.js';
 export { RAMUtilization } from './ramUtilization.js';
 export { GithubOIDC } from './githubOIDC.js';
 export * as ReportUtils from './reportUtils.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC;AAGhD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAC;AAGhD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"normalizeReport.d.ts","sourceRoot":"","sources":["../../src/normalizeReport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAyB9D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,CAAC,MAAM,GAAG,eAAe,CAAC,MAAM,CAmDtF"}
+{"version":3,"file":"normalizeReport.d.ts","sourceRoot":"","sources":["../../src/normalizeReport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAyB9D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,CAAC,MAAM,GAAG,eAAe,CAAC,MAAM,CAoDtF"}

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

@@ -1 +1 @@
-{"version":3,"file":"readReport.d.ts","sourceRoot":"","sources":["../../src/readReport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAG9D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAsB,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9D,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC;IAC/B,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,kBAAkB,EAAE,eAAe,CAAC,UAAU,EAAE,CAAC;CAClD,CAAC,CA0CD"}
+{"version":3,"file":"readReport.d.ts","sourceRoot":"","sources":["../../src/readReport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAG9D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAsB,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9D,MAAM,EAAE,eAAe,CAAC,MAAM,CAAC;IAC/B,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,kBAAkB,EAAE,eAAe,CAAC,UAAU,EAAE,CAAC;CAClD,CAAC,CAoDD"}