cssgrep 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-07-12
+
+### Added
+- Embedded HTML in JS/TS: files with `.js`/`.mjs`/`.cjs`/`.jsx`/`.ts`/`.mts`/
+  `.cts`/`.tsx` extensions are searched for HTML inside template literals
+  (tagged or not), with locators pointing into the host file — quickfix jumps
+  straight to the match inside `` html`…` ``. `${…}` holes match as
+  whitespace but display as the original source; each literal parses
+  independently, so an unclosed tag in one can't leak into the next. Under
+  `-r`, opt in with `--ext js,ts`. JSX is not extracted (it isn't HTML).
+
+## [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
@@ -125,7 +144,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.4.0...HEAD
+[Unreleased]: https://github.com/msbatarce/cssgrep/compare/v1.6.0...HEAD
+[1.6.0]: https://github.com/msbatarce/cssgrep/compare/v1.5.0...v1.6.0
+[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

package/README.md

@@ -90,7 +90,7 @@ own `line:col` locator (that per-match precision is the point of the tool). A
 | `-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. |
@@ -187,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
@@ -204,6 +204,38 @@ globally to every selector. With `-e`, positional arguments are always file
 paths — like `grep -e`, a mistyped path is reported as unreadable rather than
 re-guessed as a selector.
 
+### Embedded HTML in JS/TS
+
+Modern HTML often lives inside JavaScript. Files with JS/TS extensions
+(`.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts`, `.tsx`) are
+automatically searched for HTML inside **template literals** — lit-html's
+`` html`…` ``, vanilla `` el.innerHTML = `…` ``, nested templates — and
+matches report **host-file locators** that vim's quickfix jumps straight to:
+
+```sh
+$ cssgrep '.price' -n components/card.js
+41:23     <span class="price">${item.price}</span>
+
+$ cssgrep 'img:not([alt])' -rn --ext js,ts,html src/   # audit across both worlds
+```
+
+How it works: every backtick literal whose content looks like markup (`<` +
+letter) is parsed as its own document, with each `${…}` interpolation masked
+to same-length whitespace — so offsets in the fragment *are* offsets in the
+host file, and no position math can drift. Because fragments parse
+independently, an unclosed tag in one literal can never swallow the next.
+Printed lines and `--json`'s `html` field show the *original* source
+(interpolations visible); selector matching, `attribs` and `--text` see holes
+as whitespace, so `class="${cls} card"` matches `.card`, and a tag name
+that's a hole (`<${Tag}>`) never matches. JSX is not extracted — it isn't
+HTML.
+
+With `-r`, JS/TS files are reached by adding their extensions (`--ext
+js,ts`); the default stays `html,htm`. Server-side template files (PHP, ERB,
+Handlebars…) usually need none of this — they're HTML with interruptions, and
+forgiving parsing handles them: `cssgrep '.card' -r --ext php,erb .`. The
+rewrite ops don't apply inside JS/TS files.
+
 ### Watch mode (`--watch`)
 
 `--watch` keeps the search running and re-runs it whenever a watched file

package/cli.js

@@ -4,9 +4,15 @@
 const fs = require('fs');
 const path = require('path');
 const {
-  parse, offsetToPosition, lineTextAt, textOf, collapseWs, ancestor,
+  parse, extractHtmlFragments, lineIndex, offsetToPosition, lineTextAt,
+  textOf, collapseWs, ancestor,
 } = require('./lib.js');
 
+// Files with these extensions are scanned for HTML inside JS/TS template
+// literals instead of being parsed as one HTML document (ROADMAP Phase 12).
+const EMBEDDED_EXTS = new Set(['js', 'mjs', 'cjs', 'jsx', 'ts', 'mts', 'cts', 'tsx']);
+const isEmbeddedPath = p => EMBEDDED_EXTS.has(path.extname(p).slice(1).toLowerCase());
+
 // 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.
@@ -23,7 +29,7 @@ function loadPrettyPrinter() {
 // 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.4.0';
+const VERSION = '1.6.0';
 
 const USAGE = `cssgrep - search HTML by CSS selector, grep-style.
 
@@ -58,7 +64,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.
@@ -109,6 +115,11 @@ value with = or as the next word (--max-width=100, --ext htm).
 Globs (--include/--ignore/--exclude) support *, ** (crosses /), ?, and brace
 alternation like *.{html,htm}.
 
+JS/TS files (.js .mjs .cjs .jsx .ts .mts .cts .tsx) are searched for HTML
+inside template literals: each markup-looking \`...\` is parsed on its own,
+\${...} holes match as whitespace, and locators point into the host file
+(with -r, add the extensions via --ext js,ts). Rewrite ops don't apply there.
+
 Exit status: 0 if any match was found, 1 if none, 2 on error.`;
 
 function fail(msg) {
@@ -541,11 +552,11 @@ function emitContext(src, starts, name, showLabel, targets, opts, out) {
   // 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;
+  for (const { el, base, label: selLabel } of targets) {
+    const off = base + (el.startIndex == null ? 0 : el.startIndex);
     const pos = offsetToPosition(starts, src, off, posState);
     if (info.has(pos.line)) continue;
-    const nodeEnd = (el.endIndex == null ? off : el.endIndex) + 1;
+    const nodeEnd = base + (el.endIndex == null ? off - base : el.endIndex) + 1;
     info.set(pos.line, { off, nodeEnd, pos, selLabel });
   }
 
@@ -585,13 +596,20 @@ function emitContext(src, starts, name, showLabel, targets, opts, out) {
 // `name` is the source's display name (file path, or "(standard input)"); it is
 // used by the aggregate modes (-l/-L/-c). `showLabel` decides whether per-match
 // lines carry a `file:` prefix (only when more than one file is searched).
-function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
+function searchSource(src, name, showLabel, opts, out, limit = Infinity, embedded = false) {
   // The lib owns parsing and selection: one parse per source, then one
   // doc.search() per selector against the same tree. The CLI works on the
   // raw nodes (the match objects' documented escape hatch) because its
   // output modes need node-level access the match shape doesn't model
   // (pretty-printing, ancestor re-targeting, in-line highlight spans).
-  const doc = parse(src);
+  //
+  // A plain HTML file is one fragment covering the whole source (base 0).
+  // An embedded (JS/TS) file contributes one fragment per markup-sniffing
+  // template literal — holes masked to same-length whitespace, so fragment
+  // offsets + base ARE host-file offsets — each parsed as its own document,
+  // so an unclosed tag in one literal can never swallow the next.
+  const docs = (embedded ? extractHtmlFragments(src) : [{ start: 0, masked: src }])
+    .map(f => ({ doc: parse(f.masked), base: f.start }));
   // One record per (selector, matched node): with -e a node matched by two
   // selectors is reported once per selector, tagged with each label, and the
   // merged stream is in document order (same node = same offset, so the
@@ -603,10 +621,12 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
     : [{ label: null, selector: opts.selector }];
   const records = [];
   for (const s of selList) {
-    for (const m of doc.search(s.selector)) records.push({ el: m.node, label: s.label });
+    for (const { doc, base } of docs) {
+      for (const m of doc.search(s.selector)) records.push({ el: m.node, base, label: s.label });
+    }
   }
-  if (selList.length > 1) {
-    records.sort((a, b) => (a.el.startIndex || 0) - (b.el.startIndex || 0));
+  if (selList.length > 1 || docs.length > 1) {
+    records.sort((a, b) => (a.base + (a.el.startIndex || 0)) - (b.base + (b.el.startIndex || 0)));
   }
   const found = records.length;
   // Aggregate modes suppress per-match output entirely.
@@ -630,11 +650,15 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
   // 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
-  // once each. Aggregate modes above operate on the raw matches; targeting
-  // only affects what prints.
+  // Positions are host-file positions: fragments preserve line structure, so
+  // the host source's own line index serves embedded matches directly.
+  const starts = opts.print ? null
+    : embedded ? lineIndex(src)
+    : docs[0].doc.lineStarts();
+  // --parent re-targets matches to ancestors (no-op without it; never leaves
+  // the match's own fragment). Dedup is per (ancestor, label), so two -e
+  // selectors sharing a container still report it once each. Aggregate modes
+  // above operate on the raw matches; targeting only affects what prints.
   let targets = limited;
   if (opts.parent) {
     targets = [];
@@ -645,7 +669,7 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
       if (!labels) { labels = new Set(); seen.set(a, labels); }
       if (!labels.has(r.label)) {
         labels.add(r.label);
-        targets.push({ el: a, label: r.label });
+        targets.push({ el: a, base: r.base, label: r.label });
       }
     }
   }
@@ -668,20 +692,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;
+    for (const { el, base, label: selLabel } of targets) {
+      const off = base + (el.startIndex == null ? 0 : el.startIndex);
       const pos = offsetToPosition(starts, src, off, posState);
-      const nodeEnd = (el.endIndex == null ? off : el.endIndex) + 1;
+      const nodeEnd = base + (el.endIndex == null ? off - base : 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)),
       }));
@@ -695,7 +721,7 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
   // 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) {
+  for (const { el, base, label: selLabel } of targets) {
     const c = opts.colorOn ? paint : (_, s) => s;
     // The [label] tag from -e; a null label (positional selector) prints none.
     const tag = selLabel === null ? '' : c(COLORS.label, `[${selLabel}]`) + ' ';
@@ -708,7 +734,7 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
       emitted++;
       continue;
     }
-    const off = el.startIndex == null ? 0 : el.startIndex;
+    const off = base + (el.startIndex == null ? 0 : el.startIndex);
     const pos = offsetToPosition(starts, src, off, posState);
 
     // Choose the content printed for this match. --attr/--text replace the
@@ -725,7 +751,7 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
         if (seenLines.has(pos.line)) continue;    // this line already printed
         seenLines.add(pos.line);
       }
-      const nodeEnd = (el.endIndex == null ? off : el.endIndex) + 1; // exclusive
+      const nodeEnd = base + (el.endIndex == null ? off - base : el.endIndex) + 1; // exclusive
       text = renderText(pos, off, nodeEnd, opts);
     }
     // grep-style: a `file:` prefix appears with multiple files; the line:col
@@ -1194,7 +1220,7 @@ function searchFiles(opts, files, out) {
       }
       continue;
     }
