@cssdoc/providers 0.1.0 → 0.3.0

package/dist/index.d.mts

@@ -3,6 +3,27 @@ import { ClassUsage, CssDocIndex, Location, Location as Location$1, PropertyAssi
 //#region src/types.d.ts
 /** Diagnostic severity. */
 type Severity = "error" | "warning";
+/** A configurable per-rule severity — `off` suppresses the rule entirely. */
+type RuleSeverity = "off" | "warn" | "error";
+/**
+ * Every rule id an aspect can emit, author-side and consumer-side. A superset of `@cssdoc/lint-core`'s
+ * author-side `RuleName` (which omits the consumer-side `unknown-modifier`/`deprecated-modifier` and
+ * the opt-in `unknown-custom-property`).
+ */
+type RuleId = "missing-summary" | "undocumented-modifier" | "deprecated-requires-canonical" | "name-not-in-css" | "unknown-modifier" | "deprecated-modifier" | "unknown-state" | "unknown-part" | "undocumented-part" | "undocumented-css-part" | "component-name-case" | "part-name-case" | "structure-unknown-selector" | "invalid-default-value" | "invalid-property-value" | "invalid-fallback-value" | "unknown-custom-property" | "cssdoc-directive";
+/** A resolved severity for every rule. */
+type RuleSeverities = Record<RuleId, RuleSeverity>;
+/**
+ * The default rule severities. `unknown-modifier` defaults to `warn` — safe under the BEM default's
+ * strong `--` signal; lower it to `off` for weak-signal conventions (bare/OOCSS) where every chained
+ * class is a candidate. `unknown-custom-property` stays `off` (it needs an opt-in `propertyPrefix`).
+ */
+declare const DEFAULT_RULE_SEVERITIES: RuleSeverities;
+/**
+ * Merge per-rule overrides over {@link DEFAULT_RULE_SEVERITIES}. A `boolean` override is accepted for
+ * back-compat: `false` → `off`, `true` → the rule's default.
+ */
+declare function resolveRuleSeverities(overrides?: Partial<Record<RuleId, RuleSeverity | boolean>>): RuleSeverities;
 /** One diagnostic from an aspect. */
 interface Diagnostic {
   /** The aspect that produced it (e.g. `modifier`). */
@@ -44,6 +65,27 @@ interface UsageOptions {
    */
   propertyPrefix?: string;
 }
+/**
+ * A required name case: a built-in preset, or a custom regular-expression source string tested
+ * against the class name. `(string & {})` keeps preset autocomplete while accepting any pattern.
+ */
+type NameCase = "pascalCase" | "camelCase" | "lowercase" | (string & {});
+/** Which class names a `naming` convention enforces. Absent members aren't checked. */
+interface NamingRules {
+  /** The component base-class name (e.g. SUIT `Card` → `pascalCase`). */
+  component?: NameCase;
+  /** Sub-element part class names. */
+  part?: NameCase;
+}
+/** The built-in name-case patterns, tested against a class name without its leading dot. */
+declare const NAME_CASE_PRESETS: Record<string, RegExp>;
+/** A {@link NamingRules} compiled to regexes (custom patterns compiled from their source). */
+interface ResolvedNaming {
+  component?: RegExp;
+  part?: RegExp;
+}
+/** Compile {@link NamingRules} to regexes once, for the record/part name-case checks. */
+declare function resolveNaming(naming?: NamingRules): ResolvedNaming;
 //#endregion
 //#region src/syntax.d.ts
 /** The result of matching a value against a syntax. */
@@ -63,9 +105,31 @@ interface SyntaxMatch {
  */
 declare function matchesSyntax(syntax: string, value: string): SyntaxMatch;
 //#endregion
+//#region src/directives.d.ts
+type DirectiveKind = "disable" | "enable" | "disable-line" | "disable-next-line" | "expect-error";
+interface Directive {
+  kind: DirectiveKind;
+  /** Rule ids the directive scopes to, or `null` for every rule. */
+  rules: string[] | null;
+  /** 1-based line the comment starts / ends on. */
+  startLine: number;
+  endLine: number;
+}
+/** Parse every `cssdoc-*` directive comment out of a CSS source. */
+declare function parseDirectives(source: string): Directive[];
+/**
+ * Drop diagnostics suppressed by directive comments in `source`, and add a `cssdoc-directive`
+ * diagnostic for any `cssdoc-expect-error` that matched nothing.
+ *
+ * @param diagnostics - The diagnostics to filter (author-side, with CSS spans).
+ * @param source - The CSS the diagnostics came from (the same text passed to the linter).
+ * @returns The surviving diagnostics.
+ */
+declare function applyDirectives(diagnostics: Diagnostic[], source: string): Diagnostic[];
+//#endregion
 //#region src/aspects.d.ts
 declare const record: {
-  model(index: CssDocIndex): Diagnostic[];
+  model(index: CssDocIndex, naming?: ResolvedNaming, structureIgnore?: readonly string[]): Diagnostic[];
   completions(index: CssDocIndex): Completion[];
   hover(base: string, index: CssDocIndex): Hover | undefined;
   definition(base: string, index: CssDocIndex): Location$1 | undefined;
@@ -78,8 +142,15 @@ declare const modifier: {
   definition(base: string, token: string, index: CssDocIndex): Location$1 | undefined;
 };
 declare const part: {
+  model(index: CssDocIndex, naming?: ResolvedNaming): Diagnostic[];
+};
+declare const cssPart: {
   model(index: CssDocIndex): Diagnostic[];
 };
+/** A host-document class that looks like a state (via `statePrefixes`) but isn't a documented state. */
+declare function stateUsage(usage: ClassUsage, index: CssDocIndex): Diagnostic[];
+/** A host-document class that looks like a BEM element (`base<sep>…`) but isn't a documented part. */
+declare function partUsage(usage: ClassUsage, index: CssDocIndex): Diagnostic[];
 declare const customProperty: {
   /** Author-side: a registered property's default (`initial-value`/`@defaultValue`) must match its syntax. */model(index: CssDocIndex): Diagnostic[]; /** Consumer-side: an assignment `--name: value` must match the property's declared syntax. */
   assignment(a: PropertyAssignment, index: CssDocIndex): Diagnostic[];
@@ -96,15 +167,18 @@ declare const func: {
 //#endregion
 //#region src/index.d.ts
 /** The aspect names covered, in a stable order (the extension point for future aspects). */
-declare const ASPECTS: readonly ["record", "modifier", "part", "custom-property", "structure", "function", "state", "condition"];
+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): Diagnostic[];
+declare function lintModel(index: CssDocIndex, severities?: RuleSeverities, naming?: ResolvedNaming, structureIgnore?: readonly string[]): Diagnostic[];
 /** Consumer-side diagnostics for custom-property assignments (`--x: value` must match its `@property` syntax). */
-declare function checkPropertyAssignments(assignments: readonly PropertyAssignment[], index: CssDocIndex): Diagnostic[];
-/** Consumer-side diagnostics for class-attribute usage (unknown or deprecated modifiers). */
-declare function checkClassUsage(usages: readonly ClassUsage[], index: CssDocIndex): Diagnostic[];
+declare function checkPropertyAssignments(assignments: readonly PropertyAssignment[], index: CssDocIndex, severities?: RuleSeverities): Diagnostic[];
+/**
+ * Consumer-side diagnostics for class-attribute usage: unknown/deprecated modifiers, plus unknown
+ * state classes (`statePrefixes`) and unknown BEM element classes, routed by the token's kind.
+ */
+declare function checkClassUsage(usages: readonly ClassUsage[], index: CssDocIndex, severities?: RuleSeverities): Diagnostic[];
 /** Consumer-side diagnostics for `var(--…)` references (unknown custom properties; opt-in via prefix). */
-declare function checkPropertyUsage(usages: readonly PropertyUsage[], index: CssDocIndex, options?: UsageOptions): Diagnostic[];
+declare function checkPropertyUsage(usages: readonly PropertyUsage[], index: CssDocIndex, options?: UsageOptions, severities?: RuleSeverities): Diagnostic[];
 /** Completions for a class attribute: modifiers of `base` when given, else the component classes. */
 declare function completeClasses(base: string | undefined, index: CssDocIndex): Completion[];
 /** Completions for `var(--…)`: the declared custom properties. */
@@ -124,4 +198,4 @@ declare function definitionForCustomProperty(name: string, index: CssDocIndex):
 /** Definition of a custom function (its `@function` rule). */
 declare function definitionForFunction(name: string, index: CssDocIndex): Location$1 | undefined;
 //#endregion
-export { ASPECTS, Completion, CompletionKind, Diagnostic, Hover, type Location, Severity, type SourceSpan, SyntaxMatch, UsageOptions, checkClassUsage, checkPropertyAssignments, checkPropertyUsage, completeClasses, completeCustomProperties, completeFunctions, customProperty, definitionForClass, definitionForCustomProperty, definitionForFunction, func, hoverForClass, hoverForCustomProperty, hoverForFunction, lintModel, matchesSyntax, modifier, part, record };
+export { ASPECTS, Completion, CompletionKind, DEFAULT_RULE_SEVERITIES, Diagnostic, Hover, type Location, NAME_CASE_PRESETS, NameCase, NamingRules, ResolvedNaming, RuleId, RuleSeverities, RuleSeverity, Severity, type SourceSpan, SyntaxMatch, UsageOptions, applyDirectives, checkClassUsage, checkPropertyAssignments, checkPropertyUsage, completeClasses, completeCustomProperties, completeFunctions, cssPart, customProperty, definitionForClass, definitionForCustomProperty, definitionForFunction, func, hoverForClass, hoverForCustomProperty, hoverForFunction, lintModel, matchesSyntax, modifier, parseDirectives, part, partUsage, record, resolveNaming, resolveRuleSeverities, stateUsage };

package/dist/index.mjs

@@ -56,29 +56,69 @@ function matchesSyntax(syntax, value) {
 }
 //#endregion
 //#region src/aspects.ts
-/**
-* The aspect modules. Each documented aspect contributes some of: author-side model diagnostics,
-* consumer-side usage diagnostics, completions, hover, and definitions. All six aspects the model
-* carries are represented; the component hover folds in the structure, state, and condition facts, and
-* the generators (phase 3) surface them further. `index.ts` aggregates these into the public API.
-*
-* @module
-*/
 const stripDot = (name) => name.replace(/^\./u, "");
 const warn = (d) => ({
 	...d,
 	severity: "warning"
 });
+/**
+* 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.
+*/
+const globMatch = (pattern, value) => {
+	if (!pattern.includes("*")) return pattern === value;
+	return new RegExp(`^${pattern.replace(/[.+?^${}()|[\]\\]/gu, "\\$&").replace(/\*/gu, ".*")}$`, "u").test(value);
+};
 const record = {
-	model(index) {
+	model(index, naming, structureIgnore = []) {
 		const out = [];
-		for (const info of index.records) if (!info.entry.summary?.trim()) out.push(warn({
-			aspect: "record",
-			rule: "missing-summary",
-			message: `Record "${info.entry.name}" has no @summary.`,
-			record: info.entry.name,
-			span: info.span
-		}));
+		for (const info of index.records) {
+			if (!info.entry.summary?.trim()) out.push(warn({
+				aspect: "record",
+				rule: "missing-summary",
+				message: `Record "${info.entry.name}" has no @summary.`,
+				record: info.entry.name,
+				span: info.span
+			}));
+			if (naming?.component && info.entry.kind === "component" && info.entry.className) {
+				if (!naming.component.test(stripDot(info.entry.className))) out.push(warn({
+					aspect: "record",
+					rule: "component-name-case",
+					message: `Component class "${info.entry.className}" doesn't match the configured name case.`,
+					record: info.entry.name,
+					span: info.span
+				}));
+			}
+			if (info.entry.structure?.length) {
+				const known = /* @__PURE__ */ new Set([
+					stripDot(info.entry.className),
+					...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 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;
+							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
+							}));
+						}
+						walk(node.children);
+					}
+				};
+				walk(info.entry.structure);
+			}
+		}
 		return out;
 	},
 	completions(index) {
@@ -99,6 +139,7 @@ const record = {
 		const facets = [
 			entry.modifiers.length && `${entry.modifiers.length} modifiers`,
 			entry.parts.length && `${entry.parts.length} parts`,
+			entry.shadowParts.length && `${entry.shadowParts.length} shadow parts`,
 			entry.states.length && `${entry.states.length} states`,
 			entry.cssPropertiesDeclared.length && `${entry.cssPropertiesDeclared.length} custom properties`,
 			entry.functions.length && `${entry.functions.length} functions`,
@@ -119,26 +160,27 @@ const modifier = {
 		for (const info of index.records) {
 			const name = info.entry.name;
 			for (const m of info.entry.modifiers) {
+				const sel = index.matcher.selectorFor(m.name);
 				const span = info.memberSpans.get(memberKey("modifier", m.name)) ?? info.span;
 				if (!m.description?.trim() && !m.deprecated) out.push(warn({
 					aspect: "modifier",
 					rule: "undocumented-modifier",
-					message: `Modifier ".${m.name}" of "${name}" has no @modifier description.`,
+					message: `Modifier "${sel}" of "${name}" has no @modifier description.`,
 					record: name,
 					span
 				}));
 				if (m.deprecated && !m.deprecated.canonical && !m.deprecated.note?.trim()) out.push(warn({
 					aspect: "modifier",
 					rule: "deprecated-requires-canonical",
-					message: `Deprecated modifier ".${m.name}" of "${name}" needs a canonical replacement ({@link -x}) or a note.`,
+					message: `Deprecated modifier "${sel}" of "${name}" needs a canonical replacement ({@link}) or a note.`,
 					record: name,
 					span
 				}));
 			}
-			for (const authored of info.authoredModifiers) if (!info.selectorText.includes(`.${authored}`)) out.push(warn({
+			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 ".${authored}" of "${name}" is not defined by any selector.`,
+				message: `Documented modifier "${index.matcher.selectorFor(authored)}" of "${name}" is not defined by any selector.`,
 				record: name,
 				span: info.span
 			}));
@@ -146,23 +188,24 @@ const modifier = {
 		return out;
 	},
 	classUsage(usage, index) {
-		if (!usage.base || !usage.token.startsWith("-")) return [];
+		if (!usage.base || !index.matcher.looksLikeUsage(usage.token, usage.base)) return [];
 		const entry = index.componentForClass(usage.base);
 		if (!entry) return [];
+		const sel = index.matcher.selectorFor(index.matcher.normalizeMember(usage.token));
 		if (!index.isModifier(usage.base, usage.token)) return [warn({
 			aspect: "modifier",
 			rule: "unknown-modifier",
-			message: `".${usage.token}" is not a documented modifier of "${entry.name}".`,
+			message: `"${sel}" is not a documented modifier of "${entry.name}".`,
 			record: entry.name,
 			span: usage.loc
 		})];
 		const dep = index.deprecationOf(usage.base, usage.token);
 		if (dep) {
-			const advice = dep.canonical ? `use ".${dep.canonical}"` : dep.note ?? "no replacement given";
+			const advice = dep.canonical ? `use "${index.matcher.selectorFor(dep.canonical)}"` : dep.note ?? "no replacement given";
 			return [warn({
 				aspect: "modifier",
 				rule: "deprecated-modifier",
-				message: `Modifier ".${usage.token}" of "${entry.name}" is deprecated — ${advice}.`,
+				message: `Modifier "${sel}" of "${entry.name}" is deprecated — ${advice}.`,
 				record: entry.name,
 				span: usage.loc
 			})];
@@ -173,7 +216,7 @@ const modifier = {
 		const entry = index.componentForClass(base);
 		if (!entry) return [];
 		return entry.modifiers.map((m) => ({
-			label: `-${m.name.replace(/^-/u, "")}`,
+			label: m.name,
 			kind: "modifier",
 			detail: m.prop,
 			documentation: m.description,
@@ -182,32 +225,41 @@ const modifier = {
 	},
 	hover(base, token, index) {
 		const entry = index.componentForClass(base);
-		const m = entry?.modifiers.find((x) => x.name === stripDot(token));
+		const m = entry?.modifiers.find((x) => x.name === index.matcher.normalizeMember(token));
 		if (!m) return void 0;
-		const lines = [`\`.${m.name}\` — modifier of \`${entry.className}\``];
+		const lines = [`\`${index.matcher.selectorFor(m.name)}\` — modifier of \`${entry.className}\``];
 		if (m.description) lines.push("", m.description);
 		if (m.deprecated) {
-			const advice = m.deprecated.canonical ? `use \`.${m.deprecated.canonical}\`` : m.deprecated.note ?? "";
+			const advice = m.deprecated.canonical ? `use \`${index.matcher.selectorFor(m.deprecated.canonical)}\`` : m.deprecated.note ?? "";
 			lines.push("", `**Deprecated** — ${advice}`);
 		}
 		return { contents: lines.join("\n") };
 	},
 	definition(base, token, index) {
 		const entry = index.componentForClass(base);
-		return entry ? index.location(entry.name, memberKey("modifier", stripDot(token))) : void 0;
+		return entry ? index.location(entry.name, memberKey("modifier", index.matcher.normalizeMember(token))) : void 0;
 	}
 };
-const part = { model(index) {
+const part = { model(index, naming) {
 	const out = [];
 	for (const info of index.records) {
 		const name = info.entry.name;
-		for (const p of info.entry.parts) if (!p.description?.trim()) out.push(warn({
-			aspect: "part",
-			rule: "undocumented-part",
-			message: `Part ".${p.name}" of "${name}" has no @part description.`,
-			record: name,
-			span: info.memberSpans.get(memberKey("part", p.name)) ?? info.span
-		}));
+		for (const p of info.entry.parts) {
+			if (!p.description?.trim()) out.push(warn({
+				aspect: "part",
+				rule: "undocumented-part",
+				message: `Part ".${p.name}" of "${name}" has no @part description.`,
+				record: name,
+				span: info.memberSpans.get(memberKey("part", p.name)) ?? info.span
+			}));
+			if (naming?.part && !naming.part.test(p.name)) out.push(warn({
+				aspect: "part",
+				rule: "part-name-case",
+				message: `Part ".${p.name}" of "${name}" doesn't match the configured name case.`,
+				record: name,
+				span: info.memberSpans.get(memberKey("part", p.name)) ?? info.span
+			}));
+		}
 		for (const authored of info.authoredParts) if (!info.selectorText.includes(`.${authored}`)) out.push(warn({
 			aspect: "part",
 			rule: "name-not-in-css",
@@ -218,6 +270,50 @@ const part = { model(index) {
 	}
 	return out;
 } };
+const cssPart = { model(index) {
+	const out = [];
+	for (const info of index.records) {
+		const name = info.entry.name;
+		for (const p of info.entry.shadowParts) if (!p.description?.trim()) out.push(warn({
+			aspect: "css-part",
+			rule: "undocumented-css-part",
+			message: `Shadow part "::part(${p.name})" of "${name}" has no @csspart description.`,
+			record: name,
+			span: info.memberSpans.get(memberKey("shadow-part", p.name)) ?? info.span
+		}));
+	}
+	return out;
+} };
+/** A host-document class that looks like a state (via `statePrefixes`) but isn't a documented state. */
+function stateUsage(usage, index) {
+	if (!usage.base) return [];
+	const entry = index.componentForClass(usage.base);
+	if (!entry) return [];
+	const name = usage.token.replace(/^\./u, "");
+	if (entry.states.some((s) => s.name === name)) return [];
+	return [warn({
+		aspect: "state",
+		rule: "unknown-state",
+		message: `".${name}" is not a documented state of "${entry.name}".`,
+		record: entry.name,
+		span: usage.loc
+	})];
+}
+/** A host-document class that looks like a BEM element (`base<sep>…`) but isn't a documented part. */
+function partUsage(usage, index) {
+	if (!usage.base) return [];
+	const entry = index.componentForClass(usage.base);
+	if (!entry) return [];
+	const name = usage.token.replace(/^\./u, "");
+	if (entry.parts.some((p) => p.name === name || p.modifiers?.some((m) => m.name === name))) return [];
+	return [warn({
+		aspect: "part",
+		rule: "unknown-part",
+		message: `".${name}" is not a documented part of "${entry.name}".`,
+		record: entry.name,
+		span: usage.loc
+	})];
+}
 function findProperty(index, name) {
 	for (const rec of index.records) {
 		const i = rec.entry.cssPropertiesDeclared.findIndex((p) => p.name === name);
@@ -328,12 +424,185 @@ const func = {
 	}
 };
 //#endregion
+//#region src/types.ts
+/**
+* The default rule severities. `unknown-modifier` defaults to `warn` — safe under the BEM default's
+* strong `--` signal; lower it to `off` for weak-signal conventions (bare/OOCSS) where every chained
+* class is a candidate. `unknown-custom-property` stays `off` (it needs an opt-in `propertyPrefix`).
+*/
+const DEFAULT_RULE_SEVERITIES = {
+	"missing-summary": "warn",
+	"undocumented-modifier": "warn",
+	"deprecated-requires-canonical": "warn",
+	"name-not-in-css": "warn",
+	"unknown-modifier": "warn",
+	"deprecated-modifier": "warn",
+	"unknown-state": "warn",
+	"unknown-part": "warn",
+	"undocumented-part": "warn",
+	"undocumented-css-part": "warn",
+	"component-name-case": "warn",
+	"part-name-case": "warn",
+	"structure-unknown-selector": "warn",
+	"invalid-default-value": "warn",
+	"invalid-property-value": "warn",
+	"invalid-fallback-value": "warn",
+	"unknown-custom-property": "off",
+	"cssdoc-directive": "warn"
+};
+/**
+* Merge per-rule overrides over {@link DEFAULT_RULE_SEVERITIES}. A `boolean` override is accepted for
+* back-compat: `false` → `off`, `true` → the rule's default.
+*/
+function resolveRuleSeverities(overrides) {
+	const resolved = { ...DEFAULT_RULE_SEVERITIES };
+	if (!overrides) return resolved;
+	for (const [rule, value] of Object.entries(overrides)) {
+		if (value === void 0) continue;
+		if (typeof value === "boolean") resolved[rule] = value ? DEFAULT_RULE_SEVERITIES[rule] : "off";
+		else resolved[rule] = value;
+	}
+	return resolved;
+}
+/** The built-in name-case patterns, tested against a class name without its leading dot. */
+const NAME_CASE_PRESETS = {
+	pascalCase: /^[A-Z][A-Za-z0-9]*$/u,
+	camelCase: /^[a-z][A-Za-z0-9]*$/u,
+	lowercase: /^[a-z][a-z0-9-]*$/u
+};
+/** Compile one {@link NameCase} to a regex: a preset, else the string as a custom pattern. */
+function compileNameCase(spec) {
+	if (!spec) return void 0;
+	if (spec in NAME_CASE_PRESETS) return NAME_CASE_PRESETS[spec];
+	try {
+		return new RegExp(spec, "u");
+	} catch {
+		return;
+	}
+}
+/** Compile {@link NamingRules} to regexes once, for the record/part name-case checks. */
+function resolveNaming(naming) {
+	return {
+		component: compileNameCase(naming?.component),
+		part: compileNameCase(naming?.part)
+	};
+}
+//#endregion
+//#region src/directives.ts
+const DIRECTIVE_RE = /\/\*\s*cssdoc-(disable-next-line|disable-line|disable|enable|expect-error)\b([^*]*?)\*\//gu;
+const lineAt = (source, index) => {
+	let line = 1;
+	for (let i = 0; i < index && i < source.length; i++) if (source[i] === "\n") line += 1;
+	return line;
+};
+/** Parse every `cssdoc-*` directive comment out of a CSS source. */
+function parseDirectives(source) {
+	const out = [];
+	for (const m of source.matchAll(DIRECTIVE_RE)) {
+		const at = m.index ?? 0;
+		const rest = m[2].trim();
+		out.push({
+			kind: m[1],
+			rules: rest ? rest.split(/[\s,]+/u).filter(Boolean) : null,
+			startLine: lineAt(source, at),
+			endLine: lineAt(source, at + m[0].length - 1)
+		});
+	}
+	return out;
+}
+const scopesRule = (d, rule) => d.rules === null || d.rules.includes(rule);
+/**
+* Drop diagnostics suppressed by directive comments in `source`, and add a `cssdoc-directive`
+* diagnostic for any `cssdoc-expect-error` that matched nothing.
+*
+* @param diagnostics - The diagnostics to filter (author-side, with CSS spans).
+* @param source - The CSS the diagnostics came from (the same text passed to the linter).
+* @returns The surviving diagnostics.
+*/
+function applyDirectives(diagnostics, source) {
+	const directives = parseDirectives(source);
+	if (directives.length === 0) return diagnostics;
+	const block = directives.filter((d) => d.kind === "disable" || d.kind === "enable").sort((a, b) => a.startLine - b.startLine);
+	const perLine = directives.filter((d) => d.kind !== "disable" && d.kind !== "enable");
+	const blockDisabled = (line, rule) => {
+		let all = false;
+		const disabled = /* @__PURE__ */ new Set();
+		const exceptions = /* @__PURE__ */ new Set();
+		for (const d of block) {
+			if (d.startLine > line) break;
+			if (d.kind === "disable" && d.rules === null) {
+				all = true;
+				exceptions.clear();
+			} else if (d.kind === "disable") for (const r of d.rules ?? []) if (all) exceptions.delete(r);
+			else disabled.add(r);
+			else if (d.rules === null) {
+				all = false;
+				disabled.clear();
+				exceptions.clear();
+			} else for (const r of d.rules) if (all) exceptions.add(r);
+			else disabled.delete(r);
+		}
+		return all ? !exceptions.has(rule) : disabled.has(rule);
+	};
+	const lineDirectiveFor = (line, rule) => perLine.find((d) => scopesRule(d, rule) && (d.kind === "disable-line" ? line >= d.startLine && line <= d.endLine : line === d.endLine + 1));
+	const satisfied = /* @__PURE__ */ new Set();
+	const kept = [];
+	for (const diag of diagnostics) {
+		const line = diag.span?.start.line;
+		if (line === void 0) {
+			kept.push(diag);
+			continue;
+		}
+		const hit = lineDirectiveFor(line, diag.rule);
+		if (hit) {
+			satisfied.add(hit);
+			continue;
+		}
+		if (!blockDisabled(line, diag.rule)) kept.push(diag);
+	}
+	for (const d of perLine) if (d.kind === "expect-error" && !satisfied.has(d)) kept.push({
+		aspect: "directive",
+		rule: "cssdoc-directive",
+		message: "Unused cssdoc-expect-error: no cssdoc problem was reported on the following line.",
+		span: {
+			start: {
+				line: d.startLine,
+				column: 1
+			},
+			end: {
+				line: d.endLine,
+				column: 2
+			}
+		},
+		severity: "warning"
+	});
+	return kept;
+}
+//#endregion
 //#region src/index.ts
+/**
+* Apply resolved rule severities to a batch of diagnostics: drop `off` rules, and stamp the configured
+* severity onto the rest. This is the single place severity/enablement is decided — every host inherits
+* it. Aspects emit a placeholder `warning`; this overrides it.
+*/
+function applySeverities(diagnostics, severities) {
+	const out = [];
+	for (const d of diagnostics) {
+		const severity = severities[d.rule] ?? "warn";
+		if (severity === "off") continue;
+		out.push({
+			...d,
+			severity: severity === "error" ? "error" : "warning"
+		});
+	}
+	return out;
+}
 /** The aspect names covered, in a stable order (the extension point for future aspects). */
 const ASPECTS = [
 	"record",
 	"modifier",
 	"part",
+	"css-part",
 	"custom-property",
 	"structure",
 	"function",
@@ -341,25 +610,34 @@ const ASPECTS = [
 	"condition"
 ];
 /** Author-side hygiene diagnostics over the whole model (missing summaries, undocumented members, drift, invalid defaults). */
-function lintModel(index) {
-	return [
-		...record.model(index),
+function lintModel(index, severities = DEFAULT_RULE_SEVERITIES, naming, structureIgnore) {
+	return applySeverities([
+		...record.model(index, naming, structureIgnore),
 		...modifier.model(index),
-		...part.model(index),
+		...part.model(index, naming),
+		...cssPart.model(index),
 		...customProperty.model(index)
-	];
+	], severities);
 }
 /** Consumer-side diagnostics for custom-property assignments (`--x: value` must match its `@property` syntax). */
-function checkPropertyAssignments(assignments, index) {
-	return assignments.flatMap((a) => customProperty.assignment(a, index));
+function checkPropertyAssignments(assignments, index, severities = DEFAULT_RULE_SEVERITIES) {
+	return applySeverities(assignments.flatMap((a) => customProperty.assignment(a, index)), severities);
 }
-/** Consumer-side diagnostics for class-attribute usage (unknown or deprecated modifiers). */
-function checkClassUsage(usages, index) {
-	return usages.flatMap((usage) => modifier.classUsage(usage, index));
+/**
+* Consumer-side diagnostics for class-attribute usage: unknown/deprecated modifiers, plus unknown
+* state classes (`statePrefixes`) and unknown BEM element classes, routed by the token's kind.
+*/
+function checkClassUsage(usages, index, severities = DEFAULT_RULE_SEVERITIES) {
+	return applySeverities(usages.flatMap((usage) => {
+		const kind = usage.base ? index.matcher.usageKind(usage.token, usage.base) : void 0;
+		if (kind === "state") return stateUsage(usage, index);
+		if (kind === "element") return partUsage(usage, index);
+		return modifier.classUsage(usage, index);
+	}), severities);
 }
 /** Consumer-side diagnostics for `var(--…)` references (unknown custom properties; opt-in via prefix). */
-function checkPropertyUsage(usages, index, options = {}) {
-	return usages.flatMap((usage) => customProperty.propertyUsage(usage, index, options));
+function checkPropertyUsage(usages, index, options = {}, severities = DEFAULT_RULE_SEVERITIES) {
+	return applySeverities(usages.flatMap((usage) => customProperty.propertyUsage(usage, index, options)), severities);
 }
 /** Completions for a class attribute: modifiers of `base` when given, else the component classes. */
 function completeClasses(base, index) {
@@ -398,4 +676,4 @@ function definitionForFunction(name, index) {
 	return func.definition(name, index);
 }
 //#endregion
-export { ASPECTS, checkClassUsage, checkPropertyAssignments, checkPropertyUsage, completeClasses, completeCustomProperties, completeFunctions, customProperty, definitionForClass, definitionForCustomProperty, definitionForFunction, func, hoverForClass, hoverForCustomProperty, hoverForFunction, lintModel, matchesSyntax, modifier, part, record };
+export { ASPECTS, DEFAULT_RULE_SEVERITIES, NAME_CASE_PRESETS, applyDirectives, checkClassUsage, checkPropertyAssignments, checkPropertyUsage, completeClasses, completeCustomProperties, completeFunctions, cssPart, customProperty, definitionForClass, definitionForCustomProperty, definitionForFunction, func, hoverForClass, hoverForCustomProperty, hoverForFunction, lintModel, matchesSyntax, modifier, parseDirectives, part, partUsage, record, resolveNaming, resolveRuleSeverities, stateUsage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cssdoc/providers",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "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.1.0",
-    "@cssdoc/index": "0.1.0"
+    "@cssdoc/core": "0.3.0",
+    "@cssdoc/index": "0.3.0"
   },
   "devDependencies": {
     "@types/css-tree": "^2.3.11",