vite-plugin-css-module-types 1.0.0

package/src/tests/class-index.spec.ts

@@ -0,0 +1,439 @@
+import { describe, it, expect } from "vitest";
+import type { LineMapping } from "../lib/sourcemap.ts";
+import type { CssCommentInfo } from "../lib/types.ts";
+import {
+  buildClassNameIndex,
+  buildOriginalClassLineMap,
+  extractCssRuleBodies,
+  resolveClassEntries,
+} from "../lib/class-index.ts";
+
+// ─── buildClassNameIndex ────────────────────────────────────────────────────
+
+describe("buildClassNameIndex", () => {
+  it("builds index from generated CSS lines with class selectors", () => {
+    const mappings: LineMapping[] = [
+      {
+        generatedLine: 1,
+        generatedContent: ".btn_hash { color: red; }",
+        originalLine: 5,
+      },
+      {
+        generatedLine: 2,
+        generatedContent: ".card_hash { padding: 10px; }",
+        originalLine: 10,
+      },
+    ];
+
+    const index = buildClassNameIndex(mappings);
+    expect(index.get("btn_hash")).toBe(mappings[0]);
+    expect(index.get("card_hash")).toBe(mappings[1]);
+  });
+
+  it("keeps the first occurrence when a class appears multiple times", () => {
+    const mappings: LineMapping[] = [
+      {
+        generatedLine: 1,
+        generatedContent: ".btn_hash { color: red; }",
+        originalLine: 5,
+      },
+      {
+        generatedLine: 3,
+        generatedContent: ".btn_hash:hover { color: blue; }",
+        originalLine: 8,
+      },
+    ];
+
+    const index = buildClassNameIndex(mappings);
+    expect(index.get("btn_hash")?.originalLine).toBe(5);
+  });
+
+  it("skips lines without originalLine", () => {
+    const mappings: LineMapping[] = [
+      {
+        generatedLine: 1,
+        generatedContent: ".btn_hash { color: red; }",
+      },
+    ];
+
+    const index = buildClassNameIndex(mappings);
+    expect(index.size).toBe(0);
+  });
+
+  it("extracts multiple class names from a single line", () => {
+    const mappings: LineMapping[] = [
+      {
+        generatedLine: 1,
+        generatedContent: ".container .btn_hash, .card_hash { }",
+        originalLine: 3,
+      },
+    ];
+
+    const index = buildClassNameIndex(mappings);
+    expect(index.has("container")).toBe(true);
+    expect(index.has("btn_hash")).toBe(true);
+    expect(index.has("card_hash")).toBe(true);
+  });
+
+  it('ignores numeric-starting tokens like ".5em"', () => {
+    const mappings: LineMapping[] = [
+      {
+        generatedLine: 1,
+        generatedContent: "margin: .5em; border-radius: .25rem;",
+        originalLine: 2,
+      },
+    ];
+
+    const index = buildClassNameIndex(mappings);
+    expect(index.size).toBe(0);
+  });
+
+  it("returns empty map for empty input", () => {
+    const index = buildClassNameIndex([]);
+    expect(index.size).toBe(0);
+  });
+});
+
+// ─── resolveClassEntries ────────────────────────────────────────────────────
+
+describe("resolveClassEntries", () => {
+  it("resolves classes with line numbers and comments", () => {
+    const classMapping = { button: "btn_hash" };
+    const mapping: LineMapping = {
+      generatedLine: 1,
+      generatedContent: ".btn_hash { }",
+      originalLine: 10,
+    };
+    const classIndex = new Map([["btn_hash", mapping]]);
+
+    const comments: CssCommentInfo[] = [];
+    comments[9] = { content: "Primary button", endLine: 9 };
+
+    const entries = resolveClassEntries(classMapping, classIndex, comments);
+    expect(entries).toEqual([
+      {
+        rule: "button",
+        value: "btn_hash",
+        line: 10,
+        comment: "Primary button",
+        cssBlock: "",
+      },
+    ]);
+  });
+
+  it("resolves classes without sourcemap (null index)", () => {
+    const classMapping = { button: "btn_hash" };
+
+    const entries = resolveClassEntries(classMapping, null, null);
+    expect(entries).toEqual([
+      {
+        rule: "button",
+        value: "btn_hash",
+        line: undefined,
+        comment: "",
+        cssBlock: "",
+      },
+    ]);
+  });
+
+  it("resolves classes with no preceding comment", () => {
+    const classMapping = { button: "btn_hash" };
+    const mapping: LineMapping = {
+      generatedLine: 1,
+      generatedContent: ".btn_hash { }",
+      originalLine: 5,
+    };
+    const classIndex = new Map([["btn_hash", mapping]]);
+
+    const entries = resolveClassEntries(classMapping, classIndex, []);
+    expect(entries).toEqual([
+      {
+        rule: "button",
+        value: "btn_hash",
+        line: 5,
+        comment: "",
+        cssBlock: "",
+      },
+    ]);
+  });
+
+  it("handles multiple classes ordered by mapping keys", () => {
+    const classMapping = { alpha: "a_hash", beta: "b_hash" };
+    const entries = resolveClassEntries(classMapping, null, null);
+    expect(entries).toHaveLength(2);
+    expect(entries[0]?.rule).toBe("alpha");
+    expect(entries[1]?.rule).toBe("beta");
+  });
+
+  it("prefers originalClassLines over classIndex for line resolution", () => {
+    const classMapping = { button: "btn_hash" };
+    const mapping: LineMapping = {
+      generatedLine: 1,
+      generatedContent: ".btn_hash { }",
+      originalLine: 99, // wrong line from sourcemap
+    };
+    const classIndex = new Map([["btn_hash", mapping]]);
+    const originalClassLines = new Map([["button", 5]]); // correct line
+
+    const entries = resolveClassEntries(classMapping, classIndex, [], originalClassLines);
+    expect(entries[0]?.line).toBe(5);
+  });
+
+  it("falls back to classIndex when originalClassLines has no match", () => {
+    const classMapping = { button: "btn_hash" };
+    const mapping: LineMapping = {
+      generatedLine: 1,
+      generatedContent: ".btn_hash { }",
+      originalLine: 10,
+    };
+    const classIndex = new Map([["btn_hash", mapping]]);
+    const originalClassLines = new Map<string, number>(); // empty
+
+    const entries = resolveClassEntries(classMapping, classIndex, [], originalClassLines);
+    expect(entries[0]?.line).toBe(10);
+  });
+
+  it("resolves composes classes that fail sourcemap lookup", () => {
+    // Simulates the `composes:` case where the hashed value is multi-class
+    const classMapping = {
+      "zone-controlled-counter": "_zone-controlled-counter_15m5f_8 _text-s_bold_wt63m_93",
+    };
+    // The multi-class hash won't match any single entry in classIndex
+    const classIndex = new Map<string, LineMapping>();
+    const originalClassLines = new Map([["zone-controlled-counter", 8]]);
+
+    const entries = resolveClassEntries(classMapping, classIndex, [], originalClassLines);
+    expect(entries[0]?.line).toBe(8);
+  });
+
+  it("propagates line from resolved entry to unresolved entry with same hash", () => {
+    // Simulates Vite localsConvention: 'camelCase' with lodash-style camelCase
+    // that produces a variant our toCamelCase doesn't match.
+    // CSS: .text_c-disabled  (line 169)
+    // Vite classMapping keys: 'text_c-disabled', 'textCDisabled' (lodash camelCase)
+    // Our toCamelCase('text_c-disabled') = 'text_cDisabled' (hyphens only)
+    // So 'textCDisabled' is NOT in originalClassLines.
+    const hash = "_text_c-disabled_wt63m_169";
+    const classMapping = {
+      "text_c-disabled": hash,
+      textCDisabled: hash,
+    };
+    const originalClassLines = new Map([
+      ["text_c-disabled", 169],
+      ["text_cDisabled", 169], // our toCamelCase variant
+    ]);
+
+    const entries = resolveClassEntries(classMapping, null, null, originalClassLines);
+
+    const original = entries.find((e) => e.rule === "text_c-disabled");
+    const viteVariant = entries.find((e) => e.rule === "textCDisabled");
+
+    expect(original?.line).toBe(169);
+    // textCDisabled is not in originalClassLines, but shares the same hash
+    // → inherits line from the resolved entry via second-pass propagation.
+    expect(viteVariant?.line).toBe(169);
+  });
+
+  it("propagates comment along with line in second pass", () => {
+    const hash = "_btn-primary_h";
+    const classMapping = {
+      "btn-primary": hash,
+      btnPrimary: hash, // Vite camelCase variant
+    };
+    const originalClassLines = new Map([
+      ["btn-primary", 5],
+      ["btnPrimary", 5],
+    ]);
+    const comments: CssCommentInfo[] = [];
+    comments[4] = { content: "Primary button", endLine: 4 };
+
+    // Remove btnPrimary from originalClassLines to force second-pass
+    originalClassLines.delete("btnPrimary");
+
+    const entries = resolveClassEntries(classMapping, null, comments, originalClassLines);
+
+    const camelEntry = entries.find((e) => e.rule === "btnPrimary");
+    expect(camelEntry?.line).toBe(5);
+    expect(camelEntry?.comment).toBe("Primary button");
+  });
+});
+
+// ─── buildOriginalClassLineMap ──────────────────────────────────────────────
+
+describe("buildOriginalClassLineMap", () => {
+  it("maps class selectors to their 1-based line numbers", () => {
+    const css = [
+      ".zone-filter {",
+      "  position: relative;",
+      "}",
+      "",
+      ".zone-controlled-counter {",
+      "  margin-right: 0.25rem;",
+      "}",
+      "",
+      ".zone-state-filter {",
+      "  display: flex;",
+      "}",
+    ].join("\n");
+
+    const map = buildOriginalClassLineMap(css);
+
+    expect(map.get("zone-filter")).toBe(1);
+    expect(map.get("zone-controlled-counter")).toBe(5);
+    expect(map.get("zone-state-filter")).toBe(9);
+
+    // camelCase variants are also registered
+    expect(map.get("zoneFilter")).toBe(1);
+    expect(map.get("zoneControlledCounter")).toBe(5);
+    expect(map.get("zoneStateFilter")).toBe(9);
+  });
+
+  it("keeps the first occurrence when a class appears multiple times", () => {
+    const css = [".btn { color: red; }", ".btn:hover { color: blue; }"].join("\n");
+
+    const map = buildOriginalClassLineMap(css);
+    expect(map.get("btn")).toBe(1);
+  });
+
+  it('ignores numeric-starting tokens like ".5em"', () => {
+    const css = "margin: .5em; border-radius: .25rem;";
+    const map = buildOriginalClassLineMap(css);
+    expect(map.size).toBe(0);
+  });
+
+  it("extracts multiple class names from a single line", () => {
+    const css = ".container .btn, .card { }";
+    const map = buildOriginalClassLineMap(css);
+
+    expect(map.has("container")).toBe(true);
+    expect(map.has("btn")).toBe(true);
+    expect(map.has("card")).toBe(true);
+  });
+
+  it("returns empty map for CSS with no class selectors", () => {
+    const css = "body { margin: 0; }";
+    const map = buildOriginalClassLineMap(css);
+    expect(map.size).toBe(0);
+  });
+
+  it("returns empty map for empty input", () => {
+    const map = buildOriginalClassLineMap("");
+    expect(map.size).toBe(0);
+  });
+
+  it("does not add camelCase variant when name has no dashes", () => {
+    const css = ".button { color: red; }";
+    const map = buildOriginalClassLineMap(css);
+    expect(map.get("button")).toBe(1);
+    // "button" is already camelCase, so no extra entry
+    expect(map.size).toBe(1);
+  });
+
+  it("registers camelCase variant for kebab-case class", () => {
+    const css = ".my-component { color: red; }";
+    const map = buildOriginalClassLineMap(css);
+    expect(map.get("my-component")).toBe(1);
+    expect(map.get("myComponent")).toBe(1);
+    expect(map.size).toBe(2);
+  });
+
+  it("handles composes directive without picking up from-path as class", () => {
+    const css = [
+      ".counter {",
+      '  composes: text-bold from "@app/styles/typography.module.css";',
+      "  margin: 0;",
+      "}",
+    ].join("\n");
+
+    const map = buildOriginalClassLineMap(css);
+    expect(map.get("counter")).toBe(1);
+    // text-bold in composes has no `.` prefix, so the regex won't pick it up
+    expect(map.has("text-bold")).toBe(false);
+  });
+});
+
+// ─── extractCssRuleBodies ───────────────────────────────────────────────────
+
+describe("extractCssRuleBodies", () => {
+  it("extracts a single-line rule block", () => {
+    const css = ".btn { color: red; }";
+    const map = extractCssRuleBodies(css);
+    expect(map.get("btn")).toBe(".btn { color: red; }");
+  });
+
+  it("extracts a multi-line rule block", () => {
+    const css = [
+      ".text-s {",
+      "  font-size: var(--fs-s);",
+      "  font-weight: var(--fw-regular);",
+      "  line-height: var(--lh-s);",
+      "}",
+    ].join("\n");
+
+    const map = extractCssRuleBodies(css);
+    expect(map.get("text-s")).toBe(css);
+  });
+
+  it("extracts multiple rule blocks", () => {
+    const css = [
+      ".zone-filter {",
+      "  position: relative;",
+      "}",
+      "",
+      ".zone-controlled-counter {",
+      "  margin-right: 0.25rem;",
+      "}",
+    ].join("\n");
+
+    const map = extractCssRuleBodies(css);
+    expect(map.get("zone-filter")).toBe(".zone-filter {\n  position: relative;\n}");
+    expect(map.get("zone-controlled-counter")).toBe(
+      ".zone-controlled-counter {\n  margin-right: 0.25rem;\n}",
+    );
+  });
+
+  it("registers camelCase variants", () => {
+    const css = ".my-component { color: red; }";
+    const map = extractCssRuleBodies(css);
+    expect(map.get("my-component")).toBe(".my-component { color: red; }");
+    expect(map.get("myComponent")).toBe(".my-component { color: red; }");
+  });
+
+  it("keeps only the first occurrence", () => {
+    const css = [".btn { color: red; }", ".btn:hover { color: blue; }"].join("\n");
+
+    const map = extractCssRuleBodies(css);
+    expect(map.get("btn")).toBe(".btn { color: red; }");
+  });
+
+  it("ignores numeric-starting tokens", () => {
+    const css = "margin: .5em;";
+    const map = extractCssRuleBodies(css);
+    expect(map.size).toBe(0);
+  });
+
+  it("returns empty map for CSS without class selectors", () => {
+    const css = "body { margin: 0; }";
+    const map = extractCssRuleBodies(css);
+    expect(map.size).toBe(0);
+  });
+
+  it("returns empty map for empty input", () => {
+    const map = extractCssRuleBodies("");
+    expect(map.size).toBe(0);
+  });
+
+  it("handles nested braces correctly", () => {
+    const css = [
+      ".container {",
+      "  display: grid;",
+      "  @media (max-width: 768px) {",
+      "    display: block;",
+      "  }",
+      "}",
+    ].join("\n");
+
+    const map = extractCssRuleBodies(css);
+    expect(map.get("container")).toBe(css);
+  });
+});

