tolkira 0.2.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 (64) hide show
  1. package/DESIGN.md +131 -9
  2. package/GLOSSARY.md +201 -1
  3. package/README.md +413 -29
  4. package/SECURITY.md +3 -0
  5. package/dist/attachment.d.ts +33 -0
  6. package/dist/attempt-diagnostics.d.ts +2 -0
  7. package/dist/ci.d.ts +12 -0
  8. package/dist/cli.js +6881 -2691
  9. package/dist/cli.js.map +4 -4
  10. package/dist/compat/cucumber-html-reporter.cjs +12 -0
  11. package/dist/compat/cucumber-html-reporter.d.cts +10 -0
  12. package/dist/compat/cucumber-html-reporter.js +263 -26
  13. package/dist/compat/cucumber-html-reporter.js.map +4 -4
  14. package/dist/compat/options.d.ts +4 -0
  15. package/dist/email.d.ts +18 -0
  16. package/dist/history.d.ts +41 -0
  17. package/dist/i18n/catalogs.d.ts +7 -0
  18. package/dist/index.d.ts +15 -7
  19. package/dist/index.js +5301 -1709
  20. package/dist/index.js.map +4 -4
  21. package/dist/input/background.d.ts +4 -0
  22. package/dist/input/detect.d.ts +30 -0
  23. package/dist/input/load.d.ts +3 -0
  24. package/dist/input/playwright.d.ts +14 -0
  25. package/dist/options.d.ts +18 -0
  26. package/dist/output.d.ts +9 -1
  27. package/dist/pdf.d.ts +9 -0
  28. package/dist/render/ansi.d.ts +2 -0
  29. package/dist/render/attachments.d.ts +3 -0
  30. package/dist/render/ci.d.ts +4 -0
  31. package/dist/render/client-bundle.d.ts +1 -0
  32. package/dist/render/client-i18n.d.ts +7 -0
  33. package/dist/render/details.d.ts +5 -0
  34. package/dist/render/dom-contract.d.ts +42 -0
  35. package/dist/render/format.d.ts +34 -0
  36. package/dist/render/html.d.ts +2 -9
  37. package/dist/render/i18n.d.ts +30 -0
  38. package/dist/render/markdown.d.ts +2 -0
  39. package/dist/render/matrix.d.ts +3 -0
  40. package/dist/render/print-script.d.ts +1 -0
  41. package/dist/render/report-client.d.ts +1 -0
  42. package/dist/render/report.d.ts +4 -0
  43. package/dist/render/search.d.ts +21 -0
  44. package/dist/render/trends.d.ts +7 -0
  45. package/dist/render/triage.d.ts +5 -0
  46. package/dist/render/types.d.ts +26 -0
  47. package/dist/report/index-run.d.ts +69 -0
  48. package/dist/report/model.d.ts +96 -6
  49. package/dist/report/status.d.ts +12 -0
  50. package/dist/stream.d.ts +15 -0
  51. package/dist/summary.d.ts +17 -2
  52. package/dist/text.d.ts +15 -0
  53. package/dist/warnings.d.ts +6 -0
  54. package/docs/AGENT-INTERFACE.md +504 -33
  55. package/docs/CI.md +185 -0
  56. package/docs/COMPATIBILITY.md +121 -16
  57. package/docs/CUCUMBER-COMPATIBILITY.md +232 -15
  58. package/docs/EMAIL.md +273 -0
  59. package/docs/I18N.md +241 -0
  60. package/docs/JUNIT-XML.md +46 -4
  61. package/docs/LIMITATIONS.md +21 -0
  62. package/docs/PDF.md +255 -0
  63. package/llms.txt +63 -0
  64. package/package.json +46 -8
@@ -0,0 +1,12 @@
1
+ "use strict";
2
+ function generate(options, callback) {
3
+ const promise = import('./cucumber-html-reporter.js').then((mod) => mod.generate(options, callback));
4
+ if (callback) {
5
+ // Callback-only callers ignore the returned promise; keep its rejection
6
+ // handled without changing what awaiting callers see.
7
+ promise.catch(() => undefined);
8
+ }
9
+ return promise;
10
+ }
11
+ const compat = { generate };
12
+ module.exports = compat;
@@ -0,0 +1,10 @@
1
+ import type { CompatResult, CucumberHtmlReporterOptions } from './options.js';
2
+ declare function generate(options: CucumberHtmlReporterOptions, callback?: (error?: Error | null) => void): Promise<CompatResult>;
3
+ declare const compat: {
4
+ generate: typeof generate;
5
+ };
6
+ declare namespace compat {
7
+ type CucumberHtmlReporterOptions = import('./options.js').CucumberHtmlReporterOptions;
8
+ type CompatResult = import('./options.js').CompatResult;
9
+ }
10
+ export = compat;
@@ -1,33 +1,16 @@
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
5
6
  import { randomUUID } from "node:crypto";
