contributing-to-z-schema

z-schema への貢献

z-schema は TypeScript で記述された JSON Schema バリデーター（draft-04 から draft-2020-12 まで）です。このスキルでは、開発ワークフロー、コードベースの調べ方、一般的な貢献タスクについて説明します。

リポジトリのセットアップ

git clone --recursive https://github.com/zaggino/z-schema.git
cd z-schema
npm install

--recursive を指定せずにすでにクローンしている場合（json-schema-spec/ サブモジュールに必要です）：

git submodule update --init --recursive

品質チェック

プッシュする前に、すべてのチェックを実行してください：

npm run check           # ultracite check (oxlint type-aware + oxfmt format check)
npm run build           # TypeScript + Rollup
npm run build:tests     # Type-check tests
npm test                # Vitest (node + browser)

コミット前フックは、ステージングされたファイルに対して lint と format を自動実行します。プッシュ前フックは、ビルドと型チェックを実行します。

コードベースの構成

src/
  index.ts              → Public API (all exports)
  z-schema.ts           → Factory + ZSchema/ZSchemaSafe/ZSchemaAsync/ZSchemaAsyncSafe
  z-schema-base.ts      → Core validation orchestration
  schema-compiler.ts    → $ref resolution, id collection, schema compilation
  schema-validator.ts   → Schema-level validation against meta-schemas
  json-validation.ts    → Validation orchestration (validate, recurse*, collectEvaluated)
  validation/            → Keyword validators split by category
    shared.ts            → Shared types (JsonValidatorFn), vocab helpers, caching utilities
    type.ts              → type, enum, const validators
    numeric.ts           → multipleOf, minimum, maximum, exclusiveMin/Max validators
    string.ts            → minLength, maxLength, pattern, format, content* validators
    array.ts             → items, prefixItems, contains, min/maxItems, uniqueItems validators
    object.ts            → properties, patternProperties, additionalProperties, required, etc.
    combinators.ts       → allOf, anyOf, oneOf, not, if/then/else validators
    ref.ts               → $dynamicRef/$recursiveRef resolution helpers
  schema-cache.ts       → Schema caching by URI/id
  errors.ts             → Error codes (Errors object) + ValidateError class
  format-validators.ts  → Built-in + custom format validators
  report.ts             → Error accumulation (Report, SchemaErrorDetail)
  json-schema.ts        → Common JSON Schema definitions + helpers
  json-schema-versions.ts → Draft-specific type unions + version mappings
  z-schema-options.ts   → Options interface + defaults + normalizeOptions
  z-schema-reader.ts    → Schema reader type
  z-schema-versions.ts  → Registers bundled meta-schemas into cache
  utils/                → Pure utilities (array, clone, json, uri, etc.)
  schemas/              → Bundled meta-schemas (generated at build time)

バリデーションパイプライン

