Create draft plans for addressing each limitation

plans/README.md

@@ -0,0 +1,50 @@
+# Plans for the README's limitations
+
+One plan per bullet in the README's [Limitations](../README.md#limitations) section:
+
+| Plan | Limitation | Size |
+| --- | --- | --- |
+| [01](01-return-star-explain-profile.md) | `RETURN *`, `EXPLAIN` and `PROFILE` | medium |
+| [02](02-write-statistics.md) | Write statistics | small |
+| [03](03-age-unsupported-features.md) | Multiple labels, pattern comprehensions, temporal and spatial types, indexes and constraints | large, split in parts |
+| [04](04-users-transactions-sysinfo.md) | User and role management, `SHOW TRANSACTIONS`, `:sysinfo` | medium |
+| [05](05-tls.md) | TLS (`bolt+s://`, HTTPS) | small to medium |
+| [06](06-streaming-results.md) | Results fetched fully before streaming | medium |
+
+## Shared groundwork
+
+Several plans need the same building blocks. Building them once, first, keeps the
+plans small:
+
+1. **Variable scope analysis in `cypher.py`.** `RETURN *` (01) and general pattern
+   comprehension rewriting (03) both need to know which variables are in scope at a
+   given clause. Today `cypher.py` only masks strings and tracks bracket depth. A
+   small clause splitter plus a scope tracker (variables introduced by `MATCH`,
+   `OPTIONAL MATCH`, `UNWIND ... AS`, `YIELD`, `WITH` projections, path assignments)
+   is enough; a full Cypher parser is not needed yet. If 03's multiple-labels part is
+   ever done, that is the point to reconsider a real parser (for example one
+   generated from the openCypher grammar).
+2. **One transaction per auto-commit query.** Write statistics (02) read
+   transaction-local counters, streaming (06) needs a transaction to keep a server-side
+   cursor open, and `PROFILE` (01) needs a savepoint. All three want `Session.run` to
+   wrap auto-commit queries in `BEGIN ... COMMIT` instead of relying on the
+   connection's autocommit mode. Do this once, in 06 or 02, whichever comes first.
+3. **Unit tests.** The only test is the end-to-end `tests/smoke_test.py`. Most of
+   this work is text rewriting in `cypher.py`, which is cheap to unit test without a
+   database. Add `tests/test_cypher.py` (pytest) alongside the first plan that
+   touches `cypher.py`, and keep extending the smoke test for behaviour that needs
+   AGE.
+
+## Suggested order
+
+1. 02 write statistics: small, very visible in neo4j-browser, and introduces the
+   per-query transaction.
+2. 06 streaming: builds on the same transaction handling.
+3. 01 `RETURN *` / `EXPLAIN` / `PROFILE`: introduces the scope analysis.
+4. 03 indexes and constraints (part D), then pattern comprehensions (part B), then
+   temporal types (part C). Multiple labels (part A) and spatial types (part E) last,
+   or not at all.
+5. 05 TLS and 04 user management, independent of the rest, whenever they are needed.
+
+Each plan ends with the README changes to make when it lands, so the Limitations
+section shrinks as the work is done.