hono-doctor 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Add read-only analysis for Hono RPC type loss, Promise-chain response inference, middleware ordering, timeout/stream conflicts, and workspace version skew.
+- Add pretty, JSON, and SARIF output.
+- Include rule and validation documentation in the npm package; check packaged entry points and documentation links before release.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Code of Conduct
+
+We are committed to a respectful, harassment-free project. Be constructive, assume good intent, and focus criticism on ideas and code. Maintainers may remove abusive, discriminatory, threatening, or disruptive content and restrict participation when necessary.
+
+Report conduct concerns privately to the maintainer through the contact options on their GitHub profile.

package/CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing
+
+Bug reports and focused rule proposals are welcome. A new rule must identify a documented Hono contract or a reproducible runtime/type failure and include both positive and negative fixtures.
+
+```sh
+pnpm install
+pnpm format:check
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+Please keep rules deterministic and avoid executing analyzed application code.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wang Xiaoping
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# hono-doctor
+
+Catch Hono RPC typing, middleware ordering, and streaming configuration mistakes before they reach CI or production.
+
+```sh
+npx hono-doctor .
+```
+
+`hono-doctor` is a read-only static analyzer. It does not rewrite source files, execute application code, contact a service, or collect telemetry.
+
+## Why
+
+Several valid-looking Hono patterns have consequences that are easy to miss:
+
+- registering routes after `const app = new Hono()` does not evolve the TypeScript type later exported with `typeof app`;
+- returning a `.then()` chain from a handler can make Hono RPC infer the response as `unknown`;
+- registering global middleware after routes leaves earlier routes outside that middleware;
+- Hono's timeout middleware does not support streaming responses;
+- different installed Hono versions across a monorepo can break RPC compatibility.
+
+These constraints are documented by Hono, but they are distributed across the [RPC](https://hono.dev/docs/guides/rpc), [testing](https://hono.dev/docs/guides/testing), [middleware](https://hono.dev/docs/guides/middleware), and [timeout](https://hono.dev/docs/middleware/builtin/timeout) guides. `hono-doctor` turns the deterministic parts into one local check.
+
+## Usage
+
+```sh
+# Human-readable output; exits 1 on warnings or errors
+npx hono-doctor .
+
+# Machine-readable output
+npx hono-doctor . --format json
+
+# GitHub code scanning and other SARIF consumers
+npx hono-doctor . --format sarif > hono-doctor.sarif
+
+# Report warnings but fail CI only on errors
+npx hono-doctor . --fail-on error
+```
+
+Options:
+
+| Option      | Values                     | Default   |
+| ----------- | -------------------------- | --------- |
+| `--format`  | `pretty`, `json`, `sarif`  | `pretty`  |
+| `--fail-on` | `warning`, `error`, `none` | `warning` |
+
+## Rules
+
+| Rule    | Severity      | What it detects                                                                        |
+| ------- | ------------- | -------------------------------------------------------------------------------------- |
+| `HD001` | error         | Standalone route registrations missing from an exported `typeof app`                   |
+| `HD002` | error         | Hono response returned through a `.then()` chain, which can erase RPC output inference |
+| `HD003` | warning       | Global middleware registered after one or more routes                                  |
+| `HD004` | error         | Hono timeout middleware covering a streaming route in the same file                    |
+| `HD005` | error/warning | Multiple installed Hono versions, or unverifiable conflicting declared ranges          |
+
+The analyzer deliberately skips subjective style checks. `HD003` reports only global middleware because path-specific middleware registered later can be intentional. `HD004` requires both the timeout and streaming route to be statically visible in the same file.
+
+## Library API
+
+```ts
+import { scan } from "hono-doctor";
+
+const result = await scan(".");
+for (const diagnostic of result.diagnostics) {
+  console.log(diagnostic.ruleId, diagnostic.file, diagnostic.line);
+}
+```
+
+## Scope
+
+- JavaScript and TypeScript source files are supported.
+- Generated output, dependencies, coverage, and common framework build directories are ignored.
+- No application modules are imported or executed.
+- Cross-file route composition is not reconstructed in version 0.1.0.
+
+See [rule details](docs/rules.md), [validation plan](docs/validation.md), [contributing](CONTRIBUTING.md), and [security policy](SECURITY.md).
+
+## License
+
+MIT

package/RELEASING.md

@@ -0,0 +1,24 @@
+# Releasing
+
+## First release
+
+`pnpm release:check` includes a package-content check for public entry points
+and relative Markdown links. It does not publish to npm.
+
+1. Run `pnpm release:check`.
+2. Create the public GitHub repository and push `main`.
+3. Publish `0.1.0` interactively with npm WebAuthn.
+4. Configure npm Trusted Publishing for `.github/workflows/publish.yml` with publish access.
+5. Create and push the `v0.1.0` tag, but do not publish a GitHub release for this already-published version. Doing so would trigger a duplicate npm publication.
+6. Verify the registry tarball and run `npx hono-doctor@0.1.0 --version`.
+
+Do not store a long-lived npm publish token.
+
+## Subsequent releases
+
+1. Update `CHANGELOG.md` and the version in `package.json`.
+2. Run `pnpm release:check`.
+3. Commit and push the release revision.
+4. Create and publish a GitHub release tagged `v<version>`.
+5. The publish workflow releases to npm through Trusted Publishing and provenance.
+6. Verify the registry tarball and run `npx hono-doctor@<version> --version`.

package/SECURITY.md

@@ -0,0 +1,5 @@
+# Security policy
+
+Please report vulnerabilities privately through GitHub Security Advisories for this repository. Do not include secrets or private source code in a public issue.
+
+`hono-doctor` reads local source and package metadata. It must not execute analyzed application modules, make network requests during a scan, or collect telemetry. Reports that violate this boundary are treated as security issues.

package/dist/cli-args.d.ts

@@ -0,0 +1,10 @@
+export type OutputFormat = "pretty" | "json" | "sarif";
+export type FailOn = "warning" | "error" | "none";
+export interface CliOptions {
+    target: string;
+    format: OutputFormat;
+    failOn: FailOn;
+    help: boolean;
+    version: boolean;
+}
+export declare function parseCliArgs(args: string[]): CliOptions;

package/dist/cli-args.js

@@ -0,0 +1,55 @@
+function optionValue(args, index, name) {
+    const inlinePrefix = `${name}=`;
+    if (args[index].startsWith(inlinePrefix)) {
+        const value = args[index].slice(inlinePrefix.length);
+        if (!value)
+            throw new Error(`Missing value for ${name}`);
+        return { value, nextIndex: index };
+    }
+    const value = args[index + 1];
+    if (!value || value.startsWith("-"))
+        throw new Error(`Missing value for ${name}`);
+    return { value, nextIndex: index + 1 };
+}
+export function parseCliArgs(args) {
+    let target = ".";
+    let hasTarget = false;
+    let format = "pretty";
+    let failOn = "warning";
+    let help = false;
+    let version = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "-h" || argument === "--help") {
+            help = true;
+            continue;
+        }
+        if (argument === "-v" || argument === "--version") {
+            version = true;
+            continue;
+        }
+        if (argument === "--format" || argument.startsWith("--format=")) {
+            const parsed = optionValue(args, index, "--format");
+            if (!["pretty", "json", "sarif"].includes(parsed.value))
+                throw new Error(`Unknown format: ${parsed.value}`);
+            format = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+        if (argument === "--fail-on" || argument.startsWith("--fail-on=")) {
+            const parsed = optionValue(args, index, "--fail-on");
+            if (!["warning", "error", "none"].includes(parsed.value))
+                throw new Error(`Unknown --fail-on value: ${parsed.value}`);
+            failOn = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+        if (argument.startsWith("-"))
+            throw new Error(`Unknown option: ${argument}`);
+        if (hasTarget)
+            throw new Error(`Unexpected argument: ${argument}`);
+        target = argument;
+        hasTarget = true;
+    }
+    return { target, format, failOn, help, version };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { parseCliArgs } from "./cli-args.js";
+import { formatJson, formatPretty, formatSarif } from "./format.js";
+import { scan } from "./index.js";
+const help = `hono-doctor [directory] [options]
+
+Catch Hono RPC typing, middleware ordering, and streaming configuration mistakes.
+
+Options:
+  --format <pretty|json|sarif>  Output format (default: pretty)
+  --fail-on <warning|error|none>
+                                Exit non-zero at this severity (default: warning)
+  -h, --help                    Show help
+  -v, --version                 Show version`;
+async function packageVersion() {
+    const packageFile = new URL("../package.json", import.meta.url);
+    const value = JSON.parse(await readFile(packageFile, "utf8"));
+    if (typeof value.version !== "string")
+        throw new Error("Package version is missing");
+    return value.version;
+}
+async function main() {
+    const options = parseCliArgs(process.argv.slice(2));
+    if (options.help) {
+        console.log(help);
+        return;
+    }
+    if (options.version) {
+        console.log(await packageVersion());
+        return;
+    }
+    const result = await scan(options.target);
+    console.log(options.format === "json"
+        ? formatJson(result)
+        : options.format === "sarif"
+            ? formatSarif(result)
+            : formatPretty(result));
+    if (options.failOn === "warning" && result.diagnostics.length > 0)
+        process.exitCode = 1;
+    if (options.failOn === "error" &&
+        result.diagnostics.some((item) => item.severity === "error"))
+        process.exitCode = 1;
+}
+main().catch((error) => {
+    console.error(`hono-doctor: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 2;
+});

