fix: resolve formatting issues, maintainer workflows and build size (#4)

* fix: resolve formatting issues, maintainer workflows and build size

- Fix double blank lines (MD012) by removing ensureTrailingBlankLine() from block elements
- Fix spaces in link text (MD039) by trimming leading/trailing whitespace
- Fix reference link spacing in markdown output
- Add high-frequency maintenance scripts for QA and regression testing
- Consolidate documentation by merging MAINTAINERS.md into CONTRIBUTING.md
- Streamline README.md development section for clarity
- Move packages from `dependencies` to `devDependencies`

These changes improve markdown output quality (85% fewer linting issues vs competitors), reduce package size by 82%, and provide maintainers with workflows for validation and testing.

* chore: update changesets

* fix(ci): reorder node setup jobs for regression tests

* fix(build): sync lockfile

* fix(ci): do not fail with external libraries regressions

* fix(biome): expand scope to `bench/` files

Author: gustavovalverde

.changeset/clever-zoos-judge.md

@@ -0,0 +1,16 @@
+---
+"h2m-parser": minor
+---
+
+Optimize package size and update Node.js requirements
+
+- Reduce npm package size by 82% (570KB → 103KB) by excluding source maps and enabling minification
+- Remove unused `turndown` dependency, moving it to devDependencies for benchmarks only
+- Update Node.js requirement to >=22 and test matrix to Node 22 and 24
+- Fix tsup config TypeScript error in esbuildOptions
+- Update all GitHub Actions workflows to use Node.js 24
+- Configure package.json to exclude source maps from published package
+- Enable minification in production builds while keeping it disabled for watch mode
+
+These changes improve installation speed and reduce disk usage for end users while
+maintaining full functionality.

.github/workflows/performance-regression.yml

@@ -17,26 +17,26 @@ jobs:
   regression:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      issues: write
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
         with:
           persist-credentials: false
 
-      - name: Setup Node.js
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
-        with:
-          node-version: '24'
-
-      - name: Enable Corepack
-        run: corepack enable
-
       - name: Setup pnpm
         uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4.1.0
         with:
           run_install: false
 
+      - name: Setup Node.js
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        with:
+          node-version: '24'
+
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
@@ -66,7 +66,7 @@ jobs:
           if-no-files-found: ignore
 
       - name: Comment PR with results
-        if: always()
+        if: always() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false
         uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         with:
           script: |
@@ -129,19 +129,16 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
 
-      - name: Setup Node.js
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
-        with:
-          node-version: '24'
-
-      - name: Enable Corepack
-        run: corepack enable
-
       - name: Setup pnpm
         uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4.1.0
         with:
           run_install: false
 
+      - name: Setup Node.js
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5.0.0
+        with:
+          node-version: '24'
+
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 

.markdownlint.json

@@ -0,0 +1,17 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD033": false,
+  "MD041": false,
+  "MD024": {
+    "siblings_only": true
+  },
+  "MD026": {
+    "punctuation": ".,;:!"
+  },
+  "MD029": {
+    "style": "ordered"
+  },
+  "MD036": false,
+  "MD045": false
+}

CONTRIBUTING.md

@@ -38,3 +38,167 @@ Open GitHub issues with:
 - Does new configuration default to sensible values to minimize user surprise?
 
 Thanks for helping keep h2m-parser simple and reliable!
