@geoql/vue-doctor 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +86 -17
  2. package/package.json +10 -3
package/README.md CHANGED
@@ -2,33 +2,102 @@
2
2
 
3
3
  > Your agent writes bad Vue. This catches it.
4
4
 
5
- CLI auditor for Vue 3 apps. Detects anti-patterns, AI-slop, and best-practice violations via a hybrid pass over `@vue/compiler-sfc` template ASTs and `oxlint` (with its built-in `vue` plugin) for script-level rules.
5
+ CLI auditor for Vue 3 apps. It runs a hybrid scan: a template-AST pass over `@vue/compiler-sfc` plus a script pass through `oxlint` (its native `vue` plugin and the doctor JS rules), then merges the findings into a deterministic 0–100 score. Built for catching anti-patterns, AI-slop, and best-practice violations, especially the ones coding agents leave behind.
6
6
 
7
- ## Quickstart
7
+ ## Install
8
8
 
9
- ```bash
10
- npx -y @geoql/vue-doctor ./src
9
+ ```sh
10
+ # one-off, no install
11
+ npx -y @geoql/vue-doctor
12
+
13
+ # or add it
14
+ npm i @geoql/vue-doctor
11
15
  ```
12
16
 
13
- ## CLI
17
+ Published on [npm](https://www.npmjs.com/package/@geoql/vue-doctor) and [JSR](https://jsr.io/@geoql/vue-doctor) at `v0.1.0` with provenance.
18
+
19
+ ## Usage
14
20
 
21
+ ```sh
22
+ vue-doctor [path] [options]
15
23
  ```
16
- vue-doctor [path] [--format text|json] [--config doctor.config.ts] [--fail-on error|warning]
24
+
25
+ `path` defaults to the current directory. The default output format is `agent` (compact, built for LLM consumption), not a verbose human report.
26
+
27
+ ```sh
28
+ # Audit ./src and print the agent report
29
+ vue-doctor ./src
30
+
31
+ # Human-readable output, fail the build on warnings
32
+ vue-doctor --format pretty --fail-on warn
33
+
34
+ # Machine-readable, only files changed vs HEAD, write to a file
35
+ vue-doctor --json --diff --output report.json
36
+
37
+ # Just the score, for piping into a gate
38
+ vue-doctor --score
17
39
  ```
18
40
 
19
- | Flag | Description |
20
- | ----------- | -------------------------------------------------------------------------- |
21
- | `--format` | `text` (default) or `json` |
22
- | `--config` | Path to `doctor.config.ts`. Defaults to `./doctor.config.ts` if it exists. |
23
- | `--fail-on` | `error` (default) or `warning` — threshold for non-zero exit code. |
41
+ ### Options
42
+
43
+ | Flag | Description |
44
+ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
45
+ | `--format <kind>` | Output format: `agent` (default), `pretty`, `json`, `json-compact`, `sarif`, `html`. |
46
+ | `--json` | Shorthand for `--format json`. |
47
+ | `--json-compact` | Single-line JSON. |
48
+ | `--config <path>` | Path to `doctor.config.ts`. |
49
+ | `--preset <name>` | Base preset: `minimal`, `recommended`, `strict`, `all`. |
50
+ | `--fail-on <level>` | Exit non-zero at this severity or worse: `error` (default), `warn`, `none`. |
51
+ | `--quiet` | Only show the summary. |
52
+ | `--verbose` | Emit per-pass timing and rule diagnostics to stderr. |
53
+ | `--no-color` | Disable colored output. |
54
+ | `--rule <id:level>` | Override one rule, repeatable. Levels: `error`, `warn`, `info`, `off`. e.g. `--rule vue-doctor/no-em-dash-in-string:off`. |
55
+ | `--include <glob>` | Glob of files to include, repeatable. |
56
+ | `--exclude <glob>` | Glob of files to exclude, repeatable. |
57
+ | `--no-dead-code` | Skip the dead-code (knip) analysis pass. |
58
+ | `--no-lint` | Skip the lint passes (template / SFC / oxlint). |
59
+ | `--no-respect-inline-disables` | Surface findings even inside `doctor-disable` comments. |
60
+ | `--threshold <n>` | Minimum passing score, integer `0`–`100`. |
61
+ | `--score` | Print only the numeric score, for piping. |
62
+ | `--annotations` | Emit GitHub Actions `::error::` / `::warning::` lines. |
63
+ | `--ci` | Auto-enable CI behavior (annotations on GitHub Actions). |
64
+ | `--no-ci` | Disable CI auto-detection even when a CI env is set. |
65
+ | `--diff` | Only report findings in files changed vs HEAD. |
66
+ | `--staged` | Only report findings in staged files. |
67
+ | `--full` | Force a complete scan, overriding `--diff` / `--staged`. |
68
+ | `--output <file>` | Write the report to a file instead of stdout. |
69
+
70
+ Severity is `error | warn | info` everywhere. `--diff`/`--staged`, `--verbose`/`--quiet`, and `--score`/`--json` are mutually exclusive.
71
+
72
+ ### Subcommands
73
+
74
+ | Command | Description |
75
+ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
76
+ | `list-rules` | List every registered rule with id, severity, category, source, and preset membership. Filters: `--preset <recommended\|all>`, `--category <name>`, `--source <doctor\|oxlint-builtin\|eslint-plugin-vue>`, `--severity <error\|warn\|info>`, `--json`, `--json-compact`. |
77
+ | `explain <ruleId>` | Print a rule's severity, category, recommendation, and help URL. `--json` for structured output. |
78
+ | `inspect [dir]` | Print the detected project capabilities doctor uses to gate rules. `--json` / `--json-compact`. |
79
+
80
+ ```sh
81
+ vue-doctor list-rules --category ai-slop
82
+ vue-doctor explain vue-doctor/no-em-dash-in-string
83
+ vue-doctor inspect --json
84
+ ```
85
+
86
+ ### Exit codes
87
+
88
+ | Code | Meaning |
89
+ | ---- | ----------------------------------------------------------------------------------------- |
90
+ | `0` | Clean, or score at/above `--threshold` and no findings at/above `--fail-on`. |
91
+ | `1` | Findings at/above the `--fail-on` level (default: `error`), or score below `--threshold`. |
92
+ | `2` | Configuration error or scan failure. |
93
+
94
+ ## Rules
95
+
96
+ `vue-doctor` ships ~24 Vue rules plus oxlint's native `vue` built-ins, grouped by category: `ai-slop`, `reactivity`, `composition`, `performance`, `template`, `template-perf`, `build-quality`, `deps`, `sfc`, and `dead-code`. Run `vue-doctor list-rules` for the live list. Most are on in the `recommended` preset.
24
97
 
25
- Exit codes:
98
+ ## Scope
26
99
 
27
- | Code | Meaning |
28
- | ---- | ------------------------------------------------------------ |
29
- | 0 | No findings at/above `--fail-on` threshold (default: error). |
30
- | 1 | Findings at/above threshold. |
31
- | 2 | Configuration error or scan failure. |
100
+ Vue 3 only. For Nuxt 4 projects, use [`@geoql/nuxt-doctor`](../nuxt-doctor), which layers Nuxt rules on top of this set.
32
101
 
33
102
  ## Architecture
34
103
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@geoql/vue-doctor",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "private": false,
5
5
  "description": "CLI auditor for Vue 3 apps. Detects anti-patterns, AI-slop, and best-practice violations via @vue/compiler-sfc + oxlint. Run with `npx -y @geoql/vue-doctor`.",
6
6
  "keywords": [
@@ -49,11 +49,18 @@
49
49
  "cac": "^7.0.0",
50
50
  "kolorist": "^1.8.0",
51
51
  "oxlint": "^1.67.0",
52
- "@geoql/doctor-core": "^0.1.0",
53
- "@geoql/oxlint-plugin-vue-doctor": "0.1.0"
52
+ "@geoql/doctor-core": "^0.1.1",
53
+ "@geoql/oxlint-plugin-vue-doctor": "0.1.1"
54
54
  },
55
55
  "devDependencies": {
56
56
  "@types/node": "^25.9.1",
57
+ "@vue/compiler-core": "^3.5.35",
58
+ "@vue/compiler-sfc": "^3.5.35",
59
+ "c12": "^4.0.0-beta.5",
60
+ "oxc-parser": "0.133.0",
61
+ "picocolors": "^1.1.1",
62
+ "semver": "^7.8.1",
63
+ "tinyglobby": "^0.2.16",
57
64
  "typescript": "^6.0.3",
58
65
  "vitest": "^4.1.7"
59
66
  },