feat: Use incoming GUIDs. Ensure uniqueness.

- Update BlockParser to eagerly discover the block's GUID (if a
definition file) and provide that GUID to the Block constructor.
- Add check to Block constructor to validate that the GUID is valid.
Also adds an attempt to recover if the GUID that was generated happens
to match a previous entry.

Author: Timothy Lindvall

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

@@ -6,12 +6,12 @@ import { Options, ResolvedConfiguration, resolveConfiguration } from "../configu
 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 { discoverGuid } from "./features/discover-guid";
 import { discoverName } from "./features/discover-name";
 import { exportBlocks } from "./features/export-blocks";
 import { extendBlock } from "./features/extend-block";
@@ -76,15 +76,14 @@ export class BlockParser {
     // Discover the block's preferred name.
     name = await discoverName(configuration, root, sourceFile, isDfnFile, name);
 
+    // Discover the block's GUID, if it's a definition file.
+    const guid = await discoverGuid(configuration, root, sourceFile, isDfnFile, expectedId);
+
     // Create our new Block object and save reference to the raw AST.
-    let block = new Block(name, identifier, root);
+    let block = new Block(name, identifier, root, guid);
 
     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(block, configuration, root, sourceFile, expectedId);
       debug(" - Assert Block Class Declared");
       await assertBlockClassDeclared(block, configuration, root, sourceFile);
     } else {

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

@@ -0,0 +1,53 @@
+import { postcss } from "opticss";
+
+import { BLOCK_ID } from "../../BlockSyntax";
+import { Configuration } from "../../configuration";
+import * as errors from "../../errors";
+import { sourceRange } from "../../SourceLocation";
+import { stripQuotes } from "../utils";
+
+export async function discoverGuid(configuration: Configuration, root: postcss.Root, file: string, isDfnFile = false, expectedId?: string): Promise<string | undefined> {
+  let blockId: string | undefined;
+  let scopeNode: postcss.Rule | undefined;
+
+  // Only definition files can have GUIDs declared. It's not a critical failure if it's
+  // defined... we'll check for this and complain about it later.
+  if (!isDfnFile) {
+    return;
+  }
+
+  root.walkRules(":scope", (rule) => {
+    scopeNode = rule;
+    rule.walkDecls(BLOCK_ID, (decl) => {
+      blockId = stripQuotes(decl.value.trim());
+      // We don't have to expect an ID was declared in the header comment of the Compiled CSS
+      // file, but we need to hard error if it's a mismatch.
+      if (expectedId && decl.value !== expectedId) {
+        throw new errors.InvalidBlockSyntax(
+          `Expected block-id property in definition data to match header in Compiled CSS.`,
+          sourceRange(configuration, root, file, decl),
+        );
+      }
+    });
+  });
+
+  // It's a critical failure if we can't find a block ID in the definition file, because
+  // without it we can't reason about the Compiled CSS linked to this definition.
+  if (!blockId) {
+    if (scopeNode) {
+      throw new errors.InvalidBlockSyntax(
+        `Expected block-id to be declared in definition's :scope rule.`,
+        sourceRange(configuration, root, file, scopeNode),
+        );
+    } else {
+      throw new errors.InvalidBlockSyntax(
+        `Expected block-id to be declared in definition's :scope rule.`,
+        {
+          filename: file,
+        },
+      );
+    }
+  }
+
+  return blockId;
+}

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

@@ -10,6 +10,7 @@ export const CLASS_NAME_IDENT = new RegExp(regexpu("^(-?(?:\\\\.|[A-Za-z_\\u{008
 export const EXTENDS = "extends";
 export const IMPLEMENTS = "implements";
 export const BLOCK_NAME = "block-name";
+export const BLOCK_ID = "block-id";
 export const BLOCK_ALIAS = "block-alias";
 export const COMPOSES = "composes";
 export const BLOCK_PROP_NAMES = new Set([BLOCK_NAME, BLOCK_ALIAS, EXTENDS, IMPLEMENTS, COMPOSES]);

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

@@ -45,6 +45,8 @@ function gen_guid(identifier: string): string {
 export class Block
   extends Inheritable<Block, Block, never, BlockClass> {
 
+  public static GUIDS_USED = new Map<string, string[]>();
+
   private _blockReferences: ObjectDictionary<Block> = {};
   private _blockReferencesReverseLookup: Map<Block, string> = new Map();
   private _blockExports: ObjectDictionary<Block> = {};
@@ -66,13 +68,51 @@ export class Block
   public readonly rootClass: BlockClass;
   public stylesheet: postcss.Root | undefined;
 
-  constructor(name: string, identifier: FileIdentifier, stylesheet?: postcss.Root) {
+  constructor(name: string, identifier: FileIdentifier, stylesheet?: postcss.Root, incomingGuid?: string) {
     super(name);
     this._identifier = identifier;
     this._dependencies = new Set<string>();
     this.rootClass = new BlockClass(ROOT_CLASS, this);
     this.stylesheet = stylesheet;
-    this.guid = gen_guid(identifier);
+
+    // If we found a GUID from the :scope rule, use that. Otherwise, generate one.
+    let guid = incomingGuid || gen_guid(identifier);
+
+    // We insist that each block have a unique GUID. In the event that we've somehow
+    // ended up with two blocks that have the same GUID, our options depend on whether
+    // we got a preset GUID passed in or not.
+    if (Block.GUIDS_USED.has(guid)) {
+      if (incomingGuid) {
+        // If the GUID was already generated prior to creating the block, we have to
+        // bail out. (There's likely Compiled CSS that depends on that GUID.)
+        throw new CssBlockError("Block uses a GUID that has already been used!", {
+          filename: identifier,
+        });
+      } else {
+        // Ok, we autogenerated this. Let's append some gobbledygook to recover.
+        const guidBaseList = Block.GUIDS_USED.get(guid);
+        if (!guidBaseList) {
+          // Ah crumbs. There should be a list but there isn't.
+          throw new CssBlockError("Block uses a GUID that has already been used!", {
+            filename: identifier,
+          });
+        }
+        guid = `${guid}${guidBaseList.length}`;
+        if (guidBaseList.includes(guid) || Block.GUIDS_USED.has(guid)) {
+          // Ah crumbs. Our safety check to make sure the GUID really hasn't been used failed.
+          throw new CssBlockError("Block uses a GUID that has already been used!", {
+            filename: identifier,
+          });
+        }
+        // Phew, okay, appending a numerical id works. Let's go with that.
+        guidBaseList.push(guid);
+      }
+    } else {
+      // Hey, this is unique! Cool, let's remember it in case we see it again later.
+      Block.GUIDS_USED.set(guid, []);
+    }
+    this.guid = guid;
+
     this.addClass(this.rootClass);
   }
 

packages/@css-blocks/core/src/BlockTree/Block.ts

@@ -48,7 +48,7 @@ export class BEMOutputMode extends BEMProcessor {
 
       // Discover the generated GUID for this block.
       // It changes every time the process is killed.
-      let uid = (css.match(/test-block_(.....)/) || [])[1];
+      let uid = (css.match(/test-block_([^\s{]+)/) || [])[1];
 
       assert.deepEqual(
         minify(css),