chore: enhance preprocessor commands to automate releases. (#2446)

Last release v1.3.0 had an error in the documentation, claiming
it wasn't released.

This patch makes sure we have a little bit of automation in place
to save us from this in future.

docs/api.md

@@ -1,9 +1,13 @@
 ##### Released APIs: [v1.3.0](https://github.com/GoogleChrome/puppeteer/blob/v1.3.0/docs/api.md) | [v1.2.0](https://github.com/GoogleChrome/puppeteer/blob/v1.2.0/docs/api.md) | [v1.1.1](https://github.com/GoogleChrome/puppeteer/blob/v1.1.1/docs/api.md) | [v1.1.0](https://github.com/GoogleChrome/puppeteer/blob/v1.1.0/docs/api.md) | [v1.0.0](https://github.com/GoogleChrome/puppeteer/blob/v1.0.0/docs/api.md) | [v0.13.0](https://github.com/GoogleChrome/puppeteer/blob/v0.13.0/docs/api.md) | [v0.12.0](https://github.com/GoogleChrome/puppeteer/blob/v0.12.0/docs/api.md) | [v0.11.0](https://github.com/GoogleChrome/puppeteer/blob/v0.11.0/docs/api.md) | [v0.10.2](https://github.com/GoogleChrome/puppeteer/blob/v0.10.2/docs/api.md) | [v0.10.1](https://github.com/GoogleChrome/puppeteer/blob/v0.10.1/docs/api.md) | [v0.10.0](https://github.com/GoogleChrome/puppeteer/blob/v0.10.0/docs/api.md) | [v0.9.0](https://github.com/GoogleChrome/puppeteer/blob/v0.9.0/docs/api.md)
 
-# Puppeteer API v<!-- GEN:version -->1.3.0-post<!-- GEN:stop-->
+# Puppeteer API <!-- GEN:version -->Tip-Of-Tree<!-- GEN:stop-->
+
+<!-- GEN:empty-if-release -->
 
 > Next Release: **May 8, 2018**
 
+<!-- GEN:stop -->
+
 
 ##### Table of Contents
 

utils/doclint/cli.js

@@ -20,6 +20,7 @@ const path = require('path');
 const SourceFactory = require('./SourceFactory');
 
 const PROJECT_DIR = path.join(__dirname, '..', '..');
+const VERSION = require(path.join(PROJECT_DIR, 'package.json')).version;
 
 const RED_COLOR = '\x1b[31m';
 const YELLOW_COLOR = '\x1b[33m';
@@ -43,7 +44,7 @@ async function run() {
     messages.push(...await toc(mdSources));
 
     const preprocessor = require('./preprocessor');
-    messages.push(...await preprocessor(mdSources));
+    messages.push(...await preprocessor(mdSources, VERSION));
 
     const browser = await puppeteer.launch({args: ['--no-sandbox']});
     const page = await browser.newPage();

utils/doclint/preprocessor/index.js

@@ -16,14 +16,14 @@
 
 const Message = require('../Message');
 
-const PUPPETEER_VERSION = require('../../../package.json').version;
+module.exports = function(sources, version) {
-
+  // Release version is everything that doesn't include "-".
-module.exports = function(sources) {
+  const isReleaseVersion = !version.includes('-');
   const messages = [];
-  let commands = [];
+  const commands = [];
   for (const source of sources) {
     const text = source.text();
-    const commandStartRegex = /<!--\s*gen:([a-z]+)(?:\s*\(\s*([^)]*)\s*\))?\s*-->/ig;
+    const commandStartRegex = /<!--\s*gen:([a-z-]+)\s*-->/ig;
     const commandEndRegex = /<!--\s*gen:stop\s*-->/ig;
     let start;
 
@@ -32,27 +32,29 @@ module.exports = function(sources) {
       const end = commandEndRegex.exec(text);
       if (!end) {
         messages.push(Message.error(`Failed to find 'gen:stop' for command ${start[0]}`));
-        break;
+        return messages;
       }
       const name = start[1];
-      const arg = start[2];
       const from = commandStartRegex.lastIndex;
       const to = end.index;
+      const originalText = text.substring(from, to);
+      commands.push({name, from, to, originalText, source});
       commandStartRegex.lastIndex = commandEndRegex.lastIndex;
-      commands.push({name, arg, from, to, source});
     }
   }
 
-  commands = validateCommands(commands, messages);
-
   const changedSources = new Set();
   // Iterate commands in reverse order so that edits don't conflict.
   commands.sort((a, b) => b.from - a.from);
   for (const command of commands) {
-    let newText = command.source.text();
+    let newText = null;
     if (command.name === 'version')
-      newText = replaceInText(newText, command.from, command.to, PUPPETEER_VERSION);
+      newText = isReleaseVersion ? 'v' + version : 'Tip-Of-Tree';
-    if (command.source.setText(newText))
+    else if (command.name === 'empty-if-release')
+      newText = isReleaseVersion ? '' : command.originalText;
+    if (newText === null)
+      messages.push(Message.error(`Unknown command 'gen:${command.name}'`));
+    else if (applyCommand(command, newText))
       changedSources.add(command.source);
   }
   for (const source of changedSources)
@@ -61,35 +63,13 @@ module.exports = function(sources) {
 };
 
 /**
- * @param {!Array<!Object>} commands
+ * @param {{name: string, from: number, to: number, source: !Source}} command
- * @param {!Array<!Message>} outMessages
+ * @param {string} editText
- * @return {!Array<!Object>}
+ * @return {boolean}
  */
-function validateCommands(commands, outMessages) {
+function applyCommand(command, editText) {
-  // Filter sane commands
+  const text = command.source.text();
-  const goodCommands = commands.filter(command => {
+  const newText = text.substring(0, command.from) + editText + text.substring(command.to);
-    if (command.name === 'version')
+  return command.source.setText(newText);
-      return check(command, !command.arg, `"gen:version" should not have argument`);
-    check(command, false, `Unknown command: "gen:${command.name}"`);
-  });
-
-  return goodCommands;
-
-  function check(command, condition, message) {
-    if (condition)
-      return true;
-    outMessages.push(Message.error(`${command.source.projectPath()}: ${message}`));
-    return false;
-  }
 }
 
-/**
- * @param {string} text
- * @param {number} from
- * @param {number} to
- * @param {string} newText
- * @return {string}
- */
-function replaceInText(text, from, to, newText) {
-  return text.substring(0, from) + newText + text.substring(to);
-}

utils/doclint/preprocessor/test.js

@@ -17,7 +17,6 @@
 const preprocessor = require('.');
 const SourceFactory = require('../SourceFactory');
 const factory = new SourceFactory();
-const VERSION = require('../../../package.json').version;
 
 const {TestRunner, Reporter, Matchers}  = require('../../testrunner/');
 const runner = new TestRunner();
@@ -30,8 +29,10 @@ const {expect} = new Matchers();
 
 describe('preprocessor', function() {
   it('should throw for unknown command', function() {
-    const source = factory.createForTest('doc.md', getCommand('unknownCommand()'));
+    const source = factory.createForTest('doc.md', `
-    const messages = preprocessor([source]);
+      <!-- gen:unknown-command -->something<!-- gen:stop -->
+    `);
+    const messages = preprocessor([source], '1.1.1');
     expect(source.hasUpdatedText()).toBe(false);
     expect(messages.length).toBe(1);
     expect(messages[0].type).toBe('error');
@@ -39,32 +40,85 @@ describe('preprocessor', function() {
   });
   describe('gen:version', function() {
     it('should work', function() {
-      const source = factory.createForTest('doc.md', `Puppeteer v${getCommand('version')}`);
+      const source = factory.createForTest('doc.md', `
-      const messages = preprocessor([source]);
+        Puppeteer <!-- gen:version -->XXX<!-- gen:stop -->
+      `);
+      const messages = preprocessor([source], '1.2.0');
       expect(messages.length).toBe(1);
       expect(messages[0].type).toBe('warning');
       expect(messages[0].text).toContain('doc.md');
-      expect(source.text()).toBe(`Puppeteer v${getCommand('version', VERSION)}`);
+      expect(source.text()).toBe(`
+        Puppeteer <!-- gen:version -->v1.2.0<!-- gen:stop -->
+      `);
+    });
+    it('should work for *-post versions', function() {
+      const source = factory.createForTest('doc.md', `
+        Puppeteer <!-- gen:version -->XXX<!-- gen:stop -->
+      `);
+      const messages = preprocessor([source], '1.2.0-post');
+      expect(messages.length).toBe(1);
+      expect(messages[0].type).toBe('warning');
+      expect(messages[0].text).toContain('doc.md');
+      expect(source.text()).toBe(`
+        Puppeteer <!-- gen:version -->Tip-Of-Tree<!-- gen:stop -->
+      `);
     });
     it('should tolerate different writing', function() {
-      const source = factory.createForTest('doc.md', `Puppeteer v<!--   gEn:version (  ) -->WHAT
+      const source = factory.createForTest('doc.md', `Puppeteer v<!--   gEn:version -->WHAT
 <!--     GEN:stop   -->`);
-      preprocessor([source]);
+      preprocessor([source], '1.1.1');
-      expect(source.text()).toBe(`Puppeteer v<!--   gEn:version (  ) -->${VERSION}<!--     GEN:stop   -->`);
+      expect(source.text()).toBe(`Puppeteer v<!--   gEn:version -->v1.1.1<!--     GEN:stop   -->`);
     });
     it('should not tolerate missing gen:stop', function() {
       const source = factory.createForTest('doc.md', `<!--GEN:version-->`);
-      const messages = preprocessor([source]);
+      const messages = preprocessor([source], '1.2.0');
       expect(source.hasUpdatedText()).toBe(false);
       expect(messages.length).toBe(1);
       expect(messages[0].type).toBe('error');
       expect(messages[0].text).toContain(`Failed to find 'gen:stop'`);
     });
   });
+  describe('gen:empty-if-release', function() {
+    it('should clear text when release version', function() {
+      const source = factory.createForTest('doc.md', `
+        <!-- gen:empty-if-release -->XXX<!-- gen:stop -->
+      `);
+      const messages = preprocessor([source], '1.1.1');
+      expect(messages.length).toBe(1);
+      expect(messages[0].type).toBe('warning');
+      expect(messages[0].text).toContain('doc.md');
+      expect(source.text()).toBe(`
+        <!-- gen:empty-if-release --><!-- gen:stop -->
+      `);
+    });
+    it('should keep text when non-release version', function() {
+      const source = factory.createForTest('doc.md', `
+        <!-- gen:empty-if-release -->XXX<!-- gen:stop -->
+      `);
+      const messages = preprocessor([source], '1.1.1-post');
+      expect(messages.length).toBe(0);
+      expect(source.text()).toBe(`
+        <!-- gen:empty-if-release -->XXX<!-- gen:stop -->
+      `);
+    });
+  });
+  it('should work with multiple commands', function() {
+    const source = factory.createForTest('doc.md', `
+      <!-- gen:version -->XXX<!-- gen:stop -->
+      <!-- gen:empty-if-release -->YYY<!-- gen:stop -->
+      <!-- gen:version -->ZZZ<!-- gen:stop -->
+    `);
+    const messages = preprocessor([source], '1.1.1');
+    expect(messages.length).toBe(1);
+    expect(messages[0].type).toBe('warning');
+    expect(messages[0].text).toContain('doc.md');
+    expect(source.text()).toBe(`
+      <!-- gen:version -->v1.1.1<!-- gen:stop -->
+      <!-- gen:empty-if-release --><!-- gen:stop -->
+      <!-- gen:version -->v1.1.1<!-- gen:stop -->
+    `);
+  });
 });
 
 runner.run();
 
-function getCommand(name, body = '') {
-  return `<!--gen:${name}-->${body}<!--gen:stop-->`;
-}