eslint-plugin-better-stylelint 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ice breaker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# eslint-plugin-better-stylelint
+
+Bridge Stylelint diagnostics into ESLint for style files.
+
+This package provides:
+
+- ESLint processors for `*.css` and `*.scss`
+- an ESLint rule for `.vue` files that forwards Stylelint diagnostics from
+  `<style>` blocks
+- a bundled `synckit` worker so `stylelint.lint()` can be invoked through a
+  synchronous ESLint bridge
+
+## Why
+
+Use this when you want style issues to show up in the same ESLint diagnostic
+stream as the rest of your project.
+
+## Installation
+
+```bash
+pnpm add -D eslint stylelint eslint-plugin-better-stylelint
+```
+
+## Usage
+
+```js
+import betterStylelint from 'eslint-plugin-better-stylelint'
+
+export default [
+  {
+    files: ['**/*.css'],
+    plugins: {
+      stylelint: betterStylelint,
+    },
+    processor: 'stylelint/css',
+  },
+  {
+    files: ['**/*.scss'],
+    plugins: {
+      stylelint: betterStylelint,
+    },
+    processor: 'stylelint/scss',
+  },
+  {
+    files: ['**/*.vue'],
+    plugins: {
+      stylelint: betterStylelint,
+    },
+    rules: {
+      'stylelint/stylelint': 'error',
+    },
+  },
+]
+```
+
+The plugin relies on the consuming project's Stylelint configuration and
+prefers the consuming project's `stylelint` installation. If the project does
+not provide one, it falls back to the bundled `stylelint` dependency.
+
+## Implementation Notes
+
+- The synchronous bridge is implemented with `synckit`, not by spawning the
+  Stylelint CLI.
+- The published package must include both `dist/index.js` and `dist/worker.js`.
+- `src/core.ts` resolves the worker file by swapping `core.(ts|js)` to
+  `worker.(ts|js)`, so removing the worker build entry will break runtime
+  resolution.
+
+## FAQ
+
+### Does it automatically read `stylelint.config.js`?
+
+Yes. The bridge calls `stylelint.lint({ code, codeFilename, cwd })` and lets
+Stylelint handle config discovery. In practice that means common config entry
+points such as `stylelint.config.js`, `stylelint.config.cjs`,
+`stylelint.config.mjs`, `stylelint.config.ts`, and `package.json#stylelint`
+are discovered by Stylelint itself.
+
+### Does it support `extends`, `plugins`, and `customSyntax`?
+
+Yes, as long as your Stylelint config can resolve them from the project. The
+bridge does not bypass or replace Stylelint's normal config loading, so
+`extends`, plugin rules, and `customSyntax` continue to work the same way they
+would when you run Stylelint directly.
+
+### Which `stylelint` installation does it use?
+
+It prefers the consuming project's own `stylelint` installation. If the
+project does not provide one, the bridge falls back to the bundled `stylelint`
+dependency shipped with `eslint-plugin-better-stylelint`.
+
+For the most predictable behavior, install `stylelint` in the project root so
+your ESLint bridge, Stylelint CLI, and editor integrations all use the same
+version.
+
+### Will this affect IDE plugins?
+
+Usually the ESLint extension works as expected, because the bridge runs inside
+ESLint. The main thing to watch is consistency:
+
+- If the project has its own `stylelint`, the ESLint bridge and Stylelint IDE
+  extension should stay aligned.
+- If the project does not have its own `stylelint`, the ESLint bridge can still
+  work via the bundled fallback, but a standalone Stylelint IDE extension may
+  not behave exactly the same way.
+
+### How does it handle Vue SFCs?
+
+Each `<style>` block in a `.vue` file is linted separately. The bridge:
+
+- extracts the block content instead of linting the whole SFC as one string
+- generates a virtual filename based on the block `lang`, such as `css` or
+  `scss`
+- maps Stylelint diagnostics back to the original `.vue` line and column
+- includes block context such as `scoped`, `module`, and `lang` in the message
+  when that context helps identify the source block

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+//#region src/types.d.ts
+interface BetterStylelintMessage {
+  ruleId: string;
+  message: string;
+  line: number;
+  column: number;
+  endLine?: number;
+  endColumn?: number;
+  severity: 1 | 2;
+  fatal?: boolean;
+}
+interface BetterStylelintProcessor {
+  meta?: {
+    name?: string;
+    version?: string;
+  };
+  preprocess: (text: string, filename: string) => string[];
+  postprocess: (messages: unknown[][], filename: string) => BetterStylelintMessage[];
+  supportsAutofix?: boolean;
+}
+interface BetterStylelintRuleOptions {
+  cwd?: string;
+}
+//#endregion
+//#region src/processor.d.ts
+declare const cssProcessor: BetterStylelintProcessor;
+declare const scssProcessor: BetterStylelintProcessor;
+//#endregion
+//#region src/rule.d.ts
+interface RuleContext {
+  filename: string;
+  options: BetterStylelintRuleOptions[];
+  report: (descriptor: {
+    loc: {
+      start: {
+        line: number;
+        column: number;
+      };
+      end?: {
+        line: number;
+        column: number;
+      };
+    };
+    message: string;
+  }) => void;
+  sourceCode: {
+    text: string;
+  };
+}
+declare const lintRule: {
+  meta: {
+    type: string;
+    docs: {
+      description: string;
+    };
+    schema: {
+      type: string;
+      additionalProperties: boolean;
+      properties: {
+        cwd: {
+          type: string;
+        };
+      };
+    }[];
+  };
+  create(context: RuleContext): {
+    Program(): void;
+  };
+};
+//#endregion
+//#region src/core.d.ts
+declare function runStylelintSync(code: string, filename: string, cwd?: string): BetterStylelintMessage[];
+//#endregion
+//#region src/index.d.ts
+interface BetterStylelintPlugin {
+  meta: {
+    name: string;
+    version: string;
+  };
+  processors: {
+    css: typeof cssProcessor;
+    scss: typeof scssProcessor;
+  };
+  rules: {
+    stylelint: typeof lintRule;
+  };
+}
+declare const plugin: BetterStylelintPlugin;
+//#endregion
+export { type BetterStylelintMessage, type BetterStylelintProcessor, type BetterStylelintRuleOptions, cssProcessor, plugin as default, lintRule, runStylelintSync, scssProcessor };