package/dist/files.d.ts

@@ -0,0 +1,3 @@
+export declare function findSourceFiles(root: string): Promise<string[]>;
+export declare function findPackageFiles(root: string): Promise<string[]>;
+export declare function readJson(file: string): Promise<unknown>;

package/dist/files.js

@@ -0,0 +1,59 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+const ignoredDirectories = new Set([
+    ".git",
+    ".next",
+    ".nuxt",
+    ".output",
+    ".turbo",
+    ".vercel",
+    "build",
+    "coverage",
+    "dist",
+    "node_modules",
+    "out",
+]);
+const sourceExtensions = new Set([
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".ts",
+    ".tsx",
+    ".mts",
+    ".cts",
+]);
+async function walk(root, predicate) {
+    const found = [];
+    const pending = [root];
+    while (pending.length > 0) {
+        const directory = pending.pop();
+        const entries = await readdir(directory, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            const absolute = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (!ignoredDirectories.has(entry.name))
+                    pending.push(absolute);
+                continue;
+            }
+            if (entry.isFile() && predicate(absolute))
+                found.push(absolute);
+        }
+    }
+    return found.sort();
+}
+export function findSourceFiles(root) {
+    return walk(root, (file) => {
+        if (file.endsWith(".d.ts"))
+            return false;
+        return sourceExtensions.has(path.extname(file));
+    });
+}
+export function findPackageFiles(root) {
+    return walk(root, (file) => path.basename(file) === "package.json");
+}
+export async function readJson(file) {
+    return JSON.parse(await readFile(file, "utf8"));
+}

