Fix demo bugs and doc gaps from issues #40-45

- #40: document/use -Dexec.classpathScope=compile, not runtime; system-scoped
  deps (simple-xml, fastjson, ...) are excluded from Maven's runtime scope,
  breaking any demo that touches one (e.g. dlineageBasic).
- #41: note in gettablecolumns/readme.md that runGetTableColumn needs a live
  DB connection and doesn't compile here; point at getResultColumn instead.
- #42: traceColumn's main() called runFile() against a hardcoded, nonexistent
  Windows path with the working runText() call commented out, so it always
  exited 0 with zero output. Uncommented runText(); added a readme.md.
- #43: traceDataLineageTest's two methods were fully commented out, testing
  nothing, against fixture files that don't exist in this repo. Replaced with
  one real test. While building it, found the actual reason the
  tracedatalineage demo never produces output: TGSqlParser.setSqlInputStream()
  silently parses to zero statements against the public trial artifact.
  Switched to reading the stream into sqltext, which parses correctly; added
  a sample/ directory and readme.md now that the demo actually works.
- #44: sqlrefactor's rmdupParenthesis blocked on an undocumented interactive
  stdin prompt for dialect selection. Replaced it with a /t <vendor> flag,
  consistent with every other demo; added a readme.md.
- #45: README's `head -1` trick for finding a demo's package line returns
  nothing when a blank line or comment precedes it; switched to
  `grep -m1 '^package'`.

Test count in README/CLAUDE.md drops from 153 to 152 (net -1 from replacing
traceDataLineageTest's two no-op methods with one real one); still 3 known
analyzespTest failures, 149 (was 150) passing.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012qPRpoD8exYRrUmbfXXWXj

Author: 2 people

.github/workflows/build.yml

@@ -86,6 +86,6 @@ jobs:
           printf 'SELECT a.id, b.name FROM ta a JOIN tb b ON a.id = b.id WHERE a.x > 1;\n' > q.sql
           out=$(mvn -q exec:java \
             -Dexec.mainClass=gudusoft.gsqlparser.demos.checksyntax.checksyntax \
-            -Dexec.args="/f q.sql /t oracle" -Dexec.classpathScope=runtime)
+            -Dexec.args="/f q.sql /t oracle" -Dexec.classpathScope=compile)
           echo "$out"
           grep -q "syntax errors: 0" <<<"$out"

README.md

@@ -37,7 +37,7 @@ SELECT a.id, b.name FROM ta a JOIN tb b ON a.id = b.id WHERE a.x > 1;
 SQL
 
 mvn -q exec:java -Dexec.mainClass=gudusoft.gsqlparser.demos.checksyntax.checksyntax \
-    -Dexec.args="/f q.sql /t oracle" -Dexec.classpathScope=runtime
+    -Dexec.args="/f q.sql /t oracle" -Dexec.classpathScope=compile
 ```
 
 ```text
@@ -50,7 +50,7 @@ Reformat it:
 
 ```bash
 mvn -q exec:java -Dexec.mainClass=demos.formatsql.formatsql \
-    -Dexec.args="q.sql" -Dexec.classpathScope=runtime
+    -Dexec.args="q.sql" -Dexec.classpathScope=compile
 ```
 
 ```text
@@ -66,16 +66,26 @@ Argument conventions differ between demos: `checksyntax` takes `/f <file>` and
 `/t <vendor>`, while `formatsql` takes a bare filename. Run any demo with no
 arguments and it prints its own usage line.
 
+> **Use `-Dexec.classpathScope=compile`, not `runtime`.** `pom.xml` declares
+> `simple-xml`, `fastjson` and a few other jars under `lib/` with
+> `<scope>system</scope>`, since they have no public Maven coordinate. Maven's
+> `runtime` classpath scope excludes `system`-scoped dependencies by design, so
+> any demo that touches one of them (e.g. `dlineageBasic`, which uses
+> `org.simpleframework.xml`) fails with `NoClassDefFoundError` under `runtime`
+> even though the jar is right there in `lib/`. `compile` scope includes them
+> and works for every demo.
+
 > **Package names are not uniform yet.** A move of the demos from `demos.*` to
 > `gudusoft.gsqlparser.demos.*` is partly done: 176 files sit under
 > `src/main/java/gudusoft/` while still declaring `package demos.*`, so the class
 > you pass to `-Dexec.mainClass` follows the **package declaration**, not the
 > directory. `checksyntax` is `gudusoft.gsqlparser.demos.checksyntax.checksyntax`;
-> `formatsql` is `demos.formatsql.formatsql`. When in doubt, read the first line
-> of the source:
+> `formatsql` is `demos.formatsql.formatsql`. When in doubt, grep the first
+> `package` line — some of these files lead with a blank line or a comment, so
+> plain `head -1` sometimes returns nothing:
 >
 > ```bash
