tolkira 0.1.2 → 0.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.
package/DESIGN.md CHANGED
@@ -103,19 +103,22 @@ describe the viewport, not the font.
103
103
  | Top bar / tabs | `.topbar`, `.view` | Report and Details; active tab is a text state, not a card |
104
104
  | Run header | `.runHead`, `.health` | Title, metadata, pass rate, segmented status bar |
105
105
  | Toolbar | `.toolbar`, `.search`, `.filter` | Search and status filters; search opens matching features and scenarios; filters only for present statuses |
106
- | Feature | `details.feature` | Native disclosure; status, name, path, counts, duration |
106
+ | Triage index | `.triage` | Needs-attention rows with status text, counts and up to three scenario links; five rows visible, up to fifteen more behind a disclosure |
107
+ | Source strip | `.sources` | Per-input cards for multi-file runs with real provenance; status, counts and a proportion bar; hidden below 560 px, where the feature source badge remains |
108
+ | Feature | `details.feature` | Native disclosure; status, name, counts, proportion bar, source badge, URI |
107
109
  | Scenario | `details.scenario` | Fixed thumbnail gutter, status, name, tags, steps, duration |
108
110
  | Step | `.step` | Status glyph plus screen-reader label, keyword, text, error, doc string, focusable table, attachments |
109
111
  | Attachment | `.shot`, `.fileText`, `.fileLink` | Images inline; text in `<pre>`; binary as download; alt names the scenario and step |
110
- | Details | `.analysis` | Feature table, status distribution, Run / Cucumber environment / Custom metadata blocks, agent summary |
112
+ | Details | `.analysis` | Feature-by-status matrix, status distribution, Run / Cucumber environment / Custom metadata blocks, agent summary |
111
113
 
112
114
  ## Interaction rules
113
115
 
114
116
  - Feature and scenario summaries are the only click targets that toggle; a
115
117
  click inside the detail does not close it.
116
118
  - Chevron rotates on open; `prefers-reduced-motion` removes the transition.
117
- - Search and filters: hide non-matches, open features and matched scenarios,
118
- update a polite live region, show an empty state when nothing matches.
119
+ - Search and filters: hide non-matches and open matching features; search also
120
+ opens matching scenarios, update a polite live region, show an empty state
121
+ when nothing matches.
119
122
  - Switching tabs scrolls to the top; the previous panel's scroll position is
120
123
  not restored.
121
124
  - The lightbox locks background scrolling, restores focus to its trigger on
@@ -124,7 +127,8 @@ describe the viewport, not the font.
124
127
  - Status is never colour-only: scenario badges carry text, step markers carry a
125
128
  shape glyph plus a screen-reader label, and forced-colours mode keeps the
126
129
  glyph, marker border and disclosure chevron visible.
127
- - The failure is open by default; everything else is scannable when collapsed.
130
+ - The failure is open by default; screenshot-bearing scenarios and their
131
+ features also open; everything else is scannable when collapsed.
128
132
  - No right-click-only actions; use visible buttons or a `…` menu. Keyboard and
129
133
  touch must reach the same actions.
130
134
  - No modal for a task that inline disclosure can solve.
@@ -159,6 +163,8 @@ Direction A is implemented in production:
159
163
  - warm paper tokens, hairline sections and monospace measurements;
160
164
  - fixed thumbnail gutter on every scenario row, also on mobile;
161
165
  - chevrons, failed-first disclosures and search that opens matching features;
166
+ - exception-first Report order, a triage index and a source strip;
167
+ - feature counts/proportion bars and a feature-by-status matrix in Details;
162
168
  - `undefined` is a distinct status, not a neutral one;
163
169
  - Details tab with producer, runtime, OS, CPU, protocol and user metadata;
164
170
  - empty state for search/filter results;
@@ -167,8 +173,7 @@ Direction A is implemented in production:
167
173
  CSS lives in `src/render/report.css`; `scripts/build-styles.mjs` generates
168
174
  `src/render/styles.ts` for the inline report.
169
175
 
170
- Still open: a 200 % text-zoom pass with real content, and charts/trends in
171
- Advanced.
176
+ Still open: charts/trends in Details and optional map/compact lenses.
172
177
 
173
178
  ## Non-goals
174
179
 
