vueleap 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.1] - 2026-10-12
+
+### Fixed
+
+- The npm page now shows the English README. The Portuguese translation moved to `i18n/README.pt-BR.md`.
+
+## [0.1.0] - 2026-10-12
+
+### Added
+
+- `npx vueleap` command (with `vue2to3` as an alias) that scans a Vue 2 project
+  and reports every Vue 3 breaking change with file, line, column, explanation
+  and a link to the official migration guide.
+- 41 rules covering templates, scripts, styles and `package.json`, including
+  filters, `$listeners`, `$scopedSlots`, the event bus API, `$set` and
+  `$delete`, the global API, lifecycle and directive hook renames, `v-model`
+  changes, `.sync`, `.native`, keyCode modifiers, functional components,
+  transition classes, render functions and Vue 2 only libraries.
+- Minimal `@vue/compat` configuration (runtime `configureCompat` flags and
+  compiler `compatConfig` flags) generated from the findings.
+- `--fix` dry run with unified diffs and `--fix --write` for 8 safe codemods.
+- Pretty terminal report, `--json`, and a standalone `--html` report with light
+  and dark themes and filters.
+- `--fail-on` exit codes for CI.
+- Programmatic API: `analyze`, `fix`, `formatPretty`, `formatJson`,
+  `formatHtml` and the rule registry.
+
+[0.1.0]: https://github.com/kwy404/vueleap/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandre Kohler
+
+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

