@sylphx/doctor

Project health checker for modern TypeScript/Rust monorepos.

What is Doctor?

Doctor ensures your project structure and configuration is correct. It complements code-level tools like Biome.

Tool	Level	Checks
Biome	Code	Formatting, linting rules, import sorting
TypeScript	Code	Type errors, strict mode
Doctor	Project	Config files, dependencies, scripts, CI/CD, release workflow

Doctor Checks

Config exists - biome.json, tsconfig.json, turbo.json
Config correct - extends shared configs, proper settings
Dependencies - correct versions, no legacy tools
Scripts - lint, build, test scripts use modern tools
Project structure - README, LICENSE, exports field
CI/CD - workflows exist, release process configured
Git hooks - lefthook configured, pre-commit/pre-push

Doctor Does NOT Check

Code style (Biome)
Type errors (TypeScript)
Unused variables (Biome)
Import order (Biome)

Philosophy: Doctor checks that Biome is configured correctly. Biome checks your code.

Supported Ecosystems

Ecosystem	Status	Checks
TypeScript	✅ Full	80+ checks
Rust	✅ Basic	7 checks
Go	❌ Not planned	-
Python	❌ Not planned	-

Installation

bun add -D @sylphx/doctor

Or run directly:

bunx @sylphx/doctor check

Usage

Check project

# Check with default preset (dev)
doctor check

# Check with specific preset
doctor check --preset=init
doctor check --preset=stable

# Auto-fix fixable issues
doctor check --fix

# Pre-commit mode (only errors, no warnings)
doctor check --pre-commit

Initialize config

# Create config file with init preset
doctor init

# Create config and auto-fix
doctor init --fix

# Start with specific preset
doctor init --preset=dev

Check upgrade readiness

# Preview upgrade to next preset level
doctor upgrade

# Preview upgrade to specific preset
doctor upgrade --target=stable

Project review checklist

High-level architectural review checklist (25 sections, 359 items) for manual verification. Unlike automated checks, this provides hints that cannot be automatically verified.

Philosophy (0): 0. Philosophy & Trade-offs

Architecture (1-4):

Architecture & Modularity
Contracts & Boundaries
Design Principles
State & Effects

Reliability (5-8): 5. Error Handling & Recovery 6. Runtime & Resilience 7. Concurrency & Async 8. Efficiency & Performance

Data & Integration (9-10): 9. Data & Persistence 10. API Design & Operations

Quality (11-13): 11. Testing & Correctness 12. Observability 13. Security, Auth & Compliance

Delivery (14-15): 14. Build, Deploy & Supply Chain 15. Operational Readiness

Evolution (16-18): 16. Code Health & Evolution 17. Documentation 18. Configuration & DX

Frontend (19-22): 19. UI State & Data 20. Responsive & Accessible 21. UI Feedback & Real-time 22. Frontend Performance & Design System

Cross-cutting (23-24): 23. i18n & Localization 24. Extensibility & Plugins

# Show full checklist
doctor review

# Show specific section
doctor review security
doctor review errors
doctor review data

# List available sections
doctor review --list

Presets

Preset	Description	Use when
`init`	Minimal checks	New project, just started
`dev`	Balanced checks	Active development
`stable`	Strict checks	Production-ready

Configuration

TypeScript/JavaScript projects

Create doctor.config.ts (or .js, .mjs):

import { defineConfig } from '@sylphx/doctor'

export default defineConfig({
  preset: 'dev',

  // Override specific rules
  rules: {
    'docs/vitepress': 'off',
    'github/topics': 'warn',
    'test/coverage-threshold': 'error',
  },

  // Configure rule options
  options: {
    'test/coverage-threshold': { min: 60 },
    'github/topics': { min: 5 },
  },
})

JSON config (for non-TS projects)

Create doctor.config.json:

{
  "preset": "dev",
  "rules": {
    "docs/vitepress": "off",
    "github/topics": "warn"
  }
}

Rust projects

Add to Cargo.toml:

[package.metadata.doctor]
preset = "dev"

[package.metadata.doctor.rules]
"rust/deny" = "off"

Per-package config (monorepos)

Each package can have its own config that inherits from root:

