feat!: bump devframe to v0.4.1, migrate diagnostic handles to callable API (#358)

Author: antfu

AGENTS.md

@@ -125,11 +125,13 @@ Codes are sequential 4-digit numbers per prefix (e.g. `DTK0033`, `RDDT0003`). Ch
    import { diagnostics } from './diagnostics'
 
    // For thrown errors — always prefix with `throw` for TypeScript control flow:
-   throw diagnostics.DTK0033.throw({ name })
+   throw diagnostics.DTK0033({ name })
 
-   // For reported (non-thrown) diagnostics:
-   diagnostics.DTK0033.report({ name })
-   diagnostics.DTK0033.report({ name, cause: error }) // attach cause via params
+   // For reported (non-thrown) diagnostics. The default console method is `warn`;
+   // override with the 2nd-arg reporter options when needed:
+   diagnostics.DTK0033({ name }) // console.warn
+   diagnostics.DTK0033({ name }, { method: 'error' }) // console.error
+   diagnostics.DTK0033({ name, cause: error }) // attach cause via params
    ```
 
 3. **Create a docs page** at `docs/errors/DTK0033.md`:

MIGRATION.md

@@ -50,3 +50,20 @@ These types are no longer re-exported from `@vitejs/devtools-kit`. Import them f
 ```
 
 The `@vitejs/devtools-kit/utils/when` subpath remains and re-exports these types alongside `evaluateWhen` and `resolveContextValue`.
+
+#### Diagnostic handles are callable
+
+`nostics` 0.2 (pulled in via devframe 0.4) drops the `.report()` / `.throw()` methods on diagnostic handles. Each handle is now a callable that builds and emits a diagnostic; prefix with `throw` to raise.
+
+```diff
+- throw ctx.diagnostics.logger.MYP0001.throw({ name })
++ throw ctx.diagnostics.logger.MYP0001({ name })
+
+- ctx.diagnostics.logger.MYP0002.report()
++ ctx.diagnostics.logger.MYP0002()
+
+- ctx.diagnostics.logger.MYP0002.report({ name }, { method: 'error' })
++ ctx.diagnostics.logger.MYP0002({ name }, { method: 'error' })
+```
+
+The payload shape (including `cause`) and the optional reporter-options second argument are unchanged. Apply the same rewrite to typed handles returned from `ctx.diagnostics.defineDiagnostics()`.

devframe

@@ -13,7 +13,8 @@
 interface DevToolsDiagnosticsHost {
   /**
    * Proxy-backed lookup of every registered code by name. Each entry is a
-   * `nostics` handle with `.report()` and `.throw()` methods.
+   * `nostics` `DiagnosticHandle` — a callable that builds a diagnostic and
+   * routes it through registered reporters; prefix with `throw` to raise.
    */
   readonly logger: Record<string, any>
 
@@ -56,7 +57,7 @@ export function MyPlugin(): PluginWithDevTools {
         ctx.diagnostics.register(diagnostics)
 
         // Emit codes through the shared lookup:
-        ctx.diagnostics.logger.MYP0002.report()
+        ctx.diagnostics.logger.MYP0002()
       },
     },
   }
@@ -80,23 +81,26 @@ Each definition supports `why` (string or function returning a string) and an op
 
 ## Emit a diagnostic
 
-Each registered code is reachable as a property on `ctx.diagnostics.logger`. Every handle exposes `.throw(params)` and `.report(params)`.
+Each registered code is reachable as a property on `ctx.diagnostics.logger`. Every handle is a callable — invoke it to report (returns the `Diagnostic`), or prefix with `throw` to raise.
 
 ```ts
 // Throw — control flow stops here
-throw ctx.diagnostics.logger.MYP0001.throw({ name: 'foo' })
+throw ctx.diagnostics.logger.MYP0001({ name: 'foo' })
 
-// Report without throwing (goes through the host's reporter)
-ctx.diagnostics.logger.MYP0002.report()
+// Report without throwing (default console method: `warn`)
+ctx.diagnostics.logger.MYP0002()
+
+// Override the console method per call
+ctx.diagnostics.logger.MYP0002({}, { method: 'error' })
 
 // Attach a `cause` via the params object
-ctx.diagnostics.logger.MYP0001.report({ name: 'foo', cause: error })
+ctx.diagnostics.logger.MYP0001({ name: 'foo', cause: error })
 ```
 
-`.throw()` is typed `never`. Prefix the call with `throw` so TypeScript narrows control flow correctly:
+The callable returns a `Diagnostic` (which extends `Error`). Prefix with `throw` so TypeScript narrows the lines after as unreachable:
 
 ```ts
-throw ctx.diagnostics.logger.MYP0001.throw({ name })
+throw ctx.diagnostics.logger.MYP0001({ name })
 ```
 
 ## Typed handle reference
