@bamboocss/eslint-plugin 1.29.0 → 1.30.0

package/dist/index.cjs

@@ -8,7 +8,7 @@ require("@typescript-eslint/utils/ts-eslint");
 let _bamboocss_shared = require("@bamboocss/shared");
 //#region package.json
 var name = "@bamboocss/eslint-plugin";
-var version = "1.29.0";
+var version = "1.30.0";
 //#endregion
 //#region src/utils/index.ts
 const createRule = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/bamboocss/bamboo/blob/main/packages/eslint-plugin/docs/rules/${name}.md`);
@@ -307,8 +307,8 @@ function isRecipeVariant(node, context) {
 }
 //#endregion
 //#region src/rules/file-not-included.ts
-const RULE_NAME$20 = "file-not-included";
-const rule$20 = createRule({
+const RULE_NAME$21 = "file-not-included";
+const rule$21 = createRule({
 	create(context) {
 		if (isValidFile(context)) return {};
 		let hasReported = false;
@@ -329,11 +329,11 @@ const rule$20 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$20
+	name: RULE_NAME$21
 });
 //#endregion
 //#region src/rules/no-config-function-in-source.ts
-const RULE_NAME$19 = "no-config-function-in-source";
+const RULE_NAME$20 = "no-config-function-in-source";
 const CONFIG_FUNCTIONS = new Set([
 	"defineConfig",
 	"defineGlobalStyles",
@@ -350,7 +350,7 @@ const CONFIG_FUNCTIONS = new Set([
 	"defineTokens",
 	"defineUtility"
 ]);
-const rule$19 = createRule({
+const rule$20 = createRule({
 	create(context) {
 		if (!hasPkgImport(context)) return {};
 		if (!isValidFile(context)) return {};
@@ -390,12 +390,12 @@ const rule$19 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$19
+	name: RULE_NAME$20
 });
 //#endregion
 //#region src/rules/no-debug.ts
-const RULE_NAME$18 = "no-debug";
-const rule$18 = createRule({
+const RULE_NAME$19 = "no-debug";
+const rule$19 = createRule({
 	create(context) {
 		const processedNodes = /* @__PURE__ */ new WeakSet();
 		const checkObjectForDebug = (object) => {
@@ -464,12 +464,12 @@ const rule$18 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$18
+	name: RULE_NAME$19
 });
 //#endregion
 //#region src/rules/no-deprecated-tokens.ts
-const RULE_NAME$17 = "no-deprecated-tokens";
-const rule$17 = createRule({
+const RULE_NAME$18 = "no-deprecated-tokens";
+const rule$18 = createRule({
 	create(context) {
 		const deprecatedTokensCache = /* @__PURE__ */ new Map();
 		const sendReport = (property, node, value) => {
@@ -523,12 +523,12 @@ const rule$17 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$17
+	name: RULE_NAME$18
 });
 //#endregion
 //#region src/rules/no-dynamic-styling.ts
-const RULE_NAME$16 = "no-dynamic-styling";
-const rule$16 = createRule({
+const RULE_NAME$17 = "no-dynamic-styling";
+const rule$17 = createRule({
 	create(context) {
 		function isStaticValue(node) {
 			if (!node) return false;
@@ -599,12 +599,12 @@ const rule$16 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$16
+	name: RULE_NAME$17
 });
 //#endregion
 //#region src/rules/no-escape-hatch.ts
-const RULE_NAME$15 = "no-escape-hatch";
-const rule$15 = createRule({
+const RULE_NAME$16 = "no-escape-hatch";
+const rule$16 = createRule({
 	create(context) {
 		const removeBrackets = (range) => {
 			const [start, end] = range;
@@ -677,12 +677,12 @@ const rule$15 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$15
+	name: RULE_NAME$16
 });
 //#endregion
 //#region src/rules/no-hardcoded-color.ts
-const RULE_NAME$14 = "no-hardcoded-color";
-const rule$14 = createRule({
+const RULE_NAME$15 = "no-hardcoded-color";
+const rule$15 = createRule({
 	create(context) {
 		const noOpacity = context.options[0]?.noOpacity;
 		const whitelist = context.options[0]?.whitelist ?? [];
@@ -778,14 +778,14 @@ const rule$14 = createRule({
 		}],
 		type: "problem"
 	},
-	name: RULE_NAME$14
+	name: RULE_NAME$15
 });
 //#endregion
 //#region src/rules/no-important.ts
 const exclamationRegex = /\s*!$/;
 const importantRegex = /\s*!important\s*$/;
-const RULE_NAME$13 = "no-important";
-const rule$13 = createRule({
+const RULE_NAME$14 = "no-important";
+const rule$14 = createRule({
 	create(context) {
 		const removeQuotes = (range) => {
 			const [start, end] = range;
@@ -889,12 +889,12 @@ const rule$13 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$13
+	name: RULE_NAME$14
 });
 //#endregion
 //#region src/rules/no-invalid-nesting.ts
-const RULE_NAME$12 = "no-invalid-nesting";
-const rule$12 = createRule({
+const RULE_NAME$13 = "no-invalid-nesting";
+const rule$13 = createRule({
 	create(context) {
 		const bambooFunctionCache = /* @__PURE__ */ new WeakMap();
 		const jsxPropertyCache = /* @__PURE__ */ new WeakMap();
@@ -949,12 +949,12 @@ const rule$12 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$12
+	name: RULE_NAME$13
 });
 //#endregion
 //#region src/rules/no-invalid-token-paths.ts
-const RULE_NAME$11 = "no-invalid-token-paths";
-const rule$11 = createRule({
+const RULE_NAME$12 = "no-invalid-token-paths";
+const rule$12 = createRule({
 	create(context) {
 		const invalidTokensCache = /* @__PURE__ */ new Map();
 		const sendReport = (node, value) => {
@@ -1031,12 +1031,12 @@ const rule$11 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$11
+	name: RULE_NAME$12
 });
 //#endregion
 //#region src/rules/no-margin-properties.ts
-const RULE_NAME$10 = "no-margin-properties";
-const rule$10 = createRule({
+const RULE_NAME$11 = "no-margin-properties";
+const rule$11 = createRule({
 	create(context) {
 		const whitelist = context.options[0]?.whitelist ?? [];
 		const longhandCache = /* @__PURE__ */ new Map();
@@ -1112,7 +1112,7 @@ const rule$10 = createRule({
 		}],
 		type: "suggestion"
 	},
-	name: RULE_NAME$10
+	name: RULE_NAME$11
 });
 //#endregion
 //#region src/utils/physical-properties.ts
@@ -1156,7 +1156,7 @@ const physicalPropertyValues = { textAlign: {
 } };
 //#endregion
 //#region src/rules/no-physical-properties.ts
-const RULE_NAME$9 = "no-physical-properties";
+const RULE_NAME$10 = "no-physical-properties";
 const MESSAGES = {
 	physical: "Use logical property instead of {{physical}}. Prefer `{{logical}}`.",
 	physicalValue: "Use logical value instead of {{physical}}. Prefer `{{logical}}`.",
@@ -1238,7 +1238,7 @@ const createValueReport = (valueNode, valueText, logical, context) => {
 		}]
 	});
 };
-const rule$9 = createRule({
+const rule$10 = createRule({
 	create(context) {
 		const whitelist = context.options[0]?.whitelist ?? [];
 		const cache = new PropertyCache();
@@ -1294,12 +1294,12 @@ const rule$9 = createRule({
 		}],
 		type: "suggestion"
 	},
-	name: RULE_NAME$9
+	name: RULE_NAME$10
 });
 //#endregion
 //#region src/rules/no-property-renaming.ts
-const RULE_NAME$8 = "no-property-renaming";
-const rule$8 = createRule({
+const RULE_NAME$9 = "no-property-renaming";
+const rule$9 = createRule({
 	create(context) {
 		const bambooPropertyCache = /* @__PURE__ */ new WeakMap();
 		const bambooAttributeCache = /* @__PURE__ */ new WeakMap();
@@ -1363,11 +1363,11 @@ const rule$8 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$8
+	name: RULE_NAME$9
 });
 //#endregion
 //#region src/rules/no-unlayered-override.ts
-const RULE_NAME$7 = "no-unlayered-override";
+const RULE_NAME$8 = "no-unlayered-override";
 /**
 * The call whose result is a class string in the `utilities` layer — the same layer a
 * consumer's `css()` is in, so neither can win over the other by cascade.
@@ -1392,7 +1392,7 @@ const isOpaque = (node) => {
 	if (isIdentifier(node) && node.name !== "undefined") return true;
 	return false;
 };
-const rule$7 = createRule({
+const rule$8 = createRule({
 	create(context) {
 		if (!isValidFile(context)) return {};
 		const isOwnStyles = (node) => {
@@ -1422,6 +1422,161 @@ const rule$7 = createRule({
 		schema: [],
 		type: "problem"
 	},
+	name: RULE_NAME$8
+});
+//#endregion
+//#region src/rules/require-literal-token-path.ts
+const RULE_NAME$7 = "require-literal-token-path";
+/**
+* The wrappers a typed caller writes around a path, which carry no runtime meaning.
+*
+* The generated `Token` type is a union of template literals, so a `string`-typed substitution
+* does not typecheck without an assertion — `` token(`colors.${shade}` as Token) `` is the
+* idiomatic spelling, and reading only the outermost node would report it as dynamic when the
+* build bounds it perfectly well.
+*/
+const unwrap = (node) => {
+	switch (node.type) {
+		case "TSAsExpression":
+		case "TSSatisfiesExpression":
+		case "TSNonNullExpression":
+		case "TSTypeAssertion": return unwrap(node.expression);
+		default: return node;
+	}
+};
+/**
+* How much of a token path the build can see.
+*
+* `literal` is a path spelled at the call. `bounded` is a template whose static head names a
+* category — the build cannot say which token it wants but knows which it cannot, so it keeps
+* that category and prunes the rest. `opaque` is everything else.
+*
+* Mirrors `literalPath` in `@bamboocss/node`, down to reading the *cooked* head and treating an
+* empty one as no bound at all. The rule's whole value is predicting what the build will do,
+* so a disagreement here is worse than no rule.
+*/
+const reach = (argument) => {
+	if (!argument) return "opaque";
+	const node = unwrap(argument);
+	if (isLiteral(node) && typeof node.value === "string") return "literal";
+	if (isTemplateLiteral(node)) {
+		if (node.expressions.length === 0) return "literal";
+		return node.quasis[0]?.value.cooked ? "bounded" : "opaque";
+	}
+	return "opaque";
+};
+/** A member name, whether written `a.b` or `a['b']`. */
+const memberName = (node) => {
+	if (!node.computed) return isIdentifier(node.property) ? node.property.name : void 0;
+	return isLiteral(node.property) && typeof node.property.value === "string" ? node.property.value : void 0;
+};
+const rule$7 = createRule({
+	create(context) {
+		/**
+		* Names bound to the generated token artifact in this file.
+		*
+		* Collected here rather than through the shared `getTokenImport`, which searches *every*
+		* module for a specifier named `token` and takes the first. That is wrong in both
+		* directions: an unrelated `import { token as authToken } from './auth'` made this rule
+		* report on a file with no Bamboo in it, and — worse — an unrelated `token` import
+		* declared above the real one *masked* it, so whether a genuinely dynamic path was
+		* reported depended on import order.
+		*
+		* The specifier test is a substring, like the build's cheap pass. It over-matches
+		* `./tokenserver`, which is harmless: the build declines a `token` call through any
+		* namespace it cannot classify, so over-matching agrees with it. It under-matches a
+		* tsconfig path alias, which the build resolves and this cannot — that gap is documented
+		* rather than papered over.
+		*/
+		let bindings;
+		const bound = () => {
+			if (bindings) return bindings;
+			bindings = {
+				direct: /* @__PURE__ */ new Set(),
+				namespaces: /* @__PURE__ */ new Set()
+			};
+			for (const node of context.sourceCode.ast.body) {
+				if (node.type !== "ImportDeclaration") continue;
+				if (!String(node.source.value).includes("tokens")) continue;
+				for (const specifier of node.specifiers) {
+					if (specifier.type === "ImportNamespaceSpecifier") bindings.namespaces.add(specifier.local.name);
+					if (specifier.type === "ImportSpecifier" && isIdentifier(specifier.imported)) {
+						if (specifier.imported.name === "token") bindings.direct.add(specifier.local.name);
+					}
+				}
+			}
+			return bindings;
+		};
+		/**
+		* Whether this call reaches the generated `token`.
+		*
+		* A bare `token(…)` counts even with no import to bind it, because the build counts it: its
+		* accounting keys on the name, so a local helper of that name declines there too. Staying
+		* quiet about it would mean `strict` failing a build the editor called clean.
+		*/
+		const isTokenCall = (node) => {
+			const callee = node.type === "CallExpression" ? node.callee : node.tag;
+			const { direct, namespaces } = bound();
+			if (isIdentifier(callee)) return direct.has(callee.name) || callee.name === "token";
+			if (callee.type !== "MemberExpression") return false;
+			if (callee.computed) return isComputedTokenCallee(callee, direct, namespaces) ? "computed" : false;
+			const property = memberName(callee);
+			if (property === void 0) return false;
+			if (isIdentifier(callee.object) && (direct.has(callee.object.name) || callee.object.name === "token")) return property === "value";
+			if (property === "token") return isIdentifier(callee.object) && namespaces.has(callee.object.name);
+			return property === "value" && callee.object.type === "MemberExpression" && memberName(callee.object) === "token" && isIdentifier(callee.object.object) && namespaces.has(callee.object.object.name);
+		};
+		/** The same shapes as below, but reached through a computed member. */
+		const isComputedTokenCallee = (callee, direct, namespaces) => {
+			const property = memberName(callee);
+			if (property === void 0) return false;
+			if (isIdentifier(callee.object) && (direct.has(callee.object.name) || callee.object.name === "token")) return property === "value";
+			if (property === "token") return isIdentifier(callee.object) && namespaces.has(callee.object.name);
+			return false;
+		};
+		const report = (node, found, at) => {
+			context.report({
+				messageId: found === "bounded" ? "boundedTokenPath" : "opaqueTokenPath",
+				node: at
+			});
+		};
+		return {
+			CallExpression(node) {
+				const kind = isTokenCall(node);
+				if (!kind) return;
+				const found = kind === "computed" ? "opaque" : reach(node.arguments[0]);
+				if (found === "literal") return;
+				report(node, found, node.arguments[0] ?? node);
+			},
+			/**
+			* `` token`colors.${s}` `` — a different node, and one the build declines outright since
+			* the artifact exports a function rather than a tag. Reported as opaque whatever its
+			* head, because the call never resolves at all.
+			*/
+			TaggedTemplateExpression(node) {
+				if (!isTokenCall(node)) return;
+				report(node, "opaque", node.quasi);
+			}
+		};
+	},
+	defaultOptions: [],
+	meta: {
+		docs: { description: "Require a token path the build can resolve, so `pruneUnusedTokens` can drop the declarations nothing asks for." },
+		messages: {
+			/**
+			* The build keeps every token declaration for this, because the path could name any of
+			* them. Under `pruneUnusedTokens: 'strict'` it is an error rather than a size cost.
+			*/
+			opaqueTokenPath: "Token path cannot be resolved at build time, so every token declaration is kept. Spell the path at the call, or give a template a static prefix.",
+			/**
+			* Not wrong — the build keeps the category and prunes the rest — but a spelled-out path
+			* keeps one declaration where this keeps hundreds, so it is worth knowing about.
+			*/
+			boundedTokenPath: "Token path is bounded by its prefix rather than resolved, so the whole category is kept. Spell the path at the call to keep only what you use."
+		},
+		schema: [],
+		type: "problem"
+	},
 	name: RULE_NAME$7
 });
 //#endregion
@@ -2339,6 +2494,7 @@ const rule = createRule({
 //#endregion
 //#region src/rules/index.ts
 const rules = {
+	[RULE_NAME$21]: rule$21,
 	[RULE_NAME$20]: rule$20,
 	[RULE_NAME$19]: rule$19,
 	[RULE_NAME$18]: rule$18,
@@ -2364,9 +2520,9 @@ const rules = {
 //#endregion
 //#region src/configs/all.ts
 const errorRules = [
+	RULE_NAME$21,
 	RULE_NAME$20,
-	RULE_NAME$19,
-	RULE_NAME$11
+	RULE_NAME$12
 ];
 //#endregion
 //#region src/index.ts

package/dist/index.mjs

@@ -8,7 +8,7 @@ import "@typescript-eslint/utils/ts-eslint";
 import { getArbitraryValue, parseFallbackValue } from "@bamboocss/shared";
 //#region package.json
 var name = "@bamboocss/eslint-plugin";
-var version = "1.29.0";
+var version = "1.30.0";
 //#endregion
 //#region src/utils/index.ts
 const createRule = ESLintUtils.RuleCreator((name) => `https://github.com/bamboocss/bamboo/blob/main/packages/eslint-plugin/docs/rules/${name}.md`);