-    total += searchSource(buf.toString('utf8'), f, showLabel, opts, out, room());
+    total += searchSource(buf.toString('utf8'), f, showLabel, opts, out, room(), isEmbeddedPath(f));
     if (opts.quiet && total > 0) break;   // -q: first match decides the status
   }
   return total;

package/lib.js

@@ -115,6 +115,120 @@ function retarget(nodes, opts) {
   return result;
 }
 
+// --- embedded HTML (JS/TS template literals) -----------------------------------
+
+// Replace every char except line breaks with a space: masked text has the
+// same length AND the same line structure as the original, so offsets and
+// the host file's line index stay valid.
+const maskWs = s => s.replace(/[^\n\r]/g, ' ');
+
+// Skip a '...' or "..." string; `i` is at the opening quote. Returns the
+// index just past the closing quote (or line end / EOF for unterminated).
+function skipJsString(src, i) {
+  const quote = src[i++];
+  while (i < src.length) {
+    const c = src[i];
+    if (c === '\\') { i += 2; continue; }
+    if (c === quote) return i + 1;
+    if (c === '\n') return i;              // unterminated: resync at newline
+    i++;
+  }
+  return i;
+}
+
+// Skip code until the '}' that closes a template hole (depth-balanced),
+// recursing into strings, comments and nested template literals — a nested
+// literal contributes its own fragments. `i` is just past '${'.
+function skipJsCode(src, i, fragments) {
+  let depth = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === "'" || c === '"') { i = skipJsString(src, i); continue; }
+    if (c === '`') { i = readTemplate(src, i, fragments); continue; }
+    if (c === '/' && src[i + 1] === '/') {
+      const nl = src.indexOf('\n', i);
+      if (nl === -1) return src.length;
+      i = nl + 1;
+      continue;
+    }
+    if (c === '/' && src[i + 1] === '*') {
+      const end = src.indexOf('*/', i + 2);
+      if (end === -1) return src.length;
+      i = end + 2;
+      continue;
+    }
+    if (c === '{') depth++;
+    else if (c === '}') {
+      if (depth === 0) return i + 1;
+      depth--;
+    }
+    i++;
+  }
+  return i;
+}
+
+// Read one template literal; `i` is at the opening backtick. Masks every
+// `${…}` hole to same-length whitespace and, when the masked content sniffs
+// as markup (`<` + letter, or `<!`), records it as a fragment. Returns the
+// index just past the closing backtick. Nested literals inside holes are
+// processed first, so their fragments are collected too.
+function readTemplate(src, i, fragments) {
+  const contentStart = ++i;
+  const holes = [];
+  while (i < src.length) {
+    const c = src[i];
+    if (c === '\\') { i += 2; continue; }
+    if (c === '`') break;
+    if (c === '$' && src[i + 1] === '{') {
+      const holeStart = i;
+      i = skipJsCode(src, i + 2, fragments);
+      holes.push([holeStart, i]);
+      continue;
+    }
+    i++;
+  }
+  const contentEnd = Math.min(i, src.length);
+  let masked = src.slice(contentStart, contentEnd);
+  for (const [hs, he] of holes) {
+    const a = hs - contentStart;
+    const b = Math.min(he, contentEnd) - contentStart;
+    masked = masked.slice(0, a) + maskWs(masked.slice(a, b)) + masked.slice(b);
+  }
+  if (/<[a-zA-Z!]/.test(masked)) fragments.push({ start: contentStart, masked });
+  return contentEnd + 1;
+}
+
+// Scan JS/TS source for template literals whose content looks like markup.
+// Returns fragments of { start, masked }: `start` is the host-file offset of
+// the literal's content, `masked` its text with `${…}` holes blanked to
+// same-length whitespace — so every fragment offset IS a host offset.
+// String, template and comment contexts are tracked; regex literals are not
+// (a backtick inside a regex could mislead the scan — rare, and a mislead
+// degrades to "no fragment", never to wrong positions of what is found).
+function extractHtmlFragments(src) {
+  const fragments = [];
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === "'" || c === '"') { i = skipJsString(src, i); continue; }
+    if (c === '`') { i = readTemplate(src, i, fragments); continue; }
+    if (c === '/' && src[i + 1] === '/') {
+      const nl = src.indexOf('\n', i);
+      if (nl === -1) break;
+      i = nl + 1;
+      continue;
+    }
+    if (c === '/' && src[i + 1] === '*') {
+      const end = src.indexOf('*/', i + 2);
+      if (end === -1) break;
+      i = end + 2;
+      continue;
+    }
+    i++;
+  }
+  return fragments;
+}
+
 // --- rewrite machinery --------------------------------------------------------
 
 // Lex one opening tag starting at `start` (which must point at its `<`).
