@gabrielbryk/json-schema-to-zod 2.12.1 → 2.13.0

package/.github/RELEASE_SETUP.md

@@ -0,0 +1,120 @@
+# Release Workflow Setup Guide
+
+This document explains how to set up automated releases for this package.
+
+## Prerequisites
+
+1. **NPM Account**: You need an npm account with publish permissions
+2. **GitHub Repository**: Repository must be on GitHub
+3. **Repository Secrets**: Configure the following secrets in your GitHub repository
+
+## Setup Steps
+
+### 1. Create NPM Access Token
+
+1. Go to [npmjs.com](https://www.npmjs.com/) and log in
+2. Click on your profile → "Access Tokens"
+3. Click "Generate New Token" → "Classic Token"
+4. Select "Automation" type (for CI/CD)
+5. Copy the generated token
+
+### 2. Add GitHub Secret
+
+1. Go to your GitHub repository
+2. Navigate to Settings → Secrets and variables → Actions
+3. Click "New repository secret"
+4. Name: `NPM_TOKEN`
+5. Value: Paste your npm token
+6. Click "Add secret"
+
+### 3. How It Works
+
+The release workflow (`.github/workflows/release.yml`) automatically:
+
+1. **On every push to `main` branch**:
+   - Checks for changesets
+   - If changesets exist, creates a "Release" PR
+   - The PR includes version bumps and CHANGELOG updates
+
+2. **When you merge the Release PR**:
+   - Automatically publishes to npm
+   - Creates GitHub releases
+   - Updates version tags
+
+### 4. Creating a Release
+
+```bash
+# 1. Make your changes and commit them
+git add .
+git commit -m "feat: add new feature"
+
+# 2. Create a changeset
+pnpx changeset
+# Follow the prompts:
+# - Select the type of change (major/minor/patch)
+# - Describe the changes for the changelog
+
+# 3. Commit the changeset
+git add .
+git commit -m "chore: add changeset"
+
+# 4. Push to main (or create a PR)
+git push origin main
+
+# 5. The workflow will create a Release PR automatically
+# 6. Review and merge the Release PR to publish
+```
+
+## Changeset Types
+
+- **Major** (2.0.0 → 3.0.0): Breaking changes
+- **Minor** (2.0.0 → 2.1.0): New features (backward compatible)
+- **Patch** (2.0.0 → 2.0.1): Bug fixes
+
+## Manual Release (Alternative)
+
+If you prefer manual releases:
+
+```bash
+# 1. Create and commit changesets as above
+pnpx changeset
+
+# 2. Version the package
+pnpm run local-release
+
+# 3. Push changes
+git push --follow-tags
+```
+
+## Troubleshooting
+
+### Release workflow fails with "401 Unauthorized"
+
+- Check that `NPM_TOKEN` secret is set correctly
+- Verify the token has publish permissions
+- Ensure the token hasn't expired
+
+### No Release PR is created
+
+- Verify there are changesets in `.changeset/` directory
+- Check the workflow logs in GitHub Actions
+- Ensure you're pushing to the `main` branch
+
+### Package name already exists on npm
+
+- Update the `name` field in `package.json`
+- Ensure you have permissions to publish to that package name
+
+## Best Practices
+
+1. **Always create changesets** for user-facing changes
+2. **Write clear changeset descriptions** - they become your changelog
+3. **Review Release PRs carefully** before merging
+4. **Use semantic versioning** appropriately
+5. **Test locally** with `pnpm run ci` before pushing
+
+## Additional Resources
+
+- [Changesets Documentation](https://github.com/changesets/changesets)
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [npm Publishing Guide](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry)

package/.github/TOOLING_GUIDE.md

@@ -0,0 +1,169 @@
+# Tooling Guide
+
+This document provides an overview of all the automated tooling configured in this project.
+
+## 🔍 Code Quality Tools
+
+### ESLint
+
+- **Purpose**: Static code analysis and linting
+- **Config**: `eslint.config.js` (ESLint v9 flat config)
+- **Run**: `pnpm run lint` or `pnpm run lint:fix`
+- **Features**:
+  - TypeScript ESLint rules
+  - Enforced no `require` imports
+
+### Prettier
+
+- **Purpose**: Code formatting
+- **Config**: `.prettierrc`
+- **Run**: `pnpm run format:write` or `pnpm run format:check`
+- **Settings**:
+  - Double quotes
+  - Semicolons
+  - 100 character line width
+  - 2 space indentation
+
+### TypeScript
+
+- **Purpose**: Type checking and compilation
+- **Config**: `tsconfig.json`
+- **Run**: `pnpm run build:esm`
+
+## ✅ Commit Quality
+
+### Commitlint
+
+- **Purpose**: Enforce conventional commit messages
+- **Config**: `commitlint.config.js`
+- **Hook**: `.husky/commit-msg`
+- **Format**: `type: subject` (e.g., `feat: add new feature`)
+- **Allowed types**:
+  - `feat`, `fix`, `docs`, `style`, `refactor`
+  - `perf`, `test`, `build`, `ci`, `chore`, `revert`
+
+### Husky
+
+- **Purpose**: Git hooks management
+- **Config**: `.husky/` directory
+- **Hooks**:
+  - `pre-commit`: Runs lint-staged
+  - `commit-msg`: Runs commitlint
+
+### Lint-staged
+
+- **Purpose**: Run linters on staged files only
+- **Config**: `.lintstagedrc.json`
+- **Actions**:
+  - Format with Prettier
+  - Fix with ESLint
+
+## 🧪 Testing
+
+### Jest
+
+- **Purpose**: Unit testing
+- **Config**: `jest.config.mjs`
+- **Run**: `pnpm run test` or `pnpm run dev` (watch mode)
+
+## 📦 Build & Package
+
+- **Build**: `pnpm run build` (generates index, runs tests, and emits ESM + types)
+- **Smoke test**: `pnpm run smoke:esm`
+
+## 📝 Version Management
+
+### Changesets
+
+- **Purpose**: Version management and changelog generation
+- **Config**: `.changeset/config.json`
+- **Usage**:
+  ```bash
+  pnpx changeset
+  pnpm run local-release
+  ```
+- **Features**:
+  - Semantic versioning
+  - Automatic CHANGELOG.md generation
+
+## 🤖 CI/CD
+
+### GitHub Actions - CI Workflow
+
+- **File**: `.github/workflows/ci.yml`
+- **Trigger**: Push and Pull Requests
+- **Steps**:
+  1. Install dependencies with pnpm
+  2. Run full CI pipeline (`pnpm run ci`)
+
+### GitHub Actions - Release Workflow
+
+- **File**: `.github/workflows/release.yml`
+- **Trigger**: Push to `main` branch
+- **Steps**:
+  1. Build package
+  2. Create Release PR (if changesets exist)
+  3. Publish to npm (when Release PR is merged)
+- **Setup**: See `.github/RELEASE_SETUP.md`
+
+### GitHub Actions - Security Audit
+
+- **File**: `.github/workflows/security.yml`
+- **Trigger**: Weekly schedule and dependency changes
+- **Steps**:
+  1. Run `pnpm audit`
+  2. Warn on high/critical vulnerabilities
+
+### Dependabot
+
+- **File**: `.github/dependabot.yml`
+- **Purpose**: Automated dependency updates
+- **Schedule**: Weekly on Mondays at 9:00 AM UTC
+- **Features**:
+  - Groups minor/patch updates
+  - Updates GitHub Actions
+
+## 🔄 Workflow Summary
+
+### Development Workflow
+
+```bash
+# 1. Make changes
+git checkout -b feature/my-feature
+
+# 2. Write code and tests
+
+# 3. Commit (commitlint validates, lint-staged runs)
+git commit -m "feat: add new feature"
+
+# 4. Push and create PR
+git push origin feature/my-feature
+
+# 5. CI runs automatically on PR
+# 6. Merge when CI passes
+```
+
+### Release Workflow
+
+```bash
+# 1. Create a changeset
+pnpx changeset
+
+# 2. Commit changeset
+git commit -m "chore: add changeset"
+
+# 3. Push to main (or create a PR)
+git push origin main
+
+# 4. The workflow creates a Release PR automatically
+# 5. Review and merge Release PR to publish
+```
+
+## 📊 Quality Gates
+
+All PRs must pass:
+
+- ✅ Build succeeds
+- ✅ Code is formatted (Prettier)
+- ✅ No linting errors (ESLint)
+- ✅ Tests pass (Jest)

package/.github/dependabot.yml

@@ -0,0 +1,52 @@
+# Dependabot configuration for automated dependency updates
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  # Maintain npm dependencies
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+    open-pull-requests-limit: 10
+    assignees:
+      - "gabrielbryk"
+    commit-message:
+      prefix: "chore"
+      prefix-development: "chore"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "automated"
+    groups:
+      # Group all patch and minor updates together
+      development-dependencies:
+        dependency-type: "development"
+        update-types:
+          - "minor"
+          - "patch"
+      production-dependencies:
+        dependency-type: "production"
+        update-types:
+          - "minor"
+          - "patch"
+
+  # Maintain GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+    open-pull-requests-limit: 5
+    assignees:
+      - "gabrielbryk"
+    commit-message:
+      prefix: "ci"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "github-actions"
+      - "automated"

package/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run CI
+        run: pnpm run ci

package/.github/workflows/release.yml

@@ -6,6 +6,8 @@ on:
       - main
   workflow_dispatch:
 
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
 permissions:
   contents: write
   pull-requests: write
@@ -28,13 +30,17 @@ jobs:
           cache: pnpm
           registry-url: https://registry.npmjs.org
 
-      - name: Install dependencies
+      - name: Update npm (trusted publishing requires >=11.5.1)
+        run: npm install -g npm@latest
+
+      - name: Install Dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Build
-        run: pnpm build
+      - name: Build Package
+        run: pnpm run build
 
-      - name: Release with Changesets
+      - name: Create Release Pull Request or Publish to npm
+        id: changesets
         uses: changesets/action@v1
         with:
           commit: "ci: release"
@@ -43,3 +49,5 @@ jobs:
           publish: pnpm changeset publish --access public
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ""
+          NODE_AUTH_TOKEN: ""

package/.github/workflows/security.yml

@@ -0,0 +1,40 @@
+name: Security Audit
+
+on:
+  schedule:
+    # Run every Monday at 9:00 AM UTC
+    - cron: "0 9 * * 1"
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - "package.json"
+      - "pnpm-lock.yaml"
+
+jobs:
+  audit:
+    name: Security Audit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v6
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+
+      - name: Run Security Audit
+        run: pnpm audit --audit-level=moderate
+        continue-on-error: true
+
+      - name: Check for Vulnerabilities
+        run: |
+          if pnpm audit --audit-level=high --json > audit.json; then
+            echo "No high or critical vulnerabilities found"
+          else
+            echo "::warning::High or critical vulnerabilities detected. Please review."
+            cat audit.json
+          fi

package/.husky/commit-msg

@@ -0,0 +1 @@
+pnpx commitlint --edit $1

package/.husky/pre-commit

@@ -0,0 +1 @@
+pnpm run lint-staged

package/.lintstagedrc.json

@@ -0,0 +1,3 @@
+{
+  "*.{js,jsx,ts,tsx,json,md,yml}": ["prettier --write", "pnpm run lint:fix"]
+}

package/.prettierrc

@@ -0,0 +1,20 @@
+{
+  "arrowParens": "always",
+  "bracketSpacing": true,
+  "endOfLine": "lf",
+  "htmlWhitespaceSensitivity": "css",
+  "insertPragma": false,
+  "singleAttributePerLine": false,
+  "bracketSameLine": false,
+  "jsxSingleQuote": false,
+  "printWidth": 100,
+  "proseWrap": "preserve",
+  "quoteProps": "as-needed",
+  "requirePragma": false,
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "useTabs": false,
+  "embeddedLanguageFormatting": "auto"
+}

package/AGENTS.md

@@ -1,12 +1,14 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
+
 - `src/`: TypeScript source; CLI entry in `src/cli.ts`, library entry in `src/index.ts`, conversion logic in `src/jsonSchemaToZod.ts`, parsers under `src/parsers/`, and helpers in `src/utils/`.
 - `test/`: TS test suite executed via `tsx`; fixtures live in `test/fixtures/`; snapshots in `test/generateSchemaBundle.snap.test.ts`.
 - `docs/`: Design proposals. Build outputs land in `dist/`; do not edit generated files.
 - `scripts/` and `createIndex.ts`: Codegen utilities used during builds.
 
 ## Build, Test, and Development Commands
+
 - Install with `pnpm install` (pinned `pnpm@10.x`).
 - `pnpm gen`: Regenerate index exports.
 - `pnpm test`: Run the TSX-based test suite.
@@ -16,29 +18,34 @@
 - `pnpm smoke:esm`: Quick check that the ESM bundle imports and runs.
 
 ## Coding Style & Naming Conventions
+
 - Language: TypeScript with NodeNext/ESM; keep `.js` extensions on internal imports. Package ships ESM-only with flat `dist/`; avoid adding CJS outputs or require-based entrypoints. Build config lives in `tsconfig.build.json`.
 - Indentation: 2 spaces; include semicolons; prefer camelCase for functions/vars and PascalCase for types.
 - Avoid CommonJS `require`; ESLint forbids it. Keep functions small and pure.
 - Use existing utility patterns (e.g., `withMessage`, `buildRefRegistry`) before adding helpers.
 
 ## Code Quality & Best Practices
+
 - Type safety first: prefer explicit generics and narrow types over `any`; keep option shapes well-typed and avoid implicit `unknown` casts.
 - Embrace SOLID: single-purpose parsers/utilities, extract shared helpers, and inject collaborators instead of hard-coding globals.
 - Validate boundary cases: cyclical refs, `$ref` resolution, discriminated unions, and recursion depth—add targeted tests when touching those paths.
 - Keep emitted code deterministic; avoid data-dependent randomness or network calls in conversion paths.
 
 ## Testing Guidelines
+
 - Tests use a lightweight harness in `test/suite.ts`; add new suites under `test/` mirroring module paths.
 - Prefer fixtures in `test/fixtures/` for schema examples; extend snapshots only when behavior intentionally changes.
 - Cover new parsing paths; add regression cases for edge refs/recursion.
 - Run `pnpm test` (or `pnpm dev`) before opening a PR.
 
 ## Commit & Pull Request Guidelines
+
 - Open an issue first; PRs without one are usually not considered (`CONTRIBUTING.md`).
 - Commit messages are short and imperative; gitmoji is welcome but optional. Keep related changes in separate commits.
 - PRs should describe the problem, approach, and risks; link the issue and note test coverage or added fixtures. Screenshots are unnecessary unless CLI UX changes.
 - Keep PR scope tight; avoid editing generated `dist/` files. Mention breaking changes explicitly.
 
 ## Security & Configuration Tips
+
 - Avoid adding runtime dependencies that fetch remotely; conversions should stay deterministic and offline.
 - When touching CLI paths, ensure `--module`, `--type`, and `$ref` handling stay backward compatible; add tests for recursion and bundle ordering when modifying ref logic.

package/CHANGELOG.md

@@ -1,9 +1,16 @@
 # @gabrielbryk/json-schema-to-zod
 
+## 2.13.0
+
+### Minor Changes
+
+- 1e42453: Trigger minor release after CI/tooling alignment.
+
 ## 2.12.1
 
 ### Patch Changes
 
+- d57f812: Align Zod output with Zod v4 idiomatic patterns, including strict/loose object helpers, exact optional properties, and broader discriminated union detection. Also improve recursive getter emissions to avoid TS7056 via explicit type annotations.
 - e8cbafc: Fix `unevaluatedProperties: false` with `oneOf` by avoiding strict union branches, allowing base properties through, and enforcing unknown-key rejection after composition.
 
 ## 2.12.0
@@ -26,7 +33,6 @@
 ### Patch Changes
 
 - 466d672: Fix TS7056 error when generating declarations for schemas referencing recursive types
-
   - Add explicit type annotations to any schema that references recursive schemas (not just unions)
   - This prevents TypeScript from trying to serialize extremely large expanded types when generating .d.ts files
   - Fix type narrowing in parseObject for allOf required array handling
@@ -38,19 +44,16 @@
 - 2656c90: Fix Zod v4 type compatibility and improve discriminated union detection
 
   ### Zod v4 Type Fixes
-
   - Remove `ZodEffects` usage which doesn't exist in Zod v4
   - `.superRefine()` and `.refine()` no longer change the schema type
   - `.transform()` now correctly returns `ZodPipe` type instead of `ZodEffects`
 
   ### Discriminated Union Detection Improvements
-
   - Enhanced `findImplicitDiscriminator` to detect discriminators in `allOf` members
   - Properly resolves `$ref` when checking for discriminator values
   - Correctly collects `required` fields from both parent schema and `allOf` members
 
   ### Cleaner Output Generation
-
   - Simplified `parseAllOf` to avoid generating redundant `z.record().superRefine()` patterns
   - Build proper object types with specific property annotations instead of generic `ZodObject<Record<string, ZodTypeAny>>`
   - Intersection types are now properly tracked and reflected in type annotations

package/README.md

@@ -47,15 +47,15 @@ json-refs resolve mySchema.json | json-schema-to-zod | prettier --parser typescr
 
 #### Options
 
-| Flag           | Shorthand | Function                                                                                       |
-| -------------- | --------- | ---------------------------------------------------------------------------------------------- |
-| `--input`      | `-i`      | JSON or a source file path. Required if no data is piped.                                      |
-| `--output`     | `-o`      | A file path to write to. If not supplied stdout will be used.                                  |
-| `--name`       | `-n`      | The name of the schema in the output                                                           |
-| `--depth`      | `-d`      | Maximum depth of recursion in schema before falling back to `z.any()`. Defaults to 0.          |
-| `--type`       | `-t`      | Export a named type along with the schema. Requires `name` to be set. |
-| `--noImport`   | `-ni`     | Removes the `import { z } from 'zod';` or equivalent from the output.                          |
-| `--withJsdocs` | `-wj`     | Generate jsdocs off of the description property.                                               |
+| Flag           | Shorthand | Function                                                                              |
+| -------------- | --------- | ------------------------------------------------------------------------------------- |
+| `--input`      | `-i`      | JSON or a source file path. Required if no data is piped.                             |
+| `--output`     | `-o`      | A file path to write to. If not supplied stdout will be used.                         |
+| `--name`       | `-n`      | The name of the schema in the output                                                  |
+| `--depth`      | `-d`      | Maximum depth of recursion in schema before falling back to `z.any()`. Defaults to 0. |
+| `--type`       | `-t`      | Export a named type along with the schema. Requires `name` to be set.                 |
+| `--noImport`   | `-ni`     | Removes the `import { z } from 'zod';` or equivalent from the output.                 |
+| `--withJsdocs` | `-wj`     | Generate jsdocs off of the description property.                                      |
 
 ### Programmatic
 

package/commitlint.config.js

@@ -0,0 +1,24 @@
+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", ["upper-case"]],
+    "header-max-length": [2, "always", 100],
+  },
+};

