codex-plugin-doctor 0.13.0 → 0.15.0

package/dist/core/npm-package-doctor.js

@@ -0,0 +1,173 @@
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { gunzip } from "node:zlib";
+import { buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./package-analysis.js";
+const execFileAsync = promisify(execFile);
+const gunzipAsync = promisify(gunzip);
+function npmCommand() {
+    return "npm";
+}
+function isPathWithinRoot(rootPath, candidatePath) {
+    const relativePath = path.relative(rootPath, candidatePath);
+    return (relativePath === "" ||
+        (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
+}
+function readTarString(buffer, start, length) {
+    const slice = buffer.subarray(start, start + length);
+    const end = slice.indexOf(0);
+    const finalSlice = end === -1 ? slice : slice.subarray(0, end);
+    return finalSlice.toString("utf8").trim();
+}
+function readTarSize(buffer) {
+    const rawSize = readTarString(buffer, 124, 12).replace(/\0/g, "").trim();
+    const parsedSize = Number.parseInt(rawSize, 8);
+    return Number.isFinite(parsedSize) ? parsedSize : 0;
+}
+function isEmptyHeader(header) {
+    return header.every((byte) => byte === 0);
+}
+async function extractTarGz(tarballPath, destinationPath) {
+    const tarBuffer = await gunzipAsync(await readFile(tarballPath));
+    let offset = 0;
+    await mkdir(destinationPath, { recursive: true });
+    while (offset + 512 <= tarBuffer.length) {
+        const header = tarBuffer.subarray(offset, offset + 512);
+        if (isEmptyHeader(header)) {
+            break;
+        }
+        const name = readTarString(header, 0, 100);
+        const prefix = readTarString(header, 345, 155);
+        const entryName = prefix ? `${prefix}/${name}` : name;
+        const size = readTarSize(header);
+        const typeFlag = readTarString(header, 156, 1);
+        const fileStart = offset + 512;
+        const fileEnd = fileStart + size;
+        const targetPath = path.resolve(destinationPath, entryName);
+        if (!isPathWithinRoot(destinationPath, targetPath)) {
+            throw new Error(`Refusing to extract tar entry outside destination: ${entryName}`);
+        }
+        if (typeFlag === "5") {
+            await mkdir(targetPath, { recursive: true });
+        }
+        else if (typeFlag === "" || typeFlag === "0") {
+            await mkdir(path.dirname(targetPath), { recursive: true });
+            await writeFile(targetPath, tarBuffer.subarray(fileStart, fileEnd));
+        }
+        offset = fileStart + Math.ceil(size / 512) * 512;
+    }
+}
+async function directoryExists(targetPath) {
+    try {
+        const details = await stat(targetPath);
+        return details.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function resolvePackageSpecForPack(packageSpec) {
+    const candidatePath = path.resolve(packageSpec);
+    try {
+        await stat(candidatePath);
+        return candidatePath;
+    }
+    catch {
+        return packageSpec;
+    }
+}
+async function packNpmPackage(packageSpec, destinationPath) {
+    const resolvedPackageSpec = await resolvePackageSpecForPack(packageSpec);
+    const { stdout } = await execFileAsync(npmCommand(), [
+        "pack",
+        resolvedPackageSpec,
+        "--json",
+        "--ignore-scripts",
+        "--pack-destination",
+        destinationPath
+    ], {
+        cwd: destinationPath,
+        maxBuffer: 10 * 1024 * 1024,
+        shell: process.platform === "win32"
+    });
+    const packEntries = JSON.parse(stdout);
+    const metadata = packEntries[0];
+    if (!metadata?.filename) {
+        throw new Error(`npm pack did not return a tarball for ${packageSpec}`);
+    }
+    return {
+        tarballPath: path.isAbsolute(metadata.filename)
+            ? metadata.filename
+            : path.join(destinationPath, metadata.filename),
+        metadata
+    };
+}
+export async function buildDoctorNpmPackageReport(packageSpec, options = {}) {
+    const workspacePath = await mkdtemp(path.join(os.tmpdir(), "codex-plugin-doctor-npm-"));
+    try {
+        const { tarballPath, metadata } = await packNpmPackage(packageSpec, workspacePath);
+        const extractPath = path.join(workspacePath, "extract");
+        await extractTarGz(tarballPath, extractPath);
+        const packageRoot = await directoryExists(path.join(extractPath, "package"))
+            ? path.join(extractPath, "package")
+            : extractPath;
+        const analysis = await buildPackageAnalysis(packageRoot, {
+            environment: options.environment
+        });
+        const recommendations = buildDoctorRecommendationsFromAnalysis(analysis);
+        return {
+            schemaVersion: "1.0.0",
+            generatedAt: analysis.generatedAt,
+            kind: "doctor.npm",
+            packageSpec,
+            package: {
+                name: typeof metadata.name === "string" ? metadata.name : null,
+                version: typeof metadata.version === "string" ? metadata.version : null,
+                fileCount: Array.isArray(metadata.files) ? metadata.files.length : null
+            },
+            summary: {
+                status: recommendations.status,
+                exitCode: recommendations.exitCode,
+                safeToInstall: recommendations.status === "pass"
+            },
+            validation: analysis.validationJson,
+            security: analysis.security,
+            trust: analysis.trust,
+            recommendations
+        };
+    }
+    finally {
+        await rm(workspacePath, { recursive: true, force: true });
+    }
+}
+export function renderDoctorNpmPackageReportJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function renderDoctorNpmPackageReport(report, options = {}) {
+    const packageLabel = report.package.name
+        ? `${report.package.name}${report.package.version ? `@${report.package.version}` : ""}`
+        : report.packageSpec;
+    const lines = [
+        "Doctor npm Preinstall Scan",
+        "==========================",
+        `Package: ${packageLabel}`,
+        `Spec: ${report.packageSpec}`,
+        `Status: ${report.summary.status.toUpperCase()}`,
+        `Safe to install: ${report.summary.safeToInstall ? "yes" : "no"}`,
+        `Security: ${report.security.status.toUpperCase()} (${report.security.score}/100)`,
+        `Trust: ${report.trust.status.toUpperCase()} (${report.trust.score}/100)`,
+        `Actions: ${report.recommendations.actions.length}`
+    ];
+    if (options.outputPath) {
+        lines.push(`Output: ${options.outputPath}`);
+    }
+    if (report.recommendations.actions.length > 0) {
+        lines.push("", "Top Actions", "-----------");
+        for (const action of report.recommendations.actions.slice(0, 5)) {
+            lines.push(`[${action.priority.toUpperCase()}] ${action.title}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/core/package-analysis.d.ts

@@ -0,0 +1,28 @@
+import { type CompatibilityEnvironment, type CompatibilityMatrix } from "../compatibility/compatibility-matrix.js";
+import type { CheckResult, JsonReport } from "../domain/types.js";
+import type { DoctorRecommendationsReport } from "./doctor-recommendations.js";
+import type { DoctorExportBundle } from "./doctor-export-bundle.js";
+import { type SecurityAudit } from "../security/security-audit.js";
+import { type TrustScoreReport } from "../security/trust-score.js";
+export interface PackageAnalysis {
+    generatedAt: string;
+    targetPath: string;
+    validation: CheckResult;
+    validationJson: JsonReport;
+    security: SecurityAudit;
+    compatibility: CompatibilityMatrix;
+    trust: TrustScoreReport;
+}
+export type PackageAnalysisStage = "validation" | "doctorConfig" | "security" | "compatibility" | "trust";
+export interface PackageAnalysisTiming {
+    stage: PackageAnalysisStage;
+    durationMs: number;
+}
+export interface PackageAnalysisOptions {
+    environment?: CompatibilityEnvironment;
+    recordTiming?: (timing: PackageAnalysisTiming) => void;
+    runCheck?: (targetPath: string) => Promise<CheckResult>;
+}
+export declare function buildPackageAnalysis(targetPath: string, options?: PackageAnalysisOptions): Promise<PackageAnalysis>;
+export declare function buildDoctorRecommendationsFromAnalysis(analysis: PackageAnalysis): DoctorRecommendationsReport;
+export declare function buildDoctorExportBundleFromAnalysis(analysis: PackageAnalysis, recommendations?: DoctorRecommendationsReport): DoctorExportBundle;

package/dist/core/package-analysis.js

@@ -0,0 +1,180 @@
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { buildCompatibilityMatrix, matrixExitCode } from "../compatibility/compatibility-matrix.js";
+import { applyDoctorConfig, loadDoctorConfig } from "./doctor-config.js";
+import { buildJsonReport } from "../reporting/render-json-report.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";
+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);
+    });
+}
+async function measureStage(stage, operation, recordTiming) {
+    const startedAt = performance.now();
+    try {
+        return await operation();
+    }
+    finally {
+        recordTiming?.({
+            stage,
+            durationMs: performance.now() - startedAt
+        });
+    }
+}
+export async function buildPackageAnalysis(targetPath, options = {}) {
+    const rootPath = path.resolve(targetPath);
+    const runCheck = options.runCheck ?? validatePlugin;
+    const [rawValidation, doctorConfig, security, compatibility] = await Promise.all([
+        measureStage("validation", () => runCheck(rootPath), options.recordTiming),
+        measureStage("doctorConfig", () => loadDoctorConfig(rootPath), options.recordTiming),
+        measureStage("security", () => buildSecurityAudit(rootPath), options.recordTiming),
+        measureStage("compatibility", () => buildCompatibilityMatrix(rootPath, options.environment ?? {}), options.recordTiming)
+    ]);
+    const validation = applyDoctorConfig(rawValidation, doctorConfig);
+    const trust = await measureStage("trust", () => buildTrustScore(rootPath, { securityAudit: security }), options.recordTiming);
+    return {
+        generatedAt: new Date().toISOString(),
+        targetPath: rootPath,
+        validation,
+        validationJson: buildJsonReport(validation, { runtimeProbeEnabled: false }),
+        security,
+        compatibility,
+        trust
+    };
+}
+export function buildDoctorRecommendationsFromAnalysis(analysis) {
+    const actions = sortActions(dedupeActions([
+        ...analysis.validation.findings.map((finding) => actionFromFinding(finding, analysis.targetPath)),
+        ...analysis.security.findings.map((finding) => actionFromFinding(finding, analysis.targetPath)),
+        ...actionsFromCompatibility(analysis.compatibility, analysis.targetPath)
+    ]));
+    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 ${analysis.targetPath} --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: analysis.generatedAt,
+        targetPath: analysis.targetPath,
+        status,
+        exitCode: status === "fail" ? 1 : 0,
+        summary: {
+            actionCounts: countActions(finalActions)
+        },
+        validation: {
+            status: analysis.validation.status,
+            findingCount: analysis.validation.findings.length
+        },
+        security: {
+            status: analysis.security.status,
+            score: analysis.security.score,
+            findingCount: analysis.security.findings.length
+        },
+        compatibility: {
+            failedClients: matrixExitCode(analysis.compatibility) === 1
+                ? analysis.compatibility.results
+                    .filter((result) => result.status === "fail")
+                    .map((result) => result.client)
+                : []
+        },
+        actions: finalActions
+    };
+}
+export function buildDoctorExportBundleFromAnalysis(analysis, recommendations = buildDoctorRecommendationsFromAnalysis(analysis)) {
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: analysis.generatedAt,
+        kind: "doctor.export.bundle",
+        version: packageVersion,
+        targetPath: analysis.targetPath,
+        validation: analysis.validationJson,
+        security: analysis.security,
+        compatibility: analysis.compatibility,
+        recommendations,
+        trust: analysis.trust
+    };
+}

package/dist/core/performance-report.d.ts

@@ -0,0 +1,37 @@
+import { type CompatibilityEnvironment } from "../compatibility/compatibility-matrix.js";
+import type { CheckResult } from "../domain/types.js";
+import { type PackageAnalysisStage } from "./package-analysis.js";
+export type DoctorPerformanceStageName = PackageAnalysisStage | "recommendations" | "total";
+export interface DoctorPerformanceStage {
+    name: DoctorPerformanceStageName;
+    durationMs: number;
+    status?: "pass" | "warn" | "fail";
+    itemCount?: number;
+}
+export interface DoctorPerformanceReport {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    kind: "doctor.perf";
+    targetPath: string;
+    status: "pass";
+    exitCode: 0;
+    summary: {
+        stageCount: number;
+        slowestStage: DoctorPerformanceStageName;
+        totalDurationMs: number;
+        validationStatus: "pass" | "warn" | "fail";
+        securityStatus: "pass" | "warn" | "fail";
+        trustScore: number;
+        compatibilityFailures: number;
+    };
+    stages: DoctorPerformanceStage[];
+}
+export interface BuildDoctorPerformanceReportOptions {
+    environment?: CompatibilityEnvironment;
+    runCheck?: (targetPath: string) => Promise<CheckResult>;
+}
+export declare function buildDoctorPerformanceReport(targetPath: string, options?: BuildDoctorPerformanceReportOptions): Promise<DoctorPerformanceReport>;
+export declare function renderDoctorPerformanceReportJson(report: DoctorPerformanceReport): string;
+export declare function renderDoctorPerformanceReport(report: DoctorPerformanceReport, options?: {
+    outputPath?: string | null;
+}): string;

package/dist/core/performance-report.js

@@ -0,0 +1,141 @@
+import { performance } from "node:perf_hooks";
+import { matrixExitCode } from "../compatibility/compatibility-matrix.js";
+import { buildDoctorRecommendationsFromAnalysis, buildPackageAnalysis } from "./package-analysis.js";
+const stageOrder = [
+    "validation",
+    "doctorConfig",
+    "security",
+    "compatibility",
+    "trust",
+    "recommendations",
+    "total"
+];
+function roundDuration(durationMs) {
+    return Number(durationMs.toFixed(3));
+}
+function compatibilityStatus(exitCode, warningCount) {
+    if (exitCode === 1) {
+        return "fail";
+    }
+    return warningCount > 0 ? "warn" : "pass";
+}
+function slowestStage(stages) {
+    return stages
+        .filter((stage) => stage.name !== "total")
+        .reduce((slowest, stage) => (stage.durationMs > slowest.durationMs ? stage : slowest), stages[0]).name;
+}
+export async function buildDoctorPerformanceReport(targetPath, options = {}) {
+    const timings = [];
+    const startedAt = performance.now();
+    const analysis = await buildPackageAnalysis(targetPath, {
+        environment: options.environment,
+        recordTiming: (timing) => timings.push(timing),
+        runCheck: options.runCheck
+    });
+    const recommendationsStartedAt = performance.now();
+    const recommendations = buildDoctorRecommendationsFromAnalysis(analysis);
+    const recommendationTiming = performance.now() - recommendationsStartedAt;
+    const totalDurationMs = performance.now() - startedAt;
+    const compatibilityFailures = analysis.compatibility.results
+        .filter((result) => result.status === "fail").length;
+    const compatibilityWarnings = analysis.compatibility.results
+        .filter((result) => result.status === "warn").length;
+    const timingByStage = new Map(timings.map((timing) => [timing.stage, timing.durationMs]));
+    const stages = stageOrder.map((stageName) => {
+        if (stageName === "validation") {
+            return {
+                name: stageName,
+                durationMs: roundDuration(timingByStage.get(stageName) ?? 0),
+                status: analysis.validation.status,
+                itemCount: analysis.validation.findings.length
+            };
+        }
+        if (stageName === "doctorConfig") {
+            return {
+                name: stageName,
+                durationMs: roundDuration(timingByStage.get(stageName) ?? 0),
+                status: "pass"
+            };
+        }
+        if (stageName === "security") {
+            return {
+                name: stageName,
+                durationMs: roundDuration(timingByStage.get(stageName) ?? 0),
+                status: analysis.security.status,
+                itemCount: analysis.security.findings.length
+            };
+        }
+        if (stageName === "compatibility") {
+            return {
+                name: stageName,
+                durationMs: roundDuration(timingByStage.get(stageName) ?? 0),
+                status: compatibilityStatus(matrixExitCode(analysis.compatibility), compatibilityWarnings),
+                itemCount: analysis.compatibility.results.length
+            };
+        }
+        if (stageName === "trust") {
+            return {
+                name: stageName,
+                durationMs: roundDuration(timingByStage.get(stageName) ?? 0),
+                status: analysis.trust.status,
+                itemCount: analysis.trust.findings.length
+            };
+        }
+        if (stageName === "recommendations") {
+            return {
+                name: stageName,
+                durationMs: roundDuration(recommendationTiming),
+                status: recommendations.status,
+                itemCount: recommendations.actions.length
+            };
+        }
+        return {
+            name: "total",
+            durationMs: roundDuration(totalDurationMs)
+        };
+    });
+    return {
+        schemaVersion: "1.0.0",
+        generatedAt: analysis.generatedAt,
+        kind: "doctor.perf",
+        targetPath: analysis.targetPath,
+        status: "pass",
+        exitCode: 0,
+        summary: {
+            stageCount: stages.length,
+            slowestStage: slowestStage(stages),
+            totalDurationMs: roundDuration(totalDurationMs),
+            validationStatus: analysis.validation.status,
+            securityStatus: analysis.security.status,
+            trustScore: analysis.trust.score,
+            compatibilityFailures
+        },
+        stages
+    };
+}
+export function renderDoctorPerformanceReportJson(report) {
+    return JSON.stringify(report, null, 2);
+}
+export function renderDoctorPerformanceReport(report, options = {}) {
+    const lines = [
+        "Doctor Performance",
+        "==================",
+        `Target: ${report.targetPath}`,
+        `Status: ${report.status.toUpperCase()}`,
+        `Total: ${report.summary.totalDurationMs}ms`,
+        `Slowest: ${report.summary.slowestStage}`,
+        `Validation: ${report.summary.validationStatus.toUpperCase()}`,
+        `Security: ${report.summary.securityStatus.toUpperCase()}`,
+        `Trust: ${report.summary.trustScore}/100`
+    ];
+    if (options.outputPath) {
+        lines.push(`Output: ${options.outputPath}`);
+    }
+    lines.push("", "Stages", "------");
+    for (const stage of report.stages) {
+        const status = stage.status ? ` (${stage.status.toUpperCase()})` : "";
+        const count = stage.itemCount === undefined ? "" : `, items: ${stage.itemCount}`;
+        lines.push(`${stage.name}: ${stage.durationMs}ms${status}${count}`);
+    }
+    return lines.join("\n");
+}

package/dist/core/risk-diff.d.ts

@@ -0,0 +1,33 @@
+import type { CompatibilityEnvironment } from "../compatibility/compatibility-matrix.js";
+import type { Finding } from "../domain/types.js";
+export type RiskFindingCategory = "validation" | "security";
+export interface RiskDiffFinding extends Finding {
+    category: RiskFindingCategory;
+}
+export interface DoctorRiskDiffReport {
+    schemaVersion: "1.0.0";
+    generatedAt: string;
+    kind: "doctor.risk.diff";
+    beforePath: string;
+    afterPath: string;
+    status: "pass" | "warn" | "fail";
+    exitCode: 0 | 1;
+    summary: {
+        riskIncreased: boolean;
+        newFindings: number;
+        resolvedFindings: number;
+        trustScoreBefore: number;
+        trustScoreAfter: number;
+        trustScoreDelta: number;
+    };
+    newFindings: RiskDiffFinding[];
+    resolvedFindings: RiskDiffFinding[];
+}
+export interface BuildDoctorRiskDiffReportOptions {
+    environment?: CompatibilityEnvironment;
+}
+export declare function buildDoctorRiskDiffReport(beforePath: string, afterPath: string, options?: BuildDoctorRiskDiffReportOptions): Promise<DoctorRiskDiffReport>;
+export declare function renderDoctorRiskDiffReportJson(report: DoctorRiskDiffReport): string;
+export declare function renderDoctorRiskDiffReport(report: DoctorRiskDiffReport, options?: {
+    outputPath?: string | null;
+}): string;