package/dist/format.d.ts

@@ -0,0 +1,4 @@
+import type { ScanResult } from "./types.js";
+export declare function formatPretty(result: ScanResult): string;
+export declare function formatJson(result: ScanResult): string;
+export declare function formatSarif(result: ScanResult): string;

package/dist/format.js

@@ -0,0 +1,57 @@
+import path from "node:path";
+export function formatPretty(result) {
+    if (result.diagnostics.length === 0) {
+        return `hono-doctor: no problems found (${result.filesScanned} source files, ${result.packagesScanned} packages)`;
+    }
+    const lines = result.diagnostics.flatMap((item) => [
+        `${item.file}:${item.line}:${item.column}  ${item.severity}  ${item.ruleId}  ${item.message}`,
+        `  ${item.help}`,
+    ]);
+    const errors = result.diagnostics.filter((item) => item.severity === "error").length;
+    const warnings = result.diagnostics.length - errors;
+    lines.push("", `hono-doctor: ${errors} error(s), ${warnings} warning(s) in ${result.filesScanned} source files`);
+    return lines.join("\n");
+}
+export function formatJson(result) {
+    return JSON.stringify(result, null, 2);
+}
+function sarifLevel(diagnostic) {
+    return diagnostic.severity;
+}
+export function formatSarif(result) {
+    const rules = [...new Set(result.diagnostics.map((item) => item.ruleId))].map((id) => ({
+        id,
+        name: id,
+        shortDescription: { text: `hono-doctor ${id}` },
+    }));
+    return JSON.stringify({
+        version: "2.1.0",
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "hono-doctor",
+                        informationUri: "https://github.com/wangxpych/hono-doctor",
+                        rules,
+                    },
+                },
+                results: result.diagnostics.map((item) => ({
+                    ruleId: item.ruleId,
+                    level: sarifLevel(item),
+                    message: { text: `${item.message} ${item.help}` },
+                    locations: [
+                        {
+                            physicalLocation: {
+                                artifactLocation: {
+                                    uri: item.file.split(path.sep).join("/"),
+                                },
+                                region: { startLine: item.line, startColumn: item.column },
+                            },
+                        },
+                    ],
+                })),
+            },
+        ],
+    }, null, 2);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { ScanOptions, ScanResult } from "./types.js";
+export type { Diagnostic, RuleId, ScanOptions, ScanResult, Severity, } from "./types.js";
+export declare function scan(target?: string, options?: ScanOptions): Promise<ScanResult>;

