@argos-ci/cli 6.2.0 → 6.3.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.
Files changed (2) hide show
  1. package/dist/index.mjs +202 -12
  2. package/package.json +4 -4
package/dist/index.mjs CHANGED
@@ -17,6 +17,19 @@ const buildNameOption = new Option("--build-name <string>", "Name of the build,
17
17
  const accountOption = new Option("--account <slug>", "Slug of the account (personal or team) that will own the project");
18
18
  const jsonOption = new Option("--json", "Output machine-readable JSON instead of human-readable text");
19
19
  const projectPathOption = new Option("--project <owner/project>", "Project path in owner/project format. Required for build-number references on review and comment commands");
20
+ const changeProjectPathOption = new Option("--project <owner/project>", "Project the change belongs to, in owner/project format. Also ARGOS_PROJECT");
21
+ const METRICS_PERIOD_BY_CHOICE = {
22
+ "24h": "LAST_24_HOURS",
23
+ "3d": "LAST_3_DAYS",
24
+ "7d": "LAST_7_DAYS",
25
+ "30d": "LAST_30_DAYS",
26
+ "90d": "LAST_90_DAYS"
27
+ };
28
+ const metricsPeriodOption = new Option("--metrics-period <period>", "Window over which test flakiness metrics are computed").choices(Object.keys(METRICS_PERIOD_BY_CHOICE)).default("7d");
29
+ /** Map a `--metrics-period` choice to the value the API expects. */
30
+ function toMetricsPeriod(choice) {
31
+ return METRICS_PERIOD_BY_CHOICE[choice] ?? "LAST_7_DAYS";
32
+ }
20
33
  //#endregion
21
34
  //#region src/commands/upload.ts
22
35
  function uploadCommand(program) {
@@ -196,6 +209,32 @@ function formatBuild(build) {
196
209
  `URL: ${build.url}`
197
210
  ].join("\n");
198
211
  }
212
+ /** Render a 0–1 metric to two decimals, or `-` when absent. */
213
+ function formatRatio(value) {
214
+ return value === null || value === void 0 ? "-" : value.toFixed(2);
215
+ }
216
+ /** Compact one-line summary of a test's flakiness metrics. */
217
+ function formatFlakiness(metrics) {
218
+ return `${formatRatio(metrics.flakiness)} (stability ${formatRatio(metrics.stability)}, consistency ${formatRatio(metrics.consistency)})`;
219
+ }
220
+ /** Human-readable lines for a single snapshot diff. */
221
+ function formatSnapshotDiff(diff, build) {
222
+ const lines = [
223
+ `${diff.name} [${diff.status}]`,
224
+ ` Review: ${build.url}/${diff.id}`,
225
+ ` Mask: ${formatValue(diff.url)}`,
226
+ ` Base file: ${formatValue(diff.base?.url)}`,
227
+ ` Head file: ${formatValue(diff.head?.url)}`,
228
+ ` Score: ${formatValue(diff.score)}`,
229
+ ` Group: ${formatValue(diff.group)}`
230
+ ];
231
+ if (diff.test) lines.push(` Flakiness: ${formatFlakiness(diff.test.metrics)}`);
232
+ if (diff.change) {
233
+ const ignored = diff.change.ignored ? " [ignored]" : "";
234
+ lines.push(` Change: ${diff.change.id}${ignored} · ${diff.change.occurrences} occurrences`);
235
+ }
236
+ return lines;
237
+ }
199
238
  function formatSnapshots(diffs, build) {
200
239
  if (diffs.length === 0) return "No snapshots found.";
201
240
  return [
@@ -203,18 +242,16 @@ function formatSnapshots(diffs, build) {
203
242
  `Count: ${diffs.length}`,
204
243
  `Summary: ${formatSnapshotSummary(diffs)}`,
205
244
  "",
206
- ...diffs.flatMap((diff) => [
207
- `${diff.name} [${diff.status}]`,
208
- ` Review: ${build.url}/${diff.id}`,
209
- ` Mask: ${formatValue(diff.url)}`,
210
- ` Base file: ${formatValue(diff.base?.url)}`,
211
- ` Head file: ${formatValue(diff.head?.url)}`,
212
- ` Score: ${formatValue(diff.score)}`,
213
- ` Group: ${formatValue(diff.group)}`,
214
- ""
215
- ])
245
+ ...diffs.flatMap((diff) => [...formatSnapshotDiff(diff, build), ""])
216
246
  ].slice(0, -1).join("\n");
217
247
  }
248
+ function formatChange(change) {
249
+ return [
250
+ `Change ${change.id}`,
251
+ `Ignored: ${change.ignored ? "yes" : "no"}`,
252
+ `Occurrences: ${change.occurrences}`
253
+ ].join("\n");
254
+ }
218
255
  function formatReview(review) {
219
256
  const lines = [
220
257
  `Review #${review.id}`,
@@ -238,6 +275,33 @@ function formatReviews(reviews) {
238
275
  ])
239
276
  ].slice(0, -1).join("\n");
240
277
  }
278
+ function formatAnalytics(analytics, context) {
279
+ const { screenshots, builds } = analytics;
280
+ const lines = [
281
+ `Analytics for ${context.account}`,
282
+ `Period: ${context.from} → ${context.to ?? "now"} (grouped by ${context.groupBy})`,
283
+ "",
284
+ `Builds: ${builds.all.total}`,
285
+ ` Changes detected: ${builds.all.changesDetected}`,
286
+ ` No changes: ${builds.all.noChanges}`,
287
+ ` Accepted: ${builds.all.accepted}`,
288
+ ` Rejected: ${builds.all.rejected}`,
289
+ `Screenshots: ${screenshots.all.total}`
290
+ ];
291
+ const names = /* @__PURE__ */ new Map();
292
+ for (const project of [...builds.projects, ...screenshots.projects]) names.set(project.id, project.name);
293
+ const ids = /* @__PURE__ */ new Set([...Object.keys(builds.all.projects), ...Object.keys(screenshots.all.projects)]);
294
+ if (ids.size > 0) {
295
+ const rows = [...ids].map((id) => ({
296
+ name: names.get(id) ?? id,
297
+ builds: builds.all.projects[id] ?? 0,
298
+ screenshots: screenshots.all.projects[id] ?? 0
299
+ })).sort((a, b) => b.builds - a.builds || b.screenshots - a.screenshots);
300
+ lines.push("", `Projects (${rows.length}):`);
301
+ for (const row of rows) lines.push(` ${row.name}: ${row.builds} builds, ${row.screenshots} screenshots`);
302
+ }
303
+ return lines.join("\n");
304
+ }
241
305
  function indent(text) {
242
306
  return text.split("\n").map((line) => ` ${line}`).join("\n");
243
307
  }
@@ -466,6 +530,20 @@ async function resolveBuildTarget(reference, options, { auth }) {
466
530
  buildNumber
467
531
  };
468
532
  }
