feat(clients): generate code snippets from cts (#2511)

.github/workflows/check.yml

@@ -289,7 +289,7 @@ jobs:
         run: yarn cli cts run javascript
 
       - name: Zip artifact before storing
-        run: zip -r -y clients-javascript.zip clients/algoliasearch-client-javascript ${{ fromJSON(needs.setup.outputs.JAVASCRIPT_DATA).testsToStore }} -x "**/node_modules**" "**/.yarn/cache/**" "**/.yarn/install-state.gz" "**/build/**" "**/dist/**" "**/.gradle/**" "**/bin/**" "**/.nx/**"
+        run: zip -r -y clients-javascript.zip clients/algoliasearch-client-javascript ${{ fromJSON(needs.setup.outputs.JAVASCRIPT_DATA).testsToStore }} ${{ fromJSON(needs.setup.outputs.JAVASCRIPT_DATA).snippetsToStore }} -x "**/node_modules**" "**/.yarn/cache/**" "**/.yarn/install-state.gz" "**/build/**" "**/dist/**" "**/.gradle/**" "**/bin/**" "**/.nx/**"
 
       - name: Store javascript clients
         uses: actions/upload-artifact@v4
@@ -367,7 +367,7 @@ jobs:
         run: yarn cli cts run ${{ matrix.client.language }}
 
       - name: Zip artifact before storing
-        run: zip -r -y clients-${{ matrix.client.language }}.zip ${{ matrix.client.path }} ${{ matrix.client.testsToStore }} -x "**/node_modules**" "**/__pycache__/**" "**/.yarn/cache/**" "**/build/**" "**/dist/**" "**/.gradle/**" "**/bin/**" "**/vendor/**" "**/target/**" "**/.dart_tool/**"
+        run: zip -r -y clients-${{ matrix.client.language }}.zip ${{ matrix.client.path }} ${{ matrix.client.testsToStore }} ${{ matrix.client.snippetsToStore }} -x "**/node_modules**" "**/__pycache__/**" "**/.yarn/cache/**" "**/build/**" "**/dist/**" "**/.gradle/**" "**/bin/**" "**/vendor/**" "**/target/**" "**/.dart_tool/**"
 
       - name: Store ${{ matrix.client.language }} clients
         uses: actions/upload-artifact@v4

config/clients.config.json

@@ -20,6 +20,10 @@
     "tests": {
       "extension": ".test.java",
       "outputFolder": "src/test/java/com/algolia"
+    },
+    "snippets": {
+      "extension": ".java",
+      "outputFolder": "src/test/java/com/algolia"
     }
   },
   "javascript": {
@@ -75,6 +79,10 @@
     "tests": {
       "extension": ".test.ts",
       "outputFolder": "src"
+    },
+    "snippets": {
+      "extension": ".ts",
+      "outputFolder": "src"
     }
   },
   "php": {
@@ -98,6 +106,10 @@
     "tests": {
       "extension": "Test.php",
       "outputFolder": "src"
+    },
+    "snippets": {
+      "extension": ".php",
+      "outputFolder": "src"
     }
   },
   "go": {
@@ -197,6 +209,10 @@
     "tests": {
       "extension": "_test.py",
       "outputFolder": "tests"
+    },
+    "snippets": {
+      "extension": ".py",
+      "outputFolder": ""
     }
   },
   "ruby": {

config/generation.config.mjs

@@ -3,6 +3,7 @@ export const patterns = [
   'specs/bundled/*.yml',
 
   'clients/**',
+  'snippets/**',
   '!clients/README.md',
   '!clients/**/.openapi-generator-ignore',
 
@@ -16,6 +17,7 @@ export const patterns = [
   'tests/output/java/build.gradle',
 
   // JavaScript
+  '!snippets/javascript/*.json',
   '!clients/algoliasearch-client-javascript/*',
   '!clients/algoliasearch-client-javascript/.github/**',
   '!clients/algoliasearch-client-javascript/.yarn/**',
@@ -78,6 +80,7 @@ export const patterns = [
   '!clients/algoliasearch-client-dart/packages/algoliasearch/lib/algoliasearch.dart',
 
   // Python
+  '!snippets/python/pyproject.toml',
   'clients/algoliasearch-client-python/**',
   '!clients/algoliasearch-client-python/algoliasearch/http/**',
   '!clients/algoliasearch-client-python/algoliasearch/py.typed',

generators/src/main/java/com/algolia/codegen/cts/AlgoliaCTSGenerator.java

@@ -3,6 +3,7 @@
 import com.algolia.codegen.cts.lambda.*;
 import com.algolia.codegen.cts.manager.CTSManager;
 import com.algolia.codegen.cts.manager.CTSManagerFactory;
+import com.algolia.codegen.cts.snippets.*;
 import com.algolia.codegen.cts.tests.*;
 import com.algolia.codegen.exceptions.*;
 import com.algolia.codegen.utils.*;
@@ -53,12 +54,12 @@ public void processOpts() {
     String outputFolder = Helpers.getClientConfigField(language, "tests", "outputFolder");
     String extension = Helpers.getClientConfigField(language, "tests", "extension");
 
-    setTemplateDir("templates/" + language + "/tests");
-    setOutputDir("tests/output/" + language);
+    setTemplateDir("templates/" + language);
     ctsManager.addSupportingFiles(supportingFiles);
 
     testsGenerators.add(new TestsRequest(language, client));
     testsGenerators.add(new TestsClient(language, client));
+    testsGenerators.add(new SnippetsGenerator(language, client));
 
     for (TestsGenerator testGen : testsGenerators) {
       testGen.addSupportingFiles(supportingFiles, outputFolder, extension);

generators/src/main/java/com/algolia/codegen/cts/manager/DartCTSManager.java

@@ -2,11 +2,9 @@
 
 import com.algolia.codegen.exceptions.GeneratorException;
 import com.algolia.codegen.utils.*;
-import java.util.List;
 import java.util.Map;
 import org.apache.commons.lang3.StringUtils;
 import org.apache.commons.text.WordUtils;
-import org.openapitools.codegen.SupportingFile;
 
 public class DartCTSManager implements CTSManager {
 
@@ -16,11 +14,6 @@ public DartCTSManager(String clientName) {
     this.clientName = clientName;
   }
 
-  @Override
-  public void addSupportingFiles(List<SupportingFile> supportingFiles) {
-    // NO-OP
-  }
-
   @Override
   public void addDataToBundle(Map<String, Object> bundle) throws GeneratorException {
     bundle.put("packageVersion", Helpers.getClientConfigField("dart", "packageVersion"));

generators/src/main/java/com/algolia/codegen/cts/manager/GoCTSManager.java

@@ -8,7 +8,7 @@ public class GoCTSManager implements CTSManager {
 
   @Override
   public void addSupportingFiles(List<SupportingFile> supportingFiles) {
-    supportingFiles.add(new SupportingFile("common.mustache", "tests/requests", "common.go"));
+    supportingFiles.add(new SupportingFile("tests/common.mustache", "tests/output/go/tests/requests", "common.go"));
   }
 
   @Override

generators/src/main/java/com/algolia/codegen/cts/manager/JavaCTSManager.java

@@ -15,7 +15,8 @@ public JavaCTSManager(String client) {
 
   @Override
   public void addSupportingFiles(List<SupportingFile> supportingFiles) {
-    supportingFiles.add(new SupportingFile("build.mustache", "", "build.gradle"));
+    supportingFiles.add(new SupportingFile("tests/build.mustache", "tests/output/java", "build.gradle"));
+    supportingFiles.add(new SupportingFile("tests/build.mustache", "snippets/java", "build.gradle"));
   }
 
   @Override

generators/src/main/java/com/algolia/codegen/cts/manager/JavascriptCTSManager.java

@@ -16,7 +16,7 @@ public JavascriptCTSManager(String client) {
 
   @Override
   public void addSupportingFiles(List<SupportingFile> supportingFiles) {
-    supportingFiles.add(new SupportingFile("package.mustache", "", "package.json"));
+    supportingFiles.add(new SupportingFile("tests/package.mustache", "tests/output/javascript", "package.json"));
   }
 
   @Override

generators/src/main/java/com/algolia/codegen/cts/manager/KotlinCTSManager.java

@@ -2,9 +2,7 @@
 
 import com.algolia.codegen.exceptions.GeneratorException;
 import com.algolia.codegen.utils.*;
-import java.util.List;
 import java.util.Map;
-import org.openapitools.codegen.SupportingFile;
 
 public class KotlinCTSManager implements CTSManager {
 
@@ -14,11 +12,6 @@ public KotlinCTSManager(String client) {
     this.client = client;
   }
 
-  @Override
-  public void addSupportingFiles(List<SupportingFile> supportingFiles) {
-    // NO-OP
-  }
-
   @Override
   public void addDataToBundle(Map<String, Object> bundle) throws GeneratorException {
     bundle.put("packageVersion", Helpers.getClientConfigField("kotlin", "packageVersion"));

generators/src/main/java/com/algolia/codegen/cts/manager/PhpCTSManager.java

@@ -1,14 +1,5 @@
 package com.algolia.codegen.cts.manager;
 
-import com.algolia.codegen.exceptions.GeneratorException;
 import java.util.*;
-import org.openapitools.codegen.SupportingFile;
 
-public class PhpCTSManager implements CTSManager {
-
-  @Override
-  public void addSupportingFiles(List<SupportingFile> supportingFiles) {}
-
-  @Override
-  public void addDataToBundle(Map<String, Object> bundle) throws GeneratorException {}
-}
+public class PhpCTSManager implements CTSManager {}

generators/src/main/java/com/algolia/codegen/cts/manager/PythonCTSManager.java

@@ -15,9 +15,9 @@ public PythonCTSManager(String client) {
 
   @Override
   public void addSupportingFiles(List<SupportingFile> supportingFiles) {
-    supportingFiles.add(new SupportingFile("__init__.mustache", "tests/", "__init__.py"));
-    supportingFiles.add(new SupportingFile("__init__.mustache", "tests/requests", "__init__.py"));
-    supportingFiles.add(new SupportingFile("__init__.mustache", "tests/client", "__init__.py"));
+    supportingFiles.add(new SupportingFile("tests/__init__.mustache", "tests/output/python/tests/", "__init__.py"));
+    supportingFiles.add(new SupportingFile("tests/__init__.mustache", "tests/output/python/tests/requests", "__init__.py"));
+    supportingFiles.add(new SupportingFile("tests/__init__.mustache", "tests/output/python/tests/client", "__init__.py"));
   }
 
   @Override

generators/src/main/java/com/algolia/codegen/cts/snippets/SnippetsGenerator.java

@@ -0,0 +1,50 @@
+package com.algolia.codegen.cts.snippets;
+
+import com.algolia.codegen.cts.tests.*;
+import com.algolia.codegen.utils.*;
+import java.io.File;
+import java.util.*;
+import org.openapitools.codegen.CodegenModel;
+import org.openapitools.codegen.CodegenOperation;
+import org.openapitools.codegen.SupportingFile;
+
+public class SnippetsGenerator extends TestsRequest {
+
+  public SnippetsGenerator(String language, String client) {
+    super(language, client);
+  }
+
+  @Override
+  public boolean available() {
+    File templates = new File("templates/" + language + "/snippets/method.mustache");
+    return templates.exists();
+  }
+
+  @Override
+  public void addSupportingFiles(List<SupportingFile> supportingFiles, String outputFolder, String extension) {
+    if (!available()) {
+      return;
+    }
+
+    extension = Helpers.getClientConfigField(language, "snippets", "extension");
+    outputFolder = Helpers.getClientConfigField(language, "snippets", "outputFolder");
+
+    if (!outputFolder.equals("")) {
+      outputFolder = "/" + outputFolder + "/";
+    } else {
+      outputFolder = "/";
+    }
+
+    supportingFiles.add(
+      new SupportingFile(
+        "snippets/method.mustache",
+        "snippets/" + language + outputFolder + Helpers.createClientName(client, language) + extension
+      )
+    );
+  }
+
+  @Override
+  public void run(Map<String, CodegenModel> models, Map<String, CodegenOperation> operations, Map<String, Object> bundle) throws Exception {
+    super.run(models, operations, bundle);
+  }
+}

generators/src/main/java/com/algolia/codegen/cts/tests/TestsClient.java

@@ -36,7 +36,11 @@ public void addSupportingFiles(List<SupportingFile> supportingFiles, String outp
       return;
     }
     supportingFiles.add(
-      new SupportingFile("client/suite.mustache", outputFolder + "/client", Helpers.createClientName(client, language) + extension)
+      new SupportingFile(
+        "tests/client/suite.mustache",
+        "tests/output/" + language + "/" + outputFolder + "/client",
+        Helpers.createClientName(client, language) + extension
+      )
     );
   }
 

generators/src/main/java/com/algolia/codegen/cts/tests/TestsRequest.java

@@ -36,7 +36,11 @@ public void addSupportingFiles(List<SupportingFile> supportingFiles, String outp
       return;
     }
     supportingFiles.add(
-      new SupportingFile("requests/requests.mustache", outputFolder + "/requests", Helpers.createClientName(client, language) + extension)
+      new SupportingFile(
+        "tests/requests/requests.mustache",
+        "tests/output/" + language + "/" + outputFolder + "/requests",
+        Helpers.createClientName(client, language) + extension
+      )
     );
   }
 
@@ -149,6 +153,11 @@ public void run(Map<String, CodegenModel> models, Map<String, CodegenOperation>
       Map<String, Object> testObj = new HashMap<>();
       testObj.put("tests", tests);
       testObj.put("operationId", operationId);
+
+      Map<String, Object> snippet = (Map<String, Object>) tests.get(0);
+      snippet.put("description", snippet.get("testName"));
+      testObj.put("snippet", snippet);
+
       blocks.add(testObj);
     }
     bundle.put("blocksRequests", blocks);

scripts/ci/githubActions/createMatrix.ts

@@ -91,6 +91,8 @@ async function createClientMatrix(baseBranch: string): Promise<void> {
       })
       .join(' ');
 
+    const snippetsToStore = `snippets/${language}`;
+
     const toRun = matrix[language].toRun.join(' ');
     let buildCommand = `yarn cli build clients ${language} ${toRun}`;
 
@@ -136,6 +138,7 @@ async function createClientMatrix(baseBranch: string): Promise<void> {
       testsRootFolder,
       testsToDelete,
       testsToStore,
+      snippetsToStore,
     });
   }
 

scripts/ci/githubActions/types.ts

@@ -45,6 +45,10 @@ export type ClientMatrix = BaseMatrix & {
    * The test output path to store in the artifact.
    */
   testsToStore: string;
+  /**
+   * The snippets output path to store in the artifact.
+   */
+  snippetsToStore: string;
 };
 
 export type SpecMatrix = Pick<BaseMatrix, 'cacheKey' | 'toRun'> & {

scripts/cts/generate.ts

@@ -1,5 +1,5 @@
 import { buildSpecs } from '../buildSpecs.js';
-import { buildCustomGenerators, CI, run, toAbsolutePath } from '../common.js';
+import { buildCustomGenerators, CI, exists, run, toAbsolutePath } from '../common.js';
 import { getTestOutputFolder } from '../config.js';
 import { formatter } from '../formatter.js';
 import { generateOpenapitools } from '../pre-gen/index.js';
@@ -43,6 +43,9 @@ export async function ctsGenerateMany(generators: Generator[]): Promise<void> {
       await run('YARN_ENABLE_IMMUTABLE_INSTALLS=false yarn install', {
         cwd: 'tests/output/javascript',
       });
+      await run('YARN_ENABLE_IMMUTABLE_INSTALLS=false yarn install', {
+        cwd: 'snippets/javascript',
+      });
     }
 
     if (lang === 'go') {
@@ -52,5 +55,10 @@ export async function ctsGenerateMany(generators: Generator[]): Promise<void> {
     }
 
     await formatter(lang, toAbsolutePath(`tests/output/${lang}`));
+
+    const snippetsPath = toAbsolutePath(`snippets/${lang}`);
+    if (await exists(snippetsPath)) {
+      await formatter(lang, snippetsPath);
+    }
   }
 }

snippets/javascript/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "javascript-snippets",
+  "version": "1.0.0",
+  "dependencies": {
+    "@algolia/client-abtesting": "link:../../clients/algoliasearch-client-javascript/packages/client-abtesting",
+    "@algolia/client-analytics": "link:../../clients/algoliasearch-client-javascript/packages/client-analytics",
+    "@algolia/client-common": "link:../../clients/algoliasearch-client-javascript/packages/client-common",
+    "@algolia/client-insights": "link:../../clients/algoliasearch-client-javascript/packages/client-insights",
+    "@algolia/client-personalization": "link:../../clients/algoliasearch-client-javascript/packages/client-personalization",
+    "@algolia/client-query-suggestions": "link:../../clients/algoliasearch-client-javascript/packages/client-query-suggestions",
+    "@algolia/client-search": "link:../../clients/algoliasearch-client-javascript/packages/client-search",
+    "@algolia/ingestion": "link:../../clients/algoliasearch-client-javascript/packages/ingestion",
+    "@algolia/monitoring": "link:../../clients/algoliasearch-client-javascript/packages/monitoring",
+    "@algolia/recommend": "link:../../clients/algoliasearch-client-javascript/packages/recommend",
+    "@algolia/requester-node-http": "link:../../clients/algoliasearch-client-javascript/packages/requester-node-http",
+    "algoliasearch": "link:../../clients/algoliasearch-client-javascript/packages/algoliasearch"
+  }
+}

snippets/javascript/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../config/base.tsconfig.json",
+  "compilerOptions": {
+    "typeRoots": ["../../node_modules/@types"],
+    "types": ["node", "jest"],
+    "lib": ["dom", "esnext"],
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["dist", "node_modules"]
+}