Skip to content

Commit 5cf4806

Browse files
gustavovalverdegustavovalverde
authored
fix(extract): handle fragment HTML and inline sample fixture (#8)
* fix(extract): handle fragment HTML and inline sample fixture - guard Readability extraction against missing `<html>` roots and rerun parse when needed - switch unit tests to use inline `SAMPLE_ARTICLE_HTML` fixtures, avoiding LFS pointers on CI - instruct CI checkout to pull LFS artifacts for perf workflows and test matrix Prevents null documentElement crashes during extraction and keeps regression gates reproducible. * chore(fixtures): restore benchmark corpus * chore(fixtures): restore benchmark corpus and fix LFS objects * fix(bench): add error handling and regenerate comparison results - Added error handling to benchmark runner to prevent crashes - Regenerated comparison-latest.json with proper benchmark data - Fixed LFS object issue by using actual benchmark results * fix: comprehensive fixes for benchmark and Readability issues - Fix documentElement null error by capturing metadata before Readability modifies DOM - Add real fixture tests to catch Readability errors that were missing - Fix benchmark configuration: increase max file size to 2MB to include wikipedia-largest.html - Correct iteration count from 1000 to 100 for standard benchmarks - Add robust error handling in benchmark runner to prevent crashes The core issue was that Readability.parse() modifies the DOM structure, potentially making documentElement null. We now capture lang and title before parsing. Tests now properly validate real-world HTML fixtures to prevent regression. * fix: restore missing LFS objects and update benchmarks - Recreate simple.html test fixture for CI - Regenerate benchmark artifacts with 10 iterations - Update README with latest benchmark results - Fix CI failures due to missing LFS objects (63e0267c9f, f2ea1e465b)
1 parent 5c8a43f commit 5cf4806

17 files changed

Lines changed: 799 additions & 574 deletions

‎.changeset/salty-mice-rush.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
"h2m-parser": patch
3+
---
4+
5+
- Guard Readability extraction against fragment HTML by reparsing missing `<html>` wrappers, fixing `documentElement` access errors.
6+
- Inline sample article fixtures in tests to avoid Git LFS pointers and keep CI checks working out of the box.

‎.github/workflows/performance-regression.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ jobs:
3030
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
3131
with:
3232
persist-credentials: false
33+
lfs: true
3334

3435
- name: Setup pnpm
3536
uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4.1.0
@@ -133,6 +134,7 @@ jobs:
133134
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
134135
with:
135136
fetch-depth: 0
137+
lfs: true
136138

137139
- name: Setup pnpm
138140
uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4.1.0

‎.github/workflows/test.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ jobs:
2727
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 #v5.0.0
2828
with:
2929
persist-credentials: false
30+
lfs: true
3031

3132
- name: Setup pnpm
3233
uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda #v4.1.0

‎README.md‎

Lines changed: 59 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -101,48 +101,49 @@ const options: Options = {
101101
## Benchmarks
102102

103103
<!-- BENCHMARK:START -->
104-
<!-- Last updated: 2025-09-28T17:49:57.461Z -->
104+
<!-- Last updated: 2025-09-29T08:44:59.546Z -->
105105

106106
## Performance
107107

108108
**Runtime ranking (lower is better):**
109-
1. h2m-parser — 1.429ms
110-
2. mdream — 1.535ms
111-
3. Turndown — 7.618ms
112-
4. node-html-markdown — 146.396ms
109+
1. mdream — 1.133ms
110+
2. h2m-parser — 1.193ms
111+
3. node-html-markdown — 3.894ms
112+
4. Turndown — 5.830ms
113113

114114
<details>
115115
<summary>📊 Benchmark Results (click to expand)</summary>
116116

117117
### Benchmark Methodology
118118

119-
- **Dataset:** 93 files (4 synthetic + 89 real HTML documents)
119+
- **Dataset:** 94 files (5 synthetic + 89 real HTML documents)
120120
- **Dataset path:** tests/fixtures
121-
- **File sizes:** 21KB to 1771KB (mean: ~119KB)
122-
- **Iterations:** 100 per file for statistical significance
123-
- **Total runtime:** 710.6 seconds
121+
- **File sizes:** 21KB to 420KB (mean: ~104KB)
122+
- **Iterations:** 10 per file for statistical significance
123+
- **Total runtime:** 41.3 seconds
124124
- **Environment:** Node.js with standard V8 optimizations
125125

126126
### Average Processing Time
127127

128-
Tested across 93 files in tests/fixtures (up to 1771KB):
128+
Tested across 94 files in tests/fixtures (up to 420KB):
129129

130130
| Library | Without Readability | With Readability | Relative |
131131
|---------|---------------------|------------------|----------|
132-
| **h2m-parser** ✅ | **1.429ms** | 15.656ms | **Fastest** |
133-
| mdream | 1.535ms | ❌ Not supported | 1.07x slower |
134-
| Turndown | 7.618ms | ❌ Not supported | 5.33x slower |
135-
| node-html-markdown | 146.396ms | ❌ Not supported | 102.48x slower |
132+
| mdream | 1.133ms | ❌ Not supported | Fastest |
133+
| **h2m-parser** ✅ | **1.193ms** | 7.707ms | **1.05x slower** |
134+
| node-html-markdown | 3.894ms | ❌ Not supported | 3.44x slower |
135+
| Turndown | 5.830ms | ❌ Not supported | 5.15x slower |
136136

137-
**Readability overhead (h2m-parser):** +14.228ms (enables article extraction + content cleaning)
137+
**Readability overhead (h2m-parser):** +6.513ms (enables article extraction + content cleaning)
138138

139139
### Performance Analysis
140140

141-
- **Fastest baseline:** h2m-parser averages 1.429ms per document without Readability.
142-
- **h2m-parser vs Turndown:** 5.33x faster (7.618ms → 1.429ms)
143-
- **h2m-parser vs node-html-markdown:** 102.48x faster (146.396ms → 1.429ms)
144-
- **h2m-parser vs mdream:** 1.07x faster (1.535ms → 1.429ms)
145-
- **Readability impact:** 11.0x slower when enabled (1.429ms → 15.656ms)
141+
- **Fastest baseline:** mdream averages 1.133ms per document without Readability.
142+
- **h2m-parser gap to mdream:** 1.05× slower ( mdream: 1.133ms → h2m-parser: 1.193ms ).
143+
- **h2m-parser vs Turndown:** 4.89x faster (5.830ms → 1.193ms)
144+
- **h2m-parser vs node-html-markdown:** 3.26x faster (3.894ms → 1.193ms)
145+
- **h2m-parser vs mdream:** 0.95x slower (1.133ms → 1.193ms)
146+
- **Readability impact:** 6.5x slower when enabled (1.193ms → 7.707ms)
146147
- **Token savings vs raw HTML:** 24051 tokens saved (95.63%) on tests/fixtures/039c4b966d1f2a0c589ac0aad211fe65500ad1cb58c7f45b34251db7056803ec.html.
147148
- **Algorithmic complexity:** O(n) linear scaling confirmed across file sizes
148149

@@ -153,75 +154,75 @@ Estimated processing times for different file sizes (without Readability):
153154
```
154155
100KB 1ms
155156
1MB 12ms
156-
10MB 123ms
157+
10MB 117ms
157158
100MB 1.2s
158159
```
159160

160-
*Based on linear scaling from 119KB average file size at 1.429ms*
161+
*Based on linear scaling from 104KB average file size at 1.193ms*
161162

162163
### Detailed Results by File Size
163164

164165
#### tiny (18 bytes)
165166

166167
| Library | Mean (ms) | P95 (ms) | P99 (ms) |
167168
|---------|-----------|----------|----------|
168-
| h2m-parser (no Readability) | 0.013 | 0.026 | 0.029 |
169-
| h2m-parser (with Readability) | 0.211 | 0.323 | 0.346 |
170-
| Turndown | 0.024 | 0.045 | 0.054 |
171-
| node-html-markdown | 0.012 | 0.018 | 0.022 |
172-
| Mdream | 0.005 | 0.008 | 0.011 |
169+
| h2m-parser (no Readability) | 0.014 | 0.018 | 0.018 |
170+
| h2m-parser (with Readability) | 0.253 | 0.341 | 0.341 |
171+
| Turndown | 0.033 | 0.047 | 0.047 |
172+
| node-html-markdown | 0.013 | 0.018 | 0.018 |
173+
| Mdream | 0.007 | 0.011 | 0.011 |
173174

174175
#### small (84 bytes)
175176

176177
| Library | Mean (ms) | P95 (ms) | P99 (ms) |
177178
|---------|-----------|----------|----------|
178-
| h2m-parser (no Readability) | 0.016 | 0.023 | 0.024 |
179-
| h2m-parser (with Readability) | 0.174 | 0.209 | 0.211 |
180-
| Turndown | 0.041 | 0.051 | 0.058 |
181-
| node-html-markdown | 0.021 | 0.028 | 0.028 |
182-
| Mdream | 0.014 | 0.020 | 0.021 |
179+
| h2m-parser (no Readability) | 0.026 | 0.029 | 0.029 |
180+
| h2m-parser (with Readability) | 0.225 | 0.261 | 0.261 |
181+
| Turndown | 0.064 | 0.079 | 0.079 |
182+
| node-html-markdown | 0.035 | 0.045 | 0.045 |
183+
| Mdream | 0.017 | 0.020 | 0.020 |
183184

184185
#### medium (369 bytes)
185186

186187
| Library | Mean (ms) | P95 (ms) | P99 (ms) |
187188
|---------|-----------|----------|----------|
188-
| h2m-parser (no Readability) | 0.013 | 0.015 | 0.016 |
189-
| h2m-parser (with Readability) | 0.220 | 0.249 | 0.276 |
190-
| Turndown | 0.046 | 0.053 | 0.054 |
191-
| node-html-markdown | 0.018 | 0.019 | 0.020 |
192-
| Mdream | 0.020 | 0.038 | 0.038 |
189+
| h2m-parser (no Readability) | 0.025 | 0.039 | 0.039 |
190+
| h2m-parser (with Readability) | 0.371 | 0.474 | 0.474 |
191+
| Turndown | 0.078 | 0.088 | 0.088 |
192+
| node-html-markdown | 0.046 | 0.065 | 0.065 |
193+
| Mdream | 0.048 | 0.056 | 0.056 |
193194

194195
#### file_42 (21KB)
195196

196197
| Library | Mean (ms) | P95 (ms) | P99 (ms) |
197198
|---------|-----------|----------|----------|
198-
| h2m-parser (no Readability) | 0.255 | 0.288 | 0.300 |
199-
| h2m-parser (with Readability) | 1.848 | 2.020 | 2.041 |
200-
| Turndown | 1.404 | 1.574 | 1.587 |
201-
| node-html-markdown | 0.416 | 0.474 | 0.486 |
202-
| Mdream | 0.359 | 0.419 | 0.422 |
199+
| h2m-parser (no Readability) | 0.270 | 0.307 | 0.307 |
200+
| h2m-parser (with Readability) | 1.930 | 2.146 | 2.146 |
201+
| Turndown | 1.374 | 1.502 | 1.502 |
202+
| node-html-markdown | 0.420 | 0.465 | 0.465 |
203+
| Mdream | 0.352 | 0.405 | 0.405 |
203204

204205
#### file_33 (88KB)
205206

206207
| Library | Mean (ms) | P95 (ms) | P99 (ms) |
207208
|---------|-----------|----------|----------|
208-
| h2m-parser (no Readability) | 1.012 | 1.118 | 1.142 |
209-
| h2m-parser (with Readability) | 6.122 | 6.449 | 9.356 |
210-
| Turndown | 5.964 | 7.175 | 7.260 |
211-
| node-html-markdown | 3.161 | 3.507 | 3.677 |
212-
| Mdream | 1.946 | 2.035 | 2.090 |
209+
| h2m-parser (no Readability) | 1.040 | 1.169 | 1.169 |
210+
| h2m-parser (with Readability) | 5.909 | 6.208 | 6.208 |
211+
| Turndown | 6.228 | 7.849 | 7.849 |
212+
| node-html-markdown | 3.644 | 4.039 | 4.039 |
213+
| Mdream | 2.001 | 2.194 | 2.194 |
213214

214-
#### file_89 (1771KB)
215+
#### file_88 (420KB)
215216

216217
| Library | Mean (ms) | P95 (ms) | P99 (ms) |
217218
|---------|-----------|----------|----------|
218-
| h2m-parser (no Readability) | 31.259 | 32.395 | 32.627 |
219-
| h2m-parser (with Readability) | 773.690 | 1022.269 | 1025.088 |
220-
| Turndown | 194.083 | 200.565 | 201.472 |
221-
| node-html-markdown | 13272.156 | 13570.330 | 13586.638 |
222-
| Mdream | 49.983 | 50.678 | 50.773 |
219+
| h2m-parser (no Readability) | 3.264 | 3.406 | 3.406 |
220+
| h2m-parser (with Readability) | 28.608 | 32.022 | 32.022 |
221+
| Turndown | 13.271 | 15.061 | 15.061 |
222+
| node-html-markdown | 7.431 | 7.629 | 7.629 |
223+
| Mdream | 9.212 | 9.926 | 9.926 |
223224

224-
*See [`bench/comparison-results.md`](bench/comparison-results.md) for complete results across all 93 files*
225+
*See [`bench/comparison-results.md`](bench/comparison-results.md) for complete results across all 94 files*
225226

226227
### Workflow Comparison (Await vs Stream)
227228

@@ -271,7 +272,7 @@ Fetched: https://en.wikipedia.org/wiki/Markdown
271272

272273
| Feature | h2m-parser | Turndown | node-html-markdown | mdream |
273274
|---------|------------|----------|--------------------|--------|
274-
| **Performance** | ✅ Fastest | ❌ +433% slower | ❌ +10148% slower | ⚠️ +7% slower |
275+
| **Performance** | ⚠️ +5% slower | ❌ +415% slower | ❌ +244% slower | ✅ Fastest |
275276
| **Readability** | ✅ | ❌ | ❌ | ⚠️ |
276277
| **Link cleanup** | ✅ | ❌ | ❌ | ⚠️ |
277278
| **Front matter** | ✅ | ❌ | ❌ | ✅ |
@@ -292,17 +293,14 @@ Fetched: https://en.wikipedia.org/wiki/Markdown
292293
Run benchmarks yourself:
293294

294295
```bash
295-
# Interactive menu with the common tasks
296-
pnpm bench
297-
298-
# Quick comparison (10 iterations, 10 files)
296+
# Quick comparison (10 iterations)
299297
pnpm bench:compare:quick
300298

301299
# Full comparison (1000 iterations)
302300
pnpm bench:compare:full
303301

304-
# Refresh README from cached results (use --fresh for a 100-iteration rebuild)
305-
pnpm bench:readme --cached
302+
# Update README with fresh results
303+
pnpm bench:readme
306304
```
307305

308306
<!-- BENCHMARK:END -->

‎bench/.results/comparison-latest.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
version https://git-lfs.github.com/spec/v1
2-
oid sha256:187ef6e9ec60c18360b3214e227ce830f2ec241ce0d497e5e05b4f5e5fc7cf33
3-
size 178793
2+
oid sha256:8b30c85c7c9f3b6ee358d8a8503969dec324f0d88fe74b244d3d7b63eb599816
3+
size 180118

‎bench/.results/summary-latest.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
version https://git-lfs.github.com/spec/v1
2-
oid sha256:63e0267c9f9d9e4b7c7cfa685f55099879a48e4cb30ef6882d9851c705d75711
3-
size 9927
2+
oid sha256:9e785e6ab86b1cf7a391809d326750c7dfa61cba0ffce296953cd9c0eb250870
3+
size 9930

0 commit comments

Comments
 (0)