docs: document the corrective facts in CLI diagnostics

Author: omer-cengel

README.md

@@ -84,8 +84,9 @@ A relative `--config` value is resolved against the directory the command is
 run in, while the relative paths inside the file stay relative to the file's own
 directory. `generate` exits with status `0` on success, and with status `1`
 after printing one diagnostic for invalid configuration, an unreadable source, a
-query it cannot compile, an output directory or file it cannot write, a stale
-generated file it cannot delete, or an output manifest it cannot read or write.
+schema it cannot parse, a query it cannot compile, an output directory or file
+it cannot write, a stale generated file it cannot delete, or an output manifest
+it cannot read or write.
 
 ## Getting started
 

docs/configuration.md

@@ -289,17 +289,21 @@ sqlcj: Generated file paths for repositories 'UserData' and 'Userdata' differ on
 
 Invalid configuration, unreadable SQL sources, and output that cannot be written
 or cleaned up make `sqlcj generate` print a single message on standard error and
-exit with a non-zero status. The message names the configuration file and, when
-available, the offending field, value, source path, or output path:
+exit with status `1`. The message names the configuration file and, when
+available, the offending field, value, source path, or output path, and ends
+with the fact that explains the failure, such as the reason the filesystem
+reports or the problem the YAML parser reports with its line and column:
 
 ```text
+sqlcj: Cannot read configuration file: /home/dev/project/sqlcj.yaml: No such file or directory
+sqlcj: Malformed configuration file: /home/dev/project/sqlcj.yaml: expected <block end>, but found '<block mapping start>' at line 2, column 3
 sqlcj: Invalid configuration in /home/dev/project/sqlcj.yaml: 'java.package' value 'dev.class.generated' is not a valid Java package name
-sqlcj: Cannot read queries source: /home/dev/project/sql/missing.sql
-sqlcj: Cannot create output directory: /home/dev/project/target/generated-sources/sqlcj/dev/example/generated
-sqlcj: Cannot write generated file: /home/dev/project/target/generated-sources/sqlcj/dev/example/generated/UsersRepository.java
-sqlcj: Cannot read output manifest: /home/dev/project/target/generated-sources/sqlcj/sqlcj-manifest.txt
-sqlcj: Cannot delete stale generated file: /home/dev/project/target/generated-sources/sqlcj/dev/example/generated/OrdersRepository.java
-sqlcj: Cannot write output manifest: /home/dev/project/target/generated-sources/sqlcj/sqlcj-manifest.txt
+sqlcj: Cannot read queries source: /home/dev/project/sql/missing.sql: No such file or directory
+sqlcj: Cannot create output directory: /home/dev/project/target/generated-sources/sqlcj/dev/example/generated: Not a directory
+sqlcj: Cannot write generated file: /home/dev/project/target/generated-sources/sqlcj/dev/example/generated/UsersRepository.java: Permission denied
+sqlcj: Cannot read output manifest: /home/dev/project/target/generated-sources/sqlcj/sqlcj-manifest.txt: Permission denied
+sqlcj: Cannot delete stale generated file: /home/dev/project/target/generated-sources/sqlcj/dev/example/generated/OrdersRepository.java: Permission denied
+sqlcj: Cannot write output manifest: /home/dev/project/target/generated-sources/sqlcj/sqlcj-manifest.txt: Permission denied
 ```
 
 ## Generated Output and Failures

docs/postgresql.md

@@ -219,20 +219,22 @@ accepted:
 
 ### Failure Behavior
 
-An unsupported type or an unsupported statement stops compilation. `sqlcj
-generate` prints a single message on standard error and exits with a non-zero
-status. Because every configured source is analyzed and generated before the
-run writes its first file, such a failure writes no generated file, and output
+An unsupported type, an unsupported statement, or a schema sqlcj cannot parse
+stops compilation. `sqlcj generate` prints a single message on standard error
+and exits with status `1`. Because every configured source is analyzed and
+generated before the run writes its first file, such a failure writes no
+generated file, and output
 written by an earlier successful run is left unchanged. The writing step itself
 is sequential rather than atomic; see
 [Generated Output and Failures](configuration.md#generated-output-and-failures).
 
-The message names the schema source and the offending type or statement:
+The message names the schema source and the offending type or statement, or the
+syntax error with the line and column it was found at:
 
 ```text
 sqlcj: Invalid schema source /home/dev/project/schema.sql: Unsupported SQL column type: TIMESTAMPTZ
 sqlcj: Invalid schema source /home/dev/project/schema.sql: Unsupported schema statement: Alter
-sqlcj: Invalid schema source /home/dev/project/schema.sql: Failed to parse schema
+sqlcj: Invalid schema source /home/dev/project/schema.sql: Encountered unexpected token: ";" <ST_SEMICOLON> at line 4, column 1
 ```
 
 ## Verified by