-> head -1 src/main/java/gudusoft/gsqlparser/demos/<demo>/<Demo>.java
+> grep -m1 '^package' src/main/java/gudusoft/gsqlparser/demos/<demo>/<Demo>.java
 > ```
 
 ## Where the parser comes from
@@ -134,7 +144,7 @@ mvn -Plocal -Dgsp.core.version=4.1.5.9 compile
 
 mvn -q -Plocal -Dgsp.core.version=4.1.5.9 exec:java \
     -Dexec.mainClass=gudusoft.gsqlparser.demos.checksyntax.checksyntax \
-    -Dexec.args="/f q.sql /t oracle" -Dexec.classpathScope=runtime
+    -Dexec.args="/f q.sql /t oracle" -Dexec.classpathScope=compile
 ```
 
 This replaces the loop that existed while the demos were a vendored module of
@@ -171,14 +181,20 @@ directories carry their own `readme.md`.
 mvn test
 ```
 
-153 tests run. **Three currently fail**, all in
+152 tests run. **Three currently fail**, all in
 `gudusoft.gsqlparser.demosTest.analyzespTest` (`testSample1`, `testSample6`,
 `testSample8`). They compare stored-procedure relation output against golden
 strings written for an older parser build, and that output has since changed.
 They are left in place rather than deleted or rewritten, because they are a
-real signal about output drift rather than a broken harness. The other 150
+real signal about output drift rather than a broken harness. The other 149
 pass. That is why the getting-started step above uses `-DskipTests`.
 
+(`traceDataLineageTest` used to contribute 2 of those "passing" tests with
+every line commented out — no assertions, testing nothing, referencing fixture
+files that never shipped with this repo. It's been replaced with one real
+test against inline SQL; see
+[#43](https://github.com/sqlparser/gsp_demo_java/issues/43).)
+
 ## What is excluded from the build
 
 Some demos read metadata straight out of a running database over JDBC, using

src/main/java/gudusoft/gsqlparser/demos/gettablecolumns/readme.md

@@ -8,6 +8,24 @@ For more detailed information about how this tools works, please check [this art
 ## Usage
 `java runGetTableColumn [/f <path_to_sql_file>] [/t <database type>] [/<show option>]`
 
+> **`runGetTableColumn` does not compile in this repository.** It connects to a
+> live database over JDBC to resolve ambiguous columns (see "Resolve the
+> ambiguous columns in SQL query" below), using a `TSQLDataSource` class the
+> public trial parser artifact doesn't ship — `pom.xml` excludes it from the
+> build for exactly this reason. It's only runnable from the standalone
+> "Binary version" below, which bundles the full metadata layer.
+>
+> For column/table extraction without a database connection, in this
+> repository, use `getResultColumn` instead:
+> ```bash
+> mvn -q exec:java -Dexec.mainClass=demos.gettablecolumns.getResultColumn -Dexec.classpathScope=compile
+> ```
+> It parses an inline query and prints its result columns; edit the `sqltext`
+> in `getResultColumn.java` to try your own SQL. Other classes in this folder
+> (`columnTableStmt`, `columnsInResultColumn`, `whatClause`,
+> `tableColumnRename`) demonstrate related, database-free column/table
+> analysis and build the same way.
+
 ## Binary version
 https://www.gudusoft.com/gsp_java/gettablecolumn.zip
 

src/main/java/gudusoft/gsqlparser/demos/sqlrefactor/readme.md

@@ -0,0 +1,28 @@
+## Description
+
+`rmdupParenthesis` removes redundant duplicated parentheses from a SQL
+statement using the source token list, e.g. `WHERE ((a.x > 1))` becomes
+`WHERE (a.x > 1)`.
+
+## Usage
+
+```
+java rmdupParenthesis <sqlfile.sql> [/t <database type>]
+```
+
+`/t` is optional and defaults to `oracle`.
+
+```bash
+cat > paren.sql <<'SQL'
+SELECT * FROM ta WHERE ((a.x > 1));
+SQL
+
+mvn -q exec:java -Dexec.mainClass=demos.sqlrefactor.rmdupParenthesis \
+    -Dexec.args="paren.sql /t mssql" -Dexec.classpathScope=runtime
+```
+
+```
+Selected SQL dialect: dbvmssql
+SELECT * FROM ta WHERE (a.x > 1);
+Time Escaped: 764
+```

src/main/java/gudusoft/gsqlparser/demos/sqlrefactor/rmdupParenthesis.java

@@ -5,10 +5,9 @@
 
 import gudusoft.gsqlparser.*;
 
-import java.io.BufferedReader;
 import java.io.File;
-import java.io.IOException;
-import java.io.InputStreamReader;
+import java.util.Arrays;
+import java.util.List;
 
 public class rmdupParenthesis   {
 
@@ -46,8 +45,10 @@ public static void main(String args[])
         long t;
         t = System.currentTimeMillis();
 
-        if (args.length != 1){
-            System.out.println("Usage: java rmdupParenthesis sqlfile.sql");
+        List<String> argList = Arrays.asList(args);
+        if (args.length < 1){
+            System.out.println("Usage: java rmdupParenthesis <sqlfile.sql> [/t <database type>]");
+            System.out.println("  /t <type>  - Specify database type (default: oracle)");
             return;
         }
         File file=new File(args[0]);
@@ -57,27 +58,9 @@ public static void main(String args[])
         }
 
         EDbVendor dbVendor = EDbVendor.dbvoracle;
-        String msg = "Please select SQL dialect: 1: SQL Server, 2: Oralce, 3: MySQL, 4: DB2, 5: PostGRESQL, 6: Teradta, default is 2: Oracle";
-        System.out.println(msg);
-
-        BufferedReader br=new   BufferedReader(new InputStreamReader(System.in));
-        try{
-            int db = Integer.parseInt(br.readLine());
-            if (db == 1){
-                dbVendor = EDbVendor.dbvmssql;
-            }else if(db == 2){
-                dbVendor = EDbVendor.dbvoracle;
-            }else if(db == 3){
-                dbVendor = EDbVendor.dbvmysql;
-            }else if(db == 4){
-                dbVendor = EDbVendor.dbvdb2;
-            }else if(db == 5){
-                dbVendor = EDbVendor.dbvpostgresql;
-            }else if(db == 6){
-                dbVendor = EDbVendor.dbvteradata;
-            }
-        }catch(IOException i) {
-        }catch (NumberFormatException numberFormatException){
+        int index = argList.indexOf("/t");
+        if (index != -1 && args.length > index + 1){
+            dbVendor = TGSqlParser.getDBVendorByName(args[index + 1]);
         }
 
         System.out.println("Selected SQL dialect: "+dbVendor.toString());

src/main/java/gudusoft/gsqlparser/demos/traceColumn/readme.md

@@ -0,0 +1,50 @@
+## Description
+
+Follows each result column of a `SELECT` (or the subquery of a `CREATE VIEW`)
+back to the base-table columns and expressions it's built from, printing an
+indented trace: alias, the column's own expression, then each source column it
+reads from, recursing into subqueries, derived tables and nested expressions.
+
+## Usage
+
+`runTraceColumn` runs a single query that's inline in `main()` — there's no
+`/f` file argument or CLI parsing here, unlike most other demos. Run it with:
+
+```bash
+mvn -q exec:java -Dexec.mainClass=demos.traceColumn.runTraceColumn -Dexec.classpathScope=compile
+```
+
+To trace a different query, edit the `sqltext` (or the vendor passed to
+`runText`) in `runTraceColumn.java` and rebuild, or call
+`TTraceColumn` directly from your own code:
+
+```java
+TTraceColumn traceColumn = new TTraceColumn(EDbVendor.dbvoracle);
+traceColumn.runText("SELECT a.id, b.name FROM ta a JOIN tb b ON a.id = b.id");
+System.out.print(traceColumn.getInfos().toString());
+```
+
+## Sample output
+
+For the query built into `runTraceColumn.java`:
+
+```
+"Department"
+ -->a.deptno(expr)
+  -->a.deptno
+   -->deptno(expr)
+    -->scott.emp.deptno
+"Employees"
+  -->a.num_emp/b.total_count(expr)
+   -->a.num_emp
+    -->COUNT(*)(expr)
+     -->scott.emp.*
+   -->b.total_count
+    -->COUNT(*)(expr)
+     -->scott.emp.*
+...
+```
+
+Each `-->` level is one hop back through the expression tree; a line ending in
+`(expr)` is the expression at that point, and the line above it (when present)
+is the alias or source column it was reached through.

src/main/java/gudusoft/gsqlparser/demos/traceColumn/runTraceColumn.java

@@ -27,8 +27,7 @@ public static void main(String args[]) {
 //                    "from table1 a join table2 b on a.id=b.id\n" +
 //                    "join table3 c on b.tid=c.id";
 
-      // runText(EDbVendor.dbvoracle,sqltext);
-       runFile(EDbVendor.dbvoracle,"c:/prg/tmp/demo.sql");
+       runText(EDbVendor.dbvoracle,sqltext);
     }
 
     public static void runText(EDbVendor dbVendor, String query){

src/main/java/gudusoft/gsqlparser/demos/tracedatalineage/readme.md

@@ -0,0 +1,40 @@
+## Description
+
+Reads every `.sql` file in a directory (T-SQL / `dbvmssql` syntax) as one
+combined script, builds up a model of the tables it creates and the
+`INSERT ... SELECT` / `UPDATE` statements and stored procedures that move data
+between them, then traces each base-table column forward to every column it
+ultimately feeds into. This is a directory/multi-script tool, unlike most
+other demos here which parse one query or file — see `traceColumn` for
+tracing a single query's result columns back to their sources instead.
+
+## Usage
+
+```
+java demos.tracedatalineage.traceDataLineage <sql scripts directory path> [<output file path>]
+```
+
+The first argument **must be a directory**, not a single `.sql` file —
+passing a file silently matches nothing (`SqlFileList` only lists `.sql` files
+inside a directory) and the tool exits 0 with no output, which looks
+identical to "ran fine, found no lineage." The optional second argument
+writes the result to a file instead of stdout.
+
+```bash
+mvn -q exec:java -Dexec.mainClass=demos.tracedatalineage.traceDataLineage \
+    -Dexec.args="src/main/java/gudusoft/gsqlparser/demos/tracedatalineage/sample" \
+    -Dexec.classpathScope=compile
+```
+
+```
+source_tbl.id	----->	target_tbl.id
+source_tbl.amount	----->	target_tbl.total
+```
+
+`sample/` contains the two-file script this example reads: one file creates
+`source_tbl` and `target_tbl`, the other loads the first into the second with
+`INSERT INTO target_tbl (id, total) SELECT id, amount FROM source_tbl`.
+
+Lineage is only recorded across `INSERT`/`UPDATE` statements and stored
+procedures — a `CREATE VIEW` that merely selects from a table does not, on its
+own, produce a traceable relation here.

src/main/java/gudusoft/gsqlparser/demos/tracedatalineage/sample/01_tables.sql

@@ -0,0 +1,9 @@
+CREATE TABLE source_tbl (
+  id INT,
+  amount INT
+);
+
+CREATE TABLE target_tbl (
+  id INT,
+  total INT
+);

src/main/java/gudusoft/gsqlparser/demos/tracedatalineage/sample/02_load.sql

@@ -0,0 +1,2 @@
+INSERT INTO target_tbl (id, total)
+SELECT id, amount FROM source_tbl;