@cssdoc/index 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danny Wahl
+
+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,28 @@
+# @cssdoc/index
+
+A queryable semantic index over the [`@cssdoc/core`](../core) model — the shared data layer every
+cssdoc linter and the language server query. It adds the two cross-cutting concerns those tools need:
+
+- a host-agnostic **`Usage`** abstraction (`ClassUsage`, `PropertyUsage`) so HTML, JSX, template
+  literals, and CSS selectors all feed the same providers; and
+- optional **source spans**, built in a dedicated PostCSS pass (so `@cssdoc/core` stays position-free),
+  powering diagnostics locations, hover ranges, and go-to-definition.
+
+## Usage
+
+```ts
+import { createIndex } from "@cssdoc/index";
+
+const index = createIndex(css, { file: "components.css" });
+index.componentForClass(".button"); // → the button record
+index.isModifier(".button", "-color-x"); // → boolean
+index.deprecationOf(".button", "-old"); // → { canonical } | undefined
+index.location("button", "modifier:-color-secondary"); // → { file, span } | undefined
+```
+
+`createIndex(css)` includes spans; `indexFromEntries(entries)` builds a lookup-only index from a model
+snapshot (`index.toManifest()`), without spans.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,143 @@
+import { CssAnimation, CssCondition, CssDocConfiguration, CssDocEntry, CssFunction, CssModifier, CssPart, CssPropertyDeclared, CssState, StructureNode } from "@cssdoc/core";
+
+//#region src/index.d.ts
+/** A 1-based line/column position (matching PostCSS). */
+interface Position {
+  line: number;
+  column: number;
+}
+/** A source range. */
+interface SourceSpan {
+  start: Position;
+  end: Position;
+}
+/** A location: a source range, optionally in a named file. */
+interface Location {
+  file?: string;
+  span: SourceSpan;
+}
+/**
+ * A class-attribute usage: the classes on one element, the specific `token` under inspection, and the
+ * resolved `base` component class (when one of the tokens names a documented component). Producers for
+ * HTML, JSX, and CSS selectors all emit this shape.
+ */
+interface ClassUsage {
+  /** The base component class among the tokens, if any (e.g. `.button` → `button`). */
+  base?: string;
+  /** Every class token on the element. */
+  tokens: string[];
+  /** The specific token this usage is about (e.g. a `-modifier`). */
+  token: string;
+  /** Where the token sits in the host document. */
+  loc?: SourceSpan;
+}
+/** A `var(--name)` custom-property reference. */
+interface PropertyUsage {
+  name: string;
+  /** The fallback in `var(--name, fallback)`, when present. */
+  fallback?: string;
+  loc?: SourceSpan;
+}
+/** A custom-property assignment: `--name: value`. */
+interface PropertyAssignment {
+  name: string;
+  value: string;
+  loc?: SourceSpan;
+}
+/** The value sites a stylesheet contains: custom-property assignments and `var(--…)` references. */
+interface CssValueSites {
+  assignments: PropertyAssignment[];
+  usages: PropertyUsage[];
+}
+/** The kinds of record member a span can be keyed to. */
+type MemberKind = "record" | "modifier" | "part" | "property" | "function" | "animation" | "layer" | "state" | "condition";
+/** Build a stable span key for a member. */
+declare function memberKey(kind: MemberKind, id?: string): string;
+/** One record in the index: its model entry plus source spans and the facts drift checks need. */
+interface RecordInfo {
+  entry: CssDocEntry;
+  /** The record's definition span (its base-class rule, else its doc comment). */
+  span?: SourceSpan;
+  /** Spans keyed by {@link memberKey}, e.g. `modifier:-color-secondary`, `property:--value`. */
+  memberSpans: Map<string, SourceSpan>;
+  /** Modifier names authored via `@modifier` (used for drift detection). */
+  authoredModifiers: Set<string>;
+  /** Part names authored via `@part`/`@csspart` (used for drift detection). */
+  authoredParts: Set<string>;
+  /** The concatenated selector text of the record's rules (used for drift detection). */
+  selectorText: string;
+}
+/** A serializable snapshot of the index (the model plus its file), for tools that consume JSON. */
+interface CssDocManifest {
+  version: 1;
+  file?: string;
+  entries: CssDocEntry[];
+}
+/** A queryable view over the parsed records. */
+declare class CssDocIndex {
+  readonly file?: string;
+  readonly records: readonly RecordInfo[];
+  private readonly byName;
+  private readonly byClass;
+  constructor(records: RecordInfo[], file?: string);
+  /** Every documented record's model entry. */
+  get entries(): CssDocEntry[];
+  /** The record whose base class matches `className` (with or without a leading dot). */
+  componentForClass(className: string): CssDocEntry | undefined;
+  /** The full {@link RecordInfo} for a record name. */
+  recordInfo(name: string): RecordInfo | undefined;
+  modifiersFor(name: string): CssModifier[];
+  partsFor(name: string): CssPart[];
+  customPropertiesFor(name: string): CssPropertyDeclared[];
+  functionsFor(name: string): CssFunction[];
+  statesFor(name: string): CssState[];
+  conditionsFor(name: string): CssCondition[];
+  animationsFor(name: string): CssAnimation[];
+  structureFor(name: string): StructureNode[] | undefined;
+  /** Whether `modifier` (with or without a leading dot) is a documented modifier of `base`. */
+  isModifier(base: string, modifier: string): boolean;
+  /** The deprecation of a modifier on `base`, if it is deprecated. */
+  deprecationOf(base: string, modifier: string): {
+    canonical?: string;
+    note?: string;
+  } | undefined;
+  /** Every declared custom property, paired with the record that declares it (for `var(...)` completion). */
+  allCustomProperties(): {
+    property: CssPropertyDeclared;
+    record: string;
+  }[];
+  /** Every custom function, paired with its record. */
+  allFunctions(): {
+    fn: CssFunction;
+    record: string;
+  }[];
+  /** The definition location of a record member (or the record itself), if a span is known. */
+  location(name: string, key?: string): Location | undefined;
+  /** A stable, serializable snapshot. */
+  toManifest(): CssDocManifest;
+}
+/** Build an index from a model snapshot (no source spans). */
+declare function indexFromEntries(entries: CssDocEntry[], file?: string): CssDocIndex;
+/**
+ * Build an index from CSS, with source spans. Parses the model via `@cssdoc/core`, then makes a second
+ * PostCSS pass to locate each record and member.
+ *
+ * @param css - The CSS source.
+ * @param options - `file` (attached to locations) and `configuration` (custom tags).
+ * @returns The index.
+ */
+declare function createIndex(css: string, options?: {
+  file?: string;
+  configuration?: CssDocConfiguration;
+}): CssDocIndex;
+/**
+ * Extract custom-property assignments (`--name: value`) and `var(--name, fallback)` references from
+ * CSS. Parsing lives here — the CSS-parsing package — so the linters and the language server share one
+ * extractor for the value-validation rules.
+ *
+ * @param css - The CSS source.
+ * @returns The assignments and `var(…)` usages found.
+ */
+declare function cssValueSites(css: string): CssValueSites;
+//#endregion
+export { ClassUsage, CssDocIndex, CssDocManifest, CssValueSites, Location, MemberKind, Position, PropertyAssignment, PropertyUsage, RecordInfo, SourceSpan, createIndex, cssValueSites, indexFromEntries, memberKey };