+
+## Maintainer Scripts
+
+### High-Frequency Commands
+
+```bash
+# Quick quality checks (10 seconds)
+pnpm qa:quick
+
+# Full regression test (30 seconds)
+pnpm regression
+
+# Complete QA with validation (2-3 minutes)
+pnpm qa
+
+# Development watch mode
+pnpm build:watch    # Terminal 1
+pnpm test:watch     # Terminal 2
+```
+
+### Script Reference
+
+#### Quality Assurance
+
+| Script | Purpose | Duration | When to Use |
+|--------|---------|----------|-------------|
+| `pnpm qa:quick` | Quick validation: lint, types, tests, export | ~10s | Before commits |
+| `pnpm qa` | Full QA with markdown validation | ~2-3min | Before PRs |
+| `pnpm regression` | Basic regression test | ~30s | After changes |
+| `pnpm regression:full` | Complete regression suite | ~1-2min | Before releases |
+
+#### Benchmarking
+
+| Script | Purpose | Duration | When to Use |
+|--------|---------|----------|-------------|
+| `pnpm bench:quick` | Quick performance check | ~5s | During development |
+| `pnpm bench:compare:quick` | Fast comparison with competitors | ~10s | After optimizations |
+| `pnpm bench:compare` | Full comparison benchmark | ~2min | Before releases |
+| `pnpm bench:profile` | Detailed performance profiling | ~30s | Performance debugging |
+| `pnpm bench:analyze` | Pipeline analysis | ~30s | Optimization work |
+
+#### Output Generation
+
+| Script | Purpose | Duration | When to Use |
+|--------|---------|----------|-------------|
+| `pnpm bench:export` | Generate markdown outputs | ~5s | Testing conversions |
+| `pnpm bench:export:validate` | Export + validate with markdownlint | ~10s | Quality checks |
+| `pnpm bench:readme:generate` | Generate all benchmark reports | ~3min | Before releases |
+
+### Typical Workflows
+
+#### Making Changes
+
+```bash
+# Start development
+pnpm build:watch     # In terminal 1
+pnpm test:watch     # In terminal 2
+
+# After making changes
+pnpm qa:quick       # Quick validation
+pnpm bench:export   # Check output quality
+```
+
+#### Before Committing
+
+```bash
+# Standard pre-commit check
+pnpm regression
+
+# Or if you want to be thorough
+pnpm qa
+```
+
+#### Performance Work
+
+```bash
+# Before optimization
+pnpm bench:compare:quick > before.txt
+
+# After optimization
+pnpm bench:compare:quick > after.txt
+
+# Detailed analysis
+pnpm bench:profile
+pnpm bench:analyze
+```
+
+#### Release Preparation
+
+```bash
+# Full validation
+pnpm regression:full
+
+# Generate all reports
+pnpm bench:readme:generate
+
+# Update changelog
+pnpm changeset
+
+# Release
+pnpm release
+```
+
+## Output Validation
+
+The `bench/output/` directory contains markdown outputs from different converters:
+
+- `bench/output/h2m-parser/` - Our outputs
+- `bench/output/turndown/` - Turndown outputs
+- `bench/output/node-html-markdown/` - node-html-markdown outputs
+
+To validate output quality:
+
+```bash
+# Generate fresh outputs and validate
+pnpm bench:export:validate
+
+# Check specific issues
+npx markdownlint bench/output/h2m-parser/*.md
+
+# Compare with competitors
+npx markdownlint bench/output/*/*.md 2>&1 | grep -c "^bench"
+```
+
+## Performance Baselines
+
+Current performance targets (from benchmarks):
+
+- **Without Readability**: ~1-3ms for typical web pages
+- **With Readability**: ~5-10ms for typical web pages
+- **vs Turndown**: Should be within 1-2x
+- **vs node-html-markdown**: Should be competitive or faster
+
+## Troubleshooting
+
+### Tests Failing
+
+```bash
+# Run specific test
+pnpm test -- htmlparser2-default-tags.test.ts
+
+# Update snapshots if needed
+pnpm test -- -u
+```
+
+### Performance Regression
+
+```bash
+# Quick comparison
+pnpm bench:compare:quick
+
+# Detailed profiling
+node --expose-gc bench/profile.js --memory
+```
+
+### Markdown Quality Issues
+
+```bash
+# Check specific file
+npx markdownlint bench/output/h2m-parser/[filename].md
+
+# See all issues
+pnpm bench:export:validate
+```

README.md

@@ -154,7 +154,6 @@ Estimated processing times for different file sizes (without Readability):
 
 Sample results showing performance across different file types and sizes:
 
-
 #### tiny (18 bytes)
 
 | Library | Mean (ms) | P95 (ms) | P99 (ms) |
@@ -248,37 +247,21 @@ pnpm bench:readme
 
 <!-- BENCHMARK:END -->
 
-## Tooling & scripts
-
-| Command | Description |
-|---------|-------------|
-| `pnpm verify` | Run lint → typecheck → tests in one go. |
-| `pnpm bench` | Interactive benchmark runner (profiles, comparisons, regression tools). |
-| `node bench/capture-baseline.js` | Snapshot current performance metrics for future comparisons. |
-| `node bench/check-regression.js --exit-on-regression` | Compare against the stored baseline and fail on regressions. |
-| `pnpm export:markdown` | Dump Markdown outputs for h2m-parser, Turndown, and node-html-markdown. |
-| `pnpm changeset` / `pnpm release` | Prepare and publish releases. |
-
-More detail lives in [`docs/SCRIPTS.md`](docs/SCRIPTS.md).
-
 ## Development
 
 ```bash
 pnpm install
 pnpm verify
 ```
 
-- `pnpm build` – tsup bundles (CJS+ESM+types).
-- `pnpm test` / `pnpm test:watch` – Vitest suites.
-- `pnpm lint` / `pnpm lint:fix` – Biome checks.
-- `pnpm typecheck` – `tsc --noEmit`.
-- `pnpm bench:quick` – sanity benchmark (25 files max).
-
-See [`docs/PERFORMANCE-REGRESSION.md`](docs/PERFORMANCE-REGRESSION.md) for the baseline/CI story, and [`docs/API.md`](docs/API.md) for generated API notes.
-
 ## Contributing
 
-We welcome improvements! Start with [CONTRIBUTING.md](CONTRIBUTING.md) for coding standards, commit conventions, and release flow.
+We welcome improvements! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
+
+- Development setup and coding standards
+- Commit conventions and release workflow
+- Maintainer scripts and workflows
+- Performance baselines and troubleshooting
 
 ## License