@argos-ci/core 6.3.0 → 6.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -7,17 +7,45 @@
7
7
  </a>
8
8
  </p>
9
9
 
10
- <p align="center"><strong>The open source visual testing plaform for modern engineering teams.</strong></p>
10
+ <p align="center"><strong>The open source visual testing platform for AI-native engineering teams.</strong></p>
11
11
 
12
- # Argos JavaScript SDK Core
12
+ # Argos Node.js SDK
13
13
 
14
- Argos Core JavaScript SDK contains interface definitions, base classes and utilities for building Argos JavaScript SDKs, like `@argos-ci/cli` or using it directly with Node.js.
14
+ Node.js SDK for visual testing with Argos. It powers the Argos CLI and the higher-level integrations (Playwright, Cypress, …), and can be used directly to upload screenshots from Node.js.
15
15
 
16
16
  [![npm version](https://img.shields.io/npm/v/@argos-ci/core.svg)](https://www.npmjs.com/package/@argos-ci/core)
17
17
  [![npm dm](https://img.shields.io/npm/dm/@argos-ci/core.svg)](https://www.npmjs.com/package/@argos-ci/core)
18
18
  [![npm dt](https://img.shields.io/npm/dt/@argos-ci/core.svg)](https://www.npmjs.com/package/@argos-ci/core)
19
19
 
20
+ Visit the [Node.js SDK documentation](https://argos-ci.com/docs/sdks-reference/node.js-sdk) for guides, the API reference, and more.
21
+
22
+ ## Installation
23
+
24
+ ```sh
25
+ npm install @argos-ci/core
26
+ ```
27
+
28
+ ## Usage
29
+
30
+ Upload a directory of screenshots to Argos and create a build:
31
+
32
+ ```ts
33
+ import { upload } from "@argos-ci/core";
34
+
35
+ const { build } = await upload({
36
+ // Directory containing the screenshots.
37
+ root: "./screenshots",
38
+ // Globs matching the screenshots to upload.
39
+ files: ["**/*.png"],
40
+ // Defaults to the ARGOS_TOKEN environment variable.
41
+ token: process.env.ARGOS_TOKEN,
42
+ });
43
+
44
+ console.log(`Build created: ${build.url}`);
45
+ ```
46
+
20
47
  ## Links
21
48
 
22
- - [Official SDK Docs](https://argos-ci.com/docs)
49
+ - [Official SDK Docs](https://argos-ci.com/docs/sdks-reference/node.js-sdk)
23
50
  - [API Reference](https://js-sdk-reference.argos-ci.com)
51
+ - [Discord](https://argos-ci.com/discord)
package/dist/index.d.mts CHANGED
@@ -101,7 +101,7 @@ interface Config {
101
101
  * Build mode to use.
102
102
  * - "ci": Review visual changes introduced by a feature branch and prevent regressions.
103
103
  * - "monitoring": Track visual changes outside the standard CI flow, either on a schedule or before a release.
104
- * @see https://argos-ci.com/docs/build-modes
104
+ * @see https://argos-ci.com/docs/learn/platform-fundamentals/build-modes
105
105
  */
106
106
  mode: "ci" | "monitoring" | null;
107
107
  /**
@@ -248,6 +248,12 @@ declare function finalize(params: FinalizeParameters): Promise<{
248
248
  }[];
249
249
  }>;
250
250
  //#endregion
251
+ //#region src/mime-type.d.ts
252
+ /**
253
+ * Get the mime type of a snapshot file based on its extension.
254
+ */
255
+ declare function getSnapshotMimeType(filepath: string): string;
256
+ //#endregion
251
257
  //#region src/upload.d.ts
252
258
  type BuildMetadata = ArgosAPISchema.components["schemas"]["BuildMetadata"];
253
259
  interface UploadParameters {
@@ -301,7 +307,7 @@ interface UploadParameters {
301
307
  * Build mode to use.
302
308
  * - "ci": Review the visual changes introduced by a feature branch and prevent regressions.
303
309
  * - "monitoring": Track visual changes outside the standard CI flow, either on a schedule or before a release.
304
- * @see https://argos-ci.com/docs/build-modes
310
+ * @see https://argos-ci.com/docs/learn/platform-fundamentals/build-modes
305
311
  * @default "ci"
306
312
  */
307
313
  mode?: "ci" | "monitoring";
@@ -381,4 +387,4 @@ declare function skip(params: SkipParameters): Promise<{
381
387
  build: ArgosAPISchema.components["schemas"]["Build"];
382
388
  }>;
383
389
  //#endregion
384
- export { Config, DeployParameters, FinalizeParameters, UploadParameters, deploy, finalize, getConfigFromOptions, readConfig, skip, upload };
390
+ export { Config, DeployParameters, FinalizeParameters, UploadParameters, deploy, finalize, getConfigFromOptions, getSnapshotMimeType, readConfig, skip, upload };
package/dist/index.mjs CHANGED
@@ -180,18 +180,32 @@ function listShas(path, maxCount) {
180
180
  args.push(path);
181
181
  return execFileSync("git", args).toString().trim().split("\n");
182
182
  }
183
- async function listParentCommits$1(input) {
184
- const limit = 200;
183
+ /**
184
+ * List the ancestor commits of a commit, ordered from the closest to the
185
+ * furthest ancestor, up to `limit` commits. The commit itself is excluded.
186
+ *
187
+ * The history is deepened with a shallow fetch so this works on the shallow
188
+ * clones typically used in CI. When the commit is not on the remote (e.g. not
189
+ * pushed yet) or the fetch fails, we fall back to whatever local history is
190
+ * available; when the commit is unknown locally too, we return an empty list.
191
+ */
192
+ async function listAncestorCommits$1(input) {
193
+ const depth = input.limit + 1;
185
194
  try {
186
195
  await runGitFetch([
187
- `--depth=${limit}`,
196
+ `--depth=${depth}`,
188
197
  "origin",
189
198
  input.sha
190
199
  ]);
191
200
  } catch (error) {
192
- if (getGitErrorOutput(error).includes("not our ref")) return [];
201
+ debug(`Failed to deepen history for ${input.sha}, using local history`, getGitErrorOutput(error));
202
+ }
203
+ try {
204
+ return listShas(input.sha, depth).slice(1);
205
+ } catch (error) {
206
+ debug(`Failed to list ancestors of ${input.sha}`, getGitErrorOutput(error));
207
+ return [];
193
208
  }
194
- return listShas(input.sha, limit);
195
209
  }
196
210
  //#endregion
197
211
  //#region src/ci-environment/services/bitrise.ts
@@ -226,7 +240,7 @@ const service$7 = {
226
240
  };
227
241
  },
228
242
  getMergeBaseCommitSha: getMergeBaseCommitSha$1,
229
- listParentCommits: listParentCommits$1
243
+ listAncestorCommits: listAncestorCommits$1
230
244
  };
231
245
  //#endregion
232
246
  //#region src/util/url.ts
@@ -270,7 +284,7 @@ const service$6 = {
270
284
  };
271
285
  },
272
286
  getMergeBaseCommitSha: getMergeBaseCommitSha$1,
273
- listParentCommits: listParentCommits$1
287
+ listAncestorCommits: listAncestorCommits$1
274
288
  };
275
289
  //#endregion
276
290
  //#region src/ci-environment/services/heroku.ts
@@ -293,7 +307,7 @@ const service$5 = {
293
307
  nonce: env.HEROKU_TEST_RUN_ID || null
294
308
  }),
295
309
  getMergeBaseCommitSha: getMergeBaseCommitSha$1,
296
- listParentCommits: listParentCommits$1
310
+ listAncestorCommits: listAncestorCommits$1
297
311
  };
298
312
  //#endregion
299
313
  //#region src/ci-environment/github.ts
@@ -322,7 +336,7 @@ To resolve this, Argos requires a GITHUB_TOKEN to fetch the pull request associa
322
336
 
323
337
  GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
324
338
 
325
- For more details, check out the documentation: Read more at https://argos-ci.com/docs/run-on-preview-deployment
339
+ For more details, check out the documentation: Read more at https://argos-ci.com/docs/learn/how-to-guides/ci-pipelines/run-on-preview-deployments
326
340
 
327
341
  If you want to disable this warning, you can set the following environment variable:
328
342
 
@@ -564,7 +578,7 @@ const service$4 = {
564
578
  };
565
579
  },
566
580
  getMergeBaseCommitSha: getMergeBaseCommitSha$1,
567
- listParentCommits: listParentCommits$1
581
+ listAncestorCommits: listAncestorCommits$1
568
582
  };
569
583
  //#endregion
570
584
  //#region src/ci-environment/services/circleci.ts
@@ -605,7 +619,7 @@ const service$3 = {
605
619
  };
606
620
  },
607
621
  getMergeBaseCommitSha: getMergeBaseCommitSha$1,
608
- listParentCommits: listParentCommits$1
622
+ listAncestorCommits: listAncestorCommits$1
609
623
  };
610
624
  //#endregion
611
625
  //#region src/ci-environment/services/travis.ts
@@ -644,7 +658,7 @@ const service$2 = {
644
658
  };
645
659
  },
646
660
  getMergeBaseCommitSha: getMergeBaseCommitSha$1,
647
- listParentCommits: listParentCommits$1
661
+ listAncestorCommits: listAncestorCommits$1
648
662
  };
649
663
  //#endregion
650
664
  //#region src/ci-environment/services/gitlab.ts
@@ -678,7 +692,7 @@ const service$1 = {
678
692
  };
679
693
  },
680
694
  getMergeBaseCommitSha: getMergeBaseCommitSha$1,
681
- listParentCommits: listParentCommits$1
695
+ listAncestorCommits: listAncestorCommits$1
682
696
  };
683
697
  //#endregion
684
698
  //#region src/ci-environment/services/git.ts
@@ -718,7 +732,7 @@ const services = [
718
732
  };
719
733
  },
