@gustcss/vite 0.10.0 → 0.11.0

package/README.md

@@ -70,12 +70,39 @@ Create `gustcss.config.json` in your project root:
 }
 ```
 
+### Dev-Server Linting
+
+Set `lint` to report class names that generate no CSS while the dev server runs.
+The plugin runs `gustcss lint --json` on startup and after source changes, and
+prints the diagnostics through the Vite logger.
+The lint process runs asynchronously: at most one runs at a time, changes that
+arrive while it runs are coalesced into a single follow-up run, and unchanged
+results are not printed twice. Lint problems never stop the dev server, and the
+child process is killed when the server closes.
+
+```javascript
+export default defineConfig({
+  plugins: [gustcss({ lint: true })],
+})
+```
+
+Pass `{ strict: true }` to also report custom-looking classes and low-confidence
+extractions (`gustcss lint --strict`).
+
+The same check runs on demand with the CLI (`gustcss lint`), which is what CI
+should use. See the CLI documentation for rules, configuration, and baselines.
+
 ### Production Class-Name Mangling
 
 Enable `mangleClassNames` to shorten generated selectors and matching source references during `vite build`.
 
 Development mode keeps readable class names.
 
+The mangler also rewrites class literals passed to the class-composition helpers `cn`, `cx`, `clsx`, `classNames`, `cva`, `tv`, `twMerge`, and `twJoin` (the same default list the CLI scanner extracts class names from).
+Variant helpers (`cva`, `tv`) keep their object keys untouched, because those keys are variant names, not classes. For `clsx`-style helpers the quoted object keys are classes and are rewritten.
+
+A class reference the mangler cannot rewrite stops the build: an aliased helper (`import { cn as merge }`), an unquoted `clsx` object key, or a mapped class inside an unknown string. Add the class to `mangleExclude` or move the reference to a static string when the build reports one of those errors.
+
 ```javascript
 export default defineConfig({
   plugins: [
@@ -92,15 +119,30 @@ The manifest defaults to `<output>.classes.json`; set `mangleMap` to use another
 
 Treat the manifest as generated output and ignore it in Git unless your workflow intentionally pins class mappings.
 
-The transformer supports HTML, JavaScript, TypeScript, JSX, and TSX. It rewrites static `class` and `className` attributes, static template segments, direct string arguments to `classList`, and `setAttribute('class', ...)`. Code examples inside HTML `<code>` and `<pre>` bodies are neither rewritten nor inspected; classes on the elements themselves are still rewritten. An unclosed `<code>` or `<pre>` fails the build instead of masking the remainder of the document.
+The transformer supports HTML, JavaScript, TypeScript, JSX, TSX, and Astro. It rewrites static `class` and `className` attributes, static template segments, direct string arguments to `classList`, and `setAttribute('class', ...)`. Code examples inside HTML `<code>` and `<pre>` bodies are neither rewritten nor inspected; classes on the elements themselves are still rewritten. An unclosed `<code>` or `<pre>` fails the build instead of masking the remainder of the document.
+
+**Astro templates** (`.astro`) are rewritten before the Astro compiler sees them. Astro's own Vite plugins run ahead of user plugins, so the rewrite happens in the plugin's `load` hook on the raw source, guided by the AST that `parse()` from `@astrojs/compiler` returns (the package ships with astro, so nothing extra has to be installed). Attribute kinds, the frontmatter, comments, `<style>` and `<script>` blocks are taken from that AST.
+
+**Rewritten:**
+- Static `class="…"` attributes and `class={"…"}` expressions that consist of a single string literal
+- `class:list` array elements (including the right operand of `cond && "flex"`) and quoted object keys, nested arrays and objects included
+- `classList.add("…")` / `setAttribute("class", "…")` calls in the frontmatter and in `<script>` blocks
+
+**Fail-closed** (the build stops when a mapped class appears in one of these places):
+- Any `class` expression other than a single string literal, such as `class={cond ? "flex" : "x"}` or `` class={`flex ${x}`} ``
+- Inside `class:list`: unquoted keys (`{ flex: on }`), shorthand properties (`{ hidden }`), template literals, comparison operands (`variant === "flex"`), subscripts (`map["flex"]`), function calls, method chains, or an expression that is not an array/object literal
+- Component props other than `class` / `class:list` (`<Card klass="flex" />`), `set:html` / `set:text` values, strings inside `{}` expressions (`{JSON.stringify("flex")}`), and ambiguous strings in the frontmatter or `<script>`. A `class` or `class:list` passed to a component is rewritten as a static value, like JSX `className`; forward `Astro.props.class` unchanged on the receiving side
+- `<style>` selectors (`.flex`, `@scope (.flex)`, `[class~="flex"]`); add hand-written selectors such as `.sr-only { … }` to `mangleExclude`
+
+HTML comments, `<code>` / `<pre>` bodies, ordinary non-class attributes (`<input type="flex">`) and `<style>` declarations (`border: 1px solid`) are neither rewritten nor inspected.
 
-JavaScript, TypeScript, JSX, and TSX transforms emit Source Map v3 mappings back to the original source. Comments and ordinary strings containing `class="..."` are not treated as JSX attributes. An ordinary string that still references a mapped class fails closed as ambiguous.
+JavaScript, TypeScript, JSX, TSX, and Astro frontmatter transforms emit Source Map v3 mappings back to the original source. Comments and ordinary strings containing `class="..."` are not treated as JSX attributes. An ordinary string that still references a mapped class fails closed as ambiguous.
 
 Conditional expressions, nested calls, selectors, and other ambiguous references fail the build. The plugin restores readable CSS after a failed transform.
 
 Add dynamically or externally referenced class names, including production E2E selectors, to `mangleExclude`.
 
-Vue, Astro, and Svelte templates are not supported by this option yet. A mapped class in one of these files fails the build instead of emitting mismatched output.
+Vue and Svelte templates are not supported by this option. A mapped class in one of these files fails the build instead of emitting mismatched output.
 
 Files under `node_modules` are neither rewritten nor inspected.