verelease 0.1.2-alpha.0

package/README.md

@@ -0,0 +1,145 @@
+# Verelease
+
+> **Compatibility-Aware, Executable SemVer Release Engine for Modern JavaScript & TypeScript**
+
+Verelease infers semantic versions from **actual compatibility evidence** instead of relying primarily on commit-message conventions or manually selected bump types.
+
+It maintains a historical, executable model of what consumers were promised and uses that evidence to determine the correct version, propagate workspace dependencies, generate AI release intelligence, and safely publish across registries.
+
+---
+
+## Key Features
+
+- **Executable SemVer**: Determines version bumps (`none`, `patch`, `minor`, `major`) by replaying historical public contracts against candidate packages and analyzing TypeScript AST API surfaces.
+- **Contracts ≠ Ordinary Tests**: Distinguishes public behavioral contracts from internal regression tests.
+- **Candidate Package Isolation**: Tests the actual packed artifact (`npm pack`) inside isolated consumer environments to catch packaging errors (missing exports, bad declaration files, missing dist files).
+- **Workspace & Monorepo Graph Engine**: Full support for `pnpm`, `npm`, `yarn`, and `bun` workspaces. Automatically propagates version bumps through dependency graphs and updates internal workspace ranges (`workspace:*`, `workspace:^`, etc.).
+- **Transactional Manifest & Lockfile Management**: Updates `package.json`, `jsr.json`, and `deno.json` atomically with automatic rollback if lockfile regeneration fails. Never edits lockfiles manually.
+- **Mixed Test Runner Adapters**:
+  - `node:test` (Node.js native runner)
+  - `vitest`
+  - `jest` (including React Testing Library suites)
+  - `bun:test`
+  - `deno:test`
+  - `playwright`
+  - Generic command adapter (`adapter: "command"`) for custom test suites
+- **AI-Powered Release Intelligence (TanStack AI)**:
+  - Powered by `@tanstack/ai` with provider-independent typed structured outputs.
+  - **Automatic Changelog Generation**: Transforms structured compatibility evidence and Git metadata into clear, human-readable release notes.
+  - **Automatic Migration Guide Generation**: Produces step-by-step migration documentation with before/after snippets for breaking changes.
+  - **Validated Codemod Pipeline**: Generates executable migration scripts and verifies them against historical consumer fixtures in a sandbox environment before marking them `validated` (or `experimental` if tests fail).
+  - **Strict Separation of Concerns**: Deterministic compatibility engine decides version bumps; AI explains, documents, and migrates.
+- **Pluggable Publishing**:
+  - `npm` publisher with pack verification, provenance, and dist-tag routing (`stable` → `latest`, `alpha`, `beta`, `rc`, `canary`).
+  - `jsr` / `deno` publisher.
+  - `github` Releases provider.
+- **Safe by Default**: Full `--dry-run` support on all operations. Release plans are serializable domain models inspected before any filesystem mutations occur.
+
+---
+
+## Monorepo Architecture
+
+```text
+packages/
+├── core/                  # Domain boundaries, evidence model, release plan schema, pipeline orchestrator
+├── workspace/             # Workspace discovery (pnpm, npm, yarn, bun), dependency graph & propagation
+├── semver/                # Evidence-based SemVer decision engine & zero-major policy
+├── contracts/             # Historical contract registry, temporal compatibility graph & candidate packer
+├── api-diff/              # TypeScript AST API surface extractor & export diff engine
+├── manifest/              # Transactional manifest mutator & lockfile regenerators (pnpm, npm, yarn, bun)
+├── ai/                    # TanStack AI release intelligence (changelogs, migration guides, validated codemods)
+├── test-adapter/          # Base test adapter interfaces & generic command runner
+├── test-adapter-node/     # node:test runner adapter
+├── test-adapter-vitest/   # Vitest runner adapter
+├── test-adapter-jest/     # Jest runner adapter
+├── test-adapter-bun/      # Bun test runner adapter
+├── test-adapter-deno/     # Deno test runner adapter
+├── test-adapter-playwright/# Playwright test runner adapter
+├── publisher-npm/         # npm publish provider
+├── publisher-jsr/         # JSR publish provider
+├── git/                   # Git tags, release commits & clean tree verifier
+├── source-host-github/    # GitHub Releases provider
+├── config/                # Configuration file loader (verelease.config.ts)
+└── cli/                   # verelease / verel CLI
+```
+
+---
+
+## CLI Usage
+
+### Plan Releases (`verelease plan`)
+Calculates the exact release plan, confidence score, and dependency propagations across your monorepo without modifying any files:
+```bash
+npx verelease plan
+```
+Output as JSON:
+```bash
+npx verelease plan --json
+```
+
+### Full Release Pipeline (`verelease release`)
+Executes the full release pipeline (plan → manifest update → lockfile regeneration → AI changelogs/guides → publish in topological order):
+```bash
+# Dry run: verifies candidate packing, runs contracts, and simulates publication
+npx verelease release --dry-run
+
+# Production release: applies changes and publishes
+npx verelease release
+```
+
+### Explain Release Decision (`verelease explain`)
+Explains why a package received a specific version bump:
+```bash
+npx verelease explain @acme/router
+```
+
+---
+
+## Contract Definition Example
+
+Define historical contracts in `.verelease/contracts/`:
+
+```json
+{
+  "id": "router.navigate.options-object",
+  "package": "@acme/router",
+  "category": "public",
+  "title": "createRouter options-object consumer contract",
+  "introducedIn": "1.0.0",
+  "removedIn": "3.0.0",
+  "severity": "major",
+  "testFile": "./contracts/router-options.test.js"
+}
+```
+
+When candidate package 2.0.0 is built, Verelease unpacks the candidate tarball into an isolated environment and replays this test. If the candidate broke `{ routes }` support before version 3.0.0, the failure is captured as deterministic `major` compatibility evidence!
+
+---
+
+## Codemod Validation Pipeline
+
+When machine-transformable breaking changes are detected, Verelease uses TanStack AI to generate a migration script, then validates it through a rigorous multi-stage sandbox:
+
+```text
+AI generates codemod
+       ↓
+Run against historical consumer fixtures
+       ↓
+Install candidate package
+       ↓
+Apply generated transformation
+       ↓
+Typecheck transformed project
+       ↓
+Run fixture test suite
+       ↓
+Verify compatibility
+       ↓
+Status: VALIDATED (or EXPERIMENTAL if any check fails)
+```
+
+---
+
+## License
+
+MIT

package/dist/bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node