uptide 0.2.0-next.20261003172442 → 0.3.0

package/README.md

@@ -2,143 +2,150 @@
 
 **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.
+Uptide tells you which of your lines a dependency upgrade breaks, then migrates them on a
+branch it has verified with your own compiler and tests. TypeScript repositories; verified
+migrations for **zod 3 → 4** and **stripe** today.
 
 ## 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
+npx uptide check                         # which of your lines the upgrade breaks
+npx uptide fix --only zod                # migrate on a new branch, verified; nothing is pushed
+npx uptide pr --branch uptide/zod-4.6.5   # prints the plan; add --yes to push and open the PR
 ```
 
-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.
+`npx uptide ` alone shows where zod and stripe stand: installed, latest, majors behind.
+Requires Node 20 or newer. Works with npm, pnpm and Yarn (node-modules linker).
 
-## What `check` prints
+## Before and after
 
-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):
+[`fixtures/repos/storefront`](fixtures/repos/storefront) is a small pnpm workspace in this
+repository, written to exercise Uptide: two packages on zod 3 and stripe 14, with a few
+tests. Everything below is real output from it.
+
+**Before: `check`.** What breaks, where, and who can fix it:
 
 ```console
-$ uptide check --only zod
-uptide check · smoke-pnpm (pnpm, 2 packages) · 3.0s
+$ npx uptide check
+uptide check · storefront (pnpm, 2 packages) · 8.3s
 
-zod  3.23.8 → 4.6.5   major   ✗ 4 breaking in 2 files    4 by rule
+zod                    3.25.76 → 4.6.5    major · latest on npm   ✗ 28 breaking in 7 files    24 by rule · 4 by agent
+stripe (packages/api)  14.25.0 → 23.0.0   major · latest on npm   ✗ 4 breaking in 3 files     1 by rule · 3 by agent
 
 zod
-  ✗ New error API (required_error → error)   4 sites   by rule
+  ✗ New error API (required_error → error)   24 sites          by rule
+  ✗ ZodTypeDef removed                       1 fix, 3 errors   by agent
+  ✗ .ip() removed                            monitoring.ts:6   by agent
+  ! 15 deprecated calls (.uuid, .datetime, .email, ...)   8 by rule
+
+stripe
+  ✗ Test fixture casts widened                   renewal.test.ts:7   by rule
+  ✗ Subscription billing period moved to items   2 sites             by agent
+  ✗ apiVersion no longer matches the SDK         client.ts:9         by agent
+    1 API change since 2023-10-16 affects your code
 
 Next
-  npx uptide fix --only zod                migrate on a new branch, verify, no push
-  npx uptide check --only zod --details    every site and reason
+  npx uptide fix --only zod       migrate on a new branch, verify, no push
+  npx uptide fix --only stripe    migrate on a new branch, verify, no push
+  npx uptide check --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.
+**After: `fix`**, one dependency at a time, each on its own verified branch:
+
+```console
+$ npx uptide fix --only zod
+uptide fix · zod 3.25.76 → 4.6.5 (latest on npm) · verification passed · 36s
+
+  Risk      Medium: request validation in webhooks
+  Changes   29 sites in 8 files · 25 by rule · 4 by agent
+  Types     ✅ 29 errors after the bump → 1 (1 pre-existing)
+  Behavior  ✅ 9 schemas identical · 2 not checked · 21/21 custom-message assertions
+  Tests     ✅ 5 tests in 3 files passed
+```
 
-## What `fix` does, and how it verifies
+No compiler sees this one: zod 4 words its default messages differently, and a test that
+asserted the old wording failed after the migration. Uptide updated it and says so in the
+pull request, so you can check that nothing else reads that text:
 