@@ -408,6 +522,7 @@ function parse(html) {
 module.exports = {
   parse,
   // Internal helpers, shared with cli.js; not part of the stable API.
+  extractHtmlFragments,
   lineIndex,
   offsetToPosition,
   lineTextAt,

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.4.0" "User Commands"
+.TH CSSGREP 1 "2026-07-12" "cssgrep 1.6.0" "User Commands"
 .SH NAME
 cssgrep \- search HTML by CSS selector, grep-style
 .SH SYNOPSIS
@@ -159,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
@@ -269,6 +271,28 @@ Globs for
 support
 .BR * " (within a path segment), " ** " (across " / ),
 .BR ? " (one non-slash char), and brace alternation like " *.{html,htm} .
+.SH EMBEDDED HTML
+Files with JS/TS extensions
+.RB ( .js ", " .mjs ", " .cjs ", " .jsx ", " .ts ", " .mts ", " .cts ", " .tsx )
+are searched for HTML inside template literals: every backtick literal whose
+content looks like markup is parsed as its own document, and each
+.RI \(dq${ expr }\(dq
+interpolation is masked to same-length whitespace, so match locators point
+directly into the host file. Printed lines and
+.BR \-\-json 's
+.I html
+field show the original source with interpolations visible; selector
+matching sees holes as whitespace (so
+.I class=\(dq${cls} card\(dq
+matches
+.IR .card ).
+Fragments parse independently \(em an unclosed tag in one literal never
+swallows the next. With
+.BR \-r ,
+add the extensions via
+.BR "\-\-ext js,ts" .
+JSX is not extracted (it is not HTML), and the rewrite operations treat these
+files as plain HTML.
 .SH WATCH MODE
 .TP
 .B \-\-watch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cssgrep",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Search HTML by CSS selector and print matches grep-style (file:line:col with -n).",
   "main": "lib.js",
   "types": "index.d.ts",