schemantic 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,174 +1,204 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-Got it — here’s your updated, clean and complete **`CHANGELOG.md`** entry reflecting that as well:
-
----
-
-## [0.3.0] — 2025-10-18
-
-### Removed
-
-- Removed `barrel.ts` generation and the `generateBarrelExports` configuration option.
-
-  - Exports are now consolidated into `index.ts` by default. This reduces duplication and simplifies generated output.
-
-### Migration notes
-
-- If you previously relied on a generated `barrel.ts`, update your code to import from the generated `index.ts` (e.g., `import { MyApiClient } from './generated';`).
-- The `generateBarrelExports` option has been removed; there is no replacement flag. If you require a custom barrel file, create it in your project outside of the generated files.
-
----
-
-## [0.2.1] — 2025-10-18
-
-### Fixed
-
-- CLI: Respect `outputDir` from `schemantic.config.json` when provided. The CLI no longer forces the generator to write to `./src/generated` when an output directory is specified in the configuration file or via the `--output` flag. This fixes cases where generation ignored a project's configured destination.
-
-- Zod validation generator: Updated generated validation helpers and client middleware to follow Zod v4 error shape. Generated code now uses `result.error?.issues` and types validation issues as `z.core.$ZodIssue` where appropriate. A typed `ValidationError` wrapper is emitted by the generator so consumers can rely on a stable `issues` shape.
-
-- Generator hygiene: Avoid emitting unused imports in generated outputs. The hooks generator now imports only the React hooks actually used by the generated hooks. The API client generator and plugins only import `z` when the generated client references `z.`. These changes reduce spurious TypeScript diagnostics in downstream projects.
-
-### Changed
-
-- Generation behavior: The generator was made more conservative about emitted imports and helper declarations so generated code compiles cleanly in a wider range of consuming projects.
-
-### Migration notes
-
-- If you previously relied on `ValidationError.errors` in generated code, switch to `ValidationError.issues`.
-
-- If your consuming project reported unused-import diagnostics for generated files (for example `z` or React hook imports), regenerate after updating to this version; the generator will emit only the imports that are actually used.
-
----
-
-## [0.2.0] — 2025-10-18
-
-### Added
-
-- **Zod Plugin** — Adopted Zod v4 error shape.
-
-  - `ValidationError` now exposes `issues` (Zod issues) and `data` (the invalid input).
-  - `validateRequest` and `validateResponse` now consume `error.issues` rather than the deprecated `error.errors`.
-
-### Changed
-
-- `validate<Type>` now returns structured results — `{ success: true | false, data | errors }` — for more predictable downstream handling.
-- Improved internal transform typing (`transform((val: Record<string, unknown>) => ...)`) to ensure consistent inference during schema generation.
-- **React Hooks plugin temporarily disabled** while migration to the new generator pipeline is in progress. It will be re-enabled in a future minor release.
-
-### Fixed
-
-- Respected empty `typePrefix` by default — no automatic `"API"` prefix. Added integration test to prevent regressions.
-- Made CLI `--config` flag usable without an explicit path and standardized the configuration filename to `schemantic.config.json`.
-- Prevented the generator from importing TypeScript built-ins (e.g. `Record`, `Promise`) from generated `./types`.
-- Ensured `buildObjectSchema` always returns a base schema (no missing return paths).
-- Corrected a mismatched brace bug introduced in prior edits.
-- Filtered out TypeScript built-in names in `hook-generator.ts` to prevent invalid imports.
-- Emitted generated type declarations in dependency-resolved order so declarations appear before helper / validation code.
-
-### Migration Notes
-
-- If you previously accessed `ValidationError.errors`, switch to `ValidationError.issues`.
-- React Hooks plugin is temporarily unavailable as of this release — no action required if unused.
-- No other breaking changes are expected for consumers.
-
----
-
-**Release summary:**
-
-> ✨ Zod v4 error shape support, generator fixes, and CLI improvements. React Hooks plugin temporarily disabled pending refactor.
-
----
-
-### Added
-
-- Add a lightweight CI workflow to run the prefix integration test on push/PR.
-
-## [0.1.0] - 2025-09-13
-
-### Added
-
-- First-party React hooks generator with `createApiHooks(client)` factory, enabled via `--hooks` or `generateHooks: true`.
-- Top-level exports for `HookGenerator` and `GeneratedHooksFile`.
-
-### Changed
-
-- Standardized generated client filename to `api-client.ts`; index now re-exports the client and hooks consistently.
-- Improved naming normalization for types and client methods (sanitize invalid characters; PascalCase for type identifiers).
-
-### Fixed
-
-- Corrected index re-export path for CLI to avoid `.js` resolution type issues.
-- Aligned generated hook call signatures with client method arity and parameter ordering.
-
-### Added
-
-- Initial release of Schemantic
-- OpenAPI 3.0+ schema parsing and validation
-- TypeScript type generation from OpenAPI schemas
-- API client generation with proper typing
-- Extensible plugin system
-- CLI interface with comprehensive options
-- Built-in plugins for JSDoc, validation, React hooks, and strict mode
-- Support for multiple naming conventions (camelCase, snake_case, PascalCase)
-- Custom type mappings and schema transformations
-- Path and schema filtering capabilities
-- Comprehensive documentation and examples
-- Full test coverage with Jest
-
-### Features
-
-- **Schema Parsing**: Parse OpenAPI schemas from URLs, files, or data objects
-- **Type Generation**: Generate TypeScript interfaces, enums, and type aliases
-- **API Client Generation**: Generate fully typed API client classes
-- **Plugin System**: Extensible plugin architecture for custom functionality
-- **CLI Interface**: Command-line interface with rich configuration options
-- **Validation**: Built-in OpenAPI schema validation
-- **Customization**: Flexible configuration for naming, filtering, and transformations
-- **FastAPI Integration**: Optimized for FastAPI applications
-- **React Support**: Generate React hooks and query builders
-- **TypeScript Strict Mode**: Full TypeScript strict mode support
-
-### Technical Details
-
-- **Zero Dependencies**: No runtime dependencies on external libraries
-- **Modular Architecture**: Clean separation of concerns with extensible design
-- **Type Safety**: Comprehensive TypeScript types with no `any` usage
-- **Performance**: Optimized for large schemas and complex APIs
-- **Error Handling**: Graceful error handling with detailed error messages
-- **Testing**: Comprehensive test suite with 100% coverage goals
-
-## [0.1.0] - 2024-09-12
-
-### Added
-
-- Initial release
-- Core functionality for OpenAPI schema parsing and TypeScript generation
-- Plugin system architecture
-- CLI interface
-- Documentation and examples
-
-### Changed
-
-- N/A (initial release)
-
-### Deprecated
-
-- N/A (initial release)
-
-### Removed
-
-- N/A (initial release)
-
-### Fixed
-
-- N/A (initial release)
-
-### Security
-
-- N/A (initial release)
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.1] — 2026-10-18
+
+### Fixed
+
+- Generated API clients omit imports used only by thrown error-response metadata, avoiding `noUnusedLocals` failures in strict consumers while retaining types used by request and successful/default response signatures.
+- Generated `ApiClientError` and Zod `ValidationError` use explicit fields and assignments instead of constructor parameter properties, supporting `erasableSyntaxOnly` without changing their runtime error data.
+- CI now checks unused declarations throughout the fixture matrix and enables Vite's erasable-syntax restriction for installed-package and live FastAPI consumers, with regression coverage for both property naming modes and Zod validation.
+
+## [0.4.0] — 2026-10-18
+
+### Fixed
+
+- Multipart uploads recognize both legacy `format: binary` and current FastAPI `contentMediaType` schemas. JSON representations and explicitly encoded content remain strings; live CI covers legacy and current FastAPI.
+- Fresh output supports composed schemas, aliases, arrays, dictionaries, nullable values, safe identifiers, literal enums and runtime exports.
+- Clients resolve inherited/component parameters, encode paths, merge headers, serialize array queries and URL-encoded forms, decode response media, and restrict retries to transient idempotent requests.
+- Generation validates references and output collisions, applies filters and plugins, isolates repeated runs and executes custom generators.
+- Hooks share client metadata, honor prefixes/custom filenames, stabilize equivalent query inputs and ignore stale query responses.
+- Zod validation preserves all payload fields, supports lazy references and validates numeric enums, unions, nullable values and dictionaries.
+- CLI failures return nonzero status; config overrides and types-only output work; local watch mode regenerates changes.
+- Release builds exclude test helpers; build/prepack clean and compile fresh output; CI targets Node 20, 22 and 24.
+- Release preparation updates versions and changelog locally; GitHub Releases trigger complete verification and publish the exact tested archive using npm trusted publishing, with integrity checks and safe retries.
+- CI includes cross-platform compatibility, generated fixture compilation, installed-package and live FastAPI consumers, dependency auditing, and separate CodeQL analysis. Tests no longer overwrite tracked output fixtures.
+
+### Compatibility
+
+- Node 20+ is required by Commander 14.
+- `validation` now aliases Zod validation; class-validator decorators cannot be emitted into interfaces. Consumers must install Zod 4.
+- Invalid references, duplicate exports and unsafe output filenames now fail explicitly. `--fix` reports that automatic repair is unimplemented.
+- Generated application properties now default to camelCase with schema-aware JSON/form request conversion and JSON response conversion. Set `propertyNaming: 'preserve'` to retain wire-shaped types. Types-only camelCase output includes public converters. See [naming migration](docs/NAMING_MIGRATION.md).
+- Client generation includes required types even when `generateTypes` is false. Unsupported query generation, strict-mode plugin output, content-encoded parameters and per-property request encodings fail explicitly.
+- Branded guards now use schema-backed Zod validation; branded output requires Zod 4. Optional plugin helpers remain explicit integrations.
+
+## [0.3.0] — 2025-10-18
+
+### Removed
+
+- Removed `barrel.ts` generation and the `generateBarrelExports` configuration option.
+
+  - Exports are now consolidated into `index.ts` by default. This reduces duplication and simplifies generated output.
+
+### Migration notes
+
+- If you previously relied on a generated `barrel.ts`, update your code to import from the generated `index.ts` (e.g., `import { MyApiClient } from './generated';`).
+- The `generateBarrelExports` option has been removed; there is no replacement flag. If you require a custom barrel file, create it in your project outside of the generated files.
+
+---
+
+## [0.2.1] — 2025-10-18
+
+### Fixed
+
+- CLI: Respect `outputDir` from `schemantic.config.json` when provided. The CLI no longer forces the generator to write to `./src/generated` when an output directory is specified in the configuration file or via the `--output` flag. This fixes cases where generation ignored a project's configured destination.
+
+- Zod validation generator: Updated generated validation helpers and client middleware to follow Zod v4 error shape. Generated code now uses `result.error?.issues` and types validation issues as `z.core.$ZodIssue` where appropriate. A typed `ValidationError` wrapper is emitted by the generator so consumers can rely on a stable `issues` shape.
+
+- Generator hygiene: Avoid emitting unused imports in generated outputs. The hooks generator now imports only the React hooks actually used by the generated hooks. The API client generator and plugins only import `z` when the generated client references `z.`. These changes reduce spurious TypeScript diagnostics in downstream projects.
+
+### Changed
+
+- Generation behavior: The generator was made more conservative about emitted imports and helper declarations so generated code compiles cleanly in a wider range of consuming projects.
+
+### Migration notes
+
+- If you previously relied on `ValidationError.errors` in generated code, switch to `ValidationError.issues`.
+
+- If your consuming project reported unused-import diagnostics for generated files (for example `z` or React hook imports), regenerate after updating to this version; the generator will emit only the imports that are actually used.
+
+---
+
+## [0.2.0] — 2025-10-18
+
+### Added
+
+- **Zod Plugin** — Adopted Zod v4 error shape.
+
+  - `ValidationError` now exposes `issues` (Zod issues) and `data` (the invalid input).
+  - `validateRequest` and `validateResponse` now consume `error.issues` rather than the deprecated `error.errors`.
+
+### Changed
+
+- `validate<Type>` now returns structured results — `{ success: true | false, data | errors }` — for more predictable downstream handling.
+- Improved internal transform typing (`transform((val: Record<string, unknown>) => ...)`) to ensure consistent inference during schema generation.
+- **React Hooks plugin temporarily disabled** while migration to the new generator pipeline is in progress. It will be re-enabled in a future minor release.
+
+### Fixed
+
+- Respected empty `typePrefix` by default — no automatic `"API"` prefix. Added integration test to prevent regressions.
+- Made CLI `--config` flag usable without an explicit path and standardized the configuration filename to `schemantic.config.json`.
+- Prevented the generator from importing TypeScript built-ins (e.g. `Record`, `Promise`) from generated `./types`.
+- Ensured `buildObjectSchema` always returns a base schema (no missing return paths).
+- Corrected a mismatched brace bug introduced in prior edits.
+- Filtered out TypeScript built-in names in `hook-generator.ts` to prevent invalid imports.
+- Emitted generated type declarations in dependency-resolved order so declarations appear before helper / validation code.
+
+### Migration Notes
+
+- If you previously accessed `ValidationError.errors`, switch to `ValidationError.issues`.
+- React Hooks plugin is temporarily unavailable as of this release — no action required if unused.
+- No other breaking changes are expected for consumers.
+
+---
+
+**Release summary:**
+
+> ✨ Zod v4 error shape support, generator fixes, and CLI improvements. React Hooks plugin temporarily disabled pending refactor.
+
+---
+
+### Added
+
+- Add a lightweight CI workflow to run the prefix integration test on push/PR.
+
+## [0.1.0] - 2025-09-13
+
+### Added
+
+- First-party React hooks generator with `createApiHooks(client)` factory, enabled via `--hooks` or `generateHooks: true`.
+- Top-level exports for `HookGenerator` and `GeneratedHooksFile`.
+
+### Changed
+
+- Standardized generated client filename to `api-client.ts`; index now re-exports the client and hooks consistently.
+- Improved naming normalization for types and client methods (sanitize invalid characters; PascalCase for type identifiers).
+
+### Fixed
+
+- Corrected index re-export path for CLI to avoid `.js` resolution type issues.
+- Aligned generated hook call signatures with client method arity and parameter ordering.
+
+### Added
+
+- Initial release of Schemantic
+- OpenAPI 3.0+ schema parsing and validation
+- TypeScript type generation from OpenAPI schemas
+- API client generation with proper typing
+- Extensible plugin system
+- CLI interface with comprehensive options
+- Built-in plugins for JSDoc, validation, React hooks, and strict mode
+- Support for multiple naming conventions (camelCase, snake_case, PascalCase)
+- Custom type mappings and schema transformations
+- Path and schema filtering capabilities
+- Comprehensive documentation and examples
+- Full test coverage with Jest
+
+### Features
+
+- **Schema Parsing**: Parse OpenAPI schemas from URLs, files, or data objects
+- **Type Generation**: Generate TypeScript interfaces, enums, and type aliases
+- **API Client Generation**: Generate fully typed API client classes
+- **Plugin System**: Extensible plugin architecture for custom functionality
+- **CLI Interface**: Command-line interface with rich configuration options
+- **Validation**: Built-in OpenAPI schema validation
+- **Customization**: Flexible configuration for naming, filtering, and transformations
+- **FastAPI Integration**: Optimized for FastAPI applications
+- **React Support**: Generate React hooks and query builders
+- **TypeScript Strict Mode**: Full TypeScript strict mode support
+
+### Technical Details
+
+- **Zero Dependencies**: No runtime dependencies on external libraries
+- **Modular Architecture**: Clean separation of concerns with extensible design
+- **Type Safety**: Comprehensive TypeScript types with no `any` usage
+- **Performance**: Optimized for large schemas and complex APIs
+- **Error Handling**: Graceful error handling with detailed error messages
+- **Testing**: Comprehensive test suite with 100% coverage goals
+
+## [0.1.0] - 2024-09-12
+
+### Added
+
+- Initial release
+- Core functionality for OpenAPI schema parsing and TypeScript generation
+- Plugin system architecture
+- CLI interface
+- Documentation and examples
+
+### Changed
+
+- N/A (initial release)
+
+### Deprecated
+
+- N/A (initial release)
+
+### Removed
+
+- N/A (initial release)
+
+### Fixed
+
+- N/A (initial release)
+
+### Security
+
+- N/A (initial release)

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 Schemantic
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024 Schemantic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.