feat: add contributor guide and expand shared/config tests for full coverage

Author: sonofmagic

AGENTS.md

@@ -0,0 +1,26 @@
+# Repository Guidelines
+
+## Environment Setup
+Use Node.js 18 or newer and install dependencies with `pnpm` (enforced by `preinstall`). Run `pnpm install` from the repo root to link workspace packages and set up local post-install patches via `tw-patch`.
+
+## Project Structure & Module Organization
+Source lives in `packages/`, with `@tailwindcss-mangle/core` providing the transformation engine, `shared` for cross-package utils, `config` for preset defaults, `tailwindcss-patch` to shim Tailwind versions, and `unplugin-tailwindcss-mangle` for build-tool integrations. Example applications live under `apps/` for framework-specific smoke tests, while `website/` hosts the Astro-powered docs. Reusable scripts live in `scripts/`, and assets used by docs and samples are under `assets/`.
+
+## Build, Test, and Development Commands
+- `pnpm dev`: start package-level dev modes across the workspace (e.g., watch builds).
+- `pnpm build`: run Turbo builds for every package in `packages/*`.
+- `pnpm build:docs`: build the Astro documentation site in `website/`.
+- `pnpm lint`: apply ESLint fixes across TypeScript sources.
+- `pnpm script:clean`: remove generated artifacts via the monorepo helper.
+
+## Coding Style & Naming Conventions
+The codebase is TypeScript-first with strict ESM modules. Formatting is handled by the shared `@icebreakers/eslint-config` and Prettier defaults (2-space indentation, semicolons omitted). Prefer PascalCase for exported classes (e.g., `ClassGenerator`) and camelCase for functions and variables. Keep filenames lowercase with dashes or dots (`css/index.ts`, `test/utils.ts`).
+
+## Testing Guidelines
+Vitest drives unit tests via `vitest.config.ts`, discovering suites inside each package’s `test/` directory. Name files `*.test.ts` and keep snapshots in `__snapshots__/`. Run the full suite with `pnpm test`; use `pnpm test:dev` for focused watch mode, or filter with `pnpm --filter @tailwindcss-mangle/core test`. Coverage is enabled by default and stored in `coverage/` directories.
+
+## Commit & Pull Request Guidelines
+Follow Conventional Commits enforced by Commitlint (e.g., `feat(core): add selector mangling`). Group related changes per package and mention affected workspace names in the scope. Open pull requests with a concise summary, testing notes, and links to any tracking issues. Include screenshots or CLI output when altering developer tooling or docs. Use Changesets (`pnpm release`) when preparing published releases.
+
+## Release & Automation Notes
+Changesets orchestrate versioning (`pnpm publish-packages`). Turbo caches builds, so clear with `pnpm script:clean` if results look stale. Renovate keeps dependencies current; note any pinning decisions in the PR description.

packages/config/src/types.ts

@@ -1,3 +1,5 @@
+/* c8 ignore start */
+
 import type { FilterPattern } from '@rollup/pluginutils'
 import type { IClassGeneratorOptions } from '@tailwindcss-mangle/shared'
 import type { SourceEntry } from '@tailwindcss/oxide'
@@ -71,3 +73,5 @@ export interface UserConfig {
   patch?: PatchUserConfig
   mangle?: MangleUserConfig
 }
+
+/* c8 ignore end */

packages/config/test/config.test.ts

@@ -1,6 +1,8 @@
 import fs from 'fs-extra'
+import os from 'node:os'
 import path from 'pathe'
-import { initConfig } from '@/config'
+import { defineConfig, getConfig, initConfig } from '@/config'
+import { getDefaultUserConfig } from '@/defaults'
 
 describe('config', () => {
   it('init config', async () => {
@@ -9,4 +11,29 @@ describe('config', () => {
     const dest = path.resolve(cwd, 'tailwindcss-mangle.config.ts')
     expect(await fs.readFile(dest, 'utf8')).toMatchSnapshot()
   })
+
+  it('defineConfig helper returns provided config', () => {
+    const config = defineConfig({
+      patch: {
+        output: {
+          filename: 'custom.json',
+        },
+      },
+    })
+
+    expect(config).toEqual({
+      patch: {
+        output: {
+          filename: 'custom.json',
+        },
+      },
+    })
+  })
+
+  it('getConfig falls back to defaults when config file is absent', async () => {
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'config-test-'))
+    const { config } = await getConfig(tempDir)
+    expect(config).toEqual(getDefaultUserConfig())
+    await fs.remove(tempDir)
+  })
 })

packages/config/test/defaults.test.ts

@@ -1,6 +1,6 @@
 import { createFilter } from '@rollup/pluginutils'
 import { omit } from 'lodash-es'
