Split the README, and fix two demos that crashed instead of explaining themselves

[sqlparser]

The README had grown to 877 lines, and roughly half was archaeology — detailed post-mortems of bugs fixed over the preceding three days. That history is worth keeping; several of those mistakes are easy to make again. But it sat between a new user and the information they needed.

	before	after
README.md	877 lines, history interleaved throughout	403 lines, ordered for someone who just cloned
docs/maintenance-notes.md	—	499 lines, all the history, moved not deleted

The new README runs: what it is → quick start → the demos → rewriting SQL → tests → the parser dependency → project layout → standalone jar → .bat route → CI → contributing.

The maintenance notes open with a before/after table and the lesson every entry shares (anything CI does not run is load-bearing only by luck), then a contents list covering the package rename, the test-tree return, lib/ → lib-repo/, the pom_dlineage saga, the Dependabot sweep, and the rest.

Nothing was dropped. I diffed distinctive facts from the original against both files afterwards — 57% of every source file, 263 of 273, Cp1252, Nashorn, sun.misc.Unsafe, all of it.

Fixed while documenting them

Three dead links. The Tutorials section pointed all three entries at commonTest/testModifySql.java, which left in 683f67b when the library-side test tree went back to gsp_java_core. Replaced with a table of seven demos that do exist here, showing what a parse tree is actually for — the thing an evaluator most wants to see, and the old README never showed it.

scriptwriter crashed on startup. It went straight to sqlstatements.get(0) without checking what parse() returned. Its built-in query is a deliberately hard ~49 KB Oracle statement, and the trial parser refuses input over 10,000 bytes — so the parse failed, the list was empty, and the demo died with:

Exception in thread "main" java.lang.IndexOutOfBoundsException: Index 0 out of bounds for length 0

which names neither the cause (a licensing limit) nor the fix. It now checks the return code, prints the parser's own error, says so explicitly when the input is over the limit, and takes an optional <file.sql> so it can demonstrate something with the trial jar:

Failed to parse the built-in demo query:
trial version can only process query with size of at most 10000 bytes, ...

That input is 47691 characters. The trial parser stops at 10000, so this needs
a licensed build — or pass a smaller file: scriptwriter <file.sql> [/t <vendor>]

This also means the README's claim that the trial build is "fully functional for evaluation and enough for every demo here" was wrong. Corrected, with the limit documented.

events/ProcessSQLStatement could never run. Its input was:

String sqlfile = "C:\\Users\\DELL\\Downloads\\20240311110800487_mssql_sql\\data.sql";

A hardcoded absolute path into one developer's Downloads folder. The file was missing, parse() failed, and the error branch then called getErrormessage().substring(0, 1000) unconditionally on a shorter message — throwing StringIndexOutOfBoundsException from the code whose job was to report the error. It now takes the file as an argument, prints a usage line without one, and bounds the substring.

The CI gap that let both through

run-all-demos.sh matched only linkage failures (NoClassDefFoundError and friends), so a demo could crash on its own logic and still be reported as started. It now also fails any demo that throws Exception in thread "main" when run with no arguments — with nothing to work on, a demo should print a usage line, not a stack trace.

That check is what found ProcessSQLStatement; I only went looking after scriptwriter. All 77 demos pass it.

Worth recording, and it's in the notes: my first survey of this reported "0 of 77 throw" and was wrong — it used a relative -cp target/classes from another working directory, so every demo failed to load and matched no pattern. run-all-demos.sh builds an absolute classpath for exactly this reason.

Verification

check	result
mvn clean package	green
tests	144 pass, 0 failed, 0 skipped
run-all-demos.sh	77/77, with the new guard active
run-demo-cases.sh	22/22
smoke-dlineage-jar.sh	green
every command the new README documents	actually run, output matches
every relative link and anchor in both files	resolved programmatically

🤖 Generated with Claude Code

https://claude.ai/code/session_012qPRpoD8exYRrUmbfXXWXj