Simplify snippet script (firebase#78)

samtstern · web-flow · commit c6fdfade032c · 2020-12-28T09:38:07.000-05:00
diff --git a/scripts/separate-snippets.ts b/scripts/separate-snippets.ts
@@ -31,27 +31,27 @@ function isBlank(line: string) {
 }
 
 /**
- * Turns a series of source lines into a standalone snippet file by:
- *   - Converting require statements into top-level imports.
- *   - Adjusting indentation to left-align all content
- *   - Removing any blank lines at the starts
- *   - Adding a suffix to snippet names
- *
- * @param lines the lines containing the snippet (including START/END comments)
- * @param sourceFile the source file where the original snippet lives
- * @param snippetSuffix the suffix (such as _modular)
+ * Replace all const { foo } = require('bar') with import { foo } from 'bar';
  */
-function processSnippet(
-  lines: string[],
-  sourceFile: string,
-  snippetSuffix: string
-): string {
-  const outputLines: string[] = [];
-
+function replaceRequireWithImport(lines: string[]) {
+  const outputLines = [];
   for (const line of lines) {
     if (line.match(RE_REQUIRE)) {
       outputLines.push(line.replace(RE_REQUIRE, `import {$1} from $2`));
-    } else if (line.match(RE_START_SNIPPET)) {
+    } else {
+      outputLines.push(line);
+    }
+  }
+  return outputLines;
+}
+
+/**
+ * Change all [START foo] and [END foo] to be [START foosuffix] and [END foosuffix]
+ */
+function addSuffixToSnippetNames(lines: string[], snippetSuffix: string) {
+  const outputLines = [];
+  for (const line of lines) {
+    if (line.match(RE_START_SNIPPET)) {
       outputLines.push(line.replace(RE_START_SNIPPET, `[START $1${snippetSuffix}]`));
     } else if (line.match(RE_END_SNIPPET)) {
       outputLines.push(
@@ -61,37 +61,74 @@ function processSnippet(
       outputLines.push(line);
     }
   }
+  return outputLines;
+}
 
-  // Adjust indentation of the otherLines so that they're left aligned
-  const nonBlankLines = outputLines.filter((l) => !isBlank(l));
+/**
+ * Remove all left-padding so that the least indented line is left-aligned.
+ */
+function adjustIndentation(lines: string[]) {
+  const nonBlankLines = lines.filter((l) => !isBlank(l));
   const indentSizes = nonBlankLines.map((l) => l.length - l.trimLeft().length);
   const minIndent = Math.min(...indentSizes);
 
-  const adjustedOutputLines: string[] = [];
-  for (const line of outputLines) {
+  const outputLines = [];
+  for (const line of lines) {
     if (isBlank(line)) {
-      adjustedOutputLines.push("");
+      outputLines.push("");
     } else {
-      adjustedOutputLines.push(line.substr(minIndent));
+      outputLines.push(line.substr(minIndent));
     }
   }
+  return outputLines;
+}
 
-  // Special case: if the first line after the comments is blank we want to remove it
-  const firstNonComment = adjustedOutputLines.findIndex(
+/**
+ * If the first line after leading comments is blank, remove it.
+ */
+function removeFirstLineAfterComments(lines: string[]) {
+  const outputLines = [...lines];
+
+  const firstNonComment = outputLines.findIndex(
     (l) => !l.startsWith("//")
   );
   if (isBlank(outputLines[firstNonComment])) {
-    adjustedOutputLines.splice(firstNonComment, 1);
+    outputLines.splice(firstNonComment, 1);
   }
 
+  return outputLines;
+}
+
+/**
+ * Turns a series of source lines into a standalone snippet file by running
+ * a series of transformations.
+ *
+ * @param lines the lines containing the snippet (including START/END comments)
+ * @param sourceFile the source file where the original snippet lives (used in preamble)
+ * @param snippetSuffix the suffix (such as _modular)
+ */
+function processSnippet(
+  lines: string[],
+  sourceFile: string,
+  snippetSuffix: string
+): string {
+  let outputLines = [...lines];
+
+  // Perform transformations individually, in order
+  outputLines = replaceRequireWithImport(outputLines);
+  outputLines = addSuffixToSnippetNames(outputLines, snippetSuffix);
+  outputLines = adjustIndentation(outputLines);
+  outputLines = removeFirstLineAfterComments(outputLines);
+
+  // Add a preamble to every snippet
   const preambleLines = [
     `// This snippet file was generated by processing the source file:`,
     `// ${sourceFile}`,
     `//`,
     `// To make edits to the snippets in this file, please edit the source`,
     ``,
   ];
-  const content = [...preambleLines, ...adjustedOutputLines].join("\n");
+  const content = [...preambleLines, ...outputLines].join("\n");
   return content;
 }
 
@@ -121,40 +158,55 @@ function collectSnippets(filePath: string): SnippetsConfig {
     map: {},
   };
 
+  // If a file does not have '// [SNIPPETS_SEPARATION enabled]' in it then 
+  // we don't process it for this script.
   config.enabled = lines.some((l) => !!l.match(RE_SNIPPETS_SEPARATION));
   if (!config.enabled) {
     return config;
   }
 
+  // If the file contains '// [SNIPPETS_SUFFIX _banana]' we use _banana (or whatever)
+  // as the suffix. Otherwise we default to _modular.
   const suffixLine = lines.find((l) => !!l.match(RE_SNIPPETS_SUFFIX));
   if (suffixLine) {
     const m = suffixLine.match(RE_SNIPPETS_SUFFIX);
     config.suffix = m[1];
   }
 
+  // A temporary array holding the names of snippets we're currently within.
+  // This allows for handling nested snippets.
   let inSnippetNames = [];
 
   for (const line of lines) {
     const startMatch = line.match(RE_START_SNIPPET);
     const endMatch = line.match(RE_END_SNIPPET);
 
     if (startMatch) {
+      // When we find a new [START foo] tag we are now inside snippet 'foo'.
+      // Until we find an [END foo] tag. All lines we see between now and then
+      // are part of the snippet content.
       const snippetName = startMatch[1];
-      config.map[snippetName] = [];
-      config.map[snippetName].push(line);
-
+      config.map[snippetName] = [line];
       inSnippetNames.push(snippetName);
     } else if (endMatch) {
+      // When we find a new [END foo] tag we are now exiting snippet 'foo'.
       const snippetName = endMatch[1];
-      config.map[snippetName].push(line);
 
+      // If we were not aware that we were inside this snippet (no previous START)
+      // then we hard throw.
       if (!inSnippetNames.includes(snippetName)) {
         throw new Error(
           `Unrecognized END tag ${snippetName} in ${filePath}.`
         );
       }
+
+      // Collect this line as the final line of the snippet and then
+      // remove this snippet name from the list we're tracking.
+      config.map[snippetName].push(line);
       inSnippetNames.splice(inSnippetNames.indexOf(snippetName), 1);
     } else if (inSnippetNames.length > 0) {
+      // Any line that is not START or END is appended to the list of
+      // lines for all the snippets we're currently tracking.
       for (const snippetName of inSnippetNames) {
         config.map[snippetName].push(line);
       }
@@ -189,11 +241,14 @@ async function main() {
 
     for (const snippetName in config.map) {
       const newFilePath = path.join(snippetDir, `${snippetName}.js`);
+
+      const snippetLines = config.map[snippetName];
       const content = processSnippet(
-        config.map[snippetName],
+        snippetLines,
         filePath,
         config.suffix
       );
+
       fs.writeFileSync(newFilePath, content);
     }
   }
