Confusing API for collecting Problems in ast to plan conversion

[alancai98]

Currently, the PartiQLPlanner interface has a function called plan that can take a ProblemCallback:

partiql-lang-kotlin/partiql-planner/src/main/kotlin/org/partiql/planner/PartiQLPlanner.kt

Line 23 in 5bcde13

public fun plan(statement: Statement, session: Session, onProblem: ProblemCallback = {}): Result

This is defaulted to a unit if it's not specified in the function call. The function returns a PartiQLPlanner.Result, which has a field for all the Problems:

partiql-lang-kotlin/partiql-planner/src/main/kotlin/org/partiql/planner/PartiQLPlanner.kt

Lines 25 to 33 in 5bcde13

	/**
	* Planner result along with any warnings.
	*
	* @property plan
	*/
	public class Result(
	public val plan: PartiQLPlan,
	public val problems: List<Problem>,
	)

It can be confusing to the user of the API whether they should check the ProblemCallback that they may pass in or the Result to check if any errors occurred during the ast -> plan transformation. Currently, the default PartiQLPlanner always returns an emptyList():

partiql-lang-kotlin/partiql-planner/src/main/kotlin/org/partiql/planner/PartiQLPlannerDefault.kt

Line 48 in 5bcde13

return PartiQLPlanner.Result(plan, emptyList())

so checking the PartiQLPlanner.Result for an error does not check anything since it'll always be an empty list.

I came across this issue when our other repo calls the plan function without any ProblemCallback:
https://github.com/partiql/partiql-scribe/blob/f9627257460d28f89201020d096b8f3c94be06ca/src/main/kotlin/org/partiql/scribe/ScribeCompiler.kt#L58-L65

    private fun plan(statement: Statement, session: PartiQLPlanner.Session): PartiQLPlan {
        val result = planner.plan(statement, session)
        val errors = result.problems.filter { it.details.severity == ProblemSeverity.ERROR }
        if (errors.isNotEmpty()) {
            throw RuntimeException("Planner encountered errors: ${errors.joinToString()}")
        }
        return result.plan
    }

The above code does not do any error checking following planning.

Additional Context

• Java version: 11
• PartiQL version: 0.14.5-SNAPSHOT