codex-plugin-doctor 0.13.0 → 0.15.0

package/README.md

@@ -176,10 +176,16 @@ Run these from a Codex plugin package root:
 codex-plugin-doctor --version
 codex-plugin-doctor self-test
 codex-plugin-doctor doctor
+codex-plugin-doctor doctor npm codex-plugin-doctor
+codex-plugin-doctor doctor npm codex-plugin-doctor --json --output npm-preinstall.json
+codex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin
+codex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin --json --output risk-diff.json
 codex-plugin-doctor doctor recommend .
 codex-plugin-doctor doctor recommend . --json --output recommendations.json
 codex-plugin-doctor doctor trust .
 codex-plugin-doctor doctor trust . --json --output trust-score.json
+codex-plugin-doctor doctor perf .
+codex-plugin-doctor doctor perf . --json --output perf.json
 codex-plugin-doctor doctor export --bundle .
 codex-plugin-doctor doctor export --bundle . --output doctor-bundle.json
 codex-plugin-doctor doctor snapshot
@@ -190,6 +196,8 @@ codex-plugin-doctor doctor --update-check
 codex-plugin-doctor audit --installed
 codex-plugin-doctor audit --installed --security --compat
 codex-plugin-doctor audit --installed --security --compat --json --output local-audit.json
+codex-plugin-doctor audit --installed --security --compat --cache
+codex-plugin-doctor audit --installed --changed --cache
 codex-plugin-doctor mcp .
 codex-plugin-doctor mcp . --json
 codex-plugin-doctor mcp . --json --output mcp-doctor.json
@@ -246,9 +254,9 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `self-test` runs the bundled runtime-complete sample through static validation, runtime MCP probes, and the compatibility scorecard. It is the fastest post-install check after `npm install -g codex-plugin-doctor`.
 
-`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
+`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
 
-`audit --installed` runs a local ecosystem audit against every discovered Codex plugin in the installed plugin cache. Add `--security` to include security scorecards, `--compat` to include the all-client compatibility matrix, and `--json --output local-audit.json` when you want a shareable machine-readable report.
+`audit --installed` runs a local ecosystem audit against every discovered Codex plugin in the installed plugin cache. Add `--security` to include security scorecards, `--compat` to include the all-client compatibility matrix, and `--json --output local-audit.json` when you want a shareable machine-readable report. Add `--cache` to reuse unchanged plugin results between runs; add `--changed` to only report plugins whose fingerprint changed since the last cached audit. Use `--cache-file path/to/audit-cache.json` when CI or scripted runs need an explicit cache location.
 
 `--policy codex-publish|mcp-strict|security` applies opinionated gates without requiring a local `.codex-doctor.json`. `codex-publish` fails warnings and enables runtime probes for release checks, `mcp-strict` does the same for MCP-heavy packages, and `security` fails warning-level security findings so advisory risks can block a local audit or CI gate.
 

package/dist/audit/ecosystem-audit-cache.d.ts

@@ -0,0 +1,15 @@
+import type { EcosystemAuditPluginResult } from "./ecosystem-audit.js";
+import type { InstalledPlugin } from "../core/discover-installed-plugins.js";
+export interface EcosystemAuditCacheEntry {
+    fingerprint: string;
+    cachedAt: string;
+    result: EcosystemAuditPluginResult;
+}
+export interface EcosystemAuditCacheFile {
+    schemaVersion: "1.0.0";
+    entries: Record<string, EcosystemAuditCacheEntry>;
+}
+export declare function resolveEcosystemAuditCachePath(env?: Record<string, string | undefined>, cachePath?: string | null): string;
+export declare function loadEcosystemAuditCache(cachePath: string): Promise<EcosystemAuditCacheFile>;
+export declare function writeEcosystemAuditCache(cachePath: string, cache: EcosystemAuditCacheFile): Promise<void>;
+export declare function fingerprintInstalledPlugin(plugin: InstalledPlugin): Promise<string>;

