tempest-react-sdk 0.28.1 → 0.29.1

package/bin/lib/css/extract.test.mjs

@@ -0,0 +1,304 @@
+import { createRequire } from "node:module";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { analyzeCss } from "./analyze.mjs";
+import { applyExtraction, classNamesIn, kebab, loneClass, planExtraction } from "./extract.mjs";
+import { parseCss } from "./parse.mjs";
+
+const SELF_DIR = resolve(dirname(new URL(import.meta.url).pathname), "..", "..");
+const TYPESCRIPT_DIR = dirname(createRequire(import.meta.url).resolve("typescript/package.json"));
+
+let root;
+
+/** Write a file inside the fixture project, creating its directory. */
+function write(rel, text) {
+    const full = join(root, rel);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, text);
+    return full;
+}
+
+const ROW = `.row {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+}
+.title {
+    font-weight: 600;
+}
+`;
+
+/**
+ * A minimal project the codemod can act on: a tsconfig with the `@/*` alias, a
+ * global stylesheet that the entry imports, and the project's own TypeScript
+ * (symlinked, because the CLI resolves the compiler from the project on purpose).
+ */
+function project() {
+    write("package.json", JSON.stringify({ name: "fixture" }));
+    write(
+        "tsconfig.json",
+        JSON.stringify({ compilerOptions: { baseUrl: ".", paths: { "@/*": ["./src/*"] } } }),
+    );
+    write("src/index.css", ":root {\n    --brand: #0d6efd;\n}\n");
+    write("src/main.tsx", 'import "./index.css";\n');
+    mkdirSync(join(root, "node_modules"), { recursive: true });
+    symlinkSync(TYPESCRIPT_DIR, join(root, "node_modules", "typescript"), "dir");
+}
+
+/** Two modules declaring the same block, each used from its own component. */
+function twoCopies() {
+    write("src/components/Card.module.css", ROW);
+    write(
+        "src/components/Card.tsx",
+        'import styles from "./Card.module.css";\n\nexport const Card = () => (\n  <div className={styles.row}>\n    <b className={styles.title}>x</b>\n  </div>\n);\n',
+    );
+    write("src/components/List.module.css", ROW.replace(".row", ".line"));
+    write(
+        "src/components/List.tsx",
+        'import styles from "@/components/List.module.css";\n\nexport const List = () => (\n  <li className={styles.line}>\n    <b className={styles.title}>x</b>\n  </li>\n);\n',
+    );
+}
+
+const plan = (options = {}) =>
+    planExtraction({
+        analysis: analyzeCss({ root, targets: ["."], selfDir: SELF_DIR }),
+        root,
+        ...options,
+    });
+
+beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "tempest-extract-"));
+});
+
+afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+});
+
+describe("helpers", () => {
+    it("recognizes a lone class selector and rejects anything else", () => {
+        expect(loneClass(".row")).toBe("row");
+        expect(loneClass("  .card-header ")).toBe("card-header");
+        expect(loneClass(".row:hover")).toBeNull();
+        expect(loneClass(".a .b")).toBeNull();
+        expect(loneClass(".a.b")).toBeNull();
+        expect(loneClass("div")).toBeNull();
+    });
+
+    it("kebab-cases a camelCase class name", () => {
+        expect(kebab("cardHeader")).toBe("card-header");
+        expect(kebab("row")).toBe("row");
+        expect(kebab("grid_2")).toBe("grid-2");
+    });
+
+    it("collects every class a sheet defines", () => {
+        const parsed = parseCss(".a .b { color: red; }\n.c:hover { color: blue; }\n");
+        expect(classNamesIn(parsed)).toEqual(new Set(["a", "b", "c"]));
+    });
+});
+
+describe("planExtraction — the happy path", () => {
+    beforeEach(() => {
+        project();
+        twoCopies();
+    });
+
+    it("plans one global class from two modules, with every call site", () => {
+        const result = plan();
+        expect(result.status).toBe("ok");
+        expect(result.target.file).toBe(join("src", "index.css"));
+        expect(result.groups).toHaveLength(1);
+
+        const [group] = result.groups;
+        expect(group.name).toBe("u-row");
+        expect(group.decls.map((d) => d.prop)).toEqual(["display", "align-items", "gap"]);
+        expect(group.occurrences.map((o) => o.className).sort()).toEqual(["line", "row"]);
+        expect(group.occurrences.flatMap((o) => o.sites)).toHaveLength(2);
+    });
+
+    it("honors --css-prefix", () => {
+        expect(plan({ prefix: "shared-" }).groups[0].name).toBe("shared-row");
+    });
+
+    it("honors an explicit --css-target", () => {
+        write("src/styles/app.css", "");
+        write("src/main.tsx", 'import "./styles/app.css";\n');
+        expect(plan({ target: "src/styles/app.css" }).target.file).toBe(
+            join("src", "styles", "app.css"),
+        );
+    });
+});
+
+describe("applyExtraction", () => {
+    beforeEach(() => {
+        project();
+        twoCopies();
+    });
+
+    it("moves the rule, deletes the local copies and rewrites the JSX", () => {
+        const result = applyExtraction({ plan: plan() });
+        expect(result.moved).toBe(2);
+        expect(result.rules).toBe(1);
+
+        const global = readFileSync(join(root, "src/index.css"), "utf8");
+        expect(global).toContain(".u-row {");
+        expect(global).toContain("align-items: center;");
+        expect(global).toContain("extraído por");
+
+        const card = readFileSync(join(root, "src/components/Card.module.css"), "utf8");
+        expect(card).not.toContain(".row");
+        expect(card).toContain(".title");
+
+        // `className={styles.row}` loses the braces; the other class is untouched.
+        const tsx = readFileSync(join(root, "src/components/Card.tsx"), "utf8");
+        expect(tsx).toContain('<div className="u-row">');
+        expect(tsx).toContain("{styles.title}");
+    });
+
+    it("writes nothing on a dry run", () => {
+        const before = readFileSync(join(root, "src/components/Card.tsx"), "utf8");
+        const result = applyExtraction({ plan: plan(), dryRun: true });
+        expect(result.moved).toBe(2);
+        expect(readFileSync(join(root, "src/components/Card.tsx"), "utf8")).toBe(before);
+        expect(readFileSync(join(root, "src/index.css"), "utf8")).not.toContain(".u-row");
+    });
+
+    it("leaves nothing to do on a second run", () => {
+        applyExtraction({ plan: plan() });
+        expect(plan().groups).toEqual([]);
+    });
+
+    it("rewrites a class read through a string index", () => {
+        write(
+            "src/components/List.tsx",
+            'import styles from "./List.module.css";\n\nexport const List = () => <li className={styles["line"]} />;\n',
+        );
+        applyExtraction({ plan: plan() });
+        expect(readFileSync(join(root, "src/components/List.tsx"), "utf8")).toContain(
+            'className="u-row"',
+        );
+    });
+
+    it("keeps the surrounding call when the class is one argument of many", () => {
+        write(
+            "src/components/List.tsx",
+            'import { cn } from "tempest-react-sdk";\nimport styles from "./List.module.css";\n\nexport const List = ({ on }: { on: boolean }) => (\n  <li className={cn(styles.line, on && styles.title)} />\n);\n',
+        );
+        applyExtraction({ plan: plan() });
+        expect(readFileSync(join(root, "src/components/List.tsx"), "utf8")).toContain(
+            'cn("u-row", on && styles.title)',
+        );
+    });
+});
+
+describe("planExtraction — refusals", () => {
+    beforeEach(project);
+
+    /** The reason attached to the first refusal, for a fixture built by the caller. */
+    const refusal = () => plan().refusals[0]?.reason ?? "";
+
+    it("refuses a class another rule in the same module mentions", () => {
+        twoCopies();
+        write("src/components/Card.module.css", `${ROW}.row:hover {\n    opacity: 0.8;\n}\n`);
+        expect(refusal()).toContain("ficaria sem sujeito");
+        expect(plan().groups).toEqual([]);
+    });
+
+    it("refuses a rule inside an at-rule", () => {
+        twoCopies();
+        write(
+            "src/components/Card.module.css",
+            `.title {\n    font-weight: 600;\n}\n@media (min-width: 600px) {\n    .row {\n        display: flex;\n        align-items: center;\n        gap: 8px;\n    }\n}\n`,
+        );
+        expect(refusal()).toContain("mudaria quando a regra vale");
+    });
+
+    it("refuses when the module would be left empty", () => {
+        twoCopies();
+        write(
+            "src/components/Card.module.css",
+            ".row {\n    display: flex;\n    align-items: center;\n    gap: 8px;\n}\n",
+        );
+        expect(refusal()).toContain("única regra do módulo");
+    });
+
+    it("refuses a module used through a computed key", () => {
+        twoCopies();
+        write(
+            "src/components/Card.tsx",
+            'import styles from "./Card.module.css";\n\nexport const Card = ({ k }: { k: string }) => (\n  <div className={styles[k]}>\n    <b className={styles.row} />\n  </div>\n);\n',
+        );
+        expect(refusal()).toContain("não estática");
+    });
+
+    it("refuses a module whose styles object is passed around whole", () => {
+        twoCopies();
+        write(
+            "src/components/Card.tsx",
+            'import styles from "./Card.module.css";\n\nexport const Card = () => (\n  <div className={styles.row} data-keys={Object.keys(styles).length} />\n);\n',
+        );
+        expect(refusal()).toContain("usado inteiro");
+    });
+
+    it("refuses a class no source file reads", () => {
+        twoCopies();
+        write(
+            "src/components/Card.tsx",
+            'import styles from "./Card.module.css";\n\nexport const Card = () => <div className={styles.title} />;\n',
+        );
+        expect(refusal()).toContain("código morto");
+    });
+
+    it("needs the block in two different files", () => {
+        write(
+            "src/components/Card.module.css",
+            `${ROW}.other {\n    display: flex;\n    align-items: center;\n    gap: 8px;\n}\n`,
+        );
+        write(
+            "src/components/Card.tsx",
+            'import styles from "./Card.module.css";\n\nexport const Card = () => (\n  <div className={styles.row}>\n    <b className={styles.other} />\n    <i className={styles.title} />\n  </div>\n);\n',
+        );
+        expect(plan().groups).toEqual([]);
+    });
+
+    it("refuses when the new name is already taken in the global sheet", () => {
+        twoCopies();
+        write("src/index.css", ".u-row {\n    display: block;\n}\n");
+        const result = plan();
+        expect(result.groups).toEqual([]);
+        expect(result.refusals[0].reason).toContain("já existe na folha global");
+    });
+
+    it("reports a missing global stylesheet instead of creating one", () => {
+        twoCopies();
+        rmSync(join(root, "src/index.css"));
+        const result = plan();
+        expect(result.status).toBe("no-target");
+        expect(result.message).toContain("nenhuma folha global");
+    });
+
+    it("refuses a global stylesheet nobody imports", () => {
+        twoCopies();
+        write("src/main.tsx", "export const main = 1;\n");
+        const result = plan();
+        expect(result.status).toBe("no-target");
+        expect(result.message).toContain("não é importada");
+    });
+
+    it("refuses a CSS Module as the target", () => {
+        twoCopies();
+        write("src/theme.module.css", ".x { color: red; }\n");
+        const result = plan({ target: "src/theme.module.css" });
+        expect(result.status).toBe("no-target");
+        expect(result.message).toContain("é um CSS Module");
+    });
+
+    it("reports a missing TypeScript instead of guessing at the call sites", () => {
+        twoCopies();
+        rmSync(join(root, "node_modules", "typescript"), { recursive: true, force: true });
+        const result = plan();
+        expect(result.status).toBe("no-typescript");
+    });
+});