package/GLOSSARY.md CHANGED
@@ -15,10 +15,31 @@ used by official Cucumber implementations.
15
15
  **Attachment** — a binary or text artefact attached to a test step, scenario or
16
16
  hook. Screenshots are attachments.
17
17
 
18
+ **Attachment fallback name** — the deterministic `attachment.<ext>` name used
19
+ when an attachment has no Cucumber `fileName`. Known parameterised media types
20
+ keep their extension; unknown types normalise to `application/octet-stream` and
21
+ `attachment.bin`.
22
+
23
+ **CI metadata** — the optional Messages `meta.ci` block: CI name and URL plus
24
+ git remote, revision, branch and tag. It renders in the HTML header and Details
25
+ and never in the JSON summary.
26
+
27
+ **ANSI log** — a `text/x.cucumber.log+plain` attachment. Tolkira renders its SGR
28
+ colours, including 256-colour and truecolour, strips other control sequences and
29
+ offers a copy action.
30
+
18
31
  **Embedding** — the legacy JSON representation of an attachment (`embeddings[]`).
19
32
 
20
33
  **Adapter** — code that turns an input format into Cucumber Messages.
21
34
 
35
+ **Stream adapter** — `CucumberHtmlStream`, a shape-compatible Node `Transform`
36
+ that accepts Messages envelopes and renders one HTML document on flush with
37
+ `RenderReportOptions`. It buffers the run; it is not an incremental renderer.
38
+
39
+ **Parameter highlighting** — wrapping the fragments matched by a single
40
+ `stepMatchArgumentsLists` entry in `span.param`, labelled with the Cucumber
41
+ parameter type. It is cosmetic and does not change step text or the summary.
42
+
22
43
  **Normalisation** — converting legacy JSON into Messages so one renderer can
23
44
  handle both.
24
45
 
@@ -29,6 +50,93 @@ component tree.
29
50
  **Shell** — Tolkira's own wrapper around the renderer: title, metadata, summary,
30
51
  theme, logo.
31
52
 
53
+ **Triage index** — the "Needs attention" block above the feature list. It shows
54
+ non-passing features with counts and up to three scenario links; five rows are
55
+ visible and up to fifteen more sit behind a disclosure.
56
+
57
+ **Source strip** — per-input cards above the feature list for multi-file runs
58
+ with real provenance. Each card shows the input's worst status, counts and a
59
+ proportion bar.
60
+
61
+ **Feature matrix** — the Details table with one row per feature and one count
62
+ column per status present in the run, plus total and duration.
63
+
64
+ **Scenario outline** — a Gherkin scenario template with an Examples table.
65
+ Tolkira renders one outline section per executed outline with examples in
66
+ Messages input.
67
+
68
+ **Examples block** — one Examples table under a scenario outline, with its own
69
+ name, tags and description. An outline can have several.
70
+
71
+ **Example row** — one executed row of an examples block, labelled
72
+ `#<examples>.<example>` in the report. Each row keeps its own outcome,
73
+ attachments and anchor.
74
+
75
+ **Executed scenario** — a scenario whose selected test case reported at least
76
+ one raw step result, including a hook result. Only executed scenarios appear in
77
+ scenario counts, percentages, bars, triage and the Details matrix.
78
+
79
+ **Unexecuted scenario** — a scenario whose selected test case started but
80
+ reported no raw step result, including a started-but-unfinished case. It stays
81
+ visible without an outcome, keeps `status: "unknown"` and `executed: false` in
82
+ the summary, and leaves every count surface. Any attachment emitted for it is
83
+ dropped. A never-started pickle produces no row at all.
84
+
85
+ **Rule** — a Gherkin grouping of scenarios and outlines under a named business
86
+ rule. The report renders a rule section with its keyword, name, description and
87
+ tags; scenarios stay inside their rule.
88
+
89
+ **Background** — shared setup steps for a feature or rule. Cucumber compiles
90
+ them into each pickle, so the report keeps the steps in the scenario step lists
91
+ and renders only the background heading and description once, when present.
92
+
93
+ **Description** — free-text Markdown under a feature, rule, background,
94
+ scenario, outline or examples block. The report renders a safe GFM subset in a
95
+ block container; images become alt text and raw HTML stays escaped.
96
+
97
+ **Tag expression** — the official Cucumber boolean tag query (`@a and not @b`,
98
+ `or`, `not`, parentheses, escaped tags). The search box uses it only when the
99
+ whole query is tag-shaped; mixed text and tags fall back to substring search.
100
+
101
+ **URL state** — the shareable `?query=`, repeated lowercase `?hide=` and `?tag=`
102
+ parameters. The report restores them and updates them with `replaceState`
103
+ without adding history entries.
104
+
105
+ **Own tag** — a tag written on the scenario itself; for an outline row, the
106
+ examples-block tags. A standalone scenario row shows its own tags. Outline
107
+ scenario tags appear on the outline heading and examples tags on the examples
108
+ heading; example rows show no tags.
109
+
110
+ **Inherited tag** — a feature or rule tag carried into a pickle. It stays
111
+ available to the tag filter and search but is not repeated on every row.
112
+
113
+ **Hook** — a Cucumber before/after function around a scenario or step. The
114
+ report shows per-scenario hooks separately from steps.
115
+
116
+ **Test-run hook** — a BeforeAll/AfterAll function around the whole run. It
117
+ appears in the report's Hooks section, not inside a scenario.
118
+
119
+ **Step diagnostic** — the block inside an undefined or ambiguous step. It
120
+ always shows the status lead and adds suggestion snippets or matching step
121
+ definitions when the Messages input provides them.
122
+
123
+ **Snippet** — the suggested step-definition code from a Messages `suggestion`
124
+ envelope, shown escaped inside an undefined step.
125
+
126
+ **Step definition match** — a `stepDefinition` pattern and its `uri:line`
127
+ source reference, shown inside an ambiguous step.
128
+
129
+ **Auto-expansion** — the report opens features and executed scenarios whose
130
+ status is not `passed` by default. Passed scenarios stay collapsed unless they
131
+ carry an image; unexecuted rows stay collapsed and show no outcome. A feature
132
+ whose scenarios are all unexecuted opens; a mixed feature does not open just
133
+ because it contains an unexecuted row. Text search and a valid tag expression
134
+ still open at most 20 rows.
135
+
136
+ **Provenance** — the input file a feature came from. Tolkira only uses it when
137
+ the feature URI belongs to exactly one input; shared or missing provenance
138
+ renders a flat report.
139
+
32
140
  **Summary** — the stable, renderer-independent JSON document emitted by
