the-doctor.report v0

Quickstart

Run the doctor, read the score, and triage the first finding.

First run

From the root of any Vue 3 or Nuxt 4 project:

~/your-project
npx -y @geoql/vue-doctor

The doctor will:

  1. Detect your project layout (vue vs nuxt, the app/ and server/ directories, monorepo workspaces, and the usual auto-imports).
  2. Run the audit. Most projects complete in under a second.
  3. Write a markdown report plus a SARIF artifact to .doctor/.
  4. Print a one-line summary to stdout (the agent reporter).

A typical first run looks like this:

~/your-project
$ npx -y @geoql/vue-doctor
[email protected]  ·  scanning 124 files  ·  0 errors, 4 warns, 12 info
.score 88.0  ·  grade B  ·  0.42s

Reading the score

The score is a single integer from 0 to 100 plus a letter grade (A ≥ 95, B ≥ 85, C ≥ 70, D ≥ 50, F < 50). It's deterministic: the same diff on the same ruleset always produces the same number.

The number is computed from a √-decay over the findings:

  • error deducts 5
  • warn deducts 2
  • info deducts 0.5

Repeats of the same rule are damped by 1/√(i+1) so a single em-dash on every page of a 200-file repo doesn't tank the score, but a 200-file repo with 200 different rules firing is a real problem. The full formula lives in Scoring — how the score is computed.

Reading the report

The markdown report (.doctor/report.md) has four sections:

  1. Summary — the score, file count, rule counts per severity, and a per-rule breakdown.
  2. Diagnostics — every finding with file, line, column, rule id, severity, and the suggested fix.
  3. Source profile — Vue version, Nuxt version, capabilities detected, monorepo layout.
  4. Timings — per-phase time spent (template AST, oxlint subprocess, scoring, reporter).

The SARIF artifact is the same data, in the GitHub code-scanning format. Wire it into your CI to get inline PR annotations.

Triage the first finding

The first thing most people see is no-em-dash-in-str — the doctor flags em-dashes (—) in string literals because the AI agents emitting them are almost always trying to look polished instead of being correct. It's a stylistic tell, not a bug.

To silence it project-wide, add it to your doctor.config.ts:

doctor.config.ts
import { defineConfig } from '@geoql/doctor-core';

export default defineConfig({
  rules: {
    'no-em-dash-in-str': 'off',
  },
});

To silence it for a single line, use the inline disable:

vue
// vue-doctor-disable-next-line no-em-dash-in-str const summary =
'Auto-generated — review before merging';

Inline disables are picked up by the respect-inline-disables flag (--respect-inline-disables on the CLI, respectInlineDisables: true in the config). The default is false so you don't accidentally ship a // doctor-disable-next-line that no one is reviewing.

Next: CI

Once the first run is clean locally, wire it into CI. The next section walks through GitHub Actions, GitLab CI, and the composite actions.