@modulify/validator 0.1.0 → 0.2.1

package/docs/ru/07-ai-reference.md

@@ -0,0 +1,215 @@
+# Справка для AI
+
+[Оглавление документации](./00-index.md)  
+[Английская версия](../en/07-ai-reference.md)
+
+Эта страница — компактное описание контракта для AI agents, code generators, IDE tools и людей, которым нужен максимально короткий и однозначный набор правил.
+
+Её стоит воспринимать как каноническую краткую справку поверх более подробных руководств.
+
+## Базовая модель
+
+`@modulify/validator` организован вокруг трёх основных слоёв:
+
+- predicates: проверки во время выполнения и type guards;
+- assertions: машиночитаемые ошибки leaf-уровня;
+- combinators: структурная композиция assertions и validators.
+
+Библиотека не строится вокруг встроенных человекочитаемых сообщений.
+
+Violations — это прежде всего структурированные данные.
+
+## Канонические точки входа
+
+Используйте корневой пакет для:
+
+- `validate`
+- `validate.sync`
+- `matches.sync`
+- `meta`
+- `describe`
+- `custom`
+- `collection`
+- built-in assertions
+- combinators
+
+Используйте `@modulify/validator/predicates` для самостоятельных проверок в стиле guard.
+
+Используйте `@modulify/validator/json-schema` для:
+
+- `toJsonSchema(...)`
+- `JsonSchemaExportError`
+
+## Контракт результата валидации
+
+```typescript
+type ValidationTuple<T> =
+  | [ok: true, validated: T, violations: []]
+  | [ok: false, validated: unknown, violations: Violation[]]
+```
+
+Важные следствия:
+
+- `validate(...)` сужает `validated` в успешной ветке;
+- `validate(...)` не сужает исходную входную переменную;
+- `matches.sync(...)` — это API для сужения исходной переменной;
+- `violations` при успехе всегда пуст.
+
+## Семантика wrappers
+
+- `optional(x)` принимает `undefined`
+- `nullable(x)` принимает `null`
+- `nullish(x)` принимает `null | undefined`
+
+Эти wrappers моделируют допустимые значения во время выполнения, а не формулировки для UI.
+
+## Семантика shape
+
+`shape(...)` валидирует обычные record-like objects.
+
+По умолчанию:
+
+- unknown keys разрешены;
+- unknown-key mode равен `'passthrough'`;
+- object-level rules отсутствуют.
+
+Переключатели режима:
+
+- `.strict()` сохраняет те же поля и rules, но отклоняет unknown keys;
+- `.passthrough()` сохраняет те же поля и rules, но разрешает unknown keys.
+
+Структурные derivations:
+
+- `.pick(...)`
+- `.omit(...)`
+- `.partial(...)`
+- `.extend(...)`
+- `.merge(...)`
+
+Важное правило:
+
+- structural derivations намеренно сбрасывают object-level rules;
+- mode switches намеренно сохраняют object-level rules.
+
+## Контракт violations
+
+Violations — это машиночитаемые объекты с:
+
+- значением, на котором произошла ошибка;
+- path;
+- semantic subject в `violates`.
+
+Не стройте дальнейшую обработку на разборе текста.
+
+Предпочитайте:
+
+- `violations`
+- `collection(...)`
+- поиск по path
+
+Вместо:
+
+- сопоставления строк;
+- разового разбора сообщений;
+- извлечения имён полей из текстов.
+
+## Контракт metadata
+
+`meta(...)` добавляет непрозрачные машиночитаемые метаданные к любому constraint.
+
+`describe(...)` возвращает стабильное рекурсивное дерево descriptors.
+
+Custom validators могут участвовать в этом контракте через `describe()`.
+
+Без `describe()` custom validator намеренно остаётся непрозрачным и обычно выглядит так:
+
+```typescript
+{ kind: 'validator' }
+```
+
+## Контракт JSON Schema
+
+`toJsonSchema(...)` — это производный слой для interoperability.
+
+Это не источник runtime truth.
+
+Best-effort режим:
+
+- режим по умолчанию;
+- unsupported nodes превращаются в permissive `{}` schemas;
+- unsupported shape rules могут быть отброшены с `$comment`.
+
+Strict режим:
+
+- выбрасывает `JsonSchemaExportError`;
+- содержит `descriptor`, `reason` и `path`.
+
+Важное несоответствие:
+
+- JSON Schema `required` — это лишь приближение runtime semantics вокруг `undefined`;
+- не следует ожидать полного семантического совпадения между runtime validation и экспортированной JSON Schema.
+
+## Канонические шаблоны
+
+Используйте это, когда нужно валидировать payload:
+
+```typescript
+const [ok, validated, violations] = validate.sync(input, schema)
+```
+
+Используйте это, когда нужно сузить исходную переменную:
+
+```typescript
+if (matches.sync(value, schema)) {
+  // здесь value уже сужено
+}
+```
+
+Используйте это, когда нужны переиспользуемые object schemas:
+
+```typescript
+const schema = shape({...}).strict()
+const partial = schema.partial()
+const subset = schema.pick([...])
+```
+
+Используйте это, когда другому слою нужна машиночитаемая introspection:
+
+```typescript
+const descriptor = describe(schema)
+```
+
+Используйте это, когда внешней системе нужно представление для экспорта:
+
+```typescript
+const jsonSchema = toJsonSchema(schema)
+```
+
+## Стоит / Не стоит
+
+Стоит:
+
+- держите leaf constraints маленькими и хорошо сочетаемыми друг с другом;
+- относитесь к `violations` как к данным, а не как к сообщениям;
+- используйте `shape(...)` для переиспользуемых object contracts;
+- добавляйте `describe()` к custom validators, которые должны участвовать в инструментах;
+- используйте strict JSON Schema export только тогда, когда экспорт с потерями неприемлем.
+
+Не стоит:
+
+- ожидать, что `validate(...)` сузит исходную входную переменную;
+- считать `toJsonSchema(...)` полным зеркалом runtime semantics;
+- считать, что structural derivations shape сохраняют object-level rules;
+- строить инструменты на приватных internals вместо `describe(...)`;
+- строить дальнейшую логику вокруг человекочитаемых строк.
+
+## Лучшие источники истины
+
+Для деталей реализации и edge cases предпочтителен такой порядок:
+
+1. `README.md`
+2. `docs/ru/*.md` или `docs/en/*.md`
+3. `tests/*.test.ts`
+4. `tests/*.test-d.ts`
+
+Тесты — самый точный источник поведения там, где проза может оставлять пространство для неверной интерпретации.

