schemantic 0.3.0 → 0.4.1

package/docs/ADVANCED_PLUGIN_DEVELOPMENT.md

@@ -1,309 +1,33 @@
-# Advanced Plugin Development Guide
-
-## Overview
-
-This guide documents the development of advanced plugins for Schemantic, implementing sophisticated optimization patterns, type system enhancements, and developer experience improvements based on strategic analysis of production-ready API code generation requirements.
-
-## Strategic Architecture Goals
-
-### 1. **Schema-Driven Validation Enhancement**
-
-- Runtime validation schema generation (Zod/Yup integration)
-- Type-safe request/response validation pipelines
-- Performance-optimized validation caching
-
-### 2. **Performance Optimization Architecture**
-
-- Request deduplication at client level
-- Bundle size optimization through tree-shakable endpoints
-- Memory-efficient type registry management
-
-### 3. **Type System Sophistication**
-
-- Branded types for compile-time safety
-- Phantom type parameters for auth state management
-- Discriminated unions with runtime type guards
-
-### 4. **Developer Experience Vectors**
-
-- Real-time schema synchronization
-- Semantic versioning detection
-- Performance profiling and optimization recommendations
-
-## Plugin Development Methodology
-
-### Phase 1: Foundation Plugins (Schema Enhancement)
-
-#### 1.1 Zod Validation Plugin
-
-**Purpose**: Generate Zod schemas from OpenAPI specifications for runtime validation
-
-**Architecture Considerations**:
-
-- Type-level validation mapping
-- Performance optimization through schema caching
-- Integration with request/response pipelines
-
-#### 1.2 Performance Monitoring Plugin
-
-**Purpose**: Add instrumentation and performance tracking to generated clients
-
-**Architecture Considerations**:
-
-- Request timing collection
-- Bundle size analysis
-- Memory usage profiling
-
-### Phase 2: Type System Enhancement Plugins
-
-#### 2.1 Branded Types Plugin
-
-**Purpose**: Generate branded types for compile-time safety guarantees
-
-**Architecture Considerations**:
-
-- Phantom type parameter implementation
-- Runtime type guard generation
-- Brand preservation through transformation chains
-
-#### 2.2 Request Deduplication Plugin
-
-**Purpose**: Implement intelligent request deduplication at the client level
-
-**Architecture Considerations**:
-
-- Request fingerprinting algorithms
-- Cache invalidation strategies
-- Memory management for pending requests
-
-### Phase 3: Developer Experience Plugins
-
-#### 3.1 Schema Synchronization Plugin
-
-**Purpose**: Real-time schema change detection and type regeneration
-
-**Architecture Considerations**:
-
-- File system watching integration
-- Incremental regeneration algorithms
-- Change impact analysis
-
-#### 3.2 Bundle Optimization Plugin
-
-**Purpose**: Tree-shakable endpoint generation and bundle size optimization
-
-**Architecture Considerations**:
-
-- Endpoint modularization strategies
-- Dead code elimination support
-- Dependency graph optimization
-
-## Implementation Standards
-
-### Plugin Structure Template
-
-```typescript
-export const advancedPlugin: SchemanticPlugin = {
-  name: "advanced-feature",
-  version: "1.0.0",
-  description: "Advanced feature implementation with performance optimizations",
-
-  // Lifecycle hooks with error handling
-  beforeGeneration: async (context: GenerationContext) => {
-    // Pre-generation setup and validation
-  },
-
-  // Schema transformation with caching
-  transformSchema: (schema: ResolvedSchema, context: GenerationContext) => {
-    // Schema enhancement with performance considerations
-  },
-
-  // Type generation with sophisticated patterns
-  afterTypeGeneration: async (
-    typeName: string,
-    generatedType: GeneratedType,
-    context: GenerationContext
-  ) => {
-    // Type enhancement with advanced TypeScript patterns
-  },
-
-  // Client generation with optimization
-  afterClientGeneration: async (
-    generatedClient: GeneratedApiClient,
-    context: GenerationContext
-  ) => {
-    // Client enhancement with performance optimizations
-  },
-};
-```
-
-### Error Handling Standards
-
-All plugins must implement comprehensive error handling:
-
-```typescript
-try {
-  // Plugin logic
-} catch (error) {
-  console.warn(`Plugin ${plugin.name} operation failed:`, error);
-  // Graceful degradation strategy
-}
-```
-
-### Performance Monitoring
-
-All plugins should include performance tracking:
-
-```typescript
-const startTime = performance.now();
-// Plugin operations
-const endTime = performance.now();
-context.statistics.pluginTiming[plugin.name] = endTime - startTime;
-```
-
-## Testing Strategy
-
-### Unit Testing Requirements
-
-Each plugin must include:
-
-- Schema transformation tests
-- Type generation verification
-- Performance benchmark tests
-- Error condition handling
-
-### Integration Testing
-
-Plugin combinations must be tested for:
-
-- Interaction conflicts
-- Performance impact
-- Output correctness
-
-## Documentation Standards
-
-### Plugin Documentation Requirements
-
-Each plugin must include:
-
-- Purpose and use cases
-- Configuration options
-- Performance characteristics
-- Integration considerations
-- Migration guidelines
-
-### API Documentation
-
-All generated code must include:
-
-- JSDoc comments
-- Type annotations
-- Usage examples
-- Performance notes
-
-## Deployment Considerations
-
-### Plugin Distribution
-
-Plugins can be distributed as:
-
-- Built-in plugins (core functionality)
-- External NPM packages
-- Custom project plugins
-
-### Configuration Management
-
-Plugin configuration follows the standard pattern:
-
-```typescript
-{
-  plugins: [
-    {
-      name: "zod-validation",
-      enabled: true,
-      options: {
-        strictMode: true,
-        cacheSchemas: true,
-        optimizeBundle: true,
-      },
-    },
-  ];
-}
-```
-
-## Advanced Implementation Patterns
-
-### 1. Lazy Evaluation Strategies
-
-Implement lazy evaluation for expensive operations:
-
-```typescript
-const lazyValidator = createLazyValidator(() =>
-  generateValidationSchema(schema)
-);
-```
-
-### 2. Memoization Patterns
-
-Cache expensive computations:
-
-```typescript
-const memoizedTransform = memoize(
-  (schema: ResolvedSchema) => transformSchema(schema),
-  (schema) => JSON.stringify(schema)
-);
-```
-
-### 3. Pipeline Composition
-
-Enable plugin composition:
-
-```typescript
-const pipeline = compose(
-  zodValidationPlugin,
-  performanceMonitoringPlugin,
-  bundleOptimizationPlugin
-);
-```
-
-## Performance Optimization Guidelines
-
-### Memory Management
-
-- Use WeakMap for temporary associations
-- Implement proper cleanup in lifecycle hooks
-- Monitor memory usage in long-running processes
-
-### CPU Optimization
-
-- Implement efficient algorithms for schema traversal
-- Use worker threads for CPU-intensive operations
-- Cache computed results appropriately
-
-### Bundle Size Optimization
-
-- Generate tree-shakable modules
-- Implement code splitting strategies
-- Optimize import/export patterns
-
-## Future Enhancement Roadmap
-
-### Planned Advanced Features
-
-1. **GraphQL Bridge Plugin**: Transform REST endpoints into GraphQL-compatible resolvers
-2. **State Machine Integration**: Generate XState machines for complex API workflows
-3. **Real-time Sync Plugin**: WebSocket-based schema synchronization
-4. **AI-Powered Optimization**: Machine learning-based performance recommendations
-
-### Research Areas
-
-1. **Advanced Type Inference**: Improved type inference from schema patterns
-2. **Cross-Platform Generation**: Support for additional target languages
-3. **Security Enhancement**: Automated security vulnerability detection
-4. **Performance Prediction**: Predictive performance analysis
-
-## Conclusion
-
-This advanced plugin development framework provides the foundation for sophisticated code generation capabilities that extend far beyond basic OpenAPI type generation. The focus on performance, type safety, and developer experience positions Schemantic as a comprehensive development environment integration tool rather than just a code generator.
-
-The plugin architecture enables ecosystem partnerships and network effects that can drive adoption through developer tooling integrations and community contributions.
+# Advanced plugin development
+
+Start with the [current plugin interface](PLUGIN_DEVELOPMENT.md). Advanced plugins use that same interface; there is no separate extension API for CLI commands, runtime transport interception, or arbitrary file-write hooks.
+
+A generated runtime helper and a generator-process utility are different APIs. Helpers embedded in generated clients are imported from generated files. Public plugin factories/analysis utilities are imported from `schemantic`; do not instruct consumers to import blocked `schemantic/dist/...` paths.
+
+## Design contracts
+
+- Validation helpers must enforce their documented schema constraints and preserve input data when permissive mode is requested. A cast or shallow object check is not schema validation.
+- Every emitted identifier/import/export must participate in the output graph. Shared declarations must be emitted once. Disabled features must not leave dangling imports/exports.
+- Caching must include every response-affecting request field and explicit session scope. Custom identities need a collision/tenant policy; do not log secret header values.
+- Runtime callbacks belong in factories/constructors. JSON config can carry serializable data only.
+- Timing data must come from observed calls. Source length and synthetic dependency estimates are not real bundle sizes or measured application speedups.
+- Lifecycle failures must fail generation before published output is replaced. Plugins should not write unrelated user files during hooks.
+
+## Validation memoization
+
+The public utility has a data-first signature:
+
+```ts
+import { memoizedValidation } from 'schemantic';
+import { z } from 'zod';
+
+const schema = z.object({ id: z.number().int() });
+const value = memoizedValidation({ id: 1 }, schema);
+console.log(value.id);
+```
+
+This utility runs in the process that calls it. It does not automatically validate generated endpoint responses or guarantee that generation-time schema memoization is bounded. Cache keys must include schema/version/input context; use the public clear/stat utilities according to their actual implementation.
+
+## Acceptance evidence
+
+Generate output with multiple schemas and feature switches, compile under strict bundler and NodeNext settings, then execute the generated helpers. Include invalid validator inputs, overlapping calls, tenant separation, expiry, and disabled helper imports. Keep empirical measurements separate from feature assertions. See [advanced capability boundaries](ADVANCED_PLUGINS_IMPLEMENTATION.md).