@query-doctor/core 0.4.0 → 0.4.1

package/dist/explain/rewriter.d.ts

@@ -0,0 +1,4 @@
+import type { PostgresExplainResult } from "../sql/database.js";
+import type { ExplainPlan } from "./tree.js";
+export declare function convertPostgresExplain(explainResult: PostgresExplainResult, query: string): ExplainPlan;
+//# sourceMappingURL=rewriter.d.ts.map

package/dist/explain/rewriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rewriter.d.ts","sourceRoot":"","sources":["../../src/explain/rewriter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EAEtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAIV,WAAW,EAIZ,MAAM,WAAW,CAAC;AA0CnB,wBAAgB,sBAAsB,CACpC,aAAa,EAAE,qBAAqB,EACpC,KAAK,EAAE,MAAM,GACZ,WAAW,CA8Bb"}

package/dist/explain/traverse.d.ts

@@ -0,0 +1,3 @@
+import type { PostgresExplainStage } from "../sql/database";
+export declare function traverseExplain(explain: PostgresExplainStage): Generator<PostgresExplainStage>;
+//# sourceMappingURL=traverse.d.ts.map

package/dist/explain/traverse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traverse.d.ts","sourceRoot":"","sources":["../../src/explain/traverse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,wBAAiB,eAAe,CAC9B,OAAO,EAAE,oBAAoB,GAC5B,SAAS,CAAC,oBAAoB,CAAC,CAUjC"}

package/dist/explain/tree.d.ts

@@ -0,0 +1,73 @@
+import type { PostgresExplainResult } from "../sql/database.js";
+export type ExplainNodeKind = string;
+export interface ExplainCostMetrics {
+    startupCost: number;
+    totalCost: number;
+}
+export interface ExplainRowMetrics {
+    estimatedRows: number;
+    actualRows?: number;
+}
+export interface ExplainNodeMetadata {
+    raw: Record<string, unknown>;
+}
+export type DatabaseSystem = "postgresql";
+export interface ExplainPlanMetadata {
+    databaseSystem: DatabaseSystem;
+    query: string;
+    analyzed: boolean;
+    planningTime?: number;
+    executionTime?: number;
+    raw: Record<string, unknown>;
+}
+export interface CostBreakdown {
+    reason: string;
+    cost: number;
+}
+export interface ExplainAlternativePlan {
+    kind: ExplainNodeKind;
+    indexName?: string;
+    pruneReason: string;
+    costBreakdown: CostBreakdown[];
+    totalCost: number;
+}
+export declare class ExplainNode {
+    readonly id: string;
+    readonly kind: ExplainNodeKind;
+    readonly cost: ExplainCostMetrics;
+    readonly rows: ExplainRowMetrics;
+    readonly metadata: ExplainNodeMetadata;
+    parent: ExplainNode | null;
+    private _children;
+    private _alternatives;
+    get children(): readonly ExplainNode[];
+    get alternatives(): readonly ExplainNode[];
+    constructor(params: {
+        id: string;
+        kind: ExplainNodeKind;
+        cost: ExplainCostMetrics;
+        rows: ExplainRowMetrics;
+        metadata: ExplainNodeMetadata;
+    });
+    addChild(node: ExplainNode): void;
+    addAlternative(node: ExplainNode): void;
+    root(): ExplainNode;
+    depth(): number;
+    siblings(): ExplainNode[];
+    ancestors(): ExplainNode[];
+    find(predicate: (node: ExplainNode) => boolean): ExplainNode | undefined;
+    walk(visitor: (node: ExplainNode) => void): void;
+    walkBreadth(visitor: (node: ExplainNode) => void): void;
+}
+export declare class ExplainTree {
+    root: ExplainNode;
+    metadata: ExplainPlanMetadata;
+    constructor(root: ExplainNode, metadata: ExplainPlanMetadata);
+    static fromPostgresExplain(explainResult: PostgresExplainResult, query: string): ExplainTree;
+    replaceFromPostgresExplain(explainResult: PostgresExplainResult, query: string): void;
+    find(predicate: (node: ExplainNode) => boolean): ExplainNode | undefined;
+    walk(visitor: (node: ExplainNode) => void): void;
+    walkBreadth(visitor: (node: ExplainNode) => void): void;
+    nodeCount(): number;
+}
+//# sourceMappingURL=tree.d.ts.map