720
734
  getMergeBaseCommitSha: getMergeBaseCommitSha$1,
721
- listParentCommits: listParentCommits$1
735
+ listAncestorCommits: listAncestorCommits$1
722
736
  }
723
737
  ];
724
738
  /**
@@ -743,13 +757,13 @@ function getMergeBaseCommitSha(input) {
743
757
  return service.getMergeBaseCommitSha(input, context);
744
758
  }
745
759
  /**
746
- * Get the merge base commit.
760
+ * List the ancestor commits of a commit, closest first, up to `limit` commits.
747
761
  */
748
- function listParentCommits(input) {
762
+ function listAncestorCommits(input) {
749
763
  const context = createContext();
750
764
  const service = getCiService(context);
751
- if (!service) return Promise.resolve(null);
752
- return service.listParentCommits(input, context);
765
+ if (!service) return Promise.resolve([]);
766
+ return service.listAncestorCommits(input, context);
753
767
  }
754
768
  /**
755
769
  * Get the CI environment.
@@ -1371,6 +1385,16 @@ async function finalize(params) {
1371
1385
  return finalizeBuildsResult.data;
1372
1386
  }
1373
1387
  //#endregion
1388
+ //#region src/mime-type.ts
1389
+ /**
1390
+ * Get the mime type of a snapshot file based on its extension.
1391
+ */
1392
+ function getSnapshotMimeType(filepath) {
1393
+ const type = mime.lookup(filepath);
1394
+ if (!type) throw new Error(`Unable to determine snapshot file type for: ${filepath}`);
1395
+ return type;
1396
+ }
1397
+ //#endregion
1374
1398
  //#region src/discovery.ts
1375
1399
  /**
1376
1400
  * Discover snapshots in the given root directory matching the provided patterns.
@@ -1460,15 +1484,92 @@ const require = createRequire(import.meta.url);
1460
1484
  async function getArgosCoreSDKIdentifier() {
1461
1485
  return `@argos-ci/core@${await readVersionFromPackage(require.resolve("@argos-ci/core/package.json"))}`;
1462
1486
  }
1463
- //#endregion
1464
- //#region src/mime-type.ts
1465
1487
  /**
1466
- * Get the mime type of a snapshot file based on its extension.
1488
+ * Maximum number of commits inspected before giving up.
1467
1489
  */
1468
- function getSnapshotMimeType(filepath) {
1469
- const type = mime.lookup(filepath);
1470
- if (!type) throw new Error(`Unable to determine snapshot file type for: ${filepath}`);
1471
- return type;
1490
+ const MAX_COMMITS = 5e3;
1491
+ /**
1492
+ * Cumulative number of commits to inspect after each batch: 100, 600, 1100, …,
1493
+ * up to {@link MAX_COMMITS}.
1494
+ */
1495
+ function getCumulativeBatchSizes() {
1496
+ const sizes = [];
1497
+ let total = Math.min(100, MAX_COMMITS);
1498
+ sizes.push(total);
1499
+ while (total < MAX_COMMITS) {
1500
+ total = Math.min(total + 500, MAX_COMMITS);
1501
+ sizes.push(total);
1502
+ }
1503
+ return sizes;
1504
+ }
1505
+ /**
1506
+ * Find the reference commit by asking the API to pick the closest commit that
1507
+ * has an eligible baseline build, among a list of candidate commits ordered from
1508
+ * the closest to the furthest ancestor. That build's commit becomes the
1509
+ * reference commit.
1510
+ *
1511
+ * Commits are inspected in growing batches ({@link FIRST_BATCH_SIZE}, then
1512
+ * {@link NEXT_BATCH_SIZE} per request, up to {@link MAX_COMMITS}) so the common
1513
+ * case resolves quickly without fetching and sending the whole history.
1514
+ */
1515
+ async function findReferenceCommit(params) {
1516
+ let inspectedCount = 0;
1517
+ for (const limit of getCumulativeBatchSizes()) {
1518
+ const commits = await params.listCommits(limit);
1519
+ const batch = commits.slice(inspectedCount);
1520
+ if (batch.length === 0) break;
1521
+ debug(`Looking for a baseline among ${batch.length} commit(s)`);
1522
+ const baseline = await params.findBaseline(batch);
1523
+ if (baseline) {
1524
+ debug("Found baseline build for reference commit", baseline.head.sha);
1525
+ return baseline.head.sha;
1526
+ }
1527
+ inspectedCount = commits.length;
1528
+ if (commits.length < limit) break;
1529
+ }
1530
+ debug("No eligible baseline found among ancestor commits");
1531
+ return null;
1532
+ }
1533
+ /**
1534
+ * Resolve the baseline for a build that has no remote content access (no Git
1535
+ * provider connected).
1536
+ *
1537
+ * 1. Find the merge base — the closest common ancestor of the build branch and
1538
+ * its base branch. This is always the starting point.
1539
+ * 2. From the merge base, ask the API to pick the closest commit (the merge base
1540
+ * itself or one of its ancestors) that has an eligible baseline build, and use
1541
+ * it as the reference commit.
1542
+ * 3. If none is found, the baseline build may still be processing on the server.
1543
+ * Fall back to the merge base as the reference commit and send its parent
1544
+ * commits so the server can resolve the baseline once that build completes.
1545
+ */
1546
+ async function resolveBaseline(params) {
1547
+ const mergeBase = await params.getMergeBase();
1548
+ if (!mergeBase) {
1549
+ debug("No merge base found");
1550
+ return {
1551
+ referenceCommit: null,
1552
+ parentCommits: null
1553
+ };
1554
+ }
1555
+ debug("Found merge base", mergeBase);
1556
+ const referenceCommit = await findReferenceCommit({
1557
+ listCommits: (limit) => params.listCommits(mergeBase, limit),
1558
+ findBaseline: params.findBaseline
1559
+ });
1560
+ if (referenceCommit) {
1561
+ debug("Found reference commit from baseline", referenceCommit);
1562
+ return {
1563
+ referenceCommit,
1564
+ parentCommits: null
1565
+ };
1566
+ }
1567
+ const parentCommits = await params.listCommits(mergeBase, 300);
1568
+ debug("No baseline found, using merge base with parent commits", mergeBase);
1569
+ return {
1570
+ referenceCommit: mergeBase,
1571
+ parentCommits
1572
+ };
1472
1573
  }
1473
1574
  //#endregion
1474
1575
  //#region src/skip.ts
@@ -1577,29 +1678,41 @@ async function upload(params) {
1577
1678
  if (projectResponse.error) throwAPIError(projectResponse.error, projectResponse.response);
1578
1679
  debug("Project fetched", projectResponse.data);
1579
1680
  const { defaultBaseBranch, hasRemoteContentAccess } = projectResponse.data;
1580
- const referenceCommit = await (async () => {
1681
+ const listCommits = async (sha, limit) => {
1682
+ return [sha, ...await listAncestorCommits({
1683
+ sha,
1684
+ limit: limit - 1
1685
+ })];
1686
+ };
1687
+ const { referenceCommit, parentCommits } = await (async () => {
1581
1688
  if (config.referenceCommit) {
1582
1689
  debug("Found reference commit in config", config.referenceCommit);
1583
- return config.referenceCommit;
1690
+ return {
1691
+ referenceCommit: config.referenceCommit,
1692
+ parentCommits: await listCommits(config.referenceCommit, 300)
1693
+ };
1584
1694
  }
1585
- if (hasRemoteContentAccess) return null;
1586
- const sha = await getMergeBaseCommitSha({
1587
- base: config.referenceBranch || config.prBaseBranch || defaultBaseBranch,
1588
- head: config.branch
1695
+ if (hasRemoteContentAccess) return {
1696
+ referenceCommit: null,
1697
+ parentCommits: null
1698
+ };
1699
+ const base = config.referenceBranch || config.prBaseBranch || defaultBaseBranch;
1700
+ return resolveBaseline({
1701
+ getMergeBase: () => getMergeBaseCommitSha({
1702
+ base,
1703
+ head: config.branch
1704
+ }),
1705
+ listCommits,
1706
+ findBaseline: async (commits) => {
1707
+ const response = await apiClient.POST("/baseline", { body: {
1708
+ commits,
1709
+ name: config.buildName ?? void 0,
1710
+ mode: config.mode ?? void 0
1711
+ } });
1712
+ if (response.error) throwAPIError(response.error, response.response);
1713
+ return response.data.baseline;
1714
+ }
1589
1715
  });
1590
- if (sha) debug("Found merge base", sha);
1591
- else debug("No merge base found");
1592
- return sha;
1593
- })();
1594
- const parentCommits = await (async () => {
1595
- if (hasRemoteContentAccess) return null;
1596
- if (referenceCommit) {
1597
- const commits = await listParentCommits({ sha: referenceCommit });
1598
- if (commits) debug("Found parent commits", commits);
1599
- else debug("No parent commits found");
1600
- return commits;
1601
- }
1602
- return null;
1603
1716
  })();
1604
1717
  debug("Creating build");
1605
1718
  const pwTraceKeys = [];
@@ -1719,4 +1832,4 @@ function formatPreviewUrl(url, formatter) {
1719
1832
  return new URL(urlObj.pathname + urlObj.search + urlObj.hash, formatter.baseUrl).href;
1720
1833
  }
1721
1834
  //#endregion
1722
- export { deploy, finalize, getConfigFromOptions, readConfig, skip, upload };
1835
+ export { deploy, finalize, getConfigFromOptions, getSnapshotMimeType, readConfig, skip, upload };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@argos-ci/core",
3
3
  "description": "Node.js SDK for visual testing with Argos.",
4
- "version": "6.3.0",
4
+ "version": "6.5.0",
5
5
  "type": "module",
6
6
  "exports": {
7
7
  ".": {
@@ -18,7 +18,7 @@
18
18
  "url": "https://github.com/argos-ci/argos-javascript.git",
19
19
  "directory": "packages/core"
20
20
  },
21
- "homepage": "https://argos-ci.com/docs/node-sdk",
21
+ "homepage": "https://argos-ci.com/docs/sdks-reference/node.js-sdk",
22
22
  "bugs": {
23
23
  "url": "https://github.com/argos-ci/argos-javascript/issues"
24
24
  },
@@ -39,8 +39,8 @@
39
39
  "access": "public"
40
40
  },
41
41
  "dependencies": {
42
- "@argos-ci/api-client": "0.23.0",
43
- "@argos-ci/util": "4.0.0",
42
+ "@argos-ci/api-client": "0.24.1",
43
+ "@argos-ci/util": "4.0.1",
44
44
  "convict": "^6.2.5",
45
45
  "debug": "^4.4.3",
46
46
  "fast-glob": "^3.3.3",
@@ -68,5 +68,5 @@
68
68
  "lint": "eslint .",
69
69
  "test": "vitest"
70
70
  },
71
- "gitHead": "a2fb6e1a811e66f3839293ea5a71e93fee838aac"
71
+ "gitHead": "7fddaad1a6bb251a1f2eecbf8f4ecfa3e84e9b97"
72
72
  }