package/dist/index.mjs

@@ -0,0 +1,250 @@
+import { parseCssDocs, parseDocComment, recordNameOf } from "@cssdoc/core";
+import postcss from "postcss";
+import valueParser from "postcss-value-parser";
+//#region src/index.ts
+/**
+* `@cssdoc/index` — a queryable semantic index over the `@cssdoc/core` model, plus the two
+* cross-cutting concerns every downstream tool shares: a host-agnostic usage abstraction (so
+* HTML, JSX, template literals, and CSS selectors all feed the same providers) and optional source
+* spans (so diagnostics, hover ranges, and go-to-definition can point back into the CSS).
+*
+* `@cssdoc/core` stays position-free; the spans are built here, in a dedicated PostCSS pass, and
+* carried alongside the model. Build with {@link createIndex} (from CSS, with spans) or
+* {@link indexFromEntries} (from a model snapshot, without spans).
+*
+* @module @cssdoc/index
+*/
+/** Build a stable span key for a member. */
+function memberKey(kind, id = "") {
+	return id ? `${kind}:${id}` : kind;
+}
+const escapeRe = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+const stripDot = (name) => name.replace(/^\./u, "");
+const spanOf = (node) => {
+	const { source } = node;
+	if (!source?.start) return void 0;
+	const end = source.end ?? source.start;
+	return {
+		start: {
+			line: source.start.line,
+			column: source.start.column
+		},
+		end: {
+			line: end.line,
+			column: end.column
+		}
+	};
+};
+/** A queryable view over the parsed records. */
+var CssDocIndex = class {
+	file;
+	records;
+	byName = /* @__PURE__ */ new Map();
+	byClass = /* @__PURE__ */ new Map();
+	constructor(records, file) {
+		this.records = records;
+		this.file = file;
+		for (const record of records) {
+			this.byName.set(record.entry.name, record);
+			this.byClass.set(stripDot(record.entry.className), record);
+		}
+	}
+	/** Every documented record's model entry. */
+	get entries() {
+		return this.records.map((r) => r.entry);
+	}
+	/** The record whose base class matches `className` (with or without a leading dot). */
+	componentForClass(className) {
+		return this.byClass.get(stripDot(className))?.entry;
+	}
+	/** The full {@link RecordInfo} for a record name. */
+	recordInfo(name) {
+		return this.byName.get(name);
+	}
+	modifiersFor(name) {
+		return this.byName.get(name)?.entry.modifiers ?? [];
+	}
+	partsFor(name) {
+		return this.byName.get(name)?.entry.parts ?? [];
+	}
+	customPropertiesFor(name) {
+		return this.byName.get(name)?.entry.cssPropertiesDeclared ?? [];
+	}
+	functionsFor(name) {
+		return this.byName.get(name)?.entry.functions ?? [];
+	}
+	statesFor(name) {
+		return this.byName.get(name)?.entry.states ?? [];
+	}
+	conditionsFor(name) {
+		return this.byName.get(name)?.entry.conditions ?? [];
+	}
+	animationsFor(name) {
+		return this.byName.get(name)?.entry.animations ?? [];
+	}
+	structureFor(name) {
+		return this.byName.get(name)?.entry.structure;
+	}
+	/** Whether `modifier` (with or without a leading dot) is a documented modifier of `base`. */
+	isModifier(base, modifier) {
+		const wanted = stripDot(modifier);
+		return this.byClass.get(stripDot(base))?.entry.modifiers.some((m) => m.name === wanted) ?? false;
+	}
+	/** The deprecation of a modifier on `base`, if it is deprecated. */
+	deprecationOf(base, modifier) {
+		const wanted = stripDot(modifier);
+		return this.byClass.get(stripDot(base))?.entry.modifiers.find((m) => m.name === wanted)?.deprecated;
+	}
+	/** Every declared custom property, paired with the record that declares it (for `var(...)` completion). */
+	allCustomProperties() {
+		return this.records.flatMap((r) => r.entry.cssPropertiesDeclared.map((property) => ({
+			property,
+			record: r.entry.name
+		})));
+	}
+	/** Every custom function, paired with its record. */
+	allFunctions() {
+		return this.records.flatMap((r) => r.entry.functions.map((fn) => ({
+			fn,
+			record: r.entry.name
+		})));
+	}
+	/** The definition location of a record member (or the record itself), if a span is known. */
+	location(name, key = "record") {
+		const record = this.byName.get(name);
+		if (!record) return void 0;
+		const span = key === "record" ? record.span : record.memberSpans.get(key);
+		return span ? {
+			file: this.file,
+			span
+		} : void 0;
+	}
+	/** A stable, serializable snapshot. */
+	toManifest() {
+		return {
+			version: 1,
+			file: this.file,
+			entries: this.entries
+		};
+	}
+};
+/** Build an index from a model snapshot (no source spans). */
+function indexFromEntries(entries, file) {
+	return new CssDocIndex(entries.map((entry) => ({
+		entry,
+		memberSpans: /* @__PURE__ */ new Map(),
+		authoredModifiers: /* @__PURE__ */ new Set(),
+		authoredParts: /* @__PURE__ */ new Set(),
+		selectorText: ""
+	})), file);
+}
+/** Scan a record's nodes for member spans, recording each member's first occurrence. */
+function scanNodes(nodes, build, base) {
+	const modRe = new RegExp(`(?:${escapeRe(base)}|:scope)((?:\\.-[\\w-]+)+)`, "gu");
+	const set = (key, node) => {
+		const span = spanOf(node);
+		if (span && !build.memberSpans.has(key)) build.memberSpans.set(key, span);
+	};
+	for (const node of nodes) if (node.type === "rule") {
+		build.selectorText += ` ${node.selector}`;
+		if (`.${stripDot(node.selector.trim())}` === base && !build.span) build.span = spanOf(node);
+		for (const selector of node.selector.split(",")) {
+			for (const m of selector.matchAll(modRe)) for (const mod of m[1].matchAll(/\.(-[\w-]+)/gu)) set(memberKey("modifier", mod[1]), node);
+			for (const s of selector.matchAll(/:state\(\s*([\w-]+)\s*\)/gu)) set(memberKey("state", s[1]), node);
+			const bare = selector.replace(/::?[\w-]+(\([^)]*\))?/gu, "");
+			for (const p of bare.matchAll(/\.([a-z][\w-]*)/gu)) set(memberKey("part", p[1]), node);
+		}
+	} else if (node.type === "atrule") {
+		if (node.name === "property") set(memberKey("property", node.params.trim()), node);
+		else if (node.name === "function") {
+			const fn = node.params.trim().match(/^(--[\w-]+)/u);
+			if (fn) set(memberKey("function", fn[1]), node);
+		} else if (node.name === "keyframes") set(memberKey("animation", node.params.trim()), node);
+		else if (node.name === "layer") for (const raw of node.params.split(",")) {
+			const layer = raw.trim();
+			if (layer) set(memberKey("layer", layer), node);
+		}
+		else if (node.name === "container" || node.name === "supports" || node.name === "media") set(memberKey("condition", `${node.name}:${node.params.trim()}`), node);
+		if (node.nodes) scanNodes(node.nodes, build, base);
+	}
+}
+/**
+* Build an index from CSS, with source spans. Parses the model via `@cssdoc/core`, then makes a second
+* PostCSS pass to locate each record and member.
+*
+* @param css - The CSS source.
+* @param options - `file` (attached to locations) and `configuration` (custom tags).
+* @returns The index.
+*/
+function createIndex(css, options = {}) {
+	const entries = parseCssDocs(css, { configuration: options.configuration });
+	const byName = new Map(entries.map((e) => [e.name, e]));
+	const builds = /* @__PURE__ */ new Map();
+	const root = postcss.parse(css);
+	let current;
+	for (const node of root.nodes) {
+		if (node.type === "comment") {
+			const name = recordNameOf(node.text, options.configuration);
+			const entry = name ? byName.get(name) : void 0;
+			if (name && entry) {
+				const doc = parseDocComment(node.text, options.configuration);
+				current = {
+					entry,
+					span: spanOf(node),
+					memberSpans: /* @__PURE__ */ new Map(),
+					authoredModifiers: new Set(doc.modifiers.keys()),
+					authoredParts: new Set(doc.parts.keys()),
+					selectorText: ""
+				};
+				builds.set(name, current);
+				continue;
+			}
+		}
+		if (current) scanNodes([node], current, current.entry.className);
+	}
+	return new CssDocIndex(entries.map((entry) => builds.get(entry.name) ?? {
+		entry,
+		memberSpans: /* @__PURE__ */ new Map(),
+		authoredModifiers: /* @__PURE__ */ new Set(),
+		authoredParts: /* @__PURE__ */ new Set(),
+		selectorText: ""
+	}), options.file);
+}
+/**
+* Extract custom-property assignments (`--name: value`) and `var(--name, fallback)` references from
+* CSS. Parsing lives here — the CSS-parsing package — so the linters and the language server share one
+* extractor for the value-validation rules.
+*
+* @param css - The CSS source.
+* @returns The assignments and `var(…)` usages found.
+*/
+function cssValueSites(css) {
+	const assignments = [];
+	const usages = [];
+	postcss.parse(css).walkDecls((decl) => {
+		const loc = spanOf(decl);
+		if (decl.prop.startsWith("--")) assignments.push({
+			name: decl.prop,
+			value: decl.value,
+			loc
+		});
+		if (decl.value.includes("var(")) valueParser(decl.value).walk((node) => {
+			if (node.type !== "function" || node.value !== "var") return;
+			const name = node.nodes.find((n) => n.type === "word")?.value;
+			if (!name?.startsWith("--")) return;
+			const comma = node.nodes.findIndex((n) => n.type === "div" && n.value === ",");
+			const fallback = comma >= 0 ? valueParser.stringify(node.nodes.slice(comma + 1)).trim() : void 0;
+			usages.push({
+				name,
+				fallback: fallback || void 0,
+				loc
+			});
+		});
+	});
+	return {
+		assignments,
+		usages
+	};
+}
+//#endregion
+export { CssDocIndex, createIndex, cssValueSites, indexFromEntries, memberKey };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@cssdoc/index",
+  "version": "0.1.0",
+  "description": "A queryable semantic index over the @cssdoc/core model, plus a host-agnostic Usage abstraction and source spans — the shared data layer for cssdoc's linters and language server.",
+  "keywords": [
+    "css",
+    "cssdoc",
+    "documentation",
+    "index"
+  ],
+  "homepage": "https://cssdoc.dev",
+  "bugs": "https://github.com/thedannywahl/cssdoc/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thedannywahl/cssdoc.git",
+    "directory": "packages/index"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "postcss": "^8.5.16",
+    "postcss-value-parser": "^4.2.0",
+    "@cssdoc/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "publint": "^0.3.21",
+    "typescript": "^6.0.3",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.4",
+    "vite-plus": "0.2.4"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "publint": "publint"
+  }
+}