feat(extractor): scanObjectStrings option for lookup-table class strings (#143)

## Summary

Fixes the **« obfuscator breaks design »** class of bugs where Tailwind
class strings stored in JS object lookup tables (status-color tables,
badge variants by level, etc.) produce **inconsistent obfuscation across
siblings** of the same table — diagnosed in the 2026-04-30 portfolio
session.

## The bug

The JSX extractor walks `className=` JSX attributes AND recognized
utility calls (`cn / clsx / cva / tv / twMerge / classnames`). It does
**not** walk arbitrary string literals stored in object property values:

```ts
const COLORS = {
  1: { badge: 'border-slate-400/30 bg-slate-400/10 text-slate-600' },
  2: { badge: 'border-amber-500/30 bg-amber-500/10 text-amber-700' },
  3: { badge: 'border-sky-500/30 bg-sky-500/10 text-sky-700' },
};
```

Only siblings whose tokens **also appear in a `className=`** somewhere
else (e.g. `bg-amber-500/10` if `bg-amber-500/5` exists in some
`className=`) get into the mapping. The others stay un-mapped. Then the
CSS extractor walks the BUILT CSS and renames matching selectors →
**amber gets `.tw-XXXX` but sky stays `.bg-sky-500`**. The runtime
className still says `bg-sky-500/10` (un-rewritten in JS chunks since
the mapping doesn't have it) — fine, sky still works. But for the levels
that WERE in the mapping, the JS chunk now has `'tw-XXXX tw-XXXX'` and
the CSS has the matching rewritten selectors. **The inconsistency is
what produces the visible breakage when this pattern shows up alongside
other classes.**

## The fix

New opt-in option `scanObjectStrings: boolean` (default `false`) that
runs an additional pass over JS-family files. Conservative heuristic:

- String must contain **≥2 whitespace-separated tokens**
- **Every** token must validate as a Tailwind class via
`isTailwindClass`

Single-word strings (`'flex'`, `'red'`, `'info'`) are **NEVER**
auto-extracted — they conflict with config values, JS identifiers, i18n
keys.

## Verified end-to-end

Tested on the maintainer's portfolio:

```
Before: 1326 classes in mapping, 'bg-sky-500/10' NOT in mapping
After:  1379 classes in mapping (+53), 'bg-sky-500/10' ✅, 'border-sky-500/30' ✅, 'text-sky-700' ✅, 'dark:text-sky-400' ✅
```

The `Parcours` page (which renders the ConfidenceBadge with these
tables) loads cleanly with the option on.

## Test plan

- [x] 8 new test cases in `tests/scan-object-strings.test.ts` (positive
cases, prose rejection, single-token rejection, mixed-token rejection,
template-literal handling, deduplication)
- [x] `pnpm --filter tailwindcss-obfuscator test` → 479/479 (was
471/471)
- [x] `pnpm --filter tailwindcss-obfuscator typecheck` → 0 errors
- [x] `node scripts/verify-obfuscation.mjs` → 25/25 apps still ok with
option default-off (no behavior change for existing users)
- [x] End-to-end portfolio build with `scanObjectStrings: true` → 6 of 7
previously-missing classes now in mapping; visual rendering correct

## Acknowledged limitation

Single-token entries (`'bg-slate-400'` as a `bar:` field) still won't be
auto-obfuscated even with the option on — the heuristic intentionally
requires 2+ tokens to keep false-positive rate near zero. Users hit by
this can wrap in `cn(…)` or add to `safelist`.

Author: josedacosta

.changeset/feat-scan-object-strings.md

@@ -0,0 +1,7 @@
+---
+"tailwindcss-obfuscator": minor
+---
+
+New extractor option `scanObjectStrings` (default `false`) — opt-in pass that walks Tailwind class strings stored in object property values, factory args, and lookup tables that the standard JSX / `cn()` / `cva()` / `tv()` walkers don't reach. Heuristic-gated to avoid false positives: a string is picked up only if it contains ≥2 whitespace-separated tokens AND every token validates as a Tailwind class. Single-word strings (`"flex"`, `"red"`, `"info"`) are NEVER auto-extracted — wrap them in `cn(…)` or add to `safelist`.
+
+Fixes the « broken design with obfuscator » class of bugs where status-color tables, badge variants by level, etc. produced inconsistent obfuscation across siblings of the same lookup table.

packages/tailwindcss-obfuscator/src/core/context.ts

@@ -168,6 +168,7 @@ const DEFAULT_OPTIONS: ResolvedObfuscatorOptions = {
     strategy: "merge",
   },
   trackPositions: false,
+  scanObjectStrings: false,
 };
 
 /**
@@ -223,6 +224,7 @@ export function resolveOptions(options: ObfuscatorOptions = {}): ResolvedObfusca
       strategy: options.cache?.strategy ?? DEFAULT_OPTIONS.cache.strategy,
     },
     trackPositions: options.trackPositions ?? DEFAULT_OPTIONS.trackPositions,
+    scanObjectStrings: options.scanObjectStrings ?? DEFAULT_OPTIONS.scanObjectStrings,
   };
 }
 

packages/tailwindcss-obfuscator/src/core/types.ts

@@ -297,6 +297,25 @@ export interface ObfuscatorOptions {
    * @default false
    */
   trackPositions?: boolean;
+
+  /**
+   * Also extract Tailwind classes from string literals stored in object
+   * properties / factory args / lookup tables that the standard JSX /
+   * `cn()` / `cva()` / `tv()` walkers don't reach.
+   *
+   * Heuristic-gated to avoid false positives : a string is picked up only
+   * if it contains ≥2 whitespace-separated tokens AND every token validates
+   * as a Tailwind class. Single-word utility strings (`"flex"`, `"red"`)
+   * are NEVER auto-extracted — wrap them in `cn(…)` or add them to
+   * `safelist` instead.
+   *
+   * Default `false` to preserve historical behavior, but recommended `true`
+   * for any project that stores className strings in lookup tables (e.g.
+   * status-color tables, badge variants by level).
+   *
+   * @default false
+   */
+  scanObjectStrings?: boolean;
 }
 
 /**
@@ -346,6 +365,7 @@ export interface ResolvedObfuscatorOptions {
   mapping: ResolvedMappingOutputOptions;
   cache: ResolvedCacheOptions;
   trackPositions: boolean;
+  scanObjectStrings: boolean;
 }
 
 /**

packages/tailwindcss-obfuscator/src/extractors/index.ts

@@ -8,7 +8,7 @@ import fg from "fast-glob";
 import type { ExtractionResult, ExtractorFn, PluginContext, Logger } from "../core/types.js";
 import { addClasses } from "../core/context.js";
 import { extractFromHtml } from "./html.js";
-import { extractAllFromJsx } from "./jsx.js";
+import { extractAllFromJsx, extractClassListLikeStrings } from "./jsx.js";
 import { extractFromCss, extractFromTailwindV4Css, detectTailwindVersion } from "./css.js";
 import { deduplicateClasses } from "./base.js";
 
@@ -18,6 +18,7 @@ export {
   extractFromJsxWithCva,
   extractAllFromJsx,
   extractFromTailwindVariants,
+  extractClassListLikeStrings,
 } from "./jsx.js";
 export { extractFromCss, extractFromTailwindV4Css, detectTailwindVersion } from "./css.js";
 export * from "./base.js";
@@ -60,8 +61,16 @@ export function getExtractor(filePath: string): ExtractorFn | null {
 
 /**
  * Extract classes from a single file
+ *
+ * `opts.scanObjectStrings` opts into the lookup-table-string extractor
+ * (`extractClassListLikeStrings`), which catches Tailwind class strings
+ * stored in object-property values that the standard JSX walker doesn't
+ * reach. Default off — see `scanObjectStrings` in `ObfuscatorOptions`.
  */
