cssgrep 1.1.0 → 1.3.0

package/{index.js → cli.js}

@@ -3,22 +3,24 @@
 
 const fs = require('fs');
 const path = require('path');
-const { parseDocument } = require('htmlparser2');
-const { selectAll } = require('css-select');
 const render = require('dom-serializer').default;
 const { html: beautify } = require('js-beautify');
+const {
+  parse, offsetToPosition, lineTextAt, textOf, collapseWs, ancestor,
+} = require('./lib.js');
 
 // 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.1.0';
+const VERSION = '1.3.0';
 
 const USAGE = `cssgrep - search HTML by CSS selector, grep-style.
 
 Usage:
   cssgrep <selector> [file ...]
   cssgrep <selector> -r <dir ...>
+  cssgrep -e '[label=]<sel>' [-e ...] [file ...]
   cat file.html | cssgrep <selector>
 
 Output (one line per match):
@@ -28,6 +30,10 @@ Output (one line per match):
   {file}:{line}:{col} {line contents}       (with -n; multiple files)
 
 Options:
+  -e, --selector <[label=]sel>   Add a selector (repeatable). Matches from all
+                         -e selectors merge in document order; each is tagged
+                         [label] (default label: the selector text itself).
+                         With -e, every positional argument is a file path.
   -r, --recursive        Recurse into directory arguments.
       --max-depth <n>    Limit -r recursion depth (1 = the given dir only).
       --ext <list>       Comma-separated extensions for -r (default: html,htm).
@@ -35,11 +41,14 @@ Options:
   -i, --ignore <glob>    Skip files/dirs matching <glob> when recursing (repeatable).
       --exclude <glob>   Alias for --ignore.
       --ignore-file <path>   Read ignore globs from <path> (one per line, # comments).
+  -S, --follow           Follow symbolic links when recursing with -r
+                         (default: skip them; loops are detected).
   -n, --line-number      Prefix each match with its line:col (excludes -c, -p).
   -p, --print            Pretty-print the matched node's HTML above its location.
       --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).
+      --json             Print one JSON record per match (NDJSON: file,line,col,
+                         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.
@@ -47,7 +56,8 @@ Options:
   -C, --context <n>          Print <n> source lines before and after each match.
   -m, --max-count <n>    Stop after <n> matches per file.
   -M, --max-total <n>    Stop after <n> matches in total (across all files).
-  -c, --count            Print only a count of matches (per file when relevant).
+  -c, --count            Print only a count of matches (per file when
+                         relevant, zeros included, like grep).
   -l, --files-with-matches   Print only the names of files that have a match.
   -L, --files-without-match  Print only the names of files with no match.
   -q, --quiet            Print nothing; exit 0 on first match, 1 if none.
@@ -55,10 +65,33 @@ Options:
   -0, --null             Separate the file name with a NUL byte (for xargs -0).
   -H, --with-filename    Always print the file name prefix (even for one file).
       --no-filename      Never print the file name prefix (even for many files).
-      --color[=<when>]   Colorize output: auto (default), always or never.
+      --color[=<when>]   Colorize output: auto (default, also what a bare
+                         --color means, like grep), always or never.
+      --watch            Re-run the search whenever a watched file changes
+                         (requires paths; excludes -q and the rewrite ops).
+                         On a TTY the screen is cleared and results reprinted;
+                         piped output appends each run after a == HH:MM:SS ==
+                         separator; with --json each run emits an NDJSON
+                         {"event":"run",...} record followed by the matches.
+                         Exit with Ctrl-C (status 0).
+      --no-clear         With --watch on a TTY: append instead of clearing.
   -h, --help             Show this help.
   -V, --version          Show version and exit.
 
+Rewrite (a separate mode: excludes -n/-p/--attr/--text/--json, -c/-l/-L/-q,
+-A/-B/-C, -m/-M, -w, -0 and -e; composes with --parent):
+      --add-class <c>    Add a class to each matched element.
+      --remove-class <c> Remove a class (attribute dropped when emptied).
+      --set-attr <k=v>   Set attribute k to v (added if missing).
+      --remove-attr <k>  Remove attribute k.
+      --rename-tag <t>   Rename the element (and its closing tag, if present).
+      --diff             Emit a unified diff instead of the document; required
+                         for multiple files. Apply with git apply / patch.
+
+A single input prints the rewritten document to stdout. Only the matched tags'
+bytes change; ops compose as rename -> remove-attr -> set-attr -> remove-class
+-> add-class regardless of argument order. Exit: 0 edits, 1 none, 2 error.
+
 Short flags combine (-rn) and a value attaches to its flag (-w100) or follows it
 (-w 100); a value-taking flag may close a cluster (-rnw100). Long options take a
 value with = or as the next word (--max-width=100, --ext htm).
@@ -73,13 +106,22 @@ function fail(msg) {
   process.exit(2);
 }
 
+// grep's most predictable stumble: there is no invert-match here, because CSS
+// expresses inversion in the selector itself. Teach instead of just rejecting.
+function failInvert(flag) {
+  fail(`${flag}: there is no invert-match — CSS expresses inversion in the ` +
+    `selector, e.g. 'img:not([alt])' or 'div:not(:has(a))'; see man cssgrep`);
+}
+
 // ANSI SGR codes matching grep's default scheme: bold-red match, magenta
-// filename, green line/col numbers, cyan separators.
+// filename, green line/col numbers, cyan separators. The [label] tag from -e
+// has no grep counterpart; yellow keeps it distinct from all of the above.
 const COLORS = {
   match: '1;31',
   file: '35',
   line: '32',
   sep: '36',
+  label: '33',
 };
 
 function paint(code, str) {
@@ -89,9 +131,11 @@ function paint(code, str) {
 function parseArgs(argv) {
   const opts = {
     selector: null,
+    selectors: [],
     positionals: [],
     paths: [],
     recursive: false,
+    follow: false,
     exts: ['html', 'htm'],
     extGiven: false,
     maxDepth: 0,
@@ -117,6 +161,10 @@ function parseArgs(argv) {
     noFilename: false,
     noMessages: false,
     color: 'auto',
+    rewrite: { renameTag: null, removeAttr: [], setAttr: {}, removeClass: [], addClass: [] },
+    diff: false,
+    watch: false,
+    noClear: false,
   };
   const setExts = v => {
     opts.extGiven = true;
@@ -136,6 +184,16 @@ function parseArgs(argv) {
   const setAfter = v => { opts.after = boundedInt(v, '--after-context', 0); };
   const setBefore = v => { opts.before = boundedInt(v, '--before-context', 0); };
   const setContext = v => { opts.after = opts.before = boundedInt(v, '--context', 0); };
+  // -e [label=]<selector>. A `=` outside brackets never begins a *working*
+  // selector (css-what tokenizes `a=b` as an unmatchable tag named `=b`), so a
+  // leading identifier + `=` is unambiguously a label. Unlabeled selectors are
+  // tagged with their own text, so [label] and the --json `label` field are
+  // always present when -e is used.
+  const addSelector = v => {
+    const m = /^([A-Za-z_][A-Za-z0-9_-]*)=([\s\S]+)$/.exec(v);
+    if (m) opts.selectors.push({ label: m[1], selector: m[2] });
+    else opts.selectors.push({ label: v, selector: v });
+  };
   const addIgnore = v => { const c = compileIgnore(v); if (c) opts.ignore.push(c); };
   const addInclude = v => { const c = compileIgnore(v); if (c) opts.include.push(c); };
   const addIgnoreFile = v => {
@@ -147,22 +205,28 @@ function parseArgs(argv) {
   // Short flags that take a value (rest of the cluster, or the next argument).
   const shortValueFlags = {
     w: setMaxWidth, m: setMaxCount, M: setMaxTotal, A: setAfter, B: setBefore, C: setContext,
-    i: addIgnore,
+    i: addIgnore, e: addSelector,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
 
     // Long options: --name or --name=value. A missing inline value is taken
-    // from the next argument (except --color, where a bare flag means "always").
+    // from the next argument (except --color, where a bare flag means "auto",
+    // as in GNU grep).
     if (a.startsWith('--') && a.length > 2) {
       const eq = a.indexOf('=');
       const name = eq === -1 ? a : a.slice(0, eq);
       const inline = eq === -1 ? null : a.slice(eq + 1);
-      const value = () => (inline != null ? inline : argv[++i]);
+      const value = () => {
+        if (inline != null) return inline;
+        if (i + 1 >= argv.length) fail(`option ${name} requires a value`);
+        return argv[++i];
+      };
       switch (name) {
         case '--help': process.stdout.write(USAGE + '\n'); process.exit(0); break;
         case '--version': process.stdout.write(`cssgrep ${VERSION}\n`); process.exit(0); break;
         case '--recursive': opts.recursive = true; break;
+        case '--follow': opts.follow = true; break;
         case '--line-number': opts.lineNumber = true; break;
         case '--print': opts.print = true; break;
         case '--count': opts.count = true; break;
@@ -181,14 +245,32 @@ function parseArgs(argv) {
         case '--max-count': setMaxCount(value()); break;
         case '--max-total': setMaxTotal(value()); break;
         case '--max-depth': setMaxDepth(value()); break;
-        case '--attr': opts.attr = value(); break;
+        // htmlparser2 lowercases HTML attribute names, so match case-insensitively.
+        case '--attr': opts.attr = value().toLowerCase(); break;
         case '--text': opts.text = true; break;
         case '--json': opts.json = true; break;
         case '--parent': setParent(value()); break;
         case '--after-context': setAfter(value()); break;
         case '--before-context': setBefore(value()); break;
         case '--context': setContext(value()); break;
-        case '--color': case '--colour': opts.color = inline != null ? inline : 'always'; break;
+        case '--color': case '--colour': opts.color = inline != null ? inline : 'auto'; break;
+        case '--selector': addSelector(value()); break;
+        case '--add-class': opts.rewrite.addClass.push(value()); break;
+        case '--remove-class': opts.rewrite.removeClass.push(value()); break;
+        case '--remove-attr': opts.rewrite.removeAttr.push(value()); break;
+        case '--set-attr': {
+          const v = value();
+          const eq = v.indexOf('=');
+          const k = eq === -1 ? v : v.slice(0, eq);
+          if (!k) fail('--set-attr requires a name (name=value)');
+          opts.rewrite.setAttr[k] = eq === -1 ? '' : v.slice(eq + 1);
+          break;
+        }
+        case '--rename-tag': opts.rewrite.renameTag = value(); break;
+        case '--diff': opts.diff = true; break;
+        case '--watch': opts.watch = true; break;
+        case '--no-clear': opts.noClear = true; break;
+        case '--invert-match': failInvert(name); break;
         default: fail(`unknown option: ${name}`);
       }
       continue;
@@ -202,6 +284,7 @@ function parseArgs(argv) {
         const ch = a[j];
         if (shortValueFlags[ch]) {
           const rest = a.slice(j + 1);          // attached value, if any
+          if (rest === '' && i + 1 >= argv.length) fail(`option -${ch} requires a value`);
           shortValueFlags[ch](rest !== '' ? rest : argv[++i]);
           break;                                // value swallowed the cluster tail
         }
@@ -209,6 +292,7 @@ function parseArgs(argv) {
           case 'h': process.stdout.write(USAGE + '\n'); process.exit(0); break;
           case 'V': process.stdout.write(`cssgrep ${VERSION}\n`); process.exit(0); break;
           case 'r': opts.recursive = true; break;
+          case 'S': opts.follow = true; break;
           case 'n': opts.lineNumber = true; break;
           case 'p': opts.print = true; break;
           case 'c': opts.count = true; break;
@@ -218,6 +302,7 @@ function parseArgs(argv) {
           case '0': case 'Z': opts.nul = true; break;
           case 'H': opts.withFilename = true; break;
           case 's': opts.noMessages = true; break;
+          case 'v': failInvert('-v'); break;
           default: fail(`unknown option: -${ch}`);
         }
       }
@@ -226,7 +311,9 @@ function parseArgs(argv) {
 
     opts.positionals.push(a);
   }
-  if (opts.positionals.length === 0) fail('no selector given (try --help)');
+  if (opts.positionals.length === 0 && !opts.selectors.length) {
+    fail('no selector given (try --help)');
+  }
   // Aggregate modes each suppress per-match output, so at most one may apply.
   const aggregates = [opts.count, opts.filesWithMatches, opts.filesWithoutMatch, opts.quiet]
     .filter(Boolean).length;
@@ -246,6 +333,34 @@ function parseArgs(argv) {
   }
   if (opts.lineNumber && opts.count) fail('-n cannot be combined with -c');
   if (opts.lineNumber && opts.print) fail('-n cannot be combined with -p');
+  // Rewrite is its own program mode, not a fourth output axis: it emits a
+  // document (or a diff), so everything that shapes per-match output is
+  // meaningless with it.
+  const r = opts.rewrite;
+  opts.rewriteActive = Boolean(r.renameTag) || r.removeAttr.length > 0
+    || r.removeClass.length > 0 || r.addClass.length > 0
+    || Object.keys(r.setAttr).length > 0;
+  if (opts.diff && !opts.rewriteActive) fail('--diff requires a rewrite operation');
+  if (opts.rewriteActive) {
+    if (printModes > 0) fail('rewrite operations cannot be combined with -p/--attr/--text/--json');
+    if (aggregates > 0) fail('rewrite operations cannot be combined with -c/-l/-L/-q');
+    if (opts.before > 0 || opts.after > 0) fail('rewrite operations cannot be combined with -A/-B/-C');
+    if (opts.lineNumber) fail('rewrite operations cannot be combined with -n');
+    if (opts.maxWidth) fail('rewrite operations cannot be combined with -w');
+    if (opts.nul) fail('rewrite operations cannot be combined with -0');
+    if (opts.maxCount || opts.maxTotal) fail('rewrite operations cannot be combined with -m/-M');
+    if (opts.selectors.length) {
+      fail('rewrite takes a single positional selector (use a selector list like "a, b" instead of -e)');
+    }
+  }
+  // Watch re-runs the search on change; modes that end the run early or edit
+  // files make no sense against it.
+  if (opts.noClear && !opts.watch) fail('--no-clear requires --watch');
+  if (opts.watch) {
+    if (opts.quiet) fail('--watch cannot be combined with -q');
+    if (opts.rewriteActive) fail('--watch cannot be combined with rewrite operations');
+    if (opts.noClear && opts.json) fail('--no-clear is meaningless with --json (it never clears)');
+  }
   if (!['auto', 'always', 'never'].includes(opts.color)) {
     fail(`invalid --color value: ${opts.color} (expected auto, always or never)`);
   }
@@ -265,6 +380,13 @@ function parseArgs(argv) {
 // `grepprg`, which appends args in its own order). Fall back to
 // "selector is the first positional" when the split is unclear.
 function resolveSelectorAndPaths(opts) {
+  // With -e the selectors are explicit, so — like grep -e — every positional
+  // is a file path; a mistyped one is reported as unreadable, not re-guessed
+  // as a selector.
+  if (opts.selectors.length) {
+    opts.paths = opts.positionals;
+    return;
+  }
   const pos = opts.positionals;
   const onDisk = [];
   const notOnDisk = [];
@@ -283,52 +405,18 @@ function resolveSelectorAndPaths(opts) {
   }
 }
 
-// Precompute the byte offset at which each line starts, so offset->line/col
-// is a binary search rather than a re-scan per match.
-function lineIndex(src) {
-  const starts = [0];
-  for (let i = 0; i < src.length; i++) {
-    if (src.charCodeAt(i) === 10 /* \n */) starts.push(i + 1);
-  }
-  return starts;
-}
-
-function offsetToPosition(starts, src, offset) {
-  // binary search for the greatest line start <= offset
-  let lo = 0, hi = starts.length - 1;
-  while (lo < hi) {
-    const mid = (lo + hi + 1) >> 1;
-    if (starts[mid] <= offset) lo = mid;
-    else hi = mid - 1;
-  }
-  const lineStart = starts[lo];
-  let lineEnd = src.indexOf('\n', lineStart);
-  if (lineEnd === -1) lineEnd = 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);
-  return {
-    line: lo + 1,            // 1-based
-    col: offset - lineStart + 1, // 1-based
-    text,
-  };
-}
-
-// Text of a 1-based line number, with the trailing \r stripped (CRLF), plus the
-// 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;
-  let text = src.slice(lineStart, lineEnd);
-  if (text.endsWith('\r')) text = text.slice(0, -1);
-  return { lineStart, text };
+// Never cut between the halves of a surrogate pair: a lone half is invalid
+// Unicode and serializes as U+FFFD garbage. Backing off one unit loses at most
+// one display column.
+function safeCut(text, at) {
+  const c = text.charCodeAt(at - 1);
+  return c >= 0xd800 && c <= 0xdbff ? at - 1 : at;
 }
 
 function truncate(text, maxWidth) {
   if (!maxWidth || text.length <= maxWidth) return text;
-  if (maxWidth <= 1) return text.slice(0, maxWidth);
-  return text.slice(0, maxWidth - 1) + '…'; // …
+  if (maxWidth <= 1) return text.slice(0, safeCut(text, maxWidth));
+  return text.slice(0, safeCut(text, maxWidth - 1)) + '…'; // …
 }
 
 // Produce the visible match text: truncate first (so --max-width still measures
@@ -350,43 +438,6 @@ function renderText(pos, off, nodeEnd, opts) {
   return vis.slice(0, s) + paint(COLORS.match, vis.slice(s, e)) + vis.slice(e);
 }
 
-// Concatenate the text of a node and all its descendants (dependency-free,
-// rather than pulling in domutils). Used by --text.
-function textOf(node) {
-  if (node.type === 'text') return node.data || '';
-  if (!node.children) return '';
-  let s = '';
-  for (const child of node.children) s += textOf(child);
-  return s;
-}
-
-const collapseWs = s => s.replace(/\s+/g, ' ').trim();
-
-const isElement = n => n && (n.type === 'tag' || n.type === 'script' || n.type === 'style');
-
-// Climb n element levels from el, clamping at the document root.
-function ancestor(el, n) {
-  let node = el;
-  for (let k = 0; k < n; k++) {
-    if (!isElement(node.parent)) break;
-    node = node.parent;
-  }
-  return node;
-}
-
-// --parent re-points each match to its n-th ancestor; dedup by identity so a
-// shared container is reported once, preserving first-seen order.
-function retarget(nodes, opts) {
-  if (!opts.parent) return nodes;
-  const seen = new Set();
-  const result = [];
-  for (const el of nodes) {
-    const a = ancestor(el, opts.parent);
-    if (!seen.has(a)) { seen.add(a); result.push(a); }
-  }
-  return result;
-}
-
 // Sentinels marking where a highlighted node begins/ends. They are injected as
 // HTML *comment* nodes (not text) so js-beautify keeps the surrounding block
 // layout — text markers would make adjacent block elements collapse inline.
@@ -476,14 +527,14 @@ function emitContext(src, starts, name, showLabel, targets, opts, out) {
   const lineCount = src.length === 0 ? 0 : (src.endsWith('\n') ? starts.length - 1 : starts.length);
 
   // Map each match line to a representative node span (the first match on it),
-  // which drives the in-line highlight when coloring.
+  // which drives the in-line highlight — and the [label] tag — when emitting.
   const info = new Map();
-  for (const el of targets) {
+  for (const { el, label: selLabel } of targets) {
     const off = el.startIndex == null ? 0 : el.startIndex;
     const pos = offsetToPosition(starts, src, off);
     if (info.has(pos.line)) continue;
     const nodeEnd = (el.endIndex == null ? off : el.endIndex) + 1;
-    info.set(pos.line, { off, nodeEnd, pos });
+    info.set(pos.line, { off, nodeEnd, pos, selLabel });
   }
 
   // Expand match lines to [L-before, L+after] windows and merge adjacent ones.
@@ -507,11 +558,12 @@ function emitContext(src, starts, name, showLabel, targets, opts, out) {
       if (label) prefix += c(COLORS.file, label) + (opts.nul ? '\0' : sepColored);
       if (opts.lineNumber) {
         prefix += c(COLORS.line, String(L));
-        prefix += m ? c(COLORS.sep, ':') + c(COLORS.line, String(m.pos.col)) + ' '
+        prefix += m ? c(COLORS.sep, ':') + c(COLORS.line, String(m.pos.bcol)) + ' '
                     : c(COLORS.sep, '-');
       }
+      const tag = m && m.selLabel != null ? c(COLORS.label, `[${m.selLabel}]`) + ' ' : '';
       const body = m
-        ? renderText(m.pos, m.off, m.nodeEnd, opts)        // highlight + truncate
+        ? tag + renderText(m.pos, m.off, m.nodeEnd, opts)  // highlight + truncate
         : truncate(lineTextAt(starts, src, L).text, opts.maxWidth);
       out.push(prefix + body);
     }
@@ -522,12 +574,29 @@ function emitContext(src, starts, name, showLabel, targets, opts, out) {
 // 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) {
-  const dom = parseDocument(src, {
-    withStartIndices: true,
-    withEndIndices: true,
-  });
-  const matches = selectAll(opts.selector, dom);
-  const found = matches.length;
+  // 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);
+  // 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
+  // stable sort keeps command-line selector order for ties). A positional
+  // selector is the degenerate case with a null label, which suppresses the
+  // [label] tag and the --json `label` field everywhere.
+  const selList = opts.selectors.length
+    ? opts.selectors
+    : [{ 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 });
+  }
+  if (selList.length > 1) {
+    records.sort((a, b) => (a.el.startIndex || 0) - (b.el.startIndex || 0));
+  }
+  const found = records.length;
   // Aggregate modes suppress per-match output entirely.
   if (opts.quiet) return found;                                  // status only
   if (opts.filesWithMatches) { if (found) out.push(name); return found; }
@@ -537,60 +606,88 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
   // -m/--max-count caps matches per source; `limit` is the remaining global
   // budget from -M/--max-total (Infinity when neither applies).
   const cap = Math.min(opts.maxCount || Infinity, limit);
-  const limited = Number.isFinite(cap) ? matches.slice(0, cap) : matches;
+  const limited = Number.isFinite(cap) ? records.slice(0, cap) : records;
   if (opts.count) {
-    if (limited.length) {
-      const fileSep = opts.nul ? '\0' : ':';
-      out.push(label ? `${label}${fileSep}${limited.length}` : String(limited.length));
-    }
+    // grep parity: every searched file reports a count, zeros included, so
+    // scripts get one row per file (exit status still says whether anything
+    // matched at all).
+    const fileSep = opts.nul ? '\0' : ':';
+    out.push(label ? `${label}${fileSep}${limited.length}` : String(limited.length));
     return limited.length;
   }
-  const starts = opts.print ? null : lineIndex(src);
-  // --parent re-targets matches to ancestors (no-op without it). Aggregate
-  // modes above operate on the raw matches; targeting only affects what prints.
-  const targets = retarget(limited, opts);
+  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.
+  let targets = limited;
+  if (opts.parent) {
+    targets = [];
+    const seen = new Map();                       // ancestor -> Set of labels
+    for (const r of limited) {
+      const a = ancestor(r.el, opts.parent);
+      let labels = seen.get(a);
+      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 });
+      }
+    }
+  }
   // For --parent + -p, remember which original matches sit under each ancestor
   // so they can be highlighted inside the printed container.
   const originsByTarget = new Map();
   if (opts.parent && opts.print) {
-    for (const el of limited) {
-      const a = ancestor(el, opts.parent);
+    for (const r of limited) {
+      const a = ancestor(r.el, opts.parent);
       if (!originsByTarget.has(a)) originsByTarget.set(a, []);
-      originsByTarget.get(a).push(el);
+      originsByTarget.get(a).push(r.el);
     }
   }
   if (opts.before > 0 || opts.after > 0) {
     emitContext(src, starts, name, showLabel, targets, opts, out);
     return limited.length;
   }
+  // From here on the return value is the number of *emitted* records (which is
+  // what the -M budget and the exit status should count): --attr can skip
+  // 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).
-    for (const el of targets) {
+    // one line. Ignores --color and -n (line/col are always present). `label`
+    // appears only with -e.
+    for (const { el, label: selLabel } of targets) {
       const off = el.startIndex == null ? 0 : el.startIndex;
       const pos = offsetToPosition(starts, src, off);
       const nodeEnd = (el.endIndex == null ? off : el.endIndex) + 1;
       out.push(JSON.stringify({
         file: name,
         line: pos.line,
-        col: pos.col,
+        col: pos.bcol,
+        ...(selLabel !== null && { label: selLabel }),
         html: src.slice(off, nodeEnd),
         text: collapseWs(textOf(el)),
       }));
     }
-    return limited.length;
+    return targets.length;
   }
-  for (const el of targets) {
+  let emitted = 0;
+  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.
+    const tag = selLabel === null ? '' : c(COLORS.label, `[${selLabel}]`) + ' ';
     if (opts.print) {
-      // -p shows the re-indented node only; no line:col locator. With --parent,
-      // the original matched descendants are highlighted inside the container.
+      // -p shows the re-indented node only; no line:col locator (the [label]
+      // tag gets its own line above the block). With --parent, the original
+      // matched descendants are highlighted inside the container.
+      if (tag) out.push(tag.trimEnd());
       out.push(prettyPrint(el, originsByTarget.get(el), opts), ''); // blank separator
+      emitted++;
       continue;
     }
     const off = el.startIndex == null ? 0 : el.startIndex;
     const pos = offsetToPosition(starts, src, off);
-    const c = opts.colorOn ? paint : (_, s) => s;
 
     // Choose the content printed for this match. --attr/--text replace the
     // source line with the extracted value (whole value highlighted as the
@@ -615,11 +712,12 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
     let prefix = '';
     if (label) prefix += c(COLORS.file, label) + fileSep;
     if (opts.lineNumber) {
-      prefix += c(COLORS.line, String(pos.line)) + sep + c(COLORS.line, String(pos.col)) + ' ';
+      prefix += c(COLORS.line, String(pos.line)) + sep + c(COLORS.line, String(pos.bcol)) + ' ';
     }
-    out.push(prefix + text);
+    out.push(prefix + tag + text);
+    emitted++;
   }
-  return limited.length;
+  return emitted;
 }
 
 // Translate a glob to a regex body. `*` matches within a path segment, `**`
@@ -632,9 +730,15 @@ function globToRegex(glob) {
     const c = glob[i];
     if (c === '*') {
       if (glob[i + 1] === '*') {            // **  (crosses /)
-        re += '.*';
         i++;
-        if (glob[i + 1] === '/') i++;       // consume the slash in **/
+        if (glob[i + 1] === '/') {
+          // `**/` spans whole segments (or none): `**/foo` matches `foo` and
+          // `a/b/foo`, but not `barfoo` — the `.*` must end at a `/`.
+          re += '(?:.*/)?';
+          i++;
+        } else {
+          re += '.*';
+        }
       } else {
         re += '[^/]*';
       }
@@ -672,16 +776,25 @@ function compileIgnore(pattern) {
 }
 
 // True if name/path matches any compiled glob matcher (shared by --ignore/
-// --exclude and --include).
+// --exclude and --include). Globs always use `/` as the separator (gitignore
+// semantics), so normalize Windows backslash paths before matching.
 function matchesAny(name, full, isDir, matchers) {
+  const fullPosix = path.sep === '/' ? full : full.split(path.sep).join('/');
   for (const m of matchers) {
     if (m.dirOnly && !isDir) continue;
-    if (m.re.test(m.hasSlash ? full : name)) return true;
+    if (m.re.test(m.hasSlash ? fullPosix : name)) return true;
   }
   return false;
 }
 
-function* walk(dir, opts, depth = 1) {
+// `visited` (only with -S/--follow) holds the realpath of every directory
+// already entered, so symlink cycles — and two links to the same physical
+// directory — are traversed once. Without --follow, symlinks are skipped.
+function* walk(dir, opts, depth = 1, visited = null) {
+  if (opts.follow && visited === null) {
+    visited = new Set();
+    try { visited.add(fs.realpathSync(dir)); } catch (e) { /* walked anyway */ }
+  }
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -689,14 +802,30 @@ function* walk(dir, opts, depth = 1) {
     if (!opts.noMessages) process.stderr.write(`cssgrep: ${dir}: ${e.code || e.message}\n`);
     return;
   }
+  // readdir order is filesystem-dependent; sort so output order (and therefore
+  // -M/-m truncation points) is stable across platforms.
+  entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
   for (const e of entries) {
     const full = path.join(dir, e.name);
-    const isDir = e.isDirectory();
+    let isDir = e.isDirectory();
+    let isFile = e.isFile();
+    if (opts.follow && e.isSymbolicLink()) {
+      const st = fs.statSync(full, { throwIfNoEntry: false }); // resolves the link
+      if (!st) continue;                                       // broken link
+      isDir = st.isDirectory();
+      isFile = st.isFile();
+    }
     if (opts.ignore.length && matchesAny(e.name, full, isDir, opts.ignore)) continue;
     if (isDir) {
+      if (opts.follow) {
+        let real;
+        try { real = fs.realpathSync(full); } catch (err) { continue; }
+        if (visited.has(real)) continue;    // cycle or already-walked dir
+        visited.add(real);
+      }
       // --max-depth caps how far we descend; depth 1 = the target's children.
-      if (!opts.maxDepth || depth < opts.maxDepth) yield* walk(full, opts, depth + 1);
-    } else if (e.isFile()) {
+      if (!opts.maxDepth || depth < opts.maxDepth) yield* walk(full, opts, depth + 1, visited);
+    } else if (isFile) {
       // --include replaces the extension filter; otherwise filter by --ext.
       if (opts.include.length) {
         if (matchesAny(e.name, full, false, opts.include)) yield full;
@@ -709,7 +838,7 @@ function* walk(dir, opts, depth = 1) {
 }
 
 function readStdin() {
-  return fs.readFileSync(0, 'utf8');
+  return fs.readFileSync(0); // Buffer: sniffed for binary before decoding
 }
 
 // Heuristic binary-file detector (grep/git style). A NUL byte in the first 8 KB
@@ -729,11 +858,271 @@ function looksBinary(buf) {
   return n > 0 && suspicious / n > 0.3;
 }
 
-function main() {
-  const opts = parseArgs(process.argv.slice(2));
-  resolveSelectorAndPaths(opts);
+// --- rewrite output -----------------------------------------------------------
+
+// Myers O(ND) shortest edit script over lines. Only ever runs on the middle
+// slice left after common prefix/suffix trimming, which transform()'s local
+// splices keep small.
+function myersDiff(a, b) {
+  const N = a.length, M = b.length, max = N + M, off = max;
+  if (max === 0) return [];
+  const trace = [];
+  const v = new Array(2 * max + 2).fill(0);
+  let D = -1;
+  for (let d = 0; d <= max && D < 0; d++) {
+    trace.push(v.slice());
+    for (let k = -d; k <= d; k += 2) {
+      let x = (k === -d || (k !== d && v[off + k - 1] < v[off + k + 1]))
+        ? v[off + k + 1]
+        : v[off + k - 1] + 1;
+      let y = x - k;
+      while (x < N && y < M && a[x] === b[y]) { x++; y++; }
+      v[off + k] = x;
+      if (x >= N && y >= M) { D = d; break; }
+    }
+  }
+  const script = [];
+  let x = N, y = M;
+  for (let d = D; d > 0; d--) {
+    const vp = trace[d];
+    const k = x - y;
+    const prevK = (k === -d || (k !== d && vp[off + k - 1] < vp[off + k + 1])) ? k + 1 : k - 1;
+    const prevX = vp[off + prevK], prevY = prevX - prevK;
+    while (x > prevX && y > prevY) { script.push({ t: ' ', l: a[--x] }); y--; }
+    if (x === prevX) script.push({ t: '+', l: b[--y] });
+    else script.push({ t: '-', l: a[--x] });
+  }
+  while (x > 0 && y > 0) { script.push({ t: ' ', l: a[--x] }); y--; }
+  while (x > 0) script.push({ t: '-', l: a[--x] });
+  while (y > 0) script.push({ t: '+', l: b[--y] });
+  return script.reverse();
+}
+
+// Unified diff of two documents, git-apply compatible: ---/+++ headers with
+// a/ b/ prefixes, 3 context lines, merged hunks, and "\ No newline at end of
+// file" markers when a side's last line is unterminated.
+function unifiedDiff(name, oldStr, newStr) {
+  const split = s => {
+    const lines = s.split('\n');
+    const noEol = lines[lines.length - 1] !== '';
+    if (!noEol) lines.pop();
+    return { lines, noEol };
+  };
+  const A = split(oldStr), B = split(newStr);
+  const a = A.lines, b = B.lines;
+  let pre = 0;
+  while (pre < a.length && pre < b.length && a[pre] === b[pre]) pre++;
+  let suf = 0;
+  while (suf < a.length - pre && suf < b.length - pre
+    && a[a.length - 1 - suf] === b[b.length - 1 - suf]) suf++;
+  const script = [
+    ...a.slice(0, pre).map(l => ({ t: ' ', l })),
+    ...myersDiff(a.slice(pre, a.length - suf), b.slice(pre, b.length - suf)),
+    ...a.slice(a.length - suf).map(l => ({ t: ' ', l })),
+  ];
+
+  // Old/new line number sitting *before* each script entry (1-based).
+  const oldPos = [], newPos = [];
+  let ol = 1, nl = 1;
+  for (const s of script) {
+    oldPos.push(ol);
+    newPos.push(nl);
+    if (s.t !== '+') ol++;
+    if (s.t !== '-') nl++;
+  }
+
+  // Group changes into hunks: 3 context lines, merge when gaps are ≤ 6.
+  const C = 3;
+  const hunks = [];
+  let i = 0;
+  while (i < script.length) {
+    if (script[i].t === ' ') { i++; continue; }
+    const hStart = Math.max(0, i - C);
+    let lastChange = i;
+    let j = i + 1;
+    while (j < script.length) {
+      if (script[j].t !== ' ') { lastChange = j; j++; continue; }
+      let k = j;
+      while (k < script.length && script[k].t === ' ') k++;
+      if (k === script.length || k - j > 2 * C) break;
+      j = k;
+    }
+    const hEnd = Math.min(script.length, lastChange + C + 1);
+    hunks.push([hStart, hEnd]);
+    i = hEnd;
+  }
 
-  // Resolve the list of files to search.
+  const out = [`--- a/${name}`, `+++ b/${name}`];
+  for (const [s, e] of hunks) {
+    let oc = 0, nc = 0;
+    for (let k = s; k < e; k++) {
+      if (script[k].t !== '+') oc++;
+      if (script[k].t !== '-') nc++;
+    }
+    const os = oc ? oldPos[s] : oldPos[s] - 1;
+    const ns = nc ? newPos[s] : newPos[s] - 1;
+    out.push(`@@ -${os},${oc} +${ns},${nc} @@`);
+    for (let k = s; k < e; k++) {
+      const { t, l } = script[k];
+      out.push(t + l);
+      const atOldEnd = t !== '+' && oldPos[k] === a.length && A.noEol;
+      const atNewEnd = t !== '-' && newPos[k] === b.length && B.noEol;
+      if (atOldEnd || atNewEnd) out.push('\');
+    }
+  }
+  return out.join('\n') + '\n';
+}
+
+// The rewrite program mode: transform each source and emit the document
+// (single input) or a unified diff (any number of files). Never writes a
+// file — apply diffs with git apply / patch (see ROADMAP Phase 9).
+function rewriteMain(opts, files, useStdin) {
+  if (!useStdin && files.length > 1 && !opts.diff) {
+    fail('rewriting multiple files requires --diff');
+  }
+  const sources = [];
+  if (useStdin) {
+    sources.push({ name: '(standard input)', buf: readStdin() });
+  } else {
+    for (const f of files) {
+      try {
+        sources.push({ name: f, buf: fs.readFileSync(f) });
+      } catch (e) {
+        if (!opts.noMessages) process.stderr.write(`cssgrep: ${f}: ${e.code || e.message}\n`);
+      }
+    }
+  }
+  let totalEdits = 0;
+  const diffs = [];
+  for (const { name, buf } of sources) {
+    // A rewriter must never corrupt bytes it didn't edit: binary input is
+    // never HTML, and a lossy UTF-8 decode written back would mangle every
+    // non-UTF-8 byte in the file — refuse both outright (exit 2).
+    if (looksBinary(buf)) fail(`${name}: binary input; refusing to rewrite`);
+    const src = buf.toString('utf8');
+    if (!Buffer.from(src, 'utf8').equals(buf)) {
+      fail(`${name}: not valid UTF-8; refusing to rewrite`);
+    }
+    let result;
+    try {
+      result = parse(src).transform(opts.selector, { ...opts.rewrite, parent: opts.parent });
+    } catch (e) {
+      if (e && e.message && /selector|tokeniz|parse/i.test(e.message)) {
+        fail(`invalid selector: ${opts.selector}`);
+      }
+      fail(e.message);
+    }
+    totalEdits += result.edits.length;
+    if (opts.diff) {
+      if (result.edits.length) diffs.push(unifiedDiff(name, src, result.html));
+    } else {
+      // Filter-friendly: the document is always emitted, changed or not
+      // (like sed); the exit status says whether anything was edited.
+      process.stdout.write(result.html);
+    }
+  }
+  if (diffs.length) process.stdout.write(diffs.join(''));
+  process.exitCode = totalEdits > 0 ? 0 : 1;
+}
+
+// The watch program mode: rerun the search whenever a watched path changes.
+// Native recursive fs.watch, no polling (see ROADMAP Phase 10; caveat:
+// network/virtual filesystems may not deliver events). Output adapts like
+// --color=auto does: a TTY gets clear+reprint, a pipe gets append mode with
+// `== HH:MM:SS … ==` separators (--no-clear forces append on a TTY), and
+// --json gets an NDJSON stream — {"event":"run",...} then the match records.
+// Runs until SIGINT (exit 0, like watch(1)).
+function watchMain(opts) {
+  const clearMode = !opts.json && !opts.noClear && Boolean(process.stdout.isTTY);
+  const renderOut = out => (!out.length ? ''
+    : opts.nul && (opts.filesWithMatches || opts.filesWithoutMatch)
+      ? out.map(s => s + '\0').join('')
+      : out.join('\n') + '\n');
+
+  const run = changed => {
+    // Re-walk every run: a rerun sees exactly what a fresh invocation would.
+    const { files } = resolveFiles(opts);
+    const out = [];
+    let total = 0;
+    try {
+      total = searchFiles(opts, files, out);
+    } catch (e) {
+      if (e && e.message && /selector|tokeniz|parse/i.test(e.message)) {
+        fail(`invalid selector: ${opts.selector != null
+          ? opts.selector
+          : opts.selectors.map(s => s.selector).join(', ')}`);
+      }
+      fail(e.message);
+    }
+    if (opts.json) {
+      process.stdout.write(JSON.stringify({
+        event: 'run',
+        changed: changed || null,
+        matches: total,
+      }) + '\n' + renderOut(out));
+    } else if (clearMode) {
+      process.stdout.write('\x1b[2J\x1b[H' + (out.length ? renderOut(out) : 'cssgrep: no matches\n'));
+    } else {
+      const ts = new Date().toTimeString().slice(0, 8);
+      process.stdout.write(`== ${ts} ${changed || 'watching'} ==\n` + renderOut(out));
+    }
+  };
+
+  // Debounce change bursts (editors often fire several events per save).
+  let timer = null;
+  let pending = null;
+  const schedule = changed => {
+    pending = changed;
+    clearTimeout(timer);
+    timer = setTimeout(() => { const c = pending; pending = null; run(c); }, 80);
+  };
+
+  // Directory targets get one recursive watcher each. Explicit file targets
+  // are watched via their parent directory, filtered by name — editors often
+  // save by rename-replace, which would orphan a watcher on the file itself.
+  const watchers = [];
+  const fileTargets = new Map();              // parent dir -> Set of basenames
+  const targets = opts.paths.length ? opts.paths : ['.'];
+  for (const p of targets) {
+    const st = fs.statSync(p, { throwIfNoEntry: false });
+    if (!st) {
+      if (!opts.noMessages) process.stderr.write(`cssgrep: ${p}: no such file or directory\n`);
+      continue;
+    }
+    if (st.isDirectory()) {
+      watchers.push(fs.watch(p, { recursive: true },
+        (ev, f) => schedule(f ? path.join(p, f) : p)));
+    } else {
+      const dir = path.dirname(p);
+      if (!fileTargets.has(dir)) fileTargets.set(dir, new Set());
+      fileTargets.get(dir).add(path.basename(p));
+    }
+  }
+  for (const [dir, bases] of fileTargets) {
+    watchers.push(fs.watch(dir,
+      (ev, f) => { if (!f || bases.has(f)) schedule(f ? path.join(dir, f) : dir); }));
+  }
+  if (!watchers.length) fail('--watch: nothing to watch');
+  for (const w of watchers) {
+    w.on('error', e => {
+      if (!opts.noMessages) process.stderr.write(`cssgrep: watch: ${e.message}\n`);
+    });
+  }
+
+  process.on('SIGINT', () => {
+    for (const w of watchers) w.close();
+    clearTimeout(timer);
+    process.exitCode = 0;                     // watch(1) convention
+  });
+
+  run(null);                                  // initial pass, then wait
+}
+
+// Resolve the paths to search into a concrete file list (or stdin). Watch
+// mode calls this again on every rerun, so a rerun sees exactly what a fresh
+// invocation would: new files picked up per the include/ignore/--ext rules,
+// deleted ones dropped.
+function resolveFiles(opts) {
   let files = [];
   let useStdin = false;
   if (opts.recursive) {
@@ -750,9 +1139,57 @@ function main() {
   } else {
     useStdin = true;
   }
+  return { files, useStdin };
+}
 
+// One search pass over a file list; appends output lines to `out` and returns
+// the match total. Shared by the single-shot main path and each watch rerun.
+function searchFiles(opts, files, out) {
   // A label (file prefix) is shown when searching more than one file; -H forces
   // it on (even for one file or stdin) and --no-filename forces it off.
+  const showLabel = opts.withFilename ? true
+    : opts.noFilename ? false
+    : files.length > 1;
+  let total = 0;
+  // -M/--max-total: remaining matches allowed across all files (Infinity = off).
+  const room = () => (opts.maxTotal ? Math.max(0, opts.maxTotal - total) : Infinity);
+  for (const f of files) {
+    if (room() <= 0) break;               // -M: global budget exhausted
+    let buf;
+    try {
+      buf = fs.readFileSync(f);           // Buffer: sniff before decoding
+    } catch (e) {
+      if (!opts.noMessages) process.stderr.write(`cssgrep: ${f}: ${e.code || e.message}\n`);
+      continue;
+    }
+    if (looksBinary(buf)) {
+      if (!opts.noMessages && !opts.quiet) {
+        process.stderr.write(`cssgrep: ${f}: binary file (skipped)\n`);
+      }
+      continue;
+    }
+    total += searchSource(buf.toString('utf8'), f, showLabel, opts, out, room());
+    if (opts.quiet && total > 0) break;   // -q: first match decides the status
+  }
+  return total;
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  resolveSelectorAndPaths(opts);
+
+  const { files, useStdin } = resolveFiles(opts);
+
+  if (opts.rewriteActive) {
+    rewriteMain(opts, files, useStdin);
+    return;
+  }
+  if (opts.watch) {
+    if (useStdin) fail('--watch requires file or directory paths');
+    watchMain(opts);
+    return;
+  }
+
   const showLabel = opts.withFilename ? true
     : opts.noFilename ? false
     : (!useStdin && files.length > 1);
@@ -760,35 +1197,26 @@ function main() {
   const out = [];
   let total = 0;
 
-  // -M/--max-total: remaining matches allowed across all files (Infinity = off).
-  const room = () => (opts.maxTotal ? Math.max(0, opts.maxTotal - total) : Infinity);
-
   try {
     if (useStdin) {
-      total += searchSource(readStdin(), '(standard input)', showLabel, opts, out, room());
-    } else {
-      for (const f of files) {
-        if (room() <= 0) break;               // -M: global budget exhausted
-        let buf;
-        try {
-          buf = fs.readFileSync(f);           // Buffer: sniff before decoding
-        } catch (e) {
-          if (!opts.noMessages) process.stderr.write(`cssgrep: ${f}: ${e.code || e.message}\n`);
-          continue;
+      const buf = readStdin();
+      if (looksBinary(buf)) {
+        if (!opts.noMessages && !opts.quiet) {
+          process.stderr.write('cssgrep: (standard input): binary input (skipped)\n');
         }
-        if (looksBinary(buf)) {
-          if (!opts.noMessages && !opts.quiet) {
-            process.stderr.write(`cssgrep: ${f}: binary file (skipped)\n`);
-          }
-          continue;
-        }
-        total += searchSource(buf.toString('utf8'), f, showLabel, opts, out, room());
-        if (opts.quiet && total > 0) break;   // -q: first match decides the status
+      } else {
+        total += searchSource(buf.toString('utf8'), '(standard input)', showLabel, opts, out,
+          opts.maxTotal || Infinity);
       }
+    } else {
+      total = searchFiles(opts, files, out);
     }
   } catch (e) {
     if (e && e.message && /selector|tokeniz|parse/i.test(e.message)) {
-      fail(`invalid selector: ${opts.selector}`);
+      const shown = opts.selector != null
+        ? opts.selector
+        : opts.selectors.map(s => s.selector).join(', ');
+      fail(`invalid selector: ${shown}`);
     }
     fail(e.message);
   }
@@ -805,8 +1233,11 @@ function main() {
   }
   // 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.
+  // Set exitCode rather than calling process.exit(): stdout writes to a pipe
+  // are async, and exit() would drop whatever hasn't flushed yet, truncating
+  // large result sets mid-stream.
   const success = opts.filesWithoutMatch ? out.length > 0 : total > 0;
-  process.exit(success ? 0 : 1);
+  process.exitCode = success ? 0 : 1;
 }
 
 main();