package/dist/index.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import { findPackageFiles, findSourceFiles } from "./files.js";
+import { scanPackages } from "./package-rules.js";
+import { scanSourceFile } from "./source-rules.js";
+async function mapConcurrent(values, concurrency, task) {
+    const results = new Array(values.length);
+    let nextIndex = 0;
+    async function worker() {
+        while (nextIndex < values.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            results[index] = await task(values[index]);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, worker));
+    return results;
+}
+export async function scan(target = ".", options = {}) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const root = path.resolve(cwd, target);
+    const [sourceFiles, packageFiles] = await Promise.all([
+        findSourceFiles(root),
+        findPackageFiles(root),
+    ]);
+    const sourceDiagnostics = await mapConcurrent(sourceFiles, 8, (file) => scanSourceFile(root, file));
+    const packageDiagnostics = await scanPackages(root, packageFiles);
+    const diagnostics = [...sourceDiagnostics.flat(), ...packageDiagnostics].sort((left, right) => left.file.localeCompare(right.file) ||
+        left.line - right.line ||
+        left.column - right.column ||
+        left.ruleId.localeCompare(right.ruleId));
+    return {
+        root,
+        filesScanned: sourceFiles.length,
+        packagesScanned: packageFiles.length,
+        diagnostics,
+    };
+}

package/dist/package-rules.d.ts

@@ -0,0 +1,2 @@
+import type { Diagnostic } from "./types.js";
+export declare function scanPackages(root: string, packageFiles: string[]): Promise<Diagnostic[]>;

package/dist/package-rules.js

@@ -0,0 +1,83 @@
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { readJson } from "./files.js";
+function declaredHonoRange(value) {
+    return (value.dependencies?.hono ??
+        value.devDependencies?.hono ??
+        value.optionalDependencies?.hono ??
+        value.peerDependencies?.hono);
+}
+async function installedHonoVersion(packageFile) {
+    let directory = path.dirname(packageFile);
+    while (true) {
+        const candidate = path.join(directory, "node_modules", "hono", "package.json");
+        try {
+            const resolved = await realpath(candidate);
+            const value = (await readJson(resolved));
+            return value.version;
+        }
+        catch {
+            const parent = path.dirname(directory);
+            if (parent === directory)
+                return undefined;
+            directory = parent;
+        }
+    }
+}
+export async function scanPackages(root, packageFiles) {
+    const installations = new Map();
+    const declarations = new Map();
+    for (const packageFile of packageFiles) {
+        let value;
+        try {
+            value = (await readJson(packageFile));
+        }
+        catch {
+            continue;
+        }
+        const range = declaredHonoRange(value);
+        if (!range)
+            continue;
+        const relative = path.relative(root, packageFile) || "package.json";
+        declarations.set(range, [...(declarations.get(range) ?? []), relative]);
+        const version = await installedHonoVersion(packageFile);
+        if (version)
+            installations.set(version, [
+                ...(installations.get(version) ?? []),
+                relative,
+            ]);
+    }
+    if (installations.size > 1) {
+        const details = [...installations.entries()]
+            .map(([version, files]) => `${version} in ${files.join(", ")}`)
+            .join("; ");
+        return [
+            {
+                ruleId: "HD005",
+                severity: "error",
+                message: `Multiple installed Hono versions can break RPC type compatibility: ${details}.`,
+                file: "package.json",
+                line: 1,
+                column: 1,
+                help: "Align Hono versions across the server and client workspaces, then reinstall the lockfile.",
+            },
+        ];
+    }
+    if (installations.size === 0 && declarations.size > 1) {
+        const details = [...declarations.entries()]
+            .map(([range, files]) => `${range} in ${files.join(", ")}`)
+            .join("; ");
+        return [
+            {
+                ruleId: "HD005",
+                severity: "warning",
+                message: `Hono is declared with different ranges and installed versions could not be verified: ${details}.`,
+                file: "package.json",
+                line: 1,
+                column: 1,
+                help: "Install dependencies and rerun hono-doctor, or align the declared Hono ranges.",
+            },
+        ];
+    }
+    return [];
+}

package/dist/source-rules.d.ts

@@ -0,0 +1,2 @@
+import type { Diagnostic } from "./types.js";
+export declare function scanSourceFile(root: string, absoluteFile: string): Promise<Diagnostic[]>;

package/dist/source-rules.js

