feat(analysis): diagnose untyped placeholders and suggest a cast

A placeholder that no clause types and no cast states the type of is now
rejected as "Cannot infer the type of <placeholder> in <where>; state it
with a cast, such as <placeholder>::text", naming the first such
placeholder in textual order as the query spells it. A bare placeholder
projection gets the same diagnostic. Clause rejections still come first,
and the placeholder accounting check remains as an internal guard.

Author: omer-cengel

docs/queries.md

@@ -602,7 +602,19 @@ string literal, a quoted identifier, or a comment is not a parameter.
   such as `:"x"`, and an `&name` placeholder.
 - A placeholder that neither a clause nor a cast types — for example
   `ORDER BY $1`, `lower(name) = :name`, or `(:x)::int`, whose placeholder is not
-  the direct operand of its cast — is rejected rather than left unbound.
+  the direct operand of its cast — is rejected rather than left unbound, as
+  `Cannot infer the type of :name in lower(name) = :name; state it with a cast,
+  such as :name::text`. The diagnostic writes the placeholder as the query
+  spells it, `$1` or `:name`, and names where the query writes it: the smallest
+  expression written around the placeholder, on one line, with whatever
+  separates two tokens written as one space. A concatenated pattern is
+  therefore named in its whole `LIKE` predicate and an `IN` list in its `IN`
+  predicate, while a placeholder written inside no expression stands alone in
+  its clause and is named by the keyword that opens that clause, in upper case:
+  `SELECT`, `DISTINCT ON`, `ON`, `WHERE`, `GROUP BY`, `HAVING`, `ORDER BY`,
+  `LIMIT`, `OFFSET`, `FETCH`, `VALUES`, `SET`, or `RETURNING`. One query reports
+  its first untyped placeholder in textual order, after the rules of its clauses
+  have run, so a clause's own rejection comes first.
 
 ### Logical order versus textual order
 
@@ -882,7 +894,12 @@ name, and its header line.
   `LIMIT $1 + 1` or `OFFSET $1 + 1`, a `LIMIT a, b` row count such as
   `LIMIT 5, $1`, a placeholder inside a write value such as
   `COALESCE($2, bio)`, and a `FETCH FIRST $1 ROWS ONLY` clause, so dynamic `IN`
-  expansion is unavailable. A cast states the type of such a placeholder in
+  expansion is unavailable. Each is rejected as `Cannot infer the type of $1 in
+  $1 + 1; state it with a cast, such as $1::text`, which names the placeholder
+  as the query spells it and, after `in`, the smallest expression the query
+  writes around it, on one line, or the upper-case keyword of the clause the
+  placeholder stands alone in, such as `ORDER BY` for `ORDER BY $1` and
+  `SELECT` for `SELECT $1 AS x`. A cast states the type of such a placeholder in
   every one of those locations, and it does not accept a placeholder that is not
   the direct operand of its cast, such as `(:x)::int`.
 - A cast type sqlcj does not map, such as `$1::interval` or a
@@ -1220,7 +1237,7 @@ Writes and `RETURNING`:
   and `QueryAnalyzerTest.shouldRejectAnUnknownConflictColumn` cover the accepted
   conflict target, both actions, the `EXCLUDED`, placeholder, cast, and
   computed assignments, the binding order after the `VALUES` placeholders, the
-  returning row type, and the conflict forms, unaccounted placeholder, and
+  returning row type, and the conflict forms, untyped placeholder, and
   unknown target, assigned, and `EXCLUDED` columns that are rejected on an
   `:exec` and on a returning insert alike, and
   `PostgresIntegrationTest.shouldExecuteGeneratedUpsertsAgainstPostgres`
@@ -1268,6 +1285,15 @@ Parameters:
   `QueryAnalyzerTest.shouldRejectAnonymousParameter`, and
   `QueryAnalyzerTest.shouldKeepPlaceholderTextThatIsNotAParameter` cover
   ordering, repetition, and rejection.
+- `QueryAnalyzerTest.shouldRejectAnUntypedPlaceholder`,
+  `QueryAnalyzerTest.shouldRejectAnUntypedPlaceholderOfAConcatenatedPattern`,
+  `QueryAnalyzerTest.shouldRejectTheFirstUntypedPlaceholderOfAQuery`,
+  `SqlParserTest.shouldReportTheEnclosingExpressionOfAPlaceholder`,
+  `SqlParserTest.shouldReportTheClauseOfAPlaceholderThatStandsAlone`, and
+  `SqlcjCompilerIntegrationTest.shouldRejectUntypedPlaceholderBeforeWriting`
+  cover the untyped-placeholder diagnostic, in both placeholder forms, with the
+  enclosing expression and the clause keyword it names, the first occurrence it
+  reports, and the whole located line of a compiled source.
 - `SqlParserTest.shouldCompileNamedParametersByFirstOccurrence`,
   `SqlParserTest.shouldCompileNamesThatDifferInCaseAsDistinctParameters`,
   `SqlParserTest.shouldReportBothPlaceholderFormsOfOneSource`,

sqlcj-cli/src/main/java/dev/sqlcj/analysis/QueryAnalyzer.java

