tolkira 0.3.0 → 0.4.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 (56) hide show
  1. package/DESIGN.md +131 -9
  2. package/GLOSSARY.md +115 -8
  3. package/README.md +229 -37
  4. package/dist/attachment.d.ts +33 -0
  5. package/dist/attempt-diagnostics.d.ts +2 -0
  6. package/dist/ci.d.ts +12 -0
  7. package/dist/cli.js +7099 -3785
  8. package/dist/cli.js.map +4 -4
  9. package/dist/compat/cucumber-html-reporter.js +174 -8
  10. package/dist/compat/cucumber-html-reporter.js.map +4 -4
  11. package/dist/compat/options.d.ts +2 -0
  12. package/dist/email.d.ts +18 -0
  13. package/dist/history.d.ts +41 -0
  14. package/dist/i18n/catalogs.d.ts +7 -0
  15. package/dist/index.d.ts +12 -1
  16. package/dist/index.js +5148 -2453
  17. package/dist/index.js.map +4 -4
  18. package/dist/input/detect.d.ts +30 -0
  19. package/dist/input/load.d.ts +1 -0
  20. package/dist/input/playwright.d.ts +14 -0
  21. package/dist/options.d.ts +6 -0
  22. package/dist/output.d.ts +7 -1
  23. package/dist/pdf.d.ts +9 -0
  24. package/dist/render/attachments.d.ts +3 -0
  25. package/dist/render/ci.d.ts +4 -0
  26. package/dist/render/client-i18n.d.ts +7 -0
  27. package/dist/render/details.d.ts +5 -0
  28. package/dist/render/dom-contract.d.ts +42 -0
  29. package/dist/render/format.d.ts +34 -0
  30. package/dist/render/html.d.ts +2 -9
  31. package/dist/render/i18n.d.ts +30 -0
  32. package/dist/render/markdown.d.ts +2 -1
  33. package/dist/render/matrix.d.ts +3 -0
  34. package/dist/render/print-script.d.ts +1 -0
  35. package/dist/render/report-client.d.ts +1 -0
  36. package/dist/render/report.d.ts +4 -0
  37. package/dist/render/search.d.ts +3 -0
  38. package/dist/render/trends.d.ts +7 -0
  39. package/dist/render/triage.d.ts +5 -0
  40. package/dist/render/types.d.ts +26 -0
  41. package/dist/report/index-run.d.ts +69 -0
  42. package/dist/report/model.d.ts +11 -2
  43. package/dist/summary.d.ts +3 -0
  44. package/dist/warnings.d.ts +6 -0
  45. package/docs/AGENT-INTERFACE.md +367 -33
  46. package/docs/CI.md +185 -0
  47. package/docs/COMPATIBILITY.md +72 -11
  48. package/docs/CUCUMBER-COMPATIBILITY.md +50 -26
  49. package/docs/EMAIL.md +273 -0
  50. package/docs/I18N.md +241 -0
  51. package/docs/JUNIT-XML.md +19 -2
  52. package/docs/LIMITATIONS.md +10 -6
  53. package/docs/PDF.md +255 -0
  54. package/llms.txt +36 -4
  55. package/package.json +21 -5
  56. package/dist/report/attachment.d.ts +0 -10
@@ -1,4 +1,5 @@
1
1
  // src/compat/cucumber-html-reporter.ts
2
+ import { readFile as readFile2 } from "node:fs/promises";
2
3
  import { generateReport } from "../index.js";
3
4
 
4
5
  // src/output.ts
