@cssdoc/providers 0.4.2 → 0.5.1

package/dist/index.d.mts

@@ -38,6 +38,14 @@ interface Diagnostic {
   span?: SourceSpan$1;
   /** Severity (defaults to `warning`). */
   severity: Severity;
+  /**
+   * Optional structured payload for consumers. `maskedName` is the class token as it appears in the
+   * linted (possibly projected) source, so the language server can restore an embedded `${…}`
+   * interpolation for display instead of the masked filler.
+   */
+  data?: {
+    maskedName?: string;
+  };
 }
 /** What kind of thing a completion inserts. */
 type CompletionKind = "component" | "modifier" | "part" | "property" | "function" | "state";
@@ -177,7 +185,7 @@ declare function applyDirectives(diagnostics: Diagnostic[], source: string): Dia
 //#endregion
 //#region src/aspects.d.ts
 declare const record: {
-  model(index: CssDocIndex, naming?: ResolvedNaming, structureIgnore?: readonly string[]): Diagnostic[];
+  model(index: CssDocIndex, naming?: ResolvedNaming, structureIgnore?: readonly string[], siblingIndex?: CssDocIndex): Diagnostic[];
   completions(index: CssDocIndex): Completion[];
   hover(base: string, index: CssDocIndex, detail?: HoverDetail, sections?: HoverSections, sectionOrder?: HoverSectionOrder): Hover | undefined;
   definition(base: string, index: CssDocIndex): Location$1 | undefined;
@@ -217,7 +225,7 @@ declare const func: {
 /** The aspect names covered, in a stable order (the extension point for future aspects). */
 declare const ASPECTS: readonly ["record", "modifier", "part", "css-part", "custom-property", "structure", "function", "state", "condition"];
 /** Author-side hygiene diagnostics over the whole model (missing summaries, undocumented members, drift, invalid defaults). */
-declare function lintModel(index: CssDocIndex, severities?: RuleSeverities, naming?: ResolvedNaming, structureIgnore?: readonly string[]): Diagnostic[];
+declare function lintModel(index: CssDocIndex, severities?: RuleSeverities, naming?: ResolvedNaming, structureIgnore?: readonly string[], siblingIndex?: CssDocIndex): Diagnostic[];
 /** Consumer-side diagnostics for custom-property assignments (`--x: value` must match its `@property` syntax). */
 declare function checkPropertyAssignments(assignments: readonly PropertyAssignment[], index: CssDocIndex, severities?: RuleSeverities): Diagnostic[];
 /**

package/dist/index.mjs

@@ -177,6 +177,38 @@ const warn = (d) => ({
 	...d,
 	severity: "warning"
 });
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+/** A `*`-glob name (e.g. `-icon-*`) as a regex source over one class token (`*` → any `[\w-]` run). */
+const globSource = (name) => name.split("*").map(escapeRe).join("[\\w-]*");
+/** `class` attribute selectors, capturing the operator (`~`/`^`/`$`/`*`/`|`/none) and the value. */
+const CLASS_ATTR_RE = /\[\s*class\s*([~^$*|]?)=\s*(?:"([^"]*)"|'([^']*)'|([^\]\s]*))\s*\]/gu;
+/**
+* Whether `selectorText` (the record's concatenated selectors) defines the modifier/part `selector`
+* (`.name`, where `name` may be a `*` glob for a family like `.-icon-*`; a name with no `*` is exact).
+* Beyond a literal class token, `class` attribute selectors count with their real CSS operator
+* semantics — `[class~=v]`/`[class=v]` (exact word), `[class*=v]` (substring), and `[class$=v]` (suffix)
+* can define a chained modifier; `[class^=v]` cannot, since `^=` anchors to the start of the whole
+* attribute (the base class), never a chained modifier.
+*/
+const selectorDefines = (selectorText, selector) => {
+	if (!selector.startsWith(".")) return selectorText.includes(selector);
+	const name = stripDot(selector);
+	const wild = name.includes("*");
+	const prefix = name.split("*")[0];
+	if (new RegExp(`\\.${globSource(name)}(?![\\w-])`, "u").test(selectorText)) return true;
+	const glob = new RegExp(`^${globSource(name)}$`, "u");
+	for (const m of selectorText.matchAll(CLASS_ATTR_RE)) {
+		const op = m[1];
+		const v = m[2] ?? m[3] ?? m[4] ?? "";
+		if (!v || op === "^") continue;
+		if (op === "*") {
+			if (wild ? prefix.includes(v) || v.includes(prefix) : name.includes(v)) return true;
+		} else if (op === "$") {
+			if (wild ? v.endsWith(prefix) || prefix.endsWith(v) : name.endsWith(v)) return true;
+		} else if (glob.test(v)) return true;
+	}
+	return false;
+};
 /**
 * Match a class name against a `structureIgnore` pattern — a literal name or a simple glob where `*`
 * stands for any run of characters (e.g. `util-*`, `*--legacy`, `*`). Matched literally otherwise.
@@ -199,8 +231,10 @@ const renderStructureTree = (nodes, depth = 0) => nodes.flatMap((n) => {
 	] : [`${pad}${n.selector}`];
 });
 const record = {
-	model(index, naming, structureIgnore = []) {
+	model(index, naming, structureIgnore = [], siblingIndex = index) {
 		const out = [];
+		const siblingClasses = new Set(siblingIndex.records.map((r) => stripDot(r.entry.className)));
+		const siblingNames = new Set(siblingIndex.records.flatMap((r) => r.entry.kind === "component" ? [r.entry.name] : []));
 		for (const info of index.records) {
 			if (!info.entry.summary?.trim()) out.push(warn({
 				aspect: "record",
@@ -221,25 +255,30 @@ const record = {
 			if (info.entry.structure?.length) {
 				const known = /* @__PURE__ */ new Set([
 					stripDot(info.entry.className),
+					...siblingClasses,
 					...info.entry.parts.flatMap((p) => [stripDot(p.name), ...(p.modifiers ?? []).map((m) => m.name)]),
 					...info.entry.shadowParts.map((p) => stripDot(p.name)),
 					...info.entry.states.map((s) => s.name),
 					...info.entry.modifiers.map((m) => m.name),
 					...info.entry.slots.map((s) => s.name)
 				]);
+				const own = stripDot(info.entry.className);
+				const prefix = info.entry.name && own.endsWith(info.entry.name) ? own.slice(0, own.length - info.entry.name.length) : "";
+				const isSibling = (cls) => prefix !== "" && cls.startsWith(prefix) && siblingNames.has(cls.slice(prefix.length));
 				const seen = /* @__PURE__ */ new Set();
 				const walk = (nodes) => {
 					for (const node of nodes) {
 						for (const m of node.selector.matchAll(/\.([\w-]+)/gu)) {
 							const cls = m[1];
-							if (seen.has(cls) || known.has(cls) || structureIgnore.some((g) => globMatch(g, cls))) continue;
+							if (seen.has(cls) || known.has(cls) || isSibling(cls) || structureIgnore.some((g) => globMatch(g, cls))) continue;
 							seen.add(cls);
 							out.push(warn({
 								aspect: "record",
 								rule: "structure-unknown-selector",
 								message: `@structure references ".${cls}", which isn't the component class or a documented member (add it, or list it under structureIgnore).`,
 								record: info.entry.name,
-								span: info.span
+								span: info.span,
+								data: { maskedName: cls }
 							}));
 						}
 						walk(node.children);
@@ -390,13 +429,18 @@ const modifier = {
 					span
 				}));
 			}
-			for (const authored of info.authoredModifiers) if (!info.selectorText.includes(index.matcher.selectorFor(authored))) out.push(warn({
-				aspect: "modifier",
-				rule: "name-not-in-css",
-				message: `Documented modifier "${index.matcher.selectorFor(authored)}" of "${name}" is not defined by any selector.`,
-				record: name,
-				span: info.span
-			}));
+			const deprecated = new Set(info.entry.modifiers.filter((m) => m.deprecated).map((m) => m.name));
+			for (const authored of info.authoredModifiers) {
+				if (deprecated.has(authored)) continue;
+				const sel = index.matcher.selectorFor(authored);
+				if (!selectorDefines(info.selectorText, sel)) out.push(warn({
+					aspect: "modifier",
+					rule: "name-not-in-css",
+					message: `Documented modifier "${sel}" of "${name}" is not defined by any selector.`,
+					record: name,
+					span: info.span
+				}));
+			}
 		}
 		return out;
 	},
