chore: add pkg api shape validation (#7498)

* chore: add pkg api shape validation

* chore: add api validator to precommit and integration

Author: kuhe

package.json

@@ -34,6 +34,7 @@
     "lint:release": "lerna exec --ignore '@aws-sdk/client-*' --ignore '@aws-sdk/aws-*' 'eslint --quiet src/**/*.ts'",
     "lint:versions": "node scripts/runtime-dependency-version-check/runtime-dep-version-check.js",
     "lint:dependencies": "node scripts/runtime-dependency-version-check/check-dependencies.js",
+    "lint:api": "node scripts/validation/api-snapshot-validation.js",
     "local-publish": "node ./scripts/verdaccio-publish/index.js",
     "test:all": "yarn build:all && jest --passWithNoTests && lerna run test --scope '@aws-sdk/{fetch-http-handler,hash-blob-browser}' && yarn test:versions && yarn test:integration",
     "test:ci": "lerna run test --since origin/main",
@@ -134,7 +135,7 @@
   },
   "husky": {
     "hooks": {
-      "pre-commit": "lint-staged && yarn lint:versions && yarn lint:dependencies",
+      "pre-commit": "lint-staged && yarn lint:versions && yarn lint:dependencies && yarn lint:api",
       "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
     }
   },

scripts/validation/api-snapshot-validation.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+/**
+This script uses the JSON file api-snapshot/api.json to validate that previously present symbols
+are still exported by the packages within the assessed group.
+
+Data may only be deleted from api.json in an intentional backwards-incompatible change.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const root = path.join(__dirname, "..", "..");
+const dataPath = path.join(root, "scripts", "validation", "api.json");
+const api = require(dataPath);
+
+api.$schema = "https://json-schema.org/draft/2020-12/schema";
+
+const packageDirs = [
+  ...fs.readdirSync(path.join(root, "packages")).map((f) => path.join(root, "packages", f)),
+  ...fs.readdirSync(path.join(root, "lib")).map((f) => path.join(root, "lib", f)),
+  path.join(root, "clients", "client-s3"), // rest xml
+  path.join(root, "clients", "client-s3-control"), // rest xml
+  path.join(root, "clients", "client-dynamodb"), // json rpc
+  path.join(root, "clients", "client-cloudwatch"), // query
+  path.join(root, "clients", "client-sts"), // query
+  path.join(root, "clients", "client-sagemaker"), // json rpc
+  path.join(root, "clients", "client-bedrock"), // rest json
+];
+const errors = [];
+
+for (const packageRoot of packageDirs) {
+  const pkgJsonPath = path.join(packageRoot, "package.json");
+  const cjsPath = path.join(packageRoot, "dist-cjs", "index.js");
+
+  if (fs.existsSync(pkgJsonPath) && fs.existsSync(cjsPath)) {
+    const packageJson = require(pkgJsonPath);
+    const { name, version } = packageJson;
+    const module = require(cjsPath);
+
+    for (const key of Object.keys(module)) {
+      if (module[key] === undefined) {
+        console.warn(`symbol ${key} in ${name}@${version} has a value of undefined.`);
+      }
+    }
+
+    if (!api[name]) {
+      api[name] = {};
+      for (const key of Object.keys(module)) {
+        api[name][key] = [typeof module[key], `<=${version}`].join(", since ");
+      }
+    } else {
+      for (const symbol of [...new Set([...Object.keys(api[name]), ...Object.keys(module)])]) {
+        if (symbol in module && !(symbol in api[name])) {
+          errors.push(`You must commit changes in api.json.`);
+          api[name][symbol] = [typeof module[symbol], version].join(", since ");
+        }
+        if (!(symbol in module) && symbol in api[name]) {
+          errors.push(`Symbol [${symbol}] is missing from ${name}, (${api[name][symbol]}).`);
+        }
+        if (symbol in module && symbol in api[name]) {
+          if (api[name][symbol].split(", ")[0] !== typeof module[symbol]) {
+            errors.push(
+              `Symbol [${symbol}] has a different type than expected in ${name}, actual=${typeof module[
+                symbol
+              ]} expected=${api[name][symbol]}.`
+            );
+          }
+        }
+      }
+    }
+  }
+}
+
+fs.writeFileSync(dataPath, JSON.stringify(api, null, 2) + "\n");
+
+if (errors.length) {
+  throw new Error(errors.join("\n"));
+} else {
+  console.log(`✅ API snapshot test passed.`);
+}