[codex] Add query diagnostics CLI

CHANGELOG.md

@@ -1,3 +1,8 @@
+# Unreleased
+
+- Add `pgtyped-rescript diagnose` for inspecting named SQL queries with `describe`, `explain`, and `explain analyze`, including support for parameter JSON, parameter files, processed SQL output, query listing, JSON output, and statement timeouts.
+- Reduce default CLI generation output to only recompiled files, errors, and concise unchanged-run summaries; pass `--verbose` to restore detailed per-file processing and skipped-file output.
+
 # 3.0.1
 
 - Gracefully skip optional AST-based query analysis when `pgsql-ast-parser` cannot parse valid PostgreSQL syntax, so generation can continue with database-derived types.

packages/cli/package.json

@@ -48,7 +48,9 @@
     "io-ts-reporters": "^2.0.1",
     "nunjucks": "3.2.4",
     "pascal-case": "^3.1.1",
+    "pg": "^8.11.2",
     "pgtyped-rescript-query": "^3.0.1",
+    "pgtyped-rescript-runtime": "^3.0.0",
     "piscina": "^4.0.0",
     "tinypool": "^0.7.0",
     "ts-parse-database-url": "^1.0.3",
@@ -58,6 +60,7 @@
     "@types/debug": "4.1.8",
     "@types/fs-extra": "11.0.1",
     "@types/nunjucks": "^3.1.3",
+    "@types/pg": "^8.10.2",
     "@types/yargs": "17.0.24",
     "rescript": "12.2.0"
   },

packages/cli/src/diagnostics.rescript.test.ts

@@ -0,0 +1,122 @@
+import { jest } from '@jest/globals';
+import { parseSQLFile, queryASTToIR } from '@pgtyped/parser';
+import fs from 'fs';
+import {
+  getParameterLabels,
+  parseErrorFields,
+  runDiagnostics,
+} from './diagnostics.js';
+
+const sqlFile = '../example/src/books/books.sql';
+
+describe('diagnostics', () => {
+  let logSpy: ReturnType<typeof jest.spyOn>;
+  let errorSpy: ReturnType<typeof jest.spyOn>;
+
+  beforeEach(() => {
+    logSpy = jest.spyOn(console, 'log').mockImplementation(() => undefined);
+    errorSpy = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  test('lists query names without config', async () => {
+    await runDiagnostics(undefined, {
+      file: sqlFile,
+      list: true,
+      mode: 'explain',
+      format: 'text',
+    });
+
+    expect(logSpy).toHaveBeenCalledWith('FindBookById');
+    expect(logSpy).toHaveBeenCalledWith('InsertBooks');
+  });
+
+  test('prints processed SQL without config', async () => {
+    await runDiagnostics(undefined, {
+      file: sqlFile,
+      queryName: 'FindBookById',
+      sql: true,
+      mode: 'explain',
+      format: 'text',
+    });
+
+    expect(logSpy).toHaveBeenCalledWith('SELECT * FROM books WHERE id = $1');
+  });
+
+  test('keeps scalar parameter labels when params are supplied', () => {
+    const query = parseSQLFile(`
+      /* @name FindBookById */
+      SELECT * FROM books WHERE id = :id;
+    `).queries[0];
+
+    const labels = getParameterLabels(queryASTToIR(query, null), { id: 1 });
+
+    expect(labels.get(1)).toBe('id');
+  });
+
+  test('does not require params for unused parameter declarations', async () => {
+    const file = '/tmp/pgtyped-unused-params.sql';
+    await fs.promises.writeFile(
+      file,
+      `
+        /*
+          @name StaticQuery
+          @param unused -> (id!)
+        */
+        SELECT 1;
+      `,
+    );
+
+    await runDiagnostics(undefined, {
+      file,
+      queryName: 'StaticQuery',
+      sql: true,
+      mode: 'explain',
+      format: 'text',
+    });
+
+    expect(logSpy).toHaveBeenCalledWith('SELECT 1');
+  });
+
+  test('uses SQLSTATE as parse error code', () => {
+    expect(
+      parseErrorFields({
+        C: '42601',
+        M: 'syntax error at or near "FROM"',
+        R: 'scanner_yyerror',
+      }),
+    ).toMatchObject({
+      errorCode: '42601',
+      message: 'syntax error at or near "FROM"',
+    });
+  });
+
+  test('keeps spread-pick labels when params are supplied', () => {
+    const query = parseSQLFile(`
+      /*
+        @name InsertBooks
+        @param books -> ((rank!, name!)...)
+      */
+      INSERT INTO books (rank, name)
+      VALUES :books;
+    `).queries[0];
+
+    const labels = getParameterLabels(queryASTToIR(query, null), {
+      books: [
+        { rank: 1, name: 'one' },
+        { rank: 2, name: 'two' },
+      ],
+    });
+
+    expect([...labels.values()]).toEqual([
+      'books.rank',
+      'books.name',
+      'books.rank',
+      'books.name',
+    ]);
+  });
+});