pgexplain 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,335 @@
+/**
+ * Domain model for pg-explain.
+ *
+ * Two things flow through the whole program:
+ *  - PlanTree / PlanNode  — the normalized EXPLAIN plan.
+ *  - Diagnostic           — a single actionable message. The SAME shape is used for
+ *                           operational tool errors and for plan-analysis findings, so
+ *                           one renderer serves both and `--format json` exposes both
+ *                           with identical, machine-readable actionability.
+ */
+type Severity = "error" | "warn" | "info";
+type Domain = "operational" | "plan";
+/** A copy-pasteable, credential-free command shown to the user. */
+interface RemediationCommand {
+    label?: string;
+    /** A shell command, e.g. `pg_isready -h <host> -p <port>`. */
+    shell?: string;
+    /** A SQL statement, e.g. `GRANT SELECT ON orders TO readonly;`. */
+    sql?: string;
+}
+/** HOW to fix it. Mandatory on every Diagnostic; `summary` is never empty. */
+interface Remediation {
+    summary: string;
+    steps?: string[];
+    commands?: RemediationCommand[];
+}
+interface DiagnosticLocation {
+    kind: "node" | "connection" | "input" | "option";
+    /** Pre-order id assigned during parse, for `node` locations. */
+    nodeId?: number;
+    nodeType?: string;
+    relation?: string;
+    /** 1-based line/col for `input` (malformed JSON) locations. */
+    line?: number;
+    col?: number;
+    optionName?: string;
+}
+/**
+ * The load-bearing type. Every error and every finding is one of these, and every
+ * one carries a non-empty `remediation` so the developer always knows what to do next.
+ */
+interface Diagnostic {
+    /** Stable, greppable identifier, e.g. PGX_AUTH_FAILED, PGX_SEQ_SCAN_LARGE. */
+    code: string;
+    domain: Domain;
+    severity: Severity;
+    /** One scannable headline line, no trailing punctuation. */
+    title: string;
+    /** WHAT happened, in plain language. */
+    detail: string;
+    /** WHY it happened / why it matters. */
+    cause: string;
+    remediation: Remediation;
+    /** Deep link with an anchor to the authoritative PostgreSQL doc. */
+    docsUrl?: string;
+    location?: DiagnosticLocation;
+    /** Structured extras for machine consumers (timeoutMs, pgVersion, sqlState, …). */
+    meta?: Record<string, string | number>;
+}
+/** The original EXPLAIN FORMAT JSON node, untouched. Escape hatch for rare fields. */
+interface RawPlan {
+    "Node Type": string;
+    Plans?: RawPlan[];
+    [key: string]: unknown;
+}
+/** Derived per-node metrics, all per-loop-corrected. Absent without ANALYZE. */
+interface NodeMetrics {
+    /** "Actual Rows" × "Actual Loops" — the true total this node produced. */
+    totalRows?: number;
+    /** "Actual Total Time" × "Actual Loops" — wall time of this subtree, all loops. */
+    inclusiveMs?: number;
+    /** inclusive − Σ(children inclusive), clamped ≥ 0. The bottleneck-ranking quantity. */
+    selfMs?: number;
+    /** 100 × selfMs / execution time. */
+    pctOfTotal?: number;
+    /** Misestimate factor ≥ 1 (max(est,act)/min(est,act)). */
+    estimateFactor?: number;
+    estimateDirection?: "over" | "under" | "accurate";
+    /** shared hit / (hit + read); null when no shared-buffer access here. */
+    cacheHitRatio?: number | null;
+    /** rows removed / (removed + kept). */
+    filterDiscardRatio?: number;
+    /** lossy / (lossy + exact). */
+    lossyRatio?: number;
+}
+interface PlanNode {
+    /** Pre-order index assigned at parse time; stable id for locations/diff. */
+    id: number;
+    nodeType: string;
+    parentRelationship?: string;
+    subplanName?: string;
+    relationName?: string;
+    schema?: string;
+    alias?: string;
+    indexName?: string;
+    planRows: number;
+    planWidth?: number;
+    startupCost?: number;
+    totalCost?: number;
+    actualRows?: number;
+    actualLoops?: number;
+    actualStartupTime?: number;
+    actualTotalTime?: number;
+    filter?: string;
+    rowsRemovedByFilter?: number;
+    indexCond?: string;
+    recheckCond?: string;
+    rowsRemovedByIndexRecheck?: number;
+    heapFetches?: number;
+    hashCond?: string;
+    joinType?: string;
+    joinFilter?: string;
+    rowsRemovedByJoinFilter?: number;
+    /** Projected columns (VERBOSE only). */
+    output?: string[];
+    sortMethod?: string;
+    sortSpaceType?: string;
+    sortSpaceUsed?: number;
+    sortKey?: string[];
+    hashBuckets?: number;
+    originalHashBuckets?: number;
+    hashBatches?: number;
+    originalHashBatches?: number;
+    peakMemoryUsage?: number;
+    diskUsage?: number;
+    exactHeapBlocks?: number;
+    lossyHeapBlocks?: number;
+    sharedHitBlocks?: number;
+    sharedReadBlocks?: number;
+    sharedDirtiedBlocks?: number;
+    sharedWrittenBlocks?: number;
+    localHitBlocks?: number;
+    localReadBlocks?: number;
+    tempReadBlocks?: number;
+    tempWrittenBlocks?: number;
+    ioReadTime?: number;
+    ioWriteTime?: number;
+    workersPlanned?: number;
+    workersLaunched?: number;
+    children: PlanNode[];
+    metrics: NodeMetrics;
+    /** Original JSON node — rules may read rare fields not normalized above. */
+    raw: RawPlan;
+}
+interface JitInfo {
+    functions?: number;
+    timing?: {
+        total?: number;
+        generation?: number;
+        inlining?: number;
+        optimization?: number;
+        emission?: number;
+    };
+}
+interface TriggerInfo {
+    name?: string;
+    constraintName?: string;
+    relation?: string;
+    calls?: number;
+    time?: number;
+}
+interface PlanTree {
+    root: PlanNode;
+    planningTime?: number;
+    executionTime?: number;
+    triggers: TriggerInfo[];
+    jit?: JitInfo;
+    settings?: Record<string, string>;
+    /** Actual row/time data present (EXPLAIN ANALYZE was used). */
+    hasAnalyze: boolean;
+    /** Buffer counters present (BUFFERS was used). */
+    hasBuffers: boolean;
+    raw: RawPlan;
+}
+interface Thresholds {
+    seqScanRows: number;
+    nestedLoopOuterRows: number;
+    filterDiscardRatio: number;
+    filterRemovedAbs: number;
+    misestimateFactor: number;
+    heapFetchRatio: number;
+    heapFetchAbs: number;
+    correlatedLoops: number;
+    jitPct: number;
+    triggerPct: number;
+    lowCacheHitRatio: number;
+}
+interface AnalysisContext {
+    tree: PlanTree;
+    thresholds: Thresholds;
+    /** Resolve a rule's severity, honoring config overrides. */
+    severityOf(ruleId: string, fallback: Severity): Severity;
+    /** Whether a rule is enabled (config can disable rules). */
+    isEnabled(ruleId: string): boolean;
+}
+/**
+ * One anti-pattern rule. `check` is called once per node in the tree; tree-level
+ * rules (JIT, triggers) act only when `node === ctx.tree.root`.
+ */
+interface Rule {
+    id: string;
+    title: string;
+    defaultSeverity: Severity;
+    requiresAnalyze?: boolean;
+    requiresBuffers?: boolean;
+    check(node: PlanNode, ctx: AnalysisContext): Diagnostic[];
+}
+interface AnalysisResult {
+    tree: PlanTree;
+    /** Plan-domain findings, sorted by severity then impact. */
+    diagnostics: Diagnostic[];
+    /** Top nodes by self time. */
+    bottlenecks: PlanNode[];
+    /** One-line verdict shown at the top of every report. */
+    verdict: string;
+    /** Highest severity present, or null if clean. */
+    worstSeverity: Severity | null;
+}
+
+interface RuleConfig {
+    enabled?: boolean;
+    severity?: Severity;
+}
+interface PgExplainConfig {
+    thresholds: Thresholds;
+    /** Per-rule enable/disable and severity overrides, keyed by rule id. */
+    rules: Record<string, RuleConfig>;
+}
+declare const DEFAULT_THRESHOLDS: Thresholds;
+declare const DEFAULT_CONFIG: PgExplainConfig;
+
+/**
+ * Run every enabled rule over the tree and assemble the result. Assumes
+ * computeMetrics(tree) has already run. Rules that need data the plan lacks
+ * (ANALYZE/BUFFERS) are skipped so cost-only plans degrade gracefully.
+ */
+declare function runAdvisor(tree: PlanTree, config?: PgExplainConfig): AnalysisResult;
+
+/**
+ * Fill `node.metrics` for every node. All row/time figures are PER-LOOP corrected:
+ * Postgres reports "Actual Rows"/"Actual Total Time" as the average of a single loop,
+ * so the true total is `× "Actual Loops"`. Buffer counters are already cumulative and
+ * are NOT multiplied. No-ops cleanly on cost-only plans (leaves metrics empty).
+ */
+declare function computeMetrics(tree: PlanTree): void;
+/** Total execution time in ms: prefer the reported value, else the root's inclusive time. */
+declare function executionMs(tree: PlanTree): number | undefined;
+/** Top N nodes by self time (the real bottlenecks), descending. */
+declare function bottlenecks(tree: PlanTree, n?: number): PlanNode[];
+/** A short human label for a node, e.g. "Seq Scan on orders". */
+declare function nodeLabel(node: PlanNode): string;
+
+/**
+ * Parse EXPLAIN (FORMAT JSON) text into one PlanTree per statement.
+ * Accepts the standard `[{ "Plan": … }]`, a bare statement object, or a bare plan node.
+ * Throws AppError(PGX_MALFORMED_JSON | PGX_UNEXPECTED_PLAN_SHAPE) with a location.
+ */
+declare function parseExplainJson(input: string): PlanTree[];
+/** Depth-first pre-order walk (root first). Used by metrics and the advisor. */
+declare function walk(node: PlanNode, visit: (n: PlanNode) => void): void;
+/** Flatten a tree to an array in pre-order. */
+declare function flatten(node: PlanNode): PlanNode[];
+
+/**
+ * Process exit codes. Documented in README and `pg-explain --help` so scripts and
+ * CI can branch on the *kind* of failure without parsing text.
+ */
+declare enum ExitCode {
+    /** Report produced. Findings alone do not change this unless --strict/--fail-on. */
+    Success = 0,
+    /** CI gate tripped: findings present AND --strict / --fail-on threshold met. */
+    CiGate = 1,
+    /** Usage error: bad flags/args, refused non-SELECT, unsupported option. */
+    Usage = 2,
+    /** Input error: no/empty stdin and no --file, unreadable file. */
+    Input = 3,
+    /** Parse/validation error: not valid EXPLAIN JSON or wrong shape. */
+    Parse = 4,
+    /** Database error: connect/auth/permission/timeout/cancel. */
+    Database = 5,
+    /** pg-explain itself hit an unexpected error. */
+    Internal = 70,
+    /** Interrupted by SIGINT. (128 + signal number.) */
+    Sigint = 130
+}
+
+/**
+ * An error that carries a fully-actionable Diagnostic and a process exit code.
+ * cli.ts catches these, renders the diagnostic to stderr, and exits with `exitCode`.
+ * Anything NOT an AppError that reaches the top level becomes PGX_INTERNAL.
+ */
+declare class AppError extends Error {
+    readonly diagnostic: Diagnostic;
+    readonly exitCode: ExitCode;
+    constructor(diagnostic: Diagnostic, exitCode: ExitCode, cause?: unknown);
+}
+/**
+ * Remove secrets from any string before it is logged, shown, or written.
+ * Targets:
+ *  - userinfo passwords in connection URLs:  postgres://user:secret@host  → user:***@host
+ *  - libpq keyword form:                     password=secret              → password=***
+ *  - PG* env-style:                          PGPASSWORD=secret            → PGPASSWORD=***
+ *  - URL query params:                        ?password=secret&sslmode=…  → ?password=***&…
+ */
+declare function scrubCredentials(input: string): string;
+
+/** Bump on any breaking change to the JSON shape. Consumers can assert on it. */
+declare const JSON_SCHEMA_VERSION = 1;
+
+type Format = "terminal" | "markdown" | "json" | "html" | "text";
+declare const FORMATS: Format[];
+declare function isFormat(s: string): s is Format;
+interface RenderOptions {
+    format: Format;
+    /** Summary + findings only, no plan tree. */
+    tldr?: boolean;
+    /** ASCII tree glyphs (terminal/text). */
+    ascii?: boolean;
+    /** Pretty-print JSON. */
+    pretty?: boolean;
+}
+/** Render an analysis result to the requested format. Color is configured by the caller. */
+declare function render(result: AnalysisResult, opts: RenderOptions): string;
+
+interface AnalyzeOptions {
+    config?: PgExplainConfig;
+    /** 1-based statement index when the input holds more than one. */
+    statement?: number;
+    /** Strip literal values from expressions before analysis (no data leaks downstream). */
+    redact?: boolean;
+}
+/** Parse → (redact) → compute metrics → run advisor → attach informational notices. */
+declare function analyze(input: string, options?: AnalyzeOptions): AnalysisResult;
+
+export { type AnalysisContext, type AnalysisResult, type AnalyzeOptions, AppError, DEFAULT_CONFIG, DEFAULT_THRESHOLDS, type Diagnostic, type DiagnosticLocation, type Domain, ExitCode, FORMATS, type Format, JSON_SCHEMA_VERSION, type JitInfo, type NodeMetrics, type PgExplainConfig, type PlanNode, type PlanTree, type RawPlan, type Remediation, type RemediationCommand, type RenderOptions, type Rule, type Severity, type Thresholds, type TriggerInfo, analyze, bottlenecks, computeMetrics, executionMs, flatten, isFormat, nodeLabel, parseExplainJson, render, runAdvisor, scrubCredentials, walk };