33
141
  `--json` / `summarizeReport` for agents and CI. It is versioned and is not the
34
142
  HTML report.
package/README.md CHANGED
@@ -1,12 +1,12 @@
1
1
  # Tolkira
2
2
 
3
- **One self-contained HTML report for Cucumber JSON, Messages and JUnit XML.**
3
+ **Cucumber reports that stay readable: legacy JSON, Messages and JUnit XML in one self-contained HTML file.**
4
4
 
5
5
  Tolkira turns test results into a single HTML file you can open offline, attach
6
6
  to a ticket, or keep as a CI artifact. Screenshots, logs and other attachments
7
7
  stay inside the file. There is no server, no CDN and no telemetry.
8
8
 
9
- Current release: **v0.1.2** · [npm](https://www.npmjs.com/package/tolkira) · [Changelog](https://github.com/Silasoa/tolkira/blob/main/docs/CHANGELOG.md)
9
+ Current release: **v0.3.0** - [npm](https://www.npmjs.com/package/tolkira) - [Changelog](https://github.com/Silasoa/tolkira/blob/main/docs/CHANGELOG.md)
10
10
 
11
11
  > **How this is built:** Tolkira is human-directed and largely AI-generated.
12
12
  > The maintainer sets the product direction and approves releases. Most code,
@@ -18,17 +18,23 @@ Current release: **v0.1.2** · [npm](https://www.npmjs.com/package/tolkira) · [
18
18
 
19
19
  ## Install
20
20
 
21
+ Tolkira requires Node.js 22 or newer.
22
+
21
23
  ```shell
24
+ # CLI for one-off use
22
25
  npm install --global tolkira
23
26
  tolkira --help
24
27
  ```
25
28
 
26
- Or run it without a global install:
29
+ Or add it to a project and run it from there (recommended for CI):
27
30
 
28
31
  ```shell
32
+ npm install --save-dev tolkira
29
33
  npx tolkira --help
30
34
  ```
31
35
 
36
+ `npx tolkira --help` also works without a local install.
37
+
32
38
  On Windows, `npx` can fail when the current folder contains parentheses in its
33
39
  path. Use the global install or a folder without parentheses if that happens.
34
40
 
@@ -52,28 +58,108 @@ tolkira test-results/ --out report.html --logo path/to/logo.png
52
58
  Tolkira accepts one or more files and directories. A directory is scanned
53
59
  recursively for supported result files. Everything is merged into one report.
54
60
 
55
- For CI tools and AI agents, ask for the stable JSON summary instead of scraping
56
- the HTML:
61
+ ## For agents and CI
62
+
63
+ Install as a project dependency and write both artifacts:
57
64
 
58
65
  ```shell
59
- tolkira test-results/ --out report.html --json
60
- tolkira test-results/ --json
66
+ npm install --save-dev tolkira
67
+ npx tolkira test-results/ --out report.html --title "CI run" --json > summary.json
61
68
  ```
62
69
 
70
+ GitHub Actions step:
71
+
72
+ ```yaml
73
+ - name: Generate Cucumber report
74
+ if: always()
75
+ run: npx tolkira test-results/ --out report.html --title "CI run" --json > summary.json
76
+
77
+ - name: Upload report
78
+ if: always()
79
+ uses: actions/upload-artifact@v4
80
+ with:
81
+ name: cucumber-report
82
+ path: |
83
+ report.html
84
+ summary.json
85
+ ```
86
+
87
+ `--json` writes exactly one JSON document to stdout; warnings go to stderr.
88
+ Exit code 0 means the report was generated, not that the tests passed. Read
89
+ `status` and `counts` from the summary. Abridged real output (counts and steps
90
+ trimmed):
91
+
92
+ ```json
93
+ {
94
+ "schemaVersion": 2,
95
+ "status": "failed",
96
+ "counts": {
97
+ "scenarios": { "total": 6, "passed": 5, "failed": 1 }
98
+ },
99
+ "scenarios": [
100
+ {
101
+ "name": "Fred wants to see passing scenarios in the HTML report",
102
+ "uri": "features/happy.feature",
103
+ "status": "failed",
104
+ "executed": true,
105
+ "steps": [
106
+ {
107
+ "keyword": "When",
108
+ "text": "this feature runs with background",
109
+ "status": "failed",
110
+ "message": "Expected values to be strictly equal: -8 !== 0"
111
+ }
112
+ ]
113
+ }
114
+ ]
115
+ }
116
+ ```
117
+
118
+ Paste this into an agent's instructions:
119
+
120
+ ```text
121
+ Use Tolkira for Cucumber results. Run `npx tolkira <inputs> --out report.html --json`
122
+ and parse stdout as the JSON summary; do not scrape the HTML. Exit code 0 means
123
+ the report was generated, not that the tests passed. Read summary.status and
124
+ summary.counts, and check scenarios[].executed before treating a status as an
125
+ outcome. Upload report.html as the human-facing artifact.
126
+ ```
127
+
128
+ See [`docs/AGENT-INTERFACE.md`](https://github.com/Silasoa/tolkira/blob/main/docs/AGENT-INTERFACE.md)
129
+ for the full schema and exit codes.
130
+
63
131
  ## What you get
64
132
 
65
133
  - **One file that works offline.** CSS, JavaScript and attachments are inline.
66
134
  No network requests, no remote fonts, no analytics.
67
- - **The failure first.** Failed scenarios are open by default, with the error
68
- and screenshot where you need them.
135
+ - **The failure first.** Failed scenarios are open by default, and a compact
136
+ triage index lists non-passing features and scenarios before passed ones,
137
+ with links that open the scenario detail.
138
+ - **Multi-file context.** A source strip shows per-input status, counts and a
139
+ proportion bar when the run has more than one input file and provenance is
140
+ unambiguous. On phones the strip is hidden and the feature row keeps the
141
+ source.
69
142
  - **Screenshots and attachments that survive.** Images, text, video, audio and
70
143
  files are preserved through the legacy JSON adapter.
71
144
  - **Search and filters.** Search scenarios, features, steps and tags; filter by
72
145
  status and tag; open matching features automatically and highlight matches.
146
+ - **Rendered descriptions.** Feature, rule, background, scenario and examples
147
+ descriptions render a safe GFM subset - headings, emphasis, code, lists,
148
+ tables, quotes and http(s)/mailto links - from Messages, legacy JSON and JUnit.
149
+ - **Tag expressions.** Search accepts the official Cucumber grammar
150
+ (`@a and not @b`, parentheses, escaped tags). Mixed text and tags fall back to
151
+ plain substring search.
152
+ - **Shareable filtered views.** Search, hidden statuses and the tag filter live
153
+ in `?query=`, repeated `?hide=` and `?tag=`, so a URL reproduces the same view.
154
+ - **Parameter highlighting.** Matched step arguments render with their Cucumber
155
+ parameter type from Messages; ambiguous or unmatched steps stay plain.
156
+ - **Messages stream adapter.** `CucumberHtmlStream` is shape-compatible with the
157
+ official formatter: it accepts envelopes, buffers until flush and emits the
158
+ same offline HTML as `renderReport`, for embedding without a temp file.
73
159
  - **Copy failure.** Copy a failed scenario's feature, failed step and error as
74
160
  plain text for a ticket or an agent.
75
- - **A Details view when you need it.** Status distribution, a feature table,
76
- run metadata and the Cucumber environment (producer, runtime, OS, CPU,
161
+ - **A Details view when you need it.** Status distribution, a feature-by-status
162
+ matrix, run metadata and the Cucumber environment (producer, runtime, OS, CPU,
77
163
  protocol).
78
164
  - **A stable summary for agents.** `--json` and `summarizeReport()` return a
79
165
  versioned schema with counts, durations, scenarios, steps and failure
@@ -88,7 +174,7 @@ tolkira test-results/ --json
88
174
 
89
175
  | Input | What works |
90
176
  | --- | --- |
91
- | **Legacy Cucumber JSON** | cucumber-js 2.3.1–13.3.0, Behave 1.3.3, cucumber-jvm 7.22.1 and cucumber-ruby 12.0.1 are tested with real output. Other producers often work; the adapter follows the Cucumber legacy dialect. |
177
+ | **Legacy Cucumber JSON** | cucumber-js 2.3.1–13.3.0, Behave 1.3.3, cucumber-jvm 7.22.1 and cucumber-ruby 12.0.1 are covered by producer fixtures. Behave's real run does not yet include attachments or doc strings; see the [dated limitations table](https://github.com/Silasoa/tolkira/blob/main/docs/LIMITATIONS.md). Other producers often work; the adapter follows the Cucumber legacy dialect. |
92
178
  | **Cucumber Messages (NDJSON)** | cucumber-js 11.2, cucumber-jvm 7.22.1 and cucumber-ruby 12.0.1 fixtures. This is the modern, implementation-independent format. |
93
179
  | **JUnit XML** | Basic mode: suites, test cases, statuses, durations, failures, skipped cases and system output. JUnit has no Gherkin steps or screenshots; each test case is shown as one synthetic step. |
94
180
 
@@ -114,6 +200,32 @@ Tolkira keeps the old input working and fixes the parts that hurt:
114
200
  - a stable JSON summary for agents and CI;
115
201
  - a small, reviewed dependency surface.
116
202
 
203
+ Single-file output alone is no longer unique: the official formatter and Allure
204
+ can produce one file. Tolkira's difference is the combination - both Cucumber
205
+ generations, JUnit as cheap breadth, an agent-readable summary, and no server,
206
+ CDN or telemetry.
207
+
208
+ ### What parity means here
209
+
210
+ "Parity" in this project means content and navigation: the same statements,
211
+ steps, tags, statuses, durations and descriptions, plus search, tag expressions
212
+ and shareable filter URLs, whether the input is legacy JSON, Messages or JUnit.
213
+ It does not mean theme parity with `cucumber-html-reporter`, a report folder, or
214
+ external attachments; Tolkira deliberately stays one offline file. The honest
215
+ claim is credible Messages report parity, not full formatter parity.
216
+
217
+ ### How it compares
218
+
219
+ Last checked 2026-11-11 against the current package docs. Trade-offs are
220
+ deliberate; pick the tool that fits the job.
221
+
222
+ | Tool | Offline | Legacy JSON | Messages | JUnit | JSON summary | Themes | ESM/CJS | Node | Maintenance | Choose it if… |
223
+ | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
224
+ | [cucumber-html-reporter](https://github.com/gkushang/cucumber-html-reporter) | No, CDN assets | Yes | No | No | No | Three built-in themes | CJS | Old, no engine pin | Unmaintained since Oct 2024 | You need its exact themes and offline use is not a requirement. |
225
+ | [multiple-cucumber-html-reporter](https://github.com/WasiqB/multiple-cucumber-html-reporter) | Yes, report folder (CDN optional) | Yes | Yes | No | Saved JSON (`saveCollectedJSON`) | Dark mode, custom CSS | ESM (v4) | 22+ | Active | You want a dashboard, multi-run grouping, i18n and a report folder. |
226
+ | [Official Cucumber HTML formatter](https://github.com/cucumber/html-formatter) | Yes, one file | No | Yes | No | No | Custom CSS/JS only | ESM | Modern Node | Official Cucumber project | You use Cucumber Messages only and want the official look. |
227
+ | **Tolkira** | **Yes, one file** | **Yes** | **Yes** | **Basic** | **Versioned summary (`--json`)** | **Branding, dark mode; no theme gallery** | **ESM; CJS compat shim** | **22+** | **Active** | **You need one offline file from legacy JSON and/or Messages, plus a stable summary for CI and agents.** |
228
+
117
229
  The visual comparison uses the report setup from
118
230
  [Seed-Test](https://github.com/adessoSE/Seed-Test). If you are curious about
119
231
  Seed-Test, you are welcome to take a look; the comparison notes and screenshots
@@ -121,13 +233,36 @@ are in [`docs/COMPARISON.md`](https://github.com/Silasoa/tolkira/blob/main/docs/
121
233
 
122
234
  ## Migrating from cucumber-html-reporter
123
235
 
124
- The old options object is accepted as-is; only the import changes.
236
+ Install Tolkira next to the old reporter and keep the existing JSON output:
237
+
238
+ ```shell
239
+ npm i -D tolkira
240
+ ```
241
+
242
+ Node.js 22 or newer is required. Node 20 is end-of-life and unsupported;
243
+ upgrading to Node 22+ is the migration cost for both the ESM and CommonJS
244
+ paths. The core and CLI are ESM-only; the compatibility subpath also loads
245
+ from CommonJS through an async wrapper.
246
+
247
+ **Before — CommonJS with cucumber-html-reporter:**
125
248
 
126
249
  ```js
127
- // before
250
+ // report.js
128
251
  const reporter = require('cucumber-html-reporter');
129
252
 
130
- // after
253
+ reporter.generate({
254
+ theme: 'bootstrap',
255
+ jsonFile: 'reports/cucumber.json',
256
+ output: 'reports/report.html',
257
+ brandTitle: 'Checkout acceptance',
258
+ metadata: { Browser: 'Chrome', Environment: 'Staging' },
259
+ });
260
+ ```
261
+
262
+ **After — ESM with Tolkira:**
263
+
264
+ ```js
265
+ // report.mjs
131
266
  import { generate } from 'tolkira/compat/cucumber-html-reporter';
132
267
 
133
268
  await generate({
@@ -138,11 +273,71 @@ await generate({
138
273
  });
139
274
  ```
140
275
 
141
- The shim is experimental. Themes, charts, external screenshots and browser
142
- launch are not reproduced; they warn and use Tolkira's defaults. It consumes
143
- the same input JSON, never the old rendered HTML. See
144
- [`docs/COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPATIBILITY.md) for the full mapping and
145
- caveats.
276
+ **If the project must stay CommonJS**, require the compatibility subpath and
277
+ await the async wrapper:
278
+
279
+ ```js
280
+ // report.cjs
281
+ const { generate } = require('tolkira/compat/cucumber-html-reporter');
282
+
283
+ async function main() {
284
+ await generate({
285
+ jsonFile: 'reports/cucumber.json',
286
+ output: 'reports/report.html',
287
+ });
288
+ }
289
+
290
+ main().catch((error) => {
291
+ console.error(error);
292
+ process.exitCode = 1;
293
+ });
294
+ ```
295
+
296
+ The wrapper is only for the compatibility subpath; the core package, CLI and
297
+ other exports remain ESM-only. There is no default export.
298
+
299
+ The options object is mostly compatible, but the call contract is not. Only
300
+ the import style changing is not the whole story:
301
+
302
+ | Behaviour | `cucumber-html-reporter` | Tolkira compat shim |
303
+ | --- | --- | --- |
304
+ | Input | `jsonFile` falls back to `output + '.json'` when omitted | `jsonFile` or `jsonDir` is required; there is no implicit fallback |
305
+ | Return value | Sync `true` on success without a callback, `undefined` with one; `undefined` for a bad report | Always a `Promise<CompatResult>` with `output`, `warnings` and `summary`; await every call |
306
+ | Errors | The callback receives a string; without a callback a failure can be silent | The promise rejects with an `Error`, and the callback receives the same `Error` |
307
+ | Callback | `callback()` on success, `callback(string)` on failure | `callback(error?)`; the promise still rejects |
308
+ | `jsonDir` | Recursively merges features by `uri`, dedupes them and writes an `output + '.json'` sidecar | Scans recursively but passes the files as separate inputs; writes no sidecar and does not dedupe |
309
+ | Output timing | The HTML is written synchronously before `generate` returns | The HTML is complete only when the promise resolves |
310
+ | Export | `require('cucumber-html-reporter').generate` | Named `generate`; no default export |
311
+
312
+ **Callback caveat:** callback-only code can ignore the returned promise.
313
+ Tolkira marks that ignored promise handled so it does not crash the process;
314
+ awaiting the same call still throws. Errors are `Error` objects, not the
315
+ legacy strings. If the callback itself throws, handle that error yourself.
316
+
317
+ `theme` is ignored with a warning. Themes, charts, external screenshots and
318
+ browser launch are not reproduced. The shim consumes the same input JSON,
319
+ never the old rendered HTML.
320
+ See [`docs/COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPATIBILITY.md)
321
+ for the full mapping and caveats.
322
+
323
+ ### From multiple-cucumber-html-reporter
324
+
325
+ There is no MCHR shim; use the core CLI. The common mapping:
326
+
327
+ ```shell
328
+ # MCHR config: jsonDir + reportPath + reportName
329
+ mchr
330
+
331
+ # Tolkira
332
+ npx tolkira path/to/jsonDir --out reports/index.html --title "My report"
333
+ ```
334
+
335
+ Map `jsonDir` to the input directory, `reportPath`/`reportName` to `--out`,
336
+ `metadata` to repeated `--meta key=value`, and `brandLogo` to `--logo`.
337
+ Dashboard, history, trends, i18n, email reports and the multi-file folder report
338
+ are not reproduced. See
339
+ [`docs/COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPATIBILITY.md#multiple-cucumber-html-reporter)
340
+ for the mapping.
146
341
 
147
342
  ## Privacy and limits
148
343
 
@@ -156,10 +351,17 @@ caveats.
156
351
  - One report is one file. External attachments for very large media are a
157
352
  future option.
158
353
 
354
+ See [`docs/LIMITATIONS.md`](https://github.com/Silasoa/tolkira/blob/main/docs/LIMITATIONS.md)
355
+ for the dated limitations table (last verified 2026-11-11), including the
356
+ remaining Behave real-run gap.
357
+
159
358
  ## Documentation
160
359
 
360
+ - [`llms.txt`](https://github.com/Silasoa/tolkira/blob/main/llms.txt) — short entry point for AI agents.
161
361
  - [`docs/AGENT-INTERFACE.md`](https://github.com/Silasoa/tolkira/blob/main/docs/AGENT-INTERFACE.md) — JSON schema, CLI
162
362
  contract and exit codes.
363
+ - [`docs/LIMITATIONS.md`](https://github.com/Silasoa/tolkira/blob/main/docs/LIMITATIONS.md) — dated limitations table
364
+ (last verified 2026-11-11).
163
365
  - [`docs/CUCUMBER-COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/CUCUMBER-COMPATIBILITY.md) — tested
164
366
  Cucumber producers and versions.
165
367
  - [`docs/JUNIT-XML.md`](https://github.com/Silasoa/tolkira/blob/main/docs/JUNIT-XML.md) — JUnit basic-mode mapping and
package/SECURITY.md CHANGED
@@ -26,5 +26,8 @@ Tolkira processes untrusted test output. Security-relevant areas include:
26
26
  - denial of service through very large reports or attachments;
27
27
  - dependency vulnerabilities.
28
28
 
29
+ HTML attachments are always escaped text, and SVG attachments are only used as
30
+ `<img>` data-URI sources; neither is injected as markup or a document.
31
+
29
32
  Tolkira does not send telemetry and does not make network requests. A report
30
33
  should remain fully offline.