package/docs/ru/08-violation-code-types.md

@@ -0,0 +1,241 @@
+# Типы кодов нарушений
+
+[Индекс документации](./00-index.md)  
+[English version](../en/08-violation-code-types.md)
+
+`@modulify/validator` теперь даёт два связанных слоя для машиночитаемых кодов:
+
+- точные literal-коды в assertion descriptors и structured violations;
+- расширяемый глобальный реестр, из которого можно получить project-wide union известных кодов.
+
+В этом руководстве разобрано, когда полезен каждый из слоёв, как они сочетаются и как безопасно расширять их в приложении.
+
+## Быстрый старт
+
+Основные публичные точки входа:
+
+- `ViolationCodeEntry` - компактная контрактная запись для известного кода;
+- `ViolationCodeRegistry` - интерфейс-реестр известных кодов;
+- `ViolationCode` - union, извлекаемый из `keyof ViolationCodeRegistry`;
+- `ViolationArgs<C>`, `ViolationKindOf<C>` и `ViolationNameOf<C>` - code-driven utility types.
+
+Пакет уже содержит built-in ключи для собственных violations, например:
+
+- `'type.string'`
+- `'length.min'`
+- `'shape.unknown-key'`
+- `'runtime.rejection'`
+
+Поэтому такой код работает сразу:
+
+```typescript
+import type { ViolationCode } from '@modulify/validator'
+
+const code: ViolationCode = 'type.string'
+```
+
+## Точные коды из `describe(...)`
+
+Built-in assertions теперь сохраняют точные literal-коды в интроспекции.
+
+```typescript
+import {
+  describe,
+  hasLength,
+  isString,
+} from '@modulify/validator'
+
+const stringDescriptor = describe(isString)
+const lengthDescriptor = describe(hasLength({ min: 3 }))
+```
+
+С точки зрения TypeScript это значит:
+
+- `stringDescriptor.code` имеет тип `'type.string'`;
+- `stringDescriptor.args` имеет тип `[]`;
+- `lengthDescriptor.code` имеет тип `'length.unsupported-type'`;
+- `lengthDescriptor.constraints[number].code` имеет конкретный union length-кодов вместо обычного `string`.
+
+Это удобно для адаптеров и tooling-кода, который читает descriptors и хочет ветвиться по коду без ручных cast.
+
+## Зачем нужен глобальный реестр
+
+Точные literals на отдельных значениях полезны для локальной интроспекции.
+
+Глобальный реестр решает другую задачу: позволяет получить один переиспользуемый union для всего приложения.
+
+```typescript
+import type { ViolationCode } from '@modulify/validator'
+
+type AppViolationCode = ViolationCode
+```
+
+Такой union удобно использовать в:
+
+- словарях сообщений;
+- контрактах аналитики;
+- API envelopes с ошибками;
+- UI-мапперах состояния ошибок;
+- общих helper utilities.
+
+## Расширение `ViolationCodeRegistry`
+
+Реестр рассчитан на module augmentation и теперь хранит небольшие контрактные записи по коду.
+
+```typescript
+import type { ViolationCodeEntry } from '@modulify/validator'
+import '@modulify/validator'
+
+declare module '@modulify/validator' {
+  interface ViolationCodeRegistry {
+    'user.email.taken': ViolationCodeEntry<'validator', 'user', readonly []>;
+    'profile.password.mismatch': ViolationCodeEntry<'validator', 'shape', readonly []>;
+  }
+}
+```
+
+После этого:
+
+```typescript
+import type { ViolationCode } from '@modulify/validator'
+
+const codeA: ViolationCode = 'user.email.taken'
+const codeB: ViolationCode = 'profile.password.mismatch'
+```
+
+Так можно один раз объявить project-specific коды и потом использовать извлечённый union во всех остальных слоях.
+
+Если в проекте ещё остались старые augmentation-записи с `never`, они по-прежнему будут попадать в `ViolationCode`, но для `kind` / `name` / `args` останется generic fallback, пока вы не переведёте их на `ViolationCodeEntry`.
+
+## Производные типы от кода
+
+После регистрации кода с контрактной записью он становится ключом к связанным типам.
+
+```typescript
+import type {
+  ViolationArgs,
+  ViolationKindOf,
+  ViolationNameOf,
+  ViolationSubject,
+} from '@modulify/validator'
+
+type PasswordArgs = ViolationArgs<'profile.password.mismatch'>
+type PasswordKind = ViolationKindOf<'profile.password.mismatch'>
+type PasswordName = ViolationNameOf<'profile.password.mismatch'>
+type PasswordSubject = ViolationSubject<'profile.password.mismatch'>
+```
+
+То есть:
+
+- `PasswordArgs` становится `readonly []`;
+- `PasswordKind` становится `'validator'`;
+- `PasswordName` становится `'shape'`;
+- `PasswordSubject` автоматически получает согласованные `kind`, `name`, `code` и `args`.
+
+## Использование расширенных кодов в custom assertions
+
+Custom assertions могут хранить свои собственные явные literal-коды.
+
+```typescript
+import { assert } from '@modulify/validator/assertions'
+
+const isAvailableEmail = assert(
+  (value: unknown): value is string => typeof value === 'string' && value.includes('@'),
+  {
+    name: 'isAvailableEmail',
+    bail: true,
+    code: 'user.email.taken',
+  }
+)
+```
+
+Тогда `describe(isAvailableEmail).code` будет иметь тип `'user.email.taken'`.
+
+Эта часть не зависит от глобального union. Literal сохраняется прямо из определения assertion.
+
+## Использование расширенных кодов в shape refinements
+
+Та же идея работает и для object-level refinement issues.
+
+```typescript
+import type { ObjectShapeRefinementIssue } from '@modulify/validator'
+import {
+  isEmail,
+  isString,
+  shape,
+} from '@modulify/validator'
+
+const signUpForm = shape({
+  email: [isString, isEmail],
+  password: isString,
+  confirmation: shape({
+    password: isString,
+  }),
+}).refine(value => {
+  if (value.password === value.confirmation.password) {
+    return []
+  }
+
+  return [{
+    path: ['confirmation', 'password'],
+    code: 'profile.password.mismatch',
+    args: [],
+  }] satisfies ObjectShapeRefinementIssue<'profile.password.mismatch'>
+})
+```
+
+Так код refinement остаётся согласованным с тем же реестром, из которого вы строите общий union.
+
+## Практический паттерн для app-level мапперов
+
+Часто поверх codes хочется сделать небольшой слой, который отвечает уже за рендеринг или транспорт.
+
+```typescript
+import type {
+  Violation,
+  ViolationCode,
+} from '@modulify/validator'
+
+const labels: Partial<Record<ViolationCode, string>> = {
+  'type.string': 'Expected a string',
+  'length.min': 'Value is too short',
+  'user.email.taken': 'Email is already taken',
+}
+
+function toLabel(violation: Violation) {
+  return labels[violation.violates.code as ViolationCode] ?? violation.violates.code
+}
+```
+
+Необязательно превращать все возможные коды в один огромный исчерпывающий словарь. На практике `Partial<Record<ViolationCode, ...>>` часто самый удобный вариант.
+
+## Built-In union и сохранение явных literals
+
+Эти два механизма дополняют друг друга:
+
+- built-in и augmented коды попадают в переиспользуемый union `ViolationCode`;
+- явные custom literals сохраняются прямо в местах создания значения, например в `assert(...)` или typed refinement issues.
+
+Это важное различие.
+
+Если вы определили custom literal, но ещё не аугментировали `ViolationCodeRegistry`:
+
+- локальные descriptor и violation значения всё равно могут нести точный literal;
+- глобальный union `ViolationCode` пока не будет его содержать.
+
+Если вы аугментировали `ViolationCodeRegistry` через `never`, а не через `ViolationCodeEntry`:
+
+- код попадёт в глобальный union `ViolationCode`;
+- для него всё ещё будет использоваться generic fallback по `kind`, `name` и `args`.
+
+Обычно удобно делать так:
+
+1. объявить custom code там, где он создаётся;
+2. добавить его в `ViolationCodeRegistry`;
+3. использовать `ViolationCode` в адаптерах и app-level helper types.
+
+## Связанные разделы
+
+- [Метаданные и интроспекция](./02-metadata-and-introspection.md)
+- [Нарушения](./03-violations.md)
+- [Публичный API](./05-public-api.md)