@gustcss/vite 0.10.1 → 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: [

package/dist/index.cjs

@@ -173,6 +173,105 @@ const SUPPORTED_SOURCE = /\.(?:[cm]?[jt]sx?|html)(?:$|\?)/;
 const HTML_SOURCE = /\.html(?:$|\?)/;
 const UNSUPPORTED_FRAMEWORK_SOURCE = /\.(?:vue|svelte)(?:$|\?)/;
 const DEPENDENCY_SOURCE = /(?:^|[\\/])node_modules[\\/]/;
+const CLASS_FUNCTION_NAMES = [
+	"cn",
+	"cx",
+	"clsx",
+	"classNames",
+	"cva",
+	"tv",
+	"twMerge",
+	"twJoin"
+];
+const CLASS_FUNCTION_CALL = new RegExp(`(?<![\\w$])(${CLASS_FUNCTION_NAMES.join("|")})\\s*\\(`, "g");
+const VARIANT_FUNCTION_NAMES = /* @__PURE__ */ new Set(["cva", "tv"]);
+const NESTED_CALL = /(?:^|[^\w$])([A-Za-z_$][\w$]*)\s*\(/g;
+function nestedCallRanges(args) {
+	const ranges = [];
+	NESTED_CALL.lastIndex = 0;
+	let match;
+	while ((match = NESTED_CALL.exec(args)) !== null) {
+		const open = args.indexOf("(", match.index + match[0].length - 1);
+		if (open < 0) continue;
+		const end = findBalancedEnd(args, open, "(", ")");
+		if (end < 0) continue;
+		ranges.push({
+			start: match.index,
+			end: end + 1,
+			isHelper: CLASS_FUNCTION_NAMES.includes(match[1])
+		});
+		NESTED_CALL.lastIndex = open + 1;
+	}
+	return ranges;
+}
+function innermostCallAt(ranges, index) {
+	let found = null;
+	for (const range of ranges) if (index >= range.start && index < range.end) {
+		if (found === null || range.start > found.start) found = range;
+	}
+	return found;
+}
+function parenDepthAt(value, index) {
+	let depth = 0;
+	for (let i = 0; i < index; i += 1) if (value[i] === "(") depth += 1;
+	else if (value[i] === ")") depth -= 1;
+	return depth;
+}
+function isComparisonOperand(args, segment) {
+	let before = segment.start - 1;
+	while (before >= 0 && /\s/.test(args[before])) before -= 1;
+	const lead = before >= 1 ? args.slice(before - 1, before + 1) : "";
+	if (lead === "==" || lead === "!=" || before >= 1 && args[before] === "=") return true;
+	let after = segment.end;
+	while (after < args.length && /\s/.test(args[after])) after += 1;
+	const tail = args.slice(after, after + 2);
+	return tail === "==" || tail === "!=";
+}
+function defaultVariantsRanges(args) {
+	const ranges = [];
+	const pattern = /defaultVariants\s*:\s*\{/g;
+	let match;
+	while ((match = pattern.exec(args)) !== null) {
+		const open = args.indexOf("{", match.index);
+		const end = findBalancedEnd(args, open, "{", "}");
+		if (end < 0) break;
+		ranges.push([open, end + 1]);
+		pattern.lastIndex = end;
+	}
+	return ranges;
+}
+function inRanges(ranges, index) {
+	return ranges.some(([start, end]) => index >= start && index < end);
+}
+function maskIgnoredRanges(text, origins, ranges) {
+	if (ranges.length === 0) return text;
+	const chars = text.split("");
+	let sorted = [...ranges].sort((a, b) => a[0] - b[0]);
+	let cursor = 0;
+	for (let i = 0; i < chars.length && cursor < sorted.length; i += 1) {
+		const origin = origins[i];
+		while (cursor < sorted.length && origin >= sorted[cursor][1]) cursor += 1;
+		if (cursor >= sorted.length) break;
+		if (origin >= sorted[cursor][0] && origin < sorted[cursor][1]) {
+			if (chars[i] !== "\n") chars[i] = " ";
+		}
+	}
+	return chars.join("");
+}
+function stripObjectKeys(value) {
+	return value.replace(/([{,]\s*)([A-Za-z_$][\w$]*)(\s*:)/g, (_match, lead, name, tail) => {
+		return lead + " ".repeat(name.length) + tail;
+	});
+}
+function isObjectKey(args, segment) {
+	let before = segment.start - 1;
+	while (before >= 0 && /\s/.test(args[before])) before -= 1;
+	const lead = before >= 0 ? args[before] : "";
+	if (lead !== "{" && lead !== ",") return false;
+	let after = segment.end;
+	while (after < args.length && /\s/.test(args[after])) after += 1;
+	return args[after] === ":";
+}
 function hasOwn(classes, token) {
 	return Object.hasOwn(classes, token);
 }
@@ -522,6 +621,44 @@ function collectClassListCallEdits(code, structure, classes, id, edits) {
 		pattern.lastIndex = end;
 	}
 }
+function collectClassFunctionCallEdits(code, structure, classes, id, edits, ignores) {
+	CLASS_FUNCTION_CALL.lastIndex = 0;
+	let match;
+	while ((match = CLASS_FUNCTION_CALL.exec(structure)) !== null) {
+		const name = match[1];
+		const open = code.indexOf("(", match.index + name.length);
+		if (open < 0) continue;
+		const end = findBalancedEnd(code, open, "(", ")");
+		if (end < 0) throw new Error(`[gustcss] incomplete ${name}(...) call in ${id}. Ensure the expression is properly closed.`);
+		const args = code.slice(open + 1, end - 1);
+		const argsStart = open + 1;
+		const skipKeys = VARIANT_FUNCTION_NAMES.has(name);
+		const skipRanges = skipKeys ? defaultVariantsRanges(args) : [];
+		const nestedCalls = nestedCallRanges(args);
+		const depthSource = stripQuotedSegments(args);
+		scanQuotedSegments(args, (segment) => {
+			const { start, quote, contents } = segment;
+			const nested = innermostCallAt(nestedCalls, start);
+			if (!(nested !== null && nested.isHelper) && parenDepthAt(depthSource, start) > 0) return;
+			if (skipKeys && quote !== "`" && isObjectKey(args, segment) || inRanges(skipRanges, segment.start) || isComparisonOperand(args, segment)) {
+				ignores.push([argsStart + segment.start, argsStart + segment.end]);
+				return;
+			}
+			const offset = argsStart + start + 1;
+			if (quote === "`") {
+				collectTemplateBodyEdits(contents, classes, offset, edits);
+				return;
+			}
+			collectClassListEdits(contents, classes, offset, edits);
+		});
+		let withoutStrings = stripQuotedSegments(args);
+		if (skipKeys) withoutStrings = stripObjectKeys(withoutStrings);
+		for (const [rangeStart, rangeEnd] of skipRanges) withoutStrings = withoutStrings.slice(0, rangeStart) + " ".repeat(rangeEnd - rangeStart) + withoutStrings.slice(rangeEnd);
+		const dynamic = findMappedToken(withoutStrings, classes);
+		if (dynamic) throw new Error(`[gustcss] mapped class "${dynamic}" remains in a dynamic argument of ${name}(...) in ${id}. Pass it as a direct string literal, or add it to mangleExclude.`);
+		CLASS_FUNCTION_CALL.lastIndex = end;
+	}
+}
 function rejectDynamicSetAttributeCalls(code, structure, classes, id) {
 	const pattern = /\.setAttribute\s*\(/g;
 	let match;
@@ -604,6 +741,7 @@ function sourcesForFile(code, id) {
 }
 function collectEdits(code, classes, id) {
 	const edits = [];
+	const ignores = [];
 	const sources = sourcesForFile(code, id);
 	const commentRanges = [];
 	let commentIndex = 0;
@@ -640,15 +778,23 @@ function collectEdits(code, classes, id) {
 		collectTemplateBodyEdits(match[2], classes, match.index + match[1].length, edits);
 	}
 	collectClassListCallEdits(code, sources.structure, classes, id, edits);
+	collectClassFunctionCallEdits(code, sources.structure, classes, id, edits, ignores);
 	const setAttributePattern = /(\.setAttribute\(\s*["']class["']\s*,\s*)(["'])([\s\S]*?)(\2)(\s*\))/g;
 	while ((match = setAttributePattern.exec(code)) !== null) {
 		if (sources.structure[match.index] === " ") continue;
 		collectClassListEdits(match[3], classes, match.index + match[1].length + 1, edits);
 	}
-	return edits;
+	return {
+		edits,
+		ignores
+	};
 }
 function collectRecognizedContextEdits(code, classes, id) {
-	return applyEdits(code, collectEdits(code, classes, id));
+	const collected = collectEdits(code, classes, id);
+	return {
+		...applyEdits(code, collected.edits),
+		ignores: collected.ignores
+	};
 }
 /**
 * Collect the rewrites for a source fragment (TypeScript frontmatter, an inline
@@ -657,15 +803,17 @@ function collectRecognizedContextEdits(code, classes, id) {
 * them inside a larger document.
 */
 function collectFragmentEdits(code, classes, id) {
-	const edits = collectEdits(code, classes, id);
-	const rewritten = applyEdits(code, edits).code;
+	const collected = collectEdits(code, classes, id);
+	const applied = applyEdits(code, collected.edits);
+	const rewritten = applied.code;
 	const sources = sourcesForFile(rewritten, id);
+	const inspection = maskIgnoredRanges(sources.inspection, applied.origins, collected.ignores);
 	rejectDynamicSetAttributeCalls(rewritten, sources.structure, classes, id);
 	rejectDynamicClassNameAssignments(rewritten, sources.structure, classes, id);
 	rejectAmbiguousClassExpressions(rewritten, sources.structure, classes, id);
-	const ambiguous = findMappedInQuotedSegments(sources.inspection, classes);
+	const ambiguous = findMappedInQuotedSegments(inspection, classes);
 	if (ambiguous) throw new Error(`[gustcss] mapped class "${ambiguous}" remains in an ambiguous string in ${id}. Move it to a static class/className or classList context, or add it to mangleExclude.`);
-	return edits;
+	return collected.edits;
 }
 const BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 function encodeVLQ(value) {
@@ -733,13 +881,14 @@ function transformSource(code, classes, id) {
 	const transformed = collectRecognizedContextEdits(code, classes, id);
 	const rewritten = transformed.code;
 	const sources = sourcesForFile(rewritten, id);
+	const inspection = maskIgnoredRanges(sources.inspection, transformed.origins, transformed.ignores);
 	rejectDynamicSetAttributeCalls(rewritten, sources.structure, classes, id);
 	rejectDynamicClassNameAssignments(rewritten, sources.structure, classes, id);
 	rejectAmbiguousClassExpressions(rewritten, sources.structure, classes, id);
 	return {
 		code: rewritten,
 		map: createSourceMap(code, rewritten, transformed.origins, id),
-		inspection: sources.inspection
+		inspection
 	};
 }
 function findAmbiguousMappedClass(code, classes) {
@@ -1174,6 +1323,7 @@ function createAstroTransformer({ parse, classes }) {
 * designed for build-time use only and should not process untrusted input.
 */
 const ASTRO_SOURCE = /\.astro(?:$|\?)/;
+const lintDebounceMs = 300;
 const ASTRO_MODULE = /^[^\0?]*\.astro$/;
 /**
 * Resolve @astrojs/compiler parse function from the project.
@@ -1191,12 +1341,156 @@ async function resolveAstroCompiler(root) {
 	} catch {}
 	return null;
 }
+/**
+* Vite logger へ出力する。テストなど logger が無い環境では console を使う。
+*/
+function lintLogger(server) {
+	const logger = server?.config?.logger;
+	return {
+		warn: (message) => logger?.warn ? logger.warn(message) : console.warn(message),
+		error: (message) => logger?.error ? logger.error(message) : console.error(message)
+	};
+}
+/**
+* Dev-server lint runner.
+*
+* Runs `gustcss lint --json` asynchronously and reports the diagnostics through
+* the logger. At most one lint process runs at a time; changes that arrive while
+* it runs are coalesced into one follow-up run. This keeps the dev server's
+* event loop free even on large projects.
+*/
+function createLintRunner({ cwd, binaryPath, configPath, logger, strict }) {
+	const maxOutput = 4194304;
+	const timeoutMs = 15e3;
+	let child = null;
+	let running = false;
+	let dirty = false;
+	let closed = false;
+	let lastSignature = null;
+	function report(code, stdout, stderr, aborted) {
+		if (aborted) return;
+		if (code !== 0 && code !== 1) {
+			logger.warn(`[gustcss] lint could not run: ${stderr.trim()}`);
+			return;
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(stdout);
+		} catch {
+			logger.warn("[gustcss] lint output was not JSON");
+			return;
+		}
+		const diagnostics = Array.isArray(parsed?.diagnostics) ? parsed.diagnostics : [];
+		const signature = JSON.stringify(diagnostics.map((d) => [
+			d.file,
+			d.line,
+			d.column,
+			d.ruleId,
+			d.severity,
+			d.class,
+			d.message
+		]));
+		if (signature === lastSignature) return;
+		lastSignature = signature;
+		for (const d of diagnostics) {
+			const text = `[gustcss] ${d.line ? `${d.file}:${d.line}:${d.column}` : d.file} ${d.ruleId}: ${d.message}`;
+			if (d.severity === "error") logger.error(text);
+			else logger.warn(text);
+		}
+		const suppressed = parsed?.summary?.suppressed ?? 0;
+		if (diagnostics.length > 0 && suppressed > 0) logger.warn(`[gustcss] lint: ${suppressed} problem(s) suppressed by baseline or comments`);
+	}
+	let closing = false;
+	function runOnce() {
+		return new Promise((resolve) => {
+			const args = ["lint", "--json"];
+			if (configPath) args.push("--config", configPath);
+			if (strict) args.push("--strict");
+			let proc;
+			try {
+				proc = (0, child_process.spawn)(binaryPath, args, {
+					cwd,
+					stdio: [
+						"ignore",
+						"pipe",
+						"pipe"
+					]
+				});
+			} catch (error) {
+				logger.warn(`[gustcss] lint failed to run: ${error.message}`);
+				resolve();
+				return;
+			}
+			child = proc;
+			let stdout = "";
+			let stderr = "";
+			let settled = false;
+			let aborted = false;
+			const timer = setTimeout(() => {
+				aborted = true;
+				logger.warn("[gustcss] lint timed out; skipping this run");
+				proc.kill();
+			}, timeoutMs);
+			if (closing) {
+				aborted = true;
+				proc.kill();
+			}
+			const finish = (code) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				child = null;
+				report(code, stdout, stderr, aborted || closing);
+				resolve();
+			};
+			proc.stdout?.on("data", (chunk) => {
+				if (stdout.length < maxOutput) stdout += chunk;
+			});
+			proc.stderr?.on("data", (chunk) => {
+				if (stderr.length < maxOutput) stderr += chunk;
+			});
+			proc.on("error", (error) => {
+				aborted = true;
+				logger.warn(`[gustcss] lint failed to run: ${error.message}`);
+				finish(-1);
+			});
+			proc.on("close", (code) => finish(code ?? -1));
+		});
+	}
+	return {
+		async request() {
+			if (closed) return;
+			if (running) {
+				dirty = true;
+				return;
+			}
+			running = true;
+			do {
+				dirty = false;
+				await runOnce();
+			} while (dirty && !closed);
+			running = false;
+		},
+		close() {
+			closed = true;
+			dirty = false;
+			closing = true;
+			if (child) {
+				child.kill();
+				child = null;
+			}
+		}
+	};
+}
 function cssUtility(opts = {}) {
 	const output = opts.output || "src/styles/utility.css";
 	const content = opts.content || ["./src/**/*.{js,ts,jsx,tsx,astro,vue}"];
 	const configPath = opts.config;
 	const outputToCssLayers = opts.outputToCssLayers;
 	const mangleClassNames = opts.mangleClassNames === true;
+	const lintEnabled = opts.lint === true || typeof opts.lint === "object" && opts.lint !== null;
+	const lintOptions = typeof opts.lint === "object" && opts.lint !== null ? opts.lint : {};
+	const lintSource = /\.[cm]?[jt]sx?$|\.(?:astro|html|vue|svelte|mdx?)$/;
 	const mangleMap = opts.mangleMap || `${output}.classes.json`;
 	const mangleExclude = opts.mangleExclude || [];
 	let classNameTransformer = null;
@@ -1381,7 +1675,37 @@ function cssUtility(opts = {}) {
 					}]
 				});
 			});
+			let lintTimer = null;
+			const lintRunner = lintEnabled ? createLintRunner({
+				cwd,
+				binaryPath,
+				configPath: watchConfigPath,
+				logger: lintLogger(server),
+				strict: lintOptions.strict === true
+			}) : null;
+			if (lintRunner) {
+				lintRunner.request();
+				const scheduleLint = (file) => {
+					if (typeof file === "string") {
+						if (file.includes("node_modules")) return;
+						if (!lintSource.test(file)) return;
+					}
+					if (lintTimer) clearTimeout(lintTimer);
+					lintTimer = setTimeout(() => {
+						lintTimer = null;
+						lintRunner.request();
+					}, lintDebounceMs);
+				};
+				server.watcher.on("change", scheduleLint);
+				server.watcher.on("add", scheduleLint);
+				server.watcher.on("unlink", scheduleLint);
+			}
 			const cleanup = () => {
+				if (lintTimer) {
+					clearTimeout(lintTimer);
+					lintTimer = null;
+				}
+				lintRunner?.close();
 				if (watchProcess) {
 					watchProcess.kill();
 					watchProcess = null;

package/dist/index.d.ts

@@ -49,6 +49,28 @@ export interface GustcssPluginOptions {
    * Class names that must remain readable for external or ambiguous references.
    */
   mangleExclude?: string[]
+
+  /**
+   * Run `gustcss lint` while the dev server is running and report the
+   * diagnostics through the Vite logger. Enabled by `true` or an options
+   * object. Diagnostics never fail the dev server.
+   *
+   * @default false
+   */
+  lint?: boolean | GustcssLintOptions
+}
+
+/**
+ * Options for the dev-server lint integration.
+ */
+export interface GustcssLintOptions {
+  /**
+   * Also report custom-looking classes and low-confidence extractions
+   * (`gustcss lint --strict`).
+   *
+   * @default false
+   */
+  strict?: boolean
 }
 
 /**

package/dist/index.mjs

@@ -167,6 +167,105 @@ const SUPPORTED_SOURCE = /\.(?:[cm]?[jt]sx?|html)(?:$|\?)/;
 const HTML_SOURCE = /\.html(?:$|\?)/;
 const UNSUPPORTED_FRAMEWORK_SOURCE = /\.(?:vue|svelte)(?:$|\?)/;
 const DEPENDENCY_SOURCE = /(?:^|[\\/])node_modules[\\/]/;
+const CLASS_FUNCTION_NAMES = [
+	"cn",
+	"cx",
+	"clsx",
+	"classNames",
+	"cva",
+	"tv",
+	"twMerge",
+	"twJoin"
+];
+const CLASS_FUNCTION_CALL = new RegExp(`(?<![\\w$])(${CLASS_FUNCTION_NAMES.join("|")})\\s*\\(`, "g");
+const VARIANT_FUNCTION_NAMES = /* @__PURE__ */ new Set(["cva", "tv"]);
+const NESTED_CALL = /(?:^|[^\w$])([A-Za-z_$][\w$]*)\s*\(/g;
+function nestedCallRanges(args) {
+	const ranges = [];
+	NESTED_CALL.lastIndex = 0;
+	let match;
+	while ((match = NESTED_CALL.exec(args)) !== null) {
+		const open = args.indexOf("(", match.index + match[0].length - 1);
+		if (open < 0) continue;
+		const end = findBalancedEnd(args, open, "(", ")");
+		if (end < 0) continue;
+		ranges.push({
+			start: match.index,
+			end: end + 1,
+			isHelper: CLASS_FUNCTION_NAMES.includes(match[1])
+		});
+		NESTED_CALL.lastIndex = open + 1;
+	}
+	return ranges;
+}
+function innermostCallAt(ranges, index) {
+	let found = null;
+	for (const range of ranges) if (index >= range.start && index < range.end) {
+		if (found === null || range.start > found.start) found = range;
+	}
+	return found;
+}
+function parenDepthAt(value, index) {
+	let depth = 0;
+	for (let i = 0; i < index; i += 1) if (value[i] === "(") depth += 1;
+	else if (value[i] === ")") depth -= 1;
+	return depth;
+}
+function isComparisonOperand(args, segment) {
+	let before = segment.start - 1;
+	while (before >= 0 && /\s/.test(args[before])) before -= 1;
+	const lead = before >= 1 ? args.slice(before - 1, before + 1) : "";
+	if (lead === "==" || lead === "!=" || before >= 1 && args[before] === "=") return true;
+	let after = segment.end;
+	while (after < args.length && /\s/.test(args[after])) after += 1;
+	const tail = args.slice(after, after + 2);
+	return tail === "==" || tail === "!=";
+}
+function defaultVariantsRanges(args) {
+	const ranges = [];
+	const pattern = /defaultVariants\s*:\s*\{/g;
+	let match;
+	while ((match = pattern.exec(args)) !== null) {
+		const open = args.indexOf("{", match.index);
+		const end = findBalancedEnd(args, open, "{", "}");
+		if (end < 0) break;
+		ranges.push([open, end + 1]);
+		pattern.lastIndex = end;
+	}
+	return ranges;
+}
+function inRanges(ranges, index) {
+	return ranges.some(([start, end]) => index >= start && index < end);
+}
+function maskIgnoredRanges(text, origins, ranges) {
+	if (ranges.length === 0) return text;
+	const chars = text.split("");
+	let sorted = [...ranges].sort((a, b) => a[0] - b[0]);
+	let cursor = 0;
+	for (let i = 0; i < chars.length && cursor < sorted.length; i += 1) {
+		const origin = origins[i];
+		while (cursor < sorted.length && origin >= sorted[cursor][1]) cursor += 1;
+		if (cursor >= sorted.length) break;
+		if (origin >= sorted[cursor][0] && origin < sorted[cursor][1]) {
+			if (chars[i] !== "\n") chars[i] = " ";
+		}
+	}
+	return chars.join("");
+}
+function stripObjectKeys(value) {
+	return value.replace(/([{,]\s*)([A-Za-z_$][\w$]*)(\s*:)/g, (_match, lead, name, tail) => {
+		return lead + " ".repeat(name.length) + tail;
+	});
+}
+function isObjectKey(args, segment) {
+	let before = segment.start - 1;
+	while (before >= 0 && /\s/.test(args[before])) before -= 1;
+	const lead = before >= 0 ? args[before] : "";
+	if (lead !== "{" && lead !== ",") return false;
+	let after = segment.end;
+	while (after < args.length && /\s/.test(args[after])) after += 1;
+	return args[after] === ":";
+}
 function hasOwn(classes, token) {
 	return Object.hasOwn(classes, token);
 }
@@ -516,6 +615,44 @@ function collectClassListCallEdits(code, structure, classes, id, edits) {
 		pattern.lastIndex = end;
 	}
 }
+function collectClassFunctionCallEdits(code, structure, classes, id, edits, ignores) {
+	CLASS_FUNCTION_CALL.lastIndex = 0;
+	let match;
+	while ((match = CLASS_FUNCTION_CALL.exec(structure)) !== null) {
+		const name = match[1];
+		const open = code.indexOf("(", match.index + name.length);
+		if (open < 0) continue;
+		const end = findBalancedEnd(code, open, "(", ")");
+		if (end < 0) throw new Error(`[gustcss] incomplete ${name}(...) call in ${id}. Ensure the expression is properly closed.`);
+		const args = code.slice(open + 1, end - 1);
+		const argsStart = open + 1;
+		const skipKeys = VARIANT_FUNCTION_NAMES.has(name);
+		const skipRanges = skipKeys ? defaultVariantsRanges(args) : [];
+		const nestedCalls = nestedCallRanges(args);
+		const depthSource = stripQuotedSegments(args);
+		scanQuotedSegments(args, (segment) => {
+			const { start, quote, contents } = segment;
+			const nested = innermostCallAt(nestedCalls, start);
+			if (!(nested !== null && nested.isHelper) && parenDepthAt(depthSource, start) > 0) return;
+			if (skipKeys && quote !== "`" && isObjectKey(args, segment) || inRanges(skipRanges, segment.start) || isComparisonOperand(args, segment)) {
+				ignores.push([argsStart + segment.start, argsStart + segment.end]);
+				return;
+			}
+			const offset = argsStart + start + 1;
+			if (quote === "`") {
+				collectTemplateBodyEdits(contents, classes, offset, edits);
+				return;
+			}
+			collectClassListEdits(contents, classes, offset, edits);
+		});
+		let withoutStrings = stripQuotedSegments(args);
+		if (skipKeys) withoutStrings = stripObjectKeys(withoutStrings);
+		for (const [rangeStart, rangeEnd] of skipRanges) withoutStrings = withoutStrings.slice(0, rangeStart) + " ".repeat(rangeEnd - rangeStart) + withoutStrings.slice(rangeEnd);
+		const dynamic = findMappedToken(withoutStrings, classes);
+		if (dynamic) throw new Error(`[gustcss] mapped class "${dynamic}" remains in a dynamic argument of ${name}(...) in ${id}. Pass it as a direct string literal, or add it to mangleExclude.`);
+		CLASS_FUNCTION_CALL.lastIndex = end;
+	}
+}
 function rejectDynamicSetAttributeCalls(code, structure, classes, id) {
 	const pattern = /\.setAttribute\s*\(/g;
 	let match;
@@ -598,6 +735,7 @@ function sourcesForFile(code, id) {
 }
 function collectEdits(code, classes, id) {
 	const edits = [];
+	const ignores = [];
 	const sources = sourcesForFile(code, id);
 	const commentRanges = [];
 	let commentIndex = 0;
@@ -634,15 +772,23 @@ function collectEdits(code, classes, id) {
 		collectTemplateBodyEdits(match[2], classes, match.index + match[1].length, edits);
 	}
 	collectClassListCallEdits(code, sources.structure, classes, id, edits);
+	collectClassFunctionCallEdits(code, sources.structure, classes, id, edits, ignores);
 	const setAttributePattern = /(\.setAttribute\(\s*["']class["']\s*,\s*)(["'])([\s\S]*?)(\2)(\s*\))/g;
 	while ((match = setAttributePattern.exec(code)) !== null) {
 		if (sources.structure[match.index] === " ") continue;
 		collectClassListEdits(match[3], classes, match.index + match[1].length + 1, edits);
 	}
-	return edits;
+	return {
+		edits,
+		ignores
+	};
 }
 function collectRecognizedContextEdits(code, classes, id) {
-	return applyEdits(code, collectEdits(code, classes, id));
+	const collected = collectEdits(code, classes, id);
+	return {
+		...applyEdits(code, collected.edits),
+		ignores: collected.ignores
+	};
 }
 /**
 * Collect the rewrites for a source fragment (TypeScript frontmatter, an inline
@@ -651,15 +797,17 @@ function collectRecognizedContextEdits(code, classes, id) {
 * them inside a larger document.
 */
 function collectFragmentEdits(code, classes, id) {
-	const edits = collectEdits(code, classes, id);
-	const rewritten = applyEdits(code, edits).code;
+	const collected = collectEdits(code, classes, id);
+	const applied = applyEdits(code, collected.edits);
+	const rewritten = applied.code;
 	const sources = sourcesForFile(rewritten, id);
+	const inspection = maskIgnoredRanges(sources.inspection, applied.origins, collected.ignores);
 	rejectDynamicSetAttributeCalls(rewritten, sources.structure, classes, id);
 	rejectDynamicClassNameAssignments(rewritten, sources.structure, classes, id);
 	rejectAmbiguousClassExpressions(rewritten, sources.structure, classes, id);
-	const ambiguous = findMappedInQuotedSegments(sources.inspection, classes);
+	const ambiguous = findMappedInQuotedSegments(inspection, classes);
 	if (ambiguous) throw new Error(`[gustcss] mapped class "${ambiguous}" remains in an ambiguous string in ${id}. Move it to a static class/className or classList context, or add it to mangleExclude.`);
-	return edits;
+	return collected.edits;
 }
 const BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 function encodeVLQ(value) {
@@ -727,13 +875,14 @@ function transformSource(code, classes, id) {
 	const transformed = collectRecognizedContextEdits(code, classes, id);
 	const rewritten = transformed.code;
 	const sources = sourcesForFile(rewritten, id);
+	const inspection = maskIgnoredRanges(sources.inspection, transformed.origins, transformed.ignores);
 	rejectDynamicSetAttributeCalls(rewritten, sources.structure, classes, id);
 	rejectDynamicClassNameAssignments(rewritten, sources.structure, classes, id);
 	rejectAmbiguousClassExpressions(rewritten, sources.structure, classes, id);
 	return {
 		code: rewritten,
 		map: createSourceMap(code, rewritten, transformed.origins, id),
-		inspection: sources.inspection
+		inspection
 	};
 }
 function findAmbiguousMappedClass(code, classes) {
@@ -1168,6 +1317,7 @@ function createAstroTransformer({ parse, classes }) {
 * designed for build-time use only and should not process untrusted input.
 */
 const ASTRO_SOURCE = /\.astro(?:$|\?)/;
+const lintDebounceMs = 300;
 const ASTRO_MODULE = /^[^\0?]*\.astro$/;
 /**
 * Resolve @astrojs/compiler parse function from the project.
@@ -1185,12 +1335,156 @@ async function resolveAstroCompiler(root) {
 	} catch {}
 	return null;
 }
+/**
+* Vite logger へ出力する。テストなど logger が無い環境では console を使う。
+*/
+function lintLogger(server) {
+	const logger = server?.config?.logger;
+	return {
+		warn: (message) => logger?.warn ? logger.warn(message) : console.warn(message),
+		error: (message) => logger?.error ? logger.error(message) : console.error(message)
+	};
+}
+/**
+* Dev-server lint runner.
+*
+* Runs `gustcss lint --json` asynchronously and reports the diagnostics through
+* the logger. At most one lint process runs at a time; changes that arrive while
+* it runs are coalesced into one follow-up run. This keeps the dev server's
+* event loop free even on large projects.
+*/
+function createLintRunner({ cwd, binaryPath, configPath, logger, strict }) {
+	const maxOutput = 4194304;
+	const timeoutMs = 15e3;
+	let child = null;
+	let running = false;
+	let dirty = false;
+	let closed = false;
+	let lastSignature = null;
+	function report(code, stdout, stderr, aborted) {
+		if (aborted) return;
+		if (code !== 0 && code !== 1) {
+			logger.warn(`[gustcss] lint could not run: ${stderr.trim()}`);
+			return;
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(stdout);
+		} catch {
+			logger.warn("[gustcss] lint output was not JSON");
+			return;
+		}
+		const diagnostics = Array.isArray(parsed?.diagnostics) ? parsed.diagnostics : [];
+		const signature = JSON.stringify(diagnostics.map((d) => [
+			d.file,
+			d.line,
+			d.column,
+			d.ruleId,
+			d.severity,
+			d.class,
+			d.message
+		]));
+		if (signature === lastSignature) return;
+		lastSignature = signature;
+		for (const d of diagnostics) {
+			const text = `[gustcss] ${d.line ? `${d.file}:${d.line}:${d.column}` : d.file} ${d.ruleId}: ${d.message}`;
+			if (d.severity === "error") logger.error(text);
+			else logger.warn(text);
+		}
+		const suppressed = parsed?.summary?.suppressed ?? 0;
+		if (diagnostics.length > 0 && suppressed > 0) logger.warn(`[gustcss] lint: ${suppressed} problem(s) suppressed by baseline or comments`);
+	}
+	let closing = false;
+	function runOnce() {
+		return new Promise((resolve) => {
+			const args = ["lint", "--json"];
+			if (configPath) args.push("--config", configPath);
+			if (strict) args.push("--strict");
+			let proc;
+			try {
+				proc = spawn(binaryPath, args, {
+					cwd,
+					stdio: [
+						"ignore",
+						"pipe",
+						"pipe"
+					]
+				});
+			} catch (error) {
+				logger.warn(`[gustcss] lint failed to run: ${error.message}`);
+				resolve();
+				return;
+			}
+			child = proc;
+			let stdout = "";
+			let stderr = "";
+			let settled = false;
+			let aborted = false;
+			const timer = setTimeout(() => {
+				aborted = true;
+				logger.warn("[gustcss] lint timed out; skipping this run");
+				proc.kill();
+			}, timeoutMs);
+			if (closing) {
+				aborted = true;
+				proc.kill();
+			}
+			const finish = (code) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				child = null;
+				report(code, stdout, stderr, aborted || closing);
+				resolve();
+			};
+			proc.stdout?.on("data", (chunk) => {
+				if (stdout.length < maxOutput) stdout += chunk;
+			});
+			proc.stderr?.on("data", (chunk) => {
+				if (stderr.length < maxOutput) stderr += chunk;
+			});
+			proc.on("error", (error) => {
+				aborted = true;
+				logger.warn(`[gustcss] lint failed to run: ${error.message}`);
+				finish(-1);
+			});
+			proc.on("close", (code) => finish(code ?? -1));
+		});
+	}
+	return {
+		async request() {
+			if (closed) return;
+			if (running) {
+				dirty = true;
+				return;
+			}
+			running = true;
+			do {
+				dirty = false;
+				await runOnce();
+			} while (dirty && !closed);
+			running = false;
+		},
+		close() {
+			closed = true;
+			dirty = false;
+			closing = true;
+			if (child) {
+				child.kill();
+				child = null;
+			}
+		}
+	};
+}
 function cssUtility(opts = {}) {
 	const output = opts.output || "src/styles/utility.css";
 	const content = opts.content || ["./src/**/*.{js,ts,jsx,tsx,astro,vue}"];
 	const configPath = opts.config;
 	const outputToCssLayers = opts.outputToCssLayers;
 	const mangleClassNames = opts.mangleClassNames === true;
+	const lintEnabled = opts.lint === true || typeof opts.lint === "object" && opts.lint !== null;
+	const lintOptions = typeof opts.lint === "object" && opts.lint !== null ? opts.lint : {};
+	const lintSource = /\.[cm]?[jt]sx?$|\.(?:astro|html|vue|svelte|mdx?)$/;
 	const mangleMap = opts.mangleMap || `${output}.classes.json`;
 	const mangleExclude = opts.mangleExclude || [];
 	let classNameTransformer = null;
@@ -1375,7 +1669,37 @@ function cssUtility(opts = {}) {
 					}]
 				});
 			});
+			let lintTimer = null;
+			const lintRunner = lintEnabled ? createLintRunner({
+				cwd,
+				binaryPath,
+				configPath: watchConfigPath,
+				logger: lintLogger(server),
+				strict: lintOptions.strict === true
+			}) : null;
+			if (lintRunner) {
+				lintRunner.request();
+				const scheduleLint = (file) => {
+					if (typeof file === "string") {
+						if (file.includes("node_modules")) return;
+						if (!lintSource.test(file)) return;
+					}
+					if (lintTimer) clearTimeout(lintTimer);
+					lintTimer = setTimeout(() => {
+						lintTimer = null;
+						lintRunner.request();
+					}, lintDebounceMs);
+				};
+				server.watcher.on("change", scheduleLint);
+				server.watcher.on("add", scheduleLint);
+				server.watcher.on("unlink", scheduleLint);
+			}
 			const cleanup = () => {
+				if (lintTimer) {
+					clearTimeout(lintTimer);
+					lintTimer = null;
+				}
+				lintRunner?.close();
 				if (watchProcess) {
 					watchProcess.kill();
 					watchProcess = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gustcss/vite",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Vite plugin for GustCSS",
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",
@@ -37,7 +37,7 @@
     "access": "public"
   },
   "dependencies": {
-    "gustcss": "^0.10.1"
+    "gustcss": "^0.11.0"
   },
   "devDependencies": {
     "@astrojs/compiler": "2.13.0",