feat: add --preserve-paths option to CLI for maintaining folder hierarchy

#377

Author: Ffloriel

docs/CLI.md

@@ -55,6 +55,7 @@ Options:
   -s, --safelist <list...>             list of classes that should not be removed
   -b, --blocklist <list...>            list of selectors that should be removed
   -k, --skippedContentGlobs <list...>  list of glob patterns for folders/files that should not be scanned
+  -p, --preserve-paths                 preserve folder hierarchy in the output
   -h, --help                           display help for command
 ```
 
@@ -90,6 +91,24 @@ By default, the CLI outputs the result in the console. If you wish to return the
 purgecss --css css/app.css --content src/index.html "src/**/*.js" --output build/css/
 ```
 
+### --preserve-paths
+
+By default, the CLI flattens the folder hierarchy and outputs all CSS files to the same directory. If you want to preserve the original folder structure in the output, use the `--preserve-paths` flag.
+
+```sh
+purgecss --css src/**/*.css --content src/index.html --output build/ --preserve-paths
+```
+
+For example, if your CSS files are located at:
+- `src/styles/main.css`
+- `src/components/button.css`
+
+Without `--preserve-paths`, both files would be written to `build/main.css` and `build/button.css`.
+
+With `--preserve-paths`, the files would be written to:
+- `build/src/styles/main.css`
+- `build/src/components/button.css`
+
 ### --safelist
 
 If you wish to prevent PurgeCSS from removing a specific CSS selector, you can add it to the safelist.

packages/purgecss/__tests__/cli/cli-preserve-paths.test.ts