@@ -307,8 +307,8 @@ function isRecipeVariant(node, context) {
 }
 //#endregion
 //#region src/rules/file-not-included.ts
-const RULE_NAME$20 = "file-not-included";
-const rule$20 = createRule({
+const RULE_NAME$21 = "file-not-included";
+const rule$21 = createRule({
 	create(context) {
 		if (isValidFile(context)) return {};
 		let hasReported = false;
@@ -329,11 +329,11 @@ const rule$20 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$20
+	name: RULE_NAME$21
 });
 //#endregion
 //#region src/rules/no-config-function-in-source.ts
-const RULE_NAME$19 = "no-config-function-in-source";
+const RULE_NAME$20 = "no-config-function-in-source";
 const CONFIG_FUNCTIONS = new Set([
 	"defineConfig",
 	"defineGlobalStyles",
@@ -350,7 +350,7 @@ const CONFIG_FUNCTIONS = new Set([
 	"defineTokens",
 	"defineUtility"
 ]);
-const rule$19 = createRule({
+const rule$20 = createRule({
 	create(context) {
 		if (!hasPkgImport(context)) return {};
 		if (!isValidFile(context)) return {};
@@ -390,12 +390,12 @@ const rule$19 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$19
+	name: RULE_NAME$20
 });
 //#endregion
 //#region src/rules/no-debug.ts
-const RULE_NAME$18 = "no-debug";
-const rule$18 = createRule({
+const RULE_NAME$19 = "no-debug";
+const rule$19 = createRule({
 	create(context) {
 		const processedNodes = /* @__PURE__ */ new WeakSet();
 		const checkObjectForDebug = (object) => {
@@ -464,12 +464,12 @@ const rule$18 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$18
+	name: RULE_NAME$19
 });
 //#endregion
 //#region src/rules/no-deprecated-tokens.ts
-const RULE_NAME$17 = "no-deprecated-tokens";
-const rule$17 = createRule({
+const RULE_NAME$18 = "no-deprecated-tokens";
+const rule$18 = createRule({
 	create(context) {
 		const deprecatedTokensCache = /* @__PURE__ */ new Map();
 		const sendReport = (property, node, value) => {
@@ -523,12 +523,12 @@ const rule$17 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$17
+	name: RULE_NAME$18
 });
 //#endregion
 //#region src/rules/no-dynamic-styling.ts
-const RULE_NAME$16 = "no-dynamic-styling";
-const rule$16 = createRule({
+const RULE_NAME$17 = "no-dynamic-styling";
+const rule$17 = createRule({
 	create(context) {
 		function isStaticValue(node) {
 			if (!node) return false;
@@ -599,12 +599,12 @@ const rule$16 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$16
+	name: RULE_NAME$17
 });
 //#endregion
 //#region src/rules/no-escape-hatch.ts
-const RULE_NAME$15 = "no-escape-hatch";
-const rule$15 = createRule({
+const RULE_NAME$16 = "no-escape-hatch";
+const rule$16 = createRule({
 	create(context) {
 		const removeBrackets = (range) => {
 			const [start, end] = range;
@@ -677,12 +677,12 @@ const rule$15 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$15
+	name: RULE_NAME$16
 });
 //#endregion
 //#region src/rules/no-hardcoded-color.ts
-const RULE_NAME$14 = "no-hardcoded-color";
-const rule$14 = createRule({
+const RULE_NAME$15 = "no-hardcoded-color";
+const rule$15 = createRule({
 	create(context) {
 		const noOpacity = context.options[0]?.noOpacity;
 		const whitelist = context.options[0]?.whitelist ?? [];
@@ -778,14 +778,14 @@ const rule$14 = createRule({
 		}],
 		type: "problem"
 	},
-	name: RULE_NAME$14
+	name: RULE_NAME$15
 });
 //#endregion
 //#region src/rules/no-important.ts
 const exclamationRegex = /\s*!$/;
 const importantRegex = /\s*!important\s*$/;
-const RULE_NAME$13 = "no-important";
-const rule$13 = createRule({
+const RULE_NAME$14 = "no-important";
+const rule$14 = createRule({
 	create(context) {
 		const removeQuotes = (range) => {
 			const [start, end] = range;
@@ -889,12 +889,12 @@ const rule$13 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$13
+	name: RULE_NAME$14
 });
 //#endregion
 //#region src/rules/no-invalid-nesting.ts
-const RULE_NAME$12 = "no-invalid-nesting";
-const rule$12 = createRule({
+const RULE_NAME$13 = "no-invalid-nesting";
+const rule$13 = createRule({
 	create(context) {
 		const bambooFunctionCache = /* @__PURE__ */ new WeakMap();
 		const jsxPropertyCache = /* @__PURE__ */ new WeakMap();
@@ -949,12 +949,12 @@ const rule$12 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$12
+	name: RULE_NAME$13
 });
 //#endregion
 //#region src/rules/no-invalid-token-paths.ts
-const RULE_NAME$11 = "no-invalid-token-paths";
-const rule$11 = createRule({
+const RULE_NAME$12 = "no-invalid-token-paths";
+const rule$12 = createRule({
 	create(context) {
 		const invalidTokensCache = /* @__PURE__ */ new Map();
 		const sendReport = (node, value) => {
@@ -1031,12 +1031,12 @@ const rule$11 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$11
+	name: RULE_NAME$12
 });
 //#endregion
 //#region src/rules/no-margin-properties.ts
-const RULE_NAME$10 = "no-margin-properties";
-const rule$10 = createRule({
+const RULE_NAME$11 = "no-margin-properties";
+const rule$11 = createRule({
 	create(context) {
 		const whitelist = context.options[0]?.whitelist ?? [];
 		const longhandCache = /* @__PURE__ */ new Map();
@@ -1112,7 +1112,7 @@ const rule$10 = createRule({
 		}],
 		type: "suggestion"
 	},
-	name: RULE_NAME$10
+	name: RULE_NAME$11
 });
 //#endregion
 //#region src/utils/physical-properties.ts
@@ -1156,7 +1156,7 @@ const physicalPropertyValues = { textAlign: {
 } };
 //#endregion
 //#region src/rules/no-physical-properties.ts
-const RULE_NAME$9 = "no-physical-properties";
+const RULE_NAME$10 = "no-physical-properties";
 const MESSAGES = {
 	physical: "Use logical property instead of {{physical}}. Prefer `{{logical}}`.",
 	physicalValue: "Use logical value instead of {{physical}}. Prefer `{{logical}}`.",
@@ -1238,7 +1238,7 @@ const createValueReport = (valueNode, valueText, logical, context) => {
 		}]
 	});
 };
-const rule$9 = createRule({
+const rule$10 = createRule({
 	create(context) {
 		const whitelist = context.options[0]?.whitelist ?? [];
 		const cache = new PropertyCache();
@@ -1294,12 +1294,12 @@ const rule$9 = createRule({
 		}],
 		type: "suggestion"
 	},
-	name: RULE_NAME$9
+	name: RULE_NAME$10
 });
 //#endregion
 //#region src/rules/no-property-renaming.ts
-const RULE_NAME$8 = "no-property-renaming";
-const rule$8 = createRule({
+const RULE_NAME$9 = "no-property-renaming";
+const rule$9 = createRule({
 	create(context) {
 		const bambooPropertyCache = /* @__PURE__ */ new WeakMap();
 		const bambooAttributeCache = /* @__PURE__ */ new WeakMap();
@@ -1363,11 +1363,11 @@ const rule$8 = createRule({
 		schema: [],
 		type: "problem"
 	},
-	name: RULE_NAME$8
+	name: RULE_NAME$9
 });
 //#endregion
 //#region src/rules/no-unlayered-override.ts
-const RULE_NAME$7 = "no-unlayered-override";
+const RULE_NAME$8 = "no-unlayered-override";
 /**
 * The call whose result is a class string in the `utilities` layer — the same layer a
 * consumer's `css()` is in, so neither can win over the other by cascade.
@@ -1392,7 +1392,7 @@ const isOpaque = (node) => {
 	if (isIdentifier(node) && node.name !== "undefined") return true;
 	return false;
 };
-const rule$7 = createRule({
+const rule$8 = createRule({
 	create(context) {
 		if (!isValidFile(context)) return {};
 		const isOwnStyles = (node) => {
@@ -1422,6 +1422,161 @@ const rule$7 = createRule({
 		schema: [],
 		type: "problem"
 	},
+	name: RULE_NAME$8
+});
+//#endregion
+//#region src/rules/require-literal-token-path.ts
+const RULE_NAME$7 = "require-literal-token-path";
+/**
+* The wrappers a typed caller writes around a path, which carry no runtime meaning.
+*
+* The generated `Token` type is a union of template literals, so a `string`-typed substitution
+* does not typecheck without an assertion — `` token(`colors.${shade}` as Token) `` is the
+* idiomatic spelling, and reading only the outermost node would report it as dynamic when the
+* build bounds it perfectly well.
+*/
+const unwrap = (node) => {
+	switch (node.type) {
+		case "TSAsExpression":
+		case "TSSatisfiesExpression":
+		case "TSNonNullExpression":
+		case "TSTypeAssertion": return unwrap(node.expression);
+		default: return node;
+	}
+};
+/**
+* How much of a token path the build can see.
+*
+* `literal` is a path spelled at the call. `bounded` is a template whose static head names a
+* category — the build cannot say which token it wants but knows which it cannot, so it keeps
+* that category and prunes the rest. `opaque` is everything else.
+*
+* Mirrors `literalPath` in `@bamboocss/node`, down to reading the *cooked* head and treating an
+* empty one as no bound at all. The rule's whole value is predicting what the build will do,
+* so a disagreement here is worse than no rule.
+*/
+const reach = (argument) => {
+	if (!argument) return "opaque";
+	const node = unwrap(argument);
+	if (isLiteral(node) && typeof node.value === "string") return "literal";
+	if (isTemplateLiteral(node)) {
+		if (node.expressions.length === 0) return "literal";
+		return node.quasis[0]?.value.cooked ? "bounded" : "opaque";
+	}
+	return "opaque";
+};
+/** A member name, whether written `a.b` or `a['b']`. */
+const memberName = (node) => {
+	if (!node.computed) return isIdentifier(node.property) ? node.property.name : void 0;
+	return isLiteral(node.property) && typeof node.property.value === "string" ? node.property.value : void 0;
+};
+const rule$7 = createRule({
+	create(context) {
+		/**
+		* Names bound to the generated token artifact in this file.
+		*
+		* Collected here rather than through the shared `getTokenImport`, which searches *every*
+		* module for a specifier named `token` and takes the first. That is wrong in both
+		* directions: an unrelated `import { token as authToken } from './auth'` made this rule
+		* report on a file with no Bamboo in it, and — worse — an unrelated `token` import
+		* declared above the real one *masked* it, so whether a genuinely dynamic path was
+		* reported depended on import order.
+		*
+		* The specifier test is a substring, like the build's cheap pass. It over-matches
+		* `./tokenserver`, which is harmless: the build declines a `token` call through any
+		* namespace it cannot classify, so over-matching agrees with it. It under-matches a
+		* tsconfig path alias, which the build resolves and this cannot — that gap is documented
+		* rather than papered over.
+		*/
+		let bindings;
+		const bound = () => {
+			if (bindings) return bindings;
+			bindings = {
+				direct: /* @__PURE__ */ new Set(),
+				namespaces: /* @__PURE__ */ new Set()
+			};
+			for (const node of context.sourceCode.ast.body) {
+				if (node.type !== "ImportDeclaration") continue;
+				if (!String(node.source.value).includes("tokens")) continue;
+				for (const specifier of node.specifiers) {
+					if (specifier.type === "ImportNamespaceSpecifier") bindings.namespaces.add(specifier.local.name);
+					if (specifier.type === "ImportSpecifier" && isIdentifier(specifier.imported)) {
+						if (specifier.imported.name === "token") bindings.direct.add(specifier.local.name);
+					}
+				}
+			}
+			return bindings;
+		};
+		/**
+		* Whether this call reaches the generated `token`.
+		*
+		* A bare `token(…)` counts even with no import to bind it, because the build counts it: its
+		* accounting keys on the name, so a local helper of that name declines there too. Staying
+		* quiet about it would mean `strict` failing a build the editor called clean.
+		*/
+		const isTokenCall = (node) => {
+			const callee = node.type === "CallExpression" ? node.callee : node.tag;
+			const { direct, namespaces } = bound();
+			if (isIdentifier(callee)) return direct.has(callee.name) || callee.name === "token";
+			if (callee.type !== "MemberExpression") return false;
+			if (callee.computed) return isComputedTokenCallee(callee, direct, namespaces) ? "computed" : false;
+			const property = memberName(callee);
+			if (property === void 0) return false;
+			if (isIdentifier(callee.object) && (direct.has(callee.object.name) || callee.object.name === "token")) return property === "value";
+			if (property === "token") return isIdentifier(callee.object) && namespaces.has(callee.object.name);
+			return property === "value" && callee.object.type === "MemberExpression" && memberName(callee.object) === "token" && isIdentifier(callee.object.object) && namespaces.has(callee.object.object.name);
+		};
+		/** The same shapes as below, but reached through a computed member. */
+		const isComputedTokenCallee = (callee, direct, namespaces) => {
+			const property = memberName(callee);
+			if (property === void 0) return false;
+			if (isIdentifier(callee.object) && (direct.has(callee.object.name) || callee.object.name === "token")) return property === "value";
+			if (property === "token") return isIdentifier(callee.object) && namespaces.has(callee.object.name);
+			return false;
+		};
+		const report = (node, found, at) => {
+			context.report({
+				messageId: found === "bounded" ? "boundedTokenPath" : "opaqueTokenPath",
+				node: at
+			});
+		};
+		return {
+			CallExpression(node) {
+				const kind = isTokenCall(node);
+				if (!kind) return;
+				const found = kind === "computed" ? "opaque" : reach(node.arguments[0]);
+				if (found === "literal") return;
+				report(node, found, node.arguments[0] ?? node);
+			},
+			/**
+			* `` token`colors.${s}` `` — a different node, and one the build declines outright since
+			* the artifact exports a function rather than a tag. Reported as opaque whatever its
+			* head, because the call never resolves at all.
+			*/
+			TaggedTemplateExpression(node) {
+				if (!isTokenCall(node)) return;
+				report(node, "opaque", node.quasi);
+			}
+		};
+	},
+	defaultOptions: [],
+	meta: {
+		docs: { description: "Require a token path the build can resolve, so `pruneUnusedTokens` can drop the declarations nothing asks for." },
+		messages: {
+			/**
+			* The build keeps every token declaration for this, because the path could name any of
+			* them. Under `pruneUnusedTokens: 'strict'` it is an error rather than a size cost.
+			*/
+			opaqueTokenPath: "Token path cannot be resolved at build time, so every token declaration is kept. Spell the path at the call, or give a template a static prefix.",
+			/**
+			* Not wrong — the build keeps the category and prunes the rest — but a spelled-out path
+			* keeps one declaration where this keeps hundreds, so it is worth knowing about.
+			*/
+			boundedTokenPath: "Token path is bounded by its prefix rather than resolved, so the whole category is kept. Spell the path at the call to keep only what you use."
+		},
+		schema: [],
+		type: "problem"
+	},
 	name: RULE_NAME$7
 });
 //#endregion
@@ -2339,6 +2494,7 @@ const rule = createRule({
 //#endregion
 //#region src/rules/index.ts
 const rules = {
+	[RULE_NAME$21]: rule$21,
 	[RULE_NAME$20]: rule$20,
 	[RULE_NAME$19]: rule$19,
 	[RULE_NAME$18]: rule$18,
@@ -2364,9 +2520,9 @@ const rules = {
 //#endregion
 //#region src/configs/all.ts
 const errorRules = [
+	RULE_NAME$21,
 	RULE_NAME$20,
-	RULE_NAME$19,
-	RULE_NAME$11
+	RULE_NAME$12
 ];
 //#endregion
 //#region src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bamboocss/eslint-plugin",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "description": "ESLint plugin for Bamboo CSS",
   "homepage": "https://bamboocss.com",
   "license": "MIT",
@@ -36,9 +36,9 @@
     "@typescript-eslint/utils": "^8.21.0",
     "micromatch": "^4.0.8",
     "synckit": "^0.9.0",
-    "@bamboocss/config": "1.29.0",
-    "@bamboocss/generator": "1.29.0",
-    "@bamboocss/shared": "1.29.0"
+    "@bamboocss/config": "1.30.0",
+    "@bamboocss/generator": "1.30.0",
+    "@bamboocss/shared": "1.30.0"
   },
   "devDependencies": {
     "@types/micromatch": "^4.0.10",
@@ -46,10 +46,10 @@
     "eslint": "^9.35.0",
     "multiline-ts": "^4.0.1",
     "typescript": "^5.7.2",
-    "@bamboocss/dev": "1.29.0",
-    "@bamboocss/preset-bamboo": "1.29.0",
-    "@bamboocss/preset-base": "1.29.0",
-    "@bamboocss/types": "1.29.0"
+    "@bamboocss/dev": "1.30.0",
+    "@bamboocss/preset-bamboo": "1.30.0",
+    "@bamboocss/preset-base": "1.30.0",
+    "@bamboocss/types": "1.30.0"
   },
   "peerDependencies": {
     "eslint": "*"