cssgrep 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-07-12
+
+### Added
+- `--json` records now include `attribs`, the matched element's attribute
+  object (names lowercased by the parser) — the same field the library's
+  `Match` exposes, so scraping pipelines get attribute data without a second
+  pass (e.g. `jq -r .attribs.href`).
+
+## [1.4.0] - 2026-07-07
+
+### Fixed
+- Large result sets no longer crash with `RangeError: Invalid string length`
+  (exit 1, zero output): output is written in byte-bounded chunks instead of
+  one giant join. Observed with 40k matches on an 8 MB minified line.
+- Emitting many matches on one physical line was quadratic (two O(line)
+  scans per match); the same 40k-locator case dropped from 9.4 s to 0.4 s.
+  Found by the new `npm run bench` harness.
+
+### Changed
+- grep parity: without `-n`, a matching line now prints once, however many
+  matches sit on it. With `-n` there is still one record per match, each
+  with its own `line:col` locator.
+- Startup no longer loads the pretty-printing dependencies unless `-p` is
+  used (43.4 → 37.9 ms measured), and zero-match files skip the line index.
+
 ## [1.3.0] - 2026-07-07
 
 ### Added
@@ -108,7 +133,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `-0`/`--null`, `--color`, `-w`/`--max-width`, `-V`/`--version`.
 - Standalone binaries (Bun, Node SEA), shell completions, and a man page.
 
-[Unreleased]: https://github.com/msbatarce/cssgrep/compare/v1.3.0...HEAD
+[Unreleased]: https://github.com/msbatarce/cssgrep/compare/v1.5.0...HEAD
+[1.5.0]: https://github.com/msbatarce/cssgrep/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/msbatarce/cssgrep/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/msbatarce/cssgrep/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/msbatarce/cssgrep/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/msbatarce/cssgrep/compare/v1.0.0...v1.1.0

package/README.md

@@ -61,9 +61,10 @@ cssgrep <selector> -r <dir ...>    # recurse directories
 cat page.html | cssgrep <selector> # read from stdin
 ```
 
-Output, one line per match. Like `grep`, the matched line is printed on its own;
-a `file:` prefix is added when searching multiple files, and the `line:col`
-locator appears only with `-n`:
+Like `grep`, each matching line is printed on its own, once — however many
+matches sit on it. With `-n` there is one record *per match*, each with its
+own `line:col` locator (that per-match precision is the point of the tool). A
+`file:` prefix is added when searching multiple files:
 
 ```
 {line contents}                         # default; stdin or single file
@@ -89,7 +90,7 @@ locator appears only with `-n`:
 | `-p`, `--print` | Pretty-print the matched node's HTML, re-indented from scratch (works on minified input). No `line:col` locator is shown. |
 | `--attr <name>` | Print the value of attribute `<name>` for each match (nodes without it are skipped; if every match is skipped the exit status is 1). The name is matched case-insensitively. Honors `-n` and `-w`. |
 | `--text` | Print the matched node's text content, whitespace collapsed. Honors `-n` and `-w`. |
