TypeScript

Run evidence and boundary diagnostics automatically in every TypeScript project.

Vite Doctor activates its TypeScript rules automatically when the project contains a tsconfig.json or TypeScript source files. The recommended preset focuses on unsafe type claims and unvalidated runtime data.

Install

Add Vite Doctor to any TypeScript project:

pnpm add -D vite-doctor

Run Doctor from the project root:

pnpm vite-doctor .

No framework option or TypeScript-specific configuration is required. JavaScript-only projects do not activate these rules.

Use the strict preset

The strict preset adds opinionated checks for runtime narrowing, conditional object spreads, and undocumented type assertions:

pnpm vite-doctor . --extends auto,vite-doctor/typescript/strict

It runs every TypeScript rule except opt-in policy rules such as typescript/strict/no-comments, which only a rules entry turns on.

Delete comments no tool reads

typescript/strict/no-comments (TS0017) reports comments that do not match a known directive or an allowed comment pattern. Comments that repeat the code can go stale when the code changes, and agents may read them as facts. The rule is opt-in: no preset turns it on, strict included. Name it in doctor.config.json:

doctor.config.json
{
  "rules": {
    "typescript/strict/no-comments": [
      "warn",
      {
        "allow": ["^\\s*provider-message-match:", "^\\s*@generated-by\\b"],
        "apiDocs": "exported"
      }
    ]
  }
}

When an agent adds Doctor to a project with the Doctor skill, the skill turns this rule on at warn in the project's Doctor config and tells you how to turn it off. To turn it off, set "typescript/strict/no-comments": "off" or delete the entry. Doctor itself never turns the rule on: the same repository reports the same Diagnostics for an agent, a person, and CI.

It checks comments in .ts, .tsx, .js, .jsx, .mjs, and .cjs files, in both <script> blocks of a Vue component, in Vue templates, and in JSX, including JavaScript-only projects. It also checks test code, which other Rules skip: files in test, tests, __tests__, and test-utils folders, and *.test.* and *.spec.* files. It does not check <style> blocks or the other files Doctor does not scan, such as fixtures, snapshots, and generated files.

To keep comments in tests, turn the rule off for them with overrides:

doctor.config.json
{
  "rules": { "typescript/strict/no-comments": "warn" },
  "overrides": [
    {
      "files": [
        "**/{test,tests,__tests__,test-utils}/**",
        "**/*.{test,spec}.{ts,tsx,mts,cts,js,jsx,mjs,cjs,vue}"
      ],
      "rules": { "typescript/strict/no-comments": "off" }
    }
  ]
}

What the rule keeps

The rule recognizes these common exemptions:

  • compiler, linter, formatter, and coverage directives: @ts-, eslint, /* global */, /* exported */, oxlint-, Doctor inline suppressions, prettier-ignore, oxfmt-ignore, dprint-ignore, biome-ignore, v8 ignore, c8 ignore, istanbul ignore, @vitest-environment, @jest-environment, and @jsx pragmas;
  • bundler annotations: #__PURE__, #__NO_SIDE_EFFECTS__, @vite-ignore, and webpack magic comments;
  • triple-slash references, /*! banners, @license and @preserve comments, source map comments, and the #! line;
  • SAFETY notes and the comments that directly continue them, in any form that typescript/strict/require-safety-comment-for-type-assertion (TS0008) accepts, so the two rules never disagree;
  • semantic JSDoc in JavaScript, such as @type, @template, and @readonly, and @internal annotations used by TypeScript's stripInternal, even with apiDocs: "none";
  • Vue template directives such as @vue-ignore, @vue-expect-error, @vue-skip, and @vue-generic, as well as shared directives such as <!-- eslint-disable-next-line -->.

Options

  • allow: regular expression sources, matched against the comment text without its delimiters. Use it for comments that the project's own tools read. An invalid pattern stops the run with DOC0020.
  • apiDocs: "exported" (the default) keeps a JSDoc block directly before an exported declaration and before the members of an exported declaration: interface, type literal, and class members, enum members, and union members. "none" reports those too.

Use overrides to change the options for some paths, for example to keep API docs only in published packages:

doctor.config.json
{
  "rules": { "typescript/strict/no-comments": ["warn", { "apiDocs": "none" }] },
  "overrides": [
    {
      "files": ["packages/*/src/**"],
      "rules": { "typescript/strict/no-comments": ["warn", { "apiDocs": "exported" }] }
    }
  ]
}

Adopt it in an existing codebase

Run it with --since <ref> so it reports only comments on changed lines. It needs no baseline file:

pnpm vite-doctor . --since origin/main --max-warnings 0

A full run without --since also checks old comments. Code that is moved or reformatted brings its comments into the diff. The rule sets each finding's fingerprint from the file path and the comment text, so a --baseline file also survives renamed functions and new code above a comment, but rewording a comment makes it new.

Classify before deleting

First check whether a project tool consumes the comment. If it does, add an allow pattern instead of deleting it. Otherwise, put it in one class before you delete it:

  • Tautology: it repeats what the code says. Delete it.
  • Stale: it is no longer true. Delete it.
  • Excuse: it allows a workaround. File an issue for the workaround, then delete it.
  • Decision Record: it records a non-obvious decision the code cannot show. Move it to the project's decision log, then delete it.

When removing a script or JSX comment, keep its line breaks (for example, after return) and leave a space if the comment separates tokens (for example, const/**/value).

Delete them with --unsafe-fix

Classify first. The fix deletes every reported comment it can delete without changing the code, and it cannot tell a tautology from a decision or an excuse you still need to move. That makes it unsafe: plain --fix never applies it. With the rule named in doctor.config.json, run it alone:

pnpm vite-doctor . --rules typescript/strict/no-comments --unsafe-fix

The fix removes a standalone script comment together with its line, and a trailing script comment together with the space before it. It removes a JSX comment with its {} container. In Vue templates it deletes only comments that touch element or container boundaries on both sides. Doctor then runs again and reports the comments it left, without a fix:

  • a block comment that spans lines with code on both sides, because its line break can end a statement after return or throw;
  • a JSX comment whose removal could change rendered text or merge separate text children into one, including text with unusual whitespace and runs where multiple edits would have to be applied together;
  • a Vue template comment that is a component's only child, because it can supply the default slot;
  • a Vue template comment next to text, an interpolation, another comment, or whitespace, or inside <pre>; Vue's whitespace option can preserve whitespace even on otherwise empty lines;
  • JSX comments that share a line with each other and with other code;
  • any reported comment in a file with a retained tooling directive, checked JSDoc annotation, public API JSDoc, or comment matched by allow. Doctor cannot guarantee that deleting a nearby comment preserves what the retained comment applies to. A standalone license identifier does not block fixes.

Run one rule

Use a TypeScript rule ID without selecting a framework:

pnpm vite-doctor . --rules typescript/boundaries/no-unvalidated-deserialization

Doctor returns compact structured output automatically in recognized agent runtimes. Use --format agent for a fixed agent contract or --format json for the complete machine report.

Copyright © 2026