@W-18575180@ Generate node SDK from OAS

.eslintrc.json

@@ -7,7 +7,6 @@
   "plugins": [
     "@typescript-eslint",
     "@typescript-eslint/eslint-plugin",
-    "tsdoc",
     "header",
     "jsdoc"
   ],
@@ -32,7 +31,7 @@
         "selector": "interface",
         "format": ["PascalCase"],
         "custom": {
-          "regex": "^I[A-Z]",
+          "regex": "^[A-Z]",
           "match": true
         }
       }
@@ -53,7 +52,7 @@
       ]
     ],
     "jsdoc/require-description": [
-      "error",
+      "warn",
       {
         "checkConstructors": false
       }
@@ -76,8 +75,7 @@
     "jsdoc/require-param-type": "off",
     "jsdoc/require-returns-check": "error",
     "jsdoc/require-returns-description": "error",
-    "jsdoc/require-returns-type": "off",
-    "tsdoc/syntax": "error"
+    "jsdoc/require-returns-type": "off"
   },
   "overrides": [
     {

.github/workflows/test.yml

@@ -9,7 +9,7 @@ jobs:
   linux-tests:
     strategy:
       matrix:
-        node: [16, 18, 20, 22]
+        node: [20, 22]
       fail-fast: false
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -66,6 +66,9 @@ dist
 
 .idea
 
+# Openapi-generator generates this when running renderTemplates
+openapitools.json
+
 # Release folders
 renderedTemplates
 .vscode

.nycrc.json

@@ -3,9 +3,11 @@
   "branches": 80,
   "check-coverage": true,
   "exclude": [
-    "src/generate.ts",
     "src/updateApis.ts",
-    "src/lib/config.ts"
+    "src/lib/config.ts",
+    "src/generate-oas.ts",
+    "src/static/helpers/index.ts",
+    "src/lib/utils.ts"
   ],
   "extends": "@istanbuljs/nyc-config-typescript",
   "extension": [

package.json

@@ -19,23 +19,25 @@
   ],
   "scripts": {
     "backupApis": "rm -rf updateApisTmp && mkdir updateApisTmp && mv apis updateApisTmp/oldApis",
-    "build": "npm run clean && npm run renderTemplates && tsc && eslint dist --ext .ts,.js --quiet --fix",
+    "build": "npm run clean && npm run renderTemplates && npm run compile",
+    "ci": "rm -rf node_modules && yarn install",
     "clean": "rm -rf renderedTemplates dist",
+    "compile": "tsc && eslint dist --ext .ts,.js --quiet --fix",
     "depcheck": "depcheck",
-    "diffApis": "raml-toolkit diff --dir updateApisTmp/oldApis apis -f console -o updateApisTmp/ramlDiff.txt",
+    "diffApis": "raml-toolkit diff --dir updateApisTmp/oldApis apis -f console -o updateApisTmp/oasDiff.txt -s oas",
     "doc": "npm run doc:generate && npm run doc:resources",
     "doc:generate": "typedoc --mode modules --out ./docs renderedTemplates/** --tsconfig tsconfig.json --external-modulemap  \".*/renderedTemplates/([\\w\\-_]+)/\"",
     "doc:resources": "cp CHANGELOG.md ./docs",
     "lint": "npm run lint:dev -- --quiet",
     "lint:dev": "sort-package-json && eslint . --ext .ts --fix",
     "prepack": "npm run build",
     "prepare": "snyk protect",
-    "renderTemplates": "ts-node src/generate.ts",
+    "renderTemplates": "PACKAGE_VERSION=$(node -p \"require('./package.json').version\") ts-node src/generate-oas.ts",
     "snyk:auth": "snyk auth",
-    "pretest": "npm run lint && npm run depcheck",
+    "pretest": "npm run lint",
     "test": "nyc mocha \"src/**/*.test.ts\"",
     "test:ci": "npm test -- --reporter=xunit --reporter-options output=./reports/generator.xml",
-    "updateApis": "npm run backupApis && ts-node src/updateApis.ts && git checkout apis/search && npm run diffApis"
+    "updateApis": "npm run backupApis && ts-node src/updateApis.ts && npm run diffApis"
   },
   "mocha": {
     "file": [
@@ -49,7 +51,7 @@
     "tslib": "^2.4.1"
   },
   "devDependencies": {
-    "@commerce-apps/raml-toolkit": "^0.5.12",
+    "@commerce-apps/raml-toolkit": "file:../raml-toolkit",
     "@istanbuljs/nyc-config-typescript": "^1.0.2",
     "@types/chai": "^4.3.0",
     "@types/fs-extra": "^9.0.13",
@@ -65,9 +67,8 @@
     "eslint": "^8.38.0",
     "eslint-config-prettier": "^8.8.0",
     "eslint-plugin-header": "^3.1.1",
-    "eslint-plugin-jsdoc": "^41.1.1",
+    "eslint-plugin-jsdoc": "^50.7.1",
     "eslint-plugin-prettier": "^4.2.1",
-    "eslint-plugin-tsdoc": "^0.2.17",
     "fs-extra": "^9.1.0",
     "handlebars-helpers": "^0.10.0",
     "mocha": "^8.4.0",
@@ -83,6 +84,9 @@
     "typedoc-plugin-nojekyll": "^1.0.1",
     "typescript": "^4.4.4"
   },
+  "resolutions": {
+    "@rdfjs/types": "v1.1.2"
+  },
   "publishConfig": {
     "access": "public"
   },

src/generate-oas.ts

@@ -0,0 +1,223 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import path from "path";
+import fs from "fs-extra";
+import { generateFromOas, download } from "@commerce-apps/raml-toolkit";
+import Handlebars from "handlebars";
+
+type ApiSpecDetail = {
+  filepath: string;
+  filename: string;
+  name: string;
+  apiName: string;
+  directoryName: string;
+};
+
+const API_DIRECTORY = path.resolve(`${__dirname}/../apis`);
+const STATIC_DIRECTORY = path.join(__dirname, "./static");
+const TARGET_DIRECTORY = path.resolve(`${__dirname}/../renderedTemplates`);
+const TEMPLATE_DIRECTORY = path.resolve(`${__dirname}/../templatesOas`);
+const INDEX_TEMPLATE_LOCATION = path.resolve(
+  `${__dirname}/../templates/index.ts.hbs`
+);
+const VERSION_TEMPLATE_LOCATION = path.resolve(
+  `${__dirname}/../templates/version.ts.hbs`
+);
+
+function kebabToCamelCase(str: string): string {
+  return str.replace(/-([a-z])/g, (match, letter: string) =>
+    letter.toUpperCase()
+  );
+}
+
+/**
+ * Helper function. Also contains explicit workaround for some API names.
+ */
+export function resolveApiName(name: string): string {
+  if (name === "Shopper orders OAS") {
+    return "ShopperOrders";
+  }
+  if (name === "CDN API - Process APIs OAS") {
+    return "CDNZones";
+  }
+  if (name === "SLAS Admin-UAP OAS") {
+    return "SlasAdmin";
+  }
+  if (name === "Shopper Seo OAS") {
+    return "ShopperSEO";
+  }
+  if (name === "Shopper Context OAS") {
+    return "ShopperContexts";
+  }
+  if (name === "Catalogs OAS") {
+    return "CatalogsAPI";
+  }
+  if (name === "Cors Preferences OAS") {
+    return "CORSPreferences";
+  }
+  return name.replace(/\s+/g, "").replace("OAS", "");
+}
+
+/**
+ * Helper that reads api details from exchange.json
+ */
+export function getAPIDetailsFromExchange(directory: string): ApiSpecDetail {
+  const exchangePath = path.join(directory, "exchange.json");
+  if (fs.existsSync(exchangePath)) {
+    const exchangeConfig = fs.readJSONSync(
+      exchangePath
+    ) as download.ExchangeConfig;
+
+    // Special handling for shopper-baskets-v2
+    if (
+      exchangeConfig.assetId === "shopper-baskets-oas" &&
+      exchangeConfig.apiVersion === "v2"
+    ) {
+      return {
+        filepath: path.join(directory, exchangeConfig.main),
+        filename: exchangeConfig.main,
+        directoryName: "ShopperBasketsV2",
+        name: "Shopper Baskets V2 OAS",
+        apiName: "ShopperBasketsV2",
+      };
+    }
+
+    return {
+      filepath: path.join(directory, exchangeConfig.main),
+      filename: exchangeConfig.main,
+      directoryName: kebabToCamelCase(
+        exchangeConfig.assetId.replace("-oas", "")
+      ),
+      name: exchangeConfig.name,
+      apiName: resolveApiName(exchangeConfig.name),
+    };
+  }
+  throw new Error(`Exchange file does not exist for ${directory}`);
+}
+
+/**
+ * Invokes openapi-generator via raml-toolkit to generate SDKs
+ */
+export function generateSDKs(apiSpecDetail: ApiSpecDetail): void {
+  const { filepath, name, directoryName } = apiSpecDetail;
+  if (fs.statSync(filepath).isFile()) {
+    try {
+      console.log(`Generating SDK for ${name}`);
+      const outputDir = `${TARGET_DIRECTORY}/${directoryName}`;
+      generateFromOas.generateFromOas({
+        inputSpec: `${filepath}`,
+        outputDir: `${outputDir}`,
+        templateDir: `${TEMPLATE_DIRECTORY}`,
+        flags: `--reserved-words-mappings delete=delete`,
+      });
+    } catch (error) {
+      // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+      console.error(`Error generating SDK for ${name}: ${error}`);
+    }
+  }
+}
+
+/**
+ * Generates the top level index file
+ */
+export function generateIndex(context: {
+  children: ApiSpecDetail[] | { name: string; apiName: string }[];
+}): void {
+  const indexTemplate = fs.readFileSync(INDEX_TEMPLATE_LOCATION, "utf8");
+  const generatedIndex = Handlebars.compile(indexTemplate)(context);
+  fs.writeFileSync(`${TARGET_DIRECTORY}/index.ts`, generatedIndex);
+}
+
+/**
+ * Generates the version file
+ */
+export function generateVersionFile(): void {
+  const version = process.env.PACKAGE_VERSION || 'unknown';
+  const versionTemplate = fs.readFileSync(VERSION_TEMPLATE_LOCATION, 'utf8');
+  const generatedVersion = Handlebars.compile(versionTemplate)({
+    metadata: {sdkVersion: version},
+  });
+  fs.writeFileSync(`${TARGET_DIRECTORY}/version.ts`, generatedVersion);
+}
+
+
+function getAllDirectoriesWithExchangeFiles(basePath: string, relativePath = ""): string[] {
+  const fullPath = path.join(basePath, relativePath);
+  const directories: string[] = [];
+
+  try {
+    const items = fs.readdirSync(fullPath);
+
+    for (const item of items) {
+      const itemPath = path.join(fullPath, item);
+      const relativeItemPath = relativePath
+        ? path.join(relativePath, item)
+        : item;
+
+      if (fs.lstatSync(itemPath).isDirectory()) {
+        if (fs.existsSync(path.join(itemPath, "exchange.json"))) {
+          directories.push(relativeItemPath);
+        }
+        directories.push(...getAllDirectoriesWithExchangeFiles(basePath, relativeItemPath));
+      }
+    }
+  } catch (error) {
+    console.warn(`Warning: Could not read directory ${fullPath}:`, error);
+  }
+
+  return directories;
+}
+
+/**
+ * Copies the static files to the target directory
+ */
+export function copyStaticFiles(): void {
+  const skipTestFiles = (src: string): boolean => !/\.test\.[a-z]+$/.test(src);
+  fs.copySync(STATIC_DIRECTORY, TARGET_DIRECTORY, { filter: skipTestFiles });
+}
+
+/**
+ * Main function
+ */
+export function main(): void {
+  console.log("Starting OAS generation script");
+  fs.readdir(API_DIRECTORY, (err: Error, directories: string[]) => {
+    if (err) {
+      console.error("Error reading api directory:", err);
+      return;
+    }
+
+    const apiSpecDetails: ApiSpecDetail[] = [];
+    const subDirectories: string[] = getAllDirectoriesWithExchangeFiles(API_DIRECTORY);
+
+    subDirectories.forEach((directory: string) => {
+      try {
+        const details = getAPIDetailsFromExchange(
+          path.join(API_DIRECTORY, directory)
+        );
+        apiSpecDetails.push(details);
+      } catch (error) {
+        console.log(`Skipping directory ${directory}: ${error}`);
+      }
+    });
+
+    apiSpecDetails.forEach((apiSpecDetail: ApiSpecDetail) => {
+      generateSDKs(apiSpecDetail);
+    });
+
+    generateIndex({ children: apiSpecDetails });
+    generateVersionFile();
+    copyStaticFiles();
+
+    console.log(
+      `OAS generation script completed. Files outputted to ${TARGET_DIRECTORY}`
+    );
+  });
+}
+
+main();