codex-plugin-doctor 1.27.0 → 1.29.0

package/dist/core/suppression-management.js

@@ -0,0 +1,181 @@
+import { classifySuppressionRecord, isValidSuppressionFingerprint, validateSuppressionRecord } from "./suppression-record.js";
+export class SuppressionManagementError extends Error {
+    code;
+    field;
+    index;
+    indexes;
+    constructor(message, details) {
+        super(message);
+        this.name = "SuppressionManagementError";
+        this.code = details.code;
+        this.field = details.field;
+        this.index = details.index;
+        this.indexes = details.indexes;
+    }
+}
+function createSuppressionManagementError(message, details) {
+    return new SuppressionManagementError(message, details);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readSuppressions(config) {
+    if (!("suppressions" in config)) {
+        return {
+            suppressions: [],
+            hasSuppressions: false
+        };
+    }
+    const { suppressions } = config;
+    if (!Array.isArray(suppressions)) {
+        throw createSuppressionManagementError("Doctor config suppressions must be an array when present.", {
+            code: "suppression_non_array"
+        });
+    }
+    return {
+        suppressions,
+        hasSuppressions: true
+    };
+}
+function copyConfigWithSuppressions(config, suppressions) {
+    return {
+        ...config,
+        suppressions
+    };
+}
+function buildManagedInvalidSuppression(index, invalidField) {
+    return {
+        index,
+        status: "invalid",
+        invalidField
+    };
+}
+function buildRemovedSuppressionSummary(suppression) {
+    const classified = classifySuppressionRecord(suppression, new Date(0));
+    if (classified.status === "invalid") {
+        return {
+            invalidField: classified.field
+        };
+    }
+    return {
+        fingerprint: classified.fingerprint,
+        reason: classified.reason,
+        expiresAt: classified.expiresAt
+    };
+}
+function findDuplicateFingerprintIndex(suppressions, fingerprint) {
+    return suppressions.findIndex((suppression) => isPlainObject(suppression) &&
+        typeof suppression.fingerprint === "string" &&
+        suppression.fingerprint === fingerprint);
+}
+function validateManagedFingerprint(fingerprint) {
+    if (!isValidSuppressionFingerprint(fingerprint)) {
+        throw createSuppressionManagementError("Suppression fingerprint is invalid.", {
+            code: "suppression_invalid_fingerprint"
+        });
+    }
+    return fingerprint;
+}
+function findFingerprintMatches(suppressions, fingerprint) {
+    return suppressions.flatMap((suppression, index) => isPlainObject(suppression) &&
+        typeof suppression.fingerprint === "string" &&
+        suppression.fingerprint === fingerprint
+        ? [index]
+        : []);
+}
+export function listSuppressions(config, now = new Date()) {
+    const { suppressions, hasSuppressions } = readSuppressions(config);
+    if (!hasSuppressions) {
+        return [];
+    }
+    return suppressions.map((suppression, index) => {
+        const classified = classifySuppressionRecord(suppression, now);
+        if (classified.status === "invalid") {
+            return buildManagedInvalidSuppression(index, classified.field);
+        }
+        return {
+            index,
+            status: classified.status,
+            fingerprint: classified.fingerprint,
+            reason: classified.reason,
+            expiresAt: classified.expiresAt
+        };
+    });
+}
+export function addSuppression(config, record) {
+    const { suppressions } = readSuppressions(config);
+    const validation = validateSuppressionRecord(record);
+    if (!validation.valid) {
+        throw createSuppressionManagementError(`Suppression record is invalid: ${validation.field}.`, {
+            code: "suppression_invalid_record",
+            field: validation.field
+        });
+    }
+    const duplicateIndex = findDuplicateFingerprintIndex(suppressions, validation.fingerprint);
+    if (duplicateIndex >= 0) {
+        throw createSuppressionManagementError(`Suppression fingerprint already exists at index ${duplicateIndex}.`, {
+            code: "suppression_duplicate_fingerprint",
+            index: duplicateIndex
+        });
+    }
+    const suppression = {
+        fingerprint: validation.fingerprint,
+        reason: validation.reason,
+        expiresAt: validation.expiresAt
+    };
+    const nextSuppressions = [...suppressions, suppression];
+    return {
+        config: copyConfigWithSuppressions(config, nextSuppressions),
+        index: suppressions.length,
+        suppression
+    };
+}
+export function removeSuppressionByIndex(config, index) {
+    const { suppressions } = readSuppressions(config);
+    if (!Number.isInteger(index) ||
+        index < 0 ||
+        index >= suppressions.length) {
+        throw createSuppressionManagementError("Suppression index must be an integer within range.", {
+            code: "suppression_invalid_index",
+            index
+        });
+    }
+    const suppression = suppressions[index];
+    const nextSuppressions = [
+        ...suppressions.slice(0, index),
+        ...suppressions.slice(index + 1)
+    ];
+    return {
+        config: copyConfigWithSuppressions(config, nextSuppressions),
+        index,
+        suppression: buildRemovedSuppressionSummary(suppression)
+    };
+}
+export function removeSuppressionByFingerprint(config, fingerprint) {
+    const { suppressions } = readSuppressions(config);
+    const validFingerprint = validateManagedFingerprint(fingerprint);
+    const matches = findFingerprintMatches(suppressions, validFingerprint);
+    if (matches.length === 0) {
+        throw createSuppressionManagementError("Suppression fingerprint not found.", {
+            code: "suppression_fingerprint_not_found"
+        });
+    }
+    if (matches.length > 1) {
+        throw createSuppressionManagementError(`Suppression fingerprint matches multiple suppressions at indexes: ${matches.join(", ")}.`, {
+            code: "suppression_fingerprint_ambiguous",
+            indexes: matches
+        });
+    }
+    return removeSuppressionByIndex(config, matches[0]);
+}
+export function pruneSuppressions(config, now = new Date()) {
+    const { suppressions } = readSuppressions(config);
+    const managedSuppressions = listSuppressions(config, now);
+    const removed = managedSuppressions.filter((suppression) => suppression.status !== "active");
+    const removedIndexes = new Set(removed.map((suppression) => suppression.index));
+    const nextSuppressions = suppressions.filter((_suppression, index) => !removedIndexes.has(index));
+    return {
+        config: copyConfigWithSuppressions(config, nextSuppressions),
+        removed
+    };
+}

package/dist/core/suppression-record.d.ts

@@ -0,0 +1,26 @@
+export type SuppressionRecordField = "record" | "fingerprint" | "reason" | "expiresAt";
+export interface ValidSuppressionRecord {
+    valid: true;
+    fingerprint: string;
+    reason: string;
+    expiresAt: string;
+}
+export interface InvalidSuppressionRecord {
+    valid: false;
+    field: SuppressionRecordField;
+}
+type ActiveSuppressionRecord = ValidSuppressionRecord & {
+    status: "active";
+};
+type ExpiredSuppressionRecord = ValidSuppressionRecord & {
+    status: "expired";
+};
+type InvalidClassifiedSuppressionRecord = InvalidSuppressionRecord & {
+    status: "invalid";
+};
+export type ClassifiedSuppressionRecord = ActiveSuppressionRecord | ExpiredSuppressionRecord | InvalidClassifiedSuppressionRecord;
+export declare function isValidSuppressionFingerprint(value: unknown): value is string;
+export declare function validateSuppressionRecord(value: unknown): ValidSuppressionRecord | InvalidSuppressionRecord;
+export declare function isSuppressionExpired(expiresAt: string, now: Date): boolean;
+export declare function classifySuppressionRecord(value: unknown, now: Date): ClassifiedSuppressionRecord;
+export {};

package/dist/core/suppression-record.js

@@ -0,0 +1,62 @@
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRealDate(value) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    if (!match) {
+        return false;
+    }
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return (date.getUTCFullYear() === year &&
+        date.getUTCMonth() === month - 1 &&
+        date.getUTCDate() === day);
+}
+export function isValidSuppressionFingerprint(value) {
+    return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+export function validateSuppressionRecord(value) {
+    if (!isPlainObject(value)) {
+        return { valid: false, field: "record" };
+    }
+    if (!isValidSuppressionFingerprint(value.fingerprint)) {
+        return { valid: false, field: "fingerprint" };
+    }
+    if (typeof value.reason !== "string" || value.reason.trim().length === 0) {
+        return { valid: false, field: "reason" };
+    }
+    if (typeof value.expiresAt !== "string" || !isRealDate(value.expiresAt)) {
+        return { valid: false, field: "expiresAt" };
+    }
+    return {
+        valid: true,
+        fingerprint: value.fingerprint,
+        reason: value.reason.trim(),
+        expiresAt: value.expiresAt
+    };
+}
+export function isSuppressionExpired(expiresAt, now) {
+    const expirationBoundary = Date.parse(`${expiresAt}T00:00:00.000Z`) + 86_400_000;
+    return now.getTime() >= expirationBoundary;
+}
+export function classifySuppressionRecord(value, now) {
+    const validation = validateSuppressionRecord(value);
+    if (!validation.valid) {
+        return {
+            status: "invalid",
+            ...validation
+        };
+    }
+    if (isSuppressionExpired(validation.expiresAt, now)) {
+        return {
+            status: "expired",
+            ...validation
+        };
+    }
+    return {
+        status: "active",
+        ...validation
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 import type { CheckOptions, CheckResult } from "./domain/types.js";
 export { applyDoctorConfig, loadDoctorConfig, type DoctorConfig } from "./core/doctor-config.js";
+export { readRawDoctorConfig, resolveDoctorConfigPath, writeRawDoctorConfig, type LoadedDoctorConfig, type RawDoctorConfig } from "./core/doctor-config-store.js";
+export { classifySuppressionRecord, isValidSuppressionFingerprint, isSuppressionExpired, validateSuppressionRecord, type ClassifiedSuppressionRecord, type InvalidSuppressionRecord, type SuppressionRecordField, type ValidSuppressionRecord } from "./core/suppression-record.js";
+export { addSuppression, listSuppressions, pruneSuppressions, removeSuppressionByFingerprint, removeSuppressionByIndex, SuppressionManagementError, type ManagedSuppressionRecord, type SuppressionManagementErrorCode, type SuppressionMutationResult, type SuppressionPruneResult } from "./core/suppression-management.js";
 export { buildFindingFingerprint, formatFindingFingerprintLine, withFindingFingerprint, withFindingFingerprints } from "./reporting/finding-fingerprint.js";
 export { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard, type SecurityAudit } from "./security/security-audit.js";
 export { buildTrustScore, renderTrustScore, renderTrustScoreJson, type BuildTrustScoreOptions, type TrustScoreReport } from "./security/trust-score.js";

package/dist/index.js

@@ -1,5 +1,8 @@
 import { validatePlugin } from "./core/validate-plugin.js";
 export { applyDoctorConfig, loadDoctorConfig } from "./core/doctor-config.js";
+export { readRawDoctorConfig, resolveDoctorConfigPath, writeRawDoctorConfig } from "./core/doctor-config-store.js";
+export { classifySuppressionRecord, isValidSuppressionFingerprint, isSuppressionExpired, validateSuppressionRecord } from "./core/suppression-record.js";
+export { addSuppression, listSuppressions, pruneSuppressions, removeSuppressionByFingerprint, removeSuppressionByIndex, SuppressionManagementError } from "./core/suppression-management.js";
 export { buildFindingFingerprint, formatFindingFingerprintLine, withFindingFingerprint, withFindingFingerprints } from "./reporting/finding-fingerprint.js";
 export { buildSecurityAudit, renderSecurityAuditJson, renderSecurityScorecard } from "./security/security-audit.js";
 export { buildTrustScore, renderTrustScore, renderTrustScoreJson } from "./security/trust-score.js";

package/dist/reporting/render-suppression-management.d.ts

@@ -0,0 +1,13 @@
+import type { ManagedSuppressionRecord, SuppressionMutationResult, SuppressionPruneResult } from "../core/suppression-management.js";
+type SuppressionMutationCommand = "suppress.add" | "suppress.remove";
+export declare function renderSuppressionList(configPath: string, suppressions: ManagedSuppressionRecord[]): string;
+export declare function renderSuppressionListJson(configPath: string, suppressions: ManagedSuppressionRecord[]): string;
+export declare function renderSuppressionMutation(command: SuppressionMutationCommand, configPath: string, result: SuppressionMutationResult): string;
+export declare function renderSuppressionMutationJson(command: SuppressionMutationCommand, configPath: string, result: SuppressionMutationResult): string;
+export declare function renderSuppressionPrune(configPath: string, result: SuppressionPruneResult, options: {
+    applied: boolean;
+}): string;
+export declare function renderSuppressionPruneJson(configPath: string, result: SuppressionPruneResult, options: {
+    applied: boolean;
+}): string;
+export {};

package/dist/reporting/render-suppression-management.js

@@ -0,0 +1,152 @@
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isInvalidField(value) {
+    return (value === "record" ||
+        value === "fingerprint" ||
+        value === "reason" ||
+        value === "expiresAt");
+}
+function isValidSuppressionSummary(value) {
+    return (isObject(value) &&
+        !("invalidField" in value) &&
+        typeof value.fingerprint === "string" &&
+        typeof value.reason === "string" &&
+        value.reason.trim().length > 0 &&
+        typeof value.expiresAt === "string");
+}
+function buildListEntry(record) {
+    if (record.status === "invalid" && isInvalidField(record.invalidField)) {
+        return {
+            index: record.index,
+            status: record.status,
+            invalidField: record.invalidField
+        };
+    }
+    if ((record.status === "active" || record.status === "expired") &&
+        isValidSuppressionSummary(record)) {
+        return {
+            index: record.index,
+            status: record.status,
+            fingerprint: record.fingerprint,
+            reason: record.reason,
+            expiresAt: record.expiresAt
+        };
+    }
+    return {
+        index: record.index,
+        status: "invalid",
+        invalidField: "record"
+    };
+}
+function buildMutationSummary(value) {
+    if (isObject(value) && isInvalidField(value.invalidField)) {
+        return {
+            invalidField: value.invalidField
+        };
+    }
+    if (isValidSuppressionSummary(value)) {
+        return {
+            fingerprint: value.fingerprint,
+            reason: value.reason,
+            expiresAt: value.expiresAt
+        };
+    }
+    return { invalidField: "record" };
+}
+function getActionLabel(command) {
+    return command === "suppress.add" ? "Added" : "Removed";
+}
+export function renderSuppressionList(configPath, suppressions) {
+    const lines = [
+        `Config: ${configPath}`,
+        `Total suppressions: ${suppressions.length}`
+    ];
+    if (suppressions.length === 0) {
+        lines.push("", "No suppressions.");
+        return lines.join("\n");
+    }
+    lines.push("", "Suppressions", "------------");
+    for (const suppression of suppressions) {
+        const entry = buildListEntry(suppression);
+        if (entry.status === "invalid") {
+            lines.push(`[${entry.index}] INVALID ${entry.invalidField}`);
+            continue;
+        }
+        lines.push(`[${entry.index}] ${entry.status.toUpperCase()} ${entry.fingerprint}`);
+        lines.push(`  Reason: ${entry.reason}`);
+        lines.push(`  Expires: ${entry.expiresAt}`);
+    }
+    return lines.join("\n");
+}
+export function renderSuppressionListJson(configPath, suppressions) {
+    return JSON.stringify({
+        schemaVersion: "1.0.0",
+        kind: "doctor.suppress.list",
+        command: "suppress.list",
+        configPath,
+        suppressions: suppressions.map(buildListEntry)
+    }, null, 2);
+}
+export function renderSuppressionMutation(command, configPath, result) {
+    const summary = buildMutationSummary(result.suppression);
+    const lines = [
+        `Action: ${getActionLabel(command)}`,
+        `Config: ${configPath}`,
+        `Index: ${result.index}`
+    ];
+    lines.push("");
+    if ("invalidField" in summary) {
+        lines.push(`Invalid field: ${summary.invalidField}`);
+        return lines.join("\n");
+    }
+    lines.push(`Fingerprint: ${summary.fingerprint}`);
+    lines.push(`Reason: ${summary.reason}`);
+    lines.push(`Expires: ${summary.expiresAt}`);
+    return lines.join("\n");
+}
+export function renderSuppressionMutationJson(command, configPath, result) {
+    return JSON.stringify({
+        schemaVersion: "1.0.0",
+        kind: `doctor.${command}`,
+        command,
+        configPath,
+        index: result.index,
+        suppression: buildMutationSummary(result.suppression)
+    }, null, 2);
+}
+export function renderSuppressionPrune(configPath, result, options) {
+    const lines = [
+        "Action: Prune",
+        `Mode: ${options.applied ? "apply" : "dry-run"}`,
+        `Config: ${configPath}`,
+        `Removed suppressions: ${result.removed.length}`
+    ];
+    if (result.removed.length === 0) {
+        lines.push("", "No expired or invalid suppressions to prune.");
+        return lines.join("\n");
+    }
+    lines.push("", "Removed", "-------");
+    for (const suppression of result.removed) {
+        const entry = buildListEntry(suppression);
+        if (entry.status === "invalid") {
+            lines.push(`[${entry.index}] INVALID ${entry.invalidField}`);
+            continue;
+        }
+        lines.push(`[${entry.index}] ${entry.status.toUpperCase()} ${entry.fingerprint}`);
+        lines.push(`  Reason: ${entry.reason}`);
+        lines.push(`  Expires: ${entry.expiresAt}`);
+    }
+    return lines.join("\n");
+}
+export function renderSuppressionPruneJson(configPath, result, options) {
+    return JSON.stringify({
+        schemaVersion: "1.0.0",
+        kind: "doctor.suppress.prune",
+        command: "suppress.prune",
+        configPath,
+        applied: options.applied,
+        removedCount: result.removed.length,
+        removed: result.removed.map(buildListEntry)
+    }, null, 2);
+}

package/dist/run-cli.d.ts

@@ -1,4 +1,5 @@
 import { runCheck } from "./index.js";
+import { writeRawDoctorConfig } from "./index.js";
 export interface CliIo {
     writeStdout(message: string): void;
     writeStderr(message: string): void;
@@ -13,6 +14,8 @@ export interface CliTerminalContext {
 export interface RunCliOptions {
     terminalContext?: CliTerminalContext;
     runCheckImpl?: typeof runCheck;
+    writeRawDoctorConfigImpl?: typeof writeRawDoctorConfig;
+    now?: () => Date;
     releaseAssetUploadImpl?: (args: string[]) => Promise<void>;
     resolveLatestVersion?: () => Promise<string>;
 }