@argos-ci/util 4.2.3 → 4.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.
@@ -1,2 +1,2 @@
1
- import { a as clearCaptureIndex, c as resetCaptureIndexes, d as getMetadataPath, i as getScreenshotName, l as normalizeBaseNames, n as hasPlay, o as getTestRunKey, r as mergeTags, s as nextCaptureIndex, t as validateThreshold, u as ScreenshotMetadata } from "./threshold-7lU01Zbd.mjs";
2
- export { type ScreenshotMetadata, clearCaptureIndex, getMetadataPath, getScreenshotName, getTestRunKey, hasPlay, mergeTags, nextCaptureIndex, normalizeBaseNames, resetCaptureIndexes, validateThreshold };
1
+ import { _ as normalizeBaseNames, a as PaddingSides, c as getPaddedClip, d as resolvePaddingOption, f as getScreenshotName, g as resetCaptureIndexes, h as nextCaptureIndex, i as ElementPadding, l as intersectRects, m as getTestRunKey, n as hasPlay, o as Rect, p as clearCaptureIndex, r as mergeTags, s as clampPadding, t as validateThreshold, u as resolvePadding, v as ScreenshotMetadata, y as getMetadataPath } from "./threshold-C0hRrXWT.mjs";
2
+ export { ElementPadding, PaddingSides, Rect, type ScreenshotMetadata, clampPadding, clearCaptureIndex, getMetadataPath, getPaddedClip, getScreenshotName, getTestRunKey, hasPlay, intersectRects, mergeTags, nextCaptureIndex, normalizeBaseNames, resetCaptureIndexes, resolvePadding, resolvePaddingOption, validateThreshold };
package/dist/browser.mjs CHANGED
@@ -1,2 +1 @@
1
- import { a as getMetadataPath, c as nextCaptureIndex, i as getScreenshotName, l as resetCaptureIndexes, n as hasPlay, o as clearCaptureIndex, r as mergeTags, s as getTestRunKey, t as validateThreshold, u as normalizeBaseNames } from "./threshold-CW8P4JMe.mjs";
2
- export { clearCaptureIndex, getMetadataPath, getScreenshotName, getTestRunKey, hasPlay, mergeTags, nextCaptureIndex, normalizeBaseNames, resetCaptureIndexes, validateThreshold };
1
+ export { i as clampPadding, d as clearCaptureIndex, u as getMetadataPath, a as getPaddedClip, l as getScreenshotName, f as getTestRunKey, n as hasPlay, o as intersectRects, r as mergeTags, p as nextCaptureIndex, h as normalizeBaseNames, m as resetCaptureIndexes, s as resolvePadding, c as resolvePaddingOption, t as validateThreshold } from "./threshold-C_TwjILw.mjs";
package/dist/index.d.mts CHANGED
@@ -1,5 +1,4 @@
1
- import { a as clearCaptureIndex, c as resetCaptureIndexes, d as getMetadataPath, i as getScreenshotName, l as normalizeBaseNames, n as hasPlay, o as getTestRunKey, r as mergeTags, s as nextCaptureIndex, t as validateThreshold, u as ScreenshotMetadata } from "./threshold-7lU01Zbd.mjs";
2
- //#region src/fs.d.ts
1
+ import { _ as normalizeBaseNames, a as PaddingSides, c as getPaddedClip, d as resolvePaddingOption, f as getScreenshotName, g as resetCaptureIndexes, h as nextCaptureIndex, i as ElementPadding, l as intersectRects, m as getTestRunKey, n as hasPlay, o as Rect, p as clearCaptureIndex, r as mergeTags, s as clampPadding, t as validateThreshold, u as resolvePadding, v as ScreenshotMetadata, y as getMetadataPath } from "./threshold-C0hRrXWT.mjs";
3
2
  /**
4
3
  * Create a directory if it doesn't exist.
5
4
  */
@@ -8,20 +7,14 @@ export declare function createDirectory(pathname: string): Promise<void>;
8
7
  * Create temporary directory.
9
8
  */
10
9
  export declare function createTemporaryDirectory(): Promise<string>;
11
- //#endregion
12
- //#region src/git.d.ts
13
10
  /**
14
11
  * Get the top level of the git repository.
15
12
  */
16
13
  export declare function getGitRepositoryPath(): Promise<string | null>;
17
- //#endregion
18
- //#region src/introspection.d.ts
19
14
  /**
20
15
  * Read the version from a package.json file.
21
16
  */
22
17
  export declare function readVersionFromPackage(pkgPath: string): Promise<string>;
23
- //#endregion
24
- //#region src/metadata-io.d.ts
25
18
  /**
26
19
  * Write screenshot metadata to disk.
27
20
  */