-On the same fixture (output abridged):
+```diff
+-    expect(parsed.error?.issues[0]?.message).toBe('Required');
++    expect(parsed.error?.issues[0]?.message).toBe('Invalid input: expected string, received undefined');
+```
 
 ```console
-$ uptide fix --only zod --no-llm
-uptide fix · zod 3.23.8 → 4.6.5 (latest on npm) · verification passed · 5.3s
-
-  Risk      Low: rule-based edits, verified
-  Changes   4 sites in 2 files · 4 by rule · 0 by agent
-  Types     ✅ 4 errors after the bump → 0
-  Behavior  ✅ 2 schemas identical
-  Tests     ✅ 12 related tests passed
+$ npx uptide fix --only stripe
+uptide fix · stripe 14.25.0 → 23.0.0 (latest on npm) · verification passed · 41s
+
+  Risk      High: behavior changes
+  Changes   6 sites in 3 files · 3 by rule · 3 by agent
+  Types     ✅ 5 errors after the bump → 1 (1 pre-existing)
+  Behavior  ⚠️ 1 of 570 API changes affects your code · 47 touch resources you use (8 breaking)
+  Tests     ✅ 3 tests in 2 files passed · the test script of packages/api
+```
 
-Branch uptide/zod-4.6.5 (in your repository, not checked out)
-  git diff main..uptide/zod-4.6.5 --stat
+Stripe moved a subscription's billing period from the subscription to its items. Uptide
+added a `subscriptionPeriod` helper and migrated the code that read the old fields:
 
-Next
-  npx uptide pr --branch uptide/zod-4.6.5           push the branch and open a draft PR on you/app
-  open .git/uptide/uptide__zod-4.6.5/report.html    the migration report
-  .git/uptide/uptide__zod-4.6.5/pr-body.md          the PR description
+```diff
+-    renewsAt: new Date(subscription.current_period_end * 1000),
++    renewsAt: new Date(period.end * 1000),
 ```
 
-While it runs, a terminal shows one live line with the phase and what it is verifying
-(`verify · tests (api, web)`); `--verbose` prints one line per phase with timings. The
-target is the npm `latest` dist-tag, the same one `check` compares against, unless
-`--target` names a version.
-
-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`,
-   or later run `uptide pr --branch <branch> --yes`, which loads the stored run, checks the
-   branch is still at the verified commit (else `uptide verify`), prints which repository
-   the PR goes to (a fork itself, never its parent unless `--repo` names it) and opens it
-   with the stored description.
-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 (`pr-body.md` and `report.html` next to the stored
-   run in `.git/uptide/<branch>/`) 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.
+The risk is High on purpose: types and tests pass, but a new API version changes what
+Stripe sends, and the pull request asks what only you can answer (which item's period
+counts when a subscription has several).
+
+The one type error left in both runs is the fixture's own, there on purpose: errors a
+repository already had are subtracted, never blamed on the upgrade.
+
+## What is supported
+
+| Tier | Dependencies | What you get |
+| --- | --- | --- |
+| **Verified** | zod 3 → 4, stripe 14 and newer | `check` with a migration plan per change, `fix` with rules written for that dependency, behavior checks (zod schemas compared on generated inputs; Stripe changelog filtered to what you call), a reviewed pull request body |
+| **Generic** | any other dependency, with `--only <package>` | `check` only: the API diff between the two versions, your usages of what changed, and the compiler's errors against the target. No migrations. |
+
+Verified means a migration pack exists: rules, a guide for the assisted fixer, and ground
+truth from a real upgrade that the pack is scored against. Generic is the same analysis
+without that knowledge; it is frozen while the packs mature
+([decision](docs/decisions/0010-check-freeze.md)), and generic *migrations* are planned,
+not shipped.
+
 - **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).
+- **Package managers:** `check` on npm, pnpm (workspaces and catalogs), Yarn classic and
+  bun (text lockfile); `fix` on npm (lockfile v2/v3), pnpm, and Yarn classic/Berry with the
+  node-modules linker.
 - **Not supported:** Yarn Plug'n'Play, bun's binary lockfile, Deno.
 
+## How verification works
+
+`fix` never works in your checkout. It clones your repository into a temporary directory
+and, there:
+
+1. **Baseline.** Type-checks and notes the errors you already have.
+2. **Upgrades.** Bumps the version everywhere it is declared. Your package manager
+   produces the lockfile, with lifecycle scripts disabled; a lockfile change outside the
+   upgraded dependency's subtree is rejected.
+3. **Rule-based fixes.** Deterministic rewrites, only at the sites `check` reported.
+4. **Assisted fixes (optional).** Sites no rule covers go to the LLM one at a time. A patch
+   is kept only if it removes its compiler error, introduces none, and passes the pack's
+   own validator; otherwise it is reverted and the site is left for you.
+5. **Verifies.** Type-checks with *your* TypeScript and subtracts the baseline; runs the
+   tests related to the files it touched; formats and lints only those files with your
+   tools. Tests that need a database, cache or queue do not run unless you ask
+   (`--with-services --yes`), and the report counts what was left out.
+
+The exit code is 0 only if no new type error remains and the tests pass. You get the branch
+as a ref in your repository and the run stored in `.git/uptide/`; your branch, files, hooks
+and git config are compared before and after and must be identical. Nothing is pushed
+until you run `uptide pr` or pass `--pr --yes`.
+
+Passing compilation does not prove runtime equivalence. The report says what was verified,
+what was not, and what to review; server API changes (Stripe API versions) are never
+rewritten by rule.
+
 ## Privacy
 
 Analysis runs locally. Your code is sent only to the LLM provider (Anthropic), only
@@ -148,117 +155,35 @@ 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:
+There is no Uptide server. In a table:
 
-```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.
+| | Where it runs | What leaves your machine |
+| --- | --- | --- |
+| `check` | locally | nothing of yours; it downloads package tarballs from your npm registry. No LLM call, and nothing in your repository is executed. |
+| `fix`, rules and verification | locally, in a temporary clone | nothing of yours |
+| `fix`, assisted fixes | Anthropic's API, with **your** `ANTHROPIC_API_KEY` | per site no rule covers: the finding, the enclosing function or declaration, and the compiler error |
+| `pr`, `fix --pr` | GitHub, through your own `gh` | the branch and the pull request, when you say so |
 
