feat: Utilities for compiled CSS parsing.

Timothy Lindvall · timlindvall · commit bec10d2a9ea8 · 2020-05-05T16:35:58.000-07:00
- Add utility methods to BaseImporter to handle compiled CSS files.
- Create new CompiledImportedFile type that can be now returned by
Importer.import().
- Update tests to reflect changes to ImportedFile and Importer.import().
- Add stub to BlockFactory for handling CompiledImportedFiles.
- Add test coverage for isDefinitionUrlValid().
diff --git a/packages/@css-blocks/core/src/BlockParser/BlockFactory.ts b/packages/@css-blocks/core/src/BlockParser/BlockFactory.ts
@@ -183,21 +183,26 @@ export class BlockFactory {
   private async _getBlockPromiseAsync(identifier: FileIdentifier): Promise<Block> {
     try {
       let file = await this.importer.import(identifier, this.configuration);
-      let block = await this._importAndPreprocessBlock(file);
-      debug(`Finalizing Block object for "${block.identifier}"`);
-
-      // last check to make sure we don't return a new instance
-      if (this.blocks[block.identifier]) {
-        return this.blocks[block.identifier];
+      if (file.type === 'ImportedFile') {
+        let block = await this._importAndPreprocessBlock(file);
+        debug(`Finalizing Block object for "${block.identifier}"`);
+
+        // last check to make sure we don't return a new instance
+        if (this.blocks[block.identifier]) {
+          return this.blocks[block.identifier];
+        }
+
+        // Ensure this block name is unique.
+        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;
+      } else {
+        // TODO: Process CompiledImportedFile type.
+        return new Block('foo', 'bar');
       }
-
-      // Ensure this block name is unique.
-      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.`);
diff --git a/packages/@css-blocks/core/src/PrecompiledDefinitions/compiled-comments.ts b/packages/@css-blocks/core/src/PrecompiledDefinitions/compiled-comments.ts
@@ -0,0 +1,44 @@
+import * as path from "path";
+import * as url from "url";
+
+/**
+ * A regular expression that can be used to test for the header comment in a compiled CSS file.
+ */
+export const REGEXP_COMMENT_HEADER = /\/\*#css-blocks (?!end)([A-Za-z0-9]+)\*\//m;
+
+/**
+ * A regular expression that can be used to test for the definition URL in a compiled CSS file.
+ */
+export const REGEXP_COMMENT_DEFINITION_REF = /\/\*#blockDefinitionURL=([\S]+?)\*\//m;
+
+/**
+ * A regular expression that can be used to test for the footer comment in a compiled CSS file.
+ */
+export const REGEXP_COMMENT_FOOTER = /\/\*#css-blocks end*\\/m;
+
+/**
+ * Determines if the given URL for a definition is valid.
+ *
+ * The following are valid:
+ * - Path relative to the current file on the filesystem.
+ * - Embedded base64 data.
+ *
+ * The following are invalid:
+ * - Absolute paths.
+ * - URLs with a protocol other than data.
+ *
+ * @param urlOrPath - The definition URL to check.
+ * @returns True if valid given the above rules, false otherwise.
+ */
+export function isDefinitionUrlValid(urlOrPath: string): boolean {
+  // Try to parse as a URL first.
+  try {
+    const parsedUrl = url.parse(urlOrPath);
+    if (parsedUrl.protocol) {
+      return parsedUrl.protocol === 'data:';
+    }
+  } catch (e) {}
+
+  // If we can't parse as a URL with a protocol, it's a path.
+  return !path.isAbsolute(urlOrPath);
+}
diff --git a/packages/@css-blocks/core/src/PrecompiledDefinitions/index.ts b/packages/@css-blocks/core/src/PrecompiledDefinitions/index.ts
@@ -0,0 +1,5 @@
+export {
+  REGEXP_COMMENT_HEADER,
+  REGEXP_COMMENT_DEFINITION_REF,
+  REGEXP_COMMENT_FOOTER
+} from './compiled-comments';
diff --git a/packages/@css-blocks/core/src/importing/BaseImporter.ts b/packages/@css-blocks/core/src/importing/BaseImporter.ts
@@ -1,6 +1,7 @@
 import { Syntax } from '../BlockParser';
 import { ResolvedConfiguration } from '../configuration';
-import { Importer, FileIdentifier, ImportedFile } from './Importer';
+import { Importer, FileIdentifier, ImportedFile, CompiledImportedFileCssContents, CompiledImportedFile } from './Importer';
+import { REGEXP_COMMENT_HEADER, REGEXP_COMMENT_DEFINITION_REF, REGEXP_COMMENT_FOOTER } from '../PrecompiledDefinitions/compiled-comments';
 
 /**
  * The BaseImporter is an abstract class that Importer implementations may extend from.
@@ -17,7 +18,7 @@ export abstract class BaseImporter implements Importer {
   /**
    * Import the file with the given metadata and return a string and meta data for it.
    */
-  abstract import(identifier: FileIdentifier, config: ResolvedConfiguration): Promise<ImportedFile>;
+  abstract import(identifier: FileIdentifier, config: ResolvedConfiguration): Promise<ImportedFile | CompiledImportedFile>;
   /**
    * The default name of the block used unless the block specifies one itself.
    */
@@ -36,4 +37,75 @@ export abstract class BaseImporter implements Importer {
    * Returns the syntax the contents are written in.
    */
   abstract syntax(identifier: FileIdentifier, config: ResolvedConfiguration): Syntax;
+
+  /**
+   * Determines if given file contents is a compiled CSS Blocks file.
+   * We determine this by looking for special auto-generated CSS Blocks
+   * comments in the file. We don't validate at this point that the data
+   * included in these comments is valid.
+   *
+   * @param contents - A string of the imported file contents to check.
+   * @returns True if this represents previously-compiled CSS, false otheerwise.
+   */
+  protected isCompiledBlockCSS(contents: string): boolean {
+    return REGEXP_COMMENT_HEADER.test(contents) &&
+           REGEXP_COMMENT_DEFINITION_REF.test(contents) &&
+           REGEXP_COMMENT_FOOTER.test(contents);
+  }
+
+  /**
+   * Break apart a compiled CSS file that was previously generated from a block file
+   * into segments, based on the CSS Blocks comments that are present. If given a file
+   * that's missing expected auto-generated CSS Blocks comments, this will error.
+   * You should call isCompiledBlockCSS() first to determine if the file should be
+   * processed as a compiled CSS Block file.
+   *
+   * @param contents - A string of the imported file contents to check.
+   * @returns The segmented information from the compiled CSS file.
+   */
+  protected segmentizeCompiledBlockCSS(contents: string): CompiledImportedFileCssContents {
+    // Use our regexps to find the start and end of the compiled content in the CSS file.
+    const headerRegexpResult = contents.match(REGEXP_COMMENT_HEADER);
+    const footerRegexpResult = contents.match(REGEXP_COMMENT_FOOTER);
+    if (!headerRegexpResult || !footerRegexpResult) {
+      throw new Error("Unable to parse compiled CSS file into segments. Expected comments are missing.");
+    }
+
+    // Determine start/end indexes based on the regexp results above.
+    const [headerFullMatch, blockIdFromComment] = headerRegexpResult;
+    const { index: headerStartIndex } = headerRegexpResult;
+    if (!headerStartIndex) {
+      throw new Error("Unable to determine start location of regexp result.");
+    }
+    const headerEndIndex = headerStartIndex + headerFullMatch.length;
+    const [footerFullMatch] = footerRegexpResult;
+    const { index: footerStartIndex } = footerRegexpResult;
+    if (!footerStartIndex) {
+      throw new Error("Unable to determine start location of regexp result.");
+    }
+    const footerEndIndex = footerStartIndex + footerFullMatch.length;
+
+    // Break the file into segments.
+    const pre = contents.slice(0, headerStartIndex);
+    const post = contents.slice(footerEndIndex + 1);
+    const fullBlockContents = contents.slice(headerEndIndex + 1, footerStartIndex);
+
+    // Parse out the URL, or embedded data, for the block definition.
+    // The definition comment should be removed from the block's CSS contents.
+    const definitionRegexpResult = fullBlockContents.match(REGEXP_COMMENT_DEFINITION_REF);
+    if (!definitionRegexpResult) {
+      throw new Error("Unable to find definition URL in compiled CSS. This comment must be declared between the header and footer CSS Blocks comments.");
+    }
+    const [definitionFullMatch, definitionUrl] = definitionRegexpResult;
+    const blockCssContents = fullBlockContents.replace(definitionFullMatch, '');
+
+    return {
+      type: 'CompiledImportedFileCssContents',
+      pre,
+      blockIdFromComment,
+      blockCssContents,
+      definitionUrl,
+      post
+    };
+  }
 }
diff --git a/packages/@css-blocks/core/src/importing/Importer.ts b/packages/@css-blocks/core/src/importing/Importer.ts
@@ -29,6 +29,7 @@ export type FileIdentifier = string;
  * Structure that CSS Blocks uses to represent a single file.
  */
 export interface ImportedFile {
+  type: "ImportedFile";
   /**
    * A unique identifier (probably an absolute filesystem path) that describes
    * the block and can be used for caching.
@@ -48,6 +49,76 @@ export interface ImportedFile {
   contents: string;
 }
 
+/**
+ * Represents the parsed contents from an imported pre-compiled CSS file.
+ */
+export interface CompiledImportedFileCssContents {
+  type: "CompiledImportedFileCssContents";
+
+  /**
+   * File contents prior to the CSS Blocks header comment.
+   */
+  pre: string;
+
+  /**
+   * The Block ID as declared in the header comment. This is expected
+   * to match the `block-id` declaration for the `:scope` selector
+   * in the definition.
+   */
+  blockIdFromComment: string;
+
+  /**
+   * The CSS rules that are present in this file. Only captures any CSS
+   * output between the header and footer comment. The comment that
+   * contains the definition url is omitted.
+   */
+  blockCssContents: string;
+
+  /**
+   * The definition URL as declared in the definition comment. This can
+   * be a relative path or embedded Base64 data.
+   */
+  definitionUrl: string;
+
+  /**
+   * File contents after the CSS Blocks footer comment.
+   */
+  post: string;
+}
+
+/**
+ * Represents an aggregate pre-compiled CSS file and the associated block
+ * definitions for that file. The definitions may be a separate file
+ * altogether or inlined with the compiled contents.
+ */
+export interface CompiledImportedFile {
+  type: "CompiledImportedFile";
+
+  /**
+   * A unique identifier (probably an absolute filesystem path) that describes
+   * the block and can be used for caching.
+   */
+  identifier: FileIdentifier;
+
+  /**
+   * The syntax of the source contents. For pre-compiled files, this is always CSS.
+   */
+  syntax: Syntax.css;
+
+  /**
+   * The contents of the imported pre-compiled CSS file, sliced into segments based
+   * on the presence and location of CSS Blocks comments.
+   */
+  cssContents: CompiledImportedFileCssContents;
+
+  /**
+   * The contents of the block definition. If this was embedded base64 data, it will
+   * have been decoded into a string. If this was an external file, the file's
+   * contents will be included here.
+   */
+  definitionContents: string;
+}
+
 /**
  * Importer provides an API that enables css-blocks to resolve a
  * @block directive into a string that is a css-block stylesheet and
@@ -65,7 +136,7 @@ export interface Importer {
   /**
    * import the file with the given metadata and return a string and meta data for it.
    */
-  import(identifier: FileIdentifier, config: ResolvedConfiguration): Promise<ImportedFile>;
+  import(identifier: FileIdentifier, config: ResolvedConfiguration): Promise<ImportedFile | CompiledImportedFile>;
   /**
    * the default name of the block used unless the block specifies one itself.
    */
diff --git a/packages/@css-blocks/core/src/importing/NodeJsImporter.ts b/packages/@css-blocks/core/src/importing/NodeJsImporter.ts
@@ -6,7 +6,7 @@ import * as path from "path";
 import { Syntax } from "../BlockParser";
 import { ResolvedConfiguration } from "../configuration";
 
-import { FileIdentifier, ImportedFile } from "./Importer";
+import { FileIdentifier, ImportedFile, CompiledImportedFile } from "./Importer";
 import { BaseImporter } from "./BaseImporter";
 
 const debug = debugGenerator("css-blocks:importer");
@@ -134,9 +134,10 @@ export class NodeJsImporter extends BaseImporter {
     return path.relative(config.rootDir, identifier);
   }
 
-  async import(identifier: FileIdentifier, config: ResolvedConfiguration): Promise<ImportedFile> {
+  async import(identifier: FileIdentifier, config: ResolvedConfiguration): Promise<ImportedFile | CompiledImportedFile> {
     let contents = await readFile(identifier, "utf-8");
     return {
+      type: 'ImportedFile',
       syntax: this.syntax(identifier, config),
       identifier,
       defaultName: this.defaultName(identifier, config),
diff --git a/packages/@css-blocks/core/test/PrecompiledDefinitions/compiled-comments-test.ts b/packages/@css-blocks/core/test/PrecompiledDefinitions/compiled-comments-test.ts
@@ -0,0 +1,33 @@
+import { assert } from "chai";
+import { suite, test } from "mocha-typescript";
+import { isDefinitionUrlValid } from "../../src/PrecompiledDefinitions/compiled-comments";
+
+@suite("PrecompiledDefinitions/compiled-comments")
+export class CompiledCommentsTests {
+
+  @test "isDefinitionUrlValid > Reports encoded base64 data is ok"() {
+    const testInput = "data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==";
+    assert.ok(isDefinitionUrlValid(testInput));
+  }
+
+  @test "isDefinitionUrlValid > Reports relative path is ok"() {
+    const testInput = "../../path/to/definition.block.dfn";
+    assert.ok(isDefinitionUrlValid(testInput));
+  }
+
+  @test "isDefinitionUrlValid > Reports absolute Unix path is invalid"() {
+    const testInput = "/path/to/definition.blockdfn.css";
+    assert.notOk(isDefinitionUrlValid(testInput));
+  }
+
+  @test "isDefinitionUrlValid > Reports absolute Windows path is invalid"() {
+    const testInput = "C:\\path\\to\\definition.blockdfn.css";
+    assert.notOk(isDefinitionUrlValid(testInput));
+  }
+
+  @test "isDefinitionUrlValid > Reports URL with non-data protocol is invalid"() {
+    const testInput = "https://css-blocks.com/";
+    assert.notOk(isDefinitionUrlValid(testInput));
+  }
+
+}
diff --git a/packages/@css-blocks/core/test/importing-test.ts b/packages/@css-blocks/core/test/importing-test.ts
@@ -13,6 +13,7 @@ import {
   Importer,
   NodeJsImporter,
   defaultImporter,
+  ImportedFile,
 } from "../src/importing";
 
 const FIXTURES = path.resolve(__dirname, "..", "..", "test", "fixtures");
@@ -82,7 +83,7 @@ function testFSImporter(name: string, importer: Importer) {
     it("imports a file", async () => {
       let options = getConfiguration(FSI_FIXTURES);
       let ident = importer.identifier(null, "a.block.css", options);
-      let importedFile = await importer.import(ident, options);
+      let importedFile = await importer.import(ident, options) as ImportedFile;
       assert.deepEqual(importedFile.contents, fs.readFileSync(path.join(FSI_FIXTURES, "a.block.css"), "utf-8"));
       assert.equal(importedFile.defaultName, "a");
       assert.equal(importedFile.identifier, ident);
@@ -196,7 +197,7 @@ describe("PathAliasImporter", () => {
     let options = getConfiguration(FSI_FIXTURES);
     let importer: Importer = this.importer;
     let ident = importer.identifier(null, "sub/sub.block.css", options);
-    let importedFile = await importer.import(ident, options);
+    let importedFile = await importer.import(ident, options) as ImportedFile;
     let expectedContents = fs.readFileSync(path.join(ALIAS_FIXTURES, "alias_subdirectory", "sub.block.css"), "utf-8");
     assert.deepEqual(importedFile.contents, expectedContents);
     assert.equal(importedFile.defaultName, "sub");
diff --git a/packages/@css-blocks/core/test/util/MockImportRegistry.ts b/packages/@css-blocks/core/test/util/MockImportRegistry.ts
@@ -40,6 +40,7 @@ export class MockImporter extends NodeJsImporter {
     }
     this.registry.imported[resolvedPath] = true;
     return {
+      type: "ImportedFile",
       syntax: source.syntax,
       identifier: resolvedPath,
       defaultName: this.defaultName(resolvedPath, configuration),

Original file line number	Diff line number	Diff line change
`@@ -40,6 +40,7 @@ export class MockImporter extends NodeJsImporter {`
`40`	`40`	`}`
`41`	`41`	`this.registry.imported[resolvedPath] = true;`
`42`	`42`	`return {`
	`43`	`+ type: "ImportedFile",`
`43`	`44`	`syntax: source.syntax,`
`44`	`45`	`identifier: resolvedPath,`
`45`	`46`	`defaultName: this.defaultName(resolvedPath, configuration),`