[codex] Add query diagnostics CLI by zth · Pull Request #32 · zth/pgtyped-rescript

zth · 2026-05-29T10:12:45Z

Summary

Adds a pgtyped-rescript diagnose CLI command for quickly inspecting pgtyped SQL queries, and makes normal typegen output much quieter.

What changed

Adds diagnose <sqlFile> with modes for describe, explain, and analyze.
Supports --list, --sql, --params, --params-file, --format, and --timeout.
Enriches describe output with parameter labels, PostgreSQL type names, OIDs, and source columns.
Adds diagnostics tests for config-free query listing/SQL printing, parameter label preservation, unused @param declarations, and SQLSTATE parse error mapping.
Reduces normal typegen output to recompiled files, errors, and a concise unchanged summary.
Adds --verbose to restore detailed processing output such as worker pool size, per-file processing, per-file skips, and full summary counts.
Adds changelog entries for both user-facing changes.

Review follow-up

Avoids adding a new pgtyped-rescript-query public export dependency from the CLI by keeping the wire-level describe helper local to the CLI.
Makes the explain/analyze params-required guard consider only actually used params, so unused @param declarations do not require dummy JSON.
Uses PostgreSQL SQLSTATE (C) rather than backend routine (R) for parse error diagnostic codes.

Validation

git diff --check
npm run check --workspace packages/cli
npm run build --workspace packages/cli
npm test --workspace packages/cli -- --runInBand
npm run lint -- --project packages/cli/tsconfig.json
Manual smoke tests against the example Postgres service for describe, explain, and analyze --format json --timeout 5s.
Manual smoke tests for normal and --verbose typegen output.

zth · 2026-05-29T10:24:39Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a3618aceba

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-29T10:27:52Z

+import fs from 'fs-extra';
+import pg from 'pg';
+import { processSQLQueryIR, QueryParameters } from 'pgtyped-rescript-runtime';
+import { getTypeData, IParseError, startup } from 'pgtyped-rescript-query';


Bump query dependency for getTypeData

This import depends on a new pgtyped-rescript-query export, but packages/cli/package.json still allows any ^3.0.1 install and the previous 3.0.1 entry point did not export getTypeData. In a consumer lockfile that upgrades only pgtyped-rescript while keeping pgtyped-rescript-query@3.0.1, Node will fail to load the CLI before any command runs. Please raise the dependency floor to the first query package version that includes this export.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-05-29T10:27:52Z

+    queryIR.params.length > 0 &&
+    !params


Ignore unused params when requiring diagnostics input

This guard treats declared-but-unused @param entries as requiring --params, because queryIR.params includes parameters that the parser only warns about as unused, while processSQLQueryIR later filters by usedParamSet. For a query whose SQL has no placeholders after unused declarations are ignored, diagnose --mode explain is blocked unless the user supplies dummy JSON even though the generated SQL needs no bindings.

Useful? React with 👍 / 👎.

zth · 2026-05-29T10:32:28Z

Addressed the Codex review feedback:

Removed the new CLI dependency on a fresh pgtyped-rescript-query public export by keeping the wire-level describe helper local to the CLI.
Changed the params-required guard to look only at actually used params, so unused @param declarations do not require dummy params.
Added regression coverage for unused parameter declarations.

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: df42388a89

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-29T10:35:50Z

+  if ('fields' in parseResult) {
+    const { fields: errorFields } = parseResult;
+    return {
+      errorCode: errorFields.R,


Use SQLSTATE for parse error codes

When describe hits a server parse error, this fills errorCode from ErrorResponse field R, but PostgreSQL uses R for the backend routine and C for the SQLSTATE code (the wire test fixture includes both, e.g. C: '3D000' and R: 'InitPostgres'). This makes diagnostic JSON/text report unstable routine names such as scanner_yyerror instead of actionable SQLSTATEs like 42601.

Useful? React with 👍 / 👎.

zth · 2026-05-29T10:38:47Z

Addressed the latest Codex review feedback:

diagnose describe parse errors now use PostgreSQL SQLSTATE (C) for errorCode, falling back to routine (R) only if SQLSTATE is absent.
Added a regression test for SQLSTATE parse error mapping.

@codex review

zth · 2026-05-29T10:42:47Z

@codex review latest commit 2951748

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2951748d0f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-29T10:45:29Z

+import crypto from 'crypto';
+import fs from 'fs-extra';
+import pg from 'pg';
+import { processSQLQueryIR, QueryParameters } from 'pgtyped-rescript-runtime';


Declare the runtime dependency before importing it

This new import makes the CLI package depend directly on pgtyped-rescript-runtime, but packages/cli/package.json only adds pg and still does not declare the runtime package. In package managers with strict or non-hoisted installs, such as pnpm/Yarn PnP or nested npm layouts, pgtyped-rescript/lib/index.js cannot resolve transitive dependencies of pgtyped-rescript-query, so the CLI can fail at startup before any command runs. Please add pgtyped-rescript-runtime as a direct dependency of the CLI package.

Useful? React with 👍 / 👎.

zth · 2026-05-29T10:50:29Z

Addressed latest Codex review feedback:

Added pgtyped-rescript-runtime as a direct CLI dependency because diagnostics imports it directly.

@codex review

zth · 2026-05-29T10:53:24Z

@codex review latest commit 438845d

zth · 2026-05-29T11:04:06Z

@codex review

chatgpt-codex-connector · 2026-05-29T11:08:11Z

Codex Review: Didn't find any major issues. Can't wait for the next one!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

zth force-pushed the codex/query-diagnostics branch 2 times, most recently from 8b45591 to a3618ac Compare May 29, 2026 10:21

zth marked this pull request as ready for review May 29, 2026 10:24

chatgpt-codex-connector Bot reviewed May 29, 2026

View reviewed changes

zth force-pushed the codex/query-diagnostics branch from a3618ac to df42388 Compare May 29, 2026 10:32

chatgpt-codex-connector Bot reviewed May 29, 2026

View reviewed changes

zth force-pushed the codex/query-diagnostics branch from df42388 to 2951748 Compare May 29, 2026 10:38

chatgpt-codex-connector Bot reviewed May 29, 2026

View reviewed changes

Add query diagnostics CLI

438845d

zth force-pushed the codex/query-diagnostics branch from 2951748 to 438845d Compare May 29, 2026 10:50

zth merged commit 8cdfd68 into rescript May 29, 2026
5 checks passed

zth deleted the codex/query-diagnostics branch May 29, 2026 11:11

Conversation

zth commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed

Review follow-up

Validation

Uh oh!

zth commented May 29, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 29, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot May 29, 2026

Choose a reason for hiding this comment

Uh oh!

zth commented May 29, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 29, 2026

Choose a reason for hiding this comment

Uh oh!

zth commented May 29, 2026

Uh oh!

zth commented May 29, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 29, 2026

Choose a reason for hiding this comment

Uh oh!

zth commented May 29, 2026

Uh oh!

zth commented May 29, 2026

Uh oh!

zth commented May 29, 2026

Uh oh!

chatgpt-codex-connector Bot commented May 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

zth commented May 29, 2026 •

edited

Loading