fix(spec): pre-compile JSON schema validators at build time (#5039)

The `@jsii/spec` package currently compiles JSON schemas into validators at runtime using `ajv`. This happens every time the validators are called, which adds unnecessary overhead during jsii compilation and when loading assemblies.

Every now and then we are also seeing users getting the following error. While I am not entirely clear on what is causing it (maybe some confused dependency tree?), getting rid of `ajv` completely will solve this.
```
TypeError: ajv_1.default is not a constructor
  at loadAssemblyFromFile (node_modules\@jsii\spec\lib\assembly-utils.js:139:15)
```

This change pre-compiles the validators during the build process using [Ajv's standalone code generation feature](https://ajv.js.org/standalone.html). The generated JavaScript code is a self-contained validator that doesn't require the `ajv` library at runtime. This approach has two benefits: it eliminates the schema compilation overhead at runtime, and it allows us to move `ajv` from a runtime dependency to a dev dependency, reducing the package's footprint.

While making these changes, I also noticed that `fs-extra` was only used in tests for convenience methods like `readJsonSync` and `removeSync`. Since Node.js 14+ provides `fs.rmSync` with recursive support, and JSON parsing is trivial with `JSON.parse(fs.readFileSync(...))`, the `fs-extra` dependency is no longer needed and has been removed entirely.

---

By submitting this pull request, I confirm that my contribution is made under the terms of the [Apache 2.0 license].

[Apache 2.0 license]: https://www.apache.org/licenses/LICENSE-2.0

Author: mrgrain

packages/@jsii/spec/.eslintrc.yaml

@@ -1,2 +1,5 @@
 ---
 extends: ../../../eslint-config.yaml
+
+ignorePatterns:
+  - build-tools/generate-validators.js

packages/@jsii/spec/build-tools/generate-json-schema.sh

@@ -40,3 +40,7 @@ set -euo pipefail
         --strictNullChecks true              \
         --topRef           true
 }
+
+# Generate standalone validation code from schemas
+echo "Generating standalone validation code"
+node build-tools/generate-validators.js

packages/@jsii/spec/build-tools/generate-validators.js

@@ -0,0 +1,21 @@
+const Ajv = require('ajv');
+const standaloneCode = require('ajv/dist/standalone').default;
+const { readFileSync, writeFileSync } = require('fs');
+
+const ajv = new Ajv({ code: { source: true, esm: false }, allErrors: true });
+
+// Load and compile schemas
+const assemblySchema = JSON.parse(readFileSync('schema/jsii-spec.schema.json', 'utf8'));
+const redirectSchema = JSON.parse(readFileSync('schema/assembly-redirect.schema.json', 'utf8'));
+
+ajv.addSchema(assemblySchema, 'assembly');
+ajv.addSchema(redirectSchema, 'redirect');
+
+// Generate standalone code
+const code = standaloneCode(ajv, {
+  validateAssembly: 'assembly',
+  validateRedirect: 'redirect',
+});
+
+writeFileSync('lib/validators.js', code);
+console.log('Generated lib/validators.js');

packages/@jsii/spec/jest.config.mjs

@@ -1,9 +1,12 @@
 import { overriddenConfig } from '../../../jest.config.mjs';
 
 export default overriddenConfig({
+  coveragePathIgnorePatterns: [
+    'lib/validators.js'
+  ],
   coverageThreshold: {
     global: {
-      branches: 28,
+      branches: 60,
     },
   },
 });

packages/@jsii/spec/package.json

@@ -30,11 +30,8 @@
     "test:update": "jest -u",
     "package": "package-js"
   },
-  "dependencies": {
-    "ajv": "^8.17.1"
-  },
   "devDependencies": {
-    "fs-extra": "^10.1.0",
+    "ajv": "^8.17.1",
     "jsii-build-tools": "^0.0.0",
     "typescript-json-schema": "^0.65.1"
   }

packages/@jsii/spec/src/assembly-utils.test.ts

