@geoql/nuxt-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 +11 -4
package/README.md CHANGED
@@ -2,33 +2,102 @@
2
2
 
3
3
  > Your agent writes bad Nuxt. This catches it.
4
4
 
5
- CLI auditor for Nuxt 4 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. Extends the `@geoql/vue-doctor` rule set with Nuxt-specific checks.
5
+ CLI auditor for Nuxt 4 apps. It runs the same hybrid scan as [`@geoql/vue-doctor`](../vue-doctor) — a template-AST pass over `@vue/compiler-sfc` plus a script pass through `oxlint` — and layers Nuxt-specific checks (hydration, server routes, Nitro, SEO, Cloudflare, data-fetching) on top, then merges everything into a deterministic 0–100 score. Built for catching the SSR and auto-import mistakes coding agents leave behind.
6
6
 
7
- ## Quickstart
7
+ ## Install
8
8
 
9
- ```bash
10
- npx -y @geoql/nuxt-doctor ./app
9
+ ```sh
10
+ # one-off, no install
11
+ npx -y @geoql/nuxt-doctor
12
+
13
+ # or add it
14
+ npm i @geoql/nuxt-doctor
11
15
  ```
12
16
 
13
- ## CLI
17
+ Published on [npm](https://www.npmjs.com/package/@geoql/nuxt-doctor) and [JSR](https://jsr.io/@geoql/nuxt-doctor) at `v0.1.0` with provenance.
18
+
19
+ ## Usage
14
20
 
21
+ ```sh
22
+ nuxt-doctor [path] [options]
15
23
  ```
16
- nuxt-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 the project and print the agent report
29
+ nuxt-doctor
30
+
31
+ # Human-readable output, fail the build on warnings
32
+ nuxt-doctor --format pretty --fail-on warn
33
+
34
+ # Machine-readable, only staged files, write to a file
35
+ nuxt-doctor --json --staged --output report.json
36
+
37
+ # Just the score, for piping into a gate
38
+ nuxt-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 nuxt-doctor/seo/lang-on-html: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
+ nuxt-doctor list-rules --category hydration
82
+ nuxt-doctor explain nuxt-doctor/nitro/compatibilityDate-set
83
+ nuxt-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
+ `nuxt-doctor` ships ~26 Nuxt rules **on top of** the full Vue rule set, 59 rules in the registry total. Nuxt categories: `structure`, `nitro`, `seo`, `cloudflare`, `server-routes`, `hydration`, `data-fetching`, `modules-deps`, and Nuxt `ai-slop`; the inherited Vue categories are `ai-slop`, `reactivity`, `composition`, `performance`, `template`, `template-perf`, `build-quality`, `deps`, `sfc`, and `dead-code`. Run `nuxt-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
+ Nuxt 4 only: the `app/` directory layout with `compatibilityVersion: 4`. For a plain Vue 3 project, use [`@geoql/vue-doctor`](../vue-doctor).
32
101
 
33
102
  ## Architecture
34
103
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@geoql/nuxt-doctor",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "private": false,
5
5
  "description": "CLI auditor for Nuxt 4 apps. Detects anti-patterns, AI-slop, and best-practice violations via @vue/compiler-sfc + oxlint. Run with `npx -y @geoql/nuxt-doctor`.",
6
6
  "keywords": [
@@ -49,12 +49,19 @@
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",
54
- "@geoql/oxlint-plugin-nuxt-doctor": "0.1.0"
52
+ "@geoql/doctor-core": "^0.1.1",
53
+ "@geoql/oxlint-plugin-nuxt-doctor": "0.1.1",
54
+ "@geoql/oxlint-plugin-vue-doctor": "0.1.1"
55
55
  },
56
56
  "devDependencies": {
57
57
  "@types/node": "^25.9.1",
58
+ "@vue/compiler-core": "^3.5.35",
59
+ "@vue/compiler-sfc": "^3.5.35",
60
+ "c12": "^4.0.0-beta.5",
61
+ "oxc-parser": "0.133.0",
62
+ "picocolors": "^1.1.1",
63
+ "semver": "^7.8.1",
64
+ "tinyglobby": "^0.2.16",
58
65
  "typescript": "^6.0.3",
59
66
  "vitest": "^4.1.7"
60
67
  },