package/src/tests/css-comments.spec.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from "vitest";
+import { buildNewlineIndex, getLineAtOffset, extractCssComments } from "../lib/css-comments.ts";
+
+// ─── buildNewlineIndex ──────────────────────────────────────────────────────
+
+describe("buildNewlineIndex", () => {
+  it("returns empty array for content without newlines", () => {
+    expect(buildNewlineIndex("no newlines here")).toEqual([]);
+  });
+
+  it("returns offsets for each newline character", () => {
+    expect(buildNewlineIndex("a\nb\nc")).toEqual([1, 3]);
+  });
+
+  it("handles content starting with a newline", () => {
+    expect(buildNewlineIndex("\nfirst")).toEqual([0]);
+  });
+
+  it("handles consecutive newlines", () => {
+    expect(buildNewlineIndex("a\n\n\nb")).toEqual([1, 2, 3]);
+  });
+
+  it("returns empty array for empty string", () => {
+    expect(buildNewlineIndex("")).toEqual([]);
+  });
+});
+
+// ─── getLineAtOffset ────────────────────────────────────────────────────────
+
+describe("getLineAtOffset", () => {
+  // Content: "Hello\nWorld\nFoo"
+  // Newlines at: [5, 11]
+  const newlineIndex = [5, 11];
+
+  it("returns line 1 for offsets before the first newline", () => {
+    expect(getLineAtOffset(newlineIndex, 0)).toBe(1);
+    expect(getLineAtOffset(newlineIndex, 3)).toBe(1);
+    expect(getLineAtOffset(newlineIndex, 5)).toBe(1);
+  });
+
+  it("returns line 2 for offsets after the first newline", () => {
+    expect(getLineAtOffset(newlineIndex, 6)).toBe(2);
+    expect(getLineAtOffset(newlineIndex, 11)).toBe(2);
+  });
+
+  it("returns line 3 for offsets after the second newline", () => {
+    expect(getLineAtOffset(newlineIndex, 12)).toBe(3);
+    expect(getLineAtOffset(newlineIndex, 14)).toBe(3);
+  });
+
+  it("returns line 1 for empty newline index", () => {
+    expect(getLineAtOffset([], 0)).toBe(1);
+    expect(getLineAtOffset([], 100)).toBe(1);
+  });
+});
+
+// ─── extractCssComments ─────────────────────────────────────────────────────
+
+describe("extractCssComments", () => {
+  it("returns empty array when no docblock comments exist", () => {
+    const css = ".button { color: red; }";
+    const comments = extractCssComments(css);
+    expect(comments.filter(Boolean)).toEqual([]);
+  });
+
+  it("extracts a single-line docblock comment", () => {
+    const css = "/** Primary button style */\n.button { color: red; }";
+    const comments = extractCssComments(css);
+    expect(comments[1]).toEqual({
+      content: "Primary button style",
+      endLine: 1,
+    });
+  });
+
+  it("extracts a multi-line docblock comment", () => {
+    const css = [
+      "/**",
+      " * Multi-line comment",
+      " * with details",
+      " */",
+      ".button { color: red; }",
+    ].join("\n");
+    const comments = extractCssComments(css);
+    expect(comments[4]).toBeDefined();
+    expect(comments[4]?.content).toContain("Multi-line comment");
+    expect(comments[4]?.content).toContain("with details");
+    expect(comments[4]?.endLine).toBe(4);
+  });
+
+  it("extracts multiple docblock comments keyed by end line", () => {
+    const css = [
+      "/** First comment */",
+      ".a { color: red; }",
+      "/** Second comment */",
+      ".b { color: blue; }",
+    ].join("\n");
+    const comments = extractCssComments(css);
+    expect(comments[1]).toEqual({ content: "First comment", endLine: 1 });
+    expect(comments[3]).toEqual({ content: "Second comment", endLine: 3 });
+  });
+
+  it("ignores non-docblock comments (single asterisk)", () => {
+    const css = "/* Regular comment */\n.a { color: red; }";
+    const comments = extractCssComments(css);
+    expect(comments.filter(Boolean)).toEqual([]);
+  });
+
+  it("returns sparse array with correct line numbers", () => {
+    const css = "\n\n/** Comment on line 3 */\n.a { }";
+    const comments = extractCssComments(css);
+    expect(comments[3]).toBeDefined();
+    expect(comments[3]?.endLine).toBe(3);
+    expect(comments[1]).toBeUndefined();
+    expect(comments[2]).toBeUndefined();
+  });
+});

