Configuration & API#

import { diagnose } from "@domphy/doctor"

const issues = diagnose(MyApp)

const errors = issues.filter(d => d.severity === "error")
const byRule = issues.reduce((acc, d) => {
  acc[d.rule] = (acc[d.rule] ?? 0) + 1
  return acc
}, {} as Record<string, number>)

import { validate } from "@domphy/doctor"

const report = validate(MyApp)

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

import { fix } from "@domphy/doctor"

const { tree, applied, report } = fix(MyApp)

// tree    — a copy with lossless fixes applied (reactive functions preserved)
// applied — [{ rule, path, message }] listing what changed
// report  — validate(tree): the issues that still need manual resolution

interface DiagnoseOptions {
  /**
   * Invoke reactive content functions `(listener) => …` with a no-op listener
   * to inspect their output. This is how `missing-key`, `unstable-key`, and
   * `duplicate-key` inside dynamic lists are found.
   *
   * Default: true
   * Set to false if your reactive functions have side effects.
   */
  runReactive?: boolean

  /**
   * If set, only emit diagnostics whose rule id is in this list.
   * Takes precedence over `exclude`. An empty array returns no diagnostics.
   * Applies to both built-in and custom rules.
   */
  only?: string[]

  /**
   * Rule ids to skip entirely. Ignored when `only` is also set.
   * Applies to both built-in and custom rules.
   */
  exclude?: string[]

  /**
   * Additional custom rules to run alongside the 22 built-in rules.
   * Custom rule ids are also subject to `only`/`exclude` filtering.
   * See "Custom Rules" section below.
   */
  rules?: CustomRule[]
}

import { toState } from "@domphy/core"
import { diagnose } from "@domphy/doctor"

const items = toState(["A", "B", "C"])

// The reactive function is invoked with a no-op listener.
// The doctor sees the returned list and can check for _key.
const issues = diagnose({
  ul: (l) => items.get(l).map(text => ({ li: text }))
})
// -> includes missing-key warning

const issues = diagnose(MyApp, { runReactive: false })
// dynamic-list rules (missing-key, unstable-key) won't fire;
// duplicate-key and all structural rules still run on static content.

// Only check for literal theme values:
const colorIssues = diagnose(MyApp, { only: ["raw-theme-value", "raw-spacing-value"] })

// Skip soft recommendations, fail only on structural errors:
const strictIssues = diagnose(MyApp, {
  exclude: ["raw-theme-value", "raw-spacing-value", "inline-typography"]
})

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

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

// Suppress a single rule as a string
{ div: "x", dataTone: "shift-6", _doctorDisable: "middle-surface-anchor" }

// Suppress missing-key warning on the reactive list container
{
  ul: (l) => items.get(l).map(item => ({ li: item.label })),
  _doctorDisable: ["missing-key"],
}

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

// Disallow bare <div> with no patches — enforce using a layout wrapper
const noBareDiv: CustomRule = {
  id: "no-bare-div",
  severity: "warning",
  category: "structure",
  check: (element, _path, tag) => {
    if (tag === "div" && (!element.$ || (element.$ as unknown[]).length === 0)) {
      return [{ message: "Bare <div> without patches — add a layout patch or use a semantic tag." }]
    }
    return []
  },
}

const issues = diagnose(MyApp, { rules: [noBareDiv] })

interface CustomRule {
  /** Unique id shown in diagnostics. Must not clash with any built-in rule id. */
  id: string
  /** Default severity for violations from this rule. */
  severity: Severity
  /** Category for display and filtering. Optional. */
  category?: RuleCategory
  /**
   * Called for each element node (nodes with a valid HTML/SVG tag).
   * Return violation descriptors; the engine fills in rule, severity, category, path.
   * Pass severity in the descriptor to override the rule default per violation.
   */
  check: (
    element: Record<string, unknown>,
    path: string,
    tag: string,
  ) => Array<{ message: string; hint?: string; severity?: Severity }>
}