@@ -115,7 +119,7 @@ const myDiagnostics = ctx.diagnostics.defineDiagnostics({
 ctx.diagnostics.register(myDiagnostics)
 
 // Use the typed handle directly at emit sites
-myDiagnostics.MYP0001.report({ name: 'foo' })
+myDiagnostics.MYP0001({ name: 'foo' })
 ```
 
 Both paths share the formatter and reporter defaults set by the host (ANSI console output).
@@ -135,7 +139,7 @@ Each page covers the message, cause, example, and fix; see any [DTK code page](/
 
 ## When to use what
 
-- **`ctx.diagnostics`** — coded conditions worth looking up: misconfiguration, deprecations, validation failures, internal invariants. Always docs-backed. Often `.throw()`.
+- **`ctx.diagnostics`** — coded conditions worth looking up: misconfiguration, deprecations, validation failures, internal invariants. Always docs-backed. Often `throw`-prefixed.
 - **[`ctx.messages`](./messages)** — user-facing activity surfaces in the DevTools UI: progress indicators, audit results, "URL copied" toasts. Just a message and a level.
 
 Diagnostics target tool authors and CI; messages target the human in front of the DevTools panel.

docs/kit/diagnostics.md

@@ -89,5 +89,5 @@ export async function build(options: BuildOptions) {
     outDir,
   })
 
-  diagnostics.DTK0010.report()
+  diagnostics.DTK0010()
 }

packages/core/src/node/cli-commands.ts

@@ -78,7 +78,7 @@ export async function createDevToolsContext(
       await plugin.devtools?.setup?.(context)
     }
     catch (error) {
-      throw diagnostics.DTK0014.throw({ name: plugin.name, cause: error })
+      throw diagnostics.DTK0014({ name: plugin.name, cause: error })
     }
   }
 

packages/core/src/node/context.ts

@@ -14,10 +14,10 @@ export const docksOnLaunch = defineRpcFunction({
 
         const entry = context.docks.values().find(entry => entry.id === entryId)
         if (!entry) {
-          throw diagnostics.DTK0030.throw({ id: entryId })
+          throw diagnostics.DTK0030({ id: entryId })
         }
         if (entry.type !== 'launcher') {
-          throw diagnostics.DTK0031.throw({ id: entryId })
+          throw diagnostics.DTK0031({ id: entryId })
         }
         try {
           context.docks.update({
@@ -43,7 +43,7 @@ export const docksOnLaunch = defineRpcFunction({
           return result
         }
         catch (error) {
-          diagnostics.DTK0032.report({ id: entryId, cause: error })
+          diagnostics.DTK0032({ id: entryId, cause: error })
           context.docks.update({
             ...entry,
             launcher: {

packages/core/src/node/rpc/internal/docks-on-launch.ts

@@ -15,7 +15,7 @@ export const openInEditor = defineRpcFunction({
 
         // Prevent escaping the workspace root
         if (rel.startsWith('..') || rel.includes('\0')) {
-          throw diagnostics.DTK0028.throw()
+          throw diagnostics.DTK0028()
         }
 
         launchEditor(resolved)

packages/core/src/node/rpc/public/open-in-editor.ts

@@ -15,7 +15,7 @@ export const openInFinder = defineRpcFunction({
 
         // Ensure the path stays within workspace root
         if (rel.startsWith('..') || rel.includes('\0')) {
-          throw diagnostics.DTK0029.throw()
+          throw diagnostics.DTK0029()
         }
 
         await open(resolved)

packages/core/src/node/rpc/public/open-in-finder.ts

@@ -50,7 +50,7 @@ export async function createWsServer(options: CreateWsServerOptions) {
 
   const isClientAuthDisabled = context.mode === 'build' || context.viteConfig.devtools?.config?.clientAuth === false || process.env.VITE_DEVTOOLS_DISABLE_CLIENT_AUTH === 'true'
   if (isClientAuthDisabled) {
-    diagnostics.DTK0008.report()
+    diagnostics.DTK0008()
   }
 
   contextInternal.wsEndpoint = {
@@ -74,10 +74,10 @@ export async function createWsServer(options: CreateWsServerOptions) {
     {
       rpcOptions: {
         onFunctionError(error, name) {
-          diagnostics.DTK0011.report({ name, cause: error })
+          diagnostics.DTK0011({ name, cause: error })
         },
         onGeneralError(error) {
-          diagnostics.DTK0012.report({ cause: error })
+          diagnostics.DTK0012({ cause: error })
         },
         resolver(name, fn) {
           // eslint-disable-next-line ts/no-this-alias
@@ -86,7 +86,7 @@ export async function createWsServer(options: CreateWsServerOptions) {
           // Block unauthorized access to non-anonymous methods
           if (!name.startsWith(ANONYMOUS_SCOPE) && !rpc.$meta.isTrusted) {
             return () => {
-              throw diagnostics.DTK0013.throw({ name, clientId: rpc.$meta.id })
+              throw diagnostics.DTK0013({ name, clientId: rpc.$meta.id })
             }
           }