package/createIndex.ts

@@ -15,7 +15,7 @@ function checkSrcDir(path: string): string[] {
     if (statSync(itemPath).isDirectory()) {
       lines.push(...checkSrcDir(itemPath));
     } else if (item.endsWith(".ts")) {
-      lines.push('export * from "./' + itemPath.slice(4, -2) + 'js"');
+      lines.push('export * from "./' + itemPath.slice(4, -2) + 'js";');
     }
   }
 
@@ -25,8 +25,8 @@ function checkSrcDir(path: string): string[] {
 const lines = checkSrcDir("src");
 
 lines.push(
-  'import { jsonSchemaToZod } from "./jsonSchemaToZod.js"',
-  "export default jsonSchemaToZod",
+  'import { jsonSchemaToZod } from "./jsonSchemaToZod.js";',
+  "export default jsonSchemaToZod;"
 );
 
-writeFileSync("./src/index.ts", lines.join("\n"));
+writeFileSync("./src/index.ts", `${lines.join("\n")}\n`);

package/dist/cli.js

@@ -7,8 +7,7 @@ const params = {
     input: {
         shorthand: "i",
         value: "string",
-        required: process.stdin.isTTY &&
-            "input is required when no JSON or file path is piped",
+        required: process.stdin.isTTY && "input is required when no JSON or file path is piped",
         description: "JSON or a source file path. Required if no data is piped.",
     },
     output: {
@@ -29,11 +28,11 @@ const params = {
     type: {
         shorthand: "t",
         value: "string",
-        description: "The name of the (optional) inferred type export."
+        description: "The name of the (optional) inferred type export.",
     },
     noImport: {
         shorthand: "ni",
-        description: "Removes the `import { z } from 'zod';` or equivalent from the output."
+        description: "Removes the `import { z } from 'zod';` or equivalent from the output.",
     },
     withJsdocs: {
         shorthand: "wj",