@@ -473,7 +517,7 @@ const part = { model(index, naming) {
 				span: info.memberSpans.get(memberKey("part", p.name)) ?? info.span
 			}));
 		}
-		for (const authored of info.authoredParts) if (!info.selectorText.includes(`.${authored}`)) out.push(warn({
+		for (const authored of info.authoredParts) if (!selectorDefines(info.selectorText, `.${authored}`)) out.push(warn({
 			aspect: "part",
 			rule: "name-not-in-css",
 			message: `Documented part ".${authored}" of "${name}" is not defined by any selector.`,
@@ -762,9 +806,9 @@ const ASPECTS = [
 	"condition"
 ];
 /** Author-side hygiene diagnostics over the whole model (missing summaries, undocumented members, drift, invalid defaults). */
-function lintModel(index, severities = DEFAULT_RULE_SEVERITIES, naming, structureIgnore) {
+function lintModel(index, severities = DEFAULT_RULE_SEVERITIES, naming, structureIgnore, siblingIndex) {
 	return applySeverities([
-		...record.model(index, naming, structureIgnore),
+		...record.model(index, naming, structureIgnore, siblingIndex),
 		...modifier.model(index),
 		...part.model(index, naming),
 		...cssPart.model(index),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cssdoc/providers",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Host-agnostic aspect providers over the @cssdoc/index — diagnostics, completions, hover, and definitions for modifiers, custom properties, structure, functions, states, and conditions.",
   "keywords": [
     "css",
@@ -29,8 +29,8 @@
   },
   "dependencies": {
     "css-tree": "^3.2.1",
-    "@cssdoc/core": "0.4.2",
-    "@cssdoc/index": "0.4.2"
+    "@cssdoc/core": "0.5.1",
+    "@cssdoc/index": "0.5.1"
   },
   "devDependencies": {
     "@types/css-tree": "^2.3.11",