@@ -31,12 +24,9 @@ export declare function writeMetadata(screenshotPath: string, metadata: Screensh
31
24
  * If not found, returns null.
32
25
  */
33
26
  export declare function readMetadata(screenshotPath: string): Promise<ScreenshotMetadata | null>;
34
- //#endregion
35
- //#region src/playwright-trace.d.ts
36
27
  /**
37
28
  * Get playwright trace from screenshot path.
38
29
  * If not found, returns null.
39
30
  */
40
31
  export declare function getPlaywrightTracePath(screenshotPath: string): Promise<string | null>;
41
- //#endregion
42
- export { ScreenshotMetadata, clearCaptureIndex, getMetadataPath, getScreenshotName, getTestRunKey, hasPlay, mergeTags, nextCaptureIndex, normalizeBaseNames, resetCaptureIndexes, validateThreshold };
32
+ export { ElementPadding, PaddingSides, Rect, ScreenshotMetadata, clampPadding, clearCaptureIndex, getMetadataPath, getPaddedClip, getScreenshotName, getTestRunKey, hasPlay, intersectRects, mergeTags, nextCaptureIndex, normalizeBaseNames, resetCaptureIndexes, resolvePadding, resolvePaddingOption, validateThreshold };
package/dist/index.mjs CHANGED
@@ -1,10 +1,10 @@
1
- import { a as getMetadataPath, c as nextCaptureIndex, i as getScreenshotName, l as resetCaptureIndexes, n as hasPlay, o as clearCaptureIndex, r as mergeTags, s as getTestRunKey, t as validateThreshold, u as normalizeBaseNames } from "./threshold-CW8P4JMe.mjs";
1
+ import { a as getPaddedClip, c as resolvePaddingOption, d as clearCaptureIndex, f as getTestRunKey, h as normalizeBaseNames, i as clampPadding, l as getScreenshotName, m as resetCaptureIndexes, n as hasPlay, o as intersectRects, p as nextCaptureIndex, r as mergeTags, s as resolvePadding, t as validateThreshold, u as getMetadataPath } from "./threshold-C_TwjILw.mjs";
2
2
  import { randomBytes } from "node:crypto";
3
3
  import { access, mkdir, readFile, writeFile } from "node:fs/promises";
4
4
  import { tmpdir } from "node:os";
5
5
  import { join } from "node:path";
6
6
  import { exec } from "node:child_process";
7
- //#region src/fs.ts
7
+ // src/fs.ts
8
8
  const createDirectoryPromises = /* @__PURE__ */ new Map();
9
9
  /**
10
10
  * Create a directory if it doesn't exist.
@@ -25,8 +25,7 @@ async function createTemporaryDirectory() {
25
25
  await createDirectory(path);
26
26
  return path;
27
27
  }
28
- //#endregion
29
- //#region src/git.ts
28
+ // src/git.ts
30
29
  let cached;
31
30
  /**
32
31
  * Get the top level of the git repository.
@@ -41,8 +40,7 @@ function getGitRepositoryPath() {
41
40
  });
42
41
  return cached;
43
42
  }
44
- //#endregion
45
- //#region src/introspection.ts
43
+ // src/introspection.ts
46
44
  const versionCache = /* @__PURE__ */ new Map();
47
45
  /**
48
46
  * Read the version from a package.json file.
@@ -58,8 +56,7 @@ function readVersionFromPackage(pkgPath) {
58
56
  if (!fromCache) throw new Error("Invariant violation: version not in cache");
59
57
  return fromCache;
60
58
  }
61
- //#endregion
62
- //#region src/metadata-io.ts
59
+ // src/metadata-io.ts
63
60
  /**
64
61
  * Write screenshot metadata to disk.
65
62
  */
@@ -79,8 +76,7 @@ async function readMetadata(screenshotPath) {
79
76
  throw new Error("Failed to read metadata", { cause: error });
80
77
  }
81
78
  }
82
- //#endregion
83
- //#region src/playwright-trace.ts
79
+ // src/playwright-trace.ts
84
80
  /**
85
81
  * Get trace path from screenshot path.
86
82
  */
@@ -100,5 +96,4 @@ async function getPlaywrightTracePath(screenshotPath) {
100
96
  return null;
101
97
  }
102
98
  }
