add @save annotation support for variable declaration statements (#68)

This PR extends the `@save` annotation functionality to variables &
constants

Algorithm:
1. Get all variable/constant declarations
([link](6defceb#diff-21ac06960a99cc021392aabfef047efd6b0aa04eff1dbdc351fc10602d195421))
2. Preserve saved variables &
constants([link](dc21245#diff-3e1cfc841d953f0811ae81c0a75b5484a5596ba9c3e80d6396f69c7954cfaec1))

Author: gneeri

changelog.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Extend @save annotation support for variable declaration statements ([#68](https://github.com/hasura/ndc-open-api-lambda/pull/68))
+
 ## [[1.1.0](https://github.com/hasura/ndc-open-api-lambda/releases/tag/v1.1.0)] 2024-11-28
 
 - Read the value of `NDC_OAS_BASE_URL` at runtime instead of build time ([#66](https://github.com/hasura/ndc-open-api-lambda/pull/66))

docs/documentation.md

@@ -14,7 +14,11 @@ This connector is published as a Docker Image. The image name is `ghcr.io/hasura
 
 ### Saving User Changes
 
-When re-introspecting the connector, user changes in `functions.ts` can be preserved by adding an `@save` JS Doc Tag to the documentation comment of a function. This will ensure that that function is not overwritten and the saved function will be added if missing in the newly generated `functions.ts`
+When re-introspecting the connector, user changes in `functions.ts` can be preserved by adding an `@save` JS Doc Tag to the documentation comment of a statement. `@save` is currently supported for the following statements:
+- functions
+- variable/constant declarations. 
+
+This will ensure that the statements marked with `@save` are not overwritten and the saved statements will be added if missing in the newly generated `functions.ts`
 
 Example
 
@@ -26,6 +30,12 @@ Example
 function mutateResponse(response: ApiResponseObject) {
   response.description = "This API does some work. I hope that's helpful";
 }
+
+/**
+ * localhost url for testing APIs
+ * @save
+ */
+const localApiBaseUrl = "http://localhost:8080"
 ```
 
 ### Usage without the DDN CLI

src/app/parser/typescript/index.ts

@@ -7,20 +7,38 @@ export function preserveUserChanges(
   staleContent: string,
   freshContent: string,
 ): string {
-  const staleProject = new ts.Project();
+  let staleProject = new ts.Project();
 
-  const staleSourceFile = staleProject.createSourceFile(
+  let staleSourceFile = staleProject.createSourceFile(
     path.resolve(context.getInstance().getOutputDirectory(), "stale.ts"),
     staleContent,
   );
 
-  const freshProject = new ts.Project();
-  const freshSourceFile = freshProject.createSourceFile(
+  let freshProject = new ts.Project();
+  let freshSourceFile = freshProject.createSourceFile(
     path.resolve(context.getInstance().getOutputDirectory(), "fresh.ts"),
     freshContent,
   );
 
   morph.preserveSavedFunctions(staleSourceFile, freshSourceFile);
 
+  // recalcuate nodes
+  staleContent = staleSourceFile.getFullText();
+  freshContent = freshSourceFile.getFullText();
+
+  staleProject = new ts.Project();
+  staleSourceFile = staleProject.createSourceFile(
+    path.resolve(context.getInstance().getOutputDirectory(), "stale.ts"),
+    staleContent,
+  );
+
+  freshProject = new ts.Project();
+  freshSourceFile = freshProject.createSourceFile(
+    path.resolve(context.getInstance().getOutputDirectory(), "fresh.ts"),
+    freshContent,
+  );
+
+  morph.preserveSavedVariables(staleSourceFile, freshSourceFile);
+
   return freshSourceFile.getFullText();
 }

src/app/parser/typescript/morph.test.ts

@@ -13,38 +13,63 @@ type TestCase = {
   mergedFileContents?: string;
 };
 
-const tests: TestCase[] = [
+const functionTests: TestCase[] = [
   {
     name: "Add and Replace",
-    directory: "./test-data/morph-tests/add-and-replace/",
+    directory: "./test-data/morph-tests/functions/add-and-replace/",
   },
   {
     name: "No change",
-    directory: "./test-data/morph-tests/no-change/",
+    directory: "./test-data/morph-tests/functions/no-change/",
   },
 ];
 
 describe("morph::preserveSavedFunctions", async () => {
-  for (const testCase of tests) {
+  for (const testCase of functionTests) {
     before(function () {
-      testCase.directory = path.resolve(__dirname, testCase.directory);
-      const staleProject = new ts.Project();
-      testCase.staleSourceFile = staleProject.addSourceFileAtPath(
-        path.resolve(testCase.directory, "stale.ts"),
+      setupTest(testCase);
+    });
+
+    it(testCase.name, async () => {
+      morph.preserveSavedFunctions(
+        testCase.staleSourceFile!,
+        testCase.freshSourceFile!,
       );
 
-      const freshProject = new ts.Project();
-      testCase.freshSourceFile = freshProject.addSourceFileAtPath(
-        path.resolve(testCase.directory, "fresh.ts"),
+      const gotStr = await prettier.format(
+        testCase.freshSourceFile?.getFullText()!,
+        {
+          parser: "typescript",
+        },
       );
 
-      testCase.mergedFileContents = fs
-        .readFileSync(path.resolve(testCase.directory, "merged.ts"))
-        .toString();
+      assert.equal(testCase.mergedFileContents, gotStr);
+
+      // uncomment to update merged golden file
+      // fs.writeFileSync(path.resolve(testCase.directory, "merged.ts"), gotStr);
+    });
+  }
+});
+
+const variableTests: TestCase[] = [
+  {
+    name: "Add and Replace",
+    directory: "./test-data/morph-tests/variables/add-and-replace/",
+  },
+  {
+    name: "No change",
+    directory: "./test-data/morph-tests/variables/no-change/",
+  },
+];
+
+describe("morph::preserveSavedVariables", async () => {
+  for (const testCase of variableTests) {
+    before(function () {
+      setupTest(testCase);
     });
 
     it(testCase.name, async () => {
-      morph.preserveSavedFunctions(
+      morph.preserveSavedVariables(
         testCase.staleSourceFile!,
         testCase.freshSourceFile!,
       );
@@ -63,3 +88,20 @@ describe("morph::preserveSavedFunctions", async () => {
     });
   }
 });
+
+function setupTest(testCase: TestCase) {
+  testCase.directory = path.resolve(__dirname, testCase.directory);
+  const staleProject = new ts.Project();
+  testCase.staleSourceFile = staleProject.addSourceFileAtPath(
+    path.resolve(testCase.directory, "stale.ts"),
+  );
+
+  const freshProject = new ts.Project();
+  testCase.freshSourceFile = freshProject.addSourceFileAtPath(
+    path.resolve(testCase.directory, "fresh.ts"),
+  );
+
+  testCase.mergedFileContents = fs
+    .readFileSync(path.resolve(testCase.directory, "merged.ts"))
+    .toString();
+}

src/app/parser/typescript/morph.ts

@@ -36,3 +36,35 @@ export function preserveSavedFunctions(
     }
   });
 }
+
+/**
+ * this function preserves @save variables from a stale source file to a new/fresh source file
+ * @param staleTsSourceFile the old TS source, which has the @save variables that should be preserved
+ * @param freshTsSourceFile the new TS source, to which the @save variables will copied over to
+ */
+export function preserveSavedVariables(
+  staleTsSourceFile: tsMorph.SourceFile,
+  freshTsSourceFile: tsMorph.SourceFile,
+) {
+  const staleSourceVariables = walk.getAllVariablesMap(staleTsSourceFile);
+  const freshSourceVariables = walk.getAllVariablesMap(freshTsSourceFile);
+
+  staleSourceVariables.forEach((staleVariable, staleVariableName) => {
+    if (!walk.isNodeSaved(staleVariable)) {
+      return;
+    }
+
+    const freshVariable = freshSourceVariables.get(staleVariableName);
+
+    // case 1: @save variable exists in the fresh source file
+    if (freshVariable) {
+      // in this case, the variable should be replaced with the stale variable
+      freshVariable.replaceWithText(staleVariable.getFullText());
+    } 
+  else {
+      // case 2: @save variable does not exist in the new/fresh ts source file
+      // in this case, we add the @save variable to the fresh ts source file
+      freshTsSourceFile.addStatements(staleVariable.getFullText());
+    }
+  });
+}

src/app/parser/typescript/test-data/morph-tests/add-and-replace/fresh.ts renamed to src/app/parser/typescript/test-data/morph-tests/functions/add-and-replace/fresh.ts

@@ -0,0 +1,61 @@
+import path from "path";
+
+// ------ const tests ------
+
+const constSavedApi = {
+  baseUrl: "hello world!",
+  params: {},
+};
+
+const constApi = {
+  baseUrl: "https://production.my-api.com",
+  params: {
+    headers: {
+      "Content-Type": "application/xml",
+    },
+  },
+};
+
+const constNumbers: number[] = [1, 22, 678, 4, 500000];
+
+const constSavedNumbers: number[] = [0, 0, 456];
+
+// ------ var tests ------
+
+var varSavedApi = {
+  baseUrl: "hello world!",
+  params: {},
+};
+
+var varApi = {
+  baseUrl: "https://production.my-api.com",
+  params: {
+    headers: {
+      "Content-Type": "application/xml",
+    },
+  },
+};
+
+var varNumbers: number[] = [1, 22, 678, 4, 500000];
+
+var varSavedNumbers: number[] = [0, 0, 456];
+
+// ------ let tests ------
+
+let letSavedApi = {
+  baseUrl: "hello world!",
+  params: {},
+};
+
+let letApi = {
+  baseUrl: "https://production.my-api.com",
+  params: {
+    headers: {
+      "Content-Type": "application/xml",
+    },
+  },
+};
+
+let letNumbers: number[] = [1, 22, 678, 4, 500000];
+
+let letSavedNumbers: number[] = [0, 0, 456];