533
+ /**
534
+ * Resolve a project-scoped command target: an authenticated client and the
535
+ * `owner`/`project` pair every project endpoint needs. The project path comes
536
+ * from `--project owner/project` or the `ARGOS_PROJECT` environment variable.
537
+ */
538
+ async function resolveProjectTarget(options) {
539
+ const client = createApiClient(await resolveToken(options));
540
+ const projectPath = options.project || process.env["ARGOS_PROJECT"];
541
+ if (!projectPath) fail("--project <owner/project> is required. Pass it or set ARGOS_PROJECT.");
542
+ return {
543
+ client,
544
+ ...parseProjectPathOrFail(projectPath)
545
+ };
546
+ }
469
547
  //#endregion
470
548
  //#region src/lib/run.ts
471
549
  const USER_AUTH_HINT = "Ensure your token is a personal access token with access to this project. Project tokens (ARGOS_TOKEN in CI) can read build data but cannot perform review or comment actions.";
@@ -543,6 +621,7 @@ async function fetchAllDiffs(target, options) {
543
621
  query: {
544
622
  page: String(page),
545
623
  perPage: String(PER_PAGE),
624
+ metricsPeriod: options.metricsPeriod,
546
625
  ...options.needsReview ? { needsReview: "true" } : {}
547
626
  }
548
627
  } }));
@@ -552,7 +631,7 @@ async function fetchAllDiffs(target, options) {
552
631
  return results;
553
632
  }
