zod-codegen 1.0.0

package/README.md

@@ -0,0 +1,263 @@
+# zod-codegen
+
+[![npm version](https://img.shields.io/npm/v/zod-codegen.svg)](https://www.npmjs.com/package/zod-codegen)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![CI](https://github.com/julienandreu/zod-codegen/workflows/CI/badge.svg)](https://github.com/julienandreu/zod-codegen/actions)
+[![Coverage](https://img.shields.io/codecov/c/github/julienandreu/zod-codegen)](https://codecov.io/gh/julienandreu/zod-codegen)
+
+A powerful TypeScript code generator that creates **Zod schemas** and **type-safe clients** from OpenAPI specifications.
+
+## 🚀 Features
+
+- **🔥 Zod Schema Generation**: Automatically generate Zod validation schemas from OpenAPI specs
+- **🎯 Type-Safe**: Full TypeScript support with generated types
+- **📡 Multiple Formats**: Support for OpenAPI 3.x, Swagger 2.0, JSON, and YAML
+- **🌐 Remote Files**: Fetch OpenAPI specs from URLs
+- **⚡ Fast**: Optimized for performance with minimal dependencies
+- **🔧 Configurable**: Flexible output options and customization
+- **📦 CLI & Programmatic**: Use as a CLI tool or integrate into your build process
+
+## 📦 Installation
+
+### Global Installation (CLI)
+
+```bash
+npm install -g zod-codegen
+```
+
+### Project Installation
+
+```bash
+npm install --save-dev zod-codegen
+```
+
+## 🔧 Usage
+
+### Command Line Interface
+
+```bash
+# Generate from local file
+zod-codegen --input ./openapi.json --output ./generated
+
+# Generate from URL
+zod-codegen --input https://api.example.com/openapi.json --output ./api
+
+# Generate with custom output directory
+zod-codegen -i ./swagger.yaml -o ./src/generated
+```
+
+#### CLI Options
+
+| Option      | Alias | Description                         | Default     |
+| ----------- | ----- | ----------------------------------- | ----------- |
+| `--input`   | `-i`  | Path or URL to OpenAPI file         | Required    |
+| `--output`  | `-o`  | Directory to output generated files | `generated` |
+| `--help`    | `-h`  | Show help                           |             |
+| `--version` | `-v`  | Show version                        |             |
+
+### Programmatic Usage
+
+```typescript
+import {Generator} from 'zod-codegen';
+
+const generator = new Generator();
+
+// Generate from local file
+await generator.generate({
+  input: './openapi.json',
+  output: './generated',
+});
+
+// Generate from URL
+await generator.generate({
+  input: 'https://api.example.com/openapi.json',
+  output: './api',
+});
+```
+
+## 📁 Generated Output
+
+The generator creates the following structure:
+
+```
+generated/
+├── schemas/           # Zod validation schemas
+│   ├── user.schema.ts
+│   └── product.schema.ts
+├── types/            # TypeScript type definitions
+│   ├── user.types.ts
+│   └── product.types.ts
+└── client/           # Type-safe API client
+    └── api.client.ts
+```
+
+## 🎯 Example
+
+Given this OpenAPI specification:
+
+```yaml
+openapi: 3.0.0
+info:
+  title: User API
+  version: 1.0.0
+paths:
+  /users:
+    get:
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: integer
+                  name:
+                    type: string
+                  email:
+                    type: string
+                    format: email
+                required: [id, name, email]
+```
+
+**Generated Zod Schema** (`schemas/user.schema.ts`):
+
+```typescript
+import {z} from 'zod';
+
+export const UserSchema = z.object({
+  id: z.number().int(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+export type User = z.infer<typeof UserSchema>;
+```
+
+**Generated Types** (`types/user.types.ts`):
+
+```typescript
+export interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+```
+
+**Generated Client** (`client/api.client.ts`):
+
+```typescript
+import {UserSchema, type User} from '../schemas/user.schema.js';
+
+export class ApiClient {
+  async getUsers(): Promise<User[]> {
+    const response = await fetch('/api/users');
+    const data = await response.json();
+    return UserSchema.array().parse(data);
+  }
+}
+```
+
+## 🛠️ Development
+
+### Prerequisites
+
+- Node.js ≥ 18.0.0
+- npm or yarn
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/julienandreu/zod-codegen.git
+cd zod-codegen
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run tests
+npm test
+
+# Run linting
+npm run lint
+
+# Format code
+npm run format
+```
+
+### Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests with UI
+npm run test:ui
+```
+
+### Available Scripts
+
+| Script                  | Description                                     |
+| ----------------------- | ----------------------------------------------- |
+| `npm run build`         | Build the project                               |
+| `npm run build:watch`   | Build in watch mode                             |
+| `npm run dev`           | Development mode with example                   |
+| `npm test`              | Run tests                                       |
+| `npm run test:watch`    | Run tests in watch mode                         |
+| `npm run test:coverage` | Run tests with coverage                         |
+| `npm run lint`          | Lint and fix code                               |
+| `npm run format`        | Format code with Prettier                       |
+| `npm run type-check`    | Type check without emitting                     |
+| `npm run validate`      | Run all checks (lint, format, type-check, test) |
+| `npm run clean`         | Clean build artifacts                           |
+
+## 📋 Requirements
+
+- **Node.js**: ≥ 18.0.0
+- **TypeScript**: ≥ 5.0.0
+- **Zod**: ≥ 3.20.0
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Quick Start for Contributors
+
+1. Fork the repository
+2. Create your feature branch: `git checkout -b feature/amazing-feature`
+3. Make your changes
+4. Run tests: `npm test`
+5. Run validation: `npm run validate`
+6. Commit your changes: `git commit -m 'feat: add amazing feature'`
+7. Push to the branch: `git push origin feature/amazing-feature`
+8. Open a Pull Request
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- [Zod](https://zod.dev/) - TypeScript-first schema validation
+- [OpenAPI Specification](https://www.openapis.org/) - API specification standard
+- [TypeScript](https://www.typescriptlang.org/) - Typed JavaScript
+
+## 📞 Support
+
+- 🐛 **Bug reports**: [GitHub Issues](https://github.com/julienandreu/zod-codegen/issues)
+- 💬 **Questions**: [GitHub Discussions](https://github.com/julienandreu/zod-codegen/discussions)
+- 📧 **Email**: [julienandreu@me.com](mailto:julienandreu@me.com)
+
+---
+
+Made with ❤️ by [Julien Andreu](https://github.com/julienandreu)

package/SECURITY.md

@@ -0,0 +1,108 @@
+# Security Policy
+
+## Supported Versions
+
+We actively support the following versions of zod-codegen:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x.x   | :white_check_mark: |
+| 0.1.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+The zod-codegen team takes security bugs seriously. We appreciate your efforts to responsibly disclose your findings, and will make every effort to acknowledge your contributions.
+
+### How to Report Security Issues
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+Instead, please report them via email to: [julienandreu@me.com](mailto:julienandreu@me.com)
+
+Please include the following information in your report:
+
+- Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
+- Full paths of source file(s) related to the manifestation of the issue
+- The location of the affected source code (tag/branch/commit or direct URL)
+- Any special configuration required to reproduce the issue
+- Step-by-step instructions to reproduce the issue
+- Proof-of-concept or exploit code (if possible)
+- Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.
+
+### Response Timeline
+
+- **Initial Response**: We will acknowledge receipt of your vulnerability report within 48 hours.
+- **Progress Updates**: We will send you regular updates about our progress, at least every 7 days.
+- **Resolution**: We aim to resolve critical vulnerabilities within 30 days of the initial report.
+
+### Disclosure Policy
+
+When we receive a security bug report, we will:
+
+1. Confirm the problem and determine the affected versions
+2. Audit code to find any potential similar problems
+3. Prepare fixes for all supported versions
+4. Release new versions as soon as possible
+5. Prominently announce the issue in the release notes
+
+### Bug Bounty Program
+
+Currently, we do not offer a paid bug bounty program. We express our gratitude to security researchers through:
+
+- Public acknowledgment in our security advisories (if desired)
+- Recognition in our project documentation
+- Direct communication and thanks from our team
+
+## Security Best Practices
+
+When using zod-codegen, please follow these security best practices:
+
+### Input Validation
+
+- Always validate OpenAPI specifications from untrusted sources
+- Be cautious when processing large or complex OpenAPI files
+- Consider file size limits and timeout mechanisms
+
+### Output Security
+
+- Review generated code before using in production
+- Ensure generated validation schemas are appropriate for your use case
+- Test generated code thoroughly
+
+### Dependencies
+
+- Keep zod-codegen and its dependencies up to date
+- Regularly audit your dependency tree for known vulnerabilities
+- Use tools like `npm audit` to check for security issues
+
+## Known Security Considerations
+
+### OpenAPI Processing
+
+- **File Size**: Very large OpenAPI files may consume significant memory
+- **Circular References**: Complex schemas with circular references are handled but may impact performance
+- **Remote Files**: When fetching OpenAPI specs from URLs, ensure the sources are trusted
+
+### Generated Code
+
+- **Validation Logic**: Generated Zod schemas provide runtime validation but should be part of a broader security strategy
+- **Type Safety**: While generated TypeScript types provide compile-time safety, always validate runtime data
+
+## Security Updates
+
+Security updates will be clearly marked in our release notes and will be given priority in our release schedule. We recommend:
+
+- Subscribing to release notifications
+- Keeping your installation up to date
+- Testing updates in a development environment before production deployment
+
+## Contact
+
+For questions about this security policy, please contact:
+
+- Email: [julienandreu@me.com](mailto:julienandreu@me.com)
+- GitHub: [@julienandreu](https://github.com/julienandreu)
+
+Thank you for helping keep zod-codegen and our users safe!

package/codecov.yml

@@ -0,0 +1,29 @@
+coverage:
+  status:
+    project:
+      default:
+        target: 80%
+        threshold: 2%
+        base: auto
+    patch:
+      default:
+        target: 80%
+        threshold: 2%
+        base: auto
+
+  ignore:
+    - 'dist/'
+    - 'coverage/'
+    - 'node_modules/'
+    - '**/*.d.ts'
+    - '**/*.config.*'
+    - '**/*.test.*'
+    - '**/*.spec.*'
+    - 'scripts/'
+    - 'samples/'
+    - '.github/'
+
+comment:
+  layout: 'reach,diff,flags,tree'
+  behavior: default
+  require_changes: false

package/commitlint.config.mjs

@@ -0,0 +1,28 @@
+export default {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [
+      2,
+      'always',
+      [
+        'feat',
+        'fix',
+        'docs',
+        'style',
+        'refactor',
+        'perf',
+        'test',
+        'build',
+        'ci',
+        'chore',
+        'revert',
+      ],
+    ],
+    'subject-case': [2, 'never', ['sentence-case', 'start-case', 'pascal-case', 'upper-case']],
+    'subject-empty': [2, 'never'],
+    'subject-full-stop': [2, 'never', '.'],
+    'header-max-length': [2, 'always', 100],
+    'footer-max-line-length': [0],
+    'footer-leading-blank': [0],
+  },
+};

package/dist/scripts/update-manifest.js

@@ -0,0 +1,31 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { z } from 'zod';
+/**
+ * Type guard for the package.json object
+ *
+ * @param input Unknown input
+ * @returns true if the input is an event object
+ */
+export function isPackageJson(input) {
+    const event = z
+        .object({
+        name: z.string(),
+        version: z.string(),
+        description: z.string(),
+    })
+        .strict()
+        .catchall(z.any())
+        .required();
+    const { success } = event.safeParse(input);
+    return success;
+}
+const sourcePath = resolve(__dirname, '..', 'package.json');
+const data = JSON.parse(readFileSync(sourcePath, 'utf8'));
+if (!isPackageJson(data)) {
+    process.exit(1);
+}
+const { name, version, description } = data;
+const targetPath = resolve(__dirname, '..', 'src', 'assets', 'manifest.json');
+writeFileSync(targetPath, JSON.stringify({ name, version, description }, null, 2));
+process.exit(0);

package/dist/src/assets/manifest.json

@@ -0,0 +1,5 @@
+{
+  "name": "zod-codegen",
+  "version": "0.1.0-alpha.1",
+  "description": "Zod code generator"
+}

package/dist/src/cli.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { Generator } from './generator.js';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import loudRejection from 'loud-rejection';
+import { handleErrors } from './utils/error-handler.js';
+import { handleSignals } from './utils/signal-handler.js';
+import debug from 'debug';
+import { isManifest } from './utils/manifest.js';
+import { Reporter } from './utils/reporter.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const manifestData = JSON.parse(readFileSync(join(__dirname, 'assets', 'manifest.json'), 'utf-8'));
+if (!isManifest(manifestData)) {
+    process.exit(1);
+}
+const { name, description, version } = manifestData;
+const reporter = new Reporter(process.stdout);
+const startTime = process.hrtime.bigint();
+debug(`${name}:${String(process.pid)}`);
+loudRejection();
+handleSignals(process, startTime);
+handleErrors(process, startTime);
+const argv = yargs(hideBin(process.argv))
+    .scriptName(name)
+    .usage(`${description}\n\nUsage: $0 [options]`)
+    .version(version)
+    .option('input', {
+    alias: 'i',
+    type: 'string',
+    description: 'Path or URL to OpenAPI file',
+    demandOption: true,
+})
+    .option('output', {
+    alias: 'o',
+    type: 'string',
+    description: 'Directory to output the generated files',
+    default: 'generated',
+})
+    .help()
+    .parseSync();
+const { input, output } = argv;
+void (async () => {
+    try {
+        const generator = new Generator(name, version, reporter, input, output);
+        const exitCode = await generator.run();
+        process.exit(exitCode);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            reporter.error(`Fatal error: ${error.message}`);
+        }
+        else {
+            reporter.error('An unknown fatal error occurred');
+        }
+        process.exit(1);
+    }
+})();

package/dist/src/generator.js

@@ -0,0 +1,55 @@
+import { OpenApiFileParserService, SyncFileReaderService } from './services/file-reader.service.js';
+import { TypeScriptCodeGeneratorService } from './services/code-generator.service.js';
+import { SyncFileWriterService } from './services/file-writer.service.js';
+export class Generator {
+    _name;
+    _version;
+    reporter;
+    inputPath;
+    _outputDir;
+    fileReader = new SyncFileReaderService();
+    fileParser = new OpenApiFileParserService();
+    codeGenerator = new TypeScriptCodeGeneratorService();
+    fileWriter;
+    outputPath;
+    constructor(_name, _version, reporter, inputPath, _outputDir) {
+        this._name = _name;
+        this._version = _version;
+        this.reporter = reporter;
+        this.inputPath = inputPath;
+        this._outputDir = _outputDir;
+        this.fileWriter = new SyncFileWriterService(this._name, this._version, inputPath);
+        this.outputPath = this.fileWriter.resolveOutputPath(this._outputDir);
+    }
+    async run() {
+        try {
+            const rawSource = this.readFile();
+            const openApiSpec = this.parseFile(rawSource);
+            const generatedCode = this.generateCode(openApiSpec);
+            this.writeFile(generatedCode);
+            this.reporter.log(`✅ Generated types successfully at: ${this.outputPath}`);
+            return 0;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.reporter.error(`❌ Error: ${error.message}`);
+            }
+            else {
+                this.reporter.error('❌ An unknown error occurred');
+            }
+            return Promise.resolve(1);
+        }
+    }
+    readFile() {
+        return this.fileReader.readFile(this.inputPath);
+    }
+    parseFile(source) {
+        return this.fileParser.parse(source);
+    }
+    generateCode(spec) {
+        return this.codeGenerator.generate(spec);
+    }
+    writeFile(content) {
+        this.fileWriter.writeFile(this.outputPath, content);
+    }
+}