Doctor#

@domphy/doctor is a static analyzer for Domphy element trees. It walks the plain-object tree — including the output of reactive (listener) => … functions — and flags non-idiomatic patterns. Its main job is to give AI agents (and humans) a feedback loop: generate code → diagnose() → fix what it reports.

Because Domphy UIs are plain objects, the doctor needs no parser and no build step.

Install#

npm install -D @domphy/doctor @domphy/core

@domphy/core is a peer dependency (the doctor reads its tag tables).

Live Example#

Run diagnose() on a deliberately broken tree, then apply fix() and watch the report shrink:

Usage#

import { diagnose, format } from "@domphy/doctor"

const App = {
  div: [
    { p: "Hello", style: { fontSize: "20px" } }, // inline typography
    { input: "oops" }, // void tag with content
    { dvi: "typo" }, // unknown tag
  ],
}

console.log(format(diagnose(App)))

⚠ [inline-typography] div > p
  Inline `fontSize` — avoid inline typography styles.
  → Use a typography patch (paragraph()/heading()/…) via $.
✗ [void-content] div > input
  Void tag "input" must have null content (got string).
⚠ [unknown-tag] div
  "dvi" is not a known HTML/SVG tag — likely a typo.

diagnose(element, options?) returns Diagnostic[]:

type Severity = "error" | "warning" | "info"

interface Diagnostic {
  rule: string     // "inline-typography" | "void-content" | "missing-key" | …
  severity: Severity
  category?: string // "structure" | "key" | "theme" | "typography" | "data-attr" | "visual"
  path: string     // "div > ul > li"
  message: string
  hint?: string
}

Severity is exported from @domphy/doctor as its own named type.

Rules#

The doctor implements 23 built-in rules. See Rules Reference for the full contract of each.

$ patches are part of the element#

Every rule reads the element's effective props — the element with its $ patches applied, exactly the way ElementNode composes them at runtime (each patch expanded, composed left to right, the native element last so it wins). A style, dataTone, role, tabIndex or _doctorDisable a patch contributes is therefore visible to the rules, and a rule never asks for something a patch already supplies:

// missing-color fires — panelSection({ divider: true }) themes a
// borderBottom with themeColor(), and nothing on the element sets `color`.
{ div: "Section A", $: [panelSection({ divider: true })] }

// low-contrast does NOT fire — button()'s solid variant declares
// _doctorDisable: ["low-contrast", …] for its deliberate deep brand fill,
// and that suppression travels with the patch to every host.
{ button: "Save", $: [button({ color: "primary", variant: "solid" })] }

The element's children are read from the declared tree: content a patch contributes as a default is analyzed, content the element declares itself is analyzed as written. The host tag always comes from the element, never from a patch — core resolves the tag before patches are merged.

By default the doctor invokes reactive content functions with a no-op listener to inspect their output (this is how the dynamic-list rules are found). Pass { runReactive: false } if your reactive functions have side effects.

duplicate-key is decidable on any sibling array — static or dynamic — so it is checked everywhere. missing-key and unstable-key are specific to dynamic lists, since only those go through keyed reconciliation.

Rule filtering#

Run only a subset of rules with only, or skip rules with exclude:

// Only check theming
diagnose(App, { only: ["raw-theme-value", "raw-spacing-value"] })

// Skip soft info-level recommendations
diagnose(App, { exclude: ["raw-theme-value", "raw-spacing-value"] })

Inline suppression#

Add _doctorDisable to an element to suppress rules at that node (not its children):

// Suppress all rules on this element
{ div: "x", dataTone: "shift-6", _doctorDisable: true }

// Suppress specific rules
{ div: "x", dataTone: "shift-6", _doctorDisable: ["middle-surface-anchor"] }

Custom rules#

Provide project-specific rules alongside the built-in 23:

import { type CustomRule, diagnose } from "@domphy/doctor"

const noBareDivRule: CustomRule = {
  id: "no-bare-div",
  severity: "warning",
  check: (_el, _path, tag) =>
    tag === "div" ? [{ message: "Use a semantic element or add a patch." }] : [],
}

diagnose(App, { rules: [noBareDivRule] })

See Configuration & API for full details.

validate#

validate(element, options?) is the aggregate entry point. It runs every rule and returns a structured report instead of a raw array:

import { validate } from "@domphy/doctor"

const report = validate(App)

report.ok      // false — there is at least one error-severity issue
report.issues  // Diagnostic[] — same as diagnose(App)
report.summary // { error: 1, warning: 2, info: 0, total: 3 }

interface ValidationReport {
  ok: boolean // true when there are no error-severity diagnostics
  issues: Diagnostic[]
  summary: { error: number; warning: number; info: number; total: number }
}

ok is false when any error diagnostic is present; warnings and info do not flip it. Use this as the single programmatic gate — for example fail CI when !report.ok — while diagnose / format remain available for raw access.

fix#

fix(element, options?) applies the lossless fixes automatically and reports the rest:

import { fix } from "@domphy/doctor"

const { tree, applied, report } = fix(App)
// tree    — a copy with lossless fixes applied (reactive functions preserved)
// applied — [{ rule, path, message }] describing what changed
// report  — validate(tree): the issues that still need a human/model decision

Only provably-lossless transforms run (currently void-content: a void tag cannot render children, so its content is cleared to null). Anything that needs intent — which key, tone, color token, or typography patch — is never guessed; it stays in report for the model or you to resolve. This keeps autofix safe to apply blindly in an agent loop.

In an AI loop#

This is the point of the package. After the model generates a Domphy tree, run the doctor and return the report:

const report = format(diagnose(generatedApp))
if (report !== "✓ No issues found.") {
  // hand `report` back to the model and ask it to fix the listed issues
}

Most LLMs have little Domphy training data, so they learn it in-context from llms.txt / AGENTS.md. The doctor enforces those same rules mechanically — turning "the model might get it wrong" into "the model gets told exactly what's wrong and fixes it." Wire it into your agent's task loop or CI.

Large codebases#

In a real app the model also needs to find and reuse the app's own building blocks, not just the framework surface. The repo ships an app-block registry generator, apps/web/scripts/app-manifest.mjs, which parses your app source with the TypeScript compiler API and emits one entry per exported Domphy block (function/const that returns an element tree):

node apps/web/scripts/app-manifest.mjs [srcDir] [outFile]
# defaults: srcDir = apps/web/docs/demos, outFile = apps/web/public/app-manifest.json

Each entry carries { name, kind, file, signature, jsdoc, exportKind } — a machine-readable index an agent can browse the way manifest.json exposes the framework packages and @domphy/ui patches.

@domphy/mcp wraps both halves as MCP tools so an agent gets validation and discovery over the wire:

The loop becomes: list the app's blocks → reuse them → generate → domphy_validate → fix what it reports. The doctor is the validation half; the manifest is the discovery half.