554
633
  function registerBuildSnapshots(build) {
555
- build.command("snapshots").description("Fetch snapshot diffs for a build").argument("<buildReference>", "Build number or Argos build URL").addOption(new Option("--needs-review", "Only include snapshot diffs that require review")).addOption(tokenOption).addOption(jsonOption).action(async (reference, options) => {
634
+ build.command("snapshots").description("Fetch snapshot diffs for a build").argument("<buildReference>", "Build number or Argos build URL").addOption(new Option("--needs-review", "Only include snapshot diffs that require review")).addOption(metricsPeriodOption).addOption(tokenOption).addOption(jsonOption).action(async (reference, options) => {
556
635
  try {
557
636
  const target = await resolveBuildTarget(reference, options, { auth: "project" });
558
637
  const build = await fetchBuild(target);
@@ -565,7 +644,10 @@ function registerBuildSnapshots(build) {
565
644
  console.log(message);
566
645
  return;
567
646
  }
568
- output(await fetchAllDiffs(target, { needsReview: Boolean(options.needsReview) }), options, (data) => formatSnapshots(data, build));
647
+ output(await fetchAllDiffs(target, {
648
+ needsReview: Boolean(options.needsReview),
649
+ metricsPeriod: toMetricsPeriod(options.metricsPeriod)
650
+ }), options, (data) => formatSnapshots(data, build));
569
651
  } catch (error) {
570
652
  handleCliError(error, "project");
571
653
  }
@@ -1125,6 +1207,112 @@ function createProjectCommand(program) {
1125
1207
  });
1126
1208
  }
1127
1209
  //#endregion
1210
+ //#region src/commands/analytics.ts
1211
+ const DEFAULT_PERIOD_DAYS = 30;
1212
+ const DAY_MS = 1440 * 60 * 1e3;
1213
+ /** Coerce a user-supplied date into an ISO 8601 datetime, or fail cleanly. */
1214
+ function toIsoOrFail(value, option) {
1215
+ const date = new Date(value);
1216
+ if (Number.isNaN(date.getTime())) fail(`Invalid --${option} value: "${value}". Use an ISO 8601 datetime.`);
1217
+ return date.toISOString();
1218
+ }
1219
+ /** Collect a repeatable `--project` flag into an array of project names. */
1220
+ function collectProject(value, previous = []) {
1221
+ return [...previous, value];
1222
+ }
1223
+ function analyticsCommand(program) {
1224
+ program.command("analytics").description("Fetch build and screenshot analytics for an account").option("--account <slug>", "Slug of the account (personal or team) to fetch analytics for").option("--from <datetime>", `Start of the analytics period (ISO 8601). Defaults to ${DEFAULT_PERIOD_DAYS} days ago.`).option("--to <datetime>", "End of the analytics period (ISO 8601). Defaults to now.").addOption(new Option("--group-by <period>", "Time period used to group each series data point").choices([
1225
+ "day",
1226
+ "week",
1227
+ "month"
1228
+ ]).default("day")).option("--project <name>", "Filter by project name. Repeat the flag to include multiple projects.", collectProject).addOption(tokenOption).addOption(jsonOption).action(async (options) => {
1229
+ try {
1230
+ const accountSlug = options.account || process.env["ARGOS_ACCOUNT"];
1231
+ if (!accountSlug) fail("An account is required. Use --account <slug> or set ARGOS_ACCOUNT.");
1232
+ const from = options.from ? toIsoOrFail(options.from, "from") : (/* @__PURE__ */ new Date(Date.now() - DEFAULT_PERIOD_DAYS * DAY_MS)).toISOString();
1233
+ const to = options.to ? toIsoOrFail(options.to, "to") : void 0;
1234
+ output(unwrap(await createApiClient(await resolveToken({ token: options.token })).GET("/accounts/{accountSlug}/analytics", { params: {
1235
+ path: { accountSlug },
1236
+ query: {
1237
+ from,
1238
+ to,
1239
+ groupBy: options.groupBy,
1240
+ projectNames: options.project
1241
+ }
1242
+ } })), options, (data) => formatAnalytics(data, {
1243
+ account: accountSlug,
1244
+ from,
1245
+ to,
1246
+ groupBy: options.groupBy
1247
+ }));
1248
+ } catch (error) {
1249
+ handleCliError(error, "user");
1250
+ }
1251
+ });
1252
+ }
1253
+ //#endregion
1254
+ //#region src/commands/change/_action.ts
1255
+ /**
1256
+ * Register a `change <name> <changeId>` command that runs `perform` and prints
1257
+ * the updated change. Both change actions (ignore, unignore) share the same
1258
+ * shape and differ only by the endpoint they hit. They act as a user, so they
1259
+ * need a personal access token, and the project comes from `--project` or
1260
+ * `ARGOS_PROJECT` since a change id does not carry the account slug.
1261
+ */
1262
+ function defineChangeAction(opts) {
1263
+ return (change) => {
1264
+ change.command(opts.name).description(opts.description).argument("<changeId>", "Change ID, taken from a diff's `change.id` (see `argos build snapshots`)").addOption(tokenOption).addOption(changeProjectPathOption).addOption(metricsPeriodOption).addOption(jsonOption).action(async (changeId, options) => {
1265
+ try {
1266
+ const { client, owner, project } = await resolveProjectTarget(options);
1267
+ output(await opts.perform({
1268
+ client,
1269
+ owner,
1270
+ project,
1271
+ changeId,
1272
+ metricsPeriod: toMetricsPeriod(options.metricsPeriod)
1273
+ }), options, formatChange);
1274
+ } catch (error) {
1275
+ handleCliError(error, "user");
1276
+ }
1277
+ });
1278
+ };
1279
+ }
1280
+ //#endregion
1281
+ //#region src/commands/change/ignore.ts
1282
+ const registerChangeIgnore = defineChangeAction({
1283
+ name: "ignore",
1284
+ description: "Ignore a flaky test change so its diffs stop requiring review and are auto-approved on future builds",
1285
+ perform: async ({ client, owner, project, changeId, metricsPeriod }) => unwrap(await client.POST("/projects/{owner}/{project}/changes/{changeId}/ignore", { params: {
1286
+ path: {
1287
+ owner,
1288
+ project,
1289
+ changeId
1290
+ },
1291
+ query: { metricsPeriod }
1292
+ } }))
1293
+ });
1294
+ //#endregion
1295
+ //#region src/commands/change/unignore.ts
1296
+ const registerChangeUnignore = defineChangeAction({
1297
+ name: "unignore",
1298
+ description: "Stop ignoring a test change so its diffs require review again on future builds",
1299
+ perform: async ({ client, owner, project, changeId, metricsPeriod }) => unwrap(await client.POST("/projects/{owner}/{project}/changes/{changeId}/unignore", { params: {
1300
+ path: {
1301
+ owner,
1302
+ project,
1303
+ changeId
1304
+ },
1305
+ query: { metricsPeriod }
1306
+ } }))
1307
+ });
1308
+ //#endregion
1309
+ //#region src/commands/change/index.ts
1310
+ function changeCommand(program) {
1311
+ const change = program.command("change").description("Ignore or unignore flaky test changes");
1312
+ registerChangeIgnore(change);
1313
+ registerChangeUnignore(change);
1314
+ }
1315
+ //#endregion
1128
1316
  //#region src/index.ts
1129
1317
  const rawPkg = await readFile(resolve(fileURLToPath(new URL(".", import.meta.url)), "..", "package.json"), "utf8");
1130
1318
  const pkg = JSON.parse(rawPkg);
@@ -1140,6 +1328,8 @@ logoutCommand(program);
1140
1328
  deployCommand(program);
1141
1329
  whoamiCommand(program);
1142
1330
  createProjectCommand(program);
1331
+ analyticsCommand(program);
1332
+ changeCommand(program);
1143
1333
  if (!process.argv.slice(2).length) program.outputHelp();
1144
1334
  else program.parse(process.argv);
1145
1335
  //#endregion
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@argos-ci/cli",
3
3
  "description": "Command-line (CLI) for visual testing with Argos.",
4
- "version": "6.2.0",
4
+ "version": "6.3.0",
5
5
  "bin": {
6
6
  "argos": "./bin/argos-cli.js"
7
7
  },
@@ -34,8 +34,8 @@
34
34
  "access": "public"
35
35
  },
36
36
  "dependencies": {
37
- "@argos-ci/api-client": "0.25.0",
38
- "@argos-ci/core": "6.6.0",
37
+ "@argos-ci/api-client": "0.26.0",
38
+ "@argos-ci/core": "6.6.1",
39
39
  "commander": "^15.0.0",
40
40
  "open": "^11.0.0",
41
41
  "ora": "^9.4.0",
@@ -54,5 +54,5 @@
54
54
  "check-format": "prettier --check --ignore-unknown --ignore-path=../../.gitignore --ignore-path=../../.prettierignore .",
55
55
  "lint": "eslint ."
56
56
  },
57
- "gitHead": "686b6fa8385ed77598ec86f66b073e9897cef176"
57
+ "gitHead": "e6b1b39775bc210c6b8fec81c59165c5a4aa4dc9"
58
58
  }