vite-plugin-css-module-types 1.0.0

package/src/lib/class-index.ts

@@ -0,0 +1,169 @@
+import { toCamelCase } from "./camel-case.ts";
+import type { LineMapping } from "./sourcemap.ts";
+import type { ClassEntry, CssCommentInfo } from "./types.ts";
+
+/**
+ * Builds an O(1) lookup from hashed class names to their source line mappings
+ * by scanning generated CSS lines for `.className` selectors.
+ */
+export function buildClassNameIndex(lineMappings: LineMapping[]): Map<string, LineMapping> {
+  const index = new Map<string, LineMapping>();
+  const classRegex = /\.([a-zA-Z_][\w-]*)/g;
+
+  for (const mapping of lineMappings) {
+    if (!mapping.originalLine) continue;
+
+    for (const match of mapping.generatedContent.matchAll(classRegex)) {
+      const className = match[1];
+      if (className && !index.has(className)) {
+        index.set(className, mapping);
+      }
+    }
+  }
+
+  return index;
+}
+
+/**
+ * Scans original CSS source for class selectors and returns a name→line map.
+ * Also registers camelCase variants for `localsConvention: 'camelCase'`.
+ */
+export function buildOriginalClassLineMap(cssSource: string): Map<string, number> {
+  const map = new Map<string, number>();
+  const lines = cssSource.split("\n");
+  const classRegex = /\.([a-zA-Z_][\w-]*)/g;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line) continue;
+
+    for (const match of line.matchAll(classRegex)) {
+      const name = match[1];
+      if (name && !map.has(name)) {
+        const lineNum = i + 1;
+        map.set(name, lineNum);
+
+        const camelName = toCamelCase(name);
+        if (camelName !== name && !map.has(camelName)) {
+          map.set(camelName, lineNum);
+        }
+      }
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Extracts CSS rule blocks (selector + brace-delimited body) for each class.
+ * Handles nesting for `@media`/`@layer`. Registers camelCase variants.
+ */
+export function extractCssRuleBodies(cssSource: string): Map<string, string> {
+  const map = new Map<string, string>();
+  const lines = cssSource.split("\n");
+  const classRegex = /\.([a-zA-Z_][\w-]*)/g;
+
+  const lineOffsets: number[] = [0];
+  for (let i = 0; i < lines.length - 1; i++) {
+    const prevOffset = lineOffsets[i] ?? 0;
+    const lineLen = lines[i]?.length ?? 0;
+    lineOffsets.push(prevOffset + lineLen + 1);
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line) continue;
+
+    for (const match of line.matchAll(classRegex)) {
+      const name = match[1];
+      if (!name || map.has(name)) continue;
+
+      const lineStartOffset = lineOffsets[i] ?? 0;
+      const braceIdx = cssSource.indexOf("{", lineStartOffset);
+      if (braceIdx === -1) continue;
+
+      let depth = 1;
+      let pos = braceIdx + 1;
+      while (pos < cssSource.length && depth > 0) {
+        const ch = cssSource[pos];
+        if (ch === "{") depth++;
+        else if (ch === "}") depth--;
+        pos++;
+      }
+
+      if (depth !== 0) continue;
+
+      const ruleBlock = cssSource.slice(lineStartOffset, pos).trim();
+      map.set(name, ruleBlock);
+
+      const camelName = toCamelCase(name);
+      if (camelName !== name && !map.has(camelName)) {
+        map.set(camelName, ruleBlock);
+      }
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Resolves each exported class to its source location and nearby comment.
+ *
+ * Two-tier lookup: primary from original CSS scan, fallback via sourcemap index.
+ * Second pass propagates resolved lines to unresolved entries sharing the same hash
+ * (handles camelCase variant mismatches).
+ */
+export function resolveClassEntries(
+  classMapping: Record<string, string>,
+  classIndex: Map<string, LineMapping> | null,
+  comments: CssCommentInfo[] | null,
+  originalClassLines: Map<string, number> | null = null,
+  cssRuleBodies: Map<string, string> | null = null,
+): ClassEntry[] {
+  const entries: ClassEntry[] = [];
+
+  for (const key in classMapping) {
+    const hashKey = classMapping[key] ?? "";
+
+    let line = originalClassLines?.get(key);
+    if (!line) {
+      line = classIndex?.get(hashKey)?.originalLine;
+    }
+
+    const comment = line != null ? (comments?.[line - 1]?.content ?? "") : "";
+    const cssBlock = cssRuleBodies?.get(key) ?? "";
+
+    entries.push({ rule: key, value: hashKey, line, comment, cssBlock });
+  }
+
+  // Propagate resolved lines to unresolved entries with same hash value.
+  const lineByValue = new Map<string, number>();
+  const cssBlockByValue = new Map<string, string>();
+
+  for (const entry of entries) {
+    if (entry.line != null && !lineByValue.has(entry.value)) {
+      lineByValue.set(entry.value, entry.line);
+    }
+    if (entry.cssBlock && !cssBlockByValue.has(entry.value)) {
+      cssBlockByValue.set(entry.value, entry.cssBlock);
+    }
+  }
+
+  for (const entry of entries) {
+    if (entry.line == null) {
+      const propagatedLine = lineByValue.get(entry.value);
+      if (propagatedLine != null) {
+        entry.line = propagatedLine;
+        entry.comment = comments?.[propagatedLine - 1]?.content ?? "";
+      }
+    }
+    if (!entry.cssBlock) {
+      const propagatedBlock = cssBlockByValue.get(entry.value);
+      if (propagatedBlock) {
+        entry.cssBlock = propagatedBlock;
+      }
+    }
+  }
+
+  return entries;
+}

package/src/lib/css-comments.ts

@@ -0,0 +1,55 @@
+import type { CssCommentInfo } from "./types.ts";
+
+/** Builds a sorted array of newline offsets for O(log n) line lookups. */
+export function buildNewlineIndex(content: string): number[] {
+  const offsets: number[] = [];
+  for (let i = 0; i < content.length; i++) {
+    if (content.charCodeAt(i) === 10) {
+      offsets.push(i);
+    }
+  }
+  return offsets;
+}
+
+/** Returns the 1-based line number for a byte offset via binary search. */
+export function getLineAtOffset(newlineIndex: number[], offset: number): number {
+  let lo = 0;
+  let hi = newlineIndex.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if ((newlineIndex[mid] ?? 0) < offset) {
+      lo = mid + 1;
+    } else {
+      hi = mid;
+    }
+  }
+  return lo + 1;
+}
+
+/**
+ * Extracts `/** ... *​/` docblock comments from CSS source.
+ * Returns a sparse array keyed by end-line for O(1) lookup.
+ */
+export function extractCssComments(cssContent: string): CssCommentInfo[] {
+  const newlineIndex = buildNewlineIndex(cssContent);
+  const regex = /\/\*\*([\s\S]*?)\*\//g;
+  const comments: CssCommentInfo[] = [];
+
+  for (const match of cssContent.matchAll(regex)) {
+    const content = (match[1] ?? "").trim();
+
+    if (match.index === undefined) {
+      continue;
+    }
+
+    const endOffset = match.index + match[0].length;
+    const endLine = getLineAtOffset(newlineIndex, endOffset);
+
+    comments[endLine] = {
+      content,
+      endLine,
+    };
+  }
+
+  return comments;
+}

package/src/lib/declaration-map.ts

@@ -0,0 +1,40 @@
+import { encode } from "@jridgewell/sourcemap-codec";
+import type { DtsSourceMapping } from "./types.ts";
+
+type SourceMapSegment = [number, number, number, number];
+
+/** Generates a V3 source map JSON for `.d.ts` → `.module.css` navigation. */
+export function generateDeclarationMap(
+  dtsFileName: string,
+  cssRelativePath: string,
+  lineMappings: DtsSourceMapping[],
+  totalDtsLines: number,
+): string {
+  const sorted = [...lineMappings].sort(
+    (a, b) => a.dtsLine - b.dtsLine || a.dtsColumn - b.dtsColumn,
+  );
+
+  const decoded: SourceMapSegment[][] = [];
+  let mappingIdx = 0;
+
+  for (let line = 1; line <= totalDtsLines; line++) {
+    const lineSegments: SourceMapSegment[] = [];
+
+    while (mappingIdx < sorted.length && sorted[mappingIdx]?.dtsLine === line) {
+      const m = sorted[mappingIdx];
+      if (!m) break;
+      lineSegments.push([m.dtsColumn, 0, m.cssLine - 1, m.cssColumn]);
+      mappingIdx++;
+    }
+
+    decoded.push(lineSegments);
+  }
+
+  return JSON.stringify({
+    version: 3 as const,
+    file: dtsFileName,
+    sourceRoot: "",
+    sources: [cssRelativePath],
+    mappings: encode(decoded),
+  });
+}

package/src/lib/generate-dts.ts

@@ -0,0 +1,157 @@
+import type {
+  ClassEntry,
+  DtsGenerationOptions,
+  DtsSourceMapping,
+  GenerateDtsResult,
+} from "./types.ts";
+
+const EMOJI_ARROW = "\u{2197}"; // ↗
+const JS_IDENT_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+
+/**
+ * ASTERISK OPERATOR (U+2217) — visually identical to `*` but doesn't
+ * close JSDoc or open CSS comment regions in syntax highlighters.
+ */
+const ASTERISK_OPERATOR = "\u{2217}"; // ∗
+
+function escapeCssCommentDelimiters(text: string): string {
+  return text.replaceAll("/*", `/${ASTERISK_OPERATOR}`).replaceAll("*/", `${ASTERISK_OPERATOR}/`);
+}
+
+/** Builds a JSDoc comment line with file link and optional docblock/CSS snippet. */
+export function buildJsDocLine(item: ClassEntry, fileName: string, absolutePath: string): string {
+  const lineInfo = item.line ? `#L${item.line}` : "";
+  const lineLabel = item.line ? `:${item.line}` : "";
+  const commentBlock = item.comment ? `\`\`\`txt\n${item.comment.trim()}\n\`\`\`\n` : "";
+  const cssBlock = item.cssBlock
+    ? `---\n\`\`\`css\n${escapeCssCommentDelimiters(item.cssBlock).trim()}\n\`\`\`\n`
+    : "";
+  const separator = commentBlock || cssBlock ? "---\n" : "";
+  const leadingBreak = commentBlock || cssBlock ? "\n" : "";
+  return `  /** ${leadingBreak}${commentBlock}${cssBlock}${separator} [${EMOJI_ARROW} ${fileName}${lineLabel}](file://${absolutePath}${lineInfo}) */`;
+}
+
+/**
+ * Generates `.d.ts` content for a CSS module.
+ * Returns the declaration text and line mappings for declaration map generation.
+ */
+export function generateDtsContent(
+  entries: ClassEntry[],
+  fileName: string,
+  absolutePath: string,
+  options: DtsGenerationOptions = {},
+): GenerateDtsResult {
+  if (entries.length === 0) {
+    return { content: "export {};\n", lineMappings: [] };
+  }
+
+  const lines: string[] = [];
+  const lineMappings: DtsSourceMapping[] = [];
+
+  function pushContent(content: string): void {
+    for (const part of content.split("\n")) {
+      lines.push(part);
+    }
+  }
+
+  function trackMapping(cssLine: number | undefined, dtsColumn: number): void {
+    if (cssLine) {
+      lineMappings.push({
+        dtsLine: lines.length,
+        dtsColumn,
+        cssLine,
+        cssColumn: 0,
+      });
+    }
+  }
+
+  /**
+   * Pushes JSDoc + declaration with source mappings and a guard line.
+   * The guard line absorbs TS's off-by-one in declaration-map resolution.
+   */
+  function pushMappedPair(
+    jsDoc: string,
+    declaration: string,
+    cssLine: number | undefined,
+    declColumn: number,
+  ): void {
+    const jsDocFirstLine = lines.length + 1;
+    pushContent(jsDoc);
+    const jsDocLastLine = lines.length;
+
+    if (cssLine) {
+      for (let ln = jsDocFirstLine; ln <= jsDocLastLine; ln++) {
+        lineMappings.push({ dtsLine: ln, dtsColumn: 0, cssLine, cssColumn: 0 });
+      }
+    }
+
+    pushContent(declaration);
+    trackMapping(cssLine, declColumn);
+
+    lines.push("");
+    trackMapping(cssLine, 0);
+  }
+
+  if (options.namedExports) {
+    const emittedNamedExports = new Set<string>();
+
+    for (const item of entries) {
+      if (!JS_IDENT_RE.test(item.rule)) continue;
+      if (emittedNamedExports.has(item.rule)) continue;
+      emittedNamedExports.add(item.rule);
+
+      const jsDoc = buildJsDocLine(item, fileName, absolutePath);
+      pushMappedPair(jsDoc, `export declare const ${item.rule}: string;`, item.line, 0);
+    }
+
+    lines.push("");
+    pushContent(`/** [${EMOJI_ARROW} ${fileName}](file://${absolutePath}) */`);
+    lines.push("declare const styles: {");
+
+    const emittedProps = new Set<string>();
+
+    for (const item of entries) {
+      if (emittedProps.has(item.rule)) continue;
+      emittedProps.add(item.rule);
+
+      const jsDoc = buildJsDocLine(item, fileName, absolutePath);
+      pushMappedPair(
+        jsDoc,
+        `  readonly ${JSON.stringify(item.rule)}: ${JSON.stringify(item.value)};`,
+        item.line,
+        2,
+      );
+    }
+
+    lines.push("};");
+    lines.push("export default styles;");
+    lines.push("");
+
+    return { content: lines.join("\n"), lineMappings };
+  }
+
+  // Default mode
+  pushContent(`/** [${EMOJI_ARROW} ${fileName}](file://${absolutePath}) */`);
+  lines.push("declare const styles: {");
+
+  const emittedProps = new Set<string>();
+
+  for (const item of entries) {
+    if (emittedProps.has(item.rule)) continue;
+    emittedProps.add(item.rule);
+
+    const jsDoc = buildJsDocLine(item, fileName, absolutePath);
+    pushMappedPair(
+      jsDoc,
+      `  readonly ${JSON.stringify(item.rule)}: ${JSON.stringify(item.value)};`,
+      item.line,
+      2,
+    );
+  }
+
+  lines.push("};");
+  lines.push("export default styles;");
+  lines.push("");
+
+  return { content: lines.join("\n"), lineMappings };
+}

package/src/lib/index.ts

@@ -0,0 +1,16 @@
+export type {
+  CssCommentInfo,
+  ClassEntry,
+  DtsGenerationOptions,
+  DtsSourceMapping,
+  GenerateDtsResult,
+  VitePluginCssModuleTypesOptions,
+} from "./types.ts";
+
+export { normalizeFolderPath, normalizeFolderList, isInFolders, shouldProcessFile } from "./path-filter.ts";
+export { buildNewlineIndex, getLineAtOffset, extractCssComments } from "./css-comments.ts";
+export { patchViteModuleCode, evaluateModuleExports } from "./transform.ts";
+export { buildClassNameIndex, buildOriginalClassLineMap, extractCssRuleBodies, resolveClassEntries } from "./class-index.ts";
+export { buildJsDocLine, generateDtsContent } from "./generate-dts.ts";
+export { getInlineLineMappings, type LineMapping } from "./sourcemap.ts";
+export { generateDeclarationMap } from "./declaration-map.ts";

package/src/lib/path-filter.ts

@@ -0,0 +1,37 @@
+/** Normalizes a path: slashes, strip leading `./` and trailing `/`. */
+export function normalizeFolderPath(value: string): string {
+  return value
+    .replaceAll("\\", "/")
+    .replace(/^\.?\//, "")
+    .replace(/\/+$/, "");
+}
+
+/** Normalizes a string or array into cleaned folder paths. */
+export function normalizeFolderList(folders?: string | string[]): string[] {
+  if (!folders) return [];
+  const list = Array.isArray(folders) ? folders : [folders];
+  return list.map(normalizeFolderPath).filter(Boolean);
+}
+
+/** Checks if `relativeFilePath` starts with any of `folders`. */
+export function isInFolders(relativeFilePath: string, folders: string[]): boolean {
+  if (folders.length === 0) return false;
+  const normalizedPath = normalizeFolderPath(relativeFilePath);
+  return folders.some((folder) => {
+    return normalizedPath === folder || normalizedPath.startsWith(`${folder}/`);
+  });
+}
+
+/**
+ * Returns true if the file should be processed.
+ * Empty `include` means all files match. `exclude` always wins.
+ */
+export function shouldProcessFile(
+  relativeFilePath: string,
+  includeFolders: string[],
+  excludeFolders: string[],
+): boolean {
+  const isIncluded = includeFolders.length === 0 || isInFolders(relativeFilePath, includeFolders);
+  if (!isIncluded) return false;
+  return !isInFolders(relativeFilePath, excludeFolders);
+}

package/src/lib/sourcemap.ts

@@ -0,0 +1,73 @@
+import { Buffer } from "buffer";
+import { SourceMapConsumer, type RawSourceMap, type MappingItem } from "source-map";
+
+export interface LineMapping {
+  generatedLine: number;
+  generatedContent: string;
+  source?: string;
+  originalLine?: number;
+  originalContent?: string;
+}
+
+/**
+ * Extracts per-line generated→original mappings from an inline CSS sourcemap.
+ * Returns empty array if no inline sourcemap is found.
+ */
+export async function getInlineLineMappings(css: string): Promise<LineMapping[]> {
+  const prefix = "/*# sourceMappingURL=data:application/json;base64,";
+  const suffix = "*/";
+
+  const start = css.lastIndexOf(prefix);
+  const end = css.indexOf(suffix, start);
+  if (start === -1 || end === -1) return [];
+
+  const base64 = css.slice(start + prefix.length, end).trim();
+  const rawMap = JSON.parse(Buffer.from(base64, "base64").toString("utf8")) as RawSourceMap;
+  const cssLines = css.split("\n");
+
+  const consumer = await new SourceMapConsumer(rawMap);
+
+  const sourceLineMap = new Map<string, string[]>();
+  if (rawMap.sources && rawMap.sourcesContent) {
+    for (let i = 0; i < rawMap.sources.length; i++) {
+      const src = rawMap.sources[i];
+      const content = rawMap.sourcesContent[i];
+      if (typeof src === "string" && typeof content === "string") {
+        sourceLineMap.set(src, content.split("\n"));
+      }
+    }
+  }
+
+  const lineToMapping = new Map<number, MappingItem>();
+  consumer.eachMapping((m) => {
+    if (!lineToMapping.has(m.generatedLine)) {
+      lineToMapping.set(m.generatedLine, m);
+    }
+  });
+
+  const results: LineMapping[] = [];
+
+  for (let line = 1; line <= cssLines.length; line++) {
+    const generatedContent = cssLines[line - 1] ?? "";
+    const mapping = lineToMapping.get(line);
+
+    let source: string | undefined;
+    let originalLine: number | undefined;
+    let originalContent: string | undefined;
+
+    if (mapping?.source && mapping.originalLine) {
+      source = mapping.source;
+      originalLine = mapping.originalLine;
+
+      const srcLines = sourceLineMap.get(source);
+      if (srcLines && srcLines.length >= originalLine) {
+        originalContent = srcLines[originalLine - 1];
+      }
+    }
+
+    results.push({ generatedLine: line, generatedContent, source, originalLine, originalContent });
+  }
+
+  consumer.destroy();
+  return results;
+}

package/src/lib/transform.ts

@@ -0,0 +1,30 @@
+import { Buffer } from "buffer";
+
+/**
+ * Patches Vite's CSS module JS output to be evaluable as a standalone module.
+ * Comments out HMR/client imports and re-exports `__vite__css`.
+ */
+export function patchViteModuleCode(code: string): string {
+  return code
+    .replaceAll("import {", "// import {")
+    .replaceAll("__vite__updateStyle", "// __vite__updateStyle")
+    .replace(/if\s*\(import\.meta\.hot\)\s*\{[\s\S]*?\n\}/g, "")
+    .replaceAll("import.meta.hot", "// import.meta.hot")
+    .replaceAll("const __vite__css", "export const __vite__css");
+}
+
+/**
+ * Dynamically imports patched code via data: URI to extract the class mapping
+ * and raw CSS text.
+ */
+export async function evaluateModuleExports(patchedCode: string): Promise<{
+  classMapping: Record<string, string>;
+  cssText: string;
+}> {
+  const base64 = Buffer.from(patchedCode, "utf-8").toString("base64");
+  const mod = await import(`data:text/javascript;base64,${base64}`);
+  return {
+    classMapping: mod.default ?? {},
+    cssText: mod.__vite__css ?? "",
+  };
+}

package/src/lib/types.ts

@@ -0,0 +1,65 @@
+export interface CssCommentInfo {
+  content: string;
+  /** 1-based line of the closing comment marker. */
+  endLine: number;
+}
+
+export interface VitePluginCssModuleTypesOptions {
+  /** Output directory for `.d.ts` files, relative to Vite root. */
+  dtsOutputDir: string;
+
+  /** Folder(s) to include (prefix-matched). When omitted, all folders match. */
+  include?: string | string[];
+
+  /**
+   * Folder(s) to exclude. Takes precedence over `include`.
+   * @default ["node_modules", ".git", "dist", "build"]
+   */
+  exclude?: string | string[];
+
+  /** Emit `export declare const` per class instead of a single `styles` block. */
+  namedExports?: boolean;
+
+  /**
+   * Use TS 5.0+ arbitrary-extension naming: `*.d.css.ts` instead of `*.css.d.ts`.
+   * Requires `allowArbitraryExtensions: true` in tsconfig.
+   */
+  allowArbitraryExtensions?: boolean;
+
+  /**
+   * Generate `.d.ts.map` for "Go to Definition" navigation to CSS source.
+   * Requires `css.devSourcemap: true`.
+   * @default true
+   */
+  declarationMap?: boolean;
+}
+
+export interface ClassEntry {
+  /** Original class name (e.g., `my-class`). */
+  rule: string;
+  /** Hashed/scoped class name from Vite (e.g., `_my-class_1a2b3`). */
+  value: string;
+  /** 1-based line in the original CSS source. */
+  line?: number;
+  /** Preceding docblock comment content. */
+  comment: string;
+  /** CSS rule block text (selector + body). */
+  cssBlock: string;
+}
+
+/** Maps a `.d.ts` position to a `.module.css` position for declaration maps. */
+export interface DtsSourceMapping {
+  dtsLine: number;
+  dtsColumn: number;
+  cssLine: number;
+  cssColumn: number;
+}
+
+export interface GenerateDtsResult {
+  content: string;
+  lineMappings: DtsSourceMapping[];
+}
+
+export interface DtsGenerationOptions {
+  namedExports?: boolean;
+}