fix: rename prohibited member names to avoid JSII conflicts (#1841)

Fixes #1833

## Why

When JSON schemas contain property names like `build`, `equals`, or
`hashcode`, the generated TypeScript code fails to compile. These names
conflict with synthetic declarations that JSII adds to structs in target
languages (Java, Python, etc.).

For example, a CloudFormation resource with a `build` property would
generate code that clashes with the `build()` method JSII creates for
struct builders.

## Solution

Property names matching prohibited JSII member names are now
automatically renamed by appending an underscore suffix (e.g., `build` →
`build_`). The `toJson` function correctly maps these back to the
original schema names during serialization.

---

### Ask Yourself

- [x] Have you reviewed the [contribution
guide](https://github.com/cdklabs/json2jsii/blob/main/CONTRIBUTING.md)?
- [x] Have you reviewed the [breaking changes
guide](https://github.com/cdklabs/json2jsii/blob/main/CONTRIBUTING.md#breaking-changes)?
- This is not breaking since the previously generated code does not
compile with `jsii`.

Author: mrgrain

src/type-generator.ts

@@ -11,6 +11,14 @@ const DEFINITIONS_LEGACY_PREFIX = '#/definitions/';
 const DEFINITIONS_PREFIX = '#/$defs/';
 const DEFAULT_RENDER_TYPE_NAME = (s: string) => s.split('.').map(x => pascalCase(x)).join('');
 
+/**
+ * JSII synthetic declarations that cannot be used as property names.
+ * These are reserved method names in JSII structs across target languages.
+ *
+ * @see https://github.com/aws/jsii-compiler/blob/0f142651abac9eff35dfbd74c141d5ff058b2a8a/src/assembler.ts#L3193
+ */
+const PROHIBITED_MEMBER_NAMES = ['build', 'equals', 'hashcode'];
+
 /**
  * Available opt-in schema transformations
  */
@@ -611,6 +619,11 @@ export class TypeGenerator {
     // convert the name to camel case so it's compatible with JSII
     name = camelCase(name);
 
+    // if the name conflicts with a prohibited member name, append underscore
+    if (PROHIBITED_MEMBER_NAMES.includes(name.toLowerCase())) {
+      name = name + '_';
+    }
+
     const propertyFqn = this.propertyFqn(structFqn, name);
 
     if (this.emittedProperties.has(propertyFqn)) {

test/prohibited-names.test.ts

@@ -0,0 +1,195 @@
+import { JSONSchema4 } from 'json-schema';
+import { TypeGenerator } from '../src';
+
+describe('prohibited member names', () => {
+  describe('unit tests', () => {
+    test("'build' property becomes 'build_'", () => {
+      const schema: JSONSchema4 = {
+        type: 'object',
+        properties: {
+          build: { type: 'string' },
+        },
+      };
+
+      const gen = TypeGenerator.forStruct('TestStruct', schema);
+      const output = gen.render();
+
+      expect(output).toContain('readonly build_?:');
+      expect(output).not.toMatch(/readonly build\?:/);
+    });
+
+    test("'equals' property becomes 'equals_'", () => {
+      const schema: JSONSchema4 = {
+        type: 'object',
+        properties: {
+          equals: { type: 'boolean' },
+        },
+      };
+
+      const gen = TypeGenerator.forStruct('TestStruct', schema);
+      const output = gen.render();
+
+      expect(output).toContain('readonly equals_?:');
+      expect(output).not.toMatch(/readonly equals\?:/);
+    });
+
+    test("'hashcode' property becomes 'hashcode_'", () => {
+      const schema: JSONSchema4 = {
+        type: 'object',
+        properties: {
+          hashcode: { type: 'number' },
+        },
+      };
+
+      const gen = TypeGenerator.forStruct('TestStruct', schema);
+      const output = gen.render();
+
+      expect(output).toContain('readonly hashcode_?:');
+      expect(output).not.toMatch(/readonly hashcode\?:/);
+    });
+
+    test('non-prohibited names remain unchanged', () => {
+      const schema: JSONSchema4 = {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+          value: { type: 'number' },
+          enabled: { type: 'boolean' },
+        },
+      };
+
+      const gen = TypeGenerator.forStruct('TestStruct', schema);
+      const output = gen.render();
+
+      expect(output).toContain('readonly name?:');
+      expect(output).toContain('readonly value?:');
+      expect(output).toContain('readonly enabled?:');
+    });
+
+    test('toJson correctly maps renamed properties to original names', () => {
+      const schema: JSONSchema4 = {
+        type: 'object',
+        properties: {
+          build: { type: 'string' },
+          name: { type: 'string' },
+        },
+      };
+
+      const gen = TypeGenerator.forStruct('TestStruct', schema);
+      const output = gen.render();
+
+      // The toJson function should map build_ back to 'build'
+      expect(output).toContain("'build': obj.build_");
+      expect(output).toContain("'name': obj.name");
+    });
+
+    test('prohibited names are case-insensitive', () => {
+      const schema: JSONSchema4 = {
+        type: 'object',
+        properties: {
+          BUILD: { type: 'string' },
+          Equals: { type: 'boolean' },
+          HashCode: { type: 'number' },
+        },
+      };
+
+      const gen = TypeGenerator.forStruct('TestStruct', schema);
+      const output = gen.render();
+
+      // After camelCase conversion, these become 'build', 'equals', 'hashCode'
+      // which should be renamed to 'build_', 'equals_', 'hashCode_'
+      expect(output).toContain('readonly build_?:');
+      expect(output).toContain('readonly equals_?:');
+      expect(output).toContain('readonly hashCode_?:');
+    });
+  });
+});
+
+
+import * as fc from 'fast-check';
+
+/**
+ * Property-based tests for prohibited name handling
+ * Feature: reserved-word-property-names
+ */
+describe('prohibited member names - property tests', () => {
+  const PROHIBITED_NAMES = ['build', 'equals', 'hashcode'];
+
+  /**
+   * Property 1: Prohibited names get underscore suffix
+   * Validates: Requirements 1.1
+   *
+   * For any property name that, after camelCase conversion, matches a prohibited
+   * member name (case-insensitive), the emitted TypeScript property name SHALL
+   * have an underscore suffix appended.
+   */
+  test('Property 1: Prohibited names get underscore suffix', () => {
+    fc.assert(
+      fc.property(
+        fc.constantFrom(...PROHIBITED_NAMES),
+        (prohibitedName) => {
+          const schema: JSONSchema4 = {
+            type: 'object',
+            properties: {
+              [prohibitedName]: { type: 'string' },
+            },
+          };
+
+          const gen = TypeGenerator.forStruct('TestStruct', schema);
+          const output = gen.render();
+
+          // The property should be renamed with underscore suffix
+          expect(output).toContain(`readonly ${prohibitedName}_?:`);
+          // The original name should not appear as a property
+          expect(output).not.toMatch(new RegExp(`readonly ${prohibitedName}\\?:`));
+        },
+      ),
+      { numRuns: 100 },
+    );
+  });
+});
+
+
+describe('prohibited member names - property tests (continued)', () => {
+  const PROHIBITED_NAMES = ['build', 'equals', 'hashcode'];
+
+  /**
+   * Property 2: Non-prohibited names remain unchanged
+   * Validates: Requirements 1.2
+   *
+   * For any property name that, after camelCase conversion, does NOT match any
+   * prohibited member name, the emitted TypeScript property name SHALL equal
+   * the camelCase-converted name.
+   */
+  test('Property 2: Non-prohibited names remain unchanged', () => {
+    // Generate simple lowercase alphabetic property names that are not prohibited
+    // Using lowercase-only alphabetic names avoids camelCase conversion complexity
+    const validPropertyNameArb = fc.string({ minLength: 1, maxLength: 15 })
+      .filter(s => /^[a-z]+$/.test(s))
+      .filter(s => !PROHIBITED_NAMES.includes(s));
+
+    fc.assert(
+      fc.property(
+        validPropertyNameArb,
+        (propertyName) => {
+          const schema: JSONSchema4 = {
+            type: 'object',
+            properties: {
+              [propertyName]: { type: 'string' },
+            },
+          };
+
+          const gen = TypeGenerator.forStruct('TestStruct', schema);
+          const output = gen.render();
+
+          // For lowercase-only alphabetic names, camelCase conversion is identity
+          // The property should NOT have underscore suffix
+          expect(output).not.toContain(`readonly ${propertyName}_?:`);
+          // The property should appear with its original name
+          expect(output).toContain(`readonly ${propertyName}?:`);
+        },
+      ),
+      { numRuns: 100 },
+    );
+  });
+});