@@ -48,24 +49,48 @@ async function outputOverwritesInput(inputs, output, logo) {
48
49
  const outputPath = path2.resolve(output);
49
50
  const outputInfo = await stat(outputPath).catch(() => void 0);
50
51
  if (!outputInfo?.isFile()) return false;
51
- const outputReal = realpathSync(outputPath);
52
52
  if (logo) {
53
53
  const logoInfo = await stat(logo).catch(() => void 0);
54
- if (logoInfo?.isFile() && realpathSync(logo) === outputReal) return true;
54
+ if (logoInfo?.isFile() && samePath(logo, outputPath)) return true;
55
55
  }
56
56
  for (const input of inputs) {
57
57
  const inputInfo = await stat(input).catch(() => void 0);
58
58
  if (!inputInfo) continue;
59
- if (inputInfo.isFile() && realpathSync(input) === outputReal) return true;
59
+ if (inputInfo.isFile() && samePath(input, outputPath)) return true;
60
60
  if (inputInfo.isDirectory()) {
61
- const directory = realpathSync(input);
62
- for (const file of await collectReportFiles(directory)) {
63
- if (realpathSync(file) === outputReal) return true;
61
+ for (const file of await collectReportFiles(input)) {
62
+ if (samePath(file, outputPath)) return true;
64
63
  }
65
64
  }
66
65
  }
67
66
  return false;
68
67
  }
68
+ function foldCase(value) {
69
+ return process.platform === "win32" || process.platform === "darwin" ? value.toLowerCase() : value;
70
+ }
71
+ function existingRealPath(file) {
72
+ try {
73
+ return realpathSync(file);
74
+ } catch {
75
+ return void 0;
76
+ }
77
+ }
78
+ function canonicalPath(file) {
79
+ const resolved = path2.resolve(file);
80
+ let current = resolved;
81
+ const tail = [];
82
+ for (; ; ) {
83
+ const real = existingRealPath(current);
84
+ if (real !== void 0) return foldCase(path2.join(real, ...tail));
85
+ const parent = path2.dirname(current);
86
+ if (parent === current) return foldCase(resolved);
87
+ tail.unshift(path2.basename(current));
88
+ current = parent;
89
+ }
90
+ }
91
+ function samePath(a, b) {
92
+ return canonicalPath(a) === canonicalPath(b);
93
+ }
69
94
  async function writeAtomic(output, content) {
70
95
  const directory = path2.dirname(output);
71
96
  await mkdir(directory, { recursive: true });
@@ -82,6 +107,15 @@ async function writeAtomic(output, content) {
82
107
  }
83
108
  }
84
109
 
110
+ // src/warnings.ts
111
+ var ATTACHMENT_HINT = "Run from the folder that contains the referenced files, or regenerate the JSON where the files live.";
112
+ function attachmentWarning(count) {
113
+ if (count === 1) {
114
+ return "1 path attachment was skipped: it is outside the allowed roots (its input file's folder and Tolkira's working directory). The report may be missing screenshots or files.";
115
+ }
116
+ return `${count} path attachments were skipped: they are outside the allowed roots (each input file's folder and Tolkira's working directory). The report may be missing screenshots or files.`;
117
+ }
118
+
85
119
  // src/compat/options.ts
86
120
  import { readFile, stat as stat2 } from "node:fs/promises";
87
121
  import path3 from "node:path";
@@ -97,6 +131,38 @@ import {
97
131
  import { TestStepResultStatus as TestStepResultStatus2 } from "@cucumber/messages";
98
132
  var STATUS_VALUES = new Set(Object.values(TestStepResultStatus2));
99
133
 
134
+ // src/input/playwright.ts
135
+ import {
136
+ AttachmentContentEncoding as AttachmentContentEncoding2,
137
+ TestStepResultStatus as TestStepResultStatus3
138
+ } from "@cucumber/messages";
139
+
140
+ // src/attachment.ts
141
+ var MAX_ATTACHMENT_BYTES = 50 * 1024 * 1024;
142
+ var MAX_TOTAL_ATTACHMENT_BYTES = 100 * 1024 * 1024;
143
+ var MEDIA_TYPES = {
144
+ "application/json": { extension: "json", kind: "text", textFormat: "json" },
145
+ "application/octet-stream": { extension: "bin", kind: "binary", textFormat: "plain" },
146
+ "image/gif": { extension: "gif", kind: "image", textFormat: "plain" },
147
+ "image/jpeg": { extension: "jpg", kind: "image", textFormat: "plain" },
148
+ "image/png": { extension: "png", kind: "image", textFormat: "plain" },
149
+ "image/svg+xml": { extension: "svg", kind: "image", textFormat: "plain" },
150
+ "image/webp": { extension: "webp", kind: "image", textFormat: "plain" },
151
+ "text/csv": { extension: "csv", kind: "text", textFormat: "plain" },
152
+ "text/html": { extension: "html", kind: "text", textFormat: "plain" },
153
+ "text/plain": { extension: "txt", kind: "text", textFormat: "plain" },
154
+ "text/uri-list": { extension: "txt", kind: "text", textFormat: "uri-list" },
155
+ "text/x.cucumber.log+plain": { extension: "log", kind: "text", textFormat: "log" },
156
+ "video/mp4": { extension: "mp4", kind: "video", textFormat: "plain" },
157
+ "video/webm": { extension: "webm", kind: "video", textFormat: "plain" }
158
+ };
159
+ var SAFE_MEDIA_TYPES = new Set(Object.keys(MEDIA_TYPES));
160
+
161
+ // src/input/playwright.ts
162
+ var PASSED = TestStepResultStatus3.PASSED;
163
+ var FAILED = TestStepResultStatus3.FAILED;
164
+ var SKIPPED = TestStepResultStatus3.SKIPPED;
165
+
100
166
  // src/input/load.ts
101
167
  var MAX_TOTAL_INPUT_BYTES = 100 * 1024 * 1024;
102
168
  function addInputBytes(totalBytes, size) {
@@ -177,6 +243,9 @@ function flattenMetadata(value, warnings) {
177
243
  }
178
244
  return result;
179
245
  }
246
+ function stripBom(content) {
247
+ return content.replace(/^\uFEFF/, "");
248
+ }
180
249
  async function resolveInputs(options, warnings) {
181
250
  const jsonFile = typeof options.jsonFile === "string" && options.jsonFile.trim() ? options.jsonFile.trim() : void 0;
182
251
  const jsonDir = typeof options.jsonDir === "string" && options.jsonDir.trim() ? options.jsonDir.trim() : void 0;
@@ -211,7 +280,9 @@ async function resolveInputs(options, warnings) {
211
280
  }
212
281
  totalBytes = addInputBytes(totalBytes, info.size);
213
282
  try {
214
- const parsed = JSON.parse(await readFile(file, "utf8"));
283
+ const parsed = JSON.parse(
284
+ stripBom(await readFile(file, "utf8"))
285
+ );
215
286
  if (!Array.isArray(parsed)) throw new Error("not a feature array");
216
287
  valid.push(file);
217
288
  } catch (error) {
@@ -226,19 +297,114 @@ async function resolveInputs(options, warnings) {
226
297
  }
227
298
 
228
299
  // src/compat/cucumber-html-reporter.ts
300
+ var FALLBACK_URI = "Feature: URI Not Present";
301
+ function featureKey(feature) {
302
+ return typeof feature.uri === "string" && feature.uri ? feature.uri : FALLBACK_URI;
303
+ }
304
+ async function readFeatures(file) {
305
+ let parsed;
306
+ try {
307
+ parsed = JSON.parse(stripBom(await readFile2(file, "utf8")));
308
+ } catch {
309
+ return void 0;
310
+ }
311
+ if (!Array.isArray(parsed) || parsed.some((feature) => typeof feature !== "object" || feature === null)) {
312
+ return void 0;
313
+ }
314
+ return parsed;
315
+ }
316
+ function collisionError(sidecar, input) {
317
+ return new Error(
318
+ `compat: sidecar ${sidecar} must not overwrite an input file (${input})`
319
+ );
320
+ }
321
+ function isPreviousSidecar(candidate, others) {
322
+ if (others.length === 0) return false;
323
+ const represented = /* @__PURE__ */ new Set();
324
+ for (const { features } of others) {
325
+ for (const feature of features) represented.add(featureKey(feature));
326
+ }
327
+ return candidate.features.every(
328
+ (feature) => represented.has(featureKey(feature))
329
+ );
330
+ }
331
+ async function planSidecar(inputs, sidecar) {
332
+ const parsed = [];
333
+ for (const file of inputs) {
334
+ const features = await readFeatures(file);
335
+ if (!features) {
336
+ throw new Error(`compat: ${file} is not a legacy feature array`);
337
+ }
338
+ parsed.push({ file, features });
339
+ }
340
+ const index = parsed.findIndex(({ file }) => samePath(file, sidecar));
341
+ let selected = parsed;
342
+ if (index !== -1) {
343
+ const candidate = parsed[index];
344
+ const others = parsed.filter((_, position) => position !== index);
345
+ if (!isPreviousSidecar(candidate, others)) {
346
+ throw collisionError(sidecar, candidate.file);
347
+ }
348
+ selected = others;
349
+ }
350
+ const merged = /* @__PURE__ */ new Map();
351
+ for (const { features } of selected) {
352
+ for (const feature of features) {
353
+ const key = featureKey(feature);
354
+ const elements = (Array.isArray(feature.elements) ? feature.elements : []).map((element) => ({ ...element, retried: 0 }));
355
+ const existing = merged.get(key);
356
+ if (existing) {
357
+ existing.elements.push(...elements);
358
+ } else {
359
+ merged.set(key, { feature, elements });
360
+ }
361
+ }
362
+ }
363
+ return {
364
+ inputs: selected.map(({ file }) => file),
365
+ merged: [...merged.values()]
366
+ };
367
+ }
368
+ async function writeMergedJson(plan, sidecar) {
369
+ for (const input of plan.inputs) {
370
+ if (samePath(input, sidecar)) throw collisionError(sidecar, input);
371
+ }
372
+ const result = plan.merged.map(({ feature, elements }) => ({
373
+ ...feature,
374
+ elements
375
+ }));
376
+ await writeAtomic(sidecar, JSON.stringify(result, null, 2));
377
+ }
229
378
  async function run(options) {
230
379
  const warnings = [];
231
380
  const output = requireOutput(options);
232
381
  warnIgnoredOptions(options, warnings);
382
+ const hasJsonFile = Boolean(
383
+ typeof options.jsonFile === "string" && options.jsonFile.trim()
384
+ );
385
+ const hasJsonDir = Boolean(
386
+ typeof options.jsonDir === "string" && options.jsonDir.trim()
387
+ );
233
388
  const root = inputRoot(options);
234
389
  if (root && await outputOverwritesInput([root], output)) {
235
390
  throw new Error("compat: output must not overwrite an input file");
236
391
  }
237
392
  const inputs = await resolveInputs(options, warnings);
393
+ const sidecar = `${output}.json`;
394
+ const plan = !hasJsonFile && hasJsonDir ? await planSidecar(inputs, sidecar) : void 0;
238
395
  const title = mapTitle(options, warnings);
239
396
  const metadata = flattenMetadata(options.metadata, warnings);
240
- const { html, summary } = await generateReport(inputs, { title, metadata });
397
+ const { html, summary, skippedAttachments } = await generateReport(
398
+ plan?.inputs ?? inputs,
399
+ { title, metadata }
400
+ );
241
401
  await writeAtomic(output, html);
402
+ if (plan) await writeMergedJson(plan, sidecar);
403
+ if (skippedAttachments > 0) {
404
+ warnings.push(
405
+ `${attachmentWarning(skippedAttachments)} ${ATTACHMENT_HINT}`
406
+ );
407
+ }
242
408
  return { output, warnings, summary };
243
409
  }
244
410
  function generate(options, callback) {