feat: Definition ingestion and parsing into block.

- Parse AST from definitions, build a Block.
- Check that definitions declare an ID that matches comment header from
Compiled CSS file.
- Check that definitions declare a block class.
- Check that non-definition files don't declare a block-id
or block-class.
- Update stripQuotes() to allow strings without quotes.

Author: Timothy Lindvall

packages/@css-blocks/core/src/BlockParser/BlockFactory.ts

@@ -6,7 +6,7 @@ import { RawSourceMap } from "source-map";
 
 import { Block } from "../BlockTree";
 import { Options, ResolvedConfiguration, resolveConfiguration } from "../configuration";
-import { FileIdentifier, ImportedFile, Importer } from "../importing";
+import { FileIdentifier, ImportedCompiledCssFile, ImportedFile, Importer } from "../importing";
 import { PromiseQueue } from "../util/PromiseQueue";
 
 import { BlockParser, ParsedSource } from "./BlockParser";
@@ -183,26 +183,31 @@ export class BlockFactory {
   private async _getBlockPromiseAsync(identifier: FileIdentifier): Promise<Block> {
     try {
       let file = await this.importer.import(identifier, this.configuration);
+
+      let block;
       if (file.type === "ImportedCompiledCssFile") {
-        // TODO: Process ImportedCompiledCssFile type.
-        throw new Error("Imported Compiled CSS files aren't supported yet.");
+        block = await this._reconstituteCompiledCssSource(file);
       } else {
-        let block = await this._importAndPreprocessBlock(file);
-        debug(`Finalizing Block object for "${block.identifier}"`);
+        block = await this._importAndPreprocessBlock(file);
+      }
 
-        // last check to make sure we don't return a new instance
-        if (this.blocks[block.identifier]) {
-          return this.blocks[block.identifier];
-        }
+      debug(`Finalizing Block object for "${block.identifier}"`);
 
-        // Ensure this block name is unique.
-        block.setName(this.getUniqueBlockName(block.name));
+      // last check to make sure we don't return a new instance
+      if (this.blocks[block.identifier]) {
+        return this.blocks[block.identifier];
+      }
 
-        // if the block has any errors, surface them here unless we're in fault tolerant mode.
-        this._surfaceBlockErrors(block);
-        this.blocks[block.identifier] = block;
-        return block;
+      // Ensure this block name is unique.
+      // Only need to run this on ImportedFile types.
+      if (!file.type || file.type === "ImportedFile") {
+        block.setName(this.getUniqueBlockName(block.name));
       }
+
+      // if the block has any errors, surface them here unless we're in fault tolerant mode.
+      this._surfaceBlockErrors(block);
+      this.blocks[block.identifier] = block;
+      return block;
     } catch (error) {
       if (this.preprocessQueue.activeJobCount > 0) {
         debug(`Block error. Currently there are ${this.preprocessQueue.activeJobCount} preprocessing jobs. waiting.`);
@@ -295,6 +300,44 @@ export class BlockFactory {
     return this.parser.parseSource(source);
   }
 
+  private async _reconstituteCompiledCssSource(file: ImportedCompiledCssFile): Promise<Block> {
+    // Maybe we already have this block in cache?
+    if (this.blocks[file.identifier]) {
+      debug(`Using pre-compiled Block for "${file.identifier}"`);
+      return this.blocks[file.identifier];
+    }
+
+    // NOTE: If we had to upgrade the syntax version of a definition file, here's where'd we do that.
+    //       But this isn't a thing we need to do until we have multiple syntax versions.
+
+    // NOTE: No need to run preprocessor - we assume that Compiled CSS has already been preprocessed.
+    // Parse the definition file into an AST
+    const definitionAst = this.postcssImpl.parse(file.definitionContents);
+
+    // Parse the CSS contents into an AST
+    const cssContentsAst = this.postcssImpl.parse(file.cssContents);
+
+    // TODO: Sourcemaps?
+
+    // Sanity check! Did we actually get contents for both ASTs?
+    if (!definitionAst || !definitionAst.nodes) {
+      throw new Error(`Unable to parse definition file into AST!\nIdentifier: ${file.identifier}`);
+    }
+
+    if (!cssContentsAst || !cssContentsAst.nodes) {
+      throw new Error(`Unable to parse CSS contents into AST!\nIdentifier: ${file.identifier}`);
+    }
+
+    // Construct a Block out of the definition file.
+    const block = this.parser.parseDefinitionSource(definitionAst, file.identifier, file.blockId);
+
+    // Merge the rules from the CSS contents into the Block.
+    // TODO: Actually merge the CSS rules in. (^_^")
+
+    // And we're done!
+    return block;
+  }
+
   /**
    * Similar to getBlock(), this imports and parses a block data file. However, this
    * method parses a block relative to another block.

packages/@css-blocks/core/src/BlockParser/BlockParser.ts

@@ -5,9 +5,12 @@ import { Block } from "../BlockTree";
 import { Options, ResolvedConfiguration, resolveConfiguration } from "../configuration";
 import { FileIdentifier } from "../importing";
 
+import { assertBlockClassDeclared } from "./features/assert-block-class-declared";
+import { assertBlockIdsMatch } from "./features/assert-block-ids-match";
 import { assertForeignGlobalAttribute } from "./features/assert-foreign-global-attribute";
 import { composeBlock } from "./features/composes-block";
 import { constructBlock } from "./features/construct-block";
+import { disallowDefinitionRules } from "./features/disallow-dfn-rules";
 import { disallowImportant } from "./features/disallow-important";
 import { discoverName } from "./features/discover-name";
 import { exportBlocks } from "./features/export-blocks";
@@ -52,26 +55,44 @@ export class BlockParser {
     return block;
   }
 
+  public async parseDefinitionSource(root: postcss.Root, identifier: string, expectedId: string) {
+    return await this.parse(root, identifier, undefined, true, expectedId);
+  }
+
   /**
    * Main public interface of `BlockParser`. Given a PostCSS AST, returns a promise
    * for the new `Block` object.
    * @param root  PostCSS AST
    * @param sourceFile  Source file name
    * @param defaultName Name of block
    */
-  public async parse(root: postcss.Root, identifier: string, name: string): Promise<Block> {
+  public async parse(root: postcss.Root, identifier: string, name?: string, isDfnFile = false, expectedId?: string): Promise<Block> {
     let importer = this.config.importer;
     let debugIdent = importer.debugIdentifier(identifier, this.config);
     let sourceFile = importer.filesystemPath(identifier, this.config) || debugIdent;
     let configuration = this.factory.configuration;
     debug(`Begin parse: "${debugIdent}"`);
 
     // Discover the block's preferred name.
-    name = await discoverName(configuration, root, name, sourceFile);
+    name = await discoverName(configuration, root, sourceFile, isDfnFile, name);
 
     // Create our new Block object and save reference to the raw AST.
     let block = new Block(name, identifier, root);
 
+    if (isDfnFile) {
+      // Rules only checked when parsing definition files...
+      // Assert that the block-id rule in :scope is declared and matches
+      // header comment in Compiled CSS.
+      debug(" - Assert Block IDs Match");
+      await assertBlockIdsMatch(root, debugIdent, expectedId);
+      debug(" - Assert Block Class Declared");
+      await assertBlockClassDeclared(root, debugIdent);
+    } else {
+      // If not a definition file, it shouldn't have rules that can
+      // only be in definition files.
+      debug(" - Disallow Definition-Only Declarations");
+      await disallowDefinitionRules(configuration, root, sourceFile);
+    }
     // Throw if we encounter any `!important` decls.
     debug(` - Disallow Important`);
     await disallowImportant(configuration, root, block, sourceFile);

packages/@css-blocks/core/src/BlockParser/features/assert-block-class-declared.ts

@@ -0,0 +1,29 @@
+import { postcss } from "opticss";
+
+import { CLASS_NAME_IDENT } from "../../BlockSyntax";
+import * as errors from "../../errors";
+import { FileIdentifier } from "../../importing";
+import { stripQuotes } from "../utils";
+
+export async function assertBlockClassDeclared(root: postcss.Root, identifier: FileIdentifier): Promise<postcss.Root> {
+  let foundClassDecl = false;
+
+  root.walkRules(":scope", (rule) => {
+    rule.walkDecls("block-class", (decl) => {
+      const classVal = stripQuotes(decl.value);
+      if (!CLASS_NAME_IDENT.exec(classVal)) {
+        throw new errors.InvalidBlockSyntax(
+          `Illegal block class. '${decl.value}' is not a legal CSS identifier.\nIdentifier: ${identifier}`,
+        );
+      }
+    });
+  });
+
+  if (!foundClassDecl) {
+    throw new errors.InvalidBlockSyntax(
+      `Expected block-class to be declared in definition data.\nIdentifier: ${identifier}`,
+    );
+  }
+
+  return root;
+}

packages/@css-blocks/core/src/BlockParser/features/assert-block-ids-match.ts

@@ -0,0 +1,32 @@
+import { postcss } from "opticss";
+
+import * as errors from "../../errors";
+import { FileIdentifier } from "../../importing";
+import { stripQuotes } from "../utils";
+
+export async function assertBlockIdsMatch(root: postcss.Root, identifier: FileIdentifier, expected?: string): Promise<postcss.Root> {
+  let foundIdDecl = false;
+
+  if (!expected) {
+    throw new Error(`No expected ID provided.\nIdentifier: ${identifier}`);
+  }
+
+  root.walkRules(":scope", (rule) => {
+    rule.walkDecls("block-id", (decl) => {
+      if (stripQuotes(decl.value) !== expected) {
+        throw new errors.InvalidBlockSyntax(
+          `Expected block-id property in definition data to match header in Compiled CSS.\nIdentifier: ${identifier}`,
+        );
+      }
+      foundIdDecl = true;
+    });
+  });
+
+  if (!foundIdDecl) {
+    throw new errors.InvalidBlockSyntax(
+      `Expected block-id to be declared in definition data.\nIdentifier: ${identifier}`,
+    );
+  }
+
+  return root;
+}

packages/@css-blocks/core/src/BlockParser/features/disallow-dfn-rules.ts

@@ -0,0 +1,25 @@
+import { postcss } from "opticss";
+
+import { Configuration } from "../../configuration";
+import * as errors from "../../errors";
+import { sourceRange } from "../../SourceLocation";
+
+export async function disallowDefinitionRules(configuration: Configuration, root: postcss.Root, file: string): Promise<postcss.Root> {
+  root.walkRules((rule) => {
+    rule.walkDecls((decl) => {
+      if (decl.prop === "block-id") {
+        throw new errors.InvalidBlockSyntax(
+          `block-id is disallowed in source block files.`,
+          sourceRange(configuration, root, file, decl),
+        );
+      } else if (decl.prop === "block-class") {
+        throw new errors.InvalidBlockSyntax(
+          `block-id is disallowed in source block files.`,
+          sourceRange(configuration, root, file, decl),
+        );
+      }
+    });
+  });
+
+  return root;
+}

packages/@css-blocks/core/src/BlockParser/features/discover-name.ts

@@ -5,7 +5,7 @@ import { Configuration } from "../../configuration";
 import * as errors from "../../errors";
 import { sourceRange } from "../../SourceLocation";
 
-export async function discoverName(configuration: Configuration, root: postcss.Root, defaultName: string, file: string): Promise<string> {
+export async function discoverName(configuration: Configuration, root: postcss.Root, file: string, isDfnFile: boolean, defaultName?: string): Promise<string> {
 
   // Eagerly fetch custom `block-name` from the root block rule.
   root.walkRules(":scope", (rule) => {
@@ -22,5 +22,14 @@ export async function discoverName(configuration: Configuration, root: postcss.R
     });
   });
 
+  // We expect to have a block name by this point. Either we should have found one in the source
+  // or inferred one from the filename. Definition files must include a blokc-name.
+  if (!defaultName || defaultName.trim() === "") {
+    if (isDfnFile) {
+      throw new errors.InvalidBlockSyntax(`block-name is expected to be declared in definition file's :scope rule.\nIdentifier: ${file}`);
+    } else {
+      throw new errors.CssBlockError(`Unable to find or infer a block name.\nIdentifier: ${file}`);
+    }
+  }
   return defaultName;
 }

packages/@css-blocks/core/src/BlockParser/utils/stripQuotes.ts

@@ -4,5 +4,5 @@
  * @return Result
  */
 export function stripQuotes(str: string): string {
-  return str.replace(/^(["'])(.+)\1$/, "$2");
+  return str.replace(/^(["']?)(.+)\1$/, "$2");
 }