package/src/tests/declaration-map.spec.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "vitest";
+import { decode } from "@jridgewell/sourcemap-codec";
+import { generateDeclarationMap } from "../lib/declaration-map.ts";
+import type { DtsSourceMapping } from "../lib/types.ts";
+
+// ─── generateDeclarationMap ────────────────────────────────────────────────
+
+describe("generateDeclarationMap", () => {
+  it("generates a valid V3 source map JSON", () => {
+    const mappings: DtsSourceMapping[] = [{ dtsLine: 2, dtsColumn: 0, cssLine: 1, cssColumn: 0 }];
+
+    const result = generateDeclarationMap(
+      "comp.module.d.css.ts",
+      "../comp.module.css",
+      mappings,
+      5,
+    );
+    const map = JSON.parse(result);
+
+    expect(map.version).toBe(3);
+    expect(map.file).toBe("comp.module.d.css.ts");
+    expect(map.sources).toEqual(["../comp.module.css"]);
+    expect(typeof map.mappings).toBe("string");
+  });
+
+  it("produces correct mapping for a single entry", () => {
+    const mappings: DtsSourceMapping[] = [{ dtsLine: 2, dtsColumn: 0, cssLine: 1, cssColumn: 0 }];
+
+    const result = generateDeclarationMap("f.d.ts", "../f.css", mappings, 3);
+    const map = JSON.parse(result);
+    const decoded = decode(map.mappings);
+
+    // Line 1 (idx 0): empty, Line 2 (idx 1): one segment, Line 3 (idx 2): empty
+    expect(decoded[0]).toEqual([]);
+    expect(decoded[1]).toEqual([[0, 0, 0, 0]]); // genCol=0, src=0, srcLine=0, srcCol=0
+    expect(decoded[2]).toEqual([]);
+  });
+
+  it("produces correct mappings for multiple entries", () => {
+    const mappings: DtsSourceMapping[] = [
+      { dtsLine: 2, dtsColumn: 0, cssLine: 1, cssColumn: 0 },
+      { dtsLine: 4, dtsColumn: 0, cssLine: 8, cssColumn: 0 },
+      { dtsLine: 6, dtsColumn: 0, cssLine: 13, cssColumn: 0 },
+    ];
+
+    const result = generateDeclarationMap("f.d.ts", "../f.css", mappings, 7);
+    const map = JSON.parse(result);
+    const decoded = decode(map.mappings);
+
+    expect(decoded[1]).toEqual([[0, 0, 0, 0]]); // dts line 2 → css line 1 (0-based: 0)
+    expect(decoded[3]).toEqual([[0, 0, 7, 0]]); // dts line 4 → css line 8 (0-based: 7)
+    expect(decoded[5]).toEqual([[0, 0, 12, 0]]); // dts line 6 → css line 13 (0-based: 12)
+  });
+
+  it("handles entries with non-zero dtsColumn", () => {
+    const mappings: DtsSourceMapping[] = [{ dtsLine: 3, dtsColumn: 2, cssLine: 5, cssColumn: 0 }];
+
+    const result = generateDeclarationMap("f.d.ts", "../f.css", mappings, 4);
+    const map = JSON.parse(result);
+    const decoded = decode(map.mappings);
+
+    expect(decoded[2]).toEqual([[2, 0, 4, 0]]); // genCol=2, srcLine=4 (0-based)
+  });
+
+  it("handles multiple mappings on the same line", () => {
+    const mappings: DtsSourceMapping[] = [
+      { dtsLine: 2, dtsColumn: 0, cssLine: 1, cssColumn: 0 },
+      { dtsLine: 2, dtsColumn: 10, cssLine: 3, cssColumn: 5 },
+    ];
+
+    const result = generateDeclarationMap("f.d.ts", "../f.css", mappings, 3);
+    const map = JSON.parse(result);
+    const decoded = decode(map.mappings);
+
+    expect(decoded[1]).toEqual([
+      [0, 0, 0, 0], // first segment
+      [10, 0, 2, 5], // second segment
+    ]);
+  });
+
+  it("returns empty lines for no line mappings", () => {
+    const result = generateDeclarationMap("f.d.ts", "../f.css", [], 3);
+    const map = JSON.parse(result);
+    const decoded = decode(map.mappings);
+
+    expect(decoded).toEqual([[], [], []]);
+  });
+
+  it("sorts unsorted mappings by line and column", () => {
+    const mappings: DtsSourceMapping[] = [
+      { dtsLine: 4, dtsColumn: 0, cssLine: 8, cssColumn: 0 },
+      { dtsLine: 2, dtsColumn: 0, cssLine: 1, cssColumn: 0 },
+    ];
+
+    const result = generateDeclarationMap("f.d.ts", "../f.css", mappings, 5);
+    const map = JSON.parse(result);
+    const decoded = decode(map.mappings);
+
+    expect(decoded[1]).toEqual([[0, 0, 0, 0]]); // dts 2 → css 1
+    expect(decoded[3]).toEqual([[0, 0, 7, 0]]); // dts 4 → css 8
+  });
+});