103
- //#endregion
104
- export { clearCaptureIndex, createDirectory, createTemporaryDirectory, getGitRepositoryPath, getMetadataPath, getPlaywrightTracePath, getScreenshotName, getTestRunKey, hasPlay, mergeTags, nextCaptureIndex, normalizeBaseNames, readMetadata, readVersionFromPackage, resetCaptureIndexes, validateThreshold, writeMetadata };
99
+ export { clampPadding, clearCaptureIndex, createDirectory, createTemporaryDirectory, getGitRepositoryPath, getMetadataPath, getPaddedClip, getPlaywrightTracePath, getScreenshotName, getTestRunKey, hasPlay, intersectRects, mergeTags, nextCaptureIndex, normalizeBaseNames, readMetadata, readVersionFromPackage, resetCaptureIndexes, resolvePadding, resolvePaddingOption, validateThreshold, writeMetadata };
@@ -1,4 +1,3 @@
1
- //#region src/metadata.d.ts
2
1
  type ScreenshotMetadata = {
3
2
  /** @description The URL of the page that was screenshotted */
4
3
  url?: string | null;
@@ -112,15 +111,11 @@ type ScreenshotMetadata = {
112
111
  * Get metadata path from snapshot path.
113
112
  */
114
113
  declare function getMetadataPath(snapshotPath: string): string;
115
- //#endregion
116
- //#region src/base-name.d.ts
117
114
  /**
118
115
  * Normalize the user-facing `baseName` option — a single name or an ordered
119
116
  * list of candidates — into a list, or `null` when nothing was provided.
120
117
  */
121
118
  declare function normalizeBaseNames(baseName: string | string[] | undefined | null): string[] | null;
122
- //#endregion
123
- //#region src/capture-index.d.ts
124
119
  /**
125
120
  * Return the next 0-based capture index for `testRunKey` and advance it.
126
121
  */
@@ -142,16 +137,66 @@ declare function getTestRunKey(test: {
142
137
  retry?: number | null;
143
138
  repeat?: number | null;
144
139
  }): string;
145
- //#endregion
146
- //#region src/name.d.ts
147
140
  /**
148
141
  * Build a screenshot name from a test name and options.
149
142
  */
150
143
  declare function getScreenshotName(name: string, options?: {
151
144
  viewportWidth?: number;
152
145
  }): string;
153
- //#endregion
154
- //#region src/story.d.ts
146
+ /**
147
+ * Space to capture around an element, in CSS pixels.
148
+ * A number applies to every side. An array follows the CSS `padding`
149
+ * shorthand: `[all]`, `[vertical, horizontal]`, `[top, horizontal, bottom]`
150
+ * or `[top, right, bottom, left]`.
151
+ */
152
+ type ElementPadding = number | [number] | [number, number] | [number, number, number] | [number, number, number, number];
153
+ /**
154
+ * A padding resolved to the space on each side.
155
+ */
156
+ type PaddingSides = {
157
+ top: number;
158
+ right: number;
159
+ bottom: number;
160
+ left: number;
161
+ };
162
+ type Rect = {
163
+ x: number;
164
+ y: number;
165
+ width: number;
166
+ height: number;
167
+ };
168
+ /**
169
+ * Resolve a padding to the space on each side, like the CSS `padding`
170
+ * shorthand. Throws if a value isn't a non-negative number.
171
+ */
172
+ declare function resolvePadding(padding: ElementPadding): PaddingSides;
173
+ /**
174
+ * Validate the `padding` option of an element screenshot and resolve it.
175
+ * Returns `null` when there is no space to add, so the screenshot can be
176
+ * taken like any element screenshot.
177
+ */
178
+ declare function resolvePaddingOption(options: {
179
+ padding?: ElementPadding | undefined;
180
+ element?: unknown;
181
+ clip?: unknown;
182
+ }): PaddingSides | null;
183
+ /**
184
+ * Get the overlap of two rects, with a zero size when they don't overlap.
185
+ */
186
+ declare function intersectRects(a: Rect, b: Rect): Rect;
187
+ /**
188
+ * Get the area to capture for an element screenshot with a padding.
189
+ * The element box is expanded on each side, rounded out to whole pixels, then
190
+ * clamped to the bounds (the page, or the frame the element is in).
191
+ * The box, the bounds and the result share the same coordinates.
192
+ */
193
+ declare function getPaddedClip(box: Rect, padding: PaddingSides, bounds: Rect): Rect;
194
+ /**
195
+ * Reduce a padding so the area around the box stays within the bounds, for
196
+ * tools that apply the padding themselves.
197
+ * Returns the padding as `[top, right, bottom, left]`.
198
+ */
199
+ declare function clampPadding(box: Rect, padding: PaddingSides, bounds: Rect): [number, number, number, number];
155
200
  /**
156
201
  * Merge the tags of a story given by several sources (the story, its
157
202
  * parameters…), deduplicated and without empty values.
@@ -163,11 +208,8 @@ declare function mergeTags(...tags: unknown[]): string[];
163
208
  * `playFunction` field of a story context.
164
209
  */
165
210
  declare function hasPlay(story: unknown): boolean;
166
- //#endregion
167
- //#region src/threshold.d.ts
168
211
  /**
169
212
  * Validates the threshold value.
170
213
  */
171
214
  declare function validateThreshold(threshold: number): void;
172
- //#endregion
173
- export { clearCaptureIndex as a, resetCaptureIndexes as c, getMetadataPath as d, getScreenshotName as i, normalizeBaseNames as l, hasPlay as n, getTestRunKey as o, mergeTags as r, nextCaptureIndex as s, validateThreshold as t, ScreenshotMetadata as u };
215
+ export { normalizeBaseNames as _, PaddingSides as a, getPaddedClip as c, resolvePaddingOption as d, getScreenshotName as f, resetCaptureIndexes as g, nextCaptureIndex as h, ElementPadding as i, intersectRects as l, getTestRunKey as m, hasPlay as n, Rect as o, clearCaptureIndex as p, mergeTags as r, clampPadding as s, validateThreshold as t, resolvePadding as u, ScreenshotMetadata as v, getMetadataPath as y };
@@ -1,4 +1,4 @@
1
- //#region src/base-name.ts
1
+ // src/base-name.ts
2
2
  /**
3
3
  * Normalize the user-facing `baseName` option — a single name or an ordered
4
4
  * list of candidates — into a list, or `null` when nothing was provided.
@@ -8,8 +8,7 @@ function normalizeBaseNames(baseName) {
8
8
  const validNames = (Array.isArray(baseName) ? baseName : [baseName]).filter((name) => name !== "");
9
9
  return validNames.length > 0 ? validNames : null;
10
10
  }
11
- //#endregion
12
- //#region src/capture-index.ts
11
+ // src/capture-index.ts
13
12
  /**
14
13
  * Capture order.
15
14
  *
@@ -48,16 +47,14 @@ function resetCaptureIndexes() {
48
47
  function getTestRunKey(test) {
49
48
  return `${test.id ?? test.titlePath?.join(" › ") ?? ""}#${test.retry ?? 0}@${test.repeat ?? 0}`;
50
49
  }
51
- //#endregion
52
- //#region src/metadata.ts
50
+ // src/metadata.ts
53
51
  /**
54
52
  * Get metadata path from snapshot path.
55
53
  */
56
54
  function getMetadataPath(snapshotPath) {
57
55
  return snapshotPath + ".argos.json";
58
56
  }
59
- //#endregion
60
- //#region src/name.ts
57
+ // src/name.ts
61
58
  /**
62
59
  * Build a screenshot name from a test name and options.
63
60
  */
@@ -85,8 +82,96 @@ function sanitizeFilename(name) {
85
82
  if (windowsReservedNameRegex().test(sanitized)) return `${sanitized}${replacement}`;
86
83
  return sanitized;
87
84
  }
88
- //#endregion
89
- //#region src/story.ts
85
+ // src/padding.ts
86
+ /**
87
+ * Resolve a padding to the space on each side, like the CSS `padding`
88
+ * shorthand. Throws if a value isn't a non-negative number.
89
+ */
90
+ function resolvePadding(padding) {
91
+ const values = Array.isArray(padding) ? padding : [padding];
92
+ if (values.length < 1 || values.length > 4 || values.some((value) => !Number.isFinite(value) || value < 0)) throw new Error("The `padding` option must be a non-negative number or an array of 1 to 4 non-negative numbers.");
93
+ const [top = 0, right = top, bottom = top, left = right] = values;
94
+ return {
95
+ top,
96
+ right,
97
+ bottom,
98
+ left
99
+ };
100
+ }
101
+ /**
102
+ * Validate the `padding` option of an element screenshot and resolve it.
103
+ * Returns `null` when there is no space to add, so the screenshot can be
104
+ * taken like any element screenshot.
105
+ */
106
+ function resolvePaddingOption(options) {
107
+ const { padding, element, clip } = options;
108
+ if (padding === void 0) return null;
109
+ if (element === void 0) throw new Error("The `padding` option requires the `element` option.");
110
+ if (clip) throw new Error("The `padding` option can't be used with `clip`.");
111
+ const sides = resolvePadding(padding);
112
+ return sides.top || sides.right || sides.bottom || sides.left ? sides : null;
113
+ }
114
+ /**
115
+ * Get the overlap of two rects, with a zero size when they don't overlap.
116
+ */
117
+ function intersectRects(a, b) {
118
+ const x = Math.max(a.x, b.x);
119
+ const y = Math.max(a.y, b.y);
120
+ return {
121
+ x,
122
+ y,
123
+ width: Math.max(0, Math.min(a.x + a.width, b.x + b.width) - x),
124
+ height: Math.max(0, Math.min(a.y + a.height, b.y + b.height) - y)
125
+ };
126
+ }
127
+ /**
128
+ * Round a rect out to whole pixels, like an element screenshot does, while
129
+ * tolerating float noise so a box at 10.0000001 doesn't grow a pixel.
130
+ */
131
+ function enclose(rect) {
132
+ const epsilon = .001;
133
+ const x = Math.floor(rect.x + epsilon);
134
+ const y = Math.floor(rect.y + epsilon);
135
+ return {
136
+ x,
137
+ y,
138
+ width: Math.ceil(rect.x + rect.width - epsilon) - x,
139
+ height: Math.ceil(rect.y + rect.height - epsilon) - y
140
+ };
141
+ }
142
+ /**
143
+ * Get the area to capture for an element screenshot with a padding.
144
+ * The element box is expanded on each side, rounded out to whole pixels, then
145
+ * clamped to the bounds (the page, or the frame the element is in).
146
+ * The box, the bounds and the result share the same coordinates.
147
+ */
148
+ function getPaddedClip(box, padding, bounds) {
149
+ const { top, right, bottom, left } = padding;
150
+ const clip = intersectRects(enclose({
151
+ x: box.x - left,
152
+ y: box.y - top,
153
+ width: box.width + left + right,
154
+ height: box.height + top + bottom
155
+ }), enclose(bounds));
156
+ if (!clip.width || !clip.height) throw new Error("The element is outside of the page.");
157
+ return clip;
158
+ }
159
+ /**
160
+ * Reduce a padding so the area around the box stays within the bounds, for
161
+ * tools that apply the padding themselves.
162
+ * Returns the padding as `[top, right, bottom, left]`.
163
+ */
164
+ function clampPadding(box, padding, bounds) {
165
+ const { top, right, bottom, left } = padding;
166
+ const clamp = (value, space) => Math.max(0, Math.min(value, space));
167
+ return [
168
+ clamp(top, box.y - bounds.y),
169
+ clamp(right, bounds.x + bounds.width - (box.x + box.width)),
170
+ clamp(bottom, bounds.y + bounds.height - (box.y + box.height)),
171
+ clamp(left, box.x - bounds.x)
172
+ ];
173
+ }
174
+ // src/story.ts
90
175
  /**
91
176
  * Merge the tags of a story given by several sources (the story, its
92
177
  * parameters…), deduplicated and without empty values.
@@ -104,13 +189,11 @@ function hasPlay(story) {
104
189
  if (!story || typeof story !== "object" && typeof story !== "function") return false;
105
190
  return "play" in story && typeof story.play === "function" || "playFunction" in story && typeof story.playFunction === "function";
106
191
  }
107
- //#endregion
108
- //#region src/threshold.ts
192
+ // src/threshold.ts
109
193
  /**
110
194
  * Validates the threshold value.
111
195
  */
112
196
  function validateThreshold(threshold) {
113
197
  if (threshold < 0 || threshold > 1) throw new Error("The threshold must be between 0 and 1.");
114
198
  }
115
- //#endregion
116
- export { getMetadataPath as a, nextCaptureIndex as c, getScreenshotName as i, resetCaptureIndexes as l, hasPlay as n, clearCaptureIndex as o, mergeTags as r, getTestRunKey as s, validateThreshold as t, normalizeBaseNames as u };
199
+ export { getPaddedClip as a, resolvePaddingOption as c, clearCaptureIndex as d, getTestRunKey as f, normalizeBaseNames as h, clampPadding as i, getScreenshotName as l, resetCaptureIndexes as m, hasPlay as n, intersectRects as o, nextCaptureIndex as p, mergeTags as r, resolvePadding as s, validateThreshold as t, getMetadataPath as u };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@argos-ci/util",
3
3
  "description": "Set of utilities used across all Argos SDKs.",
4
- "version": "4.2.3",
4
+ "version": "4.3.0",
5
5
  "author": "Smooth Code",
6
6
  "license": "MIT",
7
7
  "repository": {
@@ -49,5 +49,5 @@
49
49
  "@types/node": "catalog:",
50
50
  "vitest": "catalog:"
51
51
  },
52
- "gitHead": "810aab42c890851ea19ba96f49c4f167a5f2e3df"
52
+ "gitHead": "96ca00234edc12d322416295a4abebbc8471b696"
53
53
  }