feat: json schema integration

#51 JSON Schema Integration: Implementation with Features

Overview This PR introduces full JSON Schema integration into Interface-Forge, enabling automatic, type-safe factory generation from JSON Schema definitions. It maintains the lightweight core architecture by implementing the integration as an optional module and includes several advanced features, optimizations, and exhaustive documentation.

Features Implemented Core Functionality

• JsonSchemaFactory class extending core Factory
• buildMany() method as alias for batch()
• Full support for all standard JSON Schema types: string, number, integer, boolean, array, object, null
• Format support: email, uuid, date-time, uri, ipv4, ipv6, and custom formats
• Built-in schema validation via AJV during generation

Composition & References

• allOf: Merges constraints and properties intelligently
• anyOf / oneOf: Depth-controlled, recursion-safe variant selection
• $ref: Full internal reference support with loop detection
• Constraint propagation for keywords like min, max, pattern, enum

Performance & Stability

• Schema compilation caching
• Configurable recursion depth (maxDepth)
• Efficient batch generation with minimal memory footprint
• Comparable memory use to hand-written factories

Benchmark locations:

• src/json-schema.spec.ts (lines 454–620)
• examples/07-json-schema-integration.ts (lines 396–430)
• README: Benchmark guide with steps

Implementation Details Key Files

• src/json-schema.ts: JSON Schema parsing and factory logic
• src/json-schema.spec.ts: 183+ test cases
• examples/07-json-schema-integration.ts: 11 detailed examples

Sample API Usage

const UserFactory = await createFactoryFromJsonSchema(userSchema);
const user = UserFactory.build();
const users = UserFactory.buildMany(10);

Advanced Use Cases

// Self-referencing schema
const treeSchema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    children: { type: 'array', items: { $ref: '#' } }
  }
};

// Custom format
const options = {
  customFormats: {
    'product-code': (faker) => `${faker.string.alpha(3)}-${faker.string.numeric(6)}`
  }
};

Documentation README

• JSON Schema usage guide
• Performance benchmarks
• Full API reference
• Setup instructions with optional dependency notes

Examples

• 11 new scenarios in examples/07-json-schema-integration.ts
• Real-world use cases (e.g., OpenAPI)
• Side-by-side manual vs schema-based factory examples

Testing Coverage

• 183 tests across basic, advanced, and edge cases
• Validation of recursion, $ref, schema composition
• Full type safety checks
• Malformed schema error testing
• Performance regression tests

Test Categories

1. Basic data generation
2. Composition and schema merging
3. Reference resolution and recursion
4. Benchmark verification
5. Type compatibility and factory extension

Compatibility

API Compatibility

• build(), buildMany(), and batch() all supported
• Seamless extend(), compose(), beforeBuild() integration

Optional Dependency Model

• ajv and ajv-formats are optional
• Core remains dependency-free
• Graceful error messaging if packages are not installed

npm install --save-dev ajv ajv-formats

Conclusion This PR:

• Fulfills and exceeds all functional requirements
• Provides a robust, extensible JSON Schema integration
• Is fully documented, tested, and benchmarked
• Preserves core performance and architecture