feat: Class name collision detection.

- Throw an error if a generated class name collides with app CSS.
- Add convenience config option to omit class names from the optimizer.
- Add short class name to test fixture as a smoke test.

Author: Tim Lindvall

packages/@css-blocks/ember-app/src/broccoli-plugin.ts

@@ -12,7 +12,7 @@ import { OptiCSSOptions, Optimizer, parseSelector, postcss } from "opticss";
 import * as path from "path";
 
 import { RuntimeDataGenerator } from "./RuntimeDataGenerator";
-import { cssBlocksPostprocessFilename, cssBlocksPreprocessFilename } from "./utils/filepaths";
+import { cssBlocksPostprocessFilename, cssBlocksPreprocessFilename, optimizedStylesPostprocessFilepath, optimizedStylesPreprocessFilepath } from "./utils/filepaths";
 import { AddonEnvironment } from "./utils/interfaces";
 
 const debug = debugGenerator("css-blocks:ember-app");
@@ -47,7 +47,7 @@ export class CSSBlocksApplicationPlugin extends Filter {
     let factory = new BlockFactory(config, postcss);
     let analyzer = new EmberAnalyzer(factory, this.cssBlocksOptions.analysisOpts);
     let optimizerOptions = this.cssBlocksOptions.optimization;
-    this.reserveClassnames(optimizerOptions);
+    this.reserveClassnames(optimizerOptions, this.cssBlocksOptions.appClasses);
     let optimizer = new Optimizer(optimizerOptions, analyzer.optimizationOptions);
     let blocksUsed = new Set<Block>();
     for (let entry of entries) {
@@ -98,6 +98,22 @@ export class CSSBlocksApplicationPlugin extends Filter {
     this.output.writeFileSync(optLogFileName, optimizationResult.actions.logStrings().join("\n"), "utf8");
     debug("Wrote css, sourcemap, and optimization log.");
 
+    // Also, write out a list of generated classes that we can use later
+    // for conflict detection during postprocess.
+    const classesUsed: Set<string> = new Set();
+    optimizationResult.styleMapping.optimizedAttributes.forEach(attr => {
+      classesUsed.add(attr.value.valueOf());
+    });
+    this.output.writeFileSync(
+      optimizedStylesPreprocessFilepath,
+      JSON.stringify(
+        new Array(...classesUsed.values()),
+        undefined,
+        " ",
+      ),
+    );
+    debug("Wrote list of generated classes.");
+
     let dataGenerator = new RuntimeDataGenerator([...blocksUsed], optimizationResult.styleMapping, analyzer, config, reservedClassnames);
     let data = dataGenerator.generate();
     let serializedData = JSON.stringify(data, undefined, "  ");
@@ -116,7 +132,7 @@ export class CSSBlocksApplicationPlugin extends Filter {
    * application to the the list of identifiers that should be omitted by the
    * classname generator.
    */
-  reserveClassnames(optimizerOptions: Partial<OptiCSSOptions>): void {
+  reserveClassnames(optimizerOptions: Partial<OptiCSSOptions>, appClassesAlias: string[]): void {
     let rewriteIdents = optimizerOptions.rewriteIdents;
     let rewriteIdentsFlag: boolean;
     let omitIdents: Array<string>;
@@ -131,7 +147,8 @@ export class CSSBlocksApplicationPlugin extends Filter {
       omitIdents = rewriteIdents.omitIdents && rewriteIdents.omitIdents.class || [];
     }
 
-    // TODO: scan css files for other classes in use and add them to `omitIdents`.
+    // Add in any additional classes that were passed in using the appClasses alias.
+    omitIdents.push(...appClassesAlias);
 
     optimizerOptions.rewriteIdents = {
       id: false,
@@ -165,17 +182,28 @@ export class CSSBlocksStylesPreprocessorPlugin extends Plugin {
     this.cssBlocksOptions = cssBlocksOptions;
   }
   async build() {
-    // Are there any changes to make? If not, bail out early.
     let stylesheetPath = cssBlocksPreprocessFilename(this.cssBlocksOptions);
-    let entries = this.input.entries(".", {globs: [stylesheetPath]});
+
+    // Are there any changes to make? If not, bail out early.
+    let entries = this.input.entries(
+      ".",
+      {
+        globs: [
+          stylesheetPath,
+          "app/styles/css-blocks-style-mapping.css",
+        ],
+      },
+    );
     let currentFSTree = FSTree.fromEntries(entries);
     let patch = this.previousSourceTree.calculatePatch(currentFSTree);
     if (patch.length === 0) {
       return;
     } else {
       this.previousSourceTree = currentFSTree;
     }
-    // Read in the CSS Blocks compiled content that was created previously.
+
+    // Read in the CSS Blocks compiled content that was created previously
+    // from the template tree.
     let blocksFileContents: string;
     if (this.input.existsSync(stylesheetPath)) {
       blocksFileContents = this.input.readFileSync(stylesheetPath, { encoding: "utf8" });
@@ -185,10 +213,16 @@ export class CSSBlocksStylesPreprocessorPlugin extends Plugin {
       blocksFileContents = "";
     }
 
-    // Now, write out compiled content to its expected location.
+    // Now, write out compiled content to its expected location in the CSS tree.
     // By default, this is app/styles/css-blocks.css.
     this.output.mkdirSync(path.dirname(stylesheetPath), { recursive: true });
     this.output.writeFileSync(stylesheetPath, blocksFileContents);
+
+    // Also, forward along the JSON list of optimizer-generated class names.
+    if (this.input.existsSync(optimizedStylesPreprocessFilepath)) {
+      const dataContent = this.input.readFileSync(optimizedStylesPreprocessFilepath).toString("utf8");
+      this.output.writeFileSync(optimizedStylesPreprocessFilepath, dataContent);
+    }
   }
 }
 
@@ -201,10 +235,12 @@ export class CSSBlocksStylesPreprocessorPlugin extends Plugin {
  */
 export class CSSBlocksStylesPostprocessorPlugin extends Filter {
   env: AddonEnvironment;
+  previousSourceTree: FSTree;
 
   constructor(env: AddonEnvironment, inputNodes: InputNode[]) {
     super(mergeTrees(inputNodes), {});
     this.env = env;
+    this.previousSourceTree = new FSTree();
   }
 
   processString(contents: string, _relativePath: string): string {
@@ -214,28 +250,57 @@ export class CSSBlocksStylesPostprocessorPlugin extends Filter {
   async build() {
     await super.build();
 
-    // Look up all the application style content that's already present.
     const blocksCssFile = cssBlocksPostprocessFilename(this.env.config);
-    const appStyles: string[] = [];
+    let optimizerClasses: string[] = [];
+    const appCss: string[] = [];
     const foundFiles: string[] = [];
+    const foundClasses: Set<string> = new Set<string>();
+    const errorLog: string[] = [];
 
+    // Are there any changes to make? If not, bail out early.
+    let entries = this.input.entries(
+      ".",
+      {
+        globs: [
+          "**/*.css",
+          optimizedStylesPostprocessFilepath,
+        ],
+      },
+    );
+    let currentFSTree = FSTree.fromEntries(entries);
+    let patch = this.previousSourceTree.calculatePatch(currentFSTree);
+    if (patch.length === 0) {
+      return;
+    } else {
+      this.previousSourceTree = currentFSTree;
+    }
+
+    // Read in the list of classes generated by the optimizer.
+    if (this.input.existsSync(optimizedStylesPostprocessFilepath)) {
+      optimizerClasses = JSON.parse(this.input.readFileSync(optimizedStylesPostprocessFilepath).toString("utf8"));
+    } else {
+      // Welp, nothing to do if we don't have optimizer data.
+      debug("Skipping conflict analysis because there is no optimizer data.");
+      return;
+    }
+
+    // Look up all the application style content that's already present.
     const walkEntries = this.input.entries(undefined, {
       globs: ["**/*.css"],
     });
     walkEntries.forEach(entry => {
       if (entry.relativePath === blocksCssFile) return;
       try {
-        appStyles.push(this.input.readFileSync(entry.relativePath).toString("utf8"));
+        appCss.push(this.input.readFileSync(entry.relativePath).toString("utf8"));
         foundFiles.push(entry.relativePath);
       } catch (e) {
         // broccoli-concat will complain about this later. let's move on.
       }
     });
+    debug("Done looking up app CSS.");
 
-    // Now, read in each of these sources and check there are no class name conflicts.
-    const foundClasses: Set<string> = new Set<string>();
-    const errorLog: string[] = [];
-    appStyles.forEach(content => {
+    // Now, read in each of these sources and note all classes found.
+    appCss.forEach(content => {
       try {
         const parsed = postcss.parse(content);
         parsed.walkRules(rule => {
@@ -249,19 +314,38 @@ export class CSSBlocksStylesPostprocessorPlugin extends Filter {
           });
         });
       } catch (e) {
-        // TODO: Can't parse CSS? Gracefully fail or crash and burn?
+        // Can't parse CSS? We'll skip it and add a warning to the log.
         errorLog.push(e.toString());
+        debug(`Ran into an error when parsing CSS content for conflict analysis! Review the error log for details.`);
       }
     });
+    debug("Done finding app classes.");
+
+    // Find collisions between the app styles and optimizer styles.
+    const collisions = optimizerClasses.filter(val => foundClasses.has(val));
+    debug("Done identifying collisions.");
 
     // Build a logfile for the output tree, for debugging.
-    let logfile = "FOUND CLASSES:\n";
+    let logfile = "COLLISIONS:\n";
+    collisions.forEach(cssClass => { logfile += `${cssClass}\n`; });
+    logfile += "\nFOUND APP CLASSES:\n";
     foundClasses.forEach(cssClass => { logfile += `${cssClass}\n`; });
     logfile += "\nFOUND FILES:\n";
     foundFiles.forEach(file => { logfile += `${file}\n`; });
     logfile += "\nERRORS:\n";
     errorLog.forEach(err => { logfile += `${err}\n`; });
     this.output.writeFileSync("assets/app-classes.log", logfile);
+    debug("Wrote log file to broccoli tree.");
+
+    if (collisions.length > 0) {
+      throw new Error(
+        "Your application CSS contains classes that are also generated by the CSS optimizer. This can cause style conflicts between your application's classes and those generated by CSS Blocks.\n" +
+        "To resolve this conflict, you should add any short class names in non-block CSS (~5 characters or less) to the list of disallowed classes in your build configuration.\n" +
+        "(You can do this by setting css-blocks.appClasses to an array of disallowed classes in ember-cli-build.js.)\n\n" +
+        "Conflicting classes:\n" +
+        collisions.reduce((prev, curr) => prev += `${curr}\n`, ""),
+      );
+    }
   }
 }
 

packages/@css-blocks/ember-app/src/index.ts

@@ -9,7 +9,7 @@ import type { AddonImplementation, ThisAddon } from "ember-cli/lib/models/addon"
 import Project from "ember-cli/lib/models/project";
 
 import { CSSBlocksApplicationPlugin, CSSBlocksStylesPostprocessorPlugin, CSSBlocksStylesPreprocessorPlugin } from "./broccoli-plugin";
-import { appStylesPostprocessFilename, cssBlocksPostprocessFilename } from "./utils/filepaths";
+import { appStylesPostprocessFilename, cssBlocksPostprocessFilename, optimizedStylesPostprocessFilepath } from "./utils/filepaths";
 import { AddonEnvironment, CSSBlocksApplicationAddon } from "./utils/interfaces";
 
 /**
@@ -172,14 +172,20 @@ const EMBER_ADDON: AddonImplementation<CSSBlocksApplicationAddon> = {
         // tree is processed before the CSS tree, but just in case....
         throw new Error("[css-blocks/ember-app] The CSS tree ran before the JS tree, so the CSS tree doesn't have the contents for CSS Blocks files. This shouldn't ever happen, but if it does, please file an issue with us!");
       }
-      // Get the combined CSS file
+      // Copy over the CSS Blocks compiled output from the template tree to the CSS tree.
       const cssBlocksContentsTree = new CSSBlocksStylesPreprocessorPlugin(env.modulePrefix, env.config, [this.broccoliAppPluginInstance, tree]);
       return new BroccoliDebug(mergeTrees([tree, cssBlocksContentsTree], { overwrite: true }), "css-blocks:css-preprocess");
     } else {
       return tree;
     }
   },
 
+  /**
+   * Post-process the tree.
+   * @param type - The type of tree.
+   * @param tree - The tree to process.
+   * @returns - A broccoli tree.
+   */
   postprocessTree(type, tree) {
     let env = this.env!;
 
@@ -208,7 +214,10 @@ const EMBER_ADDON: AddonImplementation<CSSBlocksApplicationAddon> = {
 
       // Then overwrite the original file with our final build artifact.
       const mergedTree = funnel(mergeTrees([tree, concatTree], { overwrite: true }), {
-        exclude: [cssBlocksPostprocessFilename(env.config)],
+        exclude: [
+          cssBlocksPostprocessFilename(env.config),
+          optimizedStylesPostprocessFilepath,
+        ],
       });
       return new BroccoliDebug(mergedTree, "css-blocks:css-postprocess");
     }

packages/@css-blocks/ember-app/src/utils/filepaths.ts

@@ -2,6 +2,16 @@ import { ResolvedCSSBlocksEmberOptions } from "@css-blocks/ember-utils";
 
 import { AddonEnvironment } from "./interfaces";
 
+/**
+ * Filepath for list of optimized styles in preprocess tree.
+ */
+export const optimizedStylesPreprocessFilepath = "app/styles/css-blocks-stylelist.json";
+
+/**
+ * Filepath for list of optimized styles in postprocess tree.
+ */
+export const optimizedStylesPostprocessFilepath = "assets/css-blocks-stylelist.json";
+
 /**
  * Generate the output path for the compiled CSS Blocks content, using the
  * preferred filename given by the user. If none is given, the default

packages/@css-blocks/ember-utils/src/options.ts

@@ -49,19 +49,42 @@ export interface BroccoliConcatOptions {
 }
 
 export interface CSSBlocksEmberOptions {
+  /**
+   * The name of the CSS file generated that contains the compiled
+   * result of CSS Blocks. By default, this is css-blocks.css.
+   */
   output?: string;
   aliases?: ObjectDictionary<string>;
   analysisOpts?: AnalysisOptions;
   parserOpts?: Writeable<ParserOptions>;
+  /**
+   * Options that control the behavior of OptiCSS, which is used to
+   * rewrite and optimize compiled CSS Blocks output. By default,
+   * optimization is enabled for production builds only.
+   *
+   * To disable optimization, set optimization.enabled to false.
+   */
   optimization?: Partial<OptiCSSOptions>;
   /**
    * Options that control the behavior of broccoli-concat, which is used
    * to concatenate CSS files together by ember-app during postprocess.
+   *
    * If this is set to false, broccoli-concat will *not* run.
    * You'll need to add additional processing to add the CSS Blocks
    * compiled content to your final CSS build artifact.
    */
   broccoliConcat?: BroccoliConcatOptions | false;
+  /**
+   * List of classes that are used by application CSS and might conflict
+   * with the optimizer. You should add any short class names (~5 characters)
+   * to this list so the optimizer doesn't use these when building the
+   * CSS Blocks compiled output.
+   *
+   * This is a convenience alias for
+   * optimization.rewriteIdents.omitIdents.class[]. It has no effect if
+   * optimization is disabled.
+   */
+  appClasses?: string[];
 }
 
 export interface ResolvedCSSBlocksEmberOptions {
@@ -71,13 +94,15 @@ export interface ResolvedCSSBlocksEmberOptions {
   parserOpts: ParserOptions;
   optimization: Partial<OptiCSSOptions>;
   broccoliConcat: BroccoliConcatOptions | false;
+  appClasses: string[];
 }
 
 export function getConfig(root: string, isProduction: boolean, options: CSSBlocksEmberOptions): ResolvedCSSBlocksEmberOptions {
   if (!options.aliases) options.aliases = {};
   if (!options.analysisOpts) options.analysisOpts = {};
   if (!options.optimization) options.optimization = {};
   if (!options.broccoliConcat) options.broccoliConcat = {};
+  if (!options.appClasses) options.appClasses = [];
 
   if (!options.parserOpts) {
     options.parserOpts = config.searchSync(root) || {};

private-packages/fixtures-ember-v2/ember-app/app/styles/app.css

@@ -10,4 +10,23 @@ body {
 
 .public-addon-component-alias {
   font-size: 22px;
+}
+
+/*
+ * This class is a smoke test for the class duplication check run by
+ * the @css-blocks/ember-app css postprocess step. When optimization is
+ * enabled, this class conflicts with the default classes that are generated
+ * by OptiCSS.
+ *
+ * You can force a build failure by commenting out css-blocks.appStyles in
+ * ember-cli-build.js and building using the --prod flag (or turning on
+ * optimization via config).
+ *
+ * (Note: This info is accurate as of the time of this comment's creation.
+ * Other changes may make it so .i no longer conflicts with optimization. In
+ * this case, review the generated css-blocks output for a class name that
+ * conflicts and change this to use that class name.)
+ */
+.i {
+  font-style: italic;
 }

private-packages/fixtures-ember-v2/ember-app/ember-cli-build.js

@@ -12,6 +12,7 @@ module.exports = function(defaults) {
         mergeDeclarations: true,
         removeUnusedStyles: true,
       },
+      appClasses: ['i'],
     }
   });