my-monorepo/
├── doctor.config.ts         # Root config (preset: "dev")
├── packages/
│   ├── core/
│   │   └── doctor.config.ts  # Inherits from root, can override
│   └── cli/
│       └── doctor.config.json # JSON also works

Child configs inherit all settings from root and can override specific rules.

Config file priority

doctor.config.ts
doctor.config.js
doctor.config.mjs
doctor.config.json
Cargo.toml [package.metadata.doctor]
Legacy: sylphx-doctor.config.* (backward compatible)

Pre-commit Hook

Add to lefthook.yml:

pre-commit:
  parallel: true
  commands:
    doctor:
      run: bunx @sylphx/doctor check --pre-commit

All Checks

Files

Check	Description	Fixable
`files/readme`	README.md exists	❌
`files/license`	LICENSE exists	✅ MIT
`files/gitignore`	.gitignore exists	❌
`files/changelog`	CHANGELOG.md exists	❌
`files/progress`	progress.md exists	❌
`files/biome-config`	biome.json exists	❌
`files/turbo-config`	turbo.json exists	❌

Package.json

Check	Description	Fixable
`pkg/name`	Has name field	❌
`pkg/description`	Has description field	❌
`pkg/repository`	Has repository field	❌
`pkg/author`	Has author field	❌
`pkg/license-field`	Has license field	❌
`pkg/engines`	Has engines.node field	❌
`pkg/keywords`	Has keywords array	❌
`pkg/type-module`	Has "type": "module"	✅
`pkg/exports`	Has exports field	❌
`pkg/scripts-lint`	lint script uses biome	✅
`pkg/scripts-format`	format script uses biome	✅
`pkg/scripts-build`	build script uses bunup	✅
`pkg/scripts-test`	test script uses bun test	✅
`pkg/scripts-typecheck`	typecheck script uses tsc	✅
`pkg/scripts-bench`	bench script uses bun bench	✅
`pkg/scripts-coverage`	coverage script configured	✅

Config

Check	Description	Fixable
`config/biome-extends`	biome.json extends @sylphx/biome-config	✅
`config/tsconfig-extends`	tsconfig extends @sylphx/tsconfig	✅
`config/biome-config-dep`	@sylphx/biome-config installed	✅
`config/tsconfig-dep`	@sylphx/tsconfig installed	✅
`config/no-tsconfig-build`	No tsconfig.build.json	✅

Build

Check	Description	Fixable
`build/esm-only`	No CJS output (ESM only)	✅
`build/exports-valid`	exports properly configured	❌
`build/bunup-dep`	bunup installed	✅
`build/suggest-bunup`	Suggests bunup over legacy bundlers	❌

Format & Lint

Check	Description	Fixable
`format/biome-check`	biome check passes	❌
`format/biome-format`	biome format passes	❌
`format/biome-dep`	@biomejs/biome installed	✅
`format/no-eslint`	No eslint dependency	✅
`format/eslint-config-orphan`	No orphan eslint config	✅
`format/prettier-config-orphan`	No orphan prettier config	✅
`format/typecheck`	tsc --noEmit passes	❌

Testing

Check	Description	Fixable
`test/has-tests`	Test files exist	❌
`test/passes`	Tests pass	❌
`test/coverage-threshold`	Coverage meets threshold	❌
`test/no-legacy-frameworks`	No jest/vitest/mocha	✅
`test/no-jest-config`	No jest config files	✅
`bench/has-files`	Benchmark files exist	❌

Runtime

Check	Description	Fixable
`runtime/bun-lock`	bun.lock exists	❌
`runtime/no-npm-lock`	No package-lock.json	✅
`runtime/no-yarn-lock`	No yarn.lock	✅
`runtime/no-pnpm-lock`	No pnpm-lock.yaml	✅
`runtime/no-ts-node`	No ts-node dependency	✅
`runtime/no-other-pkg-managers`	No npm/yarn/pnpm	✅

Release

Check	Description	Fixable
`release/no-manual-version`	Don't manually edit version	❌
`release/no-release-commit`	No "release" in recent commits	❌
`release/no-direct-publish`	No npm publish in scripts	❌
`release/bump-dep`	bump installed	✅
`release/no-changesets`	No .changeset directory	✅
`release/no-changesets-dep`	No changesets dependency	✅

Hooks