-| `--json` | Print one JSON object per match (NDJSON), with `file`, `line`, `col`, `html`, `text` — plus `label` when `-e` is used. |
+| `--json` | Print one JSON object per match (NDJSON), with `file`, `line`, `col`, `attribs` (the element's attributes, names lowercased), `html`, `text` — plus `label` when `-e` is used. |
 | `--parent <n>` | Report the `n`-th element ancestor of each match instead of the match itself (de-duplicated). Pairs well with `-p`. |
 | `-w`, `--max-width <n>` | Truncate the shown line to `n` columns (adds `…`). Value attaches or follows: `-w100`, `-w 100`, `--max-width=100`. |
 | `-A`, `--after-context <n>` | Print `n` source lines after each match. |
@@ -186,8 +187,8 @@ $ cssgrep -n -e 'title=h1' -e 'price=.card .price' page.html
 9:12 [price] <span class="price">$4.99</span>
 
 $ cssgrep --json -e 'title=h1' -e 'price=.card .price' page.html
-{"file":"page.html","line":3,"col":5,"label":"title","html":"<h1>Widget</h1>","text":"Widget"}
-{"file":"page.html","line":9,"col":12,"label":"price","html":"...","text":"$4.99"}
+{"file":"page.html","line":3,"col":5,"label":"title","attribs":{},"html":"<h1>Widget</h1>","text":"Widget"}
+{"file":"page.html","line":9,"col":12,"label":"price","attribs":{"class":"price"},"html":"...","text":"$4.99"}
 ```
 
 The label is anything matching `[A-Za-z_][A-Za-z0-9_-]*` before a `=`; since a

package/cli.js

@@ -3,17 +3,27 @@
 
 const fs = require('fs');
 const path = require('path');
-const render = require('dom-serializer').default;
-const { html: beautify } = require('js-beautify');
 const {
   parse, offsetToPosition, lineTextAt, textOf, collapseWs, ancestor,
 } = require('./lib.js');
 
+// dom-serializer + js-beautify are only needed by -p, and cost ~13 ms of a
+// ~43 ms startup (measured, ROADMAP Phase 11) — loaded on first use so the
+// grepprg-style hot path never pays for them.
+let render = null;
+let beautify = null;
+function loadPrettyPrinter() {
+  if (!render) {
+    render = require('dom-serializer').default;
+    beautify = require('js-beautify').html;
+  }
+}
+
 // Single source of truth for the version. A constant rather than a read of
 // package.json, so it survives compilation into a standalone binary (Bun
 // --compile / Node SEA), where package.json won't sit next to the executable.
 // Keep in sync with package.json on release.
-const VERSION = '1.3.0';
+const VERSION = '1.5.0';
 
 const USAGE = `cssgrep - search HTML by CSS selector, grep-style.
 
@@ -23,7 +33,7 @@ Usage:
   cssgrep -e '[label=]<sel>' [-e ...] [file ...]
   cat file.html | cssgrep <selector>
 
-Output (one line per match):
+Output (each matching line once, like grep; with -n, one record per match):
   {line contents}                           (default; stdin or single file)
   {file}:{line contents}                    (default; multiple files)
   {line}:{col} {line contents}              (with -n; stdin or single file)
@@ -48,7 +58,7 @@ Options:
       --attr <name>      Print the value of attribute <name> (skips nodes without it).
       --text             Print the matched node's text content (whitespace collapsed).
       --json             Print one JSON record per match (NDJSON: file,line,col,
-                         html,text; plus label with -e).
+                         attribs,html,text; plus label with -e).
       --parent <n>       Report the n-th ancestor of each match instead (dedup'd).
   -w, --max-width <n>    Truncate the shown line to <n> columns (ellipsis added).
   -A, --after-context <n>    Print <n> source lines after each match.
@@ -452,6 +462,7 @@ const HL_END = '';
 // highlight) is given and coloring is on, those nodes are wrapped in the match
 // color within the printed block.
 function prettyPrint(el, origins, opts) {
+  loadPrettyPrinter();
   const highlight = origins && origins.length && opts && opts.colorOn;
   const inserted = [];
   if (highlight) {
@@ -529,9 +540,10 @@ function emitContext(src, starts, name, showLabel, targets, opts, out) {
   // Map each match line to a representative node span (the first match on it),
   // which drives the in-line highlight — and the [label] tag — when emitting.
   const info = new Map();
+  const posState = {};
   for (const { el, label: selLabel } of targets) {
     const off = el.startIndex == null ? 0 : el.startIndex;
-    const pos = offsetToPosition(starts, src, off);
+    const pos = offsetToPosition(starts, src, off, posState);
     if (info.has(pos.line)) continue;
     const nodeEnd = (el.endIndex == null ? off : el.endIndex) + 1;
     info.set(pos.line, { off, nodeEnd, pos, selLabel });
@@ -615,6 +627,9 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
     out.push(label ? `${label}${fileSep}${limited.length}` : String(limited.length));
     return limited.length;
   }
+  // Nothing to emit: return before building the line index — a zero-match
+  // pass over a large file shouldn't pay a full line scan for nothing.
+  if (limited.length === 0) return 0;
   const starts = opts.print ? null : doc.lineStarts();
   // --parent re-targets matches to ancestors (no-op without it). Dedup is per
   // (ancestor, label), so two -e selectors sharing a container still report it
@@ -653,19 +668,22 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
   // matches lacking the attribute, and --parent dedup can merge several
   // matches into one printed ancestor.
   if (opts.json) {
-    // NDJSON: one self-contained record per match. `html` is the exact source
-    // slice; newlines are escaped by JSON.stringify, so each record stays on
-    // one line. Ignores --color and -n (line/col are always present). `label`
-    // appears only with -e.
+    // NDJSON: one self-contained record per match. `attribs` mirrors the lib
+    // Match's field (names lowercased by the parser) so scraping never needs
+    // a second pass; `html` is the exact source slice; newlines are escaped
+    // by JSON.stringify, so each record stays on one line. Ignores --color
+    // and -n (line/col are always present). `label` appears only with -e.
+    const posState = {};
     for (const { el, label: selLabel } of targets) {
       const off = el.startIndex == null ? 0 : el.startIndex;
-      const pos = offsetToPosition(starts, src, off);
+      const pos = offsetToPosition(starts, src, off, posState);
       const nodeEnd = (el.endIndex == null ? off : el.endIndex) + 1;
       out.push(JSON.stringify({
         file: name,
         line: pos.line,
         col: pos.bcol,
         ...(selLabel !== null && { label: selLabel }),
+        attribs: el.attribs || {},
         html: src.slice(off, nodeEnd),
         text: collapseWs(textOf(el)),
       }));
@@ -673,6 +691,12 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
     return targets.length;
   }
   let emitted = 0;
+  // grep parity: without -n, a physical line prints once no matter how many
+  // matches sit on it (grep never repeats a line). With -n each match keeps
+  // its own line:col record — that per-match locator is the tool's point.
+  // Extraction modes print per-match values, so they never dedup.
+  const seenLines = (opts.lineNumber || opts.attr != null || opts.text) ? null : new Set();
+  const posState = {};
   for (const { el, label: selLabel } of targets) {
     const c = opts.colorOn ? paint : (_, s) => s;
     // The [label] tag from -e; a null label (positional selector) prints none.
@@ -687,7 +711,7 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
       continue;
     }
     const off = el.startIndex == null ? 0 : el.startIndex;
-    const pos = offsetToPosition(starts, src, off);
+    const pos = offsetToPosition(starts, src, off, posState);
 
     // Choose the content printed for this match. --attr/--text replace the
     // source line with the extracted value (whole value highlighted as the
@@ -699,6 +723,10 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
     } else if (opts.text) {
       text = c(COLORS.match, truncate(collapseWs(textOf(el)), opts.maxWidth));
     } else {
+      if (seenLines) {
+        if (seenLines.has(pos.line)) continue;    // this line already printed
+        seenLines.add(pos.line);
+      }
       const nodeEnd = (el.endIndex == null ? off : el.endIndex) + 1; // exclusive
       text = renderText(pos, off, nodeEnd, opts);
     }
@@ -1225,11 +1253,29 @@ function main() {
     // For -l/-L, -0 NUL-terminates each file name (no newline) so the list is
     // safe for `xargs -0`. Other modes keep newline-separated records (with -0
     // the NUL appears only as the in-record file-name separator).
-    if (opts.nul && (opts.filesWithMatches || opts.filesWithoutMatch)) {
-      process.stdout.write(out.map(s => s + '\0').join(''));
-    } else {
-      process.stdout.write(out.join('\n') + '\n');
+    //
+    // Written in byte-bounded chunks, never as one join of everything: with
+    // enough (or long enough) result lines a single joined string exceeds
+    // V8's maximum string length and crashes — observed with 40k matches on
+    // an 8 MB minified line. Writes queue; process.exitCode (not exit())
+    // keeps them flush-safe.
+    const nulList = opts.nul && (opts.filesWithMatches || opts.filesWithoutMatch);
+    const CHUNK_BYTES = 32 << 20;             // ~32 MB per write
+    let batch = [];
+    let bytes = 0;
+    const flush = () => {
+      if (!batch.length) return;
+      process.stdout.write(nulList ? batch.map(s => s + '\0').join('')
+        : batch.join('\n') + '\n');
+      batch = [];
+      bytes = 0;
+    };
+    for (const line of out) {
+      batch.push(line);
+      bytes += line.length + 1;
+      if (bytes >= CHUNK_BYTES) flush();
     }
+    flush();
   }
   // Normally success means "a match was found". With -L it means "a file
   // without a match was printed", which is decoupled from the match total.

package/lib.js

@@ -26,7 +26,7 @@ function lineIndex(src) {
   return starts;
 }
 
-function offsetToPosition(starts, src, offset) {
+function offsetToPosition(starts, src, offset, state) {
   // binary search for the greatest line start <= offset
   let lo = 0, hi = starts.length - 1;
   while (lo < hi) {
@@ -35,11 +35,27 @@ function offsetToPosition(starts, src, offset) {
     else hi = mid - 1;
   }
   const lineStart = starts[lo];
-  let lineEnd = src.indexOf('\n', lineStart);
-  if (lineEnd === -1) lineEnd = src.length;
+  // The next line's start bounds this line (O(1)); an indexOf scan here is
+  // O(line length) *per match* — quadratic on minified single-line files.
+  const lineEnd = lo + 1 < starts.length ? starts[lo + 1] - 1 : src.length;
   // strip a trailing \r so CRLF files render cleanly
   let text = src.slice(lineStart, lineEnd);
   if (text.endsWith('\r')) text = text.slice(0, -1);
+  // bcol counts bytes from the line start — also quadratic if recomputed per
+  // match. `state` (one mutable object per source, supplied by the caller)
+  // remembers the previous match's byte count, so in-order matches on the
+  // same line pay only the delta; out-of-order falls back to a full count.
+  let bytes;
+  if (state && state.lineStart === lineStart && offset >= state.offset) {
+    bytes = state.bytes + Buffer.byteLength(src.slice(state.offset, offset), 'utf8');
+  } else {
+    bytes = Buffer.byteLength(src.slice(lineStart, offset), 'utf8');
+  }
+  if (state) {
+    state.lineStart = lineStart;
+    state.offset = offset;
+    state.bytes = bytes;
+  }
   return {
     line: lo + 1,            // 1-based
     // col in UTF-16 code units: a JS string index into `text`, used by the
@@ -47,7 +63,7 @@ function offsetToPosition(starts, src, offset) {
     // and terminals count bytes, so non-ASCII text before the match would
     // otherwise land the cursor short.
     col: offset - lineStart + 1, // 1-based
-    bcol: Buffer.byteLength(src.slice(lineStart, offset), 'utf8') + 1, // 1-based
+    bcol: bytes + 1,             // 1-based
     text,
   };
 }
@@ -56,8 +72,7 @@ function offsetToPosition(starts, src, offset) {
 // line's byte start (so a node's offset maps to a column within it).
 function lineTextAt(starts, src, lineNo) {
   const lineStart = starts[lineNo - 1];
-  let lineEnd = src.indexOf('\n', lineStart);
-  if (lineEnd === -1) lineEnd = src.length;
+  const lineEnd = lineNo < starts.length ? starts[lineNo] - 1 : src.length;
   let text = src.slice(lineStart, lineEnd);
   if (text.endsWith('\r')) text = text.slice(0, -1);
   return { lineStart, text };
@@ -296,7 +311,8 @@ function parse(html) {
   });
   let starts = null;
   const lineStarts = () => starts || (starts = lineIndex(html));
-  const position = offset => offsetToPosition(lineStarts(), html, offset);
+  const posState = {};   // incremental byte-column cache, scoped to this doc
+  const position = offset => offsetToPosition(lineStarts(), html, offset, posState);
   return {
     html,
     // Internal (unstable): the raw htmlparser2 document and the cached

package/man/cssgrep.1

@@ -1,6 +1,6 @@
 .\" Man page for cssgrep. Keep the OPTIONS section in sync with the USAGE
 .\" string in cli.js.
-.TH CSSGREP 1 "2026-07-07" "cssgrep 1.3.0" "User Commands"
+.TH CSSGREP 1 "2026-07-12" "cssgrep 1.5.0" "User Commands"
 .SH NAME
 cssgrep \- search HTML by CSS selector, grep-style
 .SH SYNOPSIS
@@ -46,15 +46,16 @@ skipped with a note on standard error, suppressible with
 .B \-s
 or
 .BR \-q .
-One line is printed per match.
 As with
 .BR grep ,
-the matched line is printed on its own; a
+each matching line is printed on its own, once \(em however many matches sit
+on it. With
+.B \-n
+there is one record per
+.IR match ,
+each with its own locator. A
 .RI " file :"
-prefix is added when searching multiple files, and the
-.IR line : col
-locator appears only with
-.BR \-n .
+prefix is added when searching multiple files.
 .SH OPTIONS
 .TP
 .BR \-e ", " \-\-selector " [\fIlabel\fR=]\fIsel\fR"
@@ -158,11 +159,13 @@ Print the matched node's text content, whitespace collapsed.
 .TP
 .B \-\-json
 Print one JSON object per match (NDJSON) with
-.IR file ", " line ", " col ", " html ", " text
+.IR file ", " line ", " col ", " attribs ", " html ", " text
 (plus
 .I label
 with
 .BR \-e ).
+.I attribs
+is the element's attribute object, names lowercased by the parser.
 .TP
 .BI \-\-parent " n"
 Report the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cssgrep",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Search HTML by CSS selector and print matches grep-style (file:line:col with -n).",
   "main": "lib.js",
   "types": "index.d.ts",
@@ -37,7 +37,8 @@
     "build:darwin-arm64": "bun build ./cli.js --compile --target=bun-darwin-arm64 --outfile dist/cssgrep-darwin-arm64",
     "build:windows-x64": "bun build ./cli.js --compile --target=bun-windows-x64 --outfile dist/cssgrep-windows-x64.exe",
     "build:binaries": "npm run build:linux-x64 && npm run build:linux-arm64 && npm run build:darwin-x64 && npm run build:darwin-arm64 && npm run build:windows-x64",
-    "build:sea": "node scripts/build-sea.js"
+    "build:sea": "node scripts/build-sea.js",
+    "bench": "node bench/bench.js"
   },
   "keywords": [
     "css",