package/bin/lib/css/fix.e2e.test.mjs

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -97,3 +98,93 @@ describe("tempest fix — the CSS pass", () => {
         expect(code).toBe(1);
     });
 });
+
+const TYPESCRIPT_DIR = dirname(createRequire(import.meta.url).resolve("typescript/package.json"));
+
+/**
+ * A fixture with two modules declaring the same block, each read from its own
+ * component, plus the global sheet the entry imports and the project's own
+ * TypeScript — everything `--extract-css` refuses to work without.
+ */
+function extractableProject() {
+    const rule =
+        ".row {\n    display: flex;\n    align-items: center;\n    gap: 8px;\n}\n.title {\n    font-weight: 600;\n}\n";
+    writeFileSync(
+        join(root, "package.json"),
+        JSON.stringify({ name: "fixture", devDependencies: { typescript: "^5" } }),
+    );
+    write(
+        "tsconfig.json",
+        JSON.stringify({ compilerOptions: { baseUrl: ".", paths: { "@/*": ["./src/*"] } } }),
+    );
+    write("src/index.css", ":root {\n    --brand: #0d6efd;\n}\n");
+    write("src/main.tsx", 'import "./index.css";\n');
+    write("src/components/Card.module.css", rule);
+    write(
+        "src/components/Card.tsx",
+        'import styles from "./Card.module.css";\n\nexport const Card = () => (\n  <div className={styles.row}>\n    <b className={styles.title} />\n  </div>\n);\n',
+    );
+    write("src/components/List.module.css", rule.replace(".row", ".line"));
+    write(
+        "src/components/List.tsx",
+        'import styles from "@/components/List.module.css";\n\nexport const List = () => (\n  <li className={styles.line}>\n    <b className={styles.title} />\n  </li>\n);\n',
+    );
+    mkdirSync(join(root, "node_modules"), { recursive: true });
+    symlinkSync(TYPESCRIPT_DIR, join(root, "node_modules", "typescript"), "dir");
+}
+
+describe("tempest fix --extract-css", () => {
+    it("moves the repeated block into the global sheet and rewrites the JSX", () => {
+        extractableProject();
+        const { out } = fix(["--extract-css"]);
+        expect(out).toContain("css extract");
+        expect(out).toContain("movidas 2 regra(s)");
+        expect(readFileSync(join(root, "src/index.css"), "utf8")).toContain(".u-row {");
+        expect(readFileSync(join(root, "src/components/Card.tsx"), "utf8")).toContain(
+            'className="u-row"',
+        );
+        expect(readFileSync(join(root, "src/components/Card.module.css"), "utf8")).not.toContain(
+            ".row",
+        );
+    });
+
+    it("writes nothing under --dry-run", () => {
+        extractableProject();
+        const before = readFileSync(join(root, "src/components/Card.tsx"), "utf8");
+        const { out } = fix(["--extract-css", "--dry-run"]);
+        expect(out).toContain("moveria 2 regra(s)");
+        expect(readFileSync(join(root, "src/components/Card.tsx"), "utf8")).toBe(before);
+    });
+
+    it("honors --css-prefix without treating its value as a path", () => {
+        extractableProject();
+        fix(["--extract-css", "--css-prefix", "shared-"]);
+        expect(readFileSync(join(root, "src/index.css"), "utf8")).toContain(".shared-row {");
+    });
+
+    it("does nothing extra when the flag is absent", () => {
+        extractableProject();
+        const { out } = fix([]);
+        expect(out).not.toContain("css extract");
+        expect(readFileSync(join(root, "src/index.css"), "utf8")).not.toContain(".u-row");
+    });
+
+    it("rejects --css-target without --extract-css", () => {
+        extractableProject();
+        const { out, code } = fix(["--css-target", "src/index.css"]);
+        expect(out).toContain("só valem com --extract-css");
+        expect(code).toBe(1);
+    });
+
+    it("reports the reason instead of extracting what it cannot prove safe", () => {
+        extractableProject();
+        write(
+            "src/components/Card.module.css",
+            ".row {\n    display: flex;\n    align-items: center;\n    gap: 8px;\n}\n.row:hover {\n    opacity: 0.8;\n}\n.title {\n    font-weight: 600;\n}\n",
+        );
+        const { out } = fix(["--extract-css"]);
+        expect(out).toContain("não extraído");
+        expect(out).toContain("nada a extrair");
+        expect(readFileSync(join(root, "src/index.css"), "utf8")).not.toContain(".u-row");
+    });
+});