Check	Description	Fixable
`hooks/pre-commit`	Pre-commit hook exists	❌
`hooks/lefthook-pre-commit`	Lefthook pre-commit configured	❌
`hooks/lefthook-pre-push`	Lefthook pre-push configured	❌
`hooks/lefthook-doctor`	Doctor in lefthook config	❌
`hooks/lefthook-installed`	Lefthook hooks installed	✅
`hooks/lefthook-dep`	lefthook installed	✅
`hooks/no-husky`	No husky dependency	✅
`hooks/lefthook-prepare`	prepare script runs lefthook	✅
`hooks/doctor-dep`	@sylphx/doctor installed	✅

Monorepo

Check	Description	Fixable
`monorepo/root-private`	Root has "private": true	✅
`monorepo/packages-readme`	All packages have README	❌
`monorepo/packages-license`	All packages have LICENSE	❌
`monorepo/workspace-protocol`	Uses workspace: protocol	❌
`monorepo/workspace-star`	Uses workspace:* (not ^)	❌
`monorepo/consistent-versions`	Consistent dep versions	❌
`monorepo/turbo-tasks`	Turbo has standard tasks	❌
`monorepo/turbo-dep`	turbo installed	✅

CI/CD

Check	Description	Fixable
`ci/has-workflow`	CI workflow exists	❌
`ci/publish-workflow`	Publish workflow exists	❌
`ci/rust-workflow`	Rust CI workflow exists	✅

GitHub

Check	Description	Fixable
`github/description`	Repo has description	❌
`github/website`	Repo has website URL	❌
`github/topics`	Repo has topics (≥3)	❌

Docs

Check	Description	Fixable
`docs/vitepress`	VitePress docs exist	❌
`docs/vercel-config`	vercel.json for docs	❌

Dependencies

Check	Description	Fixable
`deps/outdated`	No outdated dependencies	❌
`deps/security`	No security vulnerabilities	❌
`deps/has-knip`	knip configured for unused deps	❌

Branding

Check	Description	Fixable
`branding/header`	README has centered header with emoji title	❌
`branding/footer`	README has footer with Star History + Sylphx	❌
`branding/version-badge`	Version badge (npm/crates.io)	❌
`branding/downloads-badge`	Downloads badge (npm/crates.io)	❌
`branding/stars-badge`	GitHub stars badge	❌
`branding/license-badge`	MIT license badge	❌
`branding/ci-badge`	CI status badge (if has workflow)	❌
`branding/coverage-badge`	Coverage badge (for libraries)	❌
`branding/typescript-badge`	TypeScript badge (for TS libraries)	❌
`branding/package-links`	Monorepo root has package links table	❌
`branding/packages`	README mentions all @sylphx packages used	❌

Rust

Check	Description	Fixable
`rust/has-cargo`	Cargo.toml exists	❌
`rust/edition`	Uses modern Rust edition (2021+)	❌
`rust/has-rustfmt`	rustfmt.toml exists	❌
`rust/has-clippy`	clippy config exists	❌
`rust/has-tests`	Rust tests exist	❌
`rust/deny`	deny.toml for security audit	❌
`rust/cargo-lock`	Binary crate has Cargo.lock	❌

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 241 Commits
.claude		.claude
.github/workflows		.github/workflows
src		src
.gitignore		.gitignore
.mcp.json		.mcp.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
build.config.ts		build.config.ts
bun.lock		bun.lock
lefthook.yml		lefthook.yml
package.json		package.json
progress.md		progress.md
tsconfig.json		tsconfig.json
turbo.json		turbo.json

License

SylphxAI/doctor

Folders and files

Latest commit

History

Repository files navigation

@sylphx/doctor

What is Doctor?

Doctor Checks

Doctor Does NOT Check

Supported Ecosystems

Installation

Usage

Check project

Initialize config

Check upgrade readiness

Project review checklist

Presets

Configuration

TypeScript/JavaScript projects

JSON config (for non-TS projects)

Rust projects

Per-package config (monorepos)

Config file priority

Pre-commit Hook

All Checks

Files

Package.json

Config

Build

Format & Lint

Testing

Runtime

Release

Hooks

Monorepo

CI/CD

GitHub

Docs

Dependencies

Branding

Rust

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 65

Packages 0

Uh oh!

Contributors 3

Uh oh!

Languages

Packages