@@ -0,0 +1,106 @@
+import { Command } from "commander";
+import { promises as asyncFs } from "fs";
+import * as path from "path";
+import { parseCommandOptions, run } from "../../src/bin";
+
+const CLI_TEST_FOLDER = path.resolve(__dirname, "../test_examples/cli/nested/");
+
+describe("PurgeCSS CLI preserve paths", () => {
+  const tempFolder = path.resolve(CLI_TEST_FOLDER, ".temp");
+
+  beforeAll(async () => {
+    try {
+      await asyncFs.access(tempFolder);
+      // Clean up temp folder if it exists
+      await asyncFs.rm(tempFolder, { recursive: true });
+    } catch {
+      // Folder doesn't exist, that's fine
+    }
+    await asyncFs.mkdir(tempFolder, { recursive: true });
+  });
+
+  afterAll(async () => {
+    try {
+      await asyncFs.rm(tempFolder, { recursive: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  it("should flatten folder hierarchy by default", async () => {
+    const program = parseCommandOptions(new Command());
+    program.parse([
+      "purgecss",
+      "",
+      "--content",
+      `${CLI_TEST_FOLDER}/src/content.html`,
+      "--css",
+      `${CLI_TEST_FOLDER}/src/root.css`,
+      `${CLI_TEST_FOLDER}/src/level1/middle.css`,
+      `${CLI_TEST_FOLDER}/src/level1/level2/nested.css`,
+      "--output",
+      `${tempFolder}/flattened`,
+    ]);
+    await run(program);
+
+    // All files should be in the same directory (flattened)
+    const rootCss = (
+      await asyncFs.readFile(`${tempFolder}/flattened/root.css`)
+    ).toString();
+    const middleCss = (
+      await asyncFs.readFile(`${tempFolder}/flattened/middle.css`)
+    ).toString();
+    const nestedCss = (
+      await asyncFs.readFile(`${tempFolder}/flattened/nested.css`)
+    ).toString();
+
+    expect(rootCss).toContain(".root-class");
+    expect(rootCss).not.toContain(".unused-root");
+    expect(middleCss).toContain(".middle-class");
+    expect(middleCss).not.toContain(".unused-middle");
+    expect(nestedCss).toContain(".nested-class");
+    expect(nestedCss).not.toContain(".unused-nested");
+  });
+
+  it("should preserve folder hierarchy when --preserve-paths is used", async () => {
+    const program = parseCommandOptions(new Command());
+    program.parse([
+      "purgecss",
+      "",
+      "--content",
+      `${CLI_TEST_FOLDER}/src/content.html`,
+      "--css",
+      `${CLI_TEST_FOLDER}/src/root.css`,
+      `${CLI_TEST_FOLDER}/src/level1/middle.css`,
+      `${CLI_TEST_FOLDER}/src/level1/level2/nested.css`,
+      "--output",
+      `${tempFolder}/preserved`,
+      "--preserve-paths",
+    ]);
+    await run(program);
+
+    // Files should preserve their original path structure
+    const rootCss = (
+      await asyncFs.readFile(
+        `${tempFolder}/preserved/${CLI_TEST_FOLDER}/src/root.css`,
+      )
+    ).toString();
+    const middleCss = (
+      await asyncFs.readFile(
+        `${tempFolder}/preserved/${CLI_TEST_FOLDER}/src/level1/middle.css`,
+      )
+    ).toString();
+    const nestedCss = (
+      await asyncFs.readFile(
+        `${tempFolder}/preserved/${CLI_TEST_FOLDER}/src/level1/level2/nested.css`,
+      )
+    ).toString();
+
+    expect(rootCss).toContain(".root-class");
+    expect(rootCss).not.toContain(".unused-root");
+    expect(middleCss).toContain(".middle-class");
+    expect(middleCss).not.toContain(".unused-middle");
+    expect(nestedCss).toContain(".nested-class");
+    expect(nestedCss).not.toContain(".unused-nested");
+  });
+});

packages/purgecss/__tests__/test_examples/cli/nested/src/content.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Nested Test</title>
+</head>
+<body>
+  <div class="nested-class">Nested</div>
+  <div class="middle-class">Middle</div>
+  <div class="root-class">Root</div>
+</body>
+</html>

packages/purgecss/__tests__/test_examples/cli/nested/src/level1/level2/nested.css

@@ -0,0 +1,7 @@
+.nested-class {
+  color: blue;
+}
+
+.unused-nested {
+  background: red;
+}

packages/purgecss/__tests__/test_examples/cli/nested/src/level1/middle.css

@@ -0,0 +1,7 @@
+.middle-class {
+  color: green;
+}
+
+.unused-middle {
+  background: yellow;
+}

packages/purgecss/__tests__/test_examples/cli/nested/src/root.css

@@ -0,0 +1,7 @@
+.root-class {
+  color: purple;
+}
+
+.unused-root {
+  background: orange;
+}

packages/purgecss/src/bin.ts

@@ -38,6 +38,7 @@ type CommandOptions = {
   safelist?: string[];
   blocklist?: string[];
   skippedContentGlobs: string[];
+  preservePaths?: boolean;
 };
 
 export function parseCommandOptions(program: Command): Command {
@@ -70,12 +71,15 @@ export function parseCommandOptions(program: Command): Command {
     .option(
       "-k, --skippedContentGlobs <list...>",
       "list of glob patterns for folders/files that should not be scanned",
-    );
+    )
+    .option("-p, --preserve-paths", "preserve folder hierarchy in the output");
 
   return program;
 }
 
-export async function getOptions(program: Command): Promise<Options> {
+export async function getOptions(
+  program: Command,
+): Promise<Options & { preservePaths?: boolean }> {
   const {
     config,
     css,
@@ -89,6 +93,7 @@ export async function getOptions(program: Command): Promise<Options> {
     safelist,
     blocklist,
     skippedContentGlobs,
+    preservePaths,
   } = program.opts<CommandOptions>();
   // config file is not specified or the content and css are not,
   // PurgeCSS will not run
@@ -134,12 +139,13 @@ export async function getOptions(program: Command): Promise<Options> {
   if (blocklist) options.blocklist = blocklist;
   if (skippedContentGlobs) options.skippedContentGlobs = skippedContentGlobs;
   if (output) options.output = output;
-  return options;
+  return { ...options, preservePaths };
 }
 
 export async function run(program: Command) {
   const options = await getOptions(program);
-  const purged = await new PurgeCSS().purge(options);
+  const { preservePaths, ...purgeOptions } = options;
+  const purged = await new PurgeCSS().purge(purgeOptions);
 
   // output results in specified directory
   if (options.output) {
@@ -149,8 +155,19 @@ export async function run(program: Command) {
     }
 
     for (const purgedResult of purged) {
-      const fileName = purgedResult?.file?.split("/").pop();
-      await writeCSSToFile(`${options.output}/${fileName}`, purgedResult.css);
+      let outputPath: string;
+      if (preservePaths && purgedResult?.file) {
+        // Preserve the folder hierarchy
+        outputPath = `${options.output}/${purgedResult.file}`;
+      } else {
+        // Default behavior: flatten to just the filename
+        const fileName = purgedResult?.file?.split("/").pop();
+        outputPath = `${options.output}/${fileName}`;
+      }
+      // Ensure the directory exists
+      const dir = outputPath.substring(0, outputPath.lastIndexOf("/"));
+      await fs.promises.mkdir(dir, { recursive: true });
+      await writeCSSToFile(outputPath, purgedResult.css);
     }
   } else {
     console.log(JSON.stringify(purged));