pgexplain 0.1.0

package/dist/cli.js

@@ -0,0 +1,3205 @@
+#!/usr/bin/env node
+import { defineCommand, runMain } from 'citty';
+import { readFile, writeFile, stat, readdir } from 'fs/promises';
+import { join } from 'path';
+import { z } from 'zod';
+import pc from 'picocolors';
+
+// package.json
+var package_default = {
+  version: "0.1.0"};
+
+// src/diagnostics/diagnostic.ts
+var AppError = class extends Error {
+  diagnostic;
+  exitCode;
+  constructor(diagnostic, exitCode, cause) {
+    super(diagnostic.title);
+    this.name = "AppError";
+    this.diagnostic = diagnostic;
+    this.exitCode = exitCode;
+    if (cause !== void 0) this.cause = cause;
+  }
+};
+var SEVERITY_RANK = { error: 0, warn: 1, info: 2 };
+function bySeverity(a, b) {
+  return SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+}
+function maxSeverity(a, b) {
+  return SEVERITY_RANK[a] <= SEVERITY_RANK[b] ? a : b;
+}
+function severityAtLeast(s, threshold) {
+  return SEVERITY_RANK[s] <= SEVERITY_RANK[threshold];
+}
+function scrubCredentials(input) {
+  if (!input) return input;
+  return input.replace(/(\b[a-z][a-z0-9+.-]*:\/\/[^:/?#@\s]+:)([^@\s]+)(@)/gi, "$1***$3").replace(/\bpassword\s*=\s*'[^']*'/gi, "password='***'").replace(/(\bpassword\s*=\s*)([^\s&'"]+)/gi, "$1***").replace(/(\bPGPASSWORD\s*=\s*)([^\s&'"]+)/gi, "$1***");
+}
+
+// src/diagnostics/catalog.ts
+var DOCS = "https://www.postgresql.org/docs/current";
+var CATALOG = {
+  PGX_AUTH_FAILED: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Authentication failed",
+    detail: "The server rejected the supplied credentials.",
+    cause: "The password or role is wrong, or pg_hba.conf does not permit this role from your host.",
+    remediation: {
+      summary: "Verify the credentials and supply the password safely (never on the command line).",
+      steps: [
+        "Confirm the username and password are correct.",
+        "Provide the password via PGPASSWORD or ~/.pgpass instead of the command line.",
+        "Check that pg_hba.conf allows this role from your client host."
+      ],
+      commands: [
+        { label: "Set password via env", shell: "export PGPASSWORD=<password>" },
+        {
+          label: "Or store it (chmod 600)",
+          shell: 'echo "<host>:<port>:<db>:<user>:<password>" >> ~/.pgpass && chmod 600 ~/.pgpass'
+        }
+      ]
+    },
+    docsUrl: `${DOCS}/auth-pg-hba-conf.html`
+  },
+  PGX_HOST_UNREACHABLE: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Cannot reach the PostgreSQL server",
+    detail: "DNS resolution failed or the TCP connection was refused.",
+    cause: "Wrong host/port, the server is down, or a firewall/VPN/security group is blocking the port.",
+    remediation: {
+      summary: "Verify the host and port, then probe reachability.",
+      steps: [
+        "Double-check --host and --port (or the DSN) for typos.",
+        "Confirm the server is running and accepts TCP connections.",
+        "Check VPN, firewall, and cloud security-group rules for the port."
+      ],
+      commands: [{ label: "Probe reachability", shell: "pg_isready -h <host> -p <port>" }]
+    },
+    docsUrl: `${DOCS}/libpq-connect.html`
+  },
+  PGX_DB_NOT_FOUND: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Database does not exist",
+    detail: "The named database was not found on the server.",
+    cause: "The database name is misspelled or the database has not been created.",
+    remediation: {
+      summary: "List the available databases and correct the name.",
+      commands: [
+        { label: "List databases", shell: "psql -h <host> -U <user> -l" },
+        { label: "Re-run with the right name", shell: "pg-explain run --dbname <name> ..." }
+      ]
+    }
+  },
+  PGX_SSL_REQUIRED: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Server requires SSL",
+    detail: "The server requires an encrypted connection but a plaintext one was offered.",
+    cause: "pg_hba.conf mandates SSL (e.g. `hostssl`) for this role/host.",
+    remediation: {
+      summary: "Enable SSL on the connection.",
+      commands: [
+        { label: "Require encryption", shell: "pg-explain run --sslmode require ..." },
+        {
+          label: "Or verify the certificate too",
+          shell: "pg-explain run --sslmode verify-full --sslrootcert <ca.pem> ..."
+        }
+      ]
+    },
+    docsUrl: `${DOCS}/libpq-ssl.html`
+  },
+  PGX_SSL_VERIFY_FAILED: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "TLS certificate verification failed",
+    detail: "Under verify-full the certificate chain is untrusted or the hostname does not match.",
+    cause: "The CA is not trusted locally, or the certificate's CN/SAN does not match the host you connect to.",
+    remediation: {
+      summary: "Point at the CA bundle and confirm the hostname matches the certificate.",
+      steps: [
+        "Provide the CA certificate the server's cert chains to.",
+        "Confirm the certificate CN/SAN matches the --host value.",
+        "Only fall back to `--sslmode require` (encryption without identity check) if you accept the risk."
+      ],
+      commands: [
+        {
+          label: "Trust a CA",
+          shell: "pg-explain run --sslmode verify-full --sslrootcert <ca.pem> ..."
+        }
+      ]
+    },
+    docsUrl: `${DOCS}/libpq-ssl.html`
+  },
+  PGX_CONN_TIMEOUT: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Connection timed out",
+    detail: "The connect handshake did not complete within the connect deadline.",
+    cause: "High network latency, an overloaded server, or a firewall silently dropping packets.",
+    remediation: {
+      summary: "Raise the connect budget and investigate the network path.",
+      commands: [
+        { label: "Increase connect timeout", shell: "pg-explain run --connect-timeout 30s ..." }
+      ]
+    },
+    docsUrl: `${DOCS}/libpq-connect.html`
+  },
+  PGX_PERMISSION_DENIED: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Permission denied",
+    detail: "The connecting role lacks a privilege the query needs.",
+    cause: "EXPLAIN must plan the query, which requires SELECT (and any referenced privileges) on the relations.",
+    remediation: {
+      summary: "Grant the missing privilege, or connect with a role that already has it.",
+      commands: [
+        { label: "Grant SELECT (run as owner)", sql: "GRANT SELECT ON <table> TO <role>;" }
+      ]
+    },
+    docsUrl: `${DOCS}/sql-grant.html`
+  },
+  PGX_RELATION_NOT_FOUND: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Relation does not exist",
+    detail: "A table or view referenced by the query was not found.",
+    cause: "The name is misspelled, or it lives in a schema that is not on the search_path.",
+    remediation: {
+      summary: "Schema-qualify the relation or set the search_path.",
+      steps: ["Check spelling and the schema.", "List tables with `\\dt` in psql."],
+      commands: [{ label: "Set the search path", sql: "SET search_path = <schema>, public;" }]
+    }
+  },
+  PGX_STATEMENT_TIMEOUT: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Statement timeout reached",
+    detail: "statement_timeout fired while EXPLAIN ANALYZE was executing the query.",
+    cause: "The query genuinely takes longer than the configured statement_timeout to run.",
+    remediation: {
+      summary: "Raise the timeout, or avoid executing the query at all.",
+      steps: [
+        "Raise the per-run statement timeout.",
+        "Or get an estimate-only plan that never executes (drop --analyze).",
+        "Or reduce measurement overhead with --timing off."
+      ],
+      commands: [
+        { label: "Raise the timeout", shell: "pg-explain run --statement-timeout 60s ..." }
+      ]
+    },
+    docsUrl: `${DOCS}/runtime-config-client.html#GUC-STATEMENT-TIMEOUT`
+  },
+  PGX_LOCK_TIMEOUT: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Lock timeout reached",
+    detail: "lock_timeout elapsed while waiting to acquire a lock on a relation.",
+    cause: "Another transaction holds a conflicting lock on a relation the query touches.",
+    remediation: {
+      summary: "Raise the lock timeout, identify the blocker, or retry off-peak.",
+      commands: [
+        { label: "Raise the lock timeout", shell: "pg-explain run --lock-timeout 30s ..." },
+        {
+          label: "Find blockers",
+          sql: "SELECT * FROM pg_locks l JOIN pg_stat_activity a USING (pid) WHERE NOT l.granted;"
+        }
+      ]
+    },
+    docsUrl: `${DOCS}/runtime-config-client.html#GUC-LOCK-TIMEOUT`
+  },
+  PGX_QUERY_CANCELED: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "Query was canceled",
+    detail: "The query was canceled by an administrator or a signal before completing.",
+    cause: "An admin pg_cancel_backend call, a resource group, or a pool limit canceled the statement.",
+    remediation: {
+      summary: "Re-run the command; if it recurs, check for admin cancellation or pool limits."
+    }
+  },
+  PGX_UNSUPPORTED_PG_VERSION: {
+    severity: "error",
+    exit: 2 /* Usage */,
+    title: "EXPLAIN option not supported by this server",
+    detail: "A requested EXPLAIN option requires a newer PostgreSQL major version.",
+    cause: "Options are version-gated (e.g. SETTINGS\u226512, WAL\u226513, GENERIC_PLAN\u226516, SERIALIZE/MEMORY\u226517).",
+    remediation: {
+      summary: "Drop the unsupported option, target a newer server, or let pg-explain auto-omit it.",
+      commands: [{ label: "Auto-omit unsupported options", shell: "pg-explain run --compat ..." }]
+    },
+    docsUrl: `${DOCS}/sql-explain.html`
+  },
+  PGX_INVALID_EXPLAIN_OPTION: {
+    severity: "error",
+    exit: 2 /* Usage */,
+    title: "Invalid EXPLAIN option combination",
+    detail: "The server rejected an EXPLAIN option or a mutually-exclusive combination.",
+    cause: "Some options require ANALYZE (WAL, SERIALIZE, TIMING) and GENERIC_PLAN is incompatible with ANALYZE.",
+    remediation: {
+      summary: "Fix the option combination; see `pg-explain --help` for valid combinations.",
+      steps: [
+        "WAL/SERIALIZE/TIMING require --analyze.",
+        "GENERIC_PLAN cannot be combined with --analyze."
+      ]
+    },
+    docsUrl: `${DOCS}/sql-explain.html`
+  },
+  PGX_MALFORMED_JSON: {
+    severity: "error",
+    exit: 4 /* Parse */,
+    title: "Input is not valid JSON",
+    detail: "The plan input could not be parsed as JSON.",
+    cause: "The input was truncated when captured, or it is not EXPLAIN (FORMAT JSON) output.",
+    remediation: {
+      summary: "Validate the input and make sure it is FORMAT JSON output.",
+      commands: [{ label: "Validate JSON", shell: "jq . plan.json" }]
+    }
+  },
+  PGX_UNEXPECTED_PLAN_SHAPE: {
+    severity: "error",
+    exit: 4 /* Parse */,
+    title: "Input is not an EXPLAIN plan",
+    detail: "The JSON parsed but does not contain a recognizable EXPLAIN plan tree.",
+    cause: "The 'Plan' node is missing \u2014 this may be query result rows rather than a plan.",
+    remediation: {
+      summary: "Regenerate the plan with FORMAT JSON and pipe that in.",
+      commands: [
+        { label: "Capture a plan", sql: "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) <your query>;" }
+      ]
+    },
+    docsUrl: `${DOCS}/sql-explain.html`
+  },
+  PGX_EMPTY_INPUT: {
+    severity: "error",
+    exit: 3 /* Input */,
+    title: "No plan input received",
+    detail: "stdin and the named file were both empty.",
+    cause: "No plan was piped in and no query/file was provided.",
+    remediation: {
+      summary: "Pipe a plan, or provide SQL to run.",
+      commands: [
+        { label: "Analyze a saved plan", shell: "pg-explain < plan.json" },
+        { label: "Or run a query", shell: 'pg-explain run --query "<sql>" --dsn <dsn>' }
+      ]
+    }
+  },
+  PGX_NON_SELECT_REFUSED: {
+    severity: "error",
+    exit: 2 /* Usage */,
+    title: "Refusing to ANALYZE a data-modifying statement",
+    detail: "EXPLAIN ANALYZE executes the statement, and this one would modify data.",
+    cause: "INSERT/UPDATE/DELETE/MERGE/DDL run for real under ANALYZE; running it could change your data.",
+    remediation: {
+      summary: "Use --force to run it inside an automatically rolled-back transaction, or drop --analyze.",
+      steps: [
+        "With --force, pg-explain wraps it as `BEGIN; <stmt>; ROLLBACK;` so nothing is committed.",
+        "Without --analyze you get an estimate-only plan that never executes."
+      ],
+      commands: [
+        {
+          label: "Run safely (auto-rollback)",
+          shell: "pg-explain run --force --file mutation.sql --dsn <dsn>"
+        }
+      ]
+    }
+  },
+  PGX_MULTIPLE_STATEMENTS: {
+    severity: "error",
+    exit: 2 /* Usage */,
+    title: "Multiple SQL statements found",
+    detail: "The input contains more than one statement; pg-explain analyzes one at a time.",
+    cause: "A .sql file or --query string contained several semicolon-separated statements.",
+    remediation: {
+      summary: "Select one statement, or split them into separate invocations.",
+      commands: [
+        {
+          label: "Pick the Nth statement (1-based)",
+          shell: "pg-explain run --statement 2 --file queries.sql --dsn <dsn>"
+        }
+      ]
+    }
+  },
+  PGX_COST_ONLY_PLAN: {
+    severity: "info",
+    exit: 0 /* Success */,
+    title: "Cost-only plan \u2014 estimate-vs-actual checks unavailable",
+    detail: "This plan has cost estimates but no actual row/time data.",
+    cause: "It was produced by plain EXPLAIN (without ANALYZE), so runtime behavior is unknown.",
+    remediation: {
+      summary: "Re-run with ANALYZE to unlock estimate-vs-actual, timing, and spill findings.",
+      commands: [
+        { label: "Capture actuals", sql: "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) <query>;" }
+      ]
+    },
+    docsUrl: `${DOCS}/using-explain.html#USING-EXPLAIN-ANALYZE`
+  },
+  PGX_NO_BUFFERS: {
+    severity: "info",
+    exit: 0 /* Success */,
+    title: "No BUFFERS data \u2014 cache/I/O analysis skipped",
+    detail: "Buffer counters are absent, so cache-hit ratio and I/O findings cannot be computed.",
+    cause: "The plan was captured without BUFFERS.",
+    remediation: {
+      summary: "Add BUFFERS to surface shared/temp block usage and the cache-hit ratio.",
+      commands: [
+        { label: "Capture buffers", sql: "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) <query>;" }
+      ]
+    }
+  },
+  PGX_EMPTY_PLAN: {
+    severity: "info",
+    exit: 0 /* Success */,
+    title: "Nothing to analyze",
+    detail: "The plan has no scans or joins to evaluate (e.g. a bare Result node).",
+    cause: "The query is trivial and has no tuning surface.",
+    remediation: { summary: "Confirm this is the query you intended to profile." }
+  },
+  PGX_PG_DRIVER_MISSING: {
+    severity: "error",
+    exit: 2 /* Usage */,
+    title: "The 'pg' driver is not installed",
+    detail: "The run command needs the PostgreSQL driver, which is an optional dependency.",
+    cause: "pgexplain ships 'pg' as optional so plan-only use stays dependency-free; it isn't installed here.",
+    remediation: {
+      summary: "Install the pg driver, then re-run. (Plan-only analysis from a file/stdin needs no driver.)",
+      commands: [
+        { label: "with pnpm", shell: "pnpm add pg" },
+        { label: "with npm", shell: "npm install pg" }
+      ]
+    }
+  },
+  PGX_QUERY_FAILED: {
+    severity: "error",
+    exit: 5 /* Database */,
+    title: "The query could not be planned or executed",
+    detail: "PostgreSQL returned an error while running EXPLAIN.",
+    cause: "The statement has a syntax error, references something invalid, or hit a server-side limit.",
+    remediation: {
+      summary: "Read the server message below, fix the statement, and re-run. Test it in psql first if unsure.",
+      commands: [{ label: "Try it directly", shell: 'psql "<dsn>" -c "EXPLAIN <your statement>"' }]
+    },
+    docsUrl: `${DOCS}/sql-explain.html`
+  },
+  PGX_INTERNAL: {
+    severity: "error",
+    exit: 70 /* Internal */,
+    title: "pg-explain hit an unexpected error",
+    detail: "This is a bug in pg-explain, not in your query or plan.",
+    cause: "An unhandled condition was reached.",
+    remediation: {
+      summary: "Re-run with --debug for a credential-scrubbed stack trace, then file an issue.",
+      commands: [
+        { label: "Show the trace", shell: "pg-explain --debug ..." },
+        { label: "Report your version", shell: "pg-explain --version" }
+      ]
+    }
+  }
+};
+function opDiagnostic(code, overrides = {}) {
+  const spec = CATALOG[code];
+  const diag = {
+    code,
+    domain: "operational",
+    severity: spec.severity,
+    title: spec.title,
+    detail: overrides.detail ?? spec.detail,
+    cause: spec.cause,
+    remediation: spec.remediation
+  };
+  if (spec.docsUrl) diag.docsUrl = spec.docsUrl;
+  if (overrides.location) diag.location = overrides.location;
+  if (overrides.meta) diag.meta = overrides.meta;
+  return diag;
+}
+function opError(code, overrides = {}, cause) {
+  return new AppError(opDiagnostic(code, overrides), CATALOG[code].exit, cause);
+}
+var DEFAULT_THRESHOLDS = {
+  seqScanRows: 1e5,
+  nestedLoopOuterRows: 1e4,
+  filterDiscardRatio: 0.9,
+  filterRemovedAbs: 1e4,
+  misestimateFactor: 10,
+  heapFetchRatio: 0.1,
+  heapFetchAbs: 1e3,
+  correlatedLoops: 1e3,
+  jitPct: 25,
+  triggerPct: 10,
+  lowCacheHitRatio: 0.9
+};
+var DEFAULT_CONFIG = {
+  thresholds: { ...DEFAULT_THRESHOLDS },
+  rules: {}
+};
+var CONFIG_FILES = [".pgexplainrc.json", ".pgexplainrc"];
+function merge(partial) {
+  return {
+    thresholds: { ...DEFAULT_THRESHOLDS, ...partial.thresholds ?? {} },
+    rules: { ...partial.rules ?? {} }
+  };
+}
+async function readJson(path) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (err) {
+    throw opError(
+      "PGX_EMPTY_INPUT",
+      {
+        detail: `Could not read config '${path}': ${err instanceof Error ? err.message : String(err)}`
+      },
+      err
+    );
+  }
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw opError(
+      "PGX_MALFORMED_JSON",
+      {
+        detail: `Config '${path}' is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
+      },
+      err
+    );
+  }
+}
+async function loadConfig(explicitPath, cwd = process.cwd()) {
+  if (explicitPath) return merge(await readJson(explicitPath));
+  for (const name of CONFIG_FILES) {
+    try {
+      const text = await readFile(join(cwd, name), "utf8");
+      return merge(JSON.parse(text));
+    } catch {
+    }
+  }
+  try {
+    const pkg = JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
+    if (pkg.pgExplain) return merge(pkg.pgExplain);
+  } catch {
+  }
+  return { ...DEFAULT_CONFIG, thresholds: { ...DEFAULT_THRESHOLDS }, rules: {} };
+}
+var PlanNodeSchema = z.looseObject({
+  "Node Type": z.string(),
+  get Plans() {
+    return z.array(PlanNodeSchema).optional();
+  }
+});
+var StatementSchema = z.looseObject({
+  Plan: PlanNodeSchema,
+  "Planning Time": z.number().optional(),
+  "Execution Time": z.number().optional(),
+  Triggers: z.array(z.looseObject({})).optional(),
+  JIT: z.looseObject({}).optional(),
+  Settings: z.record(z.string(), z.unknown()).optional()
+});
+var ExplainOutputSchema = z.array(StatementSchema).min(1);
+
+// src/core/parse.ts
+function num(raw, key) {
+  const v = raw[key];
+  return typeof v === "number" ? v : void 0;
+}
+function str(raw, key) {
+  const v = raw[key];
+  return typeof v === "string" ? v : void 0;
+}
+function strArray(raw, key) {
+  const v = raw[key];
+  if (Array.isArray(v) && v.every((x) => typeof x === "string")) return v;
+  if (typeof v === "string") return [v];
+  return void 0;
+}
+function parseJsonWithLocation(input) {
+  try {
+    return JSON.parse(input);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    let line;
+    let col;
+    const lc = message.match(/line (\d+) column (\d+)/i);
+    if (lc?.[1] && lc[2]) {
+      line = Number(lc[1]);
+      col = Number(lc[2]);
+    } else {
+      const pos = message.match(/position (\d+)/i);
+      if (pos?.[1]) {
+        const offset = Number(pos[1]);
+        const before = input.slice(0, offset);
+        line = before.split("\n").length;
+        col = offset - before.lastIndexOf("\n");
+      }
+    }
+    const where = line && col ? ` (line ${line}, col ${col})` : "";
+    throw opError(
+      "PGX_MALFORMED_JSON",
+      {
+        detail: `The plan input could not be parsed as JSON${where}: ${message}`,
+        location: line && col ? { kind: "input", line, col } : { kind: "input" }
+      },
+      err
+    );
+  }
+}
+function normalizeNode(raw, nextId) {
+  const node = {
+    id: nextId(),
+    nodeType: raw["Node Type"],
+    planRows: num(raw, "Plan Rows") ?? 0,
+    children: [],
+    metrics: {},
+    raw
+  };
+  assign(node, {
+    parentRelationship: str(raw, "Parent Relationship"),
+    subplanName: str(raw, "Subplan Name"),
+    relationName: str(raw, "Relation Name"),
+    schema: str(raw, "Schema"),
+    alias: str(raw, "Alias"),
+    indexName: str(raw, "Index Name"),
+    planWidth: num(raw, "Plan Width"),
+    startupCost: num(raw, "Startup Cost"),
+    totalCost: num(raw, "Total Cost"),
+    actualRows: num(raw, "Actual Rows"),
+    actualLoops: num(raw, "Actual Loops"),
+    actualStartupTime: num(raw, "Actual Startup Time"),
+    actualTotalTime: num(raw, "Actual Total Time"),
+    filter: str(raw, "Filter"),
+    rowsRemovedByFilter: num(raw, "Rows Removed by Filter"),
+    indexCond: str(raw, "Index Cond"),
+    recheckCond: str(raw, "Recheck Cond"),
+    rowsRemovedByIndexRecheck: num(raw, "Rows Removed by Index Recheck"),
+    heapFetches: num(raw, "Heap Fetches"),
+    hashCond: str(raw, "Hash Cond"),
+    joinType: str(raw, "Join Type"),
+    joinFilter: str(raw, "Join Filter"),
+    rowsRemovedByJoinFilter: num(raw, "Rows Removed by Join Filter"),
+    output: strArray(raw, "Output"),
+    sortMethod: str(raw, "Sort Method"),
+    sortSpaceType: str(raw, "Sort Space Type"),
+    sortSpaceUsed: num(raw, "Sort Space Used"),
+    sortKey: strArray(raw, "Sort Key"),
+    hashBuckets: num(raw, "Hash Buckets"),
+    originalHashBuckets: num(raw, "Original Hash Buckets"),
+    hashBatches: num(raw, "Hash Batches"),
+    originalHashBatches: num(raw, "Original Hash Batches"),
+    peakMemoryUsage: num(raw, "Peak Memory Usage"),
+    diskUsage: num(raw, "Disk Usage"),
+    exactHeapBlocks: num(raw, "Exact Heap Blocks"),
+    lossyHeapBlocks: num(raw, "Lossy Heap Blocks"),
+    sharedHitBlocks: num(raw, "Shared Hit Blocks"),
+    sharedReadBlocks: num(raw, "Shared Read Blocks"),
+    sharedDirtiedBlocks: num(raw, "Shared Dirtied Blocks"),
+    sharedWrittenBlocks: num(raw, "Shared Written Blocks"),
+    localHitBlocks: num(raw, "Local Hit Blocks"),
+    localReadBlocks: num(raw, "Local Read Blocks"),
+    tempReadBlocks: num(raw, "Temp Read Blocks"),
+    tempWrittenBlocks: num(raw, "Temp Written Blocks"),
+    ioReadTime: num(raw, "I/O Read Time"),
+    ioWriteTime: num(raw, "I/O Write Time"),
+    workersPlanned: num(raw, "Workers Planned"),
+    workersLaunched: num(raw, "Workers Launched")
+  });
+  const childPlans = raw.Plans;
+  if (Array.isArray(childPlans)) {
+    for (const child of childPlans) {
+      node.children.push(normalizeNode(child, nextId));
+    }
+  }
+  return node;
+}
+function assign(target, fields) {
+  for (const [k, v] of Object.entries(fields)) {
+    if (v !== void 0) target[k] = v;
+  }
+}
+function parseTriggers(raw) {
+  if (!Array.isArray(raw)) return [];
+  return raw.map((t) => {
+    const r = t;
+    const info = {};
+    assign(info, {
+      name: str(r, "Trigger Name"),
+      constraintName: str(r, "Constraint Name"),
+      relation: str(r, "Relation"),
+      calls: num(r, "Calls"),
+      time: num(r, "Time")
+    });
+    return info;
+  });
+}
+function parseJit(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const r = raw;
+  const timing = r.Timing;
+  const jit = {};
+  const functions = num(r, "Functions");
+  if (functions !== void 0) jit.functions = functions;
+  if (timing && typeof timing === "object") {
+    jit.timing = {
+      total: num(timing, "Total"),
+      generation: num(timing, "Generation"),
+      inlining: num(timing, "Inlining"),
+      optimization: num(timing, "Optimization"),
+      emission: num(timing, "Emission")
+    };
+  }
+  return jit;
+}
+function parseExplainJson(input) {
+  const json = parseJsonWithLocation(input);
+  let candidate = json;
+  if (json && typeof json === "object" && !Array.isArray(json)) {
+    const obj = json;
+    candidate = "Plan" in obj ? [obj] : "Node Type" in obj ? [{ Plan: obj }] : json;
+  }
+  const result = ExplainOutputSchema.safeParse(candidate);
+  if (!result.success) {
+    throw opError("PGX_UNEXPECTED_PLAN_SHAPE", {
+      detail: `The JSON is valid but is not an EXPLAIN plan: ${result.error.issues[0]?.message ?? "missing 'Plan' node"}.`,
+      location: { kind: "input" }
+    });
+  }
+  return result.data.map((stmt) => {
+    let id = 0;
+    const root = normalizeNode(stmt.Plan, () => id++);
+    const hasAnalyze = root.actualLoops !== void 0 || stmt["Execution Time"] !== void 0;
+    const hasBuffers = root.sharedHitBlocks !== void 0 || root.sharedReadBlocks !== void 0;
+    const tree = {
+      root,
+      triggers: parseTriggers(stmt.Triggers),
+      hasAnalyze,
+      hasBuffers,
+      raw: stmt.Plan
+    };
+    if (stmt["Planning Time"] !== void 0) tree.planningTime = stmt["Planning Time"];
+    if (stmt["Execution Time"] !== void 0) tree.executionTime = stmt["Execution Time"];
+    const jit = parseJit(stmt.JIT);
+    if (jit) tree.jit = jit;
+    if (stmt.Settings) tree.settings = stmt.Settings;
+    return tree;
+  });
+}
+function walk(node, visit) {
+  visit(node);
+  for (const child of node.children) walk(child, visit);
+}
+function flatten(node) {
+  const out = [];
+  walk(node, (n) => out.push(n));
+  return out;
+}
+
+// src/core/metrics.ts
+function computeMetrics(tree) {
+  walk(tree.root, (node) => {
+    const { actualRows, actualLoops, actualTotalTime } = node;
+    if (actualRows !== void 0 && actualLoops !== void 0) {
+      node.metrics.totalRows = actualRows * actualLoops;
+    }
+    if (actualTotalTime !== void 0 && actualLoops !== void 0) {
+      node.metrics.inclusiveMs = actualTotalTime * actualLoops;
+    }
+    if (node.metrics.totalRows !== void 0) {
+      const est = Math.max(node.planRows, 1);
+      const act = Math.max(node.metrics.totalRows, 1);
+      node.metrics.estimateFactor = est >= act ? est / act : act / est;
+      node.metrics.estimateDirection = node.planRows > node.metrics.totalRows ? "over" : node.metrics.totalRows > node.planRows ? "under" : "accurate";
+    }
+    const hit = node.sharedHitBlocks ?? 0;
+    const read = node.sharedReadBlocks ?? 0;
+    node.metrics.cacheHitRatio = hit + read > 0 ? hit / (hit + read) : null;
+    if (node.rowsRemovedByFilter !== void 0 && actualLoops !== void 0) {
+      const removed = node.rowsRemovedByFilter * actualLoops;
+      const kept = node.metrics.totalRows ?? 0;
+      const denom = removed + kept;
+      if (denom > 0) node.metrics.filterDiscardRatio = removed / denom;
+    }
+    if (node.lossyHeapBlocks !== void 0) {
+      const lossy = node.lossyHeapBlocks;
+      const exact = node.exactHeapBlocks ?? 0;
+      const denom = lossy + exact;
+      if (denom > 0) node.metrics.lossyRatio = lossy / denom;
+    }
+  });
+  walk(tree.root, (node) => {
+    if (node.metrics.inclusiveMs === void 0) return;
+    let childrenMs = 0;
+    for (const child of node.children) childrenMs += child.metrics.inclusiveMs ?? 0;
+    node.metrics.selfMs = Math.max(node.metrics.inclusiveMs - childrenMs, 0);
+  });
+  const totalMs = executionMs(tree);
+  if (totalMs && totalMs > 0) {
+    walk(tree.root, (node) => {
+      if (node.metrics.selfMs !== void 0) {
+        node.metrics.pctOfTotal = 100 * node.metrics.selfMs / totalMs;
+      }
+    });
+  }
+}
+function executionMs(tree) {
+  return tree.executionTime ?? tree.root.metrics.inclusiveMs;
+}
+function bottlenecks(tree, n = 5) {
+  return flatten(tree.root).filter((node) => node.metrics.selfMs !== void 0).sort((a, b) => (b.metrics.selfMs ?? 0) - (a.metrics.selfMs ?? 0)).slice(0, n);
+}
+function nodeLabel(node) {
+  let label = node.nodeType;
+  if (node.indexName && node.relationName)
+    label += ` using ${node.indexName} on ${node.relationName}`;
+  else if (node.relationName) label += ` on ${node.relationName}`;
+  if (node.alias && node.alias !== node.relationName) label += ` (${node.alias})`;
+  return label;
+}
+
+// src/util/format.ts
+var BLOCK_BYTES = 8192;
+function fmtInt(n) {
+  return Math.round(n).toLocaleString("en-US");
+}
+function fmtMs(ms) {
+  if (ms < 1) return `${ms.toFixed(3)} ms`;
+  if (ms < 1e3) return `${ms.toFixed(1)} ms`;
+  if (ms < 6e4) return `${(ms / 1e3).toFixed(2)} s`;
+  const min = Math.floor(ms / 6e4);
+  const sec = (ms % 6e4 / 1e3).toFixed(0);
+  return `${min}m ${sec}s`;
+}
+function fmtPct(fraction0to100) {
+  return `${fraction0to100.toFixed(1)}%`;
+}
+function fmtKiB(kib) {
+  return fmtBytes(kib * 1024);
+}
+function fmtBlocks(blocks) {
+  return `${fmtInt(blocks)} blk (${fmtBytes(blocks * BLOCK_BYTES)})`;
+}
+function fmtBytes(bytes) {
+  const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+  let v = bytes;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  const s = i === 0 ? String(Math.round(v)) : v.toFixed(1);
+  return `${s} ${units[i]}`;
+}
+function roundUpMiB(kib, stepMiB = 4) {
+  const mib = Math.ceil(kib / 1024 / stepMiB) * stepMiB;
+  return `${Math.max(mib, stepMiB)}MB`;
+}
+var UNICODE_TREE = { branch: "\u251C\u2500 ", last: "\u2514\u2500 ", vert: "\u2502  ", space: "   " };
+var ASCII_TREE = { branch: "+- ", last: "`- ", vert: "|  ", space: "   " };
+
+// src/advisor/rules/util.ts
+var DOCS2 = "https://www.postgresql.org/docs/current";
+function locationOf(node) {
+  const loc = { kind: "node", nodeId: node.id, nodeType: node.nodeType };
+  if (node.relationName) loc.relation = node.relationName;
+  return loc;
+}
+function makeFinding(rule, ctx, node, parts) {
+  const d = {
+    code: rule.id,
+    domain: "plan",
+    severity: ctx.severityOf(rule.id, parts.severity ?? rule.defaultSeverity),
+    title: parts.title,
+    detail: parts.detail,
+    cause: parts.cause,
+    remediation: parts.remediation,
+    location: locationOf(node)
+  };
+  if (parts.docsUrl) d.docsUrl = parts.docsUrl;
+  if (parts.meta) d.meta = parts.meta;
+  return d;
+}
+function outerChild(node) {
+  return node.children[0];
+}
+
+// src/advisor/rules/bitmap-lossy.ts
+var bitmapLossy = {
+  id: "PGX_BITMAP_LOSSY",
+  title: "Lossy bitmap heap scan",
+  defaultSeverity: "info",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Bitmap Heap Scan") return [];
+    const lossy = node.lossyHeapBlocks ?? 0;
+    if (lossy <= 0) return [];
+    const exact = node.exactHeapBlocks ?? 0;
+    const rel = node.relationName ?? "the table";
+    const rechecked = node.rowsRemovedByIndexRecheck ?? 0;
+    const recheckNote = rechecked > 0 ? ` The recheck discarded ${fmtInt(rechecked)} extra rows that the lossy bitmap could not exclude.` : "";
+    return [
+      makeFinding(bitmapLossy, ctx, node, {
+        title: `Lossy bitmap heap scan on ${rel} (${fmtInt(lossy)} lossy blocks)`,
+        detail: `The bitmap for ${rel} held ${fmtInt(lossy)} lossy (page-granularity) blocks alongside ${fmtInt(
+          exact
+        )} exact blocks, so Postgres re-checked the index condition against every tuple on the lossy pages.${recheckNote}`,
+        cause: "The exact (per-tuple) bitmap did not fit in work_mem, so Postgres fell back to storing whole heap pages and recheck the index condition while reading them \u2014 more heap I/O and CPU than an exact bitmap.",
+        remediation: {
+          summary: `Raise work_mem for this session so the bitmap stays exact (no lossy blocks, no rechecks) on ${rel}; alternatively make the index condition more selective or add a composite index so the bitmap is smaller.`,
+          steps: [
+            "Increase work_mem for the session, then re-run EXPLAIN (ANALYZE) and confirm Lossy Heap Blocks drops to 0.",
+            "If raising work_mem is undesirable, make the index condition more selective (a more selective leading column or a composite index over the filtered columns) so fewer heap pages enter the bitmap."
+          ],
+          commands: [
+            {
+              label: "Give this session more work_mem",
+              sql: "SET work_mem = '<X>MB';"
+            },
+            {
+              label: "Or shrink the bitmap with a more selective index",
+              sql: `CREATE INDEX ON ${rel} (<more selective / composite columns>);`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-resource.html#GUC-WORK-MEM`,
+        meta: { lossyBlocks: lossy, exactBlocks: exact }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/cartesian-product.ts
+function rowsOf(node) {
+  return node.metrics.totalRows ?? node.planRows;
+}
+var cartesianProduct = {
+  id: "PGX_CARTESIAN_PRODUCT",
+  title: "Cartesian product (missing join condition)",
+  defaultSeverity: "error",
+  check(node, ctx) {
+    if (node.nodeType !== "Nested Loop") return [];
+    if (node.joinFilter) return [];
+    const inner = node.children[1];
+    if (!inner) return [];
+    if (inner.indexCond || inner.recheckCond) return [];
+    const outer = node.children[0];
+    if (!outer) return [];
+    const outerRows = rowsOf(outer);
+    const innerRows = rowsOf(inner);
+    if (outerRows <= 1 || innerRows <= 1) return [];
+    const estimated = node.metrics.totalRows === void 0;
+    const product = fmtInt(outerRows * innerRows);
+    return [
+      makeFinding(cartesianProduct, ctx, node, {
+        title: `Cartesian product: Nested Loop with no join condition (~${product}${estimated ? " est." : ""} rows)`,
+        detail: `The Nested Loop has no Join Filter and the inner side has no Index Cond or Recheck Cond, so each of ${fmtInt(
+          outerRows
+        )} outer rows is paired with every one of ${fmtInt(innerRows)} inner rows${estimated ? " (estimated \u2014 run with ANALYZE for actuals)" : ""}.`,
+        cause: "No predicate links the two relations, so Postgres can only emit the full cross product. This usually means an ON or WHERE join condition was omitted (e.g. a comma join across tables).",
+        remediation: {
+          summary: "Add the missing join condition linking the two tables on their key columns (e.g. ON a.id = b.a_id). If a cross product is truly intended, make it explicit with CROSS JOIN and bound it with a LIMIT or aggregation.",
+          steps: [
+            "Find the two relations feeding this Nested Loop in your query.",
+            "Add an ON (or WHERE) clause matching their key columns so the loop becomes selective.",
+            "If you really want every combination, write CROSS JOIN explicitly and cap the size with LIMIT or an aggregate."
+          ],
+          commands: [
+            {
+              label: "Add the join predicate",
+              sql: "SELECT ...\nFROM <outer_table> a\nJOIN <inner_table> b ON a.<key> = b.<key>;"
+            },
+            {
+              label: "Or make the cross join explicit and bounded",
+              sql: "SELECT ...\nFROM <outer_table> a\nCROSS JOIN <inner_table> b\nLIMIT <n>;"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/queries-table-expressions.html#QUERIES-JOIN`,
+        meta: { outerRows: Math.round(outerRows), innerRows: Math.round(innerRows) }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/correlated-subplan.ts
+var correlatedSubplan = {
+  id: "PGX_CORRELATED_SUBPLAN",
+  title: "Correlated subplan re-executed per row",
+  defaultSeverity: "warn",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    const isSubplan = node.parentRelationship === "SubPlan" || (node.subplanName?.startsWith("SubPlan") ?? false);
+    if (!isSubplan) return [];
+    const loops = node.actualLoops ?? 0;
+    if (loops <= ctx.thresholds.correlatedLoops) return [];
+    const name = node.subplanName ?? "the subplan";
+    return [
+      makeFinding(correlatedSubplan, ctx, node, {
+        title: `Correlated ${name} re-executed ${fmtInt(loops)} times`,
+        detail: `${name} ran ${fmtInt(loops)} times \u2014 once per outer row \u2014 instead of being evaluated a single time.`,
+        cause: "The subquery references a column from the enclosing query, so the planner cannot pull it out of the per-row loop and re-runs the whole subplan for every outer row.",
+        remediation: {
+          summary: `De-correlate the subquery: rewrite it as a JOIN or LATERAL join, or hoist it into a CTE/derived table evaluated once, then index the correlation key so the rewrite stays cheap.`,
+          steps: [
+            "Identify the outer column the subquery references (the correlation key).",
+            "For a scalar subquery in SELECT/WHERE, rewrite it as a LEFT JOIN to a grouped derived table, or a LATERAL join when it returns per-row results.",
+            "For EXISTS/IN, prefer the semi-join form (EXISTS / = ANY) the planner can de-correlate into a single hash/merge join.",
+            "Add an index on the correlation key so the resulting JOIN does not fall back to the same per-row cost.",
+            // Before (correlated, runs once per outer row):
+            //   SELECT o.id, (SELECT count(*) FROM events e WHERE e.order_id = o.id) AS n FROM orders o;
+            // After (evaluated once, joined):
+            //   SELECT o.id, COALESCE(e.n, 0) AS n
+            //   FROM orders o
+            //   LEFT JOIN (SELECT order_id, count(*) AS n FROM events GROUP BY order_id) e
+            //     ON e.order_id = o.id;
+            "See the before/after sketch: SELECT (SELECT count(*) FROM events e WHERE e.order_id = o.id) becomes a LEFT JOIN to (SELECT order_id, count(*) FROM events GROUP BY order_id)."
+          ],
+          commands: [
+            {
+              label: "Index the correlation key so the de-correlated JOIN stays cheap",
+              sql: "CREATE INDEX ON <subquery table> (<correlation key column>);"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/queries-table-expressions.html#QUERIES-LATERAL`,
+        meta: { loops }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/could-be-index-only.ts
+var couldBeIndexOnly = {
+  id: "PGX_COULD_BE_INDEX_ONLY",
+  title: "Index scan may be eligible for index-only",
+  defaultSeverity: "info",
+  check(node, ctx) {
+    if (node.nodeType !== "Index Scan") return [];
+    if (!node.indexName) return [];
+    if (node.filter) return [];
+    if (!node.output || node.output.length === 0) return [];
+    if (node.output.length > 4) return [];
+    const rel = node.relationName ?? "the table";
+    const cols = node.output;
+    const colList = cols.join(", ");
+    const includeCols = cols.join(", ");
+    return [
+      makeFinding(couldBeIndexOnly, ctx, node, {
+        title: `Index Scan using ${node.indexName} on ${rel} may be eligible for index-only`,
+        detail: `This Index Scan projects only ${cols.length} column${cols.length === 1 ? "" : "s"} (${colList}) and applies no residual filter, so its predicate is fully resolved by ${node.indexName}. If that index also covers the selected columns, Postgres could use an Index Only Scan and skip the heap entirely.`,
+        cause: "An Index Scan still visits the table heap to fetch the projected columns. When every selected column is contained in the index (as a key or INCLUDE column) and the visibility map is current, Postgres can answer from the index alone (Index Only Scan).",
+        remediation: {
+          summary: `Add the selected columns (${includeCols}) to ${node.indexName} as INCLUDE columns so it covers the query, then keep the visibility map current with VACUUM so Postgres can switch ${rel} to an Index Only Scan.`,
+          steps: [
+            "Confirm which columns the index already covers (\\d <index> in psql) \u2014 this hint assumes VERBOSE Output and cannot read the index definition.",
+            "If any projected column is missing, recreate the index with those columns as INCLUDE (non-key) columns.",
+            "Run VACUUM so the visibility map is set; Index Only Scans fall back to heap fetches on pages not marked all-visible."
+          ],
+          commands: [
+            {
+              label: "Create a covering index",
+              sql: `CREATE INDEX ON ${rel} (<key columns from the Index Cond>) INCLUDE (${includeCols});`
+            },
+            {
+              label: "Keep the visibility map current",
+              sql: `VACUUM ${rel};`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/indexes-index-only-scans.html`,
+        meta: { outputColumns: cols.length }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/filter-could-be-index-cond.ts
+var filterCouldBeIndexCond = {
+  id: "PGX_FILTER_COULD_BE_INDEX_COND",
+  title: "Filter could be an index condition",
+  defaultSeverity: "info",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    const indexed = node.nodeType === "Index Scan" || node.nodeType === "Index Only Scan" || node.nodeType === "Bitmap Heap Scan";
+    if (!indexed) return [];
+    if (!node.filter) return [];
+    if (!node.indexCond && !node.recheckCond) return [];
+    if ((node.rowsRemovedByFilter ?? 0) <= 0) return [];
+    const rel = node.relationName ?? "the table";
+    const cond = node.indexCond ?? node.recheckCond ?? "";
+    const loops = node.actualLoops ?? 1;
+    const removed = (node.rowsRemovedByFilter ?? 0) * loops;
+    return [
+      makeFinding(filterCouldBeIndexCond, ctx, node, {
+        title: `Residual filter on ${rel} could be an index condition`,
+        detail: `${node.nodeType} on ${rel} used the index for ${cond} but then applied Filter ${node.filter} to the fetched rows, discarding ${fmtInt(removed)} of them.`,
+        cause: `The Filter columns are not part of the index, so Postgres must fetch each row the index matched and re-check the predicate in the executor instead of skipping non-matching entries during the index traversal.`,
+        remediation: {
+          summary: `Extend the index on ${rel} to include the Filter columns from ${node.filter} as trailing key columns, so the predicate is applied as an Index Cond during traversal instead of as a post-fetch Filter.`,
+          steps: [
+            `Confirm the Filter ${node.filter} is sargable \u2014 no functions or implicit casts wrapping the column.`,
+            "Append the filter columns after the existing key columns so the index still serves the original lookup.",
+            "Re-run EXPLAIN (ANALYZE) and check the Filter moved into the Index Cond with no Rows Removed by Filter."
+          ],
+          commands: [
+            {
+              label: "Extend the index with the filter columns",
+              sql: `CREATE INDEX ON ${rel} (<existing key columns>, <filter columns>);`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/indexes-multicolumn.html`,
+        meta: { rowsRemovedByFilter: Math.round(removed) }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/hash-spill-disk.ts
+var hashSpillDisk = {
+  id: "PGX_HASH_SPILL_DISK",
+  title: "Hash join spilled to disk",
+  defaultSeverity: "warn",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Hash") return [];
+    const hashBatches = node.hashBatches ?? 1;
+    if (hashBatches <= 1) return [];
+    const originalHashBatches = node.originalHashBatches ?? hashBatches;
+    const repartitioned = hashBatches > originalHashBatches;
+    const peakKiB = node.peakMemoryUsage ?? 0;
+    const diskKiB = node.diskUsage ?? 0;
+    const workMemRecommended = roundUpMiB((peakKiB + diskKiB) * 1.2);
+    return [
+      makeFinding(hashSpillDisk, ctx, node, {
+        title: `Hash build side spilled to disk (${fmtInt(hashBatches)} batches)`,
+        detail: `The hash table was split into ${fmtInt(hashBatches)} batches${repartitioned ? ` (up from ${fmtInt(originalHashBatches)} planned)` : ""}, so the build side did not fit in work_mem and overflowed to temporary files${diskKiB > 0 ? ` (${fmtKiB(diskKiB)} written to disk)` : ""}.`,
+        cause: repartitioned ? "Postgres had to add batches at runtime because the build side was larger than estimated \u2014 usually a row underestimate sized work_mem too small." : "The build (hash) side was larger than work_mem, forcing the hash join to partition it across disk-backed batches.",
+        remediation: {
+          summary: `Raise work_mem to about ${workMemRecommended} so the build side fits in a single batch, and make sure the SMALLER input is the hash/build side (a wrong build side usually comes from a row underestimate \u2014 fix the stats). Reducing build-side rows also avoids the spill.`,
+          steps: [
+            `Set work_mem high enough to hold the build side in one batch (~${workMemRecommended} here) at session or role scope, not globally \u2014 every sort/hash node can use work_mem, so a global bump can exhaust memory.`,
+            "Confirm the smaller relation is on the build (Hash) side; if Postgres chose the larger side, a row underestimate is likely \u2014 re-run ANALYZE or raise statistics targets so the planner picks the smaller build side.",
+            "Alternatively, filter or aggregate the build side earlier so fewer rows need to be hashed."
+          ],
+          commands: [
+            {
+              label: "Raise work_mem for this session",
+              sql: `SET work_mem = '${workMemRecommended}';`
+            },
+            {
+              label: "Or set it for a specific role",
+              sql: `ALTER ROLE <role> SET work_mem = '${workMemRecommended}';`
+            },
+            {
+              label: "Refresh planner statistics on the build-side table",
+              sql: "ANALYZE <build_side_table>;"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-resource.html#GUC-WORK-MEM`,
+        meta: { hashBatches, workMemRecommended }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/high-filter-discard.ts
+var highFilterDiscard = {
+  id: "PGX_HIGH_FILTER_DISCARD",
+  title: "Filter discards most rows read",
+  defaultSeverity: "warn",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    const ratio = node.metrics.filterDiscardRatio;
+    if (ratio === void 0 || ratio <= ctx.thresholds.filterDiscardRatio) return [];
+    const removed = (node.rowsRemovedByFilter ?? 0) * (node.actualLoops ?? 1);
+    if (removed <= ctx.thresholds.filterRemovedAbs) return [];
+    const rel = node.relationName ?? "the table";
+    const kept = node.metrics.totalRows ?? 0;
+    const discardPct = ratio * 100;
+    const filter = node.filter ?? "the filter predicate";
+    return [
+      makeFinding(highFilterDiscard, ctx, node, {
+        title: `Filter on ${rel} discards ${fmtPct(discardPct)} of rows read`,
+        detail: `Postgres read this node's rows then dropped ${fmtInt(removed)} of them (${fmtPct(
+          discardPct
+        )}), keeping only ${fmtInt(kept)}, via the post-read filter ${filter}.`,
+        cause: `The predicate ${filter} is evaluated as a Filter after the rows are fetched, so every discarded row was still read and examined \u2014 work no index condition narrowed.`,
+        remediation: {
+          summary: `Move ${filter} into an index on ${rel} so the predicate becomes an Index Cond instead of a post-read Filter, letting Postgres skip the non-matching rows. For a low-cardinality predicate, a partial index keyed on the discarded condition is smaller and faster.`,
+          steps: [
+            "Identify the column(s) referenced by the filter above.",
+            "Ensure the predicate is sargable (no function-wrapping or implicit casts on the indexed column).",
+            "Use a plain index when the columns are selective across queries; use a partial index when the same constant predicate is always applied."
+          ],
+          commands: [
+            {
+              label: "Index the filter columns",
+              sql: `CREATE INDEX ON ${rel} (<filter columns>);`
+            },
+            {
+              label: "Or a partial index for a fixed low-cardinality predicate",
+              sql: `CREATE INDEX ON ${rel} (<filter columns>) WHERE <predicate>;`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/indexes-partial.html`,
+        meta: { discardPct: Math.round(discardPct) }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/index-only-heap-fetches.ts
+var indexOnlyHeapFetches = {
+  id: "PGX_INDEX_ONLY_HEAP_FETCHES",
+  title: "Index-only scan with heap fetches",
+  defaultSeverity: "info",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Index Only Scan") return [];
+    const heapFetches = node.heapFetches ?? 0;
+    if (heapFetches <= 0) return [];
+    const rows = Math.max(node.metrics.totalRows ?? 1, 1);
+    const ratio = heapFetches / rows;
+    if (ratio <= ctx.thresholds.heapFetchRatio && heapFetches <= ctx.thresholds.heapFetchAbs) {
+      return [];
+    }
+    const rel = node.relationName ?? "the table";
+    return [
+      makeFinding(indexOnlyHeapFetches, ctx, node, {
+        title: `Index-only scan on ${rel} did ${fmtInt(heapFetches)} heap fetches`,
+        detail: `The index-only scan on ${rel} fell back to the heap ${fmtInt(heapFetches)} times for ${fmtInt(
+          rows
+        )} rows produced. Each fetch is an extra table page read the index-only path was meant to avoid.`,
+        cause: `Heap fetches happen when the visibility map does not mark the pages as all-visible, so Postgres must read the table row to confirm visibility. This usually means ${rel} has not been vacuumed recently enough for its write/update rate.`,
+        remediation: {
+          summary: `Run VACUUM (or VACUUM ANALYZE) on ${rel} to refresh the visibility map so the index-only scan can skip the heap. For a high-churn table, lower autovacuum_vacuum_scale_factor so autovacuum keeps the map current.`,
+          steps: [
+            `VACUUM ${rel} to update the visibility map; add ANALYZE if statistics are also stale.`,
+            "If heap fetches keep returning, the table is updated faster than autovacuum runs \u2014 make autovacuum more aggressive on it.",
+            "Confirm the scan stays index-only afterwards by re-running EXPLAIN (ANALYZE) and checking Heap Fetches drops toward 0."
+          ],
+          commands: [
+            {
+              label: "Refresh the visibility map",
+              sql: `VACUUM (ANALYZE) ${rel};`
+            },
+            {
+              label: "Keep the map current on a high-churn table",
+              sql: `ALTER TABLE ${rel} SET (autovacuum_vacuum_scale_factor = 0.02);`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/indexes-index-only-scans.html`,
+        meta: { heapFetches }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/low-cache-hit.ts
+var MIN_READ_BLOCKS = 1e3;
+var lowCacheHit = {
+  id: "PGX_LOW_CACHE_HIT",
+  title: "Low cache hit ratio (heavy disk reads)",
+  defaultSeverity: "info",
+  requiresBuffers: true,
+  check(node, ctx) {
+    const ratio = node.metrics.cacheHitRatio;
+    const readBlocks = node.sharedReadBlocks ?? 0;
+    if (ratio == null) return [];
+    if (ratio >= ctx.thresholds.lowCacheHitRatio) return [];
+    if (readBlocks <= MIN_READ_BLOCKS) return [];
+    const label = nodeLabel(node);
+    const rel = node.relationName;
+    const ratioPct = ratio * 100;
+    return [
+      makeFinding(lowCacheHit, ctx, node, {
+        title: `Low cache hit ratio at ${label} (${fmtPct(ratioPct)})`,
+        detail: `${label} served only ${fmtPct(ratioPct)} of its shared-buffer accesses from cache, reading ${fmtBlocks(readBlocks)} from disk.`,
+        cause: "The pages this node needed were not resident in shared_buffers, so PostgreSQL had to read them from disk. On a first run this is an expected cold cache; if it persists, the working set is larger than the cache or the scan touches more pages than necessary.",
+        remediation: {
+          summary: `Re-run the query to check whether this is just a cold cache \u2014 the ratio should climb on a warm run. If it stays low, the working set exceeds shared_buffers: size shared_buffers/effective_cache_size to your RAM, or add a selective index on ${rel ?? "the scanned relation"} so far fewer pages are read.`,
+          steps: [
+            "Run the same EXPLAIN (ANALYZE, BUFFERS) a second time; a much higher hit ratio means the first run was a cold cache and no action is needed.",
+            "If the ratio stays low, check whether shared_buffers (and effective_cache_size for planner costing) are sized to the machine's RAM.",
+            "If the node reads far more pages than the rows it returns, add a selective index so only matching pages are fetched."
+          ],
+          commands: [
+            {
+              label: "Inspect current buffer-cache sizing",
+              sql: "SHOW shared_buffers; SHOW effective_cache_size;"
+            },
+            {
+              label: "Reduce pages read with a selective index",
+              sql: `CREATE INDEX ON ${rel ?? "<table>"} (<predicate columns>);`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-resource.html#GUC-SHARED-BUFFERS`,
+        meta: { cacheHitPct: Math.round(ratioPct * 10) / 10, readBlocks }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/nested-loop-large-outer.ts
+var nestedLoopLargeOuter = {
+  id: "PGX_NESTED_LOOP_LARGE_OUTER",
+  title: "Nested loop with a large outer side",
+  defaultSeverity: "warn",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Nested Loop") return [];
+    const outer = outerChild(node);
+    const outerRows = outer?.metrics.totalRows;
+    if (outerRows === void 0 || outerRows <= ctx.thresholds.nestedLoopOuterRows) return [];
+    const outerLabel = outer ? nodeLabel(outer) : "the outer side";
+    const inner = node.children[1];
+    const innerLabel = inner ? nodeLabel(inner) : "the inner side";
+    const innerCond = inner?.indexCond ?? inner?.joinFilter ?? inner?.filter ?? node.joinFilter;
+    const misestimated = outer?.metrics.estimateDirection === "under";
+    return [
+      makeFinding(nestedLoopLargeOuter, ctx, node, {
+        title: `Nested loop driven by ${fmtInt(outerRows)} outer rows (${outerLabel})`,
+        detail: `The nested loop's outer side (${outerLabel}) produced ${fmtInt(
+          outerRows
+        )} rows, so its inner side (${innerLabel}) is re-executed roughly that many times.`,
+        cause: misestimated ? `The planner expected far fewer outer rows than the ${fmtInt(
+          outerRows
+        )} that actually came back, so it chose a per-row nested loop where a single hash/merge join would have been cheaper.` : `A nested loop probes the inner side once per outer row; with ${fmtInt(
+          outerRows
+        )} outer rows that is ${fmtInt(outerRows)} inner executions.`,
+        remediation: {
+          summary: `Fix the outer-side row estimate first \u2014 re-ANALYZE ${outer?.relationName ?? "the driving table"}, raise its column statistics, or add extended statistics \u2014 so the planner switches to a hash or merge join. If the estimate is already accurate, add an index on the inner join key (${innerCond ?? "<inner join column>"}) so each of the ${fmtInt(outerRows)} probes is cheap.`,
+          steps: [
+            "Compare the outer node's estimated vs actual rows: a large gap means the estimate is the real problem.",
+            "Refresh statistics so the planner sees the true cardinality and can prefer a hash/merge join.",
+            "If columns are correlated, create extended (multivariate) statistics on them.",
+            "If estimates are already correct, index the inner join key so each probe is an index lookup, not a scan.",
+            "As a last resort to confirm the diagnosis, test with `SET enable_nestloop = off` for this query only."
+          ],
+          commands: [
+            {
+              label: "Refresh planner statistics on the driving table",
+              sql: `ANALYZE ${outer?.relationName ?? "<outer table>"};`
+            },
+            {
+              label: "Increase statistics target on the misestimated column, then re-ANALYZE",
+              sql: `ALTER TABLE ${outer?.relationName ?? "<outer table>"} ALTER COLUMN <column> SET STATISTICS 1000;
+ANALYZE ${outer?.relationName ?? "<outer table>"};`
+            },
+            {
+              label: "Add extended statistics for correlated columns",
+              sql: `CREATE STATISTICS ${outer?.relationName ?? "<outer table>"}_stats (dependencies, ndistinct) ON <col_a>, <col_b> FROM ${outer?.relationName ?? "<outer table>"};
+ANALYZE ${outer?.relationName ?? "<outer table>"};`
+            },
+            {
+              label: "If estimates are correct, index the inner join key",
+              sql: `CREATE INDEX ON ${inner?.relationName ?? "<inner table>"} (<inner join column>);`
+            },
+            {
+              label: "Confirm the diagnosis by disabling nested loops for this query only",
+              sql: "SET enable_nestloop = off;"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-query.html`,
+        meta: { outerRows: Math.round(outerRows) }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/row-misestimate.ts
+var rowMisestimate = {
+  id: "PGX_ROW_MISESTIMATE",
+  title: "Row count misestimate",
+  defaultSeverity: "info",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    const { estimateFactor, estimateDirection, totalRows } = node.metrics;
+    if (estimateFactor === void 0) return [];
+    if (estimateFactor < ctx.thresholds.misestimateFactor) return [];
+    if (estimateDirection === void 0 || estimateDirection === "accurate") return [];
+    const rows = Math.max(totalRows ?? 0, node.planRows);
+    if (rows < 100) return [];
+    const factor = Math.round(estimateFactor);
+    const rel = node.relationName;
+    const onRel = rel ? ` on ${rel}` : "";
+    const target = rel ?? "the underlying table";
+    const under = estimateDirection === "under";
+    const direction = under ? "underestimate" : "overestimate";
+    const actual = totalRows ?? 0;
+    const detail = `Postgres estimated ${fmtInt(node.planRows)} rows but ${fmtInt(actual)} were produced \u2014 a ${fmtInt(factor)}x ${direction}${onRel}.`;
+    return [
+      makeFinding(rowMisestimate, ctx, node, {
+        // Severity: underestimates are the dangerous ones (under-sized joins/memory).
+        severity: under ? "warn" : "info",
+        title: `${fmtInt(factor)}x row ${direction}${onRel}`,
+        detail,
+        cause: "The planner's row estimate is based on statistics that are stale, missing, or too coarse for this predicate (e.g. correlated columns the planner treats as independent).",
+        remediation: {
+          summary: `Refresh and sharpen statistics for ${target}: run ANALYZE ${rel ?? "<relation>"}, raise per-column statistics targets on the predicate columns, and add extended statistics for correlated columns so the planner estimates rows correctly.${under ? " Underestimates feeding a nested loop or hash join are the highest priority \u2014 fix these first." : ""}`,
+          steps: [
+            `Refresh table statistics first; this alone often fixes the estimate.`,
+            `If the column has a skewed/uneven distribution, raise its statistics target and re-ANALYZE.`,
+            `If the predicate spans multiple correlated columns, create extended statistics so the planner stops assuming independence.`
+          ],
+          commands: [
+            {
+              label: "Refresh statistics",
+              sql: `ANALYZE ${rel ?? "<relation>"};`
+            },
+            {
+              label: "Raise per-column statistics target",
+              sql: `ALTER TABLE ${rel ?? "<relation>"} ALTER COLUMN <column> SET STATISTICS 1000;
+ANALYZE ${rel ?? "<relation>"};`
+            },
+            {
+              label: "Add extended statistics for correlated columns",
+              sql: `CREATE STATISTICS <stats_name> (dependencies, ndistinct) ON <col_a>, <col_b> FROM ${rel ?? "<relation>"};
+ANALYZE ${rel ?? "<relation>"};`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/planner-stats.html`,
+        meta: {
+          estimatedRows: Math.round(node.planRows),
+          actualRows: Math.round(actual),
+          factor,
+          direction: estimateDirection
+        }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/seq-scan-large.ts
+var seqScanLarge = {
+  id: "PGX_SEQ_SCAN_LARGE",
+  title: "Sequential scan on a large table",
+  defaultSeverity: "warn",
+  check(node, ctx) {
+    if (node.nodeType !== "Seq Scan") return [];
+    const rows = node.metrics.totalRows ?? node.planRows;
+    if (rows < ctx.thresholds.seqScanRows) return [];
+    const rel = node.relationName ?? "the table";
+    const estimated = node.metrics.totalRows === void 0;
+    const filterCols = node.filter ? ` matching ${node.filter}` : "";
+    return [
+      makeFinding(seqScanLarge, ctx, node, {
+        title: `Sequential scan on ${rel} (${fmtInt(rows)}${estimated ? " est." : ""} rows)`,
+        detail: `Postgres read ${rel} sequentially, scanning roughly ${fmtInt(rows)} rows${estimated ? " (estimated \u2014 run with ANALYZE for actuals)" : ""}.`,
+        cause: node.filter ? `A row filter (${node.filter}) is applied after reading every row, so no index narrowed the scan.` : "No index condition narrowed the scan, so the whole relation was read.",
+        remediation: {
+          summary: `Add an index covering the WHERE/JOIN predicate on ${rel} so Postgres can skip non-matching rows. If the query genuinely needs most of the table, the seq scan is correct \u2014 reduce the rows touched instead.`,
+          steps: [
+            "Identify the selective columns in the WHERE/JOIN predicate.",
+            "Ensure they are sargable (no function-wrapping or implicit casts on the column).",
+            "If selectivity is low, a partial index (WHERE \u2026) may be better."
+          ],
+          commands: [
+            {
+              label: "Index the predicate columns",
+              sql: `CREATE INDEX ON ${rel} (<predicate columns>)${filterCols ? " -- columns from the filter above" : ""};`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/indexes-intro.html`,
+        meta: { rows: Math.round(rows) }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/significant-jit.ts
+var significantJit = {
+  id: "PGX_SIGNIFICANT_JIT",
+  title: "JIT compilation dominates execution",
+  defaultSeverity: "info",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node !== ctx.tree.root) return [];
+    const t = ctx.tree.jit?.timing;
+    const jitTotal = t?.total ?? (t?.generation ?? 0) + (t?.inlining ?? 0) + (t?.optimization ?? 0) + (t?.emission ?? 0);
+    const execMs = executionMs(ctx.tree);
+    if (!execMs || jitTotal <= 0) return [];
+    const jitPct = 100 * jitTotal / execMs;
+    if (jitPct <= ctx.thresholds.jitPct) return [];
+    return [
+      makeFinding(significantJit, ctx, node, {
+        title: `JIT compilation took ${fmtMs(jitTotal)} (${fmtPct(jitPct)} of execution)`,
+        detail: `JIT spent ${fmtMs(jitTotal)} generating, optimizing, and emitting machine code, out of ${fmtMs(
+          execMs
+        )} total execution time. The compilation overhead outweighs the runtime it saved.`,
+        cause: "The plan's estimated cost crossed jit_above_cost, so Postgres JIT-compiled the query \u2014 but the query is too short for compilation to pay off, often because a row overestimate inflated the cost.",
+        remediation: {
+          summary: "Raise jit_above_cost (and jit_inline_above_cost / jit_optimize_above_cost) so short queries skip JIT, or disable JIT for this session with SET jit = off. Then investigate why the cost estimate is high enough to trigger JIT \u2014 frequently a row overestimate fixable with ANALYZE.",
+          steps: [
+            "Confirm the query is consistently short-running before tuning \u2014 JIT pays off on long, CPU-bound queries.",
+            "Raise jit_above_cost above this plan's total cost so similar queries skip JIT entirely.",
+            "If only inlining/optimization are expensive, raise jit_inline_above_cost / jit_optimize_above_cost instead of disabling JIT.",
+            "Check the planner's row estimates against actuals \u2014 an overestimate that inflates cost is the usual reason a cheap query triggers JIT; run ANALYZE on the relations involved."
+          ],
+          commands: [
+            { label: "Disable JIT for this session", sql: "SET jit = off;" },
+            {
+              label: "Raise the JIT cost thresholds",
+              sql: "SET jit_above_cost = <above this plan's total cost>;\nSET jit_inline_above_cost = <higher>;\nSET jit_optimize_above_cost = <higher>;"
+            },
+            {
+              label: "Refresh statistics if the cost is driven by a row overestimate",
+              sql: "ANALYZE <table>;"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-query.html#GUC-JIT-ABOVE-COST`,
+        meta: { jitMs: Math.round(jitTotal), jitPct: Math.round(jitPct) }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/sort-spill-disk.ts
+var sortSpillDisk = {
+  id: "PGX_SORT_SPILL_DISK",
+  title: "Sort spilled to disk",
+  defaultSeverity: "warn",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Sort") return [];
+    const onDisk = node.sortSpaceType === "Disk" || node.sortMethod !== void 0 && /external/i.test(node.sortMethod);
+    if (!onDisk) return [];
+    const usedKiB = node.sortSpaceUsed ?? 0;
+    const workMemRecommended = roundUpMiB(usedKiB > 0 ? usedKiB * 2.2 : 0);
+    const usedText = usedKiB > 0 ? ` using ${fmtKiB(usedKiB)} of temp space` : "";
+    const method = node.sortMethod ? ` (${node.sortMethod})` : "";
+    const orderBy = node.sortKey && node.sortKey.length > 0 ? node.sortKey.join(", ") : "<ORDER BY columns>";
+    const summary = usedKiB > 0 ? `Raise work_mem for this query so the sort stays in memory, e.g. SET work_mem = '${workMemRecommended}' at session or role scope (do NOT raise it globally without accounting for max_connections \u2014 each connection can allocate work_mem several times over). Alternatively, add an index on (${orderBy}) so rows arrive pre-sorted and the Sort node disappears.` : `Raise work_mem for this query so the sort stays in memory, e.g. SET work_mem = '64MB' at session or role scope (do NOT raise it globally without accounting for max_connections \u2014 each connection can allocate work_mem several times over). Alternatively, add an index on (${orderBy}) so rows arrive pre-sorted and the Sort node disappears.`;
+    return [
+      makeFinding(sortSpillDisk, ctx, node, {
+        title: `Sort spilled to disk${usedText}`,
+        detail: `The Sort node ran an external merge sort on disk${method}${usedText}, because the data exceeded work_mem.`,
+        cause: "work_mem was too small to hold the sort set, so Postgres wrote sorted runs to temporary files and merged them \u2014 adding temp-file I/O that an in-memory sort avoids.",
+        remediation: {
+          summary,
+          steps: [
+            "Set work_mem at session or role scope for this workload, not cluster-wide.",
+            `Size it above the spilled footprint${usedKiB > 0 ? ` (~${fmtKiB(usedKiB)}); ${workMemRecommended} leaves headroom` : ""}.`,
+            `Or add an index on (${orderBy}) so the sort is satisfied by an ordered scan and removed entirely.`
+          ],
+          commands: [
+            {
+              label: "Raise work_mem for this session",
+              sql: `SET work_mem = '${usedKiB > 0 ? workMemRecommended : "64MB"}';`
+            },
+            {
+              label: "Or set it per role",
+              sql: `ALTER ROLE <role> SET work_mem = '${usedKiB > 0 ? workMemRecommended : "64MB"}';`
+            },
+            {
+              label: "Or add an index matching the sort key",
+              sql: `CREATE INDEX ON <table> (${orderBy});`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-resource.html#GUC-WORK-MEM`,
+        meta: { sortSpaceUsedKiB: Math.round(usedKiB), workMemRecommended }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/trigger-time.ts
+var triggerTime = {
+  id: "PGX_TRIGGER_TIME",
+  title: "Triggers consume significant time",
+  defaultSeverity: "info",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node !== ctx.tree.root) return [];
+    const triggers = ctx.tree.triggers;
+    const execMs = executionMs(ctx.tree);
+    const triggerTotal = triggers.reduce((s, t) => s + (t.time ?? 0), 0);
+    if (!triggers.length || !execMs || triggerTotal <= 0) return [];
+    const pct = 100 * triggerTotal / execMs;
+    if (pct <= ctx.thresholds.triggerPct) return [];
+    const worst = triggers.reduce((a, b) => (b.time ?? 0) > (a.time ?? 0) ? b : a);
+    const worstLabel = worst.name ?? worst.constraintName ?? "a trigger";
+    const onRel = worst.relation ? ` on ${worst.relation}` : "";
+    return [
+      makeFinding(triggerTime, ctx, node, {
+        title: `Triggers consumed ${fmtMs(triggerTotal)} (${fmtPct(pct)} of execution)`,
+        detail: `Trigger execution took ${fmtMs(triggerTotal)} of the ${fmtMs(
+          execMs
+        )} total \u2014 ${fmtPct(pct)} of the time is spent outside the plan tree (heaviest: "${worstLabel}"${onRel}).`,
+        cause: "Time spent firing triggers (often foreign-key constraint checks or AFTER triggers) is not attributed to any plan node, so it is invisible in the node timings even though it dominates the statement.",
+        remediation: {
+          summary: `Index the foreign-key columns involved in the constraint checks so each row's lookup is cheap, and review the trigger function bodies for per-row inefficiency. For bulk loads, defer constraints (SET CONSTRAINTS ALL DEFERRED) or disable and replay triggers around the batch.`,
+          steps: [
+            "Confirm both the referencing and referenced FK columns are indexed \u2014 an FK check does a lookup on the referenced key for every row, and a missing index makes it a full scan per row.",
+            "Inspect each trigger function body for per-row work that could be batched or removed.",
+            "For bulk INSERT/UPDATE/COPY, defer FK constraints until commit, or temporarily disable user triggers and replay the work once after the batch."
+          ],
+          commands: [
+            {
+              label: "Index the referencing FK column(s) so constraint checks are cheap",
+              sql: `CREATE INDEX ON <referencing_table> (<fk_columns>);`
+            },
+            {
+              label: "Defer FK constraint checks to commit for a bulk load",
+              sql: `BEGIN;
+SET CONSTRAINTS ALL DEFERRED;
+-- bulk INSERT/UPDATE/COPY here
+COMMIT;`
+            },
+            {
+              label: "Disable user triggers around a batch, then re-enable",
+              sql: `ALTER TABLE <table> DISABLE TRIGGER USER;
+-- bulk work here
+ALTER TABLE <table> ENABLE TRIGGER USER;`
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/sql-createtrigger.html`,
+        meta: { triggerMs: Math.round(triggerTotal), triggerPct: Math.round(pct) }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/workers-not-launched.ts
+var workersNotLaunched = {
+  id: "PGX_WORKERS_NOT_LAUNCHED",
+  title: "Parallel workers planned but not launched",
+  defaultSeverity: "info",
+  requiresAnalyze: true,
+  check(node, ctx) {
+    if (node.nodeType !== "Gather" && node.nodeType !== "Gather Merge") return [];
+    if (node.workersPlanned === void 0 || node.workersLaunched === void 0) return [];
+    if (node.workersLaunched >= node.workersPlanned) return [];
+    const planned = node.workersPlanned;
+    const launched = node.workersLaunched;
+    const shortfall = planned - launched;
+    return [
+      makeFinding(workersNotLaunched, ctx, node, {
+        title: `${node.nodeType} got ${fmtInt(launched)} of ${fmtInt(planned)} planned workers`,
+        detail: `This ${node.nodeType} planned for ${fmtInt(planned)} parallel worker${planned === 1 ? "" : "s"} but only ${fmtInt(launched)} were launched (${fmtInt(shortfall)} short), so part of the work ran serially.`,
+        cause: "The global background-worker pool was exhausted: max_worker_processes or max_parallel_workers was already saturated (often by other concurrent parallel queries) when this node tried to start its workers.",
+        remediation: {
+          summary: `Raise max_parallel_workers and max_worker_processes so the pool can supply the ${fmtInt(
+            planned
+          )} workers this query plans for, and confirm max_parallel_workers_per_gather permits them. If parallelism is not actually speeding this query up, the shortfall is harmless.`,
+          steps: [
+            "Check current limits: max_worker_processes, max_parallel_workers, max_parallel_workers_per_gather.",
+            "max_parallel_workers must be <= max_worker_processes; raise both together (max_worker_processes change needs a restart).",
+            "Look for other concurrent parallel queries saturating the shared pool during peak load.",
+            "If a serial plan is no slower here, leave the settings alone \u2014 this is informational."
+          ],
+          commands: [
+            {
+              label: "Enlarge the global parallel-worker pool",
+              sql: "ALTER SYSTEM SET max_parallel_workers = '<N>';\nALTER SYSTEM SET max_worker_processes = '<N+>';\nSELECT pg_reload_conf();"
+            },
+            {
+              label: "Allow more workers per Gather",
+              sql: "ALTER SYSTEM SET max_parallel_workers_per_gather = '<N>';\nSELECT pg_reload_conf();"
+            },
+            {
+              label: "Inspect the current settings",
+              sql: "SELECT name, setting FROM pg_settings WHERE name IN ('max_worker_processes', 'max_parallel_workers', 'max_parallel_workers_per_gather');"
+            }
+          ]
+        },
+        docsUrl: `${DOCS2}/runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS`,
+        meta: { planned, launched }
+      })
+    ];
+  }
+};
+
+// src/advisor/rules/index.ts
+var ALL_RULES = [
+  cartesianProduct,
+  seqScanLarge,
+  nestedLoopLargeOuter,
+  highFilterDiscard,
+  sortSpillDisk,
+  hashSpillDisk,
+  correlatedSubplan,
+  rowMisestimate,
+  filterCouldBeIndexCond,
+  couldBeIndexOnly,
+  indexOnlyHeapFetches,
+  bitmapLossy,
+  workersNotLaunched,
+  lowCacheHit,
+  significantJit,
+  triggerTime
+];
+
+// src/advisor/index.ts
+function runAdvisor(tree, config = DEFAULT_CONFIG) {
+  const ctx = {
+    tree,
+    thresholds: config.thresholds,
+    severityOf: (id, fallback) => config.rules[id]?.severity ?? fallback,
+    isEnabled: (id) => config.rules[id]?.enabled !== false
+  };
+  const nodes = flatten(tree.root);
+  const diagnostics = [];
+  for (const rule of ALL_RULES) {
+    if (!ctx.isEnabled(rule.id)) continue;
+    if (rule.requiresAnalyze && !tree.hasAnalyze) continue;
+    if (rule.requiresBuffers && !tree.hasBuffers) continue;
+    for (const node of nodes) {
+      for (const finding of rule.check(node, ctx)) diagnostics.push(finding);
+    }
+  }
+  diagnostics.sort(bySeverity);
+  let worst = null;
+  for (const d of diagnostics) worst = worst === null ? d.severity : maxSeverity(worst, d.severity);
+  const bn = bottlenecks(tree, 5);
+  return {
+    tree,
+    diagnostics,
+    bottlenecks: bn,
+    verdict: buildVerdict(tree, diagnostics, bn),
+    worstSeverity: worst
+  };
+}
+function buildVerdict(tree, diagnostics, bn) {
+  const counts = { error: 0, warn: 0, info: 0 };
+  for (const d of diagnostics) counts[d.severity]++;
+  const parts = [];
+  if (counts.error) parts.push(`${counts.error} critical`);
+  if (counts.warn) parts.push(`${counts.warn} warning${counts.warn > 1 ? "s" : ""}`);
+  if (counts.info) parts.push(`${counts.info} note${counts.info > 1 ? "s" : ""}`);
+  const findings = parts.length ? parts.join(", ") : "no issues found";
+  const top = bn[0];
+  let bottleneck = "";
+  if (top?.metrics.selfMs !== void 0) {
+    const pct = top.metrics.pctOfTotal !== void 0 ? ` (${top.metrics.pctOfTotal.toFixed(0)}% of time)` : "";
+    bottleneck = ` \u2014 top cost: ${nodeLabel(top)}${pct}`;
+  }
+  const ms = executionMs(tree);
+  const timing = ms !== void 0 ? ` Total ${fmtMs(ms)}.` : " Cost-only plan (no timing).";
+  return `${findings}${bottleneck}.${timing}`;
+}
+
+// src/input/redact.ts
+function redactExpression(expr) {
+  return expr.replace(/'(?:[^']|'')*'/g, "'?'").replace(/\b\d+(?:\.\d+)?\b/g, "N");
+}
+var EXPR_FIELDS = [
+  "filter",
+  "indexCond",
+  "recheckCond",
+  "hashCond",
+  "joinFilter"
+];
+function redactNode(node) {
+  for (const field of EXPR_FIELDS) {
+    const value = node[field];
+    if (typeof value === "string") node[field] = redactExpression(value);
+  }
+  if (node.output) node.output = node.output.map(redactExpression);
+  if (node.sortKey) node.sortKey = node.sortKey.map(redactExpression);
+}
+function redactPlanTree(tree) {
+  walk(tree.root, redactNode);
+}
+
+// src/report/tree.ts
+function treeLines(tree, glyphs) {
+  const lines = [];
+  const recurse = (node, indent, isLast, isRoot) => {
+    const connector = isRoot ? "" : isLast ? glyphs.last : glyphs.branch;
+    lines.push({ node, prefix: indent + connector });
+    const childIndent = isRoot ? "" : indent + (isLast ? glyphs.space : glyphs.vert);
+    node.children.forEach((child, i) => {
+      recurse(child, childIndent, i === node.children.length - 1, false);
+    });
+  };
+  recurse(tree.root, "", true, true);
+  return lines;
+}
+function nodeSummary(node) {
+  const m = node.metrics;
+  const parts = [];
+  if (m.totalRows !== void 0) {
+    let rows = `rows=${fmtInt(m.totalRows)}`;
+    if (m.estimateFactor !== void 0 && m.estimateFactor >= 2 && m.estimateDirection !== "accurate") {
+      rows += ` (est ${fmtInt(node.planRows)}, ${m.estimateFactor.toFixed(0)}\xD7 ${m.estimateDirection})`;
+    }
+    parts.push(rows);
+  } else {
+    parts.push(`rows\u2248${fmtInt(node.planRows)} est`);
+  }
+  if (m.selfMs !== void 0) {
+    let t = `self ${fmtMs(m.selfMs)}`;
+    if (m.pctOfTotal !== void 0 && m.pctOfTotal >= 1) t += ` (${m.pctOfTotal.toFixed(0)}%)`;
+    parts.push(t);
+  }
+  if (node.metrics.cacheHitRatio != null) {
+    parts.push(`cache ${(node.metrics.cacheHitRatio * 100).toFixed(0)}%`);
+  }
+  return parts.join(" \xB7 ");
+}
+
+// src/report/json.ts
+var JSON_SCHEMA_VERSION = 1;
+function renderJson(result, pretty = true) {
+  const { tree, diagnostics, bottlenecks: bottlenecks2 } = result;
+  const counts = { error: 0, warn: 0, info: 0 };
+  for (const d of diagnostics) counts[d.severity]++;
+  const report = {
+    schemaVersion: JSON_SCHEMA_VERSION,
+    verdict: result.verdict,
+    worstSeverity: result.worstSeverity,
+    summary: {
+      planningTimeMs: tree.planningTime ?? null,
+      executionTimeMs: executionMs(tree) ?? null,
+      hasAnalyze: tree.hasAnalyze,
+      hasBuffers: tree.hasBuffers,
+      nodeCount: flatten(tree.root).length,
+      findings: counts
+    },
+    diagnostics,
+    bottlenecks: bottlenecks2.filter((n) => (n.metrics.selfMs ?? 0) > 0).map((n) => ({
+      id: n.id,
+      label: nodeLabel(n),
+      nodeType: n.nodeType,
+      relation: n.relationName ?? null,
+      selfMs: n.metrics.selfMs ?? null,
+      pctOfTotal: n.metrics.pctOfTotal ?? null,
+      totalRows: n.metrics.totalRows ?? null
+    })),
+    plan: serializeNode(tree.root)
+  };
+  return JSON.stringify(report, null, pretty ? 2 : 0);
+}
+function serializeNode(node) {
+  const { children, metrics, raw, ...fields } = node;
+  return { ...fields, metrics, children: children.map(serializeNode) };
+}
+
+// src/report/html.ts
+var SEV = {
+  error: { label: "Critical", cls: "sev-error" },
+  warn: { label: "Warning", cls: "sev-warn" },
+  info: { label: "Note", cls: "sev-info" }
+};
+function esc(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function renderHtml(result) {
+  const { tree, diagnostics } = result;
+  const ms = executionMs(tree);
+  const treeHtml = treeLines(tree, UNICODE_TREE).map(({ node, prefix }) => {
+    const pct = node.metrics.pctOfTotal ?? 0;
+    const heat2 = pct >= 50 ? "hot" : pct >= 20 ? "warm" : pct >= 5 ? "" : "cold";
+    return `<div class="node ${heat2}"><span class="glyph">${esc(prefix)}</span><span class="label">${esc(nodeLabel(node))}</span> <span class="meta">${esc(nodeSummary(node))}</span></div>`;
+  }).join("\n");
+  const findingsHtml = diagnostics.length ? diagnostics.map(findingHtml).join("\n") : '<p class="ok">No anti-patterns detected. \u{1F389}</p>';
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>pg-explain report</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font: 15px/1.5 -apple-system, system-ui, sans-serif; margin: 0; padding: 2rem; max-width: 980px; margin-inline: auto; }
+  h1 { font-size: 1.4rem; } h2 { font-size: 1.1rem; margin-top: 2rem; border-bottom: 1px solid #8884; padding-bottom: .3rem; }
+  .verdict { padding: .75rem 1rem; border-left: 4px solid #888; background: #8881; border-radius: 4px; }
+  .verdict.sev-error { border-color: #e5484d; } .verdict.sev-warn { border-color: #f5a623; } .verdict.sev-info { border-color: #4493f8; }
+  table { border-collapse: collapse; width: 100%; } td, th { text-align: left; padding: .3rem .6rem; border-bottom: 1px solid #8883; }
+  .tree { overflow-x: auto; } .node { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; white-space: pre; font-size: 13px; }
+  .glyph { color: #8888; } .meta { color: #888; }
+  .node.hot .label { color: #e5484d; font-weight: 700; } .node.warm .label { color: #f5a623; } .node.cold .label { opacity: .6; }
+  .finding { border: 1px solid #8883; border-radius: 6px; padding: 1rem; margin: 1rem 0; }
+  .finding .tag { font-size: .75rem; font-weight: 700; padding: .1rem .5rem; border-radius: 3px; color: #fff; }
+  .sev-error .tag { background: #e5484d; } .sev-warn .tag { background: #f5a623; } .sev-info .tag { background: #4493f8; }
+  .finding code, pre { font-family: ui-monospace, monospace; font-size: 13px; }
+  pre { background: #8881; padding: .6rem .8rem; border-radius: 4px; overflow-x: auto; }
+  .label-cmd { color: #888; font-size: .85rem; margin-top: .5rem; }
+  .ok { color: #2e7d32; }
+</style>
+</head>
+<body>
+<h1>pg-explain report</h1>
+<div class="verdict ${result.worstSeverity ? SEV[result.worstSeverity].cls : ""}">${esc(result.verdict)}</div>
+
+<h2>Summary</h2>
+<table>
+  ${tree.planningTime !== void 0 ? `<tr><th>Planning time</th><td>${esc(fmtMs(tree.planningTime))}</td></tr>` : ""}
+  ${ms !== void 0 ? `<tr><th>Execution time</th><td>${esc(fmtMs(ms))}</td></tr>` : ""}
+  ${!tree.hasAnalyze ? "<tr><th>Mode</th><td>cost-only (no ANALYZE)</td></tr>" : ""}
+  <tr><th>Findings</th><td>${diagnostics.length}</td></tr>
+</table>
+
+<h2>Plan tree</h2>
+<div class="tree">
+${treeHtml}
+</div>
+
+<h2>Findings</h2>
+${findingsHtml}
+</body>
+</html>
+`;
+}
+function findingHtml(d) {
+  const sev = SEV[d.severity];
+  const steps = d.remediation.steps?.length ? `<ul>${d.remediation.steps.map((s) => `<li>${esc(s)}</li>`).join("")}</ul>` : "";
+  const cmds = (d.remediation.commands ?? []).map((c) => {
+    const body = c.sql ?? c.shell ?? "";
+    const label = c.label ? `<div class="label-cmd">${esc(c.label)}</div>` : "";
+    return `${label}<pre><code>${esc(body)}</code></pre>`;
+  }).join("");
+  const docs = d.docsUrl ? `<p>\u{1F4D6} <a href="${esc(d.docsUrl)}">PostgreSQL docs</a></p>` : "";
+  const meta = d.location?.relation ? ` <span class="meta">on ${esc(d.location.relation)}</span>` : "";
+  return `<div class="finding ${sev.cls}">
+  <p><span class="tag">${sev.label}</span> <strong>${esc(d.title)}</strong> <code>${esc(d.code)}</code>${meta}</p>
+  <p><strong>What:</strong> ${esc(d.detail)}</p>
+  <p><strong>Why:</strong> ${esc(d.cause)}</p>
+  <p><strong>Fix:</strong> ${esc(d.remediation.summary)}</p>
+  ${steps}
+  ${cmds}
+  ${docs}
+</div>`;
+}
+
+// src/report/markdown.ts
+var SEV_LABEL = {
+  error: "\u{1F534} Critical",
+  warn: "\u{1F7E0} Warning",
+  info: "\u{1F535} Note"
+};
+function renderMarkdown(result, opts = {}) {
+  const { tree, diagnostics, bottlenecks: bottlenecks2 } = result;
+  const out = [];
+  out.push("# pg-explain report", "");
+  out.push(`> **Verdict:** ${result.verdict}`, "");
+  out.push("## Summary", "");
+  const ms = executionMs(tree);
+  out.push("| Metric | Value |", "| --- | --- |");
+  if (tree.planningTime !== void 0) out.push(`| Planning time | ${fmtMs(tree.planningTime)} |`);
+  if (ms !== void 0) out.push(`| Execution time | ${fmtMs(ms)} |`);
+  if (!tree.hasAnalyze) out.push("| Mode | cost-only (no ANALYZE) |");
+  out.push(`| Findings | ${summarizeCounts(diagnostics)} |`, "");
+  if (opts.tldr) {
+    out.push(...renderFindings(diagnostics, true));
+    return `${out.join("\n").trimEnd()}
+`;
+  }
+  out.push("## Plan tree", "", "```");
+  for (const { node, prefix } of treeLines(tree, UNICODE_TREE)) {
+    out.push(`${prefix}${nodeLabel(node)}  \u2014  ${nodeSummary(node)}`);
+  }
+  out.push("```", "");
+  const ranked = bottlenecks2.filter((n) => (n.metrics.selfMs ?? 0) > 0);
+  if (ranked.length) {
+    out.push("## Bottlenecks (by self time)", "");
+    out.push("| # | Node | Self time | % of total | Rows |", "| --- | --- | --- | --- | --- |");
+    ranked.forEach((node, i) => {
+      const pct = node.metrics.pctOfTotal !== void 0 ? `${node.metrics.pctOfTotal.toFixed(1)}%` : "\u2014";
+      const rows = node.metrics.totalRows !== void 0 ? fmtInt(node.metrics.totalRows) : "\u2014";
+      out.push(
+        `| ${i + 1} | ${nodeLabel(node)} | ${fmtMs(node.metrics.selfMs ?? 0)} | ${pct} | ${rows} |`
+      );
+    });
+    out.push("");
+  }
+  out.push(...renderFindings(diagnostics, false));
+  return `${out.join("\n").trimEnd()}
+`;
+}
+function renderFindings(diagnostics, tldr) {
+  const out = ["## Findings", ""];
+  if (diagnostics.length === 0) {
+    out.push("No anti-patterns detected. \u{1F389}", "");
+    return out;
+  }
+  for (const d of diagnostics) {
+    out.push(`### ${SEV_LABEL[d.severity]} \u2014 ${d.title}`, "");
+    out.push(`\`${d.code}\``, "");
+    out.push(`**What:** ${d.detail}`, "");
+    out.push(`**Why:** ${d.cause}`, "");
+    out.push(`**Fix:** ${d.remediation.summary}`, "");
+    if (!tldr) {
+      if (d.remediation.steps?.length) {
+        for (const step of d.remediation.steps) out.push(`- ${step}`);
+        out.push("");
+      }
+      for (const cmd of d.remediation.commands ?? []) {
+        const body = cmd.sql ?? cmd.shell ?? "";
+        const lang = cmd.sql ? "sql" : "sh";
+        if (cmd.label) out.push(`_${cmd.label}:_`);
+        out.push("```" + lang, body, "```", "");
+      }
+      if (d.docsUrl) out.push(`\u{1F4D6} [PostgreSQL docs](${d.docsUrl})`, "");
+    }
+  }
+  return out;
+}
+function summarizeCounts(diagnostics) {
+  const counts = { error: 0, warn: 0, info: 0 };
+  for (const d of diagnostics) counts[d.severity]++;
+  if (diagnostics.length === 0) return "none";
+  return `${counts.error} critical, ${counts.warn} warning(s), ${counts.info} note(s)`;
+}
+var { createColors, isColorSupported } = pc;
+var active = createColors(isColorSupported);
+function configureColor(mode) {
+  active = createColors(mode === "always" || mode === "auto" && isColorSupported);
+}
+function colors() {
+  return active;
+}
+
+// src/report/terminal.ts
+var SEV_TAG = { error: "CRITICAL", warn: "WARNING", info: "NOTE" };
+function sevColor(sev, text) {
+  const c = colors();
+  if (sev === "error") return c.red(c.bold(text));
+  if (sev === "warn") return c.yellow(text);
+  return c.cyan(text);
+}
+function heat(node, text) {
+  const c = colors();
+  const pct = node.metrics.pctOfTotal;
+  if (pct === void 0) return text;
+  if (pct >= 50) return c.red(c.bold(text));
+  if (pct >= 20) return c.yellow(text);
+  if (pct >= 5) return text;
+  return c.dim(text);
+}
+function bar(pct, width = 8) {
+  const filled = Math.round(pct / 100 * width);
+  return "\u2587".repeat(Math.min(filled, width)) + "\u2581".repeat(Math.max(width - filled, 0));
+}
+function renderTerminal(result, opts = {}) {
+  const c = colors();
+  const { tree, diagnostics, bottlenecks: bottlenecks2 } = result;
+  const glyphs = opts.ascii ? ASCII_TREE : UNICODE_TREE;
+  const out = [];
+  out.push(c.bold("pg-explain report"));
+  out.push(`${c.bold("Verdict:")} ${verdictColored(result)}`);
+  out.push("");
+  if (opts.tldr) {
+    out.push(...findingsBlock(diagnostics, opts));
+    return `${out.join("\n").trimEnd()}
+`;
+  }
+  out.push(c.bold("Plan tree"));
+  for (const { node, prefix } of treeLines(tree, glyphs)) {
+    const heatBar = opts.bars !== false && node.metrics.pctOfTotal !== void 0 ? ` ${c.dim(bar(node.metrics.pctOfTotal))}` : "";
+    out.push(
+      `${c.dim(prefix)}${heat(node, nodeLabel(node))}${heatBar}  ${c.dim(nodeSummary(node))}`
+    );
+  }
+  out.push("");
+  const ranked = bottlenecks2.filter((n) => (n.metrics.selfMs ?? 0) > 0);
+  if (ranked.length) {
+    out.push(c.bold("Bottlenecks (by self time)"));
+    ranked.forEach((node, i) => {
+      const pct = node.metrics.pctOfTotal !== void 0 ? `${node.metrics.pctOfTotal.toFixed(0)}%` : "\u2014";
+      out.push(
+        `  ${i + 1}. ${heat(node, nodeLabel(node))} \u2014 ${fmtMs(node.metrics.selfMs ?? 0)} (${pct})`
+      );
+    });
+    out.push("");
+  }
+  out.push(...findingsBlock(diagnostics, opts));
+  const ms = executionMs(tree);
+  if (ms !== void 0) out.push(c.dim(`Total execution time: ${fmtMs(ms)}`));
+  return `${out.join("\n").trimEnd()}
+`;
+}
+function verdictColored(result) {
+  if (result.worstSeverity === null) return colors().green(result.verdict);
+  return sevColor(result.worstSeverity, result.verdict);
+}
+function findingsBlock(diagnostics, opts) {
+  const c = colors();
+  const out = [c.bold("Findings")];
+  if (diagnostics.length === 0) {
+    out.push(`  ${c.green("No anti-patterns detected.")}`, "");
+    return out;
+  }
+  for (const d of diagnostics) {
+    out.push("");
+    out.push(
+      `${sevColor(d.severity, `[${SEV_TAG[d.severity]}]`)} ${c.bold(d.title)} ${c.dim(d.code)}`
+    );
+    out.push(`  ${c.dim("What:")} ${d.detail}`);
+    out.push(`  ${c.dim("Why: ")} ${d.cause}`);
+    out.push(`  ${c.dim("Fix: ")} ${d.remediation.summary}`);
+    if (!opts.tldr) {
+      for (const step of d.remediation.steps ?? []) out.push(`        - ${step}`);
+      for (const cmd of d.remediation.commands ?? []) {
+        const body = cmd.sql ?? cmd.shell ?? "";
+        const label = cmd.label ? `${c.dim(`${cmd.label}:`)} ` : "";
+        out.push(`        ${label}${c.green(body)}`);
+      }
+      if (d.docsUrl) out.push(`        ${c.dim(`docs: ${d.docsUrl}`)}`);
+    }
+  }
+  out.push("");
+  return out;
+}
+
+// src/report/render.ts
+var FORMATS = ["terminal", "markdown", "json", "html", "text"];
+function isFormat(s) {
+  return FORMATS.includes(s);
+}
+function render(result, opts) {
+  switch (opts.format) {
+    case "markdown":
+      return renderMarkdown(result, { tldr: opts.tldr });
+    case "json":
+      return renderJson(result, opts.pretty ?? true);
+    case "html":
+      return renderHtml(result);
+    case "text":
+      return renderTerminal(result, { ascii: true, bars: false, tldr: opts.tldr });
+    default:
+      return renderTerminal(result, { ascii: opts.ascii, tldr: opts.tldr });
+  }
+}
+
+// src/index.ts
+function analyze(input, options = {}) {
+  const trees = parseExplainJson(input);
+  const tree = selectStatement(trees, options.statement);
+  if (options.redact) redactPlanTree(tree);
+  computeMetrics(tree);
+  const result = runAdvisor(tree, options.config ?? DEFAULT_CONFIG);
+  const notices = planNotices(tree);
+  if (notices.length) {
+    result.diagnostics = [...result.diagnostics, ...notices].sort(bySeverity);
+    result.worstSeverity = result.diagnostics.reduce(
+      (worst, d) => worst === null ? d.severity : maxSeverity(worst, d.severity),
+      null
+    );
+  }
+  return result;
+}
+function selectStatement(trees, statement) {
+  if (statement !== void 0) {
+    const tree = trees[statement - 1];
+    if (!tree) {
+      throw opError("PGX_MULTIPLE_STATEMENTS", {
+        detail: `--statement ${statement} is out of range; the input has ${trees.length} statement(s).`
+      });
+    }
+    return tree;
+  }
+  const first = trees[0];
+  if (!first) throw opError("PGX_UNEXPECTED_PLAN_SHAPE");
+  return first;
+}
+function planNotices(tree) {
+  const notices = [];
+  if (!tree.hasAnalyze) notices.push(opDiagnostic("PGX_COST_ONLY_PLAN"));
+  else if (!tree.hasBuffers) notices.push(opDiagnostic("PGX_NO_BUFFERS"));
+  const nodes = flatten(tree.root);
+  const trivial = nodes.length === 1 && /^(Result|Values? Scan)$/.test(tree.root.nodeType);
+  if (trivial) notices.push(opDiagnostic("PGX_EMPTY_PLAN"));
+  return notices;
+}
+
+// src/input/stdin.ts
+function readStdin(timeoutMs = 3e4) {
+  if (process.stdin.isTTY) return Promise.resolve("");
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    const timer = setTimeout(() => {
+      process.stdin.pause();
+      reject(new Error(`Timed out after ${timeoutMs}ms waiting for stdin`));
+    }, timeoutMs);
+    process.stdin.on("data", (c) => chunks.push(c)).on("end", () => {
+      clearTimeout(timer);
+      resolve(Buffer.concat(chunks).toString("utf8"));
+    }).on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+// src/input/source.ts
+async function resolvePlanInput(file) {
+  if (file) {
+    let text2;
+    try {
+      text2 = await readFile(file, "utf8");
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw opError(
+        "PGX_EMPTY_INPUT",
+        { detail: `Could not read file '${file}': ${msg}`, location: { kind: "input" } },
+        err
+      );
+    }
+    if (!text2.trim()) {
+      throw opError("PGX_EMPTY_INPUT", {
+        detail: `File '${file}' is empty.`,
+        location: { kind: "input" }
+      });
+    }
+    return text2;
+  }
+  if (process.stdin.isTTY) {
+    throw opError("PGX_EMPTY_INPUT", {
+      detail: "No --file given and stdin is a terminal (nothing was piped in)."
+    });
+  }
+  const text = await readStdin();
+  if (!text.trim()) throw opError("PGX_EMPTY_INPUT");
+  return text;
+}
+async function emit(result, opts) {
+  configureColor(opts.format === "terminal" ? opts.color : "never");
+  const text = render(result, {
+    format: opts.format,
+    tldr: opts.tldr,
+    ascii: opts.ascii,
+    pretty: opts.pretty
+  });
+  if (opts.output) {
+    await writeFile(opts.output, text);
+  } else {
+    process.stdout.write(text.endsWith("\n") ? text : `${text}
+`);
+  }
+  return gateExit(result, opts.failOn);
+}
+function gateExit(result, failOn) {
+  if (!failOn || result.worstSeverity === null) return 0 /* Success */;
+  return severityAtLeast(result.worstSeverity, failOn) ? 1 /* CiGate */ : 0 /* Success */;
+}
+
+// src/commands/analyze.ts
+async function runAnalyze(args) {
+  if (args.file && await isDirectory(args.file)) return runBatch(args, args.file);
+  const text = await resolvePlanInput(args.file);
+  const result = analyze(text, {
+    config: args.config,
+    statement: args.statement,
+    redact: args.redact
+  });
+  return emit(result, args);
+}
+async function isDirectory(path) {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function runBatch(args, dir) {
+  const files = (await readdir(dir)).filter((f) => f.endsWith(".json")).sort();
+  if (!files.length) {
+    throw opError("PGX_EMPTY_INPUT", {
+      detail: `No .json plan files found in directory '${dir}'.`
+    });
+  }
+  configureColor(args.format === "terminal" ? args.color : "never");
+  const jsonReports = [];
+  const textReports = [];
+  let worst = 0 /* Success */;
+  for (const name of files) {
+    const text = await readFile(join(dir, name), "utf8");
+    let result;
+    try {
+      result = analyze(text, { config: args.config, redact: args.redact });
+    } catch (err) {
+      process.stderr.write(
+        `skipping ${name}: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      worst = 4 /* Parse */;
+      continue;
+    }
+    if (gateTrips(result, args.failOn)) worst = 1 /* CiGate */;
+    const body = render(result, {
+      format: args.format,
+      tldr: args.tldr,
+      ascii: args.ascii,
+      pretty: args.pretty
+    });
+    if (args.format === "json") jsonReports.push({ file: name, report: JSON.parse(body) });
+    else textReports.push(`
+${"=".repeat(60)}
+${name}
+${"=".repeat(60)}
+${body}`);
+  }
+  const out = args.format === "json" ? `${JSON.stringify(jsonReports, null, args.pretty ? 2 : 0)}
+` : `${textReports.join("\n")}
+`;
+  if (args.output) await writeFile(args.output, out);
+  else process.stdout.write(out);
+  return worst;
+}
+function gateTrips(result, failOn) {
+  if (!failOn || result.worstSeverity === null) return false;
+  return severityAtLeast(result.worstSeverity, failOn);
+}
+
+// src/commands/completion.ts
+var SUBCOMMANDS = "run diff completion";
+var FLAGS = "--format --output --tldr --redact --ascii --color --no-color --fail-on --strict --config --statement --quiet --verbose --debug --help --version";
+var FORMATS2 = "terminal markdown json html text";
+var BASH = `# pg-explain bash completion
+_pg_explain() {
+  local cur prev
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  if [ "$prev" = "--format" ] || [ "$prev" = "-f" ]; then
+    COMPREPLY=( $(compgen -W "${FORMATS2}" -- "$cur") ); return
+  fi
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "${SUBCOMMANDS} ${FLAGS}" -f -- "$cur") ); return
+  fi
+  COMPREPLY=( $(compgen -W "${FLAGS}" -f -- "$cur") )
+}
+complete -F _pg_explain pg-explain
+`;
+var ZSH = `#compdef pg-explain
+# pg-explain zsh completion
+_pg_explain() {
+  local -a subcmds flags
+  subcmds=(${SUBCOMMANDS.split(" ").map((s) => `'${s}'`).join(" ")})
+  flags=(${FLAGS.split(" ").map((f) => `'${f}'`).join(" ")})
+  if (( CURRENT == 2 )); then
+    _alternative "subcmds:subcommand:(\${subcmds})" 'files:file:_files' "flags:flag:(\${flags})"
+  else
+    _alternative 'files:file:_files' "flags:flag:(\${flags})"
+  fi
+}
+compdef _pg_explain pg-explain
+`;
+var FISH = `# pg-explain fish completion
+complete -c pg-explain -f
+${SUBCOMMANDS.split(" ").map((s) => `complete -c pg-explain -n '__fish_use_subcommand' -a '${s}'`).join("\n")}
+complete -c pg-explain -l format -x -a '${FORMATS2}'
+${FLAGS.split(" ").filter((f) => f.startsWith("--")).map((f) => `complete -c pg-explain -l '${f.replace(/^--/, "")}'`).join("\n")}
+`;
+function runCompletion(shell) {
+  const scripts = { bash: BASH, zsh: ZSH, fish: FISH };
+  const script = shell ? scripts[shell] : void 0;
+  if (!script) {
+    process.stderr.write(
+      `Usage: pg-explain completion <bash|zsh|fish>
+  bash: pg-explain completion bash > /etc/bash_completion.d/pg-explain
+  zsh:  pg-explain completion zsh  > "\${fpath[1]}/_pg-explain"
+  fish: pg-explain completion fish > ~/.config/fish/completions/pg-explain.fish
+`
+    );
+    return 2 /* Usage */;
+  }
+  process.stdout.write(script);
+  return 0 /* Success */;
+}
+
+// src/core/diff.ts
+function weight(node) {
+  if (node.metrics.selfMs !== void 0) return node.metrics.selfMs;
+  const own = node.totalCost ?? 0;
+  let children = 0;
+  for (const c of node.children) children += c.totalCost ?? 0;
+  return Math.max(own - children, 0);
+}
+function signature(node) {
+  return nodeLabel(node);
+}
+function weightBySignature(result) {
+  const map = /* @__PURE__ */ new Map();
+  walk(result.tree.root, (node) => {
+    const key = signature(node);
+    map.set(key, (map.get(key) ?? 0) + weight(node));
+  });
+  return map;
+}
+function findingKey(d) {
+  return `${d.code}|${d.location?.relation ?? ""}`;
+}
+function diffAnalyses(before, after) {
+  const beforeMs = executionMs(before.tree);
+  const afterMs = executionMs(after.tree);
+  const timed = before.tree.hasAnalyze && after.tree.hasAnalyze;
+  let execDeltaMs;
+  let execDeltaPct;
+  if (beforeMs !== void 0 && afterMs !== void 0) {
+    execDeltaMs = afterMs - beforeMs;
+    execDeltaPct = beforeMs > 0 ? 100 * execDeltaMs / beforeMs : void 0;
+  }
+  const beforeMap = weightBySignature(before);
+  const afterMap = weightBySignature(after);
+  const keys = /* @__PURE__ */ new Set([...beforeMap.keys(), ...afterMap.keys()]);
+  const regressed = [];
+  const improved = [];
+  const added = [];
+  const removed = [];
+  for (const key of keys) {
+    const b = beforeMap.get(key);
+    const a = afterMap.get(key);
+    const beforeVal = b ?? 0;
+    const afterVal = a ?? 0;
+    const deltaMs = afterVal - beforeVal;
+    const deltaPct = beforeVal > 0 ? 100 * deltaMs / beforeVal : null;
+    const entry = {
+      signature: key,
+      beforeMs: beforeVal,
+      afterMs: afterVal,
+      deltaMs,
+      deltaPct
+    };
+    if (b === void 0) added.push(entry);
+    else if (a === void 0) removed.push(entry);
+    else if (deltaMs > 1e-4) regressed.push(entry);
+    else if (deltaMs < -1e-4) improved.push(entry);
+  }
+  regressed.sort((x, y) => y.deltaMs - x.deltaMs);
+  improved.sort((x, y) => x.deltaMs - y.deltaMs);
+  added.sort((x, y) => y.afterMs - x.afterMs);
+  removed.sort((x, y) => y.beforeMs - x.beforeMs);
+  const beforeKeys = new Set(before.diagnostics.map(findingKey));
+  const afterKeys = new Set(after.diagnostics.map(findingKey));
+  const newFindings = after.diagnostics.filter((d) => !beforeKeys.has(findingKey(d)));
+  const resolvedFindings = before.diagnostics.filter((d) => !afterKeys.has(findingKey(d)));
+  return {
+    beforeMs,
+    afterMs,
+    execDeltaMs,
+    execDeltaPct,
+    timed,
+    regressed,
+    improved,
+    added,
+    removed,
+    newFindings,
+    resolvedFindings
+  };
+}
+
+// src/report/diff.ts
+function renderDiff(diff, format) {
+  if (format === "json") return JSON.stringify(diff, null, 2);
+  if (format === "markdown") return renderDiffMarkdown(diff);
+  return renderDiffTerminal(diff);
+}
+function headline(diff) {
+  if (diff.execDeltaMs === void 0)
+    return "Compared plans (no timing available \u2014 using cost as a proxy).";
+  const dir = diff.execDeltaMs > 0 ? "slower" : diff.execDeltaMs < 0 ? "faster" : "unchanged";
+  const pct = diff.execDeltaPct !== void 0 ? ` (${diff.execDeltaPct >= 0 ? "+" : ""}${diff.execDeltaPct.toFixed(1)}%)` : "";
+  return `${fmtMs(Math.abs(diff.execDeltaMs))} ${dir}${pct}: ${fmtMs(diff.beforeMs ?? 0)} \u2192 ${fmtMs(diff.afterMs ?? 0)}`;
+}
+function renderDiffTerminal(diff) {
+  const c = colors();
+  const out = [];
+  out.push(c.bold("pg-explain diff (before \u2192 after)"));
+  const slower = (diff.execDeltaMs ?? 0) > 0;
+  out.push(`${c.bold("Verdict:")} ${slower ? c.red(headline(diff)) : c.green(headline(diff))}`);
+  out.push("");
+  section(out, "Regressed nodes (slower)", diff.regressed, (d) => c.red(deltaLine(d)));
+  section(out, "Improved nodes (faster)", diff.improved, (d) => c.green(deltaLine(d)));
+  section(out, "Added nodes", diff.added, (d) => `${d.signature}  +${fmtMs(d.afterMs)}`);
+  section(out, "Removed nodes", diff.removed, (d) => `${d.signature}  -${fmtMs(d.beforeMs)}`);
+  if (diff.newFindings.length) {
+    out.push(c.bold(c.red("New findings")));
+    for (const f of diff.newFindings) out.push(`  + [${f.severity}] ${f.title} ${c.dim(f.code)}`);
+    out.push("");
+  }
+  if (diff.resolvedFindings.length) {
+    out.push(c.bold(c.green("Resolved findings")));
+    for (const f of diff.resolvedFindings) out.push(`  - ${f.title} ${c.dim(f.code)}`);
+    out.push("");
+  }
+  return `${out.join("\n").trimEnd()}
+`;
+}
+function section(out, title, items, line) {
+  if (!items.length) return;
+  out.push(colors().bold(title));
+  for (const d of items.slice(0, 10)) out.push(`  ${line(d)}`);
+  out.push("");
+}
+function deltaLine(d) {
+  const pct = d.deltaPct !== null ? ` (${d.deltaPct >= 0 ? "+" : ""}${d.deltaPct.toFixed(0)}%)` : "";
+  const sign = d.deltaMs >= 0 ? "+" : "-";
+  return `${d.signature}  ${sign}${fmtMs(Math.abs(d.deltaMs))}${pct}  [${fmtMs(d.beforeMs)} \u2192 ${fmtMs(d.afterMs)}]`;
+}
+function renderDiffMarkdown(diff) {
+  const out = ["# pg-explain diff", "", `> **${headline(diff)}**`, ""];
+  const table = (title, items) => {
+    if (!items.length) return;
+    out.push(`## ${title}`, "", "| Node | Before | After | \u0394 |", "| --- | --- | --- | --- |");
+    for (const d of items.slice(0, 20)) {
+      const pct = d.deltaPct !== null ? ` (${d.deltaPct >= 0 ? "+" : ""}${d.deltaPct.toFixed(0)}%)` : "";
+      out.push(
+        `| ${d.signature} | ${fmtMs(d.beforeMs)} | ${fmtMs(d.afterMs)} | ${d.deltaMs >= 0 ? "+" : ""}${fmtMs(d.deltaMs)}${pct} |`
+      );
+    }
+    out.push("");
+  };
+  table("Regressed (slower)", diff.regressed);
+  table("Improved (faster)", diff.improved);
+  table("Added", diff.added);
+  table("Removed", diff.removed);
+  if (diff.newFindings.length) {
+    out.push("## New findings", "");
+    for (const f of diff.newFindings) out.push(`- **${f.severity}** ${f.title} \`${f.code}\``);
+    out.push("");
+  }
+  if (diff.resolvedFindings.length) {
+    out.push("## Resolved findings", "");
+    for (const f of diff.resolvedFindings) out.push(`- ${f.title} \`${f.code}\``);
+    out.push("");
+  }
+  return `${out.join("\n").trimEnd()}
+`;
+}
+
+// src/commands/diff.ts
+async function runDiff(args) {
+  const [beforeText, afterText] = await Promise.all([readPlan(args.before), readPlan(args.after)]);
+  const before = analyze(beforeText, { config: args.config, redact: args.redact });
+  const after = analyze(afterText, { config: args.config, redact: args.redact });
+  const diff = diffAnalyses(before, after);
+  configureColor(args.format === "terminal" ? args.color : "never");
+  const text = renderDiff(diff, args.format);
+  if (args.output) await writeFile(args.output, text);
+  else process.stdout.write(text.endsWith("\n") ? text : `${text}
+`);
+  if (args.failOnNewFindings && diff.newFindings.length > 0) return 1 /* CiGate */;
+  if (args.failOnSlowerPct !== void 0 && diff.execDeltaPct !== void 0 && diff.execDeltaPct >= args.failOnSlowerPct) {
+    return 1 /* CiGate */;
+  }
+  return 0 /* Success */;
+}
+async function readPlan(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (err) {
+    throw opError(
+      "PGX_EMPTY_INPUT",
+      {
+        detail: `Could not read plan file '${path}': ${err instanceof Error ? err.message : String(err)}`
+      },
+      err
+    );
+  }
+}
+
+// src/util/log.ts
+var level = "normal";
+function setLogLevel(l) {
+  level = l;
+}
+function isDebug() {
+  return level === "debug";
+}
+function write(msg) {
+  process.stderr.write(`${msg}
+`);
+}
+function logInfo(msg) {
+  if (level !== "quiet") write(msg);
+}
+function logVerbose(msg) {
+  if (level === "verbose" || level === "debug") write(msg);
+}
+function logError(msg) {
+  write(msg);
+}
+
+// src/db/version.ts
+function capabilities(versionNum) {
+  const major = Math.floor(versionNum / 1e4);
+  return {
+    versionNum,
+    major,
+    summary: major >= 10,
+    settings: major >= 12,
+    wal: major >= 13,
+    genericPlan: major >= 16,
+    serialize: major >= 17,
+    memory: major >= 17
+  };
+}
+function versionLabel(versionNum) {
+  const major = Math.floor(versionNum / 1e4);
+  const minor = versionNum % 100;
+  return `${major}.${minor}`;
+}
+
+// src/db/explain.ts
+function buildExplain(flags, caps) {
+  if (flags.genericPlan && flags.analyze) {
+    throw opError("PGX_INVALID_EXPLAIN_OPTION", {
+      detail: "GENERIC_PLAN cannot be combined with ANALYZE (GENERIC_PLAN does not execute the query)."
+    });
+  }
+  if (flags.wal && !flags.analyze) {
+    throw opError("PGX_INVALID_EXPLAIN_OPTION", { detail: "WAL requires ANALYZE." });
+  }
+  const opts = ["FORMAT JSON"];
+  const omitted = [];
+  const gate = (label, supported, requiredMajor) => {
+    if (supported) return true;
+    if (flags.compat) {
+      omitted.push(label);
+      return false;
+    }
+    throw opError("PGX_UNSUPPORTED_PG_VERSION", {
+      detail: `EXPLAIN (${label}) requires PostgreSQL ${requiredMajor}; server is ${versionLabel(caps.versionNum)}.`,
+      meta: { option: label, requiredMajor, serverVersion: caps.versionNum }
+    });
+  };
+  if (flags.genericPlan && gate("GENERIC_PLAN", caps.genericPlan, 16)) opts.push("GENERIC_PLAN");
+  if (flags.analyze) opts.push("ANALYZE");
+  if (flags.buffers) opts.push("BUFFERS");
+  if (flags.verbose) opts.push("VERBOSE");
+  if (flags.settings && gate("SETTINGS", caps.settings, 12)) opts.push("SETTINGS");
+  if (flags.wal && gate("WAL", caps.wal, 13)) opts.push("WAL");
+  if (!flags.costs) opts.push("COSTS OFF");
+  if (flags.analyze && !flags.timing) opts.push("TIMING OFF");
+  if (!flags.summary && caps.summary) opts.push("SUMMARY OFF");
+  return { prefix: `EXPLAIN (${opts.join(", ")})`, omitted };
+}
+function leadingKeyword(sql) {
+  const cleaned = sql.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/--[^\n]*/g, " ").trim();
+  return (cleaned.split(/\s+/)[0] ?? "").toUpperCase();
+}
+function isReadOnlyStatement(sql) {
+  const kw = leadingKeyword(sql);
+  if (["SELECT", "TABLE", "VALUES", "SHOW", "EXPLAIN"].includes(kw)) return true;
+  if (kw === "WITH") return !/\b(INSERT|UPDATE|DELETE|MERGE)\b/i.test(sql);
+  return false;
+}
+function splitStatements(sql) {
+  const out = [];
+  let buf = "";
+  let i = 0;
+  const n = sql.length;
+  while (i < n) {
+    const ch = sql[i];
+    const two = sql.slice(i, i + 2);
+    if (two === "--") {
+      const nl = sql.indexOf("\n", i);
+      const end = nl === -1 ? n : nl;
+      buf += sql.slice(i, end);
+      i = end;
+    } else if (two === "/*") {
+      const close = sql.indexOf("*/", i + 2);
+      const end = close === -1 ? n : close + 2;
+      buf += sql.slice(i, end);
+      i = end;
+    } else if (ch === "'" || ch === '"') {
+      const end = scanQuoted(sql, i, ch);
+      buf += sql.slice(i, end);
+      i = end;
+    } else if (ch === "$") {
+      const tag = matchDollarTag(sql, i);
+      if (tag) {
+        const close = sql.indexOf(tag, i + tag.length);
+        const end = close === -1 ? n : close + tag.length;
+        buf += sql.slice(i, end);
+        i = end;
+      } else {
+        buf += ch;
+        i++;
+      }
+    } else if (ch === ";") {
+      if (buf.trim()) out.push(buf.trim());
+      buf = "";
+      i++;
+    } else {
+      buf += ch;
+      i++;
+    }
+  }
+  if (buf.trim()) out.push(buf.trim());
+  return out;
+}
+function scanQuoted(sql, start, quote) {
+  let i = start + 1;
+  while (i < sql.length) {
+    if (sql[i] === quote) {
+      if (sql[i + 1] === quote)
+        i += 2;
+      else return i + 1;
+    } else {
+      i++;
+    }
+  }
+  return sql.length;
+}
+function matchDollarTag(sql, start) {
+  const m = /^\$[A-Za-z_]*\$/.exec(sql.slice(start));
+  return m ? m[0] : null;
+}
+function parseDurationMs(value) {
+  const m = /^(\d+(?:\.\d+)?)\s*(ms|s|min|m|h)?$/.exec(value.trim());
+  if (!m?.[1])
+    throw opError("PGX_INVALID_EXPLAIN_OPTION", {
+      detail: `Invalid duration '${value}'. Use e.g. 60s, 500ms, 2min.`
+    });
+  const n = Number(m[1]);
+  switch (m[2]) {
+    case "s":
+      return Math.round(n * 1e3);
+    case "min":
+    case "m":
+      return Math.round(n * 6e4);
+    case "h":
+      return Math.round(n * 36e5);
+    default:
+      return Math.round(n);
+  }
+}
+
+// src/db/client.ts
+async function newClient(config) {
+  let mod;
+  try {
+    mod = await import('pg');
+  } catch (err) {
+    throw opError("PGX_PG_DRIVER_MISSING", {}, err);
+  }
+  const lib = mod.default ?? mod;
+  return new lib.Client(config);
+}
+function buildClientConfig(c, ca) {
+  const config = { connectionTimeoutMillis: c.connectTimeoutMs };
+  if (c.dsn) {
+    config.connectionString = c.dsn;
+  } else {
+    if (c.host) config.host = c.host;
+    if (c.port) config.port = c.port;
+    if (c.database) config.database = c.database;
+    if (c.user) config.user = c.user;
+    if (c.password) config.password = c.password;
+  }
+  if (c.sslmode && c.sslmode !== "disable" && c.sslmode !== "prefer") {
+    const verify = c.sslmode === "verify-ca" || c.sslmode === "verify-full";
+    config.ssl = ca ? { rejectUnauthorized: verify, ca } : { rejectUnauthorized: verify };
+  } else if (c.sslmode === "disable") {
+    config.ssl = false;
+  }
+  return config;
+}
+async function runExplain(opts) {
+  const ca = opts.connection.sslrootcert ? await readFile(opts.connection.sslrootcert, "utf8").catch((err) => {
+    throw opError("PGX_SSL_VERIFY_FAILED", {
+      detail: `Could not read --sslrootcert '${opts.connection.sslrootcert}': ${err instanceof Error ? err.message : String(err)}`
+    });
+  }) : void 0;
+  const client = await newClient(buildClientConfig(opts.connection, ca));
+  try {
+    await client.connect();
+  } catch (err) {
+    throw mapConnectError(err);
+  }
+  try {
+    const verNum = await fetchVersionNum(client);
+    const caps = capabilities(verNum);
+    const built = buildExplain(opts.flags, caps);
+    const explainSql = `${built.prefix} ${opts.statement}`;
+    logVerbose(`server_version_num=${verNum}; ${built.prefix}`);
+    const useTxn = opts.rollback;
+    if (useTxn) await client.query("BEGIN");
+    try {
+      if (useTxn) {
+        await client.query(`SET LOCAL statement_timeout = ${msInt(opts.statementTimeoutMs)}`);
+        await client.query(`SET LOCAL lock_timeout = ${msInt(opts.lockTimeoutMs)}`);
+        if (!opts.forceWrite) await client.query("SET LOCAL transaction_read_only = on");
+      }
+      const res = await client.query({
+        text: explainSql,
+        values: opts.params ?? []
+      });
+      return { json: extractPlanJson(res.rows), caps, omitted: built.omitted };
+    } catch (err) {
+      throw mapQueryError(err);
+    } finally {
+      if (useTxn) await client.query("ROLLBACK").catch(() => {
+      });
+    }
+  } finally {
+    await client.end().catch(() => {
+    });
+  }
+}
+function msInt(ms) {
+  return Math.max(0, Math.floor(ms));
+}
+async function fetchVersionNum(client) {
+  try {
+    const res = await client.query("SHOW server_version_num");
+    return Number(res.rows[0]?.server_version_num ?? 0);
+  } catch (err) {
+    throw mapQueryError(err);
+  }
+}
+function extractPlanJson(rows) {
+  const value = rows[0]?.["QUERY PLAN"];
+  if (value === void 0) {
+    throw opError("PGX_UNEXPECTED_PLAN_SHAPE", {
+      detail: "The server returned no plan rows for EXPLAIN."
+    });
+  }
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+function asPgError(err) {
+  if (err && typeof err === "object") return err;
+  return { message: String(err) };
+}
+function mapConnectError(err) {
+  if (err instanceof AppError) return err;
+  const e = asPgError(err);
+  const msg = e.message ?? "";
+  switch (e.code) {
+    case "28P01":
+    case "28000":
+      return opError("PGX_AUTH_FAILED", { detail: msg }, err);
+    case "3D000":
+      return opError("PGX_DB_NOT_FOUND", { detail: msg }, err);
+    case "ECONNREFUSED":
+    case "ENOTFOUND":
+    case "EAI_AGAIN":
+    case "EHOSTUNREACH":
+      return opError("PGX_HOST_UNREACHABLE", { detail: msg }, err);
+    case "ETIMEDOUT":
+      return opError("PGX_CONN_TIMEOUT", { detail: msg }, err);
+  }
+  if (/timeout/i.test(msg)) return opError("PGX_CONN_TIMEOUT", { detail: msg }, err);
+  if (/self.signed|certificate|verify|CERT_/i.test(msg))
+    return opError("PGX_SSL_VERIFY_FAILED", { detail: msg }, err);
+  if (/SSL|encryption/i.test(msg)) return opError("PGX_SSL_REQUIRED", { detail: msg }, err);
+  return opError("PGX_HOST_UNREACHABLE", { detail: msg }, err);
+}
+function mapQueryError(err) {
+  if (err instanceof AppError) return err;
+  const e = asPgError(err);
+  const msg = e.message ?? "";
+  const meta = e.code ? { sqlState: e.code } : void 0;
+  switch (e.code) {
+    case "57014":
+      return /statement timeout/i.test(msg) ? opError("PGX_STATEMENT_TIMEOUT", { detail: msg, meta }, err) : opError("PGX_QUERY_CANCELED", { detail: msg, meta }, err);
+    case "55P03":
+      return opError("PGX_LOCK_TIMEOUT", { detail: msg, meta }, err);
+    case "42501":
+      return opError("PGX_PERMISSION_DENIED", { detail: msg, meta }, err);
+    case "42P01":
+      return opError("PGX_RELATION_NOT_FOUND", { detail: msg, meta }, err);
+    case "28P01":
+    case "28000":
+      return opError("PGX_AUTH_FAILED", { detail: msg, meta }, err);
+    case "3D000":
+      return opError("PGX_DB_NOT_FOUND", { detail: msg, meta }, err);
+    default:
+      return opError("PGX_QUERY_FAILED", { detail: msg, meta }, err);
+  }
+}
+
+// src/commands/run.ts
+async function runRun(args) {
+  const sql = await resolveSql(args);
+  const statements = splitStatements(sql);
+  const statement = selectStatement2(statements, args.statementIndex);
+  if (args.flags.analyze && !args.flags.genericPlan && !isReadOnlyStatement(statement) && !args.forceWrite) {
+    const verb = statement.trim().split(/\s+/)[0]?.toUpperCase() ?? "statement";
+    throw opError("PGX_NON_SELECT_REFUSED", {
+      detail: `Refusing to ANALYZE a non-SELECT (${verb}) \u2014 it would modify data.`
+    });
+  }
+  const result = await runExplain({
+    connection: args.connection,
+    statement,
+    params: args.params,
+    flags: args.flags,
+    statementTimeoutMs: args.statementTimeoutMs,
+    lockTimeoutMs: args.lockTimeoutMs,
+    forceWrite: args.forceWrite,
+    rollback: args.rollback
+  });
+  if (result.omitted.length) {
+    logInfo(
+      `Note: server is PostgreSQL ${result.caps.major}; skipped unsupported option(s): ${result.omitted.join(", ")}.`
+    );
+  }
+  const analysis = analyze(result.json, { config: args.config, redact: args.redact });
+  return emit(analysis, args);
+}
+async function resolveSql(args) {
+  if (args.query) return args.query;
+  if (args.file) {
+    try {
+      return await readFile(args.file, "utf8");
+    } catch (err) {
+      throw opError(
+        "PGX_EMPTY_INPUT",
+        {
+          detail: `Could not read SQL file '${args.file}': ${err instanceof Error ? err.message : String(err)}`
+        },
+        err
+      );
+    }
+  }
+  throw opError("PGX_EMPTY_INPUT", {
+    detail: "The run command needs SQL: pass --query '<sql>' or --file <path.sql>."
+  });
+}
+function selectStatement2(statements, index) {
+  if (statements.length === 0) {
+    throw opError("PGX_EMPTY_INPUT", { detail: "No SQL statement found after parsing." });
+  }
+  if (index !== void 0) {
+    const stmt = statements[index - 1];
+    if (!stmt) {
+      throw opError("PGX_MULTIPLE_STATEMENTS", {
+        detail: `--statement ${index} is out of range; found ${statements.length} statement(s).`
+      });
+    }
+    return stmt;
+  }
+  if (statements.length > 1) {
+    throw opError("PGX_MULTIPLE_STATEMENTS", {
+      detail: `Found ${statements.length} statements. Pick one with --statement <n> (1-based).`
+    });
+  }
+  return statements[0];
+}
+
+// src/diagnostics/print.ts
+function formatDiagnostic(d) {
+  const c = colors();
+  const tag = d.severity === "error" ? c.red(c.bold("error")) : d.severity === "warn" ? c.yellow("warning") : c.cyan("info");
+  const lines = [];
+  lines.push(`${tag} ${c.bold(d.title)} ${c.dim(`[${d.code}]`)}`);
+  lines.push(`  ${c.dim("what:")} ${d.detail}`);
+  lines.push(`  ${c.dim("why: ")} ${d.cause}`);
+  lines.push(`  ${c.dim("fix: ")} ${d.remediation.summary}`);
+  for (const step of d.remediation.steps ?? []) lines.push(`        \u2022 ${step}`);
+  for (const cmd of d.remediation.commands ?? []) {
+    const body = cmd.sql ?? cmd.shell ?? "";
+    const label = cmd.label ? `${c.dim(`${cmd.label}:`)} ` : "";
+    lines.push(`        ${label}${c.green(body)}`);
+  }
+  if (d.docsUrl) lines.push(`        ${c.dim(`docs: ${d.docsUrl}`)}`);
+  return scrubCredentials(lines.join("\n"));
+}
+
+// src/cli.ts
+var SEVERITIES = ["error", "warn", "info"];
+var outputArgs = {
+  format: {
+    type: "string",
+    default: "terminal",
+    alias: "f",
+    description: "terminal | markdown | json | html | text"
+  },
+  output: {
+    type: "string",
+    alias: "o",
+    description: "Write the report to a file instead of stdout"
+  },
+  tldr: { type: "boolean", description: "Summary + findings only (no plan tree)" },
+  redact: { type: "boolean", description: "Strip literal values from expressions (safe to share)" },
+  ascii: { type: "boolean", description: "Use ASCII tree glyphs instead of Unicode" },
+  color: { type: "string", default: "auto", description: "auto | always | never" },
+  "no-color": { type: "boolean", description: "Disable color (same as --color never)" },
+  "fail-on": {
+    type: "string",
+    description: "CI gate: exit 1 if a finding at/above info|warn|error exists"
+  },
+  strict: { type: "boolean", description: "Shorthand for --fail-on warn" },
+  config: {
+    type: "string",
+    description: "Path to a config file (default: .pgexplainrc[.json] / package.json#pgExplain)"
+  },
+  compact: { type: "boolean", description: "Compact JSON output" },
+  quiet: { type: "boolean", alias: "q", description: "Suppress non-error logs" },
+  verbose: { type: "boolean", description: "Extra diagnostic logging" },
+  debug: { type: "boolean", description: "Print stack traces on internal errors" }
+};
+function applyGlobalFlags(args) {
+  setLogLevel(args.quiet ? "quiet" : args.debug ? "debug" : args.verbose ? "verbose" : "normal");
+  const mode = args["no-color"] ? "never" : args.color;
+  configureColor(mode === "always" || mode === "never" ? mode : "auto");
+}
+function emitOptionsFrom(args) {
+  const opts = {
+    format: resolveFormat(args.format),
+    color: args["no-color"] ? "never" : args.color,
+    ascii: args.ascii,
+    tldr: args.tldr,
+    pretty: !args.compact
+  };
+  if (args.output) opts.output = args.output;
+  const failOn = resolveFailOn(args);
+  if (failOn) opts.failOn = failOn;
+  return opts;
+}
+function resolveFormat(value) {
+  if (isFormat(value)) return value;
+  throw usageError(
+    `Unknown --format '${value}'`,
+    "Pick one of: terminal, markdown, json, html, text."
+  );
+}
+function resolveFailOn(args) {
+  if (args.strict) return "warn";
+  const value = args["fail-on"];
+  if (value === void 0) return void 0;
+  if (SEVERITIES.includes(value)) return value;
+  throw usageError(`Unknown --fail-on '${value}'`, "Use one of: info, warn, error.");
+}
+function resolveStatement(args) {
+  const raw = args.statement ?? args.stmt;
+  if (raw === void 0) return void 0;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1)
+    throw usageError(`Invalid --statement '${raw}'`, "Use a 1-based integer.");
+  return n;
+}
+function usageError(title, fix) {
+  const diagnostic = {
+    code: "PGX_USAGE",
+    domain: "operational",
+    severity: "error",
+    title,
+    detail: "The command could not be run as given.",
+    cause: "Invalid command-line usage.",
+    remediation: {
+      summary: fix,
+      commands: [{ label: "See all options", shell: "pg-explain --help" }]
+    }
+  };
+  return new AppError(diagnostic, 2 /* Usage */);
+}
+function handleFatal(err) {
+  if (err instanceof AppError) {
+    logError(formatDiagnostic(err.diagnostic));
+    return err.exitCode;
+  }
+  logError(formatDiagnostic(opDiagnostic("PGX_INTERNAL")));
+  if (isDebug() && err instanceof Error && err.stack) logError(scrubCredentials(err.stack));
+  return 70 /* Internal */;
+}
+var runCmd = defineCommand({
+  meta: {
+    name: "run",
+    description: "Connect to PostgreSQL, run EXPLAIN safely, and analyze the result."
+  },
+  args: {
+    dsn: {
+      type: "string",
+      description: "Connection string (or use --host/--port/\u2026 or PG* env vars)"
+    },
+    host: { type: "string", description: "Server host" },
+    port: { type: "string", description: "Server port" },
+    dbname: { type: "string", alias: "d", description: "Database name" },
+    user: { type: "string", alias: "U", description: "Role name" },
+    sslmode: { type: "string", description: "disable | require | verify-ca | verify-full" },
+    sslrootcert: { type: "string", description: "Path to a CA certificate (PEM)" },
+    "connect-timeout": {
+      type: "string",
+      default: "10s",
+      description: "Connection timeout (e.g. 30s)"
+    },
+    query: { type: "string", description: "SQL to explain" },
+    file: { type: "string", description: "Path to a .sql file to explain" },
+    statement: { type: "string", description: "1-based statement index when the file has several" },
+    param: { type: "string", description: "Value for $1, $2, \u2026 (repeatable)" },
+    "statement-timeout": {
+      type: "string",
+      default: "30s",
+      description: "statement_timeout for the run"
+    },
+    "lock-timeout": { type: "string", default: "5s", description: "lock_timeout for the run" },
+    force: {
+      type: "boolean",
+      description: "Allow a non-SELECT to execute (still auto-rolled-back)"
+    },
+    "no-rollback": {
+      type: "boolean",
+      description: "Do not wrap the run in a rolled-back transaction (dangerous)"
+    },
+    "no-analyze": { type: "boolean", description: "Do not execute the query; plan estimates only" },
+    "no-buffers": { type: "boolean", description: "Omit BUFFERS" },
+    "explain-verbose": {
+      type: "boolean",
+      description: "Add EXPLAIN VERBOSE (output columns, schemas)"
+    },
+    settings: { type: "boolean", description: "Add EXPLAIN SETTINGS (PG12+)" },
+    wal: { type: "boolean", description: "Add EXPLAIN WAL (PG13+, needs ANALYZE)" },
+    "generic-plan": {
+      type: "boolean",
+      description: "EXPLAIN GENERIC_PLAN (PG16+, does not execute)"
+    },
+    "no-timing": { type: "boolean", description: "Add TIMING OFF (reduces ANALYZE overhead)" },
+    "no-costs": { type: "boolean", description: "Add COSTS OFF" },
+    compat: { type: "boolean", description: "Auto-omit EXPLAIN options the server is too old for" },
+    ...outputArgs
+  },
+  async run({ args }) {
+    try {
+      applyGlobalFlags(args);
+      const connection = {
+        connectTimeoutMs: parseDurationMs(args["connect-timeout"])
+      };
+      if (args.dsn) connection.dsn = args.dsn;
+      if (args.host) connection.host = args.host;
+      if (args.port) connection.port = Number(args.port);
+      if (args.dbname) connection.database = args.dbname;
+      if (args.user) connection.user = args.user;
+      if (args.sslmode) connection.sslmode = args.sslmode;
+      if (args.sslrootcert) connection.sslrootcert = args.sslrootcert;
+      const flags = {
+        analyze: !args["no-analyze"],
+        buffers: !args["no-buffers"],
+        verbose: !!args["explain-verbose"],
+        settings: !!args.settings,
+        wal: !!args.wal,
+        timing: !args["no-timing"],
+        costs: !args["no-costs"],
+        summary: true,
+        genericPlan: !!args["generic-plan"],
+        compat: !!args.compat
+      };
+      const params = Array.isArray(args.param) ? args.param : args.param ? [args.param] : void 0;
+      process.exitCode = await runRun({
+        ...emitOptionsFrom(args),
+        config: await loadConfig(args.config),
+        connection,
+        query: args.query,
+        file: args.file,
+        statementIndex: resolveStatement(args),
+        params,
+        flags,
+        statementTimeoutMs: parseDurationMs(args["statement-timeout"]),
+        lockTimeoutMs: parseDurationMs(args["lock-timeout"]),
+        forceWrite: !!args.force,
+        rollback: !args["no-rollback"],
+        redact: args.redact
+      });
+    } catch (err) {
+      process.exitCode = handleFatal(err);
+    }
+  }
+});
+var diffCmd = defineCommand({
+  meta: {
+    name: "diff",
+    description: "Compare two EXPLAIN plans (before \u2192 after) and report regressions."
+  },
+  args: {
+    before: { type: "positional", required: true, description: "Baseline plan JSON file" },
+    after: { type: "positional", required: true, description: "New plan JSON file" },
+    format: {
+      type: "string",
+      default: "terminal",
+      alias: "f",
+      description: "terminal | markdown | json"
+    },
+    output: { type: "string", alias: "o", description: "Write to a file instead of stdout" },
+    color: { type: "string", default: "auto", description: "auto | always | never" },
+    "no-color": { type: "boolean", description: "Disable color" },
+    redact: { type: "boolean", description: "Strip literal values before comparing" },
+    config: { type: "string", description: "Path to a config file" },
+    "fail-on-slower": {
+      type: "string",
+      description: "Exit 1 if execution time regresses by \u2265 this percent"
+    },
+    "fail-on-new-findings": { type: "boolean", description: "Exit 1 if any new finding appears" },
+    quiet: { type: "boolean", alias: "q", description: "Suppress non-error logs" },
+    debug: { type: "boolean", description: "Print stack traces on internal errors" }
+  },
+  async run({ args }) {
+    try {
+      applyGlobalFlags(args);
+      const format = args.format;
+      if (!["terminal", "markdown", "json"].includes(format)) {
+        throw usageError(`Unknown diff --format '${format}'`, "Use terminal, markdown, or json.");
+      }
+      const diffArgs = {
+        before: args.before,
+        after: args.after,
+        format,
+        color: args["no-color"] ? "never" : args.color,
+        redact: args.redact,
+        config: await loadConfig(args.config),
+        failOnNewFindings: !!args["fail-on-new-findings"]
+      };
+      if (args.output) diffArgs.output = args.output;
+      if (args["fail-on-slower"] !== void 0) {
+        const pct = Number(args["fail-on-slower"]);
+        if (!Number.isFinite(pct))
+          throw usageError(
+            `Invalid --fail-on-slower '${args["fail-on-slower"]}'`,
+            "Use a number, e.g. 20."
+          );
+        diffArgs.failOnSlowerPct = pct;
+      }
+      process.exitCode = await runDiff(diffArgs);
+    } catch (err) {
+      process.exitCode = handleFatal(err);
+    }
+  }
+});
+var main = defineCommand({
+  meta: {
+    name: "pg-explain",
+    version: package_default.version,
+    description: "Analyze a PostgreSQL EXPLAIN plan and report fixable findings. Pipe a plan or pass a file; use `pg-explain run --help` to execute a query and explain it."
+  },
+  args: {
+    file: {
+      type: "positional",
+      required: false,
+      description: "Plan JSON file (default: read stdin)"
+    },
+    statement: {
+      type: "string",
+      description: "1-based statement index when the input holds several"
+    },
+    ...outputArgs
+  },
+  async run({ args }) {
+    try {
+      applyGlobalFlags(args);
+      process.exitCode = await runAnalyze({
+        ...emitOptionsFrom(args),
+        config: await loadConfig(args.config),
+        file: args.file,
+        statement: resolveStatement(args),
+        redact: args.redact
+      });
+    } catch (err) {
+      process.exitCode = handleFatal(err);
+    }
+  }
+});
+process.on("SIGINT", () => process.exit(130 /* Sigint */));
+process.on("SIGTERM", () => process.exit(130 /* Sigint */));
+var argv = process.argv.slice(2);
+if (argv[0] === "completion") {
+  process.exitCode = runCompletion(argv[1]);
+} else {
+  const started = argv[0] === "run" ? runMain(runCmd, { rawArgs: argv.slice(1) }) : argv[0] === "diff" ? runMain(diffCmd, { rawArgs: argv.slice(1) }) : runMain(main, { rawArgs: argv });
+  started.catch((err) => {
+    process.exitCode = handleFatal(err);
+  });
+}
+//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map