@@ -0,0 +1,351 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import ts from "typescript";
+const routeMethods = new Set([
+    "all",
+    "delete",
+    "get",
+    "head",
+    "on",
+    "options",
+    "patch",
+    "post",
+    "put",
+    "route",
+]);
+function location(source, node) {
+    const position = source.getLineAndCharacterOfPosition(node.getStart(source));
+    return { line: position.line + 1, column: position.character + 1 };
+}
+function diagnostic(source, file, node, value) {
+    return { ...value, file, ...location(source, node) };
+}
+function importedNames(source, moduleName, importedName) {
+    const names = new Set();
+    for (const statement of source.statements) {
+        if (!ts.isImportDeclaration(statement) ||
+            statement.moduleSpecifier.getText(source).slice(1, -1) !== moduleName) {
+            continue;
+        }
+        const bindings = statement.importClause?.namedBindings;
+        if (!bindings || !ts.isNamedImports(bindings))
+            continue;
+        for (const element of bindings.elements) {
+            if ((element.propertyName?.text ?? element.name.text) === importedName)
+                names.add(element.name.text);
+        }
+    }
+    function isRequireCall(node) {
+        return Boolean(node &&
+            ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            node.expression.text === "require" &&
+            node.arguments.length === 1 &&
+            ts.isStringLiteralLike(node.arguments[0]) &&
+            node.arguments[0].text === moduleName);
+    }
+    for (const statement of source.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (ts.isObjectBindingPattern(declaration.name) &&
+                isRequireCall(declaration.initializer)) {
+                for (const element of declaration.name.elements) {
+                    if (!element.dotDotDotToken &&
+                        ts.isIdentifier(element.name) &&
+                        (element.propertyName?.getText(source) ?? element.name.text) ===
+                            importedName) {
+                        names.add(element.name.text);
+                    }
+                }
+            }
+            if (ts.isIdentifier(declaration.name) &&
+                declaration.initializer &&
+                ts.isPropertyAccessExpression(declaration.initializer) &&
+                declaration.initializer.name.text === importedName &&
+                isRequireCall(declaration.initializer.expression)) {
+                names.add(declaration.name.text);
+            }
+        }
+    }
+    return names;
+}
+function rootIdentifier(expression) {
+    let current = expression;
+    while (true) {
+        if (ts.isCallExpression(current) ||
+            ts.isPropertyAccessExpression(current)) {
+            current = current.expression;
+            continue;
+        }
+        if (ts.isParenthesizedExpression(current) ||
+            ts.isAsExpression(current) ||
+            ts.isTypeAssertionExpression(current) ||
+            ts.isNonNullExpression(current) ||
+            ts.isSatisfiesExpression(current)) {
+            current = current.expression;
+            continue;
+        }
+        break;
+    }
+    if (ts.isNewExpression(current))
+        current = current.expression;
+    return ts.isIdentifier(current) ? current : undefined;
+}
+function registrationChain(app, expression, statement, representedByAppType) {
+    const calls = [];
+    function visit(current) {
+        if (ts.isParenthesizedExpression(current) ||
+            ts.isAsExpression(current) ||
+            ts.isTypeAssertionExpression(current) ||
+            ts.isNonNullExpression(current) ||
+            ts.isSatisfiesExpression(current)) {
+            visit(current.expression);
+            return;
+        }
+        if (!ts.isCallExpression(current) ||
+            !ts.isPropertyAccessExpression(current.expression))
+            return;
+        visit(current.expression.expression);
+        calls.push({
+            app,
+            method: current.expression.name.text,
+            methodNode: current.expression.name,
+            call: current,
+            statement,
+            representedByAppType,
+        });
+    }
+    visit(expression);
+    return calls;
+}
+function containsNamedCall(node, names, method) {
+    let matched = false;
+    function visit(current) {
+        if (matched)
+            return;
+        if (ts.isCallExpression(current)) {
+            const root = rootIdentifier(current.expression);
+            if (!method &&
+                ts.isIdentifier(current.expression) &&
+                names.has(current.expression.text))
+                matched = true;
+            if (method &&
+                ts.isPropertyAccessExpression(current.expression) &&
+                current.expression.name.text === method &&
+                root &&
+                names.has(root.text)) {
+                matched = true;
+            }
+        }
+        ts.forEachChild(current, visit);
+    }
+    visit(node);
+    return matched;
+}
+function isExportedAppType(statement, app) {
+    if (!ts.isTypeAliasDeclaration(statement))
+        return false;
+    if (!statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword))
+        return false;
+    const type = statement.type;
+    return (ts.isTypeQueryNode(type) &&
+        ts.isIdentifier(type.exprName) &&
+        type.exprName.text === app);
+}
+function isHonoInitializer(expression, honoNames) {
+    if (!expression)
+        return false;
+    const root = rootIdentifier(expression);
+    return Boolean(root && honoNames.has(root.text));
+}
+function hasThenReturningHonoResponse(expression, contextName) {
+    let matched = false;
+    function containsResponse(current) {
+        if (ts.isCallExpression(current) &&
+            ts.isPropertyAccessExpression(current.expression) &&
+            ts.isIdentifier(current.expression.expression) &&
+            current.expression.expression.text === contextName &&
+            ["body", "html", "json", "text"].includes(current.expression.name.text)) {
+            return true;
+        }
+        return current.getChildren().some(containsResponse);
+    }
+    function visit(current) {
+        if (matched)
+            return;
+        if (ts.isCallExpression(current) &&
+            ts.isPropertyAccessExpression(current.expression) &&
+            current.expression.name.text === "then" &&
+            !current.typeArguments?.length &&
+            current.arguments.some(containsResponse)) {
+            matched = true;
+            return;
+        }
+        ts.forEachChild(current, visit);
+    }
+    visit(expression);
+    return matched;
+}
+function returnedExpressions(handler) {
+    if (!ts.isBlock(handler.body))
+        return [handler.body];
+    const expressions = [];
+    function visit(node) {
+        if (ts.isFunctionLike(node) && node !== handler)
+            return;
+        if (ts.isReturnStatement(node) && node.expression) {
+            expressions.push(node.expression);
+            return;
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(handler.body);
+    return expressions;
+}
+function literalPath(call) {
+    const first = call.arguments[0];
+    return first && ts.isStringLiteralLike(first) ? first.text : undefined;
+}
+function pathsOverlap(middlewarePath, routePath) {
+    if (!middlewarePath || middlewarePath === "*" || middlewarePath === "/*")
+        return true;
+    if (!routePath)
+        return false;
+    const prefix = middlewarePath.replace(/\*+$/, "").replace(/\/$/, "");
+    return routePath === prefix || routePath.startsWith(`${prefix}/`);
+}
+function usesTimeout(call, timeoutNames) {
+    return call.arguments.some((argument) => containsNamedCall(argument, timeoutNames));
+}
+export async function scanSourceFile(root, absoluteFile) {
+    const text = await readFile(absoluteFile, "utf8");
+    const scriptKind = absoluteFile.endsWith("x")
+        ? ts.ScriptKind.TSX
+        : ts.ScriptKind.TS;
+    const source = ts.createSourceFile(absoluteFile, text, ts.ScriptTarget.Latest, true, scriptKind);
+    const file = path.relative(root, absoluteFile) || path.basename(absoluteFile);
+    const diagnostics = [];
+    const honoNames = importedNames(source, "hono", "Hono");
+    if (honoNames.size === 0)
+        return diagnostics;
+    const timeoutNames = importedNames(source, "hono/timeout", "timeout");
+    const streamNames = new Set([
+        ...importedNames(source, "hono/streaming", "stream"),
+        ...importedNames(source, "hono/streaming", "streamSSE"),
+    ]);
+    const apps = new Map();
+    const calls = [];
+    for (const statement of source.statements) {
+        if (ts.isVariableStatement(statement)) {
+            for (const declaration of statement.declarationList.declarations) {
+                if (ts.isIdentifier(declaration.name) &&
+                    isHonoInitializer(declaration.initializer, honoNames)) {
+                    apps.set(declaration.name.text, declaration);
+                }
+            }
+        }
+    }
+    for (const statement of source.statements) {
+        if (ts.isVariableStatement(statement)) {
+            for (const declaration of statement.declarationList.declarations) {
+                if (ts.isIdentifier(declaration.name) &&
+                    declaration.initializer &&
+                    apps.has(declaration.name.text)) {
+                    calls.push(...registrationChain(declaration.name.text, declaration.initializer, statement, !(declaration.type &&
+                        ts.isTypeReferenceNode(declaration.type) &&
+                        ts.isIdentifier(declaration.type.typeName) &&
+                        honoNames.has(declaration.type.typeName.text))));
+                }
+            }
+        }
+        if (ts.isExpressionStatement(statement)) {
+            const root = rootIdentifier(statement.expression);
+            if (root && apps.has(root.text)) {
+                calls.push(...registrationChain(root.text, statement.expression, statement, false));
+            }
+        }
+    }
+    for (const [app, declaration] of apps) {
+        const typeExport = source.statements.find((statement) => isExportedAppType(statement, app));
+        if (typeExport) {
+            const untracked = calls.filter((call) => call.app === app &&
+                routeMethods.has(call.method) &&
+                !call.representedByAppType);
+            if (untracked.length > 0) {
+                diagnostics.push(diagnostic(source, file, untracked[0].methodNode, {
+                    ruleId: "HD001",
+                    severity: "error",
+                    message: `${untracked.length} route registration${untracked.length === 1 ? " is" : "s are"} not represented by the exported typeof ${app}.`,
+                    help: `Chain registrations into the variable whose type is exported, or export typeof the final chained value.`,
+                }));
+            }
+        }
+        const appCalls = calls.filter((call) => call.app === app);
+        let sawRoute = false;
+        for (const call of appCalls) {
+            if (routeMethods.has(call.method))
+                sawRoute = true;
+            if (call.method === "use" && sawRoute) {
+                const first = call.call.arguments[0];
+                const global = !first ||
+                    !ts.isStringLiteralLike(first) ||
+                    first.text === "*" ||
+                    first.text === "/*";
+                if (global) {
+                    diagnostics.push(diagnostic(source, file, call.methodNode, {
+                        ruleId: "HD003",
+                        severity: "warning",
+                        message: "A global middleware is registered after a route and will not wrap earlier routes.",
+                        help: "Move global app.use(...) registrations before the first route, or use an explicit path when partial coverage is intentional.",
+                    }));
+                }
+            }
+        }
+        const timeouts = appCalls.filter((call) => call.method === "use" && usesTimeout(call.call, timeoutNames));
+        for (const route of appCalls.filter((call) => routeMethods.has(call.method))) {
+            if (streamNames.size === 0 ||
+                !route.call.arguments.some((argument) => containsNamedCall(argument, streamNames)))
+                continue;
+            const conflicting = timeouts.find((middleware) => middleware.call.expression.name.getStart(source) <
+                route.call.expression.name.getStart(source) &&
+                pathsOverlap(literalPath(middleware.call), literalPath(route.call)));
+            if (conflicting) {
+                diagnostics.push(diagnostic(source, file, route.methodNode, {
+                    ruleId: "HD004",
+                    severity: "error",
+                    message: "This streaming route is covered by Hono's timeout middleware, which does not support streams.",
+                    help: "Exclude the streaming path from timeout middleware and close the stream explicitly when needed.",
+                }));
+            }
+        }
+    }
+    function visit(node) {
+        if (ts.isCallExpression(node) &&
+            ts.isPropertyAccessExpression(node.expression)) {
+            const method = node.expression.name.text;
+            const root = rootIdentifier(node.expression);
+            if (routeMethods.has(method) &&
+                root &&
+                (apps.has(root.text) || honoNames.has(root.text))) {
+                for (const argument of node.arguments) {
+                    if ((ts.isArrowFunction(argument) ||
+                        ts.isFunctionExpression(argument)) &&
+                        argument.parameters[0] &&
+                        ts.isIdentifier(argument.parameters[0].name) &&
+                        returnedExpressions(argument).some((expression) => hasThenReturningHonoResponse(expression, argument.parameters[0].name.text))) {
+                        diagnostics.push(diagnostic(source, file, argument, {
+                            ruleId: "HD002",
+                            severity: "error",
+                            message: "A Hono handler returns a .then() chain containing a response, so RPC output can be inferred as unknown.",
+                            help: "Use an async handler with await, or annotate the Promise callback with TypedResponse.",
+                        }));
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(source);
+    return diagnostics;
+}

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+export type Severity = "warning" | "error";
+export type RuleId = "HD001" | "HD002" | "HD003" | "HD004" | "HD005";
+export interface Diagnostic {
+    ruleId: RuleId;
+    severity: Severity;
+    message: string;
+    file: string;
+    line: number;
+    column: number;
+    help: string;
+}
+export interface ScanOptions {
+    cwd?: string;
+}
+export interface ScanResult {
+    root: string;
+    filesScanned: number;
+    packagesScanned: number;
+    diagnostics: Diagnostic[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/docs/release-readiness.md

@@ -0,0 +1,41 @@
+# Release readiness — 2026-09-05
+
+Version 0.1.0 is locally prepared for its first release. Publication is explicitly
+deferred by the owner. This is not a claim that remote CI, npm publication or
+Trusted Publishing has succeeded.
+
+## Verified locally
+
+- `pnpm release:check`: formatting, type checking, 36 tests, coverage, build,
+  package-content checks and npm publish dry-run passed.
+- Statement coverage: 93.87%; branch coverage: 88.02%.
+- Hono 4.13.5 runtime middleware-order tests and compile-time RPC contracts are
+  included in the checks. No deployed application is needed by this static tool.
+- The npm archive installed in a fresh temporary consumer with only the package
+  and its runtime dependency, without lifecycle scripts or repository links.
+- Installed CLI/API smoke passed on Node 20.20.2, 22.14.0 and 24.20.0: version,
+  positive HD001 detection, a clean chained-route fixture, JSON, SARIF, public
+  `scan` import, exit 1 for findings, exit 0 with `--fail-on none`, and exit 2
+  for a missing directory. The installed executable link also returned 0.1.0.
+- A separate intentionally incomplete package was rejected by the package
+  checker for a README link to an unpackaged rules file (exit 1).
+- Installation audit reported zero vulnerabilities at the time of the check.
+
+## Release actions still deferred
+
+The local repository has no configured remote. Read-only checks of the expected
+GitHub repository and npm package returned 404 on this date; this is not a
+reservation of either name. Recheck availability when publishing.
+
+Follow [the release procedure](../RELEASING.md) when the owner is ready. Creating
+the remote, pushing changes, first interactive publication, configuring npm
+Trusted Publishing, and verifying the public registry artifact remain undone.
+The first interactive publication may require the owner's WebAuthn approval.
+
+## Adoption is not yet validated
+
+Passing these checks establishes local technical readiness, not usefulness in
+every Hono codebase. Cross-file composition remains outside the documented
+scope. External maintainer feedback and retained real-project integrations in
+[the validation plan](validation.md) are post-release evidence gates and have
+not been satisfied by local tests or download counts.

package/docs/rules.md

@@ -0,0 +1,34 @@
+# Rule details
+
+## HD001 — exported Hono type misses registrations
+
+Hono's [RPC guide](https://hono.dev/docs/guides/rpc) and [testing guide](https://hono.dev/docs/guides/testing) explain that client and test helpers infer routes from the type returned by chained calls. TypeScript does not mutate the declared type of a variable when a later method call returns a more specific Hono type.
+
+```ts
+// Reported
+const app = new Hono();
+app.get("/users", handler);
+export type AppType = typeof app;
+
+// Preferred
+const app = new Hono().get("/users", handler);
+export type AppType = typeof app;
+```
+
+## HD002 — Promise chain erases RPC response inference
+
+Hono's [RPC guide](https://hono.dev/docs/guides/rpc) documents a TypeScript inference limitation for handlers that directly return `.then()` chains. Prefer an `async` handler with `await`, or explicitly annotate the callback with `TypedResponse`.
+
+## HD003 — global middleware registered after routes
+
+Hono's [middleware guide](https://hono.dev/docs/guides/middleware) specifies that middleware executes according to registration order. A global `app.use(...)`, `app.use("*", ...)`, or `app.use("/*", ...)` registered after a route does not wrap that earlier route.
+
+Path-specific late middleware is not reported because limiting middleware to later routes can be intentional.
+
+## HD004 — timeout middleware covers a stream
+
+Hono's [timeout middleware documentation](https://hono.dev/docs/middleware/builtin/timeout) says the middleware does not support streaming responses. The rule reports a conflict only when it can see the timeout registration, streaming route, compatible paths, and ordering in the same file.
+
+## HD005 — Hono version skew
+
+Hono's [RPC troubleshooting guidance](https://hono.dev/docs/guides/rpc#troubleshooting) recommends matching backend and frontend versions when sharing RPC types. The rule first checks installed `node_modules/hono/package.json` files. If dependencies are not installed, different declared ranges are reported as a warning rather than a confirmed error.

package/docs/validation.md

@@ -0,0 +1,27 @@
+# Validation plan
+
+`hono-doctor` is for TypeScript teams that use Hono RPC, `hc`, or `testClient` and want deterministic feedback before CI or production. It is not a general Hono linter, formatter, runtime monitor, or security scanner.
+
+## Initial hypothesis
+
+The package is useful if it finds documented Hono mistakes in real repositories with fewer false positives than a broad lint rule, and maintainers choose to keep it in their workflow.
+
+The first implementation is deliberately limited to five statically verifiable rules. Cross-file route reconstruction, automatic rewriting, editor extensions, and hosted reporting are out of scope.
+
+## Time box
+
+- Initial implementation: 2–3 focused days.
+- Hardening and real-repository validation: up to 10 additional days.
+- After release, keep maintenance narrow until there is adoption evidence.
+
+## Evidence gates
+
+Within 30 days of the first release, seek all of the following:
+
+- runs against at least three independently maintained Hono repositories;
+- at least one confirmed finding or false-positive report from an external maintainer;
+- at least one external repository that keeps `hono-doctor` in a script, CI workflow, or dependency.
+
+npm downloads alone do not satisfy these gates: installs can come from CI, mirrors, automated scanners, or repeated downloads by the same user.
+
+If no external repository keeps the tool after targeted validation, freeze the package at a stable low-maintenance version instead of adding speculative rules. Expand scope only when a reproducible issue or documented Hono contract justifies it.

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "hono-doctor",
+  "version": "0.1.0",
+  "description": "Catch Hono RPC typing, middleware ordering, and streaming configuration mistakes.",
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "hono-doctor": "dist/cli.js"
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTING.md",
+    "RELEASING.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepack": "pnpm build",
+    "release:check": "pnpm format:check && pnpm typecheck && pnpm test:coverage && pnpm build && pnpm test:package && npm publish --dry-run --cache .cache/npm",
+    "test:package": "node scripts/check-package.mjs",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "hono",
+    "hono-rpc",
+    "static-analysis",
+    "doctor",
+    "middleware",
+    "typescript"
+  ],
+  "author": "wangxpych",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wangxpych/hono-doctor.git"
+  },
+  "homepage": "https://github.com/wangxpych/hono-doctor#readme",
+  "bugs": {
+    "url": "https://github.com/wangxpych/hono-doctor/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@10.34.5",
+  "dependencies": {
+    "typescript": ">=5.6 <7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "@vitest/coverage-v8": "4.1.11",
+    "hono": "4.13.5",
+    "prettier": "^3.9.6",
+    "typescript": "6.0.3",
+    "vitest": "^4.1.11"
+  }
+}