-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.
+Without a key, or with `--no-llm`, those sites are listed for you instead. The full model, and how to report a problem, is in
+[SECURITY.md](SECURITY.md).
 
-## Development
+## Exit codes
 
-```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
-pnpm eval:check /path/to/repo --only=stripe --target=stripe@23.0.0 --truth=fixtures/truth/traceroot-stripe.json
-```
-
-`eval:check --truth` scores a check against the new `tsc` errors a real upgrade produced
-(`fixtures/truth/*.json`: wayapi on zod 4 and stripe 22, the traceroot fork on stripe 23);
-a case's `runtime` sites are what no compiler shows, such as a Stripe client created
-without `apiVersion`, scored apart.
-
-`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.
+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.
 
-`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.
+## Documentation
 
-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.
+- [CLI reference](docs/cli.md): flags, the HTML report, each step of `fix`, pull request
+  descriptions
+- [GitHub Action](docs/github-action.md): check and migrate Renovate and Dependabot pull
+  requests
+- [Architecture](docs/architecture.md) and [decisions](docs/decisions/): how it works and why
+- [Security](SECURITY.md): the isolation model
+- [Contributing](CONTRIBUTING.md): setup, tests, how migration packs work
+- [Development](docs/development.md) and [releasing](docs/releasing.md)
 
 ## License
 
 [MIT](LICENSE).
-
-### Share a local HTML check report
-
-```sh
-uptide check --html                 # terminal output + <OS temp>/uptide/<repo>-<timestamp>.html
-uptide check --html review.html     # explicit output path, relative to your current directory
-uptide check --html --open          # open the default browser in an interactive terminal
-uptide check --json --html --ci     # stdout stays JSON; the HTML path is printed on stderr
-```
-
-The report uses the terminal's migration plan: dependency summary first, then expandable
-rules and sites, deprecated calls, analysis notes, and copyable next commands. Search
-and severity filters work with plain inline JavaScript; the report remains readable
-without it. Printing expands the details. Dark/light themes follow your system.
-
-One self-contained file, no network requests, web fonts, images, or analytics. It includes
-only the reported source excerpts (three lines before/after, up to 50 excerpts per group),
-with VS Code file links. Missing or out-of-repository files are disclosed instead of read.
-Long lines/excerpts and very large reports are trimmed with a notice to keep the file
-below 300 KB. Review excerpts before sharing. `--open` never opens a browser in CI or
-when output is redirected; `--open` requires `--html`.