uptide 0.0.1 → 0.2.0-next.20261002214842

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Uptide contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# Uptide
+
+**Renovate updates the version. We update the code.**
+
+Uptide tells you which of your call sites a dependency upgrade breaks, then migrates
+them on a branch it has verified with your own compiler and tests. Today it covers
+**zod 3 → 4** and **stripe**, in TypeScript repositories.
+
+## Quickstart (30 seconds)
+
+No account, no config. In your repository, with dependencies installed:
+
+```sh
+npx uptide                  # where zod and stripe stand: installed, latest, majors behind
+npx uptide check            # which of your lines the upgrade breaks
+npx uptide fix --only zod   # migrate on a new branch; nothing is pushed
+```
+
+Requires Node 20 or newer. `check` reads npm, pnpm (workspaces and catalogs), yarn
+classic and bun (text lockfile) repositories. `fix` supports npm (lockfile v2/v3, including workspaces), pnpm, and Yarn classic/Berry with the node-modules linker.
+
+## What `check` prints
+
+Real output, zod 3.23.8 → 4.6.5 on the pnpm workspace fixture in
+[`packages/cli/smoke/fixtures/pnpm`](packages/cli/smoke/fixtures/pnpm):
+
+```console
+$ uptide check --only zod
+uptide check · smoke-pnpm (pnpm, 2 packages) · 3.0s
+
+zod  3.23.8 → 4.6.5   major   ✗ 4 breaking in 2 files    4 by rule
+
+zod
+  ✗ New error API (required_error → error)   4 sites   by rule
+
+Next
+  npx uptide fix --only zod                migrate on a new branch, verify, no push
+  npx uptide check --only zod --details    every site and reason
+```
+
+One row per dependency, one line per change, and the commands to run next. Each change
+says who migrates it, from a dry run of the same rules `fix` applies: **by rule** (a
+deterministic transform), **by agent** (the assisted fixer, verified by your compiler), or
+**manual** (no migration pack covers it). `--details` lists every site with its snippet,
+the reason, the raw compiler message and the analysis notes.
+
+While it runs, a terminal shows one live line with the current phase, which disappears
+when the work ends; `--verbose` keeps one line per phase with timings. In a pipe or with
+`--ci`, stderr gets a start line and the final timing. The report is on stdout. `check`
+diffs the public API of the installed and the target version, finds your usages of what
+changed, compiles your code against the target, and loads both versions in a sandboxed
+Node. Nothing in your repository is executed.
+
+| Flag | Meaning |
+| --- | --- |
+| `--only zod,stripe` | dependencies to check (the default); `--only all` checks every dependency |
+| `--target zod@4.6.5` | exact target, repeatable; default is `latest` |
+| `--details` | every site, reason, compiler message and analysis note |
+| `--verbose` | one progress line per analysis phase, with timings |
+| `--cwd <dir>` | repository to work on |
+| `--json` | the full report as JSON on stdout |
+| `--ci` | plain log output: no color, no spinner (`NO_COLOR` is respected too) |
+
+Exit codes, for scripts and CI: **0** nothing breaking, **1** breaking changes found,
+**2** uptide could not answer (bad arguments, unsupported repository, no network). When
+it cannot answer, it says why and prints the exact command to run next.
+
+## What `fix` does, and how it verifies
+
+On the same fixture (output abridged):
+
+```console
+$ uptide fix --only zod --no-llm
+✔ Repository  smoke-pnpm (pnpm workspace, 2 packages) (29ms)
+  assisted fixes off (--no-llm): no code leaves this machine
+✔ Migration of zod (check, upgrade, fixes, verification)  verification passed (5.3s)
+
+## Upgrade zod 3.23.8 → 4.6.5
+
+Assisted fixes disabled (--no-llm).
+
+| **Changes** | 4 sites in 2 files · 4 by rule · 0 by agent |
+| **Types** | ✅ 4 errors after the bump → 0 |
+```
+
+Everything below happens in a temporary clone of your repository, never in your checkout:
+your branch, files, git hooks and git config are compared before and after and must be
+the same. You get the migration branch as a ref and the run stored inside `.git`. The
+clone is removed when the run is over; it is kept, and its path printed, when the run
+fails or you pass `--keep`, and `uptide clean` removes kept clones older than 7 days.
+
+1. **Starts clean.** It needs a git repository with a clean working tree, and works on a
+   new branch `uptide/<package>-<version>`. Nothing is pushed unless you pass `--pr --yes`.
+2. **Upgrades.** Bumps the version in every workspace that declares it (and in pnpm
+   catalogs), preserving `^`, `~`, or exact ranges. Installs run in a temporary git worktree with lifecycle scripts disabled. The real package manager produces the lockfile; Uptide rejects changes outside the target dependency subtree before copying it back unchanged. One commit.
+3. **Rule-based fixes.** Deterministic rewrites for the changes it has rules for, such as
+   zod's `required_error` / `invalid_type_error` (add `--include-deprecated` for
+   `z.string().email()`-style chains). One commit.
+4. **Assisted fixes (optional).** With `ANTHROPIC_API_KEY` set, sites the rules cannot
+   migrate go to the LLM one at a time. A patch is kept only if it removes its compiler
+   error and introduces none; otherwise it is reverted and the site is left for you.
+   `--no-llm` turns this off.
+5. **Verifies.** Type-checks with *your* TypeScript (or the bundled compiler when absent) before and after and subtracts the
+   errors you already had; runs the tests of the affected workspaces (each workspace's
+   `test` script, else the vitest or jest configuration that covers it, scoped to the
+   tests related to the migrated files, else the root `test` script) and reports what ran;
+   by default only tests that need no database, cache or queue run, and the report counts the
+   integration tests it left out (`--with-services --yes` includes them, after printing what
+   they connect to); formats the files it edited, and only those, with your formatter and runs your lint
+   (biome, prettier, eslint) on them, where a new lint failure fails verification; for zod,
+   compares v3 and v4 behaviour of your schemas on generated inputs. The exit code is 0
+   only if no new type error remains and tests pass. Passing compilation does not prove
+   runtime equivalence, so the report in `.uptide/pr-body.md` lists what to review.
+
+Stripe API-version changes are never rewritten by rule: they are assisted or left for
+you, with the relevant changelog entries and a dashboard/webhook checklist in the report.
+
+## Scope
+
+- **Dependencies:** zod 3 → 4 and stripe (14 and newer). Other dependencies can be
+  checked with `uptide check --only <package>`, but that generic check is frozen
+  ([decision](docs/decisions/0010-check-freeze.md)) and has no migrations.
+- **Languages:** TypeScript, and JavaScript the compiler can see (`allowJs`).
+- **Package managers:** `check` on npm, pnpm, yarn classic, bun; `fix` on npm v2/v3, pnpm, and Yarn classic/Berry (node-modules).
+- **Not supported:** Yarn Plug'n'Play, bun's binary lockfile, Deno.
+
+## Privacy
+
+Analysis runs locally. Your code is sent only to the LLM provider (Anthropic), only
+for assisted fixes in `uptide fix`, and only with your own ANTHROPIC_API_KEY: for each
+site the rules cannot migrate, the finding, the enclosing function and the compiler
+error. `uptide fix --no-llm` turns assisted fixes off. No telemetry, no account.
+Other network use: your npm registry for package metadata and tarballs, and GitHub
+only when you pass `fix --pr` or run `pr-body`.
+
+## GitHub Action: Renovate / Dependabot
+
+Use [the example workflow](examples/uptide-workflow.yml), pinning a reviewed commit of `lucasbraum/uptide`. It checks same-repository bot PRs on `pull_request`
+`opened`/`synchronize`, detects zod/stripe upgrades from manifests, catalogs and lockfile
+importers, and maintains one sticky findings comment. `only` selects dependencies;
+`paths` selects repository-relative source directories/globs.
+
+`fix: 'true'` plus `anthropic-api-key` enables migration. Comparison uses **PR-head
+source with the base dependency graph** in a temporary worktree. Final verification
+uses the actual PR-head manifests/lockfile; only source patches are transferred. A
+passing migration pushes **one commit on the existing PR branch**. Manual sites,
+failed tests/types, or a changed PR head prevent publication. No force-push or merge.
+Current migration support is TypeScript, zod and stripe, using npm, pnpm or Yarn with node_modules. Missing workspace test
+scripts are reported, not claimed as passing tests. Code context may be sent to
+Anthropic only in assisted mode. Install/test children receive no API/token secrets.
+
+Use `contents: write` and `pull-requests: write`, `persist-credentials: false`, and the
+same-PR concurrency group shown in the example. Dependabot PRs normally receive a
+read-only `GITHUB_TOKEN` and do not receive ordinary Actions secrets: configure the
+key and an appropriately scoped write token as **Dependabot secrets**, or run in a
+maintainer-controlled workflow. Do not change to `pull_request_target` to bypass
+this boundary. Fork PRs are skipped. See [GitHub's Dependabot restrictions](https://docs.github.com/en/code-security/reference/supply-chain-security/troubleshoot-dependabot/dependabot-on-actions).
+
+```sh
+pnpm eval:action  # local GitHub API simulation + real check/fix/tsc/tests/git remote
+```
+
+This creates an isolated demo repository and bare local remote under `eval-out/`,
+with a zod 3 baseline, a Renovate-style bump branch, and the verified migration result.
+It also proves that a final-verification failure cannot push. The generated README
+contains commands to publish your throwaway repository. **No hosted GitHub run or PR
+is created by this evaluation.** The real workflow requires a bot-authored PR; a
+human-authored imitation is intentionally rejected.
+
+## PR descriptions
+
+`fix` saves `.uptide/report.json` with the verified commit, Uptide version/commit, rule IDs, patches, agent
+reasoning and run metadata. PR bodies show a computed risk, a five-row summary, changes
+grouped by rule, and actionable review items.
+
+To regenerate an existing description without another migration or any push:
+
+```sh
+uptide pr-body --pr 82 --preview           # review the complete proposal first
+uptide pr-body --pr 82                     # update only the description
+# For a retained eval run, add --cwd /path/to/target/repo --run /path/to/report.json.
+```
+
+The selected PR must match the stored run's branch and verified commit. Risk is Low
+for verified rule-only edits, Medium for agent edits, sensitive paths or missing tests,
+and High for unverified sites, behavior changes or remaining manual work. Unchecked
+schema samples are called out separately; they do not imply unresolved compiler sites.
+
+Builds embed the Uptide commit and whether its source checkout had working-tree changes.
+`pnpm exec tsx scripts/reverify-run.ts <run.json> [output.json]` refreshes behavior
+and type verification on the recorded commit without installing or changing source.
+Diffs, file lists, verification and run details are collapsed; the Action comment and
+terminal share the compact migration renderer.
+
+## Development
+
+```sh
+pnpm test                       # offline regressions
+UPTIDE_NETWORK=1 pnpm test      # real package digests and Stripe tsc fixture
+pnpm eval:fix ../wayapi --without-key
+pnpm eval:fix ../wayapi --with-key
+# Only after reviewing a successful eval, publish from another temporary worktree:
+pnpm eval:fix ../wayapi --with-key --pr --yes
+pnpm eval:fix /path/to/repo --only=stripe --target=stripe@22.6.2 --without-key
+```
+
+`eval:fix` creates a temporary git worktree, copies installed dependencies (not symlinks
+to the source repo), and retains the result for review. Artifacts go in `eval-out/`.
+`--with-key` fails explicitly when no key is configured. `pnpm eval:stripe-fixture`
+measures the checked-in Stripe consumer with real `tsc`; `pnpm build:stripe-changelog`
+refreshes the versioned public changelog JSON. Migration execution never fetches it.
+
+`uptide diff <pkg> <from> <to> [--json]` compares the full public surface of two
+versions. Tarballs, surfaces and runtime probes are cached in `~/.cache/uptide/`.
+Releasing is described in [docs/releasing.md](docs/releasing.md); `pnpm smoke` runs the
+packed CLI against npm v3, npm workspaces v2, pnpm catalogs, Yarn classic and Yarn Berry fixtures in clean Node 20/22 containers. Run `pnpm smoke 20` and `pnpm smoke 22`. Each case verifies zod migration and a compatible Stripe SDK upgrade without an LLM; lifecycle-script traps must remain untouched. Lockfile diffs and JSON results are saved beside the temporary CLI tarball.
+
+Yarn PnP remains unsupported. Missing package-manager binaries or mismatched pinned versions fail with an exact Corepack recovery command. Unsupported range/lockfile syntax fails explicitly rather than silently broadening the upgrade.
+
+## License
+
+[MIT](LICENSE).