Merge branch 'simplify-options'

BREAKING CHANGE: Several types relating to options and configuration are removed/renamed.

The options code was some of the first I wrote for this project and it
was awkward to use. A lot of APIs expected a concrete options reader
instead of just the options interface in a read-only state.

This change introduces the term "configuration" to mean a set of
complete configuration options and "options" to mean a partial
configuration. The act of turning options into configuration is called
"resolving" the options. The options reader is no longer exported, the
new resolveConfiguration function should be used to get a read-only
configuration object populated with default values where necessary.

Because configurations are assignable to options, if a resolved
configuration is ever passed to resolveConfiguration, is it efficiently
passed through, so, when in doubt, an API should accept options and
resolve them.

Where user-supplied options are accepted, the Options type is accepted
and then resolved to a ResolvedConfiguration.

This merge also re-organizes the project a bit, two new directories are added
to `css-blocks/src`: configuration and importing. The importing.ts file
has been broken up into constituent parts. This enabled making the
css-blocks configuration no longer need to be augmented from different
modules in the project. Configuration and options related code is now
found in the configuration module directory.

Author: chriseppstein

Diff for: packages/css-blocks/src/Block/AttrValue.ts

@@ -7,8 +7,8 @@ import {
 import { assertNever, assertNeverCalled } from "@opticss/util";
 
 import { ATTR_PRESENT } from "../BlockSyntax";
-import { OptionsReader } from "../OptionsReader";
-import { OutputMode } from "../OutputMode";
+import { OutputMode,
+ ResolvedConfiguration } from "../configuration";
 
 import { Attribute } from "./Attribute";
 import { Block } from "./Block";
@@ -78,12 +78,12 @@ export class AttrValue extends Style<AttrValue, Block, Attribute, never> {
     return this.parent.asSource(this.value);
   }
 
-  public cssClass(opts: OptionsReader): string {
-    switch (opts.outputMode) {
+  public cssClass(config: ResolvedConfiguration): string {
+    switch (config.outputMode) {
       case OutputMode.BEM:
-        return `${this.parent.cssClass(opts)}${ this.isPresenceRule ? "" : `-${this.value}`}`;
+        return `${this.parent.cssClass(config)}${ this.isPresenceRule ? "" : `-${this.value}`}`;
       default:
-        return assertNever(opts.outputMode);
+        return assertNever(config.outputMode);
     }
   }
 

Diff for: packages/css-blocks/src/Block/Attribute.ts

@@ -9,8 +9,7 @@ import {
 import { assertNever, ObjectDictionary } from "@opticss/util";
 
 import { ATTR_PRESENT, IAttrToken as AttrToken } from "../BlockSyntax";
-import { OptionsReader } from "../OptionsReader";
-import { OutputMode } from "../OutputMode";
+import { OutputMode, ResolvedConfiguration } from "../configuration";
 
 import { AttrValue } from "./AttrValue";
 import { Block } from "./Block";
@@ -174,16 +173,16 @@ export class Attribute extends Inheritable<Attribute, Block, BlockClass, AttrVal
 
   /**
    * Export as new class name.
-   * @param opts Option hash configuring output mode.
+   * @param config Option hash configuring output mode.
    * @returns String representing output class.
    */
-  cssClass(opts: OptionsReader) {
-    switch (opts.outputMode) {
+  cssClass(config: ResolvedConfiguration) {
+    switch (config.outputMode) {
       case OutputMode.BEM:
-        let cssClassName = this.blockClass.cssClass(opts);
+        let cssClassName = this.blockClass.cssClass(config);
         return `${cssClassName}--${this.token.name}`;
       default:
-        return assertNever(opts.outputMode);
+        return assertNever(config.outputMode);
     }
   }
 

Diff for: packages/css-blocks/src/Block/Block.ts

@@ -16,8 +16,8 @@ import {
 } from "../BlockParser";
 import { isRootNode, toAttrToken } from "../BlockParser";
 import { BlockPath, CLASS_NAME_IDENT, ROOT_CLASS } from "../BlockSyntax";
-import { OptionsReader } from "../OptionsReader";
 import { SourceLocation } from "../SourceLocation";
+import { ResolvedConfiguration } from "../configuration";
 import { CssBlockError, InvalidBlockSyntax } from "../errors";
 import { FileIdentifier } from "../importing";
 
@@ -367,28 +367,28 @@ export class Block
     return null;
   }
 
-  rewriteSelectorNodes(nodes: selectorParser.Node[], opts: OptionsReader): selectorParser.Node[] {
+  rewriteSelectorNodes(nodes: selectorParser.Node[], config: ResolvedConfiguration): selectorParser.Node[] {
     let newNodes: selectorParser.Node[] = [];
     for (let i = 0; i < nodes.length; i++) {
       let node = nodes[i];
       let result = this.nodeAsStyle(node);
       if (result === null) {
         newNodes.push(node);
       } else {
-        newNodes.push(selectorParser.className({ value: result[0].cssClass(opts) }));
+        newNodes.push(selectorParser.className({ value: result[0].cssClass(config) }));
         i += result[1];
       }
     }
     return newNodes;
   }
 
-  rewriteSelectorToString(selector: ParsedSelector, opts: OptionsReader): string {
+  rewriteSelectorToString(selector: ParsedSelector, config: ResolvedConfiguration): string {
     let firstNewSelector = new CompoundSelector();
     let newSelector = firstNewSelector;
     let newCurrentSelector = newSelector;
     let currentSelector: CompoundSelector | undefined = selector.selector;
     do {
-      newCurrentSelector.nodes = this.rewriteSelectorNodes(currentSelector.nodes, opts);
+      newCurrentSelector.nodes = this.rewriteSelectorNodes(currentSelector.nodes, config);
       newCurrentSelector.pseudoelement = currentSelector.pseudoelement;
       if (currentSelector.next !== undefined) {
         let tempSel = newCurrentSelector;
@@ -402,21 +402,21 @@ export class Block
     return firstNewSelector.toString();
   }
 
-  rewriteSelector(selector: ParsedSelector, opts: OptionsReader): ParsedSelector {
+  rewriteSelector(selector: ParsedSelector, config: ResolvedConfiguration): ParsedSelector {
     // generating a string and re-parsing ensures the internal structure is consistent
     // otherwise the parent/next/prev relationships will be wonky with the new nodes.
-    let s = this.rewriteSelectorToString(selector, opts);
+    let s = this.rewriteSelectorToString(selector, config);
     return parseSelector(s)[0];
   }
 
-  debug(opts: OptionsReader): string[] {
-    let result: string[] = [`Source: ${this.identifier}`, this.rootClass.asDebug(opts)];
+  debug(config: ResolvedConfiguration): string[] {
+    let result: string[] = [`Source: ${this.identifier}`, this.rootClass.asDebug(config)];
     let sourceNames = new Set<string>(this.all().map(s => s.asSource()));
     let sortedNames = [...sourceNames].sort();
     for (let n of sortedNames) {
       if (n !== ROOT_CLASS) {
         let o = this.find(n) as Styles;
-        result.push(o.asDebug(opts));
+        result.push(o.asDebug(config));
       }
     }
     return result;

Diff for: packages/css-blocks/src/Block/BlockClass.ts

@@ -1,10 +1,10 @@
 import { Attribute as Attr, AttributeValue, attrValues } from "@opticss/element-analysis";
+import { assertNever } from "@opticss/util";
 import { isString } from "util";
 
 import { ATTR_PRESENT, IAttrToken as AttrToken, ROOT_CLASS } from "../BlockSyntax";
 import { BlockPath } from "../BlockSyntax";
-import { OptionsReader } from "../OptionsReader";
-import { OutputMode } from "../OutputMode";
+import { OutputMode, ResolvedConfiguration } from "../configuration";
 
 import { AttrValue } from "./AttrValue";
 import { Attribute } from "./Attribute";
@@ -181,19 +181,19 @@ export class BlockClass extends Style<BlockClass, Block, Block, Attribute> {
 
   /**
    * Export as new class name.
-   * @param opts Option hash configuring output mode.
+   * @param config Option hash configuring output mode.
    * @returns String representing output class.
    */
-  public cssClass(opts: OptionsReader): string {
-    switch (opts.outputMode) {
+  public cssClass(config: ResolvedConfiguration): string {
+    switch (config.outputMode) {
       case OutputMode.BEM:
         if (this.isRoot) {
           return `${this.block.name}`;
         } else {
           return `${this.block.name}__${this.name}`;
         }
       default:
-        throw new Error("this never happens");
+        return assertNever(config.outputMode);
     }
   }
 
@@ -219,10 +219,10 @@ export class BlockClass extends Style<BlockClass, Block, Block, Attribute> {
    * @param options  Options to pass to BlockClass' asDebug method.
    * @return Array of debug strings for this BlockClass
    */
-  debug(opts: OptionsReader): string[] {
+  debug(config: ResolvedConfiguration): string[] {
     let result: string[] = [];
     for (let style of this.all()) {
-      result.push(style.asDebug(opts));
+      result.push(style.asDebug(config));
     }
     return result;
   }

Diff for: packages/css-blocks/src/Block/Style.ts

@@ -1,6 +1,6 @@
 import { Attr } from "@opticss/element-analysis";
 
-import { OptionsReader } from "../OptionsReader";
+import { ResolvedConfiguration } from "../configuration";
 import { unionInto } from "../util/unionInto";
 
 import { AnyNode, Inheritable } from "./Inheritable";
@@ -38,10 +38,10 @@ export abstract class Style<
 
   /**
    * Return the css selector for this `Style`.
-   * @param opts Option hash configuring output mode.
+   * @param config Option hash configuring output mode.
    * @returns The CSS class.
    */
-  public abstract cssClass(opts: OptionsReader): string;
+  public abstract cssClass(config: ResolvedConfiguration): string;
 
   /**
    * Return the source selector this `Style` was read from.
@@ -59,10 +59,10 @@ export abstract class Style<
    * including inherited classes.
    * @returns this object's css class and all inherited classes.
    */
-  cssClasses(opts: OptionsReader): string[] {
+  cssClasses(config: ResolvedConfiguration): string[] {
     let classes: string[] = [];
     for (let style of this.resolveStyles()) {
-      classes.push(style.cssClass(opts));
+      classes.push(style.cssClass(config));
     }
     return classes;
   }
@@ -107,11 +107,11 @@ export abstract class Style<
 
   /**
    * Debug utility to help log Styles
-   * @param opts  Options for rendering cssClass.
+   * @param config  Options for rendering cssClass.
    * @returns A debug string.
    */
-  asDebug(opts: OptionsReader) {
-    return `${this.asSource()} => ${this.cssClasses(opts).map(n => `.${n}`).join(" ")}`;
+  asDebug(config: ResolvedConfiguration) {
+    return `${this.asSource()} => ${this.cssClasses(config).map(n => `.${n}`).join(" ")}`;
   }
 
   // TypeScript can't figure out that `this` is the `StyleType` so this private

Diff for: packages/css-blocks/src/BlockCompiler/ConflictResolver.ts

@@ -6,8 +6,8 @@ import selectorParser = require("postcss-selector-parser");
 import { Block, Style } from "../Block";
 import { getBlockNode } from "../BlockParser";
 import { RESOLVE_RE } from "../BlockSyntax";
-import { OptionsReader } from "../OptionsReader";
 import { SourceLocation, sourceLocation } from "../SourceLocation";
+import { ResolvedConfiguration } from "../configuration";
 import * as errors from "../errors";
 import { QueryKeySelector } from "../query";
 
@@ -61,10 +61,10 @@ function updateConflict(t1: ConflictType, t2: ConflictType): ConflictType {
  * resolves property values accordingly.
  */
 export class ConflictResolver {
-  readonly opts: OptionsReader;
+  readonly config: ResolvedConfiguration;
 
-  constructor(opts: OptionsReader) {
-    this.opts = opts;
+  constructor(config: ResolvedConfiguration) {
+    this.config = config;
   }
 
   /**
@@ -242,7 +242,7 @@ export class ConflictResolver {
       // we reverse the selectors because otherwise the insertion order causes them to be backwards from the
       // source order of the target selector
       resultSelectors.reverse().forEach((s) => {
-        let newSelectors = this.mergeKeySelectors(other.block.rewriteSelector(s.parsedSelector, this.opts), cs);
+        let newSelectors = this.mergeKeySelectors(other.block.rewriteSelector(s.parsedSelector, this.config), cs);
         if (newSelectors === null) return;
         let newSelStr = newSelectors.join(",\n");
         // avoid duplicate selector via permutation
@@ -416,7 +416,7 @@ export class ConflictResolver {
     return mergedSelectors.map(sel => new ParsedSelector(sel));
   }
   sourceLocation(block: Block, node: postcss.Node): SourceLocation | undefined {
-    let blockPath = this.opts.importer.debugIdentifier(block.identifier, this.opts);
+    let blockPath = this.config.importer.debugIdentifier(block.identifier, this.config);
     return sourceLocation(blockPath, node);
   }
 }

Diff for: packages/css-blocks/src/BlockCompiler/index.ts

@@ -8,30 +8,33 @@ import {
   parseBlockDebug,
   ROOT_CLASS,
 } from "../BlockSyntax";
-import { OptionsReader } from "../OptionsReader";
 import { StyleAnalysis } from "../TemplateAnalysis/StyleAnalysis";
-import { PluginOptions } from "../options";
+import {
+  Options,
+  resolveConfiguration,
+  ResolvedConfiguration,
+} from "../configuration";
 
 import { ConflictResolver } from "./ConflictResolver";
 /**
  * Compiler that, given a Block will return a transformed AST
  * interface is `BlockParser.parse`.
  */
 export class BlockCompiler {
-  private opts: OptionsReader;
+  private config: ResolvedConfiguration;
   private postcss: typeof postcss;
 
-  constructor(postcssImpl: typeof postcss, opts?: PluginOptions) {
-    this.opts = new OptionsReader(opts);
+  constructor(postcssImpl: typeof postcss, opts?: Options) {
+    this.config = resolveConfiguration(opts);
     this.postcss = postcssImpl;
   }
 
   compile(block: Block, root: postcss.Root, analysis?: StyleAnalysis): postcss.Root {
       if (analysis) {
         // console.log("Got an analysis for compilation. I should use it probably.", analysis);
       }
-      let resolver = new ConflictResolver(this.opts);
-      let filename = this.opts.importer.debugIdentifier(block.identifier, this.opts);
+      let resolver = new ConflictResolver(this.config);
+      let filename = this.config.importer.debugIdentifier(block.identifier, this.config);
 
       // Process all debug statements for this block.
       this.processDebugStatements(filename, root, block);
@@ -53,7 +56,7 @@ export class BlockCompiler {
       resolver.resolveInheritance(root, block);
       root.walkRules((rule) => {
         let parsedSelectors = block.getParsedSelectors(rule);
-        rule.selector = parsedSelectors.map(s => block.rewriteSelectorToString(s, this.opts)).join(",\n");
+        rule.selector = parsedSelectors.map(s => block.rewriteSelectorToString(s, this.config)).join(",\n");
       });
 
       resolver.resolve(root, block);
@@ -71,7 +74,7 @@ export class BlockCompiler {
     root.walkAtRules(BLOCK_DEBUG, (atRule) => {
       let {block: ref, channel} = parseBlockDebug(atRule, sourceFile, block);
       if (channel === "comment") {
-        let debugStr = ref.debug(this.opts);
+        let debugStr = ref.debug(this.config);
         atRule.replaceWith(this.postcss.comment({text: debugStr.join("\n   ")}));
       } else {
         // stderr/stdout are emitted during parse.