-import { getDefaultPatchConfig, getDefaultUserConfig } from '@/defaults'
+import { getDefaultMangleUserConfig, getDefaultPatchConfig, getDefaultUserConfig } from '@/defaults'
 
 function omitCwdPath(o: any) {
   return omit(o, ['tailwindcss.cwd', 'patch.tailwindcss.cwd'])
@@ -14,6 +14,25 @@ describe('defaults', () => {
   it('getDefaultUserConfig', () => {
     expect(omitCwdPath(getDefaultUserConfig())).toMatchSnapshot()
   })
+
+  it('getDefaultMangleUserConfig reflects NODE_ENV', () => {
+    const originalEnv = process.env.NODE_ENV
+
+    vi.stubEnv('NODE_ENV', 'development')
+    expect(getDefaultMangleUserConfig().disabled).toBe(true)
+    vi.unstubAllEnvs()
+
+    vi.stubEnv('NODE_ENV', 'production')
+    expect(getDefaultMangleUserConfig().disabled).toBe(false)
+    vi.unstubAllEnvs()
+
+    if (originalEnv !== undefined) {
+      process.env.NODE_ENV = originalEnv
+    }
+    else {
+      delete process.env.NODE_ENV
+    }
+  })
 })
 
 describe('createFilter', () => {

packages/config/test/entrypoint.test.ts

@@ -0,0 +1,9 @@
+import * as entry from '@/index'
+
+describe('entrypoint exports', () => {
+  it('exposes defineConfig and helpers', () => {
+    expect(typeof entry.defineConfig).toBe('function')
+    expect(typeof entry.getConfig).toBe('function')
+    expect(typeof entry.getDefaultUserConfig).toBe('function')
+  })
+})

packages/config/test/getConfig-delegation.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it, vi } from 'vitest'
+
+describe('getConfig delegation', () => {
+  it('passes cwd and defaults to c12.loadConfig', async () => {
+    const loadConfig = vi.fn().mockResolvedValue({ config: {} })
+    const getDefaultUserConfig = vi.fn().mockReturnValue({ patch: {}, mangle: {} })
+    const constants = await vi.importActual<typeof import('../src/constants')>('../src/constants')
+
+    vi.doMock('c12', () => ({
+      loadConfig,
+      createDefineConfig: () => (value: unknown) => value,
+    }))
+    vi.doMock('../src/defaults', () => ({
+      getDefaultUserConfig,
+    }))
+
+    vi.resetModules()
+    const { getConfig } = await import('../src/config')
+    await getConfig('custom-cwd')
+
+    expect(loadConfig).toHaveBeenCalledWith(expect.objectContaining({
+      name: constants.CONFIG_NAME,
+      cwd: 'custom-cwd',
+    }))
+    expect(getDefaultUserConfig).toHaveBeenCalledTimes(1)
+
+    vi.resetModules()
+    vi.doUnmock('c12')
+    vi.doUnmock('../src/defaults')
+  })
+})

packages/config/vitest.config.ts

@@ -11,5 +11,14 @@ export default defineProject({
     ],
     globals: true,
     testTimeout: 60_000,
+    coverage: {
+      exclude: [
+        'src/types.ts',
+        'dist/**',
+        'tsup.config.ts',
+        'vitest.config.ts',
+        'test/fixtures/**',
+      ],
+    },
   },
 })

packages/shared/src/types.ts

@@ -1,3 +1,5 @@
+/* c8 ignore start */
+
 export interface IClassGeneratorContextItem {
   name: string
   usedBy: Set<string>
@@ -18,3 +20,5 @@ export interface IClassGenerator {
   newClassSize: number
   context: Record<string, any>
 }
+
+/* c8 ignore end */

packages/shared/test/classGenerator.behavior.test.ts

@@ -0,0 +1,67 @@
+import { ClassGenerator } from '@/classGenerator'
+
+describe('ClassGenerator behaviour', () => {
+  it('respects include/exclude filters and ignore rules', () => {
+    const generator = new ClassGenerator({
+      include: [/src\/.+\.ts$/u],
+      exclude: [/src\/skip/u],
+      ignoreClass: [/^skip-me$/u],
+      classPrefix: 'pref-',
+    })
+
+    expect(generator.includeFilePath('src/file.ts')).toBe(true)
+    expect(generator.includeFilePath('pkg/file.ts')).toBe(false)
+    expect(generator.excludeFilePath('src/skip/component.ts')).toBe(true)
+    expect(generator.isFileIncluded('src/skip/component.ts')).toBe(false)
+    expect(generator.isFileIncluded('src/ok/component.ts')).toBe(true)
+
+    expect(generator.ignoreClassName('skip-me')).toBe(true)
+    expect(generator.ignoreClassName('keep-me')).toBe(false)
+
+    const defaultGenerator = new ClassGenerator()
+    expect(defaultGenerator.includeFilePath('any/path.vue')).toBe(true)
+    expect(defaultGenerator.excludeFilePath('any/path.vue')).toBe(false)
+  })
+
+  it('transforms mapped class names using the escape-stripped key', () => {
+    const generator = new ClassGenerator()
+    generator.newClassMap['text[50]'] = {
+      name: 'pref-a',
+      usedBy: new Set(),
+    }
+
+    expect(generator.transformCssClass('text\\[50\\]')).toBe('pref-a')
+    expect(generator.transformCssClass('text-unknown')).toBe('text-unknown')
+  })
+
+  it('reuses generated classes and supports custom generators', () => {
+    const generator = new ClassGenerator({
+      customGenerate: (original, _opts, ctx) => {
+        ctx[original] = (ctx[original] ?? 0) + 1
+        return `${original}-${ctx[original]}`
+      },
+    })
+
+    const first = generator.generateClassName('foo')
+    expect(first.name).toBe('foo-1')
+    expect(generator.context.foo).toBe(1)
+
+    const again = generator.generateClassName('foo')
+    expect(again).toBe(first)
+  })
+
+  it('falls back to default generator and skips reserved results', () => {
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined)
+    const generator = new ClassGenerator({
+      reserveClassName: [/^tw-a$/u],
+      log: true,
+    })
+
+    const result = generator.generateClassName('foo')
+    expect(result.name).toBe('tw-b')
+    expect(generator.newClassSize).toBe(2)
+    expect(logSpy).toHaveBeenCalledWith('The class name has been reserved. tw-a')
+
+    logSpy.mockRestore()
+  })
+})

packages/shared/test/index.test.ts

@@ -0,0 +1,9 @@
+import * as shared from '@/index'
+
+describe('package entrypoint', () => {
+  it('exposes key helpers', () => {
+    expect(typeof shared.ClassGenerator).toBe('function')
+    expect(typeof shared.defu).toBe('function')
+    expect(typeof shared.defaultMangleClassFilter).toBe('function')
+  })
+})