6
- import { mkdir, rename, rm, writeFile } from "node:fs/promises";
7
- import path from "node:path";
8
- async function writeAtomic(output, content) {
9
- const directory = path.dirname(output);
10
- await mkdir(directory, { recursive: true });
11
- const temp = path.join(
12
- directory,
13
- `.${path.basename(output)}.${randomUUID()}.tmp`
14
- );
15
- try {
16
- await writeFile(temp, content, { encoding: "utf8", mode: 384, flag: "wx" });
17
- await rename(temp, output);
18
- } catch (error) {
19
- await rm(temp, { force: true }).catch(() => void 0);
20
- throw error;
21
- }
22
- }
23
-
24
- // src/compat/options.ts
25
- import { readFile } from "node:fs/promises";
26
- import path3 from "node:path";
7
+ import { realpathSync } from "node:fs";
8
+ import { mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
9
+ import path2 from "node:path";
27
10
 
28
11
  // src/input/files.ts
29
12
  import { readdir } from "node:fs/promises";
30
- import path2 from "node:path";
13
+ import path from "node:path";
31
14
  var SUPPORTED_EXTENSIONS = /* @__PURE__ */ new Set([
32
15
  ".json",
33
16
  ".jsonl",
@@ -46,14 +29,14 @@ async function collectReportFiles(directory, depth = 0) {
46
29
  const files = [];
47
30
  for (const entry of entries) {
48
31
  if (entry.isSymbolicLink()) continue;
49
- const full = path2.join(directory, entry.name);
32
+ const full = path.join(directory, entry.name);
50
33
  if (entry.isDirectory()) {
51
34
  if (IGNORED_DIRECTORIES.has(entry.name)) continue;
52
35
  files.push(...await collectReportFiles(full, depth + 1));
53
36
  continue;
54
37
  }
55
38
  if (!entry.isFile()) continue;
56
- if (!SUPPORTED_EXTENSIONS.has(path2.extname(entry.name).toLowerCase())) {
39
+ if (!SUPPORTED_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
57
40
  continue;
58
41
  }
59
42
  files.push(full);
@@ -61,6 +44,136 @@ async function collectReportFiles(directory, depth = 0) {
61
44
  return files;
62
45
  }
63
46
 
47
+ // src/output.ts
48
+ async function outputOverwritesInput(inputs, output, logo) {
49
+ const outputPath = path2.resolve(output);
50
+ const outputInfo = await stat(outputPath).catch(() => void 0);
51
+ if (!outputInfo?.isFile()) return false;
52
+ if (logo) {
53
+ const logoInfo = await stat(logo).catch(() => void 0);
54
+ if (logoInfo?.isFile() && samePath(logo, outputPath)) return true;
55
+ }
56
+ for (const input of inputs) {
57
+ const inputInfo = await stat(input).catch(() => void 0);
58
+ if (!inputInfo) continue;
59
+ if (inputInfo.isFile() && samePath(input, outputPath)) return true;
60
+ if (inputInfo.isDirectory()) {
61
+ for (const file of await collectReportFiles(input)) {
62
+ if (samePath(file, outputPath)) return true;
63
+ }
64
+ }
65
+ }
66
+ return false;
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
+ }
94
+ async function writeAtomic(output, content) {
95
+ const directory = path2.dirname(output);
96
+ await mkdir(directory, { recursive: true });
97
+ const temp = path2.join(
98
+ directory,
99
+ `.${path2.basename(output)}.${randomUUID()}.tmp`
100
+ );
101
+ try {
102
+ await writeFile(temp, content, { encoding: "utf8", mode: 384, flag: "wx" });
103
+ await rename(temp, output);
104
+ } catch (error) {
105
+ await rm(temp, { force: true }).catch(() => void 0);
106
+ throw error;
107
+ }
108
+ }
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
+
119
+ // src/compat/options.ts
120
+ import { readFile, stat as stat2 } from "node:fs/promises";
121
+ import path3 from "node:path";
122
+
123
+ // src/input/legacy.ts
124
+ import {
125
+ AttachmentContentEncoding,
126
+ HookType,
127
+ TestStepResultStatus
128
+ } from "@cucumber/messages";
129
+
130
+ // src/input/messages.ts
131
+ import { TestStepResultStatus as TestStepResultStatus2 } from "@cucumber/messages";
132
+ var STATUS_VALUES = new Set(Object.values(TestStepResultStatus2));
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
+
166
+ // src/input/load.ts
167
+ var MAX_TOTAL_INPUT_BYTES = 100 * 1024 * 1024;
168
+ function addInputBytes(totalBytes, size) {
169
+ if (totalBytes + size > MAX_TOTAL_INPUT_BYTES) {
170
+ throw new Error(
171
+ "Inputs exceed 100 MB in total. Split the report or use external attachments."
172
+ );
173
+ }
174
+ return totalBytes + size;
175
+ }
176
+
64
177
  // src/compat/options.ts
65
178
  var HANDLED_OPTIONS = /* @__PURE__ */ new Set([
66
179
  "jsonFile",
@@ -92,6 +205,11 @@ function warnIgnoredOptions(options, warnings) {
92
205
  );
93
206
  }
94
207
  }
208
+ function inputRoot(options) {
209
+ const jsonFile = typeof options.jsonFile === "string" && options.jsonFile.trim() ? options.jsonFile.trim() : void 0;
210
+ if (jsonFile) return jsonFile;
211
+ return typeof options.jsonDir === "string" && options.jsonDir.trim() ? options.jsonDir.trim() : void 0;
212
+ }
95
213
  function requireOutput(options) {
96
214
  const output = typeof options.output === "string" ? options.output.trim() : "";
97
215
  if (!output) throw new Error("compat: output is required");
@@ -125,6 +243,9 @@ function flattenMetadata(value, warnings) {
125
243
  }
126
244
  return result;
127
245
  }
246
+ function stripBom(content) {
247
+ return content.replace(/^\uFEFF/, "");
248
+ }
128
249
  async function resolveInputs(options, warnings) {
129
250
  const jsonFile = typeof options.jsonFile === "string" && options.jsonFile.trim() ? options.jsonFile.trim() : void 0;
130
251
  const jsonDir = typeof options.jsonDir === "string" && options.jsonDir.trim() ? options.jsonDir.trim() : void 0;
@@ -143,9 +264,25 @@ async function resolveInputs(options, warnings) {
143
264
  }
144
265
  if (!options.ignoreBadJsonFile) return files;
145
266
  const valid = [];
267
+ let totalBytes = 0;
146
268
  for (const file of files) {
269
+ let info;
270
+ try {
271
+ info = await stat2(file);
272
+ } catch (error) {
273
+ const detail = error instanceof Error ? error.message : String(error);
274
+ warnings.push(`skipped invalid JSON file ${file}: ${detail}`);
275
+ continue;
276
+ }
277
+ if (info.size > MAX_TOTAL_INPUT_BYTES) {
278
+ warnings.push(`skipped oversized JSON file ${file}: over 100 MB`);
279
+ continue;
280
+ }
281
+ totalBytes = addInputBytes(totalBytes, info.size);
147
282
  try {
148
- const parsed = JSON.parse(await readFile(file, "utf8"));
283
+ const parsed = JSON.parse(
284
+ stripBom(await readFile(file, "utf8"))
285
+ );
149
286
  if (!Array.isArray(parsed)) throw new Error("not a feature array");
150
287
  valid.push(file);
151
288
  } catch (error) {
@@ -160,15 +297,114 @@ async function resolveInputs(options, warnings) {
160
297
  }
161
298
 
162
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
+ }
163
378
  async function run(options) {
164
379
  const warnings = [];
165
380
  const output = requireOutput(options);
166
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
+ );
388
+ const root = inputRoot(options);
389
+ if (root && await outputOverwritesInput([root], output)) {
390
+ throw new Error("compat: output must not overwrite an input file");
391
+ }
167
392
  const inputs = await resolveInputs(options, warnings);
393
+ const sidecar = `${output}.json`;
394
+ const plan = !hasJsonFile && hasJsonDir ? await planSidecar(inputs, sidecar) : void 0;
168
395
  const title = mapTitle(options, warnings);
169
396
  const metadata = flattenMetadata(options.metadata, warnings);
170
- const { html, summary } = await generateReport(inputs, { title, metadata });
397
+ const { html, summary, skippedAttachments } = await generateReport(
398
+ plan?.inputs ?? inputs,
399
+ { title, metadata }
400
+ );
171
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
+ }
172
408
  return { output, warnings, summary };
173
409
  }
174
410
  function generate(options, callback) {
@@ -178,6 +414,7 @@ function generate(options, callback) {
178
414
  () => callback(null),
179
415
  (error) => callback(error instanceof Error ? error : new Error(String(error)))
180
416
  );
417
+ promise.catch(() => void 0);
181
418
  }
182
419
  return promise;
183
420
  }