@modulify/validator 0.1.0 → 0.2.0

package/docs/ru/README.md

@@ -0,0 +1,371 @@
+# <img src="../../logo.png" alt="Logo" width="36" /> `@modulify/validator`
+
+[![npm version](https://img.shields.io/npm/v/@modulify/validator.svg)](https://www.npmjs.com/package/@modulify/validator)
+[![codecov](https://codecov.io/gh/modulify/validator/branch/main/graph/badge.svg)](https://codecov.io/gh/modulify/validator)
+[![Tests Status](https://github.com/modulify/validator/actions/workflows/tests.yml/badge.svg)](https://github.com/modulify/validator/actions)
+
+[README на английском](../../README.md)  
+[Индекс русской документации](./00-index.md)
+
+`@modulify/validator` — небольшая TypeScript-библиотека для валидации, построенная вокруг трёх отдельных слоёв:
+
+- predicates для проверок во время выполнения и сужения типов;
+- assertions для машиночитаемых результатов валидации с ошибкой;
+- combinators для композиции схем, включая структурную рекурсию по массивам и объектам.
+
+Проект сознательно строится вокруг структурированных метаданных, а не вокруг встроенных человекочитаемых сообщений об ошибках.
+
+## Что это за проект
+
+Эта библиотека рассчитана на случаи, когда вам нужно:
+
+- сохранить простые type guards полезными сами по себе;
+- валидировать вложенные данные рекурсивно;
+- получать структурированные violations вместо текстовых сообщений;
+- позже самостоятельно решать, как эти violations показывать или преобразовывать.
+
+Типичные результаты слоя валидации можно преобразовать в:
+
+- локализованные сообщения об ошибках;
+- состояние ошибок полей формы;
+- API payloads с ошибками;
+- данные для аналитики или отладки;
+- собственный UI или узлы virtual DOM.
+
+## Идея
+
+Проект разделяет две задачи, которые часто смешиваются в одной абстракции.
+
+### Предикаты
+
+Predicates — это небольшие проверки во время выполнения, которые одновременно работают как TypeScript type guards.
+
+Они отвечают на вопросы вроде:
+
+- является ли это значение строкой?
+- является ли это значение объектом с определённой формой?
+- выполняет ли это значение базовое логическое условие?
+
+Этот слой должен оставаться простым и полезным сам по себе даже вне контура валидации.
+
+### Валидаторы и assertions
+
+Assertions — это проверки, которые могут вернуть violation со структурированными метаданными.
+
+Вместо генерации текстового сообщения assertion возвращает данные, которые описывают:
+
+- что именно сломалось;
+- где это произошло;
+- какой семантический код сработал;
+- какие аргументы или границы были задействованы.
+
+Так представление результата остаётся за пределами библиотеки.
+
+### Почему это существует рядом с `zod`-подобными библиотеками
+
+Библиотеки вроде `zod`, `yup` и других schema-oriented инструментов хорошо известны и отлично решают большой класс задач.
+
+Задача этого проекта в другом.
+
+Он в первую очередь не пытается быть:
+
+- schema-definition DSL;
+- form library со встроенной семантикой сообщений;
+- all-in-one parsing и слой представления.
+
+Вместо этого проект фокусируется на:
+
+- маленьких predicates для narrowing;
+- отдельном слое assertions для diagnostics;
+- composable schema combinators;
+- machine-readable violations, которые потребитель может преобразовывать как угодно.
+
+Короткое описание направления проекта:
+
+> Type-safe predicates for narrowing, and validators for machine-readable diagnostics.
+
+Или ещё короче:
+
+> No messages, only meaning.
+
+## Установка
+
+Через `yarn`:
+
+```bash
+yarn add @modulify/validator
+```
+
+Через `npm`:
+
+```bash
+npm install @modulify/validator --save
+```
+
+## Быстрый пример
+
+```typescript
+import {
+  each,
+  shape,
+  exact,
+  hasLength,
+  isDefined,
+  isString,
+  nullable,
+  optional,
+  validate,
+} from '@modulify/validator'
+
+const [ok, validated, violations] = await validate({
+  form: {
+    nickname: undefined,
+    title: null,
+    password: '',
+    role: 'admin',
+  },
+}, shape({
+  form: [
+    isDefined,
+    shape({
+      nickname: optional([isString, hasLength({ min: 4 })]),
+      title: nullable(isString),
+      password: [isString, hasLength({ min: 6 })],
+      role: exact('admin'),
+    }),
+  ],
+}))
+
+if (ok) {
+  validated.form.nickname.toUpperCase()
+} else {
+  console.log(violations)
+}
+```
+
+Синхронная валидация:
+
+```typescript
+const [ok, validated, violations] = validate.sync({
+  form: {
+    nickname: '',
+    password: '',
+  },
+}, shape({
+  form: [
+    isDefined,
+    shape({
+      nickname: [isString, hasLength({ min: 4 })],
+      password: [isString, hasLength({ min: 6 })],
+    }),
+  ],
+}))
+
+if (ok) {
+  validated.form.password.toUpperCase()
+}
+```
+
+Сужение исходной переменной в sync-коде:
+
+```typescript
+import {
+  isDefined,
+  isString,
+  matches,
+} from '@modulify/validator'
+
+const value: unknown = 'nickname'
+
+if (matches.sync(value, [isDefined, isString])) {
+  value.toUpperCase()
+}
+```
+
+Сильная типизация успешной ветки прямо из `validate`:
+
+```typescript
+import {
+  shape,
+  isDefined,
+  isString,
+  validate,
+} from '@modulify/validator'
+
+const schema = shape({
+  name: [isDefined, isString],
+})
+
+const [ok, validated, violations] = await validate({ name: 'Kirill' }, schema)
+
+if (ok) {
+  validated.name.toUpperCase()
+} else {
+  console.log(violations)
+}
+```
+
+## API объектных схем
+
+`shape(...)` — это переиспользуемый API объектных схем. Он валидирует вложенные record-like objects и предоставляет небольшой неизменяемый API вроде `strict()`, `pick()`, `omit()`, `partial()`, `extend()`, `merge()`, `refine()` и `fieldsMatch(...)`.
+
+```typescript
+import {
+  isString,
+  optional,
+  shape,
+  validate,
+} from '@modulify/validator'
+
+const profile = shape({
+  id: isString,
+  nickname: optional(isString),
+})
+
+const [ok] = validate.sync({
+  id: 'u1',
+  nickname: 'neo',
+}, profile)
+```
+
+Подробные руководства:
+
+- [Руководство по API объектных схем](./01-shape-api.md)
+
+## Метаданные и интроспекция
+
+`meta(...)` добавляет машиночитаемые метаданные к любому constraint, а `describe(...)` возвращает стабильное рекурсивное дерево descriptors для built-in constraints и совместимых custom validators.
+
+```typescript
+import {
+  describe,
+  isString,
+  meta,
+  optional,
+  shape,
+} from '@modulify/validator'
+
+const registration = meta(shape({
+  email: meta(isString, {
+    title: 'Email',
+    placeholder: 'name@example.com',
+  }),
+  nickname: optional(isString),
+}).strict(), {
+  title: 'Registration form',
+})
+
+const node = describe(registration)
+```
+
+Подробные руководства:
+
+- [Руководство по метаданным и интроспекции](./02-metadata-and-introspection.md)
+- [Руководство по типам кодов нарушений](./08-violation-code-types.md)
+
+## Ментальная модель
+
+Практически про библиотеку удобно думать так:
+
+- predicates отвечают: удовлетворяет ли значение условию `X`?
+- assertions отвечают: если нет, то что именно сломалось?
+- combinators отвечают: как объединять constraints в более крупную схему, включая рекурсивный обход объектов и массивов?
+
+В текущем API это обычно выглядит так:
+
+- leaf checks через assertions вроде `isString`, `isDefined`, `hasLength`, `oneOf`;
+- композиция схем через combinators вроде `exact`, `optional`, `nullable`, `nullish`, `shape(...)`, `each(...)`;
+- типизированная валидация через `validate(...)` или `validate.sync(...)`;
+- narrowing исходной переменной в sync-коде через `matches.sync(...)`.
+
+## Нарушения
+
+`validate(...)` возвращает машиночитаемый список `Violation[]`, а `collection(...)` может обернуть его в небольшой helper API для точного поиска по path и обхода дерева.
+
+```typescript
+import {
+  collection,
+  isString,
+  shape,
+  validate,
+} from '@modulify/validator'
+
+const [ok, validated, violations] = validate.sync({
+  profile: {
+    email: '',
+  },
+}, shape({
+  profile: shape({
+    email: isString,
+  }),
+}))
+
+const errors = collection(violations)
+
+const rootErrors = errors.at([])
+const emailErrors = errors.at(['profile', 'email'])
+```
+
+Подробные руководства:
+
+- [Руководство по нарушениям](./03-violations.md)
+- [Руководство по типам кодов нарушений](./08-violation-code-types.md)
+
+## Экспорт JSON Schema
+
+`toJsonSchema(...)` строит представление JSON Schema поверх того же публичного дерева descriptors, которое возвращает `describe(...)`.
+
+```typescript
+import {
+  isNumber,
+  isString,
+  meta,
+  optional,
+  shape,
+} from '@modulify/validator'
+import { toJsonSchema } from '@modulify/validator/json-schema'
+
+const profile = meta(shape({
+  email: meta(isString, {
+    title: 'Email',
+    format: 'email',
+  }),
+  age: optional(isNumber),
+}).strict(), {
+  title: 'Profile',
+})
+
+const jsonSchema = toJsonSchema(profile)
+```
+
+Подробные руководства:
+
+- [Руководство по экспорту JSON Schema](./04-json-schema-export.md)
+
+## Публичный API
+
+Подробное руководство по public API описывает root exports, специализированные subpath exports, validation result tuple и то, как package surface разделён между validation, predicates, violations, metadata и экспортом JSON Schema.
+
+Подробные руководства:
+
+- [Руководство по публичному API](./05-public-api.md)
+
+## Практические рецепты и справка для AI
+
+Есть ещё два руководства, которые полезны, когда нужен более быстрый практический вход вместо последовательного чтения всей концептуальной документации.
+
+- [Практические рецепты](./06-common-recipes.md) - практические примеры для валидации payload, выбора wrappers, переиспользуемых shape, сопоставления ошибок формы и экспорта JSON Schema.
+- [Справка для AI](./07-ai-reference.md) - компактное описание контракта для agents, инструментов и быстрого поиска семантики библиотеки.
+
+## Заметки
+
+- Assertions возвращают структурированные метаданные вместо сообщений.
+- Combinators — это тонкие вспомогательные средства для построения схем поверх assertions и validators; `each` и `shape` в этой модели являются structural combinators.
+- Predicates должны оставаться полезными независимо от слоя валидации.
+- Библиотекой проще пользоваться, когда во всём проекте сохраняется один стабильный violation format.
+- `validate(...)` сужает тип `validated` в tuple, а не исходную входную переменную.
+- Чтобы сузить исходную переменную в sync-коде, используйте `matches.sync(...)`.
+
+## Переводы
+
+- [English](../../README.md)

package/drafts/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

package/package.json

@@ -3,7 +3,7 @@
   "type": "module",
   "description": "Declarative validation util for JavaScript",
   "license": "MIT",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -17,17 +17,23 @@
       "require": "./dist/assertions.cjs",
       "default": "./dist/assertions.mjs"
     },
+    "./combinators": {
+      "types": "./dist/combinators.d.ts",
+      "import": "./dist/combinators.mjs",
+      "require": "./dist/combinators.cjs",
+      "default": "./dist/combinators.mjs"
+    },
+    "./json-schema": {
+      "types": "./dist/json-schema.d.ts",
+      "import": "./dist/json-schema.mjs",
+      "require": "./dist/json-schema.cjs",
+      "default": "./dist/json-schema.mjs"
+    },
     "./predicates": {
       "types": "./dist/predicates.d.ts",
       "import": "./dist/predicates.mjs",
       "require": "./dist/predicates.cjs",
       "default": "./dist/predicates.mjs"
-    },
-    "./runners": {
-      "types": "./dist/runners.d.ts",
-      "import": "./dist/runners.mjs",
-      "require": "./dist/runners.cjs",
-      "default": "./dist/runners.mjs"
     }
   },
   "types": "dist/index.d.ts",
@@ -36,11 +42,14 @@
       "assertions": [
         "./dist/assertions.d.ts"
       ],
+      "combinators": [
+        "./dist/combinators.d.ts"
+      ],
+      "json-schema": [
+        "./dist/json-schema.d.ts"
+      ],
       "predicates": [
         "./dist/predicates.d.ts"
-      ],
-      "runners": [
-        "./dist/runners.d.ts"
       ]
     }
   },
@@ -48,33 +57,38 @@
     "build": "vite build",
     "lint": "eslint src tests types",
     "prepare": "husky",
-    "release": "standard-version",
-    "release:minor": "standard-version --release-as minor",
-    "release:patch": "standard-version --release-as patch",
-    "release:major": "standard-version --release-as major",
+    "release": "npx --yes standard-version",
+    "release:minor": "npx --yes standard-version --release-as minor",
+    "release:patch": "npx --yes standard-version --release-as patch",
+    "release:major": "npx --yes standard-version --release-as major",
     "stats": "gzip -c ./dist/index.mjs | wc -c",
     "test": "vitest run",
+    "test:d": "vitest run --typecheck.only",
     "test:coverage": "vitest run --coverage",
-    "test:coverage:html": "vitest run --coverage --reporter=html --outputFile.html=./reports/html/report.html"
+    "test:coverage:html": "vitest run --coverage --reporter=html --outputFile.html=./reports/html/report.html",
+    "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@commitlint/cli": "^17.7.1",
-    "@commitlint/config-conventional": "^17.7.0",
-    "@eslint/js": "^9.17.0",
-    "@types/node": "^18.15 || ^20.11",
-    "@vitest/coverage-istanbul": "2.1.8",
-    "@vitest/ui": "2.1.8",
-    "eslint": "^9.17.0",
-    "globals": "^15.14.0",
+    "@commitlint/cli": "^20.4.3",
+    "@commitlint/config-conventional": "^20.4.3",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.3.5",
+    "@vitest/coverage-v8": "4.0.18",
+    "@vitest/ui": "4.0.18",
+    "eslint": "^10.0.3",
+    "globals": "^17.4.0",
     "husky": "^9.1.7",
-    "standard-version": "^9.5.0",
     "ts-node": "^10.9.2",
     "tslib": "^2.8.1",
     "typescript": "^5.5.4",
-    "typescript-eslint": "^8.18.1",
-    "vite": "^5.4.11",
-    "vite-plugin-dts": "^4.4.0",
-    "vitest": "^2.1.8"
+    "typescript-eslint": "^8.56.1",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.18"
+  },
+  "resolutions": {
+    "minimatch@npm:10.2.1": "npm:10.2.4",
+    "minimatch@npm:^9.0.3": "npm:9.0.7"
   },
   "publishConfig": {
     "access": "public"
@@ -92,9 +106,5 @@
     "type": "git",
     "url": "https://github.com/modulify/validator.git"
   },
-  "husky": {
-    "hooks": {
-      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
-    }
-  }
+  "packageManager": "yarn@4.12.0"
 }

