---
title: "Extending Doctor"
description: "Write custom Rules, ship them with a Vite plugin or Nuxt module, and test them."
canonical_url: "https://vite-doctor.onmax.me/extending"
---
# Extending Doctor

> Write custom Rules, ship them with a Vite plugin or Nuxt module, and test them.

A Doctor Extension adds Rule Packs to a Doctor Run. A Rule Pack groups Rules, Presets, and the Diagnostic Codes those Rules emit. Use extensions for project-specific policies, or ship them with a library so its users get the library's diagnostics automatically.

Authoring APIs come from `vite-doctor/extension`. Test helpers come from `vite-doctor/testkit`.

## Published extensions

[`comark-linter`](https://comark-ui.onmax.me/lint/vite-doctor/) checks [Comark](https://comark.dev) Markdown documents for unclosed blocks, unknown components, broken links and anchors, and plugin issues. Its Rule Pack reports `COMARK` Diagnostic Codes, and each [Comark UI](https://comark-ui.onmax.me) package adds Rules for its own plugin. Register it in `doctor.config.ts`, add its preset next to `auto`, and pass `--config`:

```ts [doctor.config.ts]
import comark from "comark-linter/doctor";
import { defineDoctorConfig } from "vite-doctor/config";

export default defineDoctorConfig({
  extends: ["auto", "comark/recommended"],
  extensions: [comark()],
});
```

```bash
pnpm add -D vite-doctor comark-linter
pnpm vite-doctor . --config doctor.config.ts
```

See the [Comark UI guide](https://comark-ui.onmax.me/lint/vite-doctor/) for its options and the [list of Comark Diagnostic Codes](https://comark-ui.onmax.me/doctor/).

## Write a Doctor Extension

This file defines one Rule, its Diagnostic Code, a Rule Pack, and the extension that registers the pack:

```ts [doctor/extension.ts]
import {
  createRule,
  defineDoctorDiagnostics,
  defineDoctorExtension,
  defineRulePack,
} from "vite-doctor/extension";

export const acmeDiagnostics = defineDoctorDiagnostics(
  [{ code: "ACME0001", ruleId: "acme/no-legacy-client" }],
  { docsBase: "https://acme.dev/doctor" },
);

export const noLegacyClient = createRule({
  meta: {
    id: "acme/no-legacy-client",
    title: "Use the current Acme client",
    category: "correctness",
    severity: "warn",
    confidence: "proven",
    prefilter: { imports: ["acme/legacy"] },
  },
  create(ctx) {
    return {
      ImportDeclaration(node) {
        if (node.source.value !== "acme/legacy") return;
        ctx.report(
          acmeDiagnostics.diagnostics.ACME0001({
            why: "`acme/legacy` is removed in Acme 3.",
            fix: "Import `createClient` from `acme` instead.",
          }),
          { range: ctx.range(node) },
        );
      },
    };
  },
});

export const acmeRulePack = defineRulePack({
  name: "acme",
  version: "1.0.0",
  rules: [noLegacyClient],
  diagnostics: acmeDiagnostics,
  presets: { recommended: ["acme/no-legacy-client"] },
});

export default defineDoctorExtension({ name: "acme", rulePacks: [acmeRulePack] });
```

`ctx.report` takes a diagnostic created by a code handle. Every diagnostic needs `why` and `fix`. The second argument is optional: `ruleId`, `severity`, `category`, and `confidence` default to the Rule's `meta`, and you can add `range`, `file`, `evidence`, or a structured `fix` edit plan.

`meta.confidence` says how far agents can trust the Rule's Diagnostics, from the evidence the Rule actually reads. Use `proven` when the finding follows from syntax alone, `type-backed`, `manifest-backed`, or `runtime-backed` only when type information, package manifests and framework inventory, or Runtime Evidence decides the finding, and `heuristic-high`, `heuristic-medium`, or `heuristic-low` for everything else, such as name conventions, text matching, or an execution context the Rule cannot see. Pass `confidence` to `ctx.report` when one branch of a Rule is stronger or weaker than the rest. Doctor adds no confidence or evidence of its own: a Diagnostic without either reports none, and the text report counts it as undeclared.

### Visit script nodes

`create(ctx)` returns visitors keyed by ESTree node type, the same shape ESLint and oxlint use. Doctor walks each file's script once and calls a visitor only for nodes of its type. Add `:exit` to run after the node's children. This Rule reports every `createClient()` call after the first one in a module, with `ACME0002` registered next to `ACME0001`:

```ts [doctor/extension.ts]
import { createRule, type ScriptAstNodeOf } from "vite-doctor/extension";

export const singleClient = createRule({
  meta: {
    id: "acme/single-client",
    title: "Create one Acme client per module",
    category: "correctness",
    severity: "warn",
    prefilter: { calls: ["createClient"] },
  },
  create(ctx) {
    const clients: ScriptAstNodeOf<"CallExpression">[] = [];
    return {
      CallExpression(node) {
        if (node.callee.type === "Identifier" && node.callee.name === "createClient") {
          clients.push(node);
        }
      },
      "Program:exit"() {
        for (const node of clients.slice(1)) {
          ctx.report(
            acmeDiagnostics.diagnostics.ACME0002({
              why: "Each client opens its own connection pool.",
              fix: "Reuse the first client in this module.",
            }),
            { range: ctx.range(node) },
          );
        }
      },
    };
  },
});
```

Each visitor's `node` parameter is typed for its key: `CallExpression(node)` receives a `CallExpression`. Script ASTs come from [oxc-parser](https://oxc.rs/docs/guide/usage/parser), so the node types match its ESTree output, including TypeScript and JSX nodes. To type a helper, use `ScriptAstNodeOf<"CallExpression">` or the `ScriptAstNode` union from `vite-doctor/extension`. Vue SFC Rules can also use the `SFC` hook and template visitors.

Doctor links script parents before any visitor runs. Visitors must treat the AST as read-only.

### Visit template nodes

For Vue SFCs, return a `template` object with visitors keyed by node kind: `root`, `element`, `attribute`, `directive`, `text`, `interpolation`, and `comment`. Doctor walks the `<template>` AST that `@vue/compiler-sfc` builds when it parses the SFC, so template visitors add no parse of their own. This Rule reports `<AcmeImage>` elements without alt text and `:src` bindings to plain `http:` URLs, with `ACME0003` and `ACME0004` registered for `acme/image`:

```ts [doctor/extension.ts]
export const acmeImage = createRule({
  meta: {
    id: "acme/image",
    title: "Use accessible, secure Acme images",
    category: "a11y",
    severity: "warn",
  },
  create(ctx) {
    return {
      template: {
        element(node) {
          if (node.tag !== "AcmeImage") return;
          if (
            ctx.helpers.hasVueAttribute(node, "alt") ||
            ctx.helpers.hasVueDirective(node, "bind", "alt")
          )
            return;
          ctx.report(
            acmeDiagnostics.diagnostics.ACME0003({
              why: "Screen readers announce an image without alt text by its file name.",
              fix: 'Add alt text, or alt="" for a decorative image.',
            }),
            { range: ctx.range(node) },
          );
        },
        directive(node, element) {
          if (element.tag !== "AcmeImage" || node.name !== "bind" || node.arg?.content !== "src")
            return;
          const expression = node.exp && ctx.helpers.parseTemplateExpression(node.exp);
          if (expression?.type !== "Literal" || !String(expression.value).startsWith("http:"))
            return;
          ctx.report(
            acmeDiagnostics.diagnostics.ACME0004({
              why: "An http: image on an https: page is mixed content that browsers upgrade or block.",
              fix: "Serve the image over https:.",
            }),
            { range: ctx.range(expression) },
          );
        },
      },
    };
  },
});
```

Nodes are the compiler-dom nodes Vue's compiler produces, typed as `TemplateElementNode`, `TemplateDirectiveNode`, and so on in `vite-doctor/extension`:

- Each visitor receives the node and its parent. `attribute` and `directive` receive the element they belong to; other kinds receive their parent element or the template root.
- An element's attributes and directives are visited in source order before its children. `"element:exit"` and the other `:exit` keys run after a node's props and children, so a Rule can track ancestors with a counter or stack.
- `element.tag` is the tag as written, such as `button`, `NuxtLink`, or `router-view`. `element.props` holds static attributes (`type: 6`) and directives (`type: 7`).
- Directive shorthands are normalized: `:href`, `@click`, and `#default` have `name` `bind`, `on`, and `slot`, and a static argument in `arg.content`. `rawName` keeps the attribute name as written.
- A static attribute value is `attribute.value?.content`. Directive values and interpolations are strings in `exp.content`. `ctx.helpers.parseTemplateExpression(exp)` parses one with oxc on first use, shares the result with every Rule, and returns `null` for a whole `v-for` (parse `forParseResult.source`), `v-slot` parameters, and `v-on` handlers with several statements.
- Template nodes and parsed expressions carry SFC offsets, so `ctx.range(node)` points at the source. `ctx.file.templateAst` is the root, for Rules that need the whole template in `create(ctx)`.

Template visitors do not run on `<template src>` or on templates with a non-HTML `lang`, such as Pug.

### Skip files that cannot match

`meta.prefilter` skips a Rule on files that cannot produce its Diagnostics. Doctor does not call `create(ctx)` for those files. A Rule runs on a file when any listed signal is present:

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Matches
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        calls
      </code>
    </td>
    
    <td>
      Call expressions by callee name, such as <code>
        useFetch
      </code>
      
       or <code>
        Math.random
      </code>
      
      . <code>
        new
      </code>
      
       expressions do not count.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        imports
      </code>
    </td>
    
    <td>
      Static <code>
        import
      </code>
      
       declarations by exact source, such as <code>
        acme/legacy
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        names
      </code>
    </td>
    
    <td>
      Names the file text could spell, including through escape sequences. Use it for aliases and reads.
    </td>
  </tr>
</tbody>
</table>

List every signal your Rule reports from. If a Rule also reports from `create(ctx)`, `SFC`, or template visitors, or follows aliases such as `const load = createClient`, a `calls` prefilter can hide real Diagnostics; use `names` or omit the prefilter.

Rule Packs without `activation` run their `recommended` Preset whenever the extension is registered. Define an optional `strict` Preset for noisier or opinionated Rules: `extends: "strict"` and `--strict` select it for every activated Rule Pack and fall back to `recommended` when a pack has none. Set `activation: { packages: ["acme"] }` to run only when the project depends on `acme`, `activation: { frameworks: ["vue", "nuxt"] }` to run only for Vue or Nuxt packages, or `activation: false` to require an explicit `extends: ["auto", "acme/recommended"]`.

### Diagnostic Codes

A Diagnostic Code is a package-owned uppercase prefix followed by four digits, such as `ACME0001`. Pick a prefix that belongs to your package and never reuse a code.

- Built-in prefixes are reserved: `DOC`, `MCP`, `NITRO`, `NUXT`, `PINIA`, `PKG`, `SHAD`, `TS`, `VITE`, and `VUE`. Using them fails with `DOC0028`. A code that does not match the format fails with `DOC0027`.
- Two Rule Packs in the same Doctor Run cannot declare the same code (`DOC0012`).
- `docsBase` produces `https://acme.dev/doctor/ACME0001`. Pass a function to build another URL shape, or set `docs` on one entry to override or opt out with `false`. Without either, the code has no docs URL. Doctor does not link third-party codes to its own Diagnostic Reference.

Attach the registry as the Rule Pack's `diagnostics` so `vite-doctor rules` and `vite-doctor explain ACME0001` list the codes and their docs URLs.

## Add a project Rule

Keep project-only Rules in your repository and register the extension where you run Doctor.

With the CLI, load executable config explicitly:

```ts [doctor.config.ts]
import { defineDoctorConfig } from "vite-doctor/config";
import acme from "./doctor/extension";

export default defineDoctorConfig({
  extensions: [acme],
});
```

```bash
pnpm vite-doctor . --config doctor.config.ts
pnpm vite-doctor explain ACME0001 --config doctor.config.ts
```

With the Vite plugin, pass the extension in `vite.config.ts`:

```ts [vite.config.ts]
import { doctor } from "vite-doctor";
import { defineConfig } from "vite";
import acme from "./doctor/extension";

export default defineConfig({
  plugins: [doctor({ extensions: [acme] })],
});
```

In a Nuxt app, register it from a local module the same way a library does. See [Ship Rules with a Nuxt module](#ship-rules-with-a-nuxt-module).

## Ship Rules with a Vite plugin

A Vite plugin can expose Doctor Extensions as `api.doctor`. The `doctor()` plugin reads `api.doctor.extensions` from every plugin in the resolved Vite config, so users who install your plugin get your Rules with no extra setup:

```ts [src/vite.ts]
import type { Plugin } from "vite";
import type { DoctorPluginApi } from "vite-doctor/extension";

export function acme(): Plugin {
  return {
    name: "acme",
    api: {
      doctor: {
        extensions: [() => import("./doctor.js")],
      } satisfies DoctorPluginApi,
    },
  };
}
```

```ts [vite.config.ts]
import { acme } from "acme/vite";
import { doctor } from "vite-doctor";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [acme(), doctor()],
});
```

An entry can be a Doctor Extension, or a loader that returns one or a module with a default export. Use a loader so your plugin imports Doctor code only during a Doctor Run. Then `vite-doctor` can stay an optional peer dependency:

```json [package.json]
{
  "exports": {
    "./doctor": "./dist/doctor.mjs"
  },
  "peerDependencies": { "vite-doctor": "*" },
  "peerDependenciesMeta": { "vite-doctor": { "optional": true } }
}
```

The type import is erased at build time. If your package already depends on `vite-doctor` at runtime, `defineDoctorPluginApi({ extensions })` from `vite-doctor/extension` gives the same typing.

## Ship Rules with a Nuxt module

A Nuxt module registers extension entry modules through the `doctor:extendExtensions` hook. Push a path, `file:` URL, or package specifier. The entry's default export must be a Doctor Extension:

```ts [src/module.ts]
import { createResolver, defineNuxtModule } from "@nuxt/kit";
import type {} from "vite-doctor/nuxt";

export default defineNuxtModule({
  meta: { name: "acme" },
  setup(_options, nuxt) {
    const { resolve } = createResolver(import.meta.url);
    nuxt.hook("doctor:extendExtensions", (entries) => {
      entries.push(resolve("./doctor"));
    });
  },
});
```

The `import type {} from "vite-doctor/nuxt"` line loads the hook types and is erased at build time. When `vite-doctor/nuxt` is not installed, the hook never runs.

Users add both modules and run the Nuxt Doctor Command:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ["acme", "vite-doctor/nuxt"],
});
```

```bash
pnpm nuxt prepare
pnpm nuxt doctor
```

The Nuxt 4 Bridge resolves each entry to an absolute file and records it in `.nuxt/doctor.manifest.json` during `nuxt dev`, `nuxt build`, and `nuxt prepare`. `nuxt doctor` loads recorded entries because it is a Nuxt host command, and running it is the same trust decision as `nuxt dev`. The standalone CLI does not run host-registered code unless you pass `--host-extensions`. On Nuxt 4.1 to 4.5, where `nuxt doctor` exits `0` whatever Doctor finds, use that flag in CI:

```bash
pnpm vite-doctor . --host-extensions --max-warnings 0
```

Doctor loads entries with Node's native `import()`. Publish built JavaScript. For a local module in your app, keep the entry outside `modules/`, because Nuxt registers every file there as a module. A TypeScript entry works when Node can strip its types and its relative imports include file extensions. If an entry fails to load or its default export is not a Doctor Extension, the run stops with `DOC0029`. Rebuild the package and run `nuxt prepare` again.

A package that ships both a Vite plugin and a Nuxt module can point both contracts at the same `./doctor` entry.

## Test a Rule

`vite-doctor/testkit` writes fixture files to a temporary project, runs Doctor with only the Rules you pass, and returns the Doctor Run result:

```ts [doctor/extension.test.ts]
import { expect, test } from "vitest";
import { runProjectFixture, runRuleFixture } from "vite-doctor/testkit";
import acme, { noLegacyClient } from "./extension";

test("reports legacy client imports", async () => {
  const result = await runRuleFixture({
    rule: noLegacyClient,
    framework: "vite",
    files: { "src/client.ts": 'import { createClient } from "acme/legacy";\n' },
  });
  expect(result.diagnostics.map((diagnostic) => diagnostic.code)).toEqual(["ACME0001"]);
});

test("runs the published extension", async () => {
  const result = await runProjectFixture({
    framework: "vite",
    extensions: [acme],
    files: { "src/client.ts": 'import { createClient } from "acme";\n' },
  });
  expect(result.diagnostics).toEqual([]);
});
```

`framework` defaults to `vue` and accepts `vite`, `vue`, `nitro`, or `nuxt`. Pass `dependencies` to add entries to the generated `package.json`. Use `config` and `run` for Doctor config and Doctor Run options such as `extends`. Fixture projects are temporary, so the rule cache stays in memory unless you pass `run: { cache: true }`.

### Share a fixture project

`runRuleFixture` and `runProjectFixture` write a new project and detect its Project Inventory on every call. Most Rule tests change one source file, so `createProjectFixture` writes the project and detects its inventory once, then reuses both for every run:

```ts [doctor/extension.test.ts]
import { afterAll, expect, test } from "vitest";
import { createProjectFixture } from "vite-doctor/testkit";
import { noLegacyClient } from "./extension";

const project = createProjectFixture({ framework: "nuxt", files: { "app/.gitkeep": "" } });
afterAll(() => project.dispose());

test.each(["acme/legacy", "acme/legacy/client"])("reports %s", async (entry) => {
  const result = await project.run({
    rule: noLegacyClient,
    files: { "app/pages/index.vue": `<script setup>import "${entry}"</script>` },
  });
  expect(result.diagnostics.map((diagnostic) => diagnostic.code)).toEqual(["ACME0001"]);
});
```

`createProjectFixture` takes `framework`, `dependencies`, and `files`. Its files stay on disk for every run. `run` takes `rule` or `rules`, `extensions`, `config`, and `run` like `runProjectFixture`, adds its own `files`, runs Doctor on the whole project, and deletes its files before the next run starts. Runs on one fixture project never overlap.

The Project Inventory comes from the fixture project's own files, so run files cannot change it. Put files that shape it in `createProjectFixture`: dependencies, `nuxt.config.ts`, `tsconfig.json`, Nuxt `server/` routes, or the Nuxt `app/` directory, which `app/.gitkeep` creates without adding a source file. When a test needs its own inventory, use `runRuleFixture` or a separate fixture project. A run file that would replace a fixture project file throws. Call `dispose()` in `afterAll` to delete the fixture project.

## How surfaces find extensions

<table>
<thead>
  <tr>
    <th>
      Surface
    </th>
    
    <th>
      Registered extensions
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        doctor()
      </code>
      
       Vite plugin
    </td>
    
    <td>
      <code>
        extensions
      </code>
      
       option, then <code>
        api.doctor.extensions
      </code>
      
       from other Vite plugins
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        nuxt doctor
      </code>
    </td>
    
    <td>
      <code>
        doctor:extendExtensions
      </code>
      
       entries recorded by <code>
        vite-doctor/nuxt
      </code>
      
      , plus <code>
        --config
      </code>
      
       extensions
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        vite-doctor
      </code>
      
       CLI
    </td>
    
    <td>
      <code>
        --config
      </code>
      
       extensions, plus recorded Nuxt entries with <code>
        --host-extensions
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        vite-doctor/testkit
      </code>
    </td>
    
    <td>
      <code>
        rules
      </code>
      
       and <code>
        extensions
      </code>
      
       passed to the fixture
    </td>
  </tr>
</tbody>
</table>

The CLI cannot see extensions from Vite plugins in `vite.config.ts`, because it does not load host config. Run those through the Vite plugin, or register the same extension in `doctor.config.ts` and pass `--config`.

The extension `name` is its identity. If the same name is registered more than once, Doctor keeps the first registration. You can register an extension explicitly while a plugin also contributes it, and its Rules still run once.

## Rule inputs

A Rule reads its file through `ctx.file` and Project Inventory through `ctx.project`. Any other file, directory listing, or path check goes through `ctx.fs`:

```ts
const isRecord = (value: unknown): value is Record<string, unknown> =>
  typeof value === "object" && value !== null && !Array.isArray(value);

create(ctx) {
  const pkg = ctx.fs.readJson("package.json");
  if (!isRecord(pkg) || !isRecord(pkg.dependencies) || !pkg.dependencies.acme) return;
  const config = ctx.fs.readText("acme.config.ts");
  // ...
}
```

`ctx.fs` offers `readText`, `readJson`, `exists`, `stat`, `readDir`, `readDirRecursive`, `realpath`, and `glob`. Relative paths resolve from the project root, and missing files return `undefined` instead of throwing. `readJson` returns `unknown`, so validate the value before using it. Doctor records every read as an input of the Rule, so do not import `node:fs` or read `process.env` in Rule code; built-in Rule Packs enforce this with a lint rule.

`ctx.cache` is memory shared by all Rules for one Doctor Run. A value remembered with `ctx.cache.set` carries the `ctx.fs` reads made since the matching `ctx.cache.get` missed, so another Rule that reuses it depends on the same inputs. Derive cached values only from the key, `ctx.fs`, and `ctx.project`, never from the current file.

Doctor caches each Rule's Diagnostics per file between runs and replays them while the file, the Project Inventory, the Rule config, and every input the Rule read are unchanged. The cache key includes the Rule Pack `name` and `version`, the Rule's `meta` (prefilter included), and the source of its `create` function, so bump the Rule Pack version when a Rule's helpers change. Set `meta.cacheScope: "none"` for a Rule that reads anything `ctx.fs` cannot see, and `meta.determinism: "env-dependent"` or `"runtime-dependent"` for a Rule whose result depends on the environment or a network call. Doctor runs those Rules every time. A Rule that changes Project Inventory, such as adding evidence gaps, is not cached either.

## Report scope

A file Rule reports Diagnostics into the file it analyzes: the reported `file` and every `related` location must be `ctx.file.path`. That is the default `meta.reportScope: "file"`, and Doctor enforces it. A file Rule that reports anywhere else stops the Doctor Run with `DOC0030`, naming the Rule, the analyzed file, and the other file. Evidence `file` entries are not report locations and are not checked.

A file Rule that does report into other files, for example on the module an import resolves to, declares it:

```ts
createRule({
  meta: {
    id: "acme/imported-legacy",
    title: "Legacy module",
    category: "imports",
    severity: "warn",
    reportScope: "project",
  },
  create(ctx) {
    // ...
    ctx.report(diagnostics.ACME0002(), {
      file: target,
      related: [{ file: ctx.file.path, message: "Imported here" }],
    });
  },
});
```

Manifest and workspace Rules (`execution: "manifest"` or `"workspace"`) report on the project and are always project-scoped; `reportScope` does not apply to them and they are never checked.

## Activation scope

In a workspace, an activated Rule Pack runs its Rules on the files of the workspace packages that activate it. A Rule about integration code, such as a Vite plugin or Nuxt module that registers Nitro handlers for an app elsewhere, declares `meta.activationScope: "workspace"` to check every workspace package once its Rule Pack activates for any of them.

The scope decides what a `--changed` run analyzes. Diagnostics of a file-scoped Rule can only land in the file it analyzed, so `--changed` runs file-scoped Rules on changed files only, and does not even parse unchanged files unless something needs them. Project-scoped file Rules, manifest Rules, workspace Rules, and `--analyses` still see the whole project. Either way the report equals a full run filtered to the changed lines, so declare `"project"` whenever a Rule can report outside its file; a Rule that is wrongly left file-scoped fails with `DOC0030` on any run that reaches the offending report. The `affectedFiles` run option scopes a run the same way to whole files instead of changed lines; the Vite Plugin Surface passes the files a dev server saw saved.

## Test files

Doctor skips test code by default, so framework Rules don't misfire on mocks and test setup. Test code means files in `test`, `tests`, `__tests__` and `test-utils` folders, and `*.test.*` and `*.spec.*` files. A file Rule about source text that applies to tests as well, such as a policy on comments or naming, declares `meta.includeTestFiles: true`:

```ts
createRule({
  meta: {
    id: "acme/no-banned-words",
    title: "Banned words",
    category: "style",
    severity: "info",
    includeTestFiles: true,
  },
  create(ctx) {
    // runs on src/foo.ts, src/foo.test.ts and tests/setup.ts
  },
});
```

Only Rules that declare it run on test files. Doctor reads and parses test files only when such a Rule is enabled in the run, so a run without one does the same work as before. Test files never reach other Rules, Project Inventory, the workspace graph, or `--analyses`, and `ctx.inventory.sourcePaths()` does not list them. Fixtures, `__snapshots__`, type-test folders such as `test-d`, test files inside Nuxt module sources, and paths the user excludes through `exclude` or `.gitignore` stay skipped. Overrides, `doctor-disable` directives, `--changed`, `--rules`, baselines, and the analysis cache work on test files as on other files. In the report, `scope.files` counts a test file only when such a Rule analyzed it. Manifest and workspace Rules ignore the field.

`runRuleFixture`, `runProjectFixture` and `createProjectFixture` in `vite-doctor/testkit` run Rules through the same path, so a fixture file such as `src/foo.test.ts` reaches a Rule that declares `includeTestFiles` and no other.

## File Rule execution contract

File Rules run one file at a time. For each file, Doctor skips Rules whose
`meta.prefilter` cannot match, awaits every remaining Rule's `create(ctx)` in
enabled-rule order, then awaits every `SFC` hook in that order. It walks the
script once in depth-first order. On entering a node it calls each Rule's
visitor for that node type, in Rule order; after the node's children it calls
the `:exit` visitors the same way. The template walk follows with the same
enter and exit order, using each Rule's `template` visitors. All callbacks for
one file finish before the next file's `create()`. Diagnostics appear in Rule
order, then file order.

Custom Rule Packs that coordinate through shared module state or `ctx.cache`
must not assume an earlier Rule has finished its callbacks when their `create()`
runs. Use caches for reusable facts, not to sequence Rules.

The catch-all `ScriptNode` hook was removed. Move its body into visitors for
the node types it checked, for example `ScriptNode(node) { if (node.type !== "CallExpression") return; ... }` becomes `CallExpression(node) { ... }`.

Doctor checks every visitor a Rule's `create()` returns, including when its
hooks differ between files. A hook Doctor never calls stops the run with
`DOC0034`, naming the Rule and
the hook: a removed hook such as `ScriptNode` or `TemplateNode`, a misspelled
node type such as `CallExpresion` (Doctor suggests the closest hook), a
`template` key other than a template node kind, a lifecycle hook on a file
Rule, or a node visitor on a workspace or manifest Rule. Script hooks are the
node types oxc-parser's visitor keys list, so a type that never appears as a
child of another node, such as `Hashbang`, is rejected too.

The catch-all `TemplateNode` hook was removed too, along with the
vue-eslint-parser node shapes it received. `node.type === "VElement"` becomes
`template: { element(node) {} }`, `rawName` becomes `tag`,
`startTag.attributes` becomes `props`, a directive's `key.name.name` and
`key.argument.name` become `name` and `arg.content`, a static
`value.value` becomes `value.content`, `value.expression` becomes
`ctx.helpers.parseTemplateExpression(exp)`, and `parent` chains become
`element` and `"element:exit"` visitors.

Treat SFC, script and template ASTs as read-only. Script parent links are complete
before script callbacks run, and both traversals are snapshotted before
callbacks: replacing or removing children does not remove their queued visits,
and inserted children are not visited. This also applies to the single-visitor
runner. AST mutations are unsupported; no mutation behavior is guaranteed across
Rules. Keep analysis state outside the AST.


## Sitemap

See the full [sitemap](https://vite-doctor.onmax.me/sitemap.md) for all pages.