@@ -1,4 +1,4 @@
-import * as fs from 'fs-extra';
+import * as fs from 'node:fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as zlib from 'zlib';
@@ -44,7 +44,7 @@ beforeEach(() => {
 });
 
 afterEach(() => {
-  fs.removeSync(tmpdir);
+  fs.rmSync(tmpdir, { recursive: true, force: true });
 });
 
 describe(writeAssembly, () => {
@@ -56,9 +56,11 @@ describe(writeAssembly, () => {
     ).toBeTruthy();
 
     // includes .jsii files with instructions for finding compressed file
-    const instructions = fs.readJsonSync(path.join(tmpdir, SPEC_FILE_NAME), {
-      encoding: 'utf-8',
-    });
+    const instructions = JSON.parse(
+      fs.readFileSync(path.join(tmpdir, SPEC_FILE_NAME), {
+        encoding: 'utf-8',
+      }),
+    );
     expect(instructions).toEqual({
       schema: 'jsii/file-redirect',
       compression: 'gzip',
@@ -117,42 +119,57 @@ describe(loadAssemblyFromPath, () => {
       loadAssemblyFromPath(uncompressedTmpDir),
     );
 
-    fs.removeSync(compressedTmpDir);
-    fs.removeSync(uncompressedTmpDir);
+    fs.rmSync(compressedTmpDir, { recursive: true, force: true });
+    fs.rmSync(uncompressedTmpDir, { recursive: true, force: true });
   });
 
   test('throws if redirect object has unsupported compression', () => {
-    fs.writeJsonSync(path.join(tmpdir, SPEC_FILE_NAME), {
-      schema: 'jsii/file-redirect',
-      compression: '7zip',
-      filename: '.jsii.7z',
-    });
+    fs.writeFileSync(
+      path.join(tmpdir, SPEC_FILE_NAME),
+      JSON.stringify(
+        {
+          schema: 'jsii/file-redirect',
+          compression: '7zip',
+          filename: '.jsii.7z',
+        },
+        null,
+        2,
+      ),
+    );
 
     expect(() => loadAssemblyFromPath(tmpdir)).toThrow(
       /Error: Invalid assembly redirect:\n \* redirect\/compression must be equal to constant/m,
     );
   });
 
   test('throws if redirect object is missing filename', () => {
-    fs.writeJsonSync(path.join(tmpdir, SPEC_FILE_NAME), {
-      schema: 'jsii/file-redirect',
-    });
+    fs.writeFileSync(
+      path.join(tmpdir, SPEC_FILE_NAME),
+      JSON.stringify(
+        {
+          schema: 'jsii/file-redirect',
+        },
+        null,
+        2,
+      ),
+    );
 
     expect(() => loadAssemblyFromPath(tmpdir)).toThrow(
       /Error: Invalid assembly redirect:\n \* redirect must have required property 'filename'/m,
     );
   });
 
   test('throws if assembly is invalid', () => {
-    fs.writeJsonSync(
+    fs.writeFileSync(
       path.join(tmpdir, SPEC_FILE_NAME),
-      {
-        assembly: 'not a valid assembly',
-      },
-      {
-        encoding: 'utf8',
-        spaces: 2,
-      },
+      JSON.stringify(
+        {
+          assembly: 'not a valid assembly',
+        },
+        null,
+        2,
+      ),
+      { encoding: 'utf8' },
     );
 
     expect(() => loadAssemblyFromPath(tmpdir)).toThrow(/Invalid assembly/);

packages/@jsii/spec/src/format-errors.ts

@@ -0,0 +1,10 @@
+import type { ErrorObject } from 'ajv';
+
+export function formatErrors(errors: ErrorObject[], dataVar: string): string {
+  if (!errors || errors.length === 0) {
+    return 'No errors';
+  }
+  return errors
+    .map((e) => `${dataVar}${e.instancePath} ${e.message}`)
+    .join('\n * ');
+}

packages/@jsii/spec/src/redirect.ts

@@ -1,8 +1,11 @@
-import Ajv from 'ajv';
+import { formatErrors } from './format-errors';
 
 // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
 export const assemblyRedirectSchema = require('../schema/assembly-redirect.schema.json');
 
+// eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+const { validateRedirect: validateSchema } = require('../lib/validators');
+
 const SCHEMA = 'jsii/file-redirect';
 
 export interface AssemblyRedirect {
@@ -43,18 +46,9 @@ export function isAssemblyRedirect(obj: unknown): obj is AssemblyRedirect {
  * @returns the validated value.
  */
 export function validateAssemblyRedirect(obj: unknown): AssemblyRedirect {
-  const ajv = new Ajv({
-    allErrors: true,
-  });
-  const validate = ajv.compile(assemblyRedirectSchema);
-  validate(obj);
-
-  if (validate.errors) {
+  if (!validateSchema(obj)) {
     throw new Error(
-      `Invalid assembly redirect:\n * ${ajv.errorsText(validate.errors, {
-        separator: '\n * ',
-        dataVar: 'redirect',
-      })}`,
+      `Invalid assembly redirect:\n * ${formatErrors(validateSchema.errors, 'redirect')}`,
     );
   }
 

packages/@jsii/spec/src/validate-assembly.ts

@@ -1,18 +1,14 @@
-import Ajv from 'ajv';
-
 import { Assembly } from './assembly';
+import { formatErrors } from './format-errors';
 
 // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
 export const schema = require('../schema/jsii-spec.schema.json');
 
-export function validateAssembly(obj: any): Assembly {
-  const ajv = new Ajv({
-    allErrors: true,
-  });
-  const validate = ajv.compile(schema);
-  validate(obj);
+// eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+const { validateAssembly: validateSchema } = require('../lib/validators');
 
-  if (validate.errors) {
+export function validateAssembly(obj: any): Assembly {
+  if (!validateSchema(obj)) {
     let descr = '';
     if (typeof obj.name === 'string' && obj.name !== '') {
       descr =
@@ -21,10 +17,7 @@ export function validateAssembly(obj: any): Assembly {
           : ` ${obj.name}`;
     }
     throw new Error(
-      `Invalid assembly${descr}:\n * ${ajv.errorsText(validate.errors, {
-        separator: '\n * ',
-        dataVar: 'assembly',
-      })}`,
+      `Invalid assembly${descr}:\n * ${formatErrors(validateSchema.errors, 'assembly')}`,
     );
   }
   return obj;