package/skills/commit-workflow/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: commit-workflow
+description: Use this skill when creating git commits in this repository. It standardizes commit splitting, Conventional Commit type selection, optional subsystem scopes, changelog-friendly phrasing, and commitlint constraints.
+---
+
+# Commit Workflow
+
+## When To Use
+Use this skill when the user asks to:
+- create one or more commits;
+- split changes into separate commits;
+- choose commit messages, types, or scopes;
+- validate commit formatting before committing.
+
+## Mandatory First Step
+Before creating any commit in this repository, reread this skill from the top and treat it as the current source of truth for commit wording, scopes, splitting, and lockfile policy.
+
+## Source Of Truth
+- `AGENTS.md`
+- `.commitlintrc.json`
+
+## Required Rules
+- Commit format: Conventional Commits.
+- Message language: English by default.
+- Subject style: describe a completed historical change, not an intention.
+- Start commit subject description with an uppercase letter.
+- Keep commit subject description concise.
+- Put long details into the commit body; lists in body are allowed.
+- Use past/perfective wording; prefer passive voice when it reads naturally for changelogs.
+Examples: `Added ...`, `Removed ...`, `Refactored ...`, `Fixed ...`, `Updated ...`.
+- Allowed types: `feat`, `fix`, `build`, `ci`, `perf`, `docs`, `refactor`, `style`, `test`, `chore`.
+- This repository is a single package, so scope is optional.
+- If scope improves clarity, use a real subsystem scope such as:
+  `assertions`, `predicates`, `runners`, `types`, `build`, `tests`.
+- Do not invent synthetic scopes just to imitate release automation.
+- Breaking changes: use `!` in header or a `BREAKING CHANGE` footer.
+- Do not mix unrelated changes in one commit.
+- Always commit `yarn.lock` changes in a dedicated commit with no other files.
+- For a `yarn.lock`-only commit, use the exact header: `chore: Updated yarn.lock`.
+- Do not amend or rewrite history unless explicitly requested.
+
+## Commitlint Constraints
+- Header max length: `200`
+- Body line max length: `200`
+- Footer line max length: `200`
+- `subject-case: never`
+
+## Workflow
+1. Inspect pending changes:
+```bash
+git status --short
+git diff
+```
+2. Group files by logical intent.
+Keep code, docs, lockfile, and generated artifacts separated when they represent different changes.
+3. If `yarn.lock` changed, split it into a dedicated commit.
+4. Choose commit type and optional scope.
+5. Compose the header:
+```text
+<type>(<scope>): <Short description>
+```
+If scope is not useful, omit it:
+```text
+<type>: <Short description>
+```
+6. Stage only the target files:
+```bash
+git add <files>
+```
+7. Create the commit non-interactively:
+```bash
+git commit -m "<type>(<scope>): <Description>"
+```
+8. Verify the result:
+```bash
+git show --name-status --oneline -n 1
+```
+
+## Practical Patterns
+- Public API redesign:
+`feat!: Assertion API was redesigned around structured violations`
+- Assertion internals cleanup:
+`refactor(assertions): Assertion helpers were simplified`
+- Type-only adjustment:
+`refactor(types): Public assertion types were updated`
+- Test coverage update:
+`test: Assertion coverage was expanded`
+- Build/config change:
+`build: Vite entrypoints were updated`
+- Documentation update:
+`docs: README was updated`
+- Lockfile refresh:
+`chore: Updated yarn.lock`

