feat: add comments about generation and 'use strict' to transformed s…

…amples (#3696)

This adds support for adding a comment to generated samples specifying that they're generated, as well as adding the 'use strict' line.

packages/typeless-sample-bot/src/samples.ts

@@ -21,7 +21,8 @@ import {readFile, writeFile} from 'fs/promises';
 import babel from '@babel/core';
 import path from 'node:path';
 import {typescript as presetTypescript} from './preset-loader.js';
-import importToRequire from './import-to-require.js';
+import importToRequire from './transforms/import-to-require.js';
+import {addComments} from './transforms/add-comments.js';
 
 // Converts an async iterable into an array of the same type.
 export async function toArray<T>(iterable: AsyncIterable<T>): Promise<T[]> {
@@ -100,9 +101,11 @@ export async function* transformSamples(
   for await (const s of samples) {
     const config = Object.assign({}, babelConfig, {filename: s.filename});
     const transformed = await babel.transformAsync(s.contents, config);
+    let contents = transformed?.code || '';
+    contents = addComments(contents);
     yield {
       filename: s.filename.replace(/\.ts$/g, '.js'),
-      contents: transformed?.code || '',
+      contents,
     };
   }
 }

packages/typeless-sample-bot/src/transforms/add-comments.ts

@@ -0,0 +1,42 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+const headerText = `
+// This is a generated sample, using the typeless sample bot. Please
+// look for the source TypeScript sample (.ts) for modifications.
+'use strict';
+
+`.trim();
+
+/**
+ * Adds the header comments about the generation of the sample and the
+ * 'use strict' line for JS. Rather than Babel, this just uses simple
+ * text searching. The reason for that is that it's much simpler to do
+ * this particular transform that way. Rather than traversing an AST,
+ * this simply looks for the first blank line and inserts the block there.
+ * If it can't find one, it puts it at the top.
+ */
+export function addComments(text: string): string {
+  text = text.replace('\r', '');
+  const lines = text.split('\n');
+  const firstBlank = lines.findIndex(l => l.length === 0);
+  if (firstBlank < 0) {
+    // Apparently the whole file has no blank lines?
+    return headerText + text + '\n\n';
+  } else {
+    lines.splice(firstBlank, 0, '\n' + headerText);
+  }
+
+  return lines.join('\n');
+}

packages/typeless-sample-bot/test/fixtures/noBlankLines.ts

@@ -0,0 +1,3 @@
+// This file
+// has no
+// blank lines

packages/typeless-sample-bot/test/index.ts

@@ -61,6 +61,34 @@ describe('sample transformation', () => {
 
     snapshot(sOut[0].contents);
   });
+
+  it('correctly adds use strict when the sample has a licence block', async () => {
+    const fixture = await loadFixture('listSchemas.ts');
+
+    const sIn = samples.fromArray([
+      {
+        filename: 'listSchemas.ts',
+        contents: fixture,
+      },
+    ]);
+
+    const sOut = await samples.toArray(samples.transformSamples(sIn));
+    assert.strictEqual(sOut[0].contents.includes('use strict'), true);
+  });
+
+  it('correctly adds use strict when the sample has no blank lines', async () => {
+    const fixture = await loadFixture('noBlankLines.ts');
+
+    const sIn = samples.fromArray([
+      {
+        filename: 'listSchemas.ts',
+        contents: fixture,
+      },
+    ]);
+
+    const sOut = await samples.toArray(samples.transformSamples(sIn));
+    assert.strictEqual(sOut[0].contents.includes('use strict'), true);
+  });
 });
 
 describe('command line option', () => {