const strictTypography: CustomRule = {
  id: "strict-typography",
  severity: "warning",
  check: (element) => {
    const style = element.style as Record<string, unknown> | undefined
    if (style?.fontSize) {
      // Escalate to error for heading elements
      const tag = Object.keys(element).find(k => /^h[1-6]$/.test(k))
      return [{ message: "Inline font-size on heading.", severity: tag ? "error" : "warning" }]
    }
    return []
  },
}

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

type RuleCategory = "structure" | "key" | "theme" | "typography" | "data-attr" | "visual"

interface Diagnostic {
  rule: string          // e.g. "inline-typography"
  severity: Severity
  category?: RuleCategory // always set by built-in rules; optional for custom rules
  path: string          // human path to the node, e.g. "div > ul > li"
  message: string       // one-line description of the problem
  hint?: string         // how to fix it
}

interface ValidationReport {
  ok: boolean      // false when summary.error > 0
  issues: Diagnostic[]
  summary: {
    error: number
    warning: number
    info: number
    total: number
  }
}

interface FixResult {
  tree: unknown          // deep copy with lossless fixes applied
  applied: AppliedFix[]  // what changed
  report: ValidationReport // validate() on the fixed tree
}

interface AppliedFix {
  rule: string
  path: string
  message: string
}

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

const output = format(diagnose(MyApp))
console.log(output)

if (format(diagnose(MyApp)) !== "✓ No issues found.") {
  // there are issues
}

// scripts/lint-ui.ts
import { validate, format } from "@domphy/doctor"
import { MyApp } from "../src/app"

const report = validate(MyApp)

if (report.summary.total > 0) {
  console.log(format(report.issues))
}

if (!report.ok) {
  console.error(`\n${report.summary.error} error(s) — build blocked.`)
  process.exit(1)
}

if (report.summary.error > 0 || report.summary.warning > 0) {
  console.log(format(report.issues))
  process.exit(1)
}

const themeIssues = report.issues.filter(d =>
  d.rule === "raw-theme-value" || d.rule === "raw-spacing-value"
)

if (themeIssues.length > 0) {
  console.warn("Theme token gaps found:", themeIssues.length)
}

const errors = report.issues.filter(d => d.severity === "error")
const structural = errors.filter(d =>
  d.rule === "void-content" || d.rule === "duplicate-key"
)

import { ElementNode } from "@domphy/core"
import { auditOutput, format, type Layer4Options } from "@domphy/doctor"

const node = new ElementNode(MyApp)
const outputDiags = await auditOutput(node, { path: "MyApp" })
console.log(format(outputDiags))

interface Layer4Options {
  path?: string // label prefixed to each diagnostic's path; defaults to node.tagName
}

function auditOutput(node: ElementNode, options?: Layer4Options): Promise<Diagnostic[]>

import { diagnose, format, validate } from "@domphy/doctor"
import { HomePage } from "../src/pages/home"
import { SettingsPage } from "../src/pages/settings"
import { DashboardPage } from "../src/pages/dashboard"

const pages = [
  { name: "home", tree: HomePage },
  { name: "settings", tree: SettingsPage },
  { name: "dashboard", tree: DashboardPage },
]

let hasErrors = false

for (const { name, tree } of pages) {
  const report = validate(tree)
  if (report.summary.total > 0) {
    console.log(`\n--- ${name} ---`)
    console.log(format(report.issues))
  }
  if (!report.ok) hasErrors = true
}

if (hasErrors) process.exit(1)

import { toState } from "@domphy/core"

const tasks = toState<Task[]>([])

// Fine — pure read; doctor can inspect the list
{
  ul: (l) => tasks.get(l).map(task => ({
    li: task.title,
    _key: task.id,
  }))
}

// Problematic — side effect inside reactive function
// Pass { runReactive: false } if you have this pattern
{
  div: (l) => {
    trackPageView()  // side effect — do not put this inside the reactive function
    return content.get(l)
  }
}