package/bin/lib/css/index.mjs

@@ -3,6 +3,16 @@ export { analyzeCss, applyCssFixes } from "./analyze.mjs";
 export { collectStylesheets, customPropertiesInSources, looksMinified } from "./collect.mjs";
 export { countBySeverity, finding, SEVERITY, sortFindings } from "./findings.mjs";
 export { fixCss } from "./fix.mjs";
+export {
+    applyExtraction,
+    classNamesIn,
+    findGlobalSheet,
+    kebab,
+    loneClass,
+    planExtraction,
+    renderRule,
+} from "./extract.mjs";
+export { collectSources, findClassUses, indexClassUses, resolveSpecifier } from "./references.mjs";
 export { maskValue, normalizeSelectors, parseCss, stripComments } from "./parse.mjs";
 export { distance, KNOWN_AT_RULES, KNOWN_PROPERTIES, nearest } from "./properties.mjs";
 export { matchUtility, repetitionFindings } from "./repetition.mjs";

package/bin/lib/css/references.mjs

@@ -0,0 +1,238 @@
+// Where a CSS Module class is used in TypeScript.
+//
+// Extraction cannot be a CSS-only edit: deleting `.row` from `Card.module.css`
+// leaves `styles.row` in `Card.tsx` evaluating to `undefined`, which renders an
+// element with `class="undefined"` and no styling — valid code, silent damage. So
+// the codemod only touches a class it can see **every** use of.
+//
+// "Every use" is decided with the project's own TypeScript compiler rather than a
+// regex: `styles.row` inside a comment, a template literal or a string is not a
+// use, and a regex cannot tell. When anything about a module's usage is not
+// statically decidable — `styles[key]`, `Object.keys(styles)`, the object handed
+// to a child as a prop — the whole module is declared opaque and nothing in it is
+// extracted.
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, extname, join, relative, resolve } from "node:path";
+
+const SOURCE_EXTS = new Set([".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"]);
+const SKIP_DIRS = new Set([
+    "node_modules",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    ".git",
+    ".vite",
+    ".next",
+    ".turbo",
+    ".cache",
+]);
+
+/** Every source file under `root` the codemod may read. */
+export function collectSources({ root, maxFiles = 4000 }) {
+    const out = [];
+    const walk = (dir) => {
+        if (out.length >= maxFiles) return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (SKIP_DIRS.has(entry.name)) continue;
+            if (entry.name.startsWith(".") && entry.isDirectory()) continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) walk(full);
+            else if (entry.isFile() && SOURCE_EXTS.has(extname(entry.name))) out.push(full);
+        }
+    };
+    walk(root);
+    return out.sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Resolve an import specifier to an absolute path, honoring the project alias.
+ *
+ * @param {object} params
+ * @param {string} params.specifier - Raw module specifier.
+ * @param {string} params.fromFile - File the import is written in.
+ * @param {{ prefix: string, baseDir: string } | null} params.alias
+ * @returns {string | null} Absolute path, or `null` when it is a bare package.
+ */
+export function resolveSpecifier({ specifier, fromFile, alias }) {
+    if (specifier.startsWith("./") || specifier.startsWith("../")) {
+        return resolve(dirname(fromFile), specifier);
+    }
+    if (alias && specifier.startsWith(`${alias.prefix}/`)) {
+        return resolve(alias.baseDir, specifier.slice(alias.prefix.length + 1));
+    }
+    return null;
+}
+
+/**
+ * Find every static use of a CSS Module's classes in one source file.
+ *
+ * @param {object} params
+ * @param {string} params.filePath
+ * @param {string} params.text - File contents.
+ * @param {object} params.ts - The project's `typescript` module.
+ * @param {Set<string>} params.moduleFiles - Absolute paths of the CSS Modules of interest.
+ * @param {{ prefix: string, baseDir: string } | null} params.alias
+ * @returns {{
+ *   uses: Array<{ module: string, className: string, start: number, end: number, line: number }>,
+ *   opaque: Array<{ module: string, reason: string, line: number }>,
+ * }}
+ */
+export function findClassUses({ filePath, text, ts, moduleFiles, alias }) {
+    const uses = [];
+    const opaque = [];
+    const source = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true);
+
+    /** Local identifier → absolute CSS Module path, for the modules we care about. */
+    const bindings = new Map();
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement)) continue;
+        const specifier = statement.moduleSpecifier;
+        if (!ts.isStringLiteral(specifier)) continue;
+        const target = resolveSpecifier({ specifier: specifier.text, fromFile: filePath, alias });
+        if (!target || !moduleFiles.has(target)) continue;
+        const clause = statement.importClause;
+        if (clause?.name) bindings.set(clause.name.text, target);
+        // `import * as styles from "./x.module.css"` behaves the same for our purposes.
+        if (clause?.namedBindings && ts.isNamespaceImport(clause.namedBindings)) {
+            bindings.set(clause.namedBindings.name.text, target);
+        }
+    }
+    if (bindings.size === 0) return { uses, opaque };
+
+    const lineOf = (pos) => source.getLineAndCharacterOfPosition(pos).line + 1;
+
+    /**
+     * Range to replace with the new class string.
+     *
+     * `className={styles.row}` widens to the whole `{…}` container so the result
+     * is `className="u-row"` rather than `className={"u-row"}` — the braces are
+     * only there because the value was an expression, and leaving them behind
+     * would make every rewritten attribute read like generated code.
+     */
+    const replacementRange = (access) => {
+        const parent = access.parent;
+        if (
+            parent &&
+            ts.isJsxExpression(parent) &&
+            parent.expression === access &&
+            parent.parent &&
+            ts.isJsxAttribute(parent.parent)
+        ) {
+            return { start: parent.getStart(source), end: parent.getEnd() };
+        }
+        return { start: access.getStart(source), end: access.getEnd() };
+    };
+
+    /**
+     * Record a use, or mark the module opaque when the reference is not a plain
+     * `styles.name` / `styles["name"]` read.
+     */
+    const visit = (node) => {
+        if (ts.isIdentifier(node) && bindings.has(node.text)) {
+            const module = bindings.get(node.text);
+            const parent = node.parent;
+            const isImportName =
+                parent &&
+                (ts.isImportClause(parent) || ts.isNamespaceImport(parent)) &&
+                parent.name === node;
+            if (isImportName) return;
+
+            if (parent && ts.isPropertyAccessExpression(parent) && parent.expression === node) {
+                uses.push({
+                    module,
+                    className: parent.name.text,
+                    ...replacementRange(parent),
+                    line: lineOf(parent.getStart(source)),
+                });
+                return;
+            }
+            if (
+                parent &&
+                ts.isElementAccessExpression(parent) &&
+                parent.expression === node &&
+                parent.argumentExpression &&
+                ts.isStringLiteralLike(parent.argumentExpression)
+            ) {
+                uses.push({
+                    module,
+                    className: parent.argumentExpression.text,
+                    ...replacementRange(parent),
+                    line: lineOf(parent.getStart(source)),
+                });
+                return;
+            }
+            opaque.push({
+                module,
+                reason:
+                    parent && ts.isElementAccessExpression(parent)
+                        ? "acesso dinâmico (`styles[expr]`)"
+                        : "o objeto de estilos é usado inteiro, não por classe",
+                line: lineOf(node.getStart(source)),
+            });
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+
+    ts.forEachChild(source, visit);
+    return { uses, opaque };
+}
+
+/**
+ * Index every static class use across the project.
+ *
+ * @param {object} params
+ * @param {string} params.root
+ * @param {object} params.ts
+ * @param {Iterable<string>} params.modulePaths - Absolute paths of CSS Modules.
+ * @param {{ prefix: string, baseDir: string } | null} params.alias
+ * @returns {{
+ *   byModule: Map<string, Map<string, Array<{ file: string, start: number, end: number, line: number }>>>,
+ *   opaqueModules: Map<string, { file: string, reason: string, line: number }>,
+ *   texts: Map<string, string>,
+ * }}
+ */
+export function indexClassUses({ root, ts, modulePaths, alias }) {
+    const moduleFiles = new Set(modulePaths);
+    const byModule = new Map();
+    const opaqueModules = new Map();
+    const texts = new Map();
+
+    for (const file of collectSources({ root })) {
+        let text;
+        try {
+            text = readFileSync(file, "utf8");
+        } catch {
+            continue;
+        }
+        if (!text.includes(".module.css")) continue;
+        const { uses, opaque } = findClassUses({ filePath: file, text, ts, moduleFiles, alias });
+        if (uses.length === 0 && opaque.length === 0) continue;
+        texts.set(file, text);
+        for (const entry of opaque) {
+            if (!opaqueModules.has(entry.module)) {
+                opaqueModules.set(entry.module, {
+                    file: relative(root, file),
+                    reason: entry.reason,
+                    line: entry.line,
+                });
+            }
+        }
+        for (const use of uses) {
+            const classes = byModule.get(use.module) ?? new Map();
+            const sites = classes.get(use.className) ?? [];
+            sites.push({ file, start: use.start, end: use.end, line: use.line });
+            classes.set(use.className, sites);
+            byModule.set(use.module, classes);
+        }
+    }
+
+    return { byModule, opaqueModules, texts };
+}