feat: generate recorder sourcemaps (#384)

This PR adds source map generation for the Recorder.
The source map format is custom since we only need to map
step idx to lines. Source maps are VLQ encoded.

__snapshots__/PuppeteerReplayStringifyExtension.test.ts.js

@@ -48,5 +48,6 @@ export async function run(extension) {
 if (process && import.meta.url === url.pathToFileURL(process.argv[1]).href) {
   run()
 }
+//# recorderSourceMap=CQc
 
 `;

__snapshots__/lighthouse.test.ts.js

@@ -258,5 +258,6 @@ const puppeteer = require('puppeteer'); // v13.0.0 or later
   console.error(err);
   process.exit(1);
 });
+//# recorderSourceMap=CaIiBMuBaoCYgDiB
 
 `;

__snapshots__/stringify.test.ts.js

@@ -201,6 +201,7 @@ const puppeteer = require('puppeteer'); // v13.0.0 or later
   console.error(err);
   process.exit(1);
 });
+//# recorderSourceMap=CQI
 
 `;
 
@@ -414,6 +415,7 @@ const puppeteer = require('puppeteer'); // v13.0.0 or later
   console.error(err);
   process.exit(1);
 });
+//# recorderSourceMap=CQS
 
 `;
 
@@ -631,6 +633,7 @@ const puppeteer = require('puppeteer'); // v13.0.0 or later
   console.error(err);
   process.exit(1);
 });
+//# recorderSourceMap=CQa
 
 `;
 
@@ -847,6 +850,7 @@ const puppeteer = require('puppeteer'); // v13.0.0 or later
   console.error(err);
   process.exit(1);
 });
+//# recorderSourceMap=CQc
 
 `;
 
@@ -1065,6 +1069,7 @@ const puppeteer = require('puppeteer'); // v13.0.0 or later
   console.error(err);
   process.exit(1);
 });
+//# recorderSourceMap=CQc
 
 `;
 
@@ -1271,6 +1276,7 @@ const puppeteer = require('puppeteer'); // v13.0.0 or later
   console.error(err);
   process.exit(1);
 });
+//# recorderSourceMap=CQI
 
 `;
 
@@ -1477,6 +1483,7 @@ const puppeteer = require('puppeteer'); // v13.0.0 or later
   console.error(err);
   process.exit(1);
 });
+//# recorderSourceMap=CQI
 
 `;
 
@@ -1689,6 +1696,7 @@ const puppeteer = require('puppeteer'); // v13.0.0 or later
   console.error(err);
   process.exit(1);
 });
+//# recorderSourceMap=CQMcI
 
 `;
 
@@ -1897,6 +1905,7 @@ const puppeteer = require('puppeteer'); // v13.0.0 or later
   console.error(err);
   process.exit(1);
 });
+//# recorderSourceMap=CQI
 
 `;
 
@@ -2105,5 +2114,8 @@ const puppeteer = require('puppeteer'); // v13.0.0 or later
   console.error(err);
   process.exit(1);
 });
+//# recorderSourceMap=CQI
 
 `;
+
+exports['stringify should produce a source map 1'] = [1, 8, 4];

package.json

@@ -87,6 +87,7 @@
   "dependencies": {
     "cli-table3": "0.6.3",
     "colorette": "2.0.19",
+    "vlq": "2.0.4",
     "yargs": "17.6.1"
   }
 }

src/@types/vlq/index.d.ts

@@ -0,0 +1,4 @@
+declare module 'vlq' {
+  export function encode(data: number[]): string;
+  export function decode(str: string): number[];
+}

src/InMemoryLineWriter.ts

@@ -55,4 +55,8 @@ export class InMemoryLineWriter implements LineWriter {
   getIndent(): string {
     return this.#indentation;
   }
+
+  getSize(): number {
+    return this.#lines.length;
+  }
 }

src/LineWriter.ts

@@ -19,4 +19,5 @@ export interface LineWriter {
   startBlock(): LineWriter;
   endBlock(): LineWriter;
   getIndent(): string;
+  getSize(): number;
 }

src/stringify.ts

@@ -19,6 +19,7 @@ import { LineWriter } from './LineWriter.js';
 import { PuppeteerStringifyExtension } from './PuppeteerStringifyExtension.js';
 import type { Step, UserFlow } from './Schema.js';
 import { StringifyExtension } from './StringifyExtension.js';
+import * as vlq from 'vlq';
 
 export interface StringifyOptions {
   extension?: StringifyExtension;
@@ -45,13 +46,21 @@ export async function stringify(
   const out = opts.writer ?? new InMemoryLineWriter(opts.indentation ?? '  ');
 
   await ext.beforeAllSteps?.(out, flow);
+
+  // version, [lineNo, length], [lineNo, length] ...
+  const sourceMap: Array<number> = [1];
   for (const step of flow.steps) {
+    const firstLine = out.getSize();
     await ext.beforeEachStep?.(out, step, flow);
     await ext.stringifyStep(out, step, flow);
     await ext.afterEachStep?.(out, step, flow);
+    const lastLine = out.getSize();
+    sourceMap.push(...[firstLine, lastLine - firstLine]);
   }
   await ext.afterAllSteps?.(out, flow);
 
+  out.appendLine('//# recorderSourceMap=' + vlq.encode(sourceMap));
+
   return out.toString();
 }
 
@@ -75,7 +84,7 @@ export async function stringifyStep(
   if (!opts.indentation) {
     opts.indentation = '  ';
   }
-  const out = new InMemoryLineWriter(opts.indentation);
+  const out = opts.writer ?? new InMemoryLineWriter(opts.indentation ?? '  ');
 
   await ext.beforeEachStep?.(out, step);
   await ext.stringifyStep(out, step);

test/stringify.test.ts

@@ -20,6 +20,7 @@ import { StringifyExtension } from '../src/StringifyExtension.js';
 import { Step, StepType, UserFlow } from '../src/Schema.js';
 import { LineWriter } from '../src/LineWriter.js';
 import snapshot from 'snap-shot-it';
+import * as vlq from 'vlq';
 
 describe('stringify', () => {
   it('should print the correct script for a navigate step', async () => {
@@ -249,8 +250,29 @@ describe('stringify', () => {
         'stringifyStep0',
         'afterStep0',
         'afterAll',
+        '//# recorderSourceMap=CCG',
         '',
       ].join('\n')
     );
   });
+
+  it('should produce a source map', async () => {
+    const flow = {
+      title: 'Test Recording',
+      steps: [
+        {
+          type: StepType.WaitForElement as const,
+          selectors: ['body > div:nth-child(1)'],
+        },
+      ],
+    };
+    const str = await stringify(flow);
+    const sourceMapLine = str
+      .split('\n')
+      .reverse()
+      .find((line) => line.trim() !== '');
+    snapshot(
+      vlq.decode(sourceMapLine?.split('//# recorderSourceMap=').pop() as string)
+    );
+  });
 });

tsconfig.base.json

@@ -24,6 +24,7 @@
     "strictNullChecks": true,
     "strictPropertyInitialization": true,
     "target": "ES2019",
-    "useUnknownInCatchVariables": true
+    "useUnknownInCatchVariables": true,
+    "typeRoots": ["./node_modules/@types", "./src/@types"]
   }
 }