feat: add a placeholder README file in codegen'd directory (#774)

* feat(codegen): add a placeholder README file

* test: update fixtures

* test(enhancement): add ability to create new files

* refactor: use storage for timestamp

feedback: #774 (comment)

packages/api/src/codegen/languages/typescript/index.ts

@@ -1,4 +1,3 @@
-import type Storage from '../../../storage.js';
 import type { InstallerOptions } from '../../codegenerator.js';
 import type Oas from 'oas';
 import type Operation from 'oas/operation';
@@ -24,6 +23,8 @@ import semver from 'semver';
 import { IndentationText, Project, QuoteKind, ScriptTarget, VariableDeclarationKind } from 'ts-morph';
 
 import logger from '../../../logger.js';
+import { PACKAGE_VERSION } from '../../../packageInfo.js';
+import Storage from '../../../storage.js';
 import CodeGenerator from '../../codegenerator.js';
 
 import { docblockEscape, generateTypeName, wordWrap } from './util.js';
@@ -200,6 +201,7 @@ export default class TSGenerator extends CodeGenerator {
 
     this.createPackageJSON();
     this.createTSConfig();
+    this.createREADME();
 
     if (Object.keys(this.schemas).length) {
       this.createSchemasFile(srcDirectory);
@@ -237,7 +239,7 @@ export default class TSGenerator extends CodeGenerator {
          *
          * @see {@link https://ts-morph.com/manipulation/formatting}
          */
-        sourceFile.formatText();
+        if (filePath.endsWith('.ts')) sourceFile.formatText();
 
         return {
           [filePath]: sourceFile.getFullText(),
@@ -497,6 +499,35 @@ sdk.server('https://eu.api.example.com/v14');`),
     return sourceFile;
   }
 
+  /**
+   * Create a placeholder `README.md` file in the repository, with information on how to use/administer the SDK.
+   *
+   */
+  createREADME() {
+    let createdAt = new Date().toISOString();
+    const currentAPI = Storage.getLockfile().apis.find(api => api.identifier === this.identifier);
+    if (currentAPI) createdAt = currentAPI.createdAt;
+    const file = `# \`@api/${this.identifier}\`
+
+This SDK was autogenerated by the [\`api\` SDK generator](https://api.readme.dev), powered by [ReadMe](https://readme.com) 🦉
+
+Add SDK setup information and usage examples here so your users get started in a jiffy! 🚀
+
+<!---
+
+Here's some additional info about the generated SDK:
+
+\`api\` version: ${PACKAGE_VERSION}
+Generated at ${createdAt}
+
+--->
+`;
+
+    const sourceFile = this.project.createSourceFile('README.md', file);
+
+    return sourceFile;
+  }
+
   /**
    * Create our main schemas file. This is where all of the JSON Schema that our TypeScript typing
    * infrastructure sources its data from. Without this there are no types.

packages/api/test/codegen/languages/typescript/index.test.ts

@@ -45,7 +45,23 @@ function assertSDKFixture(file: string, fixture: string) {
     // Assert that the files we're generating are what we're expecting in the fixture directory.
     const sortedActualFiles = Object.keys(actualFiles);
     sortedActualFiles.sort();
-    expect(sortedActualFiles).toStrictEqual(expectedFiles);
+
+    // creates new files if they don't exist
+    if (sortedActualFiles.length > expectedFiles.length && process.env.UPDATE_FIXTURES) {
+      await Promise.all(
+        sortedActualFiles.map(actualFileName => {
+          if (!expectedFiles.includes(actualFileName)) {
+            const actualFilePath = path.join(dir, actualFileName);
+            // eslint-disable-next-line no-console
+            console.info('[creating sdk fixture]', actualFilePath);
+            return fs.writeFile(actualFilePath, actualFiles[actualFileName]);
+          }
+          return true;
+        }),
+      );
+    } else {
+      expect(sortedActualFiles).toStrictEqual(expectedFiles);
+    }
 
     // Assert that each generated file is the same as in the fixture.
     await Promise.all(
@@ -79,6 +95,14 @@ function assertSDKFixture(file: string, fixture: string) {
 }
 
 describe('typescript', () => {
+  beforeEach(() => {
+    vi.setSystemTime(new Date('2023'));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
   describe('#install', () => {
     beforeEach(() => {
       Storage.setStorageDir(uniqueTempDir());

packages/test-utils/sdks/alby/README.md

@@ -0,0 +1,14 @@
+# `@api/alby`
+
+This SDK was autogenerated by the [`api` SDK generator](https://api.readme.dev), powered by [ReadMe](https://readme.com) 🦉
+
+Add SDK setup information and usage examples here so your users get started in a jiffy! 🚀
+
+<!---
+
+Here's some additional info about the generated SDK:
+
+`api` version: <<package version>>
+Generated at 2023-01-01T00:00:00.000Z
+
+--->

packages/test-utils/sdks/metrotransit/README.md

@@ -0,0 +1,14 @@
+# `@api/metrotransit`
+
+This SDK was autogenerated by the [`api` SDK generator](https://api.readme.dev), powered by [ReadMe](https://readme.com) 🦉
+
+Add SDK setup information and usage examples here so your users get started in a jiffy! 🚀
+
+<!---
+
+Here's some additional info about the generated SDK:
+
+`api` version: <<package version>>
+Generated at 2023-01-01T00:00:00.000Z
+
+--->

packages/test-utils/sdks/operationid-quirks/README.md

@@ -0,0 +1,14 @@
+# `@api/operationid-quirks`
+
+This SDK was autogenerated by the [`api` SDK generator](https://api.readme.dev), powered by [ReadMe](https://readme.com) 🦉
+
+Add SDK setup information and usage examples here so your users get started in a jiffy! 🚀
+
+<!---
+
+Here's some additional info about the generated SDK:
+
+`api` version: <<package version>>
+Generated at 2023-01-01T00:00:00.000Z
+
+--->

packages/test-utils/sdks/optional-payload/README.md

@@ -0,0 +1,14 @@
+# `@api/optional-payload`
+
+This SDK was autogenerated by the [`api` SDK generator](https://api.readme.dev), powered by [ReadMe](https://readme.com) 🦉
+
+Add SDK setup information and usage examples here so your users get started in a jiffy! 🚀
+
+<!---
+
+Here's some additional info about the generated SDK:
+
+`api` version: <<package version>>
+Generated at 2023-01-01T00:00:00.000Z
+
+--->

packages/test-utils/sdks/petstore/README.md

@@ -0,0 +1,14 @@
+# `@api/petstore`
+
+This SDK was autogenerated by the [`api` SDK generator](https://api.readme.dev), powered by [ReadMe](https://readme.com) 🦉
+
+Add SDK setup information and usage examples here so your users get started in a jiffy! 🚀
+
+<!---
+
+Here's some additional info about the generated SDK:
+
+`api` version: <<package version>>
+Generated at 2023-01-01T00:00:00.000Z
+
+--->

packages/test-utils/sdks/readme/README.md

@@ -0,0 +1,14 @@
+# `@api/readme`
+
+This SDK was autogenerated by the [`api` SDK generator](https://api.readme.dev), powered by [ReadMe](https://readme.com) 🦉
+
+Add SDK setup information and usage examples here so your users get started in a jiffy! 🚀
+
+<!---
+
+Here's some additional info about the generated SDK:
+
+`api` version: <<package version>>
+Generated at 2023-01-01T00:00:00.000Z
+
+--->

packages/test-utils/sdks/response-title-quirks/README.md

@@ -0,0 +1,14 @@
+# `@api/response-title-quirks`
+
+This SDK was autogenerated by the [`api` SDK generator](https://api.readme.dev), powered by [ReadMe](https://readme.com) 🦉
+
+Add SDK setup information and usage examples here so your users get started in a jiffy! 🚀
+
+<!---
+
+Here's some additional info about the generated SDK:
+
+`api` version: <<package version>>
+Generated at 2023-01-01T00:00:00.000Z
+
+--->

packages/test-utils/sdks/simple/README.md

@@ -0,0 +1,14 @@
+# `@api/simple`
+
+This SDK was autogenerated by the [`api` SDK generator](https://api.readme.dev), powered by [ReadMe](https://readme.com) 🦉
+
+Add SDK setup information and usage examples here so your users get started in a jiffy! 🚀
+
+<!---
+
+Here's some additional info about the generated SDK:
+
+`api` version: <<package version>>
+Generated at 2023-01-01T00:00:00.000Z
+
+--->

packages/test-utils/sdks/star-trek/README.md

@@ -0,0 +1,14 @@
+# `@api/star-trek`
+
+This SDK was autogenerated by the [`api` SDK generator](https://api.readme.dev), powered by [ReadMe](https://readme.com) 🦉
+
+Add SDK setup information and usage examples here so your users get started in a jiffy! 🚀
+
+<!---
+
+Here's some additional info about the generated SDK:
+
+`api` version: <<package version>>
+Generated at 2023-01-01T00:00:00.000Z
+
+--->