cssgrep 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.2.0] - 2026-07-02
+
+### Added
+- `-S`/`--follow` to follow symbolic links while recursing with `-r`
+  (skipped by default). Cycle-safe: each physical directory is visited once.
+
+### Fixed
+- Large result sets are no longer truncated when stdout is a pipe (the process
+  exited before async pipe writes had flushed).
+- Columns (`-n`, `-A`/`-B`/`-C`, `--json`) now count bytes — what vim's
+  `grepformat %c` expects — instead of UTF-16 code units, so non-ASCII text
+  before a match no longer skews the locator.
+- A value-taking option with no value (e.g. a trailing `--ignore` or `--attr`)
+  now fails cleanly with exit 2 instead of crashing or being silently ignored.
+- `**/` in globs stops at path-segment boundaries: `--include '**/foo.html'`
+  no longer matches `barfoo.html`.
+- `--attr` matches attribute names case-insensitively (the parser lowercases
+  them), and exits 1 when every match was skipped for lacking the attribute.
+- `-w`/`--max-width` no longer cuts an astral character in half.
+- Binary detection now also applies to standard input.
+- Slash-containing globs (e.g. `--include 'src/*.html'`) now match on Windows:
+  paths are normalized to `/` separators before glob matching.
+- Recursive walks visit directory entries in sorted order, so output order is
+  deterministic across platforms.
+
+### Changed
+- Bare `--color` now means `auto`, matching GNU grep (was `always`).
+- `-c` prints zero counts (`file:0`, or a lone `0` for a single input),
+  matching grep.
+
+## [1.1.0] - 2026-07-02
+
+### Added
+- `-H`/`--with-filename` and `--no-filename` to force the `file:` prefix on or off.
+- `-s`/`--no-messages` to suppress errors for unreadable or missing files.
+- `--include`/`--exclude` file globs with brace alternation (`{a,b,c}`).
+  `--exclude` is an alias of `--ignore`; `--include` replaces the `--ext` filter.
+- `--max-depth <n>` to cap `-r` recursion depth.
+- Automatic skipping of binary files (NUL byte / control-byte heuristic), with a
+  note on stderr suppressible by `-s`/`-q`.
+
+### Changed
+- CI now runs on Linux, macOS and Windows across Node 20 and 22.
+- Releases publish to npm with provenance and smoke-test the built binary.
+
+## [1.0.0] - 2026-06-29
+
+### Added
+- Initial release: match a CSS selector against HTML and print each hit
+  grep-style, with byte-accurate `line:col` via `-n` (works on minified HTML).
+- Recursive search: `-r`/`--recursive`, `--ext`, `-i`/`--ignore`, `--ignore-file`.
+- Print modes: default line, `-p`/`--print`, `--attr`, `--text`, `--json`.
+- `--parent <n>` structural context; line context `-A`/`-B`/`-C`.
+- Limits `-m`/`--max-count`, `-M`/`--max-total`; aggregates `-c`, `-l`/`-L`, `-q`.
+- `-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.2.0...HEAD
+[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
+[1.0.0]: https://github.com/msbatarce/cssgrep/releases/tag/v1.0.0

package/README.md

@@ -1,5 +1,9 @@
 # cssgrep
 
+[![npm](https://img.shields.io/npm/v/cssgrep.svg)](https://www.npmjs.com/package/cssgrep)
+[![test](https://github.com/msbatarce/cssgrep/actions/workflows/test.yml/badge.svg)](https://github.com/msbatarce/cssgrep/actions/workflows/test.yml)
+[![license](https://img.shields.io/npm/l/cssgrep.svg)](LICENSE)
+
 Search HTML by CSS selector and print each match, grep-style — add `-n` to
 report it as `file:line:col`.
 
@@ -73,12 +77,16 @@ locator appears only with `-n`:
 | Flag | Description |
 |------|-------------|
 | `-r`, `--recursive` | Recurse into directory arguments (defaults to `.` if none given). |
+| `--max-depth <n>` | Limit `-r` recursion depth (`1` = the given directory only, no subdirectories). |
 | `--ext <list>` | Extensions to scan with `-r` (default `html,htm`). Value attaches with `=`: `--ext htm` or `--ext=htm`. |
+| `--include <glob>` | Only search files whose name/path matches `<glob>` while recursing (repeatable). Replaces `--ext` — the two can't be combined. e.g. `--include '*.{html,htm,xhtml}'`. |
 | `-i`, `--ignore <glob>` | Skip files/dirs matching `<glob>` while recursing (repeatable). `node_modules`, `*.min.html`, `build/` (dir-only), or path globs like `src/vendor/**`. |
+| `--exclude <glob>` | Alias for `--ignore` (grep's name for the same thing). |
 | `--ignore-file <path>` | Load ignore globs from a file, one per line (`#` comments and blank lines ignored) — like a `.gitignore`. |
+| `-S`, `--follow` | Follow symbolic links while recursing with `-r` (they are skipped by default). Each physical directory is visited once, so symlink cycles are safe. |
 | `-n`, `--line-number` | Prefix each match with its `line:col` locator. Mutually exclusive with `-c` and `-p`. |
 | `-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). Honors `-n` and `-w`. |
+| `--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`. |
 | `--parent <n>` | Report the `n`-th element ancestor of each match instead of the match itself (de-duplicated). Pairs well with `-p`. |
@@ -87,19 +95,31 @@ locator appears only with `-n`:
 | `-B`, `--before-context <n>` | Print `n` source lines before each match. |
 | `-C`, `--context <n>` | Print `n` source lines before and after each match. |
 | `-m`, `--max-count <n>` | Stop after `n` matches per file (caps `-c` too). |
-| `-M`, `--max-total <n>` | Stop after `n` matches in total across all files. |
-| `-c`, `--count` | Print only the match count (per file when relevant). |
+| `-M`, `--max-total <n>` | Stop after `n` matches in total across all files. The budget counts matches, not files — combined with `-l`/`-L`, scanning stops once `n` matches have been seen, which can cut the file list short. |
+| `-c`, `--count` | Print only the match count (per file when relevant, zeros included — `file:0`, like grep). |
 | `-l`, `--files-with-matches` | Print only the names of files that contain a match. |
 | `-L`, `--files-without-match` | Print only the names of files with no match. |
 | `-q`, `--quiet` | Print nothing; exit `0` on the first match, `1` if none. Stops early. |
+| `-s`, `--no-messages` | Suppress error messages for unreadable or missing files (handy with `-r`). |
 | `-0`, `--null` | Output a NUL after each file name instead of `:` (or, with `-l`/`-L`, instead of the newline) — pipe to `xargs -0`. |
-| `--color[=<when>]` | Colorize output: `auto` (default — color only when stdout is a terminal), `always`, or `never`. A bare `--color` means `always`. |
+| `-H`, `--with-filename` | Always print the `file:` prefix, even for a single file or stdin. |
+| `--no-filename` | Never print the `file:` prefix, even when searching multiple files. |
+| `--color[=<when>]` | Colorize output: `auto` (default — color only when stdout is a terminal), `always`, or `never`. A bare `--color` means `auto`, like grep; use `--color=always` to force color into pipes. |
 | `-h`, `--help` | Show help. |
 | `-V`, `--version` | Print the version and exit. |
 
 Boolean short flags can be combined into one token (`-rn` is `-r -n`), and a
 value-taking flag may close such a cluster (`-rnw100`).
 
+Globs for `--include`/`--ignore`/`--exclude` support `*` (within a path
+segment), `**` (across `/`), `?` (one non-slash char), and brace alternation
+like `*.{html,htm}`. A trailing `/` matches directories only; a pattern with a
+`/` matches against the path, otherwise the basename — gitignore-flavored.
+
+Binary input is detected (a NUL byte or a high ratio of control bytes in the
+first 8 KB) and skipped with a note on stderr — parsing them as HTML is never
+useful. Suppress the note with `-s` (or `-q`).
+
 When coloring is on, the matched node is highlighted within its line (grep's
 bold-red); the `file:` prefix and `line:col` locator get their own colors
 (magenta and green, like grep). Plain `-p` prints no color (the whole block is
@@ -187,4 +207,6 @@ a flag.)
 - [`css-select`](https://github.com/fb55/css-select) matches the selector
   against that DOM (the same engine cheerio uses).
 - Offsets are converted to 1-based `line:col` via a precomputed line index;
-  `col` points at the opening `<` of the matched tag.
+  `col` points at the opening `<` of the matched tag and counts *bytes* — what
+  vim's `grepformat` `%c` expects — so multibyte UTF-8 text earlier on the line
+  doesn't skew the cursor.

package/completions/_cssgrep

@@ -6,9 +6,13 @@
 _cssgrep() {
   _arguments -s -S \
     '(-r --recursive)'{-r,--recursive}'[recurse into directory arguments]' \
+    '--max-depth[limit -r recursion depth (1 = given dir only)]:depth:' \
     '--ext[extensions to scan with -r]:extensions (comma-separated):' \
+    '*--include[only search files matching glob (replaces --ext)]:glob:' \
     '*'{-i,--ignore}'[skip files/dirs matching glob while recursing]:glob:' \
+    '*--exclude[alias for --ignore]:glob:' \
     '--ignore-file[read ignore globs from a file]:file:_files' \
+    '(-S --follow)'{-S,--follow}'[follow symbolic links while recursing]' \
     '(-n --line-number)'{-n,--line-number}'[prefix each match with line:col]' \
     '(-p --print)'{-p,--print}'[pretty-print the matched node HTML]' \
     '--attr[print the value of an attribute]:attribute name:' \
@@ -25,7 +29,10 @@ _cssgrep() {
     '(-l --files-with-matches)'{-l,--files-with-matches}'[print only names of files with a match]' \
     '(-L --files-without-match)'{-L,--files-without-match}'[print only names of files without a match]' \
     '(-q --quiet)'{-q,--quiet}'[print nothing; exit on first match]' \
+    '(-s --no-messages)'{-s,--no-messages}'[suppress errors for unreadable/missing files]' \
     '(-0 --null)'{-0,--null}'[separate the file name with a NUL byte]' \
+    '(--no-filename)'{-H,--with-filename}'[always print the file name prefix]' \
+    '(-H --with-filename)--no-filename[never print the file name prefix]' \
     '--color=-[colorize output]::when:(auto always never)' \
     '(-h --help)'{-h,--help}'[show help and exit]' \
     '(-V --version)'{-V,--version}'[show version and exit]' \

package/completions/cssgrep.bash

@@ -6,11 +6,12 @@ _cssgrep() {
     cur="${COMP_WORDS[COMP_CWORD]}"
     prev="${COMP_WORDS[COMP_CWORD-1]}"
 
-    opts="-r --recursive --ext -i --ignore --ignore-file -n --line-number \
+    opts="-r --recursive --max-depth --ext --include -i --ignore --exclude --ignore-file -S --follow -n --line-number \
 -p --print --attr --text --json --parent -w --max-width \
 -A --after-context -B --before-context -C --context \
 -m --max-count -M --max-total -c --count \
--l --files-with-matches -L --files-without-match -q --quiet -0 --null \
+-l --files-with-matches -L --files-without-match -q --quiet -s --no-messages -0 --null \
+-H --with-filename --no-filename \
 --color -h --help -V --version"
 
     case "$prev" in
@@ -22,7 +23,7 @@ _cssgrep() {
             COMPREPLY=( $(compgen -f -- "$cur") )
             return 0
             ;;
-        --ext|-i|--ignore|--attr|--parent|-w|--max-width|-A|--after-context|\
+        --max-depth|--ext|--include|-i|--ignore|--exclude|--attr|--parent|-w|--max-width|-A|--after-context|\
 -B|--before-context|-C|--context|-m|--max-count|-M|--max-total)
             # value-taking flag with no enumerable completion; offer nothing
             return 0

package/completions/cssgrep.fish

@@ -2,9 +2,13 @@
 # Install: place this file in ~/.config/fish/completions/ (named cssgrep.fish).
 
 complete -c cssgrep -s r -l recursive -d 'Recurse into directory arguments'
+complete -c cssgrep -l max-depth -x -d 'Limit -r recursion depth (1 = given dir only)'
 complete -c cssgrep -l ext -x -d 'Extensions to scan with -r (comma-separated)'
+complete -c cssgrep -l include -x -d 'Only search files matching glob (replaces --ext)'
 complete -c cssgrep -s i -l ignore -x -d 'Skip files/dirs matching glob while recursing'
+complete -c cssgrep -l exclude -x -d 'Alias for --ignore'
 complete -c cssgrep -l ignore-file -r -F -d 'Read ignore globs from a file'
+complete -c cssgrep -s S -l follow -d 'Follow symbolic links while recursing'
 complete -c cssgrep -s n -l line-number -d 'Prefix each match with line:col'
 complete -c cssgrep -s p -l print -d 'Pretty-print the matched node HTML'
 complete -c cssgrep -l attr -x -d 'Print the value of an attribute'
@@ -21,7 +25,10 @@ complete -c cssgrep -s c -l count -d 'Print only a count of matches'
 complete -c cssgrep -s l -l files-with-matches -d 'Print only names of files with a match'
 complete -c cssgrep -s L -l files-without-match -d 'Print only names of files without a match'
 complete -c cssgrep -s q -l quiet -d 'Print nothing; exit on first match'
+complete -c cssgrep -s s -l no-messages -d 'Suppress errors for unreadable/missing files'
 complete -c cssgrep -s 0 -l null -d 'Separate the file name with a NUL byte'
+complete -c cssgrep -s H -l with-filename -d 'Always print the file name prefix'
+complete -c cssgrep -l no-filename -d 'Never print the file name prefix'
 complete -c cssgrep -l color -x -a 'auto always never' -d 'Colorize output'
 complete -c cssgrep -s h -l help -d 'Show help and exit'
 complete -c cssgrep -s V -l version -d 'Show version and exit'

package/index.js

@@ -12,7 +12,7 @@ const { html: beautify } = require('js-beautify');
 // 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.0.0';
+const VERSION = '1.2.0';
 
 const USAGE = `cssgrep - search HTML by CSS selector, grep-style.
 
@@ -29,9 +29,14 @@ Output (one line per match):
 
 Options:
   -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).
+      --include <glob>   Only search files matching <glob> (replaces --ext; repeatable).
   -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).
@@ -44,12 +49,17 @@ 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.
+  -s, --no-messages      Suppress error messages for unreadable/missing files.
   -0, --null             Separate the file name with a NUL byte (for xargs -0).
-      --color[=<when>]   Colorize output: auto (default), always or never.
+  -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, also what a bare
+                         --color means, like grep), always or never.
   -h, --help             Show this help.
   -V, --version          Show version and exit.
 
@@ -57,6 +67,9 @@ 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).
 
+Globs (--include/--ignore/--exclude) support *, ** (crosses /), ?, and brace
+alternation like *.{html,htm}.
+
 Exit status: 0 if any match was found, 1 if none, 2 on error.`;
 
 function fail(msg) {
@@ -83,7 +96,10 @@ function parseArgs(argv) {
     positionals: [],
     paths: [],
     recursive: false,
+    follow: false,
     exts: ['html', 'htm'],
+    extGiven: false,
+    maxDepth: 0,
     lineNumber: false,
     print: false,
     maxWidth: 0,
@@ -101,9 +117,14 @@ function parseArgs(argv) {
     before: 0,
     after: 0,
     ignore: [],
+    include: [],
+    withFilename: false,
+    noFilename: false,
+    noMessages: false,
     color: 'auto',
   };
   const setExts = v => {
+    opts.extGiven = true;
     opts.exts = (v || '').split(',').map(s => s.trim().replace(/^\./, '')).filter(Boolean);
   };
   const boundedInt = (v, what, min) => {
@@ -115,11 +136,13 @@ function parseArgs(argv) {
   const setMaxWidth = v => { opts.maxWidth = positiveInt(v, '--max-width'); };
   const setMaxCount = v => { opts.maxCount = positiveInt(v, '--max-count'); };
   const setMaxTotal = v => { opts.maxTotal = positiveInt(v, '--max-total'); };
+  const setMaxDepth = v => { opts.maxDepth = positiveInt(v, '--max-depth'); };
   const setParent = v => { opts.parent = positiveInt(v, '--parent'); };
   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); };
   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 => {
     let content;
     try { content = fs.readFileSync(v, 'utf8'); }
@@ -135,16 +158,22 @@ function parseArgs(argv) {
     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;
@@ -152,20 +181,26 @@ function parseArgs(argv) {
         case '--files-without-match': opts.filesWithoutMatch = true; break;
         case '--quiet': case '--silent': opts.quiet = true; break;
         case '--null': opts.nul = true; break;
+        case '--with-filename': opts.withFilename = true; break;
+        case '--no-filename': opts.noFilename = true; break;
+        case '--no-messages': opts.noMessages = true; break;
         case '--ext': setExts(value()); break;
-        case '--ignore': addIgnore(value()); break;
+        case '--ignore': case '--exclude': addIgnore(value()); break;
         case '--ignore-file': addIgnoreFile(value()); break;
+        case '--include': addInclude(value()); break;
         case '--max-width': setMaxWidth(value()); break;
         case '--max-count': setMaxCount(value()); break;
         case '--max-total': setMaxTotal(value()); break;
-        case '--attr': opts.attr = value(); break;
+        case '--max-depth': setMaxDepth(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;
         default: fail(`unknown option: ${name}`);
       }
       continue;
@@ -179,6 +214,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
         }
@@ -186,6 +222,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;
@@ -193,6 +230,8 @@ function parseArgs(argv) {
           case 'L': opts.filesWithoutMatch = true; break;
           case 'q': opts.quiet = true; break;
           case '0': case 'Z': opts.nul = true; break;
+          case 'H': opts.withFilename = true; break;
+          case 's': opts.noMessages = true; break;
           default: fail(`unknown option: -${ch}`);
         }
       }
@@ -206,6 +245,10 @@ function parseArgs(argv) {
   const aggregates = [opts.count, opts.filesWithMatches, opts.filesWithoutMatch, opts.quiet]
     .filter(Boolean).length;
   if (aggregates > 1) fail('only one of -c, -l, -L, -q may be given');
+  // Filename prefix can be forced on or off, but not both (grep -H / -h).
+  if (opts.withFilename && opts.noFilename) fail('-H cannot be combined with --no-filename');
+  // --include fully replaces the extension filter, so the two can't coexist.
+  if (opts.extGiven && opts.include.length) fail('--ext and --include cannot be combined');
   // Per-match print modes choose what is printed for each match; only one.
   const printModes = [opts.print, opts.attr != null, opts.text, opts.json].filter(Boolean).length;
   if (printModes > 1) fail('only one of -p, --attr, --text, --json may be given');
@@ -280,7 +323,12 @@ function offsetToPosition(starts, src, offset) {
   if (text.endsWith('\r')) text = text.slice(0, -1);
   return {
     line: lo + 1,            // 1-based
+    // col in UTF-16 code units: a JS string index into `text`, used by the
+    // highlight math. bcol in bytes: what gets printed — vim's grepformat %c
+    // 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
     text,
   };
 }
@@ -296,10 +344,18 @@ function lineTextAt(starts, src, lineNo) {
   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
@@ -478,7 +534,7 @@ 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 body = m
@@ -510,10 +566,11 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
   const cap = Math.min(opts.maxCount || Infinity, limit);
   const limited = Number.isFinite(cap) ? matches.slice(0, cap) : matches;
   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);
@@ -534,6 +591,10 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
     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
@@ -545,18 +606,20 @@ function searchSource(src, name, showLabel, opts, out, limit = Infinity) {
       out.push(JSON.stringify({
         file: name,
         line: pos.line,
-        col: pos.col,
+        col: pos.bcol,
         html: src.slice(off, nodeEnd),
         text: collapseWs(textOf(el)),
       }));
     }
-    return limited.length;
+    return targets.length;
   }
+  let emitted = 0;
   for (const el of targets) {
     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.
       out.push(prettyPrint(el, originsByTarget.get(el), opts), ''); // blank separator
+      emitted++;
       continue;
     }
     const off = el.startIndex == null ? 0 : el.startIndex;
@@ -586,35 +649,53 @@ 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);
+    emitted++;
   }
-  return limited.length;
+  return emitted;
 }
 
 // Translate a glob to a regex body. `*` matches within a path segment, `**`
-// across segments, `?` a single non-slash char; everything else is literal.
+// across segments, `?` a single non-slash char, `{a,b,c}` alternation; every
+// other char is literal.
 function globToRegex(glob) {
   let re = '';
+  let depth = 0;                            // open `{` alternation groups
   for (let i = 0; i < glob.length; i++) {
     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 += '[^/]*';
       }
     } else if (c === '?') {
       re += '[^/]';
-    } else if (/[.+^${}()|[\]\\]/.test(c)) {
+    } else if (c === '{') {
+      re += '(';
+      depth++;
+    } else if (c === '}' && depth > 0) {
+      re += ')';
+      depth--;
+    } else if (c === ',' && depth > 0) {
+      re += '|';
+    } else if (/[.+^$()|[\]\\]/.test(c)) {  // note: { } handled above
       re += '\\' + c;
     } else {
       re += c;
     }
   }
+  while (depth-- > 0) re += ')';            // close any unbalanced `{`
   return re;
 }
 
@@ -631,37 +712,87 @@ function compileIgnore(pattern) {
   return { re, dirOnly, hasSlash };
 }
 
-function isIgnored(name, full, isDir, matchers) {
+// True if name/path matches any compiled glob matcher (shared by --ignore/
+// --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) {
+// `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 });
   } catch (e) {
-    process.stderr.write(`cssgrep: ${dir}: ${e.code || e.message}\n`);
+    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();
-    if (opts.ignore.length && isIgnored(e.name, full, isDir, opts.ignore)) continue;
+    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) {
-      yield* walk(full, opts);
-    } else if (e.isFile()) {
-      const ext = path.extname(e.name).slice(1).toLowerCase();
-      if (opts.exts.includes(ext)) yield full;
+      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, 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;
+      } else {
+        const ext = path.extname(e.name).slice(1).toLowerCase();
+        if (opts.exts.includes(ext)) yield full;
+      }
     }
   }
 }
 
 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
+// is a decisive binary signal; failing that, a high ratio of non-text control
+// bytes flags binary content that happens to lack NULs. HTML is text, so binary
+// files are never worth parsing and are skipped. (stat() can't tell us this —
+// only the bytes can.)
+const BINARY_SNIFF_BYTES = 8192;
+function looksBinary(buf) {
+  const n = Math.min(buf.length, BINARY_SNIFF_BYTES);
+  let suspicious = 0;
+  for (let i = 0; i < n; i++) {
+    const b = buf[i];
+    if (b === 0) return true;                       // NUL: definitely binary
+    if (b < 9 || (b > 13 && b < 32)) suspicious++;  // control char (not \t\n\v\f\r)
+  }
+  return n > 0 && suspicious / n > 0.3;
 }
 
 function main() {
@@ -676,7 +807,7 @@ function main() {
     const targets = opts.paths.length ? opts.paths : ['.'];
     for (const p of targets) {
       const st = fs.statSync(p, { throwIfNoEntry: false });
-      if (!st) { process.stderr.write(`cssgrep: ${p}: no such file or directory\n`); continue; }
+      if (!st) { if (!opts.noMessages) process.stderr.write(`cssgrep: ${p}: no such file or directory\n`); continue; }
       if (st.isDirectory()) files.push(...walk(p, opts));
       else files.push(p);
     }
@@ -686,8 +817,11 @@ function main() {
     useStdin = true;
   }
 
-  // A label (file prefix) is shown when searching more than one file.
-  const showLabel = !useStdin && files.length > 1;
+  // 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
+    : (!useStdin && files.length > 1);
 
   const out = [];
   let total = 0;
@@ -697,18 +831,31 @@ function main() {
 
   try {
     if (useStdin) {
-      total += searchSource(readStdin(), '(standard input)', false, opts, out, room());
+      const buf = readStdin();
+      if (looksBinary(buf)) {
+        if (!opts.noMessages && !opts.quiet) {
+          process.stderr.write('cssgrep: (standard input): binary input (skipped)\n');
+        }
+      } else {
+        total += searchSource(buf.toString('utf8'), '(standard input)', showLabel, opts, out, room());
+      }
     } else {
       for (const f of files) {
         if (room() <= 0) break;               // -M: global budget exhausted
-        let src;
+        let buf;
         try {
-          src = fs.readFileSync(f, 'utf8');
+          buf = fs.readFileSync(f);           // Buffer: sniff before decoding
         } catch (e) {
-          process.stderr.write(`cssgrep: ${f}: ${e.code || e.message}\n`);
+          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(src, f, showLabel, opts, out, room());
+        total += searchSource(buf.toString('utf8'), f, showLabel, opts, out, room());
         if (opts.quiet && total > 0) break;   // -q: first match decides the status
       }
     }
@@ -731,8 +878,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();

package/man/cssgrep.1

@@ -1,6 +1,6 @@
 .\" Man page for cssgrep. Keep the OPTIONS section in sync with the USAGE
 .\" string in index.js.
-.TH CSSGREP 1 "2026-06-29" "cssgrep 1.0.0" "User Commands"
+.TH CSSGREP 1 "2026-07-02" "cssgrep 1.2.0" "User Commands"
 .SH NAME
 cssgrep \- search HTML by CSS selector, grep-style
 .SH SYNOPSIS
@@ -33,7 +33,13 @@ Input is read from the
 .I file
 arguments, recursively from directories with
 .BR \-r ,
-or from standard input when no path is given. One line is printed per match.
+or from standard input when no path is given. Binary input, including standard
+input (a NUL byte or a high ratio of control bytes in the first 8 KB), is
+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
@@ -48,17 +54,35 @@ locator appears only with
 Recurse into directory arguments (defaults to the current directory if none
 are given).
 .TP
+.BI \-\-max\-depth " n"
+Limit
+.B \-r
+recursion depth.
+.I 1
+means the given directory only (no subdirectories).
+.TP
 .BI \-\-ext " list"
 Comma-separated extensions to scan with
 .B \-r
 (default:
 .IR html,htm ).
 .TP
+.BI \-\-include " glob"
+Only search files whose name/path matches
+.I glob
+while recursing (repeatable). Replaces
+.BR \-\-ext ;
+the two cannot be combined.
+.TP
 .BR \-i ", " \-\-ignore " \fIglob\fR"
 Skip files/dirs matching
 .I glob
 while recursing (repeatable).
 .TP
+.BI \-\-exclude " glob"
+Alias for
+.BR \-\-ignore .
+.TP
 .BI \-\-ignore\-file " path"
 Read ignore globs from
 .IR path ,
@@ -67,10 +91,21 @@ one per line
 comments and blank lines ignored), like a
 .IR .gitignore .
 .TP
+.BR \-S ", " \-\-follow
+Follow symbolic links while recursing with
+.B \-r
+(they are skipped by default). Each physical directory is visited once, so
+symlink cycles are safe.
+.TP
 .BR \-n ", " \-\-line\-number
 Prefix each match with its
 .IR line : col
-locator. Excludes
+locator. The column counts bytes (what vim's
+.B grepformat
+.I %c
+expects), pointing at the opening
+.B <
+of the matched tag. Excludes
 .B \-c
 and
 .BR \-p .
@@ -83,7 +118,8 @@ locator is shown.
 .BI \-\-attr " name"
 Print the value of attribute
 .I name
-for each match (nodes without it are skipped).
+for each match (nodes without it are skipped; if every match is skipped the
+exit status is 1). The name is matched case-insensitively.
 .TP
 .B \-\-text
 Print the matched node's text content, whitespace collapsed.
@@ -125,10 +161,17 @@ matches per file.
 .BR \-M ", " \-\-max\-total " \fIn\fR"
 Stop after
 .I n
-matches in total across all files.
+matches in total across all files. The budget counts matches, not files;
+combined with
+.B \-l
+or
+.B \-L
+scanning stops once the budget is spent, which can cut the file list short.
 .TP
 .BR \-c ", " \-\-count
-Print only a count of matches (per file when relevant).
+Print only a count of matches (per file when relevant). Files with no match
+report a zero count, as in
+.BR grep .
 .TP
 .BR \-l ", " \-\-files\-with\-matches
 Print only the names of files that have a match.
@@ -139,10 +182,19 @@ Print only the names of files with no match.
 .BR \-q ", " \-\-quiet
 Print nothing; exit 0 on the first match, 1 if none.
 .TP
+.BR \-s ", " \-\-no\-messages
+Suppress error messages for unreadable or missing files.
+.TP
 .BR \-0 ", " \-\-null
 Separate the file name with a NUL byte (for
 .BR "xargs \-0" ).
 .TP
+.BR \-H ", " \-\-with\-filename
+Always print the file name prefix, even for a single file or standard input.
+.TP
+.B \-\-no\-filename
+Never print the file name prefix, even when searching multiple files.
+.TP
 .BR \-\-color [ =\fIwhen\fR ]
 Colorize output:
 .I auto
@@ -151,7 +203,12 @@ Colorize output:
 A bare
 .B \-\-color
 means
-.IR always .
+.IR auto ,
+as in
+.BR grep ;
+use
+.B \-\-color=always
+to force color into a pipe.
 .TP
 .BR \-h ", " \-\-help
 Show help and exit.
@@ -169,6 +226,12 @@ Long options take a value with
 .B =
 or as the next word
 .RB ( \-\-max\-width=100 ", " "\-\-ext htm" ).
+.PP
+Globs for
+.BR \-\-include ", " \-\-ignore ", and " \-\-exclude
+support
+.BR * " (within a path segment), " ** " (across " / ),
+.BR ? " (one non-slash char), and brace alternation like " *.{html,htm} .
 .SH EXIT STATUS
 .TP
 .B 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cssgrep",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Search HTML by CSS selector and print matches grep-style (file:line:col with -n).",
   "main": "index.js",
   "bin": {
@@ -10,6 +10,7 @@
   "files": [
     "index.js",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "man/cssgrep.1",
     "completions/"