cssgrep 1.1.0 → 1.3.0

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-07-02" "cssgrep 1.1.0" "User Commands"
+.\" string in cli.js.
+.TH CSSGREP 1 "2026-07-07" "cssgrep 1.3.0" "User Commands"
 .SH NAME
 cssgrep \- search HTML by CSS selector, grep-style
 .SH SYNOPSIS
@@ -13,6 +13,13 @@ cssgrep \- search HTML by CSS selector, grep-style
 .B \-r
 .IR dir ...
 .br
+.B cssgrep
+.B \-e
+.RI \(aq[ label =] sel \(aq
+.RB [ \-e
+\&...]
+.RI [ file ...]
+.br
 .B cat
 .I file.html
 | \fBcssgrep\fR \fIselector\fR
@@ -33,9 +40,9 @@ Input is read from the
 .I file
 arguments, recursively from directories with
 .BR \-r ,
-or from standard input when no path is given. Binary files (a NUL byte or a
-high ratio of control bytes in the first 8 KB) are skipped with a note on
-standard error, suppressible with
+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 .
@@ -50,6 +57,31 @@ locator appears only with
 .BR \-n .
 .SH OPTIONS
 .TP
+.BR \-e ", " \-\-selector " [\fIlabel\fR=]\fIsel\fR"
+Add a selector (repeatable). Matches from all
+.B \-e
+selectors merge into one document-order stream, each tagged
+.RI [ label ]
+in the output (and as a
+.I label
+field with
+.BR \-\-json ).
+An unlabeled selector is tagged with its own text. A label is an identifier
+before a
+.BR = ;
+a
+.B =
+outside brackets is never valid CSS, so attribute selectors like
+.I [href=x]
+are never mistaken for labels.
+.B \-m
+and
+.B \-M
+cap the merged stream, and print modes apply to every selector alike. With
+.BR \-e ,
+every positional argument is a file path, as with
+.BR "grep \-e" .
+.TP
 .BR \-r ", " \-\-recursive
 Recurse into directory arguments (defaults to the current directory if none
 are given).
@@ -91,10 +123,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 .
@@ -107,14 +150,19 @@ 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.
 .TP
 .B \-\-json
 Print one JSON object per match (NDJSON) with
-.IR file ", " line ", " col ", " html ", " text .
+.IR file ", " line ", " col ", " html ", " text
+(plus
+.I label
+with
+.BR \-e ).
 .TP
 .BI \-\-parent " n"
 Report the
@@ -149,10 +197,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.
@@ -184,7 +239,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.
@@ -208,10 +268,94 @@ Globs for
 support
 .BR * " (within a path segment), " ** " (across " / ),
 .BR ? " (one non-slash char), and brace alternation like " *.{html,htm} .
+.SH WATCH MODE
+.TP
+.B \-\-watch
+Keep running and repeat the search whenever a watched file changes. Requires
+file or directory arguments (standard input cannot be watched); cannot be
+combined with
+.B \-q
+or the rewrite operations. Runs until interrupted; Ctrl-C exits with
+status 0, like
+.BR watch (1).
+.TP
+.B \-\-no\-clear
+With
+.B \-\-watch
+on a terminal: append run results instead of clearing the screen.
+.PP
+Output adapts to its destination, like
+.BR \-\-color=auto :
+on a terminal each run clears the screen and reprints; piped output contains
+no escape codes and appends each run after a
+.RI \(dq== " HH:MM:SS changed-file " ==\(dq
+separator; with
+.B \-\-json
+each rerun emits an NDJSON
+.I {"event":"run","changed":...,"matches":n}
+record followed by the match records.
+.PP
+Every rerun repeats the full directory walk, so new files are discovered (and
+deleted ones dropped) under the same
+.BR \-\-include / \-\-ignore / \-\-ext
+rules as a fresh invocation; change bursts are debounced. Watching uses the
+operating system's native file events (no polling), which may be unreliable
+on network or virtual filesystems.
+.SH REWRITING
+Five repeatable, freely combinable operations edit the matched elements
+instead of reporting them:
+.TP
+.BI \-\-add\-class " c"
+Add a class to each matched element (deduplicated; attribute created if
+missing).
+.TP
+.BI \-\-remove\-class " c"
+Remove a class; the attribute is dropped when emptied.
+.TP
+.BI \-\-set\-attr " k=v"
+Set attribute
+.I k
+to
+.IR v ,
+adding it if missing. The value is escaped.
+.TP
+.BI \-\-remove\-attr " k"
+Remove attribute
+.I k
+(all source occurrences).
+.TP
+.BI \-\-rename\-tag " t"
+Rename the element \(em its closing tag too, when one explicitly exists
+(voids like
+.IR <img> ,
+self-closing and implied closes are left without one).
+.TP
+.B \-\-diff
+Emit a unified diff instead of the rewritten document. Required for multiple
+files; apply with
+.BR git-apply (1)
+or
+.BR patch (1).
+.PP
+Only the matched tags' bytes change: matching runs once against the original
+document and edits are byte-splices, so quoting, entities and formatting
+everywhere else pass through untouched. Operations compose in a fixed order
+\(em rename \(-> remove-attr \(-> set-attr \(-> remove-class \(-> add-class
+\(em regardless of argument order.
+.B \-\-parent
+composes with rewriting. A single input prints the rewritten document to
+standard output;
+.B cssgrep
+never writes a file. Input that is not valid UTF-8 is refused (exit 2).
+Rewriting cannot be combined with
+.BR \-n ", " \-p ", " \-\-attr ", " \-\-text ", " \-\-json ", " \-c ", "
+.BR \-l ", " \-L ", " \-q ", " \-A / \-B / \-C ", " \-m / \-M ", " \-w ", "
+.BR \-0 " or " \-e .
+Exit status: 0 if anything was edited, 1 if nothing matched, 2 on error.
 .SH EXIT STATUS
 .TP
 .B 0
-One or more matches were found.
+One or more matches were found (or, when rewriting, edits were made).
 .TP
 .B 1
 No matches were found.
@@ -231,6 +375,31 @@ Recurse a tree, skipping vendored files:
 .TP
 Extract attribute values for scripting:
 .B cssgrep \-\-attr href "a.external" page.html
+.TP
+Scrape several labeled fields in one pass:
+.B cssgrep \-e "title=h1" \-e "price=.card .price" \-\-json page.html
+.TP
+Rename every <b> to <strong> across a tree, review, then apply:
+.B cssgrep b \-\-rename\-tag strong \-r src/ \-\-diff | git apply
+.SH INVERTING MATCHES
+There is no
+.B \-v
+flag: CSS expresses inversion in the selector itself via
+.BR :not() " (complex selectors and selector lists included) and " :has() ,
+scoped to the elements of interest \(em a flag would have to invent its own
+answer to \(lqwhich non-matching elements?\(rq.
+.TP
+Images missing alt text:
+.B cssgrep \(dqimg:not([alt])\(dq \-rn .
+.TP
+Cards containing no link:
+.B cssgrep \(dqdiv.card:not(:has(a))\(dq page.html
+.TP
+Links outside nav and footer:
+.B cssgrep \(dqa:not(nav a, footer a)\(dq page.html
+.PP
+For whole files without any match, use
+.BR \-L .
 .SH VIM INTEGRATION
 Wire
 .B cssgrep

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "cssgrep",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Search HTML by CSS selector and print matches grep-style (file:line:col with -n).",
-  "main": "index.js",
+  "main": "lib.js",
+  "types": "index.d.ts",
   "bin": {
-    "cssgrep": "index.js"
+    "cssgrep": "cli.js"
   },
   "man": "./man/cssgrep.1",
   "files": [
-    "index.js",
+    "lib.js",
+    "cli.js",
+    "index.d.ts",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
@@ -28,11 +31,11 @@
   "homepage": "https://github.com/msbatarce/cssgrep#readme",
   "scripts": {
     "test": "node test.js",
-    "build:linux-x64": "bun build ./index.js --compile --target=bun-linux-x64 --outfile dist/cssgrep-linux-x64",
-    "build:linux-arm64": "bun build ./index.js --compile --target=bun-linux-arm64 --outfile dist/cssgrep-linux-arm64",
-    "build:darwin-x64": "bun build ./index.js --compile --target=bun-darwin-x64 --outfile dist/cssgrep-darwin-x64",
-    "build:darwin-arm64": "bun build ./index.js --compile --target=bun-darwin-arm64 --outfile dist/cssgrep-darwin-arm64",
-    "build:windows-x64": "bun build ./index.js --compile --target=bun-windows-x64 --outfile dist/cssgrep-windows-x64.exe",
+    "build:linux-x64": "bun build ./cli.js --compile --target=bun-linux-x64 --outfile dist/cssgrep-linux-x64",
+    "build:linux-arm64": "bun build ./cli.js --compile --target=bun-linux-arm64 --outfile dist/cssgrep-linux-arm64",
+    "build:darwin-x64": "bun build ./cli.js --compile --target=bun-darwin-x64 --outfile dist/cssgrep-darwin-x64",
+    "build:darwin-arm64": "bun build ./cli.js --compile --target=bun-darwin-arm64 --outfile dist/cssgrep-darwin-arm64",
+    "build:windows-x64": "bun build ./cli.js --compile --target=bun-windows-x64 --outfile dist/cssgrep-windows-x64.exe",
     "build:binaries": "npm run build:linux-x64 && npm run build:linux-arm64 && npm run build:darwin-x64 && npm run build:darwin-arm64 && npm run build:windows-x64",
     "build:sea": "node scripts/build-sea.js"
   },