@@ -1,3 +1,352 @@
-# Temporary Holding Version
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://cdn.jsdelivr.net/gh/kwy404/vueleap@main/assets/banner-dark.svg">
+    <img src="https://cdn.jsdelivr.net/gh/kwy404/vueleap@main/assets/banner.svg" width="820" alt="vueleap, the Vue 2 to Vue 3 migration tool: Hop the frog leaps from a lily pad marked 2 to a lily pad marked 3">
+  </picture>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">vueleap: migrate Vue 2 to Vue 3 with one command</h1>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/vueleap"><img src="https://img.shields.io/npm/v/vueleap?color=42b883&label=npm" width="80" alt="vueleap npm version"></a>
+  <a href="https://github.com/kwy404/vueleap/actions/workflows/ci.yml"><img src="https://github.com/kwy404/vueleap/actions/workflows/ci.yml/badge.svg" width="96" alt="CI status of the Vue 3 migration tool"></a>
+  <a href="https://github.com/kwy404/vueleap/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/vueleap?color=42b883" width="78" alt="MIT license"></a>
+  <a href="https://github.com/kwy404/vueleap/blob/main/package.json"><img src="https://img.shields.io/node/v/vueleap?color=42b883" width="90" alt="Node.js 18 or newer"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/kwy404/vueleap/blob/main/i18n/README.pt-BR.md">Leia em Português (pt-BR)</a> &middot;
+  <a href="https://kwy404.github.io/vueleap/">Documentation</a> &middot;
+  <a href="https://kwy404.github.io/vueleap/report-example.html">Sample report</a> &middot;
+  <a href="https://kwy404.github.io/vueleap/vue-3-breaking-changes-checklist.html">Breaking changes checklist</a>
+</p>
+
+**Find everything that breaks when you migrate from Vue 2 to Vue 3, in one command.** vueleap is a free, open source Vue 3 migration tool: it scans a Vue 2 project and lists every Vue 3 breaking change file by file and line by line, explains each one with a link to the official migration guide, prints the exact `@vue/compat` flags your project needs for the migration build, and applies safe automatic fixes.
+
+```bash
+npx vueleap
+```
+
+<table>
+  <tr>
+    <td width="33%" valign="top"><img src="https://cdn.jsdelivr.net/gh/kwy404/vueleap@main/assets/icons/scan.svg" width="40" alt="Scan icon: Vue 2 to Vue 3 breaking changes checker"><br><b>Scan the whole project</b><br>41 checks over templates, scripts, styles and package.json, with file, line and column.</td>
+    <td width="33%" valign="top"><img src="https://cdn.jsdelivr.net/gh/kwy404/vueleap@main/assets/icons/fix.svg" width="40" alt="Wrench icon: safe automatic Vue 3 codemods"><br><b>Apply safe fixes</b><br>8 codemods that are provably safe, shown as a diff before anything is written.</td>
+    <td width="33%" valign="top"><img src="https://cdn.jsdelivr.net/gh/kwy404/vueleap@main/assets/icons/compat.svg" width="40" alt="Toggle icon: @vue/compat build flags"><br><b>Get exact compat flags</b><br>The minimal <code>configureCompat</code> and <code>compatConfig</code> for the migration build.</td>
+  </tr>
+  <tr>
+    <td width="33%" valign="top"><img src="https://cdn.jsdelivr.net/gh/kwy404/vueleap@main/assets/icons/report.svg" width="40" alt="Chart icon: HTML Vue 3 migration report"><br><b>Share an HTML report</b><br>One standalone file with filters, light and dark themes and guide links.</td>
+    <td width="33%" valign="top"><img src="https://cdn.jsdelivr.net/gh/kwy404/vueleap@main/assets/icons/ci.svg" width="40" alt="Pipeline icon: Vue 3 migration checks in CI"><br><b>Gate it in CI</b><br><code>--fail-on error</code> and <code>--json</code> keep Vue 2 only code from coming back.</td>
+    <td width="33%" valign="top"><img src="https://cdn.jsdelivr.net/gh/kwy404/vueleap@main/assets/icons/api.svg" width="40" alt="Braces icon: programmatic Node.js API"><br><b>Use the API</b><br><code>analyze()</code> and <code>fix()</code> from Node.js for your own tooling.</td>
+  </tr>
+</table>
+
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/kwy404/vueleap@main/assets/demo.svg" width="100%" alt="Animated terminal demo: npx vueleap scans a Vue 2 app and prints Vue 3 breaking changes such as filters, beforeDestroy renames and keyCode modifiers, then a summary with an effort score">
+</p>
+
+## Table of contents
+
+- [How do I check what breaks when migrating from Vue 2 to Vue 3?](#how-do-i-check-what-breaks-when-migrating-from-vue-2-to-vue-3)
+- [What does vueleap check?](#what-does-vueleap-check)
+- [Which fixes can vueleap apply automatically?](#which-fixes-can-vueleap-apply-automatically)
+- [Which @vue/compat flags does my project need?](#which-vuecompat-flags-does-my-project-need)
+- [What does the HTML report look like?](#what-does-the-html-report-look-like)
+- [How do I run vueleap in CI?](#how-do-i-run-vueleap-in-ci)
+- [Can I use vueleap from Node.js?](#can-i-use-vueleap-from-nodejs)
+- [FAQ](#faq)
+- [How does vueleap compare to other Vue 3 migration tools?](#how-does-vueleap-compare-to-other-vue-3-migration-tools)
+- [Documentation and guides](#documentation-and-guides)
+- [Contributing](#contributing)
+- [License](#license)
+
+## How do I check what breaks when migrating from Vue 2 to Vue 3?
+
+Run vueleap at the root of your Vue 2 project. No install, no config:
+
+```bash
+npx vueleap                      # report for the current directory
+npx vueleap ./apps/web           # report for another directory
+npx vueleap --html report.html   # also write a standalone HTML report
+npx vueleap --fix                # preview safe fixes as a diff
+npx vueleap --fix --write        # apply them
+```
+
+`vue2to3` is installed as an alias, so `npx -p vueleap vue2to3` works too.
+
+vueleap reads `.vue` single file components (template, `<script>`, `<script setup>`, `<style>`), JavaScript, TypeScript, JSX, TSX, CSS, SCSS, Less and Stylus files, plus `package.json`. It respects `.gitignore` (including nested ones), always skips `node_modules` and `dist`, and never follows symbolic links. Pug templates are skipped with a warning, the rest of the file is still analyzed.
+
+This is the real output for the sample app in [`test/fixtures/vue2-app`](https://github.com/kwy404/vueleap/tree/main/test/fixtures/vue2-app) (excerpt):
+
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/kwy404/vueleap@main/assets/terminal.svg" width="100%" alt="vueleap terminal report for a Vue 2 app: Vue 3 breaking changes grouped by rule, each with file, line, column, migration guide link and @vue/compat flag">
+</p>
+
+| Option | Description |
+| --- | --- |
+| `--json` | Print the report as JSON (stable `schemaVersion: 1`) |
+| `--html <file>` | Also write a standalone HTML report |
+| `--fix` | Preview the safe automatic fixes as a unified diff (dry run) |
+| `--write` | With `--fix`, write the fixes to disk |
+| `--fail-on <level>` | Exit with code 1 when a finding at or above `error`, `warning` or `info` exists (default `none`) |
+| `--compat` | Print only the `@vue/compat` configuration |
+| `--rule <id>` / `--skip-rule <id>` | Run only, or skip, some rules (repeatable) |
+| `--ignore <pattern>` | Extra ignore pattern in `.gitignore` syntax (repeatable) |
+| `--no-gitignore` | Do not read `.gitignore` files |
+| `--list-rules` | List every rule |
+| `--verbose` | Print every finding (the default caps each rule at 15 lines) |
+| `--no-color` | Disable colors |
+
+Exit codes: `0` success, `1` findings at or above `--fail-on`, `2` usage or runtime error.
+
+## What does vueleap check?
+
+41 rules based on the official [Vue 3 migration guide](https://v3-migration.vuejs.org/breaking-changes/). Severity tells you what to expect: **error** breaks at compile time or at runtime, **warning** changes behavior, **info** deserves a review. Each rule links to its guide entry.
+
+| Rule | Severity | Where | What it finds | Auto fix | @vue/compat flag |
+| --- | --- | --- | --- | --- | --- |
+| [`filters`](https://v3-migration.vuejs.org/breaking-changes/filters) | error | Template | Filters are removed |  | `COMPILER_FILTERS` `FILTERS` |
+| [`listeners`](https://v3-migration.vuejs.org/breaking-changes/listeners-removed) | error | Script | $listeners is removed |  | `INSTANCE_LISTENERS` |
+| [`scoped-slots`](https://v3-migration.vuejs.org/breaking-changes/slots-unification) | error | Script | $scopedSlots is removed | yes | `INSTANCE_SCOPED_SLOTS` |
+| [`event-emitter`](https://v3-migration.vuejs.org/breaking-changes/events-api) | error | Script | $on, $off and $once are removed |  | `INSTANCE_EVENT_EMITTER` |
+| [`hook-events`](https://v3-migration.vuejs.org/breaking-changes/vnode-lifecycle-events) | warning | Template | hook: lifecycle events are renamed | yes | `INSTANCE_EVENT_HOOKS` |
+| [`set-delete`](https://v3-migration.vuejs.org/breaking-changes/#removed-apis) | error | Script | $set, $delete, Vue.set and Vue.delete are removed |  | `GLOBAL_SET` `GLOBAL_DELETE` `INSTANCE_SET` `INSTANCE_DELETE` |
+| [`children`](https://v3-migration.vuejs.org/breaking-changes/children) | error | Script | $children is removed |  | `INSTANCE_CHILDREN` |
+| [`destroy`](https://v3-migration.vuejs.org/breaking-changes/#removed-apis) | error | Script | $destroy is removed |  | `INSTANCE_DESTROY` |
+| [`global-mount`](https://v3-migration.vuejs.org/breaking-changes/global-api#mounting-app-instance) | error | Script | new Vue() is replaced by createApp() |  | `GLOBAL_MOUNT` |
+| [`global-api`](https://v3-migration.vuejs.org/breaking-changes/global-api) | error | Script | Global Vue API moved to the app instance |  | `GLOBAL_OBSERVABLE` `GLOBAL_PRIVATE_UTIL` |
+| [`global-prototype`](https://v3-migration.vuejs.org/breaking-changes/global-api#vue-prototype-replaced-by-config-globalproperties) | error | Script | Vue.prototype is replaced by app.config.globalProperties |  | `GLOBAL_PROTOTYPE` |
+| [`global-extend`](https://v3-migration.vuejs.org/breaking-changes/global-api#vue-extend-removed) | error | Script | Vue.extend is removed |  | `GLOBAL_EXTEND` |
+| [`config-production-tip`](https://v3-migration.vuejs.org/breaking-changes/global-api#config-productiontip-removed) | warning | Script | Vue.config.productionTip is removed | yes | `CONFIG_PRODUCTION_TIP` |
+| [`config-ignored-elements`](https://v3-migration.vuejs.org/breaking-changes/global-api#config-ignoredelements-is-now-config-compileroptions-iscustomelement) | warning | Script | Vue.config.ignoredElements is replaced by isCustomElement |  | `CONFIG_IGNORED_ELEMENTS` |
+| [`config-key-codes`](https://v3-migration.vuejs.org/breaking-changes/keycode-modifiers) | error | Script | Vue.config.keyCodes is removed |  | `CONFIG_KEY_CODES` |
+| [`global-config`](https://v3-migration.vuejs.org/breaking-changes/global-api#a-new-global-api-createapp) | warning | Script | Vue.config moved to app.config |  | `CONFIG_SILENT` `CONFIG_DEVTOOLS` `CONFIG_OPTION_MERGE_STRATS` |
+| [`destroy-hooks`](https://v3-migration.vuejs.org/breaking-changes/#other-minor-changes) | error | Script | beforeDestroy and destroyed are renamed | yes | `OPTIONS_BEFORE_DESTROY` `OPTIONS_DESTROYED` |
+| [`directive-hooks`](https://v3-migration.vuejs.org/breaking-changes/custom-directives) | error | Script | Custom directive hooks are renamed | yes | `CUSTOM_DIR` |
+| [`component-v-model`](https://v3-migration.vuejs.org/breaking-changes/v-model) | error | Script | v-model on components uses modelValue |  | `COMPONENT_V_MODEL` |
+| [`sync-modifier`](https://v3-migration.vuejs.org/breaking-changes/v-model) | error | Template | .sync is replaced by v-model:prop | yes | `COMPILER_V_BIND_SYNC` |
+| [`native-modifier`](https://v3-migration.vuejs.org/breaking-changes/v-on-native-modifier-removed) | warning | Template | The .native modifier is removed |  | `COMPILER_V_ON_NATIVE` |
+| [`keycode-modifiers`](https://v3-migration.vuejs.org/breaking-changes/keycode-modifiers) | error | Template | KeyCode modifiers are removed | yes | `V_ON_KEYCODE_MODIFIER` |
+| [`functional-components`](https://v3-migration.vuejs.org/breaking-changes/functional-components) | error | Template | Functional components changed |  | `COMPONENT_FUNCTIONAL` |
+| [`inline-template`](https://v3-migration.vuejs.org/breaking-changes/inline-template-attribute) | error | Template | inline-template is removed |  | `COMPILER_INLINE_TEMPLATE` |
+| [`template-v-for-key`](https://v3-migration.vuejs.org/breaking-changes/key-attribute) | error | Template | Key must be on &lt;template v-for&gt; |  |  |
+| [`v-if-v-for`](https://v3-migration.vuejs.org/breaking-changes/v-if-v-for) | error | Template | v-if now has higher priority than v-for |  | `COMPILER_V_IF_V_FOR_PRECEDENCE` |
+| [`v-bind-object-order`](https://v3-migration.vuejs.org/breaking-changes/v-bind) | warning | Template | v-bind="object" is order sensitive |  | `COMPILER_V_BIND_OBJECT_ORDER` |
+| [`transition-classes`](https://v3-migration.vuejs.org/breaking-changes/transition) | warning | Style | Transition classes renamed | yes | `TRANSITION_CLASSES` |
+| [`transition-group-root`](https://v3-migration.vuejs.org/breaking-changes/transition-group) | info | Template | &lt;transition-group&gt; renders no wrapper |  | `TRANSITION_GROUP_ROOT` |
+| [`render-function-h`](https://v3-migration.vuejs.org/breaking-changes/render-function-api) | error | Script | Render functions no longer receive h |  | `RENDER_FUNCTION` |
+| [`attrs-class-style`](https://v3-migration.vuejs.org/breaking-changes/attrs-includes-class-style) | info | Script | $attrs now includes class and style |  | `INSTANCE_ATTRS_CLASS_STYLE` |
+| [`data-object`](https://v3-migration.vuejs.org/breaking-changes/data-option) | error | Script | data must be a function |  | `OPTIONS_DATA_FN` |
+| [`watch-array`](https://v3-migration.vuejs.org/breaking-changes/watch) | info | Script | Array watchers need deep for mutations |  | `WATCH_ARRAY` |
+| [`deprecated-slot-syntax`](https://v2.vuejs.org/v2/guide/components-slots.html#Deprecated-Syntax) | error | Template | slot and slot-scope attributes are removed |  |  |
+| [`is-on-element`](https://v3-migration.vuejs.org/breaking-changes/custom-elements-interop#customized-built-in-elements) | warning | Template | is on native elements needs the vue: prefix |  | `COMPILER_IS_ON_ELEMENT` |
+| [`composition-api-plugin`](https://github.com/vuejs/composition-api#readme) | warning | Script | @vue/composition-api is built in |  |  |
+| [`vue-version`](https://v3-migration.vuejs.org/migration-build) | warning | package.json | Vue 2 dependency |  |  |
+| [`vue2-tooling`](https://v3-migration.vuejs.org/migration-build#installation) | warning | package.json | Vue 2 build or test tooling |  |  |
+| [`vue-router-v3`](https://router.vuejs.org/guide/migration/) | error | package.json | vue-router 3 does not support Vue 3 |  |  |
+| [`vuex-v3`](https://vuex.vuejs.org/guide/migrating-to-4-0-from-3-x.html) | error | package.json | Vuex 3 does not support Vue 3 |  |  |
+| [`vue2-libraries`](https://v3-migration.vuejs.org/) | error | package.json | Vue 2 only library |  |  |
+
+The same list, with explanations, is on the [Vue 3 breaking changes checklist](https://kwy404.github.io/vueleap/vue-3-breaking-changes-checklist.html).
+
+## Which fixes can vueleap apply automatically?
+
+Only rewrites that keep exactly the same meaning in Vue 3. Formatting is preserved because vueleap edits the exact character ranges it reported, nothing is reprinted.
+
+| Rule | Before | After |
+| --- | --- | --- |
+| `destroy-hooks` | `beforeDestroy()`, `destroyed()` | `beforeUnmount()`, `unmounted()` |
+| `directive-hooks` | `bind`, `inserted`, `componentUpdated`, `unbind` | `beforeMount`, `mounted`, `updated`, `unmounted` |
+| `scoped-slots` | `this.$scopedSlots.default` | `this.$slots.default` |
+| `transition-classes` | `.fade-enter`, `.v-leave`, `enter-class` | `.fade-enter-from`, `.v-leave-from`, `enter-from-class` |
+| `keycode-modifiers` | `@keyup.13`, `@keyup.27` | `@keyup.enter`, `@keyup.esc` |
+| `sync-modifier` | `:title.sync="doc.title"` | `v-model:title="doc.title"` |
+| `hook-events` | `@hook:mounted` | `@vue:mounted` |
+| `config-production-tip` | `Vue.config.productionTip = false` | (line removed) |
+
+Safety rules:
+
+- Dry run by default: `--fix` prints a diff, `--fix --write` writes.
+- A rename is skipped when the new name already exists in the same object (for example a half migrated mixin with both `destroyed` and `unmounted`).
+- Transition classes are renamed only for names used by a `<transition name>` or that have `-enter-active` style classes, so an unrelated `.btn-enter` is never touched.
+- KeyCode modifiers are only rewritten when one key name matches (`.112` is reported, not guessed).
+- Files are resolved inside the project root and checked again with their real path, and a file that changed since the analysis aborts the write.
+
+## Which @vue/compat flags does my project need?
+
+The [migration build](https://v3-migration.vuejs.org/migration-build) (`@vue/compat`) runs Vue 2 code on Vue 3 and lets you switch each Vue 2 behavior on or off. vueleap maps every finding to its flag and prints the smallest configuration: Vue 3 behavior by default (`MODE: 3`) with only the flags the code still needs. Runtime flags go to `configureCompat()`, template compiler flags (`COMPILER_*`) go to your build tool.
+
+```bash
+npx vueleap --compat
+```
+
+Real output for [`test/fixtures/edge-cases`](https://github.com/kwy404/vueleap/tree/main/test/fixtures/edge-cases):
+
+```js
+// main.js (with 'vue' aliased to '@vue/compat')
+import { configureCompat } from 'vue'
+
+configureCompat({
+  MODE: 3,
+  CUSTOM_DIR: true,
+  GLOBAL_DELETE: true,
+  GLOBAL_EXTEND: true,
+  GLOBAL_SET: true,
+  INSTANCE_EVENT_EMITTER: true,
+  INSTANCE_LISTENERS: true,
+  OPTIONS_BEFORE_DESTROY: true,
+  OPTIONS_DESTROYED: true,
+  RENDER_FUNCTION: true,
+  TRANSITION_CLASSES: true,
+  WATCH_ARRAY: true,
+})
+
+// vite.config.js
+import vue from '@vitejs/plugin-vue'
+
+export default {
+  resolve: { alias: { vue: '@vue/compat' } },
+  plugins: [
+    vue({
+      template: {
+        compilerOptions: {
+          compatConfig: {
+            MODE: 3,
+            COMPILER_FILTERS: true,
+          },
+        },
+      },
+    }),
+  ],
+}
+```
+
+Every flag name is checked by the test suite against the `DeprecationTypes` and `CompilerDeprecationTypes` enums shipped with Vue. Remove flags as you fix findings, and drop `@vue/compat` when the list is empty. More in [@vue/compat build flags explained](https://kwy404.github.io/vueleap/vue-compat-build-flags.html).
+
+## What does the HTML report look like?
+
+`npx vueleap --html report.html` writes one standalone file (no external scripts or styles) that you can attach to a ticket or share with your team. It has summary cards, the compat configuration with a copy button, filters by severity, rule, text and fixability, and light and dark themes. [Open the live sample report](https://kwy404.github.io/vueleap/report-example.html).
+
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/kwy404/vueleap@main/assets/report.png" width="100%" alt="vueleap HTML report for a Vue 2 app: summary cards with errors, warnings and auto fixable count, minimal @vue/compat configuration and Vue 3 breaking changes grouped by rule">
+</p>
+
+## How do I run vueleap in CI?
+
+Fail the build when Vue 2 only code is introduced, or track migration progress over time:
+
+```yaml
+# .github/workflows/vue3-migration.yml
+name: Vue 3 migration
+on: [push, pull_request]
+jobs:
+  vueleap:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npx vueleap --fail-on error --html vueleap-report.html
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: vueleap-report
+          path: vueleap-report.html
+```
+
+`--json` prints a machine readable report (`summary`, `effort`, `compat`, `findings` with `ruleId`, `severity`, `file`, `line`, `column`, `docs`, `compatFlags`, `fixable`) for dashboards and custom checks.
+
+## Can I use vueleap from Node.js?
+
+Yes. The package is ESM and ships TypeScript types.
+
+```ts
+import { promises as fs } from 'node:fs'
+import { analyze, fix, formatHtml, compatSnippet } from 'vueleap'
+
+const result = await analyze('./my-vue2-app', { skipRules: ['attrs-class-style'] })
+
+console.log(result.summary.error, 'errors in', result.summary.filesWithFindings, 'files')
+console.log('effort score:', result.effort.score, result.effort.level)
+console.log(compatSnippet(result.compat))
+
+for (const finding of result.findings) {
+  console.log(`${finding.file}:${finding.line}:${finding.column}`, finding.ruleId, finding.message)
+}
+
+// Preview fixes (nothing is written without write: true)
+const { files } = await fix('./my-vue2-app', { write: false })
+for (const file of files) console.log(file.diff)
+
+await fs.writeFile('report.html', formatHtml(result))
+```
+
+Main exports: `analyze`, `fix`, `planFixes`, `applyEdits`, `formatPretty`, `formatJson`, `formatHtml`, `compatSnippet`, `collectCompatFlags`, `RULES`, plus the `AnalysisResult`, `Finding` and `RuleMeta` types.
+
+## FAQ
+
+### How long does a Vue 2 to Vue 3 migration take?
+
+It depends on how much the code relies on removed APIs and on Vue 2 only libraries, so measure instead of guessing: `npx vueleap` ends with an **effort score**. Each finding adds its rule weight (an event bus call weighs more than a lifecycle rename, a UI library such as Vuetify 2 or BootstrapVue weighs a lot), and auto fixable findings count for a tenth. As a rough guide one point is about an hour of focused work, but the score is best used to compare projects and track progress. The sample app scores 59, mostly because of BootstrapVue, vue-router 3 and Vuex 3.
+
+### Should I use @vue/compat?
+
+For medium and large apps, usually yes: the migration build lets the app run on Vue 3 while you convert code step by step, and vueleap tells you exactly which flags to enable. It is a migration aid, not a long term runtime, and libraries that rely on Vue 2 internals (the official docs mention Vuetify, Quasar and Element UI) need their Vue 3 versions anyway. Small apps are often faster to migrate directly, using `npx vueleap --fix --write` and the report.
+
+### Is Vue 2 still supported?
+
+No. Vue 2 reached end of life on **December 31, 2023**. It no longer receives updates from the Vue team, including security fixes, and most of the ecosystem now targets Vue 3. Existing apps keep working, but the risk grows over time. See [Vue 2 end of life](https://kwy404.github.io/vueleap/vue-2-end-of-life.html).
+
+### Does vueleap change my code?
+
+Only with `--fix --write`. Without `--write`, `--fix` prints a diff. A plain `npx vueleap` only reads files.
+
+### Does it work with TypeScript, `<script setup>` and class components?
+
+Yes: `lang="ts"` and `lang="tsx"` blocks, `.ts` and `.tsx` files, Vue 2.7 `<script setup>` (including the 2.7 only `set` and `del` imports), and `vue-property-decorator` or `vue-class-component` classes are analyzed.
+
+### Does it support Nuxt 2?
+
+It analyzes the Vue code of a Nuxt 2 app and reports `nuxt` 2 in `package.json` with a pointer to the Nuxt migration guide, but it does not check Nuxt specific APIs.
+
+### Can it produce false positives?
+
+Static analysis can only see code, not runtime values, so a few findings may need judgment (for example `$attrs` info findings or a `v-bind="obj"` order warning where the keys never overlap). Component checks only run on objects that really look like Vue options, and the test suite includes look alike code that must not be reported. Use `--skip-rule` for checks that do not apply to you.
+
+## How does vueleap compare to other Vue 3 migration tools?
+
+| | vueleap | [vue-codemod](https://github.com/vuejs/vue-codemod) | [GoGoCode](https://github.com/thx/gogocode) (`gogocode-plugin-vue`) | [eslint-plugin-vue](https://eslint.vuejs.org/) |
+| --- | --- | --- | --- | --- |
+| Main purpose | Project wide report and plan | Code transformations | Code transformations | Linting in the editor and CI |
+| Reports breaking changes with file and line | Yes | No | No | Yes, with its `no-deprecated-*` rules |
+| `@vue/compat` flags for your project | Yes | No | No | No |
+| Vue 2 only dependencies and effort estimate | Yes | No | No | No |
+| Automatic rewrites | 8 safe codemods | Several transformations (jscodeshift) | Broad transformation of a whole project | Autofix for some rules |
+| Status | Active | README says "experimental" | Plugin for Vue 2 to 3 published by the GoGoCode team | Maintained by the Vue team |
+
+They work well together: run vueleap to see the size of the migration and to configure the compat build, use a transformation tool if you want large automated rewrites, and keep eslint-plugin-vue in your editor afterwards.
+
+## Documentation and guides
+
+- [vueleap documentation home](https://kwy404.github.io/vueleap/)
+- [How to migrate Vue 2 to Vue 3, step by step](https://kwy404.github.io/vueleap/migrate-vue-2-to-vue-3.html)
+- [Vue 3 breaking changes checklist](https://kwy404.github.io/vueleap/vue-3-breaking-changes-checklist.html)
+- [@vue/compat build flags explained](https://kwy404.github.io/vueleap/vue-compat-build-flags.html)
+- [Vue filters removed in Vue 3](https://kwy404.github.io/vueleap/vue-filters-removed-vue-3.html)
+- [Event bus in Vue 3 ($on, $off, $once)](https://kwy404.github.io/vueleap/vue-event-bus-vue-3.html)
+- [v-model changes in Vue 3](https://kwy404.github.io/vueleap/v-model-changes-vue-3.html)
+- [Vue 2 end of life](https://kwy404.github.io/vueleap/vue-2-end-of-life.html)
+- [Sample HTML report](https://kwy404.github.io/vueleap/report-example.html)
+
+## Contributing
+
+Issues and pull requests are welcome. [CONTRIBUTING.md](https://github.com/kwy404/vueleap/blob/main/CONTRIBUTING.md) explains the architecture and how to add a rule in a few steps (register it, detect it, add a fixture, update the snapshot).
+
+```bash
+npm install
+npm run build && npm run typecheck && npm run lint && npm test
+```
+
+## License
+
+[MIT](https://github.com/kwy404/vueleap/blob/main/LICENSE) &copy; 2026 [Alexandre Kohler](https://github.com/kwy404)

package/dist/analyze.d.ts

@@ -0,0 +1,18 @@
+import { FileContext } from './context.js';
+import type { AnalysisResult, AnalyzeOptions, EffortEstimate, Finding, Summary } from './types.js';
+export declare function analyzeFile(file: string, text: string, transitionNames: ReadonlySet<string>, enabled: (id: string) => boolean): FileContext;
+export declare function summarize(findings: readonly Finding[], filesScanned: number): Summary;
+/**
+ * Relative effort score. Each finding adds its rule weight (fixable findings
+ * count for a tenth, since `--fix` handles them). As a rough guide one point
+ * is about an hour of focused work, but treat it as a comparison tool.
+ */
+export declare function estimateEffort(findings: readonly Finding[]): EffortEstimate;
+/**
+ * Scans a Vue 2 project and returns every finding that matters for Vue 3.
+ *
+ * @example
+ * const result = await analyze('./my-app')
+ * console.log(result.summary.error, result.compat.runtime)
+ */
+export declare function analyze(projectDir: string, options?: AnalyzeOptions): Promise<AnalysisResult>;

package/dist/analyze.js

@@ -0,0 +1,167 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { parse as parseTemplate } from '@vue/compiler-dom';
+import { collectCompatFlags } from './compat.js';
+import { FileContext } from './context.js';
+import { listFiles, SCRIPT_EXTENSIONS, STYLE_EXTENSIONS } from './files.js';
+import { RULES, RULES_BY_ID } from './rules.js';
+import { scanPackageJson } from './scan/package.js';
+import { scanScript } from './scan/script.js';
+import { EMITS_INPUT, scanSfc } from './scan/sfc.js';
+import { collectTransitionNames, scanStyle } from './scan/style.js';
+import { scanTemplate } from './scan/template.js';
+import { NAME, VERSION } from './version.js';
+const SEVERITY_RANK = { error: 0, warning: 1, info: 2 };
+function ruleFilter(options) {
+    for (const id of [...(options.rules ?? []), ...(options.skipRules ?? [])]) {
+        if (!RULES_BY_ID.has(id))
+            throw new Error(`Unknown rule "${id}". Run "vueleap --list-rules" to see all rules.`);
+    }
+    const only = options.rules && options.rules.length > 0 ? new Set(options.rules) : undefined;
+    const skip = new Set(options.skipRules ?? []);
+    return (id) => (!only || only.has(id)) && !skip.has(id);
+}
+function scriptLangFor(ext) {
+    if (ext === '.ts' || ext === '.mts' || ext === '.cts')
+        return 'ts';
+    if (ext === '.tsx')
+        return 'tsx';
+    return 'jsx';
+}
+/**
+ * Scans a template given as a string (for example `template: '...'` in a
+ * component). The string is parsed behind a blank prefix of the same length
+ * as the code before it, so every location is already a file offset.
+ */
+function templateStringScanner(ctx) {
+    return (content, offset) => {
+        if (!content.includes('<'))
+            return;
+        try {
+            const padding = ctx.text.slice(0, offset).replace(/[^\r\n]/g, ' ');
+            const ast = parseTemplate(padding + content, { onError: () => undefined });
+            scanTemplate(ctx, ast);
+        }
+        catch {
+            ctx.warn('Could not parse an inline template string, skipped.');
+        }
+    };
+}
+export function analyzeFile(file, text, transitionNames, enabled) {
+    const ctx = new FileContext(file, text, enabled);
+    const ext = path.extname(file).toLowerCase();
+    try {
+        if (file === 'package.json') {
+            scanPackageJson(ctx);
+        }
+        else if (ext === '.vue') {
+            scanSfc(ctx, transitionNames, templateStringScanner(ctx));
+        }
+        else if (SCRIPT_EXTENSIONS.has(ext)) {
+            scanScript(ctx, text, {
+                offset: 0,
+                lang: scriptLangFor(ext),
+                isSfc: false,
+                emitsInput: EMITS_INPUT.test(text),
+                onTemplateString: templateStringScanner(ctx),
+            });
+        }
+        else if (STYLE_EXTENSIONS.has(ext)) {
+            scanStyle(ctx, text, 0, transitionNames);
+        }
+    }
+    catch (error) {
+        ctx.warn(`Analysis failed for this file: ${error.message}`);
+    }
+    return ctx;
+}
+export function summarize(findings, filesScanned) {
+    const byRule = new Map();
+    for (const finding of findings) {
+        const rule = RULES_BY_ID.get(finding.ruleId);
+        let entry = byRule.get(finding.ruleId);
+        if (!entry) {
+            entry = {
+                ruleId: finding.ruleId,
+                title: rule?.title ?? finding.ruleId,
+                severity: finding.severity,
+                docs: rule?.docs ?? finding.docs,
+                count: 0,
+                fixable: 0,
+            };
+            byRule.set(finding.ruleId, entry);
+        }
+        entry.count++;
+        if (finding.fixable)
+            entry.fixable++;
+    }
+    const order = new Map(RULES.map((rule, index) => [rule.id, index]));
+    const rules = [...byRule.values()].sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] ||
+        b.count - a.count ||
+        (order.get(a.ruleId) ?? 0) - (order.get(b.ruleId) ?? 0));
+    return {
+        filesScanned,
+        filesWithFindings: new Set(findings.map((f) => f.file)).size,
+        total: findings.length,
+        error: findings.filter((f) => f.severity === 'error').length,
+        warning: findings.filter((f) => f.severity === 'warning').length,
+        info: findings.filter((f) => f.severity === 'info').length,
+        fixable: findings.filter((f) => f.fixable).length,
+        byRule: rules,
+    };
+}
+/**
+ * Relative effort score. Each finding adds its rule weight (fixable findings
+ * count for a tenth, since `--fix` handles them). As a rough guide one point
+ * is about an hour of focused work, but treat it as a comparison tool.
+ */
+export function estimateEffort(findings) {
+    let total = 0;
+    for (const finding of findings) {
+        const weight = finding.effort ?? RULES_BY_ID.get(finding.ruleId)?.effort ?? 0.5;
+        total += finding.fixable ? weight / 10 : weight;
+    }
+    const score = total === 0 ? 0 : Math.max(1, Math.round(total));
+    const level = score === 0 ? 'none' : score < 8 ? 'small' : score < 40 ? 'moderate' : score < 120 ? 'large' : 'very large';
+    return { score, level };
+}
+/**
+ * Scans a Vue 2 project and returns every finding that matters for Vue 3.
+ *
+ * @example
+ * const result = await analyze('./my-app')
+ * console.log(result.summary.error, result.compat.runtime)
+ */
+export async function analyze(projectDir, options = {}) {
+    const root = path.resolve(projectDir);
+    const stat = await fs.stat(root).catch(() => undefined);
+    if (!stat?.isDirectory())
+        throw new Error(`Not a directory: ${root}`);
+    const enabled = ruleFilter(options);
+    const files = await listFiles(root, { ignore: options.ignore, gitignore: options.gitignore });
+    const texts = new Map();
+    for (const file of files)
+        texts.set(file, await fs.readFile(path.join(root, file), 'utf8'));
+    const transitionNames = new Set(['v']);
+    for (const [file, text] of texts) {
+        if (file.endsWith('.vue') || STYLE_EXTENSIONS.has(path.extname(file).toLowerCase()))
+            collectTransitionNames(text, transitionNames);
+    }
+    const findings = [];
+    const warnings = [];
+    for (const [file, text] of texts) {
+        const ctx = analyzeFile(file, text, transitionNames, enabled);
+        findings.push(...ctx.findings);
+        warnings.push(...ctx.warnings);
+    }
+    findings.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line || a.column - b.column));
+    return {
+        tool: { name: NAME, version: VERSION },
+        projectDir: root,
+        findings,
+        warnings,
+        summary: summarize(findings, files.length),
+        effort: estimateEffort(findings),
+        compat: collectCompatFlags(findings),
+    };
+}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import pc from 'picocolors';
+import { main } from './cli.js';
+main(process.argv.slice(2), {
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+    cwd: process.cwd(),
+    color: pc.isColorSupported && Boolean(process.stdout.isTTY),
+}).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    process.stderr.write(`${String(error)}\n`);
+    process.exitCode = 2;
+});

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+export interface CliIO {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    cwd: string;
+    color: boolean;
+}
+/** Runs the command line interface and returns the exit code. */
+export declare function main(argv: string[], io: CliIO): Promise<number>;