1. スキーマのコンパイル（schema-compiler.ts）：$ref を解決し、id／$id を収集して、キャッシュに登録します
2. スキーマのバリデーション（schema-validator.ts）：スキーマをそのメタスキーマに照らして検証します
3. JSON のバリデーション（json-validation.ts + validation/*.ts）：コンパイル済みスキーマに照らしてデータを検証します。型チェック、制約、結合子（allOf／anyOf／oneOf／not）、unevaluated* の追跡、フォーマットチェックを行います。キーワードバリデーターは、カテゴリごとに validation/ 配下のモジュールに分割されています
4. レポート（report.ts）：エラーは Report に蓄積され、その後 ValidateError に変換されます

一般的なタスク

新しいエラーコードの追加

1. src/errors.ts の Errors オブジェクトにエラーを追加します：

   MY_NEW_ERROR: 'Description with {0} placeholder',
   

2. バリデーションロジックで report.addError('MY_NEW_ERROR', [param]) を使用します。
3. エラーコードが生成されることを確認するテストを記述します。

新しいフォーマットバリデーターの追加

1. src/format-validators.ts にバリデーター関数を記述します：

   const myFormatValidator: FormatValidatorFn = (input: unknown) => {
     if (typeof input !== 'string') return true;
     return /^pattern$/.test(input);
   };
   

2. inbuiltValidators レコードに登録します：

   const inbuiltValidators = {
     // ...existing
     'my-format': myFormatValidator,
   };
   

3. test/spec/format-validators.spec.ts にテストを追加します。

新しいオプションの追加

1. src/z-schema-options.ts の ZSchemaOptions にオプションを追加します。
2. defaultOptions にデフォルト値を追加します。
3. オプションが strictMode の一部である場合は、normalizeOptions の strictMode ブロックに追加します。
4. docs/options.md に記載します。
5. テストを記述します。

新しい JSON Schema キーワードの実装

1. 適切な src/validation/*.ts モジュール（たとえば、配列キーワードなら array.ts、オブジェクトキーワードなら object.ts、アプリケーターなら combinators.ts）または src/schema-validator.ts（スキーマレベルのバリデーションの場合）にバリデーションロジックを追加します。src/json-validation.ts のオーケストレーション層がこれらのモジュールを呼び出します。
2. キーワードが特定の draft に固有の場合は、draft バージョンのチェックを設けます。
3. test/spec/json-schema-test-suite.common.ts の excludedFiles／excludedTests から関連する項目を削除します。
4. 準拠を確認するため、JSON Schema Test Suite を実行します：

   npx vitest run --silent=false --project node -t "draft2020-12/newKeyword"
   

5. 新しい型があれば src/index.ts からエクスポートします。

既存の動作の変更

1. 上記のコードベースの構成を参考に、該当するモジュールを見つけます。
2. コード規約（以下を参照）に従って変更します。
3. テストスイート全体を実行します。ほかの draft でリグレッションが発生することがよくあります。

テストフレームワーク

• Vitest を globals: true で使用します。
• 2 つのプロジェクトがあります：node と browser（Playwright：Chromium、Firefox、WebKit）。
• テストは test/spec/ にあります。

ファイル名

接尾辞	実行対象
*.spec.ts	node と browser の両方
*.node-spec.ts	node のみ
*.browser-spec.ts	browser のみ

テストの実行

npm test                                                        # all
npm run test:node                                               # node only
npx vitest run --silent=false --project node -t "draft4/type"   # single test
npm run test:coverage                                           # coverage

テストのパターン

import { ZSchema } from '../../src/z-schema.ts';

describe('Feature Name', () => {
  it('should accept valid data', () => {
    const validator = ZSchema.create();
    expect(validator.validate('hello', { type: 'string' })).toBe(true);
  });

  it('should reject invalid data', () => {
    const validator = ZSchema.create();
    const { valid, err } = validator.validateSafe(42, { type: 'string' });
    expect(valid).toBe(false);
    expect(err?.details?.[0]?.code).toBe('INVALID_TYPE');
  });
});

JSON Schema Test Suite

公式テストケースは test/spec/json-schema-test-suite.common.ts を通じて読み込まれます。新たに実装した機能のテストを有効にするには、excludedFiles／excludedTests から項目を削除し、テストが通ることを確認してください。

コード規約

• TypeScript の strict: true を使用し、src/ では ESM と .js 拡張子付きのインポートを使用します
• test/ では .ts 拡張子付きのインポートを使用します（allowImportingTsExtensions による）
• 型のみのインポートには import type を使用します（oxlint によって強制されます）
• インポート順：型のみ → 副作用 → Node 組み込みモジュール → パッケージ → 相対パス
• oxfmt：行幅 120 文字、シングルクォート、末尾のカンマ（es5）、セミコロン
• クラス／型：PascalCase — 関数／変数：camelCase — エラー：UPPER_SNAKE_CASE
• すべての公開 API は src/index.ts を通じてエクスポートします
• 内部型はエクスポートしないでください
• src/schemas/ のスキーマは scripts/copy-schemas.mts によって生成されます — 手動で編集しないでください
• json-schema-spec/ は Git サブモジュールです — 変更をコミットしないでください

PR チェックリスト

- [ ] Branch from `main`
- [ ] Changes follow code conventions
- [ ] npm run check passes (lint + format)
- [ ] npm run build passes
- [ ] npm run build:tests passes
- [ ] npm test passes (node + browser)
- [ ] New public types/values exported through src/index.ts
- [ ] New features have tests
- [ ] docs/ updated if public API changed
- [ ] JSON Schema Test Suite entries un-excluded if applicable

リファレンスファイル

• references/architecture-details.md — モジュールの完全な依存関係図、ファクトリーパターン、ビルド出力、内部型