package/skills/coverage-recovery/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: coverage-recovery
+description: Use this skill when coverage is below target or when uncovered validator, predicate, runner, or build-related paths must be analyzed and resolved with minimal artificial tests.
+---
+
+# Coverage Recovery
+
+## When To Use
+Use this skill when the user asks to:
+- increase test coverage;
+- analyze uncovered lines or branches;
+- explain why specific uncovered paths remain;
+- improve confidence around assertions, predicates, runners, or validation edge cases.
+
+## Source Of Truth
+- `AGENTS.md`
+- `vitest.config.ts`
+- `package.json`
+- `coverage/` HTML reports
+
+## Principles
+- Coverage is a quality signal, not a vanity metric.
+- Start from real public API behavior.
+- Prefer fixing architecture or removing dead code over adding synthetic tests for impossible paths.
+- Defensive branches should be tested with controlled failure scenarios.
+- Keep type-level and runtime behavior aligned; run `yarn typecheck` together with coverage work when typings are touched.
+
+## Workflow
+1. Collect facts:
+```bash
+yarn test:coverage
+```
+2. Read uncovered details, not only percentages.
+Use:
+- `coverage/index.html`
+- `coverage/lcov-report/index.html` if present
+3. Classify uncovered paths:
+- `real usage gap` - missed public scenario,
+- `defensive path` - malformed input or runtime failure,
+- `dead/redundant path` - likely removable,
+- `architecture smell` - design makes real testing awkward.
+4. Resolve in this order:
+- add or adjust tests for real public API scenarios,
+- add controlled break/failure tests for defensive branches,
+- simplify or remove dead branches,
+- propose architecture refactor for smell cases.
+5. Re-run checks:
+```bash
+yarn lint
+yarn typecheck
+yarn test:coverage
+```
+
+## Controlled Failure Patterns
+- Invalid values passed into assertions or runners.
+- Rejected async assertions.
+- Unsupported object/array shapes for recursive validators.
+- Type guard mismatches between runtime checks and declared narrowing.
+- Export or build-path regressions surfaced only after refactors.
+
+## Stop Condition
+If progress stalls after reasonable attempts:
+1. Stop brute-force test additions.
+2. Report exact uncovered locations and why they are hard or non-natural.
+3. Offer concrete options:
+- accept remaining defensive uncovered paths,
+- refactor the implementation to make behavior testable,
+- remove redundant branches if behavior is impossible by construction.