package/dist/index.js

@@ -0,0 +1,238 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createSyncFn } from "synckit";
+//#region src/core.ts
+const MAX_CACHE_ENTRIES = 100;
+const CORE_TS_PATTERN = /core\.ts$/u;
+const CORE_JS_PATTERN = /core\.js$/u;
+const resultCache = /* @__PURE__ */ new Map();
+let runStylelintWorker;
+function normalizeStylelintResults(result) {
+	return [...result.warnings ?? [], ...result.parseErrors ?? []].map((warning) => ({
+		ruleId: warning.rule ?? "stylelint",
+		message: warning.text,
+		line: warning.line ?? 1,
+		column: warning.column ?? 1,
+		...warning.endLine !== void 0 ? { endLine: warning.endLine } : {},
+		...warning.endColumn !== void 0 ? { endColumn: warning.endColumn } : {},
+		severity: warning.severity === "warning" ? 1 : 2,
+		...warning.rule === void 0 ? { fatal: true } : {}
+	}));
+}
+function createBridgeError(message) {
+	return [{
+		ruleId: "stylelint/bridge",
+		message,
+		line: 1,
+		column: 1,
+		severity: 2,
+		fatal: true
+	}];
+}
+function cloneMessages(messages) {
+	return messages.map((message) => ({ ...message }));
+}
+function createCacheKey(code, filename, cwd) {
+	return `${cwd}\0${filename}\0${createHash("sha1").update(code).digest("hex")}`;
+}
+function getCachedMessages(cacheKey) {
+	const cached = resultCache.get(cacheKey);
+	if (!cached) return;
+	resultCache.delete(cacheKey);
+	resultCache.set(cacheKey, cached);
+	return cloneMessages(cached);
+}
+function setCachedMessages(cacheKey, messages) {
+	if (resultCache.has(cacheKey)) resultCache.delete(cacheKey);
+	resultCache.set(cacheKey, messages);
+	while (resultCache.size > MAX_CACHE_ENTRIES) {
+		const oldestKey = resultCache.keys().next().value;
+		if (oldestKey === void 0) break;
+		resultCache.delete(oldestKey);
+	}
+	return cloneMessages(messages);
+}
+function resolveWorkerPath() {
+	const currentFilePath = fileURLToPath(import.meta.url);
+	if (currentFilePath.endsWith(".ts")) return currentFilePath.replace(CORE_TS_PATTERN, "worker.ts");
+	return currentFilePath.replace(CORE_JS_PATTERN, "worker.js");
+}
+function getRunStylelintWorker() {
+	runStylelintWorker ??= createSyncFn(resolveWorkerPath());
+	return runStylelintWorker;
+}
+function runStylelintSync(code, filename, cwd = path.dirname(filename)) {
+	const cacheKey = createCacheKey(code, filename, cwd);
+	const cached = getCachedMessages(cacheKey);
+	if (cached) return cached;
+	const response = getRunStylelintWorker()(code, filename, cwd);
+	if (!response.ok) return setCachedMessages(cacheKey, createBridgeError(response.error));
+	return setCachedMessages(cacheKey, normalizeStylelintResults(response.result));
+}
+//#endregion
+//#region src/processor.ts
+const sourceCache = /* @__PURE__ */ new Map();
+function createProcessor() {
+	return {
+		meta: {
+			name: "eslint-plugin-better-stylelint/processor",
+			version: "0.0.1"
+		},
+		preprocess(text, filename) {
+			sourceCache.set(filename, text);
+			return ["/* eslint-plugin-better-stylelint */"];
+		},
+		postprocess(_messages, filename) {
+			const source = sourceCache.get(filename) ?? "";
+			sourceCache.delete(filename);
+			return runStylelintSync(source, filename);
+		},
+		supportsAutofix: false
+	};
+}
+const cssProcessor = createProcessor();
+const scssProcessor = createProcessor();
+//#endregion
+//#region src/rule.ts
+const VUE_STYLE_BLOCK_PATTERN = /<style\b[^>]*>[\s\S]*?<\/style>/giu;
+const VUE_STYLE_OPENING_TAG_PATTERN = /^<style\b([^>]*)>/iu;
+const HTML_ATTRIBUTE_PATTERN = /([:@\w-]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/gu;
+function getColumn(value) {
+	return Math.max(0, (value ?? 1) - 1);
+}
+function getLineColumnAtOffset(source, offset) {
+	let line = 1;
+	let column = 1;
+	for (let index = 0; index < offset; index += 1) {
+		if (source[index] === "\n") {
+			line += 1;
+			column = 1;
+			continue;
+		}
+		column += 1;
+	}
+	return {
+		line,
+		column
+	};
+}
+function parseStyleAttributes(code) {
+	const rawAttributes = code.match(VUE_STYLE_OPENING_TAG_PATTERN)?.[1];
+	if (!rawAttributes) return {};
+	const attributes = {};
+	for (const match of rawAttributes.matchAll(HTML_ATTRIBUTE_PATTERN)) {
+		const name = match[1];
+		if (!name) continue;
+		const value = match[2] ?? match[3] ?? match[4];
+		attributes[name] = value === void 0 ? true : value;
+	}
+	return attributes;
+}
+function createVueStyleBlockLabel(index, attributes, blockCount) {
+	const segments = blockCount > 1 ? [`style#${index + 1}`] : ["style"];
+	if (attributes["scoped"]) segments.push("scoped");
+	if (attributes["module"]) {
+		const moduleValue = attributes["module"];
+		segments.push(moduleValue === true ? "module" : `module=${moduleValue}`);
+	}
+	if (typeof attributes["lang"] === "string") segments.push(`lang=${attributes["lang"]}`);
+	return segments.length > 1 ? segments.join(" ") : void 0;
+}
+function normalizeStyleLang(attributes) {
+	const lang = attributes["lang"];
+	if (typeof lang !== "string" || !lang.trim()) return "css";
+	return lang.trim().toLowerCase();
+}
+function createVueStyleVirtualFilename(filename, index, attributes) {
+	return `${filename}__style_${index}.${normalizeStyleLang(attributes)}`;
+}
+function extractVueStyleBlocks(source, filename = "Component.vue") {
+	const matches = [...source.matchAll(VUE_STYLE_BLOCK_PATTERN)];
+	const blocks = [];
+	for (const [matchIndex, match] of matches.entries()) {
+		const code = match[0];
+		const matchOffset = match.index;
+		if (code === void 0 || matchOffset === void 0) continue;
+		const attributes = parseStyleAttributes(code);
+		const label = createVueStyleBlockLabel(matchIndex, attributes, matches.length);
+		const contentStartOffset = matchOffset + (code.match(VUE_STYLE_OPENING_TAG_PATTERN)?.[0] ?? "<style>").length;
+		const contentEndOffset = matchOffset + code.length - 8;
+		const content = source.slice(contentStartOffset, contentEndOffset);
+		const location = getLineColumnAtOffset(source, contentStartOffset);
+		blocks.push({
+			attributes,
+			code,
+			content,
+			index: matchIndex,
+			...label !== void 0 ? { label } : {},
+			startLine: location.line,
+			startColumn: location.column,
+			virtualFilename: createVueStyleVirtualFilename(filename, matchIndex, attributes)
+		});
+	}
+	return blocks;
+}
+function mapDiagnosticToVueFile(diagnostic, block) {
+	const mappedStartLine = block.startLine + diagnostic.line - 1;
+	const mappedEndLine = diagnostic.endLine !== void 0 ? block.startLine + diagnostic.endLine - 1 : void 0;
+	return {
+		...diagnostic,
+		line: mappedStartLine,
+		column: diagnostic.line === 1 ? block.startColumn + diagnostic.column - 1 : diagnostic.column,
+		...mappedEndLine !== void 0 ? { endLine: mappedEndLine } : {},
+		...diagnostic.endColumn !== void 0 ? { endColumn: diagnostic.endLine === void 0 || diagnostic.endLine === 1 ? block.startColumn + diagnostic.endColumn - 1 : diagnostic.endColumn } : {}
+	};
+}
+const lintRule = {
+	meta: {
+		type: "problem",
+		docs: { description: "Run Stylelint and surface its diagnostics through ESLint" },
+		schema: [{
+			type: "object",
+			additionalProperties: false,
+			properties: { cwd: { type: "string" } }
+		}]
+	},
+	create(context) {
+		return { Program() {
+			if (!context.filename.endsWith(".vue")) return;
+			const cwd = context.options[0]?.cwd;
+			const styleBlocks = extractVueStyleBlocks(context.sourceCode.text, context.filename);
+			for (const styleBlock of styleBlocks) {
+				const diagnostics = runStylelintSync(styleBlock.content, styleBlock.virtualFilename, cwd);
+				for (const diagnostic of diagnostics) {
+					const mappedDiagnostic = mapDiagnosticToVueFile(diagnostic, styleBlock);
+					context.report({
+						loc: {
+							start: {
+								line: mappedDiagnostic.line,
+								column: getColumn(mappedDiagnostic.column)
+							},
+							...mappedDiagnostic.endLine !== void 0 || mappedDiagnostic.endColumn !== void 0 ? { end: {
+								line: mappedDiagnostic.endLine ?? mappedDiagnostic.line,
+								column: getColumn(mappedDiagnostic.endColumn ?? mappedDiagnostic.column)
+							} } : {}
+						},
+						message: styleBlock.label ? `[${styleBlock.label}] ${mappedDiagnostic.ruleId ? `${mappedDiagnostic.message} (${mappedDiagnostic.ruleId})` : mappedDiagnostic.message}` : mappedDiagnostic.ruleId ? `${mappedDiagnostic.message} (${mappedDiagnostic.ruleId})` : mappedDiagnostic.message
+					});
+				}
+			}
+		} };
+	}
+};
+//#endregion
+//#region src/index.ts
+const plugin = {
+	meta: {
+		name: "stylelint",
+		version: "0.0.1"
+	},
+	processors: {
+		css: cssProcessor,
+		scss: scssProcessor
+	},
+	rules: { stylelint: lintRule }
+};
+//#endregion
+export { cssProcessor, plugin as default, lintRule, runStylelintSync, scssProcessor };

package/dist/worker.d.ts

@@ -0,0 +1,5 @@
+//#region src/worker.d.ts
+declare function createProjectRequire(cwd: string): NodeJS.Require;
+declare function resolveStylelintEntry(cwd: string): string;
+//#endregion
+export { createProjectRequire as __createProjectRequire, resolveStylelintEntry as __resolveStylelintEntry };

package/dist/worker.js

@@ -0,0 +1,42 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { runAsWorker } from "synckit";
+//#region src/worker.ts
+function createProjectRequire(cwd) {
+	try {
+		return createRequire(path.join(cwd, "package.json"));
+	} catch {
+		return createRequire(import.meta.url);
+	}
+}
+function resolveStylelintEntry(cwd) {
+	const projectRequire = createProjectRequire(cwd);
+	try {
+		return projectRequire.resolve("stylelint");
+	} catch {
+		return createRequire(import.meta.url).resolve("stylelint");
+	}
+}
+async function runStylelint(code, filename, cwd) {
+	try {
+		const stylelintModule = await import(pathToFileURL(resolveStylelintEntry(cwd)).href);
+		return {
+			ok: true,
+			result: (await (stylelintModule.default ?? stylelintModule).lint({
+				allowEmptyInput: true,
+				code,
+				codeFilename: filename,
+				cwd
+			})).results[0] ?? { warnings: [] }
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+runAsWorker(runStylelint);
+//#endregion
+export { createProjectRequire as __createProjectRequire, resolveStylelintEntry as __resolveStylelintEntry };

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "eslint-plugin-better-stylelint",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "Bridge Stylelint diagnostics into ESLint for style files and Vue SFCs",
+  "author": "ice breaker <1324318532@qq.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sonofmagic/dev-configs.git",
+    "directory": "packages/eslint-plugin-better-stylelint"
+  },
+  "bugs": {
+    "url": "https://github.com/sonofmagic/dev-configs/issues"
+  },
+  "keywords": [
+    "dev-configs",
+    "eslint",
+    "stylelint",
+    "eslint-plugin"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "peerDependencies": {
+    "eslint": "^9.0.0",
+    "stylelint": "^17.4.0"
+  },
+  "peerDependenciesMeta": {
+    "stylelint": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "stylelint": "^17.4.0",
+    "synckit": "^0.11.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "tsd": {
+    "directory": "test-d",
+    "compilerOptions": {
+      "skipLibCheck": true
+    }
+  },
+  "scripts": {
+    "dev": "tsdown --watch --sourcemap",
+    "build": "tsdown",
+    "lint": "eslint src test test-d",
+    "test": "vitest run",
+    "test:types": "tsd",
+    "test:dev": "vitest",
+    "release": "pnpm publish",
+    "sync": "cnpm sync eslint-plugin-better-stylelint",
+    "typecheck": "tsc --noEmit"
+  }
+}