package/dist/audit/ecosystem-audit-cache.js

@@ -0,0 +1,78 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const skippedDirectories = new Set([
+    ".git",
+    "coverage",
+    "dist",
+    "node_modules",
+    "validation-artifacts-local",
+    "validation-sessions"
+]);
+export function resolveEcosystemAuditCachePath(env = process.env, cachePath) {
+    if (cachePath) {
+        return path.resolve(cachePath);
+    }
+    const codexHome = env.CODEX_HOME
+        ? path.resolve(env.CODEX_HOME)
+        : path.join(os.homedir(), ".codex");
+    return path.join(codexHome, "plugin-doctor", "audit-cache.json");
+}
+export async function loadEcosystemAuditCache(cachePath) {
+    try {
+        const parsed = JSON.parse(await readFile(cachePath, "utf8"));
+        if (parsed.schemaVersion === "1.0.0" && parsed.entries && typeof parsed.entries === "object") {
+            return {
+                schemaVersion: "1.0.0",
+                entries: parsed.entries
+            };
+        }
+    }
+    catch {
+        // Invalid or missing cache files are treated as cold caches.
+    }
+    return {
+        schemaVersion: "1.0.0",
+        entries: {}
+    };
+}
+export async function writeEcosystemAuditCache(cachePath, cache) {
+    await mkdir(path.dirname(cachePath), { recursive: true });
+    await writeFile(cachePath, JSON.stringify(cache, null, 2), "utf8");
+}
+async function walkFingerprintEntries(rootPath, currentPath = rootPath) {
+    const entries = await readdir(currentPath, { withFileTypes: true });
+    const fingerprintEntries = [];
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        const entryPath = path.join(currentPath, entry.name);
+        if (entry.isDirectory()) {
+            if (skippedDirectories.has(entry.name)) {
+                continue;
+            }
+            fingerprintEntries.push(...(await walkFingerprintEntries(rootPath, entryPath)));
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        const details = await stat(entryPath);
+        const relativePath = path.relative(rootPath, entryPath).replace(/\\/g, "/");
+        fingerprintEntries.push(`${relativePath}\t${details.size}\t${Math.trunc(details.mtimeMs)}`);
+    }
+    return fingerprintEntries;
+}
+export async function fingerprintInstalledPlugin(plugin) {
+    const hash = createHash("sha256");
+    hash.update(plugin.name);
+    hash.update("\n");
+    hash.update(plugin.version ?? "");
+    hash.update("\n");
+    hash.update(plugin.relativePath);
+    hash.update("\n");
+    for (const entry of await walkFingerprintEntries(plugin.rootPath)) {
+        hash.update(entry);
+        hash.update("\n");
+    }
+    return hash.digest("hex");
+}

package/dist/audit/ecosystem-audit.d.ts

@@ -9,12 +9,18 @@ export interface EcosystemAuditOptions {
     includeSecurity?: boolean;
     includeCompatibility?: boolean;
     failOnWarnings?: boolean;
+    cache?: {
+        enabled?: boolean;
+        changedOnly?: boolean;
+        cachePath?: string | null;
+    };
     validatePlugin: (targetPath: string) => Promise<CheckResult>;
 }
 export interface EcosystemAuditPluginResult {
     plugin: InstalledPlugin;
     status: "pass" | "warn" | "fail";
     validation: CheckResult;
+    cached?: boolean;
     security?: SecurityAudit;
     compatibility?: CompatibilityMatrix;
 }
@@ -27,6 +33,8 @@ export interface EcosystemAuditReport {
         pass: number;
         warn: number;
         fail: number;
+        cached: number;
+        skippedUnchanged: number;
     };
     plugins: EcosystemAuditPluginResult[];
     priorityActions: string[];

package/dist/audit/ecosystem-audit.js

