saffron-ai 1.3.3 → 1.3.4

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "saffron-ai",
3
- "version": "1.3.3",
3
+ "version": "1.3.4",
4
4
  "description": "End-to-end tests written in plain language: an AI agent records each scenario once, replays run at zero tokens, and broken replays heal into proposals you review",
5
5
  "scripts": {
6
6
  "test": "vitest run",
@@ -3,14 +3,14 @@ name: saffron
3
3
  description: Create, translate, or edit Saffron test scenarios in .saffron or .feature files, browser UI tests and HTTP API tests (@api) alike, including validating their recordings and replay. Use when asked to author or fix these test files in a Saffron project. Do not activate for ordinary application development, generic Cucumber projects, or requests only to run existing tests, inspect reports, review proposals, or configure Saffron.
4
4
  license: Saffron Free Use License v1.0 (see the saffron-ai package LICENSE)
5
5
  metadata:
6
- saffron-ai: "1.3.3"
6
+ saffron-ai: "1.3.4"
7
7
  author: saffron-ai
8
8
  homepage: https://saffron-ai.io
9
9
  ---
10
10
 
11
11
  # Saffron
12
12
 
13
- This skill describes saffron-ai 1.3.3 (see the compatibility page: https://saffron-ai.io/docs/compatibility).
13
+ This skill describes saffron-ai 1.3.4 (see the compatibility page: https://saffron-ai.io/docs/compatibility).
14
14
 
15
15
  Apply this workflow only when asked to create, translate, or edit Saffron
16
16
  scenarios in `.saffron` or `.feature` files. A Saffron mention or an
@@ -151,11 +151,19 @@ async function resolvesLinkLocal(hostname: string): Promise<boolean> {
151
151
  /** A number or boolean a request body sends where the recording holds text with tokens (a row's "<seats>"). */
152
152
  export function typed(text: string, type: "number" | "boolean" | "json"): unknown {
153
153
  if (type === "json") {
154
+ let unexact: string | undefined;
155
+ let parsed: unknown;
154
156
  try {
155
- return JSON.parse(text);
157
+ // A number not held as written (an int64 id) would be sent rounded to another one, as replay refuses it.
158
+ parsed = JSON.parse(text, (_key, value: unknown, context?: { source?: string }) => {
159
+ if (typeof value === "number" && context?.source !== undefined && !heldAsWritten(context.source, value)) unexact ??= context.source;
160
+ return value;
161
+ });
156
162
  } catch {
157
163
  throw new Error("a body part must be JSON, but its value resolves to text that is not: give the column a whole JSON value");
158
164
  }
165
+ if (unexact !== undefined) throw new Error(`a body part holds ${mask(unexact)}, which cannot be sent exactly as a JSON number; send it as a string`);
166
+ return parsed;
159
167
  }
160
168
  if (type === "boolean") {
161
169
  if (text === "true" || text === "false") return text === "true";
@@ -164,11 +172,12 @@ export function typed(text: string, type: "number" | "boolean" | "json"): unknow
164
172
  // A decimal number as JSON writes one, as replay reads it: "Infinity" would be sent as null, "0x1F" as 31.
165
173
  const number = Number(text);
166
174
  if (!/^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?$/.test(text) || !Number.isFinite(number)) throw new Error(`a body field must be a number, but its value resolves to ${JSON.stringify(mask(text))}`);
175
+ if (!heldAsWritten(text, number)) throw new Error(`a body field holds ${mask(text)}, which cannot be sent exactly as a JSON number; send it as a string`);
167
176
  return number;
168
177
  }
169
178
 
170
179
  /** A check's expected text must say something: "" is in every text. */
171
- function said<T extends string | RegExp>(expected: T, what: string): T {
180
+ export function said<T extends string | RegExp>(expected: T, what: string): T {
172
181
  if (typeof expected === "string" ? normalize(expected) === "" : expected.source === "" || expected.source === "(?:)") throw new Error(`${what} is blank, so it would hold for anything`);
173
182
  return expected;
174
183
  }
@@ -178,6 +187,28 @@ export function projectFile(file: string): string {
178
187
  return path.resolve(path.dirname(test.info().file), SETTINGS.projectRoot, file);
179
188
  }
180
189
 
190
+ /**
191
+ * A file the page may receive, as replay allows one: inside the project by
192
+ * its real path (a link out of it is out), never a dotfile (.env holds every
193
+ * secret), a single file, never a folder (found in review).
194
+ */
195
+ export function uploadFile(file: string): string {
196
+ const root = path.resolve(path.dirname(test.info().file), SETTINGS.projectRoot);
197
+ const full = path.resolve(root, file);
198
+ const inside = (base: string, p: string) => { const rel = path.relative(base, p); return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel) ? rel : undefined; };
199
+ const rel = inside(root, full);
200
+ if (rel === undefined) throw new Error(`${file} is outside the project; uploads come from files inside it`);
201
+ if (rel.split(path.sep).some((seg) => seg.startsWith("."))) throw new Error(`${file} is a hidden file; a Saffron test does not upload dotfiles`);
202
+ if (!fs.existsSync(full)) throw new Error(`${file} does not exist; uploads come from files inside the project`);
203
+ const real = inside(fs.realpathSync(root), fs.realpathSync(full));
204
+ if (real === undefined) throw new Error(`${file} is outside the project; uploads come from files inside it`);
205
+ // A link to .env is .env (found in review): the real path is judged too, and a hard link refused.
206
+ if (real.split(path.sep).some((seg) => seg.startsWith("."))) throw new Error(`${file} is a hidden file; a Saffron test does not upload dotfiles`);
207
+ if (fs.statSync(full).isDirectory()) throw new Error(`${file} is a folder; a Saffron test uploads single files only`);
208
+ if (fs.statSync(full).nlink > 1) throw new Error(`${file} is a hard link (the same file under another name, perhaps a hidden one such as .env); copy the file instead`);
209
+ return full;
210
+ }
211
+
181
212
  const LETTER = String.raw`[\p{L}\p{N}\p{M}]`;
182
213
  // A script written without spaces (Chinese, Japanese, Thai...): an edge of it is not bounded, as in replay, but for
183
214
  // a negating prefix before it ("成功" is not in "不成功").
@@ -587,7 +618,11 @@ export class Run {
587
618
 
588
619
  /** A recorded URL under the base URL, as Saffron joins them (a base path is kept). */
589
620
  url(recorded: string): string {
590
- return this.join(recorded, this.baseURL, `relative navigation "${recorded}" needs a baseURL in playwright.config.ts`);
621
+ const url = this.join(recorded, this.baseURL, `relative navigation "${recorded}" needs a baseURL in playwright.config.ts`);
622
+ // A web page only, as replay opens: never data:, file: or javascript: (found in review).
623
+ const scheme = (() => { try { return new URL(url).protocol; } catch { return ""; } })();
624
+ if (!/^localhost(:\d+)?(\/|$)/i.test(url) && url !== "about:blank" && !/^https?:$/.test(scheme)) throw new Error(`${mask(url)} is not a web page; a Saffron test only opens http(s) URLs`);
625
+ return url;
591
626
  }
592
627
 
593
628
  private join(recorded: string, baseURL: string | undefined, orElse: string): string {
@@ -730,7 +765,7 @@ export class Run {
730
765
  const chooser = this.page.waitForEvent("filechooser", { timeout: SETTINGS.timeoutMs });
731
766
  chooser.catch(() => undefined); // the action's own error comes first
732
767
  await action();
733
- await (await chooser).setFiles(files.map(projectFile));
768
+ await (await chooser).setFiles(files.map(uploadFile));
734
769
  }
735
770
 
736
771
  /** The text `target` shows, once open requests are answered and the text has held for half a second. */
@@ -1221,16 +1256,23 @@ async function shownLines(target: Locator): Promise<string[]> {
1221
1256
  }
1222
1257
 
1223
1258
  /** As replay's urlContains: a path outside the query unless the text names one, and never inside a longer word or number. */
1224
- function urlContains(url: string, expected: string | RegExp): boolean {
1259
+ export function urlContains(url: string, expected: string | RegExp): boolean {
1225
1260
  const text = typeof expected === "string" ? expected : expected.source;
1226
1261
  // Cut on the URL as sent: decoded, a "%23" in a query value reads as a fragment; a query value that is a path is no part of the page's own.
1227
1262
  const asked = /[?=&]/.test(text) ? url : text.includes("/") ? url.replace(/\?[^#]*/, "").replace(/([?&#][^=&#/]*=)[^&#]*(?:\/|%2F)[^&#]*/gi, "$1") : url.replace(/([?&#][^=&#/]*=)[^&#]*(?:\/|%2F)[^&#]*/gi, "$1");
1228
1263
  // A letter or digit written percent-encoded is part of the word beside it, an encoded "?", "&", "=" or "#" is not; beside a number, no decimal part.
1229
1264
  const encoded = "%(?!3[Ff]|26|3[Dd]|23)[0-9A-Fa-f]{2}";
1230
- const before = /^[\p{L}\p{N}]/u.test(text) ? String.raw`(?<![\p{L}\p{N}]|${encoded}${/^\p{N}/u.test(text) ? String.raw`|\p{N}[.,]` : ""})` : "";
1231
- const after = /[\p{L}\p{N}]$/u.test(text) ? String.raw`(?![\p{L}\p{N}]|${encoded}${/\p{N}$/u.test(text) ? String.raw`|[.,]\p{N}` : ""})` : "";
1232
1265
  if (typeof expected !== "string") return [asked, decode(asked), decode(asked.replace(/\+/g, "%20"))].some((u) => expected.test(u));
1233
- const re = new RegExp(`${before}${expected.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}${after}`, "gu");
1266
+ // A word starts as it ends: not after a letter (a digit, for a number) and "-", "_", "~" or "+", as replay reads it.
1267
+ // In the query and fragment, "+" and a space separate words ("shoes" is in "?q=red+shoes"); in the path they join them.
1268
+ const bounds = (sep: string, sepEnd: string) => [
1269
+ /^[\p{L}\p{N}]/u.test(text) ? String.raw`(?<![\p{L}\p{N}]|${encoded}|(?:[\p{L}\p{M}]|${encoded})${sep}+${/^\p{N}/u.test(text) ? String.raw`|\p{N}[.,]|\p{N}${sep}+` : ""})` : "",
1270
+ /[\p{L}\p{N}]$/u.test(text) ? String.raw`(?![\p{L}\p{N}]|${encoded}|${sepEnd}+(?:[\p{L}\p{N}]|${encoded})|:\p{L}${/\p{N}$/u.test(text) ? String.raw`|[.,]\p{N}` : ""})` : "",
1271
+ ];
1272
+ const word = (sep: string, sepEnd: string) => { const [before, after] = bounds(sep, sepEnd); return new RegExp(`${before}${expected.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}${after}`, "gu"); };
1273
+ const re = word("[-_~+ ]", "[-._~+ ]");
1274
+ const spaced = word("[-_~]", "[-._~]");
1275
+ const inQuery = (u: string, at: number) => { const q = u.search(/[?#]/); return q >= 0 && at > q; };
1234
1276
  // A text naming a query starts at the URL's own, as replay reads it.
1235
1277
  const mark = expected.indexOf("?");
1236
1278
  const hash = expected.indexOf("#");
@@ -1247,7 +1289,7 @@ function urlContains(url: string, expected: string | RegExp): boolean {
1247
1289
  };
1248
1290
  // Each part decoded on its own: a "?", "&", "=" or "#" a value encodes stays encoded.
1249
1291
  const parts = (u: string) => u.replace(/[^?&=#]+/g, (part) => decode(part).replace(/[?&=#]/g, encodeURIComponent));
1250
- return [asked, parts(asked), parts(asked.replace(/\+/g, "%20"))].some((u) => [...u.matchAll(re)].some((m) => atQuery(u, m.index)));
1292
+ return [asked, parts(asked), parts(asked.replace(/\+/g, "%20"))].some((u) => [...u.matchAll(re)].some((m) => atQuery(u, m.index)) || [...u.matchAll(spaced)].some((m) => inQuery(u, m.index) && atQuery(u, m.index)));
1251
1293
  }
1252
1294
 
1253
1295
  /** The URL contains `expected` (raw, decoded, or with + read as a space); with "excludes", it does not; with "path", its path is exactly `expected`. */
@@ -1330,6 +1372,56 @@ export function parseAmount(text: string): number | undefined {
1330
1372
  const amountUnit = (text: string): string =>
1331
1373
  joinGroups(text).replace(/[-\u2212\u2013]?\d(?:[\d.,]*\d)?/, " ").replace(/[()\-\u2212\u2013]/g, " ").replace(/\s+/g, " ").trim().toLowerCase();
1332
1374
 
1375
+ /**
1376
+ * The currency an amount names, as a kind and its spelling: an ISO code
1377
+ * ("NOK") or a symbol ("€"); undefined for none or a local notation ("kr").
1378
+ * Two of the same kind that differ are two currencies; a symbol against a
1379
+ * code ("$5" and "USD 5") is not judged.
1380
+ */
1381
+ export function amountCurrency(text: string): { kind: "code" | "symbol"; is: string; loose?: true } | undefined {
1382
+ // A code right beside the number ("NOK 150", "150 NOK", "EUR (150)"), in capitals first: "Top up" and "Pay all" are words,
1383
+ // not TOP or ALL. A word beside it that is no currency ("NET 150 EUR") is passed over, and "150 eur" still counts (found in review).
1384
+ const beside = (flags: string) => [...text.matchAll(new RegExp("(?<![A-Za-z])([A-Za-z]{3})\\s?[-\u2212\u2013(]?\\s?\\d|\\d[\\d.,\\s\u00a0\u202f')]*?(?:[.,:]?-)?\\s?([A-Za-z]{3})(?![A-Za-z])", flags))]
1385
+ .map((m) => m[1] ?? m[2])
1386
+ .find((word) => (flags.includes("i") || word === word.toUpperCase()) && currencies.has(word.toUpperCase()));
1387
+ // A symbol before a lowercase word: "€150 all" is in euros, not in ALL (found in review).
1388
+ const upper = beside("gu");
1389
+ if (upper) return { kind: "code", is: upper };
1390
+ // A dollar its letters name ("US$15", "CA$15", "R$ 15") is that dollar, never any (found in review).
1391
+ const named = /(?<![A-Za-z])([A-Z]{1,3})\$/.exec(text)?.[0];
1392
+ if (named && SYMBOL_CODES[named]) return { kind: "symbol", is: named };
1393
+ const symbol = /\p{Sc}+/u.exec(text)?.[0];
1394
+ if (symbol) return { kind: "symbol", is: symbol };
1395
+ // A local notation ("100 kr", "Rs. 500", "5,00 zł") is one too, by its spelling: "kr" is never "€" (found in review).
1396
+ // Only beside the number: "Din saldo: 150 kr" is in kr, its "Din" ("your") no dinar.
1397
+ const local = [...text.toLowerCase().matchAll(/(?<!\p{L})(\p{L}+)\.?\s?[-\u2212\u2013]?\d|\d[\d.,\s\u00a0\u202f']*?(?:[.,:]?-)?\s?(\p{L}+)(?!\p{L})/gu)].map((m) => m[1] ?? m[2]).find((word) => LOCAL_CURRENCIES.has(word));
1398
+ if (local) return { kind: "symbol", is: local };
1399
+ // A lowercase word ("150 eur", but also "Top 10", "try 10") is judged against codes only, never a symbol.
1400
+ const iso = beside("giu");
1401
+ return iso ? { kind: "code", is: iso.toUpperCase(), loose: true } : undefined;
1402
+ }
1403
+
1404
+ /** The codes a symbol can stand for; a symbol not listed ("kr" is no symbol) is compared by its spelling. */
1405
+ const SYMBOL_CODES: Record<string, string[]> = {
1406
+ "€": ["EUR"], "£": ["GBP", "EGP", "GIP", "FKP", "SHP", "SYP", "LBP", "SDG", "SSP"], "₹": ["INR"], "₩": ["KRW", "KPW"], "₺": ["TRY"], "₽": ["RUB"], "₪": ["ILS"], "₫": ["VND"], "₱": ["PHP"], "₴": ["UAH"], "฿": ["THB"], "₦": ["NGN"], "₲": ["PYG"], "₸": ["KZT"], "₾": ["GEL"], "₼": ["AZN"],
1407
+ "$": ["USD", "CAD", "AUD", "NZD", "SGD", "HKD", "MXN", "ARS", "CLP", "COP", "TWD", "BRL", "UYU", "JMD", "TTD", "BBD", "BSD", "BZD", "BMD", "KYD", "XCD", "FJD", "SBD", "LRD", "NAD", "GYD", "SRD", "BND", "ZWL", "TVD", "KID", "CUP", "DOP", "MOP", "NIO", "TOP", "WST", "CVE"],
1408
+ "US$": ["USD"], "CA$": ["CAD"], "C$": ["CAD", "NIO"], "A$": ["AUD"], "AU$": ["AUD"], "NZ$": ["NZD"], "HK$": ["HKD"], "S$": ["SGD"], "R$": ["BRL"], "NT$": ["TWD"], "RD$": ["DOP"], "MX$": ["MXN"], "MOP$": ["MOP"], "T$": ["TOP"], "WS$": ["WST"],
1409
+ "¥": ["JPY", "CNY"], "¥": ["JPY", "CNY"], "¢": ["USD", "CAD", "GHS"],
1410
+ };
1411
+
1412
+ /** Whether two currencies differ ("NOK" and "EUR", "$" and "€", "$" and "NOK"); "$" and "USD" or "US$" may be one. */
1413
+ export function otherCurrency(a: ReturnType<typeof amountCurrency>, b: ReturnType<typeof amountCurrency>): boolean {
1414
+ if (a === undefined || b === undefined) return false;
1415
+ if (a.kind === "code" && b.kind === "code") return a.is !== b.is;
1416
+ // A lowercase word read as a code is judged against codes only.
1417
+ if (a.loose || b.loose) return false;
1418
+ // A symbol stands for its codes: "$5" may be USD 5 or US$ 5, never EUR 5 or € 5 (found in review).
1419
+ const codes = (c: NonNullable<typeof a>) => (c.kind === "code" ? [c.is] : SYMBOL_CODES[c.is]);
1420
+ const [x, y] = [codes(a), codes(b)];
1421
+ if (x === undefined || y === undefined) return a.kind === b.kind && a.is !== b.is;
1422
+ return !x.some((code) => y.includes(code));
1423
+ }
1424
+
1333
1425
  /**
1334
1426
  * Whether two displayed values differ, for an expectDiffers check. Two
1335
1427
  * amounts compare as numbers ("NOK 1 295" and "NOK 1,295.00" are equal), and
@@ -1447,6 +1539,11 @@ export function jsonExpected(check: ResponseJsonCheck, text: string | undefined
1447
1539
  if (typeof value === "number" && Number.isInteger(value) && !Number.isSafeInteger(value)) {
1448
1540
  throw new Error(`JSON field ${JSON.stringify(check.path)}: ${text} is too large to compare exactly as a number; check it as a string`);
1449
1541
  }
1542
+ // A decimal with more digits than a double holds ("0.10000000000000001") reads as another one (0.1) (found in review).
1543
+ const digits = (n: string) => n.replace(/[eE].*$/, "").replace(/\D/g, "").replace(/^0+|0+$/g, "");
1544
+ if (typeof value === "number" && Number.isFinite(value) && digits(text!.trim()) !== digits(String(value).replace(/^-/, ""))) {
1545
+ throw new Error(`JSON field ${JSON.stringify(check.path)}: ${text} has more digits than a number holds exactly; check it as a string or with fewer digits`);
1546
+ }
1450
1547
  if ((check.type === "null" ? value === null : typeof value === check.type) && (typeof value !== "number" || Number.isFinite(value))) return value;
1451
1548
  throw new Error(`JSON field ${JSON.stringify(check.path)}: expected value must be a valid ${check.type}`);
1452
1549
  }
@@ -1513,7 +1610,7 @@ const compareDecimal = (a: NonNullable<ReturnType<typeof decimal>>, b: NonNullab
1513
1610
  };
1514
1611
 
1515
1612
  /** Whether a number parsed is the number written: 9007199254740991.1 is read as 9007199254740991, and 1e400 as Infinity. */
1516
- const heldAsWritten = (written: string, value: number): boolean => {
1613
+ export const heldAsWritten = (written: string, value: number): boolean => {
1517
1614
  const [a, b] = [decimal(written), decimal(String(value))];
1518
1615
  return a !== undefined && b !== undefined && compareDecimal(a, b) === 0;
1519
1616
  };
@@ -1523,6 +1620,32 @@ const parseChecked = (text: string): unknown =>
1523
1620
  JSON.parse(text, (_key, value: unknown, context?: { source?: string }) =>
1524
1621
  typeof value === "number" && context?.source !== undefined && (Math.abs(value) > Number.MAX_SAFE_INTEGER || !heldAsWritten(context.source, value)) ? new ExactNumber(context.source) : value);
1525
1622
 
1623
+ /**
1624
+ * A JSON body's value at a pointer as a key two values share only when they
1625
+ * are the same JSON: numbers by their exact decimal (0.1 and
1626
+ * 0.10000000000000001 differ, 1 and 1.0 do not), never equal to a string of
1627
+ * the same digits, keys in any order. For a group's `same` check (found in review).
1628
+ */
1629
+ /** A JSON body's value at a pointer as the API wrote it: 0.10000000000000001 and a 19-digit id are never shown rounded. */
1630
+ export function exactValueText(body: string, read: (json: unknown) => unknown): string | undefined {
1631
+ const mark = "\u0000exact:";
1632
+ const marked = (v: unknown): unknown => (v instanceof ExactNumber ? `${mark}${String(v)}` : Array.isArray(v) ? v.map(marked) : v !== null && typeof v === "object" ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, marked(x)])) : v);
1633
+ const value = read(parseChecked(body));
1634
+ return value === undefined ? undefined : JSON.stringify(marked(value)).replace(/"\\u0000exact:([^"]*)"/g, "$1");
1635
+ }
1636
+
1637
+ export function exactValueKey(body: string, read: (json: unknown) => unknown): string | undefined {
1638
+ const keyed = (v: unknown): unknown => {
1639
+ const number = v instanceof ExactNumber ? decimal(String(v)) : typeof v === "number" ? decimal(String(v)) : undefined;
1640
+ if (number) return { "\u0000number": `${number.sign}:${number.digits}:${number.point}` };
1641
+ if (Array.isArray(v)) return v.map(keyed);
1642
+ if (v !== null && typeof v === "object") return Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([k, x]) => [k, keyed(x)]));
1643
+ return v;
1644
+ };
1645
+ const value = read(parseChecked(body));
1646
+ return value === undefined ? undefined : JSON.stringify(keyed(value));
1647
+ }
1648
+
1526
1649
  const kind = (value: unknown) => value === null ? "null" : Array.isArray(value) ? "array" : value instanceof ExactNumber ? "number" : typeof value;
1527
1650
  const describe = (value: unknown) => `${kind(value)}${value instanceof ExactNumber ? ` ${value}` : value === null || typeof value !== "object" ? ` ${JSON.stringify(value)}` : ""}`;
1528
1651