feat: generate recorder sourcemaps

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=aIiBMuBaoCYgDiB
 
 `;

__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"]
   }
 }