package/dist/explain/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/explain/tree.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -76,12 +76,25 @@ function isANode(node) {
 }
 function parseNudges(node, stack) {
   const nudges = [];
-  if (is(node, "A_Star")) {
-    nudges.push({
-      kind: "AVOID_SELECT_STAR",
-      severity: "INFO",
-      message: "Avoid using SELECT *"
-    });
+  if (is(node, "SelectStmt")) {
+    const star = node.SelectStmt.targetList?.find(
+      (target) => {
+        if (!(is(target, "ResTarget") && target.ResTarget.val && is(target.ResTarget.val, "ColumnRef"))) {
+          return false;
+        }
+        return target.ResTarget.val.ColumnRef.fields?.some(
+          (field) => is(field, "A_Star")
+        ) ?? false;
+      }
+    );
+    if (star) {
+      nudges.push({
+        kind: "AVOID_SELECT_STAR",
+        severity: "INFO",
+        message: "Avoid using SELECT *",
+        location: star.ResTarget.location
+      });
+    }
   }
   if (is(node, "FuncCall")) {
     const inWhereClause = stack.some((item) => item === "whereClause");
@@ -91,7 +104,8 @@ function parseNudges(node, stack) {
         nudges.push({
           kind: "AVOID_FUNCTIONS_ON_COLUMNS_IN_WHERE",
           severity: "WARNING",
-          message: "Avoid using functions on columns in WHERE clause"
+          message: "Avoid using functions on columns in WHERE clause",
+          location: node.FuncCall.location
         });
       }
     }
@@ -107,18 +121,24 @@ function parseNudges(node, stack) {
           return is(fromItem, "RangeVar") || is(fromItem, "JoinExpr") && hasActualTablesInJoin(fromItem);
         });
         if (hasActualTables) {
+          const firstTable = node.SelectStmt.fromClause.find(
+            (item) => is(item, "RangeVar")
+          );
+          const fromLocation = firstTable?.RangeVar.location;
           if (!node.SelectStmt.whereClause) {
             nudges.push({
               kind: "MISSING_WHERE_CLAUSE",
               severity: "INFO",
-              message: "Missing WHERE clause"
+              message: "Missing WHERE clause",
+              location: fromLocation
             });
           }
           if (!node.SelectStmt.limitCount) {
             nudges.push({
               kind: "MISSING_LIMIT_CLAUSE",
               severity: "INFO",
-              message: "Missing LIMIT clause"
+              message: "Missing LIMIT clause",
+              location: fromLocation
             });
           }
         }
@@ -134,7 +154,8 @@ function parseNudges(node, stack) {
         nudges.push({
           kind: "USE_IS_NULL_NOT_EQUALS",
           severity: "WARNING",
-          message: "Use IS NULL instead of = or != or <> for NULL comparisons"
+          message: "Use IS NULL instead of = or != or <> for NULL comparisons",
+          location: node.A_Expr.location
         });
       }
     }
@@ -142,10 +163,15 @@ function parseNudges(node, stack) {
     if (isLikeOp && node.A_Expr.rexpr) {
       const patternString = getStringConstantValue(node.A_Expr.rexpr);
       if (patternString && patternString.startsWith("%")) {
+        let stringNode;
+        if (is(node.A_Expr.rexpr, "A_Const")) {
+          stringNode = node.A_Expr.rexpr.A_Const;
+        }
         nudges.push({
           kind: "AVOID_LEADING_WILDCARD_LIKE",
           severity: "WARNING",
-          message: "Avoid using LIKE with leading wildcards"
+          message: "Avoid using LIKE with leading wildcards",
+          location: stringNode?.location
         });
       }
     }
@@ -167,14 +193,15 @@ function parseNudges(node, stack) {
     }
   }
   if (is(node, "SelectStmt") && node.SelectStmt.fromClause && node.SelectStmt.fromClause.length > 1) {
-    const tableCount = node.SelectStmt.fromClause.filter(
+    const tables = node.SelectStmt.fromClause.filter(
       (item) => is(item, "RangeVar")
-    ).length;
-    if (tableCount > 1) {
+    );
+    if (tables.length > 1) {
       nudges.push({
         kind: "MISSING_JOIN_CONDITION",
         severity: "WARNING",
-        message: "Missing JOIN condition"
+        message: "Missing JOIN condition",
+        location: tables[1].RangeVar.location
       });
     }
   }
@@ -184,7 +211,8 @@ function parseNudges(node, stack) {
       nudges.push({
         kind: "CONSIDER_IN_INSTEAD_OF_MANY_ORS",
         severity: "WARNING",
-        message: "Consider using IN instead of many ORs"
+        message: "Consider using IN instead of many ORs",
+        location: node.BoolExpr.location
       });
     }
   }
@@ -200,7 +228,8 @@ function parseNudges(node, stack) {
         nudges.push({
           kind: "REPLACE_LARGE_IN_TUPLE_WITH_ANY_ARRAY",
           message: "`in (...)` queries with large tuples can often be replaced with `= ANY($1)` using a single parameter",
-          severity: "INFO"
+          severity: "INFO",
+          location: node.A_Expr.location
         });
       }
     }
@@ -314,7 +343,7 @@ var Walker = class _Walker {
     this.seenReferences = /* @__PURE__ */ new Map();
     this.shadowedAliases = [];
     this.nudges = [];
-    _Walker.traverse(root, [], (node, stack) => {
+    _Walker.traverse(root, (node, stack) => {
       const nodeNudges = parseNudges(node, stack);
       this.nudges = [...this.nudges, ...nodeNudges];
       if (is2(node, "CommonTableExpr")) {
@@ -507,7 +536,10 @@ var Walker = class _Walker {
     }
     this.highlights.push(ref);
   }
-  static traverse(node, stack, callback) {
+  static traverse(node, callback) {
+    _Walker.doTraverse(node, [], callback);
+  }
+  static doTraverse(node, stack, callback) {
     if (isANode2(node)) {
       callback(node, [...stack, getNodeKind(node)]);
     }
@@ -517,15 +549,19 @@ var Walker = class _Walker {
     if (Array.isArray(node)) {
       for (const item of node) {
         if (isANode2(item)) {
-          _Walker.traverse(item, stack, callback);
+          _Walker.doTraverse(item, stack, callback);
         }
       }
     } else if (isANode2(node)) {
       const keys = Object.keys(node);
-      _Walker.traverse(node[keys[0]], [...stack, getNodeKind(node)], callback);
+      _Walker.doTraverse(node[keys[0]], [...stack, getNodeKind(node)], callback);
     } else {
       for (const [key, child] of Object.entries(node)) {
-        _Walker.traverse(child, [...stack, key], callback);
+        _Walker.doTraverse(
+          child,
+          [...stack, key],
+          callback
+        );
       }
     }
   }