Add memory benchmarking and arena trimming to reduce waste

[bartveneman]

Summary

This PR adds comprehensive memory diagnostics and optimizes arena memory usage by implementing a trim operation that releases unused pre-allocated capacity after parsing completes.

Key Changes

• Memory Benchmarking Tool (benchmark/memory.ts): New diagnostic script that measures and compares memory usage across Wallace, css-tree, and PostCSS parsers. Supports baseline comparison to detect regressions with configurable thresholds.

• Arena Trimming (src/arena.ts):

  • Added trim() method to shrink the arena buffer to exactly match the number of live nodes, releasing wasted pre-allocated capacity
  • Integrated trim call into parse() to automatically optimize memory after parsing completes
  • Adjusted NODES_PER_KB from 325 to 210 based on real-world measurements across Bootstrap, Tailwind, and custom CSS files
  • Reduced CAPACITY_BUFFER from 1.2 to 1.1 for tighter pre-allocation (effective ceiling: 231 nodes/KB)

• Test Updates (src/arena.test.ts):

  • Added comprehensive tests for the new trim() method covering normal operation, data preservation, and edge cases
  • Updated real-world CSS framework tests to verify zero growth and tight capacity after parsing

• Build Configuration: Added benchmark:memory npm script and updated .gitignore to exclude benchmark results

Implementation Details

The trim operation safely shrinks the ArrayBuffer by copying live data to a new, smaller buffer. It's a no-op when capacity already equals count, making it safe to call multiple times. The memory benchmarking tool uses Node's --expose-gc flag to force garbage collection between measurements, ensuring accurate heap snapshots and enabling regression detection against saved baselines.

https://claude.ai/code/session_01TADcY37pEm5JGh8YJ7UuVQ

[codecov-commenter]

Bundle Report

Changes will increase total bundle size by 1.06kB (0.56%) ⬆️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
@projectwallace/css-parser-esm	191.94kB	1.06kB (0.56%) ⬆️

Affected Assets, Files, and Routes:

view changes for bundle: @projectwallace/css-parser-esm

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
node-types-CdY1J4fH.d.ts (New)	25.17kB	25.17kB	100.0% 🚀
css-node-viJ1-w0x.js (New)	14.88kB	14.88kB	100.0% 🚀
parse.js	21 bytes	9.98kB	0.21%
arena-DM2e0fgL.js (New)	7.87kB	7.87kB	100.0% 🚀
arena-Rkw9tCbD.d.ts (New)	4.75kB	4.75kB	100.0% 🚀
node-types-mntWKkN-.d.ts (Deleted)	-25.17kB	0 bytes	-100.0% 🗑️
css-node-BTgoFWDU.js (Deleted)	-14.88kB	0 bytes	-100.0% 🗑️
arena-DnV0a_Ne.js (Deleted)	-7.2kB	0 bytes	-100.0% 🗑️
arena-CSK5NfHq.d.ts (Deleted)	-4.38kB	0 bytes	-100.0% 🗑️

Files in parse.js:

• ./src/parse.ts → Total Size: 9.54kB

Files in arena-DM2e0fgL.js:

• ./src/arena.ts → Total Size: 7.08kB

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.22%. Comparing base (7a8048d) to head (c0f2d75).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #254      +/-   ##
==========================================
+ Coverage   93.20%   93.22%   +0.01%     
==========================================
  Files          17       17              
  Lines        3062     3071       +9     
  Branches      853      854       +1     
==========================================
+ Hits         2854     2863       +9     
  Misses        208      208              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.