-export async function extractFromFile(filePath: string): Promise<ExtractionResult> {
+export async function extractFromFile(
+  filePath: string,
+  opts: { scanObjectStrings?: boolean } = {}
+): Promise<ExtractionResult> {
   const result: ExtractionResult = {
     file: filePath,
     classes: [],
@@ -75,6 +84,18 @@ export async function extractFromFile(filePath: string): Promise<ExtractionResul
     if (extractor) {
       const classes = await extractor(content, filePath);
       result.classes = classes;
+
+      // Optional second pass: scan ALL string literals for class-list-like
+      // contents (handles class strings stored in object property values).
+      // Only relevant for JS-family files where the primary extractor is
+      // `extractAllFromJsx` — for HTML / CSS files, classes inside string
+      // literals are already handled by their dedicated extractors.
+      if (opts.scanObjectStrings && JS_FAMILY_EXTENSIONS.has(getExtension(filePath))) {
+        const extra = extractClassListLikeStrings(content, filePath);
+        if (extra.length > 0) {
+          result.classes = [...new Set([...result.classes, ...extra])];
+        }
+      }
     } else {
       result.errors = [`No extractor available for file type: ${filePath}`];
     }
@@ -87,6 +108,8 @@ export async function extractFromFile(filePath: string): Promise<ExtractionResul
   return result;
 }
 
+const JS_FAMILY_EXTENSIONS = new Set(["js", "jsx", "ts", "tsx", "vue", "svelte", "astro"]);
+
 /**
  * Extract classes from multiple files using glob patterns
  */
@@ -113,6 +136,54 @@ export async function extractFromGlob(
   return results;
 }
 
+/**
+ * Test a path against a list of patterns. RegExp entries use `.test()`;
+ * string entries fall back to substring matching on the absolute path so that
+ * users can write `"jose"` or `"node_modules"` without thinking in globs.
+ */
+function pathMatchesAny(filePath: string, patterns: ReadonlyArray<string | RegExp>): boolean {
+  for (const pattern of patterns) {
+    if (pattern instanceof RegExp) {
+      if (pattern.test(filePath)) return true;
+    } else if (filePath.includes(pattern)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Apply `sources.include` (whitelist) and `sources.exclude` (blacklist) to a
+ * file list. Earlier versions accepted these options in the config schema but
+ * never enforced them — leading to bug reports where archived HTML/CSS under
+ * gitignored personal directories ended up in the class mapping anyway and
+ * corrupted SSR chunks (e.g. `require('util')` rewritten because a `class="util"`
+ * appeared in some `*.html` snippet outside the source tree).
+ *
+ * Patterns are matched against the **relative** path (relative to `basePath`),
+ * never the absolute path — otherwise an exclude like `/[\\/]jose[\\/]/` would
+ * silently match every file under `/Users/jose/...` on the maintainer's machine.
+ */
+function applySourcesFilter(
+  files: string[],
+  sources: PluginContext["options"]["sources"] | undefined,
+  basePath: string
+): string[] {
+  if (!sources) return files;
+  const include = sources.include;
+  const exclude = sources.exclude;
+  if ((!include || include.length === 0) && (!exclude || exclude.length === 0)) return files;
+
+  return files.filter((file) => {
+    // Always test against POSIX-style relative paths so users can write
+    // `'jose/'` regardless of the host OS.
+    const relative = path.relative(basePath, file).split(path.sep).join("/");
+    if (include && include.length > 0 && !pathMatchesAny(relative, include)) return false;
+    if (exclude && exclude.length > 0 && pathMatchesAny(relative, exclude)) return false;
+    return true;
+  });
+}
+
 /**
  * Extract all classes from files and add to context
  */
@@ -128,9 +199,17 @@ export async function extractClasses(
   logger.info("Extracting Tailwind classes...");
 
   // Extract from content files (HTML, JSX, TSX, etc.)
-  const contentResults = await extractFromGlob(ctx.options.content, {
+  const matchedFiles = await fg(ctx.options.content, {
     cwd: basePath,
+    ignore: ["**/node_modules/**", "**/dist/**", "**/.next/**", "**/build/**", "**/.git/**"],
+    absolute: true,
   });
+  const filteredFiles = applySourcesFilter(matchedFiles, ctx.options.sources, basePath);
+
+  const scanObjectStrings = ctx.options.scanObjectStrings === true;
+  const contentResults = await Promise.all(
+    filteredFiles.map((file) => extractFromFile(file, { scanObjectStrings }))
+  );
 
   for (const result of contentResults) {
     if (result.errors && result.errors.length > 0) {
@@ -166,8 +245,9 @@ export async function extractFromCssFiles(
     ignore: ["**/node_modules/**", "**/dist/**", "**/.next/**", "**/build/**"],
     absolute: true,
   });
+  const filteredCssFiles = applySourcesFilter(cssFiles, ctx.options.sources, basePath);
 
-  for (const file of cssFiles) {
+  for (const file of filteredCssFiles) {
     try {
       const content = await fs.promises.readFile(file, "utf-8");
 

packages/tailwindcss-obfuscator/src/extractors/jsx.ts

@@ -485,3 +485,52 @@ export function extractAllFromJsx(content: string, filePath: string): string[] {
 
   return deduplicateClasses(classes);
 }
+
+/**
+ * Extract from string literals that LOOK like Tailwind class lists.
+ *
+ * Required for the very common pattern of storing class strings inside object
+ * literals or factory functions that the JSX/CVA/TV walkers don't reach :
+ *
+ *     const COLORS = {
+ *       1: { badge: 'border-slate-400/30 bg-slate-400/10 text-slate-600',
+ *            bar:   'bg-slate-400' },
+ *       …
+ *     };
+ *
+ * Without this pass, only siblings of these strings that ALSO appear inside
+ * a `className=` attribute somewhere else in the codebase get extracted ;
+ * the rest stay un-mapped, the CSS for them stays as-is, and at runtime the
+ * className value points at non-existent rewritten selectors → broken design.
+ *
+ * Heuristic to avoid false positives on prose / config strings :
+ *   - String must contain ≥2 whitespace-separated tokens
+ *   - EVERY token must validate as a Tailwind class via `isTailwindClass`
+ *
+ * Single-word strings (`"red"`, `"info"`, `"flex"`) are NEVER picked up here ;
+ * those would be ambiguous with JS identifiers / config values. If the user
+ * wants single-word utility strings extracted, they should wrap them in a
+ * recognised utility (`cn('flex')`) or add them to `safelist`.
+ */
+export function extractClassListLikeStrings(content: string, _filePath: string): string[] {
+  const classes: string[] = [];
+  let match: RegExpExecArray | null;
+
+  STRING_LITERAL_PATTERN.lastIndex = 0;
+  while ((match = STRING_LITERAL_PATTERN.exec(content)) !== null) {
+    const raw = match[1];
+    if (!raw || raw.length < 3) continue;
+    // Strip ${…} so template-literal expressions don't poison the per-token
+    // validation.
+    const cleaned = raw.replace(/\$\{[^}]*\}/g, " ");
+    const tokens = cleaned.split(/\s+/).filter(Boolean);
+    if (tokens.length < 2) continue;
+    // Every token must look like a Tailwind class — otherwise this is prose,
+    // a config map, an i18n key, or some other non-class string.
+    if (!tokens.every((t) => isTailwindClass(t))) continue;
+    classes.push(...tokens);
+  }
+  STRING_LITERAL_PATTERN.lastIndex = 0;
+
+  return deduplicateClasses(classes);
+}

packages/tailwindcss-obfuscator/src/internals.ts

@@ -74,6 +74,7 @@ export {
   extractFromJsxWithCva,
   extractFromTailwindVariants,
   extractAllFromJsx,
+  extractClassListLikeStrings,
   extractFromCss,
   extractFromTailwindV4Css,
   extractFromFile,

packages/tailwindcss-obfuscator/tests/scan-object-strings.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest";
+import { extractClassListLikeStrings } from "../src/extractors/jsx.js";
+
+describe("extractClassListLikeStrings — lookup-table extraction", () => {
+  it("picks up class strings stored in object property values", () => {
+    const src = `
+      export const CONFIDENCE_LEVEL_COLORS = {
+        1: { badge: 'border-slate-400/30 bg-slate-400/10 text-slate-600 dark:text-slate-400', bar: 'bg-slate-400' },
+        2: { badge: 'border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-400', bar: 'bg-amber-500' },
+        3: { badge: 'border-sky-500/30 bg-sky-500/10 text-sky-700 dark:text-sky-400',         bar: 'bg-sky-500' },
+      };
+    `;
+    const classes = extractClassListLikeStrings(src, "ConfidenceBadge.tsx");
+    expect(classes).toContain("border-slate-400/30");
+    expect(classes).toContain("bg-slate-400/10");
+    expect(classes).toContain("text-slate-600");
+    expect(classes).toContain("border-sky-500/30");
+    expect(classes).toContain("bg-sky-500/10");
+    expect(classes).toContain("text-sky-700");
+    expect(classes).toContain("dark:text-sky-400");
+    // Single-token strings (`'bg-slate-400'`) are intentionally NOT included
+    // in this pass — they require the user to wrap them or safelist.
+    expect(classes).not.toContain("bg-slate-400");
+  });
+
+  it("picks up template-literal class strings in object positions", () => {
+    const src = "const x = { foo: `flex items-center gap-2` };";
+    const classes = extractClassListLikeStrings(src, "x.ts");
+    expect(classes).toEqual(expect.arrayContaining(["flex", "items-center", "gap-2"]));
+  });
+
+  it("does NOT extract from prose strings (unrecognized tokens)", () => {
+    const src = `
+      const labels = {
+        en: "Hello world",
+        fr: "Bonjour le monde",
+        ja: "こんにちは 世界",
+      };
+    `;
+    const classes = extractClassListLikeStrings(src, "labels.ts");
+    expect(classes).toHaveLength(0);
+  });
+
+  it("does NOT extract single-word strings even when they look like utilities", () => {
+    const src = `
+      const role = "info";
+      const color = "red";
+      const layout = "flex";
+    `;
+    const classes = extractClassListLikeStrings(src, "config.ts");
+    expect(classes).toHaveLength(0);
+  });
+
+  it("does NOT extract config strings where some tokens are non-Tailwind", () => {
+    // Mixed — only "rounded" is a class, the rest are prose. Should be skipped.
+    const src = `
+      const help = "Click rounded the button to continue";
+    `;
+    const classes = extractClassListLikeStrings(src, "x.ts");
+    expect(classes).toHaveLength(0);
+  });
+
+  it("strips template-literal expressions before per-token validation", () => {
+    const src = "const x = `flex items-center ${dynamic} gap-2`;";
+    const classes = extractClassListLikeStrings(src, "x.ts");
+    expect(classes).toEqual(expect.arrayContaining(["flex", "items-center", "gap-2"]));
+  });
+
+  it("deduplicates repeated tokens across multiple strings", () => {
+    const src = `
+      const a = "flex items-center";
+      const b = "flex items-center justify-between";
+    `;
+    const classes = extractClassListLikeStrings(src, "x.ts");
+    const flexCount = classes.filter((c) => c === "flex").length;
+    expect(flexCount).toBe(1);
+    expect(classes).toContain("justify-between");
+  });
+
+  it("ignores strings shorter than 3 characters", () => {
+    const src = `const x = { a: "ab", b: "cd" };`;
+    const classes = extractClassListLikeStrings(src, "x.ts");
+    expect(classes).toHaveLength(0);
+  });
+});