feat(bench): simplify suites and enrich comparison metadata (#6)

* feat(bench): simplify suites and enrich comparison metadata

- introduce shared task runner (`bench/lib/task-runner.js`) and suite hub (`bench/suites.js`), then refactor `run-full suite`, `run-quick-suite`, and the CLI to use the unified pipeline instead of bespoke scripts
- extract fixture metadata (title, domain, link/script/table counts, word count) for every benchmarked file and persist it in
`bench/.results/comparison-latest.json`; console summaries now show domain/context and absolute deltas alongside ratios
- treat benchmark outputs/fixtures as first-class tracked artifacts by adding `.results` and root `fixtures` to Git LFS; update `.gitignore` so those directories remain visible while developers can opt out via LFS
- update README and benchmark artifacts to reflect the new metadata ordering and fresh results

* fix(h2m): types

* refactor(bench): unify benchmark tooling and refresh baseline

- standardise `runBenchmark` defaults (100 iterations, warmups, 5MB cap, full fixtures)
- wire the shared config through baseline, regression, and README refresh flows
- drop tracked benchmark artifacts now covered by .gitignore
- regenerate baseline metrics and comparison outputs with the new configuration
- document the workflow updates across README, docs, and bench guides

Ensures regression gates, published metrics, and local benches stay aligned while keeping the repo free of generated artifacts.

* chore: add changesets

* test(fixtures): increase timeout for HTML fixture processing

- Added a timeout of 60 seconds to the HTML fixture processing test to prevent potential timeouts during execution.
- Refactored the test structure for improved readability.

* fix(actions): optimize PR runs, conditions and permissions

Author: gustavovalverde

.changeset/unified-bench-telemetry.md

@@ -0,0 +1,6 @@
+---
+"h2m-parser": minor
+---
+
+Refined the htmlparser2 renderer to stream nodes directly, which removes the domhandler dependency and unlocks faster parse times on large fixtures.
+Expose granular `convert_parse`, `convert_render`, and `convert_postprocess` telemetry events (propagated through `H2MParser` and `htmlToMarkdown`) so downstream tooling can pinpoint hotspots while staying backwards compatible.

.gitattributes

@@ -0,0 +1,4 @@
+tests/fixtures/** filter=lfs diff=lfs merge=lfs -text
+bench/datasets/** filter=lfs diff=lfs merge=lfs -text
+bench/.results/** filter=lfs diff=lfs merge=lfs -text
+fixtures/** filter=lfs diff=lfs merge=lfs -text

.github/workflows/performance-regression.yml

@@ -1,5 +1,9 @@
 name: Performance Regression Check
 
+concurrency:
+  group: performance-regression-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 on:
   pull_request:
     paths:
@@ -15,7 +19,7 @@ permissions:
 
 jobs:
   regression:
-    if: github.event_name == 'pull_request'
+    if: github.event_name == 'pull_request' && contains(join(github.event.pull_request.labels.*.name, ','), 'test-regression')
     runs-on: ubuntu-latest
     permissions:
       pull-requests: write
@@ -121,13 +125,14 @@ jobs:
   update-baseline:
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           fetch-depth: 0
-          persist-credentials: false
 
       - name: Setup pnpm
         uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4.1.0

.github/workflows/test.yml

@@ -1,5 +1,9 @@
 name: Test
 
+concurrency:
+  group: test-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
 on:
   push:
     branches: [main]
@@ -47,55 +51,3 @@ jobs:
 
       - name: Build
         run: pnpm build
-
-  benchmark:
-    name: Performance Check
-    runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request'
-    permissions:
-      contents: read
-      pull-requests: write  # Needed to comment on PR
-    steps:
-      - name: Checkout PR
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 #v5.0.0
-        with:
-          persist-credentials: false
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda #v4.1.0
-
-      - name: Setup Node.js
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 #v5.0.0
-        with:
-          node-version: 24
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Build
-        run: pnpm build
-
-      - name: Run benchmark
-        run: node bench/check-regression.js
-
-      - name: Comment PR
-        if: always()
-        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd #v8.0.0
-        with:
-          script: |
-            const fs = require('fs');
-            const path = require('path');
-
-            // Read regression report if it exists
-            const reportPath = path.join(process.cwd(), 'bench', '.results', 'regression-report.md');
-            if (fs.existsSync(reportPath)) {
-              const report = fs.readFileSync(reportPath, 'utf8');
-
-              await github.rest.issues.createComment({
-                issue_number: context.issue.number,
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                body: report
-              });
-            }

.gitignore

@@ -2,9 +2,24 @@ node_modules
 .DS_Store
 dist
 coverage
-.bench
 bench/output
-fixtures/
+bench/artifacts/
+bench/datasets/
+# Local benchmark scratch space
+.bench
+# Ignore volatile benchmark outputs (canonical artifacts are tracked via LFS)
+bench/.results/latest.json
+bench/.results/regression-report.md
+bench/.results/fetch-e2e-latest.json
+bench/.results/workflows-latest.json
+bench/.results/memory-latest.json
+bench/.results/token-usage-latest.json
+bench/.results/bundle-size-*.json
+bench/output/
+bench/Users/
+bench/README-benchmarks.md
+# Allow tracked benchmark results and fixtures (managed via Git LFS)
+# (keep optional local fixture packs elsewhere)
 .vscode
 .idea
 *.log

CONTRIBUTING.md

@@ -11,7 +11,7 @@ Thanks for your interest in improving h2m-parser! Keeping cognitive load low is
 ## Coding standards
 
 - Write TypeScript in `src/` and keep exports explicit in `src/index.ts`.
-- Favor early returns and descriptive helper functions to keep cognitive load low—see `/Users/gustavovalverde/dev/personal/micro-play/cognitive-load.md` for the philosophy behind our style.
+- Favor early returns and descriptive helper functions to keep cognitive load low—see [`cognitive-load.md`](cognitive-load.md) for the philosophy behind our style.
 - Prefer pure functions; when mutating shared state, encapsulate the mutation and document it.
 - Keep custom translators compact—wrap individual tags with clear helpers instead of adding deep inheritance or cross-cutting state.
 - Use Biome for formatting and linting (`pnpm lint:fix`, `pnpm format:fix`).