dsh-taiwind 0.2.0 → 0.3.1

package/README.md

@@ -43,7 +43,7 @@ flowchart LR
 ### 1. 安装
 
 ```sh
-pnpm add dsh-taiwind
+pnpm add dsh-taiwind@latest
 ```
 
 在业务插件的 `cordis.patch.yml` 里插入它（连同自身行）：
@@ -56,15 +56,24 @@ pnpm add dsh-taiwind
       name: dsh-taiwind
 ```
 
-用户启用业务插件时，`dsh-taiwind` 将随行一起启用，而客户端半也必须有一行启用中的 Loader 条目才会被 `dsh-client-modules` 加载。
+用户启用业务插件时，`dsh-taiwind` 将随行一起启用。
 
-- 它没有界面、没有工具，唯一产物是共享样式接口 `plugins/taiwind.css` 和页面上的一个 `<style data-plugin="dsh-taiwind">`。
-- 宿主半要求 `clientModules`、`webServer`、`connection` 三件服务齐备。
+- 它没有界面和工具，唯一产物是共享样式接口 `plugins/taiwind.css` 和页面上的 `<style data-plugin="dsh-taiwind">`。
 - 扫描范围是当前客户端图里所有插件的构建产物，插件图变化会自动触发重新编译。
 
-### 2. 在插件包里写样式
+### 2. 声明样式入口
 
-在插件包中保留未编译的 `main.css`：
+在插件包的 `package.json` 里显式声明未编译的 CSS 入口（相对包根，必须位于包内）：
+
+```json
+{
+  "dsh": {
+    "taiwind": "src/main.css"
+  }
+}
+```
+
+`main.css` 保留未编译的 CSS-first 写法：
 
 ```css
 @import "tailwindcss";
@@ -81,16 +90,9 @@ pnpm add dsh-taiwind
 
 🚀 客户端直接使用 taiwind 类名，例如 `bg-notes-accent w-notes-panel notes-compact` 即可。
 
-入口发现顺序：
-
-1. 包根目录的 `main.css`
-2. 客户端入口同目录的 `main.css`（如 `client/main.css`）
-3. 以上都没有时，在包内查找 `main.css`；
-4. 找到多个会明确报错，不任意选择
-
 ### 3. 发布时携带样式文件
 