@@ -81,6 +81,15 @@ public final class QueryAnalyzer {
     private static final String MIXED_PLACEHOLDER_REJECTION = """
         Indexed '$N' and named ':name' placeholders must not be mixed in one query""";
 
+    /**
+     * The rejection of a placeholder that no clause of the query types and no
+     * cast states the type of, which names the placeholder as the query spells
+     * it and where the query writes it. The suggested cast is always
+     * {@code ::text}, because sqlcj infers no type for such a placeholder.
+     */
+    private static final String UNTYPED_PLACEHOLDER_REJECTION = """
+        Cannot infer the type of %s in %s; state it with a cast, such as %s::text""";
+
     /** The character that opens a supported named placeholder. */
     private static final String NAME_PREFIX = ":";
 
@@ -337,7 +346,7 @@ private QueryModel analyzeSelect(Query query, ParsedSql parsedSql, Select select
 
         List<Source> sources = resolveSources(plainSelect, table, schema);
 
-        List<QueryColumn> columns = resolveColumns(plainSelect, sources, schema);
+        List<QueryColumn> columns = resolveColumns(plainSelect, parsedSql, sources, schema);
 
         Placeholders placeholders = toPlaceholders(parsedSql, schema);
 
@@ -864,8 +873,9 @@ private QueryModel toQueryModel(
      * <p>An occurrence a clause of the query typed is that clause's parameter.
      * Every other occurrence is typed by the cast it is the direct operand of,
      * wherever in the statement it stands, and is named after its own
-     * placeholder. A placeholder neither a clause nor a cast types contributes
-     * no parameter, so the accounting reports it as unaccounted.
+     * placeholder. A placeholder neither a clause nor a cast types has no type
+     * to generate, so the first such occurrence in textual order is rejected
+     * naming where the query writes it.
      */
     private List<QueryParameter> resolveOccurrences(ParsedSql parsedSql, Placeholders placeholders) {
         List<QueryParameter> occurrences = new ArrayList<>();
@@ -881,18 +891,61 @@ private List<QueryParameter> resolveOccurrences(ParsedSql parsedSql, Placeholder
 
             CastPlaceholder cast = placeholders.ofCast(occurrence.cast());
 
-            if (cast != null) {
-                occurrences.add(
-                    toCastParameter(cast, indexedParameterName(cast.placeholder()))
-                );
+            if (cast == null) {
+                throw untypedPlaceholder(occurrence);
             }
+
+            occurrences.add(
+                toCastParameter(cast, indexedParameterName(cast.placeholder()))
+            );
         }
 
         placeholders.requireReportedOccurrences();
 
         return occurrences;
     }
 
+    /**
+     * The rejection of one placeholder occurrence no clause of the query typed
+     * and no cast states the type of, which the SQL parser reported together
+     * with where the query writes it.
+     */
+    private UnsupportedOperationException untypedPlaceholder(PlaceholderOccurrence occurrence) {
+        String spelled = spelledPlaceholder(occurrence.placeholder());
+
+        return new UnsupportedOperationException(
+            UNTYPED_PLACEHOLDER_REJECTION.formatted(spelled, occurrence.enclosing(), spelled)
+        );
+    }
+
+    /**
+     * One placeholder expression as the query spells it, which is its own name
+     * for a named placeholder and its index for an indexed one. Every other
+     * placeholder form is already rejected before a placeholder is spelled.
+     */
+    private String spelledPlaceholder(Expression placeholder) {
+        if (placeholder instanceof JdbcNamedParameter named) {
+            return NAME_PREFIX + named.getName();
+        }
+
+        return "$" + ((JdbcParameter) placeholder).getIndex();
+    }
+
+    /**
+     * The occurrence the SQL parser reported for one placeholder expression of
+     * the parsed source, which every placeholder of that source has.
+     */
+    private PlaceholderOccurrence occurrenceOf(ParsedSql parsedSql, Expression placeholder) {
+        return parsedSql.placeholders().stream()
+            .filter(occurrence -> occurrence.placeholder() == placeholder)
+            .findFirst()
+            .orElseThrow(
+                () -> new IllegalStateException(
+                    "A placeholder is not a reported placeholder occurrence."
+                )
+            );
+    }
+
     /**
      * Requires that the occurrences resolved against the schema are exactly the
      * placeholder tokens the SQL parser reported, in the same textual order, so
@@ -2048,9 +2101,14 @@ private Placeholders toPlaceholders(ParsedSql parsedSql, Schema schema) {
      *
      * <p>An aliased scalar count and an aliased cast each resolve to one column
      * in their own position, so either may stand beside any other item.
+     *
+     * <p>A bare placeholder projection is a placeholder a cast makes a
+     * supported result column, so it is rejected as an untyped placeholder
+     * rather than as an unsupported result expression.
      */
     private List<QueryColumn> resolveColumns(
         PlainSelect plainSelect,
+        ParsedSql parsedSql,
         List<Source> sources,
         Schema schema
     ) {
@@ -2109,6 +2167,10 @@ private List<QueryColumn> resolveColumns(
                 continue;
             }
 
+            if (expression instanceof JdbcParameter || expression instanceof JdbcNamedParameter) {
+                throw untypedPlaceholder(occurrenceOf(parsedSql, expression));
+            }
+
             throw new UnsupportedOperationException(
                 "Unsupported SELECT expression: "
                     + expression.getClass().getSimpleName()