@@ -1,6 +1,9 @@
+import path from "node:path";
 import { buildCompatibilityMatrix, matrixExitCode } from "../compatibility/compatibility-matrix.js";
 import { discoverInstalledPlugins, filterInstalledPlugins } from "../core/discover-installed-plugins.js";
 import { buildSecurityAudit } from "../security/security-audit.js";
+import { packageVersion } from "../version.js";
+import { fingerprintInstalledPlugin, loadEcosystemAuditCache, resolveEcosystemAuditCachePath, writeEcosystemAuditCache } from "./ecosystem-audit-cache.js";
 function mergeStatus(statuses) {
     if (statuses.includes("fail")) {
         return "fail";
@@ -19,12 +22,23 @@ function compatibilityStatus(matrix) {
     }
     return matrix.results.some((result) => result.status === "warn") ? "warn" : "pass";
 }
-function summarizePlugins(plugins) {
+function cacheKeyForPlugin(plugin, options) {
+    return [
+        path.resolve(plugin.rootPath).toLowerCase(),
+        `version=${packageVersion}`,
+        `security=${Boolean(options.includeSecurity)}`,
+        `compatibility=${Boolean(options.includeCompatibility)}`,
+        `failOnWarnings=${Boolean(options.failOnWarnings)}`
+    ].join("\n");
+}
+function summarizePlugins(plugins, skippedUnchanged) {
     return {
         totalPlugins: plugins.length,
         pass: plugins.filter((plugin) => plugin.status === "pass").length,
         warn: plugins.filter((plugin) => plugin.status === "warn").length,
-        fail: plugins.filter((plugin) => plugin.status === "fail").length
+        fail: plugins.filter((plugin) => plugin.status === "fail").length,
+        cached: plugins.filter((plugin) => plugin.cached).length,
+        skippedUnchanged
     };
 }
 function buildPriorityActions(plugins) {
@@ -58,7 +72,35 @@ export async function buildEcosystemAudit(options) {
         platform: options.platform
     };
     const plugins = [];
+    const cacheEnabled = Boolean(options.cache?.enabled);
+    const changedOnly = Boolean(options.cache?.changedOnly);
+    const cachePath = cacheEnabled
+        ? resolveEcosystemAuditCachePath(options.env, options.cache?.cachePath)
+        : null;
+    const cache = cachePath
+        ? await loadEcosystemAuditCache(cachePath)
+        : null;
+    let skippedUnchanged = 0;
     for (const plugin of installedPlugins) {
+        const cacheKey = cacheKeyForPlugin(plugin, options);
+        const fingerprint = cache
+            ? await fingerprintInstalledPlugin(plugin)
+            : null;
+        const cachedEntry = cache && fingerprint
+            ? cache.entries[cacheKey]
+            : undefined;
+        if (cachedEntry && cachedEntry.fingerprint === fingerprint) {
+            if (changedOnly) {
+                skippedUnchanged += 1;
+                continue;
+            }
+            plugins.push({
+                ...cachedEntry.result,
+                plugin,
+                cached: true
+            });
+            continue;
+        }
         const validation = await options.validatePlugin(plugin.rootPath);
         const security = options.includeSecurity
             ? await buildSecurityAudit(plugin.rootPath)
@@ -74,15 +116,26 @@ export async function buildEcosystemAudit(options) {
         const status = options.failOnWarnings && rawStatus === "warn"
             ? "fail"
             : rawStatus;
-        plugins.push({
+        const result = {
             plugin,
             status,
             validation,
             ...(security ? { security } : {}),
             ...(compatibility ? { compatibility } : {})
-        });
+        };
+        plugins.push(result);
+        if (cache && fingerprint) {
+            cache.entries[cacheKey] = {
+                fingerprint,
+                cachedAt: new Date().toISOString(),
+                result
+            };
+        }
+    }
+    if (cache && cachePath) {
+        await writeEcosystemAuditCache(cachePath, cache);
     }
-    const summary = summarizePlugins(plugins);
+    const summary = summarizePlugins(plugins, skippedUnchanged);
     const status = summary.fail > 0
         ? "fail"
         : summary.warn > 0
@@ -106,7 +159,8 @@ export function renderEcosystemAudit(report) {
         "=====================",
         `Status: ${report.status.toUpperCase()}`,
         `Installed plugins: ${report.summary.totalPlugins}`,
-        `Summary: ${report.summary.fail} fail, ${report.summary.warn} warn, ${report.summary.pass} pass`
+        `Summary: ${report.summary.fail} fail, ${report.summary.warn} warn, ${report.summary.pass} pass`,
+        `Cache: ${report.summary.cached} reused, ${report.summary.skippedUnchanged} skipped unchanged`
     ];
     if (report.plugins.length === 0) {
         lines.push("", "No installed Codex plugins found.");
@@ -126,6 +180,9 @@ export function renderEcosystemAudit(report) {
                 .join(", ");
             lines.push(`  Compatibility: ${compatibilitySummary}`);
         }
+        if (item.cached) {
+            lines.push("  Cache: reused");
+        }
     }
     if (report.priorityActions.length > 0) {
         lines.push("", "Priority Actions", "----------------");

package/dist/core/doctor-export-bundle.d.ts

@@ -1,8 +1,8 @@
-import { type CompatibilityEnvironment, type CompatibilityMatrix } from "../compatibility/compatibility-matrix.js";
+import type { CompatibilityEnvironment, CompatibilityMatrix } from "../compatibility/compatibility-matrix.js";
 import type { JsonReport } from "../domain/types.js";
-import { type DoctorRecommendationsReport } from "./doctor-recommendations.js";
-import { type SecurityAudit } from "../security/security-audit.js";
-import { type TrustScoreReport } from "../security/trust-score.js";
+import type { DoctorRecommendationsReport } from "./doctor-recommendations.js";
+import type { SecurityAudit } from "../security/security-audit.js";
+import type { TrustScoreReport } from "../security/trust-score.js";
 export interface DoctorExportBundle {
     schemaVersion: "1.0.0";
     generatedAt: string;

package/dist/core/doctor-export-bundle.js

@@ -1,12 +1,4 @@
-import path from "node:path";
-import { buildCompatibilityMatrix } from "../compatibility/compatibility-matrix.js";
-import { applyDoctorConfig, loadDoctorConfig } from "./doctor-config.js";
-import { buildJsonReport } from "../reporting/render-json-report.js";
-import { buildDoctorRecommendations } from "./doctor-recommendations.js";
-import { buildSecurityAudit } from "../security/security-audit.js";
-import { buildTrustScore } from "../security/trust-score.js";
-import { validatePlugin } from "./validate-plugin.js";
-import { packageVersion } from "../version.js";
+import { buildDoctorExportBundleFromAnalysis, buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./package-analysis.js";
 function redactString(value) {
     return value
         .replace(/sk-[A-Za-z0-9_-]{12,}/g, "[REDACTED_SECRET]")
@@ -30,27 +22,8 @@ function redactValue(value) {
     return value;
 }
 export async function buildDoctorExportBundle(targetPath, environment = {}) {
-    const rootPath = path.resolve(targetPath);
-    const [rawValidation, security, compatibility, recommendations, trust] = await Promise.all([
-        validatePlugin(rootPath),
-        buildSecurityAudit(rootPath),
-        buildCompatibilityMatrix(rootPath, environment),
-        buildDoctorRecommendations(rootPath, { environment }),
-        buildTrustScore(rootPath)
-    ]);
-    const validation = applyDoctorConfig(rawValidation, await loadDoctorConfig(rootPath));
-    return {
-        schemaVersion: "1.0.0",
-        generatedAt: new Date().toISOString(),
-        kind: "doctor.export.bundle",
-        version: packageVersion,
-        targetPath: rootPath,
-        validation: buildJsonReport(validation, { runtimeProbeEnabled: false }),
-        security,
-        compatibility,
-        recommendations,
-        trust
-    };
+    const analysis = await buildPackageAnalysis(targetPath, { environment });
+    return buildDoctorExportBundleFromAnalysis(analysis, buildDoctorRecommendationsFromAnalysis(analysis));
 }
 export function renderDoctorExportBundleJson(bundle) {
     return JSON.stringify(redactValue(bundle), null, 2);

package/dist/core/doctor-recommendations.d.ts

@@ -1,6 +1,6 @@
-import { type CompatibilityEnvironment } from "../compatibility/compatibility-matrix.js";
+import type { CompatibilityEnvironment } from "../compatibility/compatibility-matrix.js";
 import type { CheckResult } from "../domain/types.js";
-import { type SecurityAudit } from "../security/security-audit.js";
+import type { SecurityAudit } from "../security/security-audit.js";
 export type RecommendationPriority = "blocker" | "high" | "medium" | "info";
 export type RecommendationCategory = "validation" | "security" | "compatibility" | "release";
 export interface DoctorRecommendationAction {

package/dist/core/doctor-recommendations.js

@@ -1,139 +1,9 @@
-import path from "node:path";
-import { buildCompatibilityMatrix, matrixExitCode } from "../compatibility/compatibility-matrix.js";
-import { applyDoctorConfig, loadDoctorConfig } from "./doctor-config.js";
-import { buildSecurityAudit } from "../security/security-audit.js";
-import { validatePlugin } from "./validate-plugin.js";
-const priorityRank = {
-    blocker: 0,
-    high: 1,
-    medium: 2,
-    info: 3
-};
-function countActions(actions) {
-    return {
-        blocker: actions.filter((action) => action.priority === "blocker").length,
-        high: actions.filter((action) => action.priority === "high").length,
-        medium: actions.filter((action) => action.priority === "medium").length,
-        info: actions.filter((action) => action.priority === "info").length
-    };
-}
-function priorityForFinding(finding) {
-    if (finding.severity === "fail") {
-        return "blocker";
-    }
-    return finding.id.startsWith("plugin.security.") ? "high" : "medium";
-}
-function categoryForFinding(finding) {
-    return finding.id.startsWith("plugin.security.") ? "security" : "validation";
-}
-function commandForCategory(category, targetPath) {
-    if (category === "security") {
-        return `codex-plugin-doctor security ${targetPath} --scorecard`;
-    }
-    if (category === "compatibility") {
-        return `codex-plugin-doctor compat ${targetPath} --all --scorecard`;
-    }
-    return `codex-plugin-doctor check ${targetPath} --explain`;
-}
-function actionFromFinding(finding, targetPath) {
-    const category = categoryForFinding(finding);
-    return {
-        priority: priorityForFinding(finding),
-        category,
-        findingId: finding.id,
-        title: finding.message,
-        reason: finding.impact,
-        nextCommand: commandForCategory(category, targetPath)
-    };
-}
-function dedupeActions(actions) {
-    const seen = new Set();
-    return actions.filter((action) => {
-        const key = `${action.category}\n${action.findingId ?? action.title}\n${action.reason}`;
-        if (seen.has(key)) {
-            return false;
-        }
-        seen.add(key);
-        return true;
-    });
-}
-function actionsFromCompatibility(matrix, targetPath) {
-    return matrix.results
-        .filter((result) => result.status === "fail")
-        .map((result) => ({
-        priority: "high",
-        category: "compatibility",
-        title: `${result.client} compatibility failed.`,
-        reason: result.summary,
-        nextCommand: commandForCategory("compatibility", targetPath)
-    }));
-}
-function sortActions(actions) {
-    return [...actions].sort((left, right) => {
-        const priorityDelta = priorityRank[left.priority] - priorityRank[right.priority];
-        if (priorityDelta !== 0) {
-            return priorityDelta;
-        }
-        return left.category.localeCompare(right.category);
-    });
-}
+import { buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./package-analysis.js";
 export async function buildDoctorRecommendations(targetPath, options = {}) {
-    const rootPath = path.resolve(targetPath);
-    const runCheck = options.runCheck ?? validatePlugin;
-    const [rawValidation, security, compatibility] = await Promise.all([
-        runCheck(rootPath),
-        buildSecurityAudit(rootPath),
-        buildCompatibilityMatrix(rootPath, options.environment ?? {})
-    ]);
-    const validation = applyDoctorConfig(rawValidation, await loadDoctorConfig(rootPath));
-    const actions = sortActions(dedupeActions([
-        ...validation.findings.map((finding) => actionFromFinding(finding, rootPath)),
-        ...security.findings.map((finding) => actionFromFinding(finding, rootPath)),
-        ...actionsFromCompatibility(compatibility, rootPath)
-    ]));
-    const finalActions = actions.length > 0
-        ? actions
-        : [
-            {
-                priority: "info",
-                category: "release",
-                title: "No blocker actions.",
-                reason: "The package has no validation, security, or compatibility blockers in this recommendation pass.",
-                nextCommand: `codex-plugin-doctor check ${rootPath} --profile publish`
-            }
-        ];
-    const status = finalActions.some((action) => action.priority === "blocker")
-        ? "fail"
-        : finalActions.some((action) => action.priority === "high" || action.priority === "medium")
-            ? "warn"
-            : "pass";
-    return {
-        schemaVersion: "1.0.0",
-        generatedAt: new Date().toISOString(),
-        targetPath: rootPath,
-        status,
-        exitCode: status === "fail" ? 1 : 0,
-        summary: {
-            actionCounts: countActions(finalActions)
-        },
-        validation: {
-            status: validation.status,
-            findingCount: validation.findings.length
-        },
-        security: {
-            status: security.status,
-            score: security.score,
-            findingCount: security.findings.length
-        },
-        compatibility: {
-            failedClients: matrixExitCode(compatibility) === 1
-                ? compatibility.results
-                    .filter((result) => result.status === "fail")
-                    .map((result) => result.client)
-                : []
-        },
-        actions: finalActions
-    };
+    return buildDoctorRecommendationsFromAnalysis(await buildPackageAnalysis(targetPath, {
+        environment: options.environment,
+        runCheck: options.runCheck
+    }));
 }
 export function renderDoctorRecommendationsJson(report) {
     return JSON.stringify(report, null, 2);

package/dist/core/npm-package-doctor.d.ts

@@ -0,0 +1,33 @@
+import type { CompatibilityEnvironment } from "../compatibility/compatibility-matrix.js";
+import type { JsonReport } from "../domain/types.js";
+import type { SecurityAudit } from "../security/security-audit.js";
+import type { TrustScoreReport } from "../security/trust-score.js";
+import type { DoctorRecommendationsReport } from "./doctor-recommendations.js";
+export interface DoctorNpmPackageReport {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    kind: "doctor.npm";
+    packageSpec: string;
+    package: {
+        name: string | null;
+        version: string | null;
+        fileCount: number | null;
+    };
+    summary: {
+        status: "pass" | "warn" | "fail";
+        exitCode: 0 | 1;
+        safeToInstall: boolean;
+    };
+    validation: JsonReport;
+    security: SecurityAudit;
+    trust: TrustScoreReport;
+    recommendations: DoctorRecommendationsReport;
+}
+export interface BuildDoctorNpmPackageReportOptions {
+    environment?: CompatibilityEnvironment;
+}
+export declare function buildDoctorNpmPackageReport(packageSpec: string, options?: BuildDoctorNpmPackageReportOptions): Promise<DoctorNpmPackageReport>;
+export declare function renderDoctorNpmPackageReportJson(report: DoctorNpmPackageReport): string;
+export declare function renderDoctorNpmPackageReport(report: DoctorNpmPackageReport, options?: {
+    outputPath?: string | null;
+}): string;