-在 `package.json` 中添加 `files` 字段，发布时需要携带 `main.css`：
+在 `package.json` 中添加 `files` 字段，发布时需要携带入口 CSS 及它引用的相对 CSS：
 
 ```json
 {
@@ -126,14 +128,14 @@ CSS 入口存在时**不会自动加载根目录 JS 配置**，需要时在 CSS
 
 | 项目 | 说明 |
 | --- | --- |
-| 发布 | 原始 CSS 入口及其相对导入必须进 npm 包；只发 `dist` 时一并复制，不要用展开后的构建 CSS 代替 |
-| 不支持 | TypeScript 配置（只认 `.js` / `.mjs` / `.cjs`）、npm CSS 包导入、路径别名、远程 CSS、`@plugin`、文件路径形式的 `@source`、自定义 `source(...)` 扫描目录、跨包 CSS 导入 |
-| 冲突检测 | 自定义 token、同名 `@utility` / `@custom-variant` 定义不一致会报错并指包名；非完整 CSS 语义等价判断 |
-| 主题合并 | 遵循 Tailwind 4：同 token 的 CSS 定义优先；所有插件共享全局主题，不按插件隔离 |
+| 发布 | 原始 CSS 入口及其相对导入必须进 npm 包； |
+| 不支持 | TypeScript 配置、npm CSS 包导入、路径别名、远程 CSS、`@plugin`、文件路径形式的 `@source`、自定义 `source(...)` 扫描目录、跨包 CSS 导入 |
+| 冲突检测 | CSS token、同名 `@utility` / `@custom-variant` 定义不一致时自动合并，并输出包含冲突项和双方包名的 warn 日志；同一冲突不会在每次轮询时重复刷屏 |
+| 主题合并 | 按插件 ID、入口路径排序后交由 Tailwind 4 合并，CSS 定义优先于 JS 配置，同名 CSS 定义遵循后者覆盖；所有插件共享全局主题，不按插件隔离 |
 | 自定义 CSS | 一起输出，但不自动限定作用域、去重或改写资源 URL；请用插件前缀选择器和可直接访问的资源地址 |
 | 动态值 | 适合 CSS 变量或内联样式，不要拼接不完整类名 |
-| 共享编译器成本 | 需安装 Tailwind、Oxide 原生扫描器等宿主依赖；有磁盘占用与宿主 CPU 开销 |
-| 共享不是隔离 | 共用主题与全局选项，冲突可能阻止整份样式更新；不适合要求完全独立 Tailwind 配置的插件 |
+| 共享编译器成本 | 需安装 Tailwind、Oxide 原生扫描器等宿主依赖；有磁盘占用（约 8mb~10mb）与宿主 CPU 开销 |
+| 共享不是隔离 | 共用主题与全局选项；CSS 定义冲突只告警，非法配置与不兼容的 JS 全局选项仍会阻止更新；不适合要求完全独立 Tailwind 配置的插件 |
 
 ## 🛠️ 开发与贡献
 

package/dist/index.js

@@ -138,43 +138,18 @@ async function bundles(directory) {
 	}
 	return files;
 }
-async function nestedPackage(directory) {
-	try {
-		await readFile(join(directory, "package.json"));
-		return true;
-	} catch (error) {
-		if (error.code === "ENOENT") return false;
-		throw error;
-	}
-}
-async function cssEntry(root, clientDirectory) {
-	for (const directory of /* @__PURE__ */ new Set([root, clientDirectory])) {
-		const entry = (await readdir(directory, { withFileTypes: true })).find((item) => item.name === "main.css");
-		if (entry) {
-			if (!entry.isFile()) throw new Error(`${directory}: main.css must be a regular file`);
-			return join(directory, entry.name);
-		}
+async function cssEntry(root, owner) {
+	const entry = JSON.parse(await readFile(join(root, "package.json"), "utf8")).dsh?.taiwind;
+	if (entry === void 0) {
+		if (await stat(join(root, "main.css")).then((info) => info.isFile(), () => false)) throw new Error(`${owner}: main.css is not discovered automatically anymore; declare "dsh": { "taiwind": "main.css" } in package.json`);
+		return;
 	}
-	const found = [];
-	const visit = async (directory) => {
-		for (const item of await readdir(directory, { withFileTypes: true })) {
-			if ([
-				"node_modules",
-				"archive",
-				".git"
-			].includes(item.name) || item.isSymbolicLink()) continue;
-			const path = join(directory, item.name);
-			if (item.isDirectory()) {
-				if (await nestedPackage(path)) continue;
-				await visit(path);
-			} else if (item.isFile() && item.name === "main.css") found.push(path);
-		}
-	};
-	await visit(root);
-	if (found.length > 1) throw new Error(`${root}: multiple main.css entries found: ${found.sort().join(", ")}`);
-	return found[0];
+	if (typeof entry !== "string" || !entry.trim() || extname(entry) !== ".css") throw new Error(`${owner}: dsh.taiwind must be a relative .css path`);
+	const path = resolve(root, entry);
+	if (!await stat(path).then((info) => info.isFile(), () => false)) throw new Error(`${owner}: dsh.taiwind entry not found: ${entry}`);
+	return path;
 }
-async function compilePlugins(entries) {
+async function compilePlugins(entries, onWarning) {
 	const hash = createHash("sha256");
 	const bundleFiles = [];
 	const extend = Object.create(null);
@@ -185,6 +160,7 @@ async function compilePlugins(entries) {
 	const stylesheets = /* @__PURE__ */ new Map();
 	const cssImports = [];
 	const cssDefinitions = /* @__PURE__ */ new Map();
+	const warnings = /* @__PURE__ */ new Set();
 	const configsSeen = /* @__PURE__ */ new Set();
 	const setGlobal = (key, value, owner) => {
 		if (Object.hasOwn(merged, key) && canonical(merged[key]) !== canonical(value)) throw new Error(`Tailwind global configuration conflict at ${key}: ${owners.get(key)} and ${owner}`);
@@ -221,7 +197,7 @@ async function compilePlugins(entries) {
 	};
 	const checkDefinition = (key, value, owner) => {
 		const previous = cssDefinitions.get(key);
-		if (previous && previous.owner !== owner && previous.value !== value) throw new Error(`Tailwind CSS conflict at ${key}: ${previous.owner} and ${owner}`);
+		if (previous && previous.owner !== owner && previous.value !== value) warnings.add(`Tailwind CSS conflict at ${key}: ${previous.owner} and ${owner}; merging in plugin order`);
 		cssDefinitions.set(key, {
 			value,
 			owner
@@ -301,7 +277,7 @@ async function compilePlugins(entries) {
 			]));
 			bundleFiles.push(file);
 		}
-		const stylesheet = await cssEntry(root, dirname(path));
+		const stylesheet = await cssEntry(root, entry.id);
 		if (stylesheet) {
 			cssImports.push(await loadCss(stylesheet, root, entry.id));
 			continue;
@@ -318,6 +294,7 @@ async function compilePlugins(entries) {
 	const utilities = await readFile(new URL(import.meta.resolve("tailwindcss/utilities.css")), "utf8");
 	hash.update(JSON.stringify([theme, utilities]));
 	const digest = hash.digest("hex");
+	for (const warning of warnings) onWarning?.(warning);
 	if (cached?.signature === digest) return cached.css;
 	const sources = [];
 	for (const file of bundleFiles) sources.push({
@@ -379,20 +356,24 @@ async function apply(ctx) {
 		pending = (async () => {
 			while (true) {
 				const current = generation;
-				const compiled = await compilePlugins(ctx.clientModules.graph().entries.map(({ id }) => {
+				const entries = ctx.clientModules.graph().entries.map(({ id }) => {
 					const path = ctx.clientModules.clientPath(id);
 					if (!path) throw new Error(`Missing client bundle: ${id}`);
 					return {
 						id,
 						path
 					};
-				}));
+				});
+				const warnings = [];
+				const compiled = await compilePlugins(entries, (message) => warnings.push(message));
 				if (disposed) return;
 				if (generation !== current) continue;
 				css = compiled;
 				etag = `"${createHash("sha256").update(css).digest("hex")}"`;
 				failed = false;
-				lastError = "";
+				const warning = warnings.join("\n");
+				if (warning && warning !== lastError) ctx.logger.warn(`${PLUGIN_ID}: ${warning}`);
+				lastError = warning;
 				break;
 			}
 		})().finally(() => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-taiwind",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "One shared Tailwind stylesheet for DSH plugins with per-plugin configuration",